@gr8ful/spf 0.19.0 → 0.19.1

package/README.md

@@ -240,6 +240,10 @@ ANTHROPIC_CUSTOM_HEADERS=cf-aig-authorization: Bearer <CF_AIG_TOKEN>
 
 Agent isolation in SPF is enforced **after the fact**, not upfront. This matters because the `tools:` capability list is not a sandbox — a `bash` tool can run `git checkout` to discard changes, and a `write` tool can reach any path, regardless of the allowlist you write. So permission is verified the way every other claim in this system is: the working tree is fingerprinted before an agent runs, then compared after. If the agent touched anything outside its `writes:` allowlist (or a `protected_files:` path it wasn't given access to), the phase fails and anything the agent *introduced* outside its allowlist is rolled back. What it cannot undo, it names: a file that was already dirty before the agent ran is left alone rather than discarded, and uncommitted work the agent reverted cannot be restored. And because the check is post-hoc and tree-scoped, nothing outside the working tree is in scope at all — a push, a network call, a write above `repo_root`. When running an agent on the claude_code backend, SPF spawns it with `--permission-mode bypassPermissions --dangerously-skip-permissions` because the backend has no need to enforce — SPF will enforce in code instead, within those bounds.
 
+One narrow, explicit exception: `defaults.read_only_ignore` (default: the lockfiles of npm/pnpm/yarn/bun) names paths a **true read-only** agent (`writes: []`) may touch without failing the phase — a read-only agent that runs a dependency-manager command to inspect a package's real shape rewrites its lockfile as a side effect of a *read*, not an edit. The path is still always rolled back; the phase only *passes* when the path was clean before the phase started (so the rollback is a real restore) — a path already dirty when the phase began fails exactly like any other breach, whether the agent left it modified or reverted an operator's own uncommitted work. And the exemption is scoped to true read-only roles only: a write-restricted agent (`writes: [...]`) that changes a lockfile alongside something it *was* given (say `package.json`) left an inconsistent tree, not incidental bookkeeping, and fails like any other breach.
+
+`protected_files` always takes precedence over `read_only_ignore`: a path matching `protected_files` is never exempt, even for a true read-only agent, even when it also happens to match a `read_only_ignore` pattern. `read_only_ignore` is a narrow "this churn is incidental" carve-out for dependency-manager bookkeeping — it is never a backdoor around a path an operator explicitly locked down with `protected_files`. That path is still rolled back like any ignored churn, but it fails the phase like any other breach.
+
 For unattended work, `spf watch`'s PR-merge is the only human accountability checkpoint: the daemon opens a PR for each automated run, and a human approves the merge. For any other workflow, this enforcement is the backbone of letting a bounded agent proposal survive code's inspection without a human having to read it in between — but it is bounded, not a sandbox, and the scope above is what a reviewer should actually rely on. (Attended `simple-sdlc` runs get a second checkpoint of their own — see below.)
 
 See `core/permissions.ts` for the implementation — the snapshot/compare logic, not the config terms.
@@ -821,6 +825,8 @@ Only the states you map are touched; an unmapped state keeps today's label-only
 
 `spf watch init` still doesn't create any labels here (Jira labels are freeform strings with no color/description registry to seed, unlike GitHub's) — it reports the labels this run will use. With `watch.refine.enabled`, it also validates `watch.jira.issue_types` against the real project's issue types, read-only, and exits non-zero on a mismatch — see "Refining specs" above. Independent of `refine.enabled`, if `watch.jira.status_map` has any entry configured, both `spf watch init` and `spf watch`'s own startup check validate it against the real project's statuses the same way, and exit non-zero on a mismatch.
 
+When refining a spec into a tree, the published root(s) get linked back to the spec they came from via `watch.jira.link_type` (default `"Relates"`), a plain Jira issue link — never the hierarchical `parent` field, since the spec's own issue type frequently can't legally parent a root node's type. **`link_type` must name a symmetric link type**: the code fixes which side is which (the published root is always `inwardIssue`, the spec always `outwardIssue`) rather than exposing direction as a separate config knob, which is harmless for a symmetric type like "Relates" but would silently assert the opposite relationship for a directional one (e.g. "blocks"). If the issue-link API itself is unavailable (a renamed/removed link type, a restrictive permission scheme), it falls back to a plain comment naming the spec — and if even that fails, it's logged and swallowed rather than failing the whole publish over what is, at bottom, a cosmetic cross-reference.
+
 ### Bitbucket (`code_host: bitbucket`)
 
 ```bash
@@ -911,6 +917,8 @@ Full field reference: `spf install-skill`'s installed skill
 
 Every run produces a complete trace: all events, phases, agent calls, and tool invocations stream into SQLite as they happen. By default the trace is local-only and stays the source of truth — prompts, envelopes, tool arguments, and your source code never leave the machine. Token counts and costs ride alongside.
 
+**Billable vs. total tokens.** Every token figure SPF reports is one of two numbers, and they diverge a lot on a long-running, prompt-caching session: the **display total** (`sessions.total_tokens`, the sessions panel's "tokens" line) counts every token re-sent on every turn, cache reads included — a 49-turn conversation over an 86k-token context bills millions of these even though only a fraction of that ever moved for the first time. The **billable** figure (`billable_tokens`) is `input + cache-write + output` only — material that actually entered the context for the first time or was newly generated — which is what `defaults.max_run_tokens` and `spf loop`'s `--max-tokens` are actually checked against, what `spf estimate`'s cutoff-phase projection walks, and what the live run dashboard compares against the ceiling (printing the display total alongside it, labeled "context incl. cache reads", for occupancy). A trace db from before this split existed just has `billable_tokens = 0` on every old row; every consumer that reads it back falls through to the display total for such a row rather than reporting a false zero.
+
 ```bash
 spf ui                           # browser-based visualizer over the trace
 spf events <adw_id> --follow    # live event stream, tailable

package/assets/skill/references/config.md

@@ -82,6 +82,7 @@ agents:
 | `data_dir` | path | Runtime home, repo-relative. Default `.spf/data`. |
 | `max_run_cost` | number > 0 (USD) | Stops the NEXT agent call once a run has already spent this much — checked before each call, never after. A single call is never capped (a run can overshoot by one whole call), and a chain with only one agent dispatch (`scout`, `prompt`, `build`) can never trip it at all. Absent (default) = unbounded. Throws `BudgetExceeded`, which fails the phase closed. |
 | `max_run_tokens` | integer > 0 | Same semantics as `max_run_cost`, on `sessions.total_tokens` instead of cost. Absent (default) = unbounded. |
+| `request_timeout_ms` | integer > 0 | `flue`-backend-only (maps onto `AgentStatics.durability.timeoutMs`; silently ignored for `claude_code`/`opencode`, which have no such knob). Bounds ONE agent dispatch, not the accumulated run. Absent (default) = Flue's own default applies unchanged (1 hour, 10 attempts) — a connection that dies silently mid-call hangs that long before anything notices. Not a precise deadline: Flue's own timeout check runs on a coarser periodic sweep in practice. Not back-filled onto agents — process-scoped, like `max_run_cost`/`max_run_tokens` above. |
 
 ### `spf fanout`
 

package/dist/cli/commands/doctor.js

@@ -18,7 +18,7 @@ import * as agentOpencode from "../../core/agent_opencode.js";
 import { DEFAULT_NOTIFY_ENV_KEY } from "../../core/notify/notifier.js";
 import { endpointLabel, redact, resolveTracesUrl } from "../../core/otel.js";
 import { isKnownToolName as isKnownFlueToolName, resolveModel } from "../../core/agent_flue.js";
-import { ollamaBaseUrl } from "../../core/ollama_provider.js";
+import { ollamaApiKey, ollamaBaseUrl } from "../../core/ollama_provider.js";
 import { cloudflareAiBaseUrl } from "../../core/cloudflare_provider.js";
 import { binaryOnPath, parseCli } from "../../core/utils.js";
 import { PROVIDER_ENV_KEYS } from "../../core/providers.js";
@@ -494,9 +494,31 @@ export async function doctorCommand(argv) {
         // latency either way — strictly cheaper for a pure reachability check,
         // and there's no live-server dependency in this choice: doctor's probe
         // itself tolerates either endpoint being down (see `probeGet`).
-        const result = await withProbeStatus("OLLAMA_BASE_URL reachability", () => probeGet(`${ollamaBase}/models`));
+        //
+        // MINOR-F (MINOR 3: now via ollamaApiKey(), not a raw env read) — send a
+        // bearer on every probe, same as the Cloudflare Workers AI probe below
+        // AND same as a real dispatch: `ollamaApiKey()` (ollama_provider.ts) is
+        // the SAME function `registerOllamaModel`'s `auth.apiKey.resolve()`
+        // calls, so this probe and a real dispatch send byte-identical bearers
+        // for the same `OLLAMA_API_KEY` env state — including the dummy
+        // placeholder when it's unset, which a prior version of this probe
+        // omitted entirely (no `Authorization` header at all), a real
+        // divergence from what dispatch actually sends. A bare local Ollama
+        // server (the common case) checks nothing and answers identically
+        // either way; a gateway in front of it (e.g. Briefs' Envoy AI Gateway)
+        // 401/403s an unauthenticated, dummy, or wrong-key probe, which is
+        // exactly the misconfiguration doctor exists to surface, not silently
+        // mask as a generic "reachable: HTTP 401".
+        const ollamaApiKeyEnv = (process.env["OLLAMA_API_KEY"] ?? "").trim();
+        const ollamaHeaders = { authorization: `Bearer ${ollamaApiKey()}` };
+        const result = await withProbeStatus("OLLAMA_BASE_URL reachability", () => probeGet(`${ollamaBase}/models`, ollamaHeaders));
+        const isAuthFailure = result.ok && (result.status === 401 || result.status === 403);
         check(report, "OLLAMA_BASE_URL reachability", true, // informational/warning only — see the ANTHROPIC_BASE_URL check above for why
-        result.ok ? `reachable: GET ${ollamaBase}/models -> HTTP ${result.status}` : `unreachable: GET ${ollamaBase}/models -> ${result.error}`, result.ok ? "info" : "warn");
+        !result.ok
+            ? `unreachable: GET ${ollamaBase}/models -> ${result.error}`
+            : isAuthFailure
+                ? `HTTP ${result.status} from GET ${ollamaBase}/models — a gateway in front of Ollama is rejecting this request; set OLLAMA_API_KEY to the client key it expects${ollamaApiKeyEnv ? " (one is set, but was rejected — check its value)" : " (none is currently set — the dummy placeholder bearer a keyless dispatch sends was rejected too)"}`
+                : `reachable: GET ${ollamaBase}/models -> HTTP ${result.status}`, !result.ok || isAuthFailure ? "warn" : "info");
     }
     // Cloudflare Workers AI — the same reachability check the Ollama block
     // above runs, for the same reason: a keyed provider whose endpoint

package/dist/cli/commands/estimate.d.ts

@@ -19,15 +19,19 @@ export declare function median(values: number[]): number;
 export declare function normalizePhaseName(name: string): string;
 export interface PhaseProjection {
     name: string;
+    /** Display total (cache reads included) — for the printed "phase p50 tokens" breakdown, i.e. context, never the ceiling comparison below. */
     p50: number;
     min: number;
     max: number;
+    /** BILLABLE p50 — what `findCutoffPhase` actually walks against `defaults.max_run_tokens` (a billable ceiling; see `UsageBreakdown.billable_tokens`'s doc comment in `core/data_types.ts`). Kept alongside, never instead of, `p50`: the two answer different questions and printing only one would silently pick a metric for the reader. */
+    billable_p50: number;
 }
 /**
- * Per run: sum every iteration of a normalized phase into one observation.
- * Across runs: median (p50) and min/max of those per-run sums. A phase
- * absent from a given run (a fix loop that never triggered) counts as a
- * `0` observation for that run — not a skip — so its median reflects how
+ * Per run: sum every iteration of a normalized phase into one observation —
+ * both the display total and the billable figure. Across runs: median (p50)
+ * and min/max of the total sums, plus the median of the billable sums. A
+ * phase absent from a given run (a fix loop that never triggered) counts as
+ * a `0` observation for that run — not a skip — so its median reflects how
  * often the phase actually ran, not just its size when it did.
  */
 export declare function aggregatePhases(sessions: ChainHistorySession[]): PhaseProjection[];
@@ -36,9 +40,21 @@ export interface RunTotalsProjection {
     min: number;
     max: number;
 }
-/** The HEADLINE: median of sampled runs' `sessions.total_tokens` — NOT the sum of the per-phase medians (those are different numbers; median of sums != sum of medians). */
+/** The HEADLINE: median of sampled runs' `sessions.total_tokens` — NOT the sum of the per-phase medians (those are different numbers; median of sums != sum of medians). This is the CONTEXT figure (cache reads included); it is never compared against `max_run_tokens` — see `findCutoffPhase` for the billable-based ceiling check. */
 export declare function projectRunTotals(sessions: ChainHistorySession[]): RunTotalsProjection | null;
-/** Where a p50 run would be cut off by `max_run_tokens`, walking the phase breakdown cumulatively in the order phases first appeared. `undefined` means unset; `null` means set but never reached on the p50 path. */
+/**
+ * Where a p50 run would be cut off by `max_run_tokens`, walking the phase
+ * breakdown cumulatively in the order phases first appeared. `undefined`
+ * means unset; `null` means set but never reached on the p50 path.
+ *
+ * Walks `billable_p50`, NOT `p50` — `defaults.max_run_tokens` is a BILLABLE
+ * ceiling (`assertRunBudget` in `core/agents.ts` checks it against
+ * `Run.billable_tokens`, never the display total), so comparing it against
+ * a cumulative TOTAL (cache reads included) would trip the projected cutoff
+ * far earlier than a real run ever would — the same total-vs-billable
+ * mismatch `UsageBreakdown.billable_tokens`'s doc comment (`core/data_types.ts`)
+ * describes for the real ceiling check itself.
+ */
 export declare function findCutoffPhase(phases: PhaseProjection[], maxRunTokens: number | undefined): string | null | undefined;
 export interface DriftWarning {
     agent: string;

package/dist/cli/commands/estimate.js

@@ -95,19 +95,22 @@ export function normalizePhaseName(name) {
     return name.replace(/_\d+$/, "");
 }
 /**
- * Per run: sum every iteration of a normalized phase into one observation.
- * Across runs: median (p50) and min/max of those per-run sums. A phase
- * absent from a given run (a fix loop that never triggered) counts as a
- * `0` observation for that run — not a skip — so its median reflects how
+ * Per run: sum every iteration of a normalized phase into one observation —
+ * both the display total and the billable figure. Across runs: median (p50)
+ * and min/max of the total sums, plus the median of the billable sums. A
+ * phase absent from a given run (a fix loop that never triggered) counts as
+ * a `0` observation for that run — not a skip — so its median reflects how
  * often the phase actually ran, not just its size when it did.
  */
 export function aggregatePhases(sessions) {
     const perRunSums = sessions.map(() => new Map());
+    const perRunBillableSums = sessions.map(() => new Map());
     const firstSeq = new Map();
     sessions.forEach((session, i) => {
         for (const phase of session.phases) {
             const name = normalizePhaseName(phase.name);
             perRunSums[i].set(name, (perRunSums[i].get(name) ?? 0) + phase.tokens);
+            perRunBillableSums[i].set(name, (perRunBillableSums[i].get(name) ?? 0) + phase.billable_tokens);
             if (!firstSeq.has(name) || phase.seq < firstSeq.get(name))
                 firstSeq.set(name, phase.seq);
         }
@@ -115,23 +118,36 @@ export function aggregatePhases(sessions) {
     const names = [...firstSeq.keys()].sort((a, b) => firstSeq.get(a) - firstSeq.get(b));
     return names.map((name) => {
         const perRun = perRunSums.map((m) => m.get(name) ?? 0);
-        return { name, p50: median(perRun), min: Math.min(...perRun), max: Math.max(...perRun) };
+        const perRunBillable = perRunBillableSums.map((m) => m.get(name) ?? 0);
+        return { name, p50: median(perRun), min: Math.min(...perRun), max: Math.max(...perRun), billable_p50: median(perRunBillable) };
     });
 }
-/** The HEADLINE: median of sampled runs' `sessions.total_tokens` — NOT the sum of the per-phase medians (those are different numbers; median of sums != sum of medians). */
+/** The HEADLINE: median of sampled runs' `sessions.total_tokens` — NOT the sum of the per-phase medians (those are different numbers; median of sums != sum of medians). This is the CONTEXT figure (cache reads included); it is never compared against `max_run_tokens` — see `findCutoffPhase` for the billable-based ceiling check. */
 export function projectRunTotals(sessions) {
     if (sessions.length === 0)
         return null;
     const totals = sessions.map((s) => s.total_tokens);
     return { p50: median(totals), min: Math.min(...totals), max: Math.max(...totals) };
 }
-/** Where a p50 run would be cut off by `max_run_tokens`, walking the phase breakdown cumulatively in the order phases first appeared. `undefined` means unset; `null` means set but never reached on the p50 path. */
+/**
+ * Where a p50 run would be cut off by `max_run_tokens`, walking the phase
+ * breakdown cumulatively in the order phases first appeared. `undefined`
+ * means unset; `null` means set but never reached on the p50 path.
+ *
+ * Walks `billable_p50`, NOT `p50` — `defaults.max_run_tokens` is a BILLABLE
+ * ceiling (`assertRunBudget` in `core/agents.ts` checks it against
+ * `Run.billable_tokens`, never the display total), so comparing it against
+ * a cumulative TOTAL (cache reads included) would trip the projected cutoff
+ * far earlier than a real run ever would — the same total-vs-billable
+ * mismatch `UsageBreakdown.billable_tokens`'s doc comment (`core/data_types.ts`)
+ * describes for the real ceiling check itself.
+ */
 export function findCutoffPhase(phases, maxRunTokens) {
     if (maxRunTokens === undefined)
         return undefined;
     let cumulative = 0;
     for (const phase of phases) {
-        cumulative += phase.p50;
+        cumulative += phase.billable_p50;
         if (cumulative >= maxRunTokens)
             return phase.name;
     }
@@ -289,6 +305,12 @@ function printText(report, coldStart) {
             for (const phase of report.phases) {
                 lines.push(`${phase.name.padEnd(20)} ${fmt(phase.p50).padStart(12)}    ${fmt(phase.min)} - ${fmt(phase.max)}`);
             }
+            // The display total above (cache reads included) is context only — it is
+            // never what `max_run_tokens` is checked against (see `findCutoffPhase`).
+            // Print the same billable sum that calc actually walks, so the ceiling
+            // line below (labeled "billable tokens") has a comparable figure on screen.
+            const billableTotal = report.phases.reduce((sum, p) => sum + p.billable_p50, 0);
+            lines.push(`billable p50         ${fmt(billableTotal).padStart(12)}    (cache reads excluded; what max_run_tokens checks against)`);
         }
         if (report.projected) {
             lines.push("");
@@ -306,9 +328,9 @@ function printText(report, coldStart) {
     }
     lines.push("");
     if (report.ceilings.max_run_tokens !== undefined) {
-        lines.push(`max_run_tokens   ${fmt(report.ceilings.max_run_tokens)}` +
+        lines.push(`max_run_tokens   ${fmt(report.ceilings.max_run_tokens)} (billable tokens — cache reads excluded)` +
             (report.ceilings.cutoff_phase ? `  -> would stop at "${report.ceilings.cutoff_phase}" on a p50 run` : ""));
-        lines.push('           (checked BEFORE each call: a run can overshoot by one call, and a one-dispatch chain can never trip it)');
+        lines.push('           (checked BEFORE each call, against billable tokens: a run can overshoot by one call, and a one-dispatch chain can never trip it)');
     }
     if (report.ceilings.max_run_cost !== undefined) {
         lines.push(`max_run_cost     $${report.ceilings.max_run_cost.toFixed(3)}`);

package/dist/cli/commands/loop.d.ts

@@ -1,2 +1,22 @@
+/**
+ * BILLABLE tokens for one ledger row's readback — `--max-tokens`
+ * (`overCumulativeBudget`, `core/loop.ts`) must compare against the same
+ * metric `defaults.max_run_tokens` checks per-call inside one chain run
+ * (see `LedgerAttempt.tokens`'s doc comment), never the display total
+ * (`total_tokens`, cache reads included).
+ *
+ * `billable_tokens` is 0 — never `null` — for BOTH a row that predates the
+ * column (`ALTER TABLE ... DEFAULT 0` backfills existing rows) and a
+ * genuinely free iteration, so there is no way to tell those apart from the
+ * value alone; falling back to `total_tokens` whenever `billable_tokens` is
+ * falsy is the pragmatic rule (a real dispatch's billable figure is
+ * essentially never exactly 0, so this only ever fires for a pre-tracking
+ * row or a free one, where 0 either way is the right answer). Exported so
+ * this exact rule is unit-tested directly, not just exercised end to end.
+ */
+export declare function billableTokensFor(session: {
+    billable_tokens?: number | null;
+    total_tokens?: number | null;
+} | null | undefined): number;
 export declare const USAGE: string;
 export declare function loopCommand(argv: string[]): Promise<number>;

package/dist/cli/commands/loop.js

@@ -8,6 +8,25 @@ import { SfDb } from "../../ui/server/db.js";
 import { parseCli, resolvePrompt } from "../../core/utils.js";
 import { isInteractive } from "../ask.js";
 import { resolveIssueProvider } from "./watch.js";
+/**
+ * BILLABLE tokens for one ledger row's readback — `--max-tokens`
+ * (`overCumulativeBudget`, `core/loop.ts`) must compare against the same
+ * metric `defaults.max_run_tokens` checks per-call inside one chain run
+ * (see `LedgerAttempt.tokens`'s doc comment), never the display total
+ * (`total_tokens`, cache reads included).
+ *
+ * `billable_tokens` is 0 — never `null` — for BOTH a row that predates the
+ * column (`ALTER TABLE ... DEFAULT 0` backfills existing rows) and a
+ * genuinely free iteration, so there is no way to tell those apart from the
+ * value alone; falling back to `total_tokens` whenever `billable_tokens` is
+ * falsy is the pragmatic rule (a real dispatch's billable figure is
+ * essentially never exactly 0, so this only ever fires for a pre-tracking
+ * row or a free one, where 0 either way is the right answer). Exported so
+ * this exact rule is unit-tested directly, not just exercised end to end.
+ */
+export function billableTokensFor(session) {
+    return session?.billable_tokens || session?.total_tokens || 0;
+}
 /**
  * Just enough of `Run` for `quality.resolveSuite`/`runSuite` (`RunLike` in
  * `core/quality.ts`) to work against a real filesystem/console without a
@@ -152,7 +171,7 @@ export async function loopCommand(argv) {
                 const db = await SfDb.open(dataPaths.db, dataPaths.sessions_dir);
                 try {
                     const session = await db.session(iteration.adw_id);
-                    tokens = session?.total_tokens ?? 0;
+                    tokens = billableTokensFor(session);
                     cost = session?.total_cost ?? 0;
                 }
                 finally {

package/dist/cli/commands/ui.js

@@ -4,7 +4,7 @@ import * as paths from "../../core/paths.js";
 import { parseCli } from "../../core/utils.js";
 import { runUi } from "../../ui/server/serve.js";
 export async function uiCommand(argv) {
-    const { options, flags } = parseCli(argv, ["cwd", "config", "db", "port"], ["no-open"]);
+    const { options, flags } = parseCli(argv, ["cwd", "config", "db", "port", "host"], ["no-open"]);
     const anchor = paths.resolveAnchor(options["cwd"]);
     let db;
     let sessionsDir;
@@ -29,6 +29,7 @@ export async function uiCommand(argv) {
             sessionsDir,
             webDir: paths.WEB_DIR,
             port: options["port"] ? Number.parseInt(options["port"], 10) : undefined,
+            host: options["host"],
             open: !flags["no-open"],
         });
         console.log(`[spf] ui        ${handle.url}`);

package/dist/cli/commands/watch.js

@@ -113,7 +113,7 @@ export function resolveIssueProvider(cfg) {
             console.error('JIRA_EMAIL and JIRA_API_TOKEN must both be set — spf watch needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens). See README.md\'s "spf watch" section.');
             return null;
         }
-        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types, cfg.watch.jira.status_map);
+        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types, cfg.watch.jira.status_map, cfg.watch.jira.link_type);
     }
     console.error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} is not supported`);
     return null;

package/dist/cli/index.js

@@ -46,7 +46,7 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
   spf migrate [--apply] [--force]           move an old stamped adws/ tree onto .spf/ (dry run by default)
   spf eject [--target <dir>] [--force]      copy the installed engine out for reference/hand-editing
   spf doctor [--json]                       check everything that fails silently otherwise
-  spf ui [--port N] [--no-open] [--db path] open the trace visualizer
+  spf ui [--port N] [--host addr] [--no-open] [--db path]  open the trace visualizer (loopback-only by default; --host widens it, deliberately)
   spf watch init                            idempotently seed the <prefix>:* labels watch.repo needs
   spf watch [--dry-run] [--once]            poll watch.repo for labeled issues, run watch.chain on each
   spf sessions [--limit N] [--json]         recent runs
@@ -56,7 +56,7 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
   spf version                               print the installed version
 
 Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>] [--issue <id>] [--priority p0|p1|p2|p3]
-Run budget: set defaults.max_run_cost (USD) and/or defaults.max_run_tokens in spf.config.yaml to stop the NEXT agent call once a run has already spent this much — checked before each call, never after, so a single call is never capped and a one-agent-dispatch chain (scout/prompt/build) can never trip it; absent (the default) = unbounded.
+Run budget: set defaults.max_run_cost (USD) and/or defaults.max_run_tokens in spf.config.yaml to stop the NEXT agent call once a run has already spent this much — checked before each call, never after, so a single call is never capped and a one-agent-dispatch chain (scout/prompt/build) can never trip it; absent (the default) = unbounded. max_run_tokens is checked against BILLABLE tokens (input + cache-write + output), never the larger display total shown elsewhere (cache reads included) — see the sessions panel's "tokens" line for that total instead. \`spf loop\`'s --max-tokens is the same billable metric, cumulative across every iteration.
 Run \`spf list\` to see every chain and what it needs.`;
 /** A raw scan for `--cwd`, ahead of any command-specific argv parsing — every command that takes it means the same thing by it. */
 function findCwdFlag(argv) {

package/dist/cli/interview.js

@@ -265,6 +265,19 @@ export async function runInterview(asker, ctx) {
                 env["OLLAMA_BASE_URL"] = baseUrl;
                 envExampleKeys.push("OLLAMA_BASE_URL");
                 asker.note("spf doctor checks this one — a probe against OLLAMA_BASE_URL/models runs on every `spf doctor`.");
+                // MINOR-F: optional per-gateway bearer — NOT added to
+                // PROVIDER_ENV_KEYS.ollama (see its doc comment: a bare local Ollama
+                // server needs no key at all, so this must stay optional, never
+                // required). A gateway in front of Ollama (e.g. Briefs' Envoy AI
+                // Gateway) does enforce a per-client key, though, which
+                // ollama_provider.ts's `ollamaApiKey()` sends as the bearer when
+                // set. Collected as an optional secret, same shape as the
+                // Cloudflare API token prompt below — blank is fine, left
+                // unanswered here just means the dummy placeholder keeps being used.
+                const ollamaApiKey = await asker.secret("OLLAMA_API_KEY", { current: ctx.existingEnv.get("OLLAMA_API_KEY") });
+                if (ollamaApiKey)
+                    env["OLLAMA_API_KEY"] = ollamaApiKey;
+                envExampleKeys.push("OLLAMA_API_KEY");
                 // Same problem the claude_code branch already solves above: the
                 // packaged roster pins planner/reviewer/documenter to their own
                 // fireworks/gemini/openai model strings, which always win over

package/dist/cli/ui/run_dashboard.js

@@ -51,16 +51,22 @@ function DashboardRoot(props) {
             setHistory((h) => [...h, { key, text }]);
         },
         setLivePhase: setLive,
-        setUsage: (tokens, cost) => setUsage({ tokens, cost }),
+        setUsage: (tokens, cost, billableTokens) => setUsage({ tokens, cost, billableTokens }),
     };
     const overCost = props.maxCost !== undefined && usage.cost >= props.maxCost * 0.8;
-    const overTokens = props.maxTokens !== undefined && usage.tokens >= props.maxTokens * 0.8;
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: history, children: (line) => _jsx(Text, { children: line.text }, line.key) }), live ? (_jsxs(Box, { children: [_jsx(Text, { color: "magenta", children: "\u25B8 running: " }), _jsx(Text, { bold: true, children: live.name }), _jsxs(Text, { dimColor: true, children: [" (", live.kind, " \u00B7 ", live.owner, ") "] }), _jsx(Elapsed, { sinceMs: live.startedAtMs })] })) : null, _jsxs(Box, { children: [_jsxs(Text, { dimColor: true, children: ["spend: ", usage.tokens.toLocaleString(), " tokens \u00B7 ", formatUsd(usage.cost), props.maxCost !== undefined ? ` / ${formatUsd(props.maxCost)}` : "", props.maxTokens !== undefined ? ` (of ${props.maxTokens.toLocaleString()} tokens)` : ""] }), overCost || overTokens ? _jsx(Text, { color: "yellow", children: " \u2014 approaching ceiling" }) : null] })] }));
+    // Compared against BILLABLE tokens, never the display total — `maxTokens`
+    // is `defaults.max_run_tokens`, which `assertRunBudget` (agents.ts) checks
+    // against `billable_tokens`, not `tokens` (cache reads included). Comparing
+    // the total here would trip "approaching ceiling" on cache-driven bulk
+    // that the real ceiling check never sees. See `UsageBreakdown.billable_tokens`'s
+    // doc comment (`data_types.ts`) for the full reasoning.
+    const overTokens = props.maxTokens !== undefined && usage.billableTokens >= props.maxTokens * 0.8;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: history, children: (line) => _jsx(Text, { children: line.text }, line.key) }), live ? (_jsxs(Box, { children: [_jsx(Text, { color: "magenta", children: "\u25B8 running: " }), _jsx(Text, { bold: true, children: live.name }), _jsxs(Text, { dimColor: true, children: [" (", live.kind, " \u00B7 ", live.owner, ") "] }), _jsx(Elapsed, { sinceMs: live.startedAtMs })] })) : null, _jsxs(Box, { children: [_jsxs(Text, { dimColor: true, children: ["spend: ", usage.billableTokens.toLocaleString(), " tokens \u00B7 ", formatUsd(usage.cost), props.maxCost !== undefined ? ` / ${formatUsd(props.maxCost)}` : "", props.maxTokens !== undefined ? ` (of ${props.maxTokens.toLocaleString()} tokens)` : "", ` · ${usage.tokens.toLocaleString()} tokens context incl. cache reads`] }), overCost || overTokens ? _jsx(Text, { color: "yellow", children: " \u2014 approaching ceiling" }) : null] })] }));
 }
 export function mountRunDashboard(opts) {
     const handleRef = { current: null };
     let currentPhase = null;
-    let currentUsage = { tokens: 0, cost: 0 };
+    let currentUsage = { tokens: 0, cost: 0, billableTokens: 0 };
     // `undefined` while paused: Ink refuses a second `render()` on the same
     // stdout while a prior instance is still live (the same restriction
     // `ink_asker.tsx`'s confirm-timeout comment names), and the sign-off
@@ -104,10 +110,10 @@ export function mountRunDashboard(opts) {
             if (app)
                 handleRef.current?.setLivePhase(null);
         },
-        onUsage(tokens, cost) {
-            currentUsage = { tokens, cost };
+        onUsage(tokens, cost, billableTokens) {
+            currentUsage = { tokens, cost, billableTokens };
             if (app)
-                handleRef.current?.setUsage(tokens, cost);
+                handleRef.current?.setUsage(tokens, cost, billableTokens);
         },
     };
     async function unmount() {

package/dist/core/agent_cc.d.ts

@@ -115,17 +115,33 @@ export declare class CcToolCallTracker {
     private finish;
 }
 export declare function isKnownToolName(name: string): boolean;
+/** 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 line. */
+export interface GatewayCallIdentity {
+    adwId?: string;
+    agentName?: string;
+}
 /**
  * Merges `TRACEPARENT`/`ANTHROPIC_CUSTOM_HEADERS` into `baseEnv` for
- * outbound OTel propagation, or returns `baseEnv` UNCHANGED when
- * `otel` is absent (the common case — `observability.otel` not configured).
+ * outbound OTel + gateway-header propagation, or returns `baseEnv`
+ * UNCHANGED when NEITHER `otel` nor `gateway` has anything to contribute
+ * (no otel configured AND no adw_id/agent_name on this request — the
+ * byte-identical case for a bare, ungated `claude` install).
  * `ANTHROPIC_CUSTOM_HEADERS`'s verified format is newline-separated
  * `Name: Value` pairs (see this module's own header for the citation); an
  * operator-supplied value already present in `baseEnv` is kept and appended
  * to, not overwritten — a real header injected via config/settings must
  * still reach the wire alongside this module's own.
+ *
+ * `x-correlation-id`/`x-spf-agent` (from `gateway`) are added on EVERY call
+ * that has them, regardless of whether `otel` is configured — see
+ * `data_types.ts`'s `AgentRequest.adw_id` doc for why that pair is not
+ * gated on `observability.otel` the way `otel`/`traceparent` is. `traceparent`
+ * itself is added only when `otel` is present, unchanged from before.
+ * `x-request-id` is NEVER added — Envoy/Switchyard own that header
+ * end-to-end; this module used to send it here (BLOCKER B) and no longer
+ * does.
  */
-export declare function injectOtelEnv(baseEnv: Record<string, string>, otel: AgentRequest["otel"] | undefined): Record<string, string>;
+export declare function injectOtelEnv(baseEnv: Record<string, string>, otel: AgentRequest["otel"] | undefined, gateway?: GatewayCallIdentity): Record<string, string>;
 /**
  * Resolve `SPF_CLAUDE_CMD` for THIS call, substituting a literal `{model}`
  * token with `model` — see the module doc comment for why a fixed tag baked

package/dist/core/agent_cc.js

@@ -250,22 +250,40 @@ const EFFORT_MAP = {
 };
 /**
  * Merges `TRACEPARENT`/`ANTHROPIC_CUSTOM_HEADERS` into `baseEnv` for
- * outbound OTel propagation, or returns `baseEnv` UNCHANGED when
- * `otel` is absent (the common case — `observability.otel` not configured).
+ * outbound OTel + gateway-header propagation, or returns `baseEnv`
+ * UNCHANGED when NEITHER `otel` nor `gateway` has anything to contribute
+ * (no otel configured AND no adw_id/agent_name on this request — the
+ * byte-identical case for a bare, ungated `claude` install).
  * `ANTHROPIC_CUSTOM_HEADERS`'s verified format is newline-separated
  * `Name: Value` pairs (see this module's own header for the citation); an
  * operator-supplied value already present in `baseEnv` is kept and appended
  * to, not overwritten — a real header injected via config/settings must
  * still reach the wire alongside this module's own.
+ *
+ * `x-correlation-id`/`x-spf-agent` (from `gateway`) are added on EVERY call
+ * that has them, regardless of whether `otel` is configured — see
+ * `data_types.ts`'s `AgentRequest.adw_id` doc for why that pair is not
+ * gated on `observability.otel` the way `otel`/`traceparent` is. `traceparent`
+ * itself is added only when `otel` is present, unchanged from before.
+ * `x-request-id` is NEVER added — Envoy/Switchyard own that header
+ * end-to-end; this module used to send it here (BLOCKER B) and no longer
+ * does.
  */
-export function injectOtelEnv(baseEnv, otel) {
-    if (!otel)
+export function injectOtelEnv(baseEnv, otel, gateway = {}) {
+    const headerLines = [];
+    if (otel)
+        headerLines.push(`traceparent: ${otel.traceparent}`);
+    if (gateway.adwId)
+        headerLines.push(`x-correlation-id: ${gateway.adwId}`);
+    if (gateway.agentName)
+        headerLines.push(`x-spf-agent: ${gateway.agentName}`);
+    if (headerLines.length === 0)
         return baseEnv;
-    const ownHeaders = [`traceparent: ${otel.traceparent}`, `x-request-id: ${otel.x_request_id}`].join("\n");
     const existing = baseEnv.ANTHROPIC_CUSTOM_HEADERS;
+    const ownHeaders = headerLines.join("\n");
     return {
         ...baseEnv,
-        TRACEPARENT: otel.traceparent,
+        ...(otel ? { TRACEPARENT: otel.traceparent } : {}),
         ANTHROPIC_CUSTOM_HEADERS: existing ? `${existing}\n${ownHeaders}` : ownHeaders,
     };
 }
@@ -358,23 +376,25 @@ export async function run(request, onEvent, onSpawn, onExit) {
     const isOllamaLaunch = isOllamaLaunchCmd(cmdSpec);
     const needsOllamaLaunchSeparator = isOllamaLaunch && !cmdArgs.includes("--");
     const fullArgs = needsOllamaLaunchSeparator ? [...cmdArgs, "--", ...args] : [...cmdArgs, ...args];
-    // Outbound OTel propagation (SPF's otel-sdk extension): `request.otel` is
-    // set only when `observability.otel` is configured for this run (see
-    // `agents.ts`'s `send()`) — absent otherwise, so `env` below is
-    // byte-identical to before this existed for every repo that hasn't
-    // configured otel. `TRACEPARENT` is the standard W3C env var the `claude`
-    // CLI's own subprocesses/telemetry already look for; `ANTHROPIC_CUSTOM_
-    // HEADERS` additionally puts `traceparent` (redundant with the env var,
-    // but this is the only way to reach the ACTUAL outbound HTTP request the
-    // CLI itself makes to its configured `ANTHROPIC_BASE_URL`) and
-    // `x-request-id` (this agent call's own span id) onto that request's
-    // headers. Format verified against Claude Code's own docs (https://
+    // Outbound OTel + gateway-header propagation: `request.otel` is set only
+    // when `observability.otel` is configured for this run (see `agents.ts`'s
+    // `send()`); `request.adw_id`/`request.agent_name` are set on EVERY call
+    // regardless (see `data_types.ts`'s doc — the gateway needs them whether
+    // or not SPF's own otel export is on). `env` below is byte-identical to
+    // before this existed for a request with neither. `TRACEPARENT` is the
+    // standard W3C env var the `claude` CLI's own subprocesses/telemetry
+    // already look for; `ANTHROPIC_CUSTOM_HEADERS` additionally puts
+    // `traceparent`/`x-correlation-id`/`x-spf-agent` onto the ACTUAL outbound
+    // HTTP request the CLI itself makes to its configured `ANTHROPIC_BASE_URL`
+    // — NEVER `x-request-id` (Envoy/Switchyard own that header end-to-end;
+    // this module used to send it here — BLOCKER B — and no longer does).
+    // Format verified against Claude Code's own docs (https://
     // code.claude.com/docs/en/env-vars, fetched live for this feature —
     // requires CLI >= 2.1.227): "Custom headers to add to requests (`Name:
     // Value` format, newline-separated for multiple headers)". An
     // operator-supplied `ANTHROPIC_CUSTOM_HEADERS` already present in
     // `request.env` is PRESERVED, not clobbered — this appends to it.
-    const env = injectOtelEnv(request.env ?? operatorEnv(), request.otel);
+    const env = injectOtelEnv(request.env ?? operatorEnv(), request.otel, { adwId: request.adw_id, agentName: request.agent_name });
     const child = spawn(cmd, fullArgs, { cwd: request.cwd, env });
     // The prompt travels as a positional argv element, not stdin — closing it
     // immediately avoids a real, observed ~3s "no stdin data received" stall