segreant 0.1.0 → 0.2.0

package/dist/dashboard/routes.js

@@ -17,37 +17,51 @@
 import { reconciliationReadiness } from '../billing/readiness.js';
 import { CLAIM_USES } from '../epistemic/claim-uses.js';
 import { EXACT_ALLOCATION_EXCLUDED_FLOOR } from '../alloc/exact.js';
+import { ALLOCATION_METHODS, MATCH_FIELDS } from '../alloc/rules.js';
 import { existsSync, statSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
 import { allocatedClaimSupport, billedClaimSupport, meteredClaimSupport, realizedClaimSupport, } from './claim-support.js';
-import { isDemo } from '../config.js';
+import { isDemo, loadConfig, DemoReadOnlyError, DemoWriteBlockedError } from '../config.js';
+import { MAX_BILLING_IMPORT_BYTES, parseBillingImportText } from '../billing/importer.js';
+import { newOpenAiScopeDeclaration } from '../billing/scope.js';
+import { reconciliationCountermodels } from '../billing/countermodels.js';
+import { assessAssumptionFragility } from '../epistemic/countermodel.js';
+import { moneyToJson } from '../economics/money.js';
 import { probeProxyState } from '../egress/proxyHealth.js';
 import { buildSettingsSnapshot, applySettingsPatch, SettingsValidationError } from './settings.js';
 import { serveHtml } from './static.js';
-import { resolveEnforcedSpend, startOfLocalDay } from '../budget/guard.js';
+import { capBasisSpend, resolveEnforcedSpend, startOfLocalDay } from '../budget/guard.js';
 import { driftDetectability } from '../value/drift.js';
-import { loadRealization, realizeDiscoveredProjects } from '../value/realization.js';
+import { loadRealization, realizeDiscoveredProjects, realizationFromStore, keptSummary } from '../value/realization.js';
 // The one composition of the value primitives, shared with the CLI — see the
 // '/api/value' handler below and src/value/report.ts for why it is not inline.
 import { valueReport } from '../value/report.js';
+import { buildSessions } from './sessions.js';
 import { recordReportedOutcome } from '../value/selfReported.js';
 import { buildMarketReport, loadMarket } from '../market/market.js';
-import { projectName } from '../git/correlate.js';
+import { projectName, resolveCommit } from '../git/correlate.js';
+import { ValueReadCache, valueCacheKey } from './value-cache.js';
 import { scanWithDiff, saveScan } from '../scan/scan.js';
 import { describeSourceDepth } from '../value/sourceDepth.js';
 import { buildGuide } from '../guide.js';
 import { computeAlertCoverage, computeAlerts } from '../alerts/detect.js';
 import { requestsToCsv } from '../export/csv.js';
+import { statementToCsv } from '../export/statementCsv.js';
+import { allocationRunToCsv } from '../export/allocationCsv.js';
 import { economicRequestsToCsv } from '../export/economic.js';
 import { instant } from '../epistemic/time.js';
 import { DIMENSIONS } from '../value/characterization.js';
-import { IMPORTERS, emptyImportSummary } from '../connect/importShared.js';
-import { importClaudeCode, defaultClaudeCodeRoot } from '../connect/claudeCode.js';
-import { importOpencode, defaultOpencodeDbPath } from '../connect/opencode.js';
-import { importCodex, defaultCodexRoot } from '../connect/codex.js';
+import { emptyImportSummary } from '../connect/importShared.js';
+import { IMPORT_REGISTRY } from '../connect/registry.js';
 import { judgeSessionFromStore } from '../judge/orchestrate.js';
 import { resolveJudgeTier, hasHostedJudgeApiKey } from '../judge/tier.js';
 import { pricingStatus } from '../cost/pricing.js';
+import { declarePrice, unknownModels } from '../cost/declarations.js';
+import { previewReprice, applyReprice } from '../cost/reprice.js';
+import { modelNameError, removePriceOverride } from '../cost/overrides.js';
+import { summarizeBasis } from '../cost/basis.js';
 import { pricingCoverage } from '../cost/coverage.js';
+import { activePriceOverrides } from '../cost/overrides.js';
 import { RESOURCE_LIMITS } from '../util/resource-limits.js';
 import { buildEconomicReport } from '../cli/economicCmd.js';
 import { verifyBlockedAssignmentPlan } from '../causal/assignment.js';
@@ -116,6 +130,7 @@ export function buildOverview(store, config, range) {
         : todaySpend;
     const summary = store.summary(startMs, endMs);
     const pricingWindow = store.healthStats(startMs, endMs);
+    const provenance = store.pricingEvidenceByModel(startMs, endMs);
     // What retention deleted from inside this window. Read from the ledger's own
     // record, because an absence of rows is exactly what cannot distinguish a
     // quiet window from a pruned one (D-175).
@@ -128,7 +143,8 @@ export function buildOverview(store, config, range) {
         // in the browser, which answered `complete` for a window with no spend in it.
         claimSupport: meteredClaimSupport({
             totalCostUsd: pricingWindow.totalCostUsd,
-            estimatedCostUsd: pricingWindow.estimatedCostUsd,
+            // Prices you set are not list prices, so they never count as list support.
+            estimatedCostUsd: pricingWindow.estimatedCostUsd + pricingWindow.declaredCostUsd,
             retention,
         }),
         retention,
@@ -156,7 +172,8 @@ export function buildOverview(store, config, range) {
             // Per-row provenance, grouped without mixing cards or match paths. This
             // is deliberately separate from the active card above: a refresh never
             // rewrites the evidence captured for historical requests.
-            provenance: store.pricingEvidenceByModel(startMs, endMs),
+            provenance,
+            basis: summarizeBasis(provenance),
         },
         byModel: store.byModel(startMs, endMs),
         byProject: store.byProject(startMs, endMs),
@@ -185,23 +202,11 @@ export function buildOverview(store, config, range) {
         alertCoverage: computeAlertCoverage(store, config, { now }),
     };
 }
-const DASH_IMPORTERS = [
-    {
-        ...IMPORTERS.find((i) => i.id === 'claude-code'),
-        locate: () => (existsSync(defaultClaudeCodeRoot()) ? defaultClaudeCodeRoot() : null),
-        run: (store, opts) => importClaudeCode(store, opts),
-    },
-    {
-        ...IMPORTERS.find((i) => i.id === 'opencode'),
-        locate: () => defaultOpencodeDbPath(),
-        run: (store, opts) => importOpencode(store, opts),
-    },
-    {
-        ...IMPORTERS.find((i) => i.id === 'codex'),
-        locate: () => defaultCodexRoot(),
-        run: (store, opts) => importCodex(store, opts),
-    },
-];
+// The same registry the CLI and `scan` use (src/connect/registry.ts), so the
+// dashboard can never again skip a tool the terminal reads.
+const DASH_IMPORTERS = IMPORT_REGISTRY.map((e) => ({
+    id: e.id, label: e.label, blurb: e.blurb, locate: e.locate, run: e.run,
+}));
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -220,6 +225,14 @@ export function handleImporters({ res }) {
         }),
     });
 }
+/** Demo mode writes nothing real: refuse with a conflict and drain the body. */
+function refuseDemoImport(req, res, what) {
+    if (!isDemo())
+        return false;
+    req.resume();
+    json(res, 409, { error: new DemoWriteBlockedError(what).message });
+    return true;
+}
 /**
  * Trigger a native import from the dashboard. POST-only + a custom header the
  * browser only sets same-origin (declared in the route table): a cross-site form
@@ -227,6 +240,8 @@ export function handleImporters({ res }) {
  * mutating the local DB.
  */
 export function handleImport({ req, res, url, store }) {
+    if (refuseDemoImport(req, res, 'the import'))
+        return;
     const tool = url.searchParams.get('tool') ?? 'all';
     const targets = tool === 'all' ? DASH_IMPORTERS : DASH_IMPORTERS.filter((i) => i.id === tool);
     if (targets.length === 0)
@@ -286,6 +301,8 @@ export function handleDiscover({ req, res, url, store }) {
 export function handleScan({ req, res, url, store }) {
     const path = url.searchParams.get('path') || undefined;
     if (req.method === 'POST') {
+        if (refuseDemoImport(req, res, 'the import and setup'))
+            return;
         req.resume();
         void (async () => {
             try {
@@ -345,6 +362,219 @@ export function handleOverview({ res, url, store, config }) {
         return json(res, 500, { error: String(err) });
     }
 }
+export function handleSessions({ res, url, store }) {
+    const range = url.searchParams.get('range') ?? '7d';
+    const valid = ['today', '7d', '30d', 'all'];
+    const safe = valid.includes(range) ? range : '7d';
+    try {
+        const now = Date.now();
+        return json(res, 200, buildSessions(store, safe, resolveRange(safe, now), { now }));
+    }
+    catch (err) {
+        return json(res, 500, { error: String(err) });
+    }
+}
+const STATEMENT_MONTH_NAMES = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+const STATEMENT_TOP = 10;
+const STATEMENT_RUN_LIMIT = 50;
+/**
+ * Local-time calendar month, half-open: local midnight on the 1st to local
+ * midnight on the 1st of the next month. Local time matches startOfLocalDay,
+ * which the day figures already use. Only the rolling `segreant month` window
+ * exists in the CLI, so there is no calendar helper to reuse.
+ */
+export function calendarMonthBounds(year, month) {
+    return { startMs: new Date(year, month - 1, 1).getTime(), endMs: new Date(year, month, 1).getTime() };
+}
+/**
+ * How far a month's overlapping runs reach. Never a sum: a run that covers only
+ * part of the month says so, and no run is prorated into a month figure.
+ */
+function monthCoverageOf(runs) {
+    if (runs.length === 0)
+        return 'not_established';
+    return runs.some((r) => r.coversWholeMonth) ? 'whole' : 'partial';
+}
+export function handleStatement({ res, url, store }) {
+    const r = buildStatement(store, url.searchParams.get('month'), STATEMENT_TOP);
+    return r.status === 200 ? json(res, 200, r.payload) : json(res, r.status, { error: r.error });
+}
+/**
+ * The same month as a spreadsheet: every project and model rather than the
+ * page's top ten, and the four claims kept as four sections with no total.
+ */
+export function handleStatementCsv({ res, url, store }) {
+    const r = buildStatement(store, url.searchParams.get('month'), null);
+    if (r.status !== 200)
+        return json(res, r.status, { error: r.error });
+    res.writeHead(200, {
+        'content-type': 'text/csv; charset=utf-8',
+        'content-disposition': `attachment; filename="segreant-statement-${r.payload.month}${r.payload.demo ? '-sample' : ''}.csv"`,
+        'cache-control': 'no-store',
+    });
+    res.end(statementToCsv(r.payload));
+}
+/**
+ * F5. A unit is counted in the month its survival check falls (commit time plus
+ * the window), as last measured. Read from stored snapshots, so opening a month
+ * never runs git. Dollars are the list cost behind the work, not its value.
+ */
+export function realizedForMonth(store, startMs, endMs) {
+    const report = realizationFromStore(store);
+    // Each unit is placed by the window it was measured with. Units persisted
+    // before that was recorded fall back to the default, and the reason says so.
+    const DAY_MS = 24 * 60 * 60 * 1000;
+    const due = (u) => u.tsEpochMs + (u.checkWindowDays ?? report.windowDays) * DAY_MS;
+    const judged = report.units.filter((u) => !u.maturing && due(u) >= startMs && due(u) < endMs);
+    const waiting = report.units.filter((u) => u.maturing && u.tsEpochMs < endMs && due(u) >= startMs);
+    const k = keptSummary({ units: judged, windowDays: report.windowDays });
+    const cost = (us) => us.reduce((s, u) => s + (Number.isFinite(u.attributedCostUsd) ? u.attributedCostUsd : 0), 0);
+    const measuredAt = report.units.length > 0 ? report.generatedAt : null;
+    const assumed = [...judged, ...waiting].filter((u) => u.checkWindowDays === undefined).length;
+    return {
+        standing: judged.length > 0 ? 'judged_in_month' : 'none_judged',
+        windowDays: report.windowDays,
+        assumedWindowUnits: assumed,
+        measuredAt,
+        kept: k.kept,
+        notKept: k.notKept,
+        contested: k.contested,
+        unknown: k.unknown,
+        tooEarly: { units: waiting.length, costUsd: cost(waiting), nextCheckMs: waiting.length > 0 ? Math.min(...waiting.map(due)) : null },
+        reason: measuredAt === null
+            ? 'No outcomes have been measured on this machine yet. Run a value read from the Value page.'
+            : `Work is counted in the month its survival check falls, as last measured. The dollars are the list cost of that work, not its value; a value needs an hourly rate and is on the Value page.`
+                + (assumed > 0 ? ` ${assumed} ${assumed === 1 ? 'piece was' : 'pieces were'} measured before Segreant recorded each check's window, so ${assumed === 1 ? 'it is' : 'they are'} placed by the ${report.windowDays}-day default.` : ''),
+    };
+}
+function buildStatement(store, raw, top) {
+    try {
+        const now = Date.now();
+        let year;
+        let month;
+        if (raw === null) {
+            const current = new Date(now);
+            year = current.getFullYear();
+            month = current.getMonth() + 1;
+        }
+        else {
+            const match = /^(\d{4})-(\d{2})$/.exec(raw);
+            if (!match)
+                return { status: 400, error: 'month must be YYYY-MM, for example 2026-07' };
+            year = Number(match[1]);
+            month = Number(match[2]);
+            if (year < 1970 || month < 1 || month > 12)
+                return { status: 400, error: 'month must be a calendar month from 1970 onward' };
+        }
+        const { startMs, endMs } = calendarMonthBounds(year, month);
+        if (startMs > now)
+            return { status: 400, error: `month ${year}-${String(month).padStart(2, '0')} is entirely in the future` };
+        const overlaps = (periodStartMs, periodEndMs) => periodStartMs < endMs && periodEndMs > startMs;
+        const covers = (periodStartMs, periodEndMs) => periodStartMs <= startMs && periodEndMs >= endMs;
+        // Metered: the same reads buildOverview makes, for this month's range.
+        const summary = store.summary(startMs, endMs);
+        const pricingWindow = store.healthStats(startMs, endMs);
+        const retention = store.windowCoverage(startMs);
+        const basis = summarizeBasis(store.pricingEvidenceByModel(startMs, endMs));
+        // Provider-billed: runs whose period overlaps the month. A partial run is
+        // reported as itself, with its own figures, never prorated into the month.
+        const reconciliation = store.reconciliationRuns(STATEMENT_RUN_LIMIT);
+        const billedRuns = reconciliation
+            .filter((r) => overlaps(r.result.periodStartMs, r.result.periodEndMs))
+            .map((r) => ({
+            reconciliationRunId: r.reconciliationRunId,
+            computedAtMs: r.computedAtMs,
+            periodStartMs: r.result.periodStartMs,
+            periodEndMs: r.result.periodEndMs,
+            providerReportedMicros: r.result.providerReportedMicros,
+            localCapturedMicros: r.result.localCapturedMicros,
+            unexplainedVarianceMicros: r.result.unexplainedVarianceMicros,
+            providerSourceKind: r.result.providerSourceKind,
+            offPathBound: r.result.offPathBound ?? null,
+            snapshotStability: r.result.snapshotStability ?? null,
+            localQuantization: r.result.localQuantization ?? null,
+            providerProjectRef: r.result.providerProjectRef ?? null,
+            coversWholeMonth: covers(r.result.periodStartMs, r.result.periodEndMs),
+        }));
+        // Allocated: the same rule over allocation runs.
+        const allocations = store.allocationRuns(STATEMENT_RUN_LIMIT);
+        const allocatedRuns = allocations
+            .filter((r) => overlaps(r.result.periodStartMs, r.result.periodEndMs))
+            .map((r) => ({
+            allocationRunId: r.allocationRunId,
+            computedAtMs: r.computedAtMs,
+            periodStartMs: r.result.periodStartMs,
+            periodEndMs: r.result.periodEndMs,
+            totalMicros: r.result.totalMicros,
+            allocatedMicros: r.result.allocatedMicros,
+            unallocatedMicros: r.result.unallocatedMicros,
+            conserves: r.result.conserves,
+            byCostCentre: r.result.byCostCentre.map((c) => ({
+                costCentreId: c.costCentreId,
+                allocatedMicros: c.allocatedMicros,
+                requestCount: c.requestCount,
+                sourceBasis: c.sourceBasis,
+            })),
+            coversWholeMonth: covers(r.result.periodStartMs, r.result.periodEndMs),
+        }));
+        const closeStatus = store.economicPeriodCloseStatus(startMs, endMs);
+        const byProject = store.byProject(startMs, endMs)
+            .slice(0, top ?? undefined)
+            .map((p) => ({ label: p.label, costUsd: p.costUsd, requests: p.requests }));
+        const byModel = store.byModel(startMs, endMs)
+            .slice(0, top ?? undefined)
+            .map((m) => ({ label: m.label, provider: m.provider, costUsd: m.costUsd, requests: m.requests }));
+        return { status: 200, payload: {
+                demo: isDemo(),
+                generatedAt: new Date(now).toISOString(),
+                month: `${year}-${String(month).padStart(2, '0')}`,
+                period: {
+                    startMs,
+                    endMs,
+                    label: `${STATEMENT_MONTH_NAMES[month - 1]} ${year}`,
+                    complete: endMs <= now,
+                },
+                metered: {
+                    costUsd: summary.costUsd,
+                    requests: summary.requests,
+                    claimSupport: meteredClaimSupport({
+                        totalCostUsd: pricingWindow.totalCostUsd,
+                        estimatedCostUsd: pricingWindow.estimatedCostUsd + pricingWindow.declaredCostUsd,
+                        retention,
+                    }),
+                    basis,
+                    retention,
+                    byProject,
+                    byModel,
+                },
+                billed: {
+                    monthCoverage: monthCoverageOf(billedRuns),
+                    overlappingRuns: billedRuns.length,
+                    // False when the store returned as many runs as it was asked for, so an
+                    // older overlapping run may exist beyond the read. A "not established"
+                    // with this false is a limit of the read, not a finding.
+                    scanComplete: reconciliation.length < STATEMENT_RUN_LIMIT,
+                    runs: billedRuns,
+                },
+                allocated: {
+                    monthCoverage: monthCoverageOf(allocatedRuns),
+                    overlappingRuns: allocatedRuns.length,
+                    scanComplete: allocations.length < STATEMENT_RUN_LIMIT,
+                    runs: allocatedRuns,
+                    costCentres: store.costCentres().map((c) => ({ costCentreId: c.costCentreId, name: c.name })),
+                },
+                realized: realizedForMonth(store, startMs, endMs),
+                close: {
+                    status: closeStatus.status,
+                    activeFinalizationId: closeStatus.activeFinalizationId,
+                    eventCount: closeStatus.eventCount,
+                },
+            } };
+    }
+    catch (error) {
+        return { status: 500, error: error instanceof Error ? error.message : String(error) };
+    }
+}
 /**
  * Provider billing evidence has a different truth contract from the local
  * request ledger: an operator supplied it, Segreant has not verified it with
@@ -373,6 +603,16 @@ export function handleBilling({ res, url, store }) {
         // disagree the moment a run landed between the calls.
         const runs = store.reconciliationRuns(10);
         const summary = store.billingSummary();
+        // An adopted export is recorded as an observation whose one "page" digest
+        // is the file's SHA-256 (adoptOpenAiCostsFromImport). Only an adoption under
+        // the ACTIVE declaration puts a file in use: one adopted under an earlier
+        // declaration says nothing about the project declared now.
+        const scope = store.activeOpenAiScope();
+        const adoptions = scope === null ? [] : store.openAiCostsObservationRuns(200).filter((o) => o.sourceKind === 'operator_supplied_export' && o.resultState === 'succeeded' && o.declaredScopeId === scope.declarationId);
+        const imports = store.billingImportRuns(25).map((run) => {
+            const adopted = adoptions.find((o) => o.pageDigestChainSha256 === run.fileSha256);
+            return { ...run, inUse: adopted ? { observationRunId: adopted.observationRunId, adoptedAtMs: adopted.fetchedAtMs } : null };
+        });
         return json(res, 200, {
             demo: isDemo(),
             /** The boundary the kernel claims answer at; `null` is a live read. */
@@ -404,7 +644,17 @@ export function handleBilling({ res, url, store }) {
                 ],
             },
             summary,
-            imports: store.billingImportRuns(25),
+            // The declaration itself, so the page can name what is declared and what
+            // clearing it would end. An operator statement, never provider-verified.
+            activeScope: scope === null ? null : {
+                declarationId: scope.declarationId,
+                billingAccountRef: scope.billingAccountRef,
+                providerProjectRef: scope.providerProjectRef,
+                upstreamDisplay: scope.upstreamDisplay,
+                declaredAtMs: scope.declaredAtMs,
+                trust: scope.trust,
+            },
+            imports,
             kernel: {
                 kind: 'trusted_epistemic_kernel_billing',
                 claims: store.billingKernelClaims(25, asOf),
@@ -473,6 +723,35 @@ export function handleBilling({ res, url, store }) {
  * rather than derived money — the page needs them to name a centre and to
  * show which rule version placed each line.
  */
+/**
+ * One recorded allocation run as CSV, by id. Read from the stored run, never
+ * recomputed, so the file is the split someone reviewed. An id is required:
+ * "the latest run" would silently change meaning when a new one is recorded.
+ */
+export function handleAllocationRunCsv({ res, url, store }) {
+    const id = url.searchParams.get('id');
+    if (id === null || id.trim() === '')
+        return json(res, 400, { error: 'id is required: the allocation run to export' });
+    if (id.length > 200)
+        return json(res, 400, { error: 'id is too long to be an allocation run id' });
+    try {
+        const run = store.allocationRunById(id);
+        if (run === null)
+            return json(res, 404, { error: 'no recorded allocation run has that id' });
+        const names = new Map(store.costCentres().map((c) => [c.costCentreId, c.name]));
+        const demo = isDemo();
+        const day = new Date(run.result.periodStartMs).toISOString().slice(0, 10);
+        res.writeHead(200, {
+            'content-type': 'text/csv; charset=utf-8',
+            'content-disposition': `attachment; filename="segreant-allocation-${day}${demo ? '-sample' : ''}.csv"`,
+            'cache-control': 'no-store',
+        });
+        res.end(allocationRunToCsv(run, (costCentreId) => names.get(costCentreId) ?? costCentreId, demo));
+    }
+    catch (err) {
+        return json(res, 500, { error: String(err) });
+    }
+}
 export function handleAllocation({ res, store }) {
     try {
         const reconciliationRuns = store.reconciliationRuns(1);
@@ -606,6 +885,104 @@ export function handlePricing({ res, url, store, config }) {
         return json(res, 500, { error: String(err) });
     }
 }
+export function handlePricingUnknown({ res, store }) {
+    try {
+        const payload = {
+            models: unknownModels(store), demo: isDemo(),
+            // Sample data shows no real declarations (activePriceOverrides is empty in demo mode).
+            declared: Object.entries(activePriceOverrides()).sort(([a], [b]) => a.localeCompare(b)).map(([model, price]) => ({
+                model, kind: price.kind, declaredAt: price.declaredAt,
+                summary: price.kind === 'free' ? 'free (local model)'
+                    : price.kind === 'like' ? `like ${price.like}`
+                        : `input $${price.input}, output $${price.output}${price.cacheRead ? `, cache read $${price.cacheRead}` : ''}${price.cacheWrite ? `, cache write $${price.cacheWrite}` : ''}${price.cacheWrite1h ? `, 1-hour cache write $${price.cacheWrite1h}` : ''} per 1M tokens`,
+                ...(price.kind === 'rate' ? { rate: {
+                        input: price.input, output: price.output,
+                        ...(price.cacheRead === undefined ? {} : { cacheRead: price.cacheRead }),
+                        ...(price.cacheWrite === undefined ? {} : { cacheWrite: price.cacheWrite }),
+                        ...(price.cacheWrite1h === undefined ? {} : { cacheWrite1h: price.cacheWrite1h }),
+                    } } : {}),
+                ...(price.kind === 'like' ? { like: price.like } : {}),
+            })),
+            boundary: 'Recorded cost (estimated). Declaring a price leaves recorded requests unchanged until you re-price them.',
+        };
+        json(res, 200, payload);
+    }
+    catch (error) {
+        json(res, 500, { error: error instanceof Error ? error.message : String(error) });
+    }
+}
+/** Small local pricing operations share a strict 16 KiB JSON boundary. */
+async function pricingBody(req, allowed) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of req) {
+        bytes += chunk.byteLength;
+        if (bytes > 16_384) {
+            req.resume();
+            throw new PricingBodyTooLarge();
+        }
+        chunks.push(chunk);
+    }
+    let body;
+    try {
+        body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new Error('request must contain valid JSON');
+    }
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        throw new Error('request must be an object');
+    if (Object.keys(body).some((key) => !allowed.includes(key)))
+        throw new Error('request has an unknown field');
+    return body;
+}
+class PricingBodyTooLarge extends Error {
+}
+function pricingWrite(context, allowed, action, readOnly = () => false) {
+    void (async () => {
+        try {
+            const body = await pricingBody(context.req, allowed);
+            // A preview writes nothing, so the sample data can show one (independent
+            // review, 2026-10-18); only a write is refused there.
+            if (isDemo() && !readOnly(body))
+                return json(context.res, 409, { error: new DemoWriteBlockedError('the pricing change').message });
+            json(context.res, 200, action(body));
+        }
+        catch (error) {
+            json(context.res, error instanceof PricingBodyTooLarge ? 413 : 400, {
+                error: error instanceof PricingBodyTooLarge ? 'pricing request exceeds bounded dashboard limit' : error instanceof Error ? error.message : String(error),
+            });
+        }
+    })();
+}
+export function handlePricingDeclare(context) {
+    pricingWrite(context, ['model', 'kind', 'input', 'output', 'cacheRead', 'cacheWrite', 'cacheWrite1h', 'like'], (body) => {
+        const { model, ...input } = body;
+        const error = modelNameError(model);
+        if (error)
+            throw new Error(error);
+        // setPriceOverride validates kind-specific fields and decimal strings; no coercion.
+        const price = declarePrice(model, input);
+        return { ok: true, model: model, price };
+    });
+}
+export function handlePricingUnset(context) {
+    pricingWrite(context, ['model'], (body) => {
+        const error = modelNameError(body.model);
+        if (error)
+            throw new Error(error);
+        const model = body.model;
+        return { ok: true, model, removed: removePriceOverride(model) };
+    });
+}
+export function handleReprice(context) {
+    pricingWrite(context, ['apply'], (body) => {
+        if (typeof body.apply !== 'boolean')
+            throw new Error('apply must be true or false');
+        const { updates: _updates, meta: _meta, priceEvidence: _legacyCliEvidence, ...report } = body.apply ? applyReprice(context.store) : previewReprice(context.store);
+        return { ...report, demo: isDemo() };
+    }, (body) => body.apply === false);
+}
 export function handleExportCsv({ res, url, store }) {
     const range = url.searchParams.get('range') ?? '30d';
     const valid = ['today', '7d', '30d', 'all'];
@@ -707,6 +1084,10 @@ export function handleGuide({ res, store, config }) {
                 requestsAllTime: store.summary(0, now + 1000).requests,
                 requestsRetention: store.retentionFloor(),
                 spend30dUsd: store.summary(now - 30 * day, now + 1000).costUsd,
+                ...(() => {
+                    const capBasis = capBasisSpend(store, config.budget, now - 30 * day, now + 1000);
+                    return { capBasisSpend30dUsd: capBasis.usd, capBasis: capBasis.basis };
+                })(),
                 dailyCapUsd: config.budget.dailyUsd,
                 outcomeSignals: store.countSignals(),
                 realizationUnits: store.countRealizationUnits(),
@@ -769,103 +1150,136 @@ export function handleJudge({ req, res, store, config }) {
         }
     })();
 }
+const valueReadCaches = new WeakMap();
+/**
+ * The value read cache of one Store, created on first use. Scoped per Store so
+ * two dashboards (or two tests, each with a fresh Store) never share answers.
+ * `opts` applies only when the cache is created; tests use it to inject a clock.
+ */
+export function valueReadCacheFor(store, opts) {
+    let cache = valueReadCaches.get(store);
+    if (cache === undefined) {
+        cache = new ValueReadCache(opts);
+        valueReadCaches.set(store, cache);
+    }
+    return cache;
+}
 export function handleValue({ res, url, store, config }) {
     const repo = safeRepo(url.searchParams.get('repo'));
     const windowDays = Number(url.searchParams.get('window') || '14') || 14;
+    const explicitRepo = url.searchParams.has('repo');
     void (async () => {
         try {
-            // The whole composition — realization, baseline, Lift, money, RoI,
-            // drift, time reclaimed, frontier, per-project value, usage, cohort and
-            // budget advice — lives in src/value/report.ts, which the CLI's `roi` /
-            // `saved` commands call too. The two surfaces used to sequence these
-            // primitives independently, held in step only by comments claiming they
-            // matched. Now there is one sequence, so they cannot drift apart.
-            //
-            // `repo` is never empty — `safeRepo` falls back to the dashboard's
-            // launch directory when no `?repo=` is given, the same
-            // `flags.repo ?? process.cwd()` convention every CLI command uses — so
-            // the baseline mines that directory's git history exactly as
-            // `segreant roi` (no `--repo`) would.
-            //
-            // `discloseLiftSource: false` keeps this payload's strings exactly as
-            // they have always been: the CLI names its Lift source in
-            // `roi.lenses.lift.how` and labels the demo's synthetic TSF in
-            // `roi.notes`; this endpoint never has. It is a disclosure difference
-            // only — every value, interval and dollar is computed identically.
-            const value = await valueReport(store, config, {
-                repo,
-                windowDays,
-                limit: 40,
-                persist: false,
-                discloseLiftSource: false,
-            });
-            const spine = value.spine;
-            const rep = spine?.loaded.report ?? null;
-            // The payload's realization slice is deliberately narrower than the
-            // full report: the fields the GUI declares, and no more.
-            const realization = rep
-                ? {
-                    matured: rep.matured,
-                    firstPassAcceptance: rep.firstPassAcceptance,
-                    proposalCoverage: rep.proposalCoverage,
-                    projectScoped: rep.projectScoped,
-                    costStaleUnits: rep.costStaleUnits,
-                    units: rep.units,
-                }
-                : null;
-            // Raw frontier cells may be unlike tasks. The dashboard exposes only
-            // the separately gated, within-task model trials from `frontier`.
-            const allocation = null;
-            // Cross-project allocation is not comparable/reliable enough to
-            // recommend from raw RoI alone; per-project value stays descriptive.
-            const projectAllocation = null;
-            // The money claim is `returnRatio.manualEquivalentValueUsd`, and only when
-            // the payload's own `basis` says it is priced. A dollar figure is never
-            // invented from a bare ratio.
-            const ratio = spine?.roi?.returnRatio ?? null;
-            const roiCoverage = spine?.roi?.coverage;
-            return json(res, 200, {
-                demo: value.demo,
-                // Contradicted gate evidence lands on COVERAGE here rather than on the
-                // epistemic axis, because mature units are different propositions and a
-                // population of contradictions is not a contradiction in the aggregate.
-                // See `src/dashboard/claim-support.ts`.
-                claimSupport: realizedClaimSupport({
-                    maturedUnits: rep?.matured?.units ?? 0,
-                    realizedUnits: rep?.matured?.realizedUnits ?? 0,
-                    gateConflicts: rep?.matured?.gateConflicts ?? null,
-                    roiCoverage: typeof roiCoverage === 'number' ? roiCoverage : null,
-                    valued: ratio?.basis === 'usd' && typeof ratio.manualEquivalentValueUsd === 'number',
-                }),
-                gitRepo: spine?.loaded.source === 'git',
-                valueSource: spine?.loaded.source ?? null,
-                // Whether the realized-value dollars came from spend SCOPED to this
-                // project (imports / tagged proxy) vs the project-blind window sum —
-                // disclosed so the number's basis is never silent.
-                projectScoped: rep?.projectScoped ?? null,
+            // Answered from memory when nothing the report reads has changed (see
+            // src/dashboard/value-cache.ts for the key). Nothing here persists.
+            const head = await resolveCommit(repo, 'HEAD');
+            const key = valueCacheKey({
+                params: url.searchParams,
                 repo,
-                generatedAt: new Date(value.generatedAtMs).toISOString(),
-                realization,
-                roi: spine?.roi ?? null,
-                frontier: spine?.frontier ?? null,
-                budget: value.budget,
-                allocation,
-                projects: value.projects,
-                projectAllocation,
-                usage: value.usage,
-                selfReported: value.selfReported,
-                team: value.team,
-                drift: spine?.drift === null || spine?.drift === undefined
-                    ? null
-                    : { ...spine.drift, ...driftDetectability(spine.drift) },
-                reclaimed: spine?.reclaimed ?? null,
+                head,
+                config,
+                marks: store.valueChangeMarks(),
             });
+            const payload = await valueReadCacheFor(store).get(key, () => computeValuePayload(store, config, repo, windowDays, explicitRepo));
+            return json(res, 200, payload);
         }
         catch (err) {
             return json(res, 500, { error: String(err) });
         }
     })();
 }
+async function computeValuePayload(store, config, repo, windowDays, explicitRepo) {
+    // The whole composition — realization, baseline, Lift, money, RoI,
+    // drift, time reclaimed, frontier, per-project value, usage, cohort and
+    // budget advice — lives in src/value/report.ts, which the CLI's `roi` /
+    // `saved` commands call too. The two surfaces used to sequence these
+    // primitives independently, held in step only by comments claiming they
+    // matched. Now there is one sequence, so they cannot drift apart.
+    //
+    // `repo` is never empty — `safeRepo` falls back to the dashboard's
+    // launch directory when no `?repo=` is given, the same
+    // `flags.repo ?? process.cwd()` convention every CLI command uses — so
+    // the baseline mines that directory's git history exactly as
+    // `segreant roi` (no `--repo`) would.
+    //
+    // `discloseLiftSource: false` keeps this payload's strings exactly as
+    // they have always been: the CLI names its Lift source in
+    // `roi.lenses.lift.how` and labels the demo's synthetic TSF in
+    // `roi.notes`; this endpoint never has. It is a disclosure difference
+    // only — every value, interval and dollar is computed identically.
+    const value = await store.withReadSnapshot(() => valueReport(store, config, {
+        repo,
+        windowDays,
+        limit: 40,
+        persist: false,
+        discloseLiftSource: false,
+        // Without an explicit ?repo=, answer from what `scan` measured and
+        // stored (every project, as the CLI home view does) rather than
+        // re-reading the launch folder's git on every load.
+        preferStored: !explicitRepo,
+    }));
+    const spine = value.spine;
+    const rep = spine?.loaded.report ?? null;
+    // The payload's realization slice is deliberately narrower than the
+    // full report: the fields the GUI declares, and no more.
+    const realization = rep
+        ? {
+            matured: rep.matured,
+            firstPassAcceptance: rep.firstPassAcceptance,
+            proposalCoverage: rep.proposalCoverage,
+            projectScoped: rep.projectScoped,
+            costStaleUnits: rep.costStaleUnits,
+            units: rep.units,
+        }
+        : null;
+    // Raw frontier cells may be unlike tasks. The dashboard exposes only
+    // the separately gated, within-task model trials from `frontier`.
+    const allocation = null;
+    // Cross-project allocation is not comparable/reliable enough to
+    // recommend from raw RoI alone; per-project value stays descriptive.
+    const projectAllocation = null;
+    // The money claim is `returnRatio.manualEquivalentValueUsd`, and only when
+    // the payload's own `basis` says it is priced. A dollar figure is never
+    // invented from a bare ratio.
+    const ratio = spine?.roi?.returnRatio ?? null;
+    const roiCoverage = spine?.roi?.coverage;
+    return {
+        demo: value.demo,
+        // Contradicted gate evidence lands on COVERAGE here rather than on the
+        // epistemic axis, because mature units are different propositions and a
+        // population of contradictions is not a contradiction in the aggregate.
+        // See `src/dashboard/claim-support.ts`.
+        claimSupport: realizedClaimSupport({
+            maturedUnits: rep?.matured?.units ?? 0,
+            realizedUnits: rep?.matured?.realizedUnits ?? 0,
+            gateConflicts: rep?.matured?.gateConflicts ?? null,
+            roiCoverage: typeof roiCoverage === 'number' ? roiCoverage : null,
+            valued: ratio?.basis === 'usd' && typeof ratio.manualEquivalentValueUsd === 'number',
+        }),
+        gitRepo: spine?.loaded.source === 'git',
+        valueSource: spine?.loaded.source ?? null,
+        // Whether the realized-value dollars came from spend SCOPED to this
+        // project (imports / tagged proxy) vs the project-blind window sum —
+        // disclosed so the number's basis is never silent.
+        projectScoped: rep?.projectScoped ?? null,
+        repo,
+        generatedAt: new Date(value.generatedAtMs).toISOString(),
+        realization,
+        roi: spine?.roi ?? null,
+        frontier: spine?.frontier ?? null,
+        budget: value.budget,
+        allocation,
+        projects: value.projects,
+        projectAllocation,
+        usage: value.usage,
+        selfReported: value.selfReported,
+        team: value.team,
+        drift: spine?.drift === null || spine?.drift === undefined
+            ? null
+            : { ...spine.drift, ...driftDetectability(spine.drift) },
+        reclaimed: spine?.reclaimed ?? null,
+    };
+}
 /** Public market, read-only: the bundled snapshot plus any refresh already on disk. Never fetches. */
 export function handleMarket({ res, config }) {
     try {
@@ -875,6 +1289,442 @@ export function handleMarket({ res, config }) {
         return json(res, 500, { error: error instanceof Error ? error.message : String(error) });
     }
 }
+const ALLOCATION_WRITE_FIELDS = new Set(['op', 'apply', 'id', 'name', 'owner', 'method', 'targets', 'match', 'priority', 'from', 'to', 'until', 'note']);
+const ALLOCATION_WRITE_OPS = new Set(['centre', 'archive', 'rule', 'revoke', 'run']);
+function allocationId(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 64)
+        throw new Error('id must be a non-empty string of at most 64 characters');
+    return value;
+}
+function allocationText(value, label, max) {
+    if (typeof value !== 'string' || value.trim().length === 0 || value.length > max)
+        throw new Error(`${label} must be a non-empty string of at most ${max} characters`);
+    return value;
+}
+function allocationOptionalText(value, label) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== 'string')
+        throw new Error(`${label} must be a string`);
+    return value;
+}
+/** An ISO date or date-time, or null when absent. Mirrors parseTs in src/cli/allocCmd.ts. */
+function allocationTs(value, label) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== 'string')
+        throw new Error(`${label} must be an ISO date or date-time`);
+    if (!value.trim())
+        return null;
+    const ms = Date.parse(value.trim());
+    if (!Number.isFinite(ms))
+        throw new Error(`${label} must be an ISO date or date-time`);
+    return ms;
+}
+/** Same rules as parseTargets in src/cli/allocCmd.ts; the store validates ids and ratio ranges. */
+function allocationTargets(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw new Error('targets must name at least one cost centre');
+    return value.map((entry) => {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+            throw new Error('each target must be { costCentreId, ratio }');
+        const target = entry;
+        const costCentreId = allocationId(target.costCentreId);
+        if (typeof target.ratio !== 'number' || !Number.isFinite(target.ratio))
+            throw new Error(`target ${costCentreId}: ratio must be a number`);
+        return { costCentreId, ratio: target.ratio };
+    });
+}
+/** Same rules as parseMatch in src/cli/allocCmd.ts: known fields only, empty values are a wildcard. */
+function allocationMatch(value) {
+    const match = {};
+    if (value === undefined || value === null)
+        return match;
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw new Error('match must be an object');
+    for (const [key, field] of Object.entries(value)) {
+        if (!MATCH_FIELDS.includes(key))
+            throw new Error(`match.${key} is not a match field`);
+        if (typeof field !== 'string')
+            throw new Error(`match.${key} must be a string`);
+        if (field.trim())
+            match[key] = field.trim();
+    }
+    return match;
+}
+/**
+ * Allocation changes from the GUI: the same Store calls, validation and
+ * semantics as `segreant alloc`. Preview never writes; `run` with apply:true
+ * records the run. Demo mode refuses every write, and allows only the preview.
+ */
+export function handleAllocationWrite({ req, res, store }) {
+    void (async () => {
+        try {
+            const chunks = [];
+            let bytes = 0;
+            for await (const part of req) {
+                const chunk = part;
+                bytes += chunk.byteLength;
+                if (bytes > RESOURCE_LIMITS.dashboardRequestBytes) {
+                    req.resume();
+                    return json(res, 413, { error: 'allocation request exceeds bounded dashboard limit' });
+                }
+                chunks.push(chunk);
+            }
+            const raw = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+            if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+                throw new Error('allocation request must be an object');
+            const body = raw;
+            if (Object.keys(body).some((key) => !ALLOCATION_WRITE_FIELDS.has(key)))
+                throw new Error('allocation request has an unknown field');
+            if (typeof body.op !== 'string' || !ALLOCATION_WRITE_OPS.has(body.op))
+                throw new Error('op must be one of centre, archive, rule, revoke, run');
+            const op = body.op;
+            if (body.apply !== undefined && typeof body.apply !== 'boolean')
+                throw new Error('apply must be true or false');
+            const apply = body.apply === true;
+            // The one allocation request demo mode answers: a preview, which records nothing.
+            if (isDemo() && !(op === 'run' && !apply)) {
+                return json(res, 409, { error: new DemoWriteBlockedError('the allocation change').message });
+            }
+            if (op === 'centre') {
+                const costCentre = store.upsertCostCentre({
+                    costCentreId: allocationId(body.id),
+                    name: allocationText(body.name, 'name', 120),
+                    owner: allocationOptionalText(body.owner, 'owner'),
+                });
+                return json(res, 200, { ok: true, op, applied: true, message: `Cost centre "${costCentre.costCentreId}" saved.`, costCentre });
+            }
+            if (op === 'archive') {
+                const id = allocationId(body.id);
+                if (!store.archiveCostCentre(id))
+                    return json(res, 404, { error: `No open cost centre "${id}".` });
+                return json(res, 200, { ok: true, op, applied: true, message: `Archived "${id}". Past runs keep it; new spend will not reach it.` });
+            }
+            if (op === 'rule') {
+                const method = body.method;
+                if (typeof method !== 'string' || !ALLOCATION_METHODS.includes(method)) {
+                    throw new Error(`method must be one of ${ALLOCATION_METHODS.join(', ')}`);
+                }
+                const priority = body.priority === undefined ? 100 : body.priority;
+                if (typeof priority !== 'number' || !Number.isFinite(priority))
+                    throw new Error('priority must be a number');
+                const rule = store.saveAllocationRule({
+                    ruleId: allocationId(body.id),
+                    method: method,
+                    match: allocationMatch(body.match),
+                    targets: allocationTargets(body.targets),
+                    priority,
+                    // Default to the epoch so a first rule covers existing history, as the CLI does.
+                    effectiveFromMs: allocationTs(body.from, 'from') ?? 0,
+                    effectiveToMs: allocationTs(body.until, 'until'),
+                    revokedAtMs: null,
+                    owner: allocationOptionalText(body.owner, 'owner'),
+                    note: allocationOptionalText(body.note, 'note'),
+                });
+                const superseded = rule.version > 1
+                    ? ` v${rule.version - 1} closed at ${new Date(rule.effectiveFromMs).toISOString()} and retained — recorded runs are unchanged; new previews use effective dates.`
+                    : '';
+                return json(res, 200, { ok: true, op, applied: true, rule, message: `Rule "${rule.ruleId}" v${rule.version} (${rule.method}) saved.${superseded}` });
+            }
+            if (op === 'revoke') {
+                const id = allocationId(body.id);
+                const revoked = store.revokeAllocationRule(id);
+                if (revoked === 0)
+                    return json(res, 404, { error: `No open rule "${id}".` });
+                return json(res, 200, { ok: true, op, applied: true, revoked, message: `Revoked ${revoked} open version(s) of "${id}". Rows retained.` });
+            }
+            const from = allocationTs(body.from, 'from');
+            const to = allocationTs(body.to, 'to');
+            if (from === null || to === null)
+                throw new Error('from and to are required ISO dates or date-times');
+            if (to <= from)
+                throw new Error('to must be after from');
+            const result = store.allocatePeriod(from, to);
+            if (!result.conserves)
+                return json(res, 500, { error: 'Allocation did not conserve its input. Refusing to show or record it.' });
+            const allocationRunId = apply ? store.saveAllocationRun(result) : null;
+            return json(res, 200, {
+                ok: true,
+                op,
+                applied: apply,
+                allocationRunId,
+                message: apply ? 'Recorded as an immutable derived run.' : 'Not recorded. Apply to record this run.',
+                result,
+            });
+        }
+        catch (error) {
+            return json(res, 400, { error: error instanceof SyntaxError ? 'allocation request must contain valid JSON' : error instanceof Error ? error.message : String(error) });
+        }
+    })();
+}
+const BILLING_WRITE_FIELDS = new Set(['op', 'apply', 'fileName', 'contentBase64', 'materialityUsd', 'importId', 'accountRef', 'projectRef']);
+const BILLING_WRITE_OPS = new Set(['import', 'reconcile', 'adopt', 'scope', 'scope-clear']);
+/**
+ * Import content travels as the file's raw bytes in base64, never as decoded
+ * text. The CLI hashes the bytes on disk; a browser that sent `file.text()`
+ * would have the server hash a UTF-8 re-encoding instead, so the same export
+ * (a BOM, a non-UTF-8 byte) could get two digests and import twice, once per
+ * surface. Base64 makes the digest identical and bounds the body exactly: the
+ * import limit at 4/3, plus the envelope. The shared 16 KiB dashboard cap would
+ * refuse every realistic export.
+ */
+const BILLING_WRITE_BODY_BYTES = Math.ceil(MAX_BILLING_IMPORT_BYTES / 3) * 4 + 64 * 1024;
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+/** Serialize before the status line is written, so a payload that cannot be JSON-encoded fails as a 400 rather than a broken response. */
+function billingJson(res, status, payload) {
+    const text = stringifyJson(payload, 0);
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    res.end(text);
+}
+function billingText(value, label, max) {
+    if (typeof value !== 'string' || value.trim().length === 0 || value.length > max)
+        throw new Error(`${label} must be a non-empty string of at most ${max} characters`);
+    return value;
+}
+function billingOptionalText(value, label) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== 'string')
+        throw new Error(`${label} must be a string`);
+    return value;
+}
+/** Same reconciliation mapping as cmdReconcile in src/cli/billingCmd.ts. */
+function billingReconcile(store, body, apply) {
+    let materialityUsd;
+    if (body.materialityUsd !== undefined) {
+        if (typeof body.materialityUsd !== 'number' || body.materialityUsd < 0
+            || !Number.isSafeInteger(Math.round(body.materialityUsd * 1_000_000))) {
+            throw new Error('materialityUsd must be a non-negative dollar amount within the safe integer microdollar range');
+        }
+        materialityUsd = body.materialityUsd;
+    }
+    const readiness = reconciliationReadiness(store);
+    const notReady = {
+        status: 409,
+        payload: {
+            ok: false, op: 'reconcile', applied: false, status: 'not_ready', readiness,
+            message: 'Reconciliation is not possible yet. Complete the steps listed in readiness first.',
+            error: 'Reconciliation is not possible yet. Complete the steps listed in readiness first.',
+        },
+    };
+    if (!readiness.ready)
+        return notReady;
+    const result = store.reconcileOpenAiCosts({ materialityUsd });
+    if (!result)
+        return notReady;
+    if (result.status === 'refused') {
+        return {
+            status: 409,
+            payload: { ok: false, op: 'reconcile', applied: false, status: 'refused', refusal: result.refusal, detail: result.detail, error: result.detail, message: result.detail },
+        };
+    }
+    const reconciliationRunId = apply ? store.saveReconciliationRun(result) : null;
+    // A provider-day comparison crosses the kernel only after the immutable run is
+    // recorded. Local-only periods have no provider Evidence and stay a non-claim.
+    const kernel = apply && reconciliationRunId !== null && result.coverage.providerDays > 0
+        ? store.issueOpenAiReconciliationToKernel(reconciliationRunId)
+        : null;
+    return {
+        status: 200,
+        payload: {
+            ok: true,
+            op: 'reconcile',
+            applied: apply,
+            message: apply ? 'Recorded as an immutable derived run.' : 'Not recorded. Apply to record this run.',
+            reconciliationRunId,
+            result,
+            kernel,
+            fragility: assessAssumptionFragility([...result.conditions], reconciliationCountermodels(result)),
+        },
+    };
+}
+/** Same adoption preconditions and refusals as cmdAdoptCosts in src/cli/billingCmd.ts. */
+function billingAdopt(store, body, apply) {
+    const scope = store.activeOpenAiScope();
+    if (!scope || !scope.providerProjectRef) {
+        const error = 'Declare the route scope first, so the adopted lines are bound to a project: use op "scope" with accountRef and projectRef, then retry.';
+        return { status: 409, payload: { ok: false, op: 'adopt', applied: false, error, message: error } };
+    }
+    const imports = store.billingImportRuns(50).filter((r) => r.provider === 'openai');
+    if (imports.length === 0) {
+        const error = 'No OpenAI billing export has been imported. Import one first with op "import".';
+        return { status: 409, payload: { ok: false, op: 'adopt', applied: false, error, message: error } };
+    }
+    const importId = billingText(body.importId, 'importId', 200);
+    const plan = store.planOpenAiCostsAdoption({
+        importId,
+        declaredScopeId: scope.declarationId,
+        providerProjectRef: scope.providerProjectRef,
+    });
+    if (!plan.adoptable) {
+        const error = `Cannot adopt: ${plan.refusal.replaceAll('_', ' ')}. ${plan.detail}`;
+        return { status: 409, payload: { ok: false, op: 'adopt', applied: false, plan, error, message: error } };
+    }
+    const run = apply ? store.adoptOpenAiCostsFromImport(plan) : null;
+    return {
+        status: 200,
+        payload: {
+            ok: true,
+            op: 'adopt',
+            applied: apply,
+            observationRunId: run?.observationRunId ?? null,
+            plan,
+            networkAttempted: false,
+            credentialRead: false,
+            message: apply
+                ? 'Recorded as an immutable observation. Stamped operator_supplied_export; reconciliations built on it carry a fifth condition.'
+                : 'Not recorded. Apply to record this adoption.',
+        },
+    };
+}
+/**
+ * Same preview and effect as `billing scope clear` in src/cli/billingCmd.ts.
+ * Clearing ends the declaration for future proxy traffic only: requests
+ * already recorded keep the scope they were captured under, and recorded
+ * comparisons stay as they were.
+ */
+function billingScopeClear(store, apply) {
+    const active = store.activeOpenAiScope();
+    if (!apply) {
+        return {
+            status: 200,
+            payload: {
+                ok: true, op: 'scope-clear', applied: false, active,
+                message: active
+                    ? 'Not cleared. Clearing stops matching future OpenAI requests to this project. Requests already recorded and recorded comparisons are unchanged.'
+                    : 'No project is declared, so there is nothing to clear.',
+            },
+        };
+    }
+    const cleared = store.clearOpenAiScope();
+    return {
+        status: 200,
+        payload: {
+            ok: true, op: 'scope-clear', applied: true, cleared,
+            message: cleared
+                ? 'Cleared. Future OpenAI requests through Segreant are no longer matched to a project. Requests already recorded and recorded comparisons are unchanged.'
+                : 'No project was declared, so nothing changed.',
+        },
+    };
+}
+/** Same declaration, preview and refusal as `billing scope set` in src/cli/billingCmd.ts. */
+function billingScope(store, body, apply) {
+    const accountRef = billingText(body.accountRef, 'accountRef', 200);
+    const projectRef = billingOptionalText(body.projectRef, 'projectRef');
+    let upstreamBase;
+    let preview;
+    try {
+        upstreamBase = loadConfig().upstreams.openai;
+        preview = newOpenAiScopeDeclaration({ billingAccountRef: accountRef, providerProjectRef: projectRef, upstreamBase });
+    }
+    catch (error) {
+        throw new Error(`Billing scope failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!apply) {
+        return {
+            status: 200,
+            payload: {
+                ok: true,
+                op: 'scope',
+                applied: false,
+                message: 'No data written. Apply to declare this scope.',
+                scopePreview: {
+                    ...preview,
+                    capture: 'future OpenAI proxy rows only when the resolved configured endpoint exactly matches',
+                    trust: 'operator_declared_unverified',
+                    reconciliationStatus: 'not_reconciled',
+                },
+            },
+        };
+    }
+    const declaration = store.setOpenAiScope({ billingAccountRef: accountRef, providerProjectRef: projectRef, upstreamBase });
+    return {
+        status: 200,
+        payload: {
+            ok: true,
+            op: 'scope',
+            applied: true,
+            declaration,
+            reconciliationStatus: 'not_reconciled',
+            message: `Active local OpenAI scope ${declaration.declarationId} declared. Future matching proxy rows are declared_unverified; historical and imported rows are unchanged.`,
+        },
+    };
+}
+/**
+ * Billing evidence from the GUI: the same parsing, store calls and refusals as
+ * `segreant billing import|reconcile|openai-costs adopt|scope set`. Preview
+ * never writes; apply:true writes, and demo mode refuses every apply.
+ */
+export function handleBillingWrite({ req, res, store }) {
+    void (async () => {
+        try {
+            const chunks = [];
+            let bytes = 0;
+            for await (const part of req) {
+                const chunk = part;
+                bytes += chunk.byteLength;
+                if (bytes > BILLING_WRITE_BODY_BYTES) {
+                    req.resume();
+                    return billingJson(res, 413, { error: 'billing request exceeds bounded dashboard limit' });
+                }
+                chunks.push(chunk);
+            }
+            const raw = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+            if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+                throw new Error('billing request must be an object');
+            const body = raw;
+            if (Object.keys(body).some((key) => !BILLING_WRITE_FIELDS.has(key)))
+                throw new Error('billing request has an unknown field');
+            if (typeof body.op !== 'string' || !BILLING_WRITE_OPS.has(body.op))
+                throw new Error('op must be one of import, reconcile, adopt, scope, scope-clear');
+            const op = body.op;
+            if (body.apply !== undefined && typeof body.apply !== 'boolean')
+                throw new Error('apply must be true or false');
+            const apply = body.apply === true;
+            if (apply && isDemo()) {
+                return billingJson(res, 409, { error: new DemoWriteBlockedError('the billing change').message });
+            }
+            if (op === 'import') {
+                const fileName = billingText(body.fileName, 'fileName', 200);
+                if (fileName === '.' || fileName === '..' || posix.basename(fileName) !== fileName || win32.basename(fileName) !== fileName) {
+                    throw new Error('fileName must be an ordinary basename, without directories');
+                }
+                const encoded = billingText(body.contentBase64, 'contentBase64', BILLING_WRITE_BODY_BYTES);
+                if (encoded.length % 4 !== 0 || !BASE64.test(encoded))
+                    throw new Error('contentBase64 must be the file\'s bytes in standard base64');
+                // The file's own bytes are what is hashed, exactly as the CLI hashes the file on disk.
+                const parsed = parseBillingImportText(Buffer.from(encoded, 'base64'), fileName);
+                if (!apply) {
+                    return billingJson(res, 200, {
+                        ok: true, op, applied: false, preview: parsed.preview,
+                        message: 'Not recorded. Apply to import this file.',
+                    });
+                }
+                const result = store.applyBillingImport(parsed.input);
+                // Canonical kernel issue after the legacy compatibility write, as in the CLI.
+                const kernel = store.issueBillingImportToKernel(result.run.importId);
+                // BigInt coefficient converted to its canonical string form for the envelope only.
+                const kernelJson = { ...kernel, total: { ...moneyToJson(kernel.total) } };
+                const message = result.duplicateFile
+                    ? `Identical billing evidence was already imported as ${result.run.importId}; no duplicate provider records written.`
+                    : `Imported ${result.run.recordsInserted} provider-declared charge line(s); ${result.run.recordsDuplicate} already existed. Status remains not_reconciled. Provider-reported totals are stored separately from local metered estimates.`;
+                return billingJson(res, 200, {
+                    ok: true, op, applied: true, message, preview: parsed.preview,
+                    duplicateFile: result.duplicateFile, run: result.run, kernel: kernelJson,
+                });
+            }
+            const outcome = op === 'reconcile' ? billingReconcile(store, body, apply)
+                : op === 'adopt' ? billingAdopt(store, body, apply)
+                    : op === 'scope-clear' ? billingScopeClear(store, apply)
+                        : billingScope(store, body, apply);
+            return billingJson(res, outcome.status, outcome.payload);
+        }
+        catch (error) {
+            return billingJson(res, 400, { error: error instanceof SyntaxError ? 'billing request must contain valid JSON' : error instanceof Error ? error.message : String(error) });
+        }
+    })();
+}
 /** Same local-only POST guard as other mutations. A POST with apply:false is
  * the preview; only a second deliberate POST with apply:true appends evidence. */
 export function handleOutcomeRecord({ req, res, store, config }) {
@@ -1071,6 +1921,14 @@ export function handleSettingsUpdate({ req, res, store, config, version, configP
             if (err instanceof SyntaxError) {
                 return json(res, 400, { error: { code: 'SETTINGS_INVALID_JSON', message: 'settings request body must be valid JSON' } });
             }
+            if (err instanceof DemoReadOnlyError || (err instanceof Error && err.name === 'DemoReadOnlyError')) {
+                return json(res, 409, {
+                    error: {
+                        code: 'SETTINGS_DEMO_READ_ONLY',
+                        message: "This dashboard is showing sample data, so settings can't be changed here. Start Segreant without --demo to change your own settings.",
+                    },
+                });
+            }
             return json(res, 500, { error: { code: 'SETTINGS_UPDATE_FAILED', message: 'settings could not be persisted' } });
         }
     })();
@@ -1110,10 +1968,20 @@ export const ROUTES = [
     // POST carries the CSRF gate.
     apiRoute('scan', handleScan),
     apiRoute('overview', handleOverview),
+    apiRoute('sessions', handleSessions),
     apiRoute('billing', handleBilling),
+    apiRoute('statement', handleStatement),
+    apiRoute('statement-csv', handleStatementCsv),
     apiRoute('allocation', handleAllocation),
+    apiRoute('allocation-write', handleAllocationWrite),
+    apiRoute('allocation-run-csv', handleAllocationRunCsv),
+    apiRoute('billing-write', handleBillingWrite),
     apiRoute('economic', handleEconomic),
     apiRoute('pricing', handlePricing),
+    apiRoute('pricing-unknown', handlePricingUnknown),
+    apiRoute('pricing-declare', handlePricingDeclare),
+    apiRoute('pricing-unset', handlePricingUnset),
+    apiRoute('reprice', handleReprice),
     apiRoute('export-csv', handleExportCsv),
     apiRoute('realization', handleRealization),
     apiRoute('guide', handleGuide),