@gr8ful/spf 0.18.0 → 0.19.1

package/dist/core/permissions.js

@@ -76,6 +76,19 @@ export function changedPaths(before, after) {
 function globToRegex(pattern) {
     let out = "";
     let i = 0;
+    // A LEADING "**/" is the common "any depth, including the repo root"
+    // idiom (gitignore, npm, ...) — "**/package-lock.json" must match both a
+    // root-level "package-lock.json" and a nested "a/b/package-lock.json".
+    // The plain "**" -> ".*" rule below (still applied to a "**" anywhere else
+    // in a pattern) cannot express that alone: ".*" still requires the
+    // literal "/" that follows it in the pattern text, so a root-level file
+    // with no directory prefix would never match. Only this one leading shape
+    // gets the optional-prefix translation; `defaults.read_only_ignore`'s own
+    // default patterns are exactly this shape.
+    if (pattern.startsWith("**/")) {
+        out += "(?:.*/)?";
+        i = 3;
+    }
     while (i < pattern.length) {
         const char = pattern[i];
         if (pattern.startsWith("**", i)) {
@@ -160,6 +173,58 @@ function rollBack(run, p, before, after) {
     const result = spawnSync("git", ["checkout", "--", p], { cwd: run.repo_root, encoding: "utf-8" });
     return result.status === 0 ? "rolled back" : "could not roll back";
 }
+/**
+ * True when `p` matches one of `defaults.read_only_ignore`'s patterns —
+ * dependency-manager bookkeeping (a lockfile), not the repo's intent. See
+ * that field's own doc comment (`data_types.ts`) for why it exists and what
+ * rolling one back "silently" means. Necessary but not sufficient — see
+ * `isSafeToIgnore`, which is what `enforce()` actually gates on, and which
+ * ALSO requires the path not match `defaults.protected_files`:
+ * `read_only_ignore` is a narrow "this churn is incidental, not intent"
+ * carve-out, and must never be read as a backdoor around a path an operator
+ * explicitly locked down. `protected_files` always wins — a path listed
+ * there is never ignorable via `read_only_ignore`, regardless of role.
+ */
+function isIgnorableChurn(p, cfg) {
+    return (cfg.defaults.read_only_ignore ?? []).some((pattern) => matches(p, pattern));
+}
+/**
+ * Whether an ignorable-churn path is actually safe to ignore for THIS phase.
+ * Both conditions are required, and either one failing means: real breach,
+ * `rollBack`'s own honest outcome string, no silent "ignored".
+ *
+ *  - The agent is a TRUE read-only role (`writes: []`), not merely
+ *    write-restricted (`writes: [...]`). A write-restricted agent that
+ *    changes `package.json` and its lockfile together left an
+ *    INCONSISTENT tree, not incidental dependency-manager bookkeeping —
+ *    `read_only_ignore` exists for the read-only case this module's header
+ *    describes (a read that happens to rewrite a lockfile), never as a
+ *    blanket exemption for one specific file pattern regardless of role.
+ *  - The path was CLEAN before this phase started (`!(p in before)`). Only
+ *    then does `rollBack` below actually take the "not in before" branch
+ *    and restore it (delete the untracked file, or `git checkout --` the
+ *    tracked one back to HEAD). A path that was ALREADY dirty when the
+ *    agent started hits `rollBack`'s OTHER branch instead — "left as-is"
+ *    or, if the agent discarded that uncommitted work, "REVERTED-BY-AGENT
+ *    (uncommitted work lost, cannot restore)" — and neither of those is a
+ *    restore. Calling that "ignored" would report a repair that never
+ *    happened; it must fail the phase like any other breach instead.
+ *  - The path does NOT match `defaults.protected_files`. `protected_files`
+ *    is what made this a breach in the first place (`permitted()` above);
+ *    `read_only_ignore` matching the SAME path too is not a stronger claim
+ *    that the write was safe, it just means an operator's lockfile-churn
+ *    pattern happens to overlap a path they explicitly protected. Without
+ *    this check a `read_only_ignore` entry could silently exempt a
+ *    read-only agent from `protected_files` — the very thing `protected_files`
+ *    exists to prevent regardless of an agent's `writes` role. So a
+ *    protected path is never ignorable: it always falls through to the
+ *    real-breach path below, still rolled back, but failing the phase.
+ */
+function isSafeToIgnore(p, agent, cfg, before) {
+    const isTrueReadOnlyAgent = Array.isArray(agent.writes) && agent.writes.length === 0;
+    const isProtected = cfg.defaults.protected_files.some((pattern) => matches(p, pattern));
+    return isTrueReadOnlyAgent && isIgnorableChurn(p, cfg) && !(p in before) && !isProtected;
+}
 /**
  * Compare the tree against `before`; undo and raise if the agent overstepped.
  *
@@ -169,19 +234,42 @@ function rollBack(run, p, before, after) {
  * Detection alone would leave the repo holding the unauthorized change while
  * reporting a failure, so anything the agent introduced outside its allowlist
  * is rolled back before the phase dies. What it cannot undo, it names.
+ *
+ * `defaults.read_only_ignore` carves out one exception to "names, fails" —
+ * but only where `isSafeToIgnore` says restoring is actually possible (see
+ * its own doc comment): a TRUE read-only agent (`writes: []`) that churned
+ * a lockfile that was CLEAN before this phase. That one case is STILL
+ * rolled back unconditionally like any other breach — an ignored path is
+ * never left standing — it just does not, on its own, fail the phase.
+ * Everything else `isIgnorableChurn` alone would have matched (a dirty-before
+ * path, an agent that reverted uncommitted work, a write-restricted rather
+ * than read-only agent) falls through to the real-breach path below instead.
+ * `onIgnored`, when given, is called once with every safely-ignored path
+ * before returning, so a caller with a logger (`agents.ts`'s `execute()`)
+ * can print the one required info line — this module has no logger of its
+ * own to call (`RunLike` is only `repo_root`/`cfg`), so the caller does the
+ * printing.
  */
-export function enforce(run, _phase, agent, before) {
+export function enforce(run, _phase, agent, before, onIgnored) {
     const after = snapshot(run);
     const touched = changedPaths(before, after);
     const breaches = touched.filter((p) => !permitted(p, agent, run.cfg));
     if (breaches.length === 0)
         return touched;
+    const ignored = breaches.filter((p) => isSafeToIgnore(p, agent, run.cfg, before));
+    const realBreaches = breaches.filter((p) => !ignored.includes(p));
+    // Roll back EVERY breach, ignored ones included — restoring the tree is
+    // unconditional; only whether it fails the PHASE differs below.
     const outcomes = new Map(breaches.map((p) => [p, rollBack(run, p, before, after)]));
+    if (ignored.length > 0)
+        onIgnored?.(ignored);
+    if (realBreaches.length === 0)
+        return touched; // nothing left but ignored churn — rolled back, phase still passes
     const scope = agent.writes && agent.writes.length === 0
         ? "read-only"
         : agent.writes
             ? `limited to ${JSON.stringify(agent.writes)}`
             : `barred from ${JSON.stringify(run.cfg.defaults.protected_files)}`;
-    const detail = [...outcomes.entries()].map(([p, outcome]) => `  - ${p} — ${outcome}`).join("\n");
-    throw new PermissionBreach(`${agent.name} is ${scope} but modified ${breaches.length} path(s):\n${detail}`);
+    const detail = realBreaches.map((p) => `  - ${p} — ${outcomes.get(p)}`).join("\n");
+    throw new PermissionBreach(`${agent.name} is ${scope} but modified ${realBreaches.length} path(s):\n${detail}`);
 }

package/dist/core/providers.js

@@ -21,9 +21,14 @@ export const PROVIDER_ENV_KEYS = {
     deepseek: ["DEEPSEEK_API_KEY"],
     together: ["TOGETHER_API_KEY"],
     cerebras: ["CEREBRAS_API_KEY"],
-    // Keyless: a local server, not a hosted API — nothing to check for or
-    // prompt for. An empty array here means "known provider, needs no key",
-    // never "unknown provider" (that's a missing table entry, not `[]`).
+    // Keyless by default: a local server, not a hosted API — nothing to
+    // require or prompt for. An empty array here means "known provider,
+    // needs no key", never "unknown provider" (that's a missing table entry,
+    // not `[]`). NOT the same as "no key is ever honored": ollama_provider.ts's
+    // `ollamaApiKey()` reads `OLLAMA_API_KEY` and sends it as the bearer when
+    // set (e.g. required by a gateway in front of Ollama, like Envoy AI
+    // Gateway), falling back to its dummy placeholder otherwise — optional,
+    // not required, which is why it stays out of this required-keys table.
     ollama: [],
     // Cloudflare Workers AI — a real Bearer token (NOT keyless like ollama;
     // Cloudflare's API 401s on an empty Authorization header). The base URL

package/dist/core/refine.js

@@ -41,7 +41,7 @@ export function resolveAuthoringProvider(cfg) {
         if (!email || !token) {
             throw new Error('JIRA_EMAIL and JIRA_API_TOKEN must both be set — the refine lane needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens)');
         }
-        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);
     }
     if (cfg.watch.issue_provider !== "github") {
         throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — the refine lane needs "github" or "jira"`);
@@ -232,6 +232,18 @@ export async function publish(tracker, issues, opts) {
             if (parent)
                 await tracker.linkChild(parent.issue, issue);
         }
+        else if (opts.specIssueId) {
+            // THE GAP THIS CLOSES: `node.parent` only ever names another node
+            // IN THIS TREE — the tree's own root(s) have none, so the branch
+            // above never runs for them, and nothing else in this loop connects
+            // a root back to the spec it was refined FROM. Before this, the only
+            // trace of that relationship was `renderBody`'s "## Parent" TEXT
+            // (still rendered, unchanged) — real on GitHub (auto-linked "#N"),
+            // invisible on Jira (plain text, no cross-reference). `linkToSpec` is
+            // optional and best-effort on purpose — see its own doc comment
+            // (`issues/provider.ts`) for why this is never `linkChild`.
+            await tracker.linkToSpec?.(opts.specIssueId, issue);
+        }
     }
     return created;
 }

package/dist/core/runner.d.ts

@@ -11,7 +11,7 @@
 import { type GitHandle } from "./git_helper.ts";
 import { Console, type RunObserver } from "./console.ts";
 import { Tracer } from "./tracer.ts";
-import { type AgentCall, type EnvelopeBase, type Phase, type PhaseParams, type SFConfig } from "./data_types.ts";
+import { type AgentCall, type AgentConfig, type EnvelopeBase, type Phase, type PhaseParams, type SFConfig } from "./data_types.ts";
 import type { TierResolution } from "./tiering.ts";
 import type { Notifier } from "./notify/notifier.ts";
 interface AgentMapEntry {
@@ -60,6 +60,30 @@ export declare class Run {
     phases: Phase[];
     tokens: number;
     cost: number;
+    /** The BILLABLE half of `tokens` — see `UsageBreakdown.billable_tokens`'s doc comment. What `assertRunBudget` actually checks `defaults.max_run_tokens` against; `tokens` stays the display total. */
+    billable_tokens: number;
+    /**
+     * True once this run has DISPATCHED at least one `claude_code` agent
+     * while `ANTHROPIC_BASE_URL` pointed somewhere other than Anthropic's own
+     * API — i.e. a gateway/proxy stood in for Anthropic on a call that
+     * actually happened. Read by `Console.sessionFinished` to label the run's
+     * printed cost as an estimate rather than a fact: `claude`'s own
+     * `total_cost_usd` is ANTHROPIC's price table applied to whatever the CLI
+     * thinks it called, which is honest only when Anthropic itself served the
+     * request.
+     *
+     * Starts `false` and is flipped by `recordDispatch()` below, called once
+     * per agent dispatch (`agents.ts`'s `execute()`, right before the real
+     * coding-agent call) — computed from what this run actually DISPATCHED,
+     * never from the roster's static shape (see `agents.ts`'s
+     * `isGatewayEstimatedDispatch` vs. `isGatewayEstimatedCost` doc comments
+     * for why that distinction matters: a chain can configure a `claude_code`
+     * agent it never actually calls this run, and labeling a real cost as
+     * "estimated" because the roster merely CONTAINS such an agent would be
+     * its own kind of dishonesty). Sticky: once a qualifying dispatch has
+     * happened, a later non-qualifying one must never flip it back to false.
+     */
+    cost_is_estimate: boolean;
     repo_root: string;
     /** Every git operation for this run, bound to repo_root. Never call git_helper directly. */
     git: GitHandle;
@@ -81,7 +105,14 @@ export declare class Run {
     private agentMapPath;
     constructor(init: RunInit);
     saveAgentMap(agent: string, entry: AgentMapEntry): void;
-    addUsage(tokens: number, cost: number): Promise<void>;
+    /**
+     * Called once per agent dispatch, right before the real coding-agent call
+     * (`agents.ts`'s `execute()`) — see `cost_is_estimate`'s own doc comment
+     * for why this, not the roster, is what decides the label. Sticky: only
+     * ever flips `cost_is_estimate` from false to true, never back.
+     */
+    recordDispatch(agent: AgentConfig): void;
+    addUsage(tokens: number, cost: number, billableTokens: number): Promise<void>;
     phase<T>(params: PhaseParams, fn: (ph: PhaseHandle) => Promise<T>): Promise<T>;
     /**
      * Finalize the run and return its exit code. Call this exactly once.

package/dist/core/runner.js

@@ -66,6 +66,30 @@ export class Run {
     phases = [];
     tokens = 0;
     cost = 0;
+    /** The BILLABLE half of `tokens` — see `UsageBreakdown.billable_tokens`'s doc comment. What `assertRunBudget` actually checks `defaults.max_run_tokens` against; `tokens` stays the display total. */
+    billable_tokens = 0;
+    /**
+     * True once this run has DISPATCHED at least one `claude_code` agent
+     * while `ANTHROPIC_BASE_URL` pointed somewhere other than Anthropic's own
+     * API — i.e. a gateway/proxy stood in for Anthropic on a call that
+     * actually happened. Read by `Console.sessionFinished` to label the run's
+     * printed cost as an estimate rather than a fact: `claude`'s own
+     * `total_cost_usd` is ANTHROPIC's price table applied to whatever the CLI
+     * thinks it called, which is honest only when Anthropic itself served the
+     * request.
+     *
+     * Starts `false` and is flipped by `recordDispatch()` below, called once
+     * per agent dispatch (`agents.ts`'s `execute()`, right before the real
+     * coding-agent call) — computed from what this run actually DISPATCHED,
+     * never from the roster's static shape (see `agents.ts`'s
+     * `isGatewayEstimatedDispatch` vs. `isGatewayEstimatedCost` doc comments
+     * for why that distinction matters: a chain can configure a `claude_code`
+     * agent it never actually calls this run, and labeling a real cost as
+     * "estimated" because the roster merely CONTAINS such an agent would be
+     * its own kind of dishonesty). Sticky: once a qualifying dispatch has
+     * happened, a later non-qualifying one must never flip it back to false.
+     */
+    cost_is_estimate = false;
     repo_root; // where every agent is spawned to work — always absolute
     /** Every git operation for this run, bound to repo_root. Never call git_helper directly. */
     git;
@@ -107,12 +131,23 @@ export class Run {
         this.agent_map[agent] = entry;
         writeFileSync(this.agentMapPath, JSON.stringify(this.agent_map, null, 2));
     }
+    /**
+     * Called once per agent dispatch, right before the real coding-agent call
+     * (`agents.ts`'s `execute()`) — see `cost_is_estimate`'s own doc comment
+     * for why this, not the roster, is what decides the label. Sticky: only
+     * ever flips `cost_is_estimate` from false to true, never back.
+     */
+    recordDispatch(agent) {
+        if (agents.isGatewayEstimatedDispatch(agent))
+            this.cost_is_estimate = true;
+    }
     // ── usage (run totals mirror what the tracer accumulates in the trace db) ─
-    async addUsage(tokens, cost) {
+    async addUsage(tokens, cost, billableTokens) {
         this.tokens += tokens;
         this.cost += cost;
-        await this.tracer.sessionAddUsage(this.adw_id, tokens, cost);
-        await this.console.notifyUsage(this.tokens, this.cost);
+        this.billable_tokens += billableTokens;
+        await this.tracer.sessionAddUsage(this.adw_id, tokens, cost, billableTokens);
+        await this.console.notifyUsage(this.tokens, this.cost, this.billable_tokens);
     }
     // ── the phase primitive ─────────────────────────────────────────────────
     async phase(params, fn) {
@@ -157,7 +192,7 @@ export class Run {
             await this.tracer.phaseUpsert(phase);
             await this.tracer.sessionFinish(this.adw_id, false);
             await this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
-            await this.console.sessionFinished(false, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db));
+            await this.console.sessionFinished(false, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db), this.cost_is_estimate);
             throw error;
         }
     }
@@ -185,7 +220,7 @@ export class Run {
             await this.console.note(`not accepted: ${note}`);
         }
         await this.tracer.sessionFinish(this.adw_id, ok);
-        await this.console.sessionFinished(ok, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db));
+        await this.console.sessionFinished(ok, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db), this.cost_is_estimate);
         return ok ? 0 : 1;
     }
 }

package/dist/core/tiering.js

@@ -25,7 +25,7 @@
  * stands. `effectiveAgent` is the one place that turns a resolution into an
  * actual `AgentConfig` — overriding `model` and NOTHING else.
  */
-import { ollamaBaseUrl } from "./ollama_provider.js";
+import { ollamaApiKey, ollamaBaseUrl } from "./ollama_provider.js";
 // ── the classifier (design doc §2) ──────────────────────────────────────────
 /**
  * One explicit `name -> weight` table entry per BUILT-IN chain
@@ -184,9 +184,13 @@ async function fetchServedOllamaTags() {
     try {
         // ollamaBaseUrl() is the SAME default-substitution a real dispatch
         // uses, including treating a set-but-EMPTY OLLAMA_BASE_URL as unset —
-        // never re-derive that default here.
+        // never re-derive that default here. Same for ollamaApiKey(): against a
+        // gateway (not bare Ollama) this endpoint 401s without a bearer — send
+        // the SAME dummy-or-real bearer a real dispatch sends (byte-identical
+        // to doctor.ts's own OLLAMA_BASE_URL reachability probe), or this probe
+        // fails closed (401 -> null) even when a real dispatch would succeed.
         const url = ollamaBaseUrl().replace(/\/+$/, "") + "/models";
-        const res = await fetch(url, { signal: controller.signal });
+        const res = await fetch(url, { signal: controller.signal, headers: { authorization: `Bearer ${ollamaApiKey()}` } });
         if (res.status !== 200)
             return null;
         const body = (await res.json());

package/dist/core/tracer.d.ts

@@ -87,7 +87,13 @@ export declare class Tracer {
     sessionStart(adwId: string, engineer: string, adwName?: string | null): Promise<void>;
     sessionRequest(adwId: string, request: string): Promise<void>;
     sessionFinish(adwId: string, ok: boolean): Promise<void>;
-    sessionAddUsage(adwId: string, tokens: number, cost: number): Promise<void>;
+    /**
+     * `tokens`/`cost` are the DISPLAY totals (`total_tokens`, unchanged from
+     * before `billable_tokens` existed); `billableTokens` is the new column —
+     * see `UsageBreakdown.billable_tokens`'s doc comment for what it excludes
+     * and why. Both accumulate in the same row, same as before.
+     */
+    sessionAddUsage(adwId: string, tokens: number, cost: number, billableTokens: number): Promise<void>;
     /**
      * Record a live process for this run.
      *

package/dist/core/tracer.js

@@ -123,6 +123,12 @@ const MIGRATIONS = [
     ["agent_sessions", "context_tokens", "INTEGER"],
     ["agent_sessions", "context_window", "INTEGER"],
     ["sessions", "archived", "INTEGER DEFAULT 0"],
+    // The BILLABLE half of `total_tokens` — see `UsageBreakdown.billable_tokens`'s
+    // own doc comment (`data_types.ts`) for why the two diverge. `total_tokens`
+    // is untouched (still every re-sent token, cache reads included); this is
+    // the new column `sessionAddUsage` also increments, so a trace db from
+    // before this existed just gets a column full of 0 until its next run.
+    ["sessions", "billable_tokens", "INTEGER DEFAULT 0"],
 ];
 export class Tracer {
     db;
@@ -285,10 +291,16 @@ export class Tracer {
         if (processesError)
             throw processesError;
     }
-    async sessionAddUsage(adwId, tokens, cost) {
+    /**
+     * `tokens`/`cost` are the DISPLAY totals (`total_tokens`, unchanged from
+     * before `billable_tokens` existed); `billableTokens` is the new column —
+     * see `UsageBreakdown.billable_tokens`'s doc comment for what it excludes
+     * and why. Both accumulate in the same row, same as before.
+     */
+    async sessionAddUsage(adwId, tokens, cost, billableTokens) {
         await this.db
-            .query("UPDATE sessions SET total_tokens=total_tokens+?, total_cost=total_cost+? WHERE adw_id=?")
-            .run(tokens, cost, adwId);
+            .query("UPDATE sessions SET total_tokens=total_tokens+?, total_cost=total_cost+?, billable_tokens=billable_tokens+? WHERE adw_id=?")
+            .run(tokens, cost, billableTokens, adwId);
     }
     // ── processes (adw_id → pid, so a hung run can be found and killed) ─────
     /**

package/dist/ui/server/db.d.ts

@@ -180,10 +180,17 @@ export interface ChainHistorySession {
     started_at: string | null;
     total_tokens: number;
     total_cost: number;
-    /** In `phases.seq` order; one entry per phase iteration (e.g. `fix_1`, `fix_2`), not yet loop-normalized. */
+    /**
+     * In `phases.seq` order; one entry per phase iteration (e.g. `fix_1`,
+     * `fix_2`), not yet loop-normalized. `tokens` is the display total;
+     * `billable_tokens` is what `spf estimate`'s ceiling projection
+     * (`findCutoffPhase`) actually walks against `defaults.max_run_tokens` —
+     * see that field's own doc comment above for the old-row fallback.
+     */
     phases: {
         name: string;
         seq: number;
         tokens: number;
+        billable_tokens: number;
     }[];
 }

package/dist/ui/server/db.js

@@ -237,7 +237,7 @@ export class SfDb {
         const rows = await this.db
             .query(`SELECT adw_id, ${await this.optionalColumn("sessions", "adw_name")}, request,
                 status, engineer, started_at, ended_at,
-                total_tokens, total_cost,
+                total_tokens, total_cost, ${await this.optionalColumn("sessions", "billable_tokens")},
                 ${await this.optionalColumn("sessions", "archived")}
            FROM sessions
           WHERE COALESCE(${(await this.hasColumn("sessions", "archived")) ? "archived" : "0"}, 0) = 0
@@ -282,7 +282,7 @@ export class SfDb {
         return ((await this.db
             .query(`SELECT adw_id, ${await this.optionalColumn("sessions", "adw_name")}, request,
                   status, engineer, started_at, ended_at,
-                  total_tokens, total_cost
+                  total_tokens, total_cost, ${await this.optionalColumn("sessions", "billable_tokens")}
              FROM sessions WHERE adw_id = ?`)
             .get(adwId)) ?? null);
     }
@@ -497,7 +497,7 @@ export class SfDb {
         const phaseRows = await this.chunked(ids, (chunk) => {
             const placeholders = chunk.map(() => "?").join(", ");
             return this.db
-                .query(`SELECT p.adw_id, p.name, p.seq, e.tokens
+                .query(`SELECT p.adw_id, p.name, p.seq, e.tokens, e.payload_json
              FROM phases p LEFT JOIN events e ON e.phase_id = p.phase_id AND e.type = 'agent_end'
             WHERE p.adw_id IN (${placeholders})
             ORDER BY p.seq ASC`)
@@ -506,7 +506,24 @@ export class SfDb {
         const phasesByAdw = new Map();
         for (const row of phaseRows) {
             const list = phasesByAdw.get(row.adw_id);
-            const entry = { name: row.name, seq: row.seq, tokens: row.tokens ?? 0 };
+            const totalTokens = row.tokens ?? 0;
+            // Derived from the payload, same "parse it in JS" approach `usage()`
+            // above already uses (never a stored column) — so a phase from before
+            // `billable_tokens` existed just falls back to the total, exactly
+            // like `Session.billable_tokens`'s own doc comment (`ui/shared/types.ts`)
+            // describes for the session-level number.
+            let billableTokens = totalTokens;
+            if (row.payload_json) {
+                try {
+                    const usage = JSON.parse(row.payload_json).usage;
+                    if (usage && typeof usage.billable_tokens === "number")
+                        billableTokens = usage.billable_tokens;
+                }
+                catch {
+                    /* a payload written by an older tracer simply falls back to the total */
+                }
+            }
+            const entry = { name: row.name, seq: row.seq, tokens: totalTokens, billable_tokens: billableTokens };
             if (list)
                 list.push(entry);
             else

package/dist/ui/server/serve.d.ts

@@ -7,6 +7,13 @@ export interface UiOptions {
     webDir: string;
     /** Explicit port. Omit to try the default and probe upward on collision. */
     port?: number;
+    /**
+     * Bind address. Omit for the safe default (`127.0.0.1`, loopback-only).
+     * Set explicitly (e.g. `"0.0.0.0"`, or a specific interface IP) to make
+     * this reachable off-box — a deliberate widening, not something a caller
+     * should ever get by accident. See the module doc comment above.
+     */
+    host?: string;
     open?: boolean;
 }
 export interface UiHandle {

package/dist/ui/server/serve.js

@@ -2,9 +2,11 @@
  * `spf ui` bootstrap: bind the app to a real port, print the URL, optionally
  * open a browser, and shut down cleanly on SIGINT/SIGTERM.
  *
- * Binds loopback-only (127.0.0.1) deliberately — this server can flip a
- * database column and reveal agent prompts, and a companion CLI has no
- * reason to listen on every interface.
+ * Binds loopback-only (127.0.0.1) by DEFAULT, deliberately — this server can
+ * flip a database column and reveal agent prompts, and a companion CLI has
+ * no reason to listen on every interface unless someone explicitly asks for
+ * it via `options.host` (`--host` on the CLI). Widening the bind is an
+ * opt-in the caller states on purpose, not a default — see issue #90.
  */
 import { spawn } from "node:child_process";
 import { serve } from "@hono/node-server";
@@ -15,9 +17,9 @@ const PORT_PROBE_ATTEMPTS = 10;
 function isAddrInUse(error) {
     return typeof error === "object" && error !== null && error.code === "EADDRINUSE";
 }
-function listen(app, port) {
+function listen(app, port, hostname) {
     return new Promise((resolvePromise, reject) => {
-        const server = serve({ fetch: app.fetch, port, hostname: "127.0.0.1" }, () => resolvePromise(server));
+        const server = serve({ fetch: app.fetch, port, hostname }, () => resolvePromise(server));
         server.on("error", reject);
     });
 }
@@ -37,6 +39,7 @@ function openUrl(url) {
 export async function runUi(options) {
     const db = await SfDb.open(options.db, options.sessionsDir);
     const app = createApp(db, options.webDir);
+    const host = options.host ?? "127.0.0.1";
     const explicit = options.port !== undefined;
     const startPort = options.port ?? DEFAULT_PORT;
     let server;
@@ -45,7 +48,7 @@ export async function runUi(options) {
     for (let i = 0; i < attempts; i++) {
         port = startPort + i;
         try {
-            server = await listen(app, port);
+            server = await listen(app, port, host);
             break;
         }
         catch (error) {
@@ -61,7 +64,7 @@ export async function runUi(options) {
     }
     const info = server.address();
     const boundPort = info?.port ?? port;
-    const url = `http://127.0.0.1:${boundPort}`;
+    const url = `http://${host}:${boundPort}`;
     const shouldOpen = options.open !== false && process.stdout.isTTY && !process.env.CI && !process.env.SSH_CONNECTION;
     if (shouldOpen)
         openUrl(url);

package/dist/ui/shared/types.d.ts

@@ -24,6 +24,22 @@ export interface Session {
     ended_at: string | null;
     total_tokens: number | null;
     total_cost: number | null;
+    /**
+     * The BILLABLE half of `total_tokens` — see `UsageBreakdown.billable_tokens`'s
+     * doc comment (`core/data_types.ts`) for why the two diverge.
+     *
+     * Two ways a row can predate real tracking, both meaning "fall back to
+     * `total_tokens`" (see `cli/commands/loop.ts`'s readback):
+     *  - `null`: this db has never run the migration that adds the column at
+     *    all (`optionalColumn` in `db.ts` substitutes `NULL AS billable_tokens`
+     *    against it) — only possible for a db a writer Tracer has never opened
+     *    since this column shipped.
+     *  - `0` while `total_tokens > 0`: the column exists (a Tracer's
+     *    `ALTER TABLE ... DEFAULT 0` ran) but this SPECIFIC row was written
+     *    before that, so it was backfilled to 0 rather than to the true
+     *    (unknowable, after the fact) billable figure.
+     */
+    billable_tokens: number | null;
     /** 1 once archived out of the review list. Review state, not run state. */
     archived: number | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",
@@ -42,8 +42,8 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "0.83.0",
-    "@flue/opentelemetry": "2.0.4",
-    "@flue/runtime": "2.0.3",
+    "@flue/opentelemetry": "2.0.5",
+    "@flue/runtime": "2.0.5",
     "@hono/node-server": "^2.1.1",
     "@inkjs/ui": "^2.0.0",
     "@opentelemetry/api": "1.9.1",