crewly 1.20.187 → 1.20.188

package/dist/backend/backend/src/services/spend/spend-cap.service.js

@@ -1,33 +1,36 @@
 /**
- * Per-agent daily spend cap with a hard stop.
+ * Daily token caps with a hard stop: per agent, per team and all agents
+ * together, plus temporary boosts.
  *
+ * - The unit is tokens (input incl. cached + output, see `eventTokens`).
  * - Caps are the owner's own limits (unlike the runtime fallback, which
  *   reacts to a provider's usage limit). All are OFF until the owner sets
- *   one: a default per-agent cap, per-agent overrides, and an optional
- *   all-agents daily total.
+ *   one: a default per-agent cap, per-agent overrides, per-team caps, and an
+ *   optional all-agents total.
  * - At {@link SPEND_CAP_CONSTANTS.WARN_FRACTION} of a cap the owner gets ONE
  *   heads-up.
  * - At 100% the agent is hard-stopped: {@link stopOf} answers the delivery
  *   and wake gates, so no new turn starts (the current one may finish) and
- *   messages stay queued. The owner gets ONE decision card: "Raise to $Y
- *   today" / "Keep stopped".
- * - Local midnight resets everything; raises last for the day they were
- *   made. When a stop lifts (midnight, raise, cap change) the queued
- *   messages are released.
- *
- * Spend comes from {@link SpendLedger} (the shared token ledger and its one
- * cost computation).
+ *   messages stay queued. The owner gets ONE decision card: "Boost +X
+ *   today" / "Unlimited today" / "Keep stopped".
+ * - A boost covers an agent, a team (its members) or everyone. For every
+ *   agent it covers, it adds `extraTokens` to EVERY cap checked for that
+ *   agent (its own, its team's, the total), or lifts them all
+ *   (`unlimited`). It ends at `until` — by default the next local midnight.
+ * - Local midnight resets the day; when a stop lifts (midnight, boost, cap
+ *   change) the queued messages are released.
  *
  * specs/2026-10-02-spend-cap.md
  *
  * @module services/spend/spend-cap.service
  */
+import { randomUUID } from 'crypto';
 import { ORCHESTRATOR_SESSION_NAME, SPEND_CAP_CONSTANTS as C } from '../../constants.js';
 import { localDateKey, localMidnight } from '../project-tickets/ticket-autopilot-decision.js';
-import { formatUsd, spendCapReason } from './spend-cap.gate.js';
-import { cents } from './spend-ledger.service.js';
+import { compactTokens, formatTokens, parseTokenAmount } from '../usage/token-format.js';
+import { spendCapReason } from './spend-cap.gate.js';
 import { emptyDay, emptySpendCapFile } from './spend-cap.store.js';
-/** A rejected cap change. */
+/** A rejected change. */
 export class SpendCapError extends Error {
     status;
     /**
@@ -52,42 +55,57 @@ function isCap(v) {
 /**
  * Validate a cap from the API.
  *
- * @param v - Value
+ * @param v - Value (number or "20M")
  * @param what - Field name for the error
- * @returns The cap (whole cents) or null
+ * @returns The cap (whole tokens) or null
  * @throws SpendCapError
  */
 function parseCap(v, what) {
-    if (v === null)
+    if (v === null || v === '')
         return null;
-    const n = typeof v === 'string' ? Number(v.replace(/^\$/, '')) : v;
-    if (!isCap(n))
-        throw new SpendCapError(400, `${what} must be a positive amount in USD (e.g. 5) or null to turn it off`);
-    return cents(n);
+    const n = parseTokenAmount(v);
+    if (n === null)
+        throw new SpendCapError(400, `${what} must be a positive number of tokens (e.g. 5000000 or "5M"), or null to turn it off`);
+    return n;
 }
 /**
- * The "Raise to $Y today" amount: the cap times RAISE_FACTOR, rounded up to
- * whole dollars, and always above what was already spent.
+ * Round up to a whole million (at least 1M).
  *
- * @param capUsd - Cap in force
- * @param spentUsd - Spent today
- * @returns USD
+ * @param tokens - Tokens
+ * @returns Rounded tokens
  */
-export function suggestedRaise(capUsd, spentUsd) {
-    return Math.max(Math.ceil(capUsd * C.RAISE_FACTOR), Math.ceil(spentUsd) + 1);
+export function roundUpMillions(tokens) {
+    return Math.max(1_000_000, Math.ceil(tokens / 1_000_000) * 1_000_000);
 }
 /**
- * Read the amount out of a "Raise to $Y today" option label.
+ * The "Boost +X today" amount on a cap card: the cap times BOOST_FACTOR,
+ * rounded up to a whole million.
+ *
+ * @param capTokens - Cap in force
+ * @returns Tokens
+ */
+export function suggestedBoost(capTokens) {
+    return roundUpMillions(capTokens * C.BOOST_FACTOR);
+}
+/**
+ * Read the amount out of a "Boost +X tokens today" option label.
  *
  * @param label - Option label
- * @returns USD, or null when the label is not a raise
+ * @returns Tokens, `unlimited`, or null when the label is not a boost
  */
-export function raiseAmountOf(label) {
-    const m = /^Raise to \$(\d+(?:\.\d+)?) today/i.exec(label ?? '');
-    return m ? Number(m[1]) : null;
+export function boostOfLabel(label) {
+    const text = (label ?? '').trim();
+    if (text.toLowerCase().startsWith(C.OPTIONS.UNLIMITED.toLowerCase()))
+        return 'unlimited';
+    const m = /^Boost \+(\S+?)(?: tokens)? today/i.exec(text);
+    return m ? parseTokenAmount(m[1]) : null;
+}
+/** Team target key. */
+export function teamTarget(teamId) {
+    return `${C.TEAM_TARGET_PREFIX}${teamId}`;
 }
 /**
- * Per-agent daily spend cap service.
+ * Daily token cap service.
  */
 export class SpendCapService {
     deps;
@@ -97,9 +115,11 @@ export class SpendCapService {
     timer = null;
     /** Sessions stopped at the last evaluation (to release them when the stop lifts) */
     lastStopped = new Set();
-    /** Evaluation passes run one after another */
     chain = Promise.resolve();
     queuedPass = null;
+    /** Team index, refreshed on every evaluation (the gate is synchronous) */
+    teamList = [];
+    teamsOfSession = new Map();
     /**
      * @param deps - Collaborators
      */
@@ -123,6 +143,17 @@ export class SpendCapService {
             clearInterval(this.timer);
         this.timer = null;
     }
+    /** Re-read the team list now (tests; the tick does it too). */
+    async refreshTeams() {
+        const teams = (await this.deps.teams?.().catch(() => [])) ?? [];
+        this.teamList = teams;
+        const index = new Map();
+        for (const t of teams) {
+            for (const s of t.members)
+                index.set(s, [...(index.get(s) ?? []), t.id]);
+        }
+        this.teamsOfSession = index;
+    }
     // ---------------------------------------------------------------- caps
     /** @returns The owner's caps (a copy) */
     getConfig() {
@@ -139,56 +170,165 @@ export class SpendCapService {
         if (!patch || typeof patch !== 'object')
             throw new SpendCapError(400, 'Send the caps to change as JSON');
         const next = this.getConfig();
-        if ('defaultAgentCapUsd' in patch)
-            next.defaultAgentCapUsd = parseCap(patch.defaultAgentCapUsd, 'defaultAgentCapUsd');
-        if ('totalCapUsd' in patch)
-            next.totalCapUsd = parseCap(patch.totalCapUsd, 'totalCapUsd');
+        if ('defaultAgentCapTokens' in patch)
+            next.defaultAgentCapTokens = parseCap(patch.defaultAgentCapTokens, 'defaultAgentCapTokens');
+        if ('totalCapTokens' in patch)
+            next.totalCapTokens = parseCap(patch.totalCapTokens, 'totalCapTokens');
         if (patch.agents !== undefined) {
             if (!patch.agents || typeof patch.agents !== 'object')
-                throw new SpendCapError(400, 'agents must be an object: { "<session>": 5 | null | "default" }');
+                throw new SpendCapError(400, 'agents must be an object: { "<session>": 5000000 | null | "default" }');
             for (const [session, value] of Object.entries(patch.agents)) {
                 if (!session.trim())
                     throw new SpendCapError(400, 'agents keys must be agent session names');
                 if (value === 'default')
-                    delete next.agentCapsUsd[session];
+                    delete next.agentCapsTokens[session];
                 else
-                    next.agentCapsUsd[session] = parseCap(value, `agents.${session}`);
+                    next.agentCapsTokens[session] = parseCap(value, `agents.${session}`);
+            }
+        }
+        if (patch.teams !== undefined) {
+            if (!patch.teams || typeof patch.teams !== 'object')
+                throw new SpendCapError(400, 'teams must be an object: { "<teamId>": 50000000 | null }');
+            for (const [teamId, value] of Object.entries(patch.teams)) {
+                if (!teamId.trim())
+                    throw new SpendCapError(400, 'teams keys must be team ids');
+                const cap = parseCap(value, `teams.${teamId}`);
+                if (cap === null)
+                    delete next.teamCapsTokens[teamId];
+                else
+                    next.teamCapsTokens[teamId] = cap;
             }
         }
         next.updatedAt = this.now().toISOString();
         this.file.config = next;
         this.persist();
-        this.logger?.info('Spend caps changed', { caps: next });
+        this.logger?.info('Token caps changed', { caps: next });
         await this.evaluate();
         return this.getConfig();
     }
+    // ---------------------------------------------------------------- boosts
+    /** @returns Boosts in force (expired ones are dropped) */
+    activeBoosts() {
+        this.pruneBoosts();
+        return this.file.boosts.map((b) => ({ ...b }));
+    }
     /**
-     * Lift a cap for today only.
+     * Add a temporary boost.
      *
-     * @param target - Agent session, or `*` for the all-agents total
-     * @param usd - New cap for today (must be above today's spend)
-     * @returns The new cap for today
-     * @throws SpendCapError when the amount is not above today's spend
+     * @param input - Scope, target, extra tokens or unlimited, optional end
+     * @returns The boost
+     * @throws SpendCapError on a bad request
      */
-    async raiseToday(target, usd) {
-        const cap = parseCap(usd, 'capUsd');
-        if (cap === null)
-            throw new SpendCapError(400, 'capUsd must be a positive amount in USD');
-        this.rollDay();
-        const spent = target === C.TOTAL_TARGET ? this.deps.ledger.totalToday() : this.deps.ledger.spentToday(target);
-        if (cap <= spent) {
-            throw new SpendCapError(400, `${formatUsd(cap)} is not above what ${this.nameOf(target)} already spent today (${formatUsd(spent)}); pick a higher amount`);
+    async boost(input) {
+        if (!input || typeof input !== 'object')
+            throw new SpendCapError(400, 'Send the boost as JSON');
+        const target = await this.resolveBoostTarget(input.scope, input.id);
+        const unlimited = input.unlimited === true;
+        const extra = unlimited ? null : parseTokenAmount(input.extraTokens);
+        if (!unlimited && extra === null)
+            throw new SpendCapError(400, 'Send extraTokens (a positive number of tokens, e.g. 20000000 or "20M") or unlimited: true');
+        const now = this.now();
+        let until = this.nextMidnight();
+        if (input.until !== undefined && input.until !== null && input.until !== '') {
+            const t = new Date(String(input.until));
+            if (Number.isNaN(t.getTime()) || t.getTime() <= now.getTime())
+                throw new SpendCapError(400, 'until must be a future time (ISO 8601)');
+            until = t;
         }
-        this.file.day.raised[target] = cap;
+        const boost = {
+            id: randomUUID(),
+            target,
+            ...(unlimited ? { unlimited: true } : { extraTokens: extra }),
+            until: until.toISOString(),
+            createdAt: now.toISOString(),
+            ...(input.by ? { by: input.by } : {}),
+        };
+        this.pruneBoosts();
+        this.file.boosts.push(boost);
         this.persist();
-        this.logger?.info('Spend cap raised for today', { target, capUsd: cap, spentUsd: cents(spent) });
+        this.logger?.info('Usage boost added', { target, extraTokens: boost.extraTokens, unlimited: boost.unlimited, until: boost.until });
         await this.evaluate();
-        return cap;
+        return { ...boost };
+    }
+    /**
+     * End a boost early.
+     *
+     * @param id - Boost id
+     * @returns True when it existed
+     */
+    async removeBoost(id) {
+        const before = this.file.boosts.length;
+        this.file.boosts = this.file.boosts.filter((b) => b.id !== id);
+        if (this.file.boosts.length === before)
+            return false;
+        this.persist();
+        await this.evaluate();
+        return true;
+    }
+    /**
+     * Owner-facing description of a boost target.
+     *
+     * @param target - Boost target
+     * @returns e.g. `everyone`, `team CE`, `Ella`
+     */
+    describeTarget(target) {
+        if (target === C.TOTAL_TARGET)
+            return 'everyone';
+        if (target.startsWith(C.TEAM_TARGET_PREFIX)) {
+            const id = target.slice(C.TEAM_TARGET_PREFIX.length);
+            return `team ${this.teamList.find((t) => t.id === id)?.name ?? id}`;
+        }
+        return this.nameOf(target);
+    }
+    /**
+     * Extra tokens / unlimited a boost set gives for one target set.
+     *
+     * @param covers - Which boost targets apply
+     * @returns Sum of extras and whether any is unlimited
+     */
+    boostFor(covers) {
+        let extra = 0;
+        let unlimited = false;
+        for (const b of this.activeBoostsRaw()) {
+            if (!covers(b.target))
+                continue;
+            if (b.unlimited)
+                unlimited = true;
+            else
+                extra += b.extraTokens ?? 0;
+        }
+        return { extra, unlimited };
+    }
+    /** Boosts covering an agent: its own, its teams', everyone's. */
+    boostForSession(session) {
+        const teams = new Set((this.teamsOfSession.get(session) ?? []).map(teamTarget));
+        return this.boostFor((t) => t === C.TOTAL_TARGET || t === session || teams.has(t));
+    }
+    /**
+     * Boosts covering a team (team and everyone boosts) — what the ticket
+     * autopilot budget of the team's projects honours.
+     *
+     * @param teamId - Team id
+     * @returns Extra tokens and unlimited
+     */
+    boostForTeam(teamId) {
+        return this.boostForTeams([teamId]);
+    }
+    /**
+     * Boosts covering any of several teams, each boost counted once (a
+     * project worked on by two teams).
+     *
+     * @param teamIds - Team ids
+     * @returns Extra tokens and unlimited
+     */
+    boostForTeams(teamIds) {
+        const keys = new Set(teamIds.map(teamTarget));
+        return this.boostFor((t) => t === C.TOTAL_TARGET || keys.has(t));
     }
     // ---------------------------------------------------------------- gate
     /**
      * The stop in force for a session (the delivery / wake gate). Synchronous
-     * and live: it reads today's spend now, not at the last tick.
+     * and live: it reads today's usage now, not at the last tick.
      *
      * @param session - Agent session
      * @returns Stop, or null when the agent may run
@@ -210,72 +350,98 @@ export class SpendCapService {
         return this.nameOf(session);
     }
     /**
-     * Cap in force today for a target, and where it comes from.
+     * An agent's own cap before boosts, and where it comes from.
      *
-     * @param target - Agent session, or `*`
+     * @param session - Agent session
      * @returns Cap (null = none) and source
      */
-    capOf(target) {
-        const raised = this.file.day.raised[target];
-        if (isCap(raised))
-            return { capUsd: raised, source: 'raised' };
+    ownCapOf(session) {
         const cfg = this.file.config;
-        if (target === C.TOTAL_TARGET)
-            return isCap(cfg.totalCapUsd) ? { capUsd: cfg.totalCapUsd, source: 'default' } : { capUsd: null, source: 'none' };
-        if (Object.prototype.hasOwnProperty.call(cfg.agentCapsUsd, target)) {
-            const v = cfg.agentCapsUsd[target];
-            return isCap(v) ? { capUsd: v, source: 'override' } : { capUsd: null, source: 'exempt' };
+        if (Object.prototype.hasOwnProperty.call(cfg.agentCapsTokens, session)) {
+            const v = cfg.agentCapsTokens[session];
+            return isCap(v) ? { capTokens: v, source: 'override' } : { capTokens: null, source: 'exempt' };
         }
-        return isCap(cfg.defaultAgentCapUsd) ? { capUsd: cfg.defaultAgentCapUsd, source: 'default' } : { capUsd: null, source: 'none' };
+        return isCap(cfg.defaultAgentCapTokens) ? { capTokens: cfg.defaultAgentCapTokens, source: 'default' } : { capTokens: null, source: 'none' };
     }
     // ---------------------------------------------------------------- view
     /**
-     * Spend plus caps for the API / Settings panel.
+     * Usage plus caps for the API / Settings panel.
      *
      * @param days - Window
      * @returns View
      */
     async view(days = C.DEFAULT_DAYS) {
         this.rollDay();
+        await this.refreshTeams();
         const summary = this.deps.ledger.summarize(days);
         const known = (await this.deps.knownSessions?.().catch(() => [])) ?? [];
         const rows = new Map(summary.agents.map((a) => [a.session, a]));
-        for (const s of known) {
+        for (const s of [...known, ...this.teamList.flatMap((t) => t.members)]) {
             if (!rows.has(s))
-                rows.set(s, { session: s, runtimes: [], todayUsd: 0, windowUsd: 0, daily: summary.days.map(() => 0) });
+                rows.set(s, { session: s, runtimes: [], todayTokens: 0, windowTokens: 0, windowCachedTokens: 0, daily: summary.days.map(() => 0) });
         }
         const agents = [...rows.values()].map((a) => {
-            const cap = this.capOf(a.session);
+            const own = this.ownCapOf(a.session);
+            const b = this.boostForSession(a.session);
             const stop = this.computeStop(a.session);
             return {
-                ...a,
+                session: a.session,
                 name: this.nameOf(a.session),
-                capUsd: cap.capUsd,
-                capSource: cap.source,
+                ...(this.teamsOfSession.get(a.session)?.[0] ? { teamId: this.teamsOfSession.get(a.session)?.[0] } : {}),
+                runtimes: a.runtimes,
+                todayTokens: a.todayTokens,
+                windowTokens: a.windowTokens,
+                daily: a.daily,
+                baseCapTokens: own.capTokens,
+                capTokens: own.capTokens === null || b.unlimited ? null : own.capTokens + b.extra,
+                capSource: own.source,
+                boosted: b.unlimited || b.extra > 0,
+                unlimited: b.unlimited,
                 stopped: !!stop,
                 ...(stop ? { stopReason: spendCapReason(stop, this.nameOf(a.session)) } : {}),
             };
         });
-        const total = this.capOf(C.TOTAL_TARGET).capUsd;
+        const teams = this.teamList.map((t) => {
+            const base = this.file.config.teamCapsTokens[t.id];
+            const b = this.boostForTeam(t.id);
+            const cap = isCap(base) && !b.unlimited ? base + b.extra : null;
+            const used = this.deps.ledger.groupToday(t.members);
+            return {
+                teamId: t.id,
+                name: t.name,
+                members: t.members,
+                todayTokens: used,
+                baseCapTokens: isCap(base) ? base : null,
+                capTokens: cap,
+                extraTokens: b.extra,
+                unlimited: b.unlimited,
+                boosts: this.activeBoostsRaw().filter((x) => x.target === teamTarget(t.id)),
+                stopped: cap !== null && used >= cap,
+            };
+        });
+        const totalBoost = this.boostFor((t) => t === C.TOTAL_TARGET);
+        const total = isCap(this.file.config.totalCapTokens) && !totalBoost.unlimited ? this.file.config.totalCapTokens + totalBoost.extra : null;
+        const { agents: _omit, ...rest } = summary;
+        void _omit;
         return {
-            ...summary,
+            ...rest,
             agents,
+            teams,
             caps: this.getConfig(),
-            raisedToday: { ...this.file.day.raised },
-            totalCapTodayUsd: total,
-            suggestedAgentCapUsd: summary.p90AgentDayUsd > 0 ? Math.max(1, Math.ceil(summary.p90AgentDayUsd)) : null,
+            boosts: this.activeBoosts(),
+            totalCapTodayTokens: total,
+            suggestedAgentCapTokens: summary.p90AgentDayTokens > 0 ? roundUpMillions(summary.p90AgentDayTokens) : null,
             totalStopped: total !== null && this.deps.ledger.totalToday() >= total,
         };
     }
     // ---------------------------------------------------------------- enforcement
     /**
-     * One enforcement pass: day roll, 80% notices, stop announcements (one
-     * card per stop), and releasing agents whose stop lifted. Passes run
-     * one at a time; a call during a pass gets another pass after it.
+     * One enforcement pass: day roll, boost expiry, 80% notices, stop
+     * announcements (one card per stop), and releasing agents whose stop
+     * lifted. Passes run one at a time; a call during a pass gets another
+     * pass after it.
      */
     evaluate() {
-        // Coalesce: a pass not yet started is shared; a call during a running
-        // pass gets a fresh pass after it (so it sees the latest change).
         if (this.queuedPass)
             return this.queuedPass;
         const pass = this.chain.then(async () => {
@@ -284,7 +450,7 @@ export class SpendCapService {
                 await this.evaluateOnce();
             }
             catch (err) {
-                this.logger?.warn('Spend cap evaluation failed', { error: err instanceof Error ? err.message : String(err) });
+                this.logger?.warn('Token cap evaluation failed', { error: err instanceof Error ? err.message : String(err) });
             }
         });
         this.queuedPass = pass;
@@ -307,100 +473,135 @@ export class SpendCapService {
                 await this.reply(d.id, 'This card is from an earlier day; the cap has already reset at midnight.');
             return null;
         }
-        const name = this.nameOf(target);
+        const who = this.describeTarget(target);
         if (d.status !== 'resolved')
             return null;
         const label = d.options.find((o) => o.key === d.chosenKey)?.label;
-        const amount = raiseAmountOf(label);
-        if (amount === null) {
-            await this.reply(d.id, `OK, ${name} stays stopped until midnight. Its messages stay queued.`);
+        const boost = boostOfLabel(label);
+        if (boost === null) {
+            await this.reply(d.id, `OK, ${who} stays stopped until midnight. Messages stay queued.`);
             return null;
         }
         try {
-            const cap = await this.raiseToday(target, amount);
-            await this.reply(d.id, `Raised ${name}'s cap to ${formatUsd(cap)} for today. Queued messages are being delivered.`);
+            const scope = target === C.TOTAL_TARGET ? 'all' : target.startsWith(C.TEAM_TARGET_PREFIX) ? 'team' : 'agent';
+            const id = scope === 'team' ? target.slice(C.TEAM_TARGET_PREFIX.length) : scope === 'agent' ? target : undefined;
+            await this.boost(boost === 'unlimited' ? { scope, id, unlimited: true, by: 'card' } : { scope, id, extraTokens: boost, by: 'card' });
+            const what = boost === 'unlimited' ? 'no cap' : `+${formatTokens(boost)}`;
+            await this.reply(d.id, `Done: ${what} for ${who} until midnight. Queued messages are being delivered.`);
         }
         catch (err) {
-            await this.reply(d.id, `Could not raise the cap: ${err instanceof Error ? err.message : String(err)}`);
+            await this.reply(d.id, `Could not boost: ${err instanceof Error ? err.message : String(err)}`);
         }
         return null;
     }
     // ---------------------------------------------------------------- internals
     async evaluateOnce() {
         this.rollDay();
+        const hadBoosts = this.file.boosts.length;
+        this.pruneBoosts();
+        if (hadBoosts !== this.file.boosts.length)
+            this.persist();
         if (!this.anyCap() && this.lastStopped.size === 0)
             return;
+        await this.refreshTeams();
         this.deps.ledger.invalidate();
         const summary = this.deps.ledger.summarize(1);
         const known = (await this.deps.knownSessions?.().catch(() => [])) ?? [];
-        const sessions = new Set([...known, ...summary.agents.map((a) => a.session), ...Object.keys(this.file.day.raised).filter((t) => t !== C.TOTAL_TARGET)]);
-        if (this.lastStopped.size > 0)
-            for (const s of this.lastStopped)
-                sessions.add(s);
-        const stoppedNow = new Set();
+        const sessions = new Set([...known, ...summary.agents.map((a) => a.session), ...this.teamList.flatMap((t) => t.members)]);
+        for (const s of this.lastStopped)
+            sessions.add(s);
         // The all-agents total first: its notice names the whole crew once.
-        const total = this.capOf(C.TOTAL_TARGET).capUsd;
-        if (total !== null) {
-            const spent = this.deps.ledger.totalToday();
-            await this.checkThresholds(C.TOTAL_TARGET, total, spent);
+        const totalCap = this.capForTarget(C.TOTAL_TARGET);
+        if (totalCap !== null)
+            await this.checkThresholds(C.TOTAL_TARGET, totalCap, this.deps.ledger.totalToday());
+        for (const t of this.teamList) {
+            const cap = this.capForTarget(teamTarget(t.id));
+            if (cap !== null)
+                await this.checkThresholds(teamTarget(t.id), cap, this.deps.ledger.groupToday(t.members));
         }
+        const stoppedNow = new Set();
         for (const session of sessions) {
-            const cap = this.capOf(session).capUsd;
+            const cap = this.capForTarget(session);
             if (cap !== null)
-                await this.checkThresholds(session, cap, this.deps.ledger.spentToday(session));
+                await this.checkThresholds(session, cap, this.deps.ledger.usedToday(session));
             if (this.computeStop(session))
                 stoppedNow.add(session);
         }
         const released = [...this.lastStopped].filter((s) => !stoppedNow.has(s));
         this.lastStopped = stoppedNow;
         if (released.length > 0) {
-            this.logger?.info('Spend cap stop lifted — releasing queued messages', { sessions: released });
+            this.logger?.info('Token cap stop lifted — releasing queued messages', { sessions: released });
             await this.deps.onReleased?.(released).catch((err) => this.logger?.warn('Releasing queued messages failed', { sessions: released, error: err instanceof Error ? err.message : String(err) }));
         }
     }
-    async checkThresholds(target, cap, spent) {
+    /**
+     * The cap in force for a cap target, with the boosts that cover the
+     * target itself (for notices and cards).
+     */
+    capForTarget(target) {
+        const cfg = this.file.config;
+        if (target === C.TOTAL_TARGET) {
+            const b = this.boostFor((t) => t === C.TOTAL_TARGET);
+            return isCap(cfg.totalCapTokens) && !b.unlimited ? cfg.totalCapTokens + b.extra : null;
+        }
+        if (target.startsWith(C.TEAM_TARGET_PREFIX)) {
+            const id = target.slice(C.TEAM_TARGET_PREFIX.length);
+            const base = cfg.teamCapsTokens[id];
+            const b = this.boostForTeam(id);
+            return isCap(base) && !b.unlimited ? base + b.extra : null;
+        }
+        const own = this.ownCapOf(target).capTokens;
+        const b = this.boostForSession(target);
+        return own !== null && !b.unlimited ? own + b.extra : null;
+    }
+    async checkThresholds(target, cap, used) {
         const key = `${target}@${cap}`;
         const day = this.file.day;
-        const name = this.nameOf(target);
-        if (spent >= cap) {
+        const who = this.describeTarget(target);
+        if (used >= cap) {
             if (day.stopped.includes(key))
                 return;
             day.stopped.push(key);
             if (!day.warned.includes(key))
                 day.warned.push(key);
             this.persist();
-            this.logger?.warn('Daily spend cap reached — hard stop (no new turns until midnight)', { target, capUsd: cap, spentUsd: cents(spent) });
-            await this.announceStop(target, name, cap, spent);
+            this.logger?.warn('Daily token cap reached — hard stop (no new turns until midnight)', { target, capTokens: cap, usedTokens: used });
+            await this.announceStop(target, who, cap, used);
             return;
         }
-        if (spent >= cap * C.WARN_FRACTION && !day.warned.includes(key)) {
+        if (used >= cap * C.WARN_FRACTION && !day.warned.includes(key)) {
             day.warned.push(key);
             this.persist();
-            const pct = Math.floor((spent / cap) * 100);
-            const who = target === C.TOTAL_TARGET ? 'All agents together have' : `${name} has`;
-            const its = target === C.TOTAL_TARGET ? 'the' : 'its';
-            const stops = target === C.TOTAL_TARGET ? 'every agent stops' : 'it stops';
-            await this.notify(`Heads-up: ${who} spent ${formatUsd(spent)} of ${its} ${formatUsd(cap)} daily spend cap today (${pct}%). At ${formatUsd(cap)} ${stops} taking new turns until midnight.`);
+            const pct = Math.floor((used / cap) * 100);
+            const subject = target === C.TOTAL_TARGET ? 'All agents together have' : target.startsWith(C.TEAM_TARGET_PREFIX) ? `Team ${who.replace(/^team /, '')} has` : `${who} has`;
+            const stops = target === C.TOTAL_TARGET ? 'every agent stops' : target.startsWith(C.TEAM_TARGET_PREFIX) ? 'its members stop' : 'it stops';
+            await this.notify(`Heads-up: ${subject} used ${formatTokens(used)} of the ${formatTokens(cap)} daily token cap today (${pct}%). At ${compactTokens(cap)} ${stops} taking new turns until midnight.`);
         }
     }
-    async announceStop(target, name, cap, spent) {
-        const raise = suggestedRaise(cap, spent);
-        const who = target === C.TOTAL_TARGET ? 'total' : target === ORCHESTRATOR_SESSION_NAME ? 'orc' : name;
+    async announceStop(target, who, cap, used) {
+        const extra = suggestedBoost(cap);
+        const dmWho = target === C.TOTAL_TARGET ? 'everyone' : target === ORCHESTRATOR_SESSION_NAME ? 'orc' : who.replace(/^team /, '');
         const headline = target === C.TOTAL_TARGET
-            ? `All agents together hit the daily total spend cap (${formatUsd(cap)}); every agent is stopped until midnight.`
-            : `${name} hit its daily spend cap (${formatUsd(cap)}) and is stopped until midnight.`;
+            ? `All agents together hit the daily token cap (${formatTokens(cap)}); every agent is stopped until midnight.`
+            : target.startsWith(C.TEAM_TARGET_PREFIX)
+                ? `Team ${who.replace(/^team /, '')} hit its daily token cap (${formatTokens(cap)}); its members are stopped until midnight.`
+                : `${who} hit its daily token cap (${formatTokens(cap)}) and is stopped until midnight.`;
         const decisions = this.deps.decisions?.() ?? null;
         if (decisions) {
             try {
                 const d = await decisions.askSystem({
                     kind: C.DECISION_KIND,
                     system: { key: target, defaultIsDecline: true },
-                    title: 'Daily spend cap reached',
-                    question: `${headline} Raise it for today?`,
+                    title: 'Daily token cap reached',
+                    question: `${headline} Boost it for today?`,
                     body: [
-                        `Spent today: ${formatUsd(spent)}. The current turn was allowed to finish; no new turns start. Messages are kept and delivered when it runs again.`,
+                        `Used today: ${formatTokens(used)}. The current turn was allowed to finish; no new turns start. Messages are kept and delivered when it runs again.`,
+                    ],
+                    options: [
+                        `Boost +${compactTokens(extra)} tokens today — runs again until midnight`,
+                        `${C.OPTIONS.UNLIMITED} — no cap until midnight`,
+                        `${C.OPTIONS.KEEP} — resets at midnight`,
                     ],
-                    options: [`Raise to $${raise} today — runs again until midnight`, `${C.OPTIONS.KEEP} — resets at midnight`],
                     default: C.OPTIONS.KEEP,
                     deadline: this.nextMidnight(),
                     sensitive: 'spend',
@@ -410,50 +611,106 @@ export class SpendCapService {
                 return;
             }
             catch (err) {
-                this.logger?.warn('Could not post the spend cap card — sending a notice instead', { target, error: err instanceof Error ? err.message : String(err) });
+                this.logger?.warn('Could not post the token cap card — sending a notice instead', { target, error: err instanceof Error ? err.message : String(err) });
             }
         }
-        await this.notify(`${headline} Its messages are queued. Reply \`raise cap for ${who} to $${raise} today\` to raise it.`);
+        await this.notify(`${headline} Messages are queued. Reply \`boost ${dmWho} by ${compactTokens(extra)} today\` or \`unlimited today for ${dmWho}\`.`);
     }
     anyCap() {
         const cfg = this.file.config;
-        return (isCap(cfg.defaultAgentCapUsd) ||
-            isCap(cfg.totalCapUsd) ||
-            Object.values(cfg.agentCapsUsd).some(isCap) ||
-            Object.values(this.file.day.raised).some(isCap));
+        return (isCap(cfg.defaultAgentCapTokens) ||
+            isCap(cfg.totalCapTokens) ||
+            Object.values(cfg.agentCapsTokens).some(isCap) ||
+            Object.values(cfg.teamCapsTokens).some(isCap));
     }
     computeStop(session) {
-        const own = this.capOf(session).capUsd;
+        const b = this.boostForSession(session);
+        if (b.unlimited)
+            return null;
+        const cfg = this.file.config;
+        const own = this.ownCapOf(session).capTokens;
         if (own !== null) {
-            const spent = this.deps.ledger.spentToday(session);
-            if (spent >= own)
-                return { session, scope: 'agent', capUsd: own, spentUsd: spent };
+            const used = this.deps.ledger.usedToday(session);
+            if (used >= own + b.extra)
+                return { session, scope: 'agent', capTokens: own + b.extra, usedTokens: used };
+        }
+        for (const teamId of this.teamsOfSession.get(session) ?? []) {
+            const base = cfg.teamCapsTokens[teamId];
+            if (!isCap(base))
+                continue;
+            const team = this.teamList.find((t) => t.id === teamId);
+            const used = this.deps.ledger.groupToday(team?.members ?? [session]);
+            if (used >= base + b.extra)
+                return { session, scope: 'team', capTokens: base + b.extra, usedTokens: used, teamId, teamName: team?.name ?? teamId };
         }
-        const total = this.capOf(C.TOTAL_TARGET).capUsd;
-        if (total !== null) {
-            const spent = this.deps.ledger.totalToday();
-            if (spent >= total)
-                return { session, scope: 'total', capUsd: total, spentUsd: spent };
+        if (isCap(cfg.totalCapTokens)) {
+            const used = this.deps.ledger.totalToday();
+            if (used >= cfg.totalCapTokens + b.extra)
+                return { session, scope: 'total', capTokens: cfg.totalCapTokens + b.extra, usedTokens: used };
         }
         return null;
     }
     stopKey(stop) {
-        return `${stop.scope === 'total' ? C.TOTAL_TARGET : stop.session}@${stop.capUsd}`;
+        const target = stop.scope === 'total' ? C.TOTAL_TARGET : stop.scope === 'team' ? teamTarget(stop.teamId ?? '') : stop.session;
+        return `${target}@${stop.capTokens}`;
     }
     scheduleEvaluate() {
         void this.evaluate();
     }
+    activeBoostsRaw() {
+        const now = this.now().getTime();
+        return this.file.boosts.filter((b) => new Date(b.until).getTime() > now);
+    }
+    pruneBoosts() {
+        const live = this.activeBoostsRaw();
+        if (live.length !== this.file.boosts.length) {
+            const ended = this.file.boosts.filter((b) => !live.includes(b));
+            this.file.boosts = live;
+            this.logger?.info('Usage boosts ended', { boosts: ended.map((b) => ({ target: b.target, until: b.until })) });
+        }
+    }
+    async resolveBoostTarget(scope, id) {
+        if (scope === 'all')
+            return C.TOTAL_TARGET;
+        const raw = typeof id === 'string' ? id.trim() : '';
+        if (scope === 'team') {
+            if (!raw)
+                throw new SpendCapError(400, 'id is required for a team boost (team id or name)');
+            await this.refreshTeams();
+            const w = raw.toLowerCase();
+            const hit = this.teamList.find((t) => t.id === raw) ?? this.teamList.filter((t) => t.name.toLowerCase() === w).at(0);
+            if (!hit)
+                throw new SpendCapError(404, `No team called "${raw}"`);
+            return teamTarget(hit.id);
+        }
+        if (scope === 'agent') {
+            if (!raw)
+                throw new SpendCapError(400, 'id is required for an agent boost (session or name)');
+            await this.refreshTeams();
+            const known = new Set([...((await this.deps.knownSessions?.().catch(() => [])) ?? []), ...this.teamList.flatMap((t) => t.members)]);
+            if (known.has(raw))
+                return raw;
+            const byName = [...known].filter((s) => this.nameOf(s).toLowerCase() === raw.toLowerCase());
+            if (byName.length === 1)
+                return byName[0];
+            if (byName.length > 1)
+                throw new SpendCapError(400, `More than one agent is called "${raw}"; use its session name`);
+            return raw;
+        }
+        throw new SpendCapError(400, 'scope must be team, agent or all');
+    }
     /** Reset today's bookkeeping when the local day changed. */
     rollDay() {
         const today = localDateKey(this.now());
         if (this.file.day.date === today)
             return;
-        const had = Object.keys(this.file.day.raised).length + this.file.day.stopped.length;
+        const had = this.file.day.stopped.length;
         this.file.day = emptyDay(today);
+        this.pruneBoosts();
         this.deps.ledger.invalidate();
         this.persist();
         if (had > 0)
-            this.logger?.info('Spend caps reset for the new day', { date: today });
+            this.logger?.info('Token caps reset for the new day', { date: today });
     }
     nextMidnight() {
         const next = localMidnight(this.now());
@@ -476,7 +733,7 @@ export class SpendCapService {
             await this.deps.notifyOwner(text);
         }
         catch (err) {
-            this.logger?.warn('Could not send the spend cap notice', { error: err instanceof Error ? err.message : String(err) });
+            this.logger?.warn('Could not send the token cap notice', { error: err instanceof Error ? err.message : String(err) });
         }
     }
     async reply(decisionId, text) {
@@ -487,7 +744,7 @@ export class SpendCapService {
             this.deps.store.write(this.file);
         }
         catch (err) {
-            this.logger?.warn('Could not save spend caps', { error: err instanceof Error ? err.message : String(err) });
+            this.logger?.warn('Could not save token caps', { error: err instanceof Error ? err.message : String(err) });
         }
     }
 }