@intentic/sandbox-contract 1.302.0 → 1.304.0

package/src/schemas/turn-break.ts

@@ -0,0 +1,49 @@
+// turn-break: what happens next when a turn stops before it finished
+//
+// One ending, one question, one answer. A turn stops for exactly one reason, and that reason gets a single
+// mutually-exclusive answer — never a set of switches that can all be armed at once over the same event. The chat
+// asks it about the ending in front of the reader; Settings holds the standing answer per ending; a conversation may
+// override either.
+
+import { z } from "zod";
+
+// The three endings that leave finished work behind a live session and can be picked back up. Spelled exactly as
+// `TurnEndingSchema.reason` spells them, so the ending a surface reads and the question it asks are one word. A restart
+// is handled apart (SandboxSettings.autoResumeOnRestart): nobody is watching a restart, so it has no in-chat question.
+export const TurnBreakSchema = z.enum(["limit", "outage", "stopped"]);
+export type TurnBreak = z.infer<typeof TurnBreakSchema>;
+
+// `move` implies `resend`: an account with room is tried at once, and the reset appointment stands as its fallback.
+// There is deliberately no "move, else hold" — a reader willing to spend a second account is willing to wait.
+export const LimitPolicySchema = z.enum(["wait", "resend", "move"]);
+export type LimitPolicy = z.infer<typeof LimitPolicySchema>;
+
+// Both ladders answer the same way, so they share a vocabulary: nothing, or keep trying on a bounded ladder.
+export const RetryPolicySchema = z.enum(["wait", "retry"]);
+export type RetryPolicy = z.infer<typeof RetryPolicySchema>;
+
+// One answer, whichever ending asked. Read against the ending: only `limit` can be `move`.
+export const TurnBreakPolicySchema = z.enum(["wait", "resend", "move", "retry"]);
+export type TurnBreakPolicy = z.infer<typeof TurnBreakPolicySchema>;
+
+// Which answers an ending may take, so a surface offers exactly these and a writer refuses anything else.
+export const TURN_BREAK_POLICIES: Readonly<Record<TurnBreak, readonly TurnBreakPolicy[]>> = {
+    limit: ["wait", "resend", "move"],
+    outage: ["wait", "retry"],
+    stopped: ["wait", "retry"],
+};
+
+/** Whether this ending may be answered this way; the one gate every writer goes through. */
+export const isTurnBreakPolicy = (ending: TurnBreak, policy: string): policy is TurnBreakPolicy =>
+    (TURN_BREAK_POLICIES[ending] as readonly string[]).includes(policy);
+
+/** Whether an answer means something happens without the reader; the one read every "is it armed" question makes. */
+export const breakArmed = (policy: TurnBreakPolicy): boolean => policy !== "wait";
+
+// How many times a bounded ladder re-runs a turn that gets nowhere before standing down. Quoted in the notice it
+// leaves, so the number and the sentence cannot drift.
+export const RETRY_LADDER_MS = [5_000, 15_000, 45_000] as const;
+export const RETRY_LADDER_TRIES = RETRY_LADDER_MS.length;
+
+/** The wait before the next rung, or undefined once the ladder is spent. */
+export const retryLadderDelay = (triesWithoutProgress: number): number | undefined => RETRY_LADDER_MS[triesWithoutProgress];

package/src/state/history-state.ts

@@ -19,6 +19,10 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // Armed condition watches; carries safely: the journal holds no credential, only names re-derived on target.
     { path: "watches/", portability: "carry" },
     { path: "transcripts/", portability: "carry" },
+    // One runtime session store per fenced conversation, holding for it what `.intentic/records/sessions/claude/` holds
+    // for every other: its own transcripts, plans, backups and checklists, kept off /work so no other conversation's
+    // namespace can reach them. Carried for the same reason that one is.
+    { path: "sessions/", portability: "carry" },
     // What each message can restore to (a checkpoint or isolated commit); the join between transcripts and scopes.
     { path: "turn-anchors.json", portability: "carry" },
     // Index of published-page conversations; the pages travel with /work anyway, this makes one withdrawable.

package/src/state/workspace-state.test.ts

@@ -33,9 +33,10 @@ describe(`staleQueryKeys`, () => {
         expect(staleQueryKeys([`.intentic/config/capabilities.json`], [])).toEqual([`capabilities`, `environment`, `panels`, `manifests`]);
     });
 
-    it(`refreshes the unreadable-manifest notice for the three files a person hand-edits`, () => {
+    it(`refreshes the unreadable-manifest notice for the four files a person hand-edits`, () => {
         const carries = WORKSPACE_STATE_FILES.filter((file) => file.invalidates.includes(`manifests`)).map((file) => file.path);
         expect(carries.toSorted()).toEqual([
+            `.intentic/config/areas.json`,
             `.intentic/config/capabilities.json`,
             `.intentic/config/personas.json`,
             `.intentic/config/settings.json`,
@@ -316,9 +317,12 @@ describe(`VERSIONED_STATE_PATHS`, () => {
     });
 
     // Spelled out rather than derived, so adding a tracked entry is a visible edit here, not a silent side effect.
-    it(`tracks exactly the configuration slice plus the agent's own authored output`, () => {
+    it(`tracks exactly the configuration files plus the agent's own authored output`, () => {
         expect(VERSIONED_STATE_PATHS.toSorted()).toEqual([
             `${STATE_DIR}/config/approvals/`,
+            // Which folders each named area holds: editing one moves what everyone granted it can see, so the
+            // change belongs in a diff rather than only in a screen.
+            `${STATE_DIR}/config/areas.json`,
             `${STATE_DIR}/config/automations.json`,
             // Which apps the daemon starts at boot: the starter site, plus whatever the owner adds.
             `${STATE_DIR}/config/autostart.json`,
@@ -493,7 +497,7 @@ describe(`SHARED_STATE_PATHS`, () => {
     });
 });
 
-// Pins the split: the authored slice that now backs up, and the credentials that still must not.
+// Pins the split: the authored area that now backs up, and the credentials that still must not.
 describe(`BACKED_UP_STATE_PATHS`, () => {
     it(`splits the table in two with nothing falling between`, () => {
         expect([...BACKED_UP_STATE_PATHS, ...UNBACKED_STATE_PATHS].toSorted()).toEqual(WORKSPACE_STATE_FILES.map((file) => file.path).toSorted());

package/src/state/workspace-state.ts

@@ -72,6 +72,13 @@ const STATE_FILES = [
     // capability catalog. `carry`: a card is a name and ids, never a credential.
     { path: ".intentic/config/personas.json", invalidates: ["personas", "capabilities", "manifests"], portability: "carry", versioned: true },
 
+    // Named parts of the workspace (AreaSchema), the unit a person's reach is granted in. `carry`: folder names, no
+    // credential, and a workspace that moves keeps the shape of its own fences. `versioned` because editing an area
+    // changes what people already granted it can see, which is precisely a change a human should review. It stays
+    // agent-writable like personas.json, and is safe there for a reason worth stating: a fenced conversation's own
+    // fence has to admit `.intentic` before its agent can reach this file, so no fence can widen itself.
+    { path: ".intentic/config/areas.json", invalidates: ["areas", "manifests"], portability: "carry", versioned: true },
+
     // Four files split by portability, not just prefix: `custom` is the owner-approved source and the only one that
     // must travel; `approved` is composed from custom + capability fragments + the base image and is rebuilt on the
     // target's first boot (carrying it would ship a `FROM` naming an image the target may not have); the proposal and
@@ -475,7 +482,7 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = STATE_FILES;
 // entry `versioned` is the only change needed.
 export const VERSIONED_STATE_PATHS: readonly string[] = WORKSPACE_STATE_FILES.filter((file) => file.versioned).map((file) => file.path);
 
-// Slice a workspace search may surface: `versioned` config plus `authored` content (approvals, staged docs,
+// What a workspace search may surface: `versioned` config plus `authored` content (approvals, staged docs,
 // workspace extensions). Everything else under `.intentic` is machine state, denied by default. `auth/`, where
 // vaulted credentials live, is always denied regardless.
 export const SEARCHABLE_STATE_PATHS: readonly string[] = WORKSPACE_STATE_FILES.filter((file) => file.versioned || file.authored).map(
@@ -552,7 +559,7 @@ export const SHARED_STATE_PATHS: readonly string[] = STATE_GROUPS.flatMap((group
         : [`${STATE_GROUP_DIR[group]}/`];
 });
 
-// Slice desktop-sync copies down: ordinary state and the records binding this sandbox to its owner, minus anything
+// What desktop-sync copies down: ordinary state and the records binding this sandbox to its owner, minus anything
 // that opts out via `backup: false`. Deliberately not the same question as the export bundle: a bundle asks what
 // may be reconstituted elsewhere, this asks what the owner may keep a copy of.
 export const BACKED_UP_STATE_PATHS: readonly string[] = WORKSPACE_STATE_FILES.filter(

package/src/text/transcript-fold.test.ts

@@ -188,11 +188,9 @@ describe("foldTurn", () => {
                 outage: { retryAt: 1, attempt: 2, maxAttempts: 6 },
             },
         ];
-        expect(foldOf("hi", outage).at(-1)).toEqual({
-            role: "notice",
-            text: "Anthropic is down. Retrying by itself: attempt 2 of 6.",
-            noticeAction: "outageOptOut",
-        });
+        // The row states what happened and nothing more: what happens next, and the one control that changes it, are
+        // the chat card's, asked once (ChatContinueStrip), not a second switch on a transcript line.
+        expect(foldOf("hi", outage).at(-1)).toEqual({ role: "notice", text: "Anthropic is down. Retrying by itself: attempt 2 of 6." });
         const renewal: AgentEvent[] = [{ kind: "error", code: "claude-token-refused", message: "Token refused.", autoResume: "scheduled" }];
         expect(foldOf("hi", renewal).at(-1)).toEqual({
             role: "notice",

package/src/text/transcript-fold.ts

@@ -96,18 +96,14 @@ const errorRow = (event: Extract<AgentEvent, { kind: "error" }>): TranscriptRow
     switch (code) {
         case "provider-outage":
             return event.outage === undefined
-                ? { role: "notice", text: `${message} Nothing is retrying it, so the turn is waiting: keep this chat going and it continues from here.` }
-                : {
-                      role: "notice",
-                      text: `${message} Retrying by itself: attempt ${event.outage.attempt} of ${event.outage.maxAttempts}.`,
-                      ...(event.autoResume === "scheduled" ? { noticeAction: "outageOptOut" } : {}),
-                  };
+                ? { role: "notice", text: `${message} Nothing is retrying it, so the turn is waiting here.` }
+                : { role: "notice", text: `${message} Retrying by itself: attempt ${event.outage.attempt} of ${event.outage.maxAttempts}.` };
         case "claude-token-refused":
             return event.autoResume === "scheduled"
                 ? { role: "notice", text: `${message} The credential is being renewed and this turn continues automatically.`, noticeWait: "credentialRenewal" }
                 : { role: "notice", text: `${message} Reconnect the account to pick this conversation back up.` };
         case "rate_limit":
-            return { role: "notice", text: event.autoResume === "scheduled" ? `${message} This chat sends it again once the allowance comes back.` : message };
+            return { role: "notice", text: message };
         // Refused before the model saw it; the composer holds the message so the user can resend it.
         case "claude-reauth":
         case "unknown-command":

package/src/time/zone.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "vitest";
+import { asCivilDay, asZone, civilDayIn, cronOptions, isZone, sameClock, utcDayOf, UTC, zoneLabel } from "./zone.js";
+import type { Zone } from "./zone.js";
+
+// The distinctions this module exists to keep, each of which was a live bug before it: a cron evaluated in the
+// process's zone instead of the author's, a civil day rendered as if it were an instant, and a zone label shown to a
+// reader who is already on that clock.
+
+const WARSAW = "Europe/Warsaw" as Zone;
+const NEW_YORK = "America/New_York" as Zone;
+// 2026-09-20T20:43Z. Warsaw is +2 (summer time), New York -4.
+const SEPTEMBER = Date.UTC(2026, 8, 20, 20, 43);
+// 2026-12-20T20:43Z. Warsaw is +1, New York -5: the same two zones, different offsets.
+const DECEMBER = Date.UTC(2026, 11, 20, 20, 43);
+
+describe(`isZone`, () => {
+    test(`accepts what ICU knows and refuses what it does not`, () => {
+        expect(isZone(`Europe/Warsaw`)).toBe(true);
+        expect(isZone(`UTC`)).toBe(true);
+        expect(isZone(`Europe/Warszawa`)).toBe(false);
+        expect(isZone(``)).toBe(false);
+    });
+
+    /* An offset is not a zone: it cannot say what happens in March, which is the whole reason schedules need a zone. */
+    test(`refuses a bare offset, which is the shape that looks like it would work`, () => {
+        expect(isZone(`+02:00`)).toBe(false);
+        expect(isZone(`UTC+2`)).toBe(false);
+    });
+
+    test(`asZone passes real ids through and swallows the rest`, () => {
+        expect(asZone(`America/New_York`)).toBe(`America/New_York`);
+        expect(asZone(`Mars/Olympus`)).toBeUndefined();
+        expect(asZone(undefined)).toBeUndefined();
+    });
+});
+
+describe(`civilDayIn`, () => {
+    /* THE ONE THAT MATTERS: one instant, three zones, three different calendar days. */
+    test(`an instant falls on different days depending on the zone asked`, () => {
+        // 2026-09-20T23:30Z: already the 21st in Warsaw, still the 20th in UTC and New York.
+        const lateEvening = Date.UTC(2026, 8, 20, 23, 30);
+        expect(civilDayIn(lateEvening, WARSAW)).toBe(`2026-09-21`);
+        expect(civilDayIn(lateEvening, UTC)).toBe(`2026-09-20`);
+        expect(civilDayIn(lateEvening, NEW_YORK)).toBe(`2026-09-20`);
+    });
+
+    test(`utcDayOf is civilDayIn UTC, spelled so every UTC bucket is greppable`, () => {
+        expect(utcDayOf(SEPTEMBER)).toBe(civilDayIn(SEPTEMBER, UTC));
+    });
+
+    test(`asCivilDay takes the shape and nothing else`, () => {
+        expect(asCivilDay(`2026-09-20`)).toBe(`2026-09-20`);
+        expect(asCivilDay(`2026-09-20T00:00:00Z`)).toBeUndefined();
+        expect(asCivilDay(`20/09/2026`)).toBeUndefined();
+    });
+});
+
+describe(`sameClock`, () => {
+    test(`two zones on the same offset right now read as one clock`, () => {
+        expect(sameClock(WARSAW, `Europe/Berlin` as Zone, SEPTEMBER)).toBe(true);
+        expect(sameClock(WARSAW, UTC, SEPTEMBER)).toBe(false);
+    });
+
+    /* Asked at an instant, not in the abstract: London and Warsaw differ all year, London and UTC only in summer. */
+    test(`the answer is a property of the instant, not of the pair`, () => {
+        expect(sameClock(`Europe/London` as Zone, UTC, SEPTEMBER)).toBe(false);
+        expect(sameClock(`Europe/London` as Zone, UTC, DECEMBER)).toBe(true);
+    });
+});
+
+describe(`zoneLabel`, () => {
+    test(`names the zone for a reader on a different clock`, () => {
+        expect(zoneLabel(WARSAW, NEW_YORK, SEPTEMBER)).toBe(`Europe/Warsaw`);
+    });
+
+    test(`stays quiet for a reader already on that clock, rather than adding width for nothing`, () => {
+        expect(zoneLabel(WARSAW, `Europe/Berlin` as Zone, SEPTEMBER)).toBeUndefined();
+        expect(zoneLabel(UTC, UTC, SEPTEMBER)).toBeUndefined();
+    });
+
+    test(`underscores become spaces, since the id is read as words here`, () => {
+        expect(zoneLabel(NEW_YORK, UTC, SEPTEMBER)).toBe(`America/New York`);
+    });
+});
+
+describe(`cronOptions`, () => {
+    test(`hands croner the key it actually reads`, () => {
+        expect(cronOptions(WARSAW)).toEqual({ timezone: `Europe/Warsaw` });
+    });
+});

package/src/time/zone.ts

@@ -0,0 +1,118 @@
+// The vocabulary for time values that cross a machine boundary, and the one rule behind all of it: an INSTANT means
+// the same thing everywhere, a WALL RULE means nothing without a zone, and a CIVIL DAY is a zone's opinion wearing the
+// costume of a fact.
+//
+// Intentic runs its daemon in a UTC container and its editor in whatever zone the reader's laptop is in. Anything that
+// says "at 09:00" was authored on one of those machines and evaluated on the other, so the zone has to travel with it
+// or the two disagree by the offset — silently, since both sides render a plausible number.
+//
+// Instants stay plain `number` (epoch ms) deliberately. That convention is already universal in this codebase and
+// already safe; branding it would touch thousands of call sites to prevent a mistake nobody is making. The two types
+// below are branded because they are the two that DO get confused for an instant, and each confusion is a shipped bug:
+// a civil day rendered in the reader's zone slides a day westward, and a cron evaluated in the wrong zone fires at the
+// wrong hour.
+import { z } from "zod";
+
+/**
+ * A named IANA zone ("Europe/Warsaw"), never a fixed offset. An offset cannot express the summer-time rule that moves
+ * "09:00" twice a year, which is exactly what a recurring schedule has to survive.
+ */
+export type Zone = string & { readonly __brand: "Zone" };
+
+/** The daemon's own zone, and the answer for a sandbox whose owner has never said where they are. */
+export const UTC = "UTC" as Zone;
+
+/**
+ * Whether ICU knows this id AND it names a place rather than an offset. The platform's own tables are the only honest
+ * source for the first half; the second half has to be enforced here, because ICU accepts `+02:00` as a `timeZone`
+ * since ES2024 and that is exactly the shape a naive `getTimezoneOffset()` would produce. A fixed offset is frozen at
+ * the moment it was read: a schedule stored as `+02:00` in September fires an hour off for the whole of the winter.
+ * `Etc/GMT+5` is left alone — it is a real id somebody may genuinely be on, not an accident of arithmetic.
+ */
+export const isZone = (value: string): value is Zone => {
+    if (value.startsWith("+") || value.startsWith("-")) {
+        return false;
+    }
+    try {
+        return Intl.DateTimeFormat("en", { timeZone: value }).resolvedOptions().timeZone !== "";
+    } catch {
+        return false;
+    }
+};
+
+/** An id from outside (a manifest, a migrated config, a browser) as a `Zone`, or undefined if ICU does not know it. */
+export const asZone = (value: string | undefined): Zone | undefined => (value !== undefined && isZone(value) ? value : undefined);
+
+// Rejects at the edge rather than at the croner call: an unknown zone in a manifest should fail the save that
+// introduced it, where somebody is still watching, not the tick three hours later.
+export const ZoneSchema = z.string().refine(isZone, { message: "Not a zone name ICU knows, e.g. Europe/Warsaw or UTC." });
+
+/**
+ * The zone the reader's own machine is in. Browser-side only by nature — in the daemon this answers UTC, which is true
+ * but useless, and is why the sandbox keeps a zone setting instead of asking its own clock.
+ */
+export const localZone = (): Zone => Intl.DateTimeFormat().resolvedOptions().timeZone as Zone;
+
+/**
+ * A calendar day as `YYYY-MM-DD`, carrying no time and no zone of its own. Branded so it cannot be handed to a
+ * formatter expecting an instant: `new Date("2026-09-20")` parses as UTC midnight, and rendering that in a zone behind
+ * UTC prints the 19th. That bug is invisible to whoever writes it, because it is correct in their own zone.
+ */
+export type CivilDay = string & { readonly __brand: "CivilDay" };
+
+export const CivilDaySchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "A calendar day as YYYY-MM-DD.");
+
+/** The calendar day an instant falls on, in a named zone. `en-CA` because its short date format IS ISO order. */
+export const civilDayIn = (at: number, zone: Zone): CivilDay =>
+    new Intl.DateTimeFormat("en-CA", { timeZone: zone, year: "numeric", month: "2-digit", day: "2-digit" }).format(at) as CivilDay;
+
+/** The UTC calendar day of an instant. Named rather than spelled inline, so every UTC bucket in the tree is greppable. */
+export const utcDayOf = (at: number): CivilDay => new Date(at).toISOString().slice(0, 10) as CivilDay;
+
+/**
+ * An instant as a person on a named clock would read it: "2026-09-20 20:43". For text the daemon writes — a log line,
+ * a note handed to an agent — where an ISO stamp is unambiguous but unreadable, and where the daemon cannot use the
+ * editor's formatters because there is no reader in the room. Never for the interface: on screen an instant is drawn
+ * in the reader's own clock, by `_editor/ui/src/lib/format.ts`.
+ * `sv-SE` because its short format is ISO-shaped, which is the point: no locale ambiguity in a machine-written line.
+ */
+export const wallClockIn = (at: number, zone: Zone): string =>
+    new Intl.DateTimeFormat("sv-SE", { timeZone: zone, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hour12: false })
+        .format(at)
+        .replace(",", "");
+
+/** A `YYYY-MM-DD` from a store, a query string or a fixture. Undefined for anything that is not one. */
+export const asCivilDay = (value: string | undefined): CivilDay | undefined => (value !== undefined && /^\d{4}-\d{2}-\d{2}$/.test(value) ? (value as CivilDay) : undefined);
+
+/**
+ * A recurring wall-clock rule: the cron AND the zone it is meant in, which is the only form in which it means anything.
+ * Kept as one type so the two cannot be passed around separately and drift apart — the original bug was a `cron:
+ * string` travelling alone from a browser in Europe/Warsaw to a daemon in UTC.
+ */
+export interface WallRule {
+    readonly cron: string;
+    readonly tz: Zone;
+}
+
+/** What croner has to be given. Never call `new Cron(expr)` bare: that silently means "in whatever zone this process is". */
+export const cronOptions = (tz: Zone): { timezone: string } => ({ timezone: tz });
+
+// The offset of a zone at an instant, in minutes east of UTC. Via the formatter's own `longOffset` part, since the
+// arithmetic alternative (formatting twice and subtracting) gets the summer-time changeover hour wrong.
+const offsetMinutes = (at: number, zone: Zone): number => {
+    const part = new Intl.DateTimeFormat("en", { timeZone: zone, timeZoneName: "longOffset" }).formatToParts(at).find((p) => p.type === "timeZoneName")?.value;
+    const match = /GMT([+-])(\d{2}):(\d{2})/.exec(part ?? "");
+    if (match === null) {
+        return 0; // "GMT" with no offset is UTC itself.
+    }
+    return (match[1] === "-" ? -1 : 1) * (Number(match[2]) * 60 + Number(match[3]));
+};
+
+/** Whether two zones are showing the same wall clock right now — which is when naming one on screen would be noise. */
+export const sameClock = (a: Zone, b: Zone, at: number = Date.now()): boolean => a === b || offsetMinutes(at, a) === offsetMinutes(at, b);
+
+/**
+ * How to name a zone beside a wall-clock time, or undefined when the reader is already on that clock and the label
+ * would only add width. The city, not the offset: "Europe/Warsaw" survives the March changeover, "UTC+2" does not.
+ */
+export const zoneLabel = (rule: Zone, reader: Zone, at: number = Date.now()): string | undefined => (sameClock(rule, reader, at) ? undefined : rule.replace(/_/g, " "));