@gr8ful/spf 0.19.0 → 0.19.1

package/dist/core/console.js

@@ -100,17 +100,30 @@ export class Console {
             ],
         });
     }
-    async sessionFinished(ok, tokens, cost, dbPath) {
+    /**
+     * `costIsEstimate` (default `false`, byte-identical to before this param
+     * existed): true when `run.cost_is_estimate` found a `claude_code` agent
+     * pointed at a non-Anthropic `ANTHROPIC_BASE_URL` (see `runner.ts`'s
+     * `Run.recordDispatch` / `agents.ts`'s `isGatewayEstimatedDispatch`) —
+     * `total_cost_usd` from `claude`'s own CLI is
+     * Anthropic's price table applied client-side, which is a fact only when
+     * Anthropic itself served the request, and a labeled guess otherwise. The
+     * label is cosmetic only: `cost` itself is unchanged (still the real sum
+     * `UsageBreakdown.total_cost` accumulated), and nothing about the budget
+     * check (`assertRunBudget`) reads this flag.
+     */
+    async sessionFinished(ok, tokens, cost, dbPath, costIsEstimate = false) {
         if (this.finished)
             return;
         this.finished = true;
         const passed = this.results.filter((r) => r === "success").length;
         const status = ok ? paint("green", "✓ success") : paint("red", "✗ fail");
+        const costText = costIsEstimate ? `≈ $${cost.toFixed(4)} (claude_code estimate; gateway-billed)` : `$${cost.toFixed(4)}`;
         const rows = [
             ` ${paint("dim", "status")}   ${status}`,
             ` ${paint("dim", "phases")}   ${passed}/${this.results.length} passed`,
             ` ${paint("dim", "tokens")}   ${tokens.toLocaleString()}`,
-            ` ${paint("dim", "cost")}     $${cost.toFixed(4)}`,
+            ` ${paint("dim", "cost")}     ${costText}`,
             ` ${paint("dim", "adw_id")}   ${this.adwId}`,
             ` ${paint("dim", "db")}       ${dbPath}`,
             ` ${paint("dim", "next")}     ${paint("bold", `just phases ${this.adwId}`)}`,
@@ -118,7 +131,7 @@ export class Console {
         const rendered = panel(rows, "ADW complete", ok ? "green" : "red");
         this.sink(rendered);
         this.observer?.onSessionEnd?.(ok);
-        const plain = `session ${this.adwId} ${ok ? "success" : "fail"} · ${passed}/${this.results.length} phases · ${tokens.toLocaleString()} tokens · $${cost.toFixed(4)}`;
+        const plain = `session ${this.adwId} ${ok ? "success" : "fail"} · ${passed}/${this.results.length} phases · ${tokens.toLocaleString()} tokens · ${costText}`;
         await this.tracer.event(makeEventRecord({
             adw_id: this.adwId,
             phase_id: this.phaseId,
@@ -134,7 +147,7 @@ export class Console {
                 ["adw_id", this.adwId],
                 ["phases", `${passed}/${this.results.length}`],
                 ["tokens", tokens.toLocaleString()],
-                ["cost", `$${cost.toFixed(4)}`],
+                ["cost", costText],
             ],
         });
     }
@@ -179,9 +192,9 @@ export class Console {
     async note(message) {
         await this.emit(`  ${paint("dim", `· ${clip(message)}`)}`);
     }
-    /** `Run.addUsage()`'s only hook into `Console` — the running total lives on `Run`, not here, so this just forwards it to the observer. No line prints for this on its own; the totals already show up in `sessionFinished`'s panel. */
-    async notifyUsage(tokens, cost) {
-        this.observer?.onUsage?.(tokens, cost);
+    /** `Run.addUsage()`'s only hook into `Console` — the running totals live on `Run`, not here, so this just forwards them to the observer. No line prints for this on its own; the totals already show up in `sessionFinished`'s panel. `billableTokens` rides alongside `tokens` so a consumer comparing against `defaults.max_run_tokens` (a billable ceiling) never has to guess which number to use — see `RunObserver.onUsage`'s own doc comment. */
+    async notifyUsage(tokens, cost, billableTokens) {
+        this.observer?.onUsage?.(tokens, cost, billableTokens);
     }
     // ── agents ──────────────────────────────────────────────────────────────
     async agentStarted(name, model, sessionId) {

package/dist/core/data_types.d.ts

@@ -696,6 +696,41 @@ export declare const ConfigDefaultsSchema: v.ObjectSchema<{
     readonly harness_engineering: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
     readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly protected_files: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => string[]>;
+    /**
+     * 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.
+     */
+    readonly read_only_ignore: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => string[]>;
     readonly data_dir: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data">;
     /**
      * RUN BUDGET CEILINGS — the two knobs that bound what one adw_id may spend.
@@ -718,11 +753,20 @@ export declare const ConfigDefaultsSchema: v.ObjectSchema<{
      * `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
@@ -741,6 +785,43 @@ export declare const ConfigDefaultsSchema: v.ObjectSchema<{
      */
     readonly max_run_cost: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
     readonly max_run_tokens: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
+    /**
+     * 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.
+     */
+    readonly request_timeout_ms: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
 }, undefined>;
 export type ConfigDefaults = v.InferOutput<typeof ConfigDefaultsSchema>;
 /**
@@ -1050,6 +1131,30 @@ export declare const WatchJiraConfigSchema: v.ObjectSchema<{
         done?: string | undefined;
         blocked?: string | undefined;
     }>;
+    /**
+     * 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.
+     */
+    readonly link_type: v.OptionalSchema<v.StringSchema<undefined>, "Relates">;
 }, undefined>;
 export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
 /**
@@ -1278,6 +1383,30 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
             done?: string | undefined;
             blocked?: string | undefined;
         }>;
+        /**
+         * 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.
+         */
+        readonly link_type: v.OptionalSchema<v.StringSchema<undefined>, "Relates">;
     }, undefined>, () => {
         base_url: string;
         project_key: string;
@@ -1297,6 +1426,7 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
             done?: string | undefined;
             blocked?: string | undefined;
         };
+        link_type: string;
     }>;
     readonly github: v.OptionalSchema<v.ObjectSchema<{
         readonly project_number: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, 0>;
@@ -1488,6 +1618,41 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly harness_engineering: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
         readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly protected_files: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => string[]>;
+        /**
+         * 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.
+         */
+        readonly read_only_ignore: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => string[]>;
         readonly data_dir: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data">;
         /**
          * RUN BUDGET CEILINGS — the two knobs that bound what one adw_id may spend.
@@ -1510,11 +1675,20 @@ export declare const SFConfigSchema: v.ObjectSchema<{
          * `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
@@ -1533,6 +1707,43 @@ export declare const SFConfigSchema: v.ObjectSchema<{
          */
         readonly max_run_cost: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
         readonly max_run_tokens: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
+        /**
+         * 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.
+         */
+        readonly request_timeout_ms: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
     }, undefined>, () => {
         coding_agent: "claude_code" | "flue" | "opencode";
         model: string;
@@ -1541,9 +1752,11 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         harness_engineering: string[];
         tools?: string[] | null | undefined;
         protected_files: string[];
+        read_only_ignore: string[];
         data_dir: string;
         max_run_cost?: number | undefined;
         max_run_tokens?: number | undefined;
+        request_timeout_ms?: number | undefined;
     }>;
     readonly observability: v.OptionalSchema<v.ObjectSchema<{
         readonly db: v.OptionalSchema<v.SchemaWithPipe<readonly [v.UnknownSchema, v.RawTransformAction<unknown, string | {
@@ -1689,6 +1902,30 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 done?: string | undefined;
                 blocked?: string | undefined;
             }>;
+            /**
+             * 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.
+             */
+            readonly link_type: v.OptionalSchema<v.StringSchema<undefined>, "Relates">;
         }, undefined>, () => {
             base_url: string;
             project_key: string;
@@ -1708,6 +1945,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 done?: string | undefined;
                 blocked?: string | undefined;
             };
+            link_type: string;
         }>;
         readonly github: v.OptionalSchema<v.ObjectSchema<{
             readonly project_number: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, 0>;
@@ -1791,6 +2029,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 done?: string | undefined;
                 blocked?: string | undefined;
             };
+            link_type: string;
         };
         github: {
             project_number: number;
@@ -2011,21 +2250,45 @@ export interface AgentRequest {
     output_type_name: string;
     cwd: string;
     flue_db_path: string;
+    request_timeout_ms?: number;
     env?: Record<string, string>;
     /** Absent (the default) => local(), byte-identical to before this field existed. See sandbox.ts. */
     sandbox?: SandboxSpec;
+    /**
+     * The run's own adw_id / the calling agent's name — set by `agents.ts`'s
+     * `send()` from `run.adw_id`/`agent.name`, which are unconditionally in
+     * scope there (unlike `otel` below, this pair is NOT gated on
+     * `observability.otel` being configured: a gateway that groups calls by
+     * `x-correlation-id`/`x-spf-agent` needs them on every call, not only when
+     * SPF's own OTel export happens to be turned on). Consulted today only by
+     * `agent_flue.ts`'s ollama registration (see `ollama_provider.ts`'s
+     * `GatewayCallContext`); every other backend ignores both fields, so this
+     * addition is byte-identical to before it existed for them.
+     */
+    adw_id?: string;
+    agent_name?: string;
     /**
      * Outbound OTel trace-context propagation — set by `agents.ts`'s `send()`
      * from `otel.ts`'s `OtelExporter.agentCallTraceContext()` ONLY when
-     * `observability.otel` is configured for this run; absent otherwise, and
-     * every backend that ignores it (`opencode` today) is byte-identical to
-     * before this field existed. `traceparent`/`x_request_id` are this call's
-     * own span context (`agent_cc.ts`'s single `spawn()` choke point turns
-     * them into `TRACEPARENT`/`ANTHROPIC_CUSTOM_HEADERS`); `endpoint`/
-     * `headers`/`service_name` are the SAME `observability.otel` block,
-     * carried through so `agent_flue.ts` can install its own (separate,
-     * process-scoped — see `otel_propagation.ts`) global http/undici
-     * propagation without needing the full `SFConfig`.
+     * `observability.otel` is configured for this run; absent otherwise.
+     * `traceparent` is this call's own span context — `agent_cc.ts`'s single
+     * `spawn()` choke point turns it (alongside `adw_id`/`agent_name` above,
+     * which are NOT gated on this field) into `TRACEPARENT`/
+     * `ANTHROPIC_CUSTOM_HEADERS`; `agent_opencode.ts` does the analogous thing
+     * into its temp `opencode.json`. `endpoint`/`headers`/`service_name` are
+     * the SAME `observability.otel` block, carried through so `agent_flue.ts`
+     * can install its own (separate, process-scoped — see
+     * `otel_propagation.ts`) global http/undici propagation without needing
+     * the full `SFConfig`.
+     *
+     * `x_request_id` (this call's own span id) is no longer turned into any
+     * outbound header by anything in this repo — `agent_cc.ts`/
+     * `agent_opencode.ts` used to send it as `x-request-id` and no longer do
+     * (BLOCKER B: Envoy/Switchyard own that header end-to-end; a client-sent
+     * value broke their own trace sampling). Kept as a field (rather than
+     * removed) since it is still a well-defined, harmless-to-carry value — a
+     * future consumer that needs "this call's own span id" for something
+     * other than a header has it available — but nothing reads it today.
      */
     otel?: {
         traceparent: string;
@@ -2049,6 +2312,24 @@ export declare class UsageBreakdown {
     cache_write_tokens: number;
     reasoning_tokens: number;
     total_tokens: number;
+    /**
+     * 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: number;
     input_cost: number;
     output_cost: number;
     cache_read_cost: number;