95923dd · f5ae598 · 4a10935 · c94ce74
@@ -1136,6 +1136,8 @@
While the default branch's own last check is red, the forge holds its pulls' che
A forge admin sees every declared flag at `/settings/flags` (Settings → Flags): why it exists, its default, the owner issue and its live value. Set it for the whole forge, for listed user ids or roles, or for a percentage of people; Clear returns it to the default. A change is validated, kept in the change record and live on the next request, with no restart. In the terminal the same admin opens the command palette (`ctrl+k`), picks Flags, and presses enter to set a flag from a line such as `forge=on users=u1,u2 roles=admin percent=30` or `x` to clear it; an agent is never an admin there either.
A forge admin sees every route the router knows at `/settings/usage` (Settings → Usage): its requests over the last 30 days, by role and by surface, and the hour of its last use. Routes with no request in the window are listed first, never-used ones before the longest-unused, as candidates to drop; the rest follow by count. Counts are per pattern, not per method. `usage` is also a boards source, for an admin only (an agent is refused); its `hour` column is text like `2026-10-16T13`, so group by a column such as `pattern` or `role`, not by a time bucket. In the terminal the same admin opens the command palette (`ctrl+k`), picks Usage, and reads the same list; an agent is never an admin there either.
## Limits
Every limit the owner can hit is declared in `src/settings/limits.ts` with its default, bounds and reason, and changed live by a forge admin at `/admin/limits`, `PUT /api/v1/admin/limits/:key` or the `limits` MCP tool (never by an agent). Each change is kept with who made it.
@@ -98,6 +98,26 @@
export const SOURCES: Readonly<Record<string, Source>> = {
      outcome: "text", at: "time",
    },
  },
  // Requests counted by the hour (`core/usage_count.ts`): admin only. `hour`
  // is `2026-10-16T13`, so `from` and `to` bound it by string and a bucket
      
        sentinelcrew
        29d ago
        
      
      Low: from and to are off by one hour for this source. runQuery turns them into new Date(v).toISOString(), for example 2026-10-16T12:00:00.000Z, and compares that with hour as a string. Because "2026-10-16T12" < "2026-10-16T12:00:00.000Z", from drops its own hour and to includes the hour it should stop before. Fix: store hour as a full ISO instant (…T13:00:00.000Z), or have the query trim the bound to 13 characters when src.time is an hour column. Add a test with a from on an hour boundary.
    
  // cannot read it; group by a column instead.
  usage: {
    table: "usage_count",
    owner: "admin",
    time: "hour",
    columns: {
      hour: "time", pattern: "text", method: "text", status: "text",
      role: "text", surface: "text", n: "number",
    },
    docs: {
      hour: "the hour the requests were answered in, UTC, like 2026-10-16T13",
      pattern: "the route pattern that matched, or (unmatched) for every path that matched none",
      status: "the status class: 2xx, 3xx, 4xx or 5xx",
      role: "anon, user, admin or agent",
      surface: "api, mcp or web",
      n: "requests in that hour with that pattern, method, status class, role and surface",
    },
  },
  // What the machine used (`boards/sampler.ts`, kept by `boards/ring.ts`):
  // 15-s points for the last day, 5-min points before that, never both
  // for one moment.
@@ -0,0 +1,56 @@
/**
 * What the router knows against what was used: every route pattern with its
 * requests over the last 30 days by role and by surface, and the hour of its
 * last use ever. A pattern with no request in the window is listed first, as
 * a candidate to drop; among those, the longest unused (or never used) leads.
 * Plain data in, plain data out: the page and its test both read it.
 */
import type { Database } from "bun:sqlite";
import { hourOf } from "./usage_count.ts";
export const WINDOW_DAYS = 30;
export interface RouteUsage {
  readonly pattern: string;
  readonly total: number;
  readonly roles: Readonly<Record<string, number>>;
  readonly surfaces: Readonly<Record<string, number>>;
  /** Hour of the last request ever (`2026-10-16T13`), or null for never. */
  readonly last: string | null;
}
/** Every known pattern, unused first (never, then oldest last use), then busiest. */
export function routeUsage(db: Database, patterns: readonly string[], now: Date): RouteUsage[] {
  const since = hourOf(new Date(now.getTime() - WINDOW_DAYS * 86_400_000));
  const rows = db
    .query(
      `SELECT pattern, role, surface, SUM(n) AS n FROM usage_count
       WHERE hour >= ?1 GROUP BY pattern, role, surface`,
    )
    .all(since) as { pattern: string; role: string; surface: string; n: number }[];
  const lasts = new Map(
    (db.query(`SELECT pattern, MAX(hour) AS last FROM usage_count GROUP BY pattern`).all() as {
      
        sentinelcrew
        29d ago
        
      
      Note: MAX(hour) GROUP BY pattern reads all of usage_count, because the primary key starts with hour and nothing prunes the table. That is fine for an admin page today. If the page slows down, add retention or an index on (pattern, hour).
    
      
        sentinelcrew
        29d ago
        
      
      Medium, performance. MAX(hour) … GROUP BY pattern has no WHERE, so every load of /settings/usage (and every open of the terminal screen) scans all of usage_count. Nothing prunes that table, and it gains rows every hour for every combination of pattern, method, status, role and surface. That is small today, but after a year it is far past the forge's millisecond page budget. Fix: give usage_count a retention (for example 90 days, deleted by whatever already flushes the counter), so 'never' means 'not within the retention'. Or compute last use only for the patterns that are unused in the window, against an index on (pattern, hour).
    
      pattern: string;
      last: string;
    }[]).map((r) => [r.pattern, r.last]),
  );
  const by = new Map<string, { total: number; roles: Record<string, number>; surfaces: Record<string, number> }>();
  for (const r of rows) {
    const e = by.get(r.pattern) ?? { total: 0, roles: {}, surfaces: {} };
    e.total += r.n;
    e.roles[r.role] = (e.roles[r.role] ?? 0) + r.n;
    e.surfaces[r.surface] = (e.surfaces[r.surface] ?? 0) + r.n;
    by.set(r.pattern, e);
  }
  return [...new Set(patterns)]
    .map((pattern): RouteUsage => {
      const e = by.get(pattern);
      return { pattern, total: e?.total ?? 0, roles: e?.roles ?? {}, surfaces: e?.surfaces ?? {}, last: lasts.get(pattern) ?? null };
    })
    .sort((a, b) => {
      if ((a.total === 0) !== (b.total === 0)) return a.total === 0 ? -1 : 1;
      if (a.total === 0) return (a.last ?? "").localeCompare(b.last ?? "") || a.pattern.localeCompare(b.pattern);
      return b.total - a.total || a.pattern.localeCompare(b.pattern);
    });
}
@@ -68,6 +68,11 @@
export class Router<H> {
    return [...heads].sort();
  }
  /** Every pattern given to `add`, once each, in the order added. */
  patterns(): string[] {
    return [...new Set(this.routes.map((r) => r.pattern))];
  }
  add(method: string, pattern: string, handler: H): this {
    this.routes.push({ method, pattern, segments: compile(pattern), handler });
    return this;
@@ -15,6 +15,7 @@
import { systemPage } from "../web/pages/system.ts";
import { telemetryPage, telemetrySet } from "../web/pages/telemetry.ts";
import { contributePage } from "../web/pages/contribute.ts";
import { flagsPage, flagsSet } from "../web/pages/flags.ts";
import { usagePage } from "../web/pages/usage.ts";
import { domainsPage } from "../web/pages/domains.ts";
import { resiliencePage } from "../web/pages/resilience.ts";
import { limitsPage, limitsSet, quotasSet, signupSet } from "../web/pages/admin-limits.ts";
@@ -763,6 +764,7 @@
export function buildRouter(): Router<Handler> {
  router.add("POST", "/boards/:slug/:op", boardPost);
  router.add("GET", "/settings/flags", flagsPage);
  router.add("POST", "/settings/flags", flagsSet);
  router.add("GET", "/settings/usage", (ctx) => usagePage(ctx, knownPatterns));
  router.add("GET", "/admin/limits", limitsPage);
  router.add("POST", "/admin/limits", limitsSet);
      
        sentinelcrew
        29d ago
        outdated
      
      Only the web door gets this. The terminal needs the same report (a tui/screens/usage.ts fed by the same pattern list), gated like Flags.
    
  router.add("POST", "/admin/quotas", quotasSet);
@@ -1288,6 +1290,12 @@
export function buildApiRouter(): Router<Handler> {
  return router;
}
let known: string[] | undefined;
/** Every pattern the studio's and the API's routers know, read once on first use. */
export function knownPatterns(): string[] {
  return (known ??= [...buildRouter().patterns(), ...buildApiRouter().patterns()]);
}
async function withGitAccess(
  ctx: Ctx,
  service: GitService,
@@ -42,6 +42,7 @@
import { dashboardScreen } from "./screens/dashboard.ts";
import { mayManageFlags } from "../core/flags.ts";
import { accessScreen } from "./screens/access.ts";
import { flagsScreen } from "./screens/flags.ts";
import { usageScreen } from "./screens/usage.ts";
import { quotasScreen } from "./screens/quotas.ts";
import { domainsScreen } from "./screens/domains.ts";
import { resilienceLines, resilienceScreen } from "./screens/resilience.ts";
@@ -345,6 +346,14 @@
export function forgeCommands(session: Session): (ctx: Ctx) => Command[] {
        hint: "declared flags and their live values",
        run: () => ctx.push(flagsScreen(session, ctx)),
      });
    // Settings → Usage, as the page has it: the same gate as Flags (#1565).
    if (mayManageFlags(session.user))
      commands.push({
        id: "usage",
        title: "Usage",
        hint: "every route, unused ones first",
        run: () => ctx.push(usageScreen(session, ctx)),
      });
    // Account quotas, as /admin/limits has them: an admin who is not an agent (#2191).
    if (session.user?.isAdmin === true && session.user.kind !== "agent")
      commands.push({
@@ -0,0 +1,52 @@
/**
 * Usage in the terminal, a forge admin's (#1565): every route pattern with
 * its requests over the last 30 days by role and by surface, unused ones
 * first with their last use or `never`, as Settings → Usage lists them
 * (`routeUsage`). The gate is the page's: an admin who is not an agent;
 * anyone else sees nothing.
 */
import { mayManageFlags } from "../../core/flags.ts";
import { ROLES, SURFACES } from "../../core/usage_count.ts";
import { routeUsage, WINDOW_DAYS, type RouteUsage } from "../../core/usage_report.ts";
import { knownPatterns } from "../../http/server.ts";
      
        sentinelcrew
        29d ago
        
      
      Low, structure. This is the first src/tui module to import http/server.ts. It loads the whole HTTP server and builds both routers just to list their patterns. A small http/known_patterns.ts that the page, the terminal and the test all import would keep the terminal from depending on the server module.
    
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import { style } from "../term/style.ts";
import { truncate } from "../term/width.ts";
import type { Session } from "../session.ts";
import { fill, len, split } from "../ui/layout.ts";
import { ListState, drawList, type ListRow } from "./common.ts";
const part = (counts: Readonly<Record<string, number>>, keys: readonly string[]) =>
  keys.map((k) => `${k} ${counts[k] ?? 0}`).join(" ");
export function usageRows(r: readonly RouteUsage[]): ListRow[] {
  return r.map((u) => ({
    title: u.pattern,
    secondary: `${u.total}`,
    meta: `${part(u.roles, ROLES)}  ${part(u.surfaces, SURFACES)}  last ${u.last === null ? "never" : `${u.last.replace("T", " ")}:00`}`,
  }));
}
export function usageScreen(f: Session, ctx: Ctx): Screen {
  const state = new ListState();
  const allowed = mayManageFlags(f.user);
  // Read once when the screen opens: the report scans the whole table, so a frame or a key never re-runs it.
      
        sentinelcrew
        29d ago
        outdated
      
      This runs routeUsage (two GROUP BY passes over all of usage_count, one with no time bound) on every render and every key. Compute it once when the screen opens and keep the array.
    
  const rows: RouteUsage[] = allowed ? routeUsage(f.db, knownPatterns(), new Date()) : [];
  return {
    title: "Usage",
    keys: [binding(["j", "k"], "move cursor")],
    render(area, s) {
      const c = ctx.theme.c;
      const [head, list] = split(area, "v", [len(1), fill(1)]);
      const all = rows;
      const text = !allowed
        ? "Usage is read by a forge admin."
        : `${all.filter((r) => r.total === 0).length} of ${all.length} routes had no request in ${WINDOW_DAYS} days; unused first.`;
      s.text(head!.x, head!.y, truncate(text, head!.w), style(c.mutedFg, c.bg), head!.x + head!.w);
      drawList(s, list!, c, state, usageRows(all));
    },
      
        sentinelcrew
        29d ago
        outdated
      
      rows().length re-runs the whole report to move the cursor one row. Use the array computed when the screen opened.
    
    key: (e) => state.key(e, rows.length),
  };
}
@@ -75,6 +75,7 @@
export type AccountSection =
  | "keys"
  | "passkeys"
  | "origins"
  | "usage"
  | "crew"
  | "accounts"
  | "subscriptions"
@@ -167,6 +168,12 @@
export function accountSections(
            icon: "activity" as const,
            current: current === "flags",
          },
          {
            label: "Usage",
            href: "/settings/usage",
            icon: "activity" as const,
            current: current === "usage",
          },
          {
            label: "Backups",
            href: "/settings/backups",
@@ -0,0 +1,64 @@
/**
 * Usage, for a forge admin: every route pattern the router knows with its
 * requests over the last 30 days by role and by surface. The unused ones
 * come first, each with its last use or "never": candidates to drop.
 * Anyone else is told 403, and an agent is never an admin here.
 */
import { mayManageFlags } from "../../core/flags.ts";
import { ROLES, SURFACES } from "../../core/usage_count.ts";
import { routeUsage, WINDOW_DAYS } from "../../core/usage_report.ts";
import type { Ctx } from "../../http/context.ts";
import { settingsLayout, signInFirst } from "../chrome.ts";
import { html } from "../html.ts";
import { page } from "../layout.ts";
import { btn, card, empty, icon } from "../ui.ts";
import { accountSections } from "./origins.ts";
const part = (counts: Readonly<Record<string, number>>, keys: readonly string[]) =>
  keys.map((k) => `${k} ${counts[k] ?? 0}`).join(" · ");
// GET /settings/usage
export function usagePage(ctx: Ctx, patterns: () => readonly string[]): Response {
      
        sentinelcrew
        29d ago
        
      
      Add a test that an agent account with isAdmin gets 403 here. mayManageFlags handles it, but nothing pins it.
    
  const user = ctx.auth.user;
  if (!user) return signInFirst(ctx);
  if (!mayManageFlags(user))
    return page(
      {
        ctx,
        title: "Forbidden",
        body: html`<div class="page-head"><h1>403</h1></div>
          ${empty({
            icon: "lock",
            title: "Admins only",
            note: "Usage is read by a forge admin.",
            action: btn("Go home", { href: "/", variant: "primary" }),
          })}`,
      },
      403,
    );
  const rows = routeUsage(ctx.app.db, patterns(), new Date());
  const unused = rows.filter((r) => r.total === 0).length;
  const body = card(
    html`<p class="muted small card-body">${String(unused)} of ${String(rows.length)} routes had no request in
        ${String(WINDOW_DAYS)} days; they are listed first. Counted by <code>usage_count</code>; one pattern
        covers every method.</p>
      <table class="table" aria-label="Route usage">
        <thead><tr><th scope="col">Pattern</th><th scope="col" class="num">${String(WINDOW_DAYS)} days</th>
          <th scope="col">By role</th><th scope="col">By surface</th><th scope="col">Last use (UTC)</th></tr></thead>
        <tbody>${rows.map(
          (r) => html`<tr data-unused="${r.total === 0 ? "1" : "0"}">
            <td class="mono">${r.pattern}</td><td class="num mono">${String(r.total)}</td>
            <td class="mono small">${part(r.roles, ROLES)}</td><td class="mono small">${part(r.surfaces, SURFACES)}</td>
            <td class="mono">${r.last === null ? "never" : r.last.replace("T", " ") + ":00"}</td></tr>`,
        )}</tbody>
      </table>`,
    { head: html`${icon("activity")}<h2>Usage</h2>`, pad: false },
  );
  return page({
    ctx,
    title: "Usage",
    body: html`<div class="page-head"><h1>Usage</h1></div>
      ${settingsLayout(accountSections("usage", { admin: true }), body, "Account settings")}`,
  });
}
@@ -74,7 +74,7 @@
afterAll(async () => {
describe("tell the crew in the terminal", () => {
  test("the owner's palette has the row", async () => {
    expect(await palette(alice, [":"])).toContain("alice/lobby — Tell the crew");
    expect(await palette(alice, [":", "tell"])).toContain("alice/lobby — Tell the crew");
  });
  test("a reader who may not direct the crew sees no row", async () => {
@@ -0,0 +1,81 @@
/** Usage in the terminal (#1565): an admin who is not an agent sees unused routes on top; nobody else has the command. */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App as Forge } from "../src/app.ts";
import { hourOf } from "../src/core/usage_count.ts";
import { createUser, getUserByName } from "../src/core/users.ts";
import { createForgeApp } from "../src/tui/forge.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
import { quietLogs } from "./helpers/globals.ts";
import { settleApp } from "./helpers/tui.ts";
quietLogs();
let dataDir: string;
let forge: Forge;
function boot(username: string) {
  const user = getUserByName(forge.db, username)!;
  const { app } = createForgeApp(
    forge,
    { sshUsername: "t", remoteAddress: "127.0.0.1", user },
    { terminal: headlessTerminal(140, 32), exitHooks: false },
  );
  app.start();
  const key = (k: string, ctrl = false) => app.dispatch({ type: "key", key: k, ctrl, alt: false, shift: false });
  return {
    text: () => app.screen.toText(),
    palette: async (word: string) => {
      key("k", true);
      for (const ch of word) key(ch);
      await settleApp(app);
    },
    enter: async () => {
      key("enter");
      await settleApp(app);
    },
    stop: () => app.stop(),
  };
}
beforeAll(async () => {
  dataDir = await mkdtemp(join(tmpdir(), "forge-tui-usage-"));
  forge = createApp({ dataDir, port: 0 });
  for (const [username, adminIfFirst] of [["alice", true], ["bob", false], ["carol", false]] as const) {
    const made = await createUser(forge.db, {
      trusted: true, username, email: `${username}@forge.local`, password: "a-good-passphrase", adminIfFirst,
    });
    if (!made.ok) throw new Error(made.error);
  }
  forge.db.query("UPDATE user SET is_admin = 1, is_agent = 1 WHERE username = 'carol'").run();
  forge.db.run(
    "INSERT INTO usage_count (hour, pattern, method, status, role, surface, n) VALUES (?, '/system', 'GET', '2xx', 'admin', 'web', 5)",
    [hourOf(new Date())],
  );
});
afterAll(async () => {
  forge.close();
  await rm(dataDir, { recursive: true, force: true });
});
test("an admin's terminal lists unused routes first, with never, and the count line", async () => {
  const h = boot("alice");
  await h.palette("Usage");
  await h.enter();
  const text = h.text();
  expect(text).toMatch(/\d+ of \d+ routes had no request in 30 days; unused first/);
  expect(text).toContain("last never");
  expect(text).not.toContain("admin 5"); // the one used route sorts below every unused one
  h.stop();
});
test("a non-admin and an admin agent have no command", async () => {
  for (const who of ["bob", "carol"]) {
    const h = boot(who);
    await h.palette("Usage");
    expect(h.text()).not.toContain("every route, unused ones first");
    h.stop();
  }
});
@@ -0,0 +1,95 @@
/** The usage page lists every known route, unused ones first; `usage` is an admin-only boards source (#1565). */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser } from "../src/core/users.ts";
import { hourOf } from "../src/core/usage_count.ts";
import { routeUsage } from "../src/core/usage_report.ts";
import { buildApiRouter, buildRouter, serve, type Servers } from "../src/http/server.ts";
let dir: string;
let app: App;
let servers: Servers;
const tok: Record<string, string> = {};
const now = new Date("2026-10-16T12:30:00Z");
const ago = (days: number) => hourOf(new Date(now.getTime() - days * 86_400_000));
function seed(hour: string, pattern: string, role: string, surface: string, n: number) {
  app.db.run(
    "INSERT INTO usage_count (hour, pattern, method, status, role, surface, n) VALUES (?, ?, 'GET', '2xx', ?, ?, ?)",
    [hour, pattern, role, surface, n],
  );
}
beforeAll(async () => {
  dir = await mkdtemp(join(tmpdir(), "forge-usage-report-"));
  app = createApp({ dataDir: dir, port: 0 });
  servers = await serve(app);
  const mk = async (username: string, adminIfFirst?: boolean) => {
    const r = await createUser(app.db, {
      trusted: true, username, email: `${username}@forge.local`,
      password: "a-good-passphrase", ...(adminIfFirst ? { adminIfFirst } : {}),
    });
    if (!r.ok) throw new Error(r.error);
    return r.value;
  };
  tok.admin = createToken(app.db, (await mk("alice", true)).id, "t", "admin").token;
  const carol = await mk("carol");
  app.db.query("UPDATE user SET is_admin = 1, is_agent = 1 WHERE id = ?").run(carol.id);
  tok.carol = createToken(app.db, carol.id, "t", "admin").token;
  tok.bob = createToken(app.db, (await mk("bob")).id, "t", "admin").token;
});
afterAll(async () => {
  servers.stop();
  app.close();
  await rm(dir, { recursive: true, force: true });
});
test("an unused route is first, with its last use or never; used ones follow by count", () => {
  seed(ago(1), "/busy", "user", "web", 5);
  seed(ago(1), "/busy", "agent", "api", 2);
  seed(ago(2), "/quiet", "admin", "web", 1);
  seed(ago(45), "/stale", "user", "web", 9); // outside the 30 days
  const rows = routeUsage(app.db, ["/busy", "/quiet", "/stale", "/never"], now);
  expect(rows.map((r) => r.pattern)).toEqual(["/never", "/stale", "/busy", "/quiet"]);
  expect(rows[0]).toMatchObject({ total: 0, last: null });
  expect(rows[1]).toMatchObject({ total: 0, last: ago(45) });
  expect(rows[2]).toMatchObject({ total: 7, roles: { user: 5, agent: 2 }, surfaces: { web: 5, api: 2 } });
});
test("the page lists every pattern both routers know, unused first, and only to an admin", async () => {
  const known = [...buildRouter().patterns(), ...buildApiRouter().patterns()];
  seed(hourOf(new Date()), "/system", "admin", "web", 3);
  const get = (who: string | null) =>
    fetch(`${servers.url}/settings/usage`, { headers: who ? { authorization: `Bearer ${tok[who]}` } : {} });
  const res = await get("admin");
  expect(res.status).toBe(200);
  const text = await res.text();
  for (const p of known) expect(text).toContain(p.replace(/&/g, "&amp;"));
  expect(text.indexOf('data-unused="1"')).toBeGreaterThan(-1);
  expect(text.indexOf('data-unused="1"')).toBeLessThan(text.indexOf('data-unused="0"'));
  expect(text).toContain("never");
  expect((await get("bob")).status).toBe(403);
  expect((await get("carol")).status).toBe(403); // an agent account is never an admin here
  expect(await (await get(null)).text()).not.toContain("Route usage");
});
test("usage is a boards source for an admin and for nobody else", async () => {
  const q = (who: string) =>
    fetch(`${servers.url}/api/v1/boards/query`, {
      method: "POST",
      headers: { authorization: `Bearer ${tok[who]}`, "content-type": "application/json" },
      body: JSON.stringify({ source: "usage", aggregate: "sum", column: "n", groupBy: "pattern" }),
    });
  const ok = await q("admin");
  expect(ok.status).toBe(200);
  const rows = ((await ok.json()) as { rows: { group: string; value: number }[] }).rows;
  expect(rows.find((r) => r.group === "/busy")?.value).toBe(7);
  expect((await q("bob")).status).toBe(403);
  expect((await q("carol")).status).toBe(403); // an admin agent is refused too
});
		@@ -1136,6 +1136,8 @@ While the default branch's own last check is red, the forge holds its pulls' che
1136	1136
1137	1137	A forge admin sees every declared flag at `/settings/flags` (Settings → Flags): why it exists, its default, the owner issue and its live value. Set it for the whole forge, for listed user ids or roles, or for a percentage of people; Clear returns it to the default. A change is validated, kept in the change record and live on the next request, with no restart. In the terminal the same admin opens the command palette (`ctrl+k`), picks Flags, and presses enter to set a flag from a line such as `forge=on users=u1,u2 roles=admin percent=30` or `x` to clear it; an agent is never an admin there either.
1138	1138
	1139	A forge admin sees every route the router knows at `/settings/usage` (Settings → Usage): its requests over the last 30 days, by role and by surface, and the hour of its last use. Routes with no request in the window are listed first, never-used ones before the longest-unused, as candidates to drop; the rest follow by count. Counts are per pattern, not per method. `usage` is also a boards source, for an admin only (an agent is refused); its `hour` column is text like `2026-10-16T13`, so group by a column such as `pattern` or `role`, not by a time bucket. In the terminal the same admin opens the command palette (`ctrl+k`), picks Usage, and reads the same list; an agent is never an admin there either.
	1140
1139	1141	## Limits
1140	1142
1141	1143	Every limit the owner can hit is declared in `src/settings/limits.ts` with its default, bounds and reason, and changed live by a forge admin at `/admin/limits`, `PUT /api/v1/admin/limits/:key` or the `limits` MCP tool (never by an agent). Each change is kept with who made it.
		@@ -98,6 +98,26 @@ export const SOURCES: Readonly<Record<string, Source>> = {
98	98	outcome: "text", at: "time",
99	99	},
100	100	},
	101	// Requests counted by the hour (`core/usage_count.ts`): admin only. `hour`
	102	// is `2026-10-16T13`, so `from` and `to` bound it by string and a bucket
		sentinelcrew 29d ago Low: `from` and `to` are off by one hour for this source. `runQuery` turns them into `new Date(v).toISOString()`, for example `2026-10-16T12:00:00.000Z`, and compares that with `hour` as a string. Because `"2026-10-16T12" < "2026-10-16T12:00:00.000Z"`, `from` drops its own hour and `to` includes the hour it should stop before. Fix: store `hour` as a full ISO instant (`…T13:00:00.000Z`), or have the query trim the bound to 13 characters when `src.time` is an hour column. Add a test with a `from` on an hour boundary.
	103	// cannot read it; group by a column instead.
	104	usage: {
	105	table: "usage_count",
	106	owner: "admin",
	107	time: "hour",
	108	columns: {
	109	hour: "time", pattern: "text", method: "text", status: "text",
	110	role: "text", surface: "text", n: "number",
	111	},
	112	docs: {
	113	hour: "the hour the requests were answered in, UTC, like 2026-10-16T13",
	114	pattern: "the route pattern that matched, or (unmatched) for every path that matched none",
	115	status: "the status class: 2xx, 3xx, 4xx or 5xx",
	116	role: "anon, user, admin or agent",
	117	surface: "api, mcp or web",
	118	n: "requests in that hour with that pattern, method, status class, role and surface",
	119	},
	120	},
101	121	// What the machine used (`boards/sampler.ts`, kept by `boards/ring.ts`):
102	122	// 15-s points for the last day, 5-min points before that, never both
103	123	// for one moment.
		@@ -0,0 +1,56 @@
	1	/**
	2	* What the router knows against what was used: every route pattern with its
	3	* requests over the last 30 days by role and by surface, and the hour of its
	4	* last use ever. A pattern with no request in the window is listed first, as
	5	* a candidate to drop; among those, the longest unused (or never used) leads.
	6	* Plain data in, plain data out: the page and its test both read it.
	7	*/
	8
	9	import type { Database } from "bun:sqlite";
	10	import { hourOf } from "./usage_count.ts";
	11
	12	export const WINDOW_DAYS = 30;
	13
	14	export interface RouteUsage {
	15	readonly pattern: string;
	16	readonly total: number;
	17	readonly roles: Readonly<Record<string, number>>;
	18	readonly surfaces: Readonly<Record<string, number>>;
	19	/** Hour of the last request ever (`2026-10-16T13`), or null for never. */
	20	readonly last: string \| null;
	21	}
	22
	23	/** Every known pattern, unused first (never, then oldest last use), then busiest. */
	24	export function routeUsage(db: Database, patterns: readonly string[], now: Date): RouteUsage[] {
	25	const since = hourOf(new Date(now.getTime() - WINDOW_DAYS * 86_400_000));
	26	const rows = db
	27	.query(
	28	`SELECT pattern, role, surface, SUM(n) AS n FROM usage_count
	29	WHERE hour >= ?1 GROUP BY pattern, role, surface`,
	30	)
	31	.all(since) as { pattern: string; role: string; surface: string; n: number }[];
	32	const lasts = new Map(
	33	(db.query(`SELECT pattern, MAX(hour) AS last FROM usage_count GROUP BY pattern`).all() as {
		sentinelcrew 29d ago Note: `MAX(hour) GROUP BY pattern` reads all of `usage_count`, because the primary key starts with `hour` and nothing prunes the table. That is fine for an admin page today. If the page slows down, add retention or an index on `(pattern, hour)`. sentinelcrew 29d ago Medium, performance. `MAX(hour) … GROUP BY pattern` has no `WHERE`, so every load of `/settings/usage` (and every open of the terminal screen) scans all of `usage_count`. Nothing prunes that table, and it gains rows every hour for every combination of pattern, method, status, role and surface. That is small today, but after a year it is far past the forge's millisecond page budget. Fix: give `usage_count` a retention (for example 90 days, deleted by whatever already flushes the counter), so 'never' means 'not within the retention'. Or compute last use only for the patterns that are unused in the window, against an index on `(pattern, hour)`.
	34	pattern: string;
	35	last: string;
	36	}[]).map((r) => [r.pattern, r.last]),
	37	);
	38	const by = new Map<string, { total: number; roles: Record<string, number>; surfaces: Record<string, number> }>();
	39	for (const r of rows) {
	40	const e = by.get(r.pattern) ?? { total: 0, roles: {}, surfaces: {} };
	41	e.total += r.n;
	42	e.roles[r.role] = (e.roles[r.role] ?? 0) + r.n;
	43	e.surfaces[r.surface] = (e.surfaces[r.surface] ?? 0) + r.n;
	44	by.set(r.pattern, e);
	45	}
	46	return [...new Set(patterns)]
	47	.map((pattern): RouteUsage => {
	48	const e = by.get(pattern);
	49	return { pattern, total: e?.total ?? 0, roles: e?.roles ?? {}, surfaces: e?.surfaces ?? {}, last: lasts.get(pattern) ?? null };
	50	})
	51	.sort((a, b) => {
	52	if ((a.total === 0) !== (b.total === 0)) return a.total === 0 ? -1 : 1;
	53	if (a.total === 0) return (a.last ?? "").localeCompare(b.last ?? "") \|\| a.pattern.localeCompare(b.pattern);
	54	return b.total - a.total \|\| a.pattern.localeCompare(b.pattern);
	55	});
	56	}
		@@ -68,6 +68,11 @@ export class Router<H> {
68	68	return [...heads].sort();
69	69	}
70	70
	71	/** Every pattern given to `add`, once each, in the order added. */
	72	patterns(): string[] {
	73	return [...new Set(this.routes.map((r) => r.pattern))];
	74	}
	75
71	76	add(method: string, pattern: string, handler: H): this {
72	77	this.routes.push({ method, pattern, segments: compile(pattern), handler });
73	78	return this;
		@@ -15,6 +15,7 @@ import { systemPage } from "../web/pages/system.ts";
15	15	import { telemetryPage, telemetrySet } from "../web/pages/telemetry.ts";
16	16	import { contributePage } from "../web/pages/contribute.ts";
17	17	import { flagsPage, flagsSet } from "../web/pages/flags.ts";
	18	import { usagePage } from "../web/pages/usage.ts";
18	19	import { domainsPage } from "../web/pages/domains.ts";
19	20	import { resiliencePage } from "../web/pages/resilience.ts";
20	21	import { limitsPage, limitsSet, quotasSet, signupSet } from "../web/pages/admin-limits.ts";
		@@ -763,6 +764,7 @@ export function buildRouter(): Router<Handler> {
763	764	router.add("POST", "/boards/:slug/:op", boardPost);
764	765	router.add("GET", "/settings/flags", flagsPage);
765	766	router.add("POST", "/settings/flags", flagsSet);
	767	router.add("GET", "/settings/usage", (ctx) => usagePage(ctx, knownPatterns));
766	768	router.add("GET", "/admin/limits", limitsPage);
767	769	router.add("POST", "/admin/limits", limitsSet);
		sentinelcrew 29d ago outdated Only the web door gets this. The terminal needs the same report (a `tui/screens/usage.ts` fed by the same pattern list), gated like Flags.
768	770	router.add("POST", "/admin/quotas", quotasSet);
		@@ -1288,6 +1290,12 @@ export function buildApiRouter(): Router<Handler> {
1288	1290	return router;
1289	1291	}
1290	1292
	1293	let known: string[] \| undefined;
	1294	/** Every pattern the studio's and the API's routers know, read once on first use. */
	1295	export function knownPatterns(): string[] {
	1296	return (known ??= [...buildRouter().patterns(), ...buildApiRouter().patterns()]);
	1297	}
	1298
1291	1299	async function withGitAccess(
1292	1300	ctx: Ctx,
1293	1301	service: GitService,
		@@ -42,6 +42,7 @@ import { dashboardScreen } from "./screens/dashboard.ts";
42	42	import { mayManageFlags } from "../core/flags.ts";
43	43	import { accessScreen } from "./screens/access.ts";
44	44	import { flagsScreen } from "./screens/flags.ts";
	45	import { usageScreen } from "./screens/usage.ts";
45	46	import { quotasScreen } from "./screens/quotas.ts";
46	47	import { domainsScreen } from "./screens/domains.ts";
47	48	import { resilienceLines, resilienceScreen } from "./screens/resilience.ts";
		@@ -345,6 +346,14 @@ export function forgeCommands(session: Session): (ctx: Ctx) => Command[] {
345	346	hint: "declared flags and their live values",
346	347	run: () => ctx.push(flagsScreen(session, ctx)),
347	348	});
	349	// Settings → Usage, as the page has it: the same gate as Flags (#1565).
	350	if (mayManageFlags(session.user))
	351	commands.push({
	352	id: "usage",
	353	title: "Usage",
	354	hint: "every route, unused ones first",
	355	run: () => ctx.push(usageScreen(session, ctx)),
	356	});
348	357	// Account quotas, as /admin/limits has them: an admin who is not an agent (#2191).
349	358	if (session.user?.isAdmin === true && session.user.kind !== "agent")
350	359	commands.push({
		@@ -0,0 +1,52 @@
	1	/**
	2	* Usage in the terminal, a forge admin's (#1565): every route pattern with
	3	* its requests over the last 30 days by role and by surface, unused ones
	4	* first with their last use or `never`, as Settings → Usage lists them
	5	* (`routeUsage`). The gate is the page's: an admin who is not an agent;
	6	* anyone else sees nothing.
	7	*/
	8
	9	import { mayManageFlags } from "../../core/flags.ts";
	10	import { ROLES, SURFACES } from "../../core/usage_count.ts";
	11	import { routeUsage, WINDOW_DAYS, type RouteUsage } from "../../core/usage_report.ts";
	12	import { knownPatterns } from "../../http/server.ts";
		sentinelcrew 29d ago Low, structure. This is the first `src/tui` module to import `http/server.ts`. It loads the whole HTTP server and builds both routers just to list their patterns. A small `http/known_patterns.ts` that the page, the terminal and the test all import would keep the terminal from depending on the server module.
	13	import type { Ctx, Screen } from "../app/app.ts";
	14	import { binding } from "../app/keys.ts";
	15	import { style } from "../term/style.ts";
	16	import { truncate } from "../term/width.ts";
	17	import type { Session } from "../session.ts";
	18	import { fill, len, split } from "../ui/layout.ts";
	19	import { ListState, drawList, type ListRow } from "./common.ts";
	20
	21	const part = (counts: Readonly<Record<string, number>>, keys: readonly string[]) =>
	22	keys.map((k) => `${k} ${counts[k] ?? 0}`).join(" ");
	23
	24	export function usageRows(r: readonly RouteUsage[]): ListRow[] {
	25	return r.map((u) => ({
	26	title: u.pattern,
	27	secondary: `${u.total}`,
	28	meta: `${part(u.roles, ROLES)} ${part(u.surfaces, SURFACES)} last ${u.last === null ? "never" : `${u.last.replace("T", " ")}:00`}`,
	29	}));
	30	}
	31
	32	export function usageScreen(f: Session, ctx: Ctx): Screen {
	33	const state = new ListState();
	34	const allowed = mayManageFlags(f.user);
	35	// Read once when the screen opens: the report scans the whole table, so a frame or a key never re-runs it.
		sentinelcrew 29d ago outdated This runs `routeUsage` (two GROUP BY passes over all of `usage_count`, one with no time bound) on every render and every key. Compute it once when the screen opens and keep the array.
	36	const rows: RouteUsage[] = allowed ? routeUsage(f.db, knownPatterns(), new Date()) : [];
	37	return {
	38	title: "Usage",
	39	keys: [binding(["j", "k"], "move cursor")],
	40	render(area, s) {
	41	const c = ctx.theme.c;
	42	const [head, list] = split(area, "v", [len(1), fill(1)]);
	43	const all = rows;
	44	const text = !allowed
	45	? "Usage is read by a forge admin."
	46	: `${all.filter((r) => r.total === 0).length} of ${all.length} routes had no request in ${WINDOW_DAYS} days; unused first.`;
	47	s.text(head!.x, head!.y, truncate(text, head!.w), style(c.mutedFg, c.bg), head!.x + head!.w);
	48	drawList(s, list!, c, state, usageRows(all));
	49	},
		sentinelcrew 29d ago outdated `rows().length` re-runs the whole report to move the cursor one row. Use the array computed when the screen opened.
	50	key: (e) => state.key(e, rows.length),
	51	};
	52	}
		@@ -75,6 +75,7 @@ export type AccountSection =
75	75	\| "keys"
76	76	\| "passkeys"
77	77	\| "origins"
	78	\| "usage"
78	79	\| "crew"
79	80	\| "accounts"
80	81	\| "subscriptions"
		@@ -167,6 +168,12 @@ export function accountSections(
167	168	icon: "activity" as const,
168	169	current: current === "flags",
169	170	},
	171	{
	172	label: "Usage",
	173	href: "/settings/usage",
	174	icon: "activity" as const,
	175	current: current === "usage",
	176	},
170	177	{
171	178	label: "Backups",
172	179	href: "/settings/backups",
		@@ -0,0 +1,64 @@
	1	/**
	2	* Usage, for a forge admin: every route pattern the router knows with its
	3	* requests over the last 30 days by role and by surface. The unused ones
	4	* come first, each with its last use or "never": candidates to drop.
	5	* Anyone else is told 403, and an agent is never an admin here.
	6	*/
	7
	8	import { mayManageFlags } from "../../core/flags.ts";
	9	import { ROLES, SURFACES } from "../../core/usage_count.ts";
	10	import { routeUsage, WINDOW_DAYS } from "../../core/usage_report.ts";
	11	import type { Ctx } from "../../http/context.ts";
	12	import { settingsLayout, signInFirst } from "../chrome.ts";
	13	import { html } from "../html.ts";
	14	import { page } from "../layout.ts";
	15	import { btn, card, empty, icon } from "../ui.ts";
	16	import { accountSections } from "./origins.ts";
	17
	18	const part = (counts: Readonly<Record<string, number>>, keys: readonly string[]) =>
	19	keys.map((k) => `${k} ${counts[k] ?? 0}`).join(" · ");
	20
	21	// GET /settings/usage
	22	export function usagePage(ctx: Ctx, patterns: () => readonly string[]): Response {
		sentinelcrew 29d ago Add a test that an agent account with `isAdmin` gets 403 here. `mayManageFlags` handles it, but nothing pins it.
	23	const user = ctx.auth.user;
	24	if (!user) return signInFirst(ctx);
	25	if (!mayManageFlags(user))
	26	return page(
	27	{
	28	ctx,
	29	title: "Forbidden",
	30	body: html`<div class="page-head"><h1>403</h1></div>
	31	${empty({
	32	icon: "lock",
	33	title: "Admins only",
	34	note: "Usage is read by a forge admin.",
	35	action: btn("Go home", { href: "/", variant: "primary" }),
	36	})}`,
	37	},
	38	403,
	39	);
	40	const rows = routeUsage(ctx.app.db, patterns(), new Date());
	41	const unused = rows.filter((r) => r.total === 0).length;
	42	const body = card(
	43	html`<p class="muted small card-body">${String(unused)} of ${String(rows.length)} routes had no request in
	44	${String(WINDOW_DAYS)} days; they are listed first. Counted by <code>usage_count</code>; one pattern
	45	covers every method.</p>
	46	<table class="table" aria-label="Route usage">
	47	<thead><tr><th scope="col">Pattern</th><th scope="col" class="num">${String(WINDOW_DAYS)} days</th>
	48	<th scope="col">By role</th><th scope="col">By surface</th><th scope="col">Last use (UTC)</th></tr></thead>
	49	<tbody>${rows.map(
	50	(r) => html`<tr data-unused="${r.total === 0 ? "1" : "0"}">
	51	<td class="mono">${r.pattern}</td><td class="num mono">${String(r.total)}</td>
	52	<td class="mono small">${part(r.roles, ROLES)}</td><td class="mono small">${part(r.surfaces, SURFACES)}</td>
	53	<td class="mono">${r.last === null ? "never" : r.last.replace("T", " ") + ":00"}</td></tr>`,
	54	)}</tbody>
	55	</table>`,
	56	{ head: html`${icon("activity")}<h2>Usage</h2>`, pad: false },
	57	);
	58	return page({
	59	ctx,
	60	title: "Usage",
	61	body: html`<div class="page-head"><h1>Usage</h1></div>
	62	${settingsLayout(accountSections("usage", { admin: true }), body, "Account settings")}`,
	63	});
	64	}
		@@ -74,7 +74,7 @@ afterAll(async () => {
74	74
75	75	describe("tell the crew in the terminal", () => {
76	76	test("the owner's palette has the row", async () => {
77		expect(await palette(alice, [":"])).toContain("alice/lobby — Tell the crew");
	77	expect(await palette(alice, [":", "tell"])).toContain("alice/lobby — Tell the crew");
78	78	});
79	79
80	80	test("a reader who may not direct the crew sees no row", async () => {