toolroll 0.9.45 → 0.9.47

package/dist/remote-audit.d.ts

@@ -0,0 +1,79 @@
+import type { ApiTokenRow, Store } from "./store.js";
+export declare const AUDIT_SOURCES: readonly ["api", "mcp"];
+export type AuditSource = typeof AUDIT_SOURCES[number];
+export type AuditOutcome = "ok" | "refused" | "error";
+export declare const AUDIT_LIMIT: {
+    readonly default: 20;
+    readonly max: 100;
+};
+export type AuditFilters = {
+    person: string | null;
+    token: string | null;
+    source: AuditSource | null;
+    since: string | null;
+};
+/** One remote action. `kind` says whether a person's CLI ran a command or their agent called a tool over MCP. */
+export type AuditAction = {
+    id: number;
+    at: string;
+    person: string;
+    token: string | null;
+    source: AuditSource;
+    kind: "command" | "tool";
+    /** The command row (`task show`), or for a tool call the tool's name when the line recorded it. */
+    name: string;
+    command: string;
+    tool: string | null;
+    repo: string | null;
+    taskId: string | null;
+    outcome: AuditOutcome;
+    /** A refusal's stable reason (`read-only`, `not-found`, ...), never free text. */
+    reason: string | null;
+};
+/**
+ * Who is reading. `self` null: the machine's own owner, reading the database here. Otherwise a person:
+ * `everyone` when they approve; `repos` their project ceiling (null: every project); `unplaced` whether lines in no
+ * project (refused before a project was known) are theirs to see for other people.
+ */
+export type AuditReader = {
+    self: string | null;
+    everyone: boolean;
+    repos: readonly string[] | null;
+    unplaced: boolean;
+};
+export declare const OWNER_READER: AuditReader;
+export type AuditPage = {
+    ok: true;
+    actions: AuditAction[];
+    nextCursor: string | null;
+    limit: number;
+} | {
+    ok: false;
+    reason: "not-found";
+    message: string;
+};
+/** The old final words, in the vocabulary people read. Anything unrecognized reads as an error, never as ok. */
+export declare function auditOutcome(outcome: string): AuditOutcome | null;
+/** `7d` → the instant that many days before `now`; null for anything else (no zero, sign, fraction or other unit). */
+export declare function sinceOf(value: string, now: Date): string | null;
+export declare const cursorOf: (value: string) => number | null;
+/**
+ * A line's token, tool and reason. The detail is `token <name>` then ` · `-separated parts: the token name is the
+ * longest of this person's token names (or ids, for a line written before the token was proved) that matches up to a
+ * separator, since a name may itself contain ` · `. Unmatched text is never echoed.
+ */
+export declare function readDetail(detail: string | null, tokens: readonly Pick<ApiTokenRow, "id" | "name">[]): {
+    token: string | null;
+    tool: string | null;
+    reason: string | null;
+};
+/**
+ * One page of remote actions, newest first, keyed by entry id so new lines never shift an older page. The reader's
+ * visibility and every filter are applied before the page is cut; the token filter is an exact name match.
+ */
+export declare function remoteAudit(store: Store, reader: AuditReader, filters: AuditFilters, page?: {
+    limit?: number;
+    before?: number | null;
+}): AuditPage;
+/** A token's standing, for People. */
+export declare function tokenStatus(token: Pick<ApiTokenRow, "revokedAt" | "expiresAt">, now: Date): "active" | "expired" | "revoked";

package/dist/remote-audit.js

@@ -0,0 +1,161 @@
+/**
+ * Remote activity (phase 3, docs/plans/remote-team.md): what people did on this server with their API tokens, read
+ * from the action history runOperateAs already writes — one `requested` line when a command starts, and a final line
+ * (`done`, `refused`, `usage`, `failed`) when it ends or is refused. The history is append-only and sealed, so old
+ * words are never rewritten: this projection maps them to `ok`, `refused` and `error` as it reads, and leaves out the
+ * `requested` lines. It never shows a line's raw detail; the token's name, an MCP tool and a refusal reason are
+ * recovered from it by exact match.
+ *
+ * Who sees what is decided inside the query, before a page is cut: the machine's owner (a local run) sees everyone;
+ * an approver sees everyone within their project ceiling and all of their own lines; a viewer sees only their own.
+ * Another person the reader may not see answers exactly like a person who doesn't exist.
+ */
+import { IN_RANGE } from "./ledger-chain.js";
+export const AUDIT_SOURCES = ["api", "mcp"];
+export const AUDIT_LIMIT = { default: 20, max: 100 };
+const SINCE_MAX_DAYS = 3650;
+export const OWNER_READER = Object.freeze({ self: null, everyone: true, repos: null, unplaced: true });
+/** The old final words, in the vocabulary people read. Anything unrecognized reads as an error, never as ok. */
+export function auditOutcome(outcome) {
+    if (outcome === "requested")
+        return null;
+    if (outcome === "done")
+        return "ok";
+    if (outcome === "refused" || outcome === "usage")
+        return "refused";
+    return "error";
+}
+/** `7d` → the instant that many days before `now`; null for anything else (no zero, sign, fraction or other unit). */
+export function sinceOf(value, now) {
+    const match = /^([1-9][0-9]{0,3})d$/.exec(value);
+    if (match === null || Number(match[1]) > SINCE_MAX_DAYS)
+        return null;
+    return new Date(now.getTime() - Number(match[1]) * 86_400_000).toISOString();
+}
+export const cursorOf = (value) => /^[1-9][0-9]{0,15}$/.test(value) && Number.isSafeInteger(Number(value)) ? Number(value) : null;
+const REASON = /^[a-z][a-z0-9-]{0,40}$/;
+const TOOL = /^[a-z][a-z0-9_]{0,40}$/;
+const COMMAND = "remote command: ";
+/**
+ * A line's token, tool and reason. The detail is `token <name>` then ` · `-separated parts: the token name is the
+ * longest of this person's token names (or ids, for a line written before the token was proved) that matches up to a
+ * separator, since a name may itself contain ` · `. Unmatched text is never echoed.
+ */
+export function readDetail(detail, tokens) {
+    const none = { token: null, tool: null, reason: null };
+    if (detail === null || !detail.startsWith("token "))
+        return none;
+    const body = detail.slice("token ".length);
+    let token = null, rest = "", matched = -1;
+    for (const one of tokens) {
+        for (const label of [one.name, one.id]) {
+            if ((body === label || body.startsWith(`${label} · `)) && label.length > matched) {
+                token = one.name;
+                rest = body.slice(label.length);
+                matched = label.length;
+            }
+        }
+    }
+    if (token === null)
+        return none;
+    let tool = null, reason = null;
+    for (const part of rest.split(" · ").slice(1)) {
+        if (part.startsWith("tool ") && TOOL.test(part.slice(5)))
+            tool = part.slice(5);
+        else if (REASON.test(part))
+            reason ??= part;
+    }
+    return { token, tool, reason };
+}
+/**
+ * One page of remote actions, newest first, keyed by entry id so new lines never shift an older page. The reader's
+ * visibility and every filter are applied before the page is cut; the token filter is an exact name match.
+ */
+export function remoteAudit(store, reader, filters, page = {}) {
+    const notFound = { ok: false, reason: "not-found", message: "Not found." };
+    const limit = Math.max(1, Math.min(AUDIT_LIMIT.max, Math.trunc(page.limit ?? AUDIT_LIMIT.default)));
+    if (filters.person !== null) {
+        if (store.accountOf(filters.person) === null)
+            return notFound;
+        if (reader.self !== null && !reader.everyone && filters.person !== reader.self)
+            return notFound;
+    }
+    const clauses = ["source IN ('api','mcp')", "outcome <> 'requested'", `action LIKE '${COMMAND}%'`];
+    const args = [];
+    if (reader.self !== null) {
+        if (!reader.everyone) {
+            clauses.push("actor = ?");
+            args.push(reader.self);
+        }
+        else if (reader.repos !== null || !reader.unplaced) {
+            const placed = reader.repos === null ? "repo IS NOT NULL" : reader.repos.length === 0 ? "0" : `repo IN (${reader.repos.map(() => "?").join(",")})`;
+            clauses.push(`(actor = ? OR ${placed}${reader.unplaced ? " OR repo IS NULL" : ""})`);
+            args.push(reader.self, ...(reader.repos ?? []));
+        }
+    }
+    if (filters.person !== null) {
+        clauses.push("actor = ?");
+        args.push(filters.person);
+    }
+    if (filters.source !== null) {
+        clauses.push("source = ?");
+        args.push(filters.source);
+    }
+    if (filters.since !== null) {
+        clauses.push("at >= ?");
+        args.push(filters.since);
+    }
+    const tokens = new Map();
+    for (const one of store.apiTokens(null))
+        tokens.set(one.account, [...(tokens.get(one.account) ?? []), one]);
+    if (filters.token !== null) {
+        // Narrow by every label a line for this name could start with; the exact owner of the line is decided below.
+        const labels = [...new Set([...tokens.values()].flat().filter(one => one.name === filters.token).flatMap(one => [one.name, one.id]))];
+        if (labels.length === 0)
+            return { ok: true, actions: [], nextCursor: null, limit };
+        clauses.push(`(${labels.map(() => "(detail = ? OR substr(detail, 1, ?) = ?)").join(" OR ")})`);
+        for (const label of labels)
+            args.push(`token ${label}`, `token ${label} · `.length, `token ${label} · `);
+    }
+    const statement = store.handle.prepare(`SELECT id, at, actor, repo, task_id, action, outcome, source, detail FROM action_ledger
+    WHERE id ${IN_RANGE} AND id < ? AND ${clauses.join(" AND ")} ORDER BY id DESC LIMIT ?`);
+    const actions = [];
+    let before = page.before ?? Number.MAX_SAFE_INTEGER, more = false;
+    const batch = limit + 1;
+    while (actions.length <= limit) {
+        const rows = statement.all(before, ...args, batch);
+        for (const row of rows) {
+            before = Number(row["id"]);
+            const action = actionOf(row, tokens.get(String(row["actor"])) ?? []);
+            if (action === null || filters.token !== null && action.token !== filters.token)
+                continue;
+            if (actions.length === limit) {
+                more = true;
+                break;
+            }
+            actions.push(action);
+        }
+        if (more || rows.length < batch)
+            break;
+    }
+    return { ok: true, actions, nextCursor: more ? String(actions.at(-1).id) : null, limit };
+}
+function actionOf(row, tokens) {
+    const outcome = auditOutcome(String(row["outcome"]));
+    const source = String(row["source"]);
+    if (outcome === null || (source !== "api" && source !== "mcp"))
+        return null;
+    const command = String(row["action"]).slice(COMMAND.length);
+    const read = readDetail(row["detail"] == null ? null : String(row["detail"]), tokens);
+    const tool = source === "mcp" ? read.tool : null;
+    return {
+        id: Number(row["id"]), at: String(row["at"]), person: String(row["actor"]), token: read.token, source,
+        kind: source === "mcp" ? "tool" : "command", name: tool ?? command, command, tool,
+        repo: row["repo"] == null ? null : String(row["repo"]), taskId: row["task_id"] == null ? null : String(row["task_id"]),
+        outcome, reason: outcome === "ok" ? null : read.reason ?? (String(row["outcome"]) === "usage" ? "usage" : null),
+    };
+}
+/** A token's standing, for People. */
+export function tokenStatus(token, now) {
+    return token.revokedAt !== null ? "revoked" : Date.parse(token.expiresAt) <= now.getTime() ? "expired" : "active";
+}

package/dist/request-budget-ui.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Settings → Sessions & tokens: each token's request limits in its line, and — for an instance operator — one
+ * disclosure to change them for everyone's tokens or for one token (request-budget.ts). Saving takes the operator's
+ * password (or a fresh identity-provider sign-in), in a browser only.
+ */
+import type { ApiTokenRow, Database } from "./store.js";
+export declare const REQUEST_LIMITS_CSS: string;
+/** "120 requests a minute · 10,000 a day" for one token's line. */
+export declare function tokenLimitWords(db: Database, token: ApiTokenRow): string;
+/** The operator's disclosure: everyone's tokens, or one token. Blank fields use the default shown. */
+export declare function requestLimitsHtml(db: Database, tokens: readonly ApiTokenRow[], csrf: string, now: number): string;

package/dist/request-budget-ui.js

@@ -0,0 +1,31 @@
+import { effectiveLimits, limitOverrides, PER_DAY_MAX, PER_MINUTE_MAX, REQUEST_BUDGET_DEFAULTS } from "./request-budget.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const n = (value) => value.toLocaleString("en-US");
+export const REQUEST_LIMITS_CSS = `.credentials .limits{display:grid;gap:14px}.credentials .limits form{display:grid;gap:10px}.credentials .limits label{display:grid;gap:6px}` +
+    `.credentials .limits input,.credentials .limits select{box-sizing:border-box;width:100%;min-width:0}.credentials .limits .pair{display:grid;grid-template-columns:1fr 1fr;gap:10px}.credentials .limits .actions{display:flex;flex-wrap:wrap;gap:8px}` +
+    `.credentials .limits h3{font-size:.95rem;margin:4px 0 0}@media(max-width:600px){.credentials .limits .pair{grid-template-columns:1fr}.credentials .limits input,.credentials .limits select{font-size:16px}}`;
+/** "120 requests a minute · 10,000 a day" for one token's line. */
+export function tokenLimitWords(db, token) {
+    const limits = effectiveLimits(db, token.id, token.access);
+    return `${n(limits.perMinute)} requests a minute · ${n(limits.perDay)} a day`;
+}
+/** The operator's disclosure: everyone's tokens, or one token. Blank fields use the default shown. */
+export function requestLimitsHtml(db, tokens, csrf, now) {
+    const overrides = limitOverrides(db);
+    const everyone = overrides.get("*") ?? { readPerMinute: null, actPerMinute: null, perDay: null };
+    const field = (name, label, value, placeholder, max) => `<label>${label}<input type="number" name="${name}" min="1" max="${max}" step="1" inputmode="numeric" value="${value === null ? "" : value}" placeholder="${placeholder}"></label>`;
+    const password = `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label>`;
+    const buttons = `<div class="actions"><button name="action" value="save">Save limits</button><button class="secondary" name="action" value="clear">Use defaults</button></div>`;
+    const live = tokens.filter(one => one.revokedAt === null && Date.parse(one.expiresAt) > now);
+    const installation = `<form method="post" action="/settings/request-limits"><input type="hidden" name="csrf" value="${e(csrf)}"><input type="hidden" name="target" value="*">` +
+        `<h3>Everyone's tokens</h3><div class="pair">${field("read-per-minute", "Read tokens, a minute", everyone.readPerMinute, String(REQUEST_BUDGET_DEFAULTS.read), PER_MINUTE_MAX)}` +
+        `${field("act-per-minute", "Act tokens, a minute", everyone.actPerMinute, String(REQUEST_BUDGET_DEFAULTS.act), PER_MINUTE_MAX)}</div>` +
+        `${field("per-day", "Each token, a day", everyone.perDay, String(REQUEST_BUDGET_DEFAULTS.day), PER_DAY_MAX)}${password}${buttons}</form>`;
+    const one = live.length === 0 ? "" : `<form method="post" action="/settings/request-limits"><input type="hidden" name="csrf" value="${e(csrf)}">` +
+        `<h3>One token</h3><label>Token<select name="target">${live.map(row => {
+            const set = overrides.get(row.id);
+            return `<option value="${e(row.id)}">${e(row.name)} (${e(row.account)}, ${row.access === "act" ? "act" : "read"})${set === undefined ? "" : " · own limits"}</option>`;
+        }).join("")}</select></label>` +
+        `<div class="pair">${field("per-minute", "A minute", null, "Everyone's", PER_MINUTE_MAX)}${field("per-day", "A day", null, "Everyone's", PER_DAY_MAX)}</div>${password}${buttons}</form>`;
+    return `<details class="card"><summary>Request limits</summary><div class="limits">${installation}${one}</div></details>`;
+}

package/dist/request-budget.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Request budgets for person API tokens (v112): how many requests one `so_` token may make to `/api/cli` and `/mcp`.
+ * One budget per token, keyed by its api_token row id (never the secret, its name or an address), shared by both
+ * routes. A read token gets 120 requests in any sliding minute, an act token 30, and either 10,000 in a rolling day;
+ * an instance operator may override any of these for the installation or for one token in the console (step-up).
+ *
+ * The token's saved access decides its class: nothing in a request body moves it. A request is counted once when it
+ * is admitted, however long it then holds the server (a task wait long-poll is one request, not one per second).
+ * Over budget answers 429 with Retry-After; the first refusal in each exhausted window is ledgered, never each one.
+ *
+ * Tracking is in memory and bounded: at most TRACKED_TOKENS tokens (least recently used goes first, saved before it
+ * goes), each with at most PER_MINUTE_MAX request times and one counter per minute of the day. It is saved every
+ * FLUSH_MS, on eviction, on server close and at once on a refusal, so a restart doesn't hand a client hammering the
+ * server a fresh budget. Anything unreadable (a policy or saved usage outside its bounds) refuses: fail closed.
+ */
+import type { Database, Store } from "./store.js";
+import type { TokenAccess } from "./api-tokens.js";
+export declare const REQUEST_BUDGET_SCHEMA = "\nCREATE TABLE IF NOT EXISTS request_budget_limit (\n  target          TEXT PRIMARY KEY CHECK (target = '*' OR (length(target) = 12 AND target NOT GLOB '*[^0-9a-f]*')),\n  read_per_minute INTEGER CHECK (read_per_minute IS NULL OR read_per_minute BETWEEN 1 AND 600),\n  act_per_minute  INTEGER CHECK (act_per_minute IS NULL OR act_per_minute BETWEEN 1 AND 600),\n  per_day         INTEGER CHECK (per_day IS NULL OR per_day BETWEEN 1 AND 100000),\n  set_by          TEXT NOT NULL,\n  set_at          TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS request_budget_usage (\n  token_id  TEXT PRIMARY KEY,\n  minute    TEXT NOT NULL,\n  day       TEXT NOT NULL,\n  noted     TEXT NOT NULL,\n  saved_at  INTEGER NOT NULL\n);\n";
+export declare const REQUEST_BUDGET_DEFAULTS: Readonly<{
+    read: 120;
+    act: 30;
+    day: 10000;
+}>;
+export declare const PER_MINUTE_MAX = 600;
+export declare const PER_DAY_MAX = 100000;
+export declare const TRACKED_TOKENS = 1024;
+export declare const FLUSH_MS = 5000;
+/** Which limit a refusal hit: the body of a 429 names only this and Retry-After. */
+export type BudgetLimit = "read-per-minute" | "act-per-minute" | "per-day";
+export type Admission = {
+    ok: true;
+} | {
+    ok: false;
+    status: 429;
+    limit: BudgetLimit;
+    retryAfter: number;
+} | {
+    ok: false;
+    status: 503;
+};
+export type BudgetRoute = "api" | "mcp";
+/** An override: null leaves that limit to the installation (for a token) or the default. */
+export type LimitOverride = {
+    readPerMinute: number | null;
+    actPerMinute: number | null;
+    perDay: number | null;
+};
+export type EffectiveLimits = {
+    perMinute: number;
+    perDay: number;
+    overridden: boolean;
+};
+/** The words for a 429, in one line. */
+export declare const limitWords: (limit: BudgetLimit, retryAfter: number) => string;
+/** A limit typed into a form: a whole number within bounds, "" for none, or a problem. */
+export declare function parseLimit(raw: string, max: number): number | null | {
+    problem: string;
+};
+/** Every override: the installation's under "*", each token's under its id. */
+export declare function limitOverrides(db: Database): Map<string, LimitOverride>;
+/** Token override, then the installation's, then the default — per limit. */
+export declare function effectiveLimits(db: Database, tokenId: string, access: TokenAccess): EffectiveLimits;
+/** Set (or, all null, clear) an override, with the change in the policy ledger. The caller checks who may. */
+export declare function setLimitOverride(store: Store, target: string, next: LimitOverride, by: string, now: Date): {
+    before: LimitOverride | null;
+    after: LimitOverride | null;
+};
+export type RequestBudgetOptions = {
+    store: Store;
+    /** Milliseconds since the epoch; tests inject their own. */
+    clock?: () => number;
+    tracked?: number;
+    flushMs?: number;
+};
+/** One per server: both routes share it, so a token's allowance is never doubled. */
+export declare class RequestBudget {
+    private readonly store;
+    private readonly clock;
+    private readonly tracked;
+    private readonly flushMs;
+    private readonly usage;
+    private lastFlush;
+    constructor(options: RequestBudgetOptions);
+    /** How many tokens are tracked in memory now (never more than `tracked`). */
+    get size(): number;
+    /**
+     * Admit one request by an authenticated token, or say why not. Called once per HTTP request, before its body is
+     * read. Anything unreadable refuses with 503 and nothing runs.
+     */
+    admit(tokenId: string, route: BudgetRoute): Admission;
+    /** Save every changed entry. A server calls this on a timer and when it closes. */
+    flush(): void;
+    private save;
+    /** The tracked entry (now the most recently used), from memory or as last saved; the least recently used is saved and let go. */
+    private load;
+}

package/dist/request-budget.js

@@ -0,0 +1,227 @@
+export const REQUEST_BUDGET_SCHEMA = `
+CREATE TABLE IF NOT EXISTS request_budget_limit (
+  target          TEXT PRIMARY KEY CHECK (target = '*' OR (length(target) = 12 AND target NOT GLOB '*[^0-9a-f]*')),
+  read_per_minute INTEGER CHECK (read_per_minute IS NULL OR read_per_minute BETWEEN 1 AND 600),
+  act_per_minute  INTEGER CHECK (act_per_minute IS NULL OR act_per_minute BETWEEN 1 AND 600),
+  per_day         INTEGER CHECK (per_day IS NULL OR per_day BETWEEN 1 AND 100000),
+  set_by          TEXT NOT NULL,
+  set_at          TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS request_budget_usage (
+  token_id  TEXT PRIMARY KEY,
+  minute    TEXT NOT NULL,
+  day       TEXT NOT NULL,
+  noted     TEXT NOT NULL,
+  saved_at  INTEGER NOT NULL
+);
+`;
+export const REQUEST_BUDGET_DEFAULTS = Object.freeze({ read: 120, act: 30, day: 10_000 });
+export const PER_MINUTE_MAX = 600;
+export const PER_DAY_MAX = 100_000;
+export const TRACKED_TOKENS = 1024;
+export const FLUSH_MS = 5_000;
+const MINUTE = 60_000, DAY = 86_400_000;
+/** The words for a 429, in one line. */
+export const limitWords = (limit, retryAfter) => `Request limit reached (${limit === "per-day" ? "requests per day" : limit === "read-per-minute" ? "read requests per minute" : "act requests per minute"}). Try again in ${retryAfter} second${retryAfter === 1 ? "" : "s"}.`;
+/** A limit typed into a form: a whole number within bounds, "" for none, or a problem. */
+export function parseLimit(raw, max) {
+    const text = raw.trim();
+    if (text === "")
+        return null;
+    if (!/^[0-9]{1,6}$/.test(text))
+        return { problem: `Limits are whole numbers from 1 to ${max.toLocaleString("en-US")}.` };
+    const value = Number(text);
+    return value >= 1 && value <= max ? value : { problem: `Limits are whole numbers from 1 to ${max.toLocaleString("en-US")}.` };
+}
+const within = (value, max) => {
+    if (value === null || value === undefined)
+        return null;
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 1 || n > max)
+        throw new Error("request budget: a saved limit is out of bounds");
+    return n;
+};
+function readOverride(db, target) {
+    const row = db.prepare("SELECT read_per_minute, act_per_minute, per_day FROM request_budget_limit WHERE target = ?").get(target);
+    if (row === undefined)
+        return null;
+    return { readPerMinute: within(row["read_per_minute"], PER_MINUTE_MAX), actPerMinute: within(row["act_per_minute"], PER_MINUTE_MAX), perDay: within(row["per_day"], PER_DAY_MAX) };
+}
+/** Every override: the installation's under "*", each token's under its id. */
+export function limitOverrides(db) {
+    const out = new Map();
+    for (const row of db.prepare("SELECT target FROM request_budget_limit ORDER BY target").all()) {
+        const target = String(row["target"]);
+        out.set(target, readOverride(db, target));
+    }
+    return out;
+}
+/** Token override, then the installation's, then the default — per limit. */
+export function effectiveLimits(db, tokenId, access) {
+    const token = readOverride(db, tokenId), installation = readOverride(db, "*");
+    const pick = (of, fallback) => (token === null ? null : of(token)) ?? (installation === null ? null : of(installation)) ?? fallback;
+    const minute = (one) => access === "read" ? one.readPerMinute : one.actPerMinute;
+    const perMinute = pick(minute, REQUEST_BUDGET_DEFAULTS[access]), perDay = pick(one => one.perDay, REQUEST_BUDGET_DEFAULTS.day);
+    return { perMinute, perDay, overridden: perMinute !== REQUEST_BUDGET_DEFAULTS[access] || perDay !== REQUEST_BUDGET_DEFAULTS.day };
+}
+/** Set (or, all null, clear) an override, with the change in the policy ledger. The caller checks who may. */
+export function setLimitOverride(store, target, next, by, now) {
+    const db = store.handle;
+    if (target !== "*" && !/^[0-9a-f]{12}$/.test(target))
+        throw new Error("request budget: unknown target");
+    within(next.readPerMinute, PER_MINUTE_MAX);
+    within(next.actPerMinute, PER_MINUTE_MAX);
+    within(next.perDay, PER_DAY_MAX);
+    const before = readOverride(db, target);
+    const cleared = next.readPerMinute === null && next.actPerMinute === null && next.perDay === null;
+    if (cleared)
+        db.prepare("DELETE FROM request_budget_limit WHERE target = ?").run(target);
+    else
+        db.prepare(`INSERT INTO request_budget_limit (target, read_per_minute, act_per_minute, per_day, set_by, set_at) VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(target) DO UPDATE SET read_per_minute = excluded.read_per_minute, act_per_minute = excluded.act_per_minute, per_day = excluded.per_day, set_by = excluded.set_by, set_at = excluded.set_at`)
+            .run(target, next.readPerMinute, next.actPerMinute, next.perDay, by, now.toISOString());
+    const after = cleared ? null : next;
+    const words = (one) => one === null ? "defaults" : [one.readPerMinute === null ? null : `read ${one.readPerMinute}/min`, one.actPerMinute === null ? null : `act ${one.actPerMinute}/min`, one.perDay === null ? null : `${one.perDay}/day`].filter(Boolean).join(", ");
+    const name = target === "*" ? "installation" : `token ${store.apiTokenSecret(target)?.row.name ?? target}`;
+    store.recordAction({ at: now.toISOString(), actor: by, repo: null, taskId: null, runId: null, action: "request limits changed", outcome: "changed", source: "policy", detail: `${name}: ${words(before)} → ${words(after)}` });
+    return { before, after };
+}
+const finiteInts = (value, max) => Array.isArray(value) && value.length <= max && value.every(one => Number.isSafeInteger(one) && one >= 0);
+function prune(usage, now) {
+    let drop = 0;
+    while (drop < usage.minute.length && usage.minute[drop] <= now - MINUTE)
+        drop++;
+    if (drop > 0) {
+        usage.minute.splice(0, drop);
+        usage.dirty = true;
+    }
+    for (const at of usage.day.keys())
+        if ((at + 1) * MINUTE + DAY <= now) {
+            usage.day.delete(at);
+            usage.dirty = true;
+        }
+}
+/** One per server: both routes share it, so a token's allowance is never doubled. */
+export class RequestBudget {
+    store;
+    clock;
+    tracked;
+    flushMs;
+    usage = new Map();
+    lastFlush;
+    constructor(options) {
+        this.store = options.store;
+        this.clock = options.clock ?? Date.now;
+        this.tracked = Math.max(1, options.tracked ?? TRACKED_TOKENS);
+        this.flushMs = options.flushMs ?? FLUSH_MS;
+        this.lastFlush = this.clock();
+    }
+    /** How many tokens are tracked in memory now (never more than `tracked`). */
+    get size() { return this.usage.size; }
+    /**
+     * Admit one request by an authenticated token, or say why not. Called once per HTTP request, before its body is
+     * read. Anything unreadable refuses with 503 and nothing runs.
+     */
+    admit(tokenId, route) {
+        try {
+            const now = this.clock();
+            const token = this.store.apiTokenSecret(tokenId)?.row;
+            if (token === undefined)
+                return { ok: false, status: 503 };
+            const limits = effectiveLimits(this.store.handle, token.id, token.access);
+            const usage = this.load(token.id, now);
+            prune(usage, now);
+            let wait = 0, limit = null;
+            if (usage.minute.length >= limits.perMinute) {
+                wait = usage.minute[usage.minute.length - limits.perMinute] + MINUTE - now;
+                limit = token.access === "read" ? "read-per-minute" : "act-per-minute";
+            }
+            let total = 0;
+            for (const count of usage.day.values())
+                total += count;
+            if (total >= limits.perDay) {
+                let freed = 0;
+                for (const at of [...usage.day.keys()].sort((a, b) => a - b)) {
+                    freed += usage.day.get(at);
+                    if (total - freed < limits.perDay) {
+                        const until = (at + 1) * MINUTE + DAY - now;
+                        if (until > wait || limit === null) {
+                            wait = until;
+                            limit = "per-day";
+                        }
+                        break;
+                    }
+                }
+            }
+            if (limit !== null) {
+                const retryAfter = Math.max(1, Math.ceil(wait / 1000));
+                const window = limit === "per-day" ? "day" : "minute";
+                // Once per exhausted window: the marker lasts until the window has room again, and is saved with the entry.
+                if (usage.noted[window] <= now) {
+                    usage.noted[window] = now + retryAfter * 1000;
+                    usage.dirty = true;
+                    this.save(token.id, usage, now);
+                    this.store.recordAction({ at: new Date(now).toISOString(), actor: token.account, repo: null, taskId: null, runId: null, action: "remote request limit reached", outcome: "refused", source: route, detail: `token ${token.name}: ${limit}` });
+                }
+                return { ok: false, status: 429, limit, retryAfter };
+            }
+            usage.minute.push(now);
+            if (usage.minute.length > PER_MINUTE_MAX)
+                usage.minute.splice(0, usage.minute.length - PER_MINUTE_MAX);
+            const at = Math.floor(now / MINUTE);
+            usage.day.set(at, (usage.day.get(at) ?? 0) + 1);
+            usage.dirty = true;
+            if (now - this.lastFlush >= this.flushMs)
+                this.flush();
+            return { ok: true };
+        }
+        catch {
+            return { ok: false, status: 503 };
+        }
+    }
+    /** Save every changed entry. A server calls this on a timer and when it closes. */
+    flush() {
+        const now = this.clock();
+        this.lastFlush = now;
+        for (const [id, usage] of this.usage)
+            if (usage.dirty)
+                this.save(id, usage, now);
+        // Saved rows whose every count has expired are no use to anyone.
+        this.store.handle.prepare("DELETE FROM request_budget_usage WHERE saved_at <= ?").run(now - DAY - MINUTE);
+    }
+    save(id, usage, now) {
+        this.store.handle.prepare(`INSERT INTO request_budget_usage (token_id, minute, day, noted, saved_at) VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(token_id) DO UPDATE SET minute = excluded.minute, day = excluded.day, noted = excluded.noted, saved_at = excluded.saved_at`)
+            .run(id, JSON.stringify(usage.minute), JSON.stringify([...usage.day]), JSON.stringify(usage.noted), now);
+        usage.dirty = false;
+    }
+    /** The tracked entry (now the most recently used), from memory or as last saved; the least recently used is saved and let go. */
+    load(id, now) {
+        let usage = this.usage.get(id);
+        if (usage !== undefined) {
+            this.usage.delete(id);
+            this.usage.set(id, usage);
+            return usage;
+        }
+        const row = this.store.handle.prepare("SELECT minute, day, noted FROM request_budget_usage WHERE token_id = ?").get(id);
+        if (row === undefined)
+            usage = { minute: [], day: new Map(), noted: { minute: 0, day: 0 }, dirty: false };
+        else {
+            const minute = JSON.parse(String(row["minute"])), day = JSON.parse(String(row["day"])), noted = JSON.parse(String(row["noted"]));
+            if (!finiteInts(minute, PER_MINUTE_MAX) || !Array.isArray(day) || day.length > 2 * DAY / MINUTE || !day.every(pair => finiteInts(pair, 2) && pair.length === 2)
+                || noted === null || typeof noted !== "object" || !finiteInts([noted["minute"], noted["day"]], 2)) {
+                throw new Error("request budget: saved usage is unreadable");
+            }
+            const kept = noted;
+            usage = { minute: [...minute].sort((a, b) => a - b), day: new Map(day), noted: { minute: kept.minute, day: kept.day }, dirty: false };
+        }
+        this.usage.set(id, usage);
+        while (this.usage.size > this.tracked) {
+            const [oldest, entry] = this.usage.entries().next().value;
+            if (entry.dirty)
+                this.save(oldest, entry, now);
+            this.usage.delete(oldest);
+        }
+        return usage;
+    }
+}

package/dist/serve.d.ts

@@ -41,13 +41,16 @@ export type ServeOptions = {
      * (arc 3 finding 2/16): EXACTLY an origin — no path, query, credentials.
      * The one trust anchor for secure-context features: it joins the allowed
      * hosts, its origin authorizes POSTs, cookies turn Secure, and the
-     * install/push cards light up. X-Forwarded-* is never consulted.
+     * install/push cards light up. X-Forwarded-* is consulted only from a
+     * loopback peer, the same-host proxy (public-access.ts).
      */
     publicUrl?: string;
     /** Tests: the shared command boundary `POST /api/cli` runs (default: operate.ts's runOperateAs). */
     cliRunner?: RunOperateAs;
     /** Tests: remote command metadata until the shared contract declares it. */
     cliModeOf?: CliHttpOptions['modeOf'];
+    /** Tests: the clock request budgets for API tokens count by (request-budget.ts). */
+    requestBudgetClock?: () => number;
     /** Where repos.json lives — every enrollment locks exactly this file. */
     registryPath?: string;
     /** This console fronts an `up` process: onboarding copy says how to watch. */
@@ -271,6 +274,11 @@ type Chrome = {
     scope?: "all" | "project" | "board-all";
     /** The saturated inbox count — never a sum of unbounded list reads. */
     inboxCount: number;
+    /** The project the Tasks count covers: the request's own project view
+     * (the open project, or /work's ?project=), null for every admitted project. */
+    inboxProject?: string | null;
+    /** The Tasks badge's words, naming what it covers: "3 need you in shop". */
+    inboxLabel?: string;
     inboxSaturated: boolean;
     settings: boolean;
     /** This database is a demo sandbox: banner every page, spend fenced. */