@intentic/sandbox-contract 1.343.0 → 1.344.0

package/src/schemas/devices.ts

@@ -1,5 +1,6 @@
 // What one of the user's own machines is running.
 import { z } from "zod";
+import { DeviceBridgeHoldSchema, DeviceConflictSchema, DeviceLowDiskSchema } from "./device-folder.js";
 import { parseHostConnection, type DeviceFacts, DeviceFactsSchema, MachineIdSchema, userDistrosOf, WslEnvironmentSchema } from "./hosts.js";
 import { RollbackTargetSchema, UpdateOutcomeSchema } from "./updates.js";
 import { DEV_VERSION } from "../state/versions.js";
@@ -316,38 +317,8 @@ export const DeviceCommandResultSchema = z.object({
 });
 export type DeviceCommandResult = z.infer<typeof DeviceCommandResultSchema>;
 
-// What one side did to a conflicted path. The first three are Mutagen's own change kinds. `untracked` is its word for
-// content it SCANS but never carries — whatever sits under an ignore pattern, which for a workspace means build output
-// — and it is the whole difference between a conflict somebody must settle and one a device can clear by itself. Absent
-// means Mutagen did not say, not that a side is untouched.
-export const DeviceConflictChangeSchema = z.enum(["created", "modified", "deleted", "untracked"]);
-export type DeviceConflictChange = z.infer<typeof DeviceConflictChangeSchema>;
-
-// Which of two unlike things this conflict is. `both-edited` is the one the mode exists for: two real copies, one
-// choice, a person's. `derived-leftover` is not a disagreement at all — one side deleted a directory, the other still
-// holds build output inside it, and Mutagen will not delete a directory whose contents it never carried. Nothing at
-// stake, nobody's edit, and no judgement to make.
-export const DeviceConflictNatureSchema = z.enum(["derived-leftover", "both-edited"]);
-export type DeviceConflictNature = z.infer<typeof DeviceConflictNatureSchema>;
-
-export const DeviceConflictSchema = z.object({
-    /** Relative to the synced folder (matches both `localDir` and /work); empty means the root itself. */
-    path: z.string(),
-    /** What happened on the device (Mutagen's alpha). */
-    local: DeviceConflictChangeSchema.optional(),
-    /** And in the sandbox's /work (its beta). */
-    sandbox: DeviceConflictChangeSchema.optional(),
-    // Absent from an agent older than the classification, which is why no reader may treat absence as `both-edited`:
-    // `clearableOnDevice` below tests for the derived shape rather than against the other one.
-    nature: DeviceConflictNatureSchema.optional(),
-});
-export type DeviceConflict = z.infer<typeof DeviceConflictSchema>;
-
-// Whether this one is the device's own to clear: build output on the device, inside a directory the sandbox deleted.
-// The rule lives here because two sides read it — the machine agent deciding what to remove, and the browser deciding
-// whether to offer a button instead of an agent — and they must never disagree about which conflicts need a person.
-export const clearableOnDevice = (conflict: DeviceConflict): boolean =>
-    conflict.nature === "derived-leftover" && conflict.local === "untracked" && conflict.sandbox === "deleted";
+// What a synced folder reports beyond Mutagen's word, its conflicts and what the device holds back (device-folder.ts).
+export * from "./device-folder.js";
 
 // One paired sandbox as the local agent holds it; `localDir` is which folder on that device holds this sandbox's /work.
 export const DevicePairingSchema = z.object({
@@ -378,6 +349,10 @@ export const DevicePairingSchema = z.object({
     paused: z.boolean().optional(),
     // Second session's status (the state-dir backup mirror), reported separately: the two fail independently.
     backupStatus: z.string().optional(),
+    // (2026-10-18) While the drive holding `localDir` is nearly full, the reading that paused its sync and git bridge; and the
+    // repos whose git history stopped following for a while (device-folder.ts). Each absent while it does not hold.
+    lowDisk: DeviceLowDiskSchema.optional(),
+    bridgeHolds: z.array(DeviceBridgeHoldSchema).optional(),
 });
 export type DevicePairing = z.infer<typeof DevicePairingSchema>;
 // One sandbox port and what became of it on this machine's localhost; carries a state rather than just live forwards,
@@ -574,14 +549,14 @@ export const DeviceSchema = z.object({
     gap: DeviceGapSchema.optional(),
 });
 export type Device = z.infer<typeof DeviceSchema>;
-// (2026-10-15) A device enrollment no capability card holds: a key into this sandbox for which no board draws a machine,
-// since a machine is drawn from its card. Listed so the owner can withdraw it (`DELETE /system/hosts/{id}`, `id` being the
-// connection key); never withdrawn by the daemon itself, since the manifest the cards live in is a workspace file a land
-// can rewrite for a moment, and withdrawing on that would unpair real devices.
+// Device keys no machine is drawn for, each list absent when empty: enrollments no card holds, which only the owner withdraws (a land can rewrite
+// the card manifest for a moment), and connections live at once that report one machine id, kept rather than deduped (hosts/host-dedupe.ts).
 export const CardlessHostSchema = z.object({ id: z.string(), card: z.string(), environment: z.string() });
 export type CardlessHost = z.infer<typeof CardlessHostSchema>;
-// `cardlessHosts` is absent when there are none, and from a daemon older than the field.
-export const DevicesListSchema = z.object({ devices: z.array(DeviceSchema), cardlessHosts: z.array(CardlessHostSchema).optional() });
+export const SharedIdentitySchema = z.object({ machineId: z.string(), connections: z.array(CardlessHostSchema) });
+export type SharedIdentity = z.infer<typeof SharedIdentitySchema>;
+const deviceKeyNotes = { cardlessHosts: z.array(CardlessHostSchema).optional(), sharedIdentities: z.array(SharedIdentitySchema).optional() };
+export const DevicesListSchema = z.object({ devices: z.array(DeviceSchema), ...deviceKeyNotes });
 export type DevicesList = z.infer<typeof DevicesListSchema>;
 
 // The physical computer a device is an environment of. Windows and every WSL distro on it are one machine with one

package/src/schemas/metrics.ts

@@ -97,7 +97,9 @@ export const SandboxUsageSchema = z.object({
             countedFileCacheBytes: z
                 .number()
                 .optional()
-                .describe("File cache counted in resident usage (memory.stat file less inactive_file), in bytes. Absent unless both counters are valid."),
+                .describe(
+                    "File cache counted in resident usage (memory.stat file less inactive_file), in bytes. Absent unless both counters are valid.",
+                ),
             kernelBytes: z
                 .number()
                 .optional()
@@ -163,7 +165,9 @@ export const SandboxMetricsSchema = z.object({
         .optional()
         .describe("How long the CPU figures were measured over, in milliseconds. Absent on a first reading, and then so is every CPU figure."),
     sandbox: SandboxUsageSchema.describe("The sandbox as a whole, including the daemon."),
-    daemon: DaemonUsageSchema.describe("The daemon's own usage, included in the sandbox total and process count but excluded from roles and session sums."),
+    daemon: DaemonUsageSchema.describe(
+        "The daemon's own usage, included in the sandbox total and process count but excluded from roles and session sums.",
+    ),
     sessions: z
         .record(z.string(), SessionMetricsSchema)
         .describe(
@@ -273,8 +277,29 @@ export const StorageScanSchema = z.object({
 export type StorageScan = z.infer<typeof StorageScanSchema>;
 
 export const StorageReportSchema = z.object({
-    scan: StorageScanSchema.optional().describe("The last scan that finished, kept across restarts; its `finishedAt` says how old it is. Absent until one has."),
+    scan: StorageScanSchema.optional().describe(
+        "The last scan that finished, kept across restarts; its `finishedAt` says how old it is. Absent until one has.",
+    ),
     scanning: z.boolean().describe("Whether a scan is running now."),
+    historyDisk: z
+        .object({
+            freeBytes: z.number().describe("Space available to the sandbox on the history volume, measured now."),
+            totalBytes: z.number().describe("The history volume's total size."),
+            floorBytes: z.number().describe("Space kept free before a new checkout: 2% of this volume clamped to 5–20 GiB."),
+            low: z.boolean().describe("Whether available history space is below the checkout floor."),
+        })
+        .optional()
+        .describe("The filesystem holding conversation checkouts, independent of the workspace volume. Absent if unreadable."),
+    repositoryCheckouts: z
+        .array(
+            z.object({
+                repo: z.string().describe("The live repository's workspace-relative id, or root for the workspace repository."),
+                head: z.string().describe("The commit whose tracked blobs were measured."),
+                bytes: z.number().describe("The sum of blob sizes at this HEAD: the estimated bytes for one full checkout."),
+            }),
+        )
+        .optional()
+        .describe("Live repositories' checkout costs, cached per repository and commit. Repositories without a readable HEAD are omitted."),
 });
 export type StorageReport = z.infer<typeof StorageReportSchema>;
 

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

@@ -13,7 +13,13 @@ 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.",