segreant 0.1.0 → 0.2.0

package/dist/proxy/server.js

@@ -21,13 +21,17 @@
  *    history refuses the outbound request before DNS/dial.
  */
 import http from 'node:http';
+import { statSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
+import { configPath, loadConfig } from '../config.js';
 import { BudgetGuard, unverifiedBasis } from '../budget/guard.js';
-import { computeCost, unpricedPricingEvidence } from '../cost/pricing.js';
+import { computeCost, withDeclarations, unpricedPricingEvidence, notSentPricingEvidence } from '../cost/pricing.js';
+import { activePriceOverrides, PriceOverridesError } from '../cost/overrides.js';
 import { StreamUsageAccumulator, normalizeAnthropicUsage, normalizeOpenAIUsage, emptyUsage, } from './usage.js';
 import { extractProposalsWithCoverage } from '../value/proposals.js';
 import { StreamProposalAccumulator } from './stream-proposals.js';
 import { EgressError, egressFetchWithConfig } from '../egress/transport.js';
+import { providerRuleCommand } from '../egress/policy.js';
 import { readBoundedResponseText, RESOURCE_LIMITS, ResourceLimitError } from '../util/resource-limits.js';
 const HOP_BY_HOP = new Set([
     'connection',
@@ -231,10 +235,21 @@ function providerBudgetUnavailableBody(provider, message) {
     }
     return JSON.stringify({ error: { message, type: 'segreant_budget_unavailable', code: 'budget_enforcement_unavailable' } });
 }
-function providerEgressRefusalBody(provider, error) {
+export function providerEgressRefusalBody(provider, error, targetUrl, method, egressMode) {
+    // Only the providers' official APIs are built in; a gateway or a self-hosted
+    // model is allowed by name, with the one command the refusal prints. A
+    // malformed egress section refuses everything, built-ins included, and its
+    // repair is the file, not a rule: printing a rule there called
+    // api.openai.com "not a built-in provider API" (independent review, 2026-10-18).
+    const invalid = egressMode === 'invalid';
+    const allow = error.code === 'policy_denied' && !invalid ? providerRuleCommand(targetUrl, method) : null;
     const repair = error.code === 'receipt_integrity_failed' || error.code === 'receipt_persistence_failed'
         ? ' Repair or restore the local receipt history before retrying.'
-        : '';
+        : invalid
+            ? ' The egress section of config.json is malformed, so every cloud request is refused. Fix it by hand, or reset it with: segreant egress apply --apply --mode local_locked'
+            : allow
+                ? ` ${new URL(targetUrl).origin} is not one of the built-in provider APIs. To send your requests there, run: ${allow}`
+                : '';
     const message = `Segreant refused this outbound request at its egress boundary: ${error.message}.${repair}`;
     if (provider === 'anthropic') {
         return JSON.stringify({ type: 'error', error: { type: 'segreant_egress_refusal', code: 'egress_refused', subcode: error.code, message } });
@@ -266,12 +281,94 @@ function waitForDrainOrClose(res) {
         res.once('close', onClose);
     });
 }
+/**
+ * The budget the running proxy enforces, kept in step with config.json.
+ *
+ * Dashboard Settings mutates the shared config object in place, but
+ * `segreant budget --daily N` and a hand edit write the FILE from another
+ * process. Before this, a cap set from the terminal was printed as "Budget
+ * updated" and not enforced until a restart (verified 2026-10-17: two requests
+ * over a $0.05 cap went through), and an invalid budget written while running
+ * kept forwarding. The file is checked at most every `intervalMs`; a changed
+ * file is re-read and validated, and only its budget is taken (ports and
+ * upstreams still need a restart). An unreadable or invalid file THROWS, which
+ * the pre-flight check turns into a fail-closed 503, and is retried at the next
+ * check rather than cached, so a half-written file does not stick. A missing
+ * file keeps the budget in force: deleting config.json never lifts a cap.
+ */
+/**
+ * The persisted budget could not be read or validated. Requests fail closed
+ * while it lasts, but unlike a ledger failure it is not latched: repairing
+ * config.json resumes enforcement without a restart.
+ */
+export class BudgetConfigUnavailable extends Error {
+    constructor(cause) {
+        super(`budget configuration unavailable: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.name = 'BudgetConfigUnavailable';
+    }
+}
+export function liveBudget(config, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 500;
+    const path = opts.path ?? configPath;
+    const load = opts.load ?? loadConfig;
+    let checkedAt = -Infinity;
+    // No mtime is recorded up front: the file may have changed between the
+    // caller's loadConfig() and this point (start awaits a pricing refresh), so
+    // the first check always re-reads what is on disk now (PR #133 review).
+    let seenMtimeMs = null;
+    let failure = null;
+    return () => {
+        const now = Date.now();
+        if (now - checkedAt >= intervalMs) {
+            checkedAt = now;
+            let mtimeMs = null;
+            try {
+                mtimeMs = statSync(path()).mtimeMs;
+            }
+            catch (error) {
+                // Only a missing file is a deletion, which keeps the cap in force.
+                // Any other stat failure (permissions, I/O) means the persisted
+                // budget cannot be verified, and that fails closed.
+                if (error?.code !== 'ENOENT')
+                    failure = new BudgetConfigUnavailable(error);
+                else {
+                    // Deleting the file is the documented way back to defaults, so the
+                    // egress policy returns to its default too: a gateway allowed by a
+                    // rule in the deleted file is refused on the next request, not at
+                    // the next restart (PR #148 review). The built-in provider routes
+                    // hold in the default. A file written again is re-read in full.
+                    config.egress = { mode: 'local_locked', rules: [] };
+                    seenMtimeMs = null;
+                }
+            }
+            if (mtimeMs !== null && (mtimeMs !== seenMtimeMs || failure !== null)) {
+                try {
+                    const fresh = load();
+                    config.budget = fresh.budget;
+                    // The egress rules follow the file the same way: a rule added with
+                    // `segreant egress apply` (the command a refusal prints) governs the
+                    // next request, with no restart, and so does a tightening (PR #148
+                    // review). An invalid file throws above and fails closed.
+                    config.egress = fresh.egress;
+                    seenMtimeMs = mtimeMs;
+                    failure = null;
+                }
+                catch (error) {
+                    failure = new BudgetConfigUnavailable(error);
+                }
+            }
+        }
+        if (failure !== null)
+            throw failure;
+        return config.budget;
+    };
+}
 export function createProxyServer(deps) {
     const { store, config } = deps;
-    // Dashboard Settings mutates the shared config object after persisting it.
     // Resolve budget at each pre-flight check so a newly chosen cap actually
-    // governs the already-running proxy, rather than merely looking saved in UI.
-    const guard = new BudgetGuard(store, () => config.budget);
+    // governs the already-running proxy, whether it was saved from Settings (the
+    // shared object) or from the CLI or an editor (the file; see liveBudget).
+    const guard = new BudgetGuard(store, deps.budget ?? liveBudget(config));
     const state = { accountingFailure: false };
     const server = http.createServer((req, res) => {
         handle(req, res, deps, guard, state).catch((err) => {
@@ -396,12 +493,25 @@ async function handle(req, res, deps, guard, state) {
     // --- Budget pre-flight ---
     let decision;
     let budgetFailure = false;
+    let declarations = Object.create(null);
     try {
+        // Declared prices are read before anything is sent: a hand-edited
+        // overrides.json that no longer parses would otherwise throw only when the
+        // answer is priced, after the provider had charged for it, leaving the
+        // request out of the ledger and the cap (PR #146 review). Like a broken
+        // config.json it does not latch: repairing the file resumes forwarding.
+        // The request is later priced from exactly these declarations, so an edit
+        // that breaks the file while it is in flight cannot stop its accounting
+        // after the provider has answered (PR #146 review).
+        declarations = activePriceOverrides();
         decision = guard.evaluate({ sessionId });
     }
-    catch {
+    catch (error) {
         budgetFailure = true;
-        state.accountingFailure = true;
+        // A ledger or accounting failure latches; an unreadable or invalid
+        // config.json or price-overrides file does not, so repairing it resumes enforcement.
+        if (!(error instanceof BudgetConfigUnavailable) && !(error instanceof PriceOverridesError))
+            state.accountingFailure = true;
         decision = {
             action: 'block',
             reason: 'budget_enforcement_unavailable',
@@ -431,7 +541,8 @@ async function handle(req, res, deps, guard, state) {
             ? 'Segreant cannot verify local budget/accounting state; the request was not sent. Repair the local ledger or configuration, then restart Segreant.'
             : decision.reason ?? 'Budget limit reached.';
         res.end(unavailable ? providerBudgetUnavailableBody(provider, message) : providerErrorBody(provider, message));
-        // Log the blocked attempt at zero cost for the audit trail.
+        // Log the blocked attempt at zero cost for the audit trail. Nothing was
+        // sent, so the cost is known to be zero, not unknown.
         safeLog(deps, {
             requestId: randomUUID(),
             sessionId,
@@ -451,7 +562,7 @@ async function handle(req, res, deps, guard, state) {
             reasoningTokens: 0,
             costUsd: 0,
             estimated: false,
-            pricing: unpricedPricingEvidence(),
+            pricing: notSentPricingEvidence(),
             streamed: parsed.stream,
             statusCode: unavailable ? 503 : 429,
             durationMs: 0,
@@ -502,7 +613,7 @@ async function handle(req, res, deps, guard, state) {
             headers['x-segreant-egress-refusal'] = egressRefusal.code;
         res.writeHead(status, headers);
         res.end(egressRefusal
-            ? providerEgressRefusalBody(provider, egressRefusal)
+            ? providerEgressRefusalBody(provider, egressRefusal, targetUrl, req.method ?? 'POST', deps.config.egress.mode)
             : providerUpstreamErrorBody(provider, detail, timedOut ? 'upstream_timeout' : 'upstream_unreachable'));
         safeLog(deps, {
             requestId,
@@ -523,7 +634,13 @@ async function handle(req, res, deps, guard, state) {
             reasoningTokens: 0,
             costUsd: 0,
             estimated: false,
-            pricing: unpricedPricingEvidence(),
+            // Only a policy or DNS refusal is certainly decided before the dial. A
+            // receipt failure can come after the provider answered (the response
+            // receipt), and a timeout or dropped connection may have reached it, so
+            // those keep an unknown cost (PR #143 review).
+            pricing: egressRefusal !== null && (egressRefusal.code === 'policy_denied' || egressRefusal.code === 'dns_denied')
+                ? notSentPricingEvidence()
+                : unpricedPricingEvidence(),
             streamed: parsed.stream,
             statusCode: status,
             durationMs: Date.now() - startedAt,
@@ -661,7 +778,7 @@ async function handle(req, res, deps, guard, state) {
         catch {
             /* non-JSON (e.g. error HTML) — usage stays empty */
         }
-        const cost = computeCost(provider, resolvedModel, usage);
+        const cost = withDeclarations(declarations, () => computeCost(provider, resolvedModel, usage));
         downHeaders['x-segreant-cost-usd'] = cost.costUsd.toFixed(6);
         if (decision.sessionSpendUsd !== null && config.budget.sessionUsd !== null) {
             const remaining = Math.max(0, config.budget.sessionUsd - decision.sessionSpendUsd - cost.costUsd);
@@ -671,7 +788,7 @@ async function handle(req, res, deps, guard, state) {
         res.end(text);
     }
     // --- Cost + log (after the client has its bytes) ---
-    const cost = computeCost(provider, resolvedModel, usage);
+    const cost = withDeclarations(declarations, () => computeCost(provider, resolvedModel, usage));
     safeLog(deps, {
         requestId,
         sessionId,
@@ -687,6 +804,9 @@ async function handle(req, res, deps, guard, state) {
         inputTokens: usage.inputTokens,
         outputTokens: usage.outputTokens,
         cacheWriteTokens: usage.cacheWriteTokens,
+        // Kept so a later reprice prices the writes at the same duration (PR #146
+        // review), and only when it was observed rather than chosen.
+        ...(usage.cacheWriteTtl === undefined || !usage.cacheWriteTtlObserved ? {} : { cacheWriteTtl: usage.cacheWriteTtl }),
         cacheReadTokens: usage.cacheReadTokens,
         reasoningTokens: usage.reasoningTokens ?? 0,
         costUsd: cost.costUsd,

package/dist/proxy/usage.js

@@ -27,19 +27,20 @@
  * is nested under a `response` key (e.g. the `response.completed` event has
  * `usage` at `event.response.usage`, not `event.usage`). See consumeOpenAI.
  */
+import { cacheWriteDuration } from '../cost/pricing.js';
 import { RESOURCE_LIMITS } from '../util/resource-limits.js';
 export function normalizeAnthropicUsage(u) {
     const ephem1h = u.cache_creation?.ephemeral_1h_input_tokens ?? 0;
     const ephem5m = u.cache_creation?.ephemeral_5m_input_tokens ?? 0;
     const cacheWrite = u.cache_creation_input_tokens ?? ephem5m + ephem1h;
-    // Prefer the longer-TTL flag when the breakdown says most writes were 1h.
-    const ttl = ephem1h > ephem5m ? '1h' : '5m';
+    const duration = cacheWriteDuration(ephem5m, ephem1h);
     return {
         inputTokens: u.input_tokens ?? 0,
         outputTokens: u.output_tokens ?? 0,
         cacheWriteTokens: cacheWrite,
         cacheReadTokens: u.cache_read_input_tokens ?? 0,
-        cacheWriteTtl: ttl,
+        ...(duration.ttl === undefined ? {} : { cacheWriteTtl: duration.ttl }),
+        cacheWriteTtlObserved: duration.observed,
     };
 }
 export function normalizeOpenAIUsage(u) {
@@ -176,7 +177,11 @@ export class StreamUsageAccumulator {
                 this.partial.inputTokens = n.inputTokens;
                 this.partial.cacheWriteTokens = n.cacheWriteTokens;
                 this.partial.cacheReadTokens = n.cacheReadTokens;
-                this.partial.cacheWriteTtl = n.cacheWriteTtl;
+                if (n.cacheWriteTtl === undefined)
+                    delete this.partial.cacheWriteTtl;
+                else
+                    this.partial.cacheWriteTtl = n.cacheWriteTtl;
+                this.partial.cacheWriteTtlObserved = n.cacheWriteTtlObserved;
                 this.maxOutput = Math.max(this.maxOutput, n.outputTokens);
             }
         }

package/dist/quota/limits.js

@@ -0,0 +1,138 @@
+/**
+ * The vendors' own usage meters, as their tools write them to local logs.
+ *
+ * Codex writes `rate_limits` on every token count: the percentage used of a
+ * 5-hour and a weekly window, with each window's reset time. Claude Code writes
+ * no percentage; when a limit is reached it writes the vendor's message
+ * ("You've hit your session limit · resets 6:40pm (Africa/Cairo)") as an API
+ * error line. Both are the VENDOR's meter. Segreant's own count is the ledger;
+ * the quota view sets the two side by side and never treats either as the
+ * other.
+ *
+ * Pure: parsing only, no I/O.
+ */
+/** Codex snapshots from one token_count payload's `rate_limits`. */
+export function codexRateLimitEvents(rateLimits, tsEpochMs) {
+    if (rateLimits === null || typeof rateLimits !== 'object')
+        return [];
+    const out = [];
+    for (const [key, kind] of [['primary', 'codex_primary'], ['secondary', 'codex_secondary']]) {
+        const w = rateLimits[key];
+        if (w === null || w === undefined || typeof w !== 'object')
+            continue;
+        const used = typeof w.used_percent === 'number' && Number.isFinite(w.used_percent) ? w.used_percent : null;
+        if (used === null)
+            continue;
+        const minutes = typeof w.window_minutes === 'number' && w.window_minutes > 0 ? w.window_minutes : null;
+        const resets = typeof w.resets_at === 'number' && w.resets_at > 0 ? w.resets_at * 1000 : null;
+        out.push({ source: 'codex', kind, tsEpochMs, usedPercent: used, windowMinutes: minutes, resetsAtMs: resets, detail: null });
+    }
+    return out;
+}
+/**
+ * The `rate_limits` object Claude Code passes to a status line script
+ * (code.claude.com/docs/en/statusline): `five_hour`, `seven_day` and
+ * `spend_limit`, each with `used_percentage` (0-100) and `resets_at` (epoch
+ * seconds). Present for Pro and Max subscribers after a session's first
+ * response; each window may be absent.
+ */
+export function claudeStatuslineEvents(input, tsEpochMs) {
+    if (input === null || typeof input !== 'object')
+        return [];
+    const limits = input.rate_limits;
+    if (limits === null || typeof limits !== 'object')
+        return [];
+    const out = [];
+    for (const [key, kind, minutes] of [
+        ['five_hour', 'claude_five_hour', 300],
+        ['seven_day', 'claude_seven_day', 10_080],
+        ['spend_limit', 'claude_spend_window', null],
+    ]) {
+        const w = limits[key];
+        if (w === null || w === undefined || typeof w !== 'object')
+            continue;
+        const used = typeof w.used_percentage === 'number' && Number.isFinite(w.used_percentage) ? w.used_percentage : null;
+        if (used === null)
+            continue;
+        const resets = typeof w.resets_at === 'number' && w.resets_at > 0 ? w.resets_at * 1000 : null;
+        out.push({ source: 'claude-code', kind, tsEpochMs, usedPercent: used, windowMinutes: minutes, resetsAtMs: resets, detail: null });
+    }
+    return out;
+}
+const CLAUDE_LIMIT = /You've hit your ([a-z ]{3,30}?) limit(?: · resets ([0-9]{1,2}(?::[0-9]{2})?\s?[ap]m)(?: \(([A-Za-z_]+(?:\/[A-Za-z_+-]+){0,2})\))?)?/;
+/**
+ * A Claude Code limit message, only from the vendor's own error line
+ * (`"isApiErrorMessage":true`). The same words quoted in a prompt or a tool
+ * result are not a limit event.
+ */
+export function claudeLimitEvent(line, tsEpochMs) {
+    if (!line.includes('"isApiErrorMessage":true'))
+        return null;
+    const m = CLAUDE_LIMIT.exec(line);
+    if (m === null)
+        return null;
+    const what = m[1].trim();
+    const kind = what === 'session' ? 'claude_session'
+        : what === 'weekly' ? 'claude_weekly'
+            : what.includes('spend') ? 'claude_spend'
+                : 'claude_other';
+    const resetsAtMs = m[2] !== undefined ? nextLocalTime(m[2], m[3] ?? null, tsEpochMs) : null;
+    return {
+        source: 'claude-code',
+        kind,
+        tsEpochMs,
+        usedPercent: null,
+        windowMinutes: kind === 'claude_session' ? 300 : kind === 'claude_weekly' ? 10_080 : null,
+        resetsAtMs,
+        detail: m[0].slice(0, 120),
+    };
+}
+/** Minutes a zone is ahead of UTC at an instant (Cairo in summer: +180). */
+export function zoneOffsetMinutes(timeZone, atMs) {
+    let parts;
+    try {
+        parts = new Intl.DateTimeFormat('en-US', {
+            timeZone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit',
+        }).formatToParts(new Date(atMs));
+    }
+    catch {
+        return null; // an unknown zone name
+    }
+    const get = (t) => Number(parts.find((p) => p.type === t)?.value);
+    const asUtc = Date.UTC(get('year'), get('month') - 1, get('day'), get('hour'), get('minute'), get('second'));
+    return Math.round((asUtc - Math.floor(atMs / 1000) * 1000) / 60_000);
+}
+/**
+ * The first instant after `afterMs` at which the clock in `timeZone` reads
+ * `clock` ("6:40pm", "4am"). With no zone, the machine's own zone is assumed,
+ * which is the zone Claude Code itself printed in.
+ */
+export function nextLocalTime(clock, timeZone, afterMs) {
+    const m = /^([0-9]{1,2})(?::([0-9]{2}))?\s?([ap]m)$/.exec(clock.trim());
+    if (m === null)
+        return null;
+    const clockHour = Number(m[1]);
+    if (clockHour < 1 || clockHour > 12)
+        return null; // a 12-hour clock reads 1 to 12
+    let hour = clockHour % 12;
+    if (m[3] === 'pm')
+        hour += 12;
+    const minute = m[2] === undefined ? 0 : Number(m[2]);
+    if (hour > 23 || minute > 59)
+        return null;
+    const offsetAt = (ms) => timeZone === null ? -new Date(ms).getTimezoneOffset() : zoneOffsetMinutes(timeZone, ms);
+    const offset = offsetAt(afterMs);
+    if (offset === null)
+        return null;
+    // The local calendar day of `afterMs`, then that day's clock time, in UTC.
+    const local = new Date(afterMs + offset * 60_000);
+    for (let day = 0; day <= 1; day++) {
+        const wallAsUtc = Date.UTC(local.getUTCFullYear(), local.getUTCMonth(), local.getUTCDate() + day, hour, minute);
+        const guess = wallAsUtc - offset * 60_000;
+        // Re-read the offset at the guess so a DST change between the two instants is honoured.
+        const exact = wallAsUtc - (offsetAt(guess) ?? offset) * 60_000;
+        if (exact > afterMs)
+            return exact;
+    }
+    return null;
+}

package/dist/quota/statusline.js

@@ -0,0 +1,68 @@
+/**
+ * Claude Code's status line, the lean path.
+ *
+ * Claude Code runs the status line command on every refresh and pipes session
+ * JSON on stdin; for Pro and Max subscribers that JSON carries the live usage
+ * meter (`rate_limits`). Going through the full CLI took 1.6 s a call, almost
+ * all of it opening the Store with its schema and integrity checks, which is
+ * far too slow for a bar that refreshes on every message. This path opens the
+ * ledger file directly, writes at most one row per meter (only when the
+ * reading changed), sums today's list cost and prints one line.
+ *
+ * It must never break the person's status bar: any failure prints a minimal
+ * line. It never creates the ledger or its tables; a fresh machine gets them
+ * from the first ordinary `segreant` command, and until then the line still
+ * prints.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { existsSync } from 'node:fs';
+import { claudeStatuslineEvents } from './limits.js';
+export function statuslineLine(dbFile, rawInput, nowMs) {
+    let input = null;
+    try {
+        input = rawInput.trim() === '' ? null : JSON.parse(rawInput);
+    }
+    catch {
+        input = null;
+    }
+    const events = claudeStatuslineEvents(input, nowMs);
+    const parts = events
+        .filter((e) => e.kind !== 'claude_spend_window')
+        .map((e) => `${e.kind === 'claude_five_hour' ? '5h' : 'week'} ${Math.round(e.usedPercent ?? 0)}%`);
+    if (!existsSync(dbFile))
+        return parts.length > 0 ? parts.join(' · ') : 'segreant';
+    let db = null;
+    try {
+        db = new DatabaseSync(dbFile);
+        // A running import holds the write lock in short batches; wait briefly, never long.
+        db.exec('PRAGMA busy_timeout = 200');
+        const hasTable = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'quota_events'").get() !== undefined;
+        if (hasTable) {
+            const last = db.prepare('SELECT used_percent AS used, resets_at_ms AS resets FROM quota_events WHERE source = ? AND kind = ? ORDER BY ts_epoch_ms DESC LIMIT 1');
+            const insert = db.prepare(`INSERT INTO quota_events (source, kind, ts_epoch_ms, used_percent, window_minutes, resets_at_ms, detail)
+         VALUES (?,?,?,?,?,?,NULL) ON CONFLICT(source, kind, ts_epoch_ms) DO NOTHING`);
+            for (const e of events) {
+                const prev = last.get(e.source, e.kind);
+                const resets = e.resetsAtMs === null ? null : Math.trunc(e.resetsAtMs);
+                if (prev !== undefined && prev.used === e.usedPercent && prev.resets === resets)
+                    continue;
+                insert.run(e.source, e.kind, Math.trunc(e.tsEpochMs), e.usedPercent, e.windowMinutes, resets);
+            }
+        }
+        const dayStart = new Date(nowMs);
+        dayStart.setHours(0, 0, 0, 0);
+        const today = db.prepare('SELECT COALESCE(SUM(cost_usd), 0) AS c FROM requests WHERE ts_epoch_ms >= ?').get(dayStart.getTime());
+        if (today !== undefined)
+            parts.push(`today $${today.c.toFixed(2)} list`);
+    }
+    catch {
+        // A locked, missing or older ledger: show what the input alone gives.
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* already closed */ }
+    }
+    return parts.length > 0 ? parts.join(' · ') : 'segreant';
+}

package/dist/quota/view.js

@@ -0,0 +1,122 @@
+const AGREE_BAND = 1.5; // within 1.5x either way of the earlier median
+const MIN_PERCENT_FOR_RATIO = 5; // a 1-2% reading is too coarse to divide by
+export function windowView(e, nowMs) {
+    const used = e.usedPercent ?? 0;
+    const reset = e.resetsAtMs !== null && e.resetsAtMs <= nowMs;
+    let projected = null;
+    let limitAt = null;
+    if (!reset && e.resetsAtMs !== null && e.windowMinutes !== null) {
+        const opened = e.resetsAtMs - e.windowMinutes * 60_000;
+        const elapsed = e.tsEpochMs - opened;
+        if (elapsed > 0) {
+            const perMs = used / elapsed;
+            projected = used + perMs * (e.resetsAtMs - e.tsEpochMs);
+            if (used >= 100)
+                limitAt = e.tsEpochMs;
+            else if (perMs > 0) {
+                const at = e.tsEpochMs + (100 - used) / perMs;
+                if (at < e.resetsAtMs)
+                    limitAt = at;
+            }
+        }
+    }
+    return {
+        kind: e.kind, usedPercent: used, windowMinutes: e.windowMinutes, resetsAtMs: e.resetsAtMs,
+        asOfMs: e.tsEpochMs, reset, projectedAtResetPercent: projected, limitAtMs: limitAt,
+    };
+}
+function median(xs) {
+    if (xs.length === 0)
+        return null;
+    const s = [...xs].sort((a, b) => a - b);
+    const mid = s.length >> 1;
+    return s.length % 2 === 1 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+/** For the longer Codex window: list cost per 1% of the vendor's meter, this window and earlier ones. */
+export function meterCheck(events, spend) {
+    const byWindow = new Map();
+    for (const e of events) {
+        if (e.kind !== 'codex_secondary' || e.resetsAtMs === null || e.windowMinutes === null)
+            continue;
+        const prev = byWindow.get(e.resetsAtMs);
+        if (prev === undefined || e.tsEpochMs > prev.tsEpochMs)
+            byWindow.set(e.resetsAtMs, e);
+    }
+    const ratios = [...byWindow.values()]
+        .sort((a, b) => b.resetsAtMs - a.resetsAtMs)
+        .map((e) => {
+        if ((e.usedPercent ?? 0) < MIN_PERCENT_FOR_RATIO)
+            return null;
+        const opened = e.resetsAtMs - e.windowMinutes * 60_000;
+        return spend('codex', opened, e.tsEpochMs + 1) / e.usedPercent;
+    });
+    const current = ratios[0] ?? null;
+    const earlier = ratios.slice(1, 9).filter((r) => r !== null);
+    const m = median(earlier);
+    return {
+        currentUsdPerPercent: current,
+        earlierUsdPerPercent: earlier,
+        agrees: current === null || m === null || earlier.length < 2 || m === 0
+            ? null
+            : current / m <= AGREE_BAND && m / current <= AGREE_BAND,
+    };
+}
+export function claudeLimitView(events, spend, nowMs) {
+    // Parallel agents hit the same wall together: one hit per window (its reset).
+    const hits = new Map();
+    for (const e of events) {
+        if (e.source !== 'claude-code')
+            continue;
+        const key = JSON.stringify([e.kind, e.resetsAtMs ?? Math.floor(e.tsEpochMs / 3_600_000)]);
+        const prev = hits.get(key);
+        if (prev === undefined || e.tsEpochMs < prev.tsEpochMs)
+            hits.set(key, e);
+    }
+    const list = [...hits.values()].sort((a, b) => a.tsEpochMs - b.tsEpochMs);
+    const fiveHours = 5 * 60 * 60_000;
+    const usdBeforeSessionHit = list
+        .filter((e) => e.kind === 'claude_session')
+        .map((e) => spend('claude-code', (e.resetsAtMs ?? e.tsEpochMs) - fiveHours, e.tsEpochMs + 1));
+    const lastFiveHoursUsd = spend('claude-code', nowMs - fiveHours, nowMs + 1);
+    if (list.length === 0 && lastFiveHoursUsd === 0)
+        return null;
+    return {
+        sessionHits: list.filter((e) => e.kind === 'claude_session').length,
+        weeklyHits: list.filter((e) => e.kind === 'claude_weekly').length,
+        spendHits: list.filter((e) => e.kind === 'claude_spend').length,
+        lastHit: list[list.length - 1] ?? null,
+        usdBeforeSessionHit,
+        lastFiveHoursUsd,
+    };
+}
+export function quotaView(events, spend, nowMs) {
+    const codexEvents = events.filter((e) => e.source === 'codex');
+    const latest = new Map();
+    for (const e of codexEvents) {
+        const prev = latest.get(e.kind);
+        if (prev === undefined || e.tsEpochMs >= prev.tsEpochMs)
+            latest.set(e.kind, e);
+    }
+    const windows = ['codex_primary', 'codex_secondary']
+        .map((k) => latest.get(k))
+        .filter((e) => e !== undefined)
+        .map((e) => windowView(e, nowMs));
+    const claudeLatest = new Map();
+    for (const e of events) {
+        if (e.kind !== 'claude_five_hour' && e.kind !== 'claude_seven_day' && e.kind !== 'claude_spend_window')
+            continue;
+        const prev = claudeLatest.get(e.kind);
+        if (prev === undefined || e.tsEpochMs >= prev.tsEpochMs)
+            claudeLatest.set(e.kind, e);
+    }
+    const claudeWindows = ['claude_five_hour', 'claude_seven_day', 'claude_spend_window']
+        .map((k) => claudeLatest.get(k))
+        .filter((e) => e !== undefined)
+        .map((e) => windowView(e, nowMs));
+    return {
+        codex: windows.length === 0 ? null : { windows, weekly: meterCheck(codexEvents, spend) },
+        claude: claudeLimitView(events.filter((e) => !e.kind.startsWith('claude_') || e.usedPercent === null), spend, nowMs),
+        claudeWindows,
+    };
+}
+export { median };

package/dist/scan/knownApps.js

@@ -1,7 +1,7 @@
 /**
  * Known-app inventory — the wider, honest half of `scan`.
  *
- * `detectTools()` (scan.ts) answers "which of our 3 NATIVELY SUPPORTED tools are
+ * `detectTools()` (scan.ts) answers "which of our NATIVELY SUPPORTED tools are
  * here" — present implies Segreant can read its usage data. This module answers
  * a different, narrower question: "which OTHER AI coding tools do we merely SEE
  * evidence of on this machine". Presence here implies nothing about import
@@ -61,6 +61,7 @@ const KNOWN_APPS = [
         id: 'cursor',
         label: 'Cursor',
         blurb: 'AI-first code editor.',
+        notReadBecause: 'its local token counts are best-effort and often 0 (Cursor staff, forum.cursor.com/t/155984); a team Admin API connector is planned',
         detect: (env) => firstExisting(env, [join(env.home, '.cursor')]),
     },
     {
@@ -104,6 +105,9 @@ export function detectKnownApps(opts = {}) {
     };
     return KNOWN_APPS.map((sig) => {
         const evidence = sig.detect(env);
-        return { id: sig.id, label: sig.label, blurb: sig.blurb, present: evidence !== null, evidence };
+        return {
+            id: sig.id, label: sig.label, blurb: sig.blurb, present: evidence !== null, evidence,
+            ...(sig.notReadBecause === undefined ? {} : { notReadBecause: sig.notReadBecause }),
+        };
     });
 }

package/dist/scan/scan.js

@@ -21,6 +21,7 @@ import { projectKey } from '../value/characterization.js';
 import { defaultClaudeCodeRoot } from '../connect/claudeCode.js';
 import { defaultOpencodeDbPath } from '../connect/opencode.js';
 import { defaultCodexRoot } from '../connect/codex.js';
+import { defaultAntigravityRoot } from '../connect/antigravity.js';
 import { detectKnownApps } from './knownApps.js';
 /**
  * Detect which supported tools have local data here, reusing each importer's own
@@ -32,6 +33,7 @@ export function detectTools() {
     const claudePresent = existsSync(claudeRoot);
     const opencodeDb = defaultOpencodeDbPath(); // already null when absent
     const codexRoot = defaultCodexRoot(); // already null when absent
+    const antigravityRoot = defaultAntigravityRoot(); // already null when absent
     return [
         {
             id: 'claude-code',
@@ -54,6 +56,13 @@ export function detectTools() {
             dataPath: codexRoot,
             blurb: 'Per-turn token usage from ~/.codex rollout session logs.',
         },
+        {
+            id: 'antigravity',
+            label: 'Antigravity',
+            present: antigravityRoot !== null,
+            dataPath: antigravityRoot,
+            blurb: 'Per-call token usage from the IDE and agy conversation databases under ~/.gemini.',
+        },
     ];
 }
 /** Directory names never worth descending into on a repo hunt (heavy or system). */