FN-8690: document Grok CLI provenance blocker

Document the unavailable Grok CLI source provenance and preserve the existing usage gate.

- Record provenance investigation results and the BLOCKED-NO-SOURCE hand-off
- Validate FN-8690 evidence sections and canonical verdicts
- Explain why the API-supplied percentage gate remains unchanged

Files changed:
 docs/solutions/integration-issues/grok-cli-usage-data-source.md | 64 ++++++++++++++++++++++
 packages/dashboard/src/__tests__/grok-usage-finding-doc.test.ts | 21 +++++++
 packages/dashboard/src/usage.ts                                  |  3 +
 3 files changed, 88 insertions(+)

Fusion-Task-Id: FN-8690

Fusion-Task-Lineage: 4521063d-2a9a-4710-9609-35b7582a2f2d

Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>

docs/solutions/integration-issues/grok-cli-usage-data-source.md

@@ -103,3 +103,67 @@ source archive. Once that chain is supplied, read the mapped handler and replay
 only its exact request through the redacted in-process harness. Until then,
 FN-8668 may implement nothing: there is no confirmed formatter operand or
 formula.
+
+## Source provenance (FN-8690)
+
+FN-8690 re-attempted the provenance recovery avenues FN-8689 did not exhaust.
+Filtered, non-executing `strings` inspection of the installed Mach-O found
+first-party debug/locus strings for
+`crates/codegen/xai-grok-shell/src/extensions/usage.rs` and
+`crates/codegen/xai-grok-shell/src/extensions/billing.rs`, including billing
+handler diagnostic loci at lines 230, 242, 262, 321, and 328. It also found
+compiled endpoint and response-identifier fragments. This is evidence that the
+installed binary contains those compiled strings, not a readable handler
+implementation: no extracted source region establishes the request construction,
+formatter operands, arithmetic, rounding, or clamping.
+
+The local bundled manifest was searched for the installed version, candidate
+build identifier, asset filename, source/commit mapping, and digest mapping. It
+contained bundled-content digests only. Filtered embedded URLs led to the
+official installer, which again maps the version to the asset download but does
+not map an asset digest to a source tag or commit; the embedded changelog route
+returned HTTP 404. No updater/release manifest mapping the installed digest to
+source was found.
+
+The source status is therefore `unavailable`: neither a published
+`version → asset filename → published digest → source tag/commit` chain nor
+readable `embedded-source` exists. The installed SHA-256 remains the FN-8689
+recorded value; it is not linked to inspectable source.
+
+## Source-identified handler, request, and arithmetic (FN-8690)
+
+Unavailable. Debug file paths and compiled string fragments are not readable
+source under the provenance policy, so FN-8690 did not read a `/usage` or
+`/cost` handler as the installed CLI's handler. It asserts no source-identified
+method, URL, query, headers, response fields, operand paths, display arithmetic,
+rounding, or clamping. Fusion's existing billing request remains historical
+context only and is not asserted to be the CLI request.
+
+## Redacted replay (FN-8690)
+
+Not performed. The local credential was present and parseable, but the harness
+is permitted to issue live traffic only after provenance-chained or readable
+embedded source identifies the exact request. No harness script or output was
+created, and no live request was issued.
+
+### Source-named operand classification
+
+| Source-named operand path | Classification |
+| --- | --- |
+| None — no source handler was readable, so no operand paths could be enumerated. | Not applicable |
+
+No absence claim is made about any response field or numeric leaf. In
+particular, this is not a `NO-FIELDS` conclusion.
+
+## FN-8668 hand-off (FN-8690)
+
+**Branch:** `BLOCKED-NO-SOURCE`.
+
+FN-8668 must not derive usage from this evidence. The narrow next action is for
+xAI to provide an official release checksum/updater manifest that maps
+`grok-0.2.118-macos-aarch64` and the already recorded installed digest to a
+source commit/archive, or a readable source bundle embedded in the installed
+artifact. A follow-up can then read the pinned handler, enumerate its operands,
+and run precisely its request through the redacted harness.
+
+VERDICT FN-8690: BLOCKED-NO-SOURCE — source could not be pinned. Blocker recorded; no source-identified request or formula asserted.

packages/dashboard/src/__tests__/grok-usage-finding-doc.test.ts

@@ -14,6 +14,13 @@ const canonicalVerdicts = [
   "VERDICT FN-8689: STATIC-BLOCKED — BLOCKED, source provenance unrecoverable. No provenance chain proven; no source-identified request and no live capture performed.",
 ] as const;
 
+const canonicalFn8690Verdicts = [
+  "VERDICT FN-8690: CONFIRMED — source pinned; /usage handler read; redacted capture returned allow-listed values for every source-consumed meter field; request and display arithmetic recorded.",
+  "VERDICT FN-8690: NO-FIELDS — source pinned and handler read; redacted capture proved every source-consumed operand field is absent from this account's response.",
+  "VERDICT FN-8690: BLOCKED-NO-SOURCE — source could not be pinned. Blocker recorded; no source-identified request or formula asserted.",
+  "VERDICT FN-8690: BLOCKED-NO-CAPTURE — source pinned and handler read; request and display arithmetic recorded from source, but the redacted capture could not confirm the source-consumed operands. Blocker recorded; no live-derived formula asserted.",
+] as const;
+
 describe("Grok CLI usage source finding", () => {
   const finding = readFileSync(findingPath, "utf8");
 
@@ -36,6 +43,20 @@ describe("Grok CLI usage source finding", () => {
     expect(canonicalVerdicts).toContain(verdictLines[0] as (typeof canonicalVerdicts)[number]);
   });
 
+  it("records one canonical FN-8690 verdict and the required evidence sections", () => {
+    const verdictLines = finding
+      .split("\n")
+      .filter((line) => line.startsWith("VERDICT FN-8690:"));
+
+    expect(verdictLines).toHaveLength(1);
+    expect(canonicalFn8690Verdicts).toContain(verdictLines[0] as (typeof canonicalFn8690Verdicts)[number]);
+    expect(finding).toContain("## Source provenance (FN-8690)");
+    expect(finding).toContain("## Source-identified handler, request, and arithmetic (FN-8690)");
+    expect(finding).toContain("## Redacted replay (FN-8690)");
+    expect(finding).toContain("### Source-named operand classification");
+    expect(finding).toContain("## FN-8668 hand-off (FN-8690)");
+  });
+
   it("does not commit credential-shaped material", () => {
     expect(finding).not.toMatch(/Bearer\s+/);
     expect(finding).not.toContain("eyJ");

packages/dashboard/src/usage.ts

@@ -1735,6 +1735,9 @@ async function fetchGrokCliBillingUsage(
     /*
     FNXC:UsageProviders 2026-07-31-20:31:
     A real account reported zero Grok credit usage while its billing response omitted `creditUsagePercent`, disproving the former omitted-field-to-100% inference. Emit a credits window only for a finite API-supplied percentage; field absence must remain an authenticated but unmeterable state rather than fabricate consumption or infer expired CLI auth.
+
+    FNXC:GrokUsageProvenance 2026-08-01-15:21:
+    FN-8690 could not map the installed Grok CLI asset to readable source, so its compiled strings cannot justify a replacement request or formula. Keep this existing API-supplied percentage gate until provenance and a redacted source-identified capture establish formatter inputs.
     */
     const pctUsed = config.creditUsagePercent;
     if (typeof pctUsed !== "number" || !Number.isFinite(pctUsed)) return { outcome: "no-data" };