@coreplane/switchboard 1.242.0 → 1.244.0

package/dist/assets/config/config.example.yaml

@@ -11,7 +11,11 @@ providers:
   anthropic:
     type: anthropic
     apiKeyEnv: ANTHROPIC_API_KEY
-  # Any OpenAI-compatible endpoint works with the same adapter:
+  # OpenAI itself runs on the same compatible adapter: any preset's model may
+  # be openai/<model-id> anywhere a model is accepted. The adapter speaks Chat
+  # Completions, not the Responses API, sends no reasoning control (our effort
+  # tiers do not reach these models), and meters tokens without pricing them.
+  # A first-class OpenAI block is a plan's business, not this file's.
   openai:
     type: openai-compatible
     baseUrl: https://api.openai.com/v1
@@ -65,10 +69,19 @@ defaults:
   # clipped (the card and the run record say so); a preset whose identity or
   # class is above a cap is refused by name before any executor exists. Absent →
   # nothing is capped and every preset runs exactly its declared profile.
+  # A fourth field, `confirm`, is the front door's and caps no run: the first
+  # blast-radius class a command the router bound from prose is handed back at
+  # (`To run this: …`) instead of run — `write` (every write is handed back; a
+  # read or a repository's own test or build runs) or `destructive` (a write
+  # runs at once; only a destructive one is handed back). It intersects toward
+  # caution like the run axes — a channel or a user can only ask MORE than what
+  # is set here — and unset everywhere it is the built-in `write`. `exec` and
+  # `never` are refused by name.
   # boundary:
   #   maxMinutes: 120
   #   maxIdentity: write
   #   machines: [none, blank, repo-cold, repo-resident]
+  #   confirm: write
 
 # PR reviews and the reading diff (docs/reference/specs/reading-diff.md). Every
 # review records its full `git diff`; the ABRIDGED version (meat.dev, run on
@@ -436,6 +449,12 @@ workspaceDir: ./workspaces
 #       r2Buckets:                                # optional: bucket name → label for buckets not named <worker>-cache
 #         some-other-bucket: uploads
 #       anthropicWorkspaceId: wrkspc_...          # this app's Anthropic workspace
+#   prices:                                    # optional: USD per million tokens by <provider>/<model>, the ref a run's
+#     openai/gpt-5:                            #   spans name — for a model the Anthropic list does not know, or to
+#       input: 1.25                            #   override the list; all four kinds named (a provider with no
+#       output: 10                             #   cache-write charge says 0). A model neither knows is "unpriced",
+#       cacheRead: 0.125                       #   never $0, on the costs page and on a run's own page
+#       cacheWrite: 0
 
 # Delivery indicators: GET /delivery and `delivery report` (docs/reference/specs/delivery.md).
 # Optional. Needs a GitHub credential (the App triple or GH_TOKEN); read-only on GitHub.

package/dist/assets/deploy/cloudflare-memory/worker.ts

@@ -25,6 +25,7 @@ import {
   isRunSession,
   isRunVisibilityFilter,
   normalizeStored,
+  pullRequestNumberOf,
   RETENTION_BOUNDS,
   RUN_EVENTS_DEFAULT_PAGE,
   RUN_EVENTS_MAX_PAGE,
@@ -59,11 +60,11 @@ import {
 } from "../../src/core/runLedger/sessionLog.ts";
 import type { RunEvent } from "../../src/core/runEvents.ts";
 import {
-  aggregateUsageByUser,
   isRunUsage,
   usageOfEvents,
   type RunUsage,
-  type RunUsageReport,
+  type RunUsageRows,
+  type UsageIdentity,
   type UsageRun,
 } from "../../src/core/runUsage.ts";
 import {
@@ -626,6 +627,27 @@ export class ScheduleDO extends DurableObject<Env> {
 // for optimistic concurrency: a `put` whose `expectedVersion` is stale is a 409,
 // never a silent clobber (the bot and the CLI both write this document).
 
+/** What the bot posts to mint a confirmation: the facts this object judges on
+ *  and the bot's own row as an opaque body (routing-and-config item 25). */
+interface ConfirmationInput {
+  id: string;
+  threadKey: string;
+  requester: string;
+  body: Record<string, unknown>;
+}
+/** A stored confirmation as a consume returns it: the input plus the expiry this object stamped. */
+interface ConfirmationRow extends ConfirmationInput {
+  expiresAt: number;
+}
+/** Why a consume or a cancel refused: the row is gone (`used`), past its expiry (`expired`), or someone else's (`foreign`). */
+type ConfirmationRefusal = "used" | "expired" | "foreign";
+type ConfirmationOutcome = { row: ConfirmationRow } | { refused: ConfirmationRefusal };
+type ConfirmationCancelOutcome = { ok: true } | { refused: Exclude<ConfirmationRefusal, "expired"> };
+
+function isJsonObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
 export class ConfigDO extends DurableObject<Env> {
   private readonly sql: SqlStorage;
 
@@ -649,9 +671,91 @@ export class ConfigDO extends DurableObject<Env> {
         expires_at INTEGER NOT NULL,
         ticket TEXT NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS confirmations (
+        id TEXT PRIMARY KEY,
+        thread_key TEXT NOT NULL,
+        requester TEXT NOT NULL,
+        expires_at INTEGER NOT NULL,
+        body TEXT NOT NULL
+      );
     `);
   }
 
+  // ---- Confirmations (docs/reference/specs/routing-and-config.md item 25): the
+  // row a routed write is offered as, minted by the bot and consumed once at
+  // the click. The body is the bot's row, opaque here; this object owns the
+  // three facts the consume decides on — the thread (one pending row per
+  // thread), the requester (the click must be theirs) and the expiry, stamped
+  // and judged on this object's clock so two bot processes alive during a roll
+  // read one answer. Nothing sweeps: expiry is checked on touch.
+
+  /** Insert the row and drop the thread's older one in one transaction; the
+   *  expiry is `now + ttlMs`, stamped here and answered to the caller. */
+  async putConfirmation(row: ConfirmationInput, ttlMs: number, now: number): Promise<number> {
+    const expiresAt = now + ttlMs;
+    this.ctx.storage.transactionSync(() => {
+      this.sql.exec(`DELETE FROM confirmations WHERE thread_key = ?`, row.threadKey);
+      this.sql.exec(
+        `INSERT OR REPLACE INTO confirmations (id, thread_key, requester, expires_at, body) VALUES (?, ?, ?, ?, ?)`,
+        row.id,
+        row.threadKey,
+        row.requester,
+        expiresAt,
+        JSON.stringify(row.body),
+      );
+    });
+    return expiresAt;
+  }
+
+  /** Read, judge and delete in one transaction on the single-threaded object,
+   *  so a confirmation runs at most once whatever the click timing: a missing
+   *  row is `used`, a row past its expiry is deleted and `expired`, a requester
+   *  none of `actorIds` names is `foreign` (the row stays for its requester),
+   *  and otherwise the row is deleted and returned. */
+  async consumeConfirmation(id: string, actorIds: readonly string[], now: number): Promise<ConfirmationOutcome> {
+    return this.ctx.storage.transactionSync(() => {
+      const stored = this.readConfirmation(id);
+      if (!stored) return { refused: "used" };
+      if (stored.expiresAt <= now) {
+        this.sql.exec(`DELETE FROM confirmations WHERE id = ?`, id);
+        return { refused: "expired" };
+      }
+      if (!actorIds.includes(stored.requester)) return { refused: "foreign" };
+      this.sql.exec(`DELETE FROM confirmations WHERE id = ?`, id);
+      return { row: stored };
+    });
+  }
+
+  /** Delete the row under the same requester check as a consume; a missing row
+   *  is `used`. Expiry plays no part: cancelling an expired offer still leaves
+   *  nothing pending, which is what the click asked for. */
+  async cancelConfirmation(id: string, actorIds: readonly string[]): Promise<ConfirmationCancelOutcome> {
+    return this.ctx.storage.transactionSync(() => {
+      const stored = this.readConfirmation(id);
+      if (!stored) return { refused: "used" };
+      if (!actorIds.includes(stored.requester)) return { refused: "foreign" };
+      this.sql.exec(`DELETE FROM confirmations WHERE id = ?`, id);
+      return { ok: true };
+    });
+  }
+
+  private readConfirmation(id: string): ConfirmationRow | undefined {
+    const row = this.sql
+      .exec<{ thread_key: string; requester: string; expires_at: number; body: string }>(
+        `SELECT thread_key, requester, expires_at, body FROM confirmations WHERE id = ?`,
+        id,
+      )
+      .toArray()[0];
+    if (!row) return undefined;
+    return {
+      id,
+      threadKey: row.thread_key,
+      requester: row.requester,
+      expiresAt: row.expires_at,
+      body: parseStored(row.body, isJsonObject) ?? {},
+    };
+  }
+
   // ---- MCP sealed credentials + connect tickets (docs/reference/specs/mcp-tools.md items 15–16).
   // Ciphertext the bot sealed — opaque here — and one-time tickets: the two
   // things a config document must never carry, kept beside it on this object.
@@ -1051,8 +1155,21 @@ const CONFIG_ROUTES = new Set([
   "/config/tickets/put",
   "/config/tickets/get",
   "/config/tickets/transition",
+  "/config/confirmations/put",
+  "/config/confirmations/consume",
+  "/config/confirmations/cancel",
 ]);
 const TICKET_STATES: ReadonlySet<string> = new Set<McpTicketState>(MCP_TICKET_STATES);
+/** A confirmation id as the bot mints it (a UUID) — one token, no whitespace, bounded. */
+const CONFIRMATION_ID_RE = /^[A-Za-z0-9_-]{8,128}$/;
+
+/** The `{ id, actorIds }` a consume or a cancel carries, or the 400 that refuses it. */
+function confirmationClickOf(b: Record<string, unknown>): { id: string; actorIds: string[] } | Response {
+  if (typeof b.id !== "string" || !CONFIRMATION_ID_RE.test(b.id)) return json({ error: "id malformed" }, 400);
+  if (!Array.isArray(b.actorIds) || !b.actorIds.every((a): a is string => typeof a === "string"))
+    return json({ error: "actorIds must be a list of actor ids" }, 400);
+  return { id: b.id, actorIds: b.actorIds };
+}
 
 async function handleConfig(pathname: string, body: unknown, env: Env): Promise<Response> {
   const b = (typeof body === "object" && body !== null ? body : {}) as Record<string, unknown>;
@@ -1094,6 +1211,38 @@ async function handleConfig(pathname: string, body: unknown, env: Env): Promise<
       );
       return json({ ok: true, applied });
     }
+    // Confirmations (routing-and-config item 25): the body is the bot's row,
+    // stored verbatim; the expiry is this object's clock plus the ttl the bot
+    // passed, never a timestamp the bot chose.
+    case "/config/confirmations/put": {
+      if (typeof b.id !== "string" || !CONFIRMATION_ID_RE.test(b.id)) return json({ error: "id malformed" }, 400);
+      if (typeof b.threadKey !== "string" || !b.threadKey) return json({ error: "threadKey required" }, 400);
+      if (typeof b.requester !== "string" || !b.requester) return json({ error: "requester required" }, 400);
+      if (!isJsonObject(b.body)) return json({ error: "body must be a JSON object" }, 400);
+      if (typeof b.ttlMs !== "number" || !Number.isInteger(b.ttlMs) || b.ttlMs < 0)
+        return json({ error: "ttlMs must be a non-negative integer" }, 400);
+      const expiresAt = await dO.putConfirmation(
+        { id: b.id, threadKey: b.threadKey, requester: b.requester, body: b.body },
+        b.ttlMs,
+        systemClock(),
+      );
+      console.log(`[config/confirmations/put] ${b.threadKey} ${b.id} expires_at=${expiresAt}`);
+      return json({ ok: true, expiresAt });
+    }
+    case "/config/confirmations/consume": {
+      const click = confirmationClickOf(b);
+      if (click instanceof Response) return click;
+      const outcome = await dO.consumeConfirmation(click.id, click.actorIds, systemClock());
+      console.log(`[config/confirmations/consume] ${click.id} ${"row" in outcome ? "consumed" : outcome.refused}`);
+      return json(outcome);
+    }
+    case "/config/confirmations/cancel": {
+      const click = confirmationClickOf(b);
+      if (click instanceof Response) return click;
+      const outcome = await dO.cancelConfirmation(click.id, click.actorIds);
+      console.log(`[config/confirmations/cancel] ${click.id} ${"ok" in outcome ? "cancelled" : outcome.refused}`);
+      return json(outcome);
+    }
     default:
       break;
   }
@@ -1265,13 +1414,15 @@ export class RunHistoryDO extends DurableObject<Env> {
     this.migrateRunsTable();
     // The indexes the visibility predicate's leaves walk (`channel_id IN`,
     // `channel_visibility IN`, `user_id =`), each ordered like the page; the
-    // session the sweep asks about; the parent a children listing filters on.
+    // session the sweep asks about; the parent a children listing filters on;
+    // the pull request a findings listing filters on.
     this.sql.exec(`
       CREATE INDEX IF NOT EXISTS runs_channel_finished ON runs(channel_id, finished_at DESC, run_id DESC);
       CREATE INDEX IF NOT EXISTS runs_visibility_finished ON runs(channel_visibility, finished_at DESC, run_id DESC);
       CREATE INDEX IF NOT EXISTS runs_user_finished ON runs(user_id, finished_at DESC, run_id DESC);
       CREATE INDEX IF NOT EXISTS runs_session ON runs(session_key);
       CREATE INDEX IF NOT EXISTS runs_parent ON runs(parent_run_id, finished_at DESC, run_id DESC);
+      CREATE INDEX IF NOT EXISTS runs_pr ON runs(repo, pr_number, finished_at DESC, run_id DESC);
     `);
     // The sessions registry (session-log item 7): every session log a run of
     // this store claimed, with its thread — the sweep cannot enumerate the
@@ -1438,7 +1589,11 @@ export class RunHistoryDO extends DurableObject<Env> {
    *  aggregate fills it from the run's stored events. The parent a child names
    *  (run-history item 46), the column a children listing filters on: the
    *  record already carries it in `summary_json`, so existing rows are filled
-   *  from there once, and every later `put` writes it beside the row. */
+   *  from there once, and every later `put` writes it beside the row. The pull
+   *  request a run names (run-history item 58; `pullRequestNumberOf`), the
+   *  column a findings listing filters on: the same one-time fill from
+   *  `summary_json` — the coding post-step's `pr`, else a posted review's
+   *  target — and every later `put` writes it beside the row. */
   migrateRunsTable(): void {
     const columns = new Set(
       this.sql
@@ -1457,6 +1612,19 @@ export class RunHistoryDO extends DurableObject<Env> {
          WHERE json_type(summary_json, '$.parentRunId') = 'text'`,
       );
     }
+    if (!columns.has("pr_number")) {
+      this.sql.exec(`ALTER TABLE runs ADD COLUMN pr_number INTEGER`);
+      // `pullRequestNumberOf` in SQL: the coding post-step's pull request, else
+      // the one a posted review targeted (a skipped post has no target).
+      this.sql.exec(
+        `UPDATE runs SET pr_number = COALESCE(
+           CASE WHEN json_type(summary_json, '$.pr.number') = 'integer' THEN json_extract(summary_json, '$.pr.number') END,
+           CASE WHEN json_extract(summary_json, '$.reviewPost.posted') = 1
+                 AND json_type(summary_json, '$.reviewPost.target.number') = 'integer'
+                THEN json_extract(summary_json, '$.reviewPost.target.number') END
+         )`,
+      );
+    }
   }
 
   private liveByThread(threadKey: string): LiveRunRow | undefined {
@@ -1970,8 +2138,8 @@ export class RunHistoryDO extends DurableObject<Env> {
         );
       this.sql.exec(
         `INSERT INTO runs (run_id, label, agent, model, channel_id, user_id, thread_key, channel_visibility, repo, started_at, finished_at, stored_at, status,
-                           event_count, stored_event_count, truncated, bytes, diagnosis_json, summary_json, session_key, usage_json, parent_run_id)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                           event_count, stored_event_count, truncated, bytes, diagnosis_json, summary_json, session_key, usage_json, parent_run_id, pr_number)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(run_id) DO UPDATE SET
            label = excluded.label, agent = excluded.agent, model = excluded.model, channel_id = excluded.channel_id,
            user_id = excluded.user_id, thread_key = excluded.thread_key, channel_visibility = excluded.channel_visibility,
@@ -1981,7 +2149,8 @@ export class RunHistoryDO extends DurableObject<Env> {
            bytes = excluded.bytes, diagnosis_json = excluded.diagnosis_json, summary_json = excluded.summary_json,
            session_key = excluded.session_key,
            usage_json = COALESCE(excluded.usage_json, runs.usage_json),
-           parent_run_id = excluded.parent_run_id`,
+           parent_run_id = excluded.parent_run_id,
+           pr_number = excluded.pr_number`,
         stored.id,
         stored.label ?? null,
         stored.agent ?? null,
@@ -2004,6 +2173,7 @@ export class RunHistoryDO extends DurableObject<Env> {
         stored.session?.key ?? null,
         stored.usage ? JSON.stringify(stored.usage) : null,
         stored.parentRunId ?? null,
+        pullRequestNumberOf(stored) ?? null,
       );
       // The session's registry row learns its newest finish (session-log item
       // 7); a record that reaches the store without a claim (the plain put
@@ -2208,28 +2378,32 @@ export class RunHistoryDO extends DurableObject<Env> {
   }
 
   /**
-   * Who spent what, per UTC day (costs.md, cost by user), over the runs that
-   * finished in [sinceMs, untilMs) and are inside the retention window. A row
-   * written before `usage_json` existed is filled in here from its stored
-   * `model.turn` events — up to USAGE_BACKFILL_PER_CALL a call, the rest
-   * reported as `pending` — so the history heals as it is read, with no
+   * What the runs that finished in [sinceMs, untilMs) and are inside the
+   * retention window cost (costs.md items 10–10a; run-history item 56): one row
+   * per run — its requester, thread, channel, agent and usage — plus the
+   * identity of every parent a child names that is outside the batch, so the
+   * bot bills the child without a second read. The arithmetic is the bot's; the
+   * Worker only reads its rows. A row written before `usage_json` existed is
+   * filled in here from its stored `model.turn` events — up to
+   * USAGE_BACKFILL_PER_CALL a call, the rest answered without `usage` and
+   * counted in `pending` — so the history heals as it is read, with no
    * operator step; a run without turns is written back as the zero usage so it
-   * is not re-read. A child is billed to its parent's requester; a parent
-   * outside the range is looked up by id.
+   * is not re-read.
    */
-  usageByUser(sinceMs: number, untilMs: number): RunUsageReport {
+  usage(sinceMs: number, untilMs: number): RunUsageRows {
     const now = systemClock();
     const { policy } = this.policyState();
     const cutoff = now - policy.retentionDays * 86_400_000;
     const rows = this.sql
       .exec<UsageRow>(
-        `SELECT run_id, user_id, started_at, finished_at, usage_json, summary_json FROM runs
+        `SELECT run_id, user_id, agent, channel_id, thread_key, started_at, finished_at, usage_json, summary_json FROM runs
           WHERE finished_at >= ? AND finished_at < ? ORDER BY finished_at ASC, run_id ASC`,
         Math.max(sinceMs, cutoff),
         untilMs,
       )
       .toArray();
     let backfilled = 0;
+    let pending = 0;
     const runs: UsageRun[] = rows.map((row) => {
       let usage = parseUsageJson(row.usage_json);
       if (usage === undefined && backfilled < USAGE_BACKFILL_PER_CALL) {
@@ -2237,31 +2411,38 @@ export class RunHistoryDO extends DurableObject<Env> {
         this.sql.exec(`UPDATE runs SET usage_json = ? WHERE run_id = ?`, JSON.stringify(usage), row.run_id);
         backfilled += 1;
       }
+      if (usage === undefined) pending += 1;
       const who = identityOfSummary(row.summary_json);
       return {
         id: row.run_id,
         userId: row.user_id,
         ...(who.userName ? { userName: who.userName } : {}),
         ...(who.parentRunId ? { parentRunId: who.parentRunId } : {}),
+        threadKey: row.thread_key,
+        channelId: row.channel_id,
+        ...(row.agent ? { agent: row.agent } : {}),
         startedAt: row.started_at,
         finishedAt: row.finished_at,
         ...(usage ? { usage } : {}),
       };
     });
-    const lookupParent = (id: string) => {
+    // The parents a child names that are not in the batch: looked up once each, known or not.
+    const inBatch = new Set(runs.map((r) => r.id));
+    const parents: Record<string, UsageIdentity> = {};
+    for (const id of new Set(runs.map((r) => r.parentRunId).filter((p): p is string => !!p && !inBatch.has(p)))) {
       const p = this.sql
         .exec<{ user_id: string; summary_json: string }>(`SELECT user_id, summary_json FROM runs WHERE run_id = ?`, id)
         .toArray()[0];
-      if (!p) return undefined;
+      if (!p) continue;
       const who = identityOfSummary(p.summary_json);
-      return { userId: p.user_id, ...(who.userName ? { userName: who.userName } : {}) };
-    };
-    const { rows: out, pending } = aggregateUsageByUser(runs, lookupParent);
+      parents[id] = { userId: p.user_id, ...(who.userName ? { userName: who.userName } : {}) };
+    }
     const earliest = this.sql
       .exec<{ m: number | null }>(`SELECT MIN(finished_at) AS m FROM runs WHERE finished_at >= ?`, cutoff)
       .one().m;
     return {
-      rows: out,
+      runs,
+      parents,
       pending,
       ...(earliest !== null ? { earliestFinishedAt: earliest } : {}),
       retentionDays: policy.retentionDays,
@@ -2343,6 +2524,11 @@ export class RunHistoryDO extends DurableObject<Env> {
       where.push(`parent_run_id = ?`);
       params.push(q.parentRunId);
     }
+    if (q.pr !== undefined) {
+      // `namesPullRequest` in SQL: the row's repository and the number it names.
+      where.push(`repo = ?`, `pr_number = ?`);
+      params.push(q.pr.repo, q.pr.number);
+    }
     if (q.visibleTo !== undefined && q.visibleTo.kind !== "all") where.push(visibilitySql(q.visibleTo, params));
     const select = `SELECT run_id, agent, channel_id, finished_at, bytes, event_count, summary_json FROM runs WHERE ${where.join(" AND ")} ORDER BY finished_at DESC, run_id DESC`;
     // `LIMIT` holds on the over-bound path too: the kept set is the newest
@@ -2423,6 +2609,9 @@ const USAGE_BACKFILL_PER_CALL = 200;
 type UsageRow = {
   run_id: string;
   user_id: string;
+  agent: string | null;
+  channel_id: string;
+  thread_key: string;
   started_at: number;
   finished_at: number;
   usage_json: string | null;
@@ -2590,12 +2779,26 @@ function parseRunList(body: unknown): Validated<{ storeKey: string; query: RunLi
     if (!id.ok) return invalid("parentRunId must match ^[A-Za-z0-9_-]{1,64}$");
     query.parentRunId = id.value;
   }
+  if (b.pr !== undefined) {
+    const pr = b.pr as Record<string, unknown> | null;
+    if (
+      typeof pr !== "object" ||
+      pr === null ||
+      typeof pr.repo !== "string" ||
+      !REPO_SLUG.test(pr.repo) ||
+      typeof pr.number !== "number" ||
+      !Number.isInteger(pr.number) ||
+      pr.number < 1
+    )
+      return invalid("pr must be { repo: owner/name, number: a positive integer }");
+    query.pr = { repo: pr.repo, number: pr.number };
+  }
   if (b.visibleTo !== undefined) {
     // A malformed filter is a 400, never "all": the bot degrades to live rows
     // rather than the DO widening what an actor may see.
     if (!isRunVisibilityFilter(b.visibleTo)) return invalid("visibleTo must be a run visibility filter");
-    if (boundParameters(b.visibleTo) > DO_MAX_BOUND_PARAMETERS - RUN_LIST_BASE_PARAMETERS)
-      return invalid(`visibleTo names more than ${DO_MAX_BOUND_PARAMETERS - RUN_LIST_BASE_PARAMETERS} ids`);
+    const headroom = DO_MAX_BOUND_PARAMETERS - RUN_LIST_BASE_PARAMETERS - (query.pr ? RUN_LIST_PR_PARAMETERS : 0);
+    if (boundParameters(b.visibleTo) > headroom) return invalid(`visibleTo names more than ${headroom} ids`);
     query.visibleTo = b.visibleTo;
   }
   return { ok: true, value: { storeKey: key.value, query } };
@@ -2604,6 +2807,8 @@ function parseRunList(body: unknown): Validated<{ storeKey: string; query: RunLi
 /** Parameters the page query binds before any filter: the cursor pair (3) and the age floor (1),
  *  plus `agent`, `channel`, `threadKey`, `parentRunId`, and the LIMIT at most — the headroom `visibleTo` must fit under. */
 const RUN_LIST_BASE_PARAMETERS = 9;
+/** The two more a `pr` filter binds (`repo`, `pr_number`), taken from the same headroom only when asked. */
+const RUN_LIST_PR_PARAMETERS = 2;
 
 /** How many `?` a filter binds (one per id, one per user). */
 function boundParameters(f: RunVisibilityFilter): number {
@@ -3800,13 +4005,13 @@ async function handleRuns(pathname: string, body: unknown, env: Env): Promise<Re
     );
     return json(result ?? { events: null });
   }
-  if (pathname === "/runs/usage-by-user") {
+  if (pathname === "/runs/usage") {
     const parsed = parseRunUsageQuery(body);
     if (!parsed.ok) return json({ error: parsed.error }, 400);
     const { storeKey, sinceMs, untilMs } = parsed.value;
-    const report = await stub(storeKey).usageByUser(sinceMs, untilMs);
-    console.log(`[runs/usage-by-user] ${storeKey} -> ${report.rows.length} rows, ${report.pending} pending`);
-    return json(report);
+    const rows = await stub(storeKey).usage(sinceMs, untilMs);
+    console.log(`[runs/usage] ${storeKey} -> ${rows.runs.length} runs, ${rows.pending} pending`);
+    return json(rows);
   }
   // /runs/delete
   const parsed = parseRunTarget(body);
@@ -3831,7 +4036,7 @@ const ROUTES = new Set([
   "/runs/summary",
   "/runs/list",
   "/runs/events",
-  "/runs/usage-by-user",
+  "/runs/usage",
   "/runs/delete",
   ...LEDGER_ROUTES,
 ]);

package/dist/assets/deploy/cloudflare-resident/gc.ts

@@ -79,6 +79,10 @@ export interface ReclaimInput {
   isDefaultRef: boolean;
   /** Thread exec/read/write currently running on this binding. */
   busy: number;
+  /** A run registered on the thread — attached and not yet released (item
+   *  44): its process lives in the container between the bot's calls, so
+   *  `busy` reads 0 while its model thinks. Held is kept, whatever the fate. */
+  held: boolean;
 }
 
 /** The PR that decided the fate (for the audit trail): the open one, else the
@@ -93,11 +97,13 @@ export type ReclaimWhy =
   | "no-pr"
   | "fate-unknown"
   | "busy"
+  | "run-held"
   | "re-attached"
   | Extract<RefFate, "gone" | "merged" | "closed">;
 
 /** Evict this binding now? A finished ref (gone/merged/closed) is reclaimed
- *  when nothing runs on it — and nothing else is asked. What its tree holds
+ *  when nothing runs on it — no op in flight and no run registered from its
+ *  attach to its release — and nothing else is asked. What its tree holds
  *  is never a reason to keep it: a run starts from a clean tree, so dirt in a
  *  tree no run is using protects nothing (the next attach wipes it); the
  *  Worker measures and records what it removes instead. Keeps are named so
@@ -113,6 +119,7 @@ export function reclaimDecision(input: ReclaimInput): { reclaim: boolean; why: R
       return { reclaim: false, why: "fate-unknown" };
   }
   if (input.busy > 0) return { reclaim: false, why: "busy" };
+  if (input.held) return { reclaim: false, why: "run-held" };
   return { reclaim: true, why: input.fate };
 }