@gr8ful/spf 0.19.0 → 0.19.1

package/dist/core/agent_flue.js

@@ -317,8 +317,18 @@ const SfAgent = Object.assign(sfAgentRender, {
 });
 const pendingUsage = new Map();
 let runtimePromise = null;
-function ensureRuntime(flueDbPath) {
+/**
+ * `requestTimeoutMs` (from `defaults.request_timeout_ms`) only has an effect
+ * on the FIRST call — `SfAgent.durability` is a static Flue reads once, and
+ * `runtimePromise` below already memoizes `start()` to run once per process.
+ * A later call with a different value is silently ignored, same as `start()`
+ * itself already is; every dispatch in one `spf` process shares one config
+ * anyway, so this can't happen in practice outside a test harness.
+ */
+function ensureRuntime(flueDbPath, requestTimeoutMs) {
     if (!runtimePromise) {
+        if (requestTimeoutMs !== undefined)
+            SfAgent.durability = { timeoutMs: requestTimeoutMs };
         runtimePromise = start({ agents: [SfAgent], db: sqlite(flueDbPath) }).then((flue) => {
             observe((event) => {
                 if (event.type !== "turn" || !event.submissionId)
@@ -394,8 +404,35 @@ export async function run(request, onEvent, onSpawn, onExit) {
     // imports this module for `resolveModel()` alone (doctor.ts, interview.ts)
     // without ever dispatching an ollama call.
     const [provider, modelId] = resolveModel(request.model);
+    // Outbound OTel propagation (SPF's otel-sdk extension) — see
+    // `otel_propagation.ts`'s own header for what this does and does not
+    // guarantee. `request.otel` is set only when `observability.otel` is
+    // configured for this run (see `agents.ts`'s `send()`); the installer is
+    // itself a no-op on `undefined` AND idempotent across every later call in
+    // this same process, so this costs nothing for a repo that hasn't
+    // configured otel and installs at most once for one that has. Called
+    // BEFORE `registerOllamaModel` below (not after, as an earlier version had
+    // it): `ollama_provider.ts`'s `modelFor()`/`resolve()` both consult
+    // `isFluePropagationInstalled()` to decide whether THEY need to supply
+    // `traceparent`/`x-correlation-id`/`x-spf-agent` themselves — if
+    // installation happened AFTER the first registration in a run that has
+    // otel configured, that first model would be built (and cached in
+    // `Model.headers`) believing propagation wasn't installed yet, then keep
+    // stale static headers alongside the instrumentation's own per-request
+    // ones for the rest of the process (a duplicate-header bug, same shape as
+    // BLOCKER A). Installing first means every registration in this run sees
+    // the SAME, final installed-state.
+    installFluePropagation(request.otel);
+    // `adw_id`/`agent_name` (when the caller supplied them — see
+    // `data_types.ts`'s `AgentRequest` doc) become this model id's static
+    // `x-correlation-id`/`x-spf-agent` gateway headers, re-stamped on every
+    // call — see `ollama_provider.ts`'s "Gateway headers" section and
+    // `registerOllamaModel`'s own doc (MAJOR-D) for why this must run every
+    // time, not just on first registration, and why it's a no-op for these
+    // two headers specifically once otel propagation is installed (see
+    // `registerFlueSessionTrace` below instead, in that case).
     if (provider === "ollama")
-        await registerOllamaModel(modelId);
+        await registerOllamaModel(modelId, { adwId: request.adw_id, agentName: request.agent_name });
     // Cloudflare Workers AI is the same self-registration shape as Ollama
     // (no pi-ai/Flue built-in "cloudflare" provider on Node) — see
     // cloudflare_provider.ts's header comment for the Workers AI OpenAI-
@@ -403,15 +440,7 @@ export async function run(request, onEvent, onSpawn, onExit) {
     // real-Bearer-token (not dummy-key) auth.
     if (provider === "cloudflare")
         await registerCloudflareModel(modelId);
-    // Outbound OTel propagation (SPF's otel-sdk extension) — see
-    // `otel_propagation.ts`'s own header for what this does and does not
-    // guarantee. `request.otel` is set only when `observability.otel` is
-    // configured for this run (see `agents.ts`'s `send()`); the installer is
-    // itself a no-op on `undefined` AND idempotent across every later call in
-    // this same process, so this costs nothing for a repo that hasn't
-    // configured otel and installs at most once for one that has.
-    installFluePropagation(request.otel);
-    await ensureRuntime(request.flue_db_path);
+    await ensureRuntime(request.flue_db_path, request.request_timeout_ms);
     REGISTRY.set(request.session_id, {
         model: request.model,
         thinking: request.thinking,
@@ -436,9 +465,17 @@ export async function run(request, onEvent, onSpawn, onExit) {
     // async context is captured by the first dispatch that started it, so a
     // dispatch-time context wrap would silently mis-attribute every later
     // agent's spans into the FIRST agent's trace. No-op when otel is
-    // unconfigured.
-    if (request.otel)
-        registerFlueSessionTrace(request.session_id, request.otel.traceparent);
+    // unconfigured. The SAME registration also carries `adw_id`/`agent_name`
+    // (MAJOR-D) — `otel_propagation.ts`'s `GatewayHeadersPropagator` reads
+    // them back per real outbound call this session makes, exactly the way
+    // `resolveFlueRootContext` already reads `traceparent` back per span.
+    if (request.otel) {
+        registerFlueSessionTrace(request.session_id, {
+            traceparent: request.otel.traceparent,
+            adwId: request.adw_id,
+            agentName: request.agent_name,
+        });
+    }
     const receipt = await handle.dispatch(request.prompt);
     const slot = { usage: new UsageBreakdown(), context_tokens: 0 };
     pendingUsage.set(receipt.submissionId, slot);

package/dist/core/agent_opencode.d.ts

@@ -70,32 +70,61 @@
  * documented gap in both guarantees, not a bug this module can paper over
  * from the outside.
  *
- * OUTBOUND OTEL PROPAGATION [OFFICIAL config surface; best-effort
- * behavior]: when `request.otel` is present (`agents.ts`'s `send()` threads
- * it only when `observability.otel` is configured — absent otherwise, and
- * this whole path is byte-identical to before), this module propagates
- * trace context two ways:
+ * OUTBOUND OTEL + GATEWAY-HEADER PROPAGATION [OFFICIAL config surface;
+ * best-effort behavior]: `request.otel` is present only when
+ * `observability.otel` is configured (`agents.ts`'s `send()`); `request.
+ * adw_id`/`request.agent_name` are present on EVERY call regardless (the
+ * gateway needs `x-correlation-id`/`x-spf-agent` whether or not SPF's own
+ * otel export is on — see `data_types.ts`'s `AgentRequest.adw_id` doc). This
+ * module propagates whatever subset of the two is present, two ways:
  *
  *   1. `TRACEPARENT` on the child's env — the standard W3C env var, same
- *      shape `agent_cc.ts` sets. No published statement confirms the
- *      opencode CLI itself reads it (UNVERIFIED either way; set for parity
- *      and for any opencode-spawned subprocess telemetry, at zero cost).
- *   2. `traceparent` + `x-request-id` as STATIC provider headers in the
- *      temp `opencode.json` (`provider.<id>.options.headers` — opencode's
- *      documented per-provider options surface;
+ *      shape `agent_cc.ts` sets, ONLY when `otel` is present. No published
+ *      statement confirms the opencode CLI itself reads it (UNVERIFIED
+ *      either way; set for parity and for any opencode-spawned subprocess
+ *      telemetry, at zero cost).
+ *   2. `traceparent` (when `otel` present) and `x-correlation-id`/
+ *      `x-spf-agent` (when `adw_id`/`agent_name` present) as STATIC provider
+ *      headers in the temp `opencode.json` (`provider.<id>.options.headers`
+ *      — opencode's documented per-provider options surface;
  *      https://opencode.ai/docs/providers/). Static values are CORRECT
  *      here, unlike the general case, because one `opencode run` subprocess
- *      IS exactly one SPF agent call — the traceparent can never go stale
- *      mid-run. This is the header that actually reaches the wire:
- *      opencode's provider requests flow through the AI SDK, which honors
- *      `options.headers` for that provider's requests. Subject to the
- *      CONFIG PRECEDENCE limitation above: a repo's own `opencode.json` can
- *      override these headers.
+ *      IS exactly one SPF agent call — none of these three headers can go
+ *      stale mid-run. This is the header set that actually reaches the
+ *      wire: opencode's provider requests flow through the AI SDK, which
+ *      honors `options.headers` for that provider's requests. Subject to
+ *      the CONFIG PRECEDENCE limitation above: a repo's own `opencode.json`
+ *      can override these headers. `x-request-id` is NEVER one of them —
+ *      Envoy/Switchyard own that header end-to-end; this module used to
+ *      send it here (BLOCKER B) and no longer does.
  *
  * `injectOtelEnv()` / `otelProviderHeaders()` / `tempConfigContents()` are
  * exported pure functions so every fragment is unit-testable without
  * spawning a real subprocess — same discipline as the rest of this module.
  *
+ * MINOR-4 (deliberate, not an oversight): `otelProviderHeaders()` returns
+ * non-null — and so `tempConfigContents()` writes a real `provider` block —
+ * whenever EITHER `otel` OR `gateway.adwId`/`gateway.agentName` is present,
+ * and `data_types.ts`'s `AgentRequest.adw_id`/`agent_name` doc is explicit
+ * that those two are set by `agents.ts`'s `send()` from `run.adw_id`/
+ * `agent.name` UNCONDITIONALLY — every SPF run has an adw_id, every agent
+ * has a name — NOT gated on `observability.otel` being configured at all.
+ * The practical consequence: for any `opencode` agent whose `--model`
+ * carries a `provider/` prefix (opencode's own documented model-id shape;
+ * see `otelProviderHeaders`'s own doc for the bare-model-name exception),
+ * this module writes a temporary `opencode.json` (`mkdtempSync` + one
+ * `writeFileSync`, removed in `run()`'s `finally`) on EVERY invocation, even
+ * with `observability.otel` unconfigured and no `tools:` restriction in
+ * play — there is no "otel off, no gateway identity, no tools restriction"
+ * case left in practice once a run has an adw_id, which is always. This is
+ * KEPT, not gated behind an extra "only when otel/tools apply" check: the
+ * gateway needs `x-correlation-id`/`x-spf-agent` on every real call to group
+ * it by run (same rationale as `ollama_provider.ts`'s static per-model
+ * headers), independent of whether tracing is turned on, and a temp file
+ * per subprocess invocation is cheap relative to spawning that subprocess
+ * at all. A caller that truly wants zero config-file overhead has no lever
+ * for that today short of clearing `adw_id`/`agent_name` on the request.
+ *
  * OPERATOR-CONFIG MERGE: when a caller-provided `OPENCODE_CONFIG` already
  * exists in the base env (operatorEnv() passthrough or an agent's
  * env_allowlist) AND this module needs a temp config of its own (a tools:
@@ -257,22 +286,30 @@ export declare function isKnownToolName(name: string): boolean;
 export declare function injectOtelEnv(baseEnv: Record<string, string>, otel: AgentRequest["otel"] | undefined): Record<string, string>;
 export interface OpencodeOtelHeaders {
     provider: string;
-    headers: {
-        traceparent: string;
-        "x-request-id": string;
-    };
+    /** Never carries `x-request-id` — see the module doc comment's OUTBOUND OTEL + GATEWAY-HEADER PROPAGATION section. */
+    headers: Record<string, string>;
+}
+/** This call's own SPF identity, when the caller has it — see `data_types.ts`'s `AgentRequest.adw_id`/`agent_name` doc. Both optional; an absent one simply omits its header. */
+export interface GatewayCallIdentity {
+    adwId?: string;
+    agentName?: string;
 }
 /**
  * Builds the `provider.<id>.options.headers` fragment for a temp
- * `opencode.json` (see the module doc comment's OUTBOUND OTEL PROPAGATION
- * section for why static values are correct here). Returns `null` when
- * `otel` is absent, or when the model id carries no `provider/` prefix —
+ * `opencode.json` (see the module doc comment's OUTBOUND OTEL + GATEWAY-
+ * HEADER PROPAGATION section for why static values are correct here).
+ * Returns `null` when NEITHER `otel` nor `gateway` has anything to
+ * contribute, or when the model id carries no `provider/` prefix —
  * opencode's own `--model` vocabulary is documented as `provider/model-id`,
  * but a bare model name has no provider id this module could key headers
  * under, and guessing the wrong provider id would write a config block
  * opencode merges onto a DIFFERENT provider than the one being called.
+ * `x-correlation-id`/`x-spf-agent` are added whenever `gateway` supplies
+ * them, regardless of whether `otel` is configured — see
+ * `data_types.ts`'s `AgentRequest.adw_id` doc for why that pair isn't
+ * gated on `observability.otel` the way `traceparent` is.
  */
-export declare function otelProviderHeaders(model: string, otel: AgentRequest["otel"] | undefined): OpencodeOtelHeaders | null;
+export declare function otelProviderHeaders(model: string, otel: AgentRequest["otel"] | undefined, gateway?: GatewayCallIdentity): OpencodeOtelHeaders | null;
 /**
  * Builds the JSON CONTENT of the temp `opencode.json`: a `permission` map
  * when `toolNames` is an array (including `[]` — restrict to exactly those,

package/dist/core/agent_opencode.js

@@ -70,32 +70,61 @@
  * documented gap in both guarantees, not a bug this module can paper over
  * from the outside.
  *
- * OUTBOUND OTEL PROPAGATION [OFFICIAL config surface; best-effort
- * behavior]: when `request.otel` is present (`agents.ts`'s `send()` threads
- * it only when `observability.otel` is configured — absent otherwise, and
- * this whole path is byte-identical to before), this module propagates
- * trace context two ways:
+ * OUTBOUND OTEL + GATEWAY-HEADER PROPAGATION [OFFICIAL config surface;
+ * best-effort behavior]: `request.otel` is present only when
+ * `observability.otel` is configured (`agents.ts`'s `send()`); `request.
+ * adw_id`/`request.agent_name` are present on EVERY call regardless (the
+ * gateway needs `x-correlation-id`/`x-spf-agent` whether or not SPF's own
+ * otel export is on — see `data_types.ts`'s `AgentRequest.adw_id` doc). This
+ * module propagates whatever subset of the two is present, two ways:
  *
  *   1. `TRACEPARENT` on the child's env — the standard W3C env var, same
- *      shape `agent_cc.ts` sets. No published statement confirms the
- *      opencode CLI itself reads it (UNVERIFIED either way; set for parity
- *      and for any opencode-spawned subprocess telemetry, at zero cost).
- *   2. `traceparent` + `x-request-id` as STATIC provider headers in the
- *      temp `opencode.json` (`provider.<id>.options.headers` — opencode's
- *      documented per-provider options surface;
+ *      shape `agent_cc.ts` sets, ONLY when `otel` is present. No published
+ *      statement confirms the opencode CLI itself reads it (UNVERIFIED
+ *      either way; set for parity and for any opencode-spawned subprocess
+ *      telemetry, at zero cost).
+ *   2. `traceparent` (when `otel` present) and `x-correlation-id`/
+ *      `x-spf-agent` (when `adw_id`/`agent_name` present) as STATIC provider
+ *      headers in the temp `opencode.json` (`provider.<id>.options.headers`
+ *      — opencode's documented per-provider options surface;
  *      https://opencode.ai/docs/providers/). Static values are CORRECT
  *      here, unlike the general case, because one `opencode run` subprocess
- *      IS exactly one SPF agent call — the traceparent can never go stale
- *      mid-run. This is the header that actually reaches the wire:
- *      opencode's provider requests flow through the AI SDK, which honors
- *      `options.headers` for that provider's requests. Subject to the
- *      CONFIG PRECEDENCE limitation above: a repo's own `opencode.json` can
- *      override these headers.
+ *      IS exactly one SPF agent call — none of these three headers can go
+ *      stale mid-run. This is the header set that actually reaches the
+ *      wire: opencode's provider requests flow through the AI SDK, which
+ *      honors `options.headers` for that provider's requests. Subject to
+ *      the CONFIG PRECEDENCE limitation above: a repo's own `opencode.json`
+ *      can override these headers. `x-request-id` is NEVER one of them —
+ *      Envoy/Switchyard own that header end-to-end; this module used to
+ *      send it here (BLOCKER B) and no longer does.
  *
  * `injectOtelEnv()` / `otelProviderHeaders()` / `tempConfigContents()` are
  * exported pure functions so every fragment is unit-testable without
  * spawning a real subprocess — same discipline as the rest of this module.
  *
+ * MINOR-4 (deliberate, not an oversight): `otelProviderHeaders()` returns
+ * non-null — and so `tempConfigContents()` writes a real `provider` block —
+ * whenever EITHER `otel` OR `gateway.adwId`/`gateway.agentName` is present,
+ * and `data_types.ts`'s `AgentRequest.adw_id`/`agent_name` doc is explicit
+ * that those two are set by `agents.ts`'s `send()` from `run.adw_id`/
+ * `agent.name` UNCONDITIONALLY — every SPF run has an adw_id, every agent
+ * has a name — NOT gated on `observability.otel` being configured at all.
+ * The practical consequence: for any `opencode` agent whose `--model`
+ * carries a `provider/` prefix (opencode's own documented model-id shape;
+ * see `otelProviderHeaders`'s own doc for the bare-model-name exception),
+ * this module writes a temporary `opencode.json` (`mkdtempSync` + one
+ * `writeFileSync`, removed in `run()`'s `finally`) on EVERY invocation, even
+ * with `observability.otel` unconfigured and no `tools:` restriction in
+ * play — there is no "otel off, no gateway identity, no tools restriction"
+ * case left in practice once a run has an adw_id, which is always. This is
+ * KEPT, not gated behind an extra "only when otel/tools apply" check: the
+ * gateway needs `x-correlation-id`/`x-spf-agent` on every real call to group
+ * it by run (same rationale as `ollama_provider.ts`'s static per-model
+ * headers), independent of whether tracing is turned on, and a temp file
+ * per subprocess invocation is cheap relative to spawning that subprocess
+ * at all. A caller that truly wants zero config-file overhead has no lever
+ * for that today short of clearing `adw_id`/`agent_name` on the request.
+ *
  * OPERATOR-CONFIG MERGE: when a caller-provided `OPENCODE_CONFIG` already
  * exists in the base env (operatorEnv() passthrough or an agent's
  * env_allowlist) AND this module needs a temp config of its own (a tools:
@@ -413,21 +442,33 @@ export function injectOtelEnv(baseEnv, otel) {
 }
 /**
  * Builds the `provider.<id>.options.headers` fragment for a temp
- * `opencode.json` (see the module doc comment's OUTBOUND OTEL PROPAGATION
- * section for why static values are correct here). Returns `null` when
- * `otel` is absent, or when the model id carries no `provider/` prefix —
+ * `opencode.json` (see the module doc comment's OUTBOUND OTEL + GATEWAY-
+ * HEADER PROPAGATION section for why static values are correct here).
+ * Returns `null` when NEITHER `otel` nor `gateway` has anything to
+ * contribute, or when the model id carries no `provider/` prefix —
  * opencode's own `--model` vocabulary is documented as `provider/model-id`,
  * but a bare model name has no provider id this module could key headers
  * under, and guessing the wrong provider id would write a config block
  * opencode merges onto a DIFFERENT provider than the one being called.
+ * `x-correlation-id`/`x-spf-agent` are added whenever `gateway` supplies
+ * them, regardless of whether `otel` is configured — see
+ * `data_types.ts`'s `AgentRequest.adw_id` doc for why that pair isn't
+ * gated on `observability.otel` the way `traceparent` is.
  */
-export function otelProviderHeaders(model, otel) {
-    if (!otel)
-        return null;
+export function otelProviderHeaders(model, otel, gateway = {}) {
     const slash = model.indexOf("/");
     if (slash <= 0)
         return null;
-    return { provider: model.slice(0, slash), headers: { traceparent: otel.traceparent, "x-request-id": otel.x_request_id } };
+    const headers = {};
+    if (otel)
+        headers.traceparent = otel.traceparent;
+    if (gateway.adwId)
+        headers["x-correlation-id"] = gateway.adwId;
+    if (gateway.agentName)
+        headers["x-spf-agent"] = gateway.agentName;
+    if (Object.keys(headers).length === 0)
+        return null;
+    return { provider: model.slice(0, slash), headers };
 }
 /**
  * Builds the JSON CONTENT of the temp `opencode.json`: a `permission` map
@@ -601,12 +642,12 @@ export async function run(request, onEvent, onSpawn, onExit) {
     const [cmd, ...cmdArgs] = cmdTokens;
     const fullArgs = [...cmdArgs, ...args];
     const baseEnv = request.env ?? operatorEnv();
-    // `request.tools` null/undefined AND no otel config -> every tool, no
-    // config file written at all (see tempConfigContents' own doc comment).
-    // Otherwise -> a real temp opencode.json (tool restriction, OTel provider
-    // headers, or both), pointed at via OPENCODE_CONFIG on the CHILD's env
-    // only — never mutates process.env.
-    const otelHeaders = otelProviderHeaders(request.model, request.otel);
+    // `request.tools` null/undefined AND no otel config AND no adw_id/agent_name
+    // -> every tool, no config file written at all (see tempConfigContents'
+    // own doc comment). Otherwise -> a real temp opencode.json (tool
+    // restriction, gateway provider headers, or both), pointed at via
+    // OPENCODE_CONFIG on the CHILD's env only — never mutates process.env.
+    const otelHeaders = otelProviderHeaders(request.model, request.otel, { adwId: request.adw_id, agentName: request.agent_name });
     let configContents = tempConfigContents(request.tools, otelHeaders);
     // A caller-provided OPENCODE_CONFIG (operatorEnv() passthrough or an
     // agent's env_allowlist) is MERGED into the temp file, never replaced —

package/dist/core/agents.d.ts

@@ -37,15 +37,56 @@ export declare class BudgetExceeded extends Error {
  * message that says `$0.00 of max_run_cost $0.40` tells nobody anything.
  */
 export declare function formatUsd(value: number): string;
+/**
+ * True when THIS ONE AGENT, if dispatched right now, would report a
+ * gateway-estimated cost — a `claude_code` agent AND a non-Anthropic
+ * `ANTHROPIC_BASE_URL`. The per-agent primitive `Run.recordDispatch`
+ * (`runner.ts`) calls AT DISPATCH TIME, in `execute()` below, right before
+ * the real coding-agent call — so `run.cost_is_estimate` reflects what this
+ * run actually DISPATCHED, never what the roster merely makes possible (see
+ * `isGatewayEstimatedCost`'s own doc comment for why that distinction is
+ * the whole point of this function existing separately).
+ *
+ * `env` defaults to `process.env` (already carrying `cfg.env`'s own
+ * defaults — see `applyConfigEnv`, applied once at CLI startup before any
+ * `Run` is constructed) but is overridable so a test never touches the
+ * real environment.
+ */
+export declare function isGatewayEstimatedDispatch(agent: AgentConfig, env?: Record<string, string | undefined>): boolean;
+/**
+ * Whole-ROSTER check: true when ANY configured agent (dispatched or not)
+ * is a `claude_code` agent AND `ANTHROPIC_BASE_URL` is non-Anthropic.
+ *
+ * NOT what `Run.cost_is_estimate` is computed from — a chain can configure
+ * a `claude_code` agent it never actually dispatches this run (a
+ * conditional phase, a different `--agent` override, ...), and labeling a
+ * real, non-gateway cost as "estimated" because the ROSTER merely contains
+ * such an agent would be its own kind of dishonesty. `Run` instead starts
+ * `cost_is_estimate` at `false` and `recordDispatch()` (`runner.ts`, driven
+ * by `isGatewayEstimatedDispatch` above) flips it true only when a
+ * qualifying dispatch actually happens. This whole-roster version is kept
+ * as the general "could this config ever need the estimate label" check
+ * (`spf estimate`-shaped questions, and this file's own test suite) — never
+ * wire it back into the per-run label.
+ */
+export declare function isGatewayEstimatedCost(cfg: SFConfig, env?: Record<string, string | undefined>): boolean;
 /**
  * The accumulating totals a budget check reads. Structurally a subset of
- * `Run` (`core/runner.ts`) — `run.tokens`/`run.cost` are incremented by
- * `run.addUsage()` after every send — so the real `Run` satisfies it with no
- * adapter, and a test can pass a plain object with fake usage.
+ * `Run` (`core/runner.ts`) — `run.tokens`/`run.cost`/`run.billable_tokens`
+ * are incremented by `run.addUsage()` after every send — so the real `Run`
+ * satisfies it with no adapter, and a test can pass a plain object with fake
+ * usage.
+ *
+ * `tokens` (the display total, cache reads included) is kept on this
+ * interface for structural parity with `Run` even though `assertRunBudget`
+ * itself no longer reads it — only `billable_tokens` does. See
+ * `UsageBreakdown.billable_tokens`'s doc comment (`data_types.ts`) for why
+ * the two diverge.
  */
 export interface RunBudgetState {
     cfg: SFConfig;
     tokens: number;
+    billable_tokens: number;
     cost: number;
 }
 /**
@@ -122,6 +163,8 @@ interface RunForAgents {
     /** Run-total tokens/cost so far, mirrored by `addUsage` below — read by `assertRunBudget` before every send. */
     tokens: number;
     cost: number;
+    /** The BILLABLE half of `tokens` — what `assertRunBudget` actually checks `max_run_tokens` against. See `UsageBreakdown.billable_tokens`'s doc comment. */
+    billable_tokens: number;
     repo_root: string;
     spf_dir: string | null;
     data_dir: string;
@@ -159,8 +202,12 @@ interface RunForAgents {
         retry: (name: string, attempt: number, limit: number, reason: string) => Promise<void>;
         envelopeSummary: (envelope: EnvelopeBase, typeName: string) => Promise<void>;
         agentFinished: (name: string, tokens: number, cost: number) => Promise<void>;
+        /** Free-form detail line — used here only to name a `defaults.read_only_ignore` restore so it's visible without failing the phase. */
+        note: (message: string) => Promise<void>;
     };
-    addUsage: (tokens: number, cost: number) => Promise<void>;
+    addUsage: (tokens: number, cost: number, billableTokens: number) => Promise<void>;
+    /** See `Run.recordDispatch`'s own doc comment (`runner.ts`) and `isGatewayEstimatedDispatch` above — called once per real dispatch, before it happens. */
+    recordDispatch: (agent: AgentConfig) => void;
     saveAgentMap: (agent: string, entry: {
         session_id: string;
         model: string;

package/dist/core/agents.js

@@ -69,6 +69,68 @@ export function formatUsd(value) {
     const fixed = value.toFixed(3);
     return `$${fixed.endsWith("0") ? fixed.slice(0, -1) : fixed}`;
 }
+/** Anthropic's own API — a `claude_code` agent talking to exactly this is billed honestly; anything else is a gateway/proxy standing in for it. */
+const ANTHROPIC_DEFAULT_BASE_URL_RE = /^https:\/\/api\.anthropic\.com\/?$/i;
+/**
+ * WHY THIS MATTERS: `agent_cc.ts`'s `run()` reports `final.total_cost_usd`
+ * (the `claude` CLI's OWN number) into `UsageBreakdown.total_cost` verbatim
+ * — that figure is Anthropic's price table applied to whichever model the
+ * CLI thinks it called, computed CLIENT-SIDE with no visibility into what
+ * actually served the request. Pointed at a gateway (Ollama Cloud, a
+ * Cloudflare AI Gateway proxy, ...) fronting a different provider/billing
+ * model entirely (subscription, flat per-token gateway price, ...), that
+ * number is a plausible-looking ESTIMATE of what Anthropic would have
+ * charged for this many tokens — not a fact about what was actually billed.
+ * `Console.sessionFinished` reads this to change the run summary's "cost"
+ * line from a bare dollar figure to a labeled estimate rather than silently
+ * presenting a guess as ground truth.
+ */
+function usesNonAnthropicGateway(env) {
+    const baseUrl = env["ANTHROPIC_BASE_URL"];
+    if (!baseUrl || !baseUrl.trim())
+        return false;
+    return !ANTHROPIC_DEFAULT_BASE_URL_RE.test(baseUrl.trim());
+}
+/**
+ * True when THIS ONE AGENT, if dispatched right now, would report a
+ * gateway-estimated cost — a `claude_code` agent AND a non-Anthropic
+ * `ANTHROPIC_BASE_URL`. The per-agent primitive `Run.recordDispatch`
+ * (`runner.ts`) calls AT DISPATCH TIME, in `execute()` below, right before
+ * the real coding-agent call — so `run.cost_is_estimate` reflects what this
+ * run actually DISPATCHED, never what the roster merely makes possible (see
+ * `isGatewayEstimatedCost`'s own doc comment for why that distinction is
+ * the whole point of this function existing separately).
+ *
+ * `env` defaults to `process.env` (already carrying `cfg.env`'s own
+ * defaults — see `applyConfigEnv`, applied once at CLI startup before any
+ * `Run` is constructed) but is overridable so a test never touches the
+ * real environment.
+ */
+export function isGatewayEstimatedDispatch(agent, env = process.env) {
+    return agent.coding_agent === "claude_code" && usesNonAnthropicGateway(env);
+}
+/**
+ * Whole-ROSTER check: true when ANY configured agent (dispatched or not)
+ * is a `claude_code` agent AND `ANTHROPIC_BASE_URL` is non-Anthropic.
+ *
+ * NOT what `Run.cost_is_estimate` is computed from — a chain can configure
+ * a `claude_code` agent it never actually dispatches this run (a
+ * conditional phase, a different `--agent` override, ...), and labeling a
+ * real, non-gateway cost as "estimated" because the ROSTER merely contains
+ * such an agent would be its own kind of dishonesty. `Run` instead starts
+ * `cost_is_estimate` at `false` and `recordDispatch()` (`runner.ts`, driven
+ * by `isGatewayEstimatedDispatch` above) flips it true only when a
+ * qualifying dispatch actually happens. This whole-roster version is kept
+ * as the general "could this config ever need the estimate label" check
+ * (`spf estimate`-shaped questions, and this file's own test suite) — never
+ * wire it back into the per-run label.
+ */
+export function isGatewayEstimatedCost(cfg, env = process.env) {
+    const usesClaudeCode = cfg.agents.some((a) => a.coding_agent === "claude_code");
+    if (!usesClaudeCode)
+        return false;
+    return usesNonAnthropicGateway(env);
+}
 /**
  * Throw if this run has spent its budget. Called BEFORE every agent
  * dispatch, never after.
@@ -92,8 +154,8 @@ export function assertRunBudget(run) {
         throw new BudgetExceeded(`run budget exceeded: ${formatUsd(run.cost)} of max_run_cost ${formatUsd(maxCost)} — ` +
             `raise defaults.max_run_cost or split the work`);
     }
-    if (maxTokens !== undefined && run.tokens >= maxTokens) {
-        throw new BudgetExceeded(`run budget exceeded: ${run.tokens.toLocaleString("en-US")} tokens of max_run_tokens ` +
+    if (maxTokens !== undefined && run.billable_tokens >= maxTokens) {
+        throw new BudgetExceeded(`run budget exceeded: ${run.billable_tokens.toLocaleString("en-US")} tokens of max_run_tokens ` +
             `${maxTokens.toLocaleString("en-US")} — raise defaults.max_run_tokens or split the work`);
     }
 }
@@ -833,8 +895,11 @@ export async function execute(run, phase, call) {
             output_type_name: call.output_type.name,
             cwd: spec ? spec.workspace_dir : run.repo_root,
             flue_db_path: path.join(run.data_dir, "flue.db"),
+            request_timeout_ms: run.cfg.defaults.request_timeout_ms,
             env: agentEnv(agent),
             sandbox: spec,
+            adw_id: run.adw_id,
+            agent_name: agent.name,
             otel: otelCtx && otelBlock
                 ? {
                     traceparent: otelCtx.traceparent,
@@ -854,6 +919,9 @@ export async function execute(run, phase, call) {
         const onExit = (pid) => void run.tracer.processEnd(run.adw_id, pid).catch(() => { });
         if (spec)
             await sandbox.reconcileWorkspace(spec);
+        // Recorded right before the real dispatch, not derived from the roster
+        // up front — see `isGatewayEstimatedDispatch`'s doc comment for why.
+        run.recordDispatch(agent);
         let result;
         if (agent.coding_agent === "claude_code") {
             result = await agentCc.run(request, forward, onSpawn, onExit);
@@ -866,7 +934,7 @@ export async function execute(run, phase, call) {
         }
         // SPEND IS RECORDED BEFORE THE EXTRACT CAN THROW: a failed extract must
         // not also lose this call's tokens/cost off the Run's ledger.
-        await run.addUsage(result.tokens, result.cost);
+        await run.addUsage(result.tokens, result.cost, result.usage.billable_tokens);
         spent.merge(result.usage);
         // opencode-ONLY: every subsequent send() in THIS phase (JSON-repair
         // retries, gate corrections) must target the real captured session, not
@@ -934,7 +1002,14 @@ export async function execute(run, phase, call) {
     // wrote somewhere it was not allowed to.
     let touched;
     try {
-        touched = permissions.enforce(run, phase, agent, treeBefore);
+        touched = permissions.enforce(run, phase, agent, treeBefore, (ignoredPaths) => {
+            // Fire-and-forget, same discipline as onSpawn/onExit above: this is a
+            // logging side effect off the main control flow, not something a
+            // failed write here should turn into an unhandled rejection.
+            void run.console
+                .note(`${agent.name}: restored and ignored dependency-lockfile churn (defaults.read_only_ignore) without failing the phase: ${ignoredPaths.join(", ")}`)
+                .catch(() => { });
+        });
     }
     catch (breach) {
         await run.tracer.event(makeEventRecord({

package/dist/core/console.d.ts

@@ -27,7 +27,15 @@ interface Tracer {
 export interface RunObserver {
     onPhaseStart?(phase: Phase): void;
     onPhaseEnd?(phase: Phase, seconds: number): void;
-    onUsage?(tokens: number, cost: number): void;
+    /**
+     * `tokens` is the DISPLAY total (every re-sent token, cache reads
+     * included — context occupancy); `billableTokens` is what
+     * `defaults.max_run_tokens` actually checks (see
+     * `UsageBreakdown.billable_tokens`'s doc comment in `data_types.ts`). A
+     * dashboard comparing spend against the ceiling must compare
+     * `billableTokens`, never `tokens` — see `run_dashboard.tsx`.
+     */
+    onUsage?(tokens: number, cost: number, billableTokens: number): void;
     onSessionEnd?(ok: boolean): void;
 }
 /** Bound to one run's tracer. Reachable as `run.console` everywhere. */
@@ -71,13 +79,25 @@ export declare class Console {
     observer?: RunObserver | null);
     private emit;
     sessionStarted(adwId: string, engineer: string): Promise<void>;
-    sessionFinished(ok: boolean, tokens: number, cost: number, dbPath: string): Promise<void>;
+    /**
+     * `costIsEstimate` (default `false`, byte-identical to before this param
+     * existed): true when `run.cost_is_estimate` found a `claude_code` agent
+     * pointed at a non-Anthropic `ANTHROPIC_BASE_URL` (see `runner.ts`'s
+     * `Run.recordDispatch` / `agents.ts`'s `isGatewayEstimatedDispatch`) —
+     * `total_cost_usd` from `claude`'s own CLI is
+     * Anthropic's price table applied client-side, which is a fact only when
+     * Anthropic itself served the request, and a labeled guess otherwise. The
+     * label is cosmetic only: `cost` itself is unchanged (still the real sum
+     * `UsageBreakdown.total_cost` accumulated), and nothing about the budget
+     * check (`assertRunBudget`) reads this flag.
+     */
+    sessionFinished(ok: boolean, tokens: number, cost: number, dbPath: string, costIsEstimate?: boolean): Promise<void>;
     phaseStarted(phase: Phase): Promise<void>;
     phaseEnded(phase: Phase, seconds: number): Promise<void>;
     /** Free-form detail inside the current phase — what `ph.log()` recorded. */
     note(message: string): Promise<void>;
-    /** `Run.addUsage()`'s only hook into `Console` — the running total lives on `Run`, not here, so this just forwards it to the observer. No line prints for this on its own; the totals already show up in `sessionFinished`'s panel. */
-    notifyUsage(tokens: number, cost: number): Promise<void>;
+    /** `Run.addUsage()`'s only hook into `Console` — the running totals live on `Run`, not here, so this just forwards them to the observer. No line prints for this on its own; the totals already show up in `sessionFinished`'s panel. `billableTokens` rides alongside `tokens` so a consumer comparing against `defaults.max_run_tokens` (a billable ceiling) never has to guess which number to use — see `RunObserver.onUsage`'s own doc comment. */
+    notifyUsage(tokens: number, cost: number, billableTokens: number): Promise<void>;
     agentStarted(name: string, model: string, sessionId: string): Promise<void>;
     agentFinished(name: string, tokens: number, cost: number): Promise<void>;
     retry(name: string, attempt: number, limit: number, reason: string): Promise<void>;