toolroll 0.9.83 → 0.9.85

package/dist/settings-proofs.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The settings proof inventory (docs/plans/settings-revamp.md §4): for every settings action, the proof its handler
+ * already asks for, as data. Only rendering code reads it (settings-kit.ts draws the step-up dialog from it); no
+ * handler does, and nothing here changes what a handler proves. `src/settings-kit.test.ts` pins every row against the
+ * form contracts (console-api.ts), the route table, and — for one row of each kind — the handler itself over HTTP.
+ *
+ * Proof kinds, as the handlers implement them (scope.ts, server/guards.ts):
+ * - `none`: the session and the form token (CSRF) only.
+ * - `step-up`: `authenticateApprover` — a password typed now; an empty field stands in under Passwordless (the
+ *   person's own live browser session) and for a one-use identity-provider re-check.
+ * - `credential`: `authenticateCredential` — a password typed now, or a one-use identity-provider re-check. Passwordless
+ *   never covers it.
+ * - `typed-password`: the handler checks the typed password itself (`authenticateAccount`, or an empty field refused
+ *   before the check). Neither Passwordless nor an identity-provider re-check stands in.
+ * - `typed-now-operator`: a password typed now by an instance operator (widening check access); not even a re-check.
+ */
+import { type ConsoleFormName } from "./contracts/console-api.js";
+export type ProofKind = "none" | "step-up" | "credential" | "typed-password" | "typed-now-operator";
+/** Who the route table admits (route-table.ts `role`); `handler` notes a narrower check the handler makes itself. */
+export type ProofRole = "any" | "approver" | "operator";
+export type ProofRow = {
+    /** Stable id the kit is called with. */
+    readonly id: string;
+    /** What the person is doing, in words. */
+    readonly action: string;
+    /** The exact POST paths. */
+    readonly routes: readonly string[];
+    /** The form contract its handler reads through. */
+    readonly form: ConsoleFormName;
+    /** The proof field's name, or null when none is read. */
+    readonly field: "password" | "token" | null;
+    readonly proof: ProofKind;
+    /** Only some submissions need the proof (the rest are `none`), in words. */
+    readonly when?: string;
+    /** Rows that share a route are variants of one handler, each with its own exact proof. A variant with `select`
+     * applies exactly when the form carries that hidden value (the kit refuses a form whose hidden terms pick another
+     * variant); a variant with `explicit` is named by the caller (a choice the server decides, like widening). */
+    readonly select?: {
+        readonly field: string;
+        readonly value: string;
+    };
+    readonly explicit?: true;
+    /** Under Passwordless, does an empty proof field pass? (`accepted` only for step-up.) */
+    readonly passwordless: "accepted" | "refused" | "n/a";
+    /** Does a one-use identity-provider re-check (empty field after "Confirm with …") pass? */
+    readonly sso: "accepted" | "refused" | "n/a";
+    readonly role: ProofRole;
+    /** A narrower standing the handler checks itself, in words. */
+    readonly handlerRole?: string;
+    /** Fields that hold a secret that is not the person's proof (never echoed, password managers kept out). */
+    readonly secrets: readonly string[];
+    /** Fields whose name reads like a credential but hold something else (an id, a bot token…). */
+    readonly notProof?: readonly string[];
+    /** Every term the handler requires besides the proof: hidden fields carried back unchanged (nonce, digest,
+     * fingerprint, the shown project, what a preview showed) and the fields that pick the target (repo, act). */
+    readonly terms: readonly string[];
+    /** Anything else the handler requires, in words. */
+    readonly note?: string;
+};
+export declare const PROOF_INVENTORY: readonly ProofRow[];
+/** One row by id; throws on an unknown id (a rendering bug, never a request's input). */
+export declare function proofRow(id: string): ProofRow;
+/** Whether the field a row names is one its form contract reads (used by the kit's own guard and the tests). */
+export declare function contractReads(row: ProofRow, field: string): boolean;

package/dist/settings-proofs.js

@@ -0,0 +1,101 @@
+/**
+ * The settings proof inventory (docs/plans/settings-revamp.md §4): for every settings action, the proof its handler
+ * already asks for, as data. Only rendering code reads it (settings-kit.ts draws the step-up dialog from it); no
+ * handler does, and nothing here changes what a handler proves. `src/settings-kit.test.ts` pins every row against the
+ * form contracts (console-api.ts), the route table, and — for one row of each kind — the handler itself over HTTP.
+ *
+ * Proof kinds, as the handlers implement them (scope.ts, server/guards.ts):
+ * - `none`: the session and the form token (CSRF) only.
+ * - `step-up`: `authenticateApprover` — a password typed now; an empty field stands in under Passwordless (the
+ *   person's own live browser session) and for a one-use identity-provider re-check.
+ * - `credential`: `authenticateCredential` — a password typed now, or a one-use identity-provider re-check. Passwordless
+ *   never covers it.
+ * - `typed-password`: the handler checks the typed password itself (`authenticateAccount`, or an empty field refused
+ *   before the check). Neither Passwordless nor an identity-provider re-check stands in.
+ * - `typed-now-operator`: a password typed now by an instance operator (widening check access); not even a re-check.
+ */
+import { CONSOLE_FORMS } from "./contracts/console-api.js";
+const ACCEPT = { passwordless: "accepted", sso: "accepted" };
+const CREDENTIAL = { passwordless: "refused", sso: "accepted" };
+const TYPED = { passwordless: "refused", sso: "refused" };
+const NONE = { passwordless: "n/a", sso: "n/a" };
+/** /mode/sign re-derives the digest from the posted terms, so every one rides back. */
+const MODE_TERMS = ["nonce", "digest", "expiry", "name", "days", "publication", "auto-approve", "plan-auto", "chat-approve"];
+const CHAT_APPS = [["slack", "Slack", "slack", ["app-token", "bot-token"]], ["teams", "Teams", "teams", ["secret"]], ["discord", "Discord", "discord", ["bot-token"]]];
+export const PROOF_INVENTORY = [
+    // CSRF only.
+    { id: "quality-default", action: "Set the default quality for new tasks", routes: ["/settings/quality-default"], form: "qualityDefault", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "notifications", action: "Choose what reaches you", routes: ["/settings/notifications"], form: "notifications", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "notifications-mute", action: "Mute a project", routes: ["/settings/notifications/mute"], form: "notificationsMute", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "messaging", action: "Choose the chat app that receives alerts", routes: ["/settings/messaging"], form: "messaging", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "telegram-digest", action: "Set the Telegram digest", routes: ["/settings/telegram-digest"], form: "telegramDigest", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "provider-key", action: "Save or clear an AI provider key", routes: ["/settings/provider-key", "/settings/provider-key-clear"], form: "providerKey", field: null, proof: "none", ...NONE, role: "any", secrets: ["value"], terms: [] },
+    { id: "telegram-token", action: "Save the Telegram bot token", routes: ["/settings/telegram-token"], form: "telegramToken", field: null, proof: "none", ...NONE, role: "any", secrets: ["token"], notProof: ["token"], terms: [] },
+    { id: "email", action: "Set up or test email", routes: ["/settings/email", "/settings/email-test", "/settings/email-read-test"], form: "email", field: null, proof: "none", ...NONE, role: "any", secrets: ["password"], notProof: ["password"], terms: [], note: "`password` is the mail server's password; its wire name stays" },
+    { id: "google", action: "Connect or disconnect Google", routes: ["/settings/google", "/settings/google/disconnect"], form: "google", field: null, proof: "none", ...NONE, role: "any", secrets: ["clientSecret"], terms: [] },
+    { id: "appearance", action: "Change the theme or accent", routes: ["/settings/appearance"], form: "appearance", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "chat-approval-confirm", action: "Review approving from chat", routes: ["/settings/chat-approval/confirm", "/settings/chat-approval/off"], form: "chatApproval", field: null, proof: "none", ...NONE, role: "approver", secrets: [], terms: [] },
+    ...CHAT_APPS.map(([app, name, form]) => ({ id: `${app}-alerts`, action: `Send alerts to ${name}`, routes: [`/settings/${app}/alerts`], form, field: null, proof: "none", ...NONE, role: "approver", secrets: [], terms: [] })),
+    // Step-up: a password typed now, the Passwordless session, or a one-use re-check.
+    { id: "permission-default", action: "Start new tasks with Full access", routes: ["/settings/permission-default"], form: "permissionDefault", field: "password", proof: "step-up", when: "only when widening to Full access", ...ACCEPT, role: "any", secrets: [], terms: [] },
+    { id: "spend-budget", action: "Set a monthly limit", routes: ["/spend/budget"], form: "spendBudget", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: [] },
+    { id: "models-agent", action: "Change which model does each job", routes: ["/settings/models/agent"], form: "modelsChange", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: ["scope", "digest"] },
+    { id: "models-apply", action: "Apply a model preset or switch", routes: ["/settings/models/apply"], form: "modelsChange", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: ["scope", "digest", "change"], note: "plus the previewed preset, or switch and to" },
+    ...[
+        ["policy", "Change the policy", "policy", "operator"],
+        ["approval", "Change approval rules", "approval", "operator"],
+        ["request-limits", "Change request limits", "requestLimits", "operator"],
+        ["retention", "Change retention", "retention", "operator"],
+        ["backups", "Change backups", "backups", "operator"],
+        ["data", "Download everything", "data", "operator"],
+    ].map(([path, action, form, role]) => ({ id: path, action, routes: [`/settings/${path}`], form, field: "password", proof: "step-up", ...ACCEPT, role, secrets: [], terms: path === "approval" ? ["repo"] : [] })),
+    { id: "pull-requests", action: "Change pull-request settings, or turn them off", routes: ["/settings/pull-requests"], form: "pullRequests", field: "password", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "act"] },
+    { id: "pull-requests-on", action: "Turn pull requests on", routes: ["/settings/pull-requests"], select: { field: "act", value: "on" }, form: "pullRequests", field: "password", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "act", "github", "base"], note: "`github` and `base` are what the page showed; the handler checks again and refuses a difference" },
+    { id: "checks", action: "Change checks", routes: ["/settings/checks"], form: "checks", field: "password", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "act"] },
+    { id: "monitoring", action: "Change monitoring", routes: ["/settings/monitoring"], form: "monitoring", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: ["header-value"], terms: [] },
+    { id: "updates", action: "Update Toolroll", routes: ["/settings/updates", "/settings/updates/seen", "/settings/updates/cancel"], form: "updates", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: [] },
+    { id: "storage-cleanup", action: "Choose when checkouts are removed", routes: ["/settings/storage"], form: "storage", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: [] },
+    { id: "storage-clean", action: "Clean up checkouts", routes: ["/settings/storage/clean"], form: "storage", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: ["preview"], note: "`preview` is the digest of what the page showed; a changed list is refused" },
+    { id: "storage-discard", action: "Discard a checkout", routes: ["/settings/storage/discard"], form: "storage", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: ["path"] },
+    { id: "project-live-view", action: "Show a project's commands in the live view", routes: ["/settings/project/live-view"], form: "projectLiveView", field: "password", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "nonce"] },
+    { id: "project-delete", action: "Delete a project", routes: ["/settings/project/delete"], form: "projectDelete", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: ["repo", "step"], note: "the project's name typed too" },
+    { id: "tools-connect", action: "Connect a tool", routes: ["/settings/tools/connect"], form: "toolsConnect", field: "password", proof: "step-up", ...ACCEPT, role: "approver", secrets: [], terms: ["repo", "shown"], note: "`shown` is the project the page showed (a post from another project is refused), not a digest" },
+    { id: "tools-change", action: "Change a project's tools", routes: ["/settings/tools/change"], form: "toolsChange", field: "password", proof: "step-up", when: "only to add a tool (catalog, custom, import) or set a secret", ...ACCEPT, role: "approver", secrets: ["value"], terms: ["repo", "shown", "action"] },
+    ...CHAT_APPS.map(([app, name, form]) => ({ id: `${app}-close`, action: `Unpair or disconnect ${name}`, routes: [`/settings/${app}/unpair`, `/settings/${app}/disconnect`], form, field: "password", proof: "step-up", ...ACCEPT, role: "approver", secrets: [], terms: [] })),
+    { id: "telegram-unpair", action: "Unpair your phone from Telegram", routes: ["/settings/telegram/unpair"], form: "telegramPair", field: "password", proof: "step-up", ...ACCEPT, role: "approver", secrets: [], terms: [] },
+    { id: "people-close", action: "Cancel an invite or remove a person", routes: ["/people/invite-revoke", "/people/revoke"], form: "peopleRevoke", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver", secrets: [], terms: [] },
+    { id: "project-setup", action: "Approve project setup", routes: ["/control/setup-approve"], form: "projectSetup", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project; models for a new installation need an instance operator", secrets: [], terms: ["repo", "nonce", "fingerprint", "provider", "model", "command", "seconds"], note: "the nonce is spent before the password is checked: after a refusal, review again; the reviewed inputs are previewed again and must match the fingerprint" },
+    { id: "project-instructions", action: "Add the agent instructions", routes: ["/control/instructions-approve"], form: "projectSetup", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "nonce", "fingerprint"], note: "the nonce is spent before the password is checked" },
+    { id: "mode-sign", action: "Sign an operating mode", routes: ["/mode/sign"], form: "mode", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: MODE_TERMS },
+    { id: "mode-sign-chat-approve", action: "Sign an operating mode that lets your chat app approve", routes: ["/mode/sign"], select: { field: "chat-approve", value: "1" }, form: "mode", field: "token", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: MODE_TERMS },
+    // Credential acts: a password typed now or a one-use re-check; never Passwordless.
+    { id: "passwordless-on", action: "Turn Passwordless on", routes: ["/settings/passwordless"], form: "passwordless", field: "password", proof: "credential", when: "only to turn it on (off needs nothing)", ...CREDENTIAL, role: "operator", secrets: [], terms: [] },
+    { id: "sign-in", action: "Change sign-in (SSO)", routes: ["/settings/sign-in"], form: "signIn", field: "password", proof: "credential", when: "every action except Test", ...CREDENTIAL, role: "operator", secrets: ["client-secret"], terms: [] },
+    { id: "release-approval", action: "Approve releases automatically", routes: ["/settings/release-approval"], form: "releaseApproval", field: "password", proof: "credential", when: "only to approve automatically (Ask me needs nothing)", ...CREDENTIAL, role: "approver", handlerRole: "an approver of the project", secrets: [], terms: ["repo"] },
+    { id: "project-network", action: "Change what builds may reach", routes: ["/settings/project/network"], form: "projectNetwork", field: "password", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo"] },
+    { id: "project-writes", action: "Change where builds may write", routes: ["/settings/project/writes"], form: "projectWrites", field: "password", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo"] },
+    { id: "project-sandbox", action: "Change a project's sandbox", routes: ["/settings/project/sandbox"], form: "projectSandbox", field: "password", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo"] },
+    { id: "project-check-access", action: "Narrow how far checks reach", routes: ["/settings/project/check-access"], form: "projectCheckAccess", field: "password", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo"], note: "for a form that can only narrow; one that offers a wider level uses project-check-access-widen" },
+    { id: "project-check-access-widen", action: "Widen how far checks reach", routes: ["/settings/project/check-access"], explicit: true, form: "projectCheckAccess", field: "password", proof: "typed-now-operator", ...TYPED, role: "any", handlerRole: "an instance operator", secrets: [], terms: ["repo"], note: "the server decides whether a choice widens; a form offering any wider level asks for this proof" },
+    ...CHAT_APPS.map(([app, name, form, secrets]) => ({ id: `${app}-open`, action: `Connect or pair ${name}`, routes: [`/settings/${app}/connect`, `/settings/${app}/pair`], form, field: "password", proof: "credential", ...CREDENTIAL, role: "approver", secrets, terms: [] })),
+    { id: "sessions-token", action: "Make an API token", routes: ["/settings/sessions"], form: "sessions", field: "password", proof: "credential", when: "only to make a token (ending sessions and revoking tokens need nothing)", ...CREDENTIAL, role: "any", secrets: [], notProof: ["token"], terms: [], note: "`token` here names an API token to revoke" },
+    { id: "people-invite", action: "Invite someone", routes: ["/people/invite"], form: "peopleInvite", field: "token", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver", secrets: [], terms: [] },
+    { id: "people-projects", action: "Change a person's projects", routes: ["/people/projects"], form: "peopleProjects", field: "token", proof: "credential", ...CREDENTIAL, role: "operator", secrets: [], terms: ["name"] },
+    // A typed password, checked by the handler itself.
+    { id: "telegram-pair", action: "Pair your phone with Telegram", routes: ["/settings/telegram/pair"], form: "telegramPair", field: "password", proof: "typed-password", ...TYPED, role: "approver", secrets: [], terms: [] },
+    { id: "chat-approval-save", action: "Turn on approving from chat", routes: ["/settings/chat-approval/save"], form: "chatApproval", field: "token", proof: "typed-password", ...TYPED, role: "approver", secrets: [], terms: ["nonce", "digest", "scope", "full-access", "cap-usd"] },
+    { id: "push-subscribe", action: "Get alerts on this device", routes: ["/push/subscribe"], form: "pushSubscribe", field: "token", proof: "typed-password", ...TYPED, role: "any", handlerRole: "an approver", secrets: [], terms: ["endpoint", "p256dh", "auth"] },
+    { id: "lead-config", action: "Set up the lead's model and its own key", routes: ["/chat/config"], form: "chatConfig", field: "token", proof: "typed-password", ...TYPED, role: "any", handlerRole: "an approver", secrets: ["key"], terms: [] },
+];
+const BY_ID = new Map(PROOF_INVENTORY.map(row => [row.id, row]));
+/** One row by id; throws on an unknown id (a rendering bug, never a request's input). */
+export function proofRow(id) {
+    const row = BY_ID.get(id);
+    if (row === undefined)
+        throw new Error(`no proof inventory row ${id}`);
+    return row;
+}
+/** Whether the field a row names is one its form contract reads (used by the kit's own guard and the tests). */
+export function contractReads(row, field) {
+    return CONSOLE_FORMS[row.form].fields.includes(field);
+}

package/dist/setup-guide.js

@@ -15,8 +15,10 @@ export const ASSISTANTS = withAcp({
 export function modelChoices(provider, configured, home = homedir()) {
     // Aliases documented at https://code.claude.com/docs/en/model-config.
     let choices = provider === "claude"
-        ? [{ value: "sonnet", label: "Sonnet — everyday coding" }, { value: "opus", label: "Opus — complex tasks" },
-            { value: "haiku", label: "Haiku — smaller tasks" }]
+        // Exact ids first: Sonnet 5.5 builds routine tasks under "Sized by job" (Settings → Models); the short names float.
+        ? [{ value: "claude-sonnet-5-5", label: "Sonnet 5.5 — routine tasks" }, { value: "claude-opus-5-5", label: "Opus 5.5 — large or risky tasks" },
+            { value: "claude-haiku-5-5", label: "Haiku 5.5 — small tasks" }, { value: "sonnet", label: "Sonnet (floating) — moves to the newest version" },
+            { value: "opus", label: "Opus (floating) — moves to the newest version" }, { value: "haiku", label: "Haiku (floating) — moves to the newest version" }]
         : [];
     if (provider === "codex") {
         // Use the local CLI's own catalog, including account-specific availability.

package/dist/spend-report.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The Spend page's reader (docs/plans/spend-dashboard.md, slice 1): one row per piece of agent work in a month, with
+ * three things kept apart that today's budget sum folds together:
+ *
+ * - `billing`: what the work's own records prove about how it was billed. A machine default, a login mode or a
+ *   setting is never proof: an unproved login is `unproved`, never a confirmed subscription.
+ * - `amount`: API dollars, subscription usage or unknown, exactly as the eval collector reads it (reported-usage.ts
+ *   `runAmountOf` / `chatTurnAmountOf`, the same inputs `runAccounting` / `chatTurnAccounting` read).
+ * - `charge`: the saved amount a limit could count, with its basis (reported, settled or estimated). It is what was
+ *   saved when the work settled, never re-priced at today's catalogue, and a guessed-subscription zero is never one.
+ *
+ * Attribution follows spend.ts `spendItems`: runs at their start, a lead turn's requests at the turn's creation,
+ * everything else at its own time. Evals are read from their own tables, per invocation, and never count toward a
+ * limit. This module reads only; it changes nothing the budget gate counts.
+ */
+import type { Database } from "./store.js";
+import { type ReportedAmount } from "./reported-usage.js";
+import { type Billing } from "./spend.js";
+export type SpendSource = "run" | "chat" | "lead" | "subagent" | "draft" | "sort" | "eval";
+export type SpendRole = "builder" | "repair" | "planner" | "reviewer" | "scout" | "lead" | "chat" | "subagent" | "flow" | "evals";
+/** What the work's own records prove about its billing. */
+export type BillingEvidence = Billing | "unproved";
+export type ChargeBasis = "reported" | "settled" | "estimated";
+export type SpendCharge = {
+    microusd: number;
+    basis: ChargeBasis;
+};
+export type SpendRow = {
+    /** The record behind the row, as `table:id` (run:12, chat_turn:5, mate_turn:3, eval_invocation:9, ...). */
+    ref: string;
+    at: string;
+    source: SpendSource;
+    role: SpendRole;
+    project: string | null;
+    person: string | null;
+    subagent: number | null;
+    taskId: string | null;
+    runId: number | null;
+    provider: string;
+    modelChosen: string | null;
+    modelReported: string | null;
+    billing: BillingEvidence;
+    /** Null only for a lead turn's held reservation beyond its requests' own charges (a saved charge, no request). */
+    amount: ReportedAmount | null;
+    charge: SpendCharge | null;
+};
+/** Every piece of work in [from, to), one row each. */
+export declare function spendRows(db: Database, from: string, to: string): SpendRow[];
+/** One line of a breakdown: the three amounts kept apart. */
+export type SpendLine = {
+    key: string;
+    count: number;
+    apiMicrousd: number;
+    /** Subscription usage the providers reported (at API prices), and how many subscription pieces reported none. */
+    usageMicrousd: number;
+    usageUnreported: number;
+    usageCount: number;
+    unknown: number;
+    /** By model: how each piece chose the model it ran on ("opus", the exact id), sorted; empty elsewhere. */
+    chosen: string[];
+    /** Saved charges on work that isn't measured API dollars (estimates). */
+    estimatedMicrousd: number;
+};
+export type SpendReport = {
+    totals: SpendLine;
+    byProject: SpendLine[];
+    byModel: SpendLine[];
+    byRole: SpendLine[];
+    byPerson: SpendLine[];
+    /** The runs with the most API dollars, biggest first. */
+    topRuns: {
+        runId: number;
+        taskId: string;
+        role: SpendRole;
+        project: string | null;
+        provider: string;
+        model: string;
+        microusd: number;
+    }[];
+};
+/** The model a row ran on, in words: the reported model; a floating choice beside what it ran as (no verdict); the
+ * chosen model "not reported" when the provider said nothing. */
+export declare function modelLabel(row: Pick<SpendRow, "modelChosen" | "modelReported">): string;
+/** The month's totals, breakdowns and most expensive runs, from `spendRows`. Pure. */
+export declare function spendReport(rows: readonly SpendRow[], top?: number): SpendReport;
+/** One CSV row per piece of work, the same rows the page adds up. */
+export declare function spendReportCsv(rows: readonly SpendRow[], subagentNames: Map<number, string>): string;

package/dist/spend-report.js

@@ -0,0 +1,265 @@
+import { chatTurnAmountOf, reportedCostUsdOf, runAmountOf } from "./reported-usage.js";
+import { filersOf, subagentFilers } from "./spend.js";
+const RUN_ROLES = new Set(["builder", "repair", "planner", "reviewer", "scout"]);
+const DIRECT_CHAT = new Set(["anthropic-api", "openrouter-api"]);
+const text = (value) => value === null || value === undefined ? null : String(value);
+const count = (value) => value === null || value === undefined ? null : Number(value);
+const micro = (value) => {
+    const n = count(value);
+    return n !== null && Number.isSafeInteger(n) && n >= 0 ? n : null;
+};
+const usdMicro = (value) => {
+    const usd = reportedCostUsdOf(typeof value === "number" ? value : value === null || value === undefined ? null : Number(value));
+    return usd === null ? null : Math.round(usd * 1_000_000);
+};
+/** A charge on work that isn't measured API dollars must be a positive saved amount; a zero there proves nothing. */
+const chargeOf = (amount, microusd, basis) => microusd === null || (amount?.kind !== "api" && microusd <= 0) ? null : { microusd, basis };
+/** Every piece of work in [from, to), one row each. */
+export function spendRows(db, from, to) {
+    const rows = [];
+    const subagentOf = subagentFilers(db);
+    const filerOf = filersOf(db);
+    // A task's project as its newest record names it. task_ref's index leads with its backend, so the lookup walks the
+    // few backends (each step an index seek) instead of scanning every task, once per task.
+    const backends = db.prepare(`WITH RECURSIVE b(x) AS (SELECT (SELECT MIN(backend) FROM task_ref) UNION ALL SELECT (SELECT MIN(backend) FROM task_ref WHERE backend > b.x) FROM b WHERE b.x IS NOT NULL)
+    SELECT x FROM b WHERE x IS NOT NULL`).all().map(row => String(row["x"]));
+    const repoOfTask = backends.length === 0 ? null
+        : db.prepare(`SELECT repo FROM task_ref WHERE backend IN (${backends.map(() => "?").join(", ")}) AND external_id = ? ORDER BY id DESC LIMIT 1`);
+    const taskRepos = new Map();
+    const taskRepo = (taskId) => {
+        if (!taskRepos.has(taskId))
+            taskRepos.set(taskId, repoOfTask === null ? null : text(repoOfTask.get(...backends, taskId)?.["repo"]));
+        return taskRepos.get(taskId) ?? null;
+    };
+    // Runs: the columns runAccounting reads, with their task's project and filer.
+    for (const row of db.prepare(`SELECT run.id, run.task_ref, run.role, run.provider, run.model, run.model_reported, run.cost_usd, run.started_at, run.billing_basis, run.cost_unknown,
+      r.external_id AS task, r.repo, r.filed_by, r.filed_by_kind, r.revision_of, s.microusd, s.source, s.billing
+    FROM run JOIN task_ref r ON r.id = run.task_ref LEFT JOIN run_spend s ON s.run = run.id
+    WHERE run.started_at >= ? AND run.started_at < ? ORDER BY run.id`).all(from, to)) {
+        const settledBilling = row["billing"] === "subscription" || row["billing"] === "api-key" ? row["billing"] : null;
+        const basis = row["billing_basis"] === "evidence" || row["billing_basis"] === "default" ? row["billing_basis"] : null;
+        const costUnknown = Number(row["cost_unknown"] ?? 1) !== 0;
+        const amount = runAmountOf({ billing: settledBilling, spendMicrousd: count(row["microusd"]), costUsd: count(row["cost_usd"]), basis, costUnknown });
+        // Only the run's own evidence proves its billing; a guess (`default`) or no basis at all is unproved.
+        const billing = basis === "evidence" && settledBilling !== null ? settledBilling : "unproved";
+        let charge = null;
+        if (billing !== "subscription") {
+            const settled = micro(row["microusd"]);
+            if (settled !== null && (row["source"] === "reported" || row["source"] === "estimated")) {
+                // A run whose cost wasn't reported holds its cap in cost_usd, settled as "reported": that is a conservative estimate.
+                charge = chargeOf(amount, settled, billing === "unproved" || costUnknown || row["source"] === "estimated" ? "estimated" : "reported");
+            }
+            else {
+                charge = chargeOf(amount, usdMicro(row["cost_usd"]), "estimated");
+            }
+        }
+        const filer = row["filed_by"] == null && row["revision_of"] != null ? filerOf(Number(row["task_ref"]))
+            : { repo: text(row["repo"]), filedBy: text(row["filed_by"]), kind: text(row["filed_by_kind"]) };
+        const role = String(row["role"]);
+        rows.push({
+            ref: `run:${Number(row["id"])}`, at: String(row["started_at"]), source: "run", role: RUN_ROLES.has(role) ? role : "builder",
+            project: text(row["repo"]), person: filer.kind === "person" || filer.kind === "coordinator" ? filer.filedBy : null,
+            subagent: subagentOf(filer.repo, filer.filedBy, filer.kind), taskId: String(row["task"]), runId: Number(row["id"]),
+            provider: String(row["provider"]), modelChosen: text(row["model"]), modelReported: text(row["model_reported"]), billing, amount, charge,
+        });
+    }
+    // One chat request (fleet chat, or one request of a lead turn), as chatTurnAccounting reads it.
+    const chatRequest = (row) => {
+        const provider = String(row["provider"]);
+        const reportedCostUsd = count(row["reported_cost_usd"]);
+        const billingReported = row["billing_reported"] === "subscription" || row["billing_reported"] === "api-key" ? row["billing_reported"] : null;
+        const unknownSpend = Number(row["unknown_spend"]) === 1;
+        const amount = chatTurnAmountOf({ provider, settledMicrousd: count(row["settled_microusd"]), unknownSpend, reportedCostUsd, billingReported });
+        if (DIRECT_CHAT.has(provider)) {
+            // Toolroll sent its own key: billed to it. The settlement is the charge (a held reservation when the cost is unknown).
+            return { amount, billing: "api-key", charge: chargeOf(amount, micro(row["settled_microusd"]), unknownSpend ? "estimated" : "settled") };
+        }
+        // A subscription harness settles at zero whatever it billed; its own events are the evidence.
+        const billing = billingReported ?? "unproved";
+        const reported = usdMicro(reportedCostUsd);
+        return { amount, billing, charge: billing === "subscription" ? null : chargeOf(amount, reported, billing === "api-key" ? "reported" : "estimated") };
+    };
+    for (const row of db.prepare(`SELECT id, created_at, approver, provider, model, model_reported, settled_microusd, unknown_spend, reported_cost_usd, billing_reported
+      FROM chat_turn WHERE mate_turn IS NULL AND created_at >= ? AND created_at < ? ORDER BY id`).all(from, to)) {
+        const request = chatRequest(row);
+        rows.push({ ref: `chat_turn:${Number(row["id"])}`, at: String(row["created_at"]), source: "chat", role: "chat", project: null, person: text(row["approver"]), subagent: null,
+            taskId: null, runId: null, provider: String(row["provider"]), modelChosen: text(row["model"]), modelReported: text(row["model_reported"]), ...request });
+    }
+    // A lead turn: each request at the turn's creation, and whatever the turn settled beyond its requests' charges (a held
+    // reservation) once, as an estimate attributed to the turn.
+    const turns = new Map();
+    // The month's turns (mate_turn_created), each thread by its key; a task thread's project resolved once per task.
+    let until = null;
+    for (const row of db.prepare(`SELECT t.id, t.created_at, t.approver, t.settled_microusd, th.scope_kind, th.scope_key,
+        MAX(t.deadline_at, COALESCE(t.finished_at, t.created_at), t.created_at) AS until
+      FROM mate_turn t LEFT JOIN lead_thread th ON th.id = t.thread WHERE t.created_at >= ? AND t.created_at < ? ORDER BY t.id`).all(from, to)) {
+        const project = row["scope_kind"] === "project" ? text(row["scope_key"]) : row["scope_kind"] === "task" && row["scope_key"] != null ? taskRepo(String(row["scope_key"])) : null;
+        turns.set(Number(row["id"]), { at: String(row["created_at"]), person: text(row["approver"]), project, settled: micro(row["settled_microusd"]), provider: null, model: null, charged: 0, unknown: false });
+        if (until === null || String(row["until"]) > until)
+            until = String(row["until"]);
+    }
+    // Their requests: written after their turn began and before it ended or ran out of time, so a bounded range of
+    // chat_turn_created (an hour's margin either side) holds every one; each is kept only when its turn is this month's.
+    const stepsFrom = new Date(Date.parse(from) - 3_600_000).toISOString();
+    const stepsUntil = until === null ? from : new Date(Date.parse(until) + 3_600_000).toISOString();
+    for (const row of until === null ? [] : db.prepare(`SELECT c.id, c.mate_turn AS turn, c.provider, c.model, c.model_reported, c.settled_microusd, c.unknown_spend, c.reported_cost_usd, c.billing_reported
+      FROM chat_turn c WHERE c.created_at >= ? AND c.created_at < ? AND c.mate_turn IS NOT NULL ORDER BY c.mate_turn, c.id`).all(stepsFrom, stepsUntil)) {
+        const turn = turns.get(Number(row["turn"]));
+        if (turn === undefined)
+            continue;
+        const request = chatRequest(row);
+        turn.provider ??= String(row["provider"]);
+        turn.model ??= text(row["model"]);
+        turn.charged += micro(row["settled_microusd"]) ?? 0;
+        if (request.amount.kind === "unknown")
+            turn.unknown = true;
+        rows.push({ ref: `chat_turn:${Number(row["id"])}`, at: turn.at, source: "lead", role: "lead", project: turn.project, person: turn.person, subagent: null,
+            taskId: null, runId: null, provider: String(row["provider"]), modelChosen: text(row["model"]), modelReported: text(row["model_reported"]), ...request });
+    }
+    for (const [id, turn] of turns) {
+        const held = turn.settled === null ? 0 : turn.settled - turn.charged;
+        if (held <= 0)
+            continue;
+        // The turn's uncertainty is counted once: by its unknown request when it has one, otherwise by this row.
+        const amount = turn.unknown ? null : { kind: "unknown" };
+        rows.push({ ref: `mate_turn:${id}`, at: turn.at, source: "lead", role: "lead", project: turn.project, person: turn.person, subagent: null, taskId: null, runId: null,
+            provider: turn.provider ?? "lead", modelChosen: turn.model, modelReported: null, billing: "api-key", amount, charge: { microusd: held, basis: "estimated" } });
+    }
+    // A subagent's turns and a flow's drafts run on this computer's Claude sign-in with no key from Toolroll: their billing
+    // stamp is a machine default, so it is unproved, and a cost they report is an estimate.
+    for (const row of db.prepare(`SELECT t.id, t.at, t.subagent, t.model, t.cost_usd, m.repo FROM subagent_turn t JOIN subagent m ON m.id = t.subagent
+      WHERE t.at >= ? AND t.at < ? ORDER BY t.id`).all(from, to)) {
+        const amount = { kind: "unknown" };
+        rows.push({ ref: `subagent_turn:${Number(row["id"])}`, at: String(row["at"]), source: "subagent", role: "subagent", project: text(row["repo"]), person: null,
+            subagent: Number(row["subagent"]), taskId: null, runId: null, provider: "claude", modelChosen: text(row["model"]), modelReported: null, billing: "unproved",
+            amount, charge: chargeOf(amount, usdMicro(row["cost_usd"]), "estimated") });
+    }
+    for (const row of db.prepare("SELECT id, at, repo, provider, model, cost_usd FROM side_spend WHERE at >= ? AND at < ? ORDER BY id").all(from, to)) {
+        const amount = { kind: "unknown" };
+        rows.push({ ref: `side_spend:${Number(row["id"])}`, at: String(row["at"]), source: "draft", role: "flow", project: text(row["repo"]), person: null, subagent: null,
+            taskId: null, runId: null, provider: String(row["provider"]), modelChosen: text(row["model"]), modelReported: null, billing: "unproved",
+            amount, charge: chargeOf(amount, usdMicro(row["cost_usd"]), "estimated") });
+    }
+    // A flow's Sort step asks Jev on OpenRouter with Toolroll's key: its reported cost, or unknown.
+    for (const row of db.prepare(`SELECT fs.card, fs.entry, fs.stage, fs.started_at AS at, json_extract(fs.decision_json, '$.cost') AS cost, json_extract(fs.decision_json, '$.model') AS model, f.repo
+      FROM flow_step_run fs JOIN flow_card c ON c.id = fs.card JOIN flow f ON f.id = c.flow
+      WHERE fs.kind = 'sort' AND fs.decision_json IS NOT NULL AND fs.started_at >= ? AND fs.started_at < ? ORDER BY fs.started_at, fs.card, fs.entry`).all(from, to)) {
+        const cost = typeof row["cost"] === "number" ? usdMicro(row["cost"]) : null;
+        const amount = cost === null ? { kind: "unknown" } : { kind: "api", microusd: cost };
+        rows.push({ ref: `flow_step_run:${Number(row["card"])}:${Number(row["entry"])}:${String(row["stage"])}`, at: String(row["at"]), source: "sort", role: "flow", project: text(row["repo"]), person: null, subagent: null,
+            taskId: null, runId: null, provider: "openrouter", modelChosen: text(row["model"]), modelReported: null, billing: "api-key", amount, charge: chargeOf(amount, cost, "reported") });
+    }
+    // Evals, from their own records: one row per provider invocation, kinds kept apart; a campaign whose spending was
+    // left unknown adds one unknown. Never counted toward a limit, so never a charge.
+    // The month's attempts first, then each one's invocations through their (attempt, world_ref) key.
+    for (const row of db.prepare(`SELECT i.id, i.amount, i.api_microusd, i.subscription_microusd, i.model_reported, a.started_at, a.model_pinned, c.started_by
+      FROM eval_attempt a CROSS JOIN eval_invocation i ON i.attempt = a.id JOIN eval_campaign c ON c.id = a.campaign
+      WHERE a.started_at >= ? AND a.started_at < ? ORDER BY i.id`).all(from, to)) {
+        const api = micro(row["api_microusd"]);
+        const subscription = micro(row["subscription_microusd"]);
+        const amount = row["amount"] === "api" && api !== null ? { kind: "api", microusd: api }
+            : row["amount"] === "subscription" ? { kind: "subscription", reportedUsd: subscription === null ? null : subscription / 1_000_000 } : { kind: "unknown" };
+        rows.push({ ref: `eval_invocation:${Number(row["id"])}`, at: String(row["started_at"]), source: "eval", role: "evals", project: null, person: text(row["started_by"]), subagent: null,
+            taskId: null, runId: null, provider: "evals", modelChosen: text(row["model_pinned"]), modelReported: text(row["model_reported"]),
+            billing: row["amount"] === "api" ? "api-key" : row["amount"] === "subscription" ? "subscription" : "unproved", amount, charge: null });
+    }
+    for (const row of db.prepare("SELECT id, admitted_at, started_by FROM eval_campaign WHERE spending_unknown = 1 AND admitted_at >= ? AND admitted_at < ? ORDER BY admitted_at, id").all(from, to)) {
+        rows.push({ ref: `eval_campaign:${String(row["id"])}`, at: String(row["admitted_at"]), source: "eval", role: "evals", project: null, person: text(row["started_by"]), subagent: null,
+            taskId: null, runId: null, provider: "evals", modelChosen: null, modelReported: null, billing: "unproved", amount: { kind: "unknown" }, charge: null });
+    }
+    return rows;
+}
+const empty = (key) => ({ key, count: 0, apiMicrousd: 0, usageMicrousd: 0, usageUnreported: 0, usageCount: 0, unknown: 0, chosen: [], estimatedMicrousd: 0 });
+function add(line, row) {
+    line.count++;
+    const amount = row.amount;
+    if (amount?.kind === "api")
+        line.apiMicrousd += amount.microusd;
+    else if (row.charge !== null)
+        line.estimatedMicrousd += row.charge.microusd;
+    if (amount?.kind === "subscription") {
+        line.usageCount++;
+        if (amount.reportedUsd === null)
+            line.usageUnreported++;
+        else
+            line.usageMicrousd += Math.round(amount.reportedUsd * 1_000_000);
+    }
+    if (amount?.kind === "unknown")
+        line.unknown++;
+}
+/** A floating choice (an alias such as `opus`, or the CLI's default) names no version: it has no digit. */
+const floating = (model) => !/\d/.test(model);
+/** The model a row ran on, in words: the reported model; a floating choice beside what it ran as (no verdict); the
+ * chosen model "not reported" when the provider said nothing. */
+export function modelLabel(row) {
+    const chosen = row.modelChosen === null || row.modelChosen === "" ? null : row.modelChosen;
+    if (row.modelReported === null)
+        return `${chosen ?? "default"} (not reported)`;
+    if (chosen === null || chosen === row.modelReported)
+        return row.modelReported;
+    return floating(chosen) ? `floating choice ${chosen} → ${row.modelReported}` : `${row.modelReported} (chose ${chosen})`;
+}
+/** What a row ran on, for grouping: the reported model; the chosen one, "not reported", when the provider said nothing. */
+const ranOn = (row) => `${row.provider} · ${row.modelReported ?? `${row.modelChosen === null || row.modelChosen === "" ? "default" : row.modelChosen} (not reported)`}`;
+/** The model breakdown, grouped by the model the work ran on; how it was chosen is detail on the line. */
+function byModel(rows) {
+    const lines = new Map();
+    for (const row of rows) {
+        const key = ranOn(row);
+        const line = lines.get(key) ?? empty(key);
+        add(line, row);
+        const chosen = row.modelChosen === null || row.modelChosen === "" ? "default" : row.modelChosen;
+        if (row.modelReported !== null && chosen !== row.modelReported && !line.chosen.includes(chosen))
+            line.chosen = [...line.chosen, chosen].sort();
+        lines.set(key, line);
+    }
+    return sortLines([...lines.values()]);
+}
+const sortLines = (lines) => lines.sort((a, b) => b.apiMicrousd - a.apiMicrousd || b.estimatedMicrousd - a.estimatedMicrousd || b.usageMicrousd - a.usageMicrousd || b.count - a.count || a.key.localeCompare(b.key));
+/** The month's totals, breakdowns and most expensive runs, from `spendRows`. Pure. */
+export function spendReport(rows, top = 10) {
+    const totals = empty("");
+    const by = (keyOf) => {
+        const lines = new Map();
+        for (const row of rows) {
+            const key = keyOf(row);
+            if (key === null)
+                continue;
+            const line = lines.get(key) ?? empty(key);
+            add(line, row);
+            lines.set(key, line);
+        }
+        return sortLines([...lines.values()]);
+    };
+    for (const row of rows)
+        add(totals, row);
+    const topRuns = rows.filter(row => row.source === "run" && row.amount?.kind === "api" && row.runId !== null && row.taskId !== null)
+        .map(row => ({ runId: row.runId, taskId: row.taskId, role: row.role, project: row.project, provider: row.provider, model: modelLabel(row), microusd: row.amount.microusd }))
+        .sort((a, b) => b.microusd - a.microusd || b.runId - a.runId).slice(0, top);
+    return {
+        totals,
+        byProject: by(row => row.project),
+        byModel: byModel(rows),
+        byRole: by(row => row.role),
+        byPerson: by(row => row.person),
+        topRuns,
+    };
+}
+/** One CSV row per piece of work, the same rows the page adds up. */
+export function spendReportCsv(rows, subagentNames) {
+    const cell = (value) => {
+        const value_ = value === null || value === undefined ? "" : String(value);
+        const safe = /^[=+\-@\t\r]/.test(value_) ? `'${value_}` : value_;
+        return /[",\n\r]/.test(safe) ? `"${safe.replace(/"/g, '""')}"` : safe;
+    };
+    const dollars = (microusd) => microusd === null ? null : (microusd / 1_000_000).toFixed(6);
+    const head = ["time_utc", "source", "role", "project", "person", "subagent", "task", "run", "provider", "model", "model_reported", "billing", "amount_kind", "api_usd", "usage_usd", "charge_usd", "charge_basis"];
+    const lines = rows.map(row => [
+        row.at, row.source, row.role, row.project, row.person, row.subagent === null ? null : subagentNames.get(row.subagent) ?? row.subagent, row.taskId, row.runId,
+        row.provider, row.modelChosen, row.modelReported, row.billing, row.amount?.kind ?? "held",
+        row.amount?.kind === "api" ? dollars(row.amount.microusd) : null,
+        row.amount?.kind === "subscription" && row.amount.reportedUsd !== null ? row.amount.reportedUsd.toFixed(6) : null,
+        dollars(row.charge?.microusd ?? null), row.charge?.basis ?? null,
+    ].map(cell).join(","));
+    return `${head.join(",")}\r\n${lines.map(line => `${line}\r\n`).join("")}`;
+}

package/dist/spend-ui.d.ts

@@ -1,17 +1,33 @@
 /**
- * The Spend page (v105): what agent work cost this month, where it went, and
- * the monthly budgets that alert at 50/80/100 % and (unless set to alert
- * only) stop new work at 100 %. An instance operator's page; budgets change
- * with a step-up.
+ * The Spend page (docs/plans/spend-dashboard.md, slice 1): what agent work cost this month, with API dollars, plan
+ * usage and unknown cost kept apart and never added together, broken down by project, model, role and person, the
+ * runs that cost most, and what isn't recorded here. An instance operator's page. Monthly limits show read-only here
+ * and change on Settings → Spend, with a step-up.
  */
 import { type Html } from "./html.js";
 import { type BudgetState, type SpendItem } from "./spend.js";
+import type { SpendReport } from "./spend-report.js";
 export declare const SPEND_CSS: string;
+/** What this page doesn't record, in plain words (docs/plans/spend-dashboard.md §2.2). */
+export declare const NOT_COUNTED: readonly string[];
 export type SpendView = {
     month: string;
     previous: string;
     next: string | null;
-    items: SpendItem[];
+    report: SpendReport;
+    /** This month's limits; null for a past month (a limit is this month's). */
+    budgets: BudgetState[] | null;
+    /** The plan windows as their providers last reported them (limits-ui.ts), or nothing. */
+    windows: Html;
+    subagentNames: Map<number, string>;
+};
+/** Dollars for the page: a positive amount under a cent reads "<$0.01", never a false $0. */
+export declare const money: (microusd: number) => string;
+export declare function spendHtml(view: SpendView, notice: {
+    said?: string | null;
+    problem?: string | null;
+}): Html;
+export type SpendSettingsView = {
     budgets: BudgetState[];
     targets: {
         value: string;
@@ -19,11 +35,16 @@ export type SpendView = {
         group: "Everything" | "Projects" | "People" | "Subagents";
     }[];
     subagentNames: Map<number, string>;
-    csrf: string;
+    /** Each role's model at the installation, in words. */
+    models: {
+        role: string;
+        model: string;
+    }[];
 };
-export declare function spendHtml(view: SpendView, notice: {
+/** Settings → Spend: the monthly limits editor (moved from the Spend page) and a summary of the models in use. */
+export declare function spendSettingsHtml(view: SpendSettingsView, notice: {
     said?: string | null;
     problem?: string | null;
 }): Html;
-/** One row per piece of spend, for a spreadsheet. */
+/** One row per piece of spend, for a spreadsheet (the command line's `spend --csv`). */
 export declare function spendCsv(items: readonly SpendItem[], subagentNames: Map<number, string>): string;