segreant 0.1.0 → 0.2.0

package/dist/git/repoScope.js

@@ -0,0 +1,207 @@
+/**
+ * Which recorded AI spend belongs to a repository.
+ *
+ * The plain rule is the project label: spend recorded while a tool ran inside
+ * the repository's folder. That rule loses a repository's history as soon as it
+ * moves (the old folder's label no longer matches), and it cannot see work done
+ * from a git worktree or from a parent folder.
+ *
+ * This module adds what the agents' own logs PROVE. An agent session that
+ * created a commit printed git's "[branch sha] subject" line, which the
+ * importers record (observed_commits). An observation is accepted as evidence
+ * for this repository only when all three hold:
+ *
+ *   1. the sha names a commit in this repository,
+ *   2. the subject git printed starts the commit's subject (or the reverse), and
+ *   3. the observation was logged within 30 minutes of the commit time.
+ *
+ * From the accepted observations two links follow:
+ *
+ *   - session: every request of a session that verifiably committed here
+ *     belongs here, wherever the session was started;
+ *   - folder: a folder a verified commit was made from belongs here when it no
+ *     longer exists (a moved or deleted checkout) or is itself a checkout of
+ *     this repository (a worktree). An existing folder that is not this
+ *     repository (a parent folder, another repo) is never linked as a whole:
+ *     only its verified sessions are.
+ *
+ * Nothing here is persisted and no ledger row is relabelled. The links are
+ * recomputed from evidence on every run and reported beside the result.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { evidenceMatcher, normPath as norm, pathUnder as under } from '../store/scopeEvidence.js';
+import { projectName } from './correlate.js';
+const run = promisify(execFile);
+async function git(repoPath, args) {
+    const { stdout } = await run('git', ['-C', repoPath, ...args], { maxBuffer: 64 * 1024 * 1024 });
+    return stdout;
+}
+const MAX_OBSERVATION_SKEW_MS = 30 * 60 * 1000;
+const SUBJECT_PREFIX = 40;
+/** True when the subject git printed and the commit's subject are the same subject. */
+export function subjectsAgree(printed, actual) {
+    const a = printed.trim().replace(/\s+/g, ' ');
+    const b = actual.trim().replace(/\s+/g, ' ');
+    if (a.length === 0 || b.length === 0)
+        return false;
+    const n = Math.min(SUBJECT_PREFIX, b.length);
+    return a.startsWith(b.slice(0, n)) || b.startsWith(a.slice(0, Math.min(SUBJECT_PREFIX, a.length)));
+}
+/**
+ * A repository's identity: its root commit(s), the one thing every clone,
+ * worktree and moved copy of it shares and no unrelated repository does. The
+ * folder is not the identity (it moves) and the remote URL is not either (an
+ * agent's working copy is often cloned from a local path).
+ */
+const identityCache = new Map();
+export function repoIdentity(dir) {
+    const key = norm(dir);
+    let pending = identityCache.get(key);
+    if (pending === undefined) {
+        pending = git(dir, ['rev-list', '--max-parents=0', 'HEAD']).then((out) => {
+            const roots = out.split('\n').map((s) => s.trim()).filter(Boolean).sort();
+            return roots.length > 0 ? roots.join(',') : null;
+        }, () => null);
+        identityCache.set(key, pending);
+    }
+    return pending;
+}
+/**
+ * A checkout's top level, spelled the way `dir` is spelled. `--show-toplevel`
+ * returns the physical path (macOS adds /private, Windows expands 8.3 short
+ * names), while ledger rows keep the spelling the agent logged; a linked folder
+ * spelled differently would never match them. `--show-cdup` is relative, so
+ * resolving it against `dir` keeps that spelling.
+ */
+async function topLevel(dir) {
+    try {
+        const up = (await git(dir, ['rev-parse', '--show-cdup'])).trim();
+        return resolve(dir, up);
+    }
+    catch {
+        return null;
+    }
+}
+async function commonDir(dir) {
+    try {
+        const out = (await git(dir, ['rev-parse', '--path-format=absolute', '--git-common-dir'])).trim();
+        return out === '' ? null : norm(out);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the evidence-extended spend scope for one repository. `maxCommits`
+ * bounds the history read to resolve observed shas (newest first).
+ */
+export async function repoSpendScope(store, repoPath, opts = {}) {
+    const label = await projectName(repoPath);
+    const labels = new Set(store.projectFamily(label));
+    // A caller scoping many repositories reads the observations once and passes them in.
+    const observations = opts.observations ?? store.observedCommits();
+    const linkedSessions = new Set();
+    const folderCounts = new Map();
+    let verifiedObservations = 0;
+    if (observations.length > 0) {
+        // One read of this repository's history: sha -> (time, subject).
+        let log = '';
+        try {
+            log = await git(repoPath, ['log', '--all', `-n${opts.maxCommits ?? 20_000}`, '--format=%H%x1f%ct%x1f%s']);
+        }
+        catch {
+            log = '';
+        }
+        const byPrefix = new Map();
+        for (const line of log.split('\n')) {
+            const [hash, ct, subject] = line.split('\x1f');
+            if (!hash || hash.length < 7 || ct === undefined || subject === undefined)
+                continue;
+            const key = hash.slice(0, 7);
+            const list = byPrefix.get(key) ?? [];
+            list.push({ hash, tsMs: Number(ct) * 1000, subject });
+            byPrefix.set(key, list);
+        }
+        for (const o of observations) {
+            const candidates = byPrefix.get(o.shortSha.slice(0, 7)) ?? [];
+            const hit = candidates.find((c) => c.hash.startsWith(o.shortSha)
+                && subjectsAgree(o.subject, c.subject)
+                && Math.abs(o.tsEpochMs - c.tsMs) <= MAX_OBSERVATION_SKEW_MS);
+            if (!hit)
+                continue;
+            verifiedObservations += 1;
+            linkedSessions.add(o.sessionId);
+            if (o.cwd) {
+                const key = norm(o.cwd);
+                const entry = folderCounts.get(key) ?? { path: o.cwd, count: 0 };
+                entry.count += 1;
+                folderCounts.set(key, entry);
+            }
+        }
+    }
+    // A folder is linked as a whole only when it is gone (moved or deleted) or is
+    // a checkout of this very repository. Its own top level is what is linked.
+    const repoCommon = await commonDir(repoPath);
+    const repoId = await repoIdentity(repoPath);
+    const repoRoot = norm(repoPath);
+    const linkedFolders = [];
+    for (const [key, entry] of folderCounts) {
+        if (under(key, repoRoot))
+            continue; // already covered by the label
+        if (!existsSync(entry.path)) {
+            linkedFolders.push({ path: entry.path, reason: 'moved', verifiedCommits: entry.count });
+            continue;
+        }
+        const common = await commonDir(entry.path);
+        const reason = common !== null && repoCommon !== null && common === repoCommon
+            ? 'worktree'
+            : repoId !== null && (await repoIdentity(entry.path)) === repoId
+                ? 'clone'
+                : null;
+        if (reason === null)
+            continue;
+        // The checkout's own top level is linked, so the rest of its work counts too.
+        const top = (await topLevel(entry.path)) ?? entry.path;
+        if (under(norm(top), repoRoot))
+            continue;
+        const existing = linkedFolders.find((f) => norm(f.path) === norm(top));
+        if (existing)
+            existing.verifiedCommits += entry.count;
+        else
+            linkedFolders.push({ path: top, reason, verifiedCommits: entry.count });
+    }
+    const linked = evidenceMatcher({ sessions: [...linkedSessions], folders: linkedFolders.map((f) => f.path) });
+    const labelled = (row) => labels.has(row.projectCanonical ?? row.project) || labels.has(row.project);
+    return {
+        labels,
+        linkedFolders,
+        linkedSessions,
+        verifiedObservations,
+        extended: linkedFolders.length > 0 || linkedSessions.size > 0,
+        matches(row) {
+            return labelled(row) || linked(row);
+        },
+        evidenceFor(rows) {
+            const sessions = new Set();
+            const folders = new Set();
+            for (const row of rows) {
+                if (labelled(row))
+                    continue;
+                if (row.sessionId !== null && linkedSessions.has(row.sessionId))
+                    sessions.add(row.sessionId);
+                if (row.cwd) {
+                    const c = norm(row.cwd);
+                    for (const f of linkedFolders)
+                        if (under(c, norm(f.path)))
+                            folders.add(f.path);
+                }
+            }
+            return sessions.size === 0 && folders.size === 0
+                ? undefined
+                : { sessions: [...sessions].sort(), folders: [...folders].sort() };
+        },
+    };
+}

package/dist/git/survivalStore.js

@@ -0,0 +1,186 @@
+/**
+ * Survival work kept between runs, so a later run spends its budget on what
+ * an earlier run did not reach.
+ *
+ * Two kinds of git output are kept, per repository, in one JSON file under
+ * `<SEGREANT_HOME>/survival/`:
+ *
+ *  - a commit's file list (`git show --numstat`). A commit hash names fixed
+ *    content, so its file list never changes; a rewritten commit has a new hash.
+ *  - one file's blame at a HEAD: how many of its lines belong to each commit.
+ *    Survival is measured at the CURRENT HEAD, so an old blame may only stand in
+ *    for a new one when it is the same observation. It is reused only when
+ *      1. it was taken at this HEAD, or at an ancestor of it (history was not
+ *         rewritten), and
+ *      2. no commit between the two touched the path, counting both sides of a
+ *         rename and every parent of a merge. Same file contents is not enough:
+ *         a change followed by a revert gives the reverted lines a new author.
+ *      3. it was taken with a history bound no newer than the one asked for. A
+ *         bound collapses older lines onto a boundary commit; every commit newer
+ *         than the stored bound has its exact count.
+ *    Anything else is blamed again.
+ *
+ * This is a cache of git's answers, not evidence: deleting the directory loses
+ * time, never a figure. It is off unless an entry point turns it on
+ * (`configureSurvivalStore`), so tests and library callers never write to a
+ * home directory they did not choose.
+ */
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const run = promisify(execFile);
+const VERSION = 1;
+/** Bounds per repository file. Exceeding one drops the oldest half of that map. */
+const MAX_BLAME_PATHS = 20_000;
+const MAX_COMMITS = 10_000;
+let directory = null;
+const loaded = new Map();
+const validity = new Map();
+let exitHooked = false;
+/** Turn persistence on, into `dir`, or off with null. Off is the default. */
+export function configureSurvivalStore(dir) {
+    if (directory !== dir)
+        flushSurvivalStore();
+    directory = dir;
+    loaded.clear();
+    validity.clear();
+    if (dir !== null && !exitHooked) {
+        exitHooked = true;
+        // Deliberately synchronous: the exit event runs no further asynchronous
+        // work, and a CLI command that calls process.exit() still keeps what it measured.
+        process.once('exit', flushSurvivalStore);
+    }
+}
+/** Exposed for tests: forget what was read into memory, as a new process would. */
+export function forgetLoadedSurvivalStore() {
+    flushSurvivalStore();
+    loaded.clear();
+    validity.clear();
+}
+function repoKey(repoPath) {
+    let real = repoPath;
+    try {
+        real = realpathSync.native(repoPath);
+    }
+    catch { /* keep the path as given */ }
+    return createHash('sha256').update(real.replace(/\\/g, '/')).digest('hex').slice(0, 32);
+}
+function load(repoPath) {
+    if (directory === null)
+        return null;
+    const key = repoKey(repoPath);
+    let hit = loaded.get(key);
+    if (hit)
+        return hit;
+    const file = join(directory, `${key}.json`);
+    let data = { v: VERSION, blame: {}, numstat: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (parsed && parsed.v === VERSION && typeof parsed.blame === 'object' && typeof parsed.numstat === 'object') {
+            data = { v: VERSION, blame: parsed.blame ?? {}, numstat: parsed.numstat ?? {} };
+        }
+    }
+    catch { /* missing or unreadable: start empty */ }
+    hit = { file, data, dirty: false };
+    loaded.set(key, hit);
+    return hit;
+}
+/** Write every changed store. Never throws: a cache that cannot be written only costs time. */
+export function flushSurvivalStore() {
+    for (const store of loaded.values()) {
+        if (!store.dirty)
+            continue;
+        try {
+            mkdirSync(join(store.file, '..'), { recursive: true });
+            const tmp = `${store.file}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify(store.data));
+            renameSync(tmp, store.file);
+            store.dirty = false;
+        }
+        catch { /* read-only home or full disk: keep running without it */ }
+    }
+}
+function trim(map, max) {
+    const keys = Object.keys(map);
+    if (keys.length <= max)
+        return;
+    for (const k of keys.slice(0, Math.ceil(keys.length / 2)))
+        delete map[k];
+}
+/** A commit's stored file list, or undefined when it has not been read before. */
+export function storedCommitFiles(repoPath, hash) {
+    const rows = load(repoPath)?.data.numstat[hash];
+    return rows?.map(([path, added]) => ({ path, added }));
+}
+export function rememberCommitFiles(repoPath, hash, files) {
+    const store = load(repoPath);
+    if (!store)
+        return;
+    store.data.numstat[hash] = files.map((f) => [f.path, f.added]);
+    trim(store.data.numstat, MAX_COMMITS);
+    store.dirty = true;
+}
+async function git(repoPath, args) {
+    const { stdout } = await run('git', ['-C', repoPath, ...args], { maxBuffer: 64 * 1024 * 1024 });
+    return stdout;
+}
+/**
+ * Paths any commit after `from` and up to `to` touched, or null when `from` is
+ * not an ancestor of `to` (history rewritten, or `from` gone). `-m` lists a
+ * merge's changes against every parent and `--no-renames` lists both sides of a
+ * rename, so the set can only be too large, which costs a blame, never wrong.
+ */
+function touchedBetween(repoPath, from, to) {
+    if (from === to)
+        return Promise.resolve(new Set());
+    const key = `${repoKey(repoPath)}\0${from}\0${to}`;
+    let pending = validity.get(key);
+    if (pending === undefined) {
+        pending = (async () => {
+            try {
+                await git(repoPath, ['merge-base', '--is-ancestor', from, to]);
+            }
+            catch {
+                return null;
+            }
+            const out = await git(repoPath, ['log', '-m', '--no-renames', '--name-only', '-z', '--format=', `${from}..${to}`]);
+            return new Set(out.split('\0').map((p) => p.replace(/^\n+/, '')).filter((p) => p !== ''));
+        })().catch(() => null);
+        validity.set(key, pending);
+    }
+    return pending;
+}
+/**
+ * A stored blame of `path` that is the same observation as blaming it at
+ * `head` with `sinceSec`, or undefined when it has to be blamed again.
+ */
+export async function reusableBlame(repoPath, head, path, sinceSec) {
+    const store = load(repoPath);
+    const entry = store?.data.blame[path];
+    if (!store || !entry)
+        return undefined;
+    // Condition 3: a stored bound newer than the one asked for has collapsed
+    // lines the caller needs exactly.
+    if (entry.since !== null && (sinceSec === undefined || entry.since > sinceSec))
+        return undefined;
+    if (entry.head !== head) {
+        const touched = await touchedBetween(repoPath, entry.head, head);
+        if (touched === null || touched.has(path))
+            return undefined;
+        // The same observation at the new HEAD: re-key it, so the next run checks
+        // a shorter range.
+        entry.head = head;
+        store.dirty = true;
+    }
+    return new Map(entry.counts);
+}
+export function rememberBlame(repoPath, head, path, sinceSec, counts) {
+    const store = load(repoPath);
+    if (!store)
+        return;
+    store.data.blame[path] = { head, since: sinceSec ?? null, counts: [...counts] };
+    trim(store.data.blame, MAX_BLAME_PATHS);
+    store.dirty = true;
+}

package/dist/guide.js

@@ -65,16 +65,21 @@ export function buildGuide(f) {
                 ? envHints
                 : ['segreant scan --setup', 'segreant start', ...envHints],
     };
+    const capBasisSpend = f.capBasisSpend30dUsd ?? f.spend30dUsd;
     const cap = {
         id: 'cap',
         title: 'Cap it',
         done: f.dailyCapUsd !== null,
         state: f.dailyCapUsd !== null ? `daily hard cap $${f.dailyCapUsd}` : 'metering only — no enforcement',
         why: 'Metering without enforcement is a report, not governance. The proxy can actually say no.',
-        notice: f.spend30dUsd > 0
-            ? 'The recommendation uses your observed spend history.'
-            : 'Set a hard cap and optional soft threshold for governed spend.',
-        commands: f.spend30dUsd > 0
+        notice: capBasisSpend > 0
+            ? f.capBasis === 'all_observed'
+                ? 'The recommendation uses all observed spend, imported included, which is what your cap counts.'
+                : 'The recommendation uses your spend through the proxy, which is what a cap governs.'
+            : f.spend30dUsd > 0
+                ? 'Your spend so far was imported from agent logs, and a cap governs requests through the proxy. A recommendation needs a few days of proxied requests; set a cap by hand until then.'
+                : 'Set a hard cap and optional soft threshold for governed spend.',
+        commands: capBasisSpend > 0
             ? ['segreant budget --recommend', 'segreant budget --daily 25 --soft 18']
             : ['segreant budget --daily 25 --soft 18'],
     };

package/dist/plans/detect.js

@@ -0,0 +1,147 @@
+/**
+ * Which plan each tool runs on, read from the tool's own local files.
+ *
+ * Subscription usage is the main reason a Segreant number is a list-price
+ * estimate rather than a bill: a $20 plan can do hundreds of dollars of
+ * list-price work. Saying which plan a source is on lets every surface name
+ * both bases side by side ("your $20 plan did $X of list-price work").
+ *
+ * The plan is detected; the PRICE is never assumed. What a person pays depends
+ * on the channel (an App Store subscription costs more than the web one), tax,
+ * annual billing and discounts, so the price comes only from the person
+ * (`segreant plan set`). The public prices below are offered as a suggestion
+ * when asking, with their date, and never used as a figure.
+ *
+ * Reads only plan fields. Claude Code's plan comes from `~/.claude.json`
+ * (`oauthAccount`), never from the credentials file, which holds tokens.
+ */
+import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Public monthly prices, as a suggestion when asking only. Checked 2026-10-08. */
+export const PUBLIC_PLAN_PRICES = {
+    'claude-code:pro': 20,
+    'claude-code:max:5x': 100,
+    'claude-code:max:20x': 200,
+    'codex:plus': 20,
+    'codex:pro': 200,
+};
+export const PUBLIC_PLAN_PRICES_CHECKED = '2026-10-08';
+export const PLAN_LABELS = {
+    'claude-code': 'Claude',
+    codex: 'ChatGPT',
+};
+export function suggestedPrice(p) {
+    if (p.plan === null)
+        return null;
+    return PUBLIC_PLAN_PRICES[`${p.source}:${p.plan}${p.tier ? `:${p.tier}` : ''}`]
+        ?? PUBLIC_PLAN_PRICES[`${p.source}:${p.plan}`]
+        ?? null;
+}
+/** "Claude Max 20x", "ChatGPT Plus", or null when the plan is unknown. */
+export function planName(p) {
+    if (p.plan === null)
+        return null;
+    const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+    return `${PLAN_LABELS[p.source]} ${cap(p.plan)}${p.tier ? ` ${p.tier}` : ''}`;
+}
+export function detectClaudePlan(home = homedir()) {
+    const path = join(home, '.claude.json');
+    const none = (evidence) => ({ source: 'claude-code', plan: null, tier: null, billing: null, evidence });
+    if (!existsSync(path))
+        return none('no ~/.claude.json');
+    let account;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (parsed.oauthAccount === null || typeof parsed.oauthAccount !== 'object')
+            return none('~/.claude.json has no signed-in account (an API key, or signed out)');
+        account = parsed.oauthAccount;
+    }
+    catch {
+        return none('~/.claude.json could not be read');
+    }
+    const str = (k) => (typeof account[k] === 'string' && account[k] !== '' ? account[k] : null);
+    const orgType = str('organizationType');
+    const plan = orgType === null ? null : orgType.replace(/^claude_/, '');
+    // Max states its usage multiple in the rate-limit tier ("default_claude_max_20x").
+    const tierSource = str('userRateLimitTier') ?? str('organizationRateLimitTier') ?? '';
+    const tier = plan === 'max' ? (/(\d+x)\b/.exec(tierSource)?.[1] ?? null) : null;
+    return {
+        source: 'claude-code',
+        plan,
+        tier,
+        billing: str('billingType'),
+        evidence: orgType === null ? '~/.claude.json: no organizationType' : `~/.claude.json: organizationType ${orgType}`,
+    };
+}
+const PLAN_TYPE = /"plan_type":"([a-z_]+)"/g;
+/** The plan named in the newest Codex session log (its rate-limit events carry plan_type). */
+export function detectCodexPlan(root = join(homedir(), '.codex', 'sessions')) {
+    const none = (evidence) => ({ source: 'codex', plan: null, tier: null, billing: null, evidence });
+    const newest = newestJsonl(root);
+    if (newest === null)
+        return none('no Codex session logs');
+    const tail = readTail(newest, 512 * 1024);
+    let plan = null;
+    for (const m of tail.matchAll(PLAN_TYPE))
+        plan = m[1];
+    if (plan === null)
+        return none('the newest Codex session log names no plan');
+    return { source: 'codex', plan, tier: null, billing: null, evidence: 'newest Codex session log: plan_type ' + plan };
+}
+export function detectPlans() {
+    return [detectClaudePlan(), detectCodexPlan()];
+}
+/** Newest *.jsonl under a sessions/YYYY/MM/DD tree, walking newest directories first. */
+function newestJsonl(root) {
+    const dirsDesc = (dir) => {
+        try {
+            return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort().reverse();
+        }
+        catch {
+            return [];
+        }
+    };
+    const walk = (dir, depth) => {
+        if (depth === 0) {
+            let best = null;
+            let names = [];
+            try {
+                names = readdirSync(dir).filter((n) => n.endsWith('.jsonl'));
+            }
+            catch {
+                return null;
+            }
+            for (const n of names) {
+                const p = join(dir, n);
+                try {
+                    const m = statSync(p).mtimeMs;
+                    if (best === null || m > best.mtime)
+                        best = { path: p, mtime: m };
+                }
+                catch { /* gone */ }
+            }
+            return best?.path ?? null;
+        }
+        for (const d of dirsDesc(dir)) {
+            const hit = walk(join(dir, d), depth - 1);
+            if (hit !== null)
+                return hit;
+        }
+        return null;
+    };
+    return walk(root, 3);
+}
+function readTail(path, bytes) {
+    const fd = openSync(path, 'r');
+    try {
+        const size = statSync(path).size;
+        const len = Math.min(size, bytes);
+        const buf = Buffer.alloc(len);
+        readSync(fd, buf, 0, len, size - len);
+        return buf.toString('utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}