toolroll 0.9.45 → 0.9.47

package/dist/store.d.ts

@@ -2,6 +2,8 @@ import type { DecisionOption } from "./contracts/decision.js";
 import { type SavedToolAction, type SavedToolRule } from "./contracts/store-json.js";
 import type { FlowCardChange, FlowCardFields } from "./contracts/flow-card.js";
 import { type Actor } from "./actor.js";
+import { type LiveActivityKind } from "./live.js";
+import { type TokenPurpose } from "./api-tokens.js";
 import { type CriterionMatrixRow, type CriterionJudgementWord } from "./proof.js";
 import { type ExecutionProfile, type ChainEntry, type UnattendedPermissionMode, type AcceptanceCriterion } from "./scope.js";
 import { type ProviderRoom, type CandidateTier, type TaskSize, type TaskSizing, type PhaseRoute, type PublicationAuthority, type RouteStamp, type ReadinessLookup, type ReadinessObservation, type RiskLevel, type RouteOverride } from "./phase-routing.js";
@@ -68,6 +70,10 @@ export declare const FLOW_SEND_SCHEMA = "\nCREATE TABLE IF NOT EXISTS flow_send
 /** An owner's lasting choice to approve plans and merges from their paired chat (chat-approval.ts), for all their
  * projects (scope '*') or one (its path), with the limits they agreed to. Off unless a row says on; a project's own row
  * outranks the all-projects one. `generation` is the account's at the change: a reset password ends it. */
+/** What a running agent did last (live tasks): one row per run, a fixed kind from live.ts's
+ * vocabulary and when — never text, tool names or arguments. Display state, not evidence;
+ * a finished run's row goes with the live log's own retention (sweepRunActivity). */
+export declare const RUN_ACTIVITY_SCHEMA = "\nCREATE TABLE IF NOT EXISTS run_activity (\n  run  INTEGER PRIMARY KEY REFERENCES run(id) ON DELETE CASCADE,\n  kind TEXT NOT NULL CHECK (kind IN ('session','message','edit','command','read','search','lookup','plan','delegate','tool')),\n  at   TEXT NOT NULL\n);\n";
 export declare const CHAT_APPROVAL_SCHEMA = "\nCREATE TABLE IF NOT EXISTS chat_approval_setting (\n  approver             TEXT NOT NULL,\n  scope                TEXT NOT NULL,\n  enabled              INTEGER NOT NULL CHECK (enabled IN (0,1)),\n  full_access          INTEGER NOT NULL DEFAULT 0 CHECK (full_access IN (0,1)),\n  attempt_cap_microusd INTEGER CHECK (attempt_cap_microusd IS NULL OR attempt_cap_microusd >= 0),\n  generation           INTEGER NOT NULL,\n  digest               TEXT NOT NULL,\n  updated_by           TEXT NOT NULL,\n  updated_at           TEXT NOT NULL,\n  PRIMARY KEY (approver, scope)\n);\n";
 /** The second tap on a flow decision in Telegram (telegram-flow.ts): Approve arms Yes and Cancel, bound to the binding,
  * chat, message and exact visit of the card; Yes decides it once. */
@@ -145,7 +151,7 @@ export type SealedLedgerEntry = LedgerEntry & {
         hash: string;
     } | null;
 };
-export declare const SCHEMA_VERSION = 110;
+export declare const SCHEMA_VERSION = 113;
 /**
  * The migrations `toolroll update` may carry a database through in place: each
  * one only adds (a table, a column, an accepted value) and leaves every saved row
@@ -155,11 +161,43 @@ export declare const SCHEMA_VERSION = 110;
  * migrates and does not read this list.
  *
  * v110 rebuilds action_ledger only to widen its source check ('api', 'mcp'):
- * every row, id and hash-chain link is copied unchanged.
+ * every row, id and hash-chain link is copied unchanged. v111 adds nullable
+ * api_token columns (project limit, rotation); existing tokens read as before.
+ * v112 only adds the two request-budget tables.
+ * v113 adds MCP sign-in tables and API-token purpose metadata.
  */
 export declare const UPDATE_SAFE_MIGRATIONS: readonly number[];
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export declare function updateSafeSchema(version: number | null): boolean;
+export type OAuthClientRow = {
+    id: string;
+    name: string;
+    redirectUris: string[];
+    createdAt: string;
+};
+export type OAuthCodeRow = {
+    client: string;
+    account: string;
+    generation: number;
+    access: "read" | "act";
+    projects: string[];
+    redirectUri: string;
+    resource: string;
+    challenge: string;
+    expiresAt: string;
+    usedAt: string | null;
+    token: string | null;
+};
+export type OAuthGrantRow = {
+    token: string;
+    client: string;
+    account: string;
+    generation: number;
+    projects: string[];
+    resource: string;
+    accessExpiresAt: string;
+    refreshHash: string;
+};
 export type ApiTokenRow = {
     id: string;
     account: string;
@@ -171,6 +209,14 @@ export type ApiTokenRow = {
     lastUsedAt: string | null;
     revokedAt: string | null;
     revokedBy: string | null;
+    /** v113: MCP manages its own access-secret rotation. */
+    purpose: TokenPurpose;
+    /** v111: the projects it is limited to (null: every project its person may use). */
+    projects: string[] | null;
+    /** v111: the token it replaced, the one that replaced it, and when this one stops after being replaced. */
+    replaces: string | null;
+    replacedBy: string | null;
+    overlapUntil: string | null;
 };
 export type WebSessionRow = {
     idHash: string;
@@ -2591,7 +2637,26 @@ export declare class Store {
         access: "read" | "act";
         expiresAt: string;
         by: string;
+        projects?: readonly string[] | null;
+        purpose?: TokenPurpose;
     }, now: Date): void;
+    /**
+     * v111: replace a live, not-yet-replaced token with a new secret on the same terms (access, projects, end date, so
+     * rotating never extends it). The old one keeps working until `overlapUntil` (never past its own end), then stops;
+     * every check reads that time, and endRotatedApiTokens records the end afterwards. Only the token's own person.
+     */
+    rotateApiToken(oldId: string, replacement: {
+        id: string;
+        secretHash: string;
+    }, by: string, now: Date, overlapMs: number): {
+        ok: true;
+        row: ApiTokenRow;
+    } | {
+        ok: false;
+        reason: "unknown" | "replaced" | "mcp-managed";
+    };
+    /** v111: record the end of each replaced token whose overlap has passed (it already signs no one in). */
+    endRotatedApiTokens(now: Date): number;
     /** A token by id with its kept hash (for the check), or null. */
     apiTokenSecret(id: string): {
         row: ApiTokenRow;
@@ -2602,6 +2667,62 @@ export declare class Store {
     /** Kept at most once a minute: a busy script doesn't write on every request. */
     touchApiToken(id: string, now: Date): void;
     revokeApiToken(id: string, by: string, now: Date, why?: string): boolean;
+    /** A registered client, or null. */
+    oauthClient(id: string): OAuthClientRow | null;
+    /** Expire unused registrations, retaining clients with a live code, grant or in-process consent. */
+    pruneOAuthClients(now: Date, pending?: readonly string[]): void;
+    /**
+     * Unused registrations expire after a day. Admission has a global and per-source bound; it never evicts a live
+     * registration. Repeating metadata from the same source returns its existing registration without spending a slot.
+     */
+    registerOAuthClient(client: {
+        id: string;
+        name: string;
+        redirectUris: string[];
+        source: string;
+    }, now: Date, cap: number, perSourceCap: number, pending?: readonly string[]): OAuthClientRow | null;
+    /** Keep a one-time code by its hash. */
+    saveOAuthCode(hash: string, code: Omit<OAuthCodeRow, "usedAt" | "token">): void;
+    /**
+     * Spend a code: the first caller gets it (`taken`), once, before it expires. A code spent before answers `used`
+     * with the token it made, so that token can be ended; anything else is null.
+     */
+    takeOAuthCode(hash: string, now: Date): {
+        taken: OAuthCodeRow;
+    } | {
+        used: string | null;
+    } | null;
+    /** Make a grant: its API token (created and recorded as any other) and its binding, together; the code notes the token. */
+    createOAuthGrant(code: string, token: {
+        id: string;
+        account: string;
+        name: string;
+        secretHash: string;
+        access: "read" | "act";
+        expiresAt: string;
+    }, grant: Omit<OAuthGrantRow, "token">, now: Date): void;
+    /** The grant an API token signs in for, or null when the token is an ordinary one. */
+    oauthGrant(token: string): OAuthGrantRow | null;
+    /**
+     * Classify, validate and rotate under one write transaction. Every issued hash remains in the family, so any
+     * older secret revokes even a concurrent winner. An unknown guess or the wrong client cannot end the family.
+     */
+    rotateOAuthGrant(token: string, ask: {
+        client: string;
+        resource: string;
+        refreshHash: string;
+        scope?: string;
+    }, next: {
+        refreshHash: string;
+        accessHash: string;
+        accessExpiresAt: string;
+    }, now: Date, projectsFor: (account: string) => readonly string[]): {
+        ok: true;
+        access: "read" | "act";
+    } | {
+        ok: false;
+        reason: "invalid_grant" | "invalid_scope";
+    };
     saveWebSession(session: WebSessionRow): void;
     webSession(idHash: string): WebSessionRow | null;
     webSessions(account: string | null): WebSessionRow[];
@@ -5485,6 +5606,17 @@ export declare class Store {
      * page and focused chat render live, including once the run that wrote
      * it has ended. */
     latestCheckpointForTask(taskRef: number): RunCheckpoint | null;
+    /** What the agent did last on this run (live tasks): one fixed kind and when, replacing the last. */
+    recordRunActivity(run: number, kind: LiveActivityKind, now: Date): void;
+    /** A run's last recorded activity and its newest progress checkpoint's time, in one read. */
+    runActivity(run: number): {
+        kind: LiveActivityKind | null;
+        at: string | null;
+        progressAt: string | null;
+    };
+    /** The live log's own retention: a finished run's activity goes once older than `retainMs`, and beyond the newest
+     * `bound` finished runs; a live run's always stays. */
+    sweepRunActivity(now: Date, retainMs: number, bound: number): number;
     /** One run's full checkpoint history, oldest first. */
     checkpointHistory(run: number): RunCheckpoint[];
     /** The newest scout run's report for a task (v34), when one exists. */

package/dist/store.js

@@ -12,6 +12,8 @@ import { cardOutputsForStore, cardOutputsFromStore } from "./contracts/stage-out
 import { chatControlHref, chatResultHref } from "./chat-controls.js";
 import { actorLabel, currentActor, leadSecretMatches, mintLeadToken, parseLeadToken } from "./actor.js";
 import { scanForSecrets } from "./evidence.js";
+import { LIVE_ACTIVITY_KINDS } from "./live.js";
+import { tokenPurpose, tokenRotationProblem } from "./api-tokens.js";
 /**
  * The database: a small task store, and the operational overlay beside it.
  *
@@ -69,6 +71,7 @@ import { PLAN_AUTO_SCHEMA } from "./plan-auto.js";
 import { RECIPE_SCHEMA } from "./recipes.js";
 import { POLICY_SCHEMA, agentRefusal, approvalRefusal, attendedRefusal, policyParts, readPolicy, underCeiling, sessionCeilingRefusal } from "./policy.js";
 import { PROVIDER_AUTH_SCHEMA } from "./provider-auth.js";
+import { REQUEST_BUDGET_SCHEMA } from "./request-budget.js";
 import { REVIEW_SCHEMA, reviewSwitchWords } from "./review-switch.js";
 import { SPEND_SCHEMA, billingOf, budgetStates, canPrice, claudeMachineBilling, countsToward, filersOf, monthOf, priceWork, seenBilling as seenBillingOf, spendItems, teammateFilers, usd } from "./spend.js";
 import { DEFAULT_PERIODS, RETENTION_SCHEMA, periodWords, widenRetentionSchema } from "./retention.js";
@@ -357,6 +360,16 @@ CREATE INDEX IF NOT EXISTS telegram_flow_choice_visit ON telegram_flow_choice (c
 /** An owner's lasting choice to approve plans and merges from their paired chat (chat-approval.ts), for all their
  * projects (scope '*') or one (its path), with the limits they agreed to. Off unless a row says on; a project's own row
  * outranks the all-projects one. `generation` is the account's at the change: a reset password ends it. */
+/** What a running agent did last (live tasks): one row per run, a fixed kind from live.ts's
+ * vocabulary and when — never text, tool names or arguments. Display state, not evidence;
+ * a finished run's row goes with the live log's own retention (sweepRunActivity). */
+export const RUN_ACTIVITY_SCHEMA = `
+CREATE TABLE IF NOT EXISTS run_activity (
+  run  INTEGER PRIMARY KEY REFERENCES run(id) ON DELETE CASCADE,
+  kind TEXT NOT NULL CHECK (kind IN ('session','message','edit','command','read','search','lookup','plan','delegate','tool')),
+  at   TEXT NOT NULL
+);
+`;
 export const CHAT_APPROVAL_SCHEMA = `
 CREATE TABLE IF NOT EXISTS chat_approval_setting (
   approver             TEXT NOT NULL,
@@ -564,7 +577,10 @@ const REGISTERED_AT_FILING = "again, as it was filed";
 // v108 keeps sign-in pauses: one incident per provider whose sign-in stopped working (provider_auth_pause).
 // v109 remembers which sign-in pause parked a task (task_ref.auth_wait_pause), so reviews and other runs outside the tick wait for it too.
 // v110 lets the action ledger record commands a person ran on this server with their API token (source 'api', or 'mcp' from their agent).
-export const SCHEMA_VERSION = 110;
+// v111 keeps an API token's project limit and its rotation: the token that replaced it, and when the old one stops.
+// v112 keeps request budgets for API tokens: owner overrides (request_budget_limit) and saved usage (request_budget_usage).
+// v113 keeps MCP sign-ins (OAuth): registered clients, one-time codes, and each grant's binding to its API token.
+export const SCHEMA_VERSION = 113;
 /**
  * The migrations `toolroll update` may carry a database through in place: each
  * one only adds (a table, a column, an accepted value) and leaves every saved row
@@ -574,9 +590,12 @@ export const SCHEMA_VERSION = 110;
  * migrates and does not read this list.
  *
  * v110 rebuilds action_ledger only to widen its source check ('api', 'mcp'):
- * every row, id and hash-chain link is copied unchanged.
+ * every row, id and hash-chain link is copied unchanged. v111 adds nullable
+ * api_token columns (project limit, rotation); existing tokens read as before.
+ * v112 only adds the two request-budget tables.
+ * v113 adds MCP sign-in tables and API-token purpose metadata.
  */
-export const UPDATE_SAFE_MIGRATIONS = Object.freeze([110]);
+export const UPDATE_SAFE_MIGRATIONS = Object.freeze([110, 111, 112, 113]);
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export function updateSafeSchema(version) {
     if (version === null || !Number.isSafeInteger(version) || version <= 0 || version > SCHEMA_VERSION)
@@ -643,6 +662,58 @@ CREATE TABLE IF NOT EXISTS web_session (
 );
 CREATE INDEX IF NOT EXISTS web_session_account ON web_session (account);
 `;
+/**
+ * v113: MCP sign-in (OAuth 2.1, mcp-oauth.ts). A registered client, a one-time code (its hash, a minute at most), and
+ * each grant: the ordinary API token it signs in with (revoked like any other), the account generation and exact
+ * projects the person chose, and every issued refresh-secret hash (any replay ends the whole family).
+ */
+const OAUTH_SCHEMA = `
+CREATE TABLE IF NOT EXISTS oauth_client (
+  id            TEXT PRIMARY KEY,
+  name          TEXT NOT NULL,
+  redirect_json TEXT NOT NULL,
+  created_at    TEXT NOT NULL,
+  source_hash   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS oauth_client_source ON oauth_client (source_hash);
+CREATE TABLE IF NOT EXISTS oauth_code (
+  hash         TEXT PRIMARY KEY,
+  client       TEXT NOT NULL REFERENCES oauth_client(id),
+  account      TEXT NOT NULL,
+  generation   INTEGER NOT NULL,
+  access       TEXT NOT NULL CHECK (access IN ('read','act')),
+  projects_json TEXT NOT NULL,
+  redirect_uri TEXT NOT NULL,
+  resource     TEXT NOT NULL,
+  challenge    TEXT NOT NULL,
+  expires_at   TEXT NOT NULL,
+  used_at      TEXT,
+  token        TEXT
+);
+CREATE TABLE IF NOT EXISTS oauth_grant (
+  token              TEXT PRIMARY KEY REFERENCES api_token(id),
+  client             TEXT NOT NULL REFERENCES oauth_client(id),
+  account            TEXT NOT NULL,
+  generation         INTEGER NOT NULL,
+  projects_json      TEXT NOT NULL,
+  resource           TEXT NOT NULL,
+  access_expires_at  TEXT NOT NULL,
+  renew_hash       TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS oauth_grant_client ON oauth_grant (client);
+CREATE TABLE IF NOT EXISTS oauth_refresh (
+  token TEXT NOT NULL REFERENCES oauth_grant(token),
+  hash  TEXT NOT NULL,
+  PRIMARY KEY (token, hash)
+);
+`;
+const stringList = (raw) => { try {
+    const value = JSON.parse(String(raw));
+    return Array.isArray(value) && value.every((one) => typeof one === "string") ? value : [];
+}
+catch {
+    return [];
+} };
 /** v100: which account each identity-provider identity (issuer + subject) signs in as. */
 const SSO_SCHEMA = `
 CREATE TABLE IF NOT EXISTS sso_identity (
@@ -4013,6 +4084,14 @@ function initializeStore(db, file) {
     db.exec(TEAM_SCHEMA);
     db.exec(SSO_SCHEMA);
     db.exec(CREDENTIALS_SCHEMA);
+    // v111: a token's project limit (null: every project its person may use) and its rotation.
+    addColumn(db, "api_token", "projects_json", "TEXT");
+    addColumn(db, "api_token", "replaces", "TEXT");
+    addColumn(db, "api_token", "replaced_by", "TEXT");
+    addColumn(db, "api_token", "overlap_until", "TEXT");
+    // v113: MCP sign-in (OAuth), and whether a token is an ordinary one or an MCP sign-in's.
+    db.exec(OAUTH_SCHEMA);
+    addColumn(db, "api_token", "purpose", "TEXT NOT NULL DEFAULT 'api' CHECK (purpose IN ('api','mcp'))");
     db.exec(APPROVAL_SCHEMA);
     db.exec(LEDGER_CHAIN_SCHEMA);
     db.exec(MONITORING_SCHEMA);
@@ -4022,12 +4101,16 @@ function initializeStore(db, file) {
     db.exec(CHAT_DECIDE_SCHEMA);
     // An owner's lasting chat-approval setting (no version bump: additive only; absent means off).
     db.exec(CHAT_APPROVAL_SCHEMA);
+    // What a running agent did last (no version bump: additive only; absent means no word yet).
+    db.exec(RUN_ACTIVITY_SCHEMA);
     db.exec(TELEGRAM_FLOW_CONFIRM_SCHEMA);
     // A flow's "Send to me" and "Person chooses" zones (no version bump: additive only).
     db.exec(FLOW_SEND_SCHEMA);
     db.exec(SPEND_SCHEMA);
     // Sign-in pauses: one row per incident of a provider's sign-in no longer working.
     db.exec(PROVIDER_AUTH_SCHEMA);
+    // v112: request budgets for API tokens (request-budget.ts).
+    db.exec(REQUEST_BUDGET_SCHEMA);
     // The sign-in pause the dispatch gate last left this task waiting on (null: none), for the work index.
     addColumn(db, "task_ref", "auth_wait_pause", "INTEGER REFERENCES provider_auth_pause(id)");
     // Sized routing (no version bump: additive, and a wider tier check whose rows carry over): how big each task is,
@@ -5547,7 +5630,20 @@ function rebuildExact(db, table, oldDdl, targetDdl, columns) {
 function readApiToken(row) {
     const text = (key) => row[key] == null ? null : String(row[key]);
     return { id: String(row["id"]), account: String(row["account"]), name: String(row["name"]), access: row["access"] === "act" ? "act" : "read", createdAt: String(row["created_at"]), createdBy: String(row["created_by"]),
-        expiresAt: String(row["expires_at"]), lastUsedAt: text("last_used_at"), revokedAt: text("revoked_at"), revokedBy: text("revoked_by") };
+        expiresAt: String(row["expires_at"]), lastUsedAt: text("last_used_at"), revokedAt: text("revoked_at"), revokedBy: text("revoked_by"),
+        purpose: tokenPurpose(row["purpose"]), projects: tokenProjectsOf(row["projects_json"]), replaces: text("replaces"), replacedBy: text("replaced_by"), overlapUntil: text("overlap_until") };
+}
+/** A token's stored project limit. Anything unreadable limits it to no project at all: never wider. */
+function tokenProjectsOf(value) {
+    if (value == null)
+        return null;
+    try {
+        const parsed = JSON.parse(String(value));
+        return Array.isArray(parsed) && parsed.every(one => typeof one === "string") ? parsed : [];
+    }
+    catch {
+        return [];
+    }
 }
 function readWebSession(row) {
     return { idHash: String(row["id_hash"]), account: String(row["account"]), csrf: String(row["csrf"]), role: row["role"] === "viewer" ? "viewer" : "approver", generation: Number(row["generation"]),
@@ -9808,12 +9904,45 @@ export class Store {
     // ---- API tokens and browser sessions (v101) ------------------------------
     createApiToken(token, now) {
         this.transact(() => {
-            this.db.prepare("INSERT INTO api_token (id, account, name, secret_hash, access, created_at, created_by, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
-                .run(token.id, token.account, token.name, token.secretHash, token.access, now.toISOString(), token.by, token.expiresAt);
+            const projects = token.projects ?? null;
+            this.db.prepare("INSERT INTO api_token (id, account, name, secret_hash, access, created_at, created_by, expires_at, projects_json, purpose) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+                .run(token.id, token.account, token.name, token.secretHash, token.access, now.toISOString(), token.by, token.expiresAt, projects === null ? null : JSON.stringify(projects), token.purpose ?? "api");
             this.recordAction({ at: now.toISOString(), actor: token.by, repo: null, taskId: null, runId: null, action: `API token created: ${token.name}`, outcome: token.access, source: "access",
-                detail: `for ${token.account}, until ${token.expiresAt.slice(0, 10)}` });
+                detail: `for ${token.account}, until ${token.expiresAt.slice(0, 10)}${projects === null ? "" : ` · ${projects.length === 0 ? "no projects" : projects.join(", ")}`} · id ${token.id}` });
         });
     }
+    /**
+     * v111: replace a live, not-yet-replaced token with a new secret on the same terms (access, projects, end date, so
+     * rotating never extends it). The old one keeps working until `overlapUntil` (never past its own end), then stops;
+     * every check reads that time, and endRotatedApiTokens records the end afterwards. Only the token's own person.
+     */
+    rotateApiToken(oldId, replacement, by, now, overlapMs) {
+        return this.transact(() => {
+            const old = this.apiTokenSecret(oldId)?.row ?? null;
+            const at = now.getTime();
+            if (old === null || old.account !== by || old.revokedAt !== null || !(Date.parse(old.expiresAt) > at) || old.overlapUntil !== null && !(Date.parse(old.overlapUntil) > at))
+                return { ok: false, reason: "unknown" };
+            if (tokenRotationProblem(old) !== null || this.oauthGrant(oldId) !== null)
+                return { ok: false, reason: "mcp-managed" };
+            if (old.replacedBy !== null)
+                return { ok: false, reason: "replaced" };
+            const stamp = now.toISOString();
+            const until = new Date(Math.min(at + Math.max(0, overlapMs), Date.parse(old.expiresAt))).toISOString();
+            this.db.prepare("INSERT INTO api_token (id, account, name, secret_hash, access, created_at, created_by, expires_at, projects_json, replaces) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+                .run(replacement.id, old.account, old.name, replacement.secretHash, old.access, stamp, by, old.expiresAt, old.projects === null ? null : JSON.stringify(old.projects), old.id);
+            this.db.prepare("UPDATE api_token SET replaced_by = ?, overlap_until = ? WHERE id = ? AND replaced_by IS NULL").run(replacement.id, until, old.id);
+            this.recordAction({ at: stamp, actor: by, repo: null, taskId: null, runId: null, action: `API token rotated: ${old.name}`, outcome: old.access, source: "access",
+                detail: `${old.account}'s · id ${old.id} → ${replacement.id}, the old one stops ${until.slice(0, 16).replace("T", " ")} UTC` });
+            return { ok: true, row: this.apiTokenSecret(replacement.id).row };
+        });
+    }
+    /** v111: record the end of each replaced token whose overlap has passed (it already signs no one in). */
+    endRotatedApiTokens(now) {
+        const due = this.db.prepare("SELECT id, overlap_until FROM api_token WHERE revoked_at IS NULL AND overlap_until IS NOT NULL AND overlap_until <= ?").all(now.toISOString());
+        for (const row of due)
+            this.revokeApiToken(String(row["id"]), "system", new Date(String(row["overlap_until"])), "replaced; its overlap ended");
+        return due.length;
+    }
     /** A token by id with its kept hash (for the check), or null. */
     apiTokenSecret(id) {
         const row = this.db.prepare("SELECT * FROM api_token WHERE id = ?").get(id);
@@ -9837,6 +9966,119 @@ export class Store {
             return true;
         });
     }
+    // ---- MCP sign-in (v113, mcp-oauth.ts) ---------------------------------------------------------------------------
+    /** A registered client, or null. */
+    oauthClient(id) {
+        const row = this.db.prepare("SELECT * FROM oauth_client WHERE id = ?").get(id);
+        return row === undefined ? null : { id: String(row["id"]), name: String(row["name"]), redirectUris: stringList(row["redirect_json"]), createdAt: String(row["created_at"]) };
+    }
+    /** Expire unused registrations, retaining clients with a live code, grant or in-process consent. */
+    pruneOAuthClients(now, pending = []) {
+        this.transact(() => {
+            const stale = new Date(now.getTime() - 86_400_000).toISOString();
+            this.db.prepare("DELETE FROM oauth_code WHERE expires_at <= ?").run(now.toISOString());
+            this.db.prepare(`DELETE FROM oauth_client WHERE created_at <= ? AND id NOT IN (SELECT client FROM oauth_grant)
+        AND id NOT IN (SELECT client FROM oauth_code) AND id NOT IN (SELECT value FROM json_each(?))`).run(stale, JSON.stringify(pending));
+        });
+    }
+    /**
+     * Unused registrations expire after a day. Admission has a global and per-source bound; it never evicts a live
+     * registration. Repeating metadata from the same source returns its existing registration without spending a slot.
+     */
+    registerOAuthClient(client, now, cap, perSourceCap, pending = []) {
+        return this.transact(() => {
+            const redirectJson = JSON.stringify(client.redirectUris);
+            this.pruneOAuthClients(now, pending);
+            const same = this.db.prepare("SELECT id FROM oauth_client WHERE name = ? AND redirect_json = ? AND source_hash = ?").get(client.name, redirectJson, client.source);
+            if (same !== undefined)
+                return this.oauthClient(String(same["id"]));
+            const unused = "FROM oauth_client WHERE id NOT IN (SELECT client FROM oauth_grant)";
+            if (Number(this.db.prepare(`SELECT COUNT(*) AS n ${unused}`).get()?.["n"] ?? 0) >= cap
+                || Number(this.db.prepare(`SELECT COUNT(*) AS n ${unused} AND source_hash = ?`).get(client.source)?.["n"] ?? 0) >= perSourceCap)
+                return null;
+            this.db.prepare("INSERT INTO oauth_client (id, name, redirect_json, created_at, source_hash) VALUES (?, ?, ?, ?, ?)").run(client.id, client.name, redirectJson, now.toISOString(), client.source);
+            return this.oauthClient(client.id);
+        });
+    }
+    /** Keep a one-time code by its hash. */
+    saveOAuthCode(hash, code) {
+        this.db.prepare("INSERT INTO oauth_code (hash, client, account, generation, access, projects_json, redirect_uri, resource, challenge, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+            .run(hash, code.client, code.account, code.generation, code.access, JSON.stringify(code.projects), code.redirectUri, code.resource, code.challenge, code.expiresAt);
+    }
+    /**
+     * Spend a code: the first caller gets it (`taken`), once, before it expires. A code spent before answers `used`
+     * with the token it made, so that token can be ended; anything else is null.
+     */
+    takeOAuthCode(hash, now) {
+        return this.transact(() => {
+            const row = this.db.prepare("SELECT * FROM oauth_code WHERE hash = ?").get(hash);
+            if (row === undefined)
+                return null;
+            if (row["used_at"] !== null)
+                return { used: row["token"] === null ? null : String(row["token"]) };
+            this.db.prepare("UPDATE oauth_code SET used_at = ? WHERE hash = ? AND used_at IS NULL").run(now.toISOString(), hash);
+            if (String(row["expires_at"]) <= now.toISOString())
+                return null;
+            return { taken: { client: String(row["client"]), account: String(row["account"]), generation: Number(row["generation"]), access: row["access"] === "act" ? "act" : "read", projects: stringList(row["projects_json"]),
+                    redirectUri: String(row["redirect_uri"]), resource: String(row["resource"]), challenge: String(row["challenge"]), expiresAt: String(row["expires_at"]), usedAt: null, token: null } };
+        });
+    }
+    /** Make a grant: its API token (created and recorded as any other) and its binding, together; the code notes the token. */
+    createOAuthGrant(code, token, grant, now) {
+        this.transact(() => {
+            this.createApiToken({ ...token, by: token.account, projects: grant.projects, purpose: "mcp" }, now);
+            this.db.prepare("INSERT INTO oauth_grant (token, client, account, generation, projects_json, resource, access_expires_at, renew_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
+                .run(token.id, grant.client, grant.account, grant.generation, JSON.stringify(grant.projects), grant.resource, grant.accessExpiresAt, grant.refreshHash);
+            this.db.prepare("INSERT INTO oauth_refresh (token, hash) VALUES (?, ?)").run(token.id, grant.refreshHash);
+            this.db.prepare("UPDATE oauth_code SET token = ? WHERE hash = ?").run(token.id, code);
+        });
+    }
+    /** The grant an API token signs in for, or null when the token is an ordinary one. */
+    oauthGrant(token) {
+        const row = this.db.prepare("SELECT * FROM oauth_grant WHERE token = ?").get(token);
+        return row === undefined ? null : { token: String(row["token"]), client: String(row["client"]), account: String(row["account"]), generation: Number(row["generation"]), projects: stringList(row["projects_json"]),
+            resource: String(row["resource"]), accessExpiresAt: String(row["access_expires_at"]), refreshHash: String(row["renew_hash"]) };
+    }
+    /**
+     * Classify, validate and rotate under one write transaction. Every issued hash remains in the family, so any
+     * older secret revokes even a concurrent winner. An unknown guess or the wrong client cannot end the family.
+     */
+    rotateOAuthGrant(token, ask, next, now, projectsFor) {
+        return this.transact(() => {
+            const invalid = { ok: false, reason: "invalid_grant" };
+            const grant = this.oauthGrant(token), kept = this.apiTokenSecret(token)?.row;
+            if (grant === null || kept === undefined || grant.client !== ask.client || grant.resource !== ask.resource)
+                return invalid;
+            const issued = this.db.prepare("SELECT 1 FROM oauth_refresh WHERE token = ? AND hash = ?").get(token, ask.refreshHash);
+            if (issued === undefined)
+                return invalid;
+            if (grant.refreshHash !== ask.refreshHash) {
+                this.revokeApiToken(token, "toolroll", now, "its refresh secret was used twice");
+                return invalid;
+            }
+            if (kept.revokedAt !== null || !(Date.parse(kept.expiresAt) > now.getTime()))
+                return invalid;
+            const account = this.accountOf(grant.account);
+            if (account === null || account.revokedAt !== null || account.generation !== grant.generation || (kept.access === "act" && account.role !== "approver")) {
+                this.revokeApiToken(token, "toolroll", now, "the person's sign-in changed");
+                return invalid;
+            }
+            const mine = projectsFor(grant.account);
+            if (!grant.projects.some(project => mine.includes(project) && (kept.projects === null || kept.projects.includes(project)))) {
+                this.revokeApiToken(token, "toolroll", now, "its projects are no longer the person's");
+                return invalid;
+            }
+            if (ask.scope !== undefined && !ask.scope.split(" ").every(one => one === kept.access || one === "read"))
+                return { ok: false, reason: "invalid_scope" };
+            const moved = this.db.prepare("UPDATE oauth_grant SET renew_hash = ?, access_expires_at = ? WHERE token = ? AND renew_hash = ?")
+                .run(next.refreshHash, next.accessExpiresAt, token, ask.refreshHash);
+            if (Number(moved.changes) !== 1)
+                return invalid;
+            this.db.prepare("UPDATE api_token SET secret_hash = ? WHERE id = ? AND revoked_at IS NULL").run(next.accessHash, token);
+            this.db.prepare("INSERT INTO oauth_refresh (token, hash) VALUES (?, ?)").run(token, next.refreshHash);
+            return { ok: true, access: kept.access };
+        });
+    }
     saveWebSession(session) {
         this.db.prepare(`INSERT INTO web_session (id_hash, account, csrf, role, generation, created_at, last_seen, project, project_revision, sso_at, agent, address) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id_hash) DO UPDATE SET last_seen = excluded.last_seen, project = excluded.project, project_revision = excluded.project_revision, sso_at = excluded.sso_at`)
@@ -17294,6 +17536,27 @@ export class Store {
         const row = this.db.prepare("SELECT * FROM run_checkpoint WHERE task_ref = ? ORDER BY id DESC LIMIT 1").get(taskRef);
         return row === undefined ? null : readRunCheckpoint(row);
     }
+    /** What the agent did last on this run (live tasks): one fixed kind and when, replacing the last. */
+    recordRunActivity(run, kind, now) {
+        this.db.prepare("INSERT INTO run_activity (run, kind, at) VALUES (?, ?, ?) ON CONFLICT (run) DO UPDATE SET kind = excluded.kind, at = excluded.at")
+            .run(run, kind, now.toISOString());
+    }
+    /** A run's last recorded activity and its newest progress checkpoint's time, in one read. */
+    runActivity(run) {
+        const row = this.db.prepare(`SELECT (SELECT kind FROM run_activity WHERE run = ?1) AS kind, (SELECT at FROM run_activity WHERE run = ?1) AS at,
+      (SELECT created_at FROM run_checkpoint WHERE run = ?1 ORDER BY id DESC LIMIT 1) AS progress_at`).get(run);
+        const kind = typeof row["kind"] === "string" && LIVE_ACTIVITY_KINDS.includes(row["kind"]) ? row["kind"] : null;
+        return { kind, at: kind === null ? null : String(row["at"]), progressAt: row["progress_at"] == null ? null : String(row["progress_at"]) };
+    }
+    /** The live log's own retention: a finished run's activity goes once older than `retainMs`, and beyond the newest
+     * `bound` finished runs; a live run's always stays. */
+    sweepRunActivity(now, retainMs, bound) {
+        const finished = "run IN (SELECT id FROM run WHERE outcome IS NOT NULL)";
+        const aged = this.db.prepare(`DELETE FROM run_activity WHERE at < ? AND ${finished}`).run(new Date(now.getTime() - retainMs).toISOString()).changes;
+        const over = this.db.prepare(`DELETE FROM run_activity WHERE ${finished} AND run NOT IN (SELECT run FROM run_activity WHERE ${finished} ORDER BY at DESC, run DESC LIMIT ?)`)
+            .run(Math.max(0, Math.floor(bound))).changes;
+        return Number(aged) + Number(over);
+    }
     /** One run's full checkpoint history, oldest first. */
     checkpointHistory(run) {
         return this.db.prepare("SELECT * FROM run_checkpoint WHERE run = ? ORDER BY id ASC").all(run).map(readRunCheckpoint);

package/dist/surface.js

@@ -135,6 +135,16 @@ const GUIDE_ROWS = [
     { invocation: "brief", synopsis: "with a saved central profile, --lead <id> --conversation <id> reads messages, proposals and saved work; --request-id inspects your saved receipt without resending; --local uses local DB catch-up, where --history selects the older operational report", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
     { invocation: "gaps", synopsis: "requirement gaps blocking dispatch", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag, repoFlag] },
     { invocation: "grants", synopsis: "list authority grants", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "audit", synopsis: "what people did on this server with their API tokens, newest first: when, who, which token, from the CLI (api) or an agent (mcp), the command or tool, the project and the outcome (ok, refused, error); an approver sees everyone in their projects, anyone else only themselves",
+        audience: "agent", agentMayInvoke: true, mutation: "none",
+        flags: [jsonFlag, dbFlag,
+            { name: "person", takesValue: true, meaning: "only this person's actions" },
+            { name: "token", takesValue: true, meaning: "only actions with the token of this name (on the server's own machine)" },
+            { name: "token-name", takesValue: true, meaning: "the same, where --token would be a credential (remotely)" },
+            { name: "source", takesValue: true, meaning: "api (the CLI) or mcp (an agent)" },
+            { name: "since", takesValue: true, meaning: "only the last N days, as Nd (7d)" },
+            { name: "limit", takesValue: true, meaning: "actions per page (default 20, at most 100)" },
+            { name: "cursor", takesValue: true, meaning: "the nextCursor of the previous page" }] },
     { invocation: "sync", synopsis: "refresh external-tracker mirrors and deliver write-backs — safe to run; fails closed", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
         flags: [jsonFlag, dbFlag, repoFlag], notableReasons: ["no-op", "external"] },
     { invocation: "task add", synopsis: "queue work", audience: "agent", agentMayInvoke: true, mutation: "keyed",
@@ -377,6 +387,10 @@ const GUIDE_ROWS = [
     operator("people invite", "mint a single-use sign-in link for one person — their powers are pinned when you mint, never after"),
     operator("people projects", "set a person's project access — selected project, all projects, or no projects"),
     operator("people revoke", "end a person's access — their sessions, invites, and signed modes end with them; history stays"),
+    operator("tokens create", "make one of your API tokens: --name, --access read|act, --days 30|90|365, optional --projects a,b; your password at the prompt or --password-stdin; the token is shown once"),
+    operatorRead("tokens list", "your API tokens: name, access, projects, made, last used, expiry — never a secret; your password at the prompt or --password-stdin"),
+    operator("tokens revoke", "end one of your API tokens now, by name or id; your password at the prompt or --password-stdin"),
+    operator("tokens rotate", "replace one of your API tokens on the same terms; the old one works 10 more minutes (--overlap), then stops; the new one is shown once"),
     operatorRead("mode show", "the repository's operating mode, in full — or 'locked' when none is signed"),
     operator("mode set", "sign a per-repository operating mode (password ceremony; standard or hands-off, always expiring)"),
     operator("publish merge", "say yes to ONE waiting merge — it fires only when CI is seen green on the exact commit you authorized"),
@@ -411,6 +425,7 @@ const GUIDE_ROWS = [
     operator("publish unblock", "lift a repair's merge hold"),
     operator("publish rearm", "re-arm a refused merge after fixing the named cause"),
     operator("serve", "the operations console (HTTP)"),
+    operatorRead("serve check-public", "is this server ready on its --public-url? checks the URL, --allow-host, the console on --port, the certificate, HSTS and the proxy, and names each problem; sends no credentials"),
     operator("watch", "the unattended loop, kept running"),
     operator("up", "console + worker + browser, one command"),
     operator("onboard", "add this repository, report signed-in agents, install or --remove the operator skill (--yes), offer the starter flows (--starter <ids>), and print the handoff"),
@@ -436,7 +451,7 @@ const REMOTE_NO = [
     // Workers, the loop and the services that run here.
     "claim", "heartbeat", "release", "reap", "tick", "build", "reconcile",
     "runner register", "runner retire", "runner bind", "runner capacity", "coordinator mint", "coordinator revoke", "mcp", "outbox deliver", "peek",
-    "serve", "watch", "up", "onboard", "daemon", "bridge", "setup show", "setup clear",
+    "serve", "serve check-public", "watch", "up", "onboard", "daemon", "bridge", "setup show", "setup clear",
     // Provider keys and model tools on this machine.
     "providers", "keys status", "keys set", "keys clear", "keys verify", "keys auth", "models check", "models update", "models watch",
     // Publication and release.
@@ -452,11 +467,13 @@ const REMOTE_STEP_UP = [
     "proposals", "decide", "task regate", "task approve", "task accept", "task merge", "run settle", "routine approve", "knowledge apply", "memory apply",
     "flows card approve", "flows card send-back", "flows script approve",
     "approver list", "approver add", "people list", "people invite", "people projects", "people revoke",
+    // A person's own API tokens: a password step-up on the server's machine, or the console. Never with a token.
+    "tokens create", "tokens list", "tokens revoke", "tokens rotate",
     "mode show", "mode set", "mode revoke", "chat-approval on", "review on", "review off", "config set", "config clear",
     "verify set", "verify clear", "verify level", "project checks", "project concurrency", "intake grant", "intake clear", "webhook primary",
 ];
 const REMOTE_YES = [
-    "status", "integrations", "ready", "gaps", "grants", "sync",
+    "status", "integrations", "ready", "gaps", "grants", "sync", "audit",
     "task add", "task ask", "task checks", "task add-tests", "task list", "task show", "check-progress", "task wait", "task complete", "task revise",
     "task state", "task block", "task unblock", "task next", "task steer", "task assign", "task scope", "task plan", "task hold", "task unhold", "task require",
     "task requeue", "task review", "task repair", "task route", "task reopen", "task stop", "task resume",