@intentic/sandbox-contract 1.304.0 → 1.306.0

package/src/schemas/devices.ts

@@ -1,8 +1,8 @@
 // What one of the user's own machines is running.
 import { z } from "zod";
-import { hostCardOf, hostEnvironmentOf, type HostFacts, HostFactsSchema, WslEnvironmentSchema } from "./hosts.js";
+import { hostEntryOf, hostEnvironmentOf, type DeviceFacts, DeviceFactsSchema, WSL_SYSTEM_DISTROS, WslEnvironmentSchema } from "./hosts.js";
 import { DEV_VERSION } from "../state/versions.js";
-// Desktop-sync report shape shared by the agent, daemon and browser, produced only by `intentic-machine status --json`.
+// Desktop-sync report shape shared by the agent, daemon and browser, produced only by the agent's own `deviceReport`.
 // The agent never reports `sandboxes`; the docker half is filled in by whoever reads the report, scoped to the reader's
 // own pairing.
 
@@ -64,15 +64,20 @@ export const DeviceSandboxOpSchema = z.enum([
     "reshape",
     "remove",
     "logs",
-    // Only op that redeems a fresh setup code; others recreate a container from its own existing env.
+    // The two ops that redeem a fresh setup code; every other one recreates a container from its own existing env.
+    // They differ only in which row the claim names — an existing sandbox on this machine, or one that has never run
+    // anywhere — which is why each checks the opposite thing about the slug before spending the code.
     "reconnect",
+    "create",
     "runner-up",
     "runner-remove",
 ]);
 export type DeviceSandboxOp = z.infer<typeof DeviceSandboxOpSchema>;
 export const DeviceSandboxFlowSchema = z.object({
     op: DeviceSandboxOpSchema,
-    // Sandbox slug, or the runner's name for the runner ops (as `/system/runners`/`ic runner list` know it).
+    // Sandbox slug, the runner's name for the runner ops (as `/system/runners`/`ic runner list` know it), or for
+    // `create` the name the claim is about to produce — the one op where the slug is an expectation rather than a
+    // lookup, and the device refuses if anything already answers to it.
     slug: z.string().min(1),
     // Approved overlay's sha256, required only by `rebuild`; only content matching it is ever built.
     hash: z.string().optional(),
@@ -81,7 +86,7 @@ export const DeviceSandboxFlowSchema = z.object({
     // `runner-up` only, daemon-filled, never by the caller: the browser never holds the pairing credential.
     parentUrl: z.string().optional(),
     pair: z.string().optional().meta({ secret: true }),
-    // Required by `reconnect` only; single-sandbox and short-lived, so a leak only buys a recreate.
+    // Required by `reconnect` and `create`; single-sandbox and short-lived, so a leak only buys one recreate.
     setupCode: z.string().optional().meta({ secret: true }),
     // `runner-up` only, daemon-filled: `definition` carries no capabilities or secrets; `overlay`/`overlayHash` are
     // re-verified by hash before build.
@@ -101,9 +106,13 @@ export const DeviceFlowLineSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("error"), message: z.string() }),
 ]);
 export type DeviceFlowLine = z.infer<typeof DeviceFlowLineSchema>;
-// Both ops stop the resident process mid-command; a stream ending with no terminal frame is normal, not a failure, and
+// Every op stops the resident process mid-command; a stream ending with no terminal frame is normal, not a failure, and
 // confirmation is the version moving on the next poll. `restart` is just a bare `intentic-machine run`.
-export const DeviceAgentOpSchema = z.enum(["upgrade", "restart"]);
+// `forget-unreachable` drops the machine's links to sandboxes that have answered nothing for long enough to be gone
+// (peer-dial's LONG_OUTAGE_ATTEMPTS) — never the link carrying the request, which is by definition answering. Never
+// automatic either: a laptop closed for a fortnight must find its sandboxes again, so nothing expires on its own and
+// dropping one is always somebody's decision.
+export const DeviceAgentOpSchema = z.enum(["upgrade", "restart", "forget-unreachable"]);
 export type DeviceAgentOp = z.infer<typeof DeviceAgentOpSchema>;
 export const DeviceAgentFlowSchema = z.object({ op: DeviceAgentOpSchema });
 export type DeviceAgentFlow = z.infer<typeof DeviceAgentFlowSchema>;
@@ -114,7 +123,7 @@ export type DeviceAgentFlowInput = z.infer<typeof DeviceAgentFlowInputSchema>;
 // command: the same socket carries `run_command`, which would grant a shell on the user's machine.
 // `sync-unpair` runs the machine's own `sync uninstall --sandbox` (terminates both Mutagen sessions, drops the pairing,
 // self-revokes enrollment); revoking from the sandbox side is a different route.
-// `dev-reload`, `dev-rebuild` and `sync-install` are the three whose argv the daemon fills from what only it knows — the
+// `dev-restart`, `dev-rebuild` and `sync-install` are the three whose argv the daemon fills from what only it knows — the
 // dev checkout on that machine, a freshly minted pairing token — which is also why none takes a path or a token from the
 // caller. The two dev commands are also why a machine-side op is the wrong shape for them: this door carries a COMMAND
 // STRING to a tool every released agent already has, so a sandbox can drive a machine whose agent predates the feature.
@@ -135,7 +144,7 @@ export const DeviceCommandSchema = z.enum([
     "sync-resume",
     "sync-unpair",
     "sync-clean",
-    "dev-reload",
+    "dev-restart",
     "dev-rebuild",
     "dev-rebuild-log",
     "sync-install",
@@ -144,7 +153,7 @@ export type DeviceCommand = z.infer<typeof DeviceCommandSchema>;
 // The reversible sync switches: the subset a device's own row drives with a pair of buttons, as opposed to the two
 // commands a card elsewhere issues once. Its own type so those button tables stay total without carrying entries for
 // commands they can never send.
-export const DeviceSyncSwitchSchema = DeviceCommandSchema.exclude(["dev-reload", "dev-rebuild", "dev-rebuild-log", "sync-install", "sync-clean"]);
+export const DeviceSyncSwitchSchema = DeviceCommandSchema.exclude(["dev-restart", "dev-rebuild", "dev-rebuild-log", "sync-install", "sync-clean"]);
 export type DeviceSyncSwitch = z.infer<typeof DeviceSyncSwitchSchema>;
 
 // WHERE A DETACHED REBUILD REPORTS ITSELF. `dev-rebuild` returns the moment the build is under way and nothing streams
@@ -368,7 +377,7 @@ export const reportQuiet = (report: DeviceReport, receivedAt: number): boolean =
 // distro, `native` for an install on the metal. Connect-time facts are read first, since no scope can withhold them;
 // facts from an agent too old to carry `hostname` say nothing, and a report without `wsl` is native, as it always
 // was. Undefined is an absence of evidence, never read as agreement.
-export const environmentOf = (facts: Pick<HostFacts, "hostname" | "wsl"> | undefined, report: DeviceReport | undefined): string | undefined => {
+export const environmentOf = (facts: Pick<DeviceFacts, "hostname" | "wsl"> | undefined, report: DeviceReport | undefined): string | undefined => {
     const wsl = facts?.wsl ?? report?.wsl;
     if (wsl !== undefined) {
         return `wsl:${wsl.distro}`;
@@ -398,9 +407,7 @@ export const DeviceGapSchema = z.enum([
     // Connected, but "Run commands" is off on its capability card, so it won't describe itself: no folders, no
     // ports, no agent health. Says nothing about its containers, which ride their own switch (`Device.sandboxes`).
     "scope-off",
-    // Reachable and asked, but has no `intentic-machine` installed, so nothing knows its folders or ports.
-    "no-agent",
-    // Sync-enrolled but has not posted a report yet; unlike `no-agent`, the agent is there and syncing.
+    // The agent is there but gave no report: never posted since enrolling, or refused `report` other than by its switch.
     "unreported",
 ]);
 export type DeviceGap = z.infer<typeof DeviceGapSchema>;
@@ -431,7 +438,7 @@ export const DeviceSchema = z.object({
     // Carried beside the report so a device with no report still has an OS; `platform` is the normalised slug, `facts`
     // its connect-time self-description.
     platform: z.string().optional(),
-    facts: HostFactsSchema.optional(),
+    facts: DeviceFactsSchema.optional(),
     // Announced at connect; matches `report.agent.build` when known, the only version a report-less device has.
     agentVersion: z.string().optional(),
     lastSeen: z.number().optional(),
@@ -483,7 +490,7 @@ const hostnameKey = (device: Device): string | undefined => deviceHostname(devic
 
 // The card a device's door hangs off: one card is one computer, so two doors naming the same card are one machine
 // whatever either has said about itself — which is the whole of what an environment that has never connected says.
-const cardKey = (device: Device): string | undefined => (device.hostId === undefined ? undefined : hostCardOf(device.hostId));
+const cardKey = (device: Device): string | undefined => (device.hostId === undefined ? undefined : hostEntryOf(device.hostId));
 
 // What makes two devices one computer: a shared card, or a shared hostname where a distro answers to it, since WSL
 // hands a distro the Windows machine's name. Two native installs that merely share a name stay two machines.
@@ -568,10 +575,6 @@ export const hostRunningSandbox = (devices: readonly Device[], slug: string | un
 // the line naming it would work under.
 const windowsPath = (path: string): boolean => /^([A-Za-z]:[\\/]|\\\\)/.test(path);
 
-// Docker Desktop's own distros. `wsl -l -q` lists them like any other and neither ever holds a checkout, so counting
-// them would make every Docker Desktop PC look ambiguous.
-const SYSTEM_DISTROS: ReadonlySet<string> = new Set(["docker-desktop", "docker-desktop-data"]);
-
 // How a line written for a host path reaches the environment that holds it, through one door. `none` carries the
 // distros that were candidates, since "this PC has two and nothing says which" is a different answer for the reader
 // than "there is no way in".
@@ -589,11 +592,11 @@ export type PathReach =
 // an argument it would reject. Two real distros stay a refusal that names them — nothing here knows which one has the
 // folder, and the distro's own door, once connected, answers directly.
 // A platform that never said what it is stays a candidate, as every other reading of device evidence does.
-export const pathReach = (platform: string | undefined, facts: HostFacts | undefined, path: string): PathReach => {
+export const pathReach = (platform: string | undefined, facts: DeviceFacts | undefined, path: string): PathReach => {
     if (platform === undefined || (platform === "windows") === windowsPath(path)) {
         return { kind: "direct" };
     }
-    const distros = platform === "windows" ? (facts?.wslDistros ?? []).filter((distro) => !SYSTEM_DISTROS.has(distro)) : [];
+    const distros = platform === "windows" ? (facts?.wslDistros ?? []).filter((distro) => !WSL_SYSTEM_DISTROS.has(distro)) : [];
     const only = distros.length === 1 ? distros[0] : undefined;
     return only === undefined ? { kind: "none", distros } : { kind: "wsl", distro: only };
 };

package/src/schemas/extension-updates.ts

@@ -264,7 +264,7 @@ export const WorkspaceExtensionCreatedSchema = z.object({
 export const ExtensionRemovalConnectionSchema = z.object({
     id: z.string().describe("The name the owner gave it, which is also the agent's handle for it."),
     kind: z.string().describe("Which core kind it is underneath: cli, browser, host or webext."),
-    card: z.string().describe("The card it was added from, named as the grid names it."),
+    entry: z.string().describe("The catalog entry it was added from, named as the grid names it."),
     secrets: z
         .array(z.string())
         .describe("Credential fields stored for it, by name. The values are deleted with the entry and cannot be recovered from here."),

package/src/schemas/git/git.test.ts

@@ -0,0 +1,11 @@
+import { test, expect } from "bun:test";
+import { isScratch } from "./git.js";
+
+test("a scratch directory entry covers everything under it, and a file entry only itself", () => {
+    const scratch = [{ path: ".trun/" }, { path: "src/debug.log" }];
+
+    expect(isScratch(".trun/deep/x.log", scratch)).toBe(true);
+    expect(isScratch(".trunk/x", scratch)).toBe(false);
+    expect(isScratch("src/debug.log", scratch)).toBe(true);
+    expect(isScratch("src/debug.log.txt", scratch)).toBe(false);
+});

package/src/schemas/git/git.ts

@@ -233,6 +233,23 @@ export const GitOperationStateSchema = z.object({
     ),
 });
 export type GitOperationState = z.infer<typeof GitOperationStateSchema>;
+// Judged by shape alone: the names scratch arrives under are made up fresh every time, so no list of names could hold.
+export const ScratchReasonSchema = z
+    .enum(["hidden", "byproduct", "checkout", "oversized", "root"])
+    .describe(
+        "Why it looks like scratch. A new hidden directory that is not one a project keeps on purpose (like `.github`). A log, dump, backup or editor leftover. A git checkout of its own. A new file past the size source code reaches. Or a new dotfile at the top of a workspace whose projects are the repositories inside it.",
+    );
+export type ScratchReason = z.infer<typeof ScratchReasonSchema>;
+export const ScratchPathSchema = z.object({
+    path: z.string().describe("Relative to its repository. A directory ends in a slash and stands for everything inside it."),
+    reason: ScratchReasonSchema,
+    files: z.number().optional().describe("How many files it holds. Absent for a checkout of its own, whose contents are not walked."),
+    bytes: z.number().optional().describe("Their total size in bytes. Absent exactly when `files` is."),
+});
+export type ScratchPath = z.infer<typeof ScratchPathSchema>;
+// Whether a scratch entry covers `path`: a directory entry everything under it, a file entry only itself.
+export const isScratch = (path: string, scratch: readonly Pick<ScratchPath, "path">[]): boolean =>
+    scratch.some((entry) => (entry.path.endsWith("/") ? path.startsWith(entry.path) : path === entry.path));
 export const RepoChangesSchema = z.object({
     // The {repo} param the per-repo git routes accept: "root" or a repo id (its root-relative dir).
     repo: z.string(),
@@ -267,6 +284,14 @@ export const RepoChangesSchema = z.object({
         .describe(
             "How many changes were cut from each of the two lists above. A freshly cloned monorepo or a mass delete runs to six figures, which no screen can draw, so past a budget the lists arrive short and this says by how much on each side. Absent means they are complete.",
         ),
+    // A subset of `unstaged`'s untracked rows, restated by the entry that covers them rather than flagged per row, since
+    // one scratch directory can stand for thousands of files.
+    scratch: z
+        .array(ScratchPathSchema)
+        .optional()
+        .describe(
+            "Untracked paths that look like scratch. Staging or committing everything leaves them out, while staging one by its own path takes it like any other file. Absent when there are none.",
+        ),
     // 0 for `ahead`/`behind` with no remote or no upstream.
     remote: GitRemoteStateSchema.optional().describe("Where this repository stands against its remote."),
     // Keyed by path, not on each change, since one path can appear on two sides with the same origin. Ids only; look up
@@ -394,9 +419,50 @@ export const AgentChangesSchema = z.object({
         .describe(
             "Why the last merge refused, when one did. Carried here as well as in the merge's own answer, because a conflict is found the moment a turn ends and dealt with hours later on this surface, which would otherwise open with nothing to explain what it promised to resolve.",
         ),
+    // On the response, not on a repository's own row: a repository whose branch holds nothing gets no row at all, and
+    // that is exactly the case where the conversation did all of its work on the other branch.
+    elsewhere: z
+        .array(
+            z.object({
+                repo: z.string().describe("Which repository."),
+                branch: z
+                    .string()
+                    .optional()
+                    .describe("The branch its copy is standing on. Absent where it stands on no branch at all, which is a state git allows."),
+            }),
+        )
+        .optional()
+        .describe(
+            "Repositories whose copy the conversation left standing on a different branch of its own. What is listed for them is this conversation's branch as it was last left, not what its copy holds now, and anything it has written since went to the other branch.",
+        ),
+    // Read off the live copy, so a retired one has none: its scratch went with it.
+    scratch: z
+        .array(
+            z.object({
+                repo: z.string().describe("Which repository."),
+                paths: z.array(ScratchPathSchema).describe("What it keeps out there."),
+            }),
+        )
+        .optional()
+        .describe(
+            "Untracked files the conversation left in its copy that look like scratch: logs, probe scripts, dumps, a checkout of its own. They are not in the list above and no merge carries them. They stay in its copy until they are included or deleted, and go with the copy when it is archived or retired. Absent when there are none.",
+        ),
 });
 export type AgentChanges = z.infer<typeof AgentChangesSchema>;
 
+// Names scratch exactly as `AgentChanges.scratch` lists it; anything else is refused, so a stale list cannot reach a
+// file that was never scratch.
+export const AgentScratchSchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    repo: z.string().min(1).describe("Which repository of its composition."),
+    paths: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(MAX_ACTION_PATHS)
+        .describe("Paths exactly as the review lists them under scratch, a directory with its trailing slash."),
+});
+export type AgentScratch = z.infer<typeof AgentScratchSchema>;
+
 // Own read (a `git log` per repo), not folded into the review, whose rows are differences against main and these are
 // not. A commit CARRIES the work without authoring it: a path is attributed to the newest commit that left it there.
 export const AgentHistoryCommitSchema = z.object({

package/src/schemas/hosts.ts

@@ -11,7 +11,7 @@ export type WslEnvironment = z.infer<typeof WslEnvironmentSchema>;
 
 // What a machine reports once at connect (`host.describe`), cached until it reconnects: the skill pack says how to
 // drive Windows, this says which Windows it is.
-export const HostFactsSchema = z.object({
+export const DeviceFactsSchema = z.object({
     // The OS's own name for itself, e.g. "Windows 11 Pro 24H2".
     os: z.string(),
     arch: z.string(),
@@ -31,8 +31,15 @@ export const HostFactsSchema = z.object({
     wsl: WslEnvironmentSchema.optional(),
     // Windows only: the distros `wsl -l -q` lists, the names `run_command`'s `in: "wsl:<name>"` accepts.
     wslDistros: z.array(z.string()).optional(),
+    // What this machine's agent is holding links to, and how much of it is answering nothing. COUNTS AND AN AGE ONLY:
+    // the rest are other sandboxes' addresses, and a sandbox has no business learning its siblings'. Absent from an
+    // agent older than this field, which is why "none unreachable" is not the same value as "did not say".
+    links: z.object({ total: z.number(), unreachable: z.number(), unreachableSince: z.number().optional() }).optional(),
 });
-export type HostFacts = z.infer<typeof HostFactsSchema>;
+export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
+
+// Docker Desktop's own distros: `wsl -l -q` lists them like any other, and none ever runs an agent or holds a checkout.
+export const WSL_SYSTEM_DISTROS: ReadonlySet<string> = new Set(["docker-desktop", "docker-desktop-data"]);
 
 // One folder, two names. Windows sees a distro's files under a UNC share and a distro sees the Windows drives under
 // /mnt, so a path handed across the boundary is translated here rather than by hand at every call site.
@@ -54,13 +61,13 @@ const ENVIRONMENT_SEPARATOR = "::";
 // Which environment a machine is describing when it connects: the distro by the name WSL registered (what `wsl -l -q`
 // prints and `in: "wsl:<name>"` takes), or the metal. Facts arrive at connect and no scope withholds them, so this is
 // always answerable — unlike `environmentOf` (devices.ts), which weighs a report too and may hold no evidence at all.
-export const environmentKeyOf = (facts: Pick<HostFacts, "wsl">): string =>
+export const environmentKeyOf = (facts: Pick<DeviceFacts, "wsl">): string =>
     facts.wsl === undefined ? HOST_NATIVE_ENVIRONMENT : `wsl:${facts.wsl.distro}`;
 
-export const hostConnectionKey = (card: string, environment: string): string =>
-    environment === HOST_NATIVE_ENVIRONMENT ? card : `${card}${ENVIRONMENT_SEPARATOR}${environment}`;
+export const hostConnectionKey = (entry: string, environment: string): string =>
+    environment === HOST_NATIVE_ENVIRONMENT ? entry : `${entry}${ENVIRONMENT_SEPARATOR}${environment}`;
 
-export const hostCardOf = (connection: string): string => connection.split(ENVIRONMENT_SEPARATOR)[0] ?? connection;
+export const hostEntryOf = (connection: string): string => connection.split(ENVIRONMENT_SEPARATOR)[0] ?? connection;
 
 export const hostEnvironmentOf = (connection: string): string => {
     const at = connection.indexOf(ENVIRONMENT_SEPARATOR);
@@ -75,7 +82,7 @@ export const HostEnvironmentSchema = z.object({
     online: z.boolean(),
     version: z.string().optional(),
     lastSeen: z.number().optional(),
-    facts: HostFactsSchema.optional(),
+    facts: DeviceFactsSchema.optional(),
 });
 export type HostEnvironment = z.infer<typeof HostEnvironmentSchema>;
 
@@ -92,7 +99,7 @@ export const HostSummarySchema = z.object({
     version: z.string().optional(),
     // Epoch ms of the last held socket; absent means not since this daemon booted (liveness resets on restart).
     lastSeen: z.number().optional(),
-    facts: HostFactsSchema.optional(),
+    facts: DeviceFactsSchema.optional(),
 });
 export type HostSummary = z.infer<typeof HostSummarySchema>;
 export const HostsListSchema = z.object({ hosts: z.array(HostSummarySchema) });

package/src/schemas/issues.ts

@@ -193,7 +193,7 @@ export const IssueIntakeIdParamSchema = z.object({ automationId: entryId.describ
 
 // Constants both the editor and the route need, so a limit is visible to the owner before it is hit.
 
-// Default daily ceiling; higher than the Front Desk's 200 since a report is only sometimes a turn (dedup decides),
+// Default daily ceiling; higher than the Visitor chat's 200 since a report is only sometimes a turn (dedup decides),
 // unlike a visitor message.
 export const ISSUES_DAILY_MAX_DEFAULT = 2000;
 

package/src/schemas/metrics.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+
+// What the sandbox is using right now, measured only when asked (GET /system/metrics). CPU percentages are of ONE core
+// unless the field says otherwise; memory is resident bytes.
+
+// The kinds of process a sandbox runs, as the daemon classifies them by command line.
+export const PROCESS_ROLES = [
+    "languageServer",
+    "searchEngine",
+    "agentRuntime",
+    "browser",
+    "git",
+    "translator",
+    "extension",
+    "terminal",
+    // A build, test, typecheck or lint run and the package manager driving it: the fan-out shape, which is what every
+    // memory peak the resource log has recorded was made of.
+    "toolchain",
+    // An inference server this sandbox runs for itself.
+    "localModel",
+    // A process of a nested Docker container: charged to this cgroup, visible to nothing else here.
+    "container",
+    "other",
+] as const;
+export const ProcessRoleSchema = z.enum(PROCESS_ROLES);
+export type ProcessRole = z.infer<typeof ProcessRoleSchema>;
+
+export const ProcessGroupMetricsSchema = z.object({
+    processes: z.number().describe("How many processes."),
+    rssBytes: z
+        .number()
+        .describe(
+            "Their resident memory added up, in bytes. Memory two processes share is counted in each, so this can exceed what they cost together.",
+        ),
+});
+export type ProcessGroupMetrics = z.infer<typeof ProcessGroupMetricsSchema>;
+
+export const SessionMetricsSchema = ProcessGroupMetricsSchema.extend({
+    cpuPercent: z
+        .number()
+        .optional()
+        .describe(
+            "CPU its processes used over the window, as a percentage of one core, so a conversation busy on four cores reads 400. Counts commands that finished inside the window too. Absent on a first reading, which has nothing earlier to measure from.",
+        ),
+});
+export type SessionMetrics = z.infer<typeof SessionMetricsSchema>;
+
+// Linux pressure stall information: the share of the last ten seconds in which some task waited on the resource.
+export const PressureMetricsSchema = z.object({
+    cpu: z.number().describe("Percent of the last ten seconds in which something was waiting for a CPU."),
+    memory: z.number().describe("Percent of the last ten seconds in which something was waiting on memory: reclaim, swap-in, or a refault."),
+    io: z.number().describe("Percent of the last ten seconds in which something was waiting on disk."),
+});
+export type PressureMetrics = z.infer<typeof PressureMetricsSchema>;
+
+export const SandboxUsageSchema = z.object({
+    cpuPercent: z
+        .number()
+        .optional()
+        .describe("CPU the whole sandbox used over the window, as a percentage of all it may use (`cores`). Absent on a first reading."),
+    cores: z.number().describe("How many cores the sandbox may use: its CPU quota, or every core it is allowed to run on when it has none."),
+    memoryBytes: z
+        .number()
+        .describe("Memory in use, less the file cache the kernel takes back on demand: the figure that runs into the limit."),
+    memoryLimitBytes: z.number().describe("The memory limit: the container's own, or the machine's memory when the container has none."),
+    swapBytes: z.number().optional().describe("Memory pushed out to swap. Absent where the sandbox cannot see its own swap."),
+    diskBytes: z.number().optional().describe("Space used on the volume the workspace lives on. Absent when the volume would not say."),
+    diskTotalBytes: z.number().optional().describe("That volume's size. Absent when the volume would not say."),
+    loadAverage: z
+        .tuple([z.number(), z.number(), z.number()])
+        .describe("The load average over 1, 5 and 15 minutes. It is the machine's, so other sandboxes on it count too."),
+    processes: z.number().describe("How many processes are running in the sandbox."),
+    pressure: PressureMetricsSchema.optional().describe("How much work waited on CPU, memory or disk lately. Absent where the kernel does not report it."),
+});
+export type SandboxUsage = z.infer<typeof SandboxUsageSchema>;
+
+export const DaemonUsageSchema = z.object({
+    rssBytes: z.number().describe("The daemon's own resident memory."),
+    heapUsedBytes: z.number().describe("Of that, JavaScript objects in use."),
+    cpuPercent: z.number().optional().describe("CPU the daemon itself used over the window, as a percentage of one core. Absent on a first reading."),
+    eventLoopPercent: z
+        .number()
+        .optional()
+        .describe(
+            "How much of the window the daemon spent busy rather than waiting. Near 100, every request queues behind whatever it is doing. Absent on a first reading.",
+        ),
+});
+export type DaemonUsage = z.infer<typeof DaemonUsageSchema>;
+
+export const SandboxMetricsSchema = z.object({
+    at: z.number().describe("When this reading was taken, in milliseconds."),
+    windowMs: z
+        .number()
+        .optional()
+        .describe("How long the CPU figures were measured over, in milliseconds. Absent on a first reading, and then so is every CPU figure."),
+    sandbox: SandboxUsageSchema.describe("The sandbox as a whole."),
+    daemon: DaemonUsageSchema.describe("The daemon that runs it, which none of the other figures include."),
+    sessions: z
+        .record(z.string(), SessionMetricsSchema)
+        .describe(
+            "What each conversation's processes use, by conversation id: the agent's own process and everything it started. Only conversations with processes running, and only those the caller may see.",
+        ),
+    roles: z
+        .partialRecord(ProcessRoleSchema, ProcessGroupMetricsSchema)
+        .describe("Every process in the sandbox but the daemon, by what kind of work it is. A kind with nothing running is absent."),
+});
+export type SandboxMetrics = z.infer<typeof SandboxMetricsSchema>;

package/src/schemas/panels.ts

@@ -70,14 +70,14 @@ export const PanelSummarySchema = z.object({
     // desiredState: desired-state.json (present after the first resolve).
     // directoryUi: .intentic/ui/index.html.
     // monorepo: pnpm-workspace.yaml + turbo.json.
-    // vitest: a root vitest.config.ts, or "vitest" in the manifest/workspace catalog.
+    // tests: a root `test` script or runner config (vitest.config.ts, bunfig.toml), or "vitest" in the workspace catalog.
     // userStories: docs/user-stories.
     // docs: docs/architecture.
     deployConfig: z.boolean().describe("It declares infrastructure."),
     desiredState: z.boolean().describe("That declaration has been resolved at least once."),
     directoryUi: z.boolean().describe("It carries a small interface of its own."),
     monorepo: z.boolean().describe("It holds several packages."),
-    vitest: z.boolean().describe("It has tests that can be run."),
+    tests: z.boolean().describe("It has tests that can be run."),
     userStories: z
         .boolean()
         .describe("It carries stories an agent could test the running app against. The one fact here that says nothing about the language."),

package/src/schemas/personas.ts

@@ -65,7 +65,7 @@ export const PersonaContextSchema = z.object({
         .array(z.string().min(1).max(200))
         .max(50)
         .describe(
-            "Which nested repositories a conversation wearing this card carries, by workspace-relative path. The workspace itself is always carried; empty means the workspace alone.",
+            "Which nested repositories a conversation on this persona carries, by workspace-relative path. The workspace itself is always carried; empty means the workspace alone.",
         ),
 });
 export type PersonaContext = z.infer<typeof PersonaContextSchema>;
@@ -177,7 +177,7 @@ export const PersonaBriefingSchema = z.object({
         .array(TurnBriefingNoteIdSchema)
         .max(20)
         .describe(
-            "Which of the notes the sandbox prepends to each message a conversation wearing this card does NOT get. Everything not named here is sent as usual; the notes that keep a turn inside its own branch or explain a missing account cannot be named at all.",
+            "Which of the notes the sandbox prepends to each message a conversation on this persona does NOT get. Everything not named here is sent as usual; the notes that keep a turn inside its own branch or explain a missing account cannot be named at all.",
         ),
 });
 export type PersonaBriefing = z.infer<typeof PersonaBriefingSchema>;
@@ -229,33 +229,10 @@ export type Persona = z.infer<typeof PersonaSchema>;
 // has no opinion — the caller decides, not "run nothing".
 export const personaModels = (card: Pick<Persona, "models">, sources: readonly ModelSource[]): readonly ModelPin[] =>
     readyChain(sources, card.models ?? []);
-// Asked once per chat, on the message it was sent with; answers with the one card the message belongs to, or none.
-// `folder`/`paths` are the facts a card's `context`/`startIn` can be matched against that words alone can't supply.
-export const PersonaRouteAskSchema = z.object({
-    prompt: z.string().min(1).max(20000).describe("The message a new chat is about to open with."),
-    folder: z.string().max(200).optional().describe("The workspace folder the chat was opened in, when it was opened in one."),
-    paths: z
-        .array(z.string().min(1).max(500))
-        .max(50)
-        .default([])
-        .describe("Workspace paths the message names: uploads, @-mentions, the editor's own file."),
-});
-export type PersonaRouteAsk = z.infer<typeof PersonaRouteAskSchema>;
-export const PersonaRouteSchema = z.object({
-    persona: entryId.optional().describe("The card this message belongs to, or absent when none does and the chat should stay open to everything."),
-    reason: z.string().describe("Why, in the one line a chat can show. Present whether or not a card was named."),
-    // Absent means nothing was spent: matched on the folder, or answered before any model was reached.
-    model: z
-        .string()
-        .optional()
-        .describe(
-            "Which model answered, as `provider:model`, so the chat can name what the reading cost. Absent when no model was asked at all, which a folder match and an empty persona list both are.",
-        ),
-});
-export type PersonaRoute = z.infer<typeof PersonaRouteSchema>;
+// Which persona a new chat belongs to is asked with what it runs on, in one reading: chat-route.ts.
 // The one stock persona id; lives here because the daemon and the automations form are separate packages that must
-// agree on it exactly, or a Front Desk pins to a card nobody creates.
-export const FRONT_DESK_PERSONA = "front-desk";
+// agree on it exactly, or a Visitor chat pins to a card nobody creates.
+export const VISITOR_CHAT_PERSONA = "visitor-chat";
 // One phrase describing how bounded a card is, shared so the Personas page and the automation picker can't grow
 // different vocabularies for the same card. "Read-only"/"no shell" are named; everything else collapses to a count.
 export const personaBounds = (persona: Persona): string => {

package/src/schemas/providers/plan-limits.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../../models/provider-specs.js";
 import { AgentHarnessSchema, AgentProviderSchema, EditorContextSchema } from "../agent.js";
+import { MENTION_LIMIT } from "../../text/mentions.js";
 // Headroom is one shape shared by every provider, not a Claude idea others imitate: a native account and a routed
 // subscription differ in who holds the credential, never in what a reading is. Every surface that draws a percentage
 // reads this one type.
@@ -218,6 +219,14 @@ export const SteerSchema = z
             .max(20)
             .optional()
             .describe("Files to send with it, as workspace paths. A screenshot dropped in mid-turn with no words is a legitimate thing to send."),
+        // Same split as a turn's: a guessed path is dropped, only a chosen attachment can refuse the steer.
+        mentions: z
+            .array(z.string().min(1))
+            .max(MENTION_LIMIT)
+            .optional()
+            .describe(
+                "Workspace paths the message mentions with `@`. Unlike attachments, one that escapes the workspace or names no file is ignored rather than refused.",
+            ),
         editorContext: EditorContextSchema.optional().describe("What you have open, folded in so that pointing words resolve."),
     })
     // An attachment-only steer (a screenshot dropped in mid-turn) is legal; an entirely empty one is not.

package/src/schemas/secrets.ts

@@ -62,7 +62,7 @@ export const CredentialGatesSchema = z.object({
 });
 export type CredentialGates = z.infer<typeof CredentialGatesSchema>;
 
-export const CredentialGateSubjectParamSchema = z.object({
+export const CredentialGuardSubjectParamSchema = z.object({
     subject: z.string().min(1).describe("Which gate, by the secret name or capability id it covers."),
 });
 

package/src/schemas/settings.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, test, expect } from "bun:test";
 import { RuleSchema } from "./settings.js";
 
 // A rule that saves cleanly and silently does nothing is the failure this schema exists to refuse: an action, and a