hacklab 0.10.4 → 0.11.0

package/dist/prompt-consent.js

@@ -0,0 +1,167 @@
+import { createInterface } from 'node:readline';
+import { loadConfig, saveConfig } from './config.js';
+import { bold, dim, info } from './ui.js';
+/**
+ * Consent for uploading anything derived from the user's Claude Code
+ * conversations.
+ *
+ * Nothing conversation-derived leaves the machine until someone has answered
+ * this explicitly. The tiers are additive:
+ *
+ *   none   token counts only — exactly what the CLI did before this existed
+ *   stats  + prompt-length histogram and per-project prompt counts (numbers
+ *          only; no prompt text ever leaves the machine)
+ *   full   + a sample of the raw prompt text, so the backend can score how
+ *          technical the prompting is. It scores the sample and discards it.
+ *
+ * The answer is remembered in ~/.hacklab/config.json so the question is asked
+ * once, and can be changed or revoked at any time with
+ * `hacklab config prompt-stats <tier>`.
+ */
+export const PROMPT_CONSENT_TIERS = ['none', 'stats', 'full'];
+export function isPromptConsentTier(value) {
+    return (typeof value === 'string' &&
+        PROMPT_CONSENT_TIERS.includes(value));
+}
+/** The stored answer, or null when the user has never been asked. */
+export async function loadPromptConsent() {
+    const config = await loadConfig();
+    return isPromptConsentTier(config.promptStatsConsent)
+        ? config.promptStatsConsent
+        : null;
+}
+export async function savePromptConsent(tier) {
+    const config = await loadConfig();
+    config.promptStatsConsent = tier;
+    await saveConfig(config);
+}
+/**
+ * Read `--share-prompt-stats[=<tier>]` out of a command's args.
+ *
+ * This is the agent-friendly path: it answers the question up front so an
+ * unattended run never blocks on a prompt it can't see. Bare
+ * `--share-prompt-stats` means the numbers-only tier — the safe reading of an
+ * unqualified yes, since sending prompt *text* should always be deliberate.
+ * `--no-share-prompt-stats` is an explicit refusal.
+ *
+ * Returns the chosen tier, or null when the flag is absent. `rest` is the args
+ * with the flag removed so per-command parsing never sees it.
+ */
+export function parsePromptStatsFlag(args) {
+    const rest = [];
+    let tier = null;
+    for (const arg of args) {
+        if (arg === '--no-share-prompt-stats') {
+            tier = 'none';
+            continue;
+        }
+        if (arg === '--share-prompt-stats') {
+            tier = 'stats';
+            continue;
+        }
+        if (arg.startsWith('--share-prompt-stats=')) {
+            const value = arg.slice('--share-prompt-stats='.length);
+            tier = isPromptConsentTier(value) ? value : 'stats';
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { tier, rest };
+}
+/**
+ * Ask a yes/no question with no default: Enter alone re-asks, and only `y` or
+ * `n` settles it. Deliberately not @clack/prompts' confirm, which ships a
+ * highlighted default that can be accepted with a stray Enter — consent to
+ * upload conversation data should never be something you agree to by
+ * reflex.
+ *
+ * Returns null on a non-TTY stdin or EOF, which callers treat as "unanswered"
+ * rather than as a yes.
+ */
+export async function askYesNo(question) {
+    if (!process.stdin.isTTY)
+        return null;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        for (;;) {
+            const answer = await new Promise((resolve) => {
+                rl.question(`${question} ${dim('[y/n]')} `, (value) => resolve(value));
+                rl.once('close', () => resolve(null));
+            });
+            if (answer === null)
+                return null;
+            const normalized = answer.trim().toLowerCase();
+            if (normalized === 'y' || normalized === 'yes')
+                return true;
+            if (normalized === 'n' || normalized === 'no')
+                return false;
+            // Anything else (including a bare Enter) is not an answer.
+            console.log(dim('  please press y or n.'));
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+/** The disclosure. Printed verbatim before the first question. */
+function printDisclosure() {
+    console.log('');
+    console.log(bold('  share prompt stats?'));
+    console.log('');
+    info('  hacklab can read your local Claude Code history to chart how you prompt.');
+    info(`  it is read on this machine, from ${dim('~/.claude/projects')}.`);
+    console.log('');
+    info(`  ${bold('what would be uploaded')}`);
+    info('    how many prompts you have sent, and how long they are in words');
+    info('    a prompt count per project, matched by its git remote');
+    console.log('');
+    info(`  ${bold('what would not')}`);
+    info('    the text of your prompts, unless you separately say yes below');
+    info('    anything from a project without a git remote');
+    console.log('');
+    info(dim('  hacklab stores the numbers on your profile. you can change or revoke'));
+    info(dim('  this later with `hacklab config prompt-stats <none|stats|full>`.'));
+    console.log('');
+}
+/**
+ * Resolve the consent tier for this run.
+ *
+ * Precedence: an explicit flag wins (and is remembered), then the stored
+ * answer, then the interactive questions. An unattended run that has never
+ * answered gets `none` — silence is never consent.
+ */
+export async function resolvePromptConsent(flagTier, opts = {}) {
+    if (flagTier) {
+        await savePromptConsent(flagTier);
+        return flagTier;
+    }
+    const stored = await loadPromptConsent();
+    if (stored)
+        return stored;
+    if (!opts.interactive || !process.stdin.isTTY)
+        return 'none';
+    printDisclosure();
+    const shareNumbers = await askYesNo('  share these numbers with hacklab?');
+    if (shareNumbers === null)
+        return 'none';
+    if (!shareNumbers) {
+        await savePromptConsent('none');
+        console.log('');
+        info(dim('  no problem — syncing token counts only, as before.'));
+        return 'none';
+    }
+    console.log('');
+    info('  optional: a sample of your prompt text (up to 20k characters) can be');
+    info('  sent so an LLM can score how technical your prompting is. hacklab');
+    info(`  scores it and ${bold('discards it')} — the text is never stored.`);
+    console.log('');
+    const shareText = await askYesNo('  also send a sample of your prompt text?');
+    const tier = shareText === true ? 'full' : 'stats';
+    await savePromptConsent(tier);
+    console.log('');
+    info(dim(tier === 'full'
+        ? '  sharing prompt stats and a text sample.'
+        : '  sharing prompt stats. numbers only, no text.'));
+    return tier;
+}
+//# sourceMappingURL=prompt-consent.js.map

package/dist/prompt-consent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-consent.js","sourceRoot":"","sources":["../src/prompt-consent.ts"],"names":[],"mappings":"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"}

package/dist/prompt-stats.d.ts

@@ -0,0 +1,72 @@
+/** Buckets are `1..bucketMax`, so the axis stays readable at any prompt length. */
+export declare const PROMPT_LENGTH_BUCKET_MIN = 10;
+export declare const PROMPT_LENGTH_BUCKET_MAX = 100;
+/** The percentile that sets `bucketMax`; everything above lands in the overflow. */
+export declare const PROMPT_LENGTH_OVERFLOW_PERCENTILE = 0.9;
+/** Matches the backend's cap — anything longer is truncated before upload. */
+export declare const CONVERSATION_SAMPLE_MAX_CHARS = 20000;
+export type PromptStatsProject = {
+    repoUrl: string;
+    promptCount: number;
+    lastActiveAt: string;
+};
+export type PromptStats = {
+    totalPrompts: number;
+    bucketMax: number;
+    histogram: {
+        length: number;
+        count: number;
+    }[];
+    projects: PromptStatsProject[];
+    /** Only ever set under the `full` consent tier. */
+    conversationSample?: string;
+};
+/**
+ * The user's own prompt text from one transcript line, or null when the line
+ * isn't one.
+ *
+ * A transcript's `user` entries cover more than typed prompts: tool results
+ * come back as synthetic user turns too. Those carry `tool_result` content
+ * blocks, so a line only counts when its content is a plain string or an array
+ * of nothing but `text` blocks. Sidechain entries (subagent conversations) are
+ * the agent talking to itself, not the person typing, so they're excluded.
+ */
+export declare function promptTextFrom(entry: unknown): string | null;
+/** Whitespace-separated word count. Zero-word prompts are dropped by callers. */
+export declare function countWords(text: string): number;
+/**
+ * The overflow threshold for this user's own distribution: their p90 prompt
+ * length rounded up to a multiple of 10, clamped to [10, 100].
+ *
+ * Per-user rather than fixed because prompt length varies enormously between
+ * people — a fixed axis would either crush a terse user's histogram into the
+ * first two buckets or run a verbose one off the end.
+ */
+export declare function bucketMaxFor(wordCounts: number[]): number;
+/**
+ * Bucket the word counts. Buckets `1..bucketMax-1` are exact word counts; the
+ * bucket at `bucketMax` is the overflow, holding every prompt that long or
+ * longer. Empty buckets are omitted — the chart fills the gaps.
+ */
+export declare function buildHistogram(wordCounts: number[], bucketMax: number): {
+    length: number;
+    count: number;
+}[];
+/**
+ * The `origin` remote of the repo at `cwd`, or null when there isn't one (not
+ * a repo, no origin, no git binary, or the directory is gone). The URL is sent
+ * as-is; the backend normalizes it before matching against the user's own
+ * projects.
+ */
+export declare function gitOriginUrl(cwd: string): Promise<string | null>;
+/**
+ * Scan the local Claude Code transcripts.
+ *
+ * `includeSample` gates the raw prompt text: only the `full` consent tier
+ * passes true, and the sample never touches disk here — it goes straight into
+ * the upload payload the caller builds.
+ */
+export declare function scanPromptStats(options?: {
+    includeSample?: boolean;
+}): Promise<PromptStats | null>;
+//# sourceMappingURL=prompt-stats.d.ts.map

package/dist/prompt-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-stats.d.ts","sourceRoot":"","sources":["../src/prompt-stats.ts"],"names":[],"mappings":"AA6BA,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAC1C,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAC3C,oFAAoF;AACpF,eAAO,MAAM,iCAAiC,MAAM,CAAA;AACpD,8EAA8E;AAC9E,eAAO,MAAM,6BAA6B,QAAS,CAAA;AAEnD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC9C,QAAQ,EAAE,kBAAkB,EAAE,CAAA;IAC9B,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAwB5D;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAazD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAAE,EACpB,SAAS,EAAE,MAAM,GAChB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAUrC;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYtE;AAQD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAoF7B"}

package/dist/prompt-stats.js

@@ -0,0 +1,244 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { findFiles } from './scanners/util.js';
+/**
+ * Prompt statistics, computed entirely on this machine from the local Claude
+ * Code transcripts and uploaded only under an explicit consent tier (see
+ * prompt-consent.ts).
+ *
+ * Two numbers come out of a scan:
+ *
+ *   - a histogram of how long the user's own prompts are, in words
+ *   - a per-project prompt count, keyed by the project's git origin
+ *
+ * and, under the `full` tier only, a sample of the raw prompt text so the
+ * backend can score "how technical is this person's prompting". The backend
+ * scores that sample and throws it away; it is never stored.
+ *
+ * Everything here is deliberately best-effort: an unreadable transcript, a
+ * project that isn't a git repo, a missing `git` binary — each drops its own
+ * contribution and the rest of the scan still uploads.
+ */
+const execFileAsync = promisify(execFile);
+/** Buckets are `1..bucketMax`, so the axis stays readable at any prompt length. */
+export const PROMPT_LENGTH_BUCKET_MIN = 10;
+export const PROMPT_LENGTH_BUCKET_MAX = 100;
+/** The percentile that sets `bucketMax`; everything above lands in the overflow. */
+export const PROMPT_LENGTH_OVERFLOW_PERCENTILE = 0.9;
+/** Matches the backend's cap — anything longer is truncated before upload. */
+export const CONVERSATION_SAMPLE_MAX_CHARS = 20_000;
+/**
+ * The user's own prompt text from one transcript line, or null when the line
+ * isn't one.
+ *
+ * A transcript's `user` entries cover more than typed prompts: tool results
+ * come back as synthetic user turns too. Those carry `tool_result` content
+ * blocks, so a line only counts when its content is a plain string or an array
+ * of nothing but `text` blocks. Sidechain entries (subagent conversations) are
+ * the agent talking to itself, not the person typing, so they're excluded.
+ */
+export function promptTextFrom(entry) {
+    if (!entry || typeof entry !== 'object')
+        return null;
+    const line = entry;
+    if (line.type !== 'user')
+        return null;
+    if (line.isSidechain === true)
+        return null;
+    const content = line.message?.content;
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return null;
+    const texts = [];
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            return null;
+        const { type, text } = block;
+        // One non-text block (a tool_result, an image) disqualifies the whole
+        // entry: it isn't a prompt the person typed.
+        if (type !== 'text' || typeof text !== 'string')
+            return null;
+        texts.push(text);
+    }
+    return texts.length > 0 ? texts.join('\n') : null;
+}
+/** Whitespace-separated word count. Zero-word prompts are dropped by callers. */
+export function countWords(text) {
+    const matches = text.match(/\S+/g);
+    return matches ? matches.length : 0;
+}
+/**
+ * The overflow threshold for this user's own distribution: their p90 prompt
+ * length rounded up to a multiple of 10, clamped to [10, 100].
+ *
+ * Per-user rather than fixed because prompt length varies enormously between
+ * people — a fixed axis would either crush a terse user's histogram into the
+ * first two buckets or run a verbose one off the end.
+ */
+export function bucketMaxFor(wordCounts) {
+    if (wordCounts.length === 0)
+        return PROMPT_LENGTH_BUCKET_MIN;
+    const sorted = [...wordCounts].sort((a, b) => a - b);
+    const index = Math.min(sorted.length - 1, Math.floor(sorted.length * PROMPT_LENGTH_OVERFLOW_PERCENTILE));
+    const p90 = sorted[index] ?? PROMPT_LENGTH_BUCKET_MIN;
+    const rounded = Math.ceil(p90 / 10) * 10;
+    return Math.min(PROMPT_LENGTH_BUCKET_MAX, Math.max(PROMPT_LENGTH_BUCKET_MIN, rounded));
+}
+/**
+ * Bucket the word counts. Buckets `1..bucketMax-1` are exact word counts; the
+ * bucket at `bucketMax` is the overflow, holding every prompt that long or
+ * longer. Empty buckets are omitted — the chart fills the gaps.
+ */
+export function buildHistogram(wordCounts, bucketMax) {
+    const counts = new Map();
+    for (const words of wordCounts) {
+        if (words <= 0)
+            continue;
+        const bucket = words >= bucketMax ? bucketMax : words;
+        counts.set(bucket, (counts.get(bucket) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([length, count]) => ({ length, count }))
+        .sort((a, b) => a.length - b.length);
+}
+/**
+ * The `origin` remote of the repo at `cwd`, or null when there isn't one (not
+ * a repo, no origin, no git binary, or the directory is gone). The URL is sent
+ * as-is; the backend normalizes it before matching against the user's own
+ * projects.
+ */
+export async function gitOriginUrl(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', cwd, 'remote', 'get-url', 'origin'], { timeout: 5_000 });
+        const url = stdout.trim();
+        return url.length > 0 ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scan the local Claude Code transcripts.
+ *
+ * `includeSample` gates the raw prompt text: only the `full` consent tier
+ * passes true, and the sample never touches disk here — it goes straight into
+ * the upload payload the caller builds.
+ */
+export async function scanPromptStats(options = {}) {
+    const root = join(homedir(), '.claude', 'projects');
+    const files = await findFiles(root, '.jsonl');
+    if (files.length === 0)
+        return null;
+    const wordCounts = [];
+    const sampleParts = [];
+    let sampleChars = 0;
+    // Keyed by the transcript's project directory, which is Claude Code's own
+    // grouping. The directory name is a lossy encoding of the path, so the real
+    // working directory comes from the `cwd` recorded inside the entries.
+    const byProjectDir = new Map();
+    for (const filePath of files) {
+        const projectDir = dirname(filePath);
+        let project = byProjectDir.get(projectDir);
+        if (!project) {
+            project = { cwd: null, promptCount: 0, lastActiveAt: 0 };
+            byProjectDir.set(projectDir, project);
+        }
+        let content;
+        try {
+            content = await readFile(filePath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of content.split('\n')) {
+            if (!line.trim())
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const entry = parsed;
+            if (!project.cwd && typeof entry.cwd === 'string' && entry.cwd) {
+                project.cwd = entry.cwd;
+            }
+            const text = promptTextFrom(parsed);
+            if (text === null)
+                continue;
+            const words = countWords(text);
+            if (words <= 0)
+                continue;
+            wordCounts.push(words);
+            project.promptCount += 1;
+            if (typeof entry.timestamp === 'string') {
+                const at = Date.parse(entry.timestamp);
+                if (Number.isFinite(at) && at > project.lastActiveAt) {
+                    project.lastActiveAt = at;
+                }
+            }
+            if (options.includeSample &&
+                sampleChars < CONVERSATION_SAMPLE_MAX_CHARS) {
+                sampleParts.push(text);
+                sampleChars += text.length + 2;
+            }
+        }
+    }
+    if (wordCounts.length === 0)
+        return null;
+    const bucketMax = bucketMaxFor(wordCounts);
+    const stats = {
+        totalPrompts: wordCounts.length,
+        bucketMax,
+        histogram: buildHistogram(wordCounts, bucketMax),
+        projects: await resolveProjects(byProjectDir),
+    };
+    if (options.includeSample && sampleParts.length > 0) {
+        stats.conversationSample = sampleParts
+            .join('\n\n')
+            .slice(0, CONVERSATION_SAMPLE_MAX_CHARS);
+    }
+    return stats;
+}
+/**
+ * Turn the per-directory tallies into repo-keyed entries. Directories with no
+ * prompts, no recorded `cwd`, or no git origin drop out — the backend can only
+ * match a project by its repo URL, so an entry without one is dead weight.
+ *
+ * Two transcript directories can resolve to the same repo (the same project
+ * opened at different paths), so counts are summed per origin.
+ */
+async function resolveProjects(byProjectDir) {
+    const byRepo = new Map();
+    for (const project of byProjectDir.values()) {
+        if (project.promptCount === 0 || !project.cwd)
+            continue;
+        const repoUrl = await gitOriginUrl(project.cwd);
+        if (!repoUrl)
+            continue;
+        const existing = byRepo.get(repoUrl);
+        if (existing) {
+            existing.promptCount += project.promptCount;
+            existing.lastActiveAt = Math.max(existing.lastActiveAt, project.lastActiveAt);
+        }
+        else {
+            byRepo.set(repoUrl, {
+                promptCount: project.promptCount,
+                lastActiveAt: project.lastActiveAt,
+            });
+        }
+    }
+    return [...byRepo.entries()].map(([repoUrl, entry]) => ({
+        repoUrl,
+        promptCount: entry.promptCount,
+        // A transcript with no usable timestamp still happened; dating it now is
+        // more honest than dropping the project or claiming the epoch.
+        lastActiveAt: new Date(entry.lastActiveAt > 0 ? entry.lastActiveAt : Date.now()).toISOString(),
+    }));
+}
+//# sourceMappingURL=prompt-stats.js.map

package/dist/prompt-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-stats.js","sourceRoot":"","sources":["../src/prompt-stats.ts"],"names":[],"mappings":"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"}

package/dist/scanners/incremental.d.ts

@@ -0,0 +1,144 @@
+import { type AggregateScan, type ScanResult, type TokensMessages, type Tool, type UsageLine } from './index.js';
+export declare const SCAN_STATE_VERSION = 1;
+/** Where a file's tail-follow stands: what we saw, and how far we read. */
+export type FileState = {
+    size: number;
+    mtimeMs: number;
+    offset: number;
+};
+/** Codex only: the running total a session file has reported so far. */
+export type CodexFileState = {
+    maxTotal: number;
+    model: string;
+    date: string;
+};
+export type HarnessState = {
+    /** JSONL harnesses: per-file read cursor, keyed by absolute path. */
+    files: Record<string, FileState>;
+    /** Codex only: per-file running totals (see codexFileTotals). */
+    codexTotals?: Record<string, CodexFileState>;
+    /** SQLite harnesses: fingerprints of the db and its -wal. */
+    dbMtimeMs?: number;
+    walMtimeMs?: number;
+    /** "date|model" -> tokens/messages */
+    daily: Record<string, TokensMessages>;
+    /** "date|hour|model" -> tokens/messages */
+    hourly: Record<string, TokensMessages>;
+    /** model -> cumulative tokens */
+    models: Record<string, number>;
+};
+export type ScanState = {
+    version: number;
+    harnesses: Record<string, HarnessState>;
+    /**
+     * Dates whose rows changed since the last accepted upload. Dates, not
+     * (harness, date) pairs, because the server reconciles a synced date by
+     * deleting this machine's rows for that date that the payload didn't
+     * mention — so a date we touch has to go out complete, with every harness's
+     * rows for it. Cleared only on a 200, so a failed POST retries next tick.
+     */
+    dirty: string[];
+    /** Cumulative totals as of the last accepted upload. */
+    uploaded: {
+        toolTotals: Record<string, number>;
+        modelTotals: Record<string, number>;
+    };
+    /** 429 backoff: ticks before this epoch-ms do nothing. */
+    nextAllowedAt?: number;
+    /** The last failure written to sync.log, so a stuck tick can't fill it. */
+    lastError?: string;
+};
+/** Lives next to the session file, so it honors HACKLAB_SESSION_PATH. */
+export declare function scanStatePath(): string;
+export declare function emptyHarness(): HarnessState;
+export declare function emptyState(): ScanState;
+/**
+ * The saved state, or null when there isn't a usable one — missing, corrupt, or
+ * written by an older layout. Null means "re-read everything from scratch";
+ * callers must treat that rebuild as a baseline, not as new tokens.
+ */
+export declare function loadScanState(): Promise<ScanState | null>;
+/** Persist the state, pruning hourly buckets that fell out of the 90-day window
+ * the server keeps (they'd otherwise accumulate forever). Best-effort. */
+export declare function saveScanState(state: ScanState): Promise<void>;
+type Aggregates = {
+    daily: Record<string, TokensMessages>;
+    hourly: Record<string, TokensMessages>;
+    models: Record<string, number>;
+};
+/** A full scanner's result as the maps the state stores. */
+export declare function aggregatesOfResult(result: ScanResult): Aggregates;
+/**
+ * Read `[from, to)` and hand back only whole lines. A harness may be mid-append
+ * when we look, so the trailing partial line is left for the next tick — that's
+ * what the returned offset points at.
+ */
+export declare function readCompleteLines(path: string, from: number, to: number): Promise<{
+    text: string;
+    offset: number;
+}>;
+export type JsonlSource = {
+    tool: Tool;
+    files: () => Promise<string[]>;
+    parse: (line: string) => UsageLine | null;
+};
+export type CodexSource = {
+    files: () => Promise<string[]>;
+    /** Session date from the path layout, or null to fall back to the mtime day. */
+    dateFor: (path: string) => string | null;
+};
+export type SqliteSource = {
+    tool: Tool;
+    dbPath: () => string;
+    scan: () => Promise<ScanResult>;
+};
+export type TickSources = {
+    jsonl: JsonlSource[];
+    codex: CodexSource;
+    sqlite: SqliteSource[];
+};
+/** The real harnesses. Injectable so the tick can be tested against a tmp dir. */
+export declare function defaultSources(): TickSources;
+export type TickOutcome = {
+    state: ScanState;
+    /** Did anything on disk move? (If not, the state file isn't worth rewriting.) */
+    changed: boolean;
+};
+/**
+ * One incremental pass over every harness. `prev` is the saved state, or null
+ * for a cold start — in which case this reads everything and marks nothing
+ * dirty: those tokens are already on the server (the daily job put them there),
+ * and re-uploading every date would only invite the reconcile to prune rows
+ * this scan can't see (Cursor's, above all).
+ */
+export declare function runTick(prev: ScanState | null, sources?: TickSources): Promise<TickOutcome>;
+/** Cumulative per-tool and per-model totals for this machine. */
+export declare function cumulativeTotals(state: ScanState): {
+    toolTotals: Record<string, number>;
+    modelTotals: Record<string, number>;
+};
+export declare function sameTotals(a: Record<string, number>, b: Record<string, number>): boolean;
+/**
+ * What a tick uploads: cumulative tool/model totals (the server diffs those
+ * against its own per-machine snapshot) plus the daily and hourly rows for the
+ * dirty dates only.
+ *
+ * Every harness's rows go out for a dirty date, including Cursor's — which the
+ * tick never scans, and carries over from the last full scan instead. The
+ * server reconciles a date by deleting this machine's rows for it that the
+ * payload didn't mention, so a date has to be reported complete or the harnesses
+ * left out of it lose that day.
+ */
+export declare function tickPayload(state: ScanState): AggregateScan;
+/** Called on a 200: the dirty dates are on the server now. */
+export declare function markUploaded(state: ScanState): void;
+/**
+ * Rebuild the whole state from a full scan's results — the self-healing half of
+ * the design. Whatever the tick's tail-follow got wrong (a rotated log, a
+ * mid-file model switch, a Codex date guessed from an mtime) is corrected here,
+ * so incremental drift can never outlive a day. Best-effort: a state we failed
+ * to rebuild costs a tick, never the sync that just succeeded.
+ */
+export declare function rebuildScanState(results: ScanResult[], sources?: TickSources): Promise<void>;
+export {};
+//# sourceMappingURL=incremental.d.ts.map

package/dist/scanners/incremental.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incremental.d.ts","sourceRoot":"","sources":["../../src/scanners/incremental.ts"],"names":[],"mappings":"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"}