@intentic/sandbox-contract 1.152.0 → 1.154.0

package/src/events.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { AgentSummarySchema, PermissionModeSchema, RateLimitInfoSchema } from "./schemas.js";
+import { AgentProviderSchema, AgentSummarySchema, PermissionModeSchema, RateLimitInfoSchema } from "./schemas.js";
 
 // The wire shapes streamed from the daemon's event-iterator procedures. This is their canonical home: the
 // daemon yields them and the browser client consumes them from the same schema, so the two can't drift (they
@@ -41,8 +41,9 @@ export const PermissionAskSchema = z.object({
 });
 export type PermissionAsk = z.infer<typeof PermissionAskSchema>;
 
-// One provider-advertised slash command (an ACP agent's available_commands entry). `hint` is the argument
-// placeholder the popover shows after the name.
+// One provider-advertised slash command — an ACP agent's available_commands entry, or a Claude Code session's
+// supportedCommands() (its built-ins plus the workspace's own .claude/commands and any plugin/skill commands).
+// `hint` is the argument placeholder the popover shows after the name.
 export const AgentCommandSchema = z.object({
     name: z.string(),
     description: z.string(),
@@ -50,6 +51,10 @@ export const AgentCommandSchema = z.object({
 });
 export type AgentCommand = z.infer<typeof AgentCommandSchema>;
 
+// GET /agent/commands — which provider's last-published list to read; absent = claude, matching AgentTurn.
+export const AgentCommandsQuerySchema = z.object({ agent: AgentProviderSchema.optional() });
+export const AgentCommandsSchema = z.object({ commands: z.array(AgentCommandSchema) });
+
 // One TodoWrite/Task checklist item, surfaced live so the UI shows the agent's plan-of-work (Claude Code style).
 export const TodoItemSchema = z.object({
     content: z.string(),

package/src/index.ts

@@ -17,11 +17,13 @@ import { kimiContract } from "./contracts/kimi.contract.js";
 import { logsContract } from "./contracts/logs.contract.js";
 import { panelsContract } from "./contracts/panels.contract.js";
 import { portsContract } from "./contracts/ports.contract.js";
+import { pushContract } from "./contracts/push.contract.js";
 import { secretsContract } from "./contracts/secrets.contract.js";
 import { sessionsContract } from "./contracts/sessions.contract.js";
 import { settingsContract } from "./contracts/settings.contract.js";
 import { systemContract } from "./contracts/system.contract.js";
 import { translatorContract } from "./contracts/translator.contract.js";
+import { usageContract } from "./contracts/usage.contract.js";
 import { vpnContract } from "./contracts/vpn.contract.js";
 import { workspaceContract } from "./contracts/workspace.contract.js";
 
@@ -44,11 +46,13 @@ export { kimiContract } from "./contracts/kimi.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
 export { panelsContract } from "./contracts/panels.contract.js";
 export { portsContract } from "./contracts/ports.contract.js";
+export { pushContract } from "./contracts/push.contract.js";
 export { secretsContract } from "./contracts/secrets.contract.js";
 export { sessionsContract } from "./contracts/sessions.contract.js";
 export { settingsContract } from "./contracts/settings.contract.js";
 export { systemContract } from "./contracts/system.contract.js";
 export { translatorContract } from "./contracts/translator.contract.js";
+export { usageContract } from "./contracts/usage.contract.js";
 export { vpnContract } from "./contracts/vpn.contract.js";
 export { workspaceContract } from "./contracts/workspace.contract.js";
 export * from "./effects.js";
@@ -85,8 +89,10 @@ export const sandboxContract = {
     logs: logsContract,
     panels: panelsContract,
     ports: portsContract,
+    push: pushContract,
     secrets: secretsContract,
     system: systemContract,
     translator: translatorContract,
+    usage: usageContract,
     vpn: vpnContract,
 };

package/src/schemas.test.ts

@@ -0,0 +1,40 @@
+import { expect, test } from "vitest";
+import { SandboxSettingsSchema } from "./schemas.js";
+
+/* The settings shape spans a version seam that really moves: the browser ships with the platform, the daemon
+ * ships inside the user's sandbox image, so a web build routinely parses a payload from an OLDER daemon. These
+ * tests pin the property that makes that survivable — an absent key is that flag's default, not a parse
+ * failure — because failing instead reaches the user as a settings page whose switches silently do nothing. */
+
+test("a payload from a build that predates a toggle parses, with the new toggle at its default", () => {
+    // What a daemon built before the output-cleaner backend switch answers with: every key it knew, and
+    // nothing for the one added after it shipped.
+    const older = {
+        stableSystemPrompt: false,
+        skills: [],
+        hashlineEdits: false,
+        terseOutput: true,
+        iqSearch: true,
+        outputCleaners: "-cap",
+        outputHoldout: 0.1,
+    };
+    expect(SandboxSettingsSchema.parse(older)).toEqual({ ...older, filterBackend: "native" });
+});
+
+test("an empty object is the full default settings object", () => {
+    expect(SandboxSettingsSchema.parse({})).toEqual({
+        stableSystemPrompt: false,
+        skills: [],
+        hashlineEdits: false,
+        terseOutput: false,
+        iqSearch: false,
+        outputCleaners: "off",
+        outputHoldout: 0,
+        filterBackend: "native",
+    });
+});
+
+test("a key of the wrong type is still a parse failure — tolerance is for absence, not for garbage", () => {
+    expect(SandboxSettingsSchema.safeParse({ iqSearch: "yes" }).success).toBe(false);
+    expect(SandboxSettingsSchema.safeParse({ outputHoldout: 4 }).success).toBe(false);
+});

package/src/schemas.ts

@@ -222,9 +222,11 @@ export type TranslatorAccounts = z.infer<typeof TranslatorAccountsSchema>;
 // clarifying questions, a per-tool permission prompt — parks on the SAME registry keyed by `requestId`, so
 // one route resolves all three; the `kind` says which card answered and carries its payload.
 export const AgentReplySchema = z.discriminatedUnion("kind", [
-    // ExitPlanMode approval. `mode` is the posture to execute the approved plan in — Claude Code's "yes, and
-    // auto-accept edits" (acceptEdits) vs "yes, and manually approve edits" (default); it rides back to the SDK
-    // as a session setMode. Rejection feedback loops back into the model as the denial reason.
+    // ExitPlanMode approval. `mode` is the posture to execute the approved plan in — auto-accept edits
+    // (acceptEdits), approve each one (default), or run everything (bypassPermissions); it rides back to the SDK
+    // as a session setMode. Absent, the turn returns to the posture it STARTED in, so an agent that put itself
+    // into plan mode does not cost the user the permissions they granted. Rejection feedback loops back into the
+    // model as the denial reason.
     z.object({
         kind: z.literal("plan"),
         requestId: z.string().min(1),
@@ -240,8 +242,9 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
         answers: z.record(z.string(), z.array(z.string())).optional(),
         cancelled: z.boolean().optional(),
     }),
-    // A per-tool permission prompt. 'once' allows this call only; 'always' also persists the SDK's suggested
-    // rules so the same tool stops asking; 'deny' blocks it and feeds `feedback` back as the reason.
+    // A per-tool permission prompt. 'once' allows this call only; 'always' allows the whole TOOL for the rest
+    // of the session (plus the SDK's own narrower suggestions), which is what the card's label promises;
+    // 'deny' blocks it and feeds `feedback` back as the reason.
     z.object({
         kind: z.literal("permission"),
         requestId: z.string().min(1),
@@ -402,16 +405,23 @@ export const SessionTranscriptSchema = z.object({ messages: z.array(SessionTrans
 //                        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.
-
+//
+// Every field carries that default IN THE SCHEMA, so a settings object written before a field existed still
+// parses — the absent key reads as its default. That is not a compatibility layer, it is the seam this shape
+// spans: the browser ships with the platform while the daemon ships inside the user's sandbox image, so a web
+// build is routinely NEWER than the daemon answering it. Requiring the key instead makes the whole settings
+// surface fail to parse the moment a toggle is added — which reaches the user as a page of switches that are
+// silently dead, not as an error. It also means an older on-disk manifest keeps the owner's other picks rather
+// than being discarded whole.
 export const SandboxSettingsSchema = z.object({
-    stableSystemPrompt: z.boolean(),
-    skills: z.array(z.string()),
-    hashlineEdits: z.boolean(),
-    terseOutput: z.boolean(),
-    iqSearch: z.boolean(),
-    outputCleaners: z.string(),
-    outputHoldout: z.number().min(0).max(1),
-    filterBackend: z.enum(["native", "rtk"]),
+    stableSystemPrompt: z.boolean().default(false),
+    skills: z.array(z.string()).default([]),
+    hashlineEdits: z.boolean().default(false),
+    terseOutput: z.boolean().default(false),
+    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"),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
 
@@ -437,19 +447,40 @@ export const IntenticRunSchema = z.object({ args: z.array(z.string()) });
 
 // ---- git ----
 
+// What a commit records — two shapes, each a real git spelling:
+//   all: true   ⇒ stage every change in the repo, then commit (`commit -a`; VSCode's "stage all and commit")
+//   absent      ⇒ commit whatever is staged (plain `git commit`)
+//
+// There is deliberately no `paths`. The index IS git's mechanism for choosing what a commit contains, so a
+// second path-selection channel alongside it can only disagree with it: a `commit --only` over a partially
+// staged file records the WORKTREE content while the row the user picked showed the INDEX content. Staging is
+// the selection; this endpoint only ever records it.
 export const CommitSchema = RepoParamSchema.extend({
     message: z.string().min(1),
-    // Repo-relative paths to commit; absent ⇒ commit everything changed in the repo.
-    paths: z.array(z.string().min(1)).max(500).optional(),
+    all: z.boolean().optional(),
 });
 export const DiscardSchema = RepoParamSchema.extend({
     // Repo-relative paths to discard; absent ⇒ discard every uncommitted change in the repo.
     paths: z.array(z.string().min(1)).max(500).optional(),
 });
-export const PushSchema = RepoParamSchema.extend({ branch: z.string().min(1) });
+// Index moves. Both are per-path and never touch the worktree, so they are always safe and need no checkpoint.
+export const GitStageSchema = RepoParamSchema.extend({ paths: z.array(z.string().min(1)).max(500) });
+// `branch` defaults to the checked-out one. There is deliberately no "set upstream" flag: the daemon publishes
+// (`push -u`) exactly when the branch has no upstream yet, which is never destructive and is the only way the
+// result is coherent — see pushBranch.
+export const PushSchema = RepoParamSchema.extend({ branch: z.string().min(1).optional() });
 export const GitFileQuerySchema = RepoParamSchema.extend({ path: z.string().min(1) });
 export const GitFileWriteSchema = RepoParamSchema.extend({ path: z.string().min(1), content: z.string() });
-export const GitFileDiffQuerySchema = RepoParamSchema.extend({ path: z.string().min(1) });
+// Which of the working tree's diffs to open — the same split the Changes panel lists under. A path that is
+// staged AND edited again has genuinely different diffs, so the side is required rather than defaulted: a
+// caller that doesn't say which one it means doesn't know what it is showing.
+//   staged     ⇒ index vs HEAD      (what a bare `git commit` would record)
+//   unstaged   ⇒ worktree vs index  (untracked ⇒ no before side)
+//   conflicted ⇒ HEAD vs worktree   (what you had vs what the merge left, markers included — an unmerged path
+//                                    has no stage 0, so the index is not a side it can be diffed against)
+export const GitDiffSideSchema = z.enum(["staged", "unstaged", "conflicted"]);
+export type GitDiffSide = z.infer<typeof GitDiffSideSchema>;
+export const GitFileDiffQuerySchema = RepoParamSchema.extend({ path: z.string().min(1), side: GitDiffSideSchema });
 export const GitStatusSchema = z.object({ branch: z.string(), dirty: z.boolean(), files: z.array(z.string()) });
 export const GitFilesSchema = z.object({ files: z.array(z.string()) });
 export const GitFileSchema = z.object({ path: z.string(), content: z.string() });
@@ -460,29 +491,120 @@ export const CommitResultSchema = z.object({ committed: z.boolean() });
 export const GitChangeSchema = z.object({
     // Repo-relative path with forward slashes; for "renamed" the NEW path (`from` carries the old one).
     path: z.string(),
-    status: z.enum(["added", "modified", "deleted", "renamed", "type-changed"]),
+    // "conflicted" is git's unmerged state (`U`), and it is not a kind of modification: the index holds "ours"
+    // and "theirs" at stages 2/3 with NO stage 0, so there is nothing a commit could record for this path and
+    // git refuses to commit while one exists. It belongs to neither side — see RepoChanges.conflicted.
+    status: z.enum(["added", "modified", "deleted", "renamed", "type-changed", "conflicted"]),
     from: z.string().optional(),
     additions: z.number().optional(),
     deletions: z.number().optional(),
 });
 export type GitChange = z.infer<typeof GitChangeSchema>;
+
+// Where a repo's checked-out branch stands against its remote. Every field is optional-or-zero because every
+// one of them is legitimately absent in a healthy repo: no remote configured yet, a branch created locally and
+// never pushed, a detached HEAD. `ahead` = commits only we have; `behind` = commits only the upstream has,
+// which is meaningful only as of the last fetch — the panel's Fetch button is what refreshes it.
+export const GitRemoteStateSchema = z.object({
+    // The remote this branch pushes to: its OWN remote when it tracks one, else the first `git remote` lists
+    // (where a never-pushed branch would publish). Those differ in a fork — `origin` and `upstream` both
+    // configured — and pushing to the wrong one succeeds while leaving `ahead` stuck. Absent ⇒ no remote.
+    remote: z.string().optional(),
+    // The checked-out branch; absent on a detached HEAD or an unborn repo.
+    branch: z.string().optional(),
+    // The tracking ref ("origin/main"); absent ⇒ this branch has no upstream, so the next push publishes it.
+    upstream: z.string().optional(),
+    ahead: z.number(),
+    behind: z.number(),
+});
+export type GitRemoteState = z.infer<typeof GitRemoteStateSchema>;
+
+// A ref name (branch/tag), validated structurally — git enforces the rest of ref-name legality itself.
+const RefNameSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/)
+    .max(200);
+
+// One local branch, for the switcher. `at` is its tip's committer time in ms (the list sorts newest-first).
+export const GitBranchSchema = z.object({
+    name: z.string(),
+    current: z.boolean(),
+    upstream: z.string().optional(),
+    ahead: z.number(),
+    behind: z.number(),
+    // The configured upstream no longer exists on the remote (a merged PR's deleted branch) — distinct from
+    // "no upstream", and the signal that this local branch is safe to delete.
+    gone: z.boolean().optional(),
+    at: z.number(),
+});
+export type GitBranch = z.infer<typeof GitBranchSchema>;
+export const GitBranchesSchema = z.object({ branches: z.array(GitBranchSchema) });
+// Create at `start` (a sha or ref; absent ⇒ HEAD); `checkout` switches to it immediately (`git switch -c`).
+export const GitBranchCreateAtSchema = RepoParamSchema.extend({
+    name: RefNameSchema,
+    start: z.string().min(1).optional(),
+    checkout: z.boolean().optional(),
+});
+// `force` is the deliberate retry after git refuses to drop an unmerged branch.
+export const GitBranchDeleteSchema = RepoParamSchema.extend({ name: RefNameSchema, force: z.boolean().optional() });
+
 export const RepoChangesSchema = z.object({
     // The {repo} param the per-repo git routes accept: "root" or a repo id (its root-relative dir).
     repo: z.string(),
     // Absent on an unborn HEAD (a repo initialized but never committed).
     branch: z.string().optional(),
-    changes: z.array(GitChangeSchema),
+    // Unmerged paths — a merge, rebase, cherry-pick or pull that git could not finish. First, because until
+    // they are resolved nothing else in this repo can be committed at all: git refuses outright. Held apart
+    // from the two sides rather than listed in them, because "staged or not" is not a question an unmerged path
+    // has an answer to. Staging one (`git add`) is exactly how you tell git it is resolved.
+    conflicted: z.array(GitChangeSchema),
+    // The two sides git actually models, kept apart because a path can appear on BOTH with different statuses
+    // (a staged edit that was then edited again — the classic `MM`). `staged` is index-vs-HEAD: exactly what a
+    // bare `git commit` would record. `unstaged` is worktree-vs-index plus untracked files. Each side's
+    // additions/deletions describe the diff it is listed under, never a conflation of the two.
+    staged: z.array(GitChangeSchema),
+    unstaged: z.array(GitChangeSchema),
+    // 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
+    // PATH rather than carried on each GitChange because a path can be listed on two sides at once (staged and
+    // 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.
+    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
-    // vanished from the panel with nothing to act on; it now arrives with empty `changes` and this set instead.
+    // vanished from the panel with nothing to act on; it now arrives with empty change lists and this set instead.
     error: z.string().optional(),
 });
 export type RepoChanges = z.infer<typeof RepoChangesSchema>;
-// The aggregated review set across every repo (root + every discovered repo); a repo appears when it has changes
-// or when it failed to scan.
+// 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 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
+// agent's CUMULATIVE output (base → worktree), not just the not-yet-landed remainder, because landing is not
+// the end of the review: a clean turn auto-lands within milliseconds, and a list scoped to the remainder shows
+// the user an empty panel for work they never got to look at. `landed` is what still separates the two — the
+// remainder is what "Land now" would apply, and the panel filters on exactly this flag.
+export const AgentChangeSchema = GitChangeSchema.extend({ landed: z.boolean() });
+export type AgentChange = z.infer<typeof AgentChangeSchema>;
+
+// An agent conversation-worktree's delta vs its recorded base — deliberately NOT RepoChanges. There is no index
+// side to speak of here: the question a fleet review answers is "what did this agent write", which is one flat
+// set. Sharing the working-tree shape would have forced a meaningless empty `staged` on every
+// row and invited the panel to render a staging affordance that cannot work on a worktree the user never checks out.
+export const AgentRepoChangesSchema = z.object({
+    repo: z.string(),
+    branch: z.string().optional(),
+    changes: z.array(AgentChangeSchema),
+});
+export type AgentRepoChanges = z.infer<typeof AgentRepoChangesSchema>;
+export const AgentChangesSchema = z.object({ repos: z.array(AgentRepoChangesSchema) });
+export type AgentChanges = z.infer<typeof AgentChangesSchema>;
+
 // ---- git history graph (the "Git Graph" view over a repo's real commits) ----
 // A hex sha (full or git-abbreviated): the only shape the graph ever sends back, so the per-commit routes
 // constrain to it rather than accepting an arbitrary git revision expression.
@@ -524,11 +646,8 @@ export const GitCommitFileDiffQuerySchema = RepoParamSchema.extend({ sha: ShaSch
 // merge / rebase / drop) add or replay commits and are auto-checkpointed daemon-side; a conflict aborts and
 // reports `ok:false` (an expected outcome, not a throw). Checkout and reset move HEAD (reset --hard discards
 // the worktree) — also auto-checkpointed. A `{repo, sha}` names the target commit for every commit-scoped
-// action; a ref name (branch/tag) is validated structurally, git enforces the rest of ref-name legality.
-const RefNameSchema = z
-    .string()
-    .regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/)
-    .max(200);
+// action; a ref name (branch/tag) is validated structurally, git enforces the rest of ref-name legality
+// (RefNameSchema is declared above, with the branch schemas that first use it).
 export const GitBranchCreateSchema = RepoParamSchema.extend({ sha: ShaSchema, name: RefNameSchema });
 export const GitTagCreateSchema = RepoParamSchema.extend({ sha: ShaSchema, name: RefNameSchema });
 export const GitCheckoutSchema = RepoParamSchema.extend({ ref: RefNameSchema });
@@ -958,6 +1077,21 @@ export type VpnProvider = z.infer<typeof VpnProviderSchema>;
 
 const autoConnect = z.enum(["on", "off"]).default("on");
 
+// FortiClient wraps every stored credential in its own "EncX <hex>" (older builds: "Enc <hex>") encryption,
+// keyed to the machine that exported the config — it is NOT recoverable from the file. Pasting one is an easy
+// mistake to make, because in the XML it sits exactly where the credential belongs, and the failure it causes
+// is unreadable: phase 1 negotiates fine and IKE then reports "calculated HASH does not match HASH payload",
+// which says nothing about where the bad value came from. Rejecting it here turns that into a sentence at the
+// point of entry. (The FortiClient importer already drops these — this catches a hand-paste.)
+// Exported so the add form can flag it inline on blur instead of only on a rejected round-trip — one
+// definition of what "this is ciphertext, not a credential" means, shared by the browser and the daemon.
+export const isForticlientCiphertext = (value: string): boolean => /^Enc[X]?\s+[0-9A-Fa-f]{8,}$/.test(value.trim());
+
+const notForticlientCiphertext = <T extends z.ZodType<string>>(field: T, label: string): T =>
+    field.refine((value) => !isForticlientCiphertext(value), {
+        message: `That looks like a value copied straight out of a FortiClient config — FortiClient encrypts it with a key tied to the machine that exported it, so it can't be used here. Enter the actual ${label} (ask whoever administers the gateway).`,
+    }) as unknown as T;
+
 export const WireguardVpnConfigSchema = z.object({
     provider: z.literal("wireguard"),
     // The pasted .conf ([Interface] + [Peer]) — it holds the private key, so it's this arm's secret field.
@@ -970,7 +1104,7 @@ export const FortinetVpnConfigSchema = z.object({
     server: z.string().min(1),
     port: z.coerce.number().int().min(1).max(65535).default(443),
     username: z.string().min(1),
-    password: z.string().min(1),
+    password: notForticlientCiphertext(z.string().min(1), "password"),
     // A FortiGate on a self-signed/private-CA certificate: openconnect pins this digest
     // ("sha256:…", copied from its own refusal message) instead of trusting a CA. Absent ⇒ normal CA validation.
     trustedCert: z.string().min(1).optional(),
@@ -981,14 +1115,25 @@ export const FortinetVpnConfigSchema = z.object({
 export const IpsecVpnConfigSchema = z.object({
     provider: z.literal("ipsec"),
     server: z.string().min(1),
-    presharedKey: z.string().min(1),
+    presharedKey: notForticlientCiphertext(z.string().min(1), "pre-shared key"),
     // The local IKE identity (FortiClient's <localid>) — dial-up FortiGates key their phase-1 selection off it.
     localId: z.string().min(1).optional(),
     remoteId: z.string().min(1).optional(),
     // XAuth (FortiClient's <xauth>) — absent for PSK-only tunnels.
     username: z.string().min(1).optional(),
-    password: z.string().min(1).optional(),
+    password: notForticlientCiphertext(z.string().min(1), "XAuth password").optional(),
     ikeVersion: z.enum(["1", "2"]).default("1"),
+    // Perfect Forward Secrecy for phase 2. Must match the gateway EXACTLY: it decides whether a KE payload is
+    // sent in quick mode, and a mismatch fails with NO_PROPOSAL_CHOSEN only after phase 1 and XAuth have
+    // succeeded — which reads like anything but a phase 2 problem. FortiClient stores it as <pfs> under
+    // <ipsec_settings> and defaults it on, so that is the default here too.
+    pfs: z.enum(["on", "off"]).default("on"),
+    // The Diffie-Hellman group, as FortiClient numbers them. ONE field for both phases on purpose: in IKEv1
+    // strongSwan sends a single KE payload in quick mode and the phase-2 group ends up following phase 1, so
+    // offering a phase-1 list that starts with a different group than the gateway wants for phase 2 fails with
+    // NO_PROPOSAL_CHOSEN no matter what the esp= line says. 14 (modp2048) is FortiClient's phase-2 default;
+    // it is <dhgroup> under <ipsec_settings> in an export.
+    dhGroup: z.enum(["2", "5", "14", "15", "16", "19", "20"]).default("14"),
     // IKEv1 aggressive mode: insecure by construction, and exactly what FortiGate dial-up with a group PSK
     // requires — hence opt-in per connection rather than a global strongSwan setting.
     aggressive: z.enum(["on", "off"]).default("on"),
@@ -1140,6 +1285,9 @@ export const ForticlientConnectionSchema = z.object({
     // ipsec-only, and only when the file stored them in the clear.
     localId: z.string().optional(),
     aggressive: z.boolean().optional(),
+    // Phase-2 settings, read from <ipsec_settings> — the pair that decides whether quick mode can succeed.
+    pfs: z.boolean().optional(),
+    dhGroup: z.string().optional(),
     // What the user still has to supply for this connection to dial (always at least the password).
     needs: z.array(z.string()),
 });
@@ -1576,9 +1724,75 @@ export const ActivityStatusSchema = z.object({
 });
 export type ActivityStatus = z.infer<typeof ActivityStatusSchema>;
 
+// ---- usage: the durable spend ledger ----
+// One row per attributed turn, appended at turn end and NEVER pruned. This exists because the activity log
+// can't answer a money question: it prunes to its most recent entries, so a month's spend is unanswerable and
+// — worse for a cost readout — the totals SHRINK as newer turns evict older ones. The ledger keeps the raw
+// per-turn facts and the rollup projects them on read, so a new grouping (by day, by model, by conversation)
+// needs no new storage and no migration.
+export const UsageTurnSchema = z.object({
+    // Epoch ms at turn end. Kept alongside `day` so a future timezone-aware rollup is a pure change over data
+    // already on disk.
+    at: z.number(),
+    // The UTC calendar day (YYYY-MM-DD) `at` fell in — precomputed so a rollup never re-derives a timezone.
+    day: z.string(),
+    provider: z.string(),
+    // Absent on an env-token turn, which has no account to attribute to (same rule as the activity log).
+    account: z.string().optional(),
+    // The model the turn ACTUALLY ran, resolved past the client's pick and every provider default. Absent only
+    // when the provider's own subscription default served it without the daemon naming one.
+    model: z.string().optional(),
+    harness: z.string(),
+    // The conversation this turn belonged to, so spend can join to a fleet agent. Absent on a main-tree turn.
+    conversationId: z.string().optional(),
+    // The provider's own turn count for the request (a Claude "turn" can be several under the hood), so turns
+    // and cost stay comparable across providers. 1 when the provider reported none.
+    turns: z.number(),
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    cacheReadTokens: z.number(),
+    cacheCreationTokens: z.number(),
+    costUsd: z.number(),
+    durationMs: z.number(),
+});
+export type UsageTurn = z.infer<typeof UsageTurnSchema>;
+
+// The ledger grouped by day × provider × account × model × harness × conversation — the finest grouping any
+// dashboard panel needs, and a handful of rows per active day instead of one per turn, so a year of history is
+// well under a MB over the tunnel. Every panel (spend per day, cost by model, cost by agent, cache hit rate) is
+// a projection of these.
+// The conversation is in the KEY, not merely along for the ride, because cost-by-agent has to answer within the
+// same window as every other panel on the screen. The fleet registry also carries a per-agent total, but only a
+// cumulative, all-time one — reading it beside a "last 7 days" filter would print an all-time number under a
+// windowed heading, which is the shrinking-totals bug wearing a different hat.
+export const UsageRollupRowSchema = z.object({
+    day: z.string(),
+    provider: z.string(),
+    account: z.string().optional(),
+    model: z.string().optional(),
+    harness: z.string(),
+    conversationId: z.string().optional(),
+    turns: z.number(),
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    cacheReadTokens: z.number(),
+    cacheCreationTokens: z.number(),
+    costUsd: z.number(),
+    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({
+    from: z.string().optional(),
+    to: z.string().optional(),
+});
+export type UsageRollupQuery = z.infer<typeof UsageRollupQuerySchema>;
+export const UsageRollupSchema = z.object({ rows: z.array(UsageRollupRowSchema) });
+
 // ---- usage: per-account token/cost totals ----
-// Aggregated from the activity log's turn.completed events (their `usage` extra), grouped by provider+account.
-// Totals cover the retained log window (the log prunes to its most recent entries), not all-time.
+// The account picker's headroom readout, folded from the ledger above (all-time, not a log window), grouped by
+// provider+account. `account` is the attribution key, so env-token turns are excluded rather than pooled under
+// a blank id — an unattributed turn belongs to no account's total.
 export const UsageAccountSchema = z.object({
     provider: z.string(),
     account: z.string(),
@@ -1631,3 +1845,43 @@ export const PresenceReportSchema = z.object({
     path: z.string().optional(),
 });
 export type PresenceReport = z.infer<typeof PresenceReportSchema>;
+
+// ---- push: web-push notifications to the owner's devices ----
+// The daemon is the only tier that knows what the agent is doing, so it is the sender. Subscriptions are
+// per-BROWSER (the endpoint is minted by that browser's push service — Google's, Mozilla's, Apple's), which
+// is why they live here and not on the platform: the platform is off the command path and would have to be
+// told about every turn to be useful.
+
+// A browser's PushSubscription, in the exact shape `web-push` consumes — the browser produces it via
+// PushManager.subscribe() and the client posts it back verbatim, so the daemon never reshapes it.
+export const PushSubscriptionSchema = z.object({
+    endpoint: z.string().url(),
+    keys: z.object({
+        // The client's public key and auth secret for payload encryption (RFC 8291). Opaque base64url here.
+        p256dh: z.string().min(1),
+        auth: z.string().min(1),
+    }),
+});
+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.
+export const PushNotificationSchema = z.object({
+    title: z.string().min(1),
+    body: z.string(),
+    url: z.string().optional(),
+    tag: z.string().optional(),
+    // Whether the notification stays on screen until dismissed. Set for the "agent is blocked on you" cases,
+    // where a notification that auto-dismisses is a request that silently went unanswered.
+    requireInteraction: z.boolean().optional(),
+});
+export type PushNotification = z.infer<typeof PushNotificationSchema>;
+
+// The VAPID public key a browser needs to subscribe, plus whether this browser's endpoint is already known —
+// so the settings toggle can render its true state instead of trusting the browser's permission alone (a
+// 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.
+export const PushConfigQuerySchema = z.object({ endpoint: z.string().url().optional() });