@intentic/sandbox-contract 1.343.0 → 1.345.0

package/src/schemas/sandbox-passwords.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { KeyringOriginSchema, KeyringRememberSchema, KeyringShareModeSchema } from "./keyring.js";
+
+// THE SANDBOX'S SIDE OF PASSWORDS (2026-10-19): an agent asking for a credential by where it is to be used (`secrets
+// want`, `type_secret` aimed at a page or a window), and the hosted Passwords view's three reads. The vault and its
+// management stay on the owner's computers; what a sandbox learns of an entry is the pointer its keyring shared here.
+
+/** `secrets want`: a credential by the place it is for, asked of the owner's keyrings. */
+export const SecretWantSchema = z
+    .object({
+        origin: KeyringOriginSchema.describe("Where it is to be used: a site, a program on the owner's computer, an ssh target, a git host."),
+        username: z.string().max(256).optional().describe("The account wanted, when the agent knows it."),
+        why: z.string().min(1).max(300).describe("What it is for, in words for the person's prompt."),
+        // Filled by the CLI itself, from the running turn, so the prompt names the conversation that asked.
+        conversationId: z.string().max(200).optional(),
+    })
+    .strict();
+export type SecretWant = z.infer<typeof SecretWantSchema>;
+
+export const SecretWantResultSchema = z.discriminatedUnion("state", [
+    z.object({
+        state: z.literal("allowed"),
+        name: z.string().describe("The name a secret reference uses from now on."),
+        machine: z.string().describe("The computer whose keyring shares it."),
+        message: z.string(),
+    }),
+    z.object({ state: z.literal("pending"), id: z.string(), machine: z.string(), message: z.string().describe("Where the owner's answer is awaited.") }),
+    z.object({ state: z.literal("denied"), message: z.string() }),
+    z.object({ state: z.literal("unknown"), message: z.string().describe("No keyring had it and nobody typed it once, or none could be asked.") }),
+]);
+export type SecretWantResult = z.infer<typeof SecretWantResultSchema>;
+
+/** One need this sandbox raised, as its record and the hosted view's Requests keep it. */
+export const SandboxNeedSchema = z.object({
+    id: z.string(),
+    origin: KeyringOriginSchema,
+    username: z.string().optional(),
+    detail: z.string(),
+    conversation: z.string().optional(),
+    machine: z.string().optional().describe("The computer it was answered on, or waits on."),
+    state: z.enum(["pending", "allowed", "denied", "unknown"]),
+    name: z.string().optional().describe("The entry it was answered with, once allowed."),
+    at: z.number().int(),
+});
+export type SandboxNeed = z.infer<typeof SandboxNeedSchema>;
+export const SandboxNeedsSchema = z.object({ needs: z.array(SandboxNeedSchema) });
+
+/** One of the owner's computers as the hosted Passwords view shows its keyring. */
+export const SandboxPasswordsKeyringSchema = z.object({
+    machine: z.string(),
+    online: z.boolean(),
+    setUp: z.boolean().describe("Answering, set up, and trusted by this sandbox: it can be asked."),
+    locked: z.boolean().optional(),
+    remember: KeyringRememberSchema.optional(),
+});
+export type SandboxPasswordsKeyring = z.infer<typeof SandboxPasswordsKeyringSchema>;
+
+/** One password this sandbox may use: a pointer one of the owner's keyrings shares here. Never a value. */
+export const SandboxPasswordSchema = z.object({
+    name: z.string(),
+    title: z.string(),
+    kind: z.enum(["password", "text"]),
+    origins: z.array(KeyringOriginSchema).describe("Where it works, from the entry's rules."),
+    anyField: z.boolean(),
+    machine: z.string().describe("The computer whose keyring keeps it."),
+    mode: KeyringShareModeSchema.describe("How this sandbox may use it."),
+    online: z.boolean(),
+    updatedAt: z.number(),
+    lastUsedAt: z.number().optional().describe("This sandbox's last use of it, from its own use ledger."),
+});
+export type SandboxPassword = z.infer<typeof SandboxPasswordSchema>;
+
+export const SandboxPasswordsSchema = z.object({
+    sandbox: z.string().describe("This sandbox's own address, as the keyrings name it."),
+    items: z.array(SandboxPasswordSchema),
+    keyrings: z.array(SandboxPasswordsKeyringSchema),
+});
+export type SandboxPasswords = z.infer<typeof SandboxPasswordsSchema>;
+
+/** One use of a keyring-held password by this sandbox, from its use ledger. */
+export const SandboxPasswordUseSchema = z.object({
+    at: z.number(),
+    name: z.string(),
+    lane: z.string(),
+    detail: z.string().optional(),
+    approvedBy: z.string().optional(),
+});
+export const SandboxPasswordsActivitySchema = z.object({ lines: z.array(SandboxPasswordUseSchema) });

package/src/schemas/secrets.ts

@@ -257,6 +257,10 @@ export const SandboxKeyringSchema = z.object({
     machine: z.string().describe("The computer, by its device card."),
     online: z.boolean().describe("Whether it answers now."),
     locked: z.boolean().optional().describe("Whether its keyring is locked, as last heard. Absent while offline."),
+    setUp: z
+        .boolean()
+        .optional()
+        .describe("Whether its keyring answers with a vault this sandbox trusts, so a value can be kept there. Absent while offline, and from a daemon older than 2026-10-19."),
     version: z.string().optional().describe("The keyring's release, as last heard."),
     pendingInbox: z.number().int().nonnegative().optional().describe("Values sent to be kept there that wait for its next unlock."),
     shared: z.number().int().nonnegative().describe("How many of its entries are shared with this sandbox."),

package/src/schemas/settings-history.ts

@@ -3,6 +3,7 @@ import { at, drop, dropAll, fold, isJsonObject, type JsonObject, mapValue, retyp
 import { type ModelRole, ModelRoleSchema } from "../models/model-roles.js";
 import { setupsFromRoleLists } from "../models/model-setups.js";
 import { ModelPinSchema, type ModelPin } from "./agent.js";
+import { RESTORE_POINT_KEEP_DAYS_DEFAULT } from "./data-protection.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
@@ -101,6 +102,21 @@ const roleListsIntoSetups = transform("folds modelRoles and modelDefault into se
     return { ...rest, modelSetups, roleSetups };
 });
 
+const restorePointsKept = fold("carries restorePointDays into restorePointKeepDays, a stored zero taking the 30-day default", {
+    from: ["restorePointDays"],
+    into: "restorePointKeepDays",
+    applies: (retention) => Object.hasOwn(retention, "restorePointDays"),
+    convert: ({ restorePointDays }, retention) => {
+        // A file that already names the new key (a definition written for both) keeps it.
+        const kept = FlatNumber.safeParse(retention["restorePointKeepDays"]);
+        if (kept.success) {
+            return kept.data;
+        }
+        const chosen = FlatNumber.safeParse(restorePointDays);
+        return chosen.success && chosen.data > 0 ? chosen.data : RESTORE_POINT_KEEP_DAYS_DEFAULT;
+    },
+});
+
 export const SETTINGS_HISTORY = [
     // Every setting a release since 2026-08-10 had and this one does not (read off the contract lock's history):
     // retired, so passthrough stops carrying them, a definition naming one still applies, and no later setting may
@@ -154,4 +170,8 @@ export const SETTINGS_HISTORY = [
     ...dropAll(["toolResultClearing", "toolResultClearingHoldout"]),
     at("modelRoles", refactorsFromChores),
     roleListsIntoSetups,
+    // Restore points kept 30 days by default (2026-10-18). `restorePointDays` held zero both where the owner chose to keep
+    // every point and where the settings page had saved the old default, which no reading could tell apart: the key is
+    // retired, a positive choice carries over, and a stored zero takes the new default.
+    at("retention", restorePointsKept),
 ] as const;

package/src/schemas/settings-savings.ts

@@ -0,0 +1,125 @@
+// settings-savings: what each token-reduction mechanism saved and how the turn-level ones are measured, as the
+// settings routes report them. Re-exported by settings.ts, whose routes carry them.
+import { z } from "zod";
+
+// What each token-reduction mechanism actually saved. Input-side: both sides of the comparison come off the same
+// command (raw in, emitted out), so the counterfactual is observed, not estimated — exact, per command.
+
+// Sequential attribution (sums exactly to raw − emitted, drawable as a stacked bar); not what disabling this stage
+// would save, since downstream would eat some of the same lines. Negative for `footer`, which adds cost back.
+export const SavingsStageSchema = z.object({ id: z.string(), commands: z.number(), savedTokens: z.number() });
+// Aggregated from historyRoot/logs/filter-stats.jsonl (one row per Bash command). Windowed on the ledger's own UTC-day
+// calendar, so the reader's date range and these figures agree.
+export const InputSavingsSchema = z.object({
+    // Epoch ms of the ledger's last command, so the card can show its age rather than implying freshness.
+    updatedAt: z.number().optional(),
+    commands: z.number(),
+    rawTokens: z.number(),
+    emittedTokens: z.number(),
+    savedPct: z.number(),
+    // Per-stage attribution, biggest first.
+    perCleaner: z.array(SavingsStageSchema),
+    // The measured control (raw vs. cleaned); the only real whole-pipeline counterfactual, not an estimate.
+    holdout: z.object({ cleaned: z.number(), heldOut: z.number(), measuredSavedPct: z.number().optional() }),
+    // Grouped by command text: worth a handler is judged by total tokens across runs, not one outlier's size.
+    gaps: z.array(z.object({ command: z.string(), commands: z.number(), tokens: z.number() })),
+});
+export type InputSavings = z.infer<typeof InputSavingsSchema>;
+// One arm of a turn-level experiment; mean is per turn, since the two arms never hold the same count.
+// `mean` is over samples capped at both arms' pooled 95th percentile, so one runaway conversation cannot carry an arm.
+// For a yes/no reading (`openedWithListing`) it is the share of yeses, 0 to 1, and uncapped.
+export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() });
+// One metric's reading of a turn-level experiment (the two arms, plus the arithmetic over them). `metric` says what
+// `mean`/`deltaPct` count:
+// searchCalls: searches a turn ran (the search teaching).
+// openingSearches: same, narrowed to before the turn first touched a file.
+// openedWithListing: whether a turn listed directories to orient itself, as a share of turns (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).
+// openingPrompt: tokens a turn's first request sent (cache reads plus cache writes), which is what every later call of
+// the turn reads again (tool search, which moves the tool schemas out of it).
+// openingWrite: tokens a follow-up turn's first request wrote to the cache instead of reading them (the stable prompt).
+// Every reading is the main agent's own: a subagent's calls are counted toward the turn and read for nothing.
+// Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest. The prompt's size is
+// the exception that proves it: it is the part every call pays again, so it is read directly rather than through cost.
+export const TurnMetricReadingSchema = z.object({
+    metric: z.enum(["searchCalls", "openingSearches", "openedWithListing", "callsBeforeTarget", "failedCalls", "openingPrompt", "openingWrite"]),
+    on: SavingsArmSchema,
+    off: SavingsArmSchema,
+    // Additional control turns to reach a fixed target resolution, not today's delta (which inherits noise and always
+    // promises "next week"). Absent means nothing to wait for: under `minTurns`, already published, or already resolved
+    // enough.
+    controlTurnsNeeded: z.number().optional(),
+    // ± percentage points at 95% (Welch); present once both arms clear `minTurns`, even when `deltaPct` is withheld —
+    // "smaller than ±35 points" is still a useful, true answer.
+    marginPct: z.number().optional(),
+    // Present only once the margin excludes zero — clearing `minTurns` alone isn't enough, or a wide, unresolved swing
+    // reads as a real number.
+    // deltaPct: change in the metric's mean per turn; negative is a saving.
+    // saved: what that delta was worth over the turns that ran with it, in the metric's own unit.
+    deltaPct: z.number().optional(),
+    saved: z.number().optional(),
+});
+export type TurnMetricReading = z.infer<typeof TurnMetricReadingSchema>;
+// One coin flip, several readings: `metrics` is a list since splitting readings into separate entries would duplicate
+// the arm assignment. Screens read `metrics[0]` as the headline, the rest as supporting lines.
+export const TurnExperimentSchema = z.object({
+    // A head and a tail, not a plain array, so "always a headline" is a type fact, not a check every screen repeats.
+    // `.nonempty()` doesn't do this in zod 4 (a runtime check, still typed as a plain array).
+    metrics: z.tuple([TurnMetricReadingSchema], TurnMetricReadingSchema),
+    // Carried on the wire so "measuring…" reflects the daemon's real threshold, not a guess; shared across every
+    // reading, since they're the same turns.
+    minTurns: z.number(),
+    // Turn mechanisms randomize by turn; session-loaded teaching randomizes whole conversations; a once-sent treatment
+    // (the map) samples one turn per conversation, not an average, or its effect divides by the conversation's length.
+    sampleUnit: z.enum(["turns", "conversations", "opening turns"]).optional(),
+    // Content-addressed treatment version; the reader filters to the latest so two instruction revisions don't blur
+    // into one experiment.
+    cohort: z.string().optional(),
+    // The latest earlier cohort that reached an answer, with only its answered readings (a margin, with or without a
+    // delta), so restarting a comparison does not wipe a finding off the screen while the new one is early. `from` and
+    // `to` are its first and last measured turn inside the window read, epoch ms. Absent when no earlier one answered.
+    previous: z
+        .object({ from: z.number(), to: z.number(), cohort: z.string().optional(), metrics: z.array(TurnMetricReadingSchema) })
+        .optional(),
+    // Whether the treatment was taken up at all, which no reading above can tell: the share, 0 to 1, of each group's
+    // searches that ran iq, pooled over the turns of this cohort that recorded it. `turns` is the treated group's count;
+    // absent until it reaches `minTurns`. The search teaching only.
+    uptake: z.object({ on: z.number(), off: z.number(), turns: z.number() }).optional(),
+});
+export type TurnExperiment = z.infer<typeof TurnExperimentSchema>;
+// 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(),
+    // Blocks of the file its priority table does not rank, so no limit ever sends them. Absent when there are none.
+    unlisted: z.array(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(),
+    toolSearch: TurnExperimentSchema.optional(),
+    stablePrompt: TurnExperimentSchema.optional(),
+    coldTrim: TurnExperimentSchema.optional(),
+});
+export type SavingsReport = z.infer<typeof SavingsReportSchema>;

package/src/schemas/settings.test.ts

@@ -207,3 +207,41 @@ describe(`per-job model lists`, () => {
         expect(convertDocument(SETTINGS_HISTORY, `object`, { modelSetups: [{ id: `low`, pins: [haiku] }], roleSetups: {} }, true).changes).toEqual([]);
     });
 });
+
+test("disk retention defaults bound checkouts and restore points while preserving explicit zero", () => {
+    const defaults = SandboxSettingsSchema.parse({});
+    expect(defaults.agentRetentionDays).toBe(3);
+    expect(defaults.heldCheckoutDays).toBe(14);
+    expect(defaults.retention.restorePointKeepDays).toBe(30);
+    const existing = SandboxSettingsSchema.parse({ heldCheckoutDays: 0, retention: { restorePointKeepDays: 0 } });
+    expect(existing.heldCheckoutDays).toBe(0);
+    expect(existing.retention.restorePointKeepDays).toBe(0);
+});
+
+describe(`restore points' retention, renamed so a stored zero is the owner's own (2026-10-18)`, () => {
+    const read = (retention: Record<string, unknown>) => {
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, { retention: { transcriptDays: 7, ...retention } }, true);
+        return { retention: SandboxSettingsSchema.parse(converted.value).retention, changes: converted.changes };
+    };
+
+    test(`an earlier release's stored zero, which the settings page wrote for the old default, takes the 30-day default`, () => {
+        const { retention, changes } = read({ restorePointDays: 0 });
+        expect(retention.restorePointKeepDays).toBe(30);
+        expect(retention.transcriptDays).toBe(7);
+        expect(changes.map((change) => change.at)).toEqual([`retention`]);
+    });
+
+    test(`a positive choice carries over`, () => {
+        expect(read({ restorePointDays: 90 }).retention.restorePointKeepDays).toBe(90);
+    });
+
+    test(`a zero stored under the new key is kept, and read again changes nothing`, () => {
+        const { retention, changes } = read({ restorePointKeepDays: 0 });
+        expect(retention.restorePointKeepDays).toBe(0);
+        expect(changes).toEqual([]);
+    });
+
+    test(`a file naming both keeps the new one`, () => {
+        expect(read({ restorePointDays: 0, restorePointKeepDays: 5 }).retention.restorePointKeepDays).toBe(5);
+    });
+});

package/src/schemas/settings.ts

@@ -6,14 +6,20 @@ import { claudeExperimentSettings, iqSearchSettings } from "./settings-experimen
 import { CommandJudgeModeSchema, ProjectInstallModeSchema } from "../policy/safety-policy.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
 import { MODEL_SETUP_ID, ModelSetupSchema } from "../models/model-setups.js";
-import { AdmissionPolicySchema, AdmissionRuleSchema } from "./agent.js";
+import { AdmissionPolicySchema, AdmissionRuleSchema } from "./command-admission.js";
 import { KeepWarmSettingsSchema } from "./keep-warm.js";
 import { LimitHandoffSchema } from "./providers/handoff.js";
 import { SessionsPlacementSchema } from "./offload.js";
 import { LimitPolicySchema, RetryPolicySchema, RoomPolicySchema } from "./turn-break.js";
 import { ZoneSchema } from "../time/zone.js";
 import { VoiceSettingsSchema } from "./voice.js";
-import { AiNoticeSchema, AuditSettingsSchema, RetentionSettingsSchema } from "./data-protection.js";
+import {
+    AiNoticeSchema,
+    AuditSettingsSchema,
+    RetentionSettingsSchema,
+    HeldCheckoutDaysSchema,
+    AgentRetentionDaysSchema,
+} from "./data-protection.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.
 // Kept in the daemon's auth root, never in SandboxSettings: an agent cannot edit its execution boundary.
@@ -398,14 +404,8 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Which repositories keep a changelog, and so get a user-facing note written alongside each merge. A list rather than a switch, and empty by default, because the commit writer's standing rule is to copy the house style rather than impose one, and a repository that has never written such a note gives it nothing to copy.",
         ),
-    agentRetentionDays: z
-        .number()
-        .min(0)
-        .max(365)
-        .default(3)
-        .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.",
-        ),
+    agentRetentionDays: AgentRetentionDaysSchema,
+    heldCheckoutDays: HeldCheckoutDaysSchema,
     // 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.
@@ -543,10 +543,10 @@ export const SandboxSettingsSchema = z.object({
     voice: VoiceSettingsSchema.prefault({}).describe(
         "How the agent's replies are spoken aloud: whether a hands-free conversation is answered out loud, which voice speaks each language, and a speech provider of your own if you connected one.",
     ),
-    // What a data protection officer asks about (schemas/data-protection.ts). Every default is the behaviour from before
-    // these existed; the public-office preset on the data protection page is what turns them on, never a default.
+    // What a data protection officer asks about (schemas/data-protection.ts). Restore points default to thirty days;
+    // the other policies preserve the earlier behaviour until the owner changes them or applies the public-office preset.
     retention: RetentionSettingsSchema.prefault({}).describe(
-        "How long this sandbox keeps each kind of copy it makes of what people and agents wrote: transcripts, restore points, the privacy shield's memory, converted documents and raw command output. Each defaults to forever.",
+        "How long this sandbox keeps each kind of copy it makes of what people and agents wrote: transcripts, restore points, the privacy shield's memory, converted documents and raw command output. Restore points default to 30 days; the other copies default to forever.",
     ),
     audit: AuditSettingsSchema.prefault({}).describe(
         "The audit trail: who changed a policy, a member, a gate or a setting, and optionally who read what. How long it is kept, and where a copy is sent.",
@@ -597,6 +597,11 @@ export const SandboxSettingsSchema = z.object({
         .max(10)
         .default(3)
         .describe("How many levels deep the delegation may go, since a subagent can start subagents of its own."),
+    // How far off a reset a spawned child's spent turn is booked to re-run by itself (classify-failure.ts); one with fallbacks
+    // keeps 90 minutes. 2026-10-18: was a fixed 90 minutes, which ended every child behind a five-hour window.
+    childRerunHorizonHours: z.number().int().min(0).max(24).default(6).describe(
+        "How long a subagent refused for a spent allowance waits for the provider's reset before it goes again by itself. Past it, or at 0, it stops and its parent hears where else the work can go. One spawned with fallbacks waits at most 90 minutes and then moves to them.",
+    ),
     // Width again, for a team-chat automation rather than a turn: each thread a message lands in is a conversation of
     // its own, and threads of one automation are worked on side by side up to this many (automations/scheduler.ts in
     // the daemon); one more waits, told it is queued, until a slot frees. Read per fire, so a change holds from the next
@@ -668,121 +673,8 @@ export type TimezoneState = z.infer<typeof TimezoneStateSchema>;
 // from, so a fork from an older build reads as a snapshot.
 export const BuiltinPromptTextSchema = z.object({ text: z.string(), version: z.string() });
 export type BuiltinPromptText = z.infer<typeof BuiltinPromptTextSchema>;
-// What each token-reduction mechanism actually saved. Input-side: both sides of the comparison come off the same
-// command (raw in, emitted out), so the counterfactual is observed, not estimated — exact, per command.
-
-// Sequential attribution (sums exactly to raw − emitted, drawable as a stacked bar); not what disabling this stage
-// would save, since downstream would eat some of the same lines. Negative for `footer`, which adds cost back.
-export const SavingsStageSchema = z.object({ id: z.string(), commands: z.number(), savedTokens: z.number() });
-// Aggregated from historyRoot/logs/filter-stats.jsonl (one row per Bash command). Windowed on the ledger's own UTC-day
-// calendar, so the reader's date range and these figures agree.
-export const InputSavingsSchema = z.object({
-    // Epoch ms of the ledger's last command, so the card can show its age rather than implying freshness.
-    updatedAt: z.number().optional(),
-    commands: z.number(),
-    rawTokens: z.number(),
-    emittedTokens: z.number(),
-    savedPct: z.number(),
-    // Per-stage attribution, biggest first.
-    perCleaner: z.array(SavingsStageSchema),
-    // The measured control (raw vs. cleaned); the only real whole-pipeline counterfactual, not an estimate.
-    holdout: z.object({ cleaned: z.number(), heldOut: z.number(), measuredSavedPct: z.number().optional() }),
-    // Grouped by command text: worth a handler is judged by total tokens across runs, not one outlier's size.
-    gaps: z.array(z.object({ command: z.string(), commands: z.number(), tokens: z.number() })),
-});
-export type InputSavings = z.infer<typeof InputSavingsSchema>;
-// One arm of a turn-level experiment; mean is per turn, since the two arms never hold the same count.
-// `mean` is over samples capped at both arms' pooled 95th percentile, so one runaway conversation cannot carry an arm.
-// For a yes/no reading (`openedWithListing`) it is the share of yeses, 0 to 1, and uncapped.
-export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() });
-// One metric's reading of a turn-level experiment (the two arms, plus the arithmetic over them). `metric` says what
-// `mean`/`deltaPct` count:
-// searchCalls: searches a turn ran (the search teaching).
-// openingSearches: same, narrowed to before the turn first touched a file.
-// openedWithListing: whether a turn listed directories to orient itself, as a share of turns (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).
-// openingPrompt: tokens a turn's first request sent (cache reads plus cache writes), which is what every later call of
-// the turn reads again (tool search, which moves the tool schemas out of it).
-// openingWrite: tokens a follow-up turn's first request wrote to the cache instead of reading them (the stable prompt).
-// Every reading is the main agent's own: a subagent's calls are counted toward the turn and read for nothing.
-// Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest. The prompt's size is
-// the exception that proves it: it is the part every call pays again, so it is read directly rather than through cost.
-export const TurnMetricReadingSchema = z.object({
-    metric: z.enum(["searchCalls", "openingSearches", "openedWithListing", "callsBeforeTarget", "failedCalls", "openingPrompt", "openingWrite"]),
-    on: SavingsArmSchema,
-    off: SavingsArmSchema,
-    // Additional control turns to reach a fixed target resolution, not today's delta (which inherits noise and always
-    // promises "next week"). Absent means nothing to wait for: under `minTurns`, already published, or already resolved
-    // enough.
-    controlTurnsNeeded: z.number().optional(),
-    // ± percentage points at 95% (Welch); present once both arms clear `minTurns`, even when `deltaPct` is withheld —
-    // "smaller than ±35 points" is still a useful, true answer.
-    marginPct: z.number().optional(),
-    // Present only once the margin excludes zero — clearing `minTurns` alone isn't enough, or a wide, unresolved swing
-    // reads as a real number.
-    // deltaPct: change in the metric's mean per turn; negative is a saving.
-    // saved: what that delta was worth over the turns that ran with it, in the metric's own unit.
-    deltaPct: z.number().optional(),
-    saved: z.number().optional(),
-});
-export type TurnMetricReading = z.infer<typeof TurnMetricReadingSchema>;
-// One coin flip, several readings: `metrics` is a list since splitting readings into separate entries would duplicate
-// the arm assignment. Screens read `metrics[0]` as the headline, the rest as supporting lines.
-export const TurnExperimentSchema = z.object({
-    // A head and a tail, not a plain array, so "always a headline" is a type fact, not a check every screen repeats.
-    // `.nonempty()` doesn't do this in zod 4 (a runtime check, still typed as a plain array).
-    metrics: z.tuple([TurnMetricReadingSchema], TurnMetricReadingSchema),
-    // Carried on the wire so "measuring…" reflects the daemon's real threshold, not a guess; shared across every
-    // reading, since they're the same turns.
-    minTurns: z.number(),
-    // Turn mechanisms randomize by turn; session-loaded teaching randomizes whole conversations; a once-sent treatment
-    // (the map) samples one turn per conversation, not an average, or its effect divides by the conversation's length.
-    sampleUnit: z.enum(["turns", "conversations", "opening turns"]).optional(),
-    // Content-addressed treatment version; the reader filters to the latest so two instruction revisions don't blur
-    // into one experiment.
-    cohort: z.string().optional(),
-    // The latest earlier cohort that reached an answer, with only its answered readings (a margin, with or without a
-    // delta), so restarting a comparison does not wipe a finding off the screen while the new one is early. `from` and
-    // `to` are its first and last measured turn inside the window read, epoch ms. Absent when no earlier one answered.
-    previous: z
-        .object({ from: z.number(), to: z.number(), cohort: z.string().optional(), metrics: z.array(TurnMetricReadingSchema) })
-        .optional(),
-});
-export type TurnExperiment = z.infer<typeof TurnExperimentSchema>;
-// 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(),
-    toolSearch: TurnExperimentSchema.optional(),
-    stablePrompt: TurnExperimentSchema.optional(),
-    coldTrim: TurnExperimentSchema.optional(),
-});
-export type SavingsReport = z.infer<typeof SavingsReportSchema>;
+// What each token-reduction mechanism saved, and the comparisons that measure the turn-level ones, in a file of their own.
+export * from "./settings-savings.js";
 
 // ---- what a REPOSITORY declares for itself, at `<repo>/.intentic/checks.json` ----
 // Here rather than in a file of its own because the line between these shapes and the settings above is authority, not

package/src/schemas/terminal.ts

@@ -219,6 +219,14 @@ export const SubagentVerificationSchema = z.object({
         ),
 });
 export type SubagentVerification = z.infer<typeof SubagentVerificationSchema>;
+// Where the Claude runtime keeps an in-process subagent's own record: beside the session it ran in, under the runtime's
+// own id for it. The daemon pairs the two while the subagent runs and writes them onto its delegation's card, so the
+// subagent's whole run reads back from that record after a restart, when nothing in memory still knows where it is.
+export const SubagentSdkRecordSchema = z.object({
+    sessionId: z.string().describe("The provider session the subagent ran in."),
+    agentId: z.string().describe("The runtime's own id for the subagent, which names its record beside that session."),
+});
+export type SubagentSdkRecord = z.infer<typeof SubagentSdkRecordSchema>;
 export const SubagentSessionSchema = z.object({
     id: z
         .string()

package/src/schemas/work-assurance.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+// WHAT HAS LOOKED AT A CONVERSATION'S WORK, as its card says it: what its last turn checked of its own work, and the
+// latest code review it reported. Both written by a turn's settle from what the turn did, never asked of the model.
+// Re-exported by agents.ts, whose summary carries them.
+
+// What the last turn showed of its own work, read off its tool calls and never asked of the model: the record a card
+// badges instead of sending the turn back to prove anything. CI checks what the owner pushes (schemas/ci.ts).
+export const TurnProofSchema = z.object({
+    at: z.number().describe("When the turn that left this ended, in milliseconds."),
+    verification: z
+        .enum(["verified", "unproven", "failing", "no-code"])
+        .describe(
+            "Verified: a check it ran passed after its last edit to code. Failing: the last one it ran failed. Unproven: it changed code and ran nothing that checked it. No-code: it changed nothing a check could speak to.",
+        ),
+    check: z.string().optional().describe("The command that spoke, when one did, so a targeted test is never read as the whole suite."),
+    unviewed: z
+        .number()
+        .optional()
+        .describe("How many rendered files it changed (pages, components, styles) without looking at the result afterwards. Absent when none."),
+});
+export type TurnProof = z.infer<typeof TurnProofSchema>;
+// The latest code review a conversation reported (events/review.ts), counted rather than carried: the findings stay in
+// its chat, where the card that sends them to be fixed draws them. Kept until a later review replaces it, since a turn
+// that reviews nothing has not undone the one before.
+export const ReviewTallySchema = z.object({
+    at: z.number().describe("When the turn that reported it ended, in milliseconds."),
+    source: z.enum(["claude", "codex"]).describe("Which harness's reviewer reported it."),
+    findings: z.number().int().nonnegative().describe("How many findings it reported."),
+    open: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("How many of those no re-report has marked fixed or set aside yet. Equal to `findings` until the review is reported again with its fixes applied."),
+});
+export type ReviewTally = z.infer<typeof ReviewTallySchema>;

package/src/schemas/workspace/workspace-tree.ts

@@ -143,6 +143,38 @@ export const WorkspaceMediaTicketSchema = z.object({
     ticket: z.string().describe("Hand this to the streaming route in the query string. It buys exactly the one file it was minted for."),
     expiresAt: z.number().describe("When it stops working, in milliseconds, so a player can tell a dead ticket from a dead file."),
 });
+// The long edges a picture is re-encoded at for drawing (GET /workspace/thumb's `size=e<edge>`), smallest first. A reader
+// asks for the smallest one at least as long as the box the picture fills on its screen, device pixels counted, the
+// way a browser picks from a srcset. Steps of about one and a half, so a pick is never much larger than it needs, and
+// few enough that the pictures of a folder seen at several sizes share their renditions.
+export const PICTURE_EDGES = [384, 512, 768, 1024, 1536, 2048] as const;
+export type PictureEdge = (typeof PICTURE_EDGES)[number];
+
+// The box each picture or video is drawn in, asked of a folder's worth at once: a gallery lays its rows out from every
+// picture's shape before any of them has loaded, so a row never reflows under the reader as its pictures arrive.
+export const WORKSPACE_DIMENSIONS_MAX = 500;
+export const WorkspaceDimensionsQuerySchema = WorkspaceScopeSchema.extend({
+    paths: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(WORKSPACE_DIMENSIONS_MAX)
+        .describe("The pictures and videos to measure, as workspace paths. Anything else, or anything unreadable, is left out of the answer."),
+});
+export const WorkspaceDimensionSchema = z.object({
+    path: z.string().describe("The path as it was asked for."),
+    width: z.number().describe("Width in pixels, as the picture is shown: a phone photo's or a phone video's rotation is already applied."),
+    height: z.number().describe("Height in pixels, as the picture is shown."),
+    duration: z.number().optional().describe("A video's running time in seconds, where its container says."),
+});
+export type WorkspaceDimension = z.infer<typeof WorkspaceDimensionSchema>;
+export const WorkspaceDimensionsSchema = z.object({
+    items: z
+        .array(WorkspaceDimensionSchema)
+        .describe(
+            "One entry per path that could be measured. A path missing here is not a picture this could read, which is an answer, not an error.",
+        ),
+});
+export type WorkspaceDimensions = z.infer<typeof WorkspaceDimensionsSchema>;
 // Credential for GET /workspace/download, which the browser navigates to so its own download manager streams the archive
 // to disk. The ticket carries the whole selection, resolved when minted, so however many entries it names the URL stays
 // short.