@kontourai/flow-agents 2.0.0 → 2.1.0

package/.github/actions/trust-verify/action.yml

@@ -113,7 +113,9 @@ runs:
           BUNDLE_ARG=""
         fi
 
-        node "${{ github.action_path }}/../../scripts/ci/trust-reconcile.js" \
+        # action_path is .github/actions/trust-verify/ — climb THREE levels to the
+        # repo root where scripts/ lives (trust-verify -> actions -> .github -> root).
+        node "${{ github.action_path }}/../../../scripts/ci/trust-reconcile.js" \
           --commands "$VERIFY_COMMAND" \
           --repo-root "${{ github.workspace }}" \
           $BUNDLE_ARG || {
@@ -130,7 +132,7 @@ runs:
     - name: Mint attestation
       if: inputs.sign == 'true' && steps.trust-verify.outcome == 'success'
       shell: bash
-      run: node "${{ github.action_path }}/../../scripts/ci/mint-attestation.js"
+      run: node "${{ github.action_path }}/../../../scripts/ci/mint-attestation.js"
 
     - name: Upload attestation
       if: inputs.sign == 'true' && steps.trust-verify.outcome == 'success'

package/.github/workflows/ci.yml

@@ -14,6 +14,14 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Suite-wide secret-scan gate, defined once in kontourai/.github (Hachure: one
+  # normative source). Scans git-tracked history; gitignored runtime/.env excluded.
+  secret-scan:
+    name: Secret Scan
+    uses: kontourai/.github/.github/workflows/secret-scan.yml@main
+    permissions:
+      contents: read
+
   source-and-static:
     name: Source and Static
     runs-on: ubuntu-latest
@@ -242,6 +250,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check telemetry-doctor-integration
 
+      - name: Usage and cost integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-and-cost-integration
+
       - name: Utterance check integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check utterance-check-integration

package/.github/workflows/runtime-compat.yml

@@ -75,7 +75,7 @@ jobs:
           node-version: 24
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.12"
 

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [2.1.0](https://github.com/kontourai/flow-agents/compare/v2.0.1...v2.1.0) (2026-06-29)
+
+
+### Features
+
+* **telemetry:** derive live pricing source from the console ([#242](https://github.com/kontourai/flow-agents/issues/242)) ([ddce44e](https://github.com/kontourai/flow-agents/commit/ddce44e813e9a3515953324f4878bf51c33252ba))
+* **telemetry:** real token+cost capture with single-source versioned pricing ([#241](https://github.com/kontourai/flow-agents/issues/241)) ([b0bd4c3](https://github.com/kontourai/flow-agents/commit/b0bd4c347897ec77f60d84cae702e7f42b2871d7))
+
+
+### Fixes
+
+* **evidence-capture:** serialize command-log appends to prevent chain forks ([#232](https://github.com/kontourai/flow-agents/issues/232)) ([bb167e9](https://github.com/kontourai/flow-agents/commit/bb167e93e7f6cc19baa88da613e96fe88a681c10))
+* **flow-agents:** stop corrupting sidecar JSONL event lines ([#244](https://github.com/kontourai/flow-agents/issues/244)) ([fb65d10](https://github.com/kontourai/flow-agents/commit/fb65d1017e5cb659ce2b48da7a548f0c1f360426))
+* **trust-verify action:** correct cross-repo script path (../../ → ../../../) ([#240](https://github.com/kontourai/flow-agents/issues/240)) ([a75a6d2](https://github.com/kontourai/flow-agents/commit/a75a6d28baf68b4be527a2e8cdff8f007af88bd5))
+
+
+### Documentation
+
+* **design:** preserve WorkflowRun observability + FlowRun event-sourcing design notes ([#239](https://github.com/kontourai/flow-agents/issues/239)) ([c2dc116](https://github.com/kontourai/flow-agents/commit/c2dc11698cf63704f14087001c4494079195d197))
+* **flow-agents:** advertise the real eval coverage, clearly scoped (ops[#23](https://github.com/kontourai/flow-agents/issues/23)) ([#248](https://github.com/kontourai/flow-agents/issues/248)) ([d208207](https://github.com/kontourai/flow-agents/commit/d20820749408d5fa63f2bf1470252000712de5d8))
+
+## [2.0.1](https://github.com/kontourai/flow-agents/compare/v2.0.0...v2.0.1) (2026-06-27)
+
+
+### Fixes
+
+* carry KIT IDENTITY through the trust chain — stop flattening non-builder kits to "builder" ([#235](https://github.com/kontourai/flow-agents/issues/235)) ([02d2782](https://github.com/kontourai/flow-agents/commit/02d2782ca8d9158a018d0fc6c35adc6a34c827d5))
+* **gate:** classify concurrent-fork vs tamper; never hard-block a benign race ([#233](https://github.com/kontourai/flow-agents/issues/233)) ([e24743b](https://github.com/kontourai/flow-agents/commit/e24743b7dbff05df64e198e420e47841ce534df3))
+
 ## [2.0.0](https://github.com/kontourai/flow-agents/compare/v1.4.0...v2.0.0) (2026-06-27)
 
 

package/README.md

@@ -29,7 +29,7 @@ Flow Agents addresses this with a process-discipline layer that sits between the
 - **Four canonical policies** — workflow steering (phase reminders at each turn), quality gate (per-file checks after edits), stop-goal-fit (evidence check before the agent stops), and config protection (veto writes to linter/formatter configs). Each policy class has a canonical script under `scripts/hooks/` and compiles to the host's native hook format.
 - **Evidence over confidence** — important work ends with tests, browser checks, CI results, review findings, governance reports, or an explicit `NOT_VERIFIED` gap. Optional [Veritas](docs/veritas-integration.md) integration attaches repo-governance evidence without making it mandatory.
 - **Verifiable, un-gameable "done"** — the agent can't mark work complete that isn't: the gate re-derives the verdict from independent evidence, an external CI anchor re-runs the verification fresh and fails the merge on any divergence, and CI mints a Sigstore-signed record of what shipped. See [Verifiable Trust — why "done" actually means done](docs/verifiable-trust.md).
-- **Evals that keep the bundle honest** — 77 integration and 36 static bundle assertions validate the skills, contracts, fixtures, and hook influence as the bundle evolves.
+- **Evals that keep the bundle honest** — 60 integration scenarios (1,829 assertions) and 7 static suites (110 assertions) validate the skills, contracts, fixtures, and hook influence as the bundle evolves.
 
 ## Flow Agents as a process-discipline layer
 
@@ -52,8 +52,8 @@ L2 means all four policy classes with blocking; L1 means steering and stop-goal-
 
 | Runtime | Ships | Tested |
 | --- | --- | --- |
-| Claude Code | install + hooks + bundle | 77 integration + 36 static assertions — reference implementation |
-| Codex | install + hooks + bundle | 77 integration + 36 static assertions — reference implementation |
+| Claude Code | install + hooks + bundle | 60 integration scenarios + 7 static suites (1,939 assertions) — reference implementation |
+| Codex | install + hooks + bundle | 60 integration scenarios + 7 static suites (1,939 assertions) — reference implementation |
 | Kiro | install + hooks + bundle | included in bundle assertions |
 
 **Partial support — L1 (steering + stop-goal-fit warning)**

package/build/src/cli/workflow-sidecar.d.ts

@@ -167,6 +167,22 @@ export declare function sidecarBase(slug: string): AnyObj;
 export declare function validateEvidenceRef(ref: AnyObj, label: string): AnyObj;
 export declare function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[];
 export declare function normalizeCheck(raw: AnyObj): AnyObj;
+/**
+ * Derive kit identity from a parsed trust.bundle by structurally reading the
+ * DECLARED primary claim (kit-typed) rather than hardcoding "builder".
+ *
+ * Resolution order (no fallbacks to "builder"):
+ *   1. First non-workflow.* claim in bundle.claims[] → claimType drives kitId + subject.
+ *   2. No kit-typed claim: try current.json active_flow_id adjacent to the bundle file
+ *      (bundle lives at <session-dir>/trust.bundle → flowAgentsDir = grandparent).
+ *   3. Genuinely unknown: mark as "unknown" — never hardcode a kit identity.
+ */
+export declare function kitIdentityFromBundle(raw: AnyObj, bundleFile: string): {
+    claimType: string;
+    kitId: string;
+    subject: string;
+    gateId: string;
+};
 export declare function writeState(dir: string, slug: string, status: string, phase: string, timestamp: string, summary: string, next?: string): void;
 export declare function normalizeFinding(raw: AnyObj): AnyObj;
 /**

package/build/src/cli/workflow-sidecar.js

@@ -6,7 +6,7 @@ import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 // ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
-import { resolveActiveFlowStep, resolveFlowFilePath, resolvePhaseMap } from "../lib/flow-resolver.js";
+import { resolveActiveFlowStep, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy } from "../lib/flow-resolver.js";
 export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
 export const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
 export const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
@@ -15,11 +15,17 @@ export const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
 function now() { return new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); }
 function read(file) { return fs.readFileSync(file, "utf8"); }
 export function writeJson(file, payload) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
-function printJson(payload) { console.log(JSON.stringify(payload).replace(/":/g, '": ').replace(/,"/g, ', "')); }
+// Single-line but readable "key": "value" form. Built by collapsing the
+// structural whitespace from an indented stringify — corruption-proof, unlike a
+// regex that would also rewrite ":"/"," sequences inside string values.
+function spacedLine(payload, replacer) {
+    return JSON.stringify(payload, replacer, 1).replace(/\n\s*/g, " ");
+}
+function printJson(payload) { console.log(spacedLine(payload)); }
 export function loadJson(file, fallback = {}) { return fs.existsSync(file) ? JSON.parse(read(file)) : { ...fallback }; }
 export function appendJsonl(file, payload) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    const line = JSON.stringify(payload, Object.keys(payload).sort()).replace(/":/g, '": ').replace(/,"/g, ', "');
+    const line = spacedLine(payload, Object.keys(payload).sort());
     fs.appendFileSync(file, `${line}\n`);
 }
 function die(message) { throw new Error(message); }
@@ -1071,15 +1077,63 @@ function deriveSurfaceStatus(ref) {
         return "fail";
     return "pass";
 }
+/**
+ * Derive kit identity from a parsed trust.bundle by structurally reading the
+ * DECLARED primary claim (kit-typed) rather than hardcoding "builder".
+ *
+ * Resolution order (no fallbacks to "builder"):
+ *   1. First non-workflow.* claim in bundle.claims[] → claimType drives kitId + subject.
+ *   2. No kit-typed claim: try current.json active_flow_id adjacent to the bundle file
+ *      (bundle lives at <session-dir>/trust.bundle → flowAgentsDir = grandparent).
+ *   3. Genuinely unknown: mark as "unknown" — never hardcode a kit identity.
+ */
+export function kitIdentityFromBundle(raw, bundleFile) {
+    // 1. Structurally read the bundle's declared kit-typed claim.
+    const claims = Array.isArray(raw.claims) ? raw.claims : [];
+    for (const claim of claims) {
+        const ct = typeof claim?.claimType === "string" ? claim.claimType : "";
+        if (ct && !ct.startsWith("workflow.")) {
+            const kitId = ct.split(".")[0] ?? "unknown";
+            if (kitId && kitId !== "unknown") {
+                return { claimType: ct, kitId, subject: `${kitId}-kit`, gateId: ct };
+            }
+        }
+    }
+    // 2. No kit-typed claim in bundle — try to derive kit from current.json active_flow_id.
+    //    The bundle lives at <session-dir>/trust.bundle, so:
+    //      sessionDir = path.dirname(bundleFile)
+    //      flowAgentsDir = path.dirname(sessionDir)
+    try {
+        const sessionDir = path.dirname(bundleFile);
+        const flowAgentsDir = path.dirname(sessionDir);
+        const currentFile = path.join(flowAgentsDir, "current.json");
+        const current = JSON.parse(fs.readFileSync(currentFile, "utf8"));
+        const flowId = typeof current["active_flow_id"] === "string" ? current["active_flow_id"] : null;
+        if (flowId && flowId.includes(".")) {
+            const kitId = flowId.split(".")[0];
+            if (kitId) {
+                const derivedClaimType = `${kitId}.trust.bundle`;
+                return { claimType: derivedClaimType, kitId, subject: `${kitId}-kit`, gateId: derivedClaimType };
+            }
+        }
+    }
+    catch {
+        // Ignore — fall through to unknown
+    }
+    // 3. Genuinely unknown — never fallback to "builder".
+    return { claimType: "unknown.trust.bundle", kitId: "unknown", subject: "unknown-kit", gateId: "unknown.trust.bundle" };
+}
 function surfaceCheckFromArtifact(file, index) {
     const raw = JSON.parse(read(file));
     const lower = JSON.stringify(raw).toLowerCase();
+    // Structurally read kit identity from the bundle — never hardcode "builder".
+    const { claimType: bundleClaimType, subject: bundleSubject, gateId: bundleGateId } = kitIdentityFromBundle(raw, file);
     let ref;
     if (lower.includes("provider") && lower.includes("absent")) {
-        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "provider.unavailable", claim_type: "builder.trust.bundle", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
+        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "provider.unavailable", claim_type: bundleClaimType, claim_status: "unknown", subject: bundleSubject, freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
     }
     else if (lower.includes("artifact") && lower.includes("absent")) {
-        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: "builder.trust.bundle", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
+        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: bundleClaimType, claim_status: "unknown", subject: bundleSubject, freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
     }
     else {
         const claimStatus = lower.includes("rejected") ? "rejected" : "accepted";
@@ -1087,7 +1141,7 @@ function surfaceCheckFromArtifact(file, index) {
         const producer = lower.includes("missing-authority") ? "unknown" : "surface-local";
         const integrity = lower.includes("mismatch") ? "mismatch" : "matched";
         // Use trust.bundle as the canonical Hachure-aligned artifact_kind for all trust-backed evidence refs
-        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "builder.trust.bundle", claim_type: "builder.trust.bundle", claim_status: claimStatus, subject: "builder-kit", freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
+        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: bundleGateId, claim_type: bundleClaimType, claim_status: claimStatus, subject: bundleSubject, freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
         ref.status = deriveSurfaceStatus(ref);
         ref.summary = ref.status === "pass" ? "accepted" : ref.status === "not_verified" ? "not currently verifiable" : (claimStatus === "rejected" ? "rejected" : producer === "unknown" ? "missing authority" : "integrity mismatch");
     }
@@ -1342,16 +1396,22 @@ async function advanceState(p) {
     if ((status === "archived" || status === "accepted") && prev.phase !== "learning")
         diagnostic(dir, "terminal_jump_rejected", "Terminal workflow states require release and learning gates.");
     const flow = opt(p, "flow-definition");
-    if (flow === "builder.build" && prev.phase === "verification" && phase === "execution") {
+    // Route-back guard: FlowDefinition-driven (not hardcoded to builder.build).
+    // Fires when the active flow's gate for prev.phase declares a route_back_policy
+    // AND the target phase maps to a step listed in on_route_back values.
+    // builder.build verify-gate already carries this declaration — behavior preserved.
+    const repoRoot = flow ? findRepoRootFromDir(dir) : "";
+    const routeBack = flow ? resolveRouteBackPolicy(flow, prev.phase, phase, repoRoot) : null;
+    if (routeBack) {
         const reason = opt(p, "route-back-reason");
         if (!reason)
-            diagnostic(dir, "route_back_reason_required", "Builder Kit route-back requires implementation_defect or equivalent reason.");
+            diagnostic(dir, "route_back_reason_required", `Route-back from ${prev.phase} to ${phase} requires a --route-back-reason (e.g. implementation_defect).`);
         const file = path.join(dir, "transition-attempts.json");
         const attempts = loadJson(file);
-        const key = `verification->execution:${reason}`;
+        const key = `${prev.phase}->${phase}:${reason}`;
         const count = attempts[key]?.count ?? 0;
-        if (count >= 3)
-            diagnostic(dir, "route_back_attempts_exceeded", "Builder Kit route-back attempts exceeded.");
+        if (count >= routeBack.maxAttempts)
+            diagnostic(dir, "route_back_attempts_exceeded", `Route-back attempt limit (${routeBack.maxAttempts}) exceeded for ${prev.phase}→${phase}.`);
         attempts[key] = { count: count + 1, reason, updated_at: opt(p, "timestamp", now()) };
         writeJson(file, attempts);
     }
@@ -1365,7 +1425,7 @@ async function advanceState(p) {
     // --step-id individually. The repoRoot is derived by walking up from dir to find kits/.
     if (flow) {
         const root = path.resolve(opt(p, "artifact-root", path.dirname(dir)));
-        const repoRoot = findRepoRootFromDir(dir);
+        // repoRoot already computed above when flow is present
         const phaseMap = resolvePhaseMap(flow, repoRoot);
         const stepId = phaseMap?.[phase] ?? undefined;
         if (stepId) {

package/build/src/lib/flow-resolver.d.ts

@@ -80,3 +80,32 @@ export declare function resolvePhaseMap(flowId: string, repoRoot: string): Recor
  * @returns ActiveFlowStep or null when fields are absent or resolution fails.
  */
 export declare function resolveActiveFlowStep(flowAgentsDir: string): ActiveFlowStep | null;
+/** The resolved route-back policy for a phase transition. */
+export type RouteBackPolicy = {
+    /** Maximum allowed route-back attempts for this transition key. */
+    maxAttempts: number;
+    /** Action when attempts are exceeded (e.g. "block"). */
+    onExceeded: string;
+    /** The step id whose gate declared this policy (e.g. "verify"). */
+    fromStepId: string;
+};
+/**
+ * Resolve the route-back policy for a phase transition, if the active FlowDefinition
+ * declares one on the source phase's gate.
+ *
+ * A route-back is a transition where the source phase's gate declares both
+ * `route_back_policy` and `on_route_back`, and the target phase maps to a step
+ * listed as a route-back target in `on_route_back` values.
+ *
+ * This is the FlowDefinition-driven replacement for the hardcoded
+ * `flow === "builder.build" && prev.phase === "verification" && phase === "execution"`
+ * guard in advance-state. Any flow that declares `route_back_policy` on a gate
+ * automatically gets route-back enforcement without code changes.
+ *
+ * @param flowId    e.g. "builder.build" — kitId is the prefix before the first ".".
+ * @param fromPhase Lifecycle phase leaving (e.g. "verification").
+ * @param toPhase   Lifecycle phase entering (e.g. "execution").
+ * @param repoRoot  Absolute path to the repository root (kits/ lives here).
+ * @returns RouteBackPolicy when the transition is a declared route-back, null otherwise.
+ */
+export declare function resolveRouteBackPolicy(flowId: string, fromPhase: string, toPhase: string, repoRoot: string): RouteBackPolicy | null;

package/build/src/lib/flow-resolver.js

@@ -235,3 +235,74 @@ export function resolveActiveFlowStep(flowAgentsDir) {
     const repoRoot = findRepoRoot(path.dirname(flowAgentsDir));
     return resolveFlowStep(flowId, stepId, repoRoot);
 }
+/**
+ * Resolve the route-back policy for a phase transition, if the active FlowDefinition
+ * declares one on the source phase's gate.
+ *
+ * A route-back is a transition where the source phase's gate declares both
+ * `route_back_policy` and `on_route_back`, and the target phase maps to a step
+ * listed as a route-back target in `on_route_back` values.
+ *
+ * This is the FlowDefinition-driven replacement for the hardcoded
+ * `flow === "builder.build" && prev.phase === "verification" && phase === "execution"`
+ * guard in advance-state. Any flow that declares `route_back_policy` on a gate
+ * automatically gets route-back enforcement without code changes.
+ *
+ * @param flowId    e.g. "builder.build" — kitId is the prefix before the first ".".
+ * @param fromPhase Lifecycle phase leaving (e.g. "verification").
+ * @param toPhase   Lifecycle phase entering (e.g. "execution").
+ * @param repoRoot  Absolute path to the repository root (kits/ lives here).
+ * @returns RouteBackPolicy when the transition is a declared route-back, null otherwise.
+ */
+export function resolveRouteBackPolicy(flowId, fromPhase, toPhase, repoRoot) {
+    if (!flowId || !fromPhase || !toPhase)
+        return null;
+    const dotIdx = flowId.indexOf(".");
+    if (dotIdx < 1)
+        return null;
+    const kitId = flowId.slice(0, dotIdx);
+    const flowName = flowId.slice(dotIdx + 1);
+    if (!kitId || !flowName)
+        return null;
+    const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
+    if (!flowFilePath)
+        return null;
+    let flowDef;
+    try {
+        const raw = fs.readFileSync(flowFilePath, "utf8");
+        flowDef = JSON.parse(raw);
+    }
+    catch {
+        return null; // ENOENT, permission error, or parse error — fail-open
+    }
+    if (!flowDef || typeof flowDef !== "object")
+        return null;
+    const phaseMap = flowDef.phase_map;
+    if (!phaseMap || typeof phaseMap !== "object" || Array.isArray(phaseMap))
+        return null;
+    const fromStep = phaseMap[fromPhase];
+    const toStep = phaseMap[toPhase];
+    if (!fromStep || !toStep)
+        return null; // phases not in this flow
+    if (!flowDef.gates)
+        return null;
+    for (const gate of Object.values(flowDef.gates)) {
+        if (!gate || gate.step !== fromStep)
+            continue;
+        if (!gate.route_back_policy || !gate.on_route_back)
+            return null;
+        // Check if toStep is a valid route-back target declared in on_route_back
+        const routeBackTargets = Object.values(gate.on_route_back);
+        if (!routeBackTargets.includes(toStep))
+            return null;
+        const maxAttempts = typeof gate.route_back_policy.max_attempts === "number"
+            ? gate.route_back_policy.max_attempts
+            : 3;
+        return {
+            maxAttempts,
+            onExceeded: gate.route_back_policy.on_exceeded ?? "block",
+            fromStepId: fromStep,
+        };
+    }
+    return null;
+}

package/context/scripts/telemetry/lib/config.sh

@@ -38,6 +38,11 @@ CONSOLE_TELEMETRY_URL="${CONSOLE_TELEMETRY_URL:-${CONSOLE_URL:-}}"
 CONSOLE_TELEMETRY_ENDPOINT_URL="${CONSOLE_TELEMETRY_ENDPOINT_URL:-}"
 CONSOLE_TELEMETRY_TOKEN="${CONSOLE_TELEMETRY_TOKEN:-${CONSOLE_AUTH_TOKEN:-}}"
 CONSOLE_TENANT_ID="${CONSOLE_TENANT_ID:-}"
+# Pricing registry source (consumed by lib/pricing.sh). Explicit file/URL win;
+# otherwise the URL is derived from the console below so all runtimes read one
+# live pricing source. Falls back to the bundled pricing.json offline.
+TELEMETRY_PRICING_FILE="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
+TELEMETRY_PRICING_URL="${TELEMETRY_PRICING_URL:-${FLOW_AGENTS_PRICING_URL:-}}"
 
 # Load config file if it exists
 if [[ -f "$TELEMETRY_CONFIG_FILE" ]]; then
@@ -78,6 +83,9 @@ if [[ -f "$TELEMETRY_CONFIG_FILE" ]]; then
         console_telemetry_token) CONSOLE_TELEMETRY_TOKEN="$value" ;;
         console_tenant_id) CONSOLE_TENANT_ID="$value" ;;
         console_telemetry_redact) CONSOLE_TELEMETRY_REDACT="$value" ;;
+        console_pricing_url) TELEMETRY_PRICING_URL="$value" ;;
+        pricing_url) TELEMETRY_PRICING_URL="$value" ;;
+        pricing_file) TELEMETRY_PRICING_FILE="$value" ;;
       esac
     fi
   done < "$TELEMETRY_CONFIG_FILE"
@@ -85,5 +93,12 @@ fi
 
 CONSOLE_TELEMETRY_REDACT="${CONSOLE_TELEMETRY_REDACT:-${TELEMETRY_CHANNEL_ANALYTICS_REDACT}}"
 
+# Derive the live pricing source from the console when not set explicitly, the
+# same way the transport derives /api/telemetry/records. One live source for
+# bash/Python/TS runtimes; lib/pricing.sh caches it and falls back to bundled.
+if [[ -z "${TELEMETRY_PRICING_URL:-}" && -n "${CONSOLE_TELEMETRY_URL:-}" ]]; then
+  TELEMETRY_PRICING_URL="${CONSOLE_TELEMETRY_URL%/}/api/telemetry/pricing"
+fi
+
 # Ensure directories exist
 mkdir -p "$TELEMETRY_DATA_DIR" "$TELEMETRY_SESSION_DIR" 2>/dev/null

package/context/scripts/telemetry/telemetry.conf

@@ -8,6 +8,10 @@ channel.analytics.redact=tool.input,tool.output,turn.prompt_text,delegation.targ
 # The transport derives /api/telemetry/records from console_telemetry_url.
 # console_telemetry_token=
 # console_tenant_id=
+# Live pricing registry source. If unset, derived from console_telemetry_url as
+# <console>/api/telemetry/pricing so bash/Python/TS runtimes read one live
+# source; lib/pricing.sh caches it and falls back to bundled pricing.json.
+# console_pricing_url=https://console.kontourai.io/api/telemetry/pricing
 enrich_system=true
 enrich_workspace=true
 enrich_auth=true

package/context/scripts/telemetry/telemetry.sh

@@ -309,13 +309,35 @@ add_stop_data_and_emit_usage() {
     tool_count=$(usage_count_tool_calls "$session_id" "$full_log")
     delegation_count=$(usage_count_delegations "$session_id" "$full_log")
 
+    # Ground-truth token + cost usage from the runtime transcript, when the
+    # runtime exposes one (Claude Code, Codex, etc. set hook.transcript_path).
+    # Tokens are source-of-truth; estimated_cost_usd is derived from pricing.json
+    # (recomputed authoritatively console-side, so pricing updates are retroactive).
+    local transcript_path transcript_usage
+    transcript_path=$(echo "$event" | jq -r '.hook.transcript_path // ""')
+    transcript_usage=$(usage_parse_transcript "$transcript_path")
+    [[ -z "$transcript_usage" ]] && transcript_usage='null'
+
     local usage_event
     usage_event=$(echo "$event" | jq -c \
       --arg m "$model" \
       --argjson tc "$tool_count" \
       --argjson dc "$delegation_count" \
+      --argjson tu "$transcript_usage" \
       '.event_type = "session.usage" | .event_id = (.event_id + "-usage") | . + {
-        usage: {model: $m, duration_s: .session.duration_s, tool_invocations: $tc, delegations: $dc, input_tokens: null, output_tokens: null, estimated_cost_usd: null}
+        usage: ({
+          model: $m,
+          duration_s: .session.duration_s,
+          tool_invocations: $tc,
+          delegations: $dc,
+          input_tokens: ($tu.input_tokens // null),
+          output_tokens: ($tu.output_tokens // null),
+          cache_creation_input_tokens: ($tu.cache_creation_input_tokens // null),
+          cache_read_input_tokens: ($tu.cache_read_input_tokens // null),
+          estimated_cost_usd: ($tu.estimated_cost_usd // null),
+          pricing_version: ($tu.pricing_version // null),
+          by_model: ($tu.by_model // null)
+        })
       }')
     transport_emit "$usage_event"
   fi