@wardby/cli 0.5.3 → 0.7.0

package/dist/core/budget-groups.js

@@ -66,6 +66,18 @@ function isOrderedBefore(run, other) {
  * returned with a null cap. One query at the widest configured window
  * (month contains week contains day), bucketed in JS, rather than a
  * separate DB round trip per period.
+ *
+ * A delegated run tree is held once, at its root. A sub-run whose tree root
+ * is a counted run of this group with a live, counted hold spends inside the
+ * root's hold, so it holds nothing (its cost still counts as spent), and the
+ * root holds its reservation minus the cost of every run in its tree, or the
+ * unspent holds of its tree's live runs when that is more (a coding run's
+ * grant can grow past the root's budget through overrun top-ups). A sub-run
+ * whose root is in another group, has finished, or whose hold is left out
+ * here (excludeReservationRunIds, holdsBefore) holds its own reservation. So
+ * does a sub-run in a period its root did not start in (a root that started
+ * yesterday, a child today: today's daily cap still holds the child's own
+ * reservation, since the root's hold falls in yesterday's bucket).
  */
 export async function computeGroupSpend(db, group, members, now = new Date(), options = {}) {
     const caps = [
@@ -97,33 +109,142 @@ export async function computeGroupSpend(db, group, members, now = new Date(), op
                 costUsd: true,
                 startedAt: true,
                 heartbeatAt: true,
+                parentRunId: true,
                 codingRun: { select: { budgetReservedUsd: true, timeoutSec: true } },
             },
         });
     const counted = runs.filter((r) => !dropped.has(r.id));
+    const countedById = new Map(counted.map((r) => [r.id, r]));
+    const holds = (r) => !excluded.has(r.id) &&
+        (options.holdsBefore === undefined || isOrderedBefore(r, options.holdsBefore)) &&
+        isHoldLive(r, now, queueTimeoutSec);
+    // 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 reservationOf = (r) => r.codingRun != null ? Number(r.codingRun.budgetReservedUsd) : (memberBudgets.get(r.agentId) ?? 0);
+    // A run inside the tree of a counted, holding root in this group spends
+    // inside that root's hold, so it holds nothing of its own.
+    const rootOf = await resolveRootRunIds(db, counted);
+    const heldRoots = new Set();
+    for (const r of counted) {
+        const rootId = rootOf.get(r.id);
+        if (rootId === undefined || rootId === r.id)
+            continue;
+        const root = countedById.get(rootId);
+        if (root && holds(root))
+            heldRoots.add(rootId);
+    }
+    // Such a root holds its reservation minus the cost of its whole tree, every
+    // run in it included (also runs in other groups: they spend the tree too).
+    // The runs below it may hold more than that: a coding run's grant takes
+    // top-ups from the root agent's overrun, and dispatch sized it beside its live
+    // siblings' holds. So the root holds at least the unspent holds of every live run below
+    // it, each held as in siblingHoldsUsd.
+    const treeHoldByRoot = new Map();
+    for (const rootId of heldRoots) {
+        const treeRunIds = await collectTreeRunIds(db, rootId);
+        const treeRuns = await db.run.findMany({
+            where: { id: { in: treeRunIds } },
+            select: {
+                id: true,
+                status: true,
+                costUsd: true,
+                startedAt: true,
+                heartbeatAt: true,
+                agent: { select: { budgetUsd: true } },
+                codingRun: { select: { budgetReservedUsd: true, timeoutSec: true } },
+            },
+        });
+        const treeCostUsd = treeRuns.reduce((sum, t) => sum + Number(t.costUsd), 0);
+        const childHoldsUsd = treeRuns
+            .filter((t) => t.id !== rootId && !excluded.has(t.id) && isHoldLive(t, now, queueTimeoutSec))
+            .reduce((sum, t) => {
+            const reservation = t.codingRun ? Number(t.codingRun.budgetReservedUsd) : Number(t.agent.budgetUsd);
+            return sum + Math.max(0, reservation - Number(t.costUsd));
+        }, 0);
+        const root = countedById.get(rootId);
+        treeHoldByRoot.set(rootId, Math.max(reservationOf(root) - treeCostUsd, childHoldsUsd));
+    }
     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);
+        const rootId = rootOf.get(r.id);
+        let ownReservedUsd = 0;
+        if (heldRoots.has(r.id)) {
+            ownReservedUsd = Math.max(0, treeHoldByRoot.get(r.id) ?? 0);
+        }
+        else if (holds(r)) {
+            ownReservedUsd = Math.max(0, reservationOf(r) - costUsd);
         }
-        return { startedAt: r.startedAt, costUsd, reservedUsd };
+        // Set when the run spends inside its root's hold: the root's startedAt.
+        const heldRootStartedAt = rootId !== undefined && rootId !== r.id && heldRoots.has(rootId) ? countedById.get(rootId).startedAt : null;
+        return { startedAt: r.startedAt, costUsd, ownReservedUsd, heldRootStartedAt };
     });
     return configured.map(({ period, capUsd }) => {
         const start = periodStart(period, now);
-        const inPeriod = accounted.filter((r) => r.startedAt >= start);
+        // A run inside a held tree holds nothing in a period only when its root's
+        // hold is counted in that period too (the root started in it); otherwise
+        // the period would see the run's spend but no hold for it.
+        const inPeriod = accounted
+            .filter((r) => r.startedAt >= start)
+            .map((r) => ({
+            costUsd: r.costUsd,
+            reservedUsd: r.heldRootStartedAt !== null && r.heldRootStartedAt >= start ? 0 : r.ownReservedUsd,
+        }));
         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) };
+        const heldRuns = inPeriod.filter((r) => r.reservedUsd > 0).length;
+        return {
+            period,
+            capUsd,
+            spentUsd,
+            reservedUsd,
+            remainingUsd: Math.max(0, capUsd - spentUsd - reservedUsd),
+            heldRuns,
+        };
     });
 }
+/** Deepest parentRunId chain resolveRootRunIds follows: a guard against a cycle. */
+const MAX_TREE_DEPTH = 32;
+/**
+ * Each run's tree root (the ancestor with parentRunId null), walking
+ * parentRunId upward in one batched query per level. A run whose chain cannot
+ * be resolved (a missing ancestor, or deeper than MAX_TREE_DEPTH) is left out.
+ */
+async function resolveRootRunIds(db, runs) {
+    const parentOf = new Map(runs.map((r) => [r.id, r.parentRunId ?? null]));
+    const missing = new Set();
+    for (let level = 0; level < MAX_TREE_DEPTH; level++) {
+        const unresolved = new Set();
+        for (const parentId of parentOf.values()) {
+            if (parentId !== null && !parentOf.has(parentId) && !missing.has(parentId))
+                unresolved.add(parentId);
+        }
+        if (unresolved.size === 0)
+            break;
+        const parents = await db.run.findMany({
+            where: { id: { in: [...unresolved] } },
+            select: { id: true, parentRunId: true, agentId: true },
+        });
+        for (const p of parents)
+            parentOf.set(p.id, p.parentRunId ?? null);
+        for (const id of unresolved)
+            if (!parentOf.has(id))
+                missing.add(id);
+    }
+    const rootOf = new Map();
+    for (const r of runs) {
+        let id = r.id;
+        let parentId = parentOf.get(id);
+        for (let depth = 0; parentId != null && depth < MAX_TREE_DEPTH; depth++) {
+            id = parentId;
+            parentId = parentOf.get(id);
+        }
+        // parentId undefined: a missing ancestor; non-null: too deep or a cycle.
+        if (parentId === null)
+            rootOf.set(r.id, id);
+    }
+    return rootOf;
+}
 /** Walks parentRunId upward from `runId` to the tree's root (parentRunId null). */
 async function findRootRun(db, runId) {
     let current = await db.run.findUniqueOrThrow({
@@ -204,7 +325,13 @@ function siblingHoldsUsd(rows, parentRunId, now, self) {
     }
     return total;
 }
-async function runTreeSpend(db, parentRunId, now, self) {
+/**
+ * With `withOverrun` (a coding run's top-up, codingTopUpRoom), the tree's
+ * ceiling is the root agent's budgetUsd raised by its own
+ * allowedOverrunPercent, still capped by the root's budget group; without it
+ * (dispatch and native callers), the root's budgetUsd: what the tree holds.
+ */
+async function runTreeSpend(db, parentRunId, now, self, withOverrun = false) {
     const root = await findRootRun(db, parentRunId);
     const treeRunIds = await collectTreeRunIds(db, root.id);
     const rows = await db.run.findMany({
@@ -224,15 +351,12 @@ async function runTreeSpend(db, parentRunId, now, self) {
     const heldUsd = siblingHoldsUsd(rows, parentRunId, now, self);
     const rootAgent = await db.agent.findUniqueOrThrow({
         where: { id: root.agentId },
-        select: { id: true, budgetGroupId: true, budgetUsd: true },
+        select: { id: true, budgetGroupId: true, budgetUsd: true, allowedOverrunPercent: 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 groupCappedBudget(db, rootAgent, now, {
-        excludeRunIds: treeRunIds,
-        holdsBefore: rootOrder,
-    });
+    const rootCeiling = await groupCappedBudget(db, rootAgent, now, { excludeRunIds: treeRunIds, holdsBefore: rootOrder }, undefined, withOverrun ? rootAgent.allowedOverrunPercent : undefined);
     const capUsd = rootCeiling.effectiveBudgetUsd;
     return {
         rootRunId: root.id,
@@ -263,7 +387,7 @@ async function runTreeSpend(db, parentRunId, now, self) {
  * the tree's included.
  */
 export async function effectiveBudgetForRun(db, agent, now = new Date(), parentRunId, options = {}) {
-    const self = options.self;
+    const { self } = options;
     const ownSpend = { excludeReservationRunIds: self ? [self.id] : [], holdsBefore: self };
     if (!parentRunId)
         return groupCappedBudget(db, agent, now, ownSpend);
@@ -272,10 +396,21 @@ export async function effectiveBudgetForRun(db, agent, now = new Date(), parentR
     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" });
+    return groupCappedBudget(db, agent, now, spend, {
+        value: tree.remainingUsd,
+        reason: "run-tree",
+        detail: {
+            capUsd: tree.capUsd,
+            spentUsd: tree.spentUsd,
+            heldUsd: tree.capUsd - tree.spentUsd - tree.remainingUsd,
+            heldRuns: 0,
+        },
+    });
 }
-async function groupCappedBudget(db, agent, now, spendOptions, extra) {
+async function groupCappedBudget(db, agent, now, spendOptions, extra, overrunPercent) {
     const ownBudgetUsd = Number(agent.budgetUsd);
+    // The ceiling the candidates tighten: own raised by the overrun, when one is given (a run tree's raised cap).
+    const ownLimitUsd = overrunPercent === undefined ? ownBudgetUsd : (ownBudgetUsd * (100 + overrunPercent)) / 100;
     const candidates = [];
     if (agent.budgetGroupId) {
         const group = await db.budgetGroup.findUnique({
@@ -286,7 +421,11 @@ async function groupCappedBudget(db, agent, now, spendOptions, extra) {
             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 });
+                candidates.push({
+                    value: s.remainingUsd,
+                    reason: s.period,
+                    detail: { capUsd: s.capUsd, spentUsd: s.spentUsd, heldUsd: s.reservedUsd, heldRuns: s.heldRuns },
+                });
                 if (s.spentUsd >= s.capUsd * warnThresholdRatio) {
                     budgetGroupLog.warn({ groupId: group.id, groupName: group.name, period: s.period, capUsd: s.capUsd, spentUsd: s.spentUsd }, `budget group "${group.name}"'s ${s.period} spend ($${s.spentUsd.toFixed(4)}) has reached ` +
                         `${(warnThresholdRatio * 100).toFixed(0)}% of its $${s.capUsd.toFixed(4)} cap`);
@@ -297,10 +436,80 @@ async function groupCappedBudget(db, agent, now, spendOptions, extra) {
     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: ownLimitUsd, constrainedBy: [] };
+    const values = candidates.map((c) => c.value);
+    const constrainedBy = candidates.filter((c) => c.value < ownLimitUsd).map((c) => c.reason);
+    const effectiveBudgetUsd = Math.min(ownLimitUsd, ...values);
     // 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 } : {}) };
+    const limiting = effectiveBudgetUsd < ownLimitUsd ? candidates.find((c) => c.value === effectiveBudgetUsd) : undefined;
+    return {
+        effectiveBudgetUsd,
+        constrainedBy,
+        ...(limiting ? { limitedBy: limiting.reason } : {}),
+        ...(exhausted ? { exhaustedBy: exhausted.reason, exhaustedDetail: exhausted.detail } : {}),
+    };
+}
+/**
+ * Room for a coding run's overrun top-up (budget-topup.ts): the least of what
+ * its budget group, its run tree's root group, and its run tree's
+ * overrun-raised ceiling have left right now. Each group is seen whole: every
+ * live hold counts, this run's own grant (or its tree's hold) included, with
+ * no first-come-first-served ordering, because a top-up is new money that runs
+ * started later did not count when they reserved. A grant of at most roomUsd
+ * raises each group's and the tree's committed total by at most that much, so
+ * caps and ceilings stay hard. Callers hold the group dispatch lock.
+ */
+export async function codingTopUpRoom(db, runId, now = new Date()) {
+    const run = await db.run.findUniqueOrThrow({
+        where: { id: runId },
+        select: { parentRunId: true, agent: { select: { budgetGroupId: true } } },
+    });
+    const candidates = [];
+    const groupIds = new Set();
+    if (run.agent.budgetGroupId)
+        groupIds.add(run.agent.budgetGroupId);
+    if (run.parentRunId) {
+        // Every live run in the tree off the ancestor chain holds its grant, this run's included.
+        const tree = await runTreeSpend(db, run.parentRunId, now, undefined, true);
+        candidates.push({
+            value: tree.remainingUsd,
+            reason: "run-tree",
+            detail: {
+                capUsd: tree.capUsd,
+                spentUsd: tree.spentUsd,
+                heldUsd: tree.capUsd - tree.spentUsd - tree.remainingUsd,
+                heldRuns: 0,
+            },
+        });
+        // The root's group holds the tree, this run's grant included, wherever this run's own group is.
+        if (tree.rootBudgetGroupId)
+            groupIds.add(tree.rootBudgetGroupId);
+    }
+    for (const groupId of groupIds) {
+        const group = await db.budgetGroup.findUnique({
+            where: { id: groupId },
+            include: { agents: { select: { id: true, budgetUsd: true } } },
+        });
+        if (!group)
+            continue;
+        for (const s of await computeGroupSpend(db, group, group.agents, now)) {
+            candidates.push({
+                value: s.remainingUsd,
+                reason: s.period,
+                detail: { capUsd: s.capUsd, spentUsd: s.spentUsd, heldUsd: s.reservedUsd, heldRuns: s.heldRuns },
+                groupName: group.name,
+            });
+        }
+    }
+    if (candidates.length === 0)
+        return { roomUsd: Infinity };
+    const least = candidates.reduce((min, c) => (c.value < min.value ? c : min));
+    const { capUsd, spentUsd, heldUsd } = least.detail;
+    return {
+        roomUsd: Math.max(0, least.value),
+        limitedBy: least.reason,
+        detail: { capUsd, spentUsd, heldUsd },
+        ...(least.groupName !== undefined ? { groupName: least.groupName } : {}),
+    };
 }

package/dist/core/budget-stopped-head.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Which run last pushed to a pull request a coding run opened, and whether that push was work a
+ * run stopped at its budget left unfinished. Mark-ready keeps such a draft a draft; the review
+ * check skips it while its head is still that push (a person's later commit is reviewed).
+ */
+import type { PrismaClient } from "#prisma";
+export type BudgetStoppedHeadDb = Pick<PrismaClient, "codingRun">;
+/** The run that pushed last: its status and the commit it pushed (result.commitSha). */
+export interface LastPusher {
+    status: string | undefined;
+    commitSha: string | undefined;
+}
+/**
+ * The newest continuation of `root` (by createdAt) whose result names pull request `prNumber`,
+ * else the root itself.
+ */
+export declare function lastPusher(db: BudgetStoppedHeadDb, root: {
+    runId: string;
+    result: unknown;
+    run: {
+        status?: string;
+    } | null;
+}, prNumber: number): Promise<LastPusher>;
+/**
+ * True when the pull request's head is the push of a run that stopped at its budget: the marker
+ * run resolves (through rootCodingRunId) to a root coding run in `repository` recorded as this
+ * pull request, and its last pusher stopped at its budget with `headSha` as its commit. Any
+ * lookup failure is false, so the pull request is reviewed as usual.
+ */
+export declare function headStoppedAtBudget(db: BudgetStoppedHeadDb, input: {
+    markerRunId: string | null | undefined;
+    repository: string;
+    prNumber: number;
+    headSha: string;
+}): Promise<boolean>;
+/**
+ * The coding run that may be pushing to the pull request right now: the marker's root coding
+ * run (in `repository`) while it is pending or running, else its newest continuation that is.
+ * Its result, and so whether it stopped at its budget, is recorded only after its push lands,
+ * so a review of the head waits for it. Null when none is in flight or the marker resolves to
+ * nothing.
+ */
+export declare function pushingRunInFlight(db: BudgetStoppedHeadDb, input: {
+    markerRunId: string | null | undefined;
+    repository: string;
+}): Promise<string | null>;

package/dist/core/budget-stopped-head.js

@@ -0,0 +1,81 @@
+import { pullRequestOutcome } from "./host-status.js";
+const commitShaOf = (result) => {
+    if (!result || typeof result !== "object")
+        return undefined;
+    const sha = result.commitSha;
+    return typeof sha === "string" ? sha : undefined;
+};
+/**
+ * The newest continuation of `root` (by createdAt) whose result names pull request `prNumber`,
+ * else the root itself.
+ */
+export async function lastPusher(db, root, prNumber) {
+    const continuations = await db.codingRun.findMany({
+        where: { rootCodingRunId: root.runId },
+        select: { result: true, run: { select: { status: true } } },
+        orderBy: { createdAt: "desc" },
+    });
+    const last = continuations.find((c) => pullRequestOutcome(c.result)?.pullRequestNumber === prNumber) ?? root;
+    return { status: last.run?.status, commitSha: commitShaOf(last.result) };
+}
+const ROOT_SELECT = {
+    runId: true,
+    repository: true,
+    rootCodingRunId: true,
+    result: true,
+    run: { select: { status: true } },
+};
+/** The marker run's root coding run (rootCodingRunId, else itself), only when it is in `repository`. */
+async function markerRoot(db, markerRunId, repository) {
+    const marked = await db.codingRun.findUnique({ where: { runId: markerRunId }, select: ROOT_SELECT });
+    if (!marked)
+        return null;
+    const root = marked.rootCodingRunId
+        ? await db.codingRun.findUnique({ where: { runId: marked.rootCodingRunId }, select: ROOT_SELECT })
+        : marked;
+    return root && root.repository.toLowerCase() === repository.toLowerCase() ? root : null;
+}
+/**
+ * True when the pull request's head is the push of a run that stopped at its budget: the marker
+ * run resolves (through rootCodingRunId) to a root coding run in `repository` recorded as this
+ * pull request, and its last pusher stopped at its budget with `headSha` as its commit. Any
+ * lookup failure is false, so the pull request is reviewed as usual.
+ */
+export async function headStoppedAtBudget(db, input) {
+    try {
+        if (!input.markerRunId)
+            return false;
+        const root = await markerRoot(db, input.markerRunId, input.repository);
+        if (!root || pullRequestOutcome(root.result)?.pullRequestNumber !== input.prNumber)
+            return false;
+        const last = await lastPusher(db, root, input.prNumber);
+        return last.status === "budget_exhausted" && last.commitSha === input.headSha;
+    }
+    catch {
+        return false;
+    }
+}
+/** Run statuses of a coding run that may still push (its result is not recorded yet). */
+const IN_FLIGHT = ["pending", "running"];
+/**
+ * The coding run that may be pushing to the pull request right now: the marker's root coding
+ * run (in `repository`) while it is pending or running, else its newest continuation that is.
+ * Its result, and so whether it stopped at its budget, is recorded only after its push lands,
+ * so a review of the head waits for it. Null when none is in flight or the marker resolves to
+ * nothing.
+ */
+export async function pushingRunInFlight(db, input) {
+    if (!input.markerRunId)
+        return null;
+    const root = await markerRoot(db, input.markerRunId, input.repository);
+    if (!root)
+        return null;
+    if (root.run && IN_FLIGHT.includes(root.run.status))
+        return root.runId;
+    const continuation = await db.codingRun.findFirst({
+        where: { rootCodingRunId: root.runId, run: { status: { in: [...IN_FLIGHT] } } },
+        select: { runId: true },
+        orderBy: { createdAt: "desc" },
+    });
+    return continuation?.runId ?? null;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Overrun from available room: a coding run reserves only its base budget at
+ * dispatch, and may spend past it, up to its limit (CodingRun.budgetLimitUsd,
+ * the base raised by the agent's allowedOverrunPercent), only out of room its
+ * budget group and run tree still have when it needs it. Overrun is
+ * permission, not a reservation.
+ *
+ * The control plane grants top-ups, never the proxy: the executor's per-run
+ * monitor loop calls topUpCodingBudget while the run's job is running. A run
+ * close to its grant (spent + held within its headroom of it: two of its
+ * largest request holds, or 20% of its base if more) is granted one step, under the same group dispatch lock dispatch takes, by
+ * raising CodingRun.budgetReservedUsd (what groups and run trees hold) and
+ * CodingProxySession.budgetUsd (what the proxy enforces, re-read on every
+ * request) together. When the group or tree has no room left, the run records
+ * an overrun_unavailable budget event and never asks again; the proxy then
+ * refuses it at its grant as it always has.
+ */
+import type { PrismaClient } from "#prisma";
+/**
+ * not_needed: the run is not close to its grant yet. granted: one step was
+ * added. unavailable: its group or run tree had no room; recorded once, and
+ * the run stops asking. closed: nothing more to ask for (no limit, the limit
+ * reached, already refused once, or the run or its proxy session is not active).
+ */
+export type TopUpOutcome = "not_needed" | "granted" | "unavailable" | "closed";
+export interface TopUpResult {
+    outcome: TopUpOutcome;
+    /** The run's grant after this call, when it has a limit. */
+    grantedUsd?: number;
+    /**
+     * The run is within twice its headroom of its grant: the caller should ask
+     * again soon (the executor polls faster), since a top-up must land while the
+     * request before the one that would not fit is still in flight.
+     */
+    near?: boolean;
+}
+/** Share of the base one step adds, unless one maximum request hold is more. */
+export declare const TOP_UP_STEP_SHARE = 0.1;
+/** Headroom: the share of the base, or this many of the run's largest request holds if more. */
+export declare const TOP_UP_HEADROOM_SHARE = 0.2;
+export declare const TOP_UP_HEADROOM_HOLDS = 2;
+/**
+ * Grants the run one overrun step when it is close to its grant and its
+ * budget group and run tree have room. Cheap when it is not close: that is
+ * read without the lock. One attempt per call, so a poll never blocks on
+ * retries: a serialization conflict (or a lock not had in time) answers
+ * not_needed and near, and the caller's next poll, soon, asks again.
+ */
+export declare function topUpCodingBudget(db: PrismaClient, runId: string, now?: Date): Promise<TopUpResult>;
+/** How long one top-up waits to start its transaction: short, so a poll (and its heartbeat) is never held long. */
+export declare const TOP_UP_TX_MAX_WAIT_MS = 2000;