@intentic/sandbox-contract 1.331.0 → 1.332.0

package/src/schemas/automations.ts

@@ -180,11 +180,15 @@ export type AutomationTarget = z.infer<typeof AutomationTargetSchema>;
 export const FireOnSchema = z.enum(["pass", "change"]);
 export type FireOn = z.infer<typeof FireOnSchema>;
 // What the daemon remembers of a watch between checks (.intentic/records/automation-watch.json), and what the list
-// shows under it. Values are kept whole up to a bound, so the next check can say what changed.
+// shows under it. Values are kept whole up to a bound, so the next check can say what changed; whether anything changed
+// is decided on the digest of the whole value, so a page longer than the bound is not "changed" on every check.
 export const WatchStateSchema = z.object({
     armedAt: z.number().describe("When it was first checked, in milliseconds."),
     checkedAt: z.number().describe("When it was last checked, in milliseconds."),
-    value: z.string().optional().describe("What the last passing check saw. Absent until one has passed."),
+    value: z.string().optional().describe("What the last passing check saw, cut to a bound. Absent until one has passed."),
+    digest: z.string().optional().describe("sha256 of the whole of what the last passing check saw, before any cut."),
+    // A watch edited to check something else starts over: what the old check saw says nothing about the new one.
+    condition: z.string().optional().describe("Which check this state belongs to: a digest of the guard or source it was recorded for."),
     changedAt: z.number().optional().describe("When what it saw last changed, in milliseconds."),
     firedAt: z.number().optional().describe("When it last set something off, in milliseconds."),
     // Why the last check did not pass, when it did not.

package/src/schemas/daemon-health.test.ts

@@ -0,0 +1,28 @@
+import { type DaemonHealth, DaemonHealthReadingSchema, DaemonHealthSchema } from "./system.js";
+
+const answer: DaemonHealth = {
+    ok: true,
+    sandboxId: "0123456789ab",
+    profile: "workspace",
+    boot: { ready: true, startedAt: 1, steps: [] },
+    state: { journal: "none", engine: 84 },
+    announce: { state: "registered", at: 2 },
+    reach: { state: "reachable", at: 3 },
+    reachedBy: "tunnel",
+    build: { version: "1.2.3" },
+};
+
+test("the daemon's answer parses whole as the contract's health", () => {
+    expect(DaemonHealthSchema.parse(answer)).toEqual(answer);
+});
+
+test("a reader takes any daemon's answer, a field of the wrong shape reading as missing", () => {
+    expect(DaemonHealthReadingSchema.parse({ ok: true, ready: false, boot: "starting", state: { journal: 7 }, reachedBy: "tunnel" })).toEqual({
+        ok: true,
+        ready: false,
+        boot: undefined,
+        state: { journal: undefined },
+        reachedBy: "tunnel",
+    });
+    expect(DaemonHealthReadingSchema.parse(answer)).toMatchObject({ sandboxId: "0123456789ab", boot: { ready: true }, announce: { state: "registered" } });
+});

package/src/schemas/devices.ts

@@ -101,6 +101,9 @@ export const DeviceSandboxSchema = z.object({
     // so this side adopted it for its rounds: `keptElsewhere` is left out, and these say whose it was and since when.
     adoptedFrom: z.string().optional(),
     keeperSilentSince: z.number().optional(),
+    // (2026-10-10) Stopped by the machine's keeper after a stretch nobody needed it (`ic sandbox sleep`), and started
+    // again by itself when somebody opens it. `running` is false while this is true.
+    asleep: z.boolean().optional(),
 });
 export type DeviceSandbox = z.infer<typeof DeviceSandboxSchema>;
 // One operation on one sandbox, streamed as lines ending in a `result` or `error` frame. `prepare` builds the pending
@@ -318,12 +321,18 @@ export const DeviceSandboxIdSchema = z
     .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
 // A folder on the DEVICE for `sync-install` to keep in step. The only caller-supplied string that reaches a command
 // line, so its shape is the guard: `~`, an absolute POSIX path or a drive letter, and none of the characters that would
-// end the argument it sits in. `~` is expanded by the daemon, which is why `$` is not allowed to arrive here.
+// end the argument it sits in. `~` is expanded by the daemon, which is why `$` is not allowed to arrive here. The line
+// may be PowerShell, which reads the typographic quotes “ ” „ as double quotes and ‘ ’ ‚ ‛ as single quotes beside the
+// ASCII ones, so those are refused too: the daemon quotes the folder, and this keeps a second guard where one quoter
+// misses a character.
 export const DeviceLocalDirSchema = z
     .string()
     .min(1)
     .max(4096)
-    .regex(/^(?:~|\/|[A-Za-z]:[\\/])[^"'`$;|&\n\r]*$/);
+    // The curly quotes as escapes: bun's transpiler rewrites a literal one in a regex to its escape and tsgo keeps it,
+    // so spelled literally the pattern reads differently from source and from dist, and contract.lock.json can match
+    // only one of them.
+    .regex(/^(?:~|\/|[A-Za-z]:[\\/])[^"'`$;|&\n\r\u201C\u201D\u201E\u2018\u2019\u201A\u201B]*$/);
 // A TCP port number, the one value a caller supplies that reaches a command line as a number rather than a string.
 export const PortNumberSchema = z.number().int().min(1).max(65535);
 export const DeviceCommandInputSchema = z.object({

package/src/schemas/engines.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 // An engine is the installed program a runtime (agent-catalog.ts) spawns or imports — the `claude` binary, `codex`
 // wrapper, `@cursor/sdk`, `opencode`, `cli-proxy-api` — not the loop itself; one engine can back several runtimes.
 
-export const ENGINE_IDS = ["claude", "codex", "cursor", "opencode", "translator"] as const;
+export const ENGINE_IDS = ["claude", "codex", "cursor", "devin", "opencode", "translator"] as const;
 export type EngineId = (typeof ENGINE_IDS)[number];
 export const EngineIdSchema = z.enum(ENGINE_IDS);
 

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

@@ -0,0 +1,91 @@
+import { type GitChange, UNATTRIBUTED_ORIGIN } from "./git.js";
+import { changeIsFrom, DISCARDABLE_SIDES, discardOutcome, isWholeRepo, scopedPaths, STAGEABLE_SIDES, UNSTAGEABLE_SIDES } from "./git-scope.js";
+
+const change = (path: string, extra: Partial<GitChange> = {}): GitChange => ({ path, status: "modified", ...extra });
+
+// Shape a scan produces: small enough to read, with something on every side.
+const sides = {
+    conflicted: [change("merge.ts", { status: "conflicted" })],
+    staged: [change("staged.ts"), change("moved.ts", { status: "renamed", from: "old.ts" })],
+    unstaged: [change("edited.ts"), change("new.ts", { status: "added" })],
+};
+
+test("a scope with no side reads every side the verb can move, and no others", () => {
+    // Staged is deliberately absent from stageable: re-adding it would sweep in worktree edits made after the freeze.
+    expect(scopedPaths(sides, STAGEABLE_SIDES, {})).toEqual(["edited.ts", "new.ts", "merge.ts"]);
+    expect(scopedPaths(sides, UNSTAGEABLE_SIDES, {})).toEqual(["staged.ts", "moved.ts", "old.ts"]);
+    expect(scopedPaths(sides, DISCARDABLE_SIDES, {})).toEqual(["merge.ts", "staged.ts", "moved.ts", "old.ts", "edited.ts", "new.ts"]);
+});
+
+test("a scope narrows the verb's sides and can never widen them", () => {
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { side: "unstaged" })).toEqual(["edited.ts", "new.ts"]);
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { side: "conflicted" })).toEqual(["merge.ts"]);
+    // Staging the one side it can't move answers empty, not everything: the honest answer to an impossible request.
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { side: "staged" })).toEqual([]);
+});
+
+test("both legs of a rename resolve together, so no verb acts on half a move", () => {
+    expect(scopedPaths(sides, UNSTAGEABLE_SIDES, { side: "staged" })).toContain("old.ts");
+});
+
+test("an origin scope keeps only what that conversation landed, either leg of a rename counting", () => {
+    const origins = { "edited.ts": ["agent-a"], "new.ts": ["agent-b"], "old.ts": ["agent-a"] };
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { origin: "agent-a" }, origins)).toEqual(["edited.ts"]);
+    // `moved.ts` attributes through the path it came from, the leg the land recorded.
+    expect(scopedPaths(sides, UNSTAGEABLE_SIDES, { origin: "agent-a" }, origins)).toEqual(["moved.ts", "old.ts"]);
+    // A side and an origin compose as an intersection, not either alone.
+    expect(scopedPaths(sides, DISCARDABLE_SIDES, { side: "unstaged", origin: "agent-b" }, origins)).toEqual(["new.ts"]);
+    // No matching attribution resolves to nothing, not a fallback to everyone's work.
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { origin: "agent-a" })).toEqual([]);
+});
+
+// The Changes panel's "You" chip sends this; it used to resolve to nothing, so its Stage all, Discard and commit
+// each moved no file at all.
+test("the unattributed origin keeps exactly what no conversation landed, a rename counting only when neither leg was", () => {
+    const origins = { "edited.ts": ["agent-a"], "old.ts": ["agent-a"] };
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { origin: UNATTRIBUTED_ORIGIN }, origins)).toEqual(["new.ts", "merge.ts"]);
+    // `moved.ts` came from a landed path, so it is the agent's work, not the owner's.
+    expect(scopedPaths(sides, UNSTAGEABLE_SIDES, { origin: UNATTRIBUTED_ORIGIN }, origins)).toEqual(["staged.ts"]);
+    // With nothing attributed, every row is the owner's.
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { side: "unstaged", origin: UNATTRIBUTED_ORIGIN })).toEqual(["edited.ts", "new.ts"]);
+});
+
+test("a path listed on two sides at once resolves to one entry", () => {
+    const both = { conflicted: [], staged: [change("a.ts")], unstaged: [change("a.ts")] };
+    expect(scopedPaths(both, DISCARDABLE_SIDES, {})).toEqual(["a.ts"]);
+});
+
+test("a scope that narrows nothing is the whole repository", () => {
+    expect(isWholeRepo({})).toBe(true);
+    expect(isWholeRepo({ side: "unstaged" })).toBe(false);
+    expect(isWholeRepo({ origin: "agent-a" })).toBe(false);
+});
+
+// The panel's count, its discard question and the daemon's scope all read this one predicate, so a rename out of an
+// agent's file cannot be "yours" in the question and the agent's in the action.
+test("a row is an origin's when either leg was landed by it, and the owner's only when neither was", () => {
+    const origins = { "util.ts": ["agent-a"] };
+    const renamed = change("helpers.ts", { status: "renamed", from: "util.ts" });
+    expect(changeIsFrom(renamed, "agent-a", origins)).toBe(true);
+    expect(changeIsFrom(renamed, UNATTRIBUTED_ORIGIN, origins)).toBe(false);
+    expect(changeIsFrom(change("mine.ts"), UNATTRIBUTED_ORIGIN, origins)).toBe(true);
+    expect(changeIsFrom(change("mine.ts"), "agent-a", origins)).toBe(false);
+});
+
+test("a discard names what leaves the disk apart from what returns to its last commit", () => {
+    const changed = {
+        conflicted: [],
+        staged: [
+            change("helpers.ts", { status: "renamed", from: "util.ts" }),
+            change("fresh.ts", { status: "added" }),
+            change("gone.ts", { status: "deleted" }),
+        ],
+        // `gone.ts` deleted in the index and recreated on disk reads untracked, yet the last commit still holds it.
+        unstaged: [change("edited.ts"), change("scratch.ts", { status: "added" }), change("gone.ts", { status: "added" })],
+    };
+    const paths = scopedPaths(changed, DISCARDABLE_SIDES, {});
+    expect(discardOutcome(changed, paths)).toEqual({
+        deletes: ["helpers.ts", "fresh.ts", "scratch.ts"],
+        restores: ["util.ts", "gone.ts", "edited.ts"],
+    });
+});

package/src/schemas/git/git-scope.ts

@@ -0,0 +1,71 @@
+import { type GitChange, type GitDiffSide, type GitScope, UNATTRIBUTED_ORIGIN } from "./git.js";
+
+// What a scope names, resolved against a repository's own status. One definition, read by the daemon when it acts on a
+// scope and by the Changes panel when it asks the owner about one, so the question and the action cannot disagree.
+// Sides are the verb's, not the scope's: staging reads the two not yet in the index; a scope narrows, never widens.
+
+export interface ChangedSides {
+    readonly conflicted: readonly GitChange[];
+    readonly staged: readonly GitChange[];
+    readonly unstaged: readonly GitChange[];
+}
+
+// Who landed each path, newest first, as `RepoChanges.origins` ships it; a rename's old path is keyed too.
+export type ChangeOrigins = Readonly<Record<string, readonly string[]>>;
+
+// What each verb can move; `git add` on an unmerged path settles a merge, so conflicts are stageable too.
+export const STAGEABLE_SIDES: readonly GitDiffSide[] = ["unstaged", "conflicted"];
+export const UNSTAGEABLE_SIDES: readonly GitDiffSide[] = ["staged"];
+// Discard rewrites the worktree, which every side has one of.
+export const DISCARDABLE_SIDES: readonly GitDiffSide[] = ["conflicted", "staged", "unstaged"];
+
+// The paths one row stands for on disk: a rename is two, and no verb acts on half a move.
+export const legsOf = (change: Pick<GitChange, "path" | "from">): readonly string[] =>
+    change.from === undefined ? [change.path] : [change.path, change.from];
+
+// Every conversation that landed either leg of a row, newest first per leg, each once.
+export const originsOfChange = (change: Pick<GitChange, "path" | "from">, origins: ChangeOrigins): readonly string[] => [
+    ...new Set(legsOf(change).flatMap((path) => origins[path] ?? [])),
+];
+
+// Whether a row is that origin's work: a conversation that landed either leg of it, or for the unattributed origin a row
+// no conversation landed any leg of. A rename out of an agent's file is the agent's row, whoever renamed it, so the
+// panel counts it, the scope moves it and the discard question names it under the same chip.
+export const changeIsFrom = (change: Pick<GitChange, "path" | "from">, origin: string, origins: ChangeOrigins): boolean => {
+    const ids = originsOfChange(change, origins);
+    return origin === UNATTRIBUTED_ORIGIN ? ids.length === 0 : ids.includes(origin);
+};
+
+// Paths a scope resolves to, for a verb that moves `sides`; both legs of a rename included.
+// Deduplicated: a path staged and edited again is two rows over one file, and a rename's legs can be named twice.
+export const scopedPaths = (changed: ChangedSides, sides: readonly GitDiffSide[], scope: GitScope, origins: ChangeOrigins = {}): readonly string[] => {
+    const origin = scope.origin;
+    const reading = scope.side === undefined ? sides : sides.filter((side) => side === scope.side);
+    const rows = reading.flatMap((side) => changed[side]);
+    const named = origin === undefined ? rows : rows.filter((change) => changeIsFrom(change, origin, origins));
+    return [...new Set(named.flatMap(legsOf))];
+};
+
+// A scope that narrows nothing is the whole repository; two of the three verbs say so to git directly, unenumerated.
+export const isWholeRepo = (scope: GitScope): boolean => scope.side === undefined && scope.origin === undefined;
+
+// What discarding `paths` does to each, read off the same status: a path the last commit does not hold leaves the disk
+// (an untracked file, a staged new file, a rename's new leg), every other returns to its committed state. Mirrors the
+// daemon's discard, which unstages first and then cleans what reads untracked.
+export const discardOutcome = (changed: ChangedSides, paths: readonly string[]): { readonly deletes: readonly string[]; readonly restores: readonly string[] } => {
+    const notInHead = new Set<string>();
+    for (const change of changed.staged) {
+        if (change.status === "added" || (change.status === "renamed" && change.from !== undefined)) {
+            notInHead.add(change.path);
+        }
+    }
+    // Untracked, unless the index deleted it from the last commit: that path is in HEAD and comes back.
+    const indexDeleted = new Set(changed.staged.filter((change) => change.status === "deleted").map((change) => change.path));
+    for (const change of changed.unstaged) {
+        if (change.status === "added" && !indexDeleted.has(change.path)) {
+            notInHead.add(change.path);
+        }
+    }
+    const unique = [...new Set(paths)];
+    return { deletes: unique.filter((path) => notInHead.has(path)), restores: unique.filter((path) => !notInHead.has(path)) };
+};

package/src/schemas/git/git.ts

@@ -78,9 +78,23 @@ export const DiscardSchema = RepoParamSchema.extend(GitTargetSchema.shape)
     .refine(oneTarget, ONE_TARGET);
 // Index-only moves; nothing on disk changes, so neither needs a checkpoint. An empty target means the whole repository
 // (`git add -A`, or the entire index).
+// `chip` is the reversible form of an origin's move (the Changes panel's origin chips): staging records what the index
+// held at every path it moves, and unstaging the same chip writes exactly that back, so a partial `git add -p` or a
+// merge's clean result survives one on/off. It names its own target, so it goes alone.
+const oneIndexMove = (move: GitTarget & { readonly chip?: string | undefined }): boolean =>
+    oneTarget(move) && (move.chip === undefined || (move.paths === undefined && move.scope === undefined));
 export const GitIndexMoveSchema = RepoParamSchema.extend(GitTargetSchema.shape)
+    .extend({
+        chip: z
+            .string()
+            .min(1)
+            .optional()
+            .describe(
+                `Stage one origin's unstaged files (a conversation id, or "${UNATTRIBUTED_ORIGIN}" for the files none landed) so the move can be taken back exactly: unstaging with the same value later restores what the index held at each of those paths before, partial staging included, and leaves alone any path staged differently since or a commit that already took them. Goes without paths or a scope.`,
+            ),
+    })
     .describe("What to move across the index. Nothing on disk changes either way.")
-    .refine(oneTarget, ONE_TARGET);
+    .refine(oneIndexMove, { message: "name paths, a scope or a chip, not more than one" });
 // No separate "set upstream" flag: the daemon runs `push -u` exactly when the branch has none yet, which is never
 // destructive.
 export const PushSchema = RepoParamSchema.extend({

package/src/schemas/hosts.ts

@@ -76,6 +76,13 @@ export const DeviceFactsSchema = z.object({
     // The agent's last upkeep pass in this environment (DeviceUpkeepSchema): whether a release brought this machine to
     // the current shape, read rather than assumed. Absent before the first pass, and from an agent older than the field.
     upkeep: DeviceUpkeepSchema.optional(),
+    // How the agent before this one ended, as one sentence (watchdog kill, crash, update, reboot), so a device that
+    // dropped off says why once it is back. Absent on a first start, and from an agent older than the field.
+    previousExit: z.string().optional(),
+    // Which ic answers on this machine and what steers it: an old ic.exe installed from a leftover IC_URL looked like
+    // a daemon bug for an afternoon. Override values are the agent's own redaction (secret-looking ones by length).
+    ic: z.object({ path: z.string(), version: z.string(), modified: z.string().optional() }).optional(),
+    icOverrides: z.array(z.string()).optional(),
 });
 export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 

package/src/schemas/keep-warm.ts

@@ -88,7 +88,8 @@ export const PromptCacheOpeningSchema = z.object({
 });
 export type PromptCacheOpening = z.infer<typeof PromptCacheOpeningSchema>;
 
-const tokensLabel = (tokens: number): string => (tokens >= 1_000 ? `${Math.round(tokens / 1_000)}k` : String(tokens));
+/** A token count as the transcript words it: "305k", or the bare count under a thousand. */
+export const tokensLabel = (tokens: number): string => (tokens >= 1_000 ? `${Math.round(tokens / 1_000)}k` : String(tokens));
 
 const spanLabel = (ms: number): string => {
     const minutes = Math.max(1, Math.round(ms / 60_000));

package/src/schemas/logs.ts

@@ -52,10 +52,35 @@ export const ClientDiagnosticSchema = z.object({
         .describe("Whatever else was worth keeping."),
 });
 export type ClientDiagnostic = z.infer<typeof ClientDiagnosticSchema>;
+// Which page a batch came from, said once per batch rather than on every event. Without it two tabs' reports read as
+// one stream, and an agent spent dozens of calls learning a page was the owner's own dev server rather than the build
+// it had just changed.
+export const ClientPageSchema = z.object({
+    pageId: z.string().min(1).max(64).describe("This page load's own id: every report from one load shares it, and a reload gets a new one."),
+    tabId: z.string().max(64).optional().describe("The browser tab's id, which a reload of the same tab keeps."),
+    userAgent: z.string().max(300).optional().describe("The browser's own description of itself."),
+    viewport: z.string().max(40).optional().describe("The window's size in CSS pixels and its pixel ratio, e.g. 390x844@3."),
+    // The join key into PostHog's session replay: absent where analytics is off (dev, self-hosted) or not loaded yet.
+    replay: z.string().max(100).optional().describe("The PostHog session id, whose replay shows what the person did."),
+    origin: z.string().max(200).optional().describe("The address the page was loaded from."),
+    served: z
+        .string()
+        .max(300)
+        .optional()
+        .describe("How the page was served: `dev` (a Vite dev server, with the checkout, branch and who started it), `desktop` (the installed app, with its version), `local` (a window on a folder) or `hosted`."),
+    commit: z
+        .string()
+        .max(40)
+        .optional()
+        .describe("The short commit the page's build was made from (a dev server's: the one it started on). Absent where the build could not read it."),
+});
+export type ClientPage = z.infer<typeof ClientPageSchema>;
 // Capped batch: the client already coalesces and drops its own side, and an unbounded array here is a way to fill a
 // disk with one request.
 export const ClientDiagnosticsReportSchema = z.object({
     events: z.array(ClientDiagnosticSchema).min(1).max(50).describe("What the browser has to report, oldest first."),
+    // Optional: a page from before it sends none.
+    page: ClientPageSchema.optional().describe("Which page load sent the batch."),
 });
 export type ClientDiagnosticsReport = z.infer<typeof ClientDiagnosticsReportSchema>;
 export const ClientDiagnosticsAcceptedSchema = z.object({

package/src/schemas/metrics.test.ts

@@ -0,0 +1,80 @@
+import { type SandboxMetrics, SandboxMetricsSchema } from "./metrics.js";
+
+// A daemon payload from before memoryBreakdown and the other optional accounting fields existed.
+const legacyMetrics = {
+    at: 1_000_000,
+    sandbox: {
+        cores: 2,
+        memoryBytes: 7 * 2 ** 30,
+        memoryLimitBytes: 16 * 2 ** 30,
+        loadAverage: [1.5, 1.25, 1],
+        processes: 3,
+    },
+    daemon: { rssBytes: 300 * 2 ** 20, heapUsedBytes: 120 * 2 ** 20 },
+    sessions: { "conv-a": { processes: 2, rssBytes: 400 * 2 ** 20 } },
+    roles: {
+        agentRuntime: { processes: 1, rssBytes: 300 * 2 ** 20 },
+        terminal: { processes: 1, rssBytes: 100 * 2 ** 20 },
+    },
+} satisfies SandboxMetrics;
+
+describe("the metrics memory accounting contract", () => {
+    test("an older payload parses unchanged without the optional breakdown or its categories", () => {
+        const parsed = SandboxMetricsSchema.parse(legacyMetrics);
+        expect(parsed).toEqual(legacyMetrics);
+        expect(Object.hasOwn(parsed.sandbox, "memoryBreakdown")).toBe(false);
+    });
+
+    test("a partial new breakdown preserves zero and leaves unmeasured categories absent", () => {
+        const payload = {
+            ...legacyMetrics,
+            sandbox: {
+                ...legacyMetrics.sandbox,
+                memoryBreakdown: { anonymousBytes: 0, inactiveFileCacheBytes: 3 * 2 ** 30 },
+            },
+        };
+        expect(SandboxMetricsSchema.parse(payload)).toEqual(payload);
+    });
+
+    test("each category is independently optional, with no zero defaults for the others", () => {
+        for (const memoryBreakdown of [
+            {},
+            { anonymousBytes: 0 },
+            { countedFileCacheBytes: 0 },
+            { kernelBytes: 0 },
+            { inactiveFileCacheBytes: 0 },
+        ]) {
+            const payload = { ...legacyMetrics, sandbox: { ...legacyMetrics.sandbox, memoryBreakdown } };
+            expect(SandboxMetricsSchema.parse(payload)).toEqual(payload);
+        }
+    });
+
+    test("measured resident categories remain separate from a headline that also counts full swap", () => {
+        const payload = {
+            ...legacyMetrics,
+            sandbox: {
+                ...legacyMetrics.sandbox,
+                memoryBytes: 16.5 * 2 ** 30,
+                swapBytes: 9.5 * 2 ** 30,
+                swapLimitBytes: 10 * 2 ** 30,
+                swapFull: true,
+                memoryBreakdown: {
+                    anonymousBytes: 5 * 2 ** 30,
+                    countedFileCacheBytes: 2 ** 30,
+                    kernelBytes: 2 ** 30,
+                    inactiveFileCacheBytes: 3 * 2 ** 30,
+                },
+            },
+        };
+        expect(SandboxMetricsSchema.parse(payload)).toEqual(payload);
+    });
+
+    test("present categories must be byte numbers, not numeric strings or non-finite values", () => {
+        for (const field of ["anonymousBytes", "countedFileCacheBytes", "kernelBytes", "inactiveFileCacheBytes"]) {
+            for (const invalid of ["0", null, Number.NaN, Number.POSITIVE_INFINITY]) {
+                const payload = { ...legacyMetrics, sandbox: { ...legacyMetrics.sandbox, memoryBreakdown: { [field]: invalid } } };
+                expect(SandboxMetricsSchema.safeParse(payload).success).toBe(false);
+            }
+        }
+    });
+});

package/src/schemas/metrics.ts

@@ -1,7 +1,7 @@
 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.
+// unless the field says otherwise; memory is in bytes, with admission accounting and process RSS distinguished below.
 
 // The kinds of process a sandbox runs, as the daemon classifies them by command line.
 export const PROCESS_ROLES = [
@@ -30,7 +30,7 @@ export const ProcessGroupMetricsSchema = z.object({
     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.",
+            "Their process resident memory (RSS) added up, in bytes, including file mappings and shared pages counted once per process. This can exceed what they cost together. It excludes unmapped file cache, kernel memory and swapped-out pages.",
         ),
 });
 export type ProcessGroupMetrics = z.infer<typeof ProcessGroupMetricsSchema>;
@@ -84,24 +84,46 @@ export const SandboxUsageSchema = z.object({
     memoryBytes: z
         .number()
         .describe(
-            "Memory counted against the limit, as the daemon admits work by it: resident memory less the file cache the kernel takes back on demand, and once swap is full (`swapFull`) what was pushed to swap as well.",
+            "Memory counted against the limit, as the daemon admits work by it: the cgroup's resident charge, including the daemon, kernel memory and file cache except inactive_file, plus swapped bytes only when swap is nearly full (`swapFull`). Falls back to the machine's used memory when the budget cannot measure it.",
         ),
     memoryLimitBytes: z
         .number()
         .describe(
             "The memory limit work is admitted against: where the kernel starts throttling the container (memory.high), else its hard limit, else the machine's memory.",
         ),
+    memoryBreakdown: z
+        .object({
+            anonymousBytes: z.number().optional().describe("Anonymous resident memory charged to the cgroup (memory.stat anon), in bytes."),
+            countedFileCacheBytes: z
+                .number()
+                .optional()
+                .describe("File cache counted in resident usage (memory.stat file less inactive_file), in bytes. Absent unless both counters are valid."),
+            kernelBytes: z
+                .number()
+                .optional()
+                .describe("Kernel memory charged to the cgroup (memory.stat kernel), in bytes. Absent on kernels without that aggregate."),
+            inactiveFileCacheBytes: z
+                .number()
+                .optional()
+                .describe("Inactive file cache (memory.stat inactive_file), in bytes, excluded from memoryBytes."),
+        })
+        .optional()
+        .describe(
+            "Approximate measured memory.stat categories, not an RSS subtraction or an exact sum of memoryBytes: admission is sampled separately and may also count swap. Missing or invalid categories are omitted, not zero. Absent without cgroup memory, on machine-memory fallback, when no category is valid, and from older daemons.",
+        ),
     swapBytes: z
         .number()
         .optional()
         .describe(
-            "What was pushed out to swap, counted in `memoryBytes` only once swap is full. Absent where the sandbox cannot see its own memory.",
+            "What was pushed out to swap, counted in `memoryBytes` only when swap is nearly full under admission policy. Absent where the sandbox cannot see its own memory.",
         ),
     swapLimitBytes: z.number().optional().describe("What swap can hold. Absent where nothing bounds it, and from a daemon that predates it."),
     swapFull: z
         .boolean()
         .optional()
-        .describe("Swap is nearly at `swapLimitBytes`: nothing more can be parked there, so what is swapped counts against the limit too."),
+        .describe(
+            "Swap has reached the admission policy's nearly-full threshold against `swapLimitBytes`, so swapped bytes count against the memory limit too, even if swap space remains.",
+        ),
     memoryRoom: MemoryRoomSchema.optional().describe("What admission reads off the same reading. Absent from a daemon that predates it."),
     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."),
@@ -114,7 +136,7 @@ export const SandboxUsageSchema = z.object({
         .describe(
             "Cores the machine's load average reads against: every core the sandbox may be scheduled on, before any quota. Absent from a daemon that predates it.",
         ),
-    processes: z.number().describe("How many processes are running in the sandbox."),
+    processes: z.number().describe("How many processes are running in the sandbox, including the daemon."),
     pressure: PressureMetricsSchema.optional().describe(
         "How much work waited on CPU, memory or disk lately. Absent where the kernel does not report it.",
     ),
@@ -140,12 +162,12 @@ export const SandboxMetricsSchema = z.object({
         .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."),
+    sandbox: SandboxUsageSchema.describe("The sandbox as a whole, including the daemon."),
+    daemon: DaemonUsageSchema.describe("The daemon's own usage, included in the sandbox total and process count but excluded from roles and session sums."),
     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.",
+            "What each conversation's processes use, by conversation id: the agent's own process and everything it started, excluding the daemon. These group many of the same process readings as roles, not additional memory. Only conversations with processes running, and only those the caller may see.",
         ),
     roles: z
         .partialRecord(ProcessRoleSchema, ProcessGroupMetricsSchema)

package/src/schemas/needs.ts

@@ -57,6 +57,13 @@ export type CapabilityNeed = z.infer<typeof CapabilityNeedSchema>;
 // The alphabet a `{{secret:NAME}}` reference resolves; a pasted value is stored under exactly this name.
 export const SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 
+// A `{{secret:name}}` reference wherever it stands in text, capturing the name. Wider than SECRET_NAME, since a
+// reference also names the other stores' entries (`<capability>/<field>`). Not global, so a shared instance carries no
+// `lastIndex` between callers: a site that replaces or spans every one derives its own /g copy from it. The terminal
+// filter (@intentic/output-cleaners, builtins only) keeps a copy, pinned to this one by the daemon's
+// src/secrets/terminal-masking-parity.test.ts.
+export const SECRET_REFERENCE = /\{\{secret:([A-Za-z0-9_./-]+)\}\}/;
+
 export const SecretNeedSchema = z.object({
     kind: z.literal("secret"),
     name: z.string().regex(SECRET_NAME).describe("The name it is stored under, and what `{{secret:NAME}}` will resolve."),
@@ -283,6 +290,16 @@ export const AgentNeedSchema = z.object({
 });
 export type AgentNeed = z.infer<typeof AgentNeedSchema>;
 
+// A credential gateway card's "Allow requests like this with <name> in this conversation": the `ask` rule it answered
+// stops asking that conversation, until somebody takes it back. Kept by the rule's own content, so editing the rule
+// asks again.
+export const BrokerRulePassSchema = z.object({
+    capability: z.string().describe("The capability whose rule asked, by id."),
+    rule: z.string().describe("The rule's own identity (its content), so an edited rule is a different one and asks again."),
+    said: z.string().describe('The request in a person\'s words, as the card put it: "GET api.github.com/repos/x with GitHub".'),
+});
+export type BrokerRulePass = z.infer<typeof BrokerRulePassSchema>;
+
 // What a person allowed one conversation beyond its persona and area, from a grant need's card
 // (personas/conversation-grants.ts). Honoured from that conversation's next turn on, and revocable on the Grants page.
 export const ConversationGrantSchema = z.object({
@@ -306,6 +323,11 @@ export const ConversationGrantSchema = z.object({
         .boolean()
         .default(false)
         .describe("Whether every request an allow-once could settle is allowed without asking, until somebody takes it back."),
+    // Answered on a credential gateway card, read live by the gateway as each request its rules would ask about arrives.
+    rules: z
+        .array(BrokerRulePassSchema)
+        .default([])
+        .describe("Credential gateway rules that no longer ask before its requests, each with the words a person allowed it in."),
     updatedAt: z.number().describe("When it last changed, in milliseconds."),
     by: z.string().optional().describe("Who last allowed something here."),
 });
@@ -323,6 +345,7 @@ export const StandingGrantsSchema = z.object({
             installs: z.boolean().default(false).describe("Whether its own dependency installs run without asking."),
             secrets: z.array(z.string()).default([]).describe("Secrets it may send past their host guard without asking."),
             everything: z.boolean().default(false).describe("Whether every request an allow-once could settle is allowed without asking."),
+            rules: z.array(BrokerRulePassSchema).default([]).describe("Credential gateway rules that no longer ask before its requests."),
             by: z.string().optional().describe("Who last allowed one of those."),
             updatedAt: z.number().optional().describe("When one of those last changed, in milliseconds."),
             releases: z
@@ -336,11 +359,14 @@ export type StandingGrants = z.infer<typeof StandingGrantsSchema>;
 export const GrantRevokeSchema = z.object({
     conversationId: z.string(),
     kind: z
-        .enum(["capability", "folder", "shelf", "release", "install", "secret", "everything"])
+        .enum(["capability", "folder", "shelf", "release", "install", "secret", "everything", "rule"])
         .describe(
-            "Which kind of yes: a grant past the persona or area, a credential's release, letting its installs run unasked, a secret sent past its host guard, or allowing everything.",
+            "Which kind of yes: a grant past the persona or area, a credential's release, letting its installs run unasked, a secret sent past its host guard, allowing everything, or a credential gateway rule that stopped asking.",
         ),
-    what: z.string().describe("The capability id, folder, shelf, released credential or secret it named; empty for installs and everything."),
+    what: z
+        .string()
+        .describe("The capability id, folder, shelf, released credential or secret it named, or the rule's identity; empty for installs and everything."),
+    capability: z.string().optional().describe("For a rule, the capability whose rule it is; a rule's identity alone does not say."),
 });
 export type GrantRevoke = z.infer<typeof GrantRevokeSchema>;