@intentic/sandbox-contract 1.264.1 → 1.266.0

package/src/chores/stack.test.ts

@@ -100,8 +100,7 @@ describe(`recognising the stack`, () => {
     });
 });
 
-// The stem normalizer is the component-overlap chore's only evidence; each case is a family that must form, or must
-// not.
+// Keep component-overlap cases explicit when stems must not form a family.
 describe(`the name two components share`, () => {
     test(`framework and qualifier noise falls away`, () => {
         expect(componentStem(`src/components/Button.vue`)).toBe(`button`);

package/src/chores/workspace-scope.ts

@@ -1,8 +1,4 @@
-/* Maintenance probes normally run inside one discovered repository, where a `refs/` directory is ordinary
- * project content. They also run once against the workspace root, where the same first segment is the reserved
- * reference shelf and can hold hundreds of thousands of files. The daemon sets this variable only for that
- * root scope; shell commands opt into the matching prune argument without baking the shelf's name into the
- * browser-safe contract package. */
+/* Maintenance probes normally run inside one discovered repository, where a `refs/` directory is ordinary project content. */
 export const WORKSPACE_ROOT_EXCLUDE_ENV = `INTENTIC_WORKSPACE_ROOT_EXCLUDE`;
 
 // Unquoted parameter expansion is intentional: when the variable is absent it contributes zero arguments;

package/src/contracts/issues.contract.ts

@@ -2,14 +2,7 @@ import { oc } from "@orpc/contract";
 import { IssueIdParamSchema, IssueInstallsSchema, IssueIntakeIdParamSchema, IssuesListSchema, IssueStatusInputSchema } from "../schemas/issues.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* The issues inbox: bug reports that arrived from the owner's own sites and apps, grouped by fingerprint.
- *
- * THE OWNER'S SIDE ONLY. Reports come in through the public `/intake/…` routes, which are deliberately a
- * different prefix rather than a verb on this one: those are reachable by any browser on the internet, these
- * are not, and two id spaces (an automation's public id out there, an issue's fingerprint in here) sharing one
- * path prefix is how a widened rule stops being visible.
- *
- * Nothing here creates an issue. The daemon writes them; this is triage. */
+/* The issues inbox: bug reports that arrived from the owner's own sites and apps, grouped by fingerprint. */
 export const issuesContract = {
     list: oc
         .route({

package/src/contracts/workspace.contract.ts

@@ -7,6 +7,7 @@ import {
     AppParamSchema,
     AppsListSchema,
     CloneRepoSchema,
+    CreateRepoSchema,
     CloneResultSchema,
     RepoAppsParamSchema,
     ReposListSchema,
@@ -14,9 +15,9 @@ import {
     TemplatesListSchema,
     WorkspaceGraphSchema,
     WorkspaceSyncSchema,
-} from "../schemas/workspace-repos.js";
-import { WorkspaceSearchQuerySchema, WorkspaceSearchResultSchema } from "../schemas/workspace-search.js";
-import { WorkspaceInstallResultSchema, WorkspaceInstallSchema, WorkspaceSetupSchema } from "../schemas/workspace-setup.js";
+} from "../schemas/workspace/workspace-repos.js";
+import { WorkspaceSearchQuerySchema, WorkspaceSearchResultSchema } from "../schemas/workspace/workspace-search.js";
+import { WorkspaceInstallResultSchema, WorkspaceInstallSchema, WorkspaceSetupSchema } from "../schemas/workspace/workspace-setup.js";
 import {
     WorkspaceChildrenQuerySchema,
     WorkspaceChildrenSchema,
@@ -34,7 +35,7 @@ import {
     WorkspaceResolveSchema,
     WorkspaceScopeSchema,
     WorkspaceTreeSchema,
-} from "../schemas/workspace-tree.js";
+} from "../schemas/workspace/workspace-tree.js";
 
 // The full /work view plus extra-repo cloning. /workspace/raw stays a plain Hono route (a streamed binary body doesn't
 // fit oRPC's request/response shape).
@@ -224,6 +225,16 @@ export const workspaceContract = {
         })
         .input(CloneRepoSchema)
         .output(CloneResultSchema),
+    createRepo: oc
+        .route({
+            method: "POST",
+            path: "/workspace/repos/new",
+            summary: "Start a new repo",
+            description:
+                "Makes an empty repository in the workspace: a folder named after it, initialised, with a README that names it and one commit, so an agent can start on it at once. Nothing is cloned and nothing leaves the machine.",
+        })
+        .input(CreateRepoSchema)
+        .output(CloneResultSchema),
     // Mutates the tree (fetch + fast-forward), which is why this is POST rather than GET.
     sync: oc
         .route({

package/src/events/cards.ts

@@ -157,6 +157,15 @@ export type TodoItem = z.infer<typeof TodoItemSchema>;
 export const ContextUsageSchema = z.object({
     tokens: z.number().describe("How much the latest request sent, all told."),
     contextWindow: z.number().describe("How much the model can hold. The gap between these two is how close the conversation is to being compacted."),
+    // Both absent unless the turn's last request actually used the prompt cache; a provider whose TTL we cannot ground
+    // reports neither rather than a guessed pair.
+    cachedAt: z
+        .number()
+        .optional()
+        .describe(
+            "When that request last touched the provider's prompt cache, in milliseconds. The cache's clock runs from here, since a read refreshes it as a write does.",
+        ),
+    cacheTtlMs: z.number().optional().describe("How long that cache entry lives from `cachedAt`, in milliseconds."),
 });
 export type ContextUsage = z.infer<typeof ContextUsageSchema>;
 

package/src/ids/share-paths.test.ts

@@ -1,9 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { SHARE_ID, shareId, shareStem } from "./share-paths.js";
 
-/* The id a shared conversation is filed under is two things at once: the readable half of a link somebody
- * pastes, and the half of the address that has to be safe to join onto a directory path. Both halves are
- * checked here, because the id is minted from a TITLE the user typed. */
+/* The id a shared conversation is filed under is two things at once: the readable half of a link somebody pastes. */
 
 describe("the readable half", () => {
     it("makes a link that says what it points at", () => {
@@ -25,8 +23,7 @@ describe("the readable half", () => {
 });
 
 describe("the safe half", () => {
-    /* The id is joined onto a path, so a title is the one attacker-shaped input in it. These are the shapes
-     * that would matter if the alphabet were not closed. */
+    /* The id is joined onto a path, so a title is the one attacker-shaped input in it. These are the shapes. */
     it.each([
         ["../../etc/passwd", "etc-passwd"],
         ["a/b", "a-b"],

package/src/index.ts

@@ -180,10 +180,10 @@ export * from "./schemas/usage.js";
 export * from "./schemas/vpn.js";
 export * from "./schemas/webext.js";
 export * from "./schemas/workflows.js";
-export * from "./schemas/workspace-repos.js";
-export * from "./schemas/workspace-search.js";
-export * from "./schemas/workspace-setup.js";
-export * from "./schemas/workspace-tree.js";
+export * from "./schemas/workspace/workspace-repos.js";
+export * from "./schemas/workspace/workspace-search.js";
+export * from "./schemas/workspace/workspace-setup.js";
+export * from "./schemas/workspace/workspace-tree.js";
 export * from "./state/arrival.js";
 export * from "./state/definition.js";
 export * from "./policy/search-globs.js";

package/src/models/provider-specs.test.ts

@@ -57,8 +57,7 @@ describe("every provider in the table", () => {
                     /\/v\d+$/,
                 );
                 expect(variant.label.trim(), `${id}/${variant.id} has no estate label`).not.toBe("");
-                // The lookup every surface goes through, not the row behind it: a named variant must resolve to itself
-                // only.
+                // Resolve each named variant exactly to itself.
                 expect(mintedVariant(id, variant.id), `${id}/${variant.id} does not resolve`).toEqual(variant);
             }
             // An absent variant defaults to the list's head: what a single-estate row or a choice-less login/start

package/src/models/provider-specs.ts

@@ -162,8 +162,7 @@ export const PROVIDER_SPECS = [
         access: { kind: "subscription", requirement: "Muse Code subscription", runs: "Muse Spark under Claude Code" },
         auth: {
             kind: "minted",
-            // One estate, no choice to offer; the id still exists since a stored account records which variant minted
-            // it.
+            // Preserve the minted variant id because stored accounts reference it.
             variants: [
                 {
                     id: "meta",

package/src/policy/batch-runs.ts

@@ -55,21 +55,7 @@ export const parseBatchFile = <T>(text: string, shape: (value: Record<string, un
     }
 };
 
-/* WHAT THE AGENT IS TOLD ABOUT WHERE TO LEAVE ITS ANSWER, appended to whatever prompt the pack composed.
- *
- * WHY THE AGENT WRITES A FILE AND NOT A ROUTE. A ledger is a daemon route, and reaching it from a turn would
- * mean handing the agent a token and a client it needs for nothing else. Writing one small JSON file is
- * something every agent can already do, and the surface promotes finished runs when it next sees them. The
- * promotion is idempotent and re-runs on every poll, so nothing is lost by not being watched.
- *
- * `outcomes` is the pack's vocabulary and is spelled out in full, because a closed set is what lets a surface
- * debounce without hiding anything: an agent that verified some findings and concluded they were false
- * positives has to be able to SAY so, or the next poll starts the same turn again forever. Pass the
- * explanations with the words — a model that reads an outcome as an admission of having done nothing useful
- * will avoid it and report something else, and the surface never goes quiet.
- *
- * The closing line is not decoration. A turn that concludes there was nothing to do and writes no file is
- * indistinguishable from a turn that died, and the surface has to show the second as an unknown. */
+/* WHAT THE AGENT IS TOLD ABOUT WHERE TO LEAVE ITS ANSWER, appended to whatever prompt the pack composed. */
 export const batchReportingClause = (params: { readonly path: string; readonly fields: string; readonly outcomes?: string | undefined }): string =>
     [
         `When you are finished, write your conclusion to ${params.path} as JSON:`,
@@ -78,23 +64,8 @@ export const batchReportingClause = (params: { readonly path: string; readonly f
         `Write that file even if you conclude there was nothing to do.`,
     ].join(`\n\n`);
 
-/* THE BODY OF THE `POST /agent` THAT STARTS ONE ITEM, so the flag combination that makes a run a run is decided
- * once. `isolated: true` with a conversationId is the shape (and the only shape) that registers a fleet entry,
- * which is why none of these packs owns session machinery; `unattended: true` is what the turn IS — started by
- * a row rather than by a person at a composer — and `runRole` is which of those rows, so the daemon answers
- * with the owner's list FOR THAT JOB (model-roles.ts) unless the caller pinned a model on the row's caret, in
- * which case the pick rides along and the daemon's fill step leaves it alone.
- *
- * PERMISSIONS AND ISOLATION ARE THE CALLER'S, deliberately. They are the two decisions that differ by kind and
- * both are about safety rather than plumbing: an acceptance test that parks on a permission card is a test that
- * never finishes, so that surface trades the prompt away; a maintenance chore is different in kind — nobody is
- * waiting on it, it may take until tomorrow, and a sweep that can answer its own permission prompts is exactly
- * the thing an owner would want to have been asked about. A default here would decide that for both. */
-/* WHAT THE CARET ON THE RUN BUTTON CHOSE, in the shell's own vocabulary (`provider`; the turn calls it `agent`).
- * Every field but the provider is optional and absent means absent: the turn goes out without it and the model's
- * own default answers. All of them travel, because all of them are things the picker can now set and each is a
- * different price — a run re-pointed at a frontier model but not at the tier, the loop or the account it was
- * pinned under is not the run the reader configured. */
+/* The batch request fixes the isolation and run flags for one item. */
+/* WHAT THE CARET ON THE RUN BUTTON CHOSE, in the shell's own vocabulary (`provider`; the turn calls it `agent`). */
 export interface BatchTurnPick {
     readonly provider: string;
     readonly model?: string | undefined;

package/src/policy/capability-env.ts

@@ -1,9 +1,4 @@
-/* HOW A CLI CAPABILITY'S ENV VARS ARE NAMED, the one rule both ends of that wire have to apply.
- *
- * The daemon writes the agent's shell env by suffixing every var a cli connector declares with the instance id
- * (cli-env.ts), so two connections of the same provider coexist on one flat environment. A connector's own
- * TOOL then has to read them back, and an extension may not import daemon internals, so without this the
- * rule would be spelled twice, and a change to it would silently split the writer from the reader. */
+/* HOW A CLI CAPABILITY'S ENV VARS ARE NAMED, the one rule both ends of that wire have to apply. */
 
 // `analytics` → `POSTGRES_URL_ANALYTICS`; the default-named `github` → `GITHUB_TOKEN_GITHUB`.
 // ponytail: ids differing only by case or `-`/`_` (my-db vs my_db) map to the same suffix, last wins.

package/src/policy/owner-ticket.test.ts

@@ -38,8 +38,7 @@ describe("owner ticket", () => {
         expect(isOwnerTicket("ig1.x.y")).toBe(false);
     });
 
-    /* One key signs both the reachability grant and the owner ticket, and neither may ever pass as the other:
-     * a grant is a sandbox's right to serve its hostnames, a ticket is a person's right to drive it. */
+    /* One key signs both the reachability grant and the owner ticket, and neither may ever pass as the other. */
     it("is never a reachability grant, and a grant is never a ticket", () => {
         const ticket = mintOwnerTicket(privatePem, { sandboxId: "0123456789ab", email: "o@x.dev", issuedAtMs: NOW });
         const grant = mintReachabilityGrant(privatePem, "0123456789ab", NOW);

package/src/protocol/host-protocol.ts

@@ -7,12 +7,7 @@ import { z } from "zod";
 // Shared with the daemon's peer bridge, which answers the handshake itself when the machine is asleep.
 export const MCP_PROTOCOL_VERSION = "2025-06-18";
 
-/* HOW OFTEN THIS DOOR PINGS A CONNECTED MACHINE, read by both sides of the socket: the daemon's hub pings on
- * it (hosts/host-peer.ts) and the agent presumes a link dead after a few of them pass in silence
- * (peer-dial.ts's peerLinkSilenceMs). Frequent enough to stay inside the idle timeout of every tunnel and proxy
- * in the path, and it is the failure of a ping that tells the daemon a lid closed without a close frame ever
- * arriving. One number, because the two sides disagreeing about it is a device that is either dropped while
- * healthy or believed alive for as long as its socket stays open. */
+/* HOW OFTEN THIS DOOR PINGS A CONNECTED MACHINE, read by both sides of the socket. */
 export const HOST_HEARTBEAT_MS = 30_000;
 
 export const HostHelloSchema = z.object({

package/src/protocol/peer-dial.test.ts

@@ -1,9 +1,7 @@
 import { expect, test, vi } from "vitest";
 import { dialPeer, type SocketLike } from "./peer-dial.js";
 
-/* The loop every peer runs, over a socket the test plays. What is at stake is the order of the two phases
- * (handler attached BEFORE the hello goes out), the retry after a drop, the one close that is never retried,
- * and that a stop reaches a dial still deciding where to go. */
+/* The loop every peer runs, over a socket the test plays. */
 
 class FakeSocket implements SocketLike {
     readyState = 0;
@@ -117,10 +115,7 @@ test("a drop redials on the ladder, telling it how long the socket held", async
     }
 });
 
-/* THE DROP NOBODY REPORTS, which is the one that used to last for days: a far end that is gone while the socket
- * stays open — a sandbox container recreated behind a port relay that outlived it, a NAT that forgot the flow, a
- * laptop's wifi suspended mid-session. Note what this test never calls: `drops`. Nothing closes, nothing errors,
- * and the loop has to reach the conclusion on its own or hold a dead link forever. */
+/* A silent socket must be abandoned even when no close event arrives. */
 test("a socket that goes silent is abandoned and redialled, though no close ever arrives", async () => {
     vi.useFakeTimers();
     try {
@@ -157,10 +152,7 @@ test("a socket that goes silent is abandoned and redialled, though no close ever
     }
 });
 
-/* THE FAR END THAT IS NEVER COMING BACK, which is not a failure the loop can fix and not one it may narrate
- * forever: a sandbox deleted, a tunnel repointed, a machine left on for a week. Every attempt here errors and
- * closes without ever opening, exactly as a laptop's agent did 1,992 times into a 2.3 MB log. What is asserted
- * is BOTH halves: the log stops repeating, and the dialling does not slow down to achieve it. */
+/* THE FAR END THAT IS NEVER COMING BACK, which is not a failure the loop can fix and not one it may narrate. */
 test("a far end that never answers is reported a few times, then retried quietly at the same cadence", async () => {
     vi.useFakeTimers();
     try {

package/src/protocol/peer-dial.ts

@@ -5,32 +5,11 @@
 // Reconnect backoff: fast floor for a restart, low cap so a reopened laptop is back within a minute.
 export const PEER_LINK_BACKOFF = { floorMs: 1_000, capMs: 30_000, stableMs: 60_000 } as const;
 
-/* HOW MUCH A LINK THAT CANNOT BE REACHED IS ALLOWED TO SAY, which is a different question from how often it
- * may try. At the cap above, a far end that is gone for good — a sandbox deleted, a tunnel pointed elsewhere —
- * costs two lines every 30 seconds for as long as the machine is on: 5,760 a day. One laptop's agent had
- * written 1,992 pairs of them, 2.3 MB, and this log is exactly where its owner had been sent to read why a
- * DIFFERENT thing had failed; the answer was in there, under an hour of repetition.
- *
- * The cadence is not the problem and is deliberately untouched — a reopened laptop must be back within a
- * minute, which is what the low cap buys. The REPETITION is. So the first few failures are reported in full,
- * then the loop says so once more to mark that it is going quiet, and after that repeats itself at most once
- * per QUIET_LOG_MS with the attempt count that says how long it has been trying. A link that opens resets all
- * of it: every reconnect is news, and the reconnect line is what reports it. */
+/* HOW MUCH A LINK THAT CANNOT BE REACHED IS ALLOWED TO SAY, which is a different question from how often it may try. */
 const LOUD_ATTEMPTS = 3;
 const QUIET_LOG_MS = 10 * 60_000;
 
-/* HOW LONG A SOCKET MAY SAY NOTHING before this side calls the link dead, as a multiple of the door's own
- * heartbeat: the hub pings every live peer on an interval (peer-hub.ts), so a socket with nothing on it for
- * three heartbeats is not quiet, it is gone.
- *
- * WHY A PEER NEEDS THIS AT ALL — a close event is not guaranteed, and the loop below has nothing else to react
- * to. The socket that taught us is a loopback one: a machine agent dialling a sandbox container on its own
- * machine through Docker Desktop's port relay. The container was recreated; the relay was not, so it held the
- * agent's TCP connection open with nothing behind it. No FIN, no error, no close event — the agent held an open
- * socket to a daemon that had never heard of it for 25 hours, its Devices card offline the whole time, every
- * control on that card dead, and the only cure anyone found was re-running setup by hand. Any path with a
- * middlebox in it (a NAT, a tunnel, a userland proxy, a laptop's suspended wifi) can do this to a socket with
- * nothing to say, and the middlebox is never the side that notices. The peer is. */
+/* HOW LONG A SOCKET MAY SAY NOTHING before this side calls the link dead, as a multiple of the door's own heartbeat. */
 export const PEER_LINK_SILENCE_HEARTBEATS = 3;
 export const peerLinkSilenceMs = (heartbeatMs: number): number => heartbeatMs * PEER_LINK_SILENCE_HEARTBEATS;
 
@@ -43,9 +22,7 @@ const OPEN = 1;
 // Structural interface a browser's WebSocket, node's global one, and a test's fake all satisfy without a cast.
 export interface SocketLike {
     readonly readyState: number;
-    /* `message` is here for the watchdog alone, which needs no more than the fact that one arrived: what is IN
-     * the frames belongs to the oRPC handler `attach` hands the socket to, and a listener added here does not
-     * take it from that one (both runtimes' sockets fan an event out to every listener). */
+/* `message` is here for the watchdog alone, which needs no more than the fact that one arrived. */
     addEventListener(type: "open" | "close" | "error" | "message", listener: (event: { readonly code?: number }) => void): void;
     send(data: string): void;
     close(code?: number, reason?: string): void;
@@ -61,10 +38,7 @@ export interface PeerDialSpec<S extends SocketLike> {
     readonly attach: (socket: S) => void;
     // The retry ladder: how long to wait after a drop, given how long the socket had held.
     readonly backoff: { readonly next: (heldMs: number) => number };
-    /* How long this socket may hear nothing before the link is presumed dead: `peerLinkSilenceMs` of the
-     * heartbeat the door's own hub pings on. Required rather than defaulted, because the number belongs to the
-     * door and a peer that quietly inherited someone else's would be guessing about the one deadline that
-     * decides whether it ever notices a dead link. */
+/* How long this socket may hear nothing before the link is presumed dead: `peerLinkSilenceMs` of the heartbeat the door's own hub pings on. */
     readonly silenceMs: number;
     readonly log: (message: string) => void;
     // Sandbox refused the enrollment (1008); the loop has already stopped, this is where the peer says so.
@@ -100,9 +74,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
     let failures = 0;
     let quietSince = 0;
 
-    /* What ONE failed attempt is allowed to say. Three sentences rather than one repeated forever: the first few
-     * failures in full, then the line that marks the loop going quiet (so a reader who sees it knows the retries
-     * continue unlogged), then a complaint carrying the attempt count at most once per window. */
+/* What ONE failed attempt is allowed to say. */
     const complain = (said: string, delay: number): void => {
         const every = `retrying every ${Math.round(delay / 1000)}s`;
         if (failures <= LOUD_ATTEMPTS) {
@@ -148,9 +120,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
         };
         disarmWatchdog = disarm;
 
-        /* THIS ATTEMPT'S DROP, taken by whichever side notices first: the far end's close frame, or the
-         * watchdog. Latched, because a socket the watchdog abandoned may still emit its close minutes later,
-         * and two redials on one link is two loops racing to hold the same door. */
+        /* An attempt drop is recorded when either endpoint notices the closed far end. */
         let dropped = false;
         const drop = (said: string): void => {
             if (dropped) {
@@ -176,9 +146,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
         const arm = (): void => {
             disarm();
             watchdog = setTimeout(() => {
-                /* ABANDONED, not closed politely. A close frame sent to an end that is gone waits on a reply
-                 * that never comes — CLOSING is the state this watchdog exists to escape — so `close` is called
-                 * for the runtime's sake and the redial does not wait on an event that may never fire. */
+                /* ABANDONED, not closed politely. A close frame sent to an end that is gone waits on a reply. */
                 ws.close(1000, "no heartbeat");
                 drop(`nothing heard for ${Math.round(spec.silenceMs / 1000)}s`);
             }, spec.silenceMs);
@@ -216,9 +184,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
         });
 
         ws.addEventListener("close", (event) => {
-            /* A revocation is answered here rather than through `drop`: it is the one close that ends the loop
-             * instead of feeding the ladder, and it must still land on a socket the watchdog abandoned first —
-             * an owner who revoked a peer has said so, whether or not this side had already given up on it. */
+            /* A revocation is answered here rather than through `drop`: it is the one close that ends the loop. */
             if (event.code === UNAUTHORIZED) {
                 dropped = true;
                 disarm();
@@ -233,10 +199,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
             drop(`disconnected (${event.code ?? "no code"})`);
         });
 
-        /* Always followed by a close event that owns the retry; this only records a cause the close code can't
-         * carry, so it is silenced with the rest once the loop goes quiet — it is half of every repeated pair in
-         * a dead link's log, and it says nothing the drop line beside it does not. The attempt that finally
-         * reconnects is loud again, this line included. */
+        /* Socket errors record a cause; the close event owns retry scheduling. */
         ws.addEventListener("error", () => {
             if (failures < LOUD_ATTEMPTS) {
                 spec.log("connection error");

package/src/protocol/peer-mcp-server.test.ts

@@ -2,8 +2,7 @@ import { expect, test } from "vitest";
 import { z } from "zod";
 import { createMcpServer, type McpAuditEntry, textResult, tool } from "./peer-mcp-server.js";
 
-/* The dispatch every peer serves its tools through, against two hand-written tools: what the model is shown,
- * what an arriving call is checked against, and the rule that a failed tool is a result and not a fault. */
+/* The dispatch every peer serves its tools through, against two hand-written tools: what the model is shown, what an arriving call is checked against. */
 
 class Refused extends Error {}
 

package/src/protocol/runner-protocol.ts

@@ -30,10 +30,7 @@ export type RunnerHello = z.infer<typeof RunnerHelloSchema>;
 
 // The URL a runner dials, given its parent's public URL. One builder, so `ic`, the Fly provisioner and the
 // daemon route cannot disagree about where the door is (hostConnectUrl's rule).
-/* HOW OFTEN THE PARENT PINGS A CONNECTED RUNNER, read by both sides of the socket: the parent's hub pings on
- * it (runners/runner-peer.ts) and the runner presumes the link dead after a few of them pass in silence
- * (peer-dial.ts's peerLinkSilenceMs). One number, because the two sides disagreeing about it is a runner either
- * dropped while healthy or believed alive for as long as its socket happens to stay open. */
+/* HOW OFTEN THE PARENT PINGS A CONNECTED RUNNER, read by both sides of the socket. */
 export const RUNNER_HEARTBEAT_MS = 30_000;
 
 export const runnerConnectUrl = (parentUrl: string): string => `${parentUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/runners/connect`;

package/src/protocol/webext-protocol.ts

@@ -4,13 +4,7 @@ import { z } from "zod";
 // host-protocol.ts. A separate protocol from host's, since the extension has no shell or filesystem, only tabs and
 // origins the person granted one at a time.
 
-/* HOW OFTEN THIS DOOR PINGS A CONNECTED BROWSER, read by both sides of the socket: the daemon's hub pings on
- * it (webext/webext-peer.ts) and the extension presumes a link dead after a few of them pass in silence
- * (peer-dial.ts's peerLinkSilenceMs). Tighter than the machine door's and the number is not a taste: an MV3
- * service worker is killed after 30 seconds of inactivity and WebSocket traffic is what counts as activity, so
- * a heartbeat at or above Chrome's own limit would race the browser into shutting the extension down between
- * beats. One number, because the two sides disagreeing about it is either a browser dropped while healthy or
- * one believed alive for as long as its socket happens to stay open. */
+/* HOW OFTEN THIS DOOR PINGS A CONNECTED BROWSER, read by both sides of the socket. */
 export const WEBEXT_HEARTBEAT_MS = 20_000;
 
 export const WebExtHelloSchema = z.object({

package/src/schemas/agent.ts

@@ -158,6 +158,14 @@ export const AgentTurnSchema = z
             .describe(
                 "Work in this conversation's own private copy of the repos rather than the shared tree, so several agents can work at once. Needs a conversation id.",
             ),
+        // Decided like `isolated`: the first turn's choice, latched. A persona's own start folder wins over it.
+        startIn: z
+            .string()
+            .max(200)
+            .optional()
+            .describe(
+                "Which folder the conversation opens in, relative to the workspace root; the project it belongs to. Decided on the first turn. A persona that names its own start folder wins.",
+            ),
         // Decided like `isolated`: the request's choice on the first turn, the registry's after. `runner` implies
         // isolation; absent means local.
         placement: AgentPlacementSchema.optional().describe(
@@ -225,7 +233,7 @@ export const AgentTurnSchema = z
                 "Content from outside caused this turn, and what to call the source. It is what makes the sandbox treat the turn as carrying somebody else's words.",
             ),
         // How tool calls are gated for this turn (the SDK's permissionMode, verbatim):
-        // plan: propose → approve → execute
+        // plan: propose → approve → execute; the proposing half asks nothing, it only withholds writes
         // default: prompts per tool on the permission side channel
         // acceptEdits: auto-accepts file edits
         // bypassPermissions: runs everything
@@ -285,30 +293,7 @@ export const AgentTurnSchema = z
         message: 'forkOf.files "then" requires isolated',
     });
 export type AgentTurn = z.infer<typeof AgentTurnSchema>;
-/* A MODEL CHOSEN FOR ONE SURFACE-STARTED RUN, what the caret on the shared run button (<AgentRunButton>) sends
- * along with the click that starts it.
- *
- * Shared rather than re-declared per route because every surface that starts an agent for the user now carries
- * that caret, and they must all mean the same thing by it: the pair rides onto the turn as `agent`/`model`, and
- * the daemon's own fill step then leaves it alone (turn-resume.ts fills only what is absent). ABSENT is the
- * ordinary case and the one to keep cheap, nobody touched the caret, so the turn's `runRole` list answers.
- *
- * Both halves or neither, because a model id is only meaningful to the provider that vends it: half a pick
- * would send a Codex model id to Claude. Routes that accept this pass it through verbatim; a model this build
- * has never heard of is a supported pick, since the picker offers a custom-id escape hatch.
- *
- * AND EVERYTHING ELSE THE PANEL CAN SET, which is the half this schema used to drop on the floor. A pinned entry
- * carries its own account, harness, effort, thinking and speed (ModelPinSchema), the daemon applies a pin's
- * knobs ONLY to a turn that named no model (turn-resume.ts), and the picker the caret opens offers every one of
- * them — so a pick that carried the pair alone moved each override onto the provider's own defaults for the
- * rest. That is worst exactly where the caret gets reached for: the one moment somebody opens it is the failure
- * that just beat the standing order, and a run re-pointed at a frontier model but not at the tier, the loop or
- * the account that model was pinned under is not the run they configured.
- *
- * The fields are AgentTurn's own (it carries all five already), so a route that accepts this spreads it onto
- * the turn verbatim. Every one is optional and absent means absent: the turn goes out without the field and the
- * model's own default answers. `thinking: false` is therefore a different statement from no thinking at all,
- * which is the distinction Claude's own refusal of `max` beside disabled thinking turns on. */
+/* A MODEL CHOSEN FOR ONE SURFACE-STARTED RUN, what the caret on the shared run button (<AgentRunButton>) sends along with the click that starts it. */
 export const AgentRunPickSchema = z
     .object({
         agent: z.string().min(1).describe("Which provider."),
@@ -330,13 +315,7 @@ export const AgentRunPickSchema = z
     })
     .optional();
 export type AgentRunPick = z.infer<typeof AgentRunPickSchema>;
-/* THE PICK A RUN BUTTON HOLDS, AS THE WIRE SPELLS IT. The picker answers in the shell's own vocabulary
- * (`provider`, the kit's AgentRunChoice) and a turn calls the same field `agent`, so every surface that starts
- * an agent had this translation written out by hand — seven of them, each re-deciding which fields to carry,
- * which is exactly how the tier came to travel from four of them and the account from none.
- *
- * ABSENT STAYS ABSENT, field by field: `undefined` means the turn goes out without it and the model's own
- * default answers, which is not the same as any value this could invent. */
+/* THE PICK A RUN BUTTON HOLDS, AS THE WIRE SPELLS IT. */
 export const runPickOf = (choice: {
     readonly provider: string;
     readonly model: string;
@@ -354,34 +333,7 @@ export const runPickOf = (choice: {
     ...(choice.thinking === undefined ? {} : { thinking: choice.thinking }),
     ...(choice.fast === undefined ? {} : { fast: choice.fast }),
 });
-/* ONE ENTRY OF ONE ROLE'S MODEL LIST (settings.modelRoles): the standing version of the pick above, and not
- * merely which model but HOW it is to be run.
- *
- * THE KNOBS RIDE THE ENTRY RATHER THAN THE LIST, which is the whole reason this is an object rather than a
- * `${provider}:${model}` string. The reasoning effort was once a single field beside a list, so one tier
- * answered for every model in it — and the entries of such a list are deliberately NOT interchangeable: it is a
- * frontier pin with the cheap account underneath that catches it when the first is spent. A tier scale is a
- * property of the MODEL as well ('max' is off Kimi's scale entirely, and off Claude's own the moment thinking
- * is switched off), so a shared effort was either off-scale for half the list or the lowest common rung for all
- * of it. Each entry carries what the composer's picker configures for the turn in front of you.
- *
- * THE SAME SHAPE FOR EVERY ROLE, one-shot helpers included, and that is a deliberate widening. A commit
- * message or a session title used to be pinnable by model alone, on the argument that the daemon runs those
- * with reasoning off and no effort, so a control for either would be a switch with nothing behind it. True of
- * the machinery, and it made the machinery the argument: an owner who pins a reasoning model to their commit
- * subjects was paying that model's price to have its distinguishing feature suppressed. The knobs now travel
- * through the one-shot path too, so an entry means the same thing wherever it is written.
- *
- * EVERY FIELD BUT THE PAIR IS OPTIONAL, AND ABSENT MEANS ABSENT: the work goes out without the field and the
- * provider's own default answers, exactly as an unconfigured pin always did. Nothing here invents a "low".
- *
- * NO TIER HOLD, and its absence is the rule rather than an omission: automatic tier selection gates on
- * `unattended` (prompt-complexity.ts), so a role-started run is never downgraded in the first place and a veto
- * over it would be a control whose state can make no difference to anything.
- *
- * The pair is BOTH HALVES for the reason the pick above is: a model id is only meaningful to the provider that
- * vends it, so half a pin would send a Codex id to Claude. Taken verbatim, never validated against a catalog:
- * the picker offers a custom-id escape hatch, so a model this build has never heard of is a supported pin. */
+/* ONE ENTRY OF ONE ROLE'S MODEL LIST (settings.modelRoles): the standing version of the pick above, and not merely which model but HOW it is to be run. */
 export const ModelPinSchema = z.object({
     provider: AgentProviderSchema.describe("Which provider serves this work."),
     model: z.string().min(1).describe("Which of its models. Both halves, because a model name only means anything to the provider that serves it."),

package/src/schemas/agents.ts

@@ -174,6 +174,9 @@ export const AgentSummarySchema = z.object({
     harness: AgentHarnessSchema.describe("Which agentic loop it runs on."),
     // Latched with the conversation, so the card can say where work runs without asking anything else.
     runner: z.string().optional().describe("The runner this conversation runs on. Absent means this sandbox."),
+    // Both latched at the first turn, so a board scoped to one project can say which conversations are its own.
+    startIn: z.string().optional().describe("Which folder it opened in, relative to the workspace root. Absent means the root."),
+    actsAs: z.string().optional().describe("Which persona its first turn acted as. Absent for an ordinary chat."),
     // Per-conversation, so opening it restores its own choices rather than another tab's; `fast` here is what was asked
     // for, not what was served.
     model: z
@@ -250,6 +253,18 @@ export const AgentSummarySchema = z.object({
     outputTokens: z.number().optional().describe("Tokens received."),
     contextTokens: z.number().optional().describe("How much of the window the conversation currently fills."),
     contextWindow: z.number().optional().describe("How large that window is."),
+    // The pair travels whole or not at all: an instant with no lifetime, or a lifetime with no instant, names no
+    // deadline. Absent for every provider whose prompt-cache TTL the daemon cannot ground in a measurement or a
+    // documented rule (prompt-cache.ts), which is most of them.
+    promptCache: z
+        .object({
+            at: z.number().describe("When its last request touched the provider's prompt cache, in milliseconds."),
+            ttlMs: z.number().describe("How long that entry lives from `at`, in milliseconds."),
+        })
+        .optional()
+        .describe(
+            "When this conversation's prompt cache was last kept alive and how long it lasts, which together say when picking the conversation up stops being cheap. Absent when the provider publishes nothing to ground it on.",
+        ),
     activity: AgentActivitySchema.optional().describe("What it is doing at this moment."),
     // The whole drafting story (which models, how long, what refused), replacing a boolean that hid all of it;
     // runtime-only, forgotten on restart like the draft itself.

package/src/schemas/automations.ts

@@ -202,6 +202,16 @@ export const WebchatMessageSchema = z.object({
         .optional(),
 });
 export type WebchatMessage = z.infer<typeof WebchatMessageSchema>;
+// What GET /webchat/<id>/messages answers: replies queued after the visitor's stream closed, which is every reply an
+// approval-gated desk produces and every one a human writes as the agent. Public by construction, like the config:
+// reaching it needs nothing but an allowed origin and the conversation id already in that browser.
+export const WebchatPendingSchema = z.object({
+    // Oldest first, so appending them to the log preserves the order they were written in.
+    replies: z.array(z.object({ seq: z.number(), at: z.number(), text: z.string() })),
+    // Send back as `after` next time. Can jump past the last reply returned, when older ones were trimmed away.
+    cursor: z.number(),
+});
+export type WebchatPending = z.infer<typeof WebchatPendingSchema>;
 export const AutomationSchema = z.object({
     id: entryId.describe("The automation's id."),
     trigger: TriggerSchema.describe("What sets it off: a schedule, an event in the workspace, a message arriving from outside, or a webhook."),
@@ -286,6 +296,9 @@ export const AutomationApprovalSchema = z.object({
             "The thread this belongs to, when it has one, so approving continues that conversation rather than opening a new one. Without it, one visitor's chat becomes a card per approved message and an agent that meets them again every turn.",
         ),
     sessionId: z.string().optional().describe("The provider session that thread last ran on."),
+    // Snapshotted from the automation at hold time, so a project-scoped board can file the wake under what the persona
+    // reaches without reading the automation.
+    actsAs: entryId.optional().describe("Which persona the approved run would speak as."),
     createdAt: z.number().describe("When it started waiting, in milliseconds."),
     // When the daemon may run this itself, for a `holdForSeconds` hold; absent for a `requireApproval` hold, which only
     // the owner releases.

package/src/schemas/codebase-health.ts

@@ -1,6 +1,6 @@
 // codebase health: one repository's structure and risk, in numbers
 import { z } from "zod";
-import { WorkspaceSearchFreshnessSchema } from "./workspace-search.js";
+import { WorkspaceSearchFreshnessSchema } from "./workspace/workspace-search.js";
 // Repo-level companion to the management panel and git-history graph: the resident engine's `hotspots` (churn ×
 // complexity) and `map` (PageRank over imports) verbs, as figures a panel can plot. Every field is a recountable count;
 // no composite maintainability grade, since those aren't comparable across projects or checkable. HEALTH_LIMIT is how