@worca/app 1.5.0 → 1.6.0-rc.1

package/README.md

@@ -352,6 +352,11 @@ worca --project /path/to/your/project --prompt "Add a /search endpoint" --workfl
 # pause with Ctrl+C, continue later (survives restarts)
 worca resume <pipelineId>
 
+# see every run from the terminal — no browser, no Worca server needed
+worca runs
+worca runs --status paused
+worca runs <pipelineId>    # one run in detail (any unique prefix; --json for machines)
+
 # run it later: once, from this terminal, or on a repeat (needs `worca ui` up, or --wait)
 worca --project /path/to/your/project --prompt "Upgrade dependencies" --at "tomorrow 02:00"
 worca --project /path/to/your/project --prompt "Upgrade dependencies" --at 02:00 --wait --yes
@@ -394,7 +399,8 @@ interactive run paused and you can resume it); `1` a hard error, a stop, or an
 interactive pause an error forced; `2` a usage error; `3` a `--yes` run that
 parked itself — auth, quota, a usage or cost limit, exhausted retries, or a
 step error — with nobody attached to resume it. Nothing is discarded on a
-pause: `worca resume <pipelineId>` picks the run up where it stopped, and the
+pause: `worca resume <pipelineId>` picks the run up where it stopped — on the
+model it was started with (`--model`, or the one picked in the UI) — and the
 cause is printed with the pause block on stdout.
 
 ### `/worca` skill (inside Claude Code)

package/docker/compose.broker.yml

@@ -0,0 +1,79 @@
+# docker/compose.broker.yml — the credential broker overlay (docs/credential-broker.md).
+#
+#   docker compose -f compose.yml -f compose.broker.yml up -d
+#   (add -f compose.egress.yml as well to lock worca's network down)
+#
+# Model keys move out of the worca container into a second container from the same
+# image. worca holds no key: each claude spawn gets a short-lived token from the
+# broker, and the broker adds the real key on the way to the provider. Agents can't
+# read a key because there is none where they run.
+#
+# In .env (never ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN: compose.yml would hand
+# those to worca, and worca refuses to start while a key is within agents' reach):
+#
+#   WORCA_BROKER_SECRET=<32+ random chars>       # `docker compose run --rm broker worca broker secrets`
+#   WORCA_BROKER_KEY_ANTHROPIC=sk-ant-…          # single mode: the one key, held by the broker only
+#
+# Multi mode (a team sharing one instance, each person with their own keys) also needs
+# WORCA_BROKER_MODE=multi, WORCA_BROKER_VAULT_KEY, WORCA_BROKER_PUBLIC_URL and an identity
+# check for the key page; see docs/credential-broker.md.
+
+services:
+  worca:
+    depends_on:
+      - broker
+    environment:
+      WORCA_BROKER_URL: http://broker:8080
+      WORCA_BROKER_SECRET: ${WORCA_BROKER_SECRET:?set WORCA_BROKER_SECRET in .env}
+      WORCA_BROKER_SYSTEM_BILL_TO: ${WORCA_BROKER_SYSTEM_BILL_TO:-}
+      # Optional: pushes and pull requests as the person who acted (prefer | required),
+      # and what to do with MCP servers that carry a literal secret (block | warn | off).
+      WORCA_GH_AS_PERSON: ${WORCA_GH_AS_PERSON:-}
+      WORCA_MCP_SECRETS: ${WORCA_MCP_SECRETS:-}
+      # The key lives in the broker now; these stay empty in worca.
+      ANTHROPIC_API_KEY: ""
+      CLAUDE_CODE_OAUTH_TOKEN: ""
+
+  broker:
+    image: ghcr.io/sinishadjukic/worca:${WORCA_TAG:-latest}
+    init: true
+    command: ["worca", "broker"]
+    environment:
+      WORCA_BROKER_MODE: ${WORCA_BROKER_MODE:-single}
+      WORCA_BROKER_SECRET: ${WORCA_BROKER_SECRET:?set WORCA_BROKER_SECRET in .env}
+      WORCA_BROKER_VAULT_KEY: ${WORCA_BROKER_VAULT_KEY:-}
+      WORCA_BROKER_KEY_ANTHROPIC: ${WORCA_BROKER_KEY_ANTHROPIC:-}
+      WORCA_BROKER_LOCAL_URL: ${WORCA_BROKER_LOCAL_URL:-}
+      WORCA_BROKER_PUBLIC_URL: ${WORCA_BROKER_PUBLIC_URL:-}
+      WORCA_BROKER_RETURN_URL: ${WORCA_BROKER_RETURN_URL:-}
+      WORCA_CF_ACCESS_TEAM_DOMAIN: ${WORCA_BROKER_CF_ACCESS_TEAM_DOMAIN:-}
+      WORCA_CF_ACCESS_AUD: ${WORCA_BROKER_CF_ACCESS_AUD:-}
+      WORCA_IDENTITY_HEADER: ${WORCA_BROKER_IDENTITY_HEADER:-}
+      WORCA_BROKER_DEFAULT_DAILY_USD: ${WORCA_BROKER_DEFAULT_DAILY_USD:-}
+      WORCA_BROKER_DEFAULT_MONTHLY_USD: ${WORCA_BROKER_DEFAULT_MONTHLY_USD:-}
+      # "Push as me": the GitHub App or OAuth App people sign in with on the key page.
+      WORCA_BROKER_GITHUB_CLIENT_ID: ${WORCA_BROKER_GITHUB_CLIENT_ID:-}
+      WORCA_BROKER_GITHUB_CLIENT_SECRET: ${WORCA_BROKER_GITHUB_CLIENT_SECRET:-}
+      WORCA_BROKER_GITHUB_SCOPES: ${WORCA_BROKER_GITHUB_SCOPES:-repo}
+      # The image's /worca is owned by the worca user, so a named volume there is too.
+      WORCA_BROKER_DATA_DIR: /worca/broker
+    volumes:
+      - broker-data:/worca
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      start_period: 10s
+      retries: 3
+    # No published ports: worca reaches the broker on the compose network. In multi mode
+    # the key page (8081) is published through cloudflared or a reverse proxy, never 8080.
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    pids_limit: 128
+    mem_limit: 256m
+    restart: unless-stopped
+
+volumes:
+  broker-data:

package/docker/compose.isolation.yml

@@ -0,0 +1,40 @@
+# docker/compose.isolation.yml — agents under their own users, for a worca a TEAM shares
+# (docs/credential-broker.md). Use it with the broker overlay:
+#
+#   docker compose -f compose.yml -f compose.broker.yml -f compose.isolation.yml up -d
+#
+# What it changes, and why:
+#   - One volume (/data) holds everything, like the single-volume hosts (Railway): the
+#     entrypoint starts as root ONLY to prepare it, then drops to the `worca` user.
+#   - Agents run as `worca-agent`, and each signed-in person's agents as their own user
+#     from the pool (worca-agent-01..16): they can't read worca's settings, database or
+#     environment, nor each other's processes (and the broker token in them).
+#   - That switch is a `sudo` to those users only (never root), which needs setuid to
+#     work: `no-new-privileges` is lifted and exactly the capabilities it needs are kept.
+#
+# Needs Docker Compose 2.24 or newer (the !reset tag). Your repositories live on the
+# volume (/data/projects): clone them from the UI, or copy them in.
+
+services:
+  worca:
+    user: "0:0"
+    environment:
+      WORCA_DATA_DIR: /data
+    volumes:
+      - worca-data:/data
+    security_opt: !reset []
+    cap_drop:
+      - ALL
+    cap_add:
+      - CHOWN          # the entrypoint takes the fresh volume
+      - DAC_OVERRIDE
+      - FOWNER
+      - FSETID         # the shared folders' setgid bit (without it the kernel silently drops it,
+                       # new files get worca's own group, and agent users can't read them)
+      - SETUID         # dropping to worca, and sudo to the agent users
+      - SETGID
+      - AUDIT_WRITE    # sudo's session record
+      - KILL           # stopping an agent's process group
+
+volumes:
+  worca-data:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worca/app",
-  "version": "1.5.0",
+  "version": "1.6.0-rc.1",
   "description": "Worca — deterministic multi-agent pipeline that drives Claude Code (headless) through Plan -> Refine -> Implement -> Review, with a CLI, an installable /worca skill, and a web UI.",
   "license": "MIT",
   "author": "Sinisha Djukic",
@@ -65,6 +65,7 @@
     "@highlightjs/cdn-assets": "11.12.0",
     "dompurify": "3.4.14",
     "express": "^4.19.2",
+    "htmlparser2": "12.0.0",
     "marked": "18.0.10",
     "ws": "^8.18.0"
   },

package/src/broker/config.mjs

@@ -0,0 +1,200 @@
+// src/broker/config.mjs
+// The credential broker's configuration (plans/credential-broker-design.html §6.2).
+// Pure: reads only the `env` it is given (plus the files its *_FILE variables name),
+// and returns every problem as a list instead of throwing, so the entry point can
+// print them all and exit 78 once.
+import { readFileSync } from 'node:fs';
+import { normalizeTeamDomain } from '../core/cf-access.mjs';
+
+export const MODES = Object.freeze(['single', 'multi']);
+const HEADER_NAME_RE = /^[A-Za-z0-9-]{1,64}$/;
+const DAY_MS = 86_400_000;
+
+/**
+ * A secret from `NAME_FILE` (preferred: never in the process env) or `NAME`.
+ * Trailing whitespace is dropped (files usually end in a newline).
+ * @returns {{value: string|null, error: string|null}}
+ */
+export function readSecret(env, name, readFile = readFileSync) {
+  const file = String(env[`${name}_FILE`] || '').trim();
+  if (file) {
+    try {
+      const v = String(readFile(file, 'utf8')).trim();
+      return v ? { value: v, error: null } : { value: null, error: `${name}_FILE (${file}) is empty` };
+    } catch (err) {
+      return { value: null, error: `${name}_FILE (${file}) cannot be read: ${err.code || err.message}` };
+    }
+  }
+  const v = typeof env[name] === 'string' ? env[name].trim() : '';
+  return { value: v || null, error: null };
+}
+
+/** "48h" | "90m" | "3600s" | "3600000" (ms) -> ms, or null. */
+export function parseDuration(v) {
+  const s = String(v ?? '').trim();
+  if (!s) return null;
+  const m = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)?$/.exec(s);
+  if (!m) return null;
+  const n = Number(m[1]);
+  const mult = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: DAY_MS }[m[2] || 'ms'];
+  return Math.round(n * mult);
+}
+
+function parsePort(v, fallback) {
+  if (v === undefined || v === '') return fallback;
+  const n = Number(v);
+  return Number.isInteger(n) && n >= 0 && n < 65536 ? n : NaN;   // 0 = an ephemeral port (tests)
+}
+
+function parseUsd(v) {
+  if (v === undefined || v === null || String(v).trim() === '') return null;
+  const n = Number(v);
+  return Number.isFinite(n) && n >= 0 ? n : NaN;
+}
+
+function isLoopbackHost(h) {
+  const host = String(h || '').toLowerCase().replace(/^\[|\]$/g, '');
+  return host === 'localhost' || host === '::1' || /^127\./.test(host);
+}
+
+/** A 32-byte AES key from base64 (or base64url), or null. */
+export function decodeVaultKey(v) {
+  if (!v) return null;
+  let buf;
+  try { buf = Buffer.from(String(v).trim(), /[-_]/.test(v) ? 'base64url' : 'base64'); } catch { return null; }
+  return buf.length === 32 ? buf : null;
+}
+
+/** Slot ids whose single-mode key is set: WORCA_BROKER_KEY_<SLOT>[_FILE]. */
+function singleKeys(env, readFile, errors) {
+  const out = {};
+  const names = new Set();
+  for (const k of Object.keys(env)) {
+    const m = /^WORCA_BROKER_KEY_([A-Z0-9_]+?)(_FILE)?$/.exec(k);
+    if (m) names.add(m[1]);
+  }
+  for (const n of names) {
+    const { value, error } = readSecret(env, `WORCA_BROKER_KEY_${n}`, readFile);
+    if (error) errors.push(error);
+    if (value) out[n.toLowerCase().replace(/_/g, '-')] = value;
+  }
+  return out;
+}
+
+/**
+ * @param {Record<string,string|undefined>} env
+ * @returns {{config: object, errors: string[]}}
+ */
+export function readBrokerConfig(env = process.env, { readFile = readFileSync } = {}) {
+  const errors = [];
+  const mode = String(env.WORCA_BROKER_MODE || '').trim().toLowerCase();
+  if (!MODES.includes(mode)) errors.push(`WORCA_BROKER_MODE must be one of ${MODES.join(', ')} (got ${JSON.stringify(env.WORCA_BROKER_MODE ?? '')})`);
+
+  const secret = readSecret(env, 'WORCA_BROKER_SECRET', readFile);
+  if (secret.error) errors.push(secret.error);
+  else if (!secret.value) errors.push('WORCA_BROKER_SECRET (or WORCA_BROKER_SECRET_FILE) is required: the secret worca uses to ask for spawn tokens');
+  else if (secret.value.length < 32) errors.push('WORCA_BROKER_SECRET is too short: use at least 32 characters (`worca broker secrets` prints one)');
+
+  const vk = readSecret(env, 'WORCA_BROKER_VAULT_KEY', readFile);
+  if (vk.error) errors.push(vk.error);
+  const vaultKey = decodeVaultKey(vk.value);
+  if (vk.value && !vaultKey) errors.push('WORCA_BROKER_VAULT_KEY must be 32 bytes, base64-encoded (`worca broker secrets` prints one)');
+  if (mode === 'multi' && !vk.value) errors.push('WORCA_BROKER_VAULT_KEY is required in multi mode: it encrypts people\'s keys at rest');
+  const vko = readSecret(env, 'WORCA_BROKER_VAULT_KEY_OLD', readFile);
+  if (vko.error) errors.push(vko.error);
+  const vaultKeyOld = decodeVaultKey(vko.value);
+  if (vko.value && !vaultKeyOld) errors.push('WORCA_BROKER_VAULT_KEY_OLD must be 32 bytes, base64-encoded');
+
+  const host = String(env.WORCA_BROKER_HOST || '0.0.0.0').trim();
+  const port = parsePort(env.WORCA_BROKER_PORT, 8080);
+  const uiPort = parsePort(env.WORCA_BROKER_UI_PORT, 8081);
+  if (Number.isNaN(port)) errors.push('WORCA_BROKER_PORT must be a port number');
+  if (Number.isNaN(uiPort)) errors.push('WORCA_BROKER_UI_PORT must be a port number');
+  if (port === uiPort && port !== 0) errors.push('WORCA_BROKER_PORT and WORCA_BROKER_UI_PORT must differ: the key page port is the only one a public route may point at');
+
+  let publicUrl = null;
+  const pu = String(env.WORCA_BROKER_PUBLIC_URL || '').trim();
+  if (pu) {
+    try {
+      const u = new URL(pu);
+      if (u.protocol !== 'https:' && !(u.protocol === 'http:' && isLoopbackHost(u.hostname))) {
+        errors.push('WORCA_BROKER_PUBLIC_URL must be https (http only for localhost)');
+      } else if (u.pathname !== '/' || u.search || u.hash || u.username || u.password) {
+        errors.push('WORCA_BROKER_PUBLIC_URL must be an origin only, e.g. https://worca-01-keys.example.com');
+      } else publicUrl = u.origin;
+    } catch { errors.push('WORCA_BROKER_PUBLIC_URL is not a URL'); }
+  }
+  let returnUrl = null;
+  const ru = String(env.WORCA_BROKER_RETURN_URL || '').trim();
+  if (ru) {
+    try { const u = new URL(ru); if (u.protocol === 'https:' || u.protocol === 'http:') returnUrl = u.href; else throw new Error(); }
+    catch { errors.push('WORCA_BROKER_RETURN_URL must be an http(s) URL'); }
+  }
+
+  const teamDomain = normalizeTeamDomain(env.WORCA_CF_ACCESS_TEAM_DOMAIN);
+  const aud = String(env.WORCA_CF_ACCESS_AUD || '').trim();
+  const identityHeader = String(env.WORCA_IDENTITY_HEADER || '').trim();
+  let identity = null;
+  if (teamDomain || aud) {
+    if (!teamDomain || !aud) errors.push('set both WORCA_CF_ACCESS_TEAM_DOMAIN and WORCA_CF_ACCESS_AUD (the AUD of the key page\'s own Access application)');
+    else identity = { kind: 'access', teamDomain, aud };
+  } else if (identityHeader) {
+    if (!HEADER_NAME_RE.test(identityHeader)) errors.push('WORCA_IDENTITY_HEADER is not a valid header name');
+    else identity = { kind: 'header', header: identityHeader.toLowerCase() };
+  }
+  if (mode === 'multi') {
+    if (!publicUrl) errors.push('WORCA_BROKER_PUBLIC_URL is required in multi mode: the address of the key page');
+    if (!identity) errors.push('multi mode needs an identity check for the key page: WORCA_CF_ACCESS_TEAM_DOMAIN + WORCA_CF_ACCESS_AUD, or WORCA_IDENTITY_HEADER');
+  }
+
+  const defaultDailyUsd = parseUsd(env.WORCA_BROKER_DEFAULT_DAILY_USD);
+  const defaultMonthlyUsd = parseUsd(env.WORCA_BROKER_DEFAULT_MONTHLY_USD);
+  if (Number.isNaN(defaultDailyUsd)) errors.push('WORCA_BROKER_DEFAULT_DAILY_USD must be a number >= 0');
+  if (Number.isNaN(defaultMonthlyUsd)) errors.push('WORCA_BROKER_DEFAULT_MONTHLY_USD must be a number >= 0');
+
+  let tokenMaxTtlMs = 48 * 3_600_000;
+  if (env.WORCA_BROKER_TOKEN_MAX_TTL) {
+    const t = parseDuration(env.WORCA_BROKER_TOKEN_MAX_TTL);
+    if (!t || t < 60_000) errors.push('WORCA_BROKER_TOKEN_MAX_TTL must be a duration of at least 1m, e.g. 48h');
+    else tokenMaxTtlMs = t;
+  }
+
+  // "Push as me" (optional): each person signs in with GitHub on the key page through the
+  // operator's GitHub App or OAuth App; worca's pushes and PRs then go out as them.
+  const githubClientId = String(env.WORCA_BROKER_GITHUB_CLIENT_ID || '').trim() || null;
+  const ghSecret = readSecret(env, 'WORCA_BROKER_GITHUB_CLIENT_SECRET', readFile);
+  if (ghSecret.error) errors.push(ghSecret.error);
+  if (ghSecret.value && !githubClientId) errors.push('WORCA_BROKER_GITHUB_CLIENT_SECRET needs WORCA_BROKER_GITHUB_CLIENT_ID');
+  if (githubClientId && !/^[A-Za-z0-9._-]{8,64}$/.test(githubClientId)) errors.push('WORCA_BROKER_GITHUB_CLIENT_ID does not look like a GitHub client ID');
+
+  const keys = singleKeys(env, readFile, errors);
+  const dataDir = String(env.WORCA_BROKER_DATA_DIR || '').trim() || null;
+
+  const config = Object.freeze({
+    mode: MODES.includes(mode) ? mode : null,
+    secret: secret.value,
+    vaultKey,
+    vaultKeyOld,
+    dataDir,
+    host,
+    port,
+    uiPort,
+    uiEnabled: mode === 'multi',
+    publicUrl,
+    returnUrl,
+    identity,
+    slotsFile: String(env.WORCA_BROKER_SLOTS_FILE || '').trim() || null,
+    localUrl: String(env.WORCA_BROKER_LOCAL_URL || '').trim() || null,
+    github: githubClientId ? Object.freeze({
+      clientId: githubClientId,
+      clientSecret: ghSecret.value || null,
+      scope: String(env.WORCA_BROKER_GITHUB_SCOPES ?? 'repo').trim(),
+    }) : null,
+    singleKeys: Object.freeze(keys),
+    allowTeamKeys: /^(1|true|yes|on)$/i.test(String(env.WORCA_BROKER_ALLOW_TEAM_KEYS || '')),
+    defaultDailyUsd: Number.isNaN(defaultDailyUsd) ? null : defaultDailyUsd,
+    defaultMonthlyUsd: Number.isNaN(defaultMonthlyUsd) ? null : defaultMonthlyUsd,
+    tokenMaxTtlMs,
+  });
+  return { config, errors };
+}

package/src/broker/copilot.mjs

@@ -0,0 +1,124 @@
+// src/broker/copilot.mjs
+// GitHub Copilot inside the credential broker (plans/credential-broker-design.html §5.3).
+// A person signs in on the key page with GitHub's device flow; the broker keeps their
+// GitHub token sealed in the vault and, per request, exchanges it for Copilot's
+// short-lived API token (cached until shortly before it expires). worca never sees
+// either token. The editor headers and endpoints are the ones worca's own Copilot
+// provider uses (src/core/bridge/providers/copilot.mjs), imported from there.
+import { githubHeaders, GITHUB_API, GITHUB_BASE, GITHUB_CLIENT_ID, GITHUB_SCOPES } from '../core/bridge/providers/copilot.mjs';
+
+export const DEFAULT_EXCHANGE_URL = `${GITHUB_API}/copilot_internal/v2/token`;
+const REFRESH_MARGIN_MS = 60_000;
+
+/** A Copilot API host must be GitHub's (the exchange response names it; never trust anything else). */
+export function isCopilotHost(origin) {
+  try {
+    const u = new URL(origin);
+    return u.protocol === 'https:' && (u.hostname === 'githubcopilot.com' || u.hostname.endsWith('.githubcopilot.com'));
+  } catch { return false; }
+}
+
+/**
+ * The exchange, cached per GitHub token.
+ * @param {{fetchImpl?:typeof fetch, exchangeUrl?:string, now?:()=>number, defaultHost?:string, allowHost?:(o:string)=>boolean}} o
+ */
+export function createCopilotExchange({ fetchImpl = globalThis.fetch, exchangeUrl = DEFAULT_EXCHANGE_URL, now = Date.now, defaultHost = 'https://api.githubcopilot.com', allowHost = isCopilotHost } = {}) {
+  const cache = new Map();   // github token -> {token, host, expiresAt}
+  return {
+    /** {token, host} or throws with .status (401/403 = the GitHub sign-in no longer works). */
+    async token(githubToken, { force = false } = {}) {
+      const hit = cache.get(githubToken);
+      if (!force && hit && hit.expiresAt - REFRESH_MARGIN_MS > now()) return hit;
+      const res = await fetchImpl(exchangeUrl, { headers: githubHeaders(githubToken) });
+      if (!res.ok) {
+        cache.delete(githubToken);
+        const err = new Error(res.status === 401 || res.status === 403
+          ? `GitHub refused the sign-in (${res.status}): sign in to Copilot again`
+          : `the Copilot token exchange failed (HTTP ${res.status})`);
+        err.status = res.status;
+        throw err;
+      }
+      const j = await res.json();
+      if (!j || typeof j.token !== 'string') throw new Error('the Copilot token exchange returned no token');
+      let host = defaultHost;
+      const api = j.endpoints && typeof j.endpoints.api === 'string' ? j.endpoints.api.replace(/\/+$/, '') : null;
+      if (api && allowHost(api)) host = new URL(api).origin;
+      const expiresAt = Number.isFinite(j.expires_at) ? j.expires_at * 1000 : now() + 25 * 60_000;
+      const v = { token: j.token, host, expiresAt };
+      cache.set(githubToken, v);
+      return v;
+    },
+    invalidate(githubToken) { cache.delete(githubToken); },
+  };
+}
+
+/**
+ * GitHub's device flow, step 1: a code for the person to enter at github.com/login/device.
+ * `clientId`/`scope`: Copilot's own app by default; "push as me" passes the operator's
+ * GitHub App or OAuth App (WORCA_BROKER_GITHUB_CLIENT_ID).
+ */
+export async function startDeviceFlow({ fetchImpl = globalThis.fetch, baseUrl = GITHUB_BASE, clientId = GITHUB_CLIENT_ID, scope = GITHUB_SCOPES } = {}) {
+  const res = await fetchImpl(`${baseUrl}/login/device/code`, {
+    method: 'POST',
+    headers: { accept: 'application/json', 'content-type': 'application/json' },
+    body: JSON.stringify({ client_id: clientId, ...(scope ? { scope } : {}) }),
+  });
+  if (!res.ok) throw new Error(`GitHub device sign-in failed (HTTP ${res.status})`);
+  const j = await res.json();
+  if (!j.device_code || !j.user_code) throw new Error('GitHub returned no device code');
+  return { deviceCode: j.device_code, userCode: j.user_code, verificationUri: j.verification_uri || 'https://github.com/login/device', interval: Number(j.interval) || 5, expiresIn: Number(j.expires_in) || 900 };
+}
+
+/**
+ * Step 2, polled: {token, refreshToken?, expiresIn?} once the person approved (a GitHub App
+ * with expiring user tokens also returns a refresh token), {pending:true} before, {error}.
+ */
+export async function pollDeviceFlow(deviceCode, { fetchImpl = globalThis.fetch, baseUrl = GITHUB_BASE, clientId = GITHUB_CLIENT_ID } = {}) {
+  const res = await fetchImpl(`${baseUrl}/login/oauth/access_token`, {
+    method: 'POST',
+    headers: { accept: 'application/json', 'content-type': 'application/json' },
+    body: JSON.stringify({ client_id: clientId, device_code: deviceCode, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }),
+  });
+  const j = await res.json().catch(() => ({}));
+  if (j.access_token) {
+    return {
+      token: j.access_token,
+      ...(j.refresh_token ? { refreshToken: j.refresh_token } : {}),
+      ...(Number.isFinite(j.expires_in) ? { expiresIn: j.expires_in } : {}),
+    };
+  }
+  if (j.error === 'authorization_pending' || j.error === 'slow_down') return { pending: true, slowDown: j.error === 'slow_down' };
+  return { error: j.error_description || j.error || `HTTP ${res.status}` };
+}
+
+// ── "Push as me": a person's GitHub user token (credential broker, docs/credential-broker.md)
+
+/**
+ * A stored GitHub credential: a plain token (a pasted fine-grained token, an OAuth App
+ * token that doesn't expire) or `{"t":…,"r":…,"e":…}` for a GitHub App user token with
+ * its refresh token and expiry (ms). Pure.
+ */
+export function parseGithubSecret(secret) {
+  const s = String(secret || '');
+  if (s.startsWith('{')) {
+    try { const j = JSON.parse(s); if (typeof j.t === 'string') return { token: j.t, refreshToken: j.r || null, expiresAt: Number(j.e) || null }; } catch { /* plain */ }
+  }
+  return { token: s, refreshToken: null, expiresAt: null };
+}
+
+export function githubSecretOf({ token, refreshToken = null, expiresIn = null }, now = Date.now()) {
+  return refreshToken ? JSON.stringify({ t: token, r: refreshToken, e: expiresIn ? now + expiresIn * 1000 : null }) : token;
+}
+
+/** Refresh a GitHub App user token. Returns the new stored secret, or throws. */
+export async function refreshGithubToken({ refreshToken, clientId, clientSecret, fetchImpl = globalThis.fetch, baseUrl = GITHUB_BASE, now = Date.now() }) {
+  if (!clientSecret) throw new Error('the GitHub sign-in expired and the broker has no client secret to renew it: sign in again');
+  const res = await fetchImpl(`${baseUrl}/login/oauth/access_token`, {
+    method: 'POST',
+    headers: { accept: 'application/json', 'content-type': 'application/json' },
+    body: JSON.stringify({ client_id: clientId, client_secret: clientSecret, grant_type: 'refresh_token', refresh_token: refreshToken }),
+  });
+  const j = await res.json().catch(() => ({}));
+  if (!j.access_token) throw new Error(`GitHub would not renew the sign-in (${j.error || `HTTP ${res.status}`}): sign in again`);
+  return githubSecretOf({ token: j.access_token, refreshToken: j.refresh_token || refreshToken, expiresIn: j.expires_in }, now);
+}

package/src/broker/limits.mjs

@@ -0,0 +1,88 @@
+// src/broker/limits.mjs
+// Spend and load limits (plans/credential-broker-design.html §6.4 step 4): the
+// worst a rogue agent can do is burn credits, and these cap how many. In memory:
+// concurrency per token and per person+slot, requests per minute per person+slot.
+// Budgets read the usage table (cached briefly) against the person's own cap, the
+// operator default, and the token's own budget.
+
+const DAY_MS = 86_400_000;
+const SPEND_CACHE_MS = 10_000;
+
+export function startOfUtcDay(now) { const d = new Date(now); d.setUTCHours(0, 0, 0, 0); return d.getTime(); }
+export function startOfUtcMonth(now) { const d = new Date(now); d.setUTCDate(1); d.setUTCHours(0, 0, 0, 0); return d.getTime(); }
+
+export function createLimits({ store, config, now = Date.now }) {
+  const active = new Map();        // key -> count
+  const windows = new Map();       // person|slot -> [timestamps]
+  const spendCache = new Map();    // person|slot|period -> {at, usd}
+
+  const inc = (k) => active.set(k, (active.get(k) || 0) + 1);
+  const dec = (k) => { const n = (active.get(k) || 1) - 1; if (n <= 0) active.delete(k); else active.set(k, n); };
+
+  function spent(billTo, slot, period) {
+    const key = `${billTo}|${slot}|${period}`;
+    const t = now();
+    const hit = spendCache.get(key);
+    if (hit && t - hit.at < SPEND_CACHE_MS) return hit.usd;
+    const since = period === 'day' ? startOfUtcDay(t) : startOfUtcMonth(t);
+    const usd = store.spentSince(billTo, slot, since);
+    spendCache.set(key, { at: t, usd });
+    return usd;
+  }
+
+  return {
+    /**
+     * Admit one request, or say why not. On admission the caller MUST call release().
+     * @returns {{release: () => void} | {status:number, kind:'rate'|'budget', message:string, retryAfter?:number}}
+     */
+    acquire({ tokenRow, slot, credentialRow = null }) {
+      const person = tokenRow.bill_to;
+      const lim = slot.limits || {};
+      const perToken = Number(lim.concurrencyPerToken) || 8;
+      const perPerson = Number(lim.concurrencyPerPerson) || 16;
+      const rpm = Number(lim.rpmPerPerson) || 240;
+
+      // Budgets first: a spent budget is not cleared by waiting.
+      if (tokenRow.budget_usd != null && tokenRow.spent_usd >= tokenRow.budget_usd) {
+        return { status: 403, kind: 'budget', message: `quota reached: this spawn's budget of $${fmt(tokenRow.budget_usd)} is spent` };
+      }
+      const daily = credentialRow?.daily_usd ?? config.defaultDailyUsd;
+      if (daily != null && spent(person, slot.id, 'day') >= daily) {
+        return { status: 403, kind: 'budget', message: `quota reached: daily budget of $${fmt(daily)} for ${person} on ${slot.id}` };
+      }
+      const monthly = credentialRow?.monthly_usd ?? config.defaultMonthlyUsd;
+      if (monthly != null && spent(person, slot.id, 'month') >= monthly) {
+        return { status: 403, kind: 'budget', message: `quota reached: monthly budget of $${fmt(monthly)} for ${person} on ${slot.id}` };
+      }
+
+      const tk = `t:${tokenRow.hash}`;
+      const pk = `p:${person}|${slot.id}`;
+      if ((active.get(tk) || 0) >= perToken || (active.get(pk) || 0) >= perPerson) {
+        return { status: 429, kind: 'rate', message: 'too many concurrent requests, retry after 2 seconds', retryAfter: 2 };
+      }
+      const t = now();
+      const w = (windows.get(pk) || []).filter((x) => t - x < 60_000);
+      if (w.length >= rpm) {
+        const wait = Math.max(1, Math.ceil((60_000 - (t - w[0])) / 1000));
+        windows.set(pk, w);
+        return { status: 429, kind: 'rate', message: `too many requests per minute, retry after ${wait} seconds`, retryAfter: wait };
+      }
+      w.push(t);
+      windows.set(pk, w);
+      inc(tk); inc(pk);
+      let released = false;
+      return { release() { if (released) return; released = true; dec(tk); dec(pk); } };
+    },
+    /** Forget cached spend for a person (after a usage row lands, budgets see it within 10 s anyway). */
+    invalidate(billTo, slot) {
+      for (const p of ['day', 'month']) spendCache.delete(`${billTo}|${slot}|${p}`);
+    },
+    _active: active,
+  };
+}
+
+function fmt(n) {
+  return Number(n).toFixed(2).replace(/\.00$/, '');
+}
+
+export { DAY_MS };