sentinelayer-cli 0.9.6 → 0.9.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/auth/session-store.js

@@ -17,6 +17,8 @@ const SESSION_WARNING_ALLOWED_FIELDS = new Set([
   "codeHint",
   "requestIdHash",
 ]);
+const emittedSessionWarningKeys = new Set();
+let keytarClientOverrideForTests;
 
 function nowIso() {
   return new Date().toISOString();
@@ -69,26 +71,45 @@ function sanitizeSessionWarningDetails(details) {
 
 function emitSessionWarning(code, details = {}) {
   const sanitizedDetails = sanitizeSessionWarningDetails(details);
+  const normalizedCode = String(code || "SESSION_WARNING").toUpperCase();
+  const allowedDetails = {};
+  for (const [key, value] of Object.entries(sanitizedDetails)) {
+    allowedDetails[key] = SESSION_WARNING_ALLOWED_FIELDS.has(key) ? value : "[OMITTED]";
+  }
+  const warningKey = `${normalizedCode}:${JSON.stringify(allowedDetails)}`;
+  if (emittedSessionWarningKeys.has(warningKey)) {
+    return;
+  }
+  emittedSessionWarningKeys.add(warningKey);
+
   const payload = {
     level: "warn",
-    code: String(code || "SESSION_WARNING").toUpperCase(),
+    code: normalizedCode,
     warningId: createSessionWarningId(),
     timestamp: nowIso(),
   };
-  for (const [key, value] of Object.entries(sanitizedDetails)) {
-    if (SESSION_WARNING_ALLOWED_FIELDS.has(key)) {
-      payload[key] = value;
-    } else {
-      payload[key] = "[OMITTED]";
-    }
+  for (const [key, value] of Object.entries(allowedDetails)) {
+    payload[key] = value;
   }
   try {
-    console.warn(`${SESSION_WARNING_PREFIX} ${JSON.stringify(payload)}`);
+    process.stderr.write(`${SESSION_WARNING_PREFIX} ${JSON.stringify(payload)}\n`);
   } catch {
-    console.warn(`${SESSION_WARNING_PREFIX} ${payload.code}`);
+    console.error(`${SESSION_WARNING_PREFIX} ${payload.code}`);
   }
 }
 
+export function resetSessionWarningsForTests() {
+  emittedSessionWarningKeys.clear();
+}
+
+export function setKeytarClientForTests(client) {
+  const previous = keytarClientOverrideForTests;
+  keytarClientOverrideForTests = client || null;
+  return () => {
+    keytarClientOverrideForTests = previous;
+  };
+}
+
 function resolveHomeDir(homeDir) {
   return path.resolve(String(homeDir || os.homedir()));
 }
@@ -356,7 +377,10 @@ async function replaceWithBackup(tmpPath, filePath) {
   }
 }
 
-async function loadKeytarClient() {
+async function loadKeytarClient({ allowImplicit = false } = {}) {
+  if (keytarClientOverrideForTests !== undefined) {
+    return keytarClientOverrideForTests;
+  }
   const disableKeyring = String(process.env.SENTINELAYER_DISABLE_KEYRING || "")
     .trim()
     .toLowerCase();
@@ -372,7 +396,7 @@ async function loadKeytarClient() {
     keyringMode === "on" ||
     keyringMode === "true" ||
     keyringMode === "1";
-  if (!enableKeyring) {
+  if (!enableKeyring && !allowImplicit) {
     return null;
   }
   try {
@@ -394,6 +418,20 @@ async function loadKeytarClient() {
   }
 }
 
+async function encryptTokenForFileFallback(token, { homeDir } = {}) {
+  const key = await loadOrCreateFileKey({ homeDir });
+  return encryptToken(token, key);
+}
+
+async function attachEncryptedTokenFallback(metadata, token, { homeDir } = {}) {
+  const encrypted = await encryptTokenForFileFallback(token, { homeDir });
+  metadata.tokenEncrypted = encrypted.tokenEncrypted;
+  metadata.tokenIv = encrypted.tokenIv;
+  metadata.tokenTag = encrypted.tokenTag;
+  metadata.token = null;
+  return metadata;
+}
+
 async function readMetadata({ homeDir } = {}) {
   const filePath = resolveCredentialsFilePath({ homeDir });
   try {
@@ -480,20 +518,12 @@ async function migratePlaintextTokenIfNeeded({ metadata, filePath, homeDir } = {
     nextMetadata.storage = "keyring";
     nextMetadata.keyringService = KEYRING_SERVICE;
     nextMetadata.keyringAccount = keyringAccount;
-    const key = await loadOrCreateFileKey({ homeDir });
-    const encrypted = encryptToken(plaintextToken, key);
-    nextMetadata.tokenEncrypted = encrypted.tokenEncrypted;
-    nextMetadata.tokenIv = encrypted.tokenIv;
-    nextMetadata.tokenTag = encrypted.tokenTag;
+    await attachEncryptedTokenFallback(nextMetadata, plaintextToken, { homeDir });
   } else {
-    const key = await loadOrCreateFileKey({ homeDir });
-    const encrypted = encryptToken(plaintextToken, key);
     nextMetadata.storage = "file";
     nextMetadata.keyringService = KEYRING_SERVICE;
     nextMetadata.keyringAccount = "";
-    nextMetadata.tokenEncrypted = encrypted.tokenEncrypted;
-    nextMetadata.tokenIv = encrypted.tokenIv;
-    nextMetadata.tokenTag = encrypted.tokenTag;
+    await attachEncryptedTokenFallback(nextMetadata, plaintextToken, { homeDir });
   }
 
   await writeMetadata(filePath, nextMetadata);
@@ -570,7 +600,7 @@ export async function readStoredSession({ homeDir } = {}) {
   }
 
   if (metadata.storage === "keyring") {
-    const keytar = await loadKeytarClient();
+    const keytar = await loadKeytarClient({ allowImplicit: true });
     let keyringError = null;
     if (keytar && metadata.keyringAccount) {
       try {
@@ -763,17 +793,12 @@ export async function writeStoredSession(
     nextMetadata.storage = "keyring";
     nextMetadata.keyringService = KEYRING_SERVICE;
     nextMetadata.keyringAccount = keyringAccount;
-    nextMetadata.token = null;
+    await attachEncryptedTokenFallback(nextMetadata, normalizedToken, { homeDir });
   } else {
     nextMetadata.storage = "file";
     nextMetadata.keyringService = KEYRING_SERVICE;
     nextMetadata.keyringAccount = "";
-    const key = await loadOrCreateFileKey({ homeDir });
-    const encrypted = encryptToken(normalizedToken, key);
-    nextMetadata.token = null;
-    nextMetadata.tokenEncrypted = encrypted.tokenEncrypted;
-    nextMetadata.tokenIv = encrypted.tokenIv;
-    nextMetadata.tokenTag = encrypted.tokenTag;
+    await attachEncryptedTokenFallback(nextMetadata, normalizedToken, { homeDir });
   }
 
   await writeMetadata(filePath, nextMetadata);
@@ -794,7 +819,7 @@ export async function writeStoredSession(
 export async function clearStoredSession({ homeDir } = {}) {
   const { filePath, metadata } = await readMetadata({ homeDir });
   if (metadata && metadata.storage === "keyring") {
-    const keytar = await loadKeytarClient();
+    const keytar = await loadKeytarClient({ allowImplicit: true });
     if (keytar && metadata.keyringAccount) {
       await keytar.deletePassword(metadata.keyringService || KEYRING_SERVICE, metadata.keyringAccount);
     }

package/src/billing/ledger-entry.js

@@ -0,0 +1,162 @@
+import crypto from "node:crypto";
+
+import { redactEventPayload } from "../session/redact.js";
+import { computeProviderCost, PRICE_BOOK_VERSION } from "./price-book.js";
+
+export const PRICED_ACTIONS = Object.freeze([
+  "audit_run",
+  "audit_security",
+  "audit_frontend",
+  "omargate_deep",
+]);
+
+const OMIT_METADATA_KEYS = new Set([
+  "content",
+  "input",
+  "message",
+  "messages",
+  "output",
+  "prompt",
+  "prompts",
+  "raw",
+  "rawtext",
+  "response",
+  "responses",
+  "text",
+]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeTokenCount(value, field) {
+  const parsed = Number(value || 0);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${field} must be a non-negative number.`);
+  }
+  return Math.floor(parsed);
+}
+
+function normalizeIsoTimestamp(value, fallbackIso = new Date().toISOString()) {
+  const normalized = normalizeString(value);
+  if (!normalized) return fallbackIso;
+  const epoch = Date.parse(normalized);
+  if (!Number.isFinite(epoch)) {
+    throw new Error("createdAt must be an ISO timestamp.");
+  }
+  return new Date(epoch).toISOString();
+}
+
+export function stableHash(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+function sanitizeMetadataValue(value, depth = 0) {
+  if (depth > 8) return "[REDACTED]";
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => sanitizeMetadataValue(item, depth + 1))
+      .filter((item) => item !== undefined);
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, inner] of Object.entries(value)) {
+      const normalizedKey = normalizeString(key).toLowerCase().replace(/[^a-z0-9]/g, "");
+      if (!normalizedKey || OMIT_METADATA_KEYS.has(normalizedKey)) {
+        continue;
+      }
+      const sanitized = sanitizeMetadataValue(inner, depth + 1);
+      if (sanitized !== undefined) {
+        out[key] = sanitized;
+      }
+    }
+    return out;
+  }
+  return value;
+}
+
+export function sanitizeBillingMetadata(metadata = {}) {
+  const sanitized = sanitizeMetadataValue(metadata);
+  const redacted = redactEventPayload({ payload: sanitized });
+  return redacted?.payload && typeof redacted.payload === "object" ? redacted.payload : {};
+}
+
+export function buildBillingRunId({
+  sessionId,
+  invocationTimestamp,
+  configHash,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedTimestamp = normalizeString(invocationTimestamp);
+  const normalizedConfigHash = normalizeString(configHash);
+  if (!normalizedSessionId) throw new Error("sessionId is required.");
+  if (!normalizedTimestamp) throw new Error("invocationTimestamp is required.");
+  if (!normalizedConfigHash) throw new Error("configHash is required.");
+  return stableHash(`${normalizedSessionId}|${normalizedTimestamp}|${normalizedConfigHash}`).slice(0, 16);
+}
+
+export function buildCallIdempotencyKey({ runId, callIndex = 0 } = {}) {
+  const normalizedRunId = normalizeString(runId);
+  if (!normalizedRunId) throw new Error("runId is required.");
+  const normalizedCallIndex = normalizeTokenCount(callIndex, "callIndex");
+  return `${normalizedRunId}:${normalizedCallIndex}`;
+}
+
+export function buildLedgerEntry({
+  sessionId,
+  agentId,
+  action,
+  model,
+  inputTokens = 0,
+  outputTokens = 0,
+  idempotencyKey,
+  billingTier = "internal",
+  metadata = {},
+  createdAt = "",
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedAgentId = normalizeString(agentId);
+  const normalizedAction = normalizeString(action);
+  const normalizedModel = normalizeString(model);
+  const normalizedIdempotencyKey = normalizeString(idempotencyKey);
+  if (!normalizedSessionId) throw new Error("sessionId is required.");
+  if (!normalizedAgentId) throw new Error("agentId is required.");
+  if (!normalizedAction) throw new Error("action is required.");
+  if (!normalizedModel) throw new Error("model is required.");
+  if (!normalizedIdempotencyKey) throw new Error("idempotencyKey is required.");
+
+  const priced = computeProviderCost({
+    model: normalizedModel,
+    inputTokens,
+    outputTokens,
+  });
+  const createdIso = normalizeIsoTimestamp(createdAt);
+  return {
+    ledgerEntryId: `bill_${stableHash(normalizedIdempotencyKey).slice(0, 16)}`,
+    schema: "billing/v1",
+    sessionId: normalizedSessionId,
+    agentId: normalizedAgentId,
+    action: normalizedAction,
+    model: normalizedModel,
+    canonicalModel: priced.canonicalModel,
+    priceBookVersion: PRICE_BOOK_VERSION,
+    inputTokens: priced.inputTokens,
+    outputTokens: priced.outputTokens,
+    totalTokens: priced.totalTokens,
+    providerCostUsd: priced.providerCostUsd,
+    customerCostUsd: null,
+    billingTier: normalizeString(billingTier) || "internal",
+    idempotencyKey: normalizedIdempotencyKey,
+    unpriced: Boolean(priced.unpriced),
+    createdAt: createdIso,
+    metadata: sanitizeBillingMetadata(metadata),
+  };
+}
+
+export function countPricedUsageEvents(events = [], pricedActions = PRICED_ACTIONS) {
+  const actions = new Set((Array.isArray(pricedActions) ? pricedActions : []).map(normalizeString));
+  return (Array.isArray(events) ? events : []).filter((event) => {
+    const payload = event?.payload || {};
+    return event?.event === "session_usage" && payload.schema === "billing/v1" && actions.has(normalizeString(payload.action));
+  }).length;
+}

package/src/billing/price-book.js

@@ -0,0 +1,123 @@
+export const PRICE_BOOK_VERSION = "2026-05-19";
+
+export const PRICE_BOOK_SOURCES = Object.freeze({
+  openai: "https://platform.openai.com/docs/pricing",
+  openaiCodex: "https://developers.openai.com/api/docs/models/gpt-5.3-codex",
+  anthropic: "https://docs.anthropic.com/en/docs/about-claude/pricing",
+});
+
+const RATE = (inputPerMTok, outputPerMTok, source, aliases = []) =>
+  Object.freeze({
+    inputPerMTok,
+    outputPerMTok,
+    currency: "USD",
+    source,
+    aliases,
+  });
+
+export const PRICE_BOOK = Object.freeze({
+  "gpt-5.4-mini": RATE(0.75, 4.5, "openai"),
+  "gpt-5.3-codex": RATE(1.75, 14, "openaiCodex"),
+  "gpt-5.2-codex": RATE(1.75, 14, "openai"),
+  "gpt-5.1-codex": RATE(1.25, 10, "openai"),
+  "gpt-5-codex": RATE(1.25, 10, "openai"),
+  "gpt-4.1-mini": RATE(0.4, 1.6, "openai"),
+  "claude-opus-4.1": RATE(15, 75, "anthropic", ["claude-opus-4-7"]),
+  "claude-opus-4": RATE(15, 75, "anthropic", ["claude-opus-4-6"]),
+  "claude-sonnet-4": RATE(3, 15, "anthropic", ["claude-sonnet-4-6"]),
+  "claude-sonnet-3.7": RATE(3, 15, "anthropic"),
+  "claude-sonnet-3.5": RATE(3, 15, "anthropic"),
+  "claude-haiku-3.5": RATE(0.8, 4, "anthropic"),
+  "claude-haiku-3": RATE(0.25, 1.25, "anthropic"),
+});
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeModel(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+function normalizeTokenCount(value, field) {
+  const parsed = Number(value || 0);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${field} must be a non-negative number.`);
+  }
+  return Math.floor(parsed);
+}
+
+function round6(value) {
+  return Math.round((Number(value || 0) + Number.EPSILON) * 1_000_000) / 1_000_000;
+}
+
+const ALIAS_TO_MODEL = Object.freeze(
+  Object.entries(PRICE_BOOK).reduce((acc, [model, rate]) => {
+    acc[model] = model;
+    for (const alias of rate.aliases || []) {
+      acc[normalizeModel(alias)] = model;
+    }
+    return acc;
+  }, {}),
+);
+
+export function resolvePriceBookRate(model) {
+  const requestedModel = normalizeString(model);
+  const normalized = normalizeModel(requestedModel);
+  const canonicalModel = ALIAS_TO_MODEL[normalized] || normalized;
+  const rate = PRICE_BOOK[canonicalModel] || null;
+  if (!rate) {
+    return {
+      model: requestedModel,
+      canonicalModel: normalized || requestedModel,
+      rate: null,
+      unpriced: true,
+      priceBookVersion: PRICE_BOOK_VERSION,
+    };
+  }
+  return {
+    model: requestedModel || canonicalModel,
+    canonicalModel,
+    rate,
+    unpriced: false,
+    priceBookVersion: PRICE_BOOK_VERSION,
+  };
+}
+
+export function computeProviderCost({
+  model,
+  inputTokens = 0,
+  outputTokens = 0,
+} = {}) {
+  const input = normalizeTokenCount(inputTokens, "inputTokens");
+  const output = normalizeTokenCount(outputTokens, "outputTokens");
+  const resolved = resolvePriceBookRate(model);
+  if (resolved.unpriced) {
+    return {
+      model: resolved.model,
+      canonicalModel: resolved.canonicalModel,
+      priceBookVersion: PRICE_BOOK_VERSION,
+      providerCostUsd: null,
+      unpriced: true,
+      inputTokens: input,
+      outputTokens: output,
+      totalTokens: input + output,
+    };
+  }
+  const providerCostUsd = round6(
+    (input / 1_000_000) * resolved.rate.inputPerMTok +
+      (output / 1_000_000) * resolved.rate.outputPerMTok,
+  );
+  return {
+    model: resolved.model,
+    canonicalModel: resolved.canonicalModel,
+    priceBookVersion: PRICE_BOOK_VERSION,
+    providerCostUsd,
+    unpriced: false,
+    inputTokens: input,
+    outputTokens: output,
+    totalTokens: input + output,
+    currency: resolved.rate.currency,
+    source: resolved.rate.source,
+  };
+}

package/src/billing/session-usage.js

@@ -0,0 +1,80 @@
+import process from "node:process";
+
+import { createAgentEvent } from "../events/schema.js";
+import { createSession } from "../session/store.js";
+import { appendToStream } from "../session/stream.js";
+import { buildLedgerEntry } from "./ledger-entry.js";
+
+const SESSION_USAGE_EVENT = "session_usage";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+async function appendUsageEvent(sessionId, envelope, { targetPath, syncRemote }) {
+  return appendToStream(sessionId, envelope, {
+    targetPath,
+    syncRemote,
+  });
+}
+
+export async function recordSessionUsage(
+  sessionId,
+  params = {},
+  {
+    targetPath = process.cwd(),
+    // Billing events originate in the CLI and must reach the API for server-side
+    // ledger/quota projection; this intentionally defaults to remote sync.
+    syncRemote = true,
+    ensureLocalSession = true,
+    append = appendUsageEvent,
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) throw new Error("sessionId is required.");
+  const entry = buildLedgerEntry({
+    ...params,
+    sessionId: normalizedSessionId,
+  });
+  const envelope = createAgentEvent({
+    event: SESSION_USAGE_EVENT,
+    sessionId: normalizedSessionId,
+    agentId: entry.agentId,
+    agentModel: entry.model,
+    payload: {
+      ...entry,
+      costUsd: entry.providerCostUsd ?? 0,
+      usage: {
+        totalTokens: entry.totalTokens,
+        inputTokens: entry.inputTokens,
+        outputTokens: entry.outputTokens,
+        costUsd: entry.providerCostUsd ?? 0,
+        providerCostUsd: entry.providerCostUsd,
+        customerCostUsd: entry.customerCostUsd,
+      },
+    },
+    ts: entry.createdAt,
+  });
+
+  try {
+    await append(normalizedSessionId, envelope, { targetPath, syncRemote });
+  } catch (error) {
+    if (!ensureLocalSession || !/was not found/i.test(error?.message || "")) {
+      throw error;
+    }
+    await createSession({
+      sessionId: normalizedSessionId,
+      targetPath,
+      title: `Billing usage ${normalizedSessionId}`,
+      createdAt: entry.createdAt,
+      lastInteractionAt: entry.createdAt,
+    });
+    await append(normalizedSessionId, envelope, { targetPath, syncRemote });
+  }
+
+  return {
+    ok: true,
+    event: SESSION_USAGE_EVENT,
+    ledgerEntry: entry,
+  };
+}

package/src/commands/session.js

@@ -1690,6 +1690,14 @@ export function registerSessionCommand(program) {
       let hydration = null;
       let remoteTail = null;
       if (options.remote) {
+        const authSession = await resolveActiveAuthSession({
+          cwd: targetPath,
+          env: process.env,
+          autoRotate: false,
+        });
+        if (!authSession || !authSession.token) {
+          throw new Error(`Remote session read requires authentication. Run \`${authLoginHint()}\` first.`);
+        }
         hydration = await hydrateSessionFromRemote({
           sessionId: normalizedSessionId,
           targetPath,

package/src/cost/tracker.js

@@ -6,8 +6,16 @@ const DEFAULT_MODEL_PRICING = Object.freeze({
     outputPerMillionUsd: 10.0,
   }),
   "gpt-5.3-codex": Object.freeze({
-    inputPerMillionUsd: 1.5,
-    outputPerMillionUsd: 6.0,
+    inputPerMillionUsd: 1.75,
+    outputPerMillionUsd: 14.0,
+  }),
+  "gpt-5.4-mini": Object.freeze({
+    inputPerMillionUsd: 0.75,
+    outputPerMillionUsd: 4.5,
+  }),
+  "gpt-4.1-mini": Object.freeze({
+    inputPerMillionUsd: 0.4,
+    outputPerMillionUsd: 1.6,
   }),
   "claude-sonnet-4": Object.freeze({
     inputPerMillionUsd: 3.0,
@@ -21,6 +29,14 @@ const DEFAULT_MODEL_PRICING = Object.freeze({
     inputPerMillionUsd: 3.0,
     outputPerMillionUsd: 15.0,
   }),
+  "claude-opus-4": Object.freeze({
+    inputPerMillionUsd: 15.0,
+    outputPerMillionUsd: 75.0,
+  }),
+  "claude-opus-4.1": Object.freeze({
+    inputPerMillionUsd: 15.0,
+    outputPerMillionUsd: 75.0,
+  }),
   "claude-opus-4-6": Object.freeze({
     inputPerMillionUsd: 15.0,
     outputPerMillionUsd: 75.0,
@@ -29,6 +45,14 @@ const DEFAULT_MODEL_PRICING = Object.freeze({
     inputPerMillionUsd: 15.0,
     outputPerMillionUsd: 75.0,
   }),
+  "claude-haiku-3.5": Object.freeze({
+    inputPerMillionUsd: 0.8,
+    outputPerMillionUsd: 4.0,
+  }),
+  "claude-haiku-3": Object.freeze({
+    inputPerMillionUsd: 0.25,
+    outputPerMillionUsd: 1.25,
+  }),
   "gemini-2.5-pro": Object.freeze({
     inputPerMillionUsd: 2.5,
     outputPerMillionUsd: 10.0,

package/src/review/ai-review.js

@@ -1,15 +1,18 @@
 import fsp from "node:fs/promises";
 import path from "node:path";
+import crypto from "node:crypto";
 
 import {
   createMultiProviderApiClient,
   resolveModel,
   resolveProvider,
 } from "../ai/client.js";
+import { computeProviderCost } from "../billing/price-book.js";
+import { buildBillingRunId, buildCallIdempotencyKey } from "../billing/ledger-entry.js";
+import { recordSessionUsage } from "../billing/session-usage.js";
 import { loadConfig } from "../config/service.js";
 import { evaluateBudget } from "../cost/budget.js";
 import { appendCostEntry, summarizeCostHistory } from "../cost/history.js";
-import { estimateModelCost } from "../cost/tracker.js";
 import { estimateTokens } from "../cost/tokenizer.js";
 import { appendRunEvent, deriveStopClassFromBudget } from "../telemetry/ledger.js";
 
@@ -329,21 +332,22 @@ export function buildAiReviewPrompt({
 }
 
 function maybeEstimateModelCost({ modelId, inputTokens, outputTokens }) {
-  try {
-    return {
-      costUsd: estimateModelCost({
-        modelId,
-        inputTokens,
-        outputTokens,
-      }),
-      pricingFound: true,
-    };
-  } catch {
-    return {
-      costUsd: 0,
-      pricingFound: false,
-    };
-  }
+  const priced = computeProviderCost({
+    model: modelId,
+    inputTokens,
+    outputTokens,
+  });
+  return {
+    costUsd: priced.providerCostUsd ?? 0,
+    providerCostUsd: priced.providerCostUsd,
+    pricingFound: !priced.unpriced,
+    priceBookVersion: priced.priceBookVersion,
+    canonicalModel: priced.canonicalModel,
+  };
+}
+
+function stableConfigHash(value = {}) {
+  return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }
 
 function composeAiReviewMarkdown({
@@ -529,6 +533,7 @@ export async function runAiReviewLayer({
   });
 
   const startedAt = Date.now();
+  const startedAtIso = new Date(startedAt).toISOString();
   const responseText = dryRun
     ? buildDryRunResponse({
         deterministicSummary: deterministic?.summary || {},
@@ -643,6 +648,53 @@ export async function runAiReviewLayer({
     }
   );
 
+  let sessionUsageLedger = null;
+  try {
+    const billingRunId = buildBillingRunId({
+      sessionId: normalizedSessionId,
+      invocationTimestamp: startedAtIso,
+      configHash: stableConfigHash({
+        sourceCommand: "review",
+        layer: "ai_reasoning",
+        provider: resolvedProvider,
+        model: resolvedModel,
+        mode: normalizedMode,
+        runId: normalizedRunId,
+        dryRun: Boolean(dryRun),
+      }),
+    });
+    sessionUsageLedger = await recordSessionUsage(
+      normalizedSessionId,
+      {
+        agentId: "audit-orchestrator",
+        action: "audit_run",
+        model: resolvedModel,
+        inputTokens,
+        outputTokens,
+        idempotencyKey: buildCallIdempotencyKey({ runId: billingRunId, callIndex: 0 }),
+        billingTier: "internal",
+        createdAt: startedAtIso,
+        metadata: {
+          sourceCommand: "review",
+          layer: "ai_reasoning",
+          provider: resolvedProvider,
+          mode: normalizedMode,
+          runId: normalizedRunId,
+          dryRun: Boolean(dryRun),
+          pricingFound: modelCost.pricingFound,
+        },
+      },
+      {
+        targetPath: normalizedTargetPath,
+      },
+    );
+  } catch (error) {
+    sessionUsageLedger = {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error || "session_usage_failed"),
+    };
+  }
+
   let stopTelemetry = null;
   if (budget.blocking) {
     stopTelemetry = await appendRunEvent(
@@ -704,6 +756,7 @@ export async function runAiReviewLayer({
     dryRun: Boolean(dryRun),
     usage,
     pricingFound: modelCost.pricingFound,
+    sessionUsageLedger,
     budget,
     deterministicSummary,
     aiSummary,
@@ -756,6 +809,7 @@ export async function runAiReviewLayer({
       usageEventId: usageTelemetry.event.eventId,
       stopEventId: stopTelemetry?.event?.eventId || null,
     },
+    billing: sessionUsageLedger,
   };
 }