@intentic/sandbox-contract 1.159.0 → 1.161.0

package/src/schemas.ts

@@ -162,9 +162,18 @@ export type AttachTurn = z.infer<typeof AttachTurnSchema>;
 // conversationId. Isolated ones own a git worktree (branch agent/<id> in every workspace repo); the fleet
 // surface shows all of them with live status/activity/cost so the user can drive N agents in parallel.
 
-// idle/running/awaiting are the turn lifecycle (awaiting = paused on a plan approval or question); landed /
-// conflict are outcomes of the land flow; error is a terminal turn failure surfaced on the card.
-export const AgentStatusSchema = z.enum(["idle", "running", "awaiting", "landed", "conflict", "error"]);
+// idle/running/awaiting are the turn lifecycle (awaiting = paused on a plan approval or question); ready /
+// landed / conflict are outcomes of the land flow — `ready` is a clean completion whose delta stayed on the
+// agent's branch because auto-land is off (the user lands it deliberately, from the review panel or the card);
+// error is a terminal turn failure surfaced on the card.
+//
+// `interrupted` is the turn that never got to report ANY of those: the daemon died under it (a container
+// rebuild, a crash, an OOM kill), taking the provider process and the whole runtime half of the fleet — status,
+// attention flags, the park a question raised — with it. It exists because the alternative is worse than
+// unlabelled: without it such a turn rehydrates as `idle`, which is the resting status of a turn that finished
+// CLEANLY, so the board files a killed agent under Finished and the question it was holding disappears with the
+// process that asked it. See agents-store.ts — this is the status a live turn leaves on disk.
+export const AgentStatusSchema = z.enum(["idle", "running", "awaiting", "ready", "landed", "conflict", "error", "interrupted"]);
 export type AgentStatus = z.infer<typeof AgentStatusSchema>;
 // The card's live activity snippet: the last tool the agent used (with its target) and the in-progress todo.
 export const AgentActivitySchema = z.object({
@@ -190,10 +199,21 @@ export const AgentSummarySchema = z.object({
     status: AgentStatusSchema,
     provider: AgentProviderSchema,
     harness: AgentHarnessSchema,
+    // What the agent's last turn ran with — the model, its reasoning effort, and whether extended thinking was
+    // on. Recorded per agent because they are facts about THIS conversation: a client opening it seeds its
+    // composer from them, rather than from whatever that browser last picked in some other tab. Absent for an
+    // agent whose turns predate the record (model has always been kept; the other two are newer).
     model: z.string().optional(),
+    effort: z.string().optional(),
+    thinking: z.boolean().optional(),
     account: z.string().optional(),
     // The worktree branch (agent/<id>); absent for a non-isolated (main-tree) conversation.
     branch: z.string().optional(),
+    // This agent's own answer to "land automatically at turn completion?" — an explicit per-agent override of
+    // the sandbox-wide `autoLand` setting. ABSENT ⇒ inherit, which is the common case and the one that keeps
+    // the global toggle meaningful: an agent that never expressed an opinion follows the sandbox wherever it
+    // is pointed next. Written by `agents.autoLand`; the UI shows the EFFECTIVE value (this ?? the setting).
+    autoLand: z.boolean().optional(),
     // Present when the conversation was opened by an outside message rather than by the user (see
     // AgentOriginSchema) — the card's provenance line. Absent ⇒ the user started it.
     origin: AgentOriginSchema.optional(),
@@ -248,17 +268,88 @@ export const AgentIdsSchema = z.object({ ids: z.array(z.string().min(1)).min(1).
 // browser holds its optimistic add/remove of exactly these ids until it sees a roster at or past `rev`.
 export const AgentsMovedSchema = z.object({ moved: z.array(AgentSummarySchema), rev: z.number() });
 export type AgentsMoved = z.infer<typeof AgentsMovedSchema>;
+// What a purge actually deleted. Ids, not summaries: these agents no longer exist anywhere — there is nothing
+// left to show and nothing to put back, so the only thing the caller can do with the answer is drop those rows
+// and count them. No revision either: archived agents are already off the broadcast roster (see `list`), so a
+// purge changes nothing the board's pending-move machinery has to hold a card against.
+export const AgentsRemovedSchema = z.object({ removed: z.array(z.string()) });
+export type AgentsRemoved = z.infer<typeof AgentsRemovedSchema>;
+/* Search the fleet by what the USER wrote — the board's filter (and the popped-out rail's).
+ *
+ * Deliberately the user's own prompts and nothing else. An agent's replies and its tool output mention
+ * nearly every identifier in the workspace, so a transcript-wide match on a fleet this size returns most of
+ * the board and the filter stops filtering; the words the user typed are both what they remember and what
+ * tells two agents apart. The card TITLE is the first of those prompts (sanitized), so a title match and a
+ * prompt match are one rule, not two.
+ *
+ * Two chars minimum: below that every agent matches and the scan is pure cost.
+ */
+export const AgentSearchQuerySchema = z.object({ query: z.string().trim().min(2) });
+// One matching agent, and the evidence for it. `snippet` is the matched prompt windowed around the hit —
+// absent when the match is the title, which the card already shows. A card that matches for a reason the user
+// cannot see is worse than no filter at all.
+export const AgentMatchSchema = z.object({ id: z.string(), snippet: z.string().optional() });
+export type AgentMatch = z.infer<typeof AgentMatchSchema>;
+// `scanned` is how many agents the daemon actually read prompts for, so the board can say when a query saw
+// less than the whole fleet rather than implying it saw all of it.
+export const AgentSearchResultSchema = z.object({ matches: z.array(AgentMatchSchema), scanned: z.number() });
+export type AgentSearchResult = z.infer<typeof AgentSearchResultSchema>;
 // rename's input: the user-chosen display title (bounded like sanitizeTitle's cap).
 export const AgentRenameSchema = z.object({ id: z.string().min(1), title: z.string().trim().min(1).max(80) });
+// autoLand's input: this agent's own land-at-completion posture. `null` CLEARS the override back to "inherit
+// the sandbox setting" — the browser sends it whenever the user toggles back to what the global already says,
+// so agents don't accumulate frozen overrides that quietly stop following the global toggle.
+export const AgentAutoLandSchema = z.object({ id: z.string().min(1), autoLand: z.boolean().nullable() });
 export const AgentFileDiffQuerySchema = z.object({ id: z.string().min(1), repo: z.string().min(1), path: z.string().min(1) });
-// land's outcome: per-repo conflicts (dirty-main overlaps or merge conflicts); landed only when every repo
-// with changes merged cleanly. Conflicted repos keep their worktree state — nothing is lost.
+/* WHY a path would not land. The distinction is the whole difference between an actionable report and a dead
+ * end, because the three have nothing in common but their symptom:
+ *   `workspace` — you have uncommitted edits on that path. Yours is the copy at risk; commit or stash it.
+ *   `diverged`  — the main tree's COMMITTED content moved under the agent since it branched. Nothing of
+ *                 yours is at risk; the agent's delta is simply written against an older file.
+ *   `binary`    — git cannot three-way merge the file at all, so no automatic resolution exists.
+ * The old report named only the first, which is the rarest of the three. */
+export const LandConflictReasonSchema = z.enum(["workspace", "diverged", "binary"]);
+export type LandConflictReason = z.infer<typeof LandConflictReasonSchema>;
+export const LandConflictPathSchema = z.object({ path: z.string(), reason: LandConflictReasonSchema });
+
+/* land's outcome, per repo of the composition. `paths` is the set that genuinely failed to apply — NOT the
+ * whole delta, which is what the first version reported whenever it could not pin the cause down, turning
+ * four real conflicts into a wall of fourteen. `clean` counts what would land regardless, so the UI can say
+ * how much is being held back by how little, and offer to take it. An empty `paths` with `clean: 0` is the
+ * repo-unavailable case: the main checkout is gone, and no path-level account exists. */
+export const LandConflictSchema = z.object({
+    repo: z.string(),
+    paths: z.array(LandConflictPathSchema),
+    clean: z.number(),
+});
+export type LandConflict = z.infer<typeof LandConflictSchema>;
+
+// land's outcome; landed only when every repo with changes applied cleanly. Conflicted repos keep their
+// worktree state — nothing is lost, and "Land now" stays available. `resolving` is populated only by a
+// `merge` land: the paths written into the workspace carrying conflict markers, which the user finishes by
+// hand in their own editor exactly as they would any merge.
 export const LandResultSchema = z.object({
     landed: z.boolean(),
-    conflicts: z.array(z.object({ repo: z.string(), paths: z.array(z.string()) })).optional(),
+    conflicts: z.array(LandConflictSchema).optional(),
+    resolving: z.array(z.object({ repo: z.string(), paths: z.array(z.string()) })).optional(),
+    // A `measure` outcome with an outstanding delta: nothing was applied and nothing failed — the work is
+    // waiting on the branch for a deliberate Land. `landed: false` alone can't say that (it means refusal).
+    held: z.boolean().optional(),
 });
 export type LandResult = z.infer<typeof LandResultSchema>;
 
+/* land's input. `check` is the safe default and the historical behaviour: the delta is applied only if ALL of
+ * it applies, so a refusal leaves the workspace byte-identical. `merge` is the escape hatch the conflict
+ * report offers — a three-way apply that lands every clean path and leaves the rest with conflict markers to
+ * resolve in place. It is opt-in because it WRITES on failure, which is the one thing `check` promises not
+ * to do. `measure` is the auto-land-off mode: everything a land does EXCEPT touching the main tree — the
+ * provenance commit onto agent/<id>, the cumulative diffstat, and the bookkeeping for work that reached the
+ * main line by another road — so a held agent's card stays as current as a landed one's while its delta waits
+ * on the branch for a deliberate Land. */
+export const LandModeSchema = z.enum(["check", "merge", "measure"]);
+export type LandMode = z.infer<typeof LandModeSchema>;
+export const AgentLandSchema = z.object({ id: z.string().min(1), mode: LandModeSchema.optional() });
+
 // ---- routed-provider subscriptions ----
 
 // The providers whose model can run UNDER the Claude Code harness through the bundled translator (CLIProxyAPI),
@@ -269,9 +360,19 @@ export type LandResult = z.infer<typeof LandResultSchema>;
 export const KeyedProviderSchema = z.enum(["codex", "grok", "gemini"]);
 export type KeyedProvider = z.infer<typeof KeyedProviderSchema>;
 
-// Which routed-provider subscriptions are connected in the translator (per provider). Drives the
-// "connected / connect subscription" state in Sandbox ▸ Agent.
-export const TranslatorAccountsSchema = z.object({ codex: z.boolean(), grok: z.boolean(), gemini: z.boolean() });
+// One connected subscription in the translator. `name` is CLIProxyAPI's auth-file name — the stable store key a
+// disconnect addresses — and `label` the sign-in identity it reported (the account email, else the file name).
+export const TranslatorAccountSchema = z.object({ name: z.string(), label: z.string() });
+export type TranslatorAccount = z.infer<typeof TranslatorAccountSchema>;
+// Which routed-provider subscriptions are connected in the translator, per provider — a LIST per provider, not
+// a flag: CLIProxyAPI holds any number of auth files per provider side by side and balances requests across
+// them, so connecting a second ChatGPT or Google account is more headroom, and each is disconnectable on its
+// own. Drives the account rows in Sandbox ▸ Agent.
+export const TranslatorAccountsSchema = z.object({
+    codex: z.array(TranslatorAccountSchema),
+    grok: z.array(TranslatorAccountSchema),
+    gemini: z.array(TranslatorAccountSchema),
+});
 export type TranslatorAccounts = z.infer<typeof TranslatorAccountsSchema>;
 
 // The side-channel body that un-parks a turn waiting on the user. Every interactive card — plan approval,
@@ -328,6 +429,12 @@ export const SteerSchema = z
 // True cancel for the conversation's in-flight turn — aborts the agent daemon-side, unlike closing the
 // /agent fetch (which sends no cancel frame).
 export const StopTurnSchema = z.object({ conversationId: z.string().min(1) });
+// Fire the conversation's remembered usage-limit resume NOW instead of waiting out the reset. `account`
+// points the re-run at a different connected account of the same provider — the "resume on another account"
+// action a spent allowance offers when the sandbox holds more than one; omitted, the turn re-runs on
+// whatever served it (a plain "try again now"). NOT_FOUND when nothing is pending (the failure was already
+// superseded by a fresh turn, or the daemon restarted).
+export const ResumeLimitSchema = z.object({ conversationId: z.string().min(1), account: z.string().min(1).optional() });
 
 // ---- claude subscription usage ----
 // The GATE signal: whether the provider is letting turns through right now, and — when it is refusing — which
@@ -381,6 +488,14 @@ export type AccountUsage = z.infer<typeof AccountUsageSchema>;
 export const OauthAccountSchema = z.object({
     id: z.string(),
     label: z.string(),
+    // WHO this account signs in as, in the provider's own words — Anthropic returns the email and the
+    // organization alongside the tokens, so a connection can name itself instead of arriving as a second row
+    // called "Claude". Kept BESIDE `label` rather than folded into it: the label is the user's to rename, and a
+    // renamed account still has to be able to say whose it is. Absent when the provider tells us nothing (a
+    // pasted API key carries no identity) — which is exactly when renaming is the only answer, so every
+    // sandbox-owned account can be renamed.
+    email: z.string().optional(),
+    organization: z.string().optional(),
     scope: z.string().optional(),
     connectedAt: z.number(), // epoch ms
     // Set only when the account's stored credential can no longer be refreshed (revoked/expired refresh token)
@@ -397,6 +512,10 @@ export type OauthAccount = z.infer<typeof OauthAccountSchema>;
 export const OauthAccountListSchema = z.object({ accounts: z.array(OauthAccountSchema) });
 // Address one account of a provider (disconnect, and the turn's `account`).
 export const AccountIdSchema = z.object({ id: z.string().min(1) });
+// Rename one account of a provider whose credential the sandbox owns (Claude, Kimi). Blank ⇒ the daemon falls
+// back to the derived name, so clearing a label restores the sign-in identity rather than leaving a nameless
+// row. Grok is absent for the same reason it holds one account: OpenCode owns that credential, not this store.
+export const AccountRenameSchema = z.object({ id: z.string().min(1), label: z.string().max(80) });
 // The completing calls carry the user-chosen label (blank ⇒ the daemon derives one from the sign-in identity
 // or a provider default).
 export const OauthExchangeSchema = z.object({
@@ -464,10 +583,29 @@ export const ModelsSchema = z.object({ models: z.array(ModelSchema), default: z.
 // ---- sessions ----
 
 export const SessionIdParamSchema = z.object({ id: z.string() });
-export const SessionSummarySchema = z.object({ id: z.string(), title: z.string(), updatedAt: z.number() });
+export const SessionSummarySchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    updatedAt: z.number(),
+    // Why a searched session matched: the line of the USER's own prompt the query hit, windowed around it.
+    // Absent on an unfiltered list, and on a match the title already shows — a snippet repeating the row's
+    // own heading is noise, not evidence. See AgentMatchSchema for the same field on the fleet's side.
+    snippet: z.string().optional(),
+});
 export const SessionsListSchema = z.object({ sessions: z.array(SessionSummarySchema) });
 
 // ---- settings: per-sandbox agent settings (.intentic/settings.json) ----
+
+// Which prompt the agent is, before this turn composes anything on top. Two built-in bases and an escape
+// hatch: Intentic's own (the default), Claude Code's preset, or the owner's text. Declared out here rather
+// than inline in the settings object because both sides of the wire branch on it — the daemon to build the
+// turn, the browser to decide which base it can show you.
+export const SystemPromptModeSchema = z.enum(["intentic", "claude", "custom"]);
+export type SystemPromptMode = z.infer<typeof SystemPromptModeSchema>;
+// The two bases a user can READ and fork — "custom" is excluded because there is nothing to fetch: it is
+// whatever they have already typed into the settings field.
+export const BuiltinPromptSchema = z.object({ base: z.enum(["intentic", "claude"]) });
+
 // Small user-owned config the /settings routes edit and streamAgent reads — all opt-in booleans the owner
 // toggles in the UI (so each can be A/B benchmarked):
 //   stableSystemPrompt — keeps the system prompt byte-stable across turns (the delegation note rides the user
@@ -480,6 +618,9 @@ export const SessionsListSchema = z.object({ sessions: z.array(SessionSummarySch
 //                        guard + fewer output tokens); off ⇒ the native file tools.
 //   terseOutput       — appends a concise-response steer to the end of the system prompt (a stable suffix, so it
 //                        composes with stableSystemPrompt) to cut the model's OWN output tokens.
+//   systemPromptMode  — which base the agent's prompt is: "intentic" (default), "claude", or "custom".
+//   systemPrompt      — the owner's own prompt text, used only by "custom" mode, where it is the ENTIRE system
+//                        prompt and nothing the daemon would otherwise append rides with it — see its own note.
 //   iqSearch          — loads the image-baked iq Claude Code plugin (skill + SessionStart nudge) so the agent
 //                        prefers the iq CLI over grep/find/Glob; off ⇒ plugin not loaded, native search tools
 //                        only. Opt-in (default off); the browser Search box uses iq regardless.
@@ -490,7 +631,7 @@ export const SessionsListSchema = z.object({ sessions: z.array(SessionSummarySch
 //                        (recorded raw as `heldOut`), so the savings report compares a real cleaned-vs-raw
 //                        population instead of an estimate. 0 = no holdout (default).
 //   filterBackend     — which cleaner runs the compression: "native" (agent-output-filter, default) or "rtk"
-//                        (the rtk binary from its installed extension, rewritten at the PreToolUse hook) — an
+//                        (the image-baked rtk binary, rewritten at the PreToolUse hook) — an
 //                        A/B backend switch, so native and rtk can be benchmarked head-to-head.
 // The booleans default off, skills defaults [] (no skill loaded), outputCleaners defaults "off" (cleaning off),
 // outputHoldout 0, filterBackend "native" — a fresh sandbox starts with cleaning and iq off until the owner enables them.
@@ -507,33 +648,167 @@ export const SandboxSettingsSchema = z.object({
     skills: z.array(z.string()).default([]),
     hashlineEdits: z.boolean().default(false),
     terseOutput: z.boolean().default(false),
+    /* Measurement control for the terse steer, at TURN level — the same trick `outputHoldout` plays over
+     * commands, one layer up. A fraction [0,1] of otherwise-eligible turns run WITHOUT the steer and record
+     * which arm they ran on (UsageTurn.terse), so the savings report can compare two real populations.
+     *
+     * It has to be an experiment: unlike a cleaned command, which yields its own raw baseline in the same
+     * event, a turn cannot be re-run to see what it would have said unsteered. 0 ⇒ no measurement (every
+     * eligible turn is steered), which is the default because the control costs the very tokens it measures. */
+    terseHoldout: z.number().min(0).max(1).default(0),
+    /* WHICH SYSTEM PROMPT THE AGENT RUNS ON — the base, before anything this turn composes.
+     *
+     *   intentic — Intentic's own prompt, tuned for this harness (intentic-prompt.ts). The default.
+     *   claude   — Claude Code's preset, as shipped in the CLI this sandbox runs. Not a copy stored here, so
+     *              picking it tracks whatever the installed CLI's prompt is rather than freezing at a snapshot.
+     *   custom   — `systemPrompt` below, and nothing else at all.
+     *
+     * The first two are peers: both get the harness's own guidance appended (the AskUserQuestion/plan blocks
+     * the chat's cards need, the checklist guidance behind the todo panel, the browser-tool guidance), plus the
+     * delegation note and the terse steer. `custom` is the one that does not, by the owner's explicit choice —
+     * see the field below. */
+    systemPromptMode: SystemPromptModeSchema.default("intentic"),
+    /* The owner's own prompt, used only when `systemPromptMode` is "custom". Then it is the ENTIRE system
+     * prompt: both built-in bases are gone and so is everything the daemon would otherwise append — the widget
+     * guidance the chat's cards are driven by, and the terse-output steer (whose toggle goes inert). That is
+     * the price of total control, and the UI states it at the moment of the edit rather than letting the
+     * widgets go quietly dark. Only the cross-provider delegation note survives, because it has a home outside
+     * the system prompt already (the user-message preamble stableSystemPrompt puts it in).
+     *
+     * Cap is roomy — the bases it stands in for are ~6.8k characters — but finite, because every turn pays it. */
+    systemPrompt: z.string().max(20000).default(""),
     iqSearch: z.boolean().default(false),
     outputCleaners: z.string().default("off"),
     outputHoldout: z.number().min(0).max(1).default(0),
     filterBackend: z.enum(["native", "rtk"]).default("native"),
+    /* The model behind the one-click helpers that are not a conversation — today the commit box's autofill.
+     * `${provider}:${modelId}`, or EMPTY for Auto, which is the default and the interesting case: Auto is
+     * resolved from whatever accounts are connected at the moment it is read (resolveQuickModel), so it can
+     * never name a provider this sandbox has no credential for and it improves by itself when one is added.
+     * Storing a resolved id here instead would go stale exactly like a pinned model does. */
+    quickModel: z.string().default(""),
     // How long a finished agent stays on the board before it is archived automatically (days; 0 ⇒ never).
     // Unlike every other flag here this one defaults ON, because the lane it governs is the board's only
     // terminal state: without a sweep the Finished lane grows for the life of the sandbox, and each card it
     // holds is a live worktree checkout, not just a row.
     agentRetentionDays: z.number().min(0).max(365).default(3),
+    /* Land a clean turn's delta into the main tree automatically at completion — the Claude Code review model,
+     * and the historical behaviour, so it defaults ON (flipping the default would silently change every
+     * existing sandbox). OFF holds finished work on the agent's branch instead: the card reads "Ready to
+     * land" and the user lands it deliberately, from the review panel or the card. Sandbox-wide because
+     * automation-opened agents (Discord, webhooks, email) finish turns with no browser in the room — a
+     * browser-held preference could not govern them. Per-agent override: AgentSummarySchema.autoLand. */
+    autoLand: z.boolean().default(true),
+    // When a turn dies on the Claude subscription's usage limit, re-run it automatically once the limit
+    // window resets (a minute after, so a skewed clock can't retry into the same closed window). Off by
+    // default: an unattended retry spends the fresh window without the user in the room, so the daemon
+    // records every limit-hit either way and the chat OFFERS the toggle at the moment it would have helped —
+    // enabling it then still resumes the turn that just bounced.
+    autoResumeOnLimit: z.boolean().default(false),
+    /* When a turn dies because the MODEL PROVIDER was failing (500/502/503, a 529 at capacity, a dropped
+     * socket), re-run it on an escalating backoff until it goes through or the attempts are spent.
+     *
+     * Defaults ON, unlike autoResumeOnLimit, and the difference is not an inconsistency: a spent allowance is
+     * the user's own budget, and resuming into a fresh window spends something they may have been saving. An
+     * outage resume spends nothing the dead turn had not already committed, resolves in minutes rather than
+     * hours, and — the deciding argument — the turns hurt worst by it are the ones with nobody in the room
+     * (automation wakes, Discord, webhooks), which no browser-held preference could ever rescue. It is the same
+     * reasoning that leaves the auth resume ungated: this is the provider's failure, not the user's decision. */
+    resumeAfterOutage: z.boolean().default(true),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
 
-// ---- output-cleaner savings report (rtk-`gain`-style) ----
-// Aggregated from historyRoot/logs/filter-stats.jsonl (one row per agent Bash command). `perCleaner` attributes
-// which cleaner ids fired across commands; `holdout` is the measured control (commands the holdout bypassed) vs
-// the cleaned population — a real saved-% rather than an estimate; `gaps` are high-volume commands that matched
-// no cleaner (the next handler to write). Empty/zeroed when no commands have run yet.
-export const CleanerSavingsSchema = z.object({
+// One of the two built-in bases, as text: Intentic's own prompt, or Claude Code's preset read out of the CLI
+// this sandbox runs (preset-prompt.ts captures it rather than storing a transcription). What the settings page
+// shows behind "View" and drops into the editor behind "Edit a copy".
+//
+// `version` is the CLI build a captured preset came from, so the UI can say WHICH text the user is looking at:
+// a custom prompt forked from an older build is a snapshot, and the version is the only honest way to tell.
+// Empty for Intentic's prompt, which ships with the app and has no version of its own to report.
+export const BuiltinPromptTextSchema = z.object({ text: z.string(), version: z.string() });
+export type BuiltinPromptText = z.infer<typeof BuiltinPromptTextSchema>;
+
+/* ---- savings report: what each token-reduction mechanism actually saved ----
+ *
+ * TWO FAMILIES, deliberately never one list of bars. They are measured differently, and a chart that ranks
+ * them side by side claims a confidence and a denominator that only one of them has:
+ *
+ *   input  — shell output the cleaners trimmed before the model ever saw it. Both sides of the comparison come
+ *            off the SAME command (raw in, emitted out), so the counterfactual is observed rather than
+ *            estimated: exact, per command, no sample size to argue about.
+ *   output — the model's own tokens under the terse steer. There is no second run of the same turn to compare
+ *            against, so the only honest number is an experiment: a turn-level holdout, an n per arm, and a
+ *            margin. It is absent entirely until both arms are large enough for the delta to mean anything.
+ *
+ * The two are also in different units of value — a saved tool-output token is saved again on every later
+ * request of that conversation, an output token is saved once but costs several times as much — which is the
+ * other reason they are separate sections with separate totals rather than one number.
+ */
+
+// One mechanism's realized saving, biggest first. `savedTokens` is what THIS stage removed from what reached
+// it in pipeline order — sequential attribution, which is why the stages sum exactly to raw − emitted and can
+// be drawn as one stacked bar. It is NOT "what turning this cleaner off would cost you": the cap downstream
+// would have eaten some of the same lines. `commands` is how many commands the stage ran on. Negative for the
+// `footer` stage, which adds the retrieval pointer back — a cost on the same ledger as what it bought.
+export const SavingsStageSchema = z.object({ id: z.string(), commands: z.number(), savedTokens: z.number() });
+
+// Whichever cleaner is ACTUALLY compressing output owns these numbers, so they are read from that backend's
+// own ledger: "native" aggregates historyRoot/logs/filter-stats.jsonl (one row per agent Bash command, written
+// by agent-output-filter), "rtk" reads rtk's own gain ledger. Reading one ledger regardless of backend is how
+// this card went stale: under rtk the native filter is switched off, nothing appends, and the last numbers
+// written — a test run's, as it happened — sat on the card looking live.
+export const InputSavingsSchema = z.object({
+    // Which backend's ledger these numbers came from — shown on the card, because a number without its source
+    // cannot be told apart from a stale one. Defaulted for the same daemon-older-than-browser seam as settings.
+    source: z.enum(["native", "rtk"]).default("native"),
+    // False ⇒ these totals cover the ledger's whole life, not the range the reader selected: `rtk gain` reports
+    // no timestamps, so its numbers cannot be windowed and the screen has to say so rather than let a 7-day
+    // filter sit above an all-time figure.
+    windowed: z.boolean(),
+    // When that ledger last recorded a command (epoch ms), so the card can show its age instead of implying
+    // freshness it doesn't have. Absent when the ledger has never been written or its age can't be read.
+    updatedAt: z.number().optional(),
     commands: z.number(),
     rawTokens: z.number(),
     emittedTokens: z.number(),
     savedPct: z.number(),
-    perCleaner: z.array(z.object({ id: z.string(), commands: z.number() })),
+    // Per-stage attribution, biggest first. Native-only: rtk reports totals, not which of its handlers fired.
+    perCleaner: z.array(SavingsStageSchema),
+    // The measured control — commands the holdout left raw — against the cleaned population. A real saved-%
+    // for the pipeline as a whole rather than an estimate, and the only whole-pipeline counterfactual there is.
     holdout: z.object({ cleaned: z.number(), heldOut: z.number(), measuredSavedPct: z.number().optional() }),
+    // High-volume commands that matched no cleaner: where the next handler is worth writing. Native-only.
     gaps: z.array(z.object({ command: z.string(), tokens: z.number() })),
 });
-export type CleanerSavings = z.infer<typeof CleanerSavingsSchema>;
+export type InputSavings = z.infer<typeof InputSavingsSchema>;
+
+// One arm of the turn-level experiment: the turns that ran with the steer, and the turns the holdout ran
+// without it. Mean output tokens PER TURN, because the arms never hold the same number of turns.
+export const SavingsArmSchema = z.object({ turns: z.number(), meanOutputTokens: z.number() });
+
+// The terse steer, as measured. Only turns where the steer was ELIGIBLE are counted — a turn under a custom
+// system prompt drops the steer along with everything else the daemon appends, so it belongs to neither arm.
+export const OutputSavingsSchema = z.object({
+    on: SavingsArmSchema,
+    off: SavingsArmSchema,
+    // Turns per arm before a delta is reported at all. Carried on the wire so the screen's "measuring…" state
+    // counts toward the daemon's real threshold instead of a number the browser guessed.
+    minTurns: z.number(),
+    /* The three below are present TOGETHER, and only once both arms clear `minTurns` — a schema that can't
+     * express a half-measured experiment is how a 34%-that-becomes-8%-tomorrow never reaches the screen.
+     *   deltaPct   — change in mean output tokens per turn under the steer; negative is a saving.
+     *   marginPct  — ± percentage points, 95% (Welch, unequal variances and unequal arms).
+     *   savedTokens — what the delta is worth over the turns that actually ran with the steer, in this window. */
+    deltaPct: z.number().optional(),
+    marginPct: z.number().optional(),
+    savedTokens: z.number().optional(),
+});
+export type OutputSavings = z.infer<typeof OutputSavingsSchema>;
+
+// `output` is absent when the experiment isn't running at all (terse off, or no holdout set) — a section that
+// isn't there reads as "not measured", which is the truth, while zeros would read as "measured, worth nothing".
+export const SavingsReportSchema = z.object({ input: InputSavingsSchema, output: OutputSavingsSchema.optional() });
+export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 
 // ---- intentic CLI ----
 
@@ -579,6 +854,24 @@ export const GitStatusSchema = z.object({ branch: z.string(), dirty: z.boolean()
 export const GitFilesSchema = z.object({ files: z.array(z.string()) });
 export const GitFileSchema = z.object({ path: z.string(), content: z.string() });
 export const CommitResultSchema = z.object({ committed: z.boolean() });
+
+/* AI-drafted commit message. Workspace-wide, not per repo, because the commit box's target IS a set of repos
+ * sharing one message — so the draft has to see every one of their diffs to describe what the commit actually
+ * records. `repos` and `all` mirror the panel's own commit target exactly: `all` reads the WORKTREE (what
+ * "Commit all" would sweep), absent reads the INDEX (what a bare commit records). Getting that wrong would
+ * describe changes the commit isn't going to contain. */
+export const CommitMessageDraftSchema = z.object({
+    repos: z.array(z.string().min(1)).min(1).max(50),
+    all: z.boolean().optional(),
+});
+// The draft plus WHICH model wrote it, so the surface can name it rather than claiming an anonymous "AI" —
+// that name is also the only place the resolved quick model is visible before anyone opens settings.
+export const CommitMessageSchema = z.object({
+    message: z.string(),
+    provider: z.string(),
+    model: z.string(),
+});
+export type CommitMessageDraft = z.infer<typeof CommitMessageSchema>;
 // One change to a file — an uncommitted working-tree change (status vs HEAD, untracked included), an agent
 // worktree's delta vs its base, or a file in a commit. `additions`/`deletions` are the numstat line counts,
 // undefined for a binary file (git reports "-"/"-") or an untracked file (no HEAD blob to diff against).
@@ -658,6 +951,11 @@ export const RepoChangesSchema = z.object({
     // additions/deletions describe the diff it is listed under, never a conflation of the two.
     staged: z.array(GitChangeSchema),
     unstaged: z.array(GitChangeSchema),
+    // How many changes were CUT from the two sides above (conflicts are never cut). A cloned monorepo or a
+    // mass delete carries six-figure change lists — a payload no panel can render and no browser should hold —
+    // so past the daemon's per-repo budget the lists arrive truncated and this carries the dropped count, which
+    // the panel adds to its badges and states under the group. Absent ⇒ the lists are complete.
+    truncated: z.number().optional(),
     // Where this repo stands against its remote; `ahead`/`behind` are 0 with no remote or no upstream.
     remote: GitRemoteStateSchema.optional(),
     // WHICH AGENT PUT IT THERE: repo-relative path → the agent ids that landed it, newest land first. Keyed by
@@ -665,7 +963,7 @@ export const RepoChangesSchema = z.object({
     // edited again) and its origin is the same fact for both. Only agents can appear here — a main-tree turn,
     // a terminal edit and your own typing never pass through land, so they are simply absent (see
     // agents/origins.ts), which is why the panel badges an agent and says nothing at all for anyone else.
-    // Ids, not titles: every client already mirrors the fleet registry and can resolve one to the other.
+    // Ids, not titles: the identity for every id named here rides the response once, in `originAgents`.
     origins: z.record(z.string(), z.array(z.string())).optional(),
     // Why the repo could not be scanned at all, condensed to git's own one-line reason ("fatal: bad object HEAD").
     // A repo left torn by a canceled or failed upload used to be dropped from the response entirely, so it just
@@ -673,9 +971,31 @@ export const RepoChangesSchema = z.object({
     error: z.string().optional(),
 });
 export type RepoChanges = z.infer<typeof RepoChangesSchema>;
+
+// WHO AN ORIGIN ID IS — the display identity of one agent named in `origins`, carried BY THE RESPONSE rather
+// than looked up in the client's fleet roster. The roster is the LIVE board and deliberately drops archived
+// agents (AgentsRegistry.list), while a landing outlives the agent that made it: archiving a finished agent
+// does not commit its lines, so the very common case — land, archive the card, review at leisure — is exactly
+// the one a roster lookup cannot answer, and the panel fell back to "Agent 1a2b3c" with a generic icon for it.
+// The daemon reads attribution and identity from the same registry in the same pass, so it is the one place
+// they cannot disagree. Per response, not per repo: one agent commonly lands into several.
+export const OriginAgentSchema = z.object({
+    // Absent for an entry that never got a title (a turn that failed before one was derived).
+    title: z.string().optional(),
+    provider: AgentProviderSchema,
+});
+export type OriginAgent = z.infer<typeof OriginAgentSchema>;
+
 // The aggregated review set across every repo (root + every discovered repo); a repo appears when it has changes,
 // when it is out of sync with its remote, or when it failed to scan.
-export const GitChangesSchema = z.object({ repos: z.array(RepoChangesSchema) });
+export const GitChangesSchema = z.object({
+    repos: z.array(RepoChangesSchema),
+    // Keyed by agent id; covers every id any repo's `origins` names, and only those. Absent when nothing in
+    // the review is attributable. An id can still be missing from it — the retention sweep can retire an
+    // entry whose landed lines are somehow still uncommitted — and the panel keeps its id-shaped fallback for
+    // exactly that, rather than dropping the chip and re-attributing the file to the user.
+    originAgents: z.record(z.string(), OriginAgentSchema).optional(),
+});
 export type GitChanges = z.infer<typeof GitChangesSchema>;
 
 // One file an agent touched, plus whether that change is ALREADY in the main tree. The review lists the
@@ -696,7 +1016,15 @@ export const AgentRepoChangesSchema = z.object({
     changes: z.array(AgentChangeSchema),
 });
 export type AgentRepoChanges = z.infer<typeof AgentRepoChangesSchema>;
-export const AgentChangesSchema = z.object({ repos: z.array(AgentRepoChangesSchema) });
+/* The review, plus WHY the last land refused — because a conflict is discovered by the daemon (a clean turn
+ * auto-lands the moment it finishes) and acted on in the browser, possibly hours later, on a surface the user
+ * reaches by clicking the card's "Resolve conflict". Carrying the report only in the land RESPONSE meant the
+ * one path that opens the review already knowing there is a conflict was the one path that could not show it:
+ * the panel opened with an empty report, no explanation, and no merge affordance — a dead end at the exact
+ * moment the UI had promised something to resolve. It rides the review because that is the surface that
+ * resolves it, and it refreshes with it: every land invalidates this query, so the report is never staler
+ * than the last attempt. */
+export const AgentChangesSchema = z.object({ repos: z.array(AgentRepoChangesSchema), conflicts: z.array(LandConflictSchema).optional() });
 export type AgentChanges = z.infer<typeof AgentChangesSchema>;
 
 // ---- git history graph (the "Git Graph" view over a repo's real commits) ----
@@ -802,11 +1130,11 @@ export const WorkspaceTreeEntrySchema = z.object({
     path: z.string(),
     type: z.enum(["file", "dir"]),
     size: z.number().optional(),
-    // Set on a dir whose child list was cut short by the entry cap — some of its items aren't in `children`.
-    truncated: z.boolean().optional(),
     // Ignored-by-tooling (node_modules, .git, .gitignore'd paths, browser profiles): the client grays the row.
-    // An ignored DIR is listed without `children` — the client lazy-loads it via /workspace/children on expand.
     ignored: z.boolean().optional(),
+    // A DIR without `children` was listed but not descended into — because it's ignored, or because the walk's
+    // breadth-first budget stopped above it. Either way the client lazy-loads it via /workspace/children on
+    // expand, so "not loaded yet" and "empty directory" (`children: []`) stay distinguishable.
     get children() {
         return z.array(WorkspaceTreeEntrySchema).optional();
     },
@@ -815,17 +1143,17 @@ export type WorkspaceTreeEntry = z.infer<typeof WorkspaceTreeEntrySchema>;
 export const WorkspaceTreeSchema = z.object({
     root: z.string(),
     tree: z.array(WorkspaceTreeEntrySchema),
-    // True when the root's own entries were cut by the entry cap (per-dir cuts are flagged on each dir entry).
-    truncated: z.boolean(),
+    // How many of the ROOT's own entries the budget cut (0 = complete); per-dir cuts are counted on each dir entry.
+    hidden: z.number(),
 });
 export type WorkspaceTree = z.infer<typeof WorkspaceTreeSchema>;
-// Lazy-load one directory's children — for an ignored dir the tree walk didn't descend into. Every returned entry
-// is itself `ignored` (it lives under an ignored subtree); child dirs again carry no `children`, so they lazy-load
-// on their own expand. `truncated` ⇒ the dir's child list was cut by the entry cap.
+// Lazy-load one directory's children — for a dir the tree walk listed but didn't descend into. Child dirs again
+// carry no `children`, so they lazy-load on their own expand. `hidden` = how many entries the cap cut (0 = all
+// listed).
 export const WorkspaceChildrenQuerySchema = z.object({ path: z.string().min(1) });
 export const WorkspaceChildrenSchema = z.object({
     entries: z.array(WorkspaceTreeEntrySchema),
-    truncated: z.boolean(),
+    hidden: z.number(),
 });
 export type WorkspaceChildren = z.infer<typeof WorkspaceChildrenSchema>;
 export const WorkspaceFileQuerySchema = z.object({ path: z.string().min(1) });
@@ -906,6 +1234,58 @@ export const WorkspaceSearchResultSchema = z.object({
 });
 export type WorkspaceSearchResult = z.infer<typeof WorkspaceSearchResultSchema>;
 
+// ---- codebase health: one repository's structure and risk, in numbers ----
+
+// The repo-level companion to the management panel and the git-history graph: what the same resident engine's
+// `hotspots` (churn × complexity) and `map` (PageRank over the import graph) verbs rank, as figures a panel can
+// plot instead of lines a terminal prints.
+//
+// Every field is a COUNT that can be recounted in the files themselves — commits, branch points, exported
+// symbols. Deliberately no composite "maintainability grade": those aren't comparable across projects and can't
+// be checked, and a repo-health surface that launders counts into a letter is worse than none.
+// How many hotspot files and key modules a report carries when the caller names no limit. A leaderboard, not an
+// inventory: past a screenful the ranking stops being the point, and the reader should be reading the files.
+export const HEALTH_LIMIT = 20;
+export const WorkspaceHealthQuerySchema = z.object({
+    // "root" (the /work repo) or a nested repo's root-relative dir — the same {repo} ids the git routes take.
+    repo: z.string().min(1),
+    // Churn window (2d, 12h, 1w, 3m). Absent = all of history, which is what a hotspot ranking wants by default.
+    since: z.string().max(16).optional(),
+    limit: z.coerce.number().int().positive().max(200).optional(),
+});
+// One file that is BOTH churning and tangled. `score` is the product the ranking sorts by — carried explicitly
+// so the panel plots the number it ranks by rather than recomputing it.
+export const WorkspaceHotspotSchema = z.object({
+    path: z.string(),
+    commits: z.number(),
+    adds: z.number(),
+    dels: z.number(),
+    complexity: z.number(),
+    score: z.number(),
+    // Epoch ms of the latest commit touching the file, within the window.
+    latestMs: z.number(),
+});
+export type WorkspaceHotspot = z.infer<typeof WorkspaceHotspotSchema>;
+// A file of the import graph's ranked skeleton — order IS the rank, so no rank number rides along.
+export const WorkspaceKeyModuleSchema = z.object({ path: z.string(), exports: z.number() });
+export type WorkspaceKeyModule = z.infer<typeof WorkspaceKeyModuleSchema>;
+export const WorkspaceHealthSchema = z.object({
+    repo: z.string(),
+    totals: z.object({
+        files: z.number(),
+        symbols: z.number(),
+        // Summed branch points across the scoped files.
+        complexity: z.number(),
+        // How many files qualify as hotspots at all — the lists below are capped, this is not.
+        hotspots: z.number(),
+    }),
+    hotspots: z.array(WorkspaceHotspotSchema),
+    modules: z.array(WorkspaceKeyModuleSchema),
+    // Same index-freshness signal the search route reports: a panel drawn off a half-built index says so.
+    freshness: WorkspaceSearchFreshnessSchema,
+});
+export type WorkspaceHealth = z.infer<typeof WorkspaceHealthSchema>;
+
 // ---- workspace setup (dependency readiness) ----
 
 // One project under /work and whether its dependencies are actually installed. A drop omits node_modules/.venv
@@ -981,12 +1361,13 @@ export const TemplatesListSchema = z.object({ templates: z.array(TemplateSummary
 export type TemplatesList = z.infer<typeof TemplatesListSchema>;
 
 // One app instance currently in a monorepo, with its own preview dev server + live status (started/stopped
-// from the apps extension). `app` is the user-chosen instance name (the _apps/ dir); `template` is the
-// manifest key it was created from (api/web/landing). previewUrl is
+// from the apps extension). `app` is the user-chosen instance name (the _apps/ dir); `kind` is what sort of
+// app it is — the manifest key it was scaffolded from (api/web/landing), else the framework detected from its
+// dependencies (astro/next/…), and absent when it was discovered purely by its `dev` script. previewUrl is
 // https://preview-<repo>--<app>-<sandboxId>.<zone> (absent on loopback — no zone or no connect token).
 export const RepoAppSchema = z.object({
     app: z.string(),
-    template: z.string(),
+    kind: z.string().optional(),
     previewUrl: z.string().optional(),
     running: z.boolean(),
     healthy: z.boolean(),
@@ -1534,7 +1915,9 @@ export const WorkspaceEventSchema = z.object({
     agentId: z.string(),
     title: z.string().optional(),
     branch: z.string(),
-    outcome: z.enum(["landed", "conflict", "idle", "error"]),
+    // `ready` is a clean turn whose delta was HELD on the branch (auto-land off) — for a chore, the moment
+    // before the user's deliberate Land, which is exactly when a pre-land review wants to run.
+    outcome: z.enum(["landed", "conflict", "ready", "idle", "error"]),
     repos: z.array(z.object({ repo: z.string(), from: z.string(), dir: z.string() })),
 });
 export type WorkspaceEvent = z.infer<typeof WorkspaceEventSchema>;
@@ -1681,13 +2064,15 @@ export const PanelSummarySchema = z.object({
     role: z.enum(["intent", "desired-state", "app"]).optional(),
     // Content facts: deploy.config.ts (the intent ledger's day-one marker), desired-state.json (present after
     // the first resolve), .intentic/ui/index.html (a sandboxed directory UI), pnpm-workspace.yaml +
-    // turbo.json (a pnpm+turbo monorepo), and vitest evidence (a root vitest.config.ts, or "vitest" in the
-    // root manifest / workspace catalog).
+    // turbo.json (a pnpm+turbo monorepo), vitest evidence (a root vitest.config.ts, or "vitest" in the
+    // root manifest / workspace catalog), and docs/user-stories (a directory of stories an agent can test
+    // against the running app — the one fact here that says nothing about the repo's language).
     deployConfig: z.boolean(),
     desiredState: z.boolean(),
     directoryUi: z.boolean(),
     monorepo: z.boolean(),
     vitest: z.boolean(),
+    userStories: z.boolean(),
 });
 export type PanelSummary = z.infer<typeof PanelSummarySchema>;
 export const PanelsListSchema = z.object({ panels: z.array(PanelSummarySchema) });
@@ -1750,11 +2135,19 @@ export type PortForwardResult = z.infer<typeof PortForwardResultSchema>;
 // declared process carries extensionId+processName, the address for its /extensions start/stop routes. The
 // `{name}` kill-route param is a bare string validated in the handler (a bad name is a BAD_REQUEST) since the
 // same charset gates a `tmux kill-session -t` shell-out.
+//
+// `activityAt` (epoch ms of the session's last output) and `exitCode` (the LAST window's exit status, absent
+// while that pane still lives) are what let a finished session be READ rather than merely listed: the panel's
+// Recent-terminals popover orders by the one and reports the other ("exit 1 · 1h ago"), and the daemon's
+// retention sweep ages sessions out by the same clock. 0 is "tmux didn't say" — treated as unknown by both,
+// never as 1970.
 export const TerminalSessionSchema = z.object({
     name: z.string(),
     label: z.string().optional(),
     kind: z.enum(["shell", "panel", "agent", "job", "process"]),
     running: z.boolean(),
+    activityAt: z.number(),
+    exitCode: z.number().optional(),
     extensionId: z.string().optional(),
     processName: z.string().optional(),
 });
@@ -1833,6 +2226,12 @@ export const InfoSchema = z.object({
     updateAvailable: z.boolean().optional(),
 });
 
+// A daemon-minted session (system.session): the steady-state browser credential, exchanged for a verified
+// Google ID token so Google UI is a sign-in moment instead of an hourly renewal. `expiresAt` is epoch ms —
+// the browser renews ahead of it without parsing the token; `email` is who the daemon verified.
+export const DaemonSessionSchema = z.object({ token: z.string(), expiresAt: z.number(), email: z.string() });
+export type DaemonSession = z.infer<typeof DaemonSessionSchema>;
+
 // Intentic-provided host SSH tunnel: minting it needs intentic's PLATFORM Cloudflare account, so the daemon
 // can't do it directly — it relays to the platform authenticated by the connect token (the announce pattern).
 // The panel embeds the returned connector token + hostname in its connect-host one-liner.
@@ -1932,6 +2331,14 @@ export const UsageTurnSchema = z.object({
     cacheCreationTokens: z.number(),
     costUsd: z.number(),
     durationMs: z.number(),
+    /* Which arm of the terse experiment this turn ran on (settings.terseHoldout) — the only record of it, and
+     * the reason the savings report can say what the steer is worth instead of guessing.
+     *
+     * ABSENT means "not part of the experiment", not "off": a turn under a custom system prompt drops the
+     * steer along with everything else the daemon appends, and a turn run with the experiment switched off has
+     * no control to be compared against. Pooling those into the off-arm would compare steered turns against a
+     * population selected by something other than the coin flip, which is not a control at all. */
+    terse: z.boolean().optional(),
 });
 export type UsageTurn = z.infer<typeof UsageTurnSchema>;
 
@@ -1959,12 +2366,14 @@ export const UsageRollupRowSchema = z.object({
     durationMs: z.number(),
 });
 export type UsageRollupRow = z.infer<typeof UsageRollupRowSchema>;
-// Inclusive UTC day bounds (YYYY-MM-DD). Both absent ⇒ the whole ledger.
-export const UsageRollupQuerySchema = z.object({
+// Inclusive UTC day bounds (YYYY-MM-DD). Both absent ⇒ the whole ledger. Shared by every windowed read of a
+// daemon ledger (spend, savings): one window shape, so a screen that filters two ledgers at once filters them
+// with the same calendar.
+export const DayWindowQuerySchema = z.object({
     from: z.string().optional(),
     to: z.string().optional(),
 });
-export type UsageRollupQuery = z.infer<typeof UsageRollupQuerySchema>;
+export type DayWindowQuery = z.infer<typeof DayWindowQuerySchema>;
 export const UsageRollupSchema = z.object({ rows: z.array(UsageRollupRowSchema) });
 
 // ---- usage: per-account token/cost totals ----
@@ -2013,6 +2422,45 @@ export const LogReadSchema = z.object({
 });
 export type LogRead = z.infer<typeof LogReadSchema>;
 
+// ---- memory: the agent's persistent memory notes (.intentic/claude/projects/<project>/memory) ----
+// The markdown files the agent curates across sessions — MEMORY.md (the index) plus one file per fact. They
+// live under the workspace's .intentic/claude control plane (symlinked from ~/.claude/projects), which the
+// generic /workspace file API deliberately refuses (session transcripts and provider state share that tree),
+// so these purpose-built routes are the only browser surface — scoped to the memory dirs and nothing else.
+
+export const MemoryFileEntrySchema = z.object({
+    // The project slug the memory belongs to (one dir per agent cwd, e.g. "-history-gits-root").
+    project: z.string(),
+    // Path relative to that project's memory dir, e.g. "MEMORY.md" or "team-conventions.md".
+    name: z.string(),
+    sizeBytes: z.number(),
+    // Epoch ms mtime.
+    modifiedAt: z.number(),
+});
+export type MemoryFileEntry = z.infer<typeof MemoryFileEntrySchema>;
+export const MemoryListSchema = z.object({ files: z.array(MemoryFileEntrySchema) });
+
+// `project` + `name` ride the query (names may contain slashes, which don't fit a path segment).
+export const MemoryFileQuerySchema = z.object({
+    project: z.string().min(1),
+    name: z.string().min(1),
+});
+export const MemoryFileSchema = z.object({
+    project: z.string(),
+    name: z.string(),
+    content: z.string(),
+    sizeBytes: z.number(),
+    modifiedAt: z.number(),
+});
+export type MemoryFile = z.infer<typeof MemoryFileSchema>;
+
+// Memory notes are small by construction (one fact per file); the cap guards the route, not real usage.
+export const MemoryWriteSchema = z.object({
+    project: z.string().min(1),
+    name: z.string().min(1),
+    content: z.string().max(1_048_576),
+});
+
 // A tab's self-report of what it is looking at, keyed by its /events connection's clientId. Full replace,
 // not a merge — an absent field means "cleared", so a tab leaving a file drops the path with the same report.
 export const PresenceReportSchema = z.object({
@@ -2044,7 +2492,10 @@ export type PushSubscription = z.infer<typeof PushSubscriptionSchema>;
 
 // What the service worker renders. `url` is the in-app route the notification opens (the click handler
 // focuses an existing tab there rather than spawning a new one); `tag` collapses repeats — a second
-// "waiting on you" for the same conversation REPLACES the first instead of stacking.
+// "waiting on you" for the same conversation REPLACES the first instead of stacking. Push payloads are
+// capped by the push services themselves (~4KB after encryption), which is why nothing here carries a
+// transcript or a diff — the notification is a pointer back into the workspace, not a delivery mechanism
+// for content.
 export const PushNotificationSchema = z.object({
     title: z.string().min(1),
     body: z.string(),
@@ -2061,5 +2512,12 @@ export type PushNotification = z.infer<typeof PushNotificationSchema>;
 // granted permission with no server-side row would notify nothing).
 export const PushConfigSchema = z.object({ publicKey: z.string(), subscribed: z.boolean() });
 export const PushEndpointSchema = z.object({ endpoint: z.string().url() });
-// `endpoint` identifies which browser is asking, so `subscribed` can be answered for THIS one.
+// The optional `endpoint` says WHICH browser is asking; without it `subscribed` could only speak for the
+// sandbox as a whole, which is never the question the settings toggle needs answered.
 export const PushConfigQuerySchema = z.object({ endpoint: z.string().url().optional() });
+
+// What a test send actually achieved. `{ ok: true }` would be a lie the one place it matters most: the button
+// exists to prove a chain the user cannot inspect, so "the daemon accepted the request" is not the answer to
+// the question being asked. A count separates "your OS swallowed it" from "nothing was sent at all".
+export const PushTestSchema = z.object({ delivered: z.number().int().nonnegative() });
+export type PushTest = z.infer<typeof PushTestSchema>;