@sweny-ai/core 0.1.198 → 0.1.200

package/dist/agent-env.d.ts

@@ -77,6 +77,8 @@ export declare const PI_ENV_PREFIXES: readonly string[];
  * name is in {@link PI_AUTH_VARS} (`meta` to `META_API_KEY`).
  */
 export declare const PI_PROVIDER_VARS: Readonly<Record<string, readonly string[]>>;
+/** pi settings that are not secrets: their presence alone never selects a provider. */
+export declare const PI_NON_SECRET_VARS: ReadonlySet<string>;
 /** The {@link PI_AUTH_VARS} names for one pi provider id (empty for a custom `models.json` provider). */
 export declare function piProviderVars(provider: string): string[];
 export interface PiProviderResolution {
@@ -115,6 +117,12 @@ export interface BuildAgentEnvOpts {
     prefixes?: readonly string[];
     /** Operator passthrough list (`env-passthrough`). `"*"` inherits everything. */
     passthrough?: readonly string[];
+    /**
+     * Where `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` are read when
+     * deciding the cloud vars. Default: `source`. A harness `env` overlay passes
+     * the overlaid env, so an overlay that turns Bedrock on keeps the `AWS_*` vars.
+     */
+    routing?: Record<string, string | undefined>;
     logger?: Pick<Logger, "warn">;
 }
 /**
@@ -221,7 +229,8 @@ export declare function noPushGitConfig(dir: string): Array<[string, string]>;
  * scoping is on. Withholds {@link PUSH_TOKEN_VARS} (the ssh agent socket and
  * askpass programs among them) and every {@link isAgentCredential} name, even
  * one a node granted with `agent_env`, appends
- * {@link noPushGitConfig} after any `GIT_CONFIG_*` entries already present,
+ * {@link noPushGitConfig} after any `GIT_CONFIG_*` entries already present
+ * (and drops `GIT_CONFIG_PARAMETERS`, which git would apply after them),
  * sets `GIT_ASKPASS` to a refusing program, turns off git's terminal prompt,
  * routes git's ssh through a wrapper that refuses `git-receive-pack` (so an
  * ssh push fails even to a remote with an explicit `pushurl` under
@@ -306,6 +315,72 @@ export declare function grantedAgentEnv(agentEnv: readonly string[] | undefined,
     grant: string[];
     dropped?: string;
 };
+/**
+ * The `env` and `envRemove` options every harness takes. They hold per
+ * harness instance: every node and every judge and route call (`complete()`)
+ * on that instance gets them, so per-run isolation means one harness per
+ * `execute()`.
+ */
+export interface HarnessEnvOptions {
+    /**
+     * Values laid over the agent env after scoping and passthrough, then put
+     * through the same credential rule as the inherited env: a skill credential
+     * (`GITHUB_TOKEN`, `SLACK_*`, a custom skill's config name) is withheld
+     * unless the node grants it with `agent_env`, and the harness's own auth
+     * vars always pass. When it names one of the harness's own credentials, the
+     * inherited ones are dropped first, so the overlay's login replaces the
+     * parent's instead of sitting beside it. In a staged or dry run the push
+     * block lands on top: it sets `GIT_ASKPASS`, `GH_CONFIG_DIR`, the ssh
+     * command and its git config entries over any overlaid value, drops
+     * `GIT_CONFIG_PARAMETERS` and every push token. `SWENY_*` names here only
+     * reach the agent; sweny itself reads its settings from `process.env`.
+     * Use it to hand a run its own `HOME` or `CLAUDE_CONFIG_DIR` without
+     * touching `process.env`, which is never modified. `HOME`,
+     * `CLAUDE_CONFIG_DIR` and `CODEX_HOME` must be absolute paths: the sandbox
+     * denies the login files under them.
+     */
+    env?: Readonly<Record<string, string>>;
+    /**
+     * Names removed from the agent env after scoping and passthrough, before
+     * `env` is applied (e.g. a parent `ANTHROPIC_API_KEY` when the run should
+     * use a login under `CLAUDE_CONFIG_DIR`).
+     */
+    envRemove?: readonly string[];
+}
+/** A validated, copied {@link HarnessEnvOptions}. */
+export interface AgentEnvOverlay {
+    readonly env: Readonly<Record<string, string>>;
+    readonly remove: readonly string[];
+}
+/**
+ * The executable a spawn of `command` with this env and cwd would run: a path
+ * with a separator resolves against `cwd`, a bare name is looked up on
+ * `env.PATH`. Undefined when nothing executable is found. Used so a version
+ * check probes the same file the spawn later runs (a harness `env` overlay may
+ * set its own `PATH`).
+ */
+export declare function resolveExecutable(command: string, env: Record<string, string | undefined>, cwd?: string): string | undefined;
+/**
+ * Validate and copy a harness's `env` / `envRemove` options. Throws on a
+ * non-string value or an invalid name, so a bad overlay fails at construction
+ * instead of at spawn. Returns undefined when neither option is set. The copy
+ * means a later change to the caller's objects has no effect.
+ */
+export declare function agentEnvOverlay(opts: HarnessEnvOptions): AgentEnvOverlay | undefined;
+/**
+ * Apply a caller overlay to a scoped agent env, before {@link finishAgentEnv}
+ * (which then withholds any overlaid skill credential the node did not grant).
+ * Drops the `remove` names, then, when the overlay names any of `credentials`
+ * (the harness's own login vars), drops the inherited ones, then lays the
+ * overlay values on top. Pure: returns a copy.
+ */
+export declare function applyEnvOverlay(env: Record<string, string>, overlay: AgentEnvOverlay | undefined, credentials: readonly string[]): Record<string, string>;
+/**
+ * `process.env` as the agent will see it for auth and command lookups (a
+ * harness's `preflight()` probe): the overlay applied by {@link applyEnvOverlay},
+ * except `SWENY_*` names, which stay as sweny reads them from `process.env`.
+ */
+export declare function overlaidProcessEnv(overlay: AgentEnvOverlay | undefined, credentials: readonly string[]): Record<string, string>;
 /** What one node's agent call may see: env var names and network hosts. */
 export interface AgentAccess {
     /**
@@ -428,14 +503,31 @@ export declare function checkSandboxSupport(platform?: NodeJS.Platform, pathEnv?
  * - `network.allowedDomains` + `strictAllowlist`: non-listed hosts are denied
  *   deterministically rather than prompted (no prompt exists headless).
  * - `credentials`: the agent's own Anthropic credentials are unset for
- *   sandboxed commands, and the Claude Code credentials file is unreadable.
+ *   sandboxed commands, and the Claude Code credentials file is unreadable:
+ *   the host's, and the one the agent env selects ({@link claudeCredentialFiles},
+ *   `agentEnv` carrying a harness `env` overlay's `HOME` / `CLAUDE_CONFIG_DIR`).
  */
 export declare function buildSandboxSettings(domains: readonly string[], opts?: {
     failIfUnavailable?: boolean;
     home?: string;
+    agentEnv?: Record<string, string | undefined>;
+    /** The agent's working directory, for a relative `HOME` / `CLAUDE_CONFIG_DIR`. */
+    cwd?: string;
 }): SandboxSettings;
+/**
+ * Claude Code login files to deny to sandboxed commands: the host's
+ * (`<hostHome>/.claude/.credentials.json`), plus the one `env` selects when it
+ * points elsewhere: `$CLAUDE_CONFIG_DIR/.credentials.json`, and
+ * `$HOME/.claude/.credentials.json`. A relative value resolves against the
+ * agent's `cwd`, where the agent would resolve it. Deduplicated, host file first.
+ */
+export declare function claudeCredentialFiles(env: Record<string, string | undefined>, hostHome: string, cwd?: string): string[];
 export interface ResolveAgentSandboxOpts {
     env: Record<string, string | undefined>;
+    /** The agent's env when it differs from `env` (a harness `env` overlay): its login files are denied too. */
+    agentEnv?: Record<string, string | undefined>;
+    /** The agent's working directory (resolves a relative path in `agentEnv`). */
+    cwd?: string;
     /** Explicit mode (client option); falls back to `env.SWENY_SANDBOX`. */
     mode?: SandboxMode;
     /** Explicit extra hosts (client option); falls back to `env.SWENY_SANDBOX_ALLOWED_DOMAINS`. */

package/dist/agent-env.js

@@ -262,7 +262,7 @@ export const PI_PROVIDER_VARS = {
     "xiaomi-token-plan-sgp": ["XIAOMI_TOKEN_PLAN_SGP_API_KEY"],
 };
 /** pi settings that are not secrets: their presence alone never selects a provider. */
-const PI_NON_SECRET_VARS = new Set([
+export const PI_NON_SECRET_VARS = new Set([
     "AZURE_OPENAI_BASE_URL",
     "AZURE_OPENAI_RESOURCE_NAME",
     "CLOUDFLARE_ACCOUNT_ID",
@@ -338,7 +338,8 @@ export function resolvePiProvider(env, model, explicit) {
 }
 /** A stored Codex login (`codex login`): `auth.json` under `CODEX_HOME`, default `~/.codex`. */
 export function hasCodexLogin(env = process.env, exists = existsSync) {
-    const home = env.CODEX_HOME || path.join(homedir(), ".codex");
+    // The env's HOME, not the process's: a harness `env` overlay may give the run its own.
+    const home = env.CODEX_HOME || path.join(env.HOME || homedir(), ".codex");
     return exists(path.join(home, "auth.json"));
 }
 /**
@@ -535,9 +536,10 @@ export function buildAgentEnv(source, opts = {}) {
     const prefixes = [...(opts.prefixes ?? AGENT_ENV_PREFIXES)];
     // Bedrock / Vertex routing is a Claude Code setting; only its default prefixes carry it.
     if (!opts.prefixes) {
-        if (truthy(source.CLAUDE_CODE_USE_BEDROCK))
+        const routing = opts.routing ?? source;
+        if (truthy(routing.CLAUDE_CODE_USE_BEDROCK))
             prefixes.push(...BEDROCK_PREFIXES);
-        if (truthy(source.CLAUDE_CODE_USE_VERTEX))
+        if (truthy(routing.CLAUDE_CODE_USE_VERTEX))
             for (const v of VERTEX_VARS)
                 exact.add(v);
     }
@@ -636,7 +638,8 @@ export function noPushGitConfig(dir) {
  * scoping is on. Withholds {@link PUSH_TOKEN_VARS} (the ssh agent socket and
  * askpass programs among them) and every {@link isAgentCredential} name, even
  * one a node granted with `agent_env`, appends
- * {@link noPushGitConfig} after any `GIT_CONFIG_*` entries already present,
+ * {@link noPushGitConfig} after any `GIT_CONFIG_*` entries already present
+ * (and drops `GIT_CONFIG_PARAMETERS`, which git would apply after them),
  * sets `GIT_ASKPASS` to a refusing program, turns off git's terminal prompt,
  * routes git's ssh through a wrapper that refuses `git-receive-pack` (so an
  * ssh push fails even to a remote with an explicit `pushurl` under
@@ -662,6 +665,10 @@ export function withPushBlocked(env, enabled) {
         // Every skill credential too, even one a node granted with `agent_env`.
         if (PUSH_TOKEN_VARS.includes(k) || isAgentCredential(k))
             continue;
+        // git reads GIT_CONFIG_PARAMETERS after the GIT_CONFIG_COUNT entries, so a value there would
+        // override the block (push.default, core.hooksPath, credential.helper).
+        if (k === "GIT_CONFIG_PARAMETERS")
+            continue;
         out[k] = v;
     }
     const base = Number.parseInt(out.GIT_CONFIG_COUNT ?? "0", 10);
@@ -814,6 +821,116 @@ export function grantedAgentEnv(agentEnv, opts) {
         return { grant: [], dropped: `agent_env withheld in a staged or dry run: ${names.join(", ")}` };
     return { grant: names };
 }
+/** POSIX leaves env names loosely defined; the rules here: not empty, no `=`, no NUL, no whitespace. */
+function checkEnvName(option, name) {
+    if (typeof name !== "string" || name === "" || /[=\0\s]/.test(name)) {
+        throw new Error(`${option}: invalid env var name ${JSON.stringify(name)} (must be a non-empty string without "=", NUL or whitespace)`);
+    }
+    return name;
+}
+/**
+ * The executable a spawn of `command` with this env and cwd would run: a path
+ * with a separator resolves against `cwd`, a bare name is looked up on
+ * `env.PATH`. Undefined when nothing executable is found. Used so a version
+ * check probes the same file the spawn later runs (a harness `env` overlay may
+ * set its own `PATH`).
+ */
+export function resolveExecutable(command, env, cwd = process.cwd()) {
+    const ok = (p) => {
+        try {
+            accessSync(p, fsConstants.X_OK);
+            return statSync(p).isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    if (command.includes(path.sep) || command.includes("/")) {
+        const p = path.resolve(cwd, command);
+        return ok(p) ? p : undefined;
+    }
+    for (const dir of (env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+        const p = path.resolve(cwd, dir, command);
+        if (ok(p))
+            return p;
+    }
+    return undefined;
+}
+/** Overlay names whose value is a directory the sandbox derives credential-file denies from. */
+const OVERLAY_PATH_VARS = ["HOME", "CLAUDE_CONFIG_DIR", "CODEX_HOME"];
+function isPlainObject(v) {
+    if (v === null || typeof v !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Validate and copy a harness's `env` / `envRemove` options. Throws on a
+ * non-string value or an invalid name, so a bad overlay fails at construction
+ * instead of at spawn. Returns undefined when neither option is set. The copy
+ * means a later change to the caller's objects has no effect.
+ */
+export function agentEnvOverlay(opts) {
+    if (opts.env === undefined && opts.envRemove === undefined)
+        return undefined;
+    const env = {};
+    if (opts.env !== undefined) {
+        if (!isPlainObject(opts.env)) {
+            throw new Error("env: must be a plain object of env var names to string values (not a Map or class instance)");
+        }
+        for (const [k, v] of Object.entries(opts.env)) {
+            checkEnvName("env", k);
+            if (typeof v !== "string") {
+                throw new Error(`env: value for ${k} must be a string, got ${typeof v}` +
+                    (v === undefined ? " (leave the key out, or name it in envRemove to unset it)" : ""));
+            }
+            if (v.includes("\0"))
+                throw new Error(`env: value for ${k} contains NUL`);
+            if (OVERLAY_PATH_VARS.includes(k) && !path.isAbsolute(v)) {
+                throw new Error(`env: ${k} must be an absolute path, got ${JSON.stringify(v)}`);
+            }
+            env[k] = v;
+        }
+    }
+    if (opts.envRemove !== undefined && !Array.isArray(opts.envRemove)) {
+        throw new Error("envRemove: must be an array of env var names");
+    }
+    const remove = (opts.envRemove ?? []).map((n) => checkEnvName("envRemove", n));
+    return Object.freeze({ env: Object.freeze(env), remove: Object.freeze(remove) });
+}
+/**
+ * Apply a caller overlay to a scoped agent env, before {@link finishAgentEnv}
+ * (which then withholds any overlaid skill credential the node did not grant).
+ * Drops the `remove` names, then, when the overlay names any of `credentials`
+ * (the harness's own login vars), drops the inherited ones, then lays the
+ * overlay values on top. Pure: returns a copy.
+ */
+export function applyEnvOverlay(env, overlay, credentials) {
+    if (!overlay)
+        return env;
+    const out = { ...env };
+    for (const name of overlay.remove)
+        delete out[name];
+    if (credentials.some((c) => Object.hasOwn(overlay.env, c)))
+        for (const c of credentials)
+            delete out[c];
+    return Object.assign(out, overlay.env);
+}
+/**
+ * `process.env` as the agent will see it for auth and command lookups (a
+ * harness's `preflight()` probe): the overlay applied by {@link applyEnvOverlay},
+ * except `SWENY_*` names, which stay as sweny reads them from `process.env`.
+ */
+export function overlaidProcessEnv(overlay, credentials) {
+    const full = Object.fromEntries(Object.entries(process.env).filter((e) => e[1] != null));
+    if (!overlay)
+        return full;
+    const own = (n) => !n.startsWith("SWENY_");
+    return applyEnvOverlay(full, {
+        env: Object.fromEntries(Object.entries(overlay.env).filter(([k]) => own(k))),
+        remove: overlay.remove.filter(own),
+    }, credentials);
+}
 /** True when a run request may load no MCP server but sweny's own bridge (read-only or staged). */
 export function mcpWithheld(readOnly, access) {
     return readOnly || access?.noMcp === true;
@@ -1031,9 +1148,12 @@ function defaultProbe() {
  * - `network.allowedDomains` + `strictAllowlist`: non-listed hosts are denied
  *   deterministically rather than prompted (no prompt exists headless).
  * - `credentials`: the agent's own Anthropic credentials are unset for
- *   sandboxed commands, and the Claude Code credentials file is unreadable.
+ *   sandboxed commands, and the Claude Code credentials file is unreadable:
+ *   the host's, and the one the agent env selects ({@link claudeCredentialFiles},
+ *   `agentEnv` carrying a harness `env` overlay's `HOME` / `CLAUDE_CONFIG_DIR`).
  */
 export function buildSandboxSettings(domains, opts = {}) {
+    const loginFiles = claudeCredentialFiles(opts.agentEnv ?? {}, opts.home ?? homedir(), opts.cwd);
     return {
         enabled: true,
         failIfUnavailable: opts.failIfUnavailable ?? true,
@@ -1046,7 +1166,7 @@ export function buildSandboxSettings(domains, opts = {}) {
         credentials: {
             envVars: AGENT_AUTH_VARS.map((name) => ({ name, mode: "deny" })),
             files: [
-                { path: path.join(opts.home ?? homedir(), ".claude", ".credentials.json"), mode: "deny" },
+                ...loginFiles.map((p) => ({ path: p, mode: "deny" })),
                 // Run journals and their keys: an agent that could read a key could forge records.
                 { path: runStateRoot(), mode: "deny" },
             ],
@@ -1055,6 +1175,21 @@ export function buildSandboxSettings(domains, opts = {}) {
         filesystem: { denyRead: [runStateRoot()], denyWrite: [runStateRoot()] },
     };
 }
+/**
+ * Claude Code login files to deny to sandboxed commands: the host's
+ * (`<hostHome>/.claude/.credentials.json`), plus the one `env` selects when it
+ * points elsewhere: `$CLAUDE_CONFIG_DIR/.credentials.json`, and
+ * `$HOME/.claude/.credentials.json`. A relative value resolves against the
+ * agent's `cwd`, where the agent would resolve it. Deduplicated, host file first.
+ */
+export function claudeCredentialFiles(env, hostHome, cwd = process.cwd()) {
+    const files = [path.join(hostHome, ".claude", ".credentials.json")];
+    if (env.CLAUDE_CONFIG_DIR)
+        files.push(path.resolve(cwd, env.CLAUDE_CONFIG_DIR, ".credentials.json"));
+    if (env.HOME)
+        files.push(path.resolve(cwd, env.HOME, ".claude", ".credentials.json"));
+    return [...new Set(files)];
+}
 /**
  * Resolve the `sandbox` query option for one agent call.
  *
@@ -1091,6 +1226,8 @@ export function resolveAgentSandbox(opts) {
         settings: buildSandboxSettings([...DEFAULT_SANDBOX_DOMAINS, ...(opts.nodeDomains ?? []), ...extra], {
             // Preflight passed: from here the sandbox is enforced or the node fails.
             failIfUnavailable: true,
+            agentEnv: opts.agentEnv,
+            cwd: opts.cwd,
         }),
     };
 }

package/dist/budget.d.ts

@@ -8,8 +8,14 @@
  *
  * Tokens are input + output tokens as the harness reports them (cache reads and
  * writes are not counted, matching the run receipt). Cost is the harness's own
- * reported USD, never estimated. Only agent node runs are counted: judge,
- * routing and retry-reflection completions report no usage and are not metered.
+ * reported USD, never estimated. Every model completion the executor itself
+ * makes is counted too, under its own `kind` (see {@link SpendKind}): judge
+ * scoring, route evaluation, retry reflection and the safe-output screen. A
+ * completion counts when its harness reports usage for it; one that reports
+ * none adds nothing (the same as a node run without usage). The run totals
+ * and the stop are over all kinds together, across a resume too; the split is
+ * `trace.spend`. Once a ceiling is reached no further executor completion
+ * starts. The decision model (`route_by: decider`) is not metered.
  *
  * Enforcement, per unit the harness can report:
  * - live: the harness calls `onUsage` during the node; crossing a limit aborts
@@ -17,7 +23,9 @@
  * - between nodes: usage on the finished result is checked; a crossing fails the
  *   node, and the run halts before the next node starts.
  * - across a resume: the run journal records each attempt's spend (live and
- *   final), and `sweny workflow resume` seeds the run total with it.
+ *   final), and each metered completion (judge, route, reflection, screen)
+ *   as its own record; `sweny workflow resume` seeds the run total with all
+ *   of it, split by kind.
  */
 import type { NodeUsage } from "./types.js";
 /** The `budget` field of a node or workflow. */
@@ -36,6 +44,20 @@ export interface Spend {
     tokens: number;
     costUsd: number;
 }
+/** Spend restored on a resume: the total, and its split by kind when the journal has one. */
+export interface SeedSpend extends Spend {
+    byKind?: Partial<Record<SpendKind, Spend>>;
+}
+/** What a unit of spend paid for. `node` is an agent node run; the rest are the executor's own completions. */
+export type SpendKind = "node" | "judge" | "route" | "reflect" | "screen";
+/** The order kinds are listed in, wherever the split is shown. */
+export declare const SPEND_KINDS: readonly SpendKind[];
+/** Spend of one {@link SpendKind}. `calls` counts the completions that reported usage. */
+export interface KindSpend extends Spend {
+    calls: number;
+}
+/** Spend by kind. A kind with no reported usage is absent. */
+export type SpendBreakdown = Partial<Record<SpendKind, KindSpend>>;
 export type BudgetUnit = "tokens" | "cost_usd";
 /** Recorded on the node whose spend crossed a budget (`NodeResult.budget`). */
 export interface BudgetOverrun {
@@ -45,6 +67,18 @@ export interface BudgetOverrun {
     limit: number;
     /** Spend at the moment of the stop (live) or at the end of the node. */
     spent: number;
+    /** The executor completion whose spend crossed it (judge, route, ...). Absent for a node run. */
+    kind?: SpendKind;
+}
+/**
+ * Thrown into an executor completion (judge, route, reflection, screen) the
+ * budget refuses: a ceiling was already reached, so the call is not made.
+ * Callers that swallow a failed completion (a judge's parse retry) must let
+ * this one through, so a refusal is never mistaken for a model answer.
+ */
+export declare class BudgetRefusal extends Error {
+    readonly breach: BudgetOverrun;
+    constructor(breach: BudgetOverrun);
 }
 export declare function toLimits(b: Budget | undefined): SpendLimits;
 /** The tighter of two limit sets, per unit. */
@@ -64,21 +98,43 @@ export declare function describeOverrun(o: BudgetOverrun, nodeId?: string): stri
 export declare class BudgetGuard {
     readonly runLimits: SpendLimits;
     private spent;
+    private kinds;
     constructor(runLimits: SpendLimits);
     get totals(): Spend;
+    /**
+     * Spend by kind, in {@link SPEND_KINDS} order. Resumed spend is restored
+     * under its kind; a journal without meter records seeds `node` only.
+     */
+    breakdown(): SpendBreakdown;
+    /** True once any completion other than a node run reported usage. */
+    get hasMeteredCalls(): boolean;
+    /**
+     * Count one executor completion (judge, route, ...) against the run. Usage
+     * with no tokens and no cost counts nothing. Returns the breach this report
+     * caused, judged against the totals before it, like a live node report.
+     */
+    meter(kind: SpendKind, usage: NodeUsage | undefined, nodeBudget?: NodeBudget): BudgetOverrun | undefined;
     /** True when any limit exists at all, so the executor can skip the machinery. */
     active(nodeLimits: SpendLimits): boolean;
     /** The run ceiling is already reached: no further attempt may start. */
     runExhausted(): BudgetOverrun | undefined;
     node(nodeLimits: SpendLimits): NodeBudget;
     /**
-     * Spend the run made before this process (a resumed run's journaled usage).
-     * Counted against the run ceiling like any other spend, so a crash never
-     * resets the whole-run budget.
+     * Spend the run made before this process (a resumed run's journaled usage
+     * and metered completions). Counted against the run ceiling like any other
+     * spend, so a crash never resets the whole-run budget. Restored under its
+     * kind when the journal has the split (a journal written before meter
+     * records existed has node spend only). Seeded spend is not a call: `calls`
+     * is unchanged.
      */
-    seed(s: Spend): void;
-    /** @internal */
-    commit(s: Spend): void;
+    seed(s: SeedSpend): void;
+    /**
+     * @internal `counted`: this commit is one completion that reported usage, so
+     * `calls` goes up. A commit that is not (seeded spend, an attempt that
+     * reported nothing) adds its spend only, and a zero one leaves no trace, so
+     * the split is the same with and without a limit.
+     */
+    commit(s: Spend, kind: SpendKind, counted: boolean): void;
 }
 export declare class NodeBudget {
     private readonly guard;
@@ -88,10 +144,18 @@ export declare class NodeBudget {
     /** A limit is already reached before the next attempt (a retry after a spend-heavy attempt, or a spent run). */
     exhausted(): BudgetOverrun | undefined;
     attempt(outer?: AbortSignal): BudgetAttempt;
+    /**
+     * Spend this visit made before a resume (a checkpointed visit's journaled
+     * spend). It counts against the node's own limit only: the run total
+     * already holds it from the seed.
+     */
+    restore(s: Spend): void;
     /** @internal */
     get committed(): Spend;
-    /** @internal */
-    commit(s: Spend): void;
+    /** Count one executor completion made during this visit (judge, retry reflection, screen). */
+    meter(kind: SpendKind, usage: NodeUsage | undefined): BudgetOverrun | undefined;
+    /** @internal See {@link BudgetGuard.commit}. */
+    commit(s: Spend, kind: SpendKind, counted: boolean): void;
 }
 /** One agent run. Its `signal` is the caller's signal plus a budget stop. */
 export declare class BudgetAttempt {
@@ -101,6 +165,8 @@ export declare class BudgetAttempt {
     private readonly controller;
     private live;
     private liveUsage;
+    /** A live report carried tokens or cost. */
+    private liveReported;
     private stopped;
     private settled;
     private readonly onOuterAbort;