@gr8ful/spf 0.19.0 → 0.19.1

package/dist/core/data_types.js

@@ -528,6 +528,46 @@ export const ConfigDefaultsSchema = v.object({
     // the machinery that decides whether its work passed.
     // .spf/ is the whole per-repo footprint now — no adws/ tree to protect.
     protected_files: v.optional(v.array(v.string()), () => [".spf/", "spf.config.yaml"]),
+    /**
+     * Paths a READ-ONLY (or write-restricted) agent may touch WITHOUT failing
+     * the phase — `core/permissions.ts`'s `enforce()` still rolls every one of
+     * them back (an agent's claimed report must never rest on a change that
+     * didn't survive), it just does not count that rollback as a breach.
+     *
+     * WHY THIS EXISTS: a lockfile is dependency-manager BOOKKEEPING, not the
+     * repo's intent — an agent that ran `npm install` (to read a package's
+     * real shape, say) rewrites `package-lock.json` as a side effect of a
+     * read, not an edit. Observed live: a read-only scout phase failed with
+     * "scout is read-only but modified 1 path(s): factory/content/
+     * package-lock.json — rolled back" over exactly this, for work that
+     * changed nothing an operator would call "the code."
+     *
+     * The four defaults are the lockfiles of every package manager this repo
+     * already builds against (npm, pnpm, yarn, bun) — additive, not
+     * exhaustive; a repo using another one adds its own pattern here. Same
+     * glob syntax as `protected_files`/`agents[].writes` (`permissions.ts`'s
+     * `globToRegex`), where a leading "**" followed by a path separator
+     * matches at any depth INCLUDING the repo root — so the packaged
+     * defaults below match a lockfile whether it sits at the top of the repo
+     * or nested under a subdirectory.
+     *
+     * Emptying this list (`read_only_ignore: []`) restores today's strict
+     * behavior exactly — every touched path outside an agent's own allowlist
+     * fails the phase, lockfiles included.
+     *
+     * PRECEDENCE: `protected_files` always wins. A path matching
+     * `protected_files` is never ignorable via `read_only_ignore`, no matter
+     * how narrowly write-restricted the agent is — a pattern here that
+     * happens to also match a protected path is not read as "exempt this
+     * from protected_files too"; it stays a real breach. See
+     * `permissions.ts`'s `isSafeToIgnore` for the enforcement.
+     */
+    read_only_ignore: v.optional(v.array(v.string()), () => [
+        "**/package-lock.json",
+        "**/pnpm-lock.yaml",
+        "**/yarn.lock",
+        "**/bun.lockb",
+    ]),
     data_dir: v.optional(v.string(), ".spf/data"),
     /**
      * RUN BUDGET CEILINGS — the two knobs that bound what one adw_id may spend.
@@ -550,11 +590,20 @@ export const ConfigDefaultsSchema = v.object({
      * `agents.ts`'s `BudgetExceeded`.
      *
      * `max_run_cost` is USD (the same unit the provider's own usage.cost
-     * arrives in, summed by `UsageBreakdown`); `max_run_tokens` is TOTAL
-     * tokens, i.e. the spend number — every turn re-sends the whole
-     * conversation, so this counts cached re-reads too, exactly like the
-     * `total_tokens` column in `sessions` (see `ui/server/db.ts`'s `usage()`
-     * for why that number is much larger than "material moved").
+     * arrives in, summed by `UsageBreakdown`); `max_run_tokens` is BILLABLE
+     * tokens — `UsageBreakdown.billable_tokens` (input + cache-write + output),
+     * checked against `Run.billable_tokens`, NOT the `total_tokens` column
+     * `sessions` also carries for display. A prompt-caching backend (Ollama
+     * Cloud's kimi models, Anthropic's own caching) re-sends the whole
+     * conversation every turn as CACHE READS, which `total_tokens` counts and
+     * this ceiling does not: cache reads are billed (when billed at all) at a
+     * small fraction of input price, sometimes free, so a ceiling measured
+     * against the bigger number trips on bulk that cost nothing — observed
+     * live, one scout phase alone reported 1,311,740 total_tokens against a
+     * gateway that billed 189,321 uncached input + 17,908 output for it.
+     * `total_tokens` is kept exactly as before for anything display-only
+     * (the sessions-panel "tokens" line, the UI) — only the budget check
+     * changed which number it reads.
      *
      * Both are `> 0`, not `>= 0`: a zero ceiling would mean "no agent may ever
      * run", which is a config mistake, not a budget — it would fail the first
@@ -573,6 +622,43 @@ export const ConfigDefaultsSchema = v.object({
      */
     max_run_cost: v.optional(v.pipe(v.number(), v.gtValue(0))),
     max_run_tokens: v.optional(v.pipe(v.number(), v.integer(), v.gtValue(0))),
+    /**
+     * REQUEST TIMEOUT — how long a single agent dispatch may run before it is
+     * aborted and settled as failed, rather than hanging on a connection that
+     * silently died mid-call with nothing to notice.
+     *
+     * FLUE-SPECIFIC, unlike every other key in this schema: it maps straight
+     * onto `AgentStatics.durability.timeoutMs` (see `@flue/runtime`'s own
+     * docs), a `flue`-backend-only mechanism. `claude_code`/`opencode` are
+     * subprocess backends with no such knob today — this field is silently
+     * ignored for them, the same way `flue_db_path` on `AgentRequest` already
+     * is. Not a bug to fix here: a subprocess backend needs its own separate
+     * process-level timeout story, which is out of scope for this key.
+     *
+     * ABSENT BY DEFAULT, and absence is a total no-op: Flue's own default
+     * applies unchanged (1 hour, 10 attempts) — the same "surprise mid-run
+     * failure on a ceiling nobody chose is worse than the spend" reasoning as
+     * `max_run_cost`/`max_run_tokens` above. Set this when a hung connection
+     * should surface as an attributable failure (and feed the normal
+     * gate-correction / `spf watch` retry loop) in minutes, not however long
+     * Flue's own default takes — e.g. `300_000` for a five-minute ceiling.
+     * NOT a precise deadline, though: manual verification against a socket
+     * that accepts a connection and then sends nothing (see
+     * `request_timeout.test.ts`'s header comment) saw Flue's own timeout check
+     * fire on a coarser periodic sweep — a 3s ceiling settled at ~15s, not 3s.
+     * Bounded-but-imprecise is still a firm improvement over unbounded.
+     *
+     * SCOPE IS ONE SUBMISSION (one agent dispatch — the first prompt, one
+     * JSON-repair retry, one gate correction), NOT the accumulated run, unlike
+     * `max_run_cost`/`max_run_tokens` above. It is still process-scoped, not
+     * per-agent: Flue's `durability` is a static on the single shared agent
+     * function `agent_flue.ts` dispatches everything through, set once before
+     * the first dispatch of the process — see that file's `ensureRuntime()`.
+     * Deliberately NOT in `loadConfig`'s per-agent back-fill list for the same
+     * reason `max_run_cost`/`max_run_tokens` aren't: a per-agent copy would
+     * read as "this agent gets its own timeout", which nothing enforces.
+     */
+    request_timeout_ms: v.optional(v.pipe(v.number(), v.integer(), v.gtValue(0))),
 });
 /**
  * OpenTelemetry span export — OFF unless this block exists, and `endpoint` is
@@ -869,6 +955,30 @@ export const WatchJiraConfigSchema = v.object({
     project_key: v.optional(v.string(), ""), // e.g. "PROJ"
     issue_types: v.optional(JiraIssueTypeMapSchema, () => v.parse(JiraIssueTypeMapSchema, {})),
     status_map: v.optional(JiraStatusMapSchema, () => v.parse(JiraStatusMapSchema, {})),
+    /**
+     * The Jira issue-link `type` name `refine.ts`'s `publish()` uses to
+     * connect a freshly-published tree's ROOT issue(s) back to the spec they
+     * were refined from (`JiraProvider.linkToSpec`) — a plain, symmetric
+     * "issue link" (Jira's generic relate-two-issues mechanism), never the
+     * hierarchical `parent` field `linkChild` sets: the spec's own issue type
+     * defaults to Story (`issue_types.spec`), and a root node is often an
+     * Epic/Task — Jira's issue-type hierarchy frequently refuses a Story as
+     * one of those types' PARENT, so the hierarchy field is not a safe choice
+     * here regardless of which type actually published. "Relates" is a
+     * built-in link type on every Jira Cloud project; override this only if a
+     * project's admin has renamed or restricted it.
+     *
+     * MUST NAME A SYMMETRIC LINK TYPE. `JiraProvider.linkToSpec` fixes which
+     * side is `inwardIssue`/`outwardIssue` (the published root is always
+     * inward, the spec always outward) and does not expose direction as a
+     * separate knob — harmless for a symmetric type like "Relates" (Jira's UI
+     * does not even surface a direction for one), but pointing this at a
+     * DIRECTIONAL type (e.g. "blocks"/"is blocked by") would silently record
+     * the opposite relationship from the one intended. Only rename this to
+     * another symmetric type; a directional one needs code changes, not just
+     * config.
+     */
+    link_type: v.optional(v.string(), "Relates"),
 });
 /**
  * Optional, per-repo `WatchState` -> GitHub Projects v2 "Status" option-name
@@ -1230,6 +1340,24 @@ export class UsageBreakdown {
     // at the output rate. Report it nested under output, never added to it.
     reasoning_tokens = 0;
     total_tokens = 0;
+    /**
+     * The SPEND number, as distinct from `total_tokens` (the SIZE number).
+     * `input_tokens + output_tokens + cache_write_tokens` — `cache_read_tokens`
+     * excluded on purpose: a cache read is Anthropic's own prompt-caching
+     * discount (billed at a small fraction of the input rate, sometimes free
+     * on some gateways) for context the conversation already sent, not new
+     * material moved. `total_tokens` re-sends (and re-counts) the whole
+     * conversation every turn, so a long-running scout/build session's cache
+     * reads dwarf everything else in it (observed live: 1.31M total_tokens in
+     * one phase, of which 1.15M were cache reads the gateway did not bill as
+     * input) — a run-budget ceiling measured against `total_tokens` trips on
+     * cache-driven bulk that cost nothing, not on real spend. `assertRunBudget`
+     * (`agents.ts`) checks THIS field against `defaults.max_run_tokens`;
+     * `total_tokens` is kept, unchanged, for display (the sessions-panel
+     * "tokens" line, the UI) because an operator sizing context occupancy
+     * still needs the real re-send count, not the billable one.
+     */
+    billable_tokens = 0;
     input_cost = 0.0;
     output_cost = 0.0;
     cache_read_cost = 0.0;
@@ -1249,6 +1377,7 @@ export class UsageBreakdown {
         this.cache_write_tokens += usage.cacheWrite || 0;
         this.reasoning_tokens += usage.reasoning || 0;
         this.total_tokens += totalTokens;
+        this.billable_tokens += (usage.input || 0) + (usage.output || 0) + (usage.cacheWrite || 0);
         this.input_cost += cost.input || 0.0;
         this.output_cost += cost.output || 0.0;
         this.cache_read_cost += cost.cacheRead || 0.0;

package/dist/core/issues/jira_provider.d.ts

@@ -71,6 +71,15 @@
  * `feature` (both mapping to Jira's Epic type by default) surfaces a real
  * Jira API error at publish time — a genuine platform difference, not
  * something this file tries to paper over.
+ *
+ * `linkToSpec` is the OTHER half of `IssueAuthoringProvider`'s hierarchy —
+ * a published tree's ROOT connected back to the spec it was refined FROM,
+ * which `linkChild` cannot express (the spec's own issue type, a Story by
+ * default, frequently cannot legally PARENT a root node's type). Uses
+ * Jira's plain issue-link API instead (`type` configurable via
+ * `watch.jira.link_type`, "Relates" by default), with a plain comment as
+ * its own fallback if that API is unavailable — see the method's own doc
+ * comment.
  */
 import type { JiraIssueTypeMap, JiraStatusMap } from "../data_types.ts";
 import type { EnsureLabelsResult, Issue, IssueAuthoringKind, IssueAuthoringProvider, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
@@ -82,8 +91,9 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
     private readonly apiToken;
     private readonly issueTypes;
     private readonly statusMap;
+    private readonly linkType;
     constructor(baseUrl: string, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap, statusMap?: JiraStatusMap);
+    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap, statusMap?: JiraStatusMap, linkType?: string);
     private authHeader;
     private jira;
     private label;
@@ -134,6 +144,46 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
      * Epic-under-Epic limitation this implies.
      */
     linkChild(parent: Issue, child: Issue): Promise<void>;
+    /**
+     * `IssueAuthoringProvider.linkToSpec` — see its own doc comment
+     * (`issues/provider.ts`) for why this is a plain Jira "issue link"
+     * (`/rest/api/3/issueLink`) rather than `linkChild`'s hierarchy `parent`
+     * field: the spec's issue type (Story by default) frequently cannot
+     * legally PARENT a root node's type under Jira's issue-type hierarchy,
+     * while a generic issue link has no such restriction.
+     *
+     * `inwardIssue`/`outwardIssue` direction is arbitrary for a symmetric
+     * type like "Relates" — Jira does not surface it differently in the UI —
+     * so `issue` (the freshly published root) is the inward side and the
+     * spec is the outward side, consistently.
+     *
+     * BEST-EFFORT: this project's Jira instance may not have `linkType`
+     * enabled/named exactly this way (a renamed or removed link type, a
+     * permission scheme that disallows issue links for this project, ...) —
+     * a failure here must never fail the whole publish over what is, at
+     * bottom, a cosmetic cross-reference. Falls back to a plain comment
+     * naming the spec, so the relationship is visible SOMEWHERE even when
+     * the link API itself is unavailable.
+     *
+     * The fallback comment gets the SAME "never fail publish() over this"
+     * treatment as the link call itself: a rate limit or network blip on the
+     * comment call is just as cosmetic a failure as one on the link call, so
+     * it is caught and logged here rather than left to propagate out of
+     * `publish()` (`refine.ts`), which awaits this unguarded.
+     *
+     * `this.linkType` MUST name a SYMMETRIC link type ("Relates" and its
+     * project-renamed equivalents) — `inwardIssue`/`outwardIssue` above are
+     * fixed (the published root is always inward, the spec always outward)
+     * and not independently configurable, which is fine for a symmetric type
+     * (Jira does not surface the direction differently in the UI) but WRONG
+     * for a directional one (e.g. "blocks"/"is blocked by"): configuring
+     * `watch.jira.link_type` to a directional type would silently assert the
+     * opposite relationship from the one intended. See that field's own doc
+     * comment (`data_types.ts`) — direction is not exposed as a separate knob
+     * on purpose, to avoid a second config field only meaningful alongside a
+     * link type most projects never change from the "Relates" default.
+     */
+    linkToSpec(specId: string, issue: Issue): Promise<void>;
     /** The read-back half of `linkChild` — same JQL-in-body pattern as `searchByLabel`, since a GET with query params silently returns nothing on this endpoint (see the module comment). What makes container roll-up (`rollUp` in `watch.ts`) work on Jira too. */
     listChildren(parent: Issue): Promise<Issue[]>;
     /**

package/dist/core/issues/jira_provider.js

@@ -56,8 +56,12 @@ export class JiraProvider {
     apiToken;
     issueTypes;
     statusMap;
+    linkType;
     constructor(baseUrl, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey, labelPrefix, email, apiToken, issueTypes, statusMap = {}) {
+    projectKey, labelPrefix, email, apiToken, issueTypes, statusMap = {}, 
+    // See `WatchJiraConfigSchema.link_type`'s own doc comment (`data_types.ts`)
+    // — the issue-link `type` name `linkToSpec` below creates.
+    linkType = "Relates") {
         this.baseUrl = baseUrl;
         this.projectKey = projectKey;
         this.labelPrefix = labelPrefix;
@@ -65,6 +69,7 @@ export class JiraProvider {
         this.apiToken = apiToken;
         this.issueTypes = issueTypes;
         this.statusMap = statusMap;
+        this.linkType = linkType;
     }
     authHeader() {
         return `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`;
@@ -185,6 +190,69 @@ export class JiraProvider {
     async linkChild(parent, child) {
         await this.jira(`/rest/api/3/issue/${child.id}`, { method: "PUT", body: JSON.stringify({ fields: { parent: { key: parent.id } } }) });
     }
+    /**
+     * `IssueAuthoringProvider.linkToSpec` — see its own doc comment
+     * (`issues/provider.ts`) for why this is a plain Jira "issue link"
+     * (`/rest/api/3/issueLink`) rather than `linkChild`'s hierarchy `parent`
+     * field: the spec's issue type (Story by default) frequently cannot
+     * legally PARENT a root node's type under Jira's issue-type hierarchy,
+     * while a generic issue link has no such restriction.
+     *
+     * `inwardIssue`/`outwardIssue` direction is arbitrary for a symmetric
+     * type like "Relates" — Jira does not surface it differently in the UI —
+     * so `issue` (the freshly published root) is the inward side and the
+     * spec is the outward side, consistently.
+     *
+     * BEST-EFFORT: this project's Jira instance may not have `linkType`
+     * enabled/named exactly this way (a renamed or removed link type, a
+     * permission scheme that disallows issue links for this project, ...) —
+     * a failure here must never fail the whole publish over what is, at
+     * bottom, a cosmetic cross-reference. Falls back to a plain comment
+     * naming the spec, so the relationship is visible SOMEWHERE even when
+     * the link API itself is unavailable.
+     *
+     * The fallback comment gets the SAME "never fail publish() over this"
+     * treatment as the link call itself: a rate limit or network blip on the
+     * comment call is just as cosmetic a failure as one on the link call, so
+     * it is caught and logged here rather than left to propagate out of
+     * `publish()` (`refine.ts`), which awaits this unguarded.
+     *
+     * `this.linkType` MUST name a SYMMETRIC link type ("Relates" and its
+     * project-renamed equivalents) — `inwardIssue`/`outwardIssue` above are
+     * fixed (the published root is always inward, the spec always outward)
+     * and not independently configurable, which is fine for a symmetric type
+     * (Jira does not surface the direction differently in the UI) but WRONG
+     * for a directional one (e.g. "blocks"/"is blocked by"): configuring
+     * `watch.jira.link_type` to a directional type would silently assert the
+     * opposite relationship from the one intended. See that field's own doc
+     * comment (`data_types.ts`) — direction is not exposed as a separate knob
+     * on purpose, to avoid a second config field only meaningful alongside a
+     * link type most projects never change from the "Relates" default.
+     */
+    async linkToSpec(specId, issue) {
+        try {
+            await this.jira("/rest/api/3/issueLink", {
+                method: "POST",
+                body: JSON.stringify({
+                    type: { name: this.linkType },
+                    inwardIssue: { key: issue.id },
+                    outwardIssue: { key: specId },
+                }),
+            });
+        }
+        catch (linkError) {
+            try {
+                await this.comment(issue, `Refined from ${specId}.`);
+            }
+            catch (commentError) {
+                // Both the issue-link API and the comment fallback failed — the
+                // spec/root relationship is not recorded ANYWHERE on Jira this run,
+                // but that is still a cosmetic loss, not a reason to fail the whole
+                // publish (see this method's own doc comment).
+                console.error(`spf watch: ${issue.id} — could not link to spec ${specId} (${linkError instanceof Error ? linkError.message : String(linkError)}) and the fallback comment also failed — ${commentError instanceof Error ? commentError.message : String(commentError)}`);
+            }
+        }
+    }
     /** The read-back half of `linkChild` — same JQL-in-body pattern as `searchByLabel`, since a GET with query params silently returns nothing on this endpoint (see the module comment). What makes container roll-up (`rollUp` in `watch.ts`) work on Jira too. */
     async listChildren(parent) {
         const jql = `parent = ${JSON.stringify(parent.id)}`;

package/dist/core/issues/provider.d.ts

@@ -311,6 +311,29 @@ export interface IssueAuthoringProvider {
      * roll-up, refine cannot function without authoring at all.
      */
     listChildren(parent: Issue): Promise<Issue[]>;
+    /**
+     * Best-effort: relate a freshly published tree's ROOT issue back to the
+     * spec issue (`specId`) it was refined FROM — `core/refine.ts`'s
+     * `publish()` calls this once per root node (a node with no `parent` of
+     * its own within the refined tree) when it was given a `specIssueId`.
+     *
+     * Deliberately NOT `linkChild`: that method sets the tracker's
+     * HIERARCHY field (Jira's `parent`, GitHub's sub-issues API), and a
+     * spec's own issue type (Story by default — `JiraIssueTypeMapSchema.spec`)
+     * frequently cannot legally PARENT a root node's type in Jira's
+     * issue-type hierarchy — see `JiraProvider`'s own doc comment on
+     * `publishSpecs()` for the same constraint. `linkToSpec` uses a plain,
+     * symmetric issue-to-issue reference instead (Jira's generic "issue
+     * link"), which has no such hierarchy restriction.
+     *
+     * OPTIONAL, not every tracker needs one: GitHub already gets a native,
+     * visible cross-reference for free the moment `renderBody`'s "## Parent"
+     * section renders a plain "#N" in the body — GitHub auto-links same-repo
+     * issue mentions into a real timeline "referenced this issue" event, no
+     * API call required. Jira does not do this for plain text, which is why
+     * `JiraProvider` implements this and `GitHubProvider` does not.
+     */
+    linkToSpec?(specId: string, issue: Issue): Promise<void>;
 }
 /**
  * Structural, not nominal: checks for the three methods rather than

package/dist/core/loop.d.ts

@@ -106,7 +106,35 @@ export interface LedgerAttempt {
     error: string | null;
     /** HEAD's short sha after a successful (exit 0) iteration — unchanged from the previous attempt's if this iteration committed nothing new, which is exactly what `isStuck` below looks for. `null` only for an errored or non-accepted (nonzero exit) attempt, where nothing was checked out to read. */
     commit_sha: string | null;
+    /**
+     * Kept for backward compatibility with ledger rows written before
+     * `billable_tokens` (below) existed — on a row this old, `tokens` is the
+     * DISPLAY total (`sessions.total_tokens`, cache reads included), the only
+     * figure that era ever recorded. On every row written since, this field
+     * and `billable_tokens` are set to the SAME (billable) value; they only
+     * ever diverge across that one-time boundary, never within a single
+     * write. `cumulativeSpend` is what actually reads either — see its own
+     * doc comment for the precedence.
+     */
     tokens: number;
+    /**
+     * The BILLABLE figure (input + cache-write + output) — what
+     * `--max-tokens`/`overCumulativeBudget` is SUPPOSED to compare against,
+     * same metric `defaults.max_run_tokens` uses within one chain run (see
+     * `UsageBreakdown.billable_tokens`'s doc comment, `data_types.ts`). NOT
+     * the display total (`sessions.total_tokens`, cache reads included) —
+     * `cli/commands/loop.ts`'s readback reads `session.billable_tokens`,
+     * falling back to `total_tokens` only for a SESSION row that predates
+     * that sqlite column being populated.
+     *
+     * `undefined` on any LEDGER row written before this field existed — a
+     * genuinely old-format row, not a free ($0) iteration. `cumulativeSpend`
+     * falls back to `tokens` for exactly that row (the only figure it has,
+     * a display total it cannot retroactively convert), and
+     * `hasLegacyTokenRows` is what a caller uses to warn once that a ceiling
+     * check is now mixing metrics across the ledger's own history.
+     */
+    billable_tokens?: number;
     cost: number;
     failures: string[];
     started_at: string;
@@ -151,13 +179,22 @@ export declare function newLedger(input: {
 export declare function resolveGoalId(explicit: string | undefined): string;
 export interface CumulativeBudget {
     maxCost?: number;
+    /** `--max-tokens` — checked against BILLABLE tokens (see `LedgerAttempt.billable_tokens`'s own doc comment), the same metric `defaults.max_run_tokens` checks per-call inside one chain run. */
     maxTokens?: number;
 }
 export declare function cumulativeSpend(attempts: LedgerAttempt[]): {
     cost: number;
     tokens: number;
 };
-/** Whether the goal-scoped ceiling is already exhausted going into the NEXT iteration — a stronger, ledger-wide check than any single iteration's own budget. */
+/**
+ * True when the ledger holds at least one attempt written before
+ * `billable_tokens` existed — `cumulativeSpend` is then silently mixing a
+ * display-total figure (that row's `tokens`) into a sum whose newer rows
+ * are billable. Used to print a one-time operator warning rather than let
+ * that mismatch pass unremarked; see `runLoop`'s call site.
+ */
+export declare function hasLegacyTokenRows(attempts: LedgerAttempt[]): boolean;
+/** Whether the goal-scoped ceiling is already exhausted going into the NEXT iteration — a stronger, ledger-wide check than any single iteration's own budget. `spend.tokens` must already be BILLABLE tokens (see `LedgerAttempt.tokens`) — this function just compares, it does not know which metric it was handed. */
 export declare function overCumulativeBudget(budget: CumulativeBudget, spend: {
     cost: number;
     tokens: number;
@@ -185,6 +222,7 @@ export interface IterationResult {
     error: string | null;
     /** `null` when nothing was committed this iteration (a no-op, or a throw before any commit). */
     commit_sha: string | null;
+    /** BILLABLE tokens — see `LedgerAttempt.tokens`'s own doc comment; `runIteration` (`cli/commands/loop.ts`) reads this straight from `LedgerAttempt`, so the two must stay the same metric. */
     tokens: number;
     cost: number;
     /** `null` when the iteration errored or exited non-zero — the stop check only ever runs against a chain that accepted its own work, same as `fixLoop` only re-verifies after a phase that didn't already throw. */

package/dist/core/loop.js

@@ -132,10 +132,30 @@ export function newLedger(input) {
 export function resolveGoalId(explicit) {
     return explicit ?? newId(8);
 }
+/**
+ * Per-attempt token figure for budget purposes: `billable_tokens` where the
+ * row has it, else `tokens` (an old-format row, predating that field — see
+ * `LedgerAttempt.billable_tokens`'s own doc comment). Never the other way
+ * around: a new row's `tokens` happens to equal its `billable_tokens` today,
+ * but `billable_tokens` is the one this function trusts on purpose.
+ */
+function tokensForBudget(a) {
+    return a.billable_tokens ?? a.tokens;
+}
 export function cumulativeSpend(attempts) {
-    return attempts.reduce((acc, a) => ({ cost: acc.cost + a.cost, tokens: acc.tokens + a.tokens }), { cost: 0, tokens: 0 });
+    return attempts.reduce((acc, a) => ({ cost: acc.cost + a.cost, tokens: acc.tokens + tokensForBudget(a) }), { cost: 0, tokens: 0 });
 }
-/** Whether the goal-scoped ceiling is already exhausted going into the NEXT iteration — a stronger, ledger-wide check than any single iteration's own budget. */
+/**
+ * True when the ledger holds at least one attempt written before
+ * `billable_tokens` existed — `cumulativeSpend` is then silently mixing a
+ * display-total figure (that row's `tokens`) into a sum whose newer rows
+ * are billable. Used to print a one-time operator warning rather than let
+ * that mismatch pass unremarked; see `runLoop`'s call site.
+ */
+export function hasLegacyTokenRows(attempts) {
+    return attempts.some((a) => a.billable_tokens === undefined);
+}
+/** Whether the goal-scoped ceiling is already exhausted going into the NEXT iteration — a stronger, ledger-wide check than any single iteration's own budget. `spend.tokens` must already be BILLABLE tokens (see `LedgerAttempt.tokens`) — this function just compares, it does not know which metric it was handed. */
 export function overCumulativeBudget(budget, spend) {
     if (budget.maxCost !== undefined && spend.cost >= budget.maxCost)
         return true;
@@ -207,6 +227,13 @@ export async function runLoop(deps) {
     if (existing) {
         deps.log(`loop: resuming goal ${deps.goalId} — ${existing.attempts.length} attempt(s) already recorded`);
     }
+    // One-time info line, not a per-iteration one: legacy rows already IN the
+    // ledger (from a resumed goal) do not change count as this run proceeds,
+    // so there is nothing to re-warn about after the first check.
+    if (deps.budget.maxTokens !== undefined && hasLegacyTokenRows(ledger.attempts)) {
+        deps.log(`loop: goal ${deps.goalId} — ledger has attempt(s) recorded before billable-token tracking; ` +
+            "--max-tokens falls back to their display-total token count for those rows (see LedgerAttempt.billable_tokens)");
+    }
     let lastVerdict = ledger.attempts.length > 0 ? { passed: false, failures: ledger.attempts[ledger.attempts.length - 1].failures, artifacts: [] } : null;
     for (let i = ledger.attempts.length + 1; i <= deps.max; i++) {
         if (overCumulativeBudget(deps.budget, cumulativeSpend(ledger.attempts))) {
@@ -244,7 +271,11 @@ export async function runLoop(deps) {
             exit_code: result.exit_code,
             error: result.error,
             commit_sha: result.commit_sha,
+            // Every row written from here on sets both to the same (billable)
+            // value — see `LedgerAttempt.tokens`/`billable_tokens`'s doc comments
+            // for why they only ever diverge on an old-format row.
             tokens: result.tokens,
+            billable_tokens: result.tokens,
             cost: result.cost,
             failures,
             started_at: startedAt,

package/dist/core/ollama_provider.d.ts

@@ -42,28 +42,111 @@
  * cost nothing at runtime either way.
  */
 import type { Provider } from "@earendil-works/pi-ai";
+/**
+ * `OLLAMA_API_KEY`, trimmed, when the operator has set one — e.g. the
+ * Briefs gateway (Envoy AI Gateway) enforces a per-client bearer and 401s
+ * the dummy key `DUMMY_API_KEY` was designed for a bare local server that
+ * checks nothing. Falls back to the dummy exactly as before when unset, so
+ * THIS function's own return value — the resolved `Authorization` bearer —
+ * is byte-identical to pre-gateway behavior for a bare local Ollama server
+ * (the common case this module was built for). MINOR-H: that is narrower
+ * than "the whole request is unchanged" — it is not, even with
+ * `OLLAMA_API_KEY` unset: a `traceparent` (and, once `agent_flue.ts` has an
+ * adw_id/agent_name to give it, `x-correlation-id`/`x-spf-agent`) is ALWAYS
+ * sent now, gateway or no gateway (see the "Gateway headers" section below).
+ * A bare local Ollama server ignores headers it doesn't recognize, so this
+ * is harmless — just not byte-identical. Read fresh inside `resolve()` (see
+ * its call site below) — never cached — so a key exported mid-process (or
+ * changed) takes effect on the very next dispatch with no re-registration.
+ *
+ * MINOR 3: exported so `doctor.ts`'s `OLLAMA_BASE_URL reachability` probe
+ * calls this SAME function rather than reading `process.env.OLLAMA_API_KEY`
+ * raw — a prior version of that probe sent NO `Authorization` header at all
+ * when the env var was unset, which diverges from what a real dispatch
+ * sends (the dummy bearer below, always). Against a gateway that rejects a
+ * request with no `Authorization` header at all differently than one with a
+ * wrong/dummy bearer, that divergence could make doctor report reachable
+ * when a real dispatch would 401, or vice versa. Calling `ollamaApiKey()` in
+ * both places means doctor's probe and a real dispatch send byte-identical
+ * bearers for the same env state.
+ */
+export declare function ollamaApiKey(): string;
+/** SPF-side identity for one LLM call, as far as `registerOllamaModel`'s caller can supply it. Both fields optional — an absent one simply omits its header. */
+export interface GatewayCallContext {
+    /** The run's adw_id — sent as `x-correlation-id` so the gateway groups this run's calls. */
+    adwId?: string;
+    /** The SPF agent name — sent as `x-spf-agent`. */
+    agentName?: string;
+}
+/** Must NEVER be sent — Envoy/Switchyard own it end-to-end; a client-supplied value breaks their sampling. Exported only so tests can assert its absence by name, not a literal string. The sole surviving export of this name in the codebase — see MINOR-G in this change's review; `otel_propagation.ts` no longer has one now that `XRequestIdPropagator` is gone (BLOCKER B). */
+export declare const X_REQUEST_ID_HEADER = "x-request-id";
+/**
+ * A fresh W3C `traceparent` for one outbound call — used only on the NOT
+ * INSTALLED path (see the section above); when propagation IS installed,
+ * `resolve()` does not call this at all, relying entirely on the
+ * instrumentation's own per-request injection instead (this is what fixed
+ * BLOCKER A/MAJOR-C: this function used to be called unconditionally, and
+ * on the installed path it silently reused the one still-open span's
+ * traceparent for every call inside that span, which is both a duplicate
+ * header AND not actually fresh per call).
+ *
+ * Reuses the active OTel span context when one is installed and current —
+ * the same trace this call's other telemetry already belongs to — falling
+ * back to a brand-new random trace/span id pair when there is none (no span
+ * active at this exact point, e.g. a stray call before any span opened), so
+ * the gateway still gets a well-formed, per-call-unique traceparent either
+ * way. Never throws; `isSpanContextValid` is the same guard
+ * `otel_propagation.ts`'s own propagators use.
+ */
+export declare function freshTraceparent(): string;
 /** Exported so `doctor.ts`'s reachability probe agrees with what a real dispatch resolves to — see its call site for why a `??`/`||` mismatch here matters. */
 export declare function ollamaBaseUrl(): string;
 /**
  * Registers `modelId` (the part after `ollama/` in an agent's `model`
  * config) with Flue's provider registry, alongside every other `ollama/*`
- * id ever registered this process. Idempotent: a repeat of an already-seen
- * id is a no-op — no re-registration, no re-import. A concurrent call for
- * the SAME id joins the in-flight registration rather than returning early
- * (see `inflight`'s doc); `registeredIds` itself is only ever updated AFTER
- * `setProvider()` succeeds, so a failed attempt (a bad install, a bundler
- * that can't resolve the deep `.lazy` subpath, a future validation error)
- * leaves the id unregistered and eligible for a real retry — not
- * permanently and misleadingly marked "done" while nothing is actually
- * registered.
+ * id ever registered this process. NOT idempotent w.r.t. `ctx` (see MAJOR-D
+ * below) — every call re-runs the union re-registration (dynamic imports
+ * are cheap after the first, and `setProvider()` is a cheap in-memory
+ * upsert), so this id's `Model.headers` always reflect the MOST RECENT
+ * `ctx` this function was called with, not just the first. A concurrent
+ * call for the SAME id joins the in-flight registration rather than running
+ * a second one in parallel (see `inflight`'s doc); `registeredIds` itself
+ * is only ever updated AFTER `setProvider()` succeeds, so a failed attempt
+ * (a bad install, a bundler that can't resolve the deep `.lazy` subpath, a
+ * future validation error) leaves the id unregistered and eligible for a
+ * real retry — not permanently and misleadingly marked "done" while
+ * nothing is actually registered.
  *
  * Must complete before the FIRST Flue dispatch that names this model
  * (agent_flue.ts's `run()` awaits this before `ensureRuntime()`/`start()`),
- * but is equally safe to call again later with a new id mid-process — that
- * later call's union re-registration is exactly how a second model gets
- * added without orphaning the first (see the `registeredIds` doc above).
+ * but is equally safe to call again later with a new id, or the SAME id
+ * again, mid-process — a new id's union re-registration is how a second
+ * model gets added without orphaning the first (see the `registeredIds` doc
+ * above); a repeat of the SAME id is how MAJOR-D below is fixed.
+ *
+ * MAJOR-D (fixed): `ctx`, when given AND `isFluePropagationInstalled()` is
+ * false (see the "Gateway headers" section above — when it's true, these
+ * two headers come from the per-request `GatewayHeadersPropagator`
+ * instead), is stamped onto this id's `Model.headers` as
+ * `x-correlation-id`/`x-spf-agent`. A PRIOR version of this function
+ * returned immediately for an already-registered id (a false comment
+ * claimed "one spf process runs one adw_id for its whole lifetime" to
+ * justify this) — which meant every later agent/adw_id sharing a model id
+ * within one process (spf `loop`/`fanout`/`watch`, which run many adw_ids
+ * in ONE process, `fanout` concurrently) silently kept the FIRST
+ * registration's headers forever. Re-running the full registration on every
+ * call, unconditionally, fixes that for every case except one, which
+ * remains and is not silently swallowed: two flue agents dispatching
+ * CONCURRENTLY (not sequentially) to the SAME `ollama/<id>` model id race on
+ * `registrationContext`/`setProvider()` — whichever registration's
+ * `setProvider()` call lands last wins the headers BOTH calls' subsequent
+ * dispatches see, until the next registration for that id. This is a
+ * `fanout` concurrency > 1 scenario specifically (two DIFFERENT agents,
+ * same process, same model id, truly overlapping registrations) — a
+ * sequential loop/watch never hits it, since each call's `await` completes
+ * before the next one starts.
  */
-export declare function registerOllamaModel(modelId: string): Promise<void>;
+export declare function registerOllamaModel(modelId: string, ctx?: GatewayCallContext): Promise<void>;
 /** Test-only: the most recently constructed provider object (see `lastProvider`'s doc). */
 export declare function providerForTest(): Provider<"openai-completions"> | undefined;
 /** Test-only: forgets accumulated ids so test files don't leak into each other. Does not touch Flue's own registry — pair with `resetModelsForTests()` from `@flue/runtime/internal`. */