segreant 0.0.0-stage → 0.2.0

package/bin/runtime-snapshot.mjs

@@ -0,0 +1,266 @@
+// Immutable copy of the compiled runtime, used by the CLI launcher.
+//
+// The launcher has to release the publication gate as soon as the copy exists —
+// holding it for the length of a command would starve every queued build — but
+// the command it launched can go on resolving modules and reading bundled
+// resources long after that. `segreant start` is the case that decides the shape
+// of this module: it resolves its command promise the moment the proxy and
+// dashboard sockets are listening, then serves for hours, and the dashboard
+// reads the bundled pricing card per REQUEST rather than at import.
+//
+// So the snapshot's correctness condition is a lifetime, not a completion. It
+// must outlive every process that imported it.
+//
+// The copy is keyed by a hash of its contents and shared by every launch of the
+// same build. A fresh copy per process was correct but slow: on Windows the
+// first open of each newly written module file costs about a second across the
+// module graph, on every command. A content-keyed copy is never modified after
+// it is complete, so sharing it cannot hand a process a half-published build: a
+// new build hashes differently and gets its own directory.
+//
+// Each process holds a lease file inside the snapshot while it runs. Shared
+// snapshots are created, leased and reaped only under one machine-wide
+// snapshot lock. The package's own publication lock is not enough: two package
+// roots with identical builds (a checkout and a copy of it) hash to the same
+// snapshot but hold different publication locks, and a reaper in one could
+// remove the snapshot another had just created and not yet leased. A snapshot
+// is reaped when no live process leases it, it is not the current build's, and
+// nothing has leased it for SHARED_IDLE_MS. A process killed mid-copy leaves an owner-stamped private
+// directory that a later launcher reaps once its owner is demonstrably dead —
+// never by pathname, which could delete a running server's module tree.
+import { createHash } from 'node:crypto';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { acquirePublicationLock, LOCK_STALE_MS, processIsAlive } from './publication-lock.mjs';
+
+export const SNAPSHOT_PREFIX = 'segreant-runtime-';
+export const SHARED_SNAPSHOT_PREFIX = `${SNAPSHOT_PREFIX}build-`;
+export const SNAPSHOT_OWNER_FILE = 'owner.json';
+export const SNAPSHOT_COMPLETE_FILE = 'complete.json';
+export const SNAPSHOT_LEASE_DIR = 'leases';
+// Deliberately outside SNAPSHOT_PREFIX, so the orphan reaper never touches it.
+export const SNAPSHOT_LOCK_DIR = 'segreant-snapshot-lock';
+// An unleased snapshot of another build survives this long after its last
+// lease, so two checkouts used alternately do not re-copy on every command.
+export const SHARED_IDLE_MS = 10 * 60_000;
+
+// The compiled runtime resolves these relative to the PACKAGE root rather than
+// to its own module: the bundled pricing card, the Lift baselines, the public
+// market snapshot, and the package version. A snapshot without them is not behaviourally equivalent to
+// the checked-out or installed layout, and the difference only surfaces at the
+// first request that needs one.
+const ROOT_RESOURCES = ['pricing', 'baselines', 'market', 'package.json'];
+
+const REMOVE_OPTIONS = { recursive: true, force: true, maxRetries: 20, retryDelay: 25 };
+
+function removeTree(path) {
+  try {
+    rmSync(path, REMOVE_OPTIONS);
+    return true;
+  } catch {
+    // Windows antivirus/indexer handles can briefly hold a just-copied file.
+    // A surviving snapshot is temp-directory residue that the reaper collects
+    // on a later run; it must never turn a completed command into a failure.
+    return false;
+  }
+}
+
+function readSnapshotOwner(path) {
+  try {
+    const owner = JSON.parse(readFileSync(join(path, SNAPSHOT_OWNER_FILE), 'utf8'));
+    if (!owner || typeof owner !== 'object') return null;
+    if (!Number.isInteger(owner.pid) || owner.pid <= 0) return null;
+    return { pid: owner.pid };
+  } catch {
+    return null;
+  }
+}
+
+/** Content hash of everything a snapshot copies, in a stable order. */
+export function runtimeKey(packageRoot) {
+  const hash = createHash('sha256');
+  const walk = (dir, rel) => {
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      const name = `${rel}/${entry.name}`;
+      if (entry.isDirectory()) walk(path, name);
+      else {
+        hash.update(`${name}\0`);
+        hash.update(readFileSync(path));
+        hash.update('\0');
+      }
+    }
+  };
+  for (const resource of ['dist', ...ROOT_RESOURCES]) {
+    const path = join(packageRoot, resource);
+    if (!existsSync(path)) continue;
+    if (statSync(path).isDirectory()) walk(path, resource);
+    else {
+      hash.update(`${resource}\0`);
+      hash.update(readFileSync(path));
+      hash.update('\0');
+    }
+  }
+  return hash.digest('hex').slice(0, 32);
+}
+
+function liveLeases(path) {
+  let names;
+  try {
+    names = readdirSync(join(path, SNAPSHOT_LEASE_DIR));
+  } catch {
+    return 0;
+  }
+  let live = 0;
+  for (const name of names) {
+    const pid = Number(name.replace(/\.json$/, ''));
+    if (processIsAlive(pid)) live++;
+    else rmSync(join(path, SNAPSHOT_LEASE_DIR, name), { force: true });
+  }
+  return live;
+}
+
+/** Time since the snapshot was last leased (its completion marker is touched on every lease). */
+function idleFor(path) {
+  for (const candidate of [join(path, SNAPSHOT_COMPLETE_FILE), path]) {
+    try {
+      return Date.now() - statSync(candidate).mtimeMs;
+    } catch {
+      // Try the directory itself.
+    }
+  }
+  return Infinity;
+}
+
+/**
+ * Remove snapshots left behind by processes that are gone.
+ *
+ * Liveness, not age, is the primary test: a `segreant start` can legitimately own
+ * its snapshot for days, so an age-only reaper would delete a live server's
+ * runtime. Age only decides for a directory with no readable owner record,
+ * which can exist solely in the sliver between `mkdtemp` and the owner write.
+ *
+ * Shared build snapshots are reaped only when `currentKey` is given, which
+ * createRuntimeSnapshot does while holding the machine-wide snapshot lock: then
+ * no launcher, from any package root, can be between creating or leasing a
+ * snapshot and recording its lease.
+ */
+export function reapOrphanRuntimeSnapshots(parent = tmpdir(), currentKey = null) {
+  let entries;
+  try {
+    entries = readdirSync(parent, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith(SNAPSHOT_PREFIX)) continue;
+    const path = join(parent, entry.name);
+    if (entry.name.startsWith(SHARED_SNAPSHOT_PREFIX)) {
+      if (currentKey === null || entry.name === `${SHARED_SNAPSHOT_PREFIX}${currentKey}`) continue;
+      if (liveLeases(path) === 0 && idleFor(path) > SHARED_IDLE_MS) removeTree(path);
+      continue;
+    }
+    const owner = readSnapshotOwner(path);
+    if (owner) {
+      if (!processIsAlive(owner.pid)) removeTree(path);
+      continue;
+    }
+    try {
+      if (Date.now() - statSync(path).mtimeMs > LOCK_STALE_MS) removeTree(path);
+    } catch {
+      // A concurrent reaper won, or the directory vanished. Nothing to do.
+    }
+  }
+}
+
+function copyRuntime(packageRoot, root) {
+  cpSync(join(packageRoot, 'dist'), join(root, 'dist'), { recursive: true, force: true, errorOnExist: false });
+  for (const resource of ROOT_RESOURCES) {
+    const source = join(packageRoot, resource);
+    if (existsSync(source)) {
+      cpSync(source, join(root, resource), { recursive: true, force: true, errorOnExist: false });
+    }
+  }
+}
+
+/**
+ * Lease the shared snapshot of the current build, creating it if needed.
+ *
+ * Call this while the package's publication lock is held: that makes the copy
+ * independent of a concurrent build. It takes the machine-wide snapshot lock
+ * itself, which keeps every reaper, from any package root, from removing a
+ * snapshot between its creation or lease and the recorded lease. The returned `dispose`
+ * releases the lease; it is idempotent and safe to register on process exit.
+ */
+export function createRuntimeSnapshot(packageRoot, parent = tmpdir()) {
+  const key = runtimeKey(packageRoot);
+  const lockRoot = join(parent, SNAPSHOT_LOCK_DIR);
+  mkdirSync(lockRoot, { recursive: true });
+  const release = acquirePublicationLock(lockRoot);
+  try {
+    return leaseSharedSnapshot(packageRoot, parent, key);
+  } finally {
+    release?.();
+  }
+}
+
+function leaseSharedSnapshot(packageRoot, parent, key) {
+  const root = join(parent, `${SHARED_SNAPSHOT_PREFIX}${key}`);
+  if (!existsSync(join(root, SNAPSHOT_COMPLETE_FILE))) {
+    // An incomplete shared directory can only be residue of a failed rename.
+    if (existsSync(root)) removeTree(root);
+    const staging = mkdtempSync(join(parent, SNAPSHOT_PREFIX));
+    try {
+      // Stamp ownership before the expensive copy, so an interrupted creation is
+      // still reapable by liveness rather than having to age out.
+      writeFileSync(join(staging, SNAPSHOT_OWNER_FILE), JSON.stringify({ pid: process.pid }), 'utf8');
+      copyRuntime(packageRoot, staging);
+      writeFileSync(join(staging, SNAPSHOT_COMPLETE_FILE), JSON.stringify({ key }), 'utf8');
+      rmSync(join(staging, SNAPSHOT_OWNER_FILE), { force: true });
+      renameSync(staging, root);
+    } catch (error) {
+      removeTree(staging);
+      throw error;
+    }
+  }
+  const lease = join(root, SNAPSHOT_LEASE_DIR, `${process.pid}.json`);
+  mkdirSync(join(root, SNAPSHOT_LEASE_DIR), { recursive: true });
+  writeFileSync(lease, JSON.stringify({ pid: process.pid }), 'utf8');
+  const now = new Date();
+  try {
+    utimesSync(join(root, SNAPSHOT_COMPLETE_FILE), now, now);
+  } catch {
+    // The idle clock is advisory; a live lease is what protects the tree.
+  }
+  reapOrphanRuntimeSnapshots(parent, key);
+
+  let disposed = false;
+  return {
+    root,
+    key,
+    entry: join(root, 'dist', 'cli.js'),
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      try {
+        rmSync(lease, { force: true });
+      } catch {
+        // A lease left behind names a dead pid; the next reaper discards it.
+      }
+    },
+  };
+}

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

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Thin launcher for the compiled runtime. Shipping JavaScript is intentional:
+// Node does not permit TypeScript type stripping for files in node_modules.
+//
+// Node emits the "SQLite is an experimental feature" warning from an internal
+// 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 { spawn } from 'node:child_process';
+import { acquirePublicationLock } from './publication-lock.mjs';
+import { createRuntimeSnapshot, reapOrphanRuntimeSnapshots } from './runtime-snapshot.mjs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+
+// Fail fast with a human message on too-old Node before Node's SQLite runtime
+// dependency reports a less actionable error.
+const major = Number(process.versions.node.split('.')[0]);
+if (major < 24) {
+  console.error(
+    `Segreant needs Node >= 24 (you have ${process.versions.node}).\n` +
+    `The packaged runtime targets Node 24 or newer.\n` +
+    `Upgrade Node from https://nodejs.org/ and re-run.`,
+  );
+  process.exit(1);
+}
+
+const self = fileURLToPath(import.meta.url);
+
+if (!process.env.__SEGREANT_CHILD) {
+  // 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' } },
+  );
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => { if (child.exitCode === null && child.signalCode === null) child.kill(signal); });
+  }
+  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,
+  // so a killed `segreant start` cannot make temp grow without bound.
+  reapOrphanRuntimeSnapshots();
+
+  // The launcher participates in the same exclusive gate as publication.
+  // Acquiring (rather than merely checking) the lock closes the race where a
+  // build starts immediately after a reader's old existsSync check. Lock
+  // failure is intentionally fatal: bypassing it would make a reader's artifact
+  // guarantee depend on an unverified filesystem assumption.
+  const release = acquirePublicationLock(join(here, '..'));
+  let snapshot;
+  try {
+    // Lease (and, for a new build, copy) while the publisher is excluded. Once
+    // the lock is released all module resolution and resource reading happens
+    // inside this immutable, content-keyed tree,
+    // so no later build can replace a dependency half-way through the import
+    // graph — or half-way through a request served hours later.
+    snapshot = createRuntimeSnapshot(join(here, '..'));
+  } finally {
+    release?.();
+  }
+
+  // Registered before the import so a failed import still releases the lease.
+  // The lease has to outlive the imported runtime, not merely the promise that
+  // runtime resolves when its deferred command work settles: `segreant start`
+  // settles that promise as soon as its sockets are listening and then serves
+  // for hours. Process exit is the only point at which no copied module or
+  // resource can still be needed.
+  process.on('exit', snapshot.dispose);
+
+  // Direct imports of dist/* and tools such as npm pack do not participate in
+  // this gate; the atomic reader guarantee is intentionally limited to the
+  // supported bin launcher and the build protocol.
+  const runtime = await import(pathToFileURL(snapshot.entry).href);
+  // The production CLI schedules dispatch with setImmediate so the launcher can
+  // release the publication lock before command work begins. Awaiting the
+  // completion promise keeps the launcher's own frame alive for the whole of a
+  // short command; it is no longer what decides when the snapshot dies.
+  if (runtime.cliCompletion && typeof runtime.cliCompletion.then === 'function') {
+    await runtime.cliCompletion;
+  }
+}

package/dist/alerts/detect.js

@@ -0,0 +1,245 @@
+/**
+ * Proactive governance — turning passive measurement into alerts.
+ *
+ * A spend-governance tool that only blocks (silently) is half a product: the
+ * user finds out something went wrong by noticing their agent stalled, or by
+ * reading a dashboard they happened to open. This detects the conditions worth
+ * surfacing — budget pressure, spend spikes, runaway loops, throttling, value
+ * craters, untrustworthy pricing — from data already on the device. No external
+ * services, no notifications leaving the machine.
+ *
+ * `detectAlerts` is pure over precomputed inputs (testable without a store);
+ * `computeAlerts` is the store-backed wrapper the CLI and dashboard call.
+ */
+import { startOfLocalDay } from '../budget/guard.js';
+const SEVERITY_ORDER = { critical: 0, warn: 1, info: 2 };
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const pos = (sorted.length - 1) * p;
+    const lo = Math.floor(pos);
+    const hi = Math.ceil(pos);
+    if (lo === hi)
+        return sorted[lo];
+    return sorted[lo] + (pos - lo) * (sorted[hi] - sorted[lo]);
+}
+function fmt(n) {
+    return n >= 1 ? n.toFixed(2) : n.toFixed(4);
+}
+export function alertCoverage(inp) {
+    const capConfigured = inp.dailyCapUsd !== null || inp.dailySoftUsd !== null;
+    // A request can only be blocked by something that blocks. A soft threshold
+    // warns and does not, so it does not light this channel.
+    const blockingConfigured = inp.dailyCapUsd !== null || inp.runaway !== null;
+    const baseline = percentile([...inp.baselineActiveDaySpends].sort((a, b) => a - b), 0.9);
+    const channels = [
+        {
+            channel: 'budget-cap',
+            live: capConfigured,
+            darkBecause: capConfigured ? null : 'no daily cap or soft threshold is set, so no budget alert can fire',
+        },
+        {
+            channel: 'runaway-loop',
+            live: inp.runaway !== null,
+            darkBecause: inp.runaway !== null ? null : 'no runaway velocity threshold is set, so no burst can trip it',
+        },
+        {
+            channel: 'throttling',
+            live: blockingConfigured,
+            darkBecause: blockingConfigured ? null : 'nothing is configured that would block a request, so none can be observed blocked',
+        },
+        {
+            channel: 'spend-spike',
+            live: baseline > 0,
+            // "yet" is a claim about the operator's history, and it is false on a
+            // ledger whose prior days Segreant deleted on their own retention policy
+            // (D-182). This is the surface whose whole job is to give the reason a
+            // channel is dark, so giving the wrong one here is worse than anywhere.
+            darkBecause: baseline > 0
+                ? null
+                : inp.baselineTruncated === true
+                    ? 'the prior active days in this window were deleted by retention, so no baseline survives to compare against'
+                    : 'no prior active day exists yet, so there is no baseline to exceed',
+        },
+        {
+            channel: 'value-crater',
+            live: inp.realizedSpendShare !== null,
+            darkBecause: inp.realizedSpendShare !== null ? null : 'realized value is uninstrumented, so no realization share exists to fall',
+        },
+        {
+            channel: 'pricing-trust',
+            live: (inp.pricedWindowSpendUsd ?? 0) > 0,
+            darkBecause: (inp.pricedWindowSpendUsd ?? 0) > 0
+                ? null
+                : 'no priced spend in the window, so an estimated share of zero reflects absent spend rather than verified pricing',
+        },
+    ];
+    const liveChannels = channels.filter((channel) => channel.live).length;
+    const total = channels.length;
+    const summary = liveChannels === total
+        ? `${liveChannels} of ${total} alert channels are watching`
+        : `${liveChannels} of ${total} alert channels are watching; the rest cannot fire as configured`;
+    return Object.freeze({
+        channels: Object.freeze(channels),
+        liveChannels,
+        complete: liveChannels === total,
+        summary,
+    });
+}
+export function detectAlerts(inp) {
+    const out = [];
+    // Budget pressure — critical once the hard cap is reached (requests now blocked).
+    const basisNote = inp.capExcludesImported ? ' The cap counts live proxy spend only; imported subscription spend is excluded.' : '';
+    if (inp.dailyCapUsd !== null && inp.todaySpendUsd >= inp.dailyCapUsd) {
+        out.push({
+            id: 'budget-exhausted',
+            severity: 'critical',
+            title: 'Daily budget reached',
+            detail: 'New requests are being blocked until the daily cap resets.' + basisNote,
+            metric: `$${fmt(inp.todaySpendUsd)} / $${fmt(inp.dailyCapUsd)}`,
+        });
+    }
+    else if (inp.dailySoftUsd !== null && inp.todaySpendUsd >= inp.dailySoftUsd) {
+        out.push({
+            id: 'budget-soft',
+            severity: 'warn',
+            title: 'Approaching daily cap',
+            detail: 'Spend has crossed the soft-warn threshold for today.' + basisNote,
+            metric: `$${fmt(inp.todaySpendUsd)} / $${fmt(inp.dailySoftUsd)} soft`,
+        });
+    }
+    // Runaway loop — a burst of spend in a short window.
+    if (inp.runaway && inp.runaway.tripped) {
+        out.push({
+            id: 'runaway',
+            severity: 'critical',
+            title: 'Runaway velocity',
+            detail: `A burst of spend in the last ${inp.runaway.windowSec}s tripped the runaway guard — check for a stuck agent loop.`,
+            metric: `$${fmt(inp.runaway.windowCostUsd)} in ${inp.runaway.windowSec}s`,
+        });
+    }
+    // Spend spike — today is well above the typical active day. Compared on TOTAL
+    // spend, because the baseline series is total (like-for-like regardless of basis).
+    const todayTotal = inp.todayTotalSpendUsd ?? inp.todaySpendUsd;
+    const base = percentile([...inp.baselineActiveDaySpends].sort((a, b) => a - b), 0.9);
+    if (base > 0 && todayTotal >= 0.01 && todayTotal > base * 2) {
+        out.push({
+            id: 'spend-spike',
+            severity: 'warn',
+            title: 'Spend spike',
+            // The alert still FIRES on a narrowed baseline, deliberately (D-173's
+            // rule, D-182's application): withholding a live overspend signal because
+            // a privacy setting shortened its comparison would withdraw the whole
+            // claim to repair half of it. What deletion undermines is the baseline's
+            // claim to represent a typical month, not the observation that today is
+            // far above what survives -- so the alert fires and the comparison says
+            // what it was computed over. No direction is asserted: deleting the
+            // oldest days can move a p90 either way.
+            detail: inp.baselineTruncated === true
+                ? `Today is well above the days that survive in this window — but retention deleted part of the comparison period, so this is not a month's typical. Compared against ${inp.baselineActiveDaySpends.length} surviving active day(s).`
+                : 'Today is well above your typical active day — worth a look before it compounds.',
+            metric: `${(todayTotal / base).toFixed(1)}× your p90 day ($${fmt(base)})`,
+        });
+    }
+    // Throttling — the user's agent is being blocked and may not realize it.
+    if (inp.blocked24h > 0) {
+        out.push({
+            id: 'throttled',
+            severity: 'warn',
+            title: 'Requests blocked by budget',
+            detail: 'Your agent is being throttled. Raise the cap or investigate what is driving the spend.',
+            metric: `${inp.blocked24h} blocked in 24h`,
+        });
+    }
+    // Value crater — spend isn't converting into kept outcomes (only when instrumented).
+    if (inp.realizedSpendShare !== null && inp.realizedSpendShare < 0.3) {
+        out.push({
+            id: 'value-crater',
+            severity: 'warn',
+            title: 'Low realized value',
+            detail: 'Most recent spend is not turning into kept, verified outcomes. Check the frontier for where it is leaking.',
+            metric: `${Math.round(inp.realizedSpendShare * 100)}% realized`,
+        });
+    }
+    // Data quality — a chunk of spend used estimated (unverified) pricing.
+    if (inp.estimatedShare > 0.2) {
+        out.push({
+            id: 'estimated-pricing',
+            severity: 'info',
+            title: 'Costs are approximate',
+            detail: 'Some spend used estimated pricing (an unrecognized model). Re-verify pricing/models.json before billing-grade use.',
+            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. */
+function gatherAlertInputs(store, config, opts) {
+    const now = opts.now ?? Date.now();
+    const day = 24 * 60 * 60 * 1000;
+    const dayStart = startOfLocalDay(now);
+    // Cap-related alerts must read the same basis the guard ENFORCES on, or the
+    // dashboard would warn about a block that will never happen (or miss one that will).
+    const liveOnly = !config.budget.capIncludesImported;
+    const todaySpendUsd = store.spendBetween(dayStart, now + 1000, liveOnly);
+    // Baseline = prior active days (exclude today), so a spike compares like-for-like.
+    const baselineStartMs = now - 30 * day;
+    const priorSeries = store.series(baselineStartMs, dayStart, day);
+    const baselineActiveDaySpends = priorSeries.map((s) => s.costUsd).filter((x) => x > 0);
+    // Same predicate as every other window in this sweep: truncated when the
+    // window STARTS strictly before a recorded boundary, because `prune` deletes
+    // rows strictly older than it. Null is no prune on record (D-170).
+    const baselinePrunedBeforeMs = store.retentionFloor().requestsPrunedBeforeMs;
+    const baselineTruncated = baselinePrunedBeforeMs !== null && baselineStartMs < baselinePrunedBeforeMs;
+    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;
+    let runaway = null;
+    if (config.budget.runawayMaxUsd !== null) {
+        const w = store.spendInWindow(now, config.budget.runawayWindowSec * 1000, liveOnly);
+        runaway = {
+            tripped: w.costUsd >= config.budget.runawayMaxUsd,
+            windowCostUsd: w.costUsd,
+            windowSec: config.budget.runawayWindowSec,
+        };
+    }
+    return Object.freeze({
+        todaySpendUsd,
+        todayTotalSpendUsd: liveOnly ? store.spendBetween(dayStart, now + 1000) : todaySpendUsd,
+        capExcludesImported: liveOnly,
+        dailyCapUsd: config.budget.dailyUsd,
+        dailySoftUsd: config.budget.dailySoftUsd,
+        baselineActiveDaySpends,
+        baselineTruncated,
+        baselinePrunedBeforeMs,
+        blocked24h,
+        estimatedShare,
+        declaredShare,
+        pricedWindowSpendUsd,
+        runaway,
+        realizedSpendShare: opts.realizedSpendShare ?? null,
+    });
+}
+/** Gather alert inputs from the store + config and detect. `realizedSpendShare` is passed in (git-gated). */
+export function computeAlerts(store, config, opts = {}) {
+    return detectAlerts(gatherAlertInputs(store, config, opts));
+}
+/** The same inputs `computeAlerts` gathers, read for coverage rather than for alerts. */
+export function computeAlertCoverage(store, config, opts = {}) {
+    return alertCoverage(gatherAlertInputs(store, config, opts));
+}