segreant 0.1.0 → 0.2.0

package/LICENSING.md

@@ -20,9 +20,9 @@ No account, key, payment or permission is needed for any of that.
 1. **Offer Segreant as a service.** You may not run it, or a modified version
    of it, as a hosted or managed service for other people or other companies.
    Running it for your own organization is fine.
-2. **Sell Segreant itself.** You may not sell, rent or charge a licence fee for
-   Segreant or a modified version of it, including a copy relabelled under
-   another name.
+2. **Sell Segreant itself.** You may not sell, rent, sublicense or otherwise
+   charge a fee for Segreant or a modified version of it, including a copy
+   relabelled under another name.
 
 ## Every version becomes fully open source
 
@@ -56,5 +56,7 @@ terms, open a
   under the PolyForm Noncommercial License 1.0.0 (from 2026-10-08 with an
   individual use permission). Those copies keep the terms they were published
   with; every later version is under the terms above.
+- The npm package `segreant` 0.1.0 (2026-10-08) is under this license
+  (`BUSL-1.1` in its package metadata and LICENSE file).
 
 *This page explains the license; it is not legal advice.*

package/README.md

@@ -7,11 +7,11 @@
 **Govern the spend. Not the developer.**
 
 The financial control layer for AI coding agents, running on your own machine.
-Every dollar your agents spend is metered, capped, checked against the
-provider's bill, assigned to the budget it belongs to, and traced to the work
-it produced. And every number tells you exactly how much it can be trusted.
+Your agents' spend is metered, capped before a loop runs away with it, checked
+against the provider's bill, assigned to the budget it belongs to, and traced to
+the work it produced. And every number tells you exactly how much it can be trusted.
 
-`local-first` · `zero runtime dependencies` · `2,300+ tests` · `Node 24+` · `free for personal use`
+`local-first` · `zero runtime dependencies` · `3,000+ tests` · `Node 24+` · `free to use, including at work (BUSL-1.1)`
 
 [![CI](https://github.com/GamingDragonwastaken/Segreant/actions/workflows/ci.yml/badge.svg)](https://github.com/GamingDragonwastaken/Segreant/actions/workflows/ci.yml)
 
@@ -87,9 +87,11 @@ No API key, no account, no setup. With Node 24 or newer:
 npx segreant demo --serve   # labelled synthetic data; opens the dashboard
 ```
 
-Open **http://localhost:8091**. You'll see spend by project and model, budget
-controls and governance alerts, the Return on Intelligence view, and a
-review-only cheaper-model trial. It all runs on an isolated `demo.db` and is
+Open **http://localhost:8091**. You'll see a month's statement with all four
+figures, spend by project and model with each session and what its commits
+came to, caps and alerts, a comparison with a generated provider bill,
+cost-centre splits, and what the spend produced, with a review-only
+cheaper-model comparison. It all runs on an isolated `demo.db` and is
 labelled as synthetic. Clear it with `segreant demo --clear`.
 
 ## Use it on your real work
@@ -100,9 +102,16 @@ Install the `segreant` command (it has no runtime dependencies):
 npm install -g segreant
 ```
 
+On Windows, a project-local install (`npm install segreant`) inside a folder
+whose path contains `&` cannot start through `npx` or `node_modules\.bin`:
+npm's generated `.cmd` shim does not quote that path. The global install above
+and `npx segreant` from any folder are not affected. For a local install there,
+run `node node_modules/segreant/bin/segreant.mjs` instead.
+
 **Option A: no wiring at all.** If you use Claude Code, Codex or opencode,
 Segreant reads the usage those tools already log on your machine, including
-subscription usage a proxy never sees:
+subscription usage a proxy never sees. Antigravity is read from 0.2.0, which is
+unreleased and not yet on npm:
 
 ```bash
 segreant scan            # finds your AI tools and git repos; changes nothing
@@ -131,10 +140,12 @@ export OPENAI_BASE_URL="http://localhost:8090/v1"
 
 A tool pointed at the proxy this way cannot connect while Segreant is stopped.
 
-Segreant starts **locked**: it forwards nothing to a cloud provider until you
-grant that exact route with `segreant egress apply`; the two commands for OpenAI
-and Anthropic are in [GETTING-STARTED.md](docs/GETTING-STARTED.md). Then set a
-cap:
+Requests to OpenAI's and Anthropic's official APIs go through as soon as Segreant
+starts: that traffic was already going to your provider, and Segreant meters it
+on the way. Everything Segreant would send on its own (webhooks, team rollups,
+hosted judging) stays off until you allow it, and another provider or gateway
+needs one rule, which a refused request prints
+([GETTING-STARTED.md](docs/GETTING-STARTED.md)). Then set a cap:
 
 ```bash
 segreant budget --daily 25 --soft 18 --runaway 2   # hard cap, warning, loop guard
@@ -166,11 +177,34 @@ Per-tool recipes (Cursor, aider, opencode, Antigravity, your own SDK scripts):
 - **Keep your data yours.** SQLite on your disk, verified backup and restore,
   and evidence packs you can sign and verify.
 
+### In the dashboard, without the terminal
+
+`segreant start` serves a local dashboard organised by job:
+
+- **Statement**: one calendar month, side by side. What was measured, what the
+  provider billed, how it was split, and what it produced. The four are never
+  added together, and the month downloads as a CSV.
+- **Spend**: where the measured spend went, by project, model and source.
+- **Protect**: caps and alerts that stop spend before it happens.
+- **Close**: declare the OpenAI project, bring in the cost export, and record
+  the comparison with what Segreant measured.
+- **Allocate**: cost centres, the rules that assign spend to them, and the
+  monthly split, previewed before it is recorded.
+- **Value**: what the spend produced, with the limits stated.
+
+- **Settings**: choose what you see, from density to which jobs sit in the top
+  bar, and a map of everything Segreant can do. Each capability the dashboard
+  runs opens from that map in one click.
+
+Splits, bill comparisons, imports, adoptions and budget changes show a preview
+before anything is saved. The dashboard follows your system's light or dark
+setting, works at phone width, and loads nothing from the internet.
+
 Every command, flag and design detail is in the **[Segreant guide](docs/GUIDE.md)**.
 
 ## For teams and enterprises
 
-The same local tool scales up without sending prompts or code anywhere:
+The same local tool scales up without sending prompts or code to any Segreant-run service:
 
 - **Team rollups.** Each machine signs and pushes per-project value and spend
   summaries to a team server *you* run. Per-developer views are opt-in,
@@ -211,13 +245,17 @@ Segreant has no hosted service and sends no telemetry by default. The ledger
 lives under `~/.segreant`, and the dashboard loads nothing from third parties:
 no CDNs, fonts or analytics. Requests you route through the proxy still go to
 the AI provider you configured, and your API keys pass through without being
-stored. Every other outbound path (price-card refresh, alert webhooks, team
-rollups) is opt-in and listed in [DATA-BOUNDARIES.md](docs/DATA-BOUNDARIES.md).
+stored. Segreant also downloads the public price list when it meets a model
+its rate card does not know; that download sends nothing about you, and
+`segreant pricing --auto off` stops it. Every other outbound path (alert
+webhooks, team rollups) is opt-in. The privacy statement is [PRIVACY.md](docs/PRIVACY.md), also
+one click from every dashboard page; every path in detail is in
+[DATA-BOUNDARIES.md](docs/DATA-BOUNDARIES.md).
 
 ## Status
 
 Segreant is **pre-release (0.1.0)**, published on npm as `segreant`. CI covers Linux, macOS and Windows, including a packaged-install
-smoke test, a browser accessibility pass and supply-chain checks.
+smoke test, real-browser tests and supply-chain checks.
 Reconciliation and outcome measurement are implemented and tested but have not
 yet been validated against real provider accounts or with outside users. That
 is what the first users will prove.
@@ -240,10 +278,10 @@ The full index is in [docs/README.md](docs/README.md).
 
 | | |
 |---|---|
-| Product code | ~88,000 lines of strict TypeScript |
-| Tests | ~70,000 lines, 2,300+ test cases across the CLI, dashboard and team server |
+| Product code | ~105,000 lines of strict TypeScript |
+| Tests | ~81,000 lines, 3,000+ test cases across the CLI, dashboard, team server and a real browser |
 | Runtime dependencies | 0 |
-| CI | 11 jobs on every pull request: three operating systems, the team server against real PostgreSQL, a packaged install, supply chain, accessibility, and exact-head verification |
+| CI | 14 checks on every pull request: three operating systems, install paths with spaces and `&`, the team server against real PostgreSQL, a packaged install, supply chain, real-browser tests, and exact-head verification |
 
 ## Development
 

package/bin/segreant-statusline.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Claude Code status line: `"statusLine": { "type": "command", "command": "segreant-statusline" }`.
+// Deliberately bypasses the full launcher (re-exec, runtime snapshot, CLI load):
+// a status line runs on every refresh and must answer in about a tenth of a
+// second. Prints one line on stdout and always exits 0, so a failure here can
+// never break the person's status bar.
+import { readFileSync } from 'node:fs';
+
+let line = 'segreant';
+try {
+  let raw = '';
+  try { raw = readFileSync(0, 'utf8').slice(0, 1_000_000); } catch { raw = ''; }
+  const { dbPath } = await import('../dist/config.js');
+  const { statuslineLine } = await import('../dist/quota/statusline.js');
+  line = statuslineLine(dbPath(), raw, Date.now());
+} catch {
+  line = 'segreant';
+}
+process.stdout.write(line + '\n');
+process.exit(0);

package/bin/segreant.mjs

@@ -6,7 +6,7 @@
 // path that a userland process.emitWarning override can't intercept, so we
 // re-exec ourselves once with --disable-warning to keep output clean. This is
 // the only knob that reliably suppresses it for `npx segreant`.
-import { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { acquirePublicationLock } from './publication-lock.mjs';
 import { createRuntimeSnapshot, reapOrphanRuntimeSnapshots } from './runtime-snapshot.mjs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -27,18 +27,29 @@ if (major < 24) {
 const self = fileURLToPath(import.meta.url);
 
 if (!process.env.__SEGREANT_CHILD) {
-  const result = spawnSync(
+  // Asynchronous, so the launcher can forward signals. With spawnSync it could
+  // not: a SIGTERM to `segreant` (a supervisor, `kill <pid>`) ended the
+  // launcher and left a running `start` or dashboard behind as an orphan.
+  // Ctrl+C in a terminal worked only because it signals the whole group.
+  const child = spawn(
     process.execPath,
     ['--disable-warning=ExperimentalWarning', self, ...process.argv.slice(2)],
     { stdio: 'inherit', env: { ...process.env, __SEGREANT_CHILD: '1' } },
   );
-  if (result.error) {
-    console.error(`Segreant could not start its runtime: ${result.error.message}`);
-    process.exit(1);
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => { if (child.exitCode === null && child.signalCode === null) child.kill(signal); });
   }
-  if (typeof result.status === 'number') process.exit(result.status);
-  console.error(`Segreant runtime terminated by signal ${result.signal ?? 'unknown'}`);
-  process.exit(1);
+  child.on('error', (error) => {
+    console.error(`Segreant could not start its runtime: ${error.message}`);
+    process.exit(1);
+  });
+  child.on('exit', (code, signal) => {
+    if (typeof code === 'number') process.exit(code);
+    // A child ended by a forwarded SIGINT/SIGTERM is the requested stop.
+    if (signal === 'SIGINT' || signal === 'SIGTERM' || signal === 'SIGHUP') process.exit(signal === 'SIGINT' ? 130 : 143);
+    console.error(`Segreant runtime terminated by signal ${signal ?? 'unknown'}`);
+    process.exit(1);
+  });
 } else {
   const here = dirname(self);
   // Collect snapshots whose owning process is gone before adding another one,

package/dist/alerts/detect.js

@@ -171,6 +171,17 @@ export function detectAlerts(inp) {
             metric: `${Math.round(inp.estimatedShare * 100)}% of last-7d spend estimated`,
         });
     }
+    // Prices the user set are not estimates of a list price, and not checked
+    // against one either; said apart from "approximate" so neither is mislabelled.
+    if ((inp.declaredShare ?? 0) > 0.2) {
+        out.push({
+            id: 'declared-pricing',
+            severity: 'info',
+            title: 'Some costs use prices you set',
+            detail: 'Part of recent spend is priced at prices set with segreant pricing set; they are not checked against a price list or your bill.',
+            metric: `${Math.round((inp.declaredShare ?? 0) * 100)}% of last-7d spend at prices you set`,
+        });
+    }
     return out.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
 }
 /** Gather the inputs once, so alerts and their coverage are read from the same observation. */
@@ -194,6 +205,7 @@ function gatherAlertInputs(store, config, opts) {
     const blocked24h = store.healthStats(now - day, now + 1000).blocked;
     const week = store.healthStats(now - 7 * day, now + 1000);
     const estimatedShare = week.totalCostUsd > 0 ? week.estimatedCostUsd / week.totalCostUsd : 0;
+    const declaredShare = week.totalCostUsd > 0 ? week.declaredCostUsd / week.totalCostUsd : 0;
     // Carried alongside the share so coverage can tell an unestimated window from
     // an empty one; the share alone cannot (D-141).
     const pricedWindowSpendUsd = week.totalCostUsd;
@@ -217,6 +229,7 @@ function gatherAlertInputs(store, config, opts) {
         baselinePrunedBeforeMs,
         blocked24h,
         estimatedShare,
+        declaredShare,
         pricedWindowSpendUsd,
         runaway,
         realizedSpendShare: opts.realizedSpendShare ?? null,

package/dist/billing/epistemic.js

@@ -503,6 +503,9 @@ function buildLocalCaptureEvidence(reconciliation, reconciliationRunId, issuedAt
             providerProjectRef: reconciliation.providerProjectRef,
             observationRunId: reconciliation.observationRunId,
             reconciliationRunId,
+            // How the exact local amounts became this microdollar total, when a rule
+            // applied; absent on runs recorded before it, which rounded nothing.
+            ...(reconciliation.localQuantization ? { localQuantization: { ...reconciliation.localQuantization } } : {}),
         },
         scope: scope({ provider: 'openai', declaredScopeId: reconciliation.declaredScopeId, providerProjectRef: reconciliation.providerProjectRef }),
         grain: grain(['provider_project_period']),
@@ -590,6 +593,7 @@ export function billingReconciliationClaim(input) {
                 // reader would get a residual with no statement of whether it bounds
                 // off-path spend at all.
                 offPathBound: input.run.offPathBound,
+                ...(input.run.localQuantization ? { localQuantization: { ...input.run.localQuantization } } : {}),
                 snapshotStability: input.run.snapshotStability,
                 providerSourceKind: input.run.providerSourceKind,
                 ...(input.reconciliationRunId === undefined ? {} : { reconciliationRunId: nonEmpty(input.reconciliationRunId, 'reconciliation run id') }),

package/dist/billing/importer.js

@@ -32,25 +32,44 @@ function preview(document, fileName, fileSha256, fileSizeBytes) {
         reconciliationStatus: 'not_reconciled',
     };
 }
+function sizeLimitError() {
+    return new Error(`billing evidence exceeds the ${MAX_BILLING_IMPORT_BYTES / (1024 * 1024)} MiB v1 import limit`);
+}
 /** Read, size-gate, hash, and strictly validate a Segreant billing-evidence v1 JSON file. */
 export function readBillingImportFile(path) {
     const stat = statSync(path);
     if (!stat.isFile())
         throw new Error('billing import --file must point to a regular local file');
-    if (stat.size > MAX_BILLING_IMPORT_BYTES) {
-        throw new Error(`billing evidence exceeds the ${MAX_BILLING_IMPORT_BYTES / (1024 * 1024)} MiB v1 import limit`);
-    }
-    const raw = readFileSync(path);
+    // Refuse before reading: a multi-gigabyte file must never be pulled into memory.
+    if (stat.size > MAX_BILLING_IMPORT_BYTES)
+        throw sizeLimitError();
+    return parseBillingImportText(readFileSync(path), basename(path));
+}
+/**
+ * The validation readBillingImportFile applies, over bytes already in hand. The
+ * dashboard import route calls this directly; the CLI reaches it through
+ * readBillingImportFile, so the two surfaces give the same preview for the same bytes.
+ */
+export function parseBillingImportText(raw, fileName) {
+    if (raw.byteLength > MAX_BILLING_IMPORT_BYTES)
+        throw sizeLimitError();
     let value;
     try {
-        value = JSON.parse(raw.toString('utf8'));
+        // A UTF-8 byte-order mark is not JSON, and Windows tools write one by
+        // default, so an export saved from Notepad was refused as "not valid JSON".
+        // It is skipped for parsing only: the digest below is over the file's own
+        // bytes, mark included, so the same file still has one identity.
+        const text = raw.toString('utf8');
+        value = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
     }
-    catch (error) {
-        throw new Error(`billing evidence is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    catch {
+        // Parser diagnostics can quote the file contents, which belong only in the
+        // operator's export, never in HTTP responses or CLI error output.
+        throw new Error('billing evidence is not valid JSON');
     }
     const document = parseBillingImportDocument(value);
-    const fileName = basename(path);
     const fileSha256 = createHash('sha256').update(raw).digest('hex');
-    const input = { document, fileName, fileSha256, fileSizeBytes: stat.size, format: 'json' };
-    return { input, preview: preview(document, fileName, fileSha256, stat.size) };
+    const fileSizeBytes = raw.byteLength;
+    const input = { document, fileName, fileSha256, fileSizeBytes, format: 'json' };
+    return { input, preview: preview(document, fileName, fileSha256, fileSizeBytes) };
 }

package/dist/billing/reconcile.js

@@ -107,6 +107,122 @@ export function describeOffPathBound(bound) {
 function refuse(refusal, detail) {
     return { status: 'refused', refusal, detail };
 }
+/**
+ * The rounding a comparison applied to the local side, in words, or null when
+ * it changed nothing. A run recorded before the rule existed rounded nothing
+ * either: it refused any exact amount finer than a microdollar.
+ */
+export function describeLocalQuantization(q) {
+    if (!q || q.daysRounded === 0)
+        return null;
+    const days = `${q.daysRounded} day total${q.daysRounded === 1 ? '' : 's'}`;
+    return `Local amounts finer than a microdollar were summed exactly for each day; ${days} then rounded to the microdollar, half to even, so the local figure is within $${(q.daysRounded * 0.0000005).toFixed(7)} of the exact sum.`;
+}
+/** An exact decimal (coefficient x 10^-scale) as bigint microdollars, rounded half to even. */
+function halfEvenMicrosBig(coefficient, scale) {
+    const shift = scale - 6;
+    if (shift <= 0)
+        return { micros: coefficient * 10n ** BigInt(-shift), rounded: false };
+    const divisor = 10n ** BigInt(shift);
+    const negative = coefficient < 0n;
+    const abs = negative ? -coefficient : coefficient;
+    let q = abs / divisor;
+    const r = abs % divisor;
+    const twice = r * 2n;
+    if (twice > divisor || (twice === divisor && q % 2n === 1n))
+        q += 1n;
+    return { micros: negative ? -q : q, rounded: r !== 0n };
+}
+/**
+ * An exact amount as an integer coefficient and a decimal scale, read through
+ * `formatMoneyAmount` so this stays a visible monetary read site (the FX
+ * consumer sweep classifies every file that reads Money).
+ */
+function exactParts(value) {
+    const text = formatMoneyAmount(value);
+    const negative = text.startsWith('-');
+    const [whole, fraction = ''] = (negative ? text.slice(1) : text).split('.');
+    const coefficient = BigInt(`${whole}${fraction}`);
+    return { coefficient: negative ? -coefficient : coefficient, scale: fraction.length };
+}
+/** bigint microdollars as a number, or null when a number cannot hold them exactly. */
+function safeMicros(micros) {
+    const max = BigInt(Number.MAX_SAFE_INTEGER);
+    return micros > max || micros < -max ? null : Number(micros);
+}
+/**
+ * An exact USD amount in microdollars, rounded half to even; says whether
+ * rounding changed it. Throws rather than return a number that lost digits.
+ */
+export function halfEvenMicros(value) {
+    const { coefficient, scale } = exactParts(value);
+    const { micros, rounded } = halfEvenMicrosBig(coefficient, scale);
+    const n = safeMicros(micros);
+    if (n === null)
+        throw new Error('amount is outside the supported fixed-point range');
+    return { micros: n, rounded };
+}
+function addExact(day, coefficient, scale) {
+    if (scale > day.scale) {
+        day.coefficient *= 10n ** BigInt(scale - day.scale);
+        day.scale = scale;
+    }
+    day.coefficient += coefficient * 10n ** BigInt(day.scale - scale);
+}
+/**
+ * Local capture per UTC day under the reconciliation's one rule: each row's
+ * exact amount (or, for a legacy row, its rate-card projection) is summed
+ * exactly per day, and only the day total is rounded to the microdollar, half
+ * to even. Anything that compares itself with a reconciliation's local figure
+ * uses this, so the two cannot disagree by a rounding: a period total rounded
+ * once from floats could come out below the per-day sum of a subset of it.
+ */
+export function quantizeLocalDays(rows, accept) {
+    const exactByDay = new Map();
+    for (const row of rows) {
+        if (!accept(row))
+            continue;
+        const key = utcDayStart(row.tsEpochMs);
+        const bucket = exactByDay.get(key) ?? { coefficient: 0n, scale: 6, requests: 0 };
+        if (row.economicAmount !== undefined) {
+            if (row.economicAmount.currency !== 'USD') {
+                return { refusal: {
+                        code: 'local_exact_amount_is_not_usd',
+                        message: `request ${row.requestId} has an exact local amount in ${row.economicAmount.currency}; this reconciliation has no FX policy`,
+                    } };
+            }
+            // Kept exact until the day is summed. Per-token prices give amounts like
+            // 0.0014008, finer than the provider's microdollars; refusing them here
+            // refused almost every real OpenAI route (found seeding the demo bill,
+            // 2026-10-16). The rule is stated in the result, not invented silently.
+            const parts = exactParts(row.economicAmount);
+            addExact(bucket, parts.coefficient, parts.scale);
+        }
+        else {
+            // Legacy rows have no exact economic event. Retain their compatibility
+            // projection explicitly as the rate-card estimate documented by the
+            // result, and add it into the same exact sum: rounding the exact part
+            // alone and adding the legacy part after could round a tie the wrong way.
+            addExact(bucket, BigInt(Math.round(row.costUsd * 1_000_000)), 6);
+        }
+        bucket.requests += 1;
+        exactByDay.set(key, bucket);
+    }
+    // Each day's exact sum becomes microdollars once, rounded half to even, and
+    // is checked against the number range before it leaves bigint.
+    let daysRounded = 0;
+    const localByDay = new Map();
+    for (const [key, day] of exactByDay) {
+        const { micros, rounded } = halfEvenMicrosBig(day.coefficient, day.scale);
+        const n = safeMicros(micros);
+        if (n === null)
+            return { refusal: { code: 'local_exact_amount_requires_explicit_quantization', message: 'a day total is outside the supported fixed-point range' } };
+        if (rounded)
+            daysRounded += 1;
+        localByDay.set(key, { micros: n, requests: day.requests });
+    }
+    return { localByDay, daysRounded };
+}
 /** UTC day key for a local ledger row, matching the provider's bucket boundary. */
 function utcDayStart(tsEpochMs) {
     return Math.floor(tsEpochMs / DAY_MS) * DAY_MS;
@@ -182,38 +298,11 @@ export function reconcileOpenAiCosts(input) {
         else
             providerByDay.set(line.bucketStartMs, [line]);
     }
-    const localByDay = new Map();
-    for (const row of input.requests) {
-        if (!isOnDeclaredRoute(row, input.run.declaredScopeId))
-            continue;
-        if (row.tsEpochMs < input.run.periodStartMs || row.tsEpochMs >= input.run.periodEndMs)
-            continue;
-        const key = utcDayStart(row.tsEpochMs);
-        const bucket = localByDay.get(key) ?? { micros: 0, requests: 0 };
-        let capturedMicros;
-        if (row.economicAmount !== undefined) {
-            if (row.economicAmount.currency !== 'USD') {
-                return refuse('local_exact_amount_is_not_usd', `request ${row.requestId} has an exact local amount in ${row.economicAmount.currency}; this reconciliation has no FX policy`);
-            }
-            try {
-                // Preserve the canonical exact amount until the fixed-point boundary.
-                // If it cannot be represented in provider microdollars, refusing is safer
-                // than inventing a rounding mode for a consequential comparison.
-                capturedMicros = usdMicros(formatMoneyAmount(row.economicAmount), `request ${row.requestId} exact amount`);
-            }
-            catch (error) {
-                return refuse('local_exact_amount_requires_explicit_quantization', `request ${row.requestId} exact local amount cannot be represented in microdollars without an explicit quantization policy: ${error instanceof Error ? error.message : String(error)}`);
-            }
-        }
-        else {
-            // Legacy rows have no exact economic event. Retain their compatibility
-            // projection explicitly as the rate-card estimate documented by the result.
-            capturedMicros = Math.round(row.costUsd * 1_000_000);
-        }
-        bucket.micros += capturedMicros;
-        bucket.requests += 1;
-        localByDay.set(key, bucket);
-    }
+    const quantized = quantizeLocalDays(input.requests, (row) => isOnDeclaredRoute(row, input.run.declaredScopeId)
+        && row.tsEpochMs >= input.run.periodStartMs && row.tsEpochMs < input.run.periodEndMs);
+    if ('refusal' in quantized)
+        return refuse(quantized.refusal.code, quantized.refusal.message);
+    const { localByDay, daysRounded } = quantized;
     const days = [];
     const allDays = [...new Set([...providerByDay.keys(), ...localByDay.keys()])].sort((a, b) => a - b);
     let providerTotal = 0;
@@ -290,6 +379,7 @@ export function reconcileOpenAiCosts(input) {
         },
         days,
         snapshotStability,
+        localQuantization: { rule: 'day_total_half_even_micros', daysRounded },
         unstableDayStartMs,
         providerSourceKind: sourceKind,
         // The fifth condition appears only when it is true. A reader who sees four

package/dist/billing/scope.js

@@ -18,6 +18,13 @@ function safeRef(value, label, required) {
         throw new Error(`${label} is required`);
     if (trimmed.length > MAX_REF || CONTROL.test(trimmed))
         throw new Error(`${label} must be a short, single-line reference`);
+    // A reference is stored for good and issued to the kernel, so a key typed into
+    // this field would become durable ledger content. OpenAI keys start `sk-`
+    // (sk-proj-, sk-admin-, sk-svcacct-); restricted keys `rk-`. Refuse the shape
+    // outright rather than store it and hope nobody exports the ledger.
+    if (/^(sk|rk)-/i.test(trimmed) || /^bearer\s/i.test(trimmed)) {
+        throw new Error(`${label} looks like an API key. Use the organisation id (org_…) or project id (proj_…) from your OpenAI settings; never a key.`);
+    }
     return trimmed;
 }
 /** Canonical, credential-free identity of the configured upstream endpoint. */

package/dist/budget/guard.js

@@ -125,18 +125,47 @@ export function resolveEnforcedSpend(exact, floatUsd) {
         };
 }
 /** One clause naming the basis, appended to whatever refusal or warning states the number. */
+/**
+ * Spend on the basis a cap governs, over [startMs, endMs), projected exactly
+ * as the guard projects it (resolveEnforcedSpend), with the number of requests
+ * behind it. The guide and the budget advisor read this rather than a series
+ * of their own: a separate series could say "no proxied spend" while the guard
+ * was blocking on it (review 4, F3).
+ */
+export function capBasisSpend(store, budget, startMs, endMs) {
+    const liveOnly = !budget.capIncludesImported;
+    const exact = typeof store.exactSpendBetween === 'function' ? store.exactSpendBetween(startMs, endMs, liveOnly) : null;
+    const resolved = resolveEnforcedSpend(exact, store.spendBetween(startMs, endMs, liveOnly));
+    return { usd: resolved.usd, requests: exact?.requestCount ?? null, basis: liveOnly ? 'live_proxy' : 'all_observed' };
+}
 export function describeSpendBasis(basis) {
     if (basis.enforcedAgainst === 'rate_card_float' && basis.exactResolvedUsd === null) {
-        return 'Basis: local rate-card estimates, with no exact economic projection available.';
+        return 'Basis: local estimates (list prices, and any prices you set), with no exact economic projection available.';
     }
     const bases = basis.sourceBases.length > 0 ? basis.sourceBases.join(', ') : 'none declared';
     if (basis.complete)
         return `Basis: effective economic charges (${bases}), complete for this window.`;
     const which = basis.enforcedAgainst === 'exact_effective'
         ? `effective economic charges (${bases})`
-        : 'local rate-card estimates';
+        : 'local estimates (list prices, and any prices you set)';
     return `Basis: ${which}, a lower bound — ${basis.unresolvedRequests} of ${basis.requestCount} requests in this window are unpriced.`;
 }
+/**
+ * Spend beside the cap it crossed. Two decimals hid the overshoot: $5.004
+ * against a $5 cap read "$5.00 of $5.00". When the two would round alike but
+ * differ, add digits (to the microdollar) until they do not. A difference
+ * below the microdollar is said in words, so two different amounts never
+ * print as the same figure (PR #142 review).
+ */
+export function spendBesideCap(spendUsd, capUsd) {
+    let digits = 2;
+    while (digits < 6 && spendUsd !== capUsd && spendUsd.toFixed(digits) === capUsd.toFixed(digits))
+        digits += 1;
+    const shown = '$' + spendUsd.toFixed(digits);
+    if (spendUsd === capUsd || spendUsd.toFixed(digits) !== capUsd.toFixed(digits))
+        return shown;
+    return `${spendUsd > capUsd ? 'just over' : 'just under'} ${shown}`;
+}
 export function startOfLocalDay(now = Date.now()) {
     const d = new Date(now);
     d.setHours(0, 0, 0, 0);
@@ -250,7 +279,7 @@ export class BudgetGuard {
             return {
                 ...base,
                 action: 'block',
-                reason: `Daily budget reached: $${daySpend.toFixed(2)} of $${dailyLimit.toFixed(2)} cap` +
+                reason: `Daily budget reached: ${spendBesideCap(daySpend, dailyLimit)} of $${dailyLimit.toFixed(2)} cap` +
                     (liveOnly ? ' (live proxy spend; imported spend excluded). ' : ' (includes imported spend). ') +
                     describeSpendBasis(day.basis),
             };
@@ -259,7 +288,7 @@ export class BudgetGuard {
             return {
                 ...base,
                 action: 'block',
-                reason: `Session budget reached: $${session.usd.toFixed(2)} of $${cfg.sessionUsd.toFixed(2)} cap. `
+                reason: `Session budget reached: ${spendBesideCap(session.usd, cfg.sessionUsd)} of $${cfg.sessionUsd.toFixed(2)} cap. `
                     + describeSpendBasis(session.basis),
             };
         }