segreant 0.1.0 → 0.2.0

package/dist/dashboard/sessions.js

@@ -0,0 +1,345 @@
+/**
+ * The Workbench read behind the Spend page: the range's metered requests,
+ * grouped by agent session, by time bucket and model, and joined to the
+ * commits each session reported making.
+ *
+ * Everything here is metered list cost. A session's link to a commit is the
+ * session's own log line (`observed_commits`), never a time-window guess, and a
+ * commit's outcome is the last value read filed by `keptBucketOf`, the rule the
+ * Statement uses. A session that made several commits splits its cost evenly
+ * across them, and the basis sentence says so.
+ */
+import { realizationFromStore, keptBucketOf } from '../value/realization.js';
+import { isDemo } from '../config.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+/** The most session rows one read returns; the rest are counted, not listed. */
+export const SESSION_LIMIT = 200;
+/** The most points one session's context profile carries. */
+export const PROFILE_POINTS = 40;
+/** The most named models in the chart; the rest are `other`. */
+export const NAMED_MODELS = 5;
+/** Past this many days the chart steps by week, so a year stays readable. */
+const MAX_DAY_BUCKETS = 92;
+/** Context sent with one request: uncached input plus cache reads and writes. */
+export function contextTokens(r) {
+    return r.inputTokens + r.cacheReadTokens + r.cacheWriteTokens;
+}
+/**
+ * What a status code shows, and no more. 429 is a refusal by a cap, Segreant's
+ * own or the provider's (the alert counts call every 429 blocked); 5xx is a
+ * failure. The code alone does not say which side refused, so neither is named.
+ */
+export function replyKind(statusCode) {
+    if (statusCode === 429)
+        return 'refused';
+    if (statusCode !== null && statusCode >= 500)
+        return 'failed';
+    return null;
+}
+/** A request that reported tokens: the only kind that says how much context was sent. */
+function measured(r) {
+    return contextTokens(r) + r.outputTokens > 0;
+}
+/**
+ * A reply that went through yet reported no tokens: its usage is unknown. This
+ * is not `estimated`, which says only that the PRICE came from a near match;
+ * such a request may carry complete token counts (Codex review 2026-10-16).
+ * A refused or failed reply with no tokens sent nothing measurable.
+ */
+function usageUnknown(r) {
+    return !measured(r) && (r.statusCode === null || r.statusCode < 400);
+}
+function localDay(ts) {
+    const d = new Date(ts);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+function localHour(ts) {
+    const d = new Date(ts);
+    d.setMinutes(0, 0, 0);
+    return d.getTime();
+}
+function localWeek(ts) {
+    const d = new Date(localDay(ts));
+    d.setDate(d.getDate() - ((d.getDay() + 6) % 7)); // weeks start on Monday
+    return d.getTime();
+}
+function nextBucket(start, step) {
+    if (step === 'hour') {
+        const next = localHour(start + HOUR_MS);
+        return next > start ? next : start + HOUR_MS;
+    }
+    // From noon of the bucket's date, so a midnight that a DST change moved to
+    // 01:00 cannot carry 01:00 into every later bucket; each boundary is then
+    // taken afresh as that date's own local midnight (Codex review 2026-10-16).
+    const d = new Date(start);
+    const noon = new Date(d.getFullYear(), d.getMonth(), d.getDate() + (step === 'week' ? 7 : 1), 12).getTime();
+    return localDay(noon);
+}
+/** Fold a sequence to at most `points` values, each the largest in its slice. */
+export function foldProfile(values, points = PROFILE_POINTS) {
+    if (values.length <= points)
+        return { profile: [...values], sliceOf: (i) => i };
+    const sliceOf = (i) => Math.min(points - 1, Math.floor((i * points) / values.length));
+    const profile = new Array(points).fill(0);
+    values.forEach((v, i) => { const s = sliceOf(i); if (v > profile[s])
+        profile[s] = v; });
+    return { profile, sliceOf };
+}
+function topBy(counts) {
+    let best;
+    let bestValue = -Infinity;
+    for (const [k, v] of counts)
+        if (v > bestValue) {
+            best = k;
+            bestValue = v;
+        }
+    return best;
+}
+function add(m, k, v) {
+    m.set(k, (m.get(k) ?? 0) + v);
+}
+export function buildSessions(store, range, window, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const sessionLimit = opts.sessionLimit ?? SESSION_LIMIT;
+    const rows = store.requestsInRange(window.startMs, window.endMs);
+    // Models: the five that cost most in the range keep their names.
+    const modelCost = new Map();
+    for (const r of rows)
+        add(modelCost, r.model, r.costUsd);
+    const models = [...modelCost.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, NAMED_MODELS).map(([m]) => m);
+    const named = new Set(models);
+    // Buckets: hours for today, days otherwise, weeks for a long all-time range.
+    // A bounded range is drawn whole, empty stretches included; all-time starts at the first request.
+    const from = window.startMs > 0 ? window.startMs : Math.min(rows[0]?.tsEpochMs ?? now, now);
+    const step = window.bucketMs <= HOUR_MS
+        ? 'hour'
+        : (now - from) / DAY_MS > MAX_DAY_BUCKETS ? 'week' : 'day';
+    const keyOf = step === 'hour' ? localHour : step === 'week' ? localWeek : localDay;
+    const buckets = [];
+    const bucketIndex = new Map();
+    for (let b = keyOf(from); b < window.endMs && b <= now; b = nextBucket(b, step)) {
+        bucketIndex.set(b, buckets.length);
+        buckets.push({ startMs: b, costUsd: 0, requests: 0, byModel: [], otherUsd: 0 });
+    }
+    const bucketModel = buckets.map(() => new Map());
+    const sessions = new Map();
+    const totals = {
+        requests: 0, costUsd: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0,
+        sessions: 0, tools: 0, refusedReplies: 0, failedReplies: 0, unsessionedRequests: 0, unsessionedCostUsd: 0,
+    };
+    const tools = new Set();
+    // Spend is added once, as whole nanodollars, and every total below is read
+    // from these integers. Summing floats in different groupings let the
+    // outcome breakdown round to 1,440 µ$ against a 1,439 µ$ total (PR #135 review).
+    const nano = (usd) => Math.round(usd * 1e9);
+    let totalNano = 0;
+    let unsessionedNano = 0;
+    for (const r of rows) {
+        totals.requests += 1;
+        totalNano += nano(r.costUsd);
+        totals.inputTokens += r.inputTokens;
+        totals.outputTokens += r.outputTokens;
+        totals.cacheReadTokens += r.cacheReadTokens;
+        totals.cacheWriteTokens += r.cacheWriteTokens;
+        const kind = replyKind(r.statusCode);
+        if (kind === 'refused')
+            totals.refusedReplies += 1;
+        if (kind === 'failed')
+            totals.failedReplies += 1;
+        if (r.source)
+            tools.add(r.source);
+        const bi = bucketIndex.get(keyOf(r.tsEpochMs));
+        if (bi !== undefined) {
+            buckets[bi].costUsd += r.costUsd;
+            buckets[bi].requests += 1;
+            if (named.has(r.model))
+                add(bucketModel[bi], r.model, r.costUsd);
+            else
+                buckets[bi].otherUsd += r.costUsd;
+        }
+        if (!r.sessionId) {
+            totals.unsessionedRequests += 1;
+            unsessionedNano += nano(r.costUsd);
+            continue;
+        }
+        let acc = sessions.get(r.sessionId);
+        if (!acc) {
+            acc = { rows: [], source: new Map(), project: new Map(), model: new Map() };
+            sessions.set(r.sessionId, acc);
+        }
+        acc.rows.push(r);
+        add(acc.source, r.source ?? null, 1);
+        add(acc.project, r.projectCanonical ?? r.project, r.costUsd + 1e-12);
+        add(acc.model, r.model, r.costUsd + 1e-12);
+    }
+    totals.costUsd = totalNano / 1e9;
+    totals.unsessionedCostUsd = unsessionedNano / 1e9;
+    totals.sessions = sessions.size;
+    totals.tools = tools.size;
+    buckets.forEach((b, i) => {
+        b.byModel = models.filter((m) => bucketModel[i].has(m)).map((m) => ({ model: m, costUsd: bucketModel[i].get(m) }));
+    });
+    // Commits: each session's own log lines, joined to the last value read.
+    const report = realizationFromStore(store);
+    const units = report.units;
+    const observed = new Map();
+    const seenSha = new Map();
+    for (const o of store.observedCommits()) {
+        if (!sessions.has(o.sessionId))
+            continue;
+        const seen = seenSha.get(o.sessionId) ?? new Set();
+        if (seen.has(o.shortSha))
+            continue;
+        seen.add(o.shortSha);
+        seenSha.set(o.sessionId, seen);
+        const list = observed.get(o.sessionId) ?? [];
+        list.push(o);
+        observed.set(o.sessionId, list);
+    }
+    // Indexed once: scanning every unit for every commit stalled the process
+    // that also serves the proxy (Codex review 2026-10-16: 30 s at 10,000).
+    const byHash = new Map();
+    const byPrefix = new Map();
+    for (const u of units) {
+        const h = u.hash.toLowerCase();
+        byHash.set(h, u);
+        if (h.length >= 7) {
+            const list = byPrefix.get(h.slice(0, 7)) ?? [];
+            list.push(u);
+            byPrefix.set(h.slice(0, 7), list);
+        }
+    }
+    const commitOf = (o) => {
+        // A log records an abbreviated sha. Only a hex abbreviation of seven or more
+        // characters may stand for a longer hash, and only when exactly one
+        // measured unit has it: with two, picking either would hand this session
+        // another repository's outcome, so the commit stays unmatched.
+        const sha = o.shortSha.toLowerCase();
+        const abbreviated = sha.length >= 7 && /^[0-9a-f]+$/.test(sha);
+        const exact = byHash.get(sha);
+        const candidates = exact || !abbreviated ? [] : (byPrefix.get(sha.slice(0, 7)) ?? []).filter((u) => u.hash.toLowerCase().startsWith(sha));
+        const unit = exact ?? (candidates.length === 1 ? candidates[0] : undefined);
+        const outcome = unit ? keptBucketOf(unit) : 'unmeasured';
+        const checkMs = unit && outcome === 'maturing' ? unit.tsEpochMs + (unit.checkWindowDays ?? report.windowDays) * DAY_MS : null;
+        return { sha: o.shortSha, subject: o.subject, tsEpochMs: o.tsEpochMs, outcome, checkMs };
+    };
+    const share = () => ({ costUsd: 0, commits: 0 });
+    const outcomes = {
+        kept: share(), notKept: share(), contested: share(), unknown: share(), maturing: share(), unmeasured: share(),
+        noCommit: { costUsd: 0, sessions: 0 },
+        basis: '',
+        measuredAt: units.length > 0 ? report.generatedAt : null,
+    };
+    const outcomeMicros = { kept: 0, notKept: 0, contested: 0, unknown: 0, maturing: 0, unmeasured: 0 };
+    let noCommitMicros = 0;
+    const built = [];
+    for (const [sessionId, acc] of sessions) {
+        const context = [];
+        const rawMarks = [];
+        for (const r of acc.rows) {
+            if (measured(r))
+                context.push(contextTokens(r));
+            const kind = replyKind(r.statusCode);
+            if (kind)
+                rawMarks.push({ at: Math.max(0, context.length - 1), kind });
+        }
+        const { profile, sliceOf } = foldProfile(context);
+        const seen = new Set();
+        const marks = rawMarks
+            .map((m) => ({ at: sliceOf(m.at), kind: m.kind }))
+            .filter((m) => { const k = `${m.at}:${m.kind}`; if (seen.has(k))
+            return false; seen.add(k); return true; });
+        const commits = (observed.get(sessionId) ?? []).sort((a, b) => a.tsEpochMs - b.tsEpochMs).map(commitOf);
+        const costNano = acc.rows.reduce((s, r) => s + nano(r.costUsd), 0);
+        const cost = costNano / 1e9;
+        // Exact (fractional) microdollars here; each category is rounded once, at
+        // the end, against the rounded total. Rounding every session first let a
+        // thousand $0.0014008 sessions add up to $1.401 of outcomes for $1.4008 of
+        // spend (review 4, F1).
+        if (commits.length === 0) {
+            noCommitMicros += costNano / 1000;
+            outcomes.noCommit.sessions += 1;
+        }
+        else {
+            const share = costNano / 1000 / commits.length;
+            for (const c of commits) {
+                outcomeMicros[c.outcome] += share;
+                outcomes[c.outcome].commits += 1;
+            }
+        }
+        built.push({
+            sessionId,
+            startMs: acc.rows[0].tsEpochMs,
+            endMs: acc.rows[acc.rows.length - 1].tsEpochMs,
+            source: topBy(acc.source) ?? null,
+            project: topBy(acc.project) ?? '',
+            model: topBy(acc.model) ?? '',
+            models: acc.model.size,
+            requests: acc.rows.length,
+            costUsd: cost,
+            inputTokens: acc.rows.reduce((s, r) => s + r.inputTokens, 0),
+            outputTokens: acc.rows.reduce((s, r) => s + r.outputTokens, 0),
+            cacheReadTokens: acc.rows.reduce((s, r) => s + r.cacheReadTokens, 0),
+            cacheWriteTokens: acc.rows.reduce((s, r) => s + r.cacheWriteTokens, 0),
+            contextStartTokens: context[0] ?? 0,
+            contextEndTokens: context[context.length - 1] ?? 0,
+            contextPeakTokens: context.reduce((m, v) => Math.max(m, v), 0),
+            refusedReplies: acc.rows.filter((r) => replyKind(r.statusCode) === 'refused').length,
+            failedReplies: acc.rows.filter((r) => replyKind(r.statusCode) === 'failed').length,
+            usageUnknownRequests: acc.rows.filter(usageUnknown).length,
+            profile: context.length > 0 ? profile : [],
+            marks,
+            commits,
+        });
+    }
+    built.sort((a, b) => b.startMs - a.startMs || a.sessionId.localeCompare(b.sessionId));
+    // Largest remainder: whole microdollars per category that add up to the
+    // rounded sum of the exact parts, so the breakdown partitions the spend.
+    const parts = [
+        ...Object.keys(outcomeMicros).map((k) => [k, outcomeMicros[k]]),
+        ['noCommit', noCommitMicros],
+    ];
+    const whole = parts.map(([k, v]) => ({ k, floor: Math.floor(v), rem: v - Math.floor(v) }));
+    // The target is the sessioned spend, rounded once from the exact integer sum.
+    let left = Math.round((totalNano - unsessionedNano) / 1000) - whole.reduce((s, w) => s + w.floor, 0);
+    for (const w of [...whole].sort((a, b) => b.rem - a.rem)) {
+        if (left <= 0)
+            break;
+        w.floor += 1;
+        left -= 1;
+    }
+    // Float error in the fractional parts can leave the floors a microdollar
+    // over the target; take it back from the smallest remainders.
+    for (const w of [...whole].sort((a, b) => a.rem - b.rem)) {
+        if (left >= 0)
+            break;
+        if (w.floor > 0) {
+            w.floor -= 1;
+            left += 1;
+        }
+    }
+    for (const w of whole) {
+        if (w.k === 'noCommit')
+            outcomes.noCommit.costUsd = w.floor / 1e6;
+        else
+            outcomes[w.k].costUsd = w.floor / 1e6;
+    }
+    outcomes.basis = 'Metered list cost of the sessions in this range. A session is linked to a commit only when its own log recorded making it;'
+        + ' a session that made several commits splits its cost evenly across them. Each commit is filed by the last value read'
+        + (outcomes.measuredAt === null ? ', and none has run on this machine yet, so every linked commit is unmeasured.' : ', by the same rule as the Statement.');
+    return {
+        demo: isDemo(),
+        generatedAt: new Date(now).toISOString(),
+        range,
+        window: { startMs: window.startMs, endMs: window.endMs, bucketMs: step === 'hour' ? HOUR_MS : step === 'week' ? 7 * DAY_MS : DAY_MS },
+        totals,
+        models,
+        buckets,
+        sessions: built.slice(0, sessionLimit),
+        sessionLimit,
+        sessionsOmitted: Math.max(0, built.length - sessionLimit),
+        outcomes,
+    };
+}

package/dist/dashboard/settings.js

@@ -4,7 +4,7 @@
  * Kept separate from server.ts (already large) and framework-free so it's unit-testable
  * without spinning up an HTTP server.
  */
-import { segreantHome, configPath, dbPath, validateBudgetConfig, FEATURE_DEFAULTS } from '../config.js';
+import { segreantHome, configPath, dbPath, validateBudgetConfig, FEATURE_DEFAULTS, isDemo } from '../config.js';
 import { describeBudgetEnforcement } from '../budget/enforceability.js';
 import { egressReceiptPath, verifyEgressReceipts } from '../egress/receipts.js';
 export function buildSettingsSnapshot(store, config, version, windowDays = 14) {
@@ -19,6 +19,7 @@ export function buildSettingsSnapshot(store, config, version, windowDays = 14) {
         retentionDays: config.retentionDays,
         proposalRetentionDays: config.proposalRetentionDays,
         metadataOnly: config.metadataOnly,
+        demo: isDemo(),
         features: { ...config.features },
         budget: config.budget,
         enforcement: describeBudgetEnforcement(config.budget),

package/dist/dashboard/value-cache.js

@@ -0,0 +1,105 @@
+/**
+ * In-memory cache for the `/api/value` payload.
+ *
+ * Why it exists: with no stored realization (the user has not run `scan`), the
+ * value report re-runs git realization for the start folder on every load —
+ * 24.7 s, then 13.2 s again, with nothing changed. This cache answers repeat
+ * loads from memory. It never writes the realization to the ledger: dashboard
+ * reads are read-only by default, and persisting is an explicit `--apply`.
+ *
+ * Correctness rules:
+ * - The key covers every input the report reads: the query string, the repo
+ *   path and its HEAD commit, a hash of the whole config, and change marks on
+ *   each ledger table the report depends on (max rowid plus exact row count).
+ *   An append, a price change, a gate signal, a stored realization or a config
+ *   edit therefore misses the cache.
+ * - Entries live at most `ttlMs` from the start of their computation, whatever
+ *   the key, because realization units mature with wall-clock time.
+ * - The payload is cached whole, so its own `generatedAt` keeps the ORIGINAL
+ *   compute time; nothing rewrites it on a hit.
+ * - Concurrent identical requests share one in-flight computation.
+ * - Bounded: at most `maxEntries` payloads, least recently used evicted first.
+ *
+ * A cache is owned per Store (see `valueReadCacheFor` in routes.ts), so a fresh
+ * Store, as in each test, starts with an empty cache.
+ */
+import { createHash } from 'node:crypto';
+export const VALUE_CACHE_MAX_ENTRIES = 8;
+export const VALUE_CACHE_TTL_MS = 10 * 60_000;
+export class ValueReadCache {
+    stats = { computes: 0, hits: 0, shared: 0 };
+    entries = new Map();
+    inflight = new Map();
+    maxEntries;
+    ttlMs;
+    now;
+    constructor(opts = {}) {
+        this.maxEntries = Math.max(1, Math.floor(opts.maxEntries ?? VALUE_CACHE_MAX_ENTRIES));
+        this.ttlMs = opts.ttlMs ?? VALUE_CACHE_TTL_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Return the stored value for `key`, or run `compute` once and store its result. */
+    get(key, compute) {
+        const nowMs = this.now();
+        const stored = this.entries.get(key);
+        if (stored !== undefined) {
+            const age = nowMs - stored.startedAtMs;
+            if (age >= 0 && age < this.ttlMs) {
+                // Re-insert to mark it most recently used.
+                this.entries.delete(key);
+                this.entries.set(key, stored);
+                this.stats.hits += 1;
+                return Promise.resolve(stored.value);
+            }
+            this.entries.delete(key);
+        }
+        const running = this.inflight.get(key);
+        if (running !== undefined) {
+            this.stats.shared += 1;
+            return running;
+        }
+        this.stats.computes += 1;
+        const started = Promise.resolve()
+            .then(compute)
+            .then((value) => {
+            this.inflight.delete(key);
+            this.store(key, value, nowMs);
+            return value;
+        }, (err) => {
+            this.inflight.delete(key);
+            throw err;
+        });
+        this.inflight.set(key, started);
+        return started;
+    }
+    store(key, value, startedAtMs) {
+        this.entries.delete(key);
+        this.entries.set(key, { value, startedAtMs });
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+    /** Number of stored entries (expired ones included until next touched). */
+    get size() {
+        return this.entries.size;
+    }
+}
+export function valueCacheKey(input) {
+    const params = [...input.params.entries()].sort(([ak, av], [bk, bv]) => {
+        if (ak !== bk)
+            return ak < bk ? -1 : 1;
+        if (av === bv)
+            return 0;
+        return av < bv ? -1 : 1;
+    });
+    return JSON.stringify({
+        params,
+        repo: input.repo,
+        head: input.head ?? 'no-git',
+        config: createHash('sha256').update(JSON.stringify(input.config) ?? 'null').digest('hex'),
+        marks: input.marks,
+    });
+}

package/dist/dashboard/web/app/components/claimInspector.js

@@ -24,7 +24,7 @@
 import { h, render, captureFocus, restoreFocus, trapFocus } from '../core/dom.js';
 import { signal, effect, onCleanup } from '../core/signal.js';
 import { usd, isPrecise } from '../core/fmt.js';
-import { claimIsSupported, claimProfileRows, claimShowsFigure, } from '../core/claimTypes.js';
+import { claimIsSupported, claimProfileRows, claimShowsFigure, claimCompletionLine, claimStrongerClaimLine, } from '../core/claimTypes.js';
 const active = signal(null);
 let opener = null;
 export function openClaimInspector(layer) {
@@ -92,6 +92,7 @@ function figureText(layer) {
 function panel(layer) {
     const i = layer.inspection;
     const scrim = h('div', { class: 'claim-scrim', onclick: () => closeClaimInspector() });
+    const stronger = claimStrongerClaimLine(layer);
     const body = h('aside', {
         class: `claim-panel${claimIsSupported(layer) ? '' : ' claim-panel-open'}`,
         role: 'dialog',
@@ -107,10 +108,10 @@ function panel(layer) {
         text: figureText(layer) }), h('p', { class: 'claim-basis', text: layer.basis }), profileCard(layer), h('dl', { class: 'claim-rows' }, row(isPrecise() ? 'Provenance' : 'Where it came from', i.provenance), row(isPrecise() ? 'Scope' : 'What it covers', i.scope), row(isPrecise() ? 'Freshness' : 'When it was computed', i.freshness), row(isPrecise() ? 'Coverage' : 'How much it reaches', i.coverage), row(isPrecise() ? 'Enforceability' : 'What it can and cannot do', i.enforceability), row(isPrecise() ? 'Evidence source' : 'Where to check it', i.evidenceSource)), i.assumptions.length
         ? list(isPrecise() ? 'Assumptions and conditions' : 'Taken on trust', i.assumptions, 'claim-assumed')
         : null, i.missingEvidence.length
-        ? list(isPrecise() ? 'Missing evidence' : 'What we do not have', i.missingEvidence, 'claim-missing')
-        : h('p', { class: 'claim-complete', text: isPrecise()
-                ? 'No missing evidence is named for this claim.'
-                : 'Nothing is missing for this one.' }), layer.nextStep
+        ? list(isPrecise() ? 'Missing evidence' : "What's missing", i.missingEvidence, 'claim-missing')
+        : h('p', { class: 'claim-complete', text: claimCompletionLine(layer, isPrecise()) }), stronger
+        ? h('p', { class: 'claim-basis', text: stronger })
+        : null, layer.nextStep
         ? h('p', { class: 'claim-next', text: `Next action: ${layer.nextStep}` })
         : null);
     const release = trapFocus(body);