@wardby/cli 0.2.1 → 0.4.0

package/dist/core/attribution.js

@@ -0,0 +1,208 @@
+import { ISSUE_KEY, ISSUE_TRACKER_PROVIDERS, projectOf, } from "../providers/issue-tracker/types.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "attribution" });
+/** A WorkItem snapshotted this recently is reused as-is, without calling the tracker. */
+export const SNAPSHOT_CACHE_MS = 10 * 60 * 1000;
+export const SNAPSHOT_TIMEOUT_MS = 3000;
+/**
+ * Snapshot budget for a caller that is answering a request (a webhook, an
+ * MCP tool call, a host event): a short timeout and no 429 retry, so a slow
+ * or rate-limited tracker degrades to key-only attribution instead of
+ * stalling the response.
+ */
+export const RESPONSE_PATH_SNAPSHOT_BUDGET = { timeoutMs: 2000, retryOn429: false };
+/**
+ * The work item a new attribution points at, snapshotted from the tracker
+ * unless a fresh snapshot is already stored. Never throws: a failed lookup or
+ * snapshot attributes by key only.
+ */
+export async function resolveWorkItem(db, trackers, provider, key, opts = {}) {
+    const now = opts.now ?? new Date();
+    const keyOnly = (scopeKey = projectOf(key)) => ({ provider, key, scopeKey, snapshot: null });
+    let existing;
+    try {
+        existing = await db.workItem.findUnique({
+            where: { provider_key: { provider, key } },
+            select: { refreshedAt: true, scopeKey: true },
+        });
+    }
+    catch (err) {
+        log.warn({ err, provider, key }, "work item lookup failed; attributing by key only");
+        return keyOnly();
+    }
+    if (existing?.refreshedAt && now.getTime() - existing.refreshedAt.getTime() < SNAPSHOT_CACHE_MS) {
+        return keyOnly(existing.scopeKey);
+    }
+    const tracker = trackers?.[provider];
+    if (!tracker)
+        return keyOnly(existing?.scopeKey);
+    try {
+        const snapshot = await tracker.snapshotIssue(key, {
+            timeoutMs: opts.timeoutMs ?? SNAPSHOT_TIMEOUT_MS,
+            retryOn429: opts.retryOn429,
+        });
+        return { provider, key, scopeKey: snapshot.scopeKey, snapshot };
+    }
+    catch (err) {
+        log.warn({ err, provider, key }, "issue snapshot failed; attributing by key only");
+        return keyOnly(existing?.scopeKey);
+    }
+}
+/** Upserts the item (and its parent) and returns the item's id and the parent to freeze. A key-only result never clobbers stored fields. */
+async function upsertWorkItem(tx, item, now) {
+    const s = item.snapshot;
+    if (s?.parent) {
+        // The parent's own type/scope/title are refreshed when it is snapshotted itself; here only make sure it exists
+        // and take a title we were handed for free.
+        await tx.workItem.upsert({
+            where: { provider_key: { provider: item.provider, key: s.parent.key } },
+            create: {
+                provider: item.provider,
+                key: s.parent.key,
+                scopeKey: projectOf(s.parent.key),
+                ...(s.parent.title ? { title: s.parent.title } : {}),
+            },
+            update: s.parent.title ? { title: s.parent.title } : {},
+        });
+    }
+    const snapshotFields = s
+        ? {
+            title: s.title ?? null,
+            type: s.type ?? null,
+            url: s.url,
+            scopeKey: s.scopeKey,
+            parentKey: s.parent?.key ?? null,
+            parentKind: s.parent?.kind ?? null,
+            refreshedAt: now,
+        }
+        : {};
+    const row = await tx.workItem.upsert({
+        where: { provider_key: { provider: item.provider, key: item.key } },
+        create: { provider: item.provider, key: item.key, scopeKey: item.scopeKey, ...snapshotFields },
+        update: snapshotFields,
+        select: { id: true, parentKey: true },
+    });
+    return row;
+}
+/**
+ * Covers runs created before attribution existed (no backfill): a continued
+ * coding run that already carries CodingRun.issueKey, else a direct parent
+ * with a RunIssueStatus. Grandchildren then inherit the child's new
+ * RunAttribution, so only the direct parent is checked.
+ */
+async function legacyIssue(tx, from) {
+    if (from.continuesCodingRunId) {
+        const prior = await tx.codingRun.findUnique({
+            where: { runId: from.continuesCodingRunId },
+            select: { issueProvider: true, issueKey: true },
+        });
+        if (prior?.issueProvider && prior.issueKey)
+            return { provider: prior.issueProvider, key: prior.issueKey };
+    }
+    if (from.parentRunId) {
+        const status = await tx.runIssueStatus.findUnique({
+            where: { runId: from.parentRunId },
+            select: { provider: true, issueKey: true },
+        });
+        if (status)
+            return { provider: status.provider, key: status.issueKey };
+    }
+    return null;
+}
+/**
+ * Writes the run's attribution inside dispatch's persist transaction.
+ * Precedence: the parent run's attribution, then the continued coding run's,
+ * then a pre-attribution issue (legacyIssue), then the caller's intent. Returns the item's provider/key (for
+ * CodingRun.issueProvider/issueKey), or null when the run is unattributed.
+ */
+export async function attributeRun(tx, runId, from, now = new Date()) {
+    for (const ancestorId of [from.parentRunId, from.continuesCodingRunId]) {
+        if (!ancestorId)
+            continue;
+        const inherited = await tx.runAttribution.findUnique({
+            where: { runId: ancestorId },
+            select: { workItemId: true, parentKeyAtRun: true, workItem: { select: { provider: true, key: true } } },
+        });
+        if (!inherited)
+            continue;
+        await tx.runAttribution.create({
+            data: { runId, workItemId: inherited.workItemId, parentKeyAtRun: inherited.parentKeyAtRun, source: "inherited" },
+        });
+        return { provider: inherited.workItem.provider, key: inherited.workItem.key };
+    }
+    const legacy = await legacyIssue(tx, from);
+    if (legacy) {
+        const item = { ...legacy, scopeKey: projectOf(legacy.key), snapshot: null };
+        const { id, parentKey } = await upsertWorkItem(tx, item, now);
+        await tx.runAttribution.create({ data: { runId, workItemId: id, parentKeyAtRun: parentKey, source: "inherited" } });
+        return legacy;
+    }
+    if (!from.intent)
+        return null;
+    const { id, parentKey } = await upsertWorkItem(tx, from.intent.item, now);
+    await tx.runAttribution.create({
+        data: { runId, workItemId: id, parentKeyAtRun: parentKey, source: from.intent.source },
+    });
+    return { provider: from.intent.item.provider, key: from.intent.item.key };
+}
+/** The issue a pull request was opened for (phase-3 IssuePullRequest); the earliest link when several exist. */
+export async function linkedPullRequestIssue(db, pr) {
+    try {
+        const row = await db.issuePullRequest.findFirst({
+            where: { codeProvider: pr.codeProvider, repository: pr.repository, number: pr.number },
+            orderBy: { createdAt: "asc" },
+            select: { issueProvider: true, issueKey: true },
+        });
+        return row ? { provider: row.issueProvider, key: row.issueKey } : null;
+    }
+    catch (err) {
+        log.warn({ err, ...pr }, "linked issue lookup failed; the run is unattributed");
+        return null;
+    }
+}
+/** Attribution for a run on a pull request that was opened for an issue; undefined when it has none. */
+export async function linkedPullRequestAttribution(db, trackers, pr, opts) {
+    const issue = await linkedPullRequestIssue(db, pr);
+    if (!issue)
+        return undefined;
+    return { source: "linked_pr", item: await resolveWorkItem(db, trackers, issue.provider, issue.key, opts) };
+}
+/** A refusal whose message is safe to return to the caller. */
+export class AttributionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AttributionError";
+    }
+}
+/**
+ * An issue a caller names on trigger_agent or a webhook. It decides whose
+ * cost this run counts toward, so it must be well formed and in a project the
+ * agent is linked to (AgentIssueProject) — otherwise the dispatch is refused.
+ * Issue keys are uppercase, so a key that differs only by case or surrounding
+ * spaces ("pay-241") is corrected rather than refused. `field` is the caller's
+ * name for the value (trigger_agent: issue; webhooks: wardbyIssue), so
+ * refusals name the field the caller actually sent.
+ */
+export async function validateExplicitIssue(db, agentId, issue, field = "issue") {
+    const candidate = issue && typeof issue === "object" ? issue : {};
+    const provider = candidate.provider;
+    const key = typeof candidate.key === "string" ? candidate.key.trim().toUpperCase() : candidate.key;
+    if (typeof provider !== "string" || !ISSUE_TRACKER_PROVIDERS.includes(provider)) {
+        throw new AttributionError(`${field}.provider must be one of: ${ISSUE_TRACKER_PROVIDERS.join(", ")}.`);
+    }
+    if (typeof key !== "string" || !ISSUE_KEY.test(key)) {
+        throw new AttributionError(`${field}.key must be an issue key such as PROJ-123.`);
+    }
+    const link = await db.agentIssueProject.findUnique({
+        where: { agentId_provider_projectKey: { agentId, provider, projectKey: projectOf(key) } },
+        select: { agentId: true },
+    });
+    if (!link)
+        throw new AttributionError(`This agent is not linked to ${provider} project ${projectOf(key)}.`);
+    return { provider: provider, key };
+}
+export async function explicitAttribution(db, trackers, agentId, issue, opts) {
+    const { field, ...budget } = opts ?? {};
+    const { provider, key } = await validateExplicitIssue(db, agentId, issue, field);
+    return { source: "explicit", item: await resolveWorkItem(db, trackers, provider, key, budget) };
+}

package/dist/core/budget-groups.d.ts

@@ -10,7 +10,28 @@
  * enforces that tightened ceiling with no changes of its own: a group
  * whose period budget is already exhausted simply produces an effective
  * budget of 0, which the engine's turn-1 gate already refuses exactly
- * like any other zero/negative budget.
+ * like any other zero/negative budget. A coding run gets the same effective
+ * budget at dispatch (dispatch.ts), where it becomes the run's reservation.
+ *
+ * Spend is the real cost of the period's runs plus the unspent part of every
+ * live run still in flight (pending or running): its hold, minus what it has
+ * spent so far, never below zero. A coding run's hold is its
+ * CodingRun.budgetReservedUsd; a native run's is its agent's current
+ * per-run budgetUsd, an upper bound on the effective budget it pinned at load.
+ * Counting holds is what stops concurrent runs from each claiming the
+ * same remainder (security review E-04).
+ *
+ * Only live runs hold anything (see isHoldLive): a run that stopped
+ * heartbeating (a crashed process, a Ctrl-C'd `wardby run`) or a coding run
+ * past its queue + run timeout releases its hold even while its row still
+ * says pending/running, so a zombie row cannot pin a group for a whole period.
+ *
+ * A native run asks for its budget at load, after its row already exists, and
+ * counts only the holds of runs that started before it (startedAt, then id):
+ * first come, first served. Two members dispatched on the same tick never
+ * both see the other's hold and starve each other; the earlier one gets the
+ * remainder and the later one gets what the earlier one leaves. A coding
+ * dispatch has no row yet, so it counts every live hold.
  */
 import type { Agent, BudgetGroup, PrismaClient } from "#prisma";
 export type Period = "day" | "week" | "month";
@@ -24,9 +45,75 @@ export declare function periodStart(period: Period, now: Date): Date;
 export interface PeriodSpend {
     period: Period;
     capUsd: number;
+    /** Real cost recorded by the period's runs, finished or not. */
     spentUsd: number;
+    /** Unspent reservations of the period's in-flight (pending/running) runs. */
+    reservedUsd: number;
+    /** capUsd - spentUsd - reservedUsd, never below zero. */
     remainingUsd: number;
 }
+/** A group member as computeGroupSpend needs it: a native run in flight holds its agent's budgetUsd. */
+export interface GroupMember {
+    id: string;
+    budgetUsd: unknown;
+}
+/** A run's position in first-come-first-served order: startedAt, then id. */
+export interface RunOrder {
+    id: string;
+    startedAt: Date;
+}
+export interface SpendOptions {
+    /**
+     * Runs whose unspent hold is left out (their real cost still counts): the
+     * run asking for its own budget, and the run tree a sub-agent spends from,
+     * whose hold already covers it.
+     */
+    excludeReservationRunIds?: readonly string[];
+    /**
+     * Runs left out of the group's spend entirely, real cost and hold alike:
+     * the run tree when computing the tree's own ceiling, whose spend is
+     * subtracted from that ceiling separately and must count only once.
+     */
+    excludeRunIds?: readonly string[];
+    /**
+     * First come, first served: count only the holds of runs ordered strictly
+     * before this one. Unset (a coding dispatch, whose row does not exist yet)
+     * counts every live hold.
+     */
+    holdsBefore?: RunOrder;
+    /** CODING_QUEUE_TIMEOUT_SEC; read from the environment when omitted. */
+    codingQueueTimeoutSec?: number;
+}
+/**
+ * How long a run's last heartbeat keeps its hold alive: the reconciler's
+ * heartbeat timeout plus one reconcile interval, so a managed run is reaped
+ * (or re-claimed, which refreshes heartbeatAt) before its hold lapses.
+ * Managed native runs beat every HEARTBEAT_INTERVAL_MS (InProcessExecutor,
+ * DbosExecutor), as do `wardby run` and native sub-agent children
+ * (withRunHeartbeat); a coding run beats while its job is polled.
+ */
+export declare const HOLD_HEARTBEAT_TTL_MS: number;
+/** Slack past a coding run's queue + run timeout before its hold lapses (matches the sub-agent wait grace). */
+export declare const CODING_HOLD_GRACE_SEC = 60;
+/** Smallest amount worth holding or reserving: CodingRun.budgetReservedUsd has 6 decimal places. */
+export declare const MIN_RESERVATION_USD = 0.000001;
+interface HoldRow {
+    id: string;
+    status: string;
+    startedAt: Date;
+    heartbeatAt: Date | null;
+    codingRun: {
+        timeoutSec: number;
+    } | null;
+}
+/**
+ * Whether an in-flight row still holds budget. A run holds while its last
+ * sign of life (heartbeatAt, or startedAt before its first beat) is within
+ * HOLD_HEARTBEAT_TTL_MS. A coding run also holds, beat or not, until its
+ * queue timeout + run timeout + grace have passed since dispatch: a queued
+ * coding run does not beat, and nothing can legitimately spend past that.
+ */
+export declare function isHoldLive(run: HoldRow, now: Date, codingQueueTimeoutSec: number): boolean;
 /**
  * Live per-period spend for whichever of a group's daily/weekly/monthly
  * caps are actually set -- unset periods are omitted from the result, not
@@ -34,7 +121,7 @@ export interface PeriodSpend {
  * (month contains week contains day), bucketed in JS, rather than a
  * separate DB round trip per period.
  */
-export declare function computeGroupSpend(db: BudgetGroupsDb, group: Pick<BudgetGroup, "dailyBudgetUsd" | "weeklyBudgetUsd" | "monthlyBudgetUsd">, memberAgentIds: string[], now?: Date): Promise<PeriodSpend[]>;
+export declare function computeGroupSpend(db: BudgetGroupsDb, group: Pick<BudgetGroup, "dailyBudgetUsd" | "weeklyBudgetUsd" | "monthlyBudgetUsd">, members: readonly GroupMember[], now?: Date, options?: SpendOptions): Promise<PeriodSpend[]>;
 export interface RunTreeSpend {
     rootRunId: string;
     capUsd: number;
@@ -44,18 +131,34 @@ export interface RunTreeSpend {
 /**
  * Real-time shared budget scope for a sub-agent dispatch: the whole run tree
  * rooted at `parentRunId`'s ultimate ancestor shares one ceiling —
- * the root's own effective budget (its own budgetUsd, itself tightened by
- * its own BudgetGroup if any) minus everything every run in the tree has
- * spent so far. The root's ceiling is recomputed fresh here, not pinned
- * from whatever it was when the root run started — consistent with
- * BudgetGroup periods already always being live-recomputed rather than
- * snapshotted.
+ * the root's own budgetUsd, itself tightened by the root agent's BudgetGroup
+ * if any — minus everything every run in the tree has spent so far. The
+ * ceiling is recomputed fresh here, not pinned from whatever it was when the
+ * root run started — consistent with BudgetGroup periods already always
+ * being live-recomputed rather than snapshotted. Its group check leaves the
+ * tree's runs out entirely, cost and hold alike: the tree's spend is
+ * subtracted once, below, so counting it in the group too would charge it
+ * twice, and the tree spends inside the root's hold, so counting that hold
+ * would leave the tree nothing. It also leaves out holds of runs that started
+ * after the root (they already counted the root's hold). capUsd is therefore
+ * the tree's whole ceiling, and remainingUsd = capUsd - spentUsd.
  */
 export declare function computeRunTreeSpend(db: BudgetGroupsDb, parentRunId: string, now?: Date): Promise<RunTreeSpend>;
+export type BudgetConstraint = Period | "run-tree";
 export interface EffectiveBudgetResult {
     effectiveBudgetUsd: number;
     /** Which constraint(s), if any, are tighter than the agent's own budgetUsd right now. */
-    constrainedBy: (Period | "run-tree")[];
+    constrainedBy: BudgetConstraint[];
+    /** The first constraint with nothing left (< MIN_RESERVATION_USD), set only when there is one. */
+    exhaustedBy?: BudgetConstraint;
+}
+export interface EffectiveBudgetOptions {
+    /**
+     * The run this budget is for, when its row already exists (a native run's
+     * load step): its own hold is not counted against itself, and neither are
+     * the holds of runs that started after it (first come, first served).
+     */
+    self?: RunOrder;
 }
 /**
  * The per-run budget ceiling to actually use for `agent`: its own
@@ -68,5 +171,12 @@ export interface EffectiveBudgetResult {
  * with no caps configured is returned unchanged. Also logs a warning
  * (never blocks, never throws) once a period's spend crosses the group's
  * own warnThresholdRatio.
+ *
+ * A sub-agent in the root's own budget group spends inside the root's hold,
+ * so its group check is the root's: the tree's holds and the holds of runs
+ * after the root are left out. A sub-agent in any other group is an
+ * ordinary member of that group and counts every earlier live hold there,
+ * the tree's included.
  */
-export declare function effectiveBudgetForRun(db: BudgetGroupsDb, agent: Pick<Agent, "id" | "budgetGroupId" | "budgetUsd">, now?: Date, parentRunId?: string): Promise<EffectiveBudgetResult>;
+export declare function effectiveBudgetForRun(db: BudgetGroupsDb, agent: Pick<Agent, "id" | "budgetGroupId" | "budgetUsd">, now?: Date, parentRunId?: string, options?: EffectiveBudgetOptions): Promise<EffectiveBudgetResult>;
+export {};

package/dist/core/budget-groups.js

@@ -1,4 +1,6 @@
+import { loadCodingConcurrencyConfig } from "../config/providers.js";
 import { logger } from "./logger.js";
+import { HEARTBEAT_TIMEOUT_MS, RECONCILE_INTERVAL_MS } from "./timing.js";
 const budgetGroupLog = logger.child({ module: "budget-groups" });
 /**
  * Calendar-aligned UTC period start. "week" is the ISO week: Monday 00:00
@@ -20,6 +22,44 @@ export function periodStart(period, now) {
 function toNullableNumber(value) {
     return value === null || value === undefined ? null : Number(value);
 }
+const IN_FLIGHT = new Set(["pending", "running"]);
+/**
+ * How long a run's last heartbeat keeps its hold alive: the reconciler's
+ * heartbeat timeout plus one reconcile interval, so a managed run is reaped
+ * (or re-claimed, which refreshes heartbeatAt) before its hold lapses.
+ * Managed native runs beat every HEARTBEAT_INTERVAL_MS (InProcessExecutor,
+ * DbosExecutor), as do `wardby run` and native sub-agent children
+ * (withRunHeartbeat); a coding run beats while its job is polled.
+ */
+export const HOLD_HEARTBEAT_TTL_MS = HEARTBEAT_TIMEOUT_MS + RECONCILE_INTERVAL_MS;
+/** Slack past a coding run's queue + run timeout before its hold lapses (matches the sub-agent wait grace). */
+export const CODING_HOLD_GRACE_SEC = 60;
+/** Smallest amount worth holding or reserving: CodingRun.budgetReservedUsd has 6 decimal places. */
+export const MIN_RESERVATION_USD = 0.000001;
+/**
+ * Whether an in-flight row still holds budget. A run holds while its last
+ * sign of life (heartbeatAt, or startedAt before its first beat) is within
+ * HOLD_HEARTBEAT_TTL_MS. A coding run also holds, beat or not, until its
+ * queue timeout + run timeout + grace have passed since dispatch: a queued
+ * coding run does not beat, and nothing can legitimately spend past that.
+ */
+export function isHoldLive(run, now, codingQueueTimeoutSec) {
+    if (!IN_FLIGHT.has(run.status))
+        return false;
+    const lastSign = (run.heartbeatAt ?? run.startedAt).getTime();
+    if (now.getTime() - lastSign <= HOLD_HEARTBEAT_TTL_MS)
+        return true;
+    if (run.codingRun) {
+        const deadlineMs = run.startedAt.getTime() + (codingQueueTimeoutSec + run.codingRun.timeoutSec + CODING_HOLD_GRACE_SEC) * 1000;
+        return now.getTime() <= deadlineMs;
+    }
+    return false;
+}
+function isOrderedBefore(run, other) {
+    const a = run.startedAt.getTime();
+    const b = other.startedAt.getTime();
+    return a < b || (a === b && run.id < other.id);
+}
 /**
  * Live per-period spend for whichever of a group's daily/weekly/monthly
  * caps are actually set -- unset periods are omitted from the result, not
@@ -27,7 +67,7 @@ function toNullableNumber(value) {
  * (month contains week contains day), bucketed in JS, rather than a
  * separate DB round trip per period.
  */
-export async function computeGroupSpend(db, group, memberAgentIds, now = new Date()) {
+export async function computeGroupSpend(db, group, members, now = new Date(), options = {}) {
     const caps = [
         { period: "day", capUsd: toNullableNumber(group.dailyBudgetUsd) },
         { period: "week", capUsd: toNullableNumber(group.weeklyBudgetUsd) },
@@ -42,28 +82,58 @@ export async function computeGroupSpend(db, group, memberAgentIds, now = new Dat
     // query itself as a cheap no-op; an empty `agentId: { in: [] }` would
     // match nothing anyway.
     const widestStart = periodStart("month", now);
-    const runs = memberAgentIds.length === 0
+    const memberBudgets = new Map(members.map((m) => [m.id, Number(m.budgetUsd)]));
+    const excluded = new Set(options.excludeReservationRunIds ?? []);
+    const dropped = new Set(options.excludeRunIds ?? []);
+    const queueTimeoutSec = options.codingQueueTimeoutSec ?? loadCodingConcurrencyConfig().queueTimeoutSec;
+    const runs = members.length === 0
         ? []
         : await db.run.findMany({
-            where: { agentId: { in: memberAgentIds }, startedAt: { gte: widestStart } },
-            select: { costUsd: true, startedAt: true },
+            where: { agentId: { in: [...memberBudgets.keys()] }, startedAt: { gte: widestStart } },
+            select: {
+                id: true,
+                agentId: true,
+                status: true,
+                costUsd: true,
+                startedAt: true,
+                heartbeatAt: true,
+                codingRun: { select: { budgetReservedUsd: true, timeoutSec: true } },
+            },
         });
+    const counted = runs.filter((r) => !dropped.has(r.id));
+    const accounted = counted.map((r) => {
+        const costUsd = Number(r.costUsd);
+        let reservedUsd = 0;
+        const holds = !excluded.has(r.id) &&
+            (options.holdsBefore === undefined || isOrderedBefore(r, options.holdsBefore)) &&
+            isHoldLive(r, now, queueTimeoutSec);
+        if (holds) {
+            // A coding run holds exactly what dispatch reserved. A native run (or
+            // a coding run whose CodingRun row is missing) holds its agent's
+            // per-run budget: never less than what it can actually spend.
+            const reservation = r.codingRun != null ? Number(r.codingRun.budgetReservedUsd) : (memberBudgets.get(r.agentId) ?? 0);
+            reservedUsd = Math.max(0, reservation - costUsd);
+        }
+        return { startedAt: r.startedAt, costUsd, reservedUsd };
+    });
     return configured.map(({ period, capUsd }) => {
         const start = periodStart(period, now);
-        const spentUsd = runs.filter((r) => r.startedAt >= start).reduce((sum, r) => sum + Number(r.costUsd), 0);
-        return { period, capUsd, spentUsd, remainingUsd: Math.max(0, capUsd - spentUsd) };
+        const inPeriod = accounted.filter((r) => r.startedAt >= start);
+        const spentUsd = inPeriod.reduce((sum, r) => sum + r.costUsd, 0);
+        const reservedUsd = inPeriod.reduce((sum, r) => sum + r.reservedUsd, 0);
+        return { period, capUsd, spentUsd, reservedUsd, remainingUsd: Math.max(0, capUsd - spentUsd - reservedUsd) };
     });
 }
 /** Walks parentRunId upward from `runId` to the tree's root (parentRunId null). */
 async function findRootRun(db, runId) {
     let current = await db.run.findUniqueOrThrow({
         where: { id: runId },
-        select: { id: true, agentId: true, parentRunId: true },
+        select: { id: true, agentId: true, parentRunId: true, startedAt: true },
     });
     while (current.parentRunId) {
         current = await db.run.findUniqueOrThrow({
             where: { id: current.parentRunId },
-            select: { id: true, agentId: true, parentRunId: true },
+            select: { id: true, agentId: true, parentRunId: true, startedAt: true },
         });
     }
     return current;
@@ -83,14 +153,23 @@ async function collectTreeRunIds(db, rootRunId) {
 /**
  * Real-time shared budget scope for a sub-agent dispatch: the whole run tree
  * rooted at `parentRunId`'s ultimate ancestor shares one ceiling —
- * the root's own effective budget (its own budgetUsd, itself tightened by
- * its own BudgetGroup if any) minus everything every run in the tree has
- * spent so far. The root's ceiling is recomputed fresh here, not pinned
- * from whatever it was when the root run started — consistent with
- * BudgetGroup periods already always being live-recomputed rather than
- * snapshotted.
+ * the root's own budgetUsd, itself tightened by the root agent's BudgetGroup
+ * if any — minus everything every run in the tree has spent so far. The
+ * ceiling is recomputed fresh here, not pinned from whatever it was when the
+ * root run started — consistent with BudgetGroup periods already always
+ * being live-recomputed rather than snapshotted. Its group check leaves the
+ * tree's runs out entirely, cost and hold alike: the tree's spend is
+ * subtracted once, below, so counting it in the group too would charge it
+ * twice, and the tree spends inside the root's hold, so counting that hold
+ * would leave the tree nothing. It also leaves out holds of runs that started
+ * after the root (they already counted the root's hold). capUsd is therefore
+ * the tree's whole ceiling, and remainingUsd = capUsd - spentUsd.
  */
 export async function computeRunTreeSpend(db, parentRunId, now = new Date()) {
+    const { rootRunId, capUsd, spentUsd, remainingUsd } = await runTreeSpend(db, parentRunId, now);
+    return { rootRunId, capUsd, spentUsd, remainingUsd };
+}
+async function runTreeSpend(db, parentRunId, now) {
     const root = await findRootRun(db, parentRunId);
     const treeRunIds = await collectTreeRunIds(db, root.id);
     const rows = await db.run.findMany({ where: { id: { in: treeRunIds } }, select: { costUsd: true } });
@@ -99,11 +178,23 @@ export async function computeRunTreeSpend(db, parentRunId, now = new Date()) {
         where: { id: root.agentId },
         select: { id: true, budgetGroupId: true, budgetUsd: true },
     });
+    const rootOrder = { id: root.id, startedAt: root.startedAt };
     // Root has no parentRunId of its own, so this terminates in one level —
     // no unbounded recursion regardless of how deep `parentRunId` itself was.
-    const rootCeiling = await effectiveBudgetForRun(db, rootAgent, now);
+    const rootCeiling = await groupCappedBudget(db, rootAgent, now, {
+        excludeRunIds: treeRunIds,
+        holdsBefore: rootOrder,
+    });
     const capUsd = rootCeiling.effectiveBudgetUsd;
-    return { rootRunId: root.id, capUsd, spentUsd, remainingUsd: Math.max(0, capUsd - spentUsd) };
+    return {
+        rootRunId: root.id,
+        capUsd,
+        spentUsd,
+        remainingUsd: Math.max(0, capUsd - spentUsd),
+        treeRunIds,
+        root: rootOrder,
+        rootBudgetGroupId: rootAgent.budgetGroupId,
+    };
 }
 /**
  * The per-run budget ceiling to actually use for `agent`: its own
@@ -116,17 +207,35 @@ export async function computeRunTreeSpend(db, parentRunId, now = new Date()) {
  * with no caps configured is returned unchanged. Also logs a warning
  * (never blocks, never throws) once a period's spend crosses the group's
  * own warnThresholdRatio.
+ *
+ * A sub-agent in the root's own budget group spends inside the root's hold,
+ * so its group check is the root's: the tree's holds and the holds of runs
+ * after the root are left out. A sub-agent in any other group is an
+ * ordinary member of that group and counts every earlier live hold there,
+ * the tree's included.
  */
-export async function effectiveBudgetForRun(db, agent, now = new Date(), parentRunId) {
+export async function effectiveBudgetForRun(db, agent, now = new Date(), parentRunId, options = {}) {
+    const self = options.self;
+    const ownSpend = { excludeReservationRunIds: self ? [self.id] : [], holdsBefore: self };
+    if (!parentRunId)
+        return groupCappedBudget(db, agent, now, ownSpend);
+    const tree = await runTreeSpend(db, parentRunId, now);
+    const sharesRootGroup = agent.budgetGroupId !== null && agent.budgetGroupId === tree.rootBudgetGroupId;
+    const spend = sharesRootGroup
+        ? { excludeReservationRunIds: [...tree.treeRunIds, ...(self ? [self.id] : [])], holdsBefore: tree.root }
+        : ownSpend;
+    return groupCappedBudget(db, agent, now, spend, { value: tree.remainingUsd, reason: "run-tree" });
+}
+async function groupCappedBudget(db, agent, now, spendOptions, extra) {
     const ownBudgetUsd = Number(agent.budgetUsd);
     const candidates = [];
     if (agent.budgetGroupId) {
         const group = await db.budgetGroup.findUnique({
             where: { id: agent.budgetGroupId },
-            include: { agents: { select: { id: true } } },
+            include: { agents: { select: { id: true, budgetUsd: true } } },
         });
         if (group) {
-            const spend = await computeGroupSpend(db, group, group.agents.map((a) => a.id), now);
+            const spend = await computeGroupSpend(db, group, group.agents, now, spendOptions);
             const warnThresholdRatio = Number(group.warnThresholdRatio);
             for (const s of spend) {
                 candidates.push({ value: s.remainingUsd, reason: s.period });
@@ -137,13 +246,13 @@ export async function effectiveBudgetForRun(db, agent, now = new Date(), parentR
             }
         }
     }
-    if (parentRunId) {
-        const tree = await computeRunTreeSpend(db, parentRunId, now);
-        candidates.push({ value: tree.remainingUsd, reason: "run-tree" });
-    }
+    if (extra)
+        candidates.push(extra);
     if (candidates.length === 0)
         return { effectiveBudgetUsd: ownBudgetUsd, constrainedBy: [] };
     const constrainedBy = candidates.filter((c) => c.value < ownBudgetUsd).map((c) => c.reason);
     const effectiveBudgetUsd = Math.min(ownBudgetUsd, ...candidates.map((c) => c.value));
-    return { effectiveBudgetUsd, constrainedBy };
+    // Less than the smallest reservable amount is nothing left.
+    const exhausted = candidates.find((c) => c.value < MIN_RESERVATION_USD);
+    return { effectiveBudgetUsd, constrainedBy, ...(exhausted ? { exhaustedBy: exhausted.reason } : {}) };
 }

package/dist/core/budget-wording.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The one sentence a host (a PR comment, a check summary) is told when a run
+ * ran out of budget, or could not start for lack of it. Public repositories
+ * read these, so it names amounts and the budget group only: never error
+ * text, token counts, or ids.
+ */
+import type { PrismaClient } from "#prisma";
+export interface BudgetFacts {
+    /** The run's own budget (a coding run's reservation); falls back to the agent's. */
+    runBudgetUsd?: number | null;
+    agentBudgetUsd: number;
+    budgetGroupName?: string | null;
+    /** The run was refused before it started. */
+    refused?: boolean;
+}
+export declare function budgetSentence(facts: BudgetFacts): string;
+/**
+ * The sentence for a finished run, read from the database: a coding run's
+ * reserved budget, otherwise the agent's. Falls back to a sentence without
+ * amounts when they cannot be read. Never throws.
+ */
+export declare function loadBudgetSentence(db: Pick<PrismaClient, "run">, runId: string, status: string): Promise<string>;