@intentic/sandbox-contract 1.344.0 → 1.346.0

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.ts

@@ -6,7 +6,7 @@ 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";
@@ -597,6 +597,13 @@ 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.",
+    ),
+    subagentBudget: z.boolean().default(true).describe("Start a subagent only where an account's allowance can carry it through its windows, on the account left with the most room after it. The rest wait as pending and start by themselves as running ones end or a window reopens. Off, every subagent starts at once, wherever the most room reads now."),
+    subagentReservePercent: z.number().int().min(0).max(50).default(10).describe("How much of each allowance window, in points of 100, subagents leave for your own conversations: a fan-out is planned against what is left past it."),
     // 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 +675,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/system.ts

@@ -61,6 +61,17 @@ export const PreparingUpdateSchema = z.object({
     percent: z.number().min(0).max(100).optional().describe("How far through the download it is, from 0 to 100. Absent for a step with no measure of its own."),
 });
 export type PreparingUpdate = z.infer<typeof PreparingUpdateSchema>;
+// What answers (state/sandbox-build.ts RunningSandbox): the build this container runs and when its daemon started.
+export const RunningSandboxSchema = z.object({
+    build: z
+        .object({
+            base: z.string().describe("The base image as the machine that runs it named it; empty when it said nothing."),
+            baseDigest: z.string().optional().describe("That base's registry digest, when the machine read one."),
+            overlay: z.string().optional().describe("The hash of the environment recipe built on the base. Absent on a stock image."),
+        })
+        .describe("Which build this container is: its base image and the environment built on it."),
+    bootedAt: z.number().describe("When the daemon answering started, in milliseconds. A container swapped in is a new boot."),
+});
 export const InfoSchema = z.object({
     name: z.string().optional().describe("What this sandbox is called."),
     image: z.string().optional().describe("The image it is running."),
@@ -129,6 +140,10 @@ export const InfoSchema = z.object({
     autoUpdate: AutoUpdateSchema.optional().describe(
         "Whether and when this sandbox takes a downloaded update by itself, and what it is waiting on. Absent where it cannot: a hosted sandbox, one built from a checkout, or one older than automatic updates.",
     ),
+    // What answers now, for a page telling a swap it pressed from one still running; absent from a daemon older than it.
+    running: RunningSandboxSchema.optional().describe(
+        "Which build answers and when its daemon started, so a page that asked for a rebuild, an update or a rollback can tell when the new container is the one answering. Absent from a sandbox older than this field.",
+    ),
 });
 export type Info = z.infer<typeof InfoSchema>;
 // What the daemon could not read in its own `.intentic/` state files, and in the files on its volume that

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.

package/src/state/auth-state.ts

@@ -0,0 +1,89 @@
+import { STATE_DIR } from "@intentic/constants";
+import type { StateFile } from "./state-portability.js";
+import type { WorkspaceStatePath } from "./workspace-state.js";
+
+// The auth root holds AI-provider logins, the sandbox's secret vaults and the trust files a turn must not edit (mode
+// 0600, off the file routes, tree walk and search index). It lives at `.intentic/secrets/auth/` unless AGENT_AUTH_DIR
+// moved it, and the workspace table names it once, as a `secret` directory. This table classifies what is inside, so
+// an export does not carry this sandbox's own keys and pairings with the credentials, and does not drop the owner's
+// restrictions with them either. auth-state-coverage.test.ts in the daemon keeps it complete.
+//
+// The default for a path no entry claims is `secret`, the class of the directory itself: a provider home (`claude/`,
+// `codex/`, `cliproxy/`, `opencode/`…) is a login, and a new provider lands secret by construction.
+//
+// The classes follow the history table's precedent. A restriction the owner set is `carry`: a secret that travels must
+// not arrive ungated. A yes the owner gave (a grant, a release, a widened rule) is `identity`, like the hook and extension
+// approvals there: a trust decision the target's owner makes again.
+
+// Where the auth root sits inside the workspace when AGENT_AUTH_DIR does not move it; a declared workspace path.
+export const AUTH_ROOT_IN_WORKSPACE = `${STATE_DIR}/secrets/auth/` as const satisfies WorkspaceStatePath;
+
+// Auth-root-relative paths, forward-slash, matched by prefix; a directory keeps its trailing slash.
+export const AUTH_STATE_FILES: readonly StateFile[] = [
+    /* ---- the owner's restrictions: no credential in them, and loosened if left behind ---- */
+
+    // Which credentials need a named person's click (secrets/credential-gates.ts).
+    { path: "credential-gates.json", portability: "carry" },
+    // Where each secret may be sent (secrets/guards/host-guards.ts).
+    { path: "secret-hosts.json", portability: "carry" },
+    // The privacy shield's policy: whether it masks, what it looks for, which providers it trusts.
+    { path: "privacy-shield.json", portability: "carry" },
+    // The execution boundary agents run in (workload/domain/agent-domain-policy.ts).
+    { path: "agent-domain.json", portability: "carry" },
+
+    /* ---- credentials and what holds their values ---- */
+
+    { path: "sandbox-secrets.json", portability: "secret" },
+    { path: "capability-secrets.json", portability: "secret" },
+    { path: "extension-secrets.json", portability: "secret" },
+    // The personal data the shield masked, by token, and the pictures it painted over.
+    { path: "privacy-vault.json", portability: "secret" },
+    { path: "privacy-images/", portability: "secret" },
+    { path: "ssh-keys/", portability: "secret" },
+    // An update's pre-images of the files above; a vault's copy is a vault.
+    { path: "converting/", portability: "secret" },
+
+    /* ---- yeses the owner gave here: decided again on the target ---- */
+
+    // Sandbox-wide permissions ("Always: <line>") and each conversation's own (personas/owner-grants.ts,
+    // conversation-grants.ts); a conversation's card simply asks again, so only the sandbox-wide ones carry a note.
+    { path: "owner-grants.json", portability: "identity", note: "Give sandbox-wide permissions again from the Access tab." },
+    { path: "conversation-grants.json", portability: "identity" },
+    // An approver's release of a gated credential for one conversation.
+    { path: "credential-releases.json", portability: "identity" },
+    // Programs a secret may be typed into unasked; unset, every typing asks.
+    { path: "secret-programs.json", portability: "identity", note: "Allow programs to receive secrets again from Secrets." },
+    // Per-card credential rules and raw delivery, the owner's widening of a connector's own rules.
+    { path: "credential-policy.json", portability: "identity", note: "Set a connection's credential rules and delivery again from Capabilities." },
+
+    /* ---- this sandbox's own keys, and what it is paired with ---- */
+
+    // The keyring keypair the owner's computers pinned their shares to; only the public halves ever leave.
+    { path: "keyring-keys.json", portability: "identity", note: "Passwords shared from your computers are shared again with the new sandbox." },
+    // What each connected computer's keyring said, the entries copied to this sandbox's key, deliveries waiting for a
+    // computer, and the needs raised to them.
+    { path: "keyring-devices.json", portability: "identity" },
+    { path: "keyring-copies.json", portability: "identity" },
+    { path: "keyring-sync-mailbox.json", portability: "identity" },
+    { path: "keyring-needs.json", portability: "identity" },
+    // The credential broker's signing key and the privacy gateway's token key, each minted on first use.
+    { path: "broker-session.key", portability: "identity" },
+    { path: "privacy-gateway.key", portability: "identity" },
+    // The organisation policy the platform hands this sandbox; the target's platform hands its own.
+    { path: "org-policy.json", portability: "identity" },
+
+    /* ---- regenerated by the target ---- */
+
+    // Seat refusals the provider answered, and the model catalogs fetched for each runtime.
+    { path: "claude/seats.json", portability: "derived" },
+    { path: "claude/models.json", portability: "derived" },
+    { path: "cursor/models.json", portability: "derived" },
+    { path: "devin/models.json", portability: "derived" },
+    { path: "gemini/models.json", portability: "derived" },
+    // Each custom endpoint's last discovered model list, fetched again from the endpoint.
+    { path: "endpoints/", portability: "derived" },
+    // Values a computer released for one use each, for masking only; never outlive the process handed them.
+    { path: "keyring-released.json", portability: "derived" },
+    // The shell script and socket OpenCode runs commands through, written at boot.
+    { path: "opencode-shell/", portability: "derived" },
+];

package/src/state/runtime-state.ts

@@ -53,10 +53,11 @@ const RUNTIME_DOMAINS = [
     // Commit subject drafted after landing; arrives too late for the turn-end refresh, needs its own push.
     { domain: "landings", invalidates: [["git", "changes"]] },
 
-    // A pipeline run reached its end (webhook delivery, or the REST poll for a repo with no hook). The board's own
-    // poll is the freshness floor, not the answer: somebody watching a run finish must not wait out a poll interval.
-    // Runs only: the frame doesn't name which run moved, and re-reading every open row's job graph would cost a
-    // vendor call per row. The row re-reads its own graph off the status this invalidation lands (useRunJobs.ts).
+    // A pipeline run or one of its jobs moved: every webhook delivery, in flight or ended (2026-10-20), or the REST poll
+    // for a repo with no hook. The board's own poll is the freshness floor, not the answer: somebody watching a run
+    // must not wait out a poll interval. Runs only: the frame doesn't name which run moved, and re-reading every open
+    // row's job graph would cost a vendor call per row. An open in-flight row re-reads its own graph when the board's
+    // runs land (useRunJobs.ts); the daemon's CI-shaped watches recheck on it too (watchers.ts).
     { domain: "ci", invalidates: [["ci-runs"]] },
 
     // An engine install starting or ending, whoever started it; the card's only feed, since a read costs registry calls.
@@ -72,6 +73,11 @@ const RUNTIME_DOMAINS = [
     // A standing yes written or taken back outside a need's answer: a permission card's pass, a release, a purge. They
     // live under the auth root, which no file push watches, and the Allowed list must move with the card that wrote one.
     { domain: "grants", invalidates: [["grants"]] },
+
+    // Somebody's composer draft was written, cleared or sent. The frame names no conversation and carries no words, since
+    // every member hears it: each window reads back its own caller's drafts (agents.drafts). The key is the editor's draft
+    // store's, which reads them back itself rather than through a cached query (models/conversations/drafts/).
+    { domain: "drafts", invalidates: [["drafts"]] },
 ] as const satisfies readonly RuntimeDomainBinding[];
 
 export const RUNTIME_DOMAIN_BINDINGS: readonly RuntimeDomainBinding[] = RUNTIME_DOMAINS;

package/src/state/sandbox-build.test.ts

@@ -0,0 +1,95 @@
+import { DEV_SANDBOX_IMAGE } from "../policy/overlay-lint.js";
+import { buildParity, builtFromCheckout, rebuildPending, type RunningSandbox, type SandboxBuild, sameBuild, swapVerdict } from "./sandbox-build.js";
+
+// Every "which build" question is one of these, asked of two SandboxBuild records; a surface that compares fields of its
+// own choosing is how "pending rebuild" outlived a rebuild and a runner read outdated for good (2026-10).
+
+const stable = "ghcr.io/intentic/sandbox:stable";
+const digest = (byte: string): string => `sha256:${byte.repeat(64)}`;
+
+test("a rebuild is pending exactly when the overlay wanted is not the one running", () => {
+    expect(rebuildPending("h1", "h1")).toBe(false);
+    expect(rebuildPending("h2", "h1")).toBe(true);
+    // A stock container wanting an overlay waits for it; one wanting none waits for nothing, whatever it runs.
+    expect(rebuildPending("h1", undefined)).toBe(true);
+    expect(rebuildPending(undefined, undefined)).toBe(false);
+    expect(rebuildPending(undefined, "h1")).toBe(false);
+});
+
+test("a runner on the parent's base and overlay is current, and either moving is outdated", () => {
+    const parent: SandboxBuild = { base: stable, overlay: "abc123" };
+    expect(buildParity(parent, { ...parent })).toBe("current");
+    expect(buildParity(parent, { ...parent, overlay: "def456" })).toBe("outdated");
+    expect(buildParity(parent, { ...parent, base: "ghcr.io/intentic/sandbox:2.2.0" })).toBe("outdated");
+});
+
+test("an overlay on one side only is a difference; neither side having one is not", () => {
+    expect(buildParity({ base: stable }, { base: stable })).toBe("current");
+    expect(buildParity({ base: stable, overlay: "abc" }, { base: stable })).toBe("outdated");
+    expect(buildParity({ base: stable }, { base: stable, overlay: "abc" })).toBe("outdated");
+});
+
+// One tag is one name for whatever the registry held when each machine pulled it; the digest is the build.
+test("the base is compared by digest when both sides read one, and by its reference otherwise", () => {
+    expect(buildParity({ base: stable, baseDigest: digest("a") }, { base: stable, baseDigest: digest("b") })).toBe("outdated");
+    expect(buildParity({ base: stable, baseDigest: digest("a") }, { base: "ghcr.io/intentic/sandbox:beta", baseDigest: digest("a") })).toBe("current");
+    expect(buildParity({ base: stable, baseDigest: digest("a") }, { base: stable })).toBe("current");
+    expect(buildParity({ base: stable, baseDigest: digest("a") }, { base: "ghcr.io/intentic/sandbox:beta" })).toBe("outdated");
+});
+
+// Each machine's `intentic-sandbox:dev` is whatever its checkout held, so the name agreeing proves nothing, and an update
+// cannot bring it level: `ic` refuses to move a checkout build onto the published image (recreate.rs).
+test("nothing to compare, or a build from a checkout on either side, reads as unknown rather than as a warning", () => {
+    const parent: SandboxBuild = { base: stable, overlay: "abc" };
+    expect(buildParity(parent, undefined)).toBe("unknown");
+    expect(buildParity(parent, { base: "" })).toBe("unknown");
+    expect(buildParity({ base: "" }, parent)).toBe("unknown");
+    expect(buildParity({ base: DEV_SANDBOX_IMAGE, overlay: "abc" }, { base: DEV_SANDBOX_IMAGE, overlay: "abc" })).toBe("unknown");
+    expect(buildParity(parent, { base: DEV_SANDBOX_IMAGE, overlay: "abc" })).toBe("unknown");
+});
+
+// A rollback pin is a local tag too, and a rolled-back sandbox rejoins its channel by updating, not by a checkout.
+test("only the dogfood base is a build from a checkout", () => {
+    expect(builtFromCheckout({ base: DEV_SANDBOX_IMAGE })).toBe(true);
+    expect(builtFromCheckout({ base: stable })).toBe(false);
+    expect(builtFromCheckout({ base: "intentic-sandbox-rollback-demo:f6e917ce9b90" })).toBe(false);
+    expect(builtFromCheckout({ base: "" })).toBe(false);
+});
+
+// A swap is told landed by what answers, never by the version: a checkout build is 0.0.0 before and after, and an update
+// of one followed by "the version moved" waited out its deadline and said the sandbox never came back (2026-10).
+const running = (build: SandboxBuild, bootedAt: number): RunningSandbox => ({ build, bootedAt });
+
+test("two builds are the same only when something can tell, and differ the moment the overlay or digest does", () => {
+    expect(sameBuild({ base: stable, baseDigest: digest("a") }, { base: stable, baseDigest: digest("a") })).toBe(true);
+    expect(sameBuild({ base: stable, baseDigest: digest("a") }, { base: stable, baseDigest: digest("b") })).toBe(false);
+    expect(sameBuild({ base: stable, overlay: "h1" }, { base: stable, overlay: "h2" })).toBe(false);
+    expect(sameBuild({ base: stable }, { base: "ghcr.io/intentic/sandbox:beta" })).toBe(false);
+    expect(sameBuild({ base: stable }, { base: stable })).toBeUndefined();
+    expect(sameBuild({ base: DEV_SANDBOX_IMAGE }, { base: DEV_SANDBOX_IMAGE })).toBeUndefined();
+});
+
+test("an update of a checkout build lands on the new boot, though every version reads 0.0.0", () => {
+    const from = running({ base: DEV_SANDBOX_IMAGE }, 1000);
+    expect(swapVerdict({ from }, from)).toBe("waiting");
+    expect(swapVerdict({ from }, running({ base: DEV_SANDBOX_IMAGE }, 2000))).toBe("landed");
+});
+
+test("an update of a release lands when the digest moves, and a new boot on the old digest came back unmoved", () => {
+    const from = running({ base: stable, baseDigest: digest("a") }, 1000);
+    expect(swapVerdict({ from }, running({ base: stable, baseDigest: digest("b") }, 2000))).toBe("landed");
+    expect(swapVerdict({ from }, running({ base: stable, baseDigest: digest("a") }, 2000))).toBe("unmoved");
+    expect(swapVerdict({ from }, from)).toBe("waiting");
+    // A rollback names another tag: moved, digest or not.
+    expect(swapVerdict({ from: running({ base: stable }, 1000) }, running({ base: "ghcr.io/intentic/sandbox:0.9.0" }, 1000))).toBe("landed");
+});
+
+test("a rebuild lands on its overlay, and a new boot on any other overlay came back without it", () => {
+    const from = running({ base: stable, overlay: "old" }, 1000);
+    expect(swapVerdict({ from, overlay: "new" }, running({ base: stable, overlay: "new" }, 2000))).toBe("landed");
+    expect(swapVerdict({ from, overlay: "new" }, running({ base: stable, overlay: "old" }, 2000))).toBe("unmoved");
+    expect(swapVerdict({ from, overlay: "new" }, from)).toBe("waiting");
+    // Pressed with nothing read: only the overlay can say.
+    expect(swapVerdict({ from: undefined, overlay: "new" }, running({ base: stable, overlay: "new" }, 2000))).toBe("landed");
+    expect(swapVerdict({ from: undefined }, running({ base: stable }, 2000))).toBe("waiting");
+});