@intentic/sandbox-contract 1.302.0 → 1.304.0

package/src/contracts/agents.contract.ts

@@ -4,6 +4,7 @@ import {
     AgentArchiveSchema,
     AgentAssignSchema,
     AgentAutoLandSchema,
+    AgentBreakPolicySchema,
     AgentFileDiffQuerySchema,
     AgentIdSchema,
     AgentToolChildrenQuerySchema,
@@ -13,10 +14,7 @@ import {
     AgentPlaceSchema,
     AgentReactSchema,
     AgentRenameSchema,
-    AgentResumeAfterLimitSchema,
     AgentStopWatchingSchema,
-    AgentMoveAfterLimitSchema,
-    AgentResumeAfterOutageSchema,
     AgentsArchivedSchema,
     AgentSearchQuerySchema,
     AgentSearchResultSchema,
@@ -125,37 +123,16 @@ export const agentsContract = {
         .input(AgentAutoLandSchema)
         .output(AgentSummarySchema),
     // Legal for a workspace conversation too (unlike autoLand): an outage kills a main-tree chat just as readily.
-    resumeAfterOutage: oc
+    // Also offered on the card, not just in chat: a limit reopens hours later, so the decider is usually at a board.
+    breakPolicy: oc
         .route({
             method: "POST",
-            path: "/agents/{id}/resume-after-outage",
-            summary: "Whether this conversation retries after a provider outage",
+            path: "/agents/{id}/break-policy",
+            summary: "What this conversation does when a turn stops before it finished",
             description:
-                "Overrides the sandbox-wide setting for one conversation; clear it to follow the default again. This is what the offer shown when a turn dies writes, because the press happens inside one conversation and honestly means finish this piece of work.",
+                "One answer per ending — a spent usage limit, a provider outage, a turn that stopped short — overriding the sandbox-wide policy for one conversation; clear it to follow the default again. The answers are mutually exclusive by construction, so nothing here can arm two automations over the same wall. Every ending starts at `wait` unless asked otherwise, because a re-run spends the user's own allowance on a turn they sent once.",
         })
-        .input(AgentResumeAfterOutageSchema)
-        .output(AgentSummarySchema),
-    // Also offered on the card, not just chat: a limit reopens hours later, so the decider is usually at a board.
-    resumeAfterLimit: oc
-        .route({
-            method: "POST",
-            path: "/agents/{id}/resume-after-limit",
-            summary: "Whether this conversation sends itself again when its allowance comes back",
-            description:
-                "Overrides the sandbox-wide setting for one conversation; clear it to follow the default again. Off unless asked for, because the allowance is the user's own budget and a turn that spends it the moment it reopens is not a decision to make on their behalf.",
-        })
-        .input(AgentResumeAfterLimitSchema)
-        .output(AgentSummarySchema),
-    // Moves the held turn the moment the refusal lands, not on the next attempt.
-    moveAfterLimit: oc
-        .route({
-            method: "POST",
-            path: "/agents/{id}/move-after-limit",
-            summary: "Whether this conversation moves to another account when its allowance is spent",
-            description:
-                "Overrides the sandbox-wide setting for one conversation; clear it to follow the default again. A move spends a second account of the same provider on this conversation's behalf, so it is off unless asked for.",
-        })
-        .input(AgentMoveAfterLimitSchema)
+        .input(AgentBreakPolicySchema)
         .output(AgentSummarySchema),
     seen: oc
         .route({

package/src/contracts/areas.contract.ts

@@ -0,0 +1,42 @@
+import { oc } from "@orpc/contract";
+import { OkSchema } from "../schemas/shared.js";
+import { AreaIdParamSchema, AreaSchema, AreasListSchema } from "../schemas/areas.js";
+
+// Named parts of the workspace (AreaSchema), the unit a member's reach is granted in. Reading them is a member's own
+// business — a fenced person is shown the name of the fence they are behind — but writing one changes who sees what,
+// which is the one decision a revokable grant must not make, so the two writes below are owner-gated in-route the way
+// the roster is.
+export const areasContract = {
+    list: oc
+        .route({
+            method: "GET",
+            path: "/areas",
+            summary: "The named parts of the workspace",
+            description:
+                "Each area with the folders it admits. Access is granted in these rather than in folder lists per person, so widening what a team sees is one edit here instead of one edit per member.",
+        })
+        .output(AreasListSchema),
+    // Upsert by id, re-saving the same id edits that area.
+    save: oc
+        .route({
+            method: "POST",
+            path: "/areas",
+            summary: "Create or edit an area",
+            description:
+                "Writes the whole area; sending an id that exists edits it. Editing the folders of an area people already hold changes what those people see on their next request, which is why this is the sandbox owner's to do and why the file it writes is tracked and reviewable.",
+        })
+        .input(AreaSchema)
+        .output(OkSchema),
+    // Refused while anyone still holds it: a member row pointing at an area that no longer exists would either fail
+    // open (everything) or fail shut (nothing), and neither is a decision anybody made.
+    remove: oc
+        .route({
+            method: "DELETE",
+            path: "/areas/{id}",
+            summary: "Delete an area",
+            description:
+                "Removes the name and the folders behind it. Refused while a member still points at it, since nobody chose what such a row should then mean; move them onto another area first, or off areas entirely.",
+        })
+        .input(AreaIdParamSchema)
+        .output(OkSchema),
+};

package/src/contracts/endpoints.contract.ts

@@ -27,6 +27,65 @@ export const TrialStatusSchema = z.object({
 });
 export type TrialStatusResponse = z.infer<typeof TrialStatusSchema>;
 
+// Whether this container can reach an NVIDIA GPU, and how sure we are. The three states are not a tri-state boolean:
+// `absent` means nobody has asked yet, so the switch is still worth offering, while `unsupported` means the host's
+// Docker answered and has no nvidia runtime, which is a sentence to print rather than a switch to offer. Before the
+// grant the sandbox cannot see VRAM at all — only after it can `gpuMemoryBytes` be anything but zero.
+export const LocalModelGpuSchema = z.enum(["granted", "unsupported", "absent"]);
+export type LocalModelGpu = z.infer<typeof LocalModelGpuSchema>;
+
+// One window rung priced against one model, so a surface never has to redo the arithmetic the start check will.
+const LocalModelWindowFitSchema = z.object({
+    tokens: z.number().int().positive(),
+    // Weights + KV cache + the runtime's own floor: the same estimate the admission check refuses a start on.
+    totalBytes: z.number().int().nonnegative(),
+    fits: z.boolean(),
+});
+
+const LocalModelOptionFitSchema = z.object({
+    model: z.string(),
+    label: z.string(),
+    tier: z.enum(["instant", "work"]),
+    weightsBytes: z.number().int().nonnegative(),
+    // Already in the workspace cache, so adding it costs no download; true for anything a previous card fetched.
+    held: z.boolean(),
+    windows: z.array(LocalModelWindowFitSchema),
+});
+
+// What the weights the connect view offers to fetch ahead of being asked for are doing right now. Read-only: the POST
+// is what starts and stops it.
+export const LocalModelPrefetchSchema = z.object({
+    model: z.string(),
+    state: z.enum(["idle", "downloading", "held", "failed"]),
+    receivedBytes: z.number().int().nonnegative(),
+    // Zero where the server never said how big the file is; a progress bar must not invent a denominator.
+    totalBytes: z.number().int().nonnegative(),
+    detail: z.string().optional(),
+});
+export type LocalModelPrefetch = z.infer<typeof LocalModelPrefetchSchema>;
+
+export const LocalModelFitSchema = z.object({
+    // What this container may actually use: its cgroup cap where it has one, the machine's own RAM otherwise.
+    memoryBytes: z.number().int().nonnegative(),
+    // True when the number above is a container limit rather than the machine's: worth saying, since the host may look
+    // much larger than what a model can have.
+    memoryCapped: z.boolean(),
+    gpu: LocalModelGpuSchema,
+    gpuMemoryBytes: z.number().int().nonnegative(),
+    // The budget a start is actually admitted against, not the raw total: a view that sizes against anything else can
+    // recommend a model the daemon then refuses.
+    budgetBytes: z.number().int().nonnegative(),
+    // Whether llama-server is in this image. False means the local lane costs a rebuild before it can serve anything.
+    serverReady: z.boolean(),
+    options: z.array(LocalModelOptionFitSchema),
+    // The two the connect view offers by name. Each is a model plus the window it was priced at, ready to be added
+    // verbatim; absent where nothing on the list fits this machine, which is an answer, not an error.
+    instant: z.object({ model: z.string(), context: z.string() }).optional(),
+    best: z.object({ model: z.string(), context: z.string() }).optional(),
+    prefetch: LocalModelPrefetchSchema,
+});
+export type LocalModelFitResponse = z.infer<typeof LocalModelFitSchema>;
+
 export const endpointsContract = {
     models: oc
         .route({
@@ -47,4 +106,27 @@ export const endpointsContract = {
                 "The allowance, what has been used, when it resets, and which model actually answered the last message. Not being available is the ordinary answer rather than a failure: most sandboxes run against a platform that offers no trial at all.",
         })
         .output(TrialStatusSchema),
+    // Sized against this machine rather than a table in the browser, because the numbers that matter (a cgroup cap, a
+    // GPU that may not be passed through, weights already on disk) are only knowable in here.
+    localModelFit: oc
+        .route({
+            method: "GET",
+            path: "/endpoints/local-model/fit",
+            summary: "Which local models this machine can actually run",
+            description:
+                "The memory this sandbox may use, whether a GPU reached it, and every curated model priced against both, plus the two the connect view offers: one that downloads in a minute and one that is the best this machine can hold. Nothing here is a preference; it is what a start would be admitted or refused on.",
+        })
+        .output(LocalModelFitSchema),
+    // Start or stop fetching the instant model's weights before anyone has asked for them, so the first local turn does
+    // not begin with a download. Idempotent: starting twice joins the transfer already running.
+    localModelPrefetch: oc
+        .route({
+            method: "POST",
+            path: "/endpoints/local-model/prefetch",
+            summary: "Fetch the small model's weights ahead of being asked",
+            description:
+                "Downloads the curated instant model into the workspace cache so that adding it later costs nothing. Stopping leaves the part file, so a later start resumes from where this one stopped rather than beginning again.",
+        })
+        .input(z.object({ action: z.enum(["start", "stop"]) }))
+        .output(LocalModelPrefetchSchema),
 };

package/src/contracts/providers.contract.ts

@@ -7,6 +7,11 @@ import { ModelsSchema } from "../schemas/providers/provider-oauth.js";
 // this sandbox serves. Deliberately not the capability list (/capabilities, maintainer): a name and a label say what a
 // chat may run on, and say nothing about what holds a credential or what this box can reach.
 export const RunnableProvidersSchema = z.object({
+    // The one thing about the fixed native list this route says, and it says no more than the ACP and endpoint lists
+    // do: a name a message can be addressed to. Which account answers for it, and whose it is, stays behind
+    // /accounts, whose tier is a different question. Without this a reader who may drive a turn but not read that
+    // route sees no native provider as runnable and is told to connect one the box already has.
+    native: z.array(NativeProviderParamSchema.shape.provider).describe("Native providers with a working credential here, by id; never what holds it."),
     agents: z
         .array(z.object({ id: z.string(), label: z.string() }))
         .describe("ACP agents installed here. The id is the provider id itself, the label its display name."),

package/src/contracts/settings.contract.ts

@@ -1,13 +1,17 @@
+import { FIELD_NOTES_FILE } from "@intentic/constants";
 import { oc } from "@orpc/contract";
 import {
     BuiltinPromptSchema,
     BuiltinPromptTextSchema,
+    FieldNotesStatusSchema,
     REPO_CHECKS_FILE,
     RepoChecksAdoptSchema,
     RepoChecksListSchema,
     RuleFiringsSchema,
     SandboxSettingsSchema,
     SavingsReportSchema,
+    TimezoneOfferSchema,
+    TimezoneStateSchema,
 } from "../schemas/settings.js";
 import { OkSchema } from "../schemas/shared.js";
 import { DayWindowQuerySchema } from "../schemas/providers/usage.js";
@@ -73,6 +77,30 @@ export const settingsContract = {
             description: `Every repository that declares its own checks at \`${REPO_CHECKS_FILE}\`, what it declares, and whether you have switched it on. A repository declares what to run because the command belongs beside the scripts it names; nothing it declares runs until you say so.`,
         })
         .output(RepoChecksListSchema),
+    // Read off the file and the automation store rather than the settings manifest: nothing here is a choice anyone
+    // made, so storing it would only give it a second place to be wrong.
+    fieldNotes: oc
+        .route({
+            method: "GET",
+            path: "/settings/field-notes",
+            summary: "The state of this sandbox's field notes",
+            description: `Whether \`${FIELD_NOTES_FILE}\` exists, when it was last rewritten, how much of it the current budget reaches, and whether a monthly rewrite is scheduled.`,
+        })
+        .output(FieldNotesStatusSchema),
+    // Its own route rather than a field on `set`, for one reason: this is the only write that must NOT overwrite. The
+    // browser offers the zone it is in; the daemon takes it only if nobody has chosen one. Folding it into the
+    // whole-object `set` would mean the second machine to open the workspace silently moved every schedule to its own
+    // clock, and an owner in Warsaw would find their chores on a colleague's Tokyo hours.
+    adoptTimezone: oc
+        .route({
+            method: "POST",
+            path: "/settings/timezone",
+            summary: "Offer this sandbox a clock, if it has none",
+            description:
+                "Sets which timezone this sandbox's schedules are meant in, but only while it has none set. Already answered, the stored zone wins and comes back unchanged, so any number of browsers can offer theirs without fighting over it. To change a zone that is already set, write the settings.",
+        })
+        .input(TimezoneOfferSchema)
+        .output(TimezoneStateSchema),
     adoptRepoChecks: oc
         .route({
             method: "POST",

package/src/events/agent-events.ts

@@ -250,7 +250,10 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         resetsAt: z.number().optional(),
         // Gated codes only: "scheduled" if this conversation arms the resume, "available" if one exists but isn't.
         autoResume: z.enum(["scheduled", "available"]).optional(),
-        // rate_limit only: how re-running the exact held turn would go, and what it would cost.
+        // "scheduled" only: epoch seconds the booked send actually fires. Distinct from `resetsAt` (the provider's fact
+        // about the allowance) since a ladder rung can fall short of it, and a stopped turn has no allowance at all.
+        nextAt: z.number().optional(),
+        // A held turn, whatever wall stopped it: how re-running the exact turn would go, and what it would cost.
         held: z
             .object({
                 ran: z.boolean(),

package/src/events/transcript.ts

@@ -228,7 +228,7 @@ export const TranscriptRowSchema = z.object({
         ),
     // The one-press follow-up this notice offers, by name; the chat decides what it does, and whether it stands.
     noticeAction: z
-        .enum(["landHold", "outageOptOut", "depsInstall", "watchStop"])
+        .enum(["landHold", "depsInstall", "watchStop"])
         .optional()
         .describe("A one-press follow-up this notice offers, by name. The chat decides what it does and whether it still applies."),
     // An unfinished wait this notice describes, by name; whether it's still running is live state, not stored here.
@@ -329,6 +329,14 @@ export const TurnEndingSchema = z.object({
         .boolean()
         .optional()
         .describe("Whether something other than the user is already booked to send this turn again, so the surface reports the wait instead of offering a press."),
+    // `resetsAt` is the provider's fact about the allowance; this is the daemon's own appointment, and the two differ
+    // whenever a ladder rung falls short of the reset, or an ending with no allowance at all is armed.
+    nextAt: z
+        .number()
+        .optional()
+        .describe(
+            "When the booked send actually fires, in epoch seconds. Present only with `scheduled`; absent for a booking that fires on the next pass, which is 'now' to a reader.",
+        ),
 });
 export type TurnEnding = z.infer<typeof TurnEndingSchema>;
 

package/src/index.ts

@@ -5,6 +5,7 @@ import { activityContract } from "./contracts/activity.contract.js";
 import { agentContract } from "./contracts/agent.contract.js";
 import { agentsContract } from "./contracts/agents.contract.js";
 import { approvalsContract } from "./contracts/approvals.contract.js";
+import { areasContract } from "./contracts/areas.contract.js";
 import { automationsContract } from "./contracts/automations.contract.js";
 import { capabilitiesContract } from "./contracts/capabilities.contract.js";
 import { choresContract } from "./contracts/chores.contract.js";
@@ -46,11 +47,23 @@ export { activityContract } from "./contracts/activity.contract.js";
 export { agentContract } from "./contracts/agent.contract.js";
 export { agentsContract } from "./contracts/agents.contract.js";
 export { approvalsContract } from "./contracts/approvals.contract.js";
+export { areasContract } from "./contracts/areas.contract.js";
 export { automationsContract } from "./contracts/automations.contract.js";
 export { capabilitiesContract } from "./contracts/capabilities.contract.js";
 export { choresContract } from "./contracts/chores.contract.js";
 export { ciContract } from "./contracts/ci.contract.js";
-export { endpointsContract, type TrialHealth, TrialStatusSchema, type TrialStatusResponse } from "./contracts/endpoints.contract.js";
+export {
+    endpointsContract,
+    LocalModelFitSchema,
+    type LocalModelFitResponse,
+    type LocalModelGpu,
+    LocalModelGpuSchema,
+    type LocalModelPrefetch,
+    LocalModelPrefetchSchema,
+    type TrialHealth,
+    TrialStatusSchema,
+    type TrialStatusResponse,
+} from "./contracts/endpoints.contract.js";
 export { exitContract } from "./contracts/exit.contract.js";
 export { extensionsContract } from "./contracts/extensions.contract.js";
 export { personasContract } from "./contracts/personas.contract.js";
@@ -143,6 +156,9 @@ export * from "./policy/approvals-execution.js";
 // flat object, split back into path/body/query. `schemas/internal.ts` is absent: it's vocabulary, not a wire shape.
 export * from "./schemas/activity.js";
 export * from "./schemas/agent.js";
+export * from "./schemas/areas.js";
+export * from "./policy/fence-paths.js";
+export * from "./policy/persona-home.js";
 export * from "./schemas/agents.js";
 export * from "./schemas/approvals.js";
 export * from "./schemas/automations.js";
@@ -186,6 +202,7 @@ export * from "./schemas/share.js";
 export * from "./schemas/shared.js";
 export * from "./schemas/system.js";
 export * from "./schemas/terminal.js";
+export * from "./schemas/turn-break.js";
 export * from "./schemas/providers/usage.js";
 export * from "./schemas/vpn.js";
 export * from "./schemas/webext.js";
@@ -205,6 +222,7 @@ export * from "./text/model-answer.js";
 export * from "./text/whisper.js";
 export * from "./text/workflow-faults.js";
 export * from "./text/emoji.js";
+export * from "./time/zone.js";
 
 // The aggregated contract; implemented server-side by per-domain route factories, consumed by the browser's typed oRPC
 // client. Mounted at the sandbox root, alongside plain Hono routes like /health and /workspace/raw.
@@ -214,6 +232,7 @@ export const sandboxContract = {
     agent: agentContract,
     agents: agentsContract,
     approvals: approvalsContract,
+    areas: areasContract,
     automations: automationsContract,
     capabilities: capabilitiesContract,
     chores: choresContract,

package/src/models/agent-catalog.ts

@@ -156,7 +156,7 @@ export const modelsFor = (provider: AgentProvider): CatalogOption[] => {
 // Every reasoning tier a catalog row's `efforts` may name, weakest first. One vocabulary for every provider, so the
 // picker can label and order a ladder it has never seen; a provider spelling a rung its own way translates on the way
 // in, at the adapter that read it.
-export const EFFORT_TIERS: readonly string[] = ["minimal", "low", "medium", "high", "xhigh", "max"];
+export const EFFORT_TIERS: readonly string[] = ["minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
 
 // Filters exactly one pair: Claude's `max` with thinking explicitly false, the one combination Anthropic's API refuses
 // (400). Absent thinking is not off; the model's own default answers, every other tier or provider passes through.

package/src/policy/fence-paths.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, test } from "vitest";
+import { fenceAllows, fenceCovers, fenceIntersection, fenceReaches, foldPath, pathInsideFolder } from "./fence-paths.js";
+
+describe("foldPath", () => {
+    test("folds the spellings of one path into one answer", () => {
+        expect(foldPath("a/./b")).toBe("a/b");
+        expect(foldPath("a//b/")).toBe("a/b");
+        expect(foldPath("./a/b")).toBe("a/b");
+        expect(foldPath("a\\b")).toBe("a/b");
+        expect(foldPath("a/c/../b")).toBe("a/b");
+    });
+
+    test("the workspace root folds to the empty string, which is an answer and not a miss", () => {
+        expect(foldPath(".")).toBe("");
+        expect(foldPath("")).toBe("");
+    });
+
+    // A path that climbs out, or opens at a root, names something this workspace does not own; the fence has no say
+    // over it and must not be tricked into answering as if it did.
+    test("a path that leaves the workspace has no folded form", () => {
+        expect(foldPath("../elsewhere")).toBeUndefined();
+        expect(foldPath("a/../../elsewhere")).toBeUndefined();
+        expect(foldPath("/etc/passwd")).toBeUndefined();
+        expect(foldPath("C:/Windows")).toBeUndefined();
+    });
+});
+
+describe("pathInsideFolder", () => {
+    test("a folder holds itself and everything under it", () => {
+        expect(pathInsideFolder("apps/web", "apps/web")).toBe(true);
+        expect(pathInsideFolder("apps/web", "apps/web/src/main.ts")).toBe(true);
+    });
+
+    // The whole reason this is segment arithmetic rather than a string prefix.
+    test("a sibling sharing a prefix is not inside", () => {
+        expect(pathInsideFolder("apps/web", "apps/web2/main.ts")).toBe(false);
+        expect(pathInsideFolder("app", "app2")).toBe(false);
+    });
+
+    test("the workspace root holds every path in the workspace", () => {
+        expect(pathInsideFolder("", "anything/at/all")).toBe(true);
+    });
+
+    test("a climbing path is inside nothing", () => {
+        expect(pathInsideFolder("apps/web", "apps/web/../../secrets")).toBe(false);
+    });
+});
+
+describe("fenceAllows", () => {
+    test("no fence is the whole workspace", () => {
+        expect(fenceAllows(undefined, "finance/ledger.csv")).toBe(true);
+    });
+
+    // The distinction the type exists for: undefined is "unfenced", [] is "fenced to nothing".
+    test("an empty fence admits nothing", () => {
+        expect(fenceAllows([], "anything")).toBe(false);
+    });
+
+    test("a fence admits its own folders and refuses the rest", () => {
+        expect(fenceAllows(["support", "docs"], "support/tickets/1.md")).toBe(true);
+        expect(fenceAllows(["support", "docs"], "finance/payroll.csv")).toBe(false);
+    });
+});
+
+describe("fenceReaches", () => {
+    // Without this a fence on `finance/reports` would hide `finance` and leave the folder unreachable in a tree.
+    test("an ancestor of an allowed folder may still be listed", () => {
+        expect(fenceReaches(["finance/reports"], "finance")).toBe(true);
+        expect(fenceReaches(["finance/reports"], "")).toBe(true);
+    });
+
+    test("a sibling of an allowed folder is not reachable", () => {
+        expect(fenceReaches(["finance/reports"], "finance/payroll")).toBe(false);
+    });
+});
+
+describe("fenceCovers", () => {
+    test("the unfenced cover everything, and are covered by nothing else", () => {
+        expect(fenceCovers(undefined, ["anything"])).toBe(true);
+        expect(fenceCovers(["anything"], undefined)).toBe(false);
+    });
+
+    test("a fence covers another when every folder of it is inside one of its own", () => {
+        expect(fenceCovers(["apps"], ["apps/web", "apps/api"])).toBe(true);
+        expect(fenceCovers(["apps/web"], ["apps"])).toBe(false);
+    });
+
+    test("a fence covers the empty one, since nothing is inside everything", () => {
+        expect(fenceCovers(["apps/web"], [])).toBe(true);
+    });
+});
+
+describe("fenceIntersection", () => {
+    test("either side alone narrows to itself", () => {
+        expect(fenceIntersection(undefined, ["apps/web"])).toEqual(["apps/web"]);
+        expect(fenceIntersection(["apps/web"], undefined)).toEqual(["apps/web"]);
+        expect(fenceIntersection(undefined, undefined)).toBeUndefined();
+    });
+
+    // The narrower of the pair survives, whichever side it came from, so a persona asking for more than its starter
+    // holds gets the starter's answer.
+    test("the tighter folder is what survives, from whichever side", () => {
+        expect(fenceIntersection(["apps"], ["apps/web"])).toEqual(["apps/web"]);
+        expect(fenceIntersection(["apps/web"], ["apps"])).toEqual(["apps/web"]);
+    });
+
+    test("disjoint fences meet at nothing, which is a fence admitting nothing", () => {
+        expect(fenceIntersection(["apps/web"], ["finance"])).toEqual([]);
+    });
+
+    test("overlapping folders are not repeated", () => {
+        expect(fenceIntersection(["apps", "apps/web"], ["apps/web"])).toEqual(["apps/web"]);
+    });
+});

package/src/policy/fence-paths.ts

@@ -0,0 +1,99 @@
+import { PUBLIC_DIR, STATE_DIR } from "@intentic/constants";
+
+// The path arithmetic a workspace fence is made of: whether a path is inside a folder, whether one set of folders
+// covers another, and what a fenced tree may still list. Pure and shared, because the daemon refuses on these answers
+// and the browser draws on them, and two implementations would disagree at exactly the boundary that matters.
+
+// Workspace-relative, forward-slash, no climb: segments are folded so `a/./b` and `a/b` are one path, and a path that
+// climbs above the root folds to `undefined` rather than to something inside it.
+// The root itself is "" — a real answer, not a missing one.
+export const foldPath = (raw: string): string | undefined => {
+    if (raw.startsWith("/") || /^[A-Za-z]:/.test(raw)) {
+        return undefined;
+    }
+    const segments: string[] = [];
+    for (const segment of raw.split(/[\\/]/)) {
+        if (segment === "" || segment === ".") {
+            continue;
+        }
+        if (segment !== "..") {
+            segments.push(segment);
+            continue;
+        }
+        if (segments.pop() === undefined) {
+            return undefined;
+        }
+    }
+    return segments.join("/");
+};
+
+// Whether `path` is `folder` or lives under it, by segment rather than by string prefix: `app2` is not inside `app`.
+// An unfoldable path is inside nothing.
+export const pathInsideFolder = (folder: string, path: string): boolean => {
+    const outer = foldPath(folder);
+    const inner = foldPath(path);
+    if (outer === undefined || inner === undefined) {
+        return false;
+    }
+    return outer === "" || inner === outer || inner.startsWith(`${outer}/`);
+};
+
+// "Change the sandbox" as paths: the daemon's own configuration, and the outbox the internet reads. One list, read by
+// the persona hook that judges a turn's writes and by the area schema that decides what a grant may name.
+export const SANDBOX_PATHS: readonly string[] = [STATE_DIR, PUBLIC_DIR];
+
+// Whether a path is one of those folders or sits inside one, by segment: `publications` is not `public`.
+// No area may name such a folder, which is what keeps a fence from handing anyone the config that decides what agents
+// may do — the enumerated control-plane table (state/workspace-state.ts) locks named entries, not the whole tree.
+export const isSandboxPath = (path: string): boolean => SANDBOX_PATHS.some((folder) => pathInsideFolder(folder, path));
+
+// A fence: the folders a caller may touch, or undefined for the whole workspace. Undefined and `[]` are deliberately
+// different answers — no fence at all, versus a fence that admits nothing.
+export type Fence = readonly string[] | undefined;
+
+/** Whether the fence admits this path at all: reading it, writing it, searching in it. */
+export const fenceAllows = (fence: Fence, path: string): boolean => fence === undefined || fence.some((folder) => pathInsideFolder(folder, path));
+
+/**
+ * Whether a fenced tree may still LIST this path: everything the fence allows, plus the ancestors leading down to it.
+ * Without the ancestors a fence on `finance/reports` would hide `finance` itself and leave the folder unreachable.
+ */
+export const fenceReaches = (fence: Fence, path: string): boolean => {
+    if (fenceAllows(fence, path)) {
+        return true;
+    }
+    const inner = foldPath(path);
+    return inner !== undefined && (fence ?? []).some((folder) => pathInsideFolder(inner, folder));
+};
+
+/**
+ * Whether `outer` covers `inner`: every folder the inner fence admits is one the outer fence admits too. The question
+ * behind every narrowing-only rule — handing work across, inheriting a fence — since a fence that covers another can
+ * safely stand in for it.
+ */
+export const fenceCovers = (outer: Fence, inner: Fence): boolean => {
+    if (outer === undefined) {
+        return true;
+    }
+    if (inner === undefined) {
+        return false;
+    }
+    return inner.every((folder) => fenceAllows(outer, folder));
+};
+
+/**
+ * The tighter of two fences: what a turn may touch when a persona's folders meet the member's own. Undefined on both
+ * sides is the whole workspace; either side alone narrows to itself.
+ */
+export const fenceIntersection = (left: Fence, right: Fence): Fence => {
+    if (left === undefined) {
+        return right;
+    }
+    if (right === undefined) {
+        return left;
+    }
+    // A folder survives only where one side contains it; the containing side's folder is already the narrower of the
+    // pair, so taking each side's contained folders and deduping gives the intersection with no overlap left over.
+    const kept = [...left.filter((folder) => fenceAllows(right, folder)), ...right.filter((folder) => fenceAllows(left, folder))];
+    return [...new Set(kept.map((folder) => foldPath(folder) ?? folder))];
+};

package/src/policy/persona-home.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "vitest";
+import { fenceHoldsPersona, personaHome } from "./persona-home.js";
+
+// Where a card lives, and therefore who may wear it. This is the whole of the rule the Access tab draws and the
+// daemon refuses on, so the three shapes a card can name a place in are each pinned here.
+
+describe("personaHome", () => {
+    test("the folder it opens in is its home, even when it may touch more", () => {
+        expect(personaHome({ workspace: { startIn: "support" } })).toEqual(["support"]);
+        expect(personaHome({ workspace: { startIn: "support", folders: ["support", "shared"] } })).toEqual(["support"]);
+    });
+
+    test("with no starting folder, the folders it may touch are its home", () => {
+        expect(personaHome({ workspace: { folders: ["finance", "billing"] } })).toEqual(["finance", "billing"]);
+    });
+
+    test("naming no place at all is the workspace root, which is not a folder any fence can hold", () => {
+        expect(personaHome({})).toBeUndefined();
+        expect(personaHome({ workspace: {} })).toBeUndefined();
+        expect(personaHome({ workspace: { folders: [] } })).toBeUndefined();
+    });
+});
+
+describe("fenceHoldsPersona", () => {
+    const support = { workspace: { startIn: "support/inbox" } };
+    const finance = { workspace: { startIn: "finance" } };
+    const anywhere = { workspace: { folders: ["finance", "support"] } };
+
+    test("an unfenced holder wears every card, root-homed ones included", () => {
+        expect(fenceHoldsPersona(undefined, support)).toBe(true);
+        expect(fenceHoldsPersona(undefined, {})).toBe(true);
+    });
+
+    test("a fenced holder wears the cards homed inside its folders and no others", () => {
+        expect(fenceHoldsPersona(["support"], support)).toBe(true);
+        expect(fenceHoldsPersona(["support"], finance)).toBe(false);
+        // By segment, not by string prefix: `support2` is not inside `support`.
+        expect(fenceHoldsPersona(["support"], { workspace: { startIn: "support2" } })).toBe(false);
+    });
+
+    test("a card spanning more than the fence is not held: the fence has to cover all of it", () => {
+        expect(fenceHoldsPersona(["support"], anywhere)).toBe(false);
+        expect(fenceHoldsPersona(["support", "finance"], anywhere)).toBe(true);
+    });
+
+    // The one card no fence can reach, whatever it names: everything is inside the root, so holding it would be
+    // holding the workspace.
+    test("a card homed at the root is the owner's alone", () => {
+        expect(fenceHoldsPersona(["support"], {})).toBe(false);
+        expect(fenceHoldsPersona([], {})).toBe(false);
+    });
+});