@gr8ful/spf 0.19.0 → 0.19.1

package/dist/core/otel_propagation.js

@@ -14,8 +14,11 @@
  * `-undici` create a real client span (with a real, non-noop SpanContext)
  * around every outbound `http`/`https`/`fetch`(undici) call made from this
  * process, and the OTel API's global propagator is what those
- * instrumentations use to inject `traceparent` (and, here, `x-request-id`)
- * into that call's headers — REGARDLESS of which provider SDK issued it.
+ * instrumentations use to inject `traceparent` (and, here, the gateway's own
+ * `x-correlation-id`/`x-spf-agent` — see GatewayHeadersPropagator below;
+ * NEVER `x-request-id`, which Envoy/Switchyard own end-to-end and which a
+ * client-sent value would corrupt) into that call's headers — REGARDLESS of
+ * which provider SDK issued it.
  * This reaches every provider whose Node SDK issues requests through
  * Node's own `http`/`https` modules or `undici` (verified: `fetch()`,
  * `https.request()`). It does NOT reach a provider transport that bypasses
@@ -58,7 +61,64 @@
  * agent processing", which is the id SPF mints and hands to
  * `init(SfAgent, { id })`. Extraction goes through the globally
  * registered propagator against ROOT_CONTEXT, so no leaked loop context
- * can stick. Consequences, all intended:
+ * can stick.
+ *
+ * BLOCKER 1 (fixed) — `resolveRootContext`'s return value NEVER becomes the
+ * active context. Verified against `@flue/opentelemetry`'s own dist
+ * (index.mjs:361 for the `chat <model>` span, :329 for the interceptor that
+ * activates it): the resolved `Context` is passed to `tracer.startSpan(...)`
+ * ONLY as `parentContext` — it supplies the new span's trace id/parent span
+ * id and is then discarded. What actually gets activated around the real
+ * dispatch is `context.with(trace.setSpan(context.active(), span), next)` —
+ * a context built from `context.active()` (whatever was active before,
+ * almost always ROOT) plus the freshly minted `span`, NOT the resolved
+ * context itself. A prior version of this module stashed the session's
+ * `adw_id`/`agent_name` as a plain context VALUE on the context
+ * `resolveFlueRootContext` returned (keyed under a private context key) and
+ * had `GatewayHeadersPropagator` read that value back at inject time — which
+ * can never work, because that exact context object is never the one made
+ * active; only its SpanContext (traceId/spanId/flags) survives, carried by
+ * the new span. Confirmed live: `scratchpad/probe_installed_real.mjs`,
+ * reproducing flue's exact two-line sequence against a real pi-ai dispatch,
+ * printed `x-correlation-id: ABSENT` / `x-spf-agent: ABSENT` before this fix.
+ *
+ * THE FIX: key the registration by TRACE ID instead of by context identity.
+ * `registerFlueSessionTrace` now ALSO records, in `traceIdRegistrations`,
+ * the trace id parsed out of the very `traceparent` it's given — the same
+ * deterministic trace id `resolveFlueRootContext` extracts and hands to
+ * `tracer.startSpan` as that span's parent, so the span it creates carries
+ * that exact trace id forward into whatever context DOES get activated.
+ * `GatewayHeadersPropagator.inject()` below reads `trace.getSpanContext(ctx)
+ * ?.traceId` — the thing that provably survives into the active context at
+ * request time — and looks IT UP in `traceIdRegistrations`, rather than
+ * trying to read a value off a context object that was never activated.
+ * One deterministic trace id per adw_id (`otel.ts:556`'s `traceIdFor(adwId)`,
+ * reused for EVERY agent call in that run — `otel.ts:737`'s
+ * `agentCallTraceContext` varies only the span id, never the trace id), and
+ * `traceIdRegistrations` is keyed on that trace id alone, not on session id
+ * or span id. So "latest registration for this trace id wins" is exact
+ * within a run when its agents run one at a time — which is how a `fanout`
+ * attempt's own agents run: `fanout.ts:448` derives each attempt its OWN
+ * adw_id, so distinct fanout attempts get distinct trace ids and cannot
+ * collide here, regardless of `fanout`'s concurrency. The one real collision
+ * this map can still see is narrower and does not happen in SPF today: TWO
+ * AGENTS OVERLAPPING INSIDE ONE adw_id — a single run dispatching a second
+ * flue agent call before the first one's `unregisterFlueSessionTrace` has
+ * run — since both share that run's one trace id, the second
+ * `registerFlueSessionTrace` call overwrites the first agent's entry in
+ * `traceIdRegistrations` while its dispatch may still be in flight, and that
+ * agent's outbound request would then carry the OTHER agent's
+ * `x-correlation-id`/`x-spf-agent` (never a wrong `adw_id`, since both
+ * belong to the same run — only the wrong `agentName`). No chain SPF ships
+ * dispatches two agents concurrently within one adw_id; this is flagged as
+ * the mechanism's honest limit, not a bug being carried forward. The SAME
+ * registration carries this session's `adw_id`/agent name (see
+ * `FlueSessionRegistration`) so a
+ * session's `x-correlation-id`/`x-spf-agent` ride the exact same "resolved
+ * once per submission, read per real HTTP call" path as `traceparent` does,
+ * via `GatewayHeadersPropagator` below, instead of the static-per-model-id
+ * fallback `ollama_provider.ts` needs when this pipeline isn't installed at
+ * all (otel unconfigured). Consequences, all intended:
  *   - Flue's spans inherit SPF's sha256 trace id, parented under the
  *     right agent-call span PER SESSION — correct under multiple agents
  *     per process, concurrent agents, and claim-loop restarts alike. Span
@@ -66,17 +126,42 @@
  *   - The http/undici client spans' injected `traceparent` carries the
  *     deterministic id too, so Switchyard/vLLM hops land as descendants of
  *     SPF's trace — parity with `claude_code`'s `ANTHROPIC_CUSTOM_HEADERS`
- *     path. `x-request-id` stays the this-span id for request-keyed
- *     correlation, unchanged.
+ *     path. The same per-request injection point also carries THIS
+ *     session's `x-correlation-id`/`x-spf-agent`, correctly attributed even
+ *     when multiple sessions are concurrent in one process, AS LONG AS their
+ *     deterministic trace ids differ (their `ctx.id`s, and therefore their
+ *     registrations, are distinct) — see BLOCKER 1 above for the precise
+ *     lookup key.
  *   - Unmapped sessions (never registered, restarted process with a
  *     durable backlog, post-`unregister` straggler bookkeeping spans)
  *     resolve to an unparented root — flue's spans root a separate SDK
- *     trace exactly as v1 did, correlatable by `x-request-id`/`spf.adw_id`/
- *     time window. Degraded join, never an error and never MIS-attributed.
+ *     trace exactly as v1 did, correlatable by `spf.adw_id`/time window.
+ *     Degraded join, never an error and never MIS-attributed; the gateway
+ *     headers for exactly this case are simply ABSENT (no fallback identity
+ *     — see `GatewayHeadersPropagator.inject()` below) rather than guessing
+ *     at whichever session happened to register most recently.
  *   - flue's internal `executionContext.traceCarrier` (typed but not on
  *     the public `AgentDispatchRequest` surface) stays unused — noted here
  *     as flue's own escape hatch, not something SPF reaches into.
  *
+ * STATIC HEADERS STAY SUPPRESSED WHEN INSTALLED (BLOCKER 1's other half,
+ * decided AGAINST enabling): `ollama_provider.ts`'s `modelFor()` keeps
+ * omitting `Model.headers`' `x-correlation-id`/`x-spf-agent` whenever
+ * `isFluePropagationInstalled()` is true — it is NOT also stamped as a
+ * baseline alongside this propagator. Measured live
+ * (`scratchpad/probe_duplicate_header.mjs`, against the REAL
+ * `@opentelemetry/instrumentation-undici` used here): `request.addHeader(k,
+ * v)` — what that instrumentation calls for every header
+ * `propagation.inject()` returns — APPENDS a second raw header line rather
+ * than replacing one already present (undici's own `Request.addHeader` has
+ * no dedupe-by-name step); the receiving `http.IncomingMessage.headers`
+ * then comma-joins the two into one corrupted value
+ * (`"FROM_STATIC, FROM_PROPAGATOR"`), and `req.rawHeaders` shows the literal
+ * duplicate line. So when propagation is installed, THIS propagator is the
+ * sole source of `x-correlation-id`/`x-spf-agent` — never doubled up with a
+ * static value from `Model.headers` — proven on the wire by
+ * `src/test/ollama_gateway_e2e.test.ts`'s "no duplicate headers" test.
+ *
  * REGISTRATION TIMING. `installFluePropagation()` is called from
  * `agent_flue.ts`'s `run()`, before `ensureRuntime()`/dispatch — i.e. before
  * the actual outbound call, which is the only ordering that matters for
@@ -108,56 +193,124 @@ import { BasicTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trac
 import { createOpenTelemetryInstrumentation } from "@flue/opentelemetry";
 import { instrument } from "@flue/runtime";
 import { resolveTracesUrl } from "./otel.js";
-/** The one custom propagation field this repo adds beyond the standard W3C `traceparent`: the current span's own id, for a collector/log pipeline that correlates by request rather than by trace. */
-export const X_REQUEST_ID_HEADER = "x-request-id";
 /**
- * Injects `x-request-id` from whatever span is active at the point of the
- * outbound call — the same id that would appear as that span's `spanId` on
- * the (separate — see the module header) Flue-side trace. One-directional:
- * `extract()` is a pass-through, since nothing on the INBOUND side of an
- * outbound provider call needs to read this back.
+ * The Briefs gateway's own correlation headers — see `ollama_provider.ts`'s
+ * "Gateway headers" section for the full three-header contract (the third,
+ * `traceparent`, is the W3C standard one `W3CTraceContextPropagator` already
+ * injects). Defined here (not in `ollama_provider.ts`) because
+ * `GatewayHeadersPropagator` below is the thing that actually injects them
+ * onto the wire when this pipeline is installed; `ollama_provider.ts`
+ * imports these two constants rather than redeclaring them, so there is
+ * exactly one spelling of each header name in the codebase.
+ */
+export const X_CORRELATION_ID_HEADER = "x-correlation-id";
+export const X_SPF_AGENT_HEADER = "x-spf-agent";
+/**
+ * Instance-id -> registration backing `resolveFlueRootContext` — see the
+ * module header for the full mechanism and WHY this is a map consulted per
+ * span rather than a dispatch-time context wrap (flue's single claim loop
+ * makes the latter mis-attribute every agent after the first). One entry per
+ * in-flight `agent_flue.run()` call.
+ */
+const flueSessionTraces = new Map();
+/**
+ * Trace id -> gateway identity, keyed on the deterministic trace id parsed
+ * out of a registration's OWN `traceparent` (see `traceIdFromTraceparent`) —
+ * see the module header's BLOCKER 1 section for why this, and not a context
+ * VALUE, is the lookup `GatewayHeadersPropagator` uses. Populated by
+ * `registerFlueSessionTrace`, pruned by `unregisterFlueSessionTrace`. A
+ * trace id collision here (two DIFFERENT registrations sharing one trace id)
+ * is not expected in practice — trace ids are SPF's deterministic per-adw_id
+ * ids — but if it ever happened, the later `registerFlueSessionTrace` call
+ * would simply win, matching this map's own "current call wins" rule.
  */
-export class XRequestIdPropagator {
+const traceIdRegistrations = new Map();
+/**
+ * Parses the W3C `traceId` segment out of a `traceparent` string via a real
+ * `propagation.extract`/`getSpanContext` round trip — the SAME extraction
+ * `resolveFlueRootContext` performs, so "the trace id we index
+ * `traceIdRegistrations` under" and "the trace id a span parented via this
+ * `traceparent` actually carries" are provably the same value, not two
+ * independent parses that could drift. Returns `undefined` for a malformed
+ * `traceparent` (mirrors `resolveFlueRootContext`'s own malformed-input
+ * handling) rather than throwing.
+ */
+function traceIdFromTraceparent(traceparent) {
+    const extracted = propagation.extract(ROOT_CONTEXT, { traceparent }, defaultTextMapGetter);
+    const spanContext = traceApi.getSpanContext(extracted);
+    return spanContext && isSpanContextValid(spanContext) ? spanContext.traceId : undefined;
+}
+/**
+ * Registers `registration` (SPF's deterministic agent-call traceparent, plus
+ * this session's adw_id/agent name — see `FlueSessionRegistration`) as the
+ * trace root for flue spans belonging to `sessionId` — flue's instance id,
+ * minted by SPF and handed to `init(SfAgent, { id })`. Overwrites a prior
+ * registration for the same id (a same-phase retry is the same logical call;
+ * the current call wins). Also indexes the SAME identity under this
+ * registration's parsed trace id (`traceIdRegistrations`) — see the module
+ * header's BLOCKER 1 section and that map's own doc for why.
+ */
+export function registerFlueSessionTrace(sessionId, registration) {
+    flueSessionTraces.set(sessionId, registration);
+    const identity = { adwId: registration.adwId, agentName: registration.agentName };
+    const traceId = traceIdFromTraceparent(registration.traceparent);
+    if (traceId)
+        traceIdRegistrations.set(traceId, identity);
+}
+/**
+ * Injects `x-correlation-id`/`x-spf-agent` by looking up the ACTIVE
+ * `Context`'s SpanContext trace id (`trace.getSpanContext(ctx)?.traceId`) in
+ * `traceIdRegistrations` — the same per-real-HTTP-call injection point
+ * `W3CTraceContextPropagator` uses for `traceparent`, and, critically, keyed
+ * on the one piece of `resolveFlueRootContext`'s return value that provably
+ * survives into that active context (see the module header's BLOCKER 1
+ * section for why a context VALUE does not). Injects NOTHING — no fallback,
+ * no last-known identity — when this exact trace id is not in the map: an
+ * unregistered/unmapped span (flue's own bookkeeping spans, or ANY span
+ * after every session has been unregistered) must not stamp a stale or
+ * unrelated session's `x-correlation-id`/`x-spf-agent` onto unrelated
+ * outbound traffic (a third-party call, a post-session straggler). A true
+ * no-op (nothing set) in that case — never throws, never invents a value.
+ * Replaces the old `XRequestIdPropagator`:
+ * `x-request-id` must NEVER reach the gateway (Envoy/Switchyard own it
+ * end-to-end; a client-sent value corrupts their own sampling) and this repo
+ * no longer has anything that wants it emitted.
+ */
+export class GatewayHeadersPropagator {
     inject(ctx, carrier, setter) {
         const spanContext = traceApi.getSpanContext(ctx);
-        if (!spanContext || !isSpanContextValid(spanContext))
+        const registration = spanContext && traceIdRegistrations.get(spanContext.traceId);
+        if (!registration)
             return;
-        setter.set(carrier, X_REQUEST_ID_HEADER, spanContext.spanId);
+        if (registration.adwId)
+            setter.set(carrier, X_CORRELATION_ID_HEADER, registration.adwId);
+        if (registration.agentName)
+            setter.set(carrier, X_SPF_AGENT_HEADER, registration.agentName);
     }
     extract(ctx) {
         return ctx;
     }
     fields() {
-        return [X_REQUEST_ID_HEADER];
+        return [X_CORRELATION_ID_HEADER, X_SPF_AGENT_HEADER];
     }
 }
-/**
- * Instance-id -> agent-call traceparent registrations backing
- * `resolveFlueRootContext` — see the module header for the full mechanism
- * and WHY this is a map consulted per span rather than a dispatch-time
- * context wrap (flue's single claim loop makes the latter mis-attribute
- * every agent after the first). One entry per in-flight `agent_flue.run()`
- * call.
- */
-const flueSessionTraces = new Map();
-/**
- * Registers `traceparent` (SPF's deterministic agent-call span, as a W3C
- * carrier string) as the trace root for flue spans belonging to `sessionId`
- * — flue's instance id, minted by SPF and handed to `init(SfAgent, { id })`.
- * Overwrites a prior registration for the same id (a same-phase retry is
- * the same logical call; the current call wins).
- */
-export function registerFlueSessionTrace(sessionId, traceparent) {
-    flueSessionTraces.set(sessionId, traceparent);
-}
 /**
  * Idempotent — called from `run()`'s `finally`. Post-settlement bookkeeping
  * spans flue mints after this point simply resolve to an unparented root
  * (separate trace), which is preferable to leaking a registration whose id
- * a REUSED session id could collide with on a later phase.
+ * a REUSED session id could collide with on a later phase. Also prunes this
+ * session's entry out of `traceIdRegistrations` (parsed fresh from the
+ * departing registration's own `traceparent`, so it removes exactly the
+ * entry this session added.
  */
 export function unregisterFlueSessionTrace(sessionId) {
+    const registration = flueSessionTraces.get(sessionId);
     flueSessionTraces.delete(sessionId);
+    if (!registration)
+        return;
+    const traceId = traceIdFromTraceparent(registration.traceparent);
+    if (traceId)
+        traceIdRegistrations.delete(traceId);
 }
 /**
  * The `resolveRootContext` implementation handed to
@@ -169,14 +322,23 @@ export function unregisterFlueSessionTrace(sessionId) {
  * unparented root span of its own) for an unmapped session id, a malformed
  * traceparent, an absent ctx — and, with no global propagator installed,
  * for everything. Exported for tests.
+ *
+ * Used by `@flue/opentelemetry` ONLY as `tracer.startSpan`'s parent
+ * argument (see the module header's BLOCKER 1 section) — the value handed
+ * back here is never itself activated, so it carries no context VALUES for
+ * `GatewayHeadersPropagator` to read; `x-correlation-id`/`x-spf-agent` are
+ * instead looked up by trace id, via `traceIdRegistrations`, which
+ * `registerFlueSessionTrace` populates independently of this function.
  */
 export function resolveFlueRootContext(_event, ctx) {
-    const traceparent = ctx?.id ? flueSessionTraces.get(ctx.id) : undefined;
-    if (!traceparent)
+    const registration = ctx?.id ? flueSessionTraces.get(ctx.id) : undefined;
+    if (!registration)
         return undefined;
-    const extracted = propagation.extract(ROOT_CONTEXT, { traceparent }, defaultTextMapGetter);
+    const extracted = propagation.extract(ROOT_CONTEXT, { traceparent: registration.traceparent }, defaultTextMapGetter);
     const spanContext = traceApi.getSpanContext(extracted);
-    return spanContext && isSpanContextValid(spanContext) ? extracted : undefined;
+    if (!spanContext || !isSpanContextValid(spanContext))
+        return undefined;
+    return extracted;
 }
 let installed = false;
 let flueInstrumented = false;
@@ -200,7 +362,7 @@ export function installFluePropagation(cfg, log = (m) => console.error(m)) {
             });
             traceApi.setGlobalTracerProvider(provider);
             contextApi.setGlobalContextManager(new AsyncHooksContextManager().enable());
-            propagation.setGlobalPropagator(new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new XRequestIdPropagator()] }));
+            propagation.setGlobalPropagator(new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new GatewayHeadersPropagator()] }));
             registerInstrumentations({ instrumentations: [new HttpInstrumentation(), new UndiciInstrumentation()] });
             // Set AFTER the fallible registrations above: on a construction-time
             // throw, the next call must be free to retry — latching `installed`
@@ -223,3 +385,17 @@ export function resetFluePropagationForTest() {
     installed = false;
     flueInstrumented = false;
 }
+/**
+ * Whether `installFluePropagation` has actually installed the global
+ * TracerProvider/propagator/instrumentations in THIS process. Consulted by
+ * `ollama_provider.ts` (see its "Gateway headers" section) so `resolve()`/
+ * `modelFor()` know whether the instrumentation above already covers
+ * `traceparent`/`x-correlation-id`/`x-spf-agent` per real outbound call —
+ * supplying any of the three a second way when this is `true` would double
+ * it up on the wire (`UndiciInstrumentation` appends via `addHeader`, it
+ * does not replace). `false` — the common case, otel unconfigured — means
+ * `ollama_provider.ts` must supply all three itself.
+ */
+export function isFluePropagationInstalled() {
+    return installed;
+}

package/dist/core/permissions.d.ts

@@ -73,6 +73,21 @@ export declare function permitted(p: string, agent: AgentConfig, cfg: SFConfig):
  * 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 declare function enforce(run: RunLike, _phase: unknown, agent: AgentConfig, before: Record<string, string>): string[];
+export declare function enforce(run: RunLike, _phase: unknown, agent: AgentConfig, before: Record<string, string>, onIgnored?: (paths: string[]) => void): string[];
 export {};

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.