2d1d680
@@ -685,6 +685,18 @@
it named none). The run that starts then resumes the same session in that
clone and is told to carry on. A task is paused at most six times before
the forge stops waiting on it.
Each subscription keeps a _standing_ (`core/standing.ts`): where it is in
its 5-hour and weekly windows — started, resets, cap, used, remaining, in
US dollars of list price. When the provider turns a run away, the window
it named and its reset are kept as _read_; everything else is _inferred_
from the usage ledger — a window opens at the first run after the last one
closed, and the cap is what the crew had spent when the provider last
called the window full (a person's own use is not in the ledger, so it is
a floor). An operator keeps a share of every window for people
(Settings → Subscriptions, 0–90%); `crewRemaining` is what is left after
it. Both read on `GET /api/v1/repos/:owner/:name/usage` and the MCP
`usage` tool, under `standing`.
The agent runs Claude Code headless in its clone, with a prompt the forge
composes: who it is, what the task is, how to finish, and what will be
refused. Permissions are the forge's, passed as settings: file tools
@@ -38,7 +38,7 @@
for a tunnel and a forge that sleeps.
| `take_updates` | a fork takes its parent's updates when git can do it alone; a conflict is refused                 | yes    |
| `converge`     | the fork's crew merges where both sides changed the same files; comes back as a pull              | yes    |
| `map`          | an app's plan: ready now, waiting on what, the critical path, where the crew is (`app`)           |        |
| `usage`        | `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue; a writer's |        |
| `usage`        | `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's |        |
| `link`         | `{ app, issue, blockedBy }`: the issue waits for another; loops and cross-repository are refused  | yes    |
| `unlink`       | `{ app, issue, blockedBy }`: the issue stops waiting for it                                       | yes    |
| `plan`         | `{ app, issues }`: open up to 12 linked issues, all or none (see below)                           | yes    |
@@ -6,7 +6,7 @@
    "ready": 90
  },
  "check": {
    "run": "bun x tsc --noEmit && bun scripts/test-shards.ts --timeout 60000 test/crew.test.ts test/crew-wrapup.test.ts test/crew-limits.test.ts test/crew-sandbox.test.ts test/steer.test.ts test/landing.test.ts test/decide.test.ts test/ledger.test.ts test/checks.test.ts test/dependencies.test.ts test/autonomy.test.ts test/studio.test.ts test/studio-words.test.ts test/forks.test.ts test/fork-flow.test.ts test/cross-repo-pull.test.ts test/pulls.test.ts test/apps.test.ts test/apps-adversarial.test.ts test/apps-busy.test.ts test/web.test.ts test/git-trust.test.ts test/helpers.test.ts test/shards.test.ts test/migrate.test.ts test/vitals.test.ts test/asks.test.ts test/feed.test.ts test/feed-page.test.ts test/offline.test.ts test/share.test.ts test/cloud.test.ts test/run-secrets.test.ts test/forge-cloudflare.test.ts test/usage.test.ts",
    "run": "bun x tsc --noEmit && bun scripts/test-shards.ts --timeout 60000 test/crew.test.ts test/crew-wrapup.test.ts test/crew-limits.test.ts test/crew-sandbox.test.ts test/steer.test.ts test/landing.test.ts test/decide.test.ts test/ledger.test.ts test/checks.test.ts test/dependencies.test.ts test/autonomy.test.ts test/studio.test.ts test/studio-words.test.ts test/forks.test.ts test/fork-flow.test.ts test/cross-repo-pull.test.ts test/pulls.test.ts test/apps.test.ts test/apps-adversarial.test.ts test/apps-busy.test.ts test/web.test.ts test/git-trust.test.ts test/helpers.test.ts test/shards.test.ts test/migrate.test.ts test/vitals.test.ts test/asks.test.ts test/feed.test.ts test/feed-page.test.ts test/offline.test.ts test/share.test.ts test/cloud.test.ts test/run-secrets.test.ts test/forge-cloudflare.test.ts test/usage.test.ts test/standing.test.ts",
    "timeout": 1800
  }
}
@@ -5,12 +5,17 @@
 * the predicate the run pages use for cost), so a reader who cannot write
 * the repository is refused. The API route and the MCP `usage` tool both
 * answer from here, so they never disagree.
 *
 * With it, each account's standing (`core/standing.ts`): where it is in its
 * 5-hour and weekly windows, account-wide. The accounts shown are those
 * granted here or on the owner, and those that paid for a run here.
 */
import type { App } from "../app.ts";
import { getIssuesByIds } from "../core/issues.ts";
import { canSeeOwnerFacts, type Repo } from "../core/repos.ts";
import { listSubscriptions } from "../core/subscriptions.ts";
import { standing, type Standing } from "../core/standing.ts";
import { listGrants, listSubscriptions } from "../core/subscriptions.ts";
import {
  recentUsage,
  usageTotals,
@@ -56,6 +61,10 @@
export interface UsageReport {
    readonly agent: string | null;
    readonly issue: number | null;
  })[];
  /** Each account this app spends: its windows, now, every figure read or inferred. */
  readonly standing: readonly (Omit<Standing, "subscriptionId"> & {
    readonly subscription: string;
  })[];
}
const ZERO: Omit<UsageTotals, "key"> = {
@@ -121,6 +130,21 @@
export function readUsage(
    ZERO,
  );
  // Granted at the repository or its owner, any agent, or spent here.
  const accounts = new Set<string>();
  for (const g of [...listGrants(db, repo.id), ...listGrants(db, repo.ownerId)])
    accounts.add(g.subscriptionId);
  for (const row of bySubscription)
    if (row.key !== null && subscriptions.has(row.key)) accounts.add(row.key);
  const standings = [...accounts]
    .flatMap((id) => {
      const s = standing(db, id, now);
      if (s === undefined) return [];
      const { subscriptionId: _, ...rest } = s;
      return [{ subscription: subscriptions.get(id) ?? id, ...rest }];
    })
    .sort((a, b) => a.subscription.localeCompare(b.subscription));
  return ok({
    app: `${repo.ownerName}/${repo.name}`,
    days,
@@ -138,5 +162,6 @@
export function readUsage(
      agent: agentName(r.agentId),
      issue: issueNumber(r.issueId),
    })),
    standing: standings,
  });
}
@@ -1025,4 +1025,20 @@
export const migrations: readonly string[] = [
  CREATE INDEX IF NOT EXISTS usage_repo ON usage(repo_id, at);
  CREATE INDEX IF NOT EXISTS usage_subscription ON usage(subscription_id, at);
  `,
  // 38 — a subscription's standing (`core/standing.ts`): the last time the
  // provider said each window (5-hour, weekly) was full and when it resets,
  // and the share of every window the operator keeps for people.
  `
  CREATE TABLE subscription_limit (
    subscription_id TEXT NOT NULL REFERENCES subscription(id) ON DELETE CASCADE,
    span            TEXT NOT NULL CHECK (span IN ('5h','week')),
    resets_at       TEXT NOT NULL,
    observed_at     TEXT NOT NULL,
    said            TEXT NOT NULL DEFAULT '',
    PRIMARY KEY (subscription_id, span)
  );
  ALTER TABLE subscription ADD COLUMN headroom_pct INTEGER NOT NULL DEFAULT 0
    CHECK (headroom_pct BETWEEN 0 AND 90);
  `,
];
@@ -0,0 +1,336 @@
/**
 * Standing — where one subscription is in each of the windows its provider
 * meters it over: the 5-hour session window and the week. Per window: when
 * it started and resets, the cap, what is used, what remains, and what of
 * that the crew may spend once the operator's headroom for people is kept.
 *
 * Every figure says where it came from:
 * - `read` — the provider said it. Claude Code's refusal names the window
 *   and its reset (`crew/limits.ts`'s `limitOf`); the runner notes it here
 *   with `noteLimit`. While that reset is ahead, the window is full.
 * - `inferred` — worked out from the usage ledger (`core/usage.ts`).
 *
 * Units, stated once: money is US dollars of the provider's list-price
 * equivalent (`usage.cost_usd`), rounded to 1/10 000 of a dollar; tokens
 * are whole tokens; instants are ISO 8601, UTC.
 *
 * How the ledger is read:
 * - A run counts in the window it started in (`at - wallMs`).
 * - Where no reset is read, a window opens at the first run to start once
 *   the last one closed, and lasts its length (5 h, 7 d) — the way Claude
 *   meters a session. The chain starts two window-lengths back, or at the
 *   last read reset if that is later; nothing started means no window is
 *   open, and nothing is used.
 * - A weekly reset once read repeats every 7 days, so a past one projects
 *   to the next (`inferred`, being a projection).
 * - The cap is what the ledger shows spent in the window when the provider
 *   last said it was full. A person's own use of the account is not in the
 *   ledger, so the cap is a floor; no refusal yet means no cap (null), and
 *   then no remaining either.
 *
 * - The ledger is read five weeks back at most; a refusal older than that
 *   no longer sets a cap.
 *
 * Pure data: no authz, no events.
 */
import type { Database } from "bun:sqlite";
/** The usage windows a Claude subscription is metered over. */
export type LimitWindow = "5h" | "week";
export const WINDOWS: readonly LimitWindow[] = ["5h", "week"];
/** Each window's length, in milliseconds. */
export const WINDOW_MS: Readonly<Record<LimitWindow, number>> = {
  "5h": 5 * 3_600_000,
  week: 7 * 86_400_000,
};
/** The most of a window an operator may keep for people, in percent. */
export const HEADROOM_MAX = 90;
export type Source = "read" | "inferred";
/** A number or instant, and whether the provider said it or the ledger did. */
export interface Figure<T> {
  readonly value: T;
  readonly source: Source;
}
export interface WindowStanding {
  readonly window: LimitWindow;
  /** The open window; null when nothing has started one. */
  readonly startsAt: Figure<string> | null;
  readonly resetsAt: Figure<string> | null;
  /** US dollars the window holds; null until the provider has refused once. */
  readonly cap: Figure<number> | null;
  /** US dollars spent in the window by the crew. */
  readonly used: Figure<number>;
  readonly remaining: Figure<number> | null;
  /** US dollars of the window kept for people: cap × headroom share. */
  readonly kept: Figure<number> | null;
  /** What the crew may still spend: remaining − kept, never below 0. */
  readonly crewRemaining: Figure<number> | null;
  /** Ledger lines counted in `used`, and their tokens. */
  readonly runs: number;
  readonly tokensIn: number;
  readonly tokensOut: number;
  /** The provider's words when it last refused in this window kind. */
  readonly said: string | null;
}
export interface Standing {
  readonly subscriptionId: string;
  /** The share of each window the crew never spends, in whole percent. */
  readonly headroomPct: number;
  readonly windows: readonly WindowStanding[];
}
export interface Limit {
  readonly window: LimitWindow;
  readonly resetsAt: string;
  readonly observedAt: string;
  readonly said: string;
}
/**
 * The provider said `window` is full until `resetsAt`. The newest word for
 * a window replaces the last; an unknown subscription is ignored.
 */
export function noteLimit(
  db: Database,
  subscriptionId: string,
  limit: Limit,
): void {
  db.query(
    `INSERT INTO subscription_limit (subscription_id, span, resets_at, observed_at, said)
     SELECT ?1, ?2, ?3, ?4, ?5 WHERE EXISTS (SELECT 1 FROM subscription WHERE id = ?1)
     ON CONFLICT (subscription_id, span) DO UPDATE SET
       resets_at = excluded.resets_at, observed_at = excluded.observed_at,
       said = excluded.said`,
  ).run(
    subscriptionId,
    limit.window,
    limit.resetsAt,
    limit.observedAt,
    limit.said.slice(0, 160),
  );
}
function limitsOf(
  db: Database,
  subscriptionId: string,
): Map<LimitWindow, Limit> {
  const rows = db
    .query<
      { span: LimitWindow; resets_at: string; observed_at: string; said: string },
      [string]
    >(
      `SELECT span, resets_at, observed_at, said FROM subscription_limit
       WHERE subscription_id = ?1`,
    )
    .all(subscriptionId);
  return new Map(
    rows.map((r) => [
      r.span,
      {
        window: r.span,
        resetsAt: r.resets_at,
        observedAt: r.observed_at,
        said: r.said,
      },
    ]),
  );
}
/** A whole percent 0–90 from text; undefined for anything else. */
export function headroomPct(text: string): number | undefined {
  if (!/^\d{1,2}$/.test(text.trim())) return undefined;
  const n = Number(text.trim());
  return n <= HEADROOM_MAX ? n : undefined;
}
/** The operator's share of each window kept for people; false if no such account. */
export function setHeadroom(
  db: Database,
  subscriptionId: string,
  pct: number,
): boolean {
  if (!Number.isInteger(pct) || pct < 0 || pct > HEADROOM_MAX) return false;
  return (
    db
      .query("UPDATE subscription SET headroom_pct = ?2 WHERE id = ?1")
      .run(subscriptionId, pct).changes > 0
  );
}
export function getHeadroom(
  db: Database,
  subscriptionId: string,
): number | undefined {
  return db
    .query<{ headroom_pct: number }, [string]>(
      "SELECT headroom_pct FROM subscription WHERE id = ?1",
    )
    .get(subscriptionId)?.headroom_pct;
}
/** One ledger line as the window arithmetic needs it. */
interface Spend {
  readonly start: number;
  readonly costUsd: number;
  readonly tokensIn: number;
  readonly tokensOut: number;
}
const money = (n: number): number => Math.round(n * 10_000) / 10_000;
const iso = (ms: number): string => new Date(ms).toISOString();
/**
 * The account's standing in each window at `now`, or undefined when there
 * is no such subscription. One ledger read covers both windows.
 */
export function standing(
  db: Database,
  subscriptionId: string,
  now: Date,
): Standing | undefined {
  const pct = getHeadroom(db, subscriptionId);
  if (pct === undefined) return undefined;
  const limits = limitsOf(db, subscriptionId);
  const t = now.getTime();
  // Two weeks back holds every window's chain; a refusal's window is read
  // too, so long as it opened within the last five weeks.
  const floor = t - 5 * WINDOW_MS.week;
  const since = Math.max(
    floor,
    Math.min(
      t - 2 * WINDOW_MS.week,
      ...[...limits.values()].map(
        (l) => Date.parse(l.resetsAt) - WINDOW_MS[l.window],
      ),
    ),
  );
  const spends: Spend[] = db
    .query<
      { at: string; wall_ms: number; cost_usd: number; tokens_in: number; tokens_out: number },
      [string, string]
    >(
      `SELECT at, wall_ms, cost_usd, tokens_in, tokens_out FROM usage
       WHERE subscription_id = ?1 AND at >= ?2`,
    )
    .all(subscriptionId, iso(since))
    .map((r) => ({
      start: Date.parse(r.at) - r.wall_ms,
      costUsd: r.cost_usd,
      tokensIn: r.tokens_in,
      tokensOut: r.tokens_out,
    }))
    .sort((a, b) => a.start - b.start);
  return {
    subscriptionId,
    headroomPct: pct,
    windows: WINDOWS.map((w) =>
      windowStanding(w, limits.get(w), spends, pct, t, since),
    ),
  };
}
function windowStanding(
  window: LimitWindow,
  limit: Limit | undefined,
  spends: readonly Spend[],
  pct: number,
  t: number,
  since: number,
): WindowStanding {
  const length = WINDOW_MS[window];
  const reset = limit === undefined ? undefined : Date.parse(limit.resetsAt);
  // Where the open window lies, and on whose word.
  let open: { start: number; end: number; source: Source } | undefined;
  if (reset !== undefined && reset > t) {
    open = { start: reset - length, end: reset, source: "read" };
  } else if (reset !== undefined && window === "week") {
    const end = reset + Math.ceil((t - reset + 1) / length) * length;
    open = { start: end - length, end, source: "inferred" };
  } else {
    let start = -Infinity;
    let end = -Infinity;
    const from = Math.max(t - 2 * length, reset ?? -Infinity);
    for (const s of spends) {
      if (s.start < from || s.start > t) continue;
      if (s.start >= end) {
        start = s.start;
        end = s.start + length;
      }
    }
    if (end > t) open = { start, end, source: "inferred" };
  }
  const sum = (from: number, to: number) => {
    let costUsd = 0;
    let tokensIn = 0;
    let tokensOut = 0;
    let runs = 0;
    for (const s of spends)
      if (s.start >= from && s.start <= to) {
        costUsd += s.costUsd;
        tokensIn += s.tokensIn;
        tokensOut += s.tokensOut;
        runs++;
      }
    return { costUsd: money(costUsd), tokensIn, tokensOut, runs };
  };
  const spent =
    open === undefined
      ? { costUsd: 0, tokensIn: 0, tokensOut: 0, runs: 0 }
      : sum(open.start, Math.min(t, open.end - 1));
  // The cap: what the crew had spent in the window the provider last
  // called full, up to the moment it said so. A refusal older than the
  // ledger read is stale, and gives none.
  const capUsd =
    limit === undefined || reset === undefined || reset - length < since
      ? 0
      : sum(reset - length, Date.parse(limit.observedAt)).costUsd;
  const cap: Figure<number> | null =
    capUsd > 0 ? { value: capUsd, source: "inferred" } : null;
  const full = open?.source === "read";
  const remaining: Figure<number> | null = full
    ? { value: 0, source: "read" }
    : cap === null
      ? null
      : { value: money(Math.max(0, cap.value - spent.costUsd)), source: "inferred" };
  const kept: Figure<number> | null =
    cap === null ? null : { value: money((cap.value * pct) / 100), source: "inferred" };
  const crewRemaining: Figure<number> | null =
    remaining === null
      ? null
      : remaining.source === "read"
        ? remaining
        : {
            value: money(Math.max(0, remaining.value - (kept?.value ?? 0))),
            source: "inferred",
          };
  return {
    window,
    startsAt:
      open === undefined ? null : { value: iso(open.start), source: open.source },
    resetsAt:
      open === undefined ? null : { value: iso(open.end), source: open.source },
    cap,
    used: { value: spent.costUsd, source: "inferred" },
    remaining,
    kept,
    crewRemaining,
    runs: spent.runs,
    tokensIn: spent.tokensIn,
    tokensOut: spent.tokensOut,
    said: limit?.said ?? null,
  };
}
@@ -5,6 +5,7 @@
 * it will listen; the person who asked never has to press anything.
 */
import type { LimitWindow } from "../core/standing.ts";
import type { ClaudeOutcome } from "./claude.ts";
/** How many times one task may be paused before the forge gives up on it. */
@@ -53,11 +54,35 @@
const MONTHS = [
 * Anything else waits the default.
 */
export function resumeAt(message: string, now: Date): Date {
  const match =
    /resets?\s+(?:at\s+)?(?:([a-z]{3,9})\.?\s+(\d{1,2}),?\s+(?:at\s+)?)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*\(([^)]+)\)/i.exec(
      message,
    );
  if (match === null) return new Date(now.getTime() + DEFAULT_WAIT_MS);
  const at = resetOf(message, now);
  if (at === undefined) return new Date(now.getTime() + DEFAULT_WAIT_MS);
  return new Date(at.getTime() + SLACK_MS);
}
/**
 * Which window the provider said is full, and the instant it resets — read
 * from its own words, or undefined when it named no time. The week is named
 * (`weekly limit`) or dated (`resets Sep 26 at 9pm`); a bare clock time is
 * the 5-hour session window. No slack is added: this is the provider's time.
 */
export function limitOf(
  message: string,
  now: Date,
): { window: LimitWindow; resetsAt: Date } | undefined {
  const match = RESET.exec(message);
  const resetsAt = resetOf(message, now);
  if (match === null || resetsAt === undefined) return undefined;
  const weekly = match[1] !== undefined || /\bweek(?:ly)?\b/i.test(message);
  return { window: weekly ? "week" : "5h", resetsAt };
}
const RESET =
  /resets?\s+(?:at\s+)?(?:([a-z]{3,9})\.?\s+(\d{1,2}),?\s+(?:at\s+)?)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*\(([^)]+)\)/i;
/** The reset instant a message names, exactly; undefined when it names none. */
function resetOf(message: string, now: Date): Date | undefined {
  const match = RESET.exec(message);
  if (match === null) return undefined;
  const [, monthName, day, h, m, meridiem, zone] = match;
  const hour = (Number(h) % 12) + (meridiem!.toLowerCase() === "pm" ? 12 : 0);
  const minute = Number(m ?? "0");
@@ -69,9 +94,7 @@
export function resumeAt(message: string, now: Date): Date {
    monthName !== undefined && month >= 0
      ? { month: month + 1, day: Number(day) }
      : undefined;
  const at = nextWallTime(now, hour, minute, zone!, date);
  if (at === undefined) return new Date(now.getTime() + DEFAULT_WAIT_MS);
  return new Date(at.getTime() + SLACK_MS);
  return nextWallTime(now, hour, minute, zone!, date);
}
/** `12:04 UTC` — how a resume time reads on a card. */
@@ -67,7 +67,14 @@
import {
} from "./brief.ts";
import { policyBrief } from "../contract/audit.ts";
import { BUDGET_REACHED, runClaude, type ClaudeOutcome } from "./claude.ts";
import { isRateLimited, MAX_PAUSES, resumeAt, whenText } from "./limits.ts";
import {
  isRateLimited,
  limitOf,
  MAX_PAUSES,
  resumeAt,
  whenText,
} from "./limits.ts";
import { noteLimit } from "../core/standing.ts";
import {
  pickSubscription,
  restSubscription,
@@ -755,7 +762,18 @@
async function work(
      // The account rests until the provider's time; another on the same
      // grant, if one is awake, takes the run straight away.
      if (picked.kind === "ready") {
        const until = resumeAt(result.result, new Date());
        const now = new Date();
        const until = resumeAt(result.result, now);
        // Which window is full and when it resets, in the provider's own
        // words, for the account's standing (`core/standing.ts`).
        const limit = limitOf(result.result, now);
        if (limit !== undefined)
          noteLimit(app.db, picked.subscription.id, {
            window: limit.window,
            resetsAt: limit.resetsAt.toISOString(),
            observedAt: now.toISOString(),
            said,
          });
        restSubscription(
          app.db,
          picked.subscription.id,
@@ -513,7 +513,7 @@
const TOOLS: readonly Tool[] = [
  {
    name: "usage",
    description:
      "What the crew's runs on an app spent over the last days (1–90, default 7): tokens in and out, cost in US dollars, wall time and outcome, by subscription, agent and issue, with the newest runs. The same data as /api/v1/repos/:owner/:name/usage; refused unless you can write the app.",
      "What the crew's runs on an app spent over the last days (1–90, default 7): tokens in and out, cost in US dollars, wall time and outcome, by subscription, agent and issue, with the newest runs, and each account's standing in its 5-hour and weekly windows (cap, used, remaining, resets at — each figure read from the provider or inferred from the ledger). The same data as /api/v1/repos/:owner/:name/usage; refused unless you can write the app.",
    inputSchema: {
      type: "object",
      properties: {
@@ -65,6 +65,7 @@
import {
  subscriptionAdd,
  subscriptionDelete,
  subscriptionsPage,
  subscriptionHeadroom,
  subscriptionWake,
} from "../web/pages/subscriptions.ts";
import {
@@ -494,6 +495,11 @@
export function buildRouter(): Router<Handler> {
  router.add("POST", "/settings/subscriptions", subscriptionAdd);
  router.add("POST", "/settings/subscriptions/:id/delete", subscriptionDelete);
  router.add("POST", "/settings/subscriptions/:id/wake", subscriptionWake);
  router.add(
    "POST",
    "/settings/subscriptions/:id/headroom",
    subscriptionHeadroom,
  );
  router.add("GET", "/settings/secrets", secretsPage);
  router.add("POST", "/settings/secrets", secretSet);
  router.add("POST", "/settings/secrets/delete", secretDelete);
@@ -18,6 +18,14 @@
import {
  wakeSubscription,
  type Subscription,
} from "../../core/subscriptions.ts";
import {
  HEADROOM_MAX,
  headroomPct,
  setHeadroom,
  standing,
  type Figure,
  type WindowStanding,
} from "../../core/standing.ts";
import { getUserById } from "../../core/users.ts";
import type { Ctx } from "../../http/context.ts";
import { notFoundPage, settingsLayout, signInFirst } from "../chrome.ts";
@@ -51,6 +59,23 @@
function requireAdmin(ctx: Ctx): Response | undefined {
const kindText = (s: Subscription): string =>
  s.kind === "oauth" ? "Claude subscription" : "API key";
const usd = (n: number): string => `$${n.toFixed(2)}`;
const mark = (f: Figure<unknown>): string => (f.source === "read" ? "" : "~");
/** `5-hour: ~$3.20 used of ~$10.00 · resets 12:04 UTC` — one window, plainly. */
function windowText(w: WindowStanding): string {
  const name = w.window === "5h" ? "5-hour" : "weekly";
  const used = `${mark(w.used)}${usd(w.used.value)} used`;
  const of = w.cap === null ? "" : ` of ${mark(w.cap)}${usd(w.cap.value)}`;
  const full =
    w.remaining?.source === "read" && w.remaining.value === 0 ? " · full" : "";
  const resets =
    w.resetsAt === null
      ? " · opens on next use"
      : ` · resets ${w.resetsAt.source === "read" ? "" : "~"}${whenText(new Date(w.resetsAt.value))}`;
  return `${name}: ${used}${of}${full}${resets}`;
}
const resting = (s: Subscription, now: Date): boolean =>
  s.restingUntil !== null && s.restingUntil > now.toISOString();
@@ -85,6 +110,7 @@
export function subscriptionsPage(ctx: Ctx): Response {
      : listCard(
          pool.map((s) => {
            const rests = resting(s, now);
            const st = standing(ctx.app.db, s.id, now);
            const by =
              s.createdBy === null
                ? undefined
@@ -108,8 +134,36 @@
export function subscriptionsPage(ctx: Ctx): Response {
                : html`last used ${timeAgo(s.lastUsedAt)}`}${when(
                rests && s.restingSaid !== "",
                () => html` · ${s.restingSaid}`,
              )}${when(
                st !== undefined,
                () =>
                  html`<br />${st!.windows.map(windowText).join(" · ")}`,
              )}`,
              trail: html`${when(
                st !== undefined,
                () =>
                  html`<form
                    class="headroom row-actions"
                    method="post"
                    action="${POOL}/${s.id}/headroom"
                  >
                    <label for="h-${s.id}" class="small muted"
                      >kept for people, %</label
                    >
                    <input
                      class="input"
                      id="h-${s.id}"
                      name="headroom"
                      type="number"
                      min="0"
                      max="${HEADROOM_MAX}"
                      step="1"
                      value="${st!.headroomPct}"
                    />
                    ${btn("Keep", { size: "sm" })}
                  </form>`,
              )}
              ${when(
                rests,
                () =>
                  html`<form
@@ -202,6 +256,16 @@
export function subscriptionsPage(ctx: Ctx): Response {
  return shell(
    ctx,
    html`${list}
      ${when(
        pool.length > 0,
        () =>
          html`<p class="muted small mt">
            Windows in US dollars of list price. A figure marked ~ is inferred
            from what the crew's runs spent; the rest the provider said. The
            cap is learned the first time the provider calls a window full,
            and the share kept for people is never spent by the crew.
          </p>`,
      )}
      <div class="mt">${add}</div>
      ${used === null ? null : html`<div class="mt">${used}</div>`}`,
  );
@@ -265,6 +329,30 @@
export async function subscriptionWake(ctx: Ctx): Promise<Response> {
  return flashTo(ctx, POOL, { message: "In use again." });
}
// POST /settings/subscriptions/:id/headroom
export async function subscriptionHeadroom(ctx: Ctx): Promise<Response> {
  const denied = requireAdmin(ctx);
  if (denied) return denied;
  const form = await readForm(ctx, "admin");
  if (form instanceof Response) return form;
  const pct = headroomPct(field(form, "headroom"));
  if (pct === undefined)
    return flashTo(ctx, POOL, {
      tone: "danger",
      message: `Headroom is a whole percent from 0 to ${HEADROOM_MAX}.`,
    });
  const saved = setHeadroom(ctx.app.db, ctx.params.id ?? "", pct);
  return flashTo(
    ctx,
    POOL,
    saved
      ? {
          message: `The crew now leaves ${pct}% of each window for people.`,
        }
      : { tone: "danger", message: "No such subscription." },
  );
}
// ---- grants, on a repository's Crew settings and an organization's page ----
/**
@@ -294,6 +294,9 @@
a.origin-chip:hover { border-color: var(--border-strong); color: var(--fg); }
.grants th[scope="row"] { text-align: left; font-weight: 500; white-space: nowrap; }
.grants input[type="checkbox"] { width: 16px; height: 16px; accent-color: var(--accent); }
.grants-foot { display: flex; align-items: center; gap: 12px; padding: 10px 12px; border-top: 1px solid var(--border); }
/* A subscription's headroom for people: a small number beside its windows. */
.headroom { display: flex; align-items: center; gap: 6px; }
.headroom .input { width: 5em; }
.backups-now { margin-top: 12px; }
.backups-error { display: flex; align-items: center; gap: 8px; color: var(--danger); }
.backups-restore { margin: 8px 0 0; padding: 8px 10px; font-size: 12px; white-space: pre-wrap; word-break: break-all; background: var(--muted); border-radius: var(--radius); }
@@ -0,0 +1,251 @@
/**
 * A subscription's standing in its 5-hour and weekly windows, against
 * windows worked by hand: which runs fall in, what they spent, when the
 * window opened and resets, and which of those the provider said.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createRepo } from "../src/actions/repos.ts";
import { createApp, type App } from "../src/app.ts";
import type { Repo } from "../src/core/repos.ts";
import { createRun } from "../src/core/runs.ts";
import {
  getHeadroom,
  headroomPct,
  noteLimit,
  setHeadroom,
  standing,
  type WindowStanding,
} from "../src/core/standing.ts";
import { addSubscription, deleteSubscription } from "../src/core/subscriptions.ts";
import { recordUsage } from "../src/core/usage.ts";
import { createUser } from "../src/core/users.ts";
import { limitOf, resumeAt } from "../src/crew/limits.ts";
describe("which window the provider says is full", () => {
  test("a bare clock time is the 5-hour window, at that time exactly", () => {
    const now = new Date("2026-10-02T05:00:00Z");
    const said = "You've hit your session limit · resets 7:20am (UTC)";
    expect(limitOf(said, now)).toEqual({
      window: "5h",
      resetsAt: new Date("2026-10-02T07:20:00Z"),
    });
    // The pause still waits a minute past it.
    expect(resumeAt(said, now).toISOString()).toBe("2026-10-02T07:21:00.000Z");
  });
  test("a dated reset, or one named weekly, is the week's", () => {
    // 9pm in Chicago in September is daylight time, UTC−5: 02:00Z next day.
    expect(
      limitOf(
        "You've hit your weekly limit · resets Sep 26 at 9pm (America/Chicago)",
        new Date("2026-09-24T00:00:00Z"),
      ),
    ).toEqual({ window: "week", resetsAt: new Date("2026-09-27T02:00:00Z") });
    expect(
      limitOf("Weekly limit reached · resets 3am (UTC)", new Date("2026-10-02T05:00:00Z")),
    ).toEqual({ window: "week", resetsAt: new Date("2026-10-03T03:00:00Z") });
  });
  test("no time named is nothing read", () => {
    expect(limitOf("rate limit exceeded", new Date())).toBeUndefined();
    expect(limitOf("resets 7:20am (Not/AZone)", new Date())).toBeUndefined();
  });
});
describe("the headroom an operator keeps", () => {
  test("is a whole percent 0–90", () => {
    expect(headroomPct("0")).toBe(0);
    expect(headroomPct("20")).toBe(20);
    expect(headroomPct(" 90 ")).toBe(90);
    for (const bad of ["91", "-1", "12.5", "", "1e1", "100", "abc"])
      expect(headroomPct(bad)).toBeUndefined();
  });
});
describe("a subscription's standing", () => {
  let dataDir: string;
  let app: App;
  let repo: Repo;
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-standing-"));
    app = createApp({ dataDir, port: 0 });
    const a = await createUser(app.db, {
      username: "alice",
      email: "[email protected]",
      password: "a-good-passphrase",
      adminIfFirst: true,
    });
    if (!a.ok) throw new Error(a.error);
    const made = await createRepo(app, a.value, { name: "one", visibility: "private" });
    if (!made.ok) throw new Error("repo");
    repo = made.value;
  });
  afterAll(async () => {
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  let n = 0;
  const account = (): string => {
    const added = addSubscription(app.db, dataDir, {
      name: `account ${++n}`,
      token: `sk-ant-oat01-standing-test-${n}`,
    });
    if (!added.ok) throw new Error(added.error);
    return added.value.id;
  };
  /** A run on `sub` that started at `start`, ran `minutes`, spent `usd`. */
  const spend = (sub: string, start: string, minutes: number, usd: number): void => {
    const wallMs = minutes * 60_000;
    recordUsage(app.db, {
      runId: createRun(app.db, { repoId: repo.id, kind: "agent" }).id,
      repoId: repo.id,
      issueId: null,
      agentId: null,
      subscriptionId: sub,
      tokensIn: 1000,
      tokensOut: 100,
      costUsd: usd,
      wallMs,
      outcome: "ok",
      at: new Date(Date.parse(start) + wallMs).toISOString(),
    });
  };
  const win = (sub: string, now: string, w: "5h" | "week"): WindowStanding =>
    standing(app.db, sub, new Date(now))!.windows.find((x) => x.window === w)!;
  test("with nothing said, each window opens at the first run after the last closed", () => {
    const sub = account();
    spend(sub, "2026-10-02T03:00:00Z", 10, 4); // opens 03:00–08:00
    spend(sub, "2026-10-02T08:00:00Z", 30, 1.25); // at 08:00 that one has closed: opens 08:00–13:00
    spend(sub, "2026-10-02T10:00:00Z", 10, 0.5); // inside 08:00–13:00
    const now = "2026-10-02T12:00:00Z";
    // 5 h: 08:00–13:00 holds 1.25 + 0.5 = 1.75. No refusal yet, so no cap.
    const session = win(sub, now, "5h");
    expect(session.startsAt).toEqual({ value: "2026-10-02T08:00:00.000Z", source: "inferred" });
    expect(session.resetsAt).toEqual({ value: "2026-10-02T13:00:00.000Z", source: "inferred" });
    expect(session.used).toEqual({ value: 1.75, source: "inferred" });
    expect(session.runs).toBe(2);
    expect(session.tokensIn).toBe(2000);
    expect(session.cap).toBeNull();
    expect(session.remaining).toBeNull();
    expect(session.crewRemaining).toBeNull();
    // The week opened with the 03:00 run and holds all three: 5.75.
    const week = win(sub, now, "week");
    expect(week.startsAt).toEqual({ value: "2026-10-02T03:00:00.000Z", source: "inferred" });
    expect(week.resetsAt).toEqual({ value: "2026-10-09T03:00:00.000Z", source: "inferred" });
    expect(week.used.value).toBe(5.75);
    // At 13:00 the 5-hour window has closed and nothing has opened another.
    const later = win(sub, "2026-10-02T13:00:00Z", "5h");
    expect(later.startsAt).toBeNull();
    expect(later.resetsAt).toBeNull();
    expect(later.used).toEqual({ value: 0, source: "inferred" });
  });
  test("the provider's refusal is read: full until its reset, and the ledger then gives the cap", () => {
    const sub = account();
    expect(setHeadroom(app.db, sub, 20)).toBe(true);
    spend(sub, "2026-10-02T08:00:00Z", 30, 2); // before the window the provider names
    spend(sub, "2026-10-02T09:30:00Z", 30, 3);
    spend(sub, "2026-10-02T10:30:00Z", 20, 2); // the run that was refused at 11:00
    noteLimit(app.db, sub, {
      window: "5h",
      resetsAt: "2026-10-02T14:00:00.000Z",
      observedAt: "2026-10-02T11:00:00.000Z",
      said: "You've hit your session limit · resets 2pm (UTC)",
    });
    // At 12:00: the window is 09:00–14:00 on the provider's word. In it
    // the crew had spent 3 + 2 = 5 when it was refused: the cap. Remaining
    // is 0, read; 20% of 5 = 1 is kept for people.
    const full = win(sub, "2026-10-02T12:00:00Z", "5h");
    expect(full.startsAt).toEqual({ value: "2026-10-02T09:00:00.000Z", source: "read" });
    expect(full.resetsAt).toEqual({ value: "2026-10-02T14:00:00.000Z", source: "read" });
    expect(full.used).toEqual({ value: 5, source: "inferred" });
    expect(full.cap).toEqual({ value: 5, source: "inferred" });
    expect(full.remaining).toEqual({ value: 0, source: "read" });
    expect(full.kept).toEqual({ value: 1, source: "inferred" });
    expect(full.crewRemaining).toEqual({ value: 0, source: "read" });
    expect(full.said).toContain("session limit");
    // At 15:00 the reset has passed and nothing has run since: no window
    // open, the cap still known, everything but the 20% the crew's.
    const after = win(sub, "2026-10-02T15:00:00Z", "5h");
    expect(after.startsAt).toBeNull();
    expect(after.cap).toEqual({ value: 5, source: "inferred" });
    expect(after.remaining).toEqual({ value: 5, source: "inferred" });
    expect(after.crewRemaining).toEqual({ value: 4, source: "inferred" });
    // A run at 14:30 for $1.20 opens the next window, 14:30–19:30:
    // remaining 5 − 1.2 = 3.8, the crew's 3.8 − 1 = 2.8.
    spend(sub, "2026-10-02T14:30:00Z", 10, 1.2);
    const next = win(sub, "2026-10-02T15:00:00Z", "5h");
    expect(next.startsAt).toEqual({ value: "2026-10-02T14:30:00.000Z", source: "inferred" });
    expect(next.resetsAt).toEqual({ value: "2026-10-02T19:30:00.000Z", source: "inferred" });
    expect(next.used.value).toBe(1.2);
    expect(next.remaining).toEqual({ value: 3.8, source: "inferred" });
    expect(next.crewRemaining).toEqual({ value: 2.8, source: "inferred" });
  });
  test("a weekly reset once read repeats every seven days", () => {
    const sub = account();
    spend(sub, "2026-09-25T10:00:00Z", 60, 30); // in the week the provider closed
    spend(sub, "2026-09-29T10:00:00Z", 60, 6); // in the week after
    spend(sub, "2026-10-02T09:00:00Z", 60, 4.5);
    noteLimit(app.db, sub, {
      window: "week",
      resetsAt: "2026-09-28T02:00:00.000Z",
      observedAt: "2026-09-27T20:00:00.000Z",
      said: "You've hit your weekly limit · resets Sep 27 at 9pm (America/Chicago)",
    });
    // Sep 28 02:00 + 7 d = Oct 5 02:00, the first reset after Oct 2 12:00.
    // Used since Sep 28 02:00: 6 + 4.5. The cap is the week to Sep 27 20:00: 30.
    const week = win(sub, "2026-10-02T12:00:00Z", "week");
    expect(week.startsAt).toEqual({ value: "2026-09-28T02:00:00.000Z", source: "inferred" });
    expect(week.resetsAt).toEqual({ value: "2026-10-05T02:00:00.000Z", source: "inferred" });
    expect(week.used.value).toBe(10.5);
    expect(week.cap).toEqual({ value: 30, source: "inferred" });
    expect(week.remaining).toEqual({ value: 19.5, source: "inferred" });
    // Exactly at a projected reset, the next week begins.
    const edge = win(sub, "2026-10-05T02:00:00Z", "week");
    expect(edge.startsAt!.value).toBe("2026-10-05T02:00:00.000Z");
    expect(edge.used.value).toBe(0);
  });
  test("the newest word for a window replaces the last; a removed account has none", () => {
    const sub = account();
    const said = (resetsAt: string) =>
      noteLimit(app.db, sub, {
        window: "5h",
        resetsAt,
        observedAt: "2026-10-02T11:00:00.000Z",
        said: "x".repeat(500),
      });
    said("2026-10-02T13:00:00.000Z");
    said("2026-10-02T14:00:00.000Z");
    const w = win(sub, "2026-10-02T12:00:00Z", "5h");
    expect(w.resetsAt!.value).toBe("2026-10-02T14:00:00.000Z");
    expect(w.said!.length).toBe(160);
    expect(setHeadroom(app.db, sub, 91)).toBe(false);
    expect(setHeadroom(app.db, sub, -1)).toBe(false);
    expect(getHeadroom(app.db, sub)).toBe(0);
    expect(deleteSubscription(app.db, sub)).toBe(true);
    expect(standing(app.db, sub, new Date())).toBeUndefined();
    expect(setHeadroom(app.db, sub, 10)).toBe(false);
    // A note for an account that is not there is dropped, not kept.
    said("2026-10-02T15:00:00.000Z");
    expect(
      app.db
        .query<{ n: number }, [string]>(
          "SELECT COUNT(*) AS n FROM subscription_limit WHERE subscription_id = ?1",
        )
        .get(sub)!.n,
    ).toBe(0);
  });
});
@@ -1,3 +1,4 @@
import { getHeadroom } from "../src/core/standing.ts";
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
import { mkdtemp, rm } from "node:fs/promises";
@@ -505,6 +506,36 @@
describe("the pages", () => {
    expect(html).toContain("@acme");
  });
  test("an admin keeps a share of each window for people, and sees each window", async () => {
    const work = listSubscriptions(app.db)[0]!;
    let html = await get("/settings/subscriptions");
    expect(html).toContain(`action="/settings/subscriptions/${work.id}/headroom"`);
    expect(html).toContain("5-hour: ~$0.00 used · opens on next use");
    const kept = await post(`/settings/subscriptions/${work.id}/headroom`, {
      headroom: "25",
    });
    expect(kept.status).toBe(303);
    expect(getHeadroom(app.db, work.id)).toBe(25);
    for (const bad of ["91", "-5", "ten", ""]) {
      const refused = await post(`/settings/subscriptions/${work.id}/headroom`, {
        headroom: bad,
      });
      expect(refused.status).toBe(303);
    }
    expect(getHeadroom(app.db, work.id)).toBe(25);
    html = await get("/settings/subscriptions");
    expect(html).toContain('value="25"');
    // Without the page's own origin, nothing changes.
    const forged = await fetch(`${base}/settings/subscriptions/${work.id}/headroom`, {
      method: "POST",
      headers: { cookie, origin: "https://elsewhere.example" },
      body: new URLSearchParams({ headroom: "0" }),
      redirect: "manual",
    });
    expect(forged.status).toBe(403);
    expect(getHeadroom(app.db, work.id)).toBe(25);
  });
  test("nobody but an admin reaches the pool", async () => {
    const signed = await fetch(`${base}/signup`, {
      method: "POST",
@@ -528,5 +559,14 @@
describe("the pages", () => {
    });
    expect(posted.status).toBe(404);
    expect(listSubscriptions(app.db)).toHaveLength(1);
    const work = listSubscriptions(app.db)[0]!;
    const headroom = await fetch(`${base}/settings/subscriptions/${work.id}/headroom`, {
      method: "POST",
      headers: { cookie: guest, origin: base },
      body: new URLSearchParams({ headroom: "0" }),
      redirect: "manual",
    });
    expect(headroom.status).toBe(404);
    expect(getHeadroom(app.db, work.id)).toBe(25);
  });
});
@@ -428,6 +428,25 @@
echo '{"type":"result","subtype":"success","is_error":false,"result":"Added CREW
    expect(body.recent[0].subscription).toBe("work");
    expect(JSON.stringify(body)).not.toContain(KEY);
    // Each account's standing rides along. The personal plan's week is full
    // on the provider's word, until the reset it named; the work key's
    // windows are inferred from the one run it paid for.
    expect(body.standing.map((s: any) => s.subscription)).toEqual([
      "personal",
      "work",
    ]);
    const [mine, theirs] = body.standing;
    const week = mine.windows.find((w: any) => w.window === "week");
    expect(week.resetsAt.source).toBe("read");
    expect(week.resetsAt.value.slice(5, 16)).toBe("09-26T21:00");
    expect(week.remaining).toEqual({ value: 0, source: "read" });
    expect(week.said).toContain("weekly limit");
    const session = theirs.windows.find((w: any) => w.window === "5h");
    expect(session.used).toEqual({ value: 0.0375, source: "inferred" });
    expect(session.startsAt.source).toBe("inferred");
    expect(session.cap).toBeNull();
    expect(session.tokensIn).toBe(32_120);
    // A window that is not 1–90 days is refused, not guessed at.
    const bad = await fetch(`${url}?days=365`, {
      headers: { authorization: `Bearer ${owner}` },
@@ -465,6 +484,10 @@
echo '{"type":"result","subtype":"success","is_error":false,"result":"Added CREW
    const told = await mcp(owner, { repo: "alice/garden", days: 7 });
    const value = JSON.parse(told.result.content[0].text);
    expect(value.total).toEqual(body.total);
    expect(value.standing.map((s: any) => s.subscription)).toEqual([
      "personal",
      "work",
    ]);
    const no = await mcp(reader, { repo: "alice/garden" });
    expect(no.result.isError).toBe(true);
    expect(no.result.content[0].text).toContain("forbidden");
		@@ -685,6 +685,18 @@ it named none). The run that starts then resumes the same session in that
685	685	clone and is told to carry on. A task is paused at most six times before
686	686	the forge stops waiting on it.
687	687
	688	Each subscription keeps a _standing_ (`core/standing.ts`): where it is in
	689	its 5-hour and weekly windows — started, resets, cap, used, remaining, in
	690	US dollars of list price. When the provider turns a run away, the window
	691	it named and its reset are kept as _read_; everything else is _inferred_
	692	from the usage ledger — a window opens at the first run after the last one
	693	closed, and the cap is what the crew had spent when the provider last
	694	called the window full (a person's own use is not in the ledger, so it is
	695	a floor). An operator keeps a share of every window for people
	696	(Settings → Subscriptions, 0–90%); `crewRemaining` is what is left after
	697	it. Both read on `GET /api/v1/repos/:owner/:name/usage` and the MCP
	698	`usage` tool, under `standing`.
	699
688	700	The agent runs Claude Code headless in its clone, with a prompt the forge
689	701	composes: who it is, what the task is, how to finish, and what will be
690	702	refused. Permissions are the forge's, passed as settings: file tools
		@@ -38,7 +38,7 @@ for a tunnel and a forge that sleeps.
38	38	\| `take_updates` \| a fork takes its parent's updates when git can do it alone; a conflict is refused \| yes \|
39	39	\| `converge` \| the fork's crew merges where both sides changed the same files; comes back as a pull \| yes \|
40	40	\| `map` \| an app's plan: ready now, waiting on what, the critical path, where the crew is (`app`) \| \|
41		\| `usage` \| `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue; a writer's \| \|
	41	\| `usage` \| `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's \| \|
42	42	\| `link` \| `{ app, issue, blockedBy }`: the issue waits for another; loops and cross-repository are refused \| yes \|
43	43	\| `unlink` \| `{ app, issue, blockedBy }`: the issue stops waiting for it \| yes \|
44	44	\| `plan` \| `{ app, issues }`: open up to 12 linked issues, all or none (see below) \| yes \|
		@@ -6,7 +6,7 @@
6	6	"ready": 90
7	7	},
8	8	"check": {
9		"run": "bun x tsc --noEmit && bun scripts/test-shards.ts --timeout 60000 test/crew.test.ts test/crew-wrapup.test.ts test/crew-limits.test.ts test/crew-sandbox.test.ts test/steer.test.ts test/landing.test.ts test/decide.test.ts test/ledger.test.ts test/checks.test.ts test/dependencies.test.ts test/autonomy.test.ts test/studio.test.ts test/studio-words.test.ts test/forks.test.ts test/fork-flow.test.ts test/cross-repo-pull.test.ts test/pulls.test.ts test/apps.test.ts test/apps-adversarial.test.ts test/apps-busy.test.ts test/web.test.ts test/git-trust.test.ts test/helpers.test.ts test/shards.test.ts test/migrate.test.ts test/vitals.test.ts test/asks.test.ts test/feed.test.ts test/feed-page.test.ts test/offline.test.ts test/share.test.ts test/cloud.test.ts test/run-secrets.test.ts test/forge-cloudflare.test.ts test/usage.test.ts",
	9	"run": "bun x tsc --noEmit && bun scripts/test-shards.ts --timeout 60000 test/crew.test.ts test/crew-wrapup.test.ts test/crew-limits.test.ts test/crew-sandbox.test.ts test/steer.test.ts test/landing.test.ts test/decide.test.ts test/ledger.test.ts test/checks.test.ts test/dependencies.test.ts test/autonomy.test.ts test/studio.test.ts test/studio-words.test.ts test/forks.test.ts test/fork-flow.test.ts test/cross-repo-pull.test.ts test/pulls.test.ts test/apps.test.ts test/apps-adversarial.test.ts test/apps-busy.test.ts test/web.test.ts test/git-trust.test.ts test/helpers.test.ts test/shards.test.ts test/migrate.test.ts test/vitals.test.ts test/asks.test.ts test/feed.test.ts test/feed-page.test.ts test/offline.test.ts test/share.test.ts test/cloud.test.ts test/run-secrets.test.ts test/forge-cloudflare.test.ts test/usage.test.ts test/standing.test.ts",
10	10	"timeout": 1800
11	11	}
12	12	}
		@@ -5,12 +5,17 @@
5	5	* the predicate the run pages use for cost), so a reader who cannot write
6	6	* the repository is refused. The API route and the MCP `usage` tool both
7	7	* answer from here, so they never disagree.
	8	*
	9	* With it, each account's standing (`core/standing.ts`): where it is in its
	10	* 5-hour and weekly windows, account-wide. The accounts shown are those
	11	* granted here or on the owner, and those that paid for a run here.
8	12	*/
9	13
10	14	import type { App } from "../app.ts";
11	15	import { getIssuesByIds } from "../core/issues.ts";
12	16	import { canSeeOwnerFacts, type Repo } from "../core/repos.ts";
13		import { listSubscriptions } from "../core/subscriptions.ts";
	17	import { standing, type Standing } from "../core/standing.ts";
	18	import { listGrants, listSubscriptions } from "../core/subscriptions.ts";
14	19	import {
15	20	recentUsage,
16	21	usageTotals,
		@@ -56,6 +61,10 @@ export interface UsageReport {
56	61	readonly agent: string \| null;
57	62	readonly issue: number \| null;
58	63	})[];
	64	/** Each account this app spends: its windows, now, every figure read or inferred. */
	65	readonly standing: readonly (Omit<Standing, "subscriptionId"> & {
	66	readonly subscription: string;
	67	})[];
59	68	}
60	69
61	70	const ZERO: Omit<UsageTotals, "key"> = {
		@@ -121,6 +130,21 @@ export function readUsage(
121	130	ZERO,
122	131	);
123	132
	133	// Granted at the repository or its owner, any agent, or spent here.
	134	const accounts = new Set<string>();
	135	for (const g of [...listGrants(db, repo.id), ...listGrants(db, repo.ownerId)])
	136	accounts.add(g.subscriptionId);
	137	for (const row of bySubscription)
	138	if (row.key !== null && subscriptions.has(row.key)) accounts.add(row.key);
	139	const standings = [...accounts]
	140	.flatMap((id) => {
	141	const s = standing(db, id, now);
	142	if (s === undefined) return [];
	143	const { subscriptionId: _, ...rest } = s;
	144	return [{ subscription: subscriptions.get(id) ?? id, ...rest }];
	145	})
	146	.sort((a, b) => a.subscription.localeCompare(b.subscription));
	147
124	148	return ok({
125	149	app: `${repo.ownerName}/${repo.name}`,
126	150	days,
		@@ -138,5 +162,6 @@ export function readUsage(
138	162	agent: agentName(r.agentId),
139	163	issue: issueNumber(r.issueId),
140	164	})),
	165	standing: standings,
141	166	});
142	167	}
		@@ -1025,4 +1025,20 @@ export const migrations: readonly string[] = [
1025	1025	CREATE INDEX IF NOT EXISTS usage_repo ON usage(repo_id, at);
1026	1026	CREATE INDEX IF NOT EXISTS usage_subscription ON usage(subscription_id, at);
1027	1027	`,
	1028
	1029	// 38 — a subscription's standing (`core/standing.ts`): the last time the
	1030	// provider said each window (5-hour, weekly) was full and when it resets,
	1031	// and the share of every window the operator keeps for people.
	1032	`
	1033	CREATE TABLE subscription_limit (
	1034	subscription_id TEXT NOT NULL REFERENCES subscription(id) ON DELETE CASCADE,
	1035	span TEXT NOT NULL CHECK (span IN ('5h','week')),
	1036	resets_at TEXT NOT NULL,
	1037	observed_at TEXT NOT NULL,
	1038	said TEXT NOT NULL DEFAULT '',
	1039	PRIMARY KEY (subscription_id, span)
	1040	);
	1041	ALTER TABLE subscription ADD COLUMN headroom_pct INTEGER NOT NULL DEFAULT 0
	1042	CHECK (headroom_pct BETWEEN 0 AND 90);
	1043	`,
1028	1044	];
		@@ -0,0 +1,336 @@
	1	/**
	2	* Standing — where one subscription is in each of the windows its provider
	3	* meters it over: the 5-hour session window and the week. Per window: when
	4	* it started and resets, the cap, what is used, what remains, and what of
	5	* that the crew may spend once the operator's headroom for people is kept.
	6	*
	7	* Every figure says where it came from:
	8	* - `read` — the provider said it. Claude Code's refusal names the window
	9	* and its reset (`crew/limits.ts`'s `limitOf`); the runner notes it here
	10	* with `noteLimit`. While that reset is ahead, the window is full.
	11	* - `inferred` — worked out from the usage ledger (`core/usage.ts`).
	12	*
	13	* Units, stated once: money is US dollars of the provider's list-price
	14	* equivalent (`usage.cost_usd`), rounded to 1/10 000 of a dollar; tokens
	15	* are whole tokens; instants are ISO 8601, UTC.
	16	*
	17	* How the ledger is read:
	18	* - A run counts in the window it started in (`at - wallMs`).
	19	* - Where no reset is read, a window opens at the first run to start once
	20	* the last one closed, and lasts its length (5 h, 7 d) — the way Claude
	21	* meters a session. The chain starts two window-lengths back, or at the
	22	* last read reset if that is later; nothing started means no window is
	23	* open, and nothing is used.
	24	* - A weekly reset once read repeats every 7 days, so a past one projects
	25	* to the next (`inferred`, being a projection).
	26	* - The cap is what the ledger shows spent in the window when the provider
	27	* last said it was full. A person's own use of the account is not in the
	28	* ledger, so the cap is a floor; no refusal yet means no cap (null), and
	29	* then no remaining either.
	30	*
	31	* - The ledger is read five weeks back at most; a refusal older than that
	32	* no longer sets a cap.
	33	*
	34	* Pure data: no authz, no events.
	35	*/
	36
	37	import type { Database } from "bun:sqlite";
	38
	39	/** The usage windows a Claude subscription is metered over. */
	40	export type LimitWindow = "5h" \| "week";
	41
	42	export const WINDOWS: readonly LimitWindow[] = ["5h", "week"];
	43
	44	/** Each window's length, in milliseconds. */
	45	export const WINDOW_MS: Readonly<Record<LimitWindow, number>> = {
	46	"5h": 5 * 3_600_000,
	47	week: 7 * 86_400_000,
	48	};
	49
	50	/** The most of a window an operator may keep for people, in percent. */
	51	export const HEADROOM_MAX = 90;
	52
	53	export type Source = "read" \| "inferred";
	54
	55	/** A number or instant, and whether the provider said it or the ledger did. */
	56	export interface Figure<T> {
	57	readonly value: T;
	58	readonly source: Source;
	59	}
	60
	61	export interface WindowStanding {
	62	readonly window: LimitWindow;
	63	/** The open window; null when nothing has started one. */
	64	readonly startsAt: Figure<string> \| null;
	65	readonly resetsAt: Figure<string> \| null;
	66	/** US dollars the window holds; null until the provider has refused once. */
	67	readonly cap: Figure<number> \| null;
	68	/** US dollars spent in the window by the crew. */
	69	readonly used: Figure<number>;
	70	readonly remaining: Figure<number> \| null;
	71	/** US dollars of the window kept for people: cap × headroom share. */
	72	readonly kept: Figure<number> \| null;
	73	/** What the crew may still spend: remaining − kept, never below 0. */
	74	readonly crewRemaining: Figure<number> \| null;
	75	/** Ledger lines counted in `used`, and their tokens. */
	76	readonly runs: number;
	77	readonly tokensIn: number;
	78	readonly tokensOut: number;
	79	/** The provider's words when it last refused in this window kind. */
	80	readonly said: string \| null;
	81	}
	82
	83	export interface Standing {
	84	readonly subscriptionId: string;
	85	/** The share of each window the crew never spends, in whole percent. */
	86	readonly headroomPct: number;
	87	readonly windows: readonly WindowStanding[];
	88	}
	89
	90	export interface Limit {
	91	readonly window: LimitWindow;
	92	readonly resetsAt: string;
	93	readonly observedAt: string;
	94	readonly said: string;
	95	}
	96
	97	/**
	98	* The provider said `window` is full until `resetsAt`. The newest word for
	99	* a window replaces the last; an unknown subscription is ignored.
	100	*/
	101	export function noteLimit(
	102	db: Database,
	103	subscriptionId: string,
	104	limit: Limit,
	105	): void {
	106	db.query(
	107	`INSERT INTO subscription_limit (subscription_id, span, resets_at, observed_at, said)
	108	SELECT ?1, ?2, ?3, ?4, ?5 WHERE EXISTS (SELECT 1 FROM subscription WHERE id = ?1)
	109	ON CONFLICT (subscription_id, span) DO UPDATE SET
	110	resets_at = excluded.resets_at, observed_at = excluded.observed_at,
	111	said = excluded.said`,
	112	).run(
	113	subscriptionId,
	114	limit.window,
	115	limit.resetsAt,
	116	limit.observedAt,
	117	limit.said.slice(0, 160),
	118	);
	119	}
	120
	121	function limitsOf(
	122	db: Database,
	123	subscriptionId: string,
	124	): Map<LimitWindow, Limit> {
	125	const rows = db
	126	.query<
	127	{ span: LimitWindow; resets_at: string; observed_at: string; said: string },
	128	[string]
	129	>(
	130	`SELECT span, resets_at, observed_at, said FROM subscription_limit
	131	WHERE subscription_id = ?1`,
	132	)
	133	.all(subscriptionId);
	134	return new Map(
	135	rows.map((r) => [
	136	r.span,
	137	{
	138	window: r.span,
	139	resetsAt: r.resets_at,
	140	observedAt: r.observed_at,
	141	said: r.said,
	142	},
	143	]),
	144	);
	145	}
	146
	147	/** A whole percent 0–90 from text; undefined for anything else. */
	148	export function headroomPct(text: string): number \| undefined {
	149	if (!/^\d{1,2}$/.test(text.trim())) return undefined;
	150	const n = Number(text.trim());
	151	return n <= HEADROOM_MAX ? n : undefined;
	152	}
	153
	154	/** The operator's share of each window kept for people; false if no such account. */
	155	export function setHeadroom(
	156	db: Database,
	157	subscriptionId: string,
	158	pct: number,
	159	): boolean {
	160	if (!Number.isInteger(pct) \|\| pct < 0 \|\| pct > HEADROOM_MAX) return false;
	161	return (
	162	db
	163	.query("UPDATE subscription SET headroom_pct = ?2 WHERE id = ?1")
	164	.run(subscriptionId, pct).changes > 0
	165	);
	166	}
	167
	168	export function getHeadroom(
	169	db: Database,
	170	subscriptionId: string,
	171	): number \| undefined {
	172	return db
	173	.query<{ headroom_pct: number }, [string]>(
	174	"SELECT headroom_pct FROM subscription WHERE id = ?1",
	175	)
	176	.get(subscriptionId)?.headroom_pct;
	177	}
	178
	179	/** One ledger line as the window arithmetic needs it. */
	180	interface Spend {
	181	readonly start: number;
	182	readonly costUsd: number;
	183	readonly tokensIn: number;
	184	readonly tokensOut: number;
	185	}
	186
	187	const money = (n: number): number => Math.round(n * 10_000) / 10_000;
	188	const iso = (ms: number): string => new Date(ms).toISOString();
	189
	190	/**
	191	* The account's standing in each window at `now`, or undefined when there
	192	* is no such subscription. One ledger read covers both windows.
	193	*/
	194	export function standing(
	195	db: Database,
	196	subscriptionId: string,
	197	now: Date,
	198	): Standing \| undefined {
	199	const pct = getHeadroom(db, subscriptionId);
	200	if (pct === undefined) return undefined;
	201	const limits = limitsOf(db, subscriptionId);
	202	const t = now.getTime();
	203	// Two weeks back holds every window's chain; a refusal's window is read
	204	// too, so long as it opened within the last five weeks.
	205	const floor = t - 5 * WINDOW_MS.week;
	206	const since = Math.max(
	207	floor,
	208	Math.min(
	209	t - 2 * WINDOW_MS.week,
	210	...[...limits.values()].map(
	211	(l) => Date.parse(l.resetsAt) - WINDOW_MS[l.window],
	212	),
	213	),
	214	);
	215	const spends: Spend[] = db
	216	.query<
	217	{ at: string; wall_ms: number; cost_usd: number; tokens_in: number; tokens_out: number },
	218	[string, string]
	219	>(
	220	`SELECT at, wall_ms, cost_usd, tokens_in, tokens_out FROM usage
	221	WHERE subscription_id = ?1 AND at >= ?2`,
	222	)
	223	.all(subscriptionId, iso(since))
	224	.map((r) => ({
	225	start: Date.parse(r.at) - r.wall_ms,
	226	costUsd: r.cost_usd,
	227	tokensIn: r.tokens_in,
	228	tokensOut: r.tokens_out,
	229	}))
	230	.sort((a, b) => a.start - b.start);
	231	return {
	232	subscriptionId,
	233	headroomPct: pct,
	234	windows: WINDOWS.map((w) =>
	235	windowStanding(w, limits.get(w), spends, pct, t, since),
	236	),
	237	};
	238	}
	239
	240	function windowStanding(
	241	window: LimitWindow,
	242	limit: Limit \| undefined,
	243	spends: readonly Spend[],
	244	pct: number,
	245	t: number,
	246	since: number,
	247	): WindowStanding {
	248	const length = WINDOW_MS[window];
	249	const reset = limit === undefined ? undefined : Date.parse(limit.resetsAt);
	250
	251	// Where the open window lies, and on whose word.
	252	let open: { start: number; end: number; source: Source } \| undefined;
	253	if (reset !== undefined && reset > t) {
	254	open = { start: reset - length, end: reset, source: "read" };
	255	} else if (reset !== undefined && window === "week") {
	256	const end = reset + Math.ceil((t - reset + 1) / length) * length;
	257	open = { start: end - length, end, source: "inferred" };
	258	} else {
	259	let start = -Infinity;
	260	let end = -Infinity;
	261	const from = Math.max(t - 2 * length, reset ?? -Infinity);
	262	for (const s of spends) {
	263	if (s.start < from \|\| s.start > t) continue;
	264	if (s.start >= end) {
	265	start = s.start;
	266	end = s.start + length;
	267	}
	268	}
	269	if (end > t) open = { start, end, source: "inferred" };
	270	}
	271
	272	const sum = (from: number, to: number) => {
	273	let costUsd = 0;
	274	let tokensIn = 0;
	275	let tokensOut = 0;
	276	let runs = 0;
	277	for (const s of spends)
	278	if (s.start >= from && s.start <= to) {
	279	costUsd += s.costUsd;
	280	tokensIn += s.tokensIn;
	281	tokensOut += s.tokensOut;
	282	runs++;
	283	}
	284	return { costUsd: money(costUsd), tokensIn, tokensOut, runs };
	285	};
	286
	287	const spent =
	288	open === undefined
	289	? { costUsd: 0, tokensIn: 0, tokensOut: 0, runs: 0 }
	290	: sum(open.start, Math.min(t, open.end - 1));
	291
	292	// The cap: what the crew had spent in the window the provider last
	293	// called full, up to the moment it said so. A refusal older than the
	294	// ledger read is stale, and gives none.
	295	const capUsd =
	296	limit === undefined \|\| reset === undefined \|\| reset - length < since
	297	? 0
	298	: sum(reset - length, Date.parse(limit.observedAt)).costUsd;
	299	const cap: Figure<number> \| null =
	300	capUsd > 0 ? { value: capUsd, source: "inferred" } : null;
	301
	302	const full = open?.source === "read";
	303	const remaining: Figure<number> \| null = full
	304	? { value: 0, source: "read" }
	305	: cap === null
	306	? null
	307	: { value: money(Math.max(0, cap.value - spent.costUsd)), source: "inferred" };
	308	const kept: Figure<number> \| null =
	309	cap === null ? null : { value: money((cap.value * pct) / 100), source: "inferred" };
	310	const crewRemaining: Figure<number> \| null =
	311	remaining === null
	312	? null
	313	: remaining.source === "read"
	314	? remaining
	315	: {
	316	value: money(Math.max(0, remaining.value - (kept?.value ?? 0))),
	317	source: "inferred",
	318	};
	319
	320	return {
	321	window,
	322	startsAt:
	323	open === undefined ? null : { value: iso(open.start), source: open.source },
	324	resetsAt:
	325	open === undefined ? null : { value: iso(open.end), source: open.source },
	326	cap,
	327	used: { value: spent.costUsd, source: "inferred" },
	328	remaining,
	329	kept,
	330	crewRemaining,
	331	runs: spent.runs,
	332	tokensIn: spent.tokensIn,
	333	tokensOut: spent.tokensOut,
	334	said: limit?.said ?? null,
	335	};
	336	}
		@@ -5,6 +5,7 @@
5	5	* it will listen; the person who asked never has to press anything.
6	6	*/
7	7
	8	import type { LimitWindow } from "../core/standing.ts";
8	9	import type { ClaudeOutcome } from "./claude.ts";
9	10
10	11	/** How many times one task may be paused before the forge gives up on it. */
		@@ -53,11 +54,35 @@ const MONTHS = [
53	54	* Anything else waits the default.
54	55	*/
55	56	export function resumeAt(message: string, now: Date): Date {
56		const match =
57		/resets?\s+(?:at\s+)?(?:([a-z]{3,9})\.?\s+(\d{1,2}),?\s+(?:at\s+)?)?(\d{1,2})(?::(\d{2}))?\s(am\|pm)\s\(([^)]+)\)/i.exec(
58		message,
59		);
60		if (match === null) return new Date(now.getTime() + DEFAULT_WAIT_MS);
	57	const at = resetOf(message, now);
	58	if (at === undefined) return new Date(now.getTime() + DEFAULT_WAIT_MS);
	59	return new Date(at.getTime() + SLACK_MS);
	60	}
	61
	62	/**
	63	* Which window the provider said is full, and the instant it resets — read
	64	* from its own words, or undefined when it named no time. The week is named
	65	* (`weekly limit`) or dated (`resets Sep 26 at 9pm`); a bare clock time is
	66	* the 5-hour session window. No slack is added: this is the provider's time.
	67	*/
	68	export function limitOf(
	69	message: string,
	70	now: Date,
	71	): { window: LimitWindow; resetsAt: Date } \| undefined {
	72	const match = RESET.exec(message);
	73	const resetsAt = resetOf(message, now);
	74	if (match === null \|\| resetsAt === undefined) return undefined;
	75	const weekly = match[1] !== undefined \|\| /\bweek(?:ly)?\b/i.test(message);
	76	return { window: weekly ? "week" : "5h", resetsAt };
	77	}
	78
	79	const RESET =
	80	/resets?\s+(?:at\s+)?(?:([a-z]{3,9})\.?\s+(\d{1,2}),?\s+(?:at\s+)?)?(\d{1,2})(?::(\d{2}))?\s(am\|pm)\s\(([^)]+)\)/i;
	81
	82	/** The reset instant a message names, exactly; undefined when it names none. */
	83	function resetOf(message: string, now: Date): Date \| undefined {
	84	const match = RESET.exec(message);
	85	if (match === null) return undefined;
61	86	const [, monthName, day, h, m, meridiem, zone] = match;
62	87	const hour = (Number(h) % 12) + (meridiem!.toLowerCase() === "pm" ? 12 : 0);
63	88	const minute = Number(m ?? "0");
		@@ -69,9 +94,7 @@ export function resumeAt(message: string, now: Date): Date {
69	94	monthName !== undefined && month >= 0
70	95	? { month: month + 1, day: Number(day) }
71	96	: undefined;
72		const at = nextWallTime(now, hour, minute, zone!, date);
73		if (at === undefined) return new Date(now.getTime() + DEFAULT_WAIT_MS);
74		return new Date(at.getTime() + SLACK_MS);
	97	return nextWallTime(now, hour, minute, zone!, date);
75	98	}
76	99
77	100	/** `12:04 UTC` — how a resume time reads on a card. */
		@@ -67,7 +67,14 @@ import {
67	67	} from "./brief.ts";
68	68	import { policyBrief } from "../contract/audit.ts";
69	69	import { BUDGET_REACHED, runClaude, type ClaudeOutcome } from "./claude.ts";
70		import { isRateLimited, MAX_PAUSES, resumeAt, whenText } from "./limits.ts";
	70	import {
	71	isRateLimited,
	72	limitOf,
	73	MAX_PAUSES,
	74	resumeAt,
	75	whenText,
	76	} from "./limits.ts";
	77	import { noteLimit } from "../core/standing.ts";
71	78	import {
72	79	pickSubscription,
73	80	restSubscription,
		@@ -755,7 +762,18 @@ async function work(
755	762	// The account rests until the provider's time; another on the same
756	763	// grant, if one is awake, takes the run straight away.
757	764	if (picked.kind === "ready") {
758		const until = resumeAt(result.result, new Date());
	765	const now = new Date();
	766	const until = resumeAt(result.result, now);
	767	// Which window is full and when it resets, in the provider's own
	768	// words, for the account's standing (`core/standing.ts`).
	769	const limit = limitOf(result.result, now);
	770	if (limit !== undefined)
	771	noteLimit(app.db, picked.subscription.id, {
	772	window: limit.window,
	773	resetsAt: limit.resetsAt.toISOString(),
	774	observedAt: now.toISOString(),
	775	said,
	776	});
759	777	restSubscription(
760	778	app.db,
761	779	picked.subscription.id,
		@@ -513,7 +513,7 @@ const TOOLS: readonly Tool[] = [
513	513	{
514	514	name: "usage",
515	515	description:
516		"What the crew's runs on an app spent over the last days (1–90, default 7): tokens in and out, cost in US dollars, wall time and outcome, by subscription, agent and issue, with the newest runs. The same data as /api/v1/repos/:owner/:name/usage; refused unless you can write the app.",
	516	"What the crew's runs on an app spent over the last days (1–90, default 7): tokens in and out, cost in US dollars, wall time and outcome, by subscription, agent and issue, with the newest runs, and each account's standing in its 5-hour and weekly windows (cap, used, remaining, resets at — each figure read from the provider or inferred from the ledger). The same data as /api/v1/repos/:owner/:name/usage; refused unless you can write the app.",
517	517	inputSchema: {
518	518	type: "object",
519	519	properties: {
		@@ -65,6 +65,7 @@ import {
65	65	subscriptionAdd,
66	66	subscriptionDelete,
67	67	subscriptionsPage,
	68	subscriptionHeadroom,
68	69	subscriptionWake,
69	70	} from "../web/pages/subscriptions.ts";
70	71	import {
		@@ -494,6 +495,11 @@ export function buildRouter(): Router<Handler> {
494	495	router.add("POST", "/settings/subscriptions", subscriptionAdd);
495	496	router.add("POST", "/settings/subscriptions/:id/delete", subscriptionDelete);
496	497	router.add("POST", "/settings/subscriptions/:id/wake", subscriptionWake);
	498	router.add(
	499	"POST",
	500	"/settings/subscriptions/:id/headroom",
	501	subscriptionHeadroom,
	502	);
497	503	router.add("GET", "/settings/secrets", secretsPage);
498	504	router.add("POST", "/settings/secrets", secretSet);
499	505	router.add("POST", "/settings/secrets/delete", secretDelete);