@intentic/sandbox-contract 1.329.0 → 1.331.0

package/src/schemas/run-targets.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { ArtifactNameSchema } from "./device-artifacts.js";
+
+// WHAT A REPOSITORY SAYS IT CAN BE RUN AS, ON ONE OF THE OWNER'S COMPUTERS (`<repo>/.intentic/run.json`). Beside the
+// build scripts it names and tracked with them, like `.intentic/checks.json`. One file serves two doors that must do the
+// same thing: an agent's `devices run <target>` in its own shell, and the editor's "Run on <device>" button, which runs
+// that very command in a terminal the owner watches. Each run builds in the sandbox, carries the build to the device
+// (`devices push`), opens the device ports the target says the sandbox needs (`devices reach`), and starts the program
+// there (the device's app_start). Nothing here runs by itself: a target runs when someone runs it.
+//
+//   {
+//     "targets": [{
+//       "name": "desktop",
+//       "device": "rog",
+//       "build": "bash _tools/scripts/desktop/build-desktop.sh 0.0.0 --windows-only",
+//       "artifact": {
+//         "intentic-desktop.exe": "_editor/desktop-app/src-tauri/target/x86_64-pc-windows-msvc/release/intentic-desktop.exe",
+//         "intentic-files.exe": "_editor/desktop-app/src-tauri/binaries/intentic-files-x86_64-pc-windows-msvc.exe"
+//       },
+//       "program": "intentic-desktop.exe"
+//     }]
+//   }
+
+export const RUN_TARGETS_FILE = ".intentic/run.json";
+
+const RepoPathSchema = z
+    .string()
+    .min(1)
+    .max(500)
+    .refine((path) => !path.startsWith("/") && !path.split(/[\\/]/).includes(".."), "a path inside the repository, relative to its root");
+const BundleNameSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9 ._()+-]{0,199}(\/[A-Za-z0-9][A-Za-z0-9 ._()+-]{0,199})*$/, "a relative name, folders by /");
+
+export const RunTargetSchema = z
+    .object({
+        // What `devices run <name>` and the button call it.
+        name: ArtifactNameSchema,
+        description: z.string().max(300).optional(),
+        // The computer it runs on unless one is named at the run; the device's name as its tools are mounted.
+        device: z.string().min(1).max(100).optional(),
+        // A shell command run from the repository's root, in the sandbox, before every run; absent means the artifact
+        // is already there.
+        build: z.string().min(1).max(4000).optional(),
+        // What is carried: one file or one folder, or a set of files and folders gathered into one folder under names of
+        // their own (an .exe beside the sidecars, DLLs and resource folders it looks for next to itself).
+        artifact: z.union([RepoPathSchema, z.record(BundleNameSchema, RepoPathSchema)]),
+        // Which file to start when the artifact is a folder or a set; a lone file is started as itself.
+        program: BundleNameSchema.optional(),
+        args: z.array(z.string().max(4000)).max(100).default([]),
+        env: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.string().max(4000)).default({}),
+        // Run it inside Windows Sandbox, a throwaway VM that sees the build read-only and nothing else of the machine.
+        isolated: z.boolean().default(false),
+        // The device's own loopback ports the sandbox needs to reach while it runs (its local API, a dev server), each
+        // opened at the same port in the sandbox.
+        reach: z.array(z.int().min(1).max(65535)).max(16).default([]),
+    })
+    .strict();
+export type RunTarget = z.infer<typeof RunTargetSchema>;
+
+export const RunTargetsFileSchema = z
+    .object({
+        targets: z
+            .array(RunTargetSchema)
+            .min(1)
+            .max(50)
+            .refine((targets) => new Set(targets.map((target) => target.name)).size === targets.length, "two targets share a name"),
+    })
+    .strict();
+
+// One repository's file as the editor lists it: its targets, or what is wrong with the file.
+export const RepoRunTargetsSchema = z.object({
+    repo: z.string(),
+    path: z.string(),
+    targets: z.array(RunTargetSchema),
+    error: z.string().optional(),
+});
+
+export const RunTargetsListSchema = z.object({
+    repos: z.array(RepoRunTargetsSchema),
+    // The owner's computers: whether each is connected, whether its agent is new enough to take a program, and whether
+    // its card's "Run programs this sandbox sends" switch is on. A run needs all three.
+    devices: z.array(z.object({ id: z.string(), online: z.boolean(), programs: z.boolean(), allowed: z.boolean() })),
+});
+export type RunTargetsList = z.infer<typeof RunTargetsListSchema>;
+
+export const RunStartSchema = z.object({
+    repo: z.string().min(1),
+    target: ArtifactNameSchema,
+    device: z.string().min(1).max(100),
+});
+export type RunStart = z.infer<typeof RunStartSchema>;
+
+// The terminal session the run is in, for the editor to open.
+export const RunStartedSchema = z.object({ session: z.string() });

package/src/schemas/settings-history.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { at, drop, dropAll, fold, isJsonObject, mapValue, retype } from "../documents/conversions.js";
+import { at, drop, dropAll, fold, isJsonObject, type JsonObject, mapValue, retype, transform } from "../documents/conversions.js";
 import type { KeepWarmSettings, RuleSchema } from "./settings.js";
 
 // The conversions the settings shape has had, oldest first: what brings any earlier release's settings to
@@ -63,6 +63,19 @@ const keepWarmObject = fold("folds keepWarm, keepWarmHours, keepWarmMinTokens an
     },
 });
 
+// The Refactors job (2026-10-09): a refactor started from a repository's Health tab used to name no job and opened on
+// whatever model the composer last held. A file from before it inherits the Maintenance chores list, the job nearest in
+// kind, so the owner's choice for work they start carries over instead of the new job opening empty. Only while the key
+// is absent: an owner who later empties it stores [], which this leaves alone.
+type RolesWithChores = JsonObject & { readonly "maintenance-chore": readonly unknown[] };
+const holdsChoresWithoutRefactors = (roles: JsonObject): roles is RolesWithChores =>
+    !Object.hasOwn(roles, "refactor-run") && Array.isArray(roles["maintenance-chore"]) && roles["maintenance-chore"].length > 0;
+const refactorsFromChores = transform(
+    "gives the new Refactors job the Maintenance chores list",
+    holdsChoresWithoutRefactors,
+    (roles): JsonObject => ({ ...roles, "refactor-run": roles["maintenance-chore"] }),
+);
+
 export const SETTINGS_HISTORY = [
     // Every setting a release since 2026-08-10 had and this one does not (read off the contract lock's history):
     // retired, so passthrough stops carrying them, a definition naming one still applies, and no later setting may
@@ -112,4 +125,5 @@ export const SETTINGS_HISTORY = [
     at("modelRoles", drop("pre-push-fix")),
     // The short guidance form (2026-10-06): it lost its A/B to the full one, which every turn now gets.
     ...dropAll(["leanGuidance", "leanGuidanceHoldout"]),
+    at("modelRoles", refactorsFromChores),
 ] as const;

package/src/schemas/settings.test.ts

@@ -129,3 +129,28 @@ describe(`the retired pre-push fix role`, () => {
         expect(convertDocument(SETTINGS_HISTORY, `object`, { modelRoles: { "pipeline-fix": [pin] } }, true).changes).toEqual([]);
     });
 });
+
+// The Refactors job arrived on 2026-10-09; a file from before it carries the owner's Maintenance chores list over, so a
+// refactor started from Health opens on a model they chose rather than on an empty job.
+describe(`the new Refactors job`, () => {
+    const opus = { provider: `claude`, model: `claude-opus-5-5` };
+    const sol = { provider: `codex`, model: `gpt-sol-6.1` };
+
+    test(`takes the Maintenance chores list in a file from before it, and every other list stays`, () => {
+        const stored = { modelRoles: { "maintenance-chore": [opus, sol], "pipeline-fix": [sol] } };
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, stored, true);
+        expect(converted.value).toEqual({ modelRoles: { "maintenance-chore": [opus, sol], "pipeline-fix": [sol], "refactor-run": [opus, sol] } });
+        expect(SandboxSettingsSchema.parse(converted.value).modelRoles[`refactor-run`]).toEqual([opus, sol]);
+    });
+
+    test(`leaves a list the owner set, even an emptied one, and a file with no chores list`, () => {
+        for (const modelRoles of [
+            { "maintenance-chore": [opus], "refactor-run": [sol] },
+            { "maintenance-chore": [opus], "refactor-run": [] },
+            { "pipeline-fix": [opus] },
+            { "maintenance-chore": [] },
+        ]) {
+            expect(convertDocument(SETTINGS_HISTORY, `object`, { modelRoles }, true).changes).toEqual([]);
+        }
+    });
+});

package/src/schemas/settings.ts

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { CommandJudgeModeSchema, ProjectInstallModeSchema } from "../policy/safety-policy.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
 import { AdmissionPolicySchema, AdmissionRuleSchema, ModelPinSchema } from "./agent.js";
-import { LimitPolicySchema, RetryPolicySchema } from "./turn-break.js";
+import { LimitPolicySchema, RetryPolicySchema, RoomPolicySchema } from "./turn-break.js";
 import { ZoneSchema } from "../time/zone.js";
 // Which prompt base the agent runs before this turn composes anything on top: Intentic's own (default), Claude Code's
 // preset, or the owner's text. Declared out here since both the daemon and the browser branch on it.
@@ -452,6 +452,11 @@ export const SandboxSettingsSchema = z.object({
     stopPolicy: RetryPolicySchema.default("wait").describe(
         "What happens to a turn that stopped short with nothing to repair — a hung runtime, a crashed harness. `wait` holds it for a press. `retry` re-runs the held turn on a short ladder, standing down after three tries that got nowhere rather than looping forever.",
     ),
+    // The one ending that defaults to going by itself: nothing ran, so sending it once there is room spends nothing twice,
+    // and it is what the person meant when they pressed Send.
+    memoryPolicy: RoomPolicySchema.default("resend").describe(
+        "What happens to a message the sandbox held because it was short of memory: nothing ran, so nothing was spent. `resend` sends it by itself once memory has stayed free for a while, one held conversation at a time. `wait` holds it until somebody presses Send anyway. The sandbox-wide default; any one conversation can say otherwise.",
+    ),
     limitMoveCarryUnder: z
         .number()
         .int()

package/src/schemas/speech.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+
+// Dictation on this sandbox: which local model hears a language, how far it is from ready, and the live wire the
+// composer streams a spoken phrase over. The daemon's engine is src/speech; the composer's half is
+// _editor/web/src/features/chat/composer/voice.
+
+// The models a sandbox can hear with, by what they are for:
+// - `parakeet` (NVIDIA Parakeet TDT 0.6B v3): 25 European languages, punctuated, ~30x faster than real time on two
+//   cores. Baked into the standard image, and the default for any language it covers.
+// - `whisper` (OpenAI Whisper large-v3-turbo): the other ~75 languages, slower, fetched the first time one is asked for.
+export const SpeechEngineSchema = z.enum(["parakeet", "whisper"]);
+export type SpeechEngine = z.infer<typeof SpeechEngineSchema>;
+
+// The 25 Parakeet hears, as ISO 639-1 primary subtags: it detects which on its own, so a browser in English and a
+// speaker in Polish still land on it.
+export const PARAKEET_LANGUAGES: ReadonlySet<string> = new Set([
+    "bg",
+    "cs",
+    "da",
+    "de",
+    "el",
+    "en",
+    "es",
+    "et",
+    "fi",
+    "fr",
+    "hr",
+    "hu",
+    "it",
+    "lt",
+    "lv",
+    "mt",
+    "nl",
+    "pl",
+    "pt",
+    "ro",
+    "ru",
+    "sk",
+    "sl",
+    "sv",
+    "uk",
+]);
+
+// A locale's primary subtag, lowercased, or undefined for anything that is not one (`""`, `*`, `auto`).
+export const speechLanguage = (locale: string | undefined): string | undefined => {
+    const primary = (locale ?? "").trim().toLowerCase().split(/[-_]/u)[0] ?? "";
+    return /^[a-z]{2,3}$/u.test(primary) && primary !== "auto" ? primary : undefined;
+};
+
+// Which model hears a locale: Parakeet for its own languages and for anything unreadable, Whisper for the rest.
+export const speechEngineFor = (locale: string | undefined): SpeechEngine => {
+    const language = speechLanguage(locale);
+    return language === undefined || PARAKEET_LANGUAGES.has(language) ? "parakeet" : "whisper";
+};
+
+export const SpeechStatusSchema = z.object({
+    provisioned: z.boolean().describe("This sandbox can run speech recognition at all."),
+    model: z
+        .enum(["absent", "downloading", "ready", "failed"])
+        .describe("Whether the model for the asked language is on disk: baked into the image, fetched, being fetched, or its fetch failed."),
+    engine: SpeechEngineSchema.optional().describe("Which model hears the asked language."),
+    loaded: z.boolean().optional().describe("The model is in memory, so the next phrase is heard without a load first."),
+    received: z.number().optional().describe("Bytes of the model fetched so far, while it downloads."),
+    total: z.number().optional().describe("The model's whole size in bytes, while it downloads."),
+    error: z.string().optional().describe("Why the last fetch failed, when it did."),
+});
+export type SpeechStatus = z.infer<typeof SpeechStatusSchema>;
+
+// GET /speech/stream, a WebSocket: the composer cuts the microphone into phrases itself (its silence segmenter) and
+// streams each one as it is spoken. A text frame `begin` opens phrase `id`; binary frames that follow are its audio,
+// 16 kHz mono s16le; `end` closes it, keeping its first `keep` samples (the trailing pause trimmed off); `drop`
+// abandons it. The daemon answers with `partial` text while the phrase is still being spoken, one `final` per ended
+// phrase, in order, and `status` whenever the model's readiness moves. The language is the socket's `lang` query.
+export const SpeechClientMessageSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("begin"), id: z.number() }),
+    z.object({ type: z.literal("end"), id: z.number(), keep: z.number() }),
+    z.object({ type: z.literal("drop"), id: z.number() }),
+]);
+export type SpeechClientMessage = z.infer<typeof SpeechClientMessageSchema>;
+
+export const SpeechServerMessageSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("status"), status: SpeechStatusSchema }),
+    z.object({ type: z.literal("partial"), id: z.number(), text: z.string() }),
+    z.object({
+        type: z.literal("final"),
+        id: z.number(),
+        text: z.string().describe("Empty when the phrase held no words."),
+        decodeMs: z.number().describe("How long hearing it took once its audio was in."),
+    }),
+    z.object({ type: z.literal("error"), id: z.number().optional(), message: z.string() }),
+]);
+export type SpeechServerMessage = z.infer<typeof SpeechServerMessageSchema>;
+
+// The longest phrase either door takes: a minute at 16 kHz. The composer's segmenter cuts a monologue at the same
+// length, so nothing it sends is ever refused.
+export const MAX_SPEECH_SAMPLES = 60 * 16_000;

package/src/schemas/terminal.ts

@@ -140,6 +140,10 @@ export const BrowsersListSchema = z.object({
 });
 export type BrowsersList = z.infer<typeof BrowsersListSchema>;
 export const BrowserNameParamSchema = z.object({ name: z.string().describe("Which browser.") });
+export const BrowserPageParamSchema = z.object({
+    name: z.string().describe("Which browser."),
+    pageId: z.string().describe("Which of its tabs: a page id from the roster."),
+});
 export const OpenBrowserInputSchema = z.object({
     url: z.string().optional().describe("Where the new tab goes. Absent opens a blank tab, the way a browser's own new tab does."),
 });

package/src/schemas/turn-break.ts

@@ -7,20 +7,23 @@
 
 import { z } from "zod";
 
-// The three endings that leave finished work behind a live session and can be picked back up. Spelled exactly as
-// `TurnEndingSchema.reason` spells them, so the ending a surface reads and the question it asks are one word. A restart
-// is handled apart (SandboxSettings.autoResumeOnRestart): nobody is watching a restart, so it has no in-chat question.
-export const TurnBreakSchema = z.enum(["limit", "outage", "stopped"]);
+// The walls a turn can stop at that take a standing answer. The first three end a turn that leaves finished work behind
+// a live session, spelled exactly as `TurnEndingSchema.reason` spells them, so the ending a surface reads and the
+// question it asks are one word. `memory` is the door: the sandbox too short of memory to start the turn at all, which
+// holds the message (or the turn the sandbox kept) until a press or room comes back. A restart is handled apart
+// (SandboxSettings.autoResumeOnRestart): nobody is watching a restart, so it has no in-chat question.
+export const TurnBreakSchema = z.enum(["limit", "outage", "stopped", "memory"]);
 export type TurnBreak = z.infer<typeof TurnBreakSchema>;
 
-// Every ending that leaves a held turn behind: the three above, plus the provider's safety classifier stopping a turn
-// partway. That one has no standing answer and never re-runs by itself: the person picks, each time, between the same
-// model again and another one (2026-09-30, the owner's call over an automatic model switch).
-export const HeldEndingSchema = z.enum([...TurnBreakSchema.options, "flagged"]);
+// Every ending that leaves a held turn behind: a spent allowance, an outage, a turn that stopped short, plus the
+// provider's safety classifier stopping a turn partway. That one has no standing answer and never re-runs by itself: the
+// person picks, each time, between the same model again and another one (2026-09-30, the owner's call over an automatic
+// model switch). A low-memory hold is no ending: nothing ran, so it is never one of these.
+export const HeldEndingSchema = z.enum(["limit", "outage", "stopped", "flagged"]);
 export type HeldEnding = z.infer<typeof HeldEndingSchema>;
 
 /** Whether this ending takes a standing answer (turn-break policy), which `flagged` never does. */
-export const isTurnBreak = (ending: HeldEnding): ending is TurnBreak => ending !== "flagged";
+export const isTurnBreak = (ending: HeldEnding): ending is Exclude<HeldEnding, "flagged"> => ending !== "flagged";
 
 // `move` implies `resend`: an account with room is tried at once, and the reset appointment stands as its fallback.
 // There is deliberately no "move, else hold" — a reader willing to spend a second account is willing to wait.
@@ -31,6 +34,11 @@ export type LimitPolicy = z.infer<typeof LimitPolicySchema>;
 export const RetryPolicySchema = z.enum(["wait", "retry"]);
 export type RetryPolicy = z.infer<typeof RetryPolicySchema>;
 
+// The memory wall's two answers: hold for a press, or send once the sandbox has room again. Nothing ran, so sending it
+// then spends nothing twice.
+export const RoomPolicySchema = z.enum(["wait", "resend"]);
+export type RoomPolicy = z.infer<typeof RoomPolicySchema>;
+
 // One answer, whichever ending asked. Read against the ending: only `limit` can be `move`.
 export const TurnBreakPolicySchema = z.enum(["wait", "resend", "move", "retry"]);
 export type TurnBreakPolicy = z.infer<typeof TurnBreakPolicySchema>;
@@ -40,6 +48,7 @@ export const TURN_BREAK_POLICIES: Readonly<Record<TurnBreak, readonly TurnBreakP
     limit: ["wait", "resend", "move"],
     outage: ["wait", "retry"],
     stopped: ["wait", "retry"],
+    memory: ["wait", "resend"],
 };
 
 /** Whether this ending may be answered this way; the one gate every writer goes through. */

package/src/schemas/workspace/workspace-graph.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+
+// A monorepo's architecture as its files state it: the packages pnpm-workspace.yaml names, which siblings each declares
+// and what its own files do with them, and, inside one package, how its modules import each other. Facts only: what to
+// draw, and what counts as a finding, is the reader's.
+
+// A component of the repository's map, docs/architecture/repo.json, which the documentation extension writes.
+export const WorkspaceComponentSchema = z.object({
+    id: z.string().describe("The component's id."),
+    name: z.string().describe("What the map calls it."),
+    accent: z.string().optional().describe('The map\'s colour slot for it: "1" to "5", or "neutral".'),
+});
+export type WorkspaceComponent = z.infer<typeof WorkspaceComponentSchema>;
+
+// A pnpm-workspace package, discovered from pnpm-workspace.yaml's globs. group is the top-level dir segment; component
+// is the repo.json component listing its dir, when the repository has a map.
+export const WorkspacePackageSchema = z.object({
+    name: z.string().describe("The name the package declares."),
+    dir: z.string().describe("Where it lives, relative to the repository."),
+    group: z.string().describe("The top-level folder it sits under, which is what a diagram colours by."),
+    component: z.string().optional().describe("The component of docs/architecture/repo.json that lists it, by id. Absent without a map."),
+});
+export type WorkspacePackage = z.infer<typeof WorkspacePackageSchema>;
+export const WorkspaceDepTypeSchema = z.enum(["prod", "dev", "peer"]);
+export type WorkspaceDepType = z.infer<typeof WorkspaceDepTypeSchema>;
+
+// What the dependent's own files do with a sibling it declares, read from them: the strongest use found wins.
+export const WorkspaceDepUsageSchema = z
+    .enum(["code", "types", "tooling", "reference", "none"])
+    .describe(
+        "What the dependent's own files do with it: `code`, a shipped file imports a value from it; `types`, shipped files import only its types; `tooling`, only its tests, scripts and config files use it; `reference`, a shipped file names it without importing it (a Dockerfile copying its build, a manifest listing its files); `none`, nothing in the dependent names it.",
+    );
+export type WorkspaceDepUsage = z.infer<typeof WorkspaceDepUsageSchema>;
+
+// A workspace-internal dependency edge: from depends on to, typed by which dependency block declared it.
+export const WorkspaceDepEdgeSchema = z.object({
+    from: z.string().describe("The package that depends."),
+    to: z.string().describe("The package it depends on."),
+    type: WorkspaceDepTypeSchema.describe("Which kind of dependency declared it."),
+    usage: WorkspaceDepUsageSchema.optional(),
+});
+export type WorkspaceDepEdge = z.infer<typeof WorkspaceDepEdgeSchema>;
+export const WorkspaceGraphSchema = z.object({
+    packages: z.array(WorkspacePackageSchema).describe("Every package in the repository."),
+    edges: z.array(WorkspaceDepEdgeSchema).describe("Which of them use which. Pure data: how to lay it out is yours to decide."),
+    components: z
+        .array(WorkspaceComponentSchema)
+        .optional()
+        .describe("The components of docs/architecture/repo.json, in the map's order. Absent when the repository has no map."),
+});
+export type WorkspaceGraph = z.infer<typeof WorkspaceGraphSchema>;
+
+// layers.json beside a package's package.json: the layers its modules sit in, lowest first. A module may import its own
+// layer and any below it; an import reaching higher is a finding, and so is a cycle between units of one layer.
+export const PackageLayerSchema = z.object({
+    name: z.string().min(1).describe("The layer's name."),
+    about: z.string().optional().describe("What sits in it, in a sentence."),
+    units: z
+        .array(z.string().min(1))
+        .describe(
+            "Path prefixes under the root it holds: a directory, a subdirectory, or a module named without its extension. A file belongs to the layer whose unit matches it longest.",
+        ),
+});
+export type PackageLayer = z.infer<typeof PackageLayerSchema>;
+export const PackageLayersFileSchema = z.object({
+    root: z.string().optional().describe('The directory the units are relative to, from the package. Default "src".'),
+    shelves: z.array(z.string()).optional().describe("Top-level directories whose every subdirectory is a unit of its own, such as one per feature."),
+    surface: z
+        .array(z.string())
+        .optional()
+        .describe('File-name patterns, `*` a wildcard, of modules that sit above every layer, such as "*.routes.ts". Nothing below may import one.'),
+    layers: z.array(PackageLayerSchema).min(1).describe("The layers, lowest first."),
+});
+export type PackageLayersFile = z.infer<typeof PackageLayersFileSchema>;
+
+export const PackageModulesParamSchema = z.object({
+    repo: z.string().describe("Which repository."),
+    package: z.string().min(1).describe("Which of its workspace packages, by the name it declares."),
+});
+export const PackageUnitSchema = z.object({
+    id: z
+        .string()
+        .describe(
+            'The unit: a directory under the root, a shelf\'s subdirectory ("features/chat"), a unit layers.json names, "(surface)" for every surface module, or "(root)" for the modules directly in the root, which no rule judges.',
+        ),
+    modules: z.number().int().nonnegative().describe("How many source modules it holds."),
+    layer: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("The declared layer it sits in, by index, lowest 0. Absent when the package declares no layers, or none places it."),
+    surface: z.literal(true).optional().describe("The surface modules' unit, above every layer."),
+});
+export type PackageUnit = z.infer<typeof PackageUnitSchema>;
+export const PackageUnitEdgeSchema = z.object({
+    from: z.string().describe("The importing unit."),
+    to: z.string().describe("The unit it imports."),
+    imports: z.number().int().positive().describe("How many value imports make the edge."),
+    sites: z.array(z.string()).describe("Up to five of them, as `path:line` relative to the root."),
+});
+export type PackageUnitEdge = z.infer<typeof PackageUnitEdgeSchema>;
+export const PackageModulesSchema = z.object({
+    package: z.string().describe("The package."),
+    root: z.string().describe("The directory read, relative to the repository."),
+    layers: z
+        .array(PackageLayerSchema.pick({ name: true, about: true }))
+        .optional()
+        .describe("Its declared layers, lowest first. Absent when it has no layers.json."),
+    invalid: z.string().optional().describe("Why its layers.json could not be read, when it has one that does not parse."),
+    units: z.array(PackageUnitSchema).describe("Every unit with a module in it."),
+    edges: z
+        .array(PackageUnitEdgeSchema)
+        .describe("Value imports between units: type-only imports erase and tests import their subject, so neither counts."),
+});
+export type PackageModules = z.infer<typeof PackageModulesSchema>;

package/src/schemas/workspace/workspace-repos.ts

@@ -91,28 +91,6 @@ export const RepoAppSchema = z.object({
 export type RepoApp = z.infer<typeof RepoAppSchema>;
 export const AppsListSchema = z.object({ apps: z.array(RepoAppSchema).describe("The apps in this repository.") });
 export type AppsList = z.infer<typeof AppsListSchema>;
-// A pnpm-workspace package, discovered from pnpm-workspace.yaml's globs. group is the top-level dir segment, the
-// dependencies view's coloring axis.
-export const WorkspacePackageSchema = z.object({
-    name: z.string().describe("The name the package declares."),
-    dir: z.string().describe("Where it lives, relative to the repository."),
-    group: z.string().describe("The top-level folder it sits under, which is what a diagram colours by."),
-});
-export type WorkspacePackage = z.infer<typeof WorkspacePackageSchema>;
-export const WorkspaceDepTypeSchema = z.enum(["prod", "dev", "peer"]);
-export type WorkspaceDepType = z.infer<typeof WorkspaceDepTypeSchema>;
-// A workspace-internal dependency edge: from depends on to, typed by which dependency block declared it.
-export const WorkspaceDepEdgeSchema = z.object({
-    from: z.string().describe("The package that depends."),
-    to: z.string().describe("The package it depends on."),
-    type: WorkspaceDepTypeSchema.describe("Which kind of dependency declared it."),
-});
-export type WorkspaceDepEdge = z.infer<typeof WorkspaceDepEdgeSchema>;
-export const WorkspaceGraphSchema = z.object({
-    packages: z.array(WorkspacePackageSchema).describe("Every package in the repository."),
-    edges: z.array(WorkspaceDepEdgeSchema).describe("Which of them use which. Pure data: how to lay it out is yours to decide."),
-});
-export type WorkspaceGraph = z.infer<typeof WorkspaceGraphSchema>;
 // Path params for the per-repo apps routes: repo names the monorepo, validated like PanelRepoParam.
 export const RepoAppsParamSchema = z.object({ repo: z.string().describe("Which repository.") });
 export const AppParamSchema = z.object({

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

@@ -5,6 +5,7 @@ import {
     isLockedWorkspacePath,
     isReportedManifest,
     isReviewableLockedPath,
+    isUnversionedStatePath,
     LOCKED_STATE_ENTRIES,
     lockedWorkspaceEntry,
     PLAN_DOCUMENTS_DIR,
@@ -29,7 +30,13 @@ const AUTOMATIONS: readonly FileContribution[] = [
 
 describe(`staleQueryKeys`, () => {
     it(`maps a manifest write to the queries it makes stale`, () => {
-        expect(staleQueryKeys([`.intentic/config/capabilities.json`], [])).toEqual([`capabilities`, `extensions`, `environment`, `panels`, `manifests`]);
+        expect(staleQueryKeys([`.intentic/config/capabilities.json`], [])).toEqual([
+            `capabilities`,
+            `extensions`,
+            `environment`,
+            `panels`,
+            `manifests`,
+        ]);
     });
 
     it(`refreshes the unreadable-manifest notice for the four files a person hand-edits`, () => {
@@ -299,6 +306,40 @@ describe(`isReviewableLockedPath`, () => {
     });
 });
 
+// What lets a git-reading reaction skip a batch: the daemon's own churn under `.intentic` must not rescan every repo,
+// while a tracked config file still has to.
+describe(`isUnversionedStatePath`, () => {
+    it(`holds the machine state the daemon rewrites constantly`, () => {
+        expect(isUnversionedStatePath(`.intentic/local/privacy-log.json`)).toBe(true);
+        expect(isUnversionedStatePath(`.intentic/local/.privacy-log.json.55.3275.tmp`)).toBe(true);
+        expect(isUnversionedStatePath(`.intentic/records/extension-usage.json`)).toBe(true);
+        expect(isUnversionedStatePath(`.intentic/records/artifacts/browser/page.png`)).toBe(true);
+        // An unversioned file beside versioned ones in config is still invisible to git.
+        expect(isUnversionedStatePath(`.intentic/config/docs/index.json`)).toBe(true);
+    });
+
+    it(`lets every versioned entry through, files and directories alike`, () => {
+        for (const path of VERSIONED_STATE_PATHS) {
+            const inside = path.endsWith(`/`) ? `${path}nested/file.json` : path;
+            expect([inside, isUnversionedStatePath(inside)]).toEqual([inside, false]);
+        }
+    });
+
+    it(`never claims a path outside the workspace's own state dir`, () => {
+        expect(isUnversionedStatePath(`intentic/_sandbox/sandbox/src/main.ts`)).toBe(false);
+        expect(isUnversionedStatePath(`README.md`)).toBe(false);
+        // A repo's nested state dir is its project's content, which git does track.
+        expect(isUnversionedStatePath(`myrepo/.intentic/local/privacy-log.json`)).toBe(false);
+        expect(isUnversionedStatePath(`.intentic`)).toBe(false);
+    });
+
+    it(`reads a platform path and a dot-relative one the same as a posix one`, () => {
+        expect(isUnversionedStatePath(`.intentic\\local\\privacy-log.json`)).toBe(true);
+        expect(isUnversionedStatePath(`./.intentic/local/privacy-log.json`)).toBe(true);
+        expect(isUnversionedStatePath(`./.intentic/config/capabilities.json`)).toBe(false);
+    });
+});
+
 describe(`VERSIONED_STATE_PATHS`, () => {
     // versioned exempts an entry from the `.intentic` exclusion; a mismarked credential can't be unmarked once
     // committed.

package/src/state/workspace-state.ts

@@ -397,7 +397,7 @@ const STATE_FILES = [
     {
         path: ".intentic/local/cache/",
         invalidates: [],
-        why: "Rebuildable indexes and caches, the iq index and its vector sidecar, the whisper model, fileq's derived/ markdown shadows of binary files; ignored by the watcher and recreated from carried workspace content.",
+        why: "Rebuildable indexes and caches, the iq index and its vector sidecar, the speech models an image does not bake, fileq's derived/ markdown shadows of binary files; ignored by the watcher and recreated from carried workspace content.",
         portability: "derived",
     },
     // Extension runtime scratch, one directory per extension via `extensionStateDir` below (the only way an extension
@@ -769,6 +769,17 @@ export const isReviewableLockedPath = (relPath: string): boolean => {
     return isLockedWorkspacePath(rel) && VERSIONED_STATE_PATHS.some((path) => (path.endsWith("/") ? rel.startsWith(path) : rel === path));
 };
 
+// Machine state the root repo never tracks: everything under the workspace's own `.intentic/` but the `versioned`
+// entries history.ts carves back out of the wholesale exclusion. A write here moves no git status, no landing and no
+// review, so a reaction that exists to re-read git can pass over a batch made only of these. The daemon rewrites
+// some of them every few seconds under load (the privacy ledger, extension usage, browser screenshots), and each
+// one used to rescan every repo. Root-level only, like the exclusion it mirrors: a repo's own nested `.intentic` is
+// its project's content. Accepts either slash.
+export const isUnversionedStatePath = (relPath: string): boolean => {
+    const rel = relPath.replaceAll("\\", "/").replace(/^\.\//, "");
+    return rel.startsWith(`${STATE_DIR}/`) && !VERSIONED_STATE_PATHS.some((path) => (path.endsWith("/") ? rel.startsWith(path) : rel === path));
+};
+
 // Every path this table declares, as a type; the daemon joins paths only through `statePath`
 // (workspace/state-paths.ts), which accepts one of these and nothing else, so renaming a store's file is a compile
 // error everywhere it's named rather than a view that silently stops refreshing.

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

@@ -0,0 +1,39 @@
+import type { TranscriptRow, TranscriptTool } from "../events/transcript.js";
+import { fitNestedTool, fitPageRow, PAGE_TEXT_CAP } from "./transcript-page.js";
+
+// What a page carries of a row, which the daemon serves and the editor mirrors: the two have to agree to the byte.
+
+const long = `x`.repeat(PAGE_TEXT_CAP + 500);
+const call = (id: string, extra: Partial<TranscriptTool> = {}): TranscriptTool => ({
+    id,
+    name: `Bash`,
+    category: `execute`,
+    status: `completed`,
+    ...extra,
+});
+
+describe(`fitPageRow`, () => {
+    it(`hands back a row with no calls as it is`, () => {
+        const row: TranscriptRow = { role: `assistant`, text: `done` };
+        expect(fitPageRow(row)).toBe(row);
+    });
+
+    it(`keeps each output's start and counts a delegation's calls instead of carrying them`, () => {
+        const row: TranscriptRow = {
+            role: `assistant`,
+            text: ``,
+            tools: [call(`a`, { content: [{ type: `text`, text: long }] }), call(`b`, { name: `Agent`, children: [call(`c`), call(`d`)] })],
+        };
+        const fitted = fitPageRow(row);
+        expect(fitted.tools?.[0]?.content).toEqual([{ type: `text`, text: long.slice(0, PAGE_TEXT_CAP) }]);
+        expect(fitted.tools?.[1]?.children).toBeUndefined();
+        expect(fitted.tools?.[1]?.nested).toBe(2);
+    });
+});
+
+describe(`fitNestedTool`, () => {
+    it(`keeps every call under it, each output fitted at every depth`, () => {
+        const fitted = fitNestedTool(call(`a`, { children: [call(`b`, { content: [{ type: `text`, text: long }] })] }));
+        expect(fitted.children?.[0]?.content).toEqual([{ type: `text`, text: long.slice(0, PAGE_TEXT_CAP) }]);
+    });
+});