sealkeep 0.11.2 → 0.11.4

package/dist/src/doctor.js

@@ -297,6 +297,29 @@ export async function runDoctor(dataDir, env = process.env, home = env.HOME ?? e
     checks.push(detected.length > 0
         ? { name: "agents", status: "pass", detail: `Detected: ${detected.join(", ")}` }
         : { name: "agents", status: "warn", detail: "No supported agent directory found on this machine" });
+    // Recall is only useful if the agent believes it, and what an agent believes
+    // is its own memory directory rather than something pushed into its prompt.
+    // So report whether Sealkeep can write there, and whether it has.
+    {
+        const { hasMemorySurface, listWrittenNotes } = await import("./agent-memory.js");
+        const here = process.cwd();
+        const claude = agents.find((agent) => agent.agent === "claude" && agent.detected);
+        if (claude) {
+            const writable = await hasMemorySurface("claude", here, home);
+            const notes = writable ? await listWrittenNotes("claude", here, home) : [];
+            checks.push(writable
+                ? {
+                    name: "agent-memory-notes", status: "pass",
+                    detail: notes.length
+                        ? `${notes.length} preserved session${notes.length === 1 ? "" : "s"} written where Claude reads its own notes for this project`
+                        : "Claude's memory directory for this project is reachable; notes appear once a session here has been preserved",
+                }
+                : {
+                    name: "agent-memory-notes", status: "warn",
+                    detail: `Claude keeps no memory directory for ${here} yet, so preserved sessions can only reach it as injected context, which agents discount`,
+                });
+        }
+    }
     // A command in hooks.json is not proof that Codex will dispatch it. Codex
     // keeps enabled/trust state separately in config.toml and deliberately lets
     // the user disable a reviewed hook. Report that state without changing it;

package/dist/src/fork.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Fork a session instead of resuming it.
+ *
+ * Resuming a long session is the expensive mistake nobody warns you about: the
+ * whole transcript goes into every request, so a few questions on a months-old
+ * session can cost tens of millions of tokens without producing anything.
+ *
+ * The answer is not to delete the history. It is to stop carrying it in the
+ * prompt. This builds a small pack — what the session decided, what it was in
+ * the middle of, where to look for the rest — and hands you the command to
+ * start fresh with it. Everything else stays in Sealkeep, one search away.
+ *
+ * The promise only holds if the session really is recoverable, so this checks
+ * that before it suggests you walk away from one, and says plainly when it is
+ * not yet safe to.
+ */
+import { type SessionCost } from "./meter.js";
+export type ForkPlan = {
+    session: SessionCost;
+    /** Sealed into the vault, so the bytes survive. */
+    archiveId: string | null;
+    /** Searchable by content, so an agent can actually pull a detail back. */
+    searchable: boolean;
+    packPath: string;
+    markdown: string;
+    packTokens: number;
+    /** What one more step costs if you carry on in this session. */
+    resumeCostPerStep: number;
+    /** What one more step costs in a fresh session carrying the pack. */
+    freshCostPerStep: number;
+    savingPerStep: number;
+    freshCommand: string;
+    warnings: string[];
+};
+/**
+ * What did this session decide, and what was it in the middle of?
+ *
+ * Deliberately shallow: the last things a person asked, the last thing the
+ * agent said back, and the files it was touching. Anything deeper belongs in
+ * a search, not in every future prompt.
+ */
+export declare function distil(lines: string[]): {
+    asks: string[];
+    handoff: string;
+    files: string[];
+};
+/** The pack itself: small, plain, and honest about where the rest lives. */
+export declare function renderPack(input: {
+    session: SessionCost;
+    archiveId: string | null;
+    searchable: boolean;
+    asks: string[];
+    handoff: string;
+    files: string[];
+}): string;
+export type ForkOptions = {
+    /** A specific transcript. Defaults to the most expensive live session. */
+    file?: string;
+    hours?: number;
+    /** Where to write the pack. Defaults beside the project. */
+    out?: string;
+    /** Injected in tests. */
+    archives?: Array<{
+        id: string;
+        source: {
+            path?: string;
+        };
+    }>;
+    indexedPaths?: Set<string>;
+    roots?: {
+        claude?: string;
+        codex?: string;
+    };
+};
+/** Works out what forking this session would save, and whether it is safe to. */
+export declare function planFork(dataDir: string, options?: ForkOptions): Promise<ForkPlan | null>;
+export declare function writePack(plan: ForkPlan): Promise<string>;
+export declare function renderFork(plan: ForkPlan, written: boolean): string;

package/dist/src/fork.js

@@ -0,0 +1,197 @@
+/**
+ * Fork a session instead of resuming it.
+ *
+ * Resuming a long session is the expensive mistake nobody warns you about: the
+ * whole transcript goes into every request, so a few questions on a months-old
+ * session can cost tens of millions of tokens without producing anything.
+ *
+ * The answer is not to delete the history. It is to stop carrying it in the
+ * prompt. This builds a small pack — what the session decided, what it was in
+ * the middle of, where to look for the rest — and hands you the command to
+ * start fresh with it. Everything else stays in Sealkeep, one search away.
+ *
+ * The promise only holds if the session really is recoverable, so this checks
+ * that before it suggests you walk away from one, and says plainly when it is
+ * not yet safe to.
+ */
+import { open, stat, writeFile, mkdir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { meterSessions } from "./meter.js";
+const roughTokens = (text) => Math.ceil(text.length / 4);
+/** Reads the last slice of a file without loading gigabytes of transcript. */
+async function tail(file, bytes) {
+    const info = await stat(file);
+    const length = Math.min(bytes, info.size);
+    const handle = await open(file, "r");
+    try {
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, info.size - length);
+        return buffer.toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+const clean = (text) => text.replace(/\s+/g, " ").trim().slice(0, 600);
+/**
+ * What did this session decide, and what was it in the middle of?
+ *
+ * Deliberately shallow: the last things a person asked, the last thing the
+ * agent said back, and the files it was touching. Anything deeper belongs in
+ * a search, not in every future prompt.
+ */
+export function distil(lines) {
+    const asks = [];
+    const files = new Set();
+    let handoff = "";
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const payload = row.payload ?? row;
+        const role = row.type ?? payload.type ?? row.message?.role;
+        const content = row.message?.content ?? payload.content ?? payload.text;
+        const textOf = (value) => {
+            if (typeof value === "string")
+                return value;
+            if (Array.isArray(value)) {
+                return value.map((part) => (typeof part === "string" ? part : part?.text ?? "")).join(" ");
+            }
+            return "";
+        };
+        const text = textOf(content);
+        if (!text.trim())
+            continue;
+        if (role === "user" || row.message?.role === "user") {
+            // Plenty of things arrive wearing the user's role without a person
+            // having typed them: hook output, tool results, slash-command bodies,
+            // whole skill documents. A pack built from those is worse than useless,
+            // because it reads like instructions the person never gave.
+            if (/hook additional context|tool_result|<system-reminder>|<command-name>|<command-message>|<local-command-stdout>/i.test(text))
+                continue;
+            if (/^\s*#{1,3}\s|\n\s*#{2,3}\s/.test(text))
+                continue; // a pasted document, not a request
+            if (text.length > 1_500)
+                continue; // same, by weight
+            const said = clean(text);
+            if (said.length < 3)
+                continue;
+            asks.push(said);
+        }
+        else if (role === "assistant" || row.message?.role === "assistant") {
+            handoff = clean(text) || handoff;
+        }
+        for (const match of text.matchAll(/(?:^|[\s"'`(])((?:\/|\.\/|src\/|test\/)[\w./-]{3,80}\.\w{1,6})/g)) {
+            files.add(match[1]);
+        }
+    }
+    return { asks: asks.slice(-4), handoff, files: [...files].slice(-12) };
+}
+/** The pack itself: small, plain, and honest about where the rest lives. */
+export function renderPack(input) {
+    const blocks = [
+        `# Where this work is up to`,
+        `Carried over from a ${input.session.tool} session in ${basename(input.session.project) || input.session.project}, `
+            + `which had grown to ${Math.round(input.session.perStep / 1000)}k tokens a step. `
+            + `This is a summary, not the transcript. Treat it as background, and check anything important against the working tree.`,
+    ];
+    if (input.handoff)
+        blocks.push(`## Where it left off\n${input.handoff}`);
+    if (input.asks.length)
+        blocks.push(`## What was being asked for\n${input.asks.map((a) => `- ${a}`).join("\n")}`);
+    if (input.files.length)
+        blocks.push(`## Files it was working in\n${input.files.map((f) => `- ${f}`).join("\n")}`);
+    blocks.push(input.searchable
+        ? `## The rest of the history\nThe full session is preserved and searchable in Sealkeep${input.archiveId ? ` as archive ${input.archiveId}` : ""}. `
+            + `Do not ask for it to be pasted in. When you need a detail — why something was decided, what an earlier attempt did — use the Sealkeep MCP search, `
+            + `or \`sealkeep search "<terms>" --content\`, and pull back only that. That is the whole point of starting fresh: the history is one question away instead of in every prompt.`
+        : `## The rest of the history\nThis session is NOT yet preserved in Sealkeep, so nothing here can be searched back. `
+            + `Seal it first; until then the transcript on disk is the only copy.`);
+    return blocks.join("\n\n");
+}
+/** Works out what forking this session would save, and whether it is safe to. */
+export async function planFork(dataDir, options = {}) {
+    const summary = await meterSessions({ hours: options.hours ?? 24, roots: options.roots });
+    const session = options.file
+        ? summary.sessions.find((candidate) => candidate.file === options.file) ?? null
+        : summary.worst ?? null;
+    if (!session)
+        return null;
+    const archives = options.archives ?? await (async () => {
+        try {
+            const { listArchives } = await import("./vault.js");
+            return await listArchives(dataDir);
+        }
+        catch {
+            return [];
+        }
+    })();
+    const archive = archives.find((record) => record.source?.path === session.file) ?? null;
+    let searchable = options.indexedPaths ? options.indexedPaths.has(session.file) : false;
+    if (!options.indexedPaths && archive) {
+        try {
+            const { indexCoverage } = await import("./search.js");
+            const coverage = await indexCoverage(dataDir);
+            searchable = Boolean(coverage?.indexed);
+        }
+        catch {
+            searchable = false;
+        }
+    }
+    const text = await tail(session.file, 400_000).catch(() => "");
+    const { asks, handoff, files } = distil(text.split("\n"));
+    const markdown = renderPack({ session, archiveId: archive?.id ?? null, searchable, asks, handoff, files });
+    const warnings = [];
+    if (!archive)
+        warnings.push("This session is not sealed yet, so nothing could be searched back. Seal it before you abandon it.");
+    else if (!searchable)
+        warnings.push("This session is sealed but its contents are not indexed yet, so only metadata can be found. Run `sealkeep index build`.");
+    const packTokens = roughTokens(markdown);
+    const freshPerStep = packTokens + Math.round(session.fresh / Math.max(session.steps, 1));
+    const packPath = options.out ?? join(dirname(session.file), `sealkeep-pack-${basename(session.file, ".jsonl")}.md`);
+    const agent = session.tool === "codex" ? "codex" : "claude";
+    return {
+        session, archiveId: archive?.id ?? null, searchable,
+        packPath, markdown, packTokens,
+        resumeCostPerStep: session.perStep,
+        freshCostPerStep: freshPerStep,
+        savingPerStep: Math.max(0, session.perStep - freshPerStep),
+        freshCommand: `${agent} "$(cat ${packPath})"`,
+        warnings,
+    };
+}
+export async function writePack(plan) {
+    await mkdir(dirname(plan.packPath), { recursive: true }).catch(() => undefined);
+    await writeFile(plan.packPath, `${plan.markdown}\n`, "utf8");
+    return plan.packPath;
+}
+const tokens = (n) => n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${Math.round(n / 1e3)}k` : String(Math.round(n));
+export function renderFork(plan, written) {
+    const out = [
+        `The most expensive session you have open is the ${plan.session.tool} one in ${basename(plan.session.project) || plan.session.project}.`,
+        "",
+        `  carrying on there   ${tokens(plan.resumeCostPerStep).padStart(7)} tokens per step, ${Math.round(plan.session.historyShare * 100)}% of it re-read history`,
+        `  starting fresh      ${tokens(plan.freshCostPerStep).padStart(7)} tokens per step, carrying a ${tokens(plan.packTokens)}-token pack instead`,
+        `  you would save      ${tokens(plan.savingPerStep).padStart(7)} tokens on every step from here on`,
+        "",
+    ];
+    if (plan.warnings.length) {
+        out.push("Before you walk away from it:");
+        for (const warning of plan.warnings)
+            out.push(`  ! ${warning}`);
+        out.push("");
+    }
+    else {
+        out.push(`The full session is sealed${plan.archiveId ? ` (${plan.archiveId})` : ""} and searchable, so nothing is lost by leaving it.`, "");
+    }
+    out.push(written ? `Pack written to ${plan.packPath}` : `Pack (not written; pass --write):`);
+    out.push("", plan.markdown, "");
+    out.push("Start fresh with it:", `  ${plan.freshCommand}`);
+    return out.join("\n");
+}

package/dist/src/heartbeat.js

@@ -262,6 +262,10 @@ async function chooseCommonTarget(dataDir, chain, config, options = {}) {
         let additional = 0;
         let eligible = true;
         for (const item of chain.records) {
+            // A long chain can outlast the caller's idle deadline on its own, and
+            // every link here is a real step. Report it the same way the loop above
+            // does, so proving a destination never looks like a stall.
+            options.onProgress?.(0);
             if (!isV2(item)) {
                 eligible = false;
                 break;
@@ -389,10 +393,24 @@ export async function uploadAndOffloadPending(dataDir, options = {}) {
             continue;
         if (attempted >= limit)
             break;
+        // Choosing a destination is real work that moves no bytes: it resolves
+        // targets, walks every link of a chain and may ask the account whether a
+        // copy already matches. On a vault with thousands of archives that costs
+        // minutes before the first byte, and the daemon's idle deadline — which
+        // only ever sees byte progress — killed the pass at two minutes, every
+        // pass, forever. Measured on a real 5,062-archive vault: first byte at
+        // 168s against a 120s deadline, so automatic uploads could never run
+        // again. Tell the deadline that preparation is progress; a genuinely
+        // stalled transfer still trips it, because that reports no bytes either.
+        uploadOptions.onProgress?.(0);
         let targetId;
         if (chain) {
             if (!commonTargets.has(chain.rootId)) {
-                commonTargets.set(chain.rootId, await chooseCommonTarget(dataDir, chain, config, { clientProvided: Boolean(uploadOptions.client) }));
+                commonTargets.set(chain.rootId, await chooseCommonTarget(dataDir, chain, config, {
+                    clientProvided: Boolean(uploadOptions.client),
+                    onProgress: uploadOptions.onProgress,
+                }));
+                uploadOptions.onProgress?.(0);
             }
             const chosen = commonTargets.get(chain.rootId);
             if (!chosen) {

package/dist/src/local-api.js

@@ -212,6 +212,16 @@ const localSettingsSchema = z.object({
     trashStrategy: z.enum(TRASH_STRATEGIES).transform(canonicalStrategy).optional(),
     schedule: z.object({ intervalMinutes: z.number().min(1).max(1440) }).strict().optional(),
     bandwidth: z.object({ uploadLimitMbps: z.number().min(0).max(100_000).nullable() }).strict().optional(),
+    // What reaches the agent. Injection is convenient and it is re-read on every
+    // later step of a conversation, so it is a switch rather than a given.
+    recall: z.object({ autoInject: z.boolean() }).strict().optional(),
+    mcp: z.object({ enabled: z.boolean() }).strict().optional(),
+    // Ceilings for background work. A floor on each, because a limit below it
+    // would stall the work rather than pace it. null returns to automatic.
+    limits: z.object({
+        cpuPercent: z.number().min(5).max(100).nullable(),
+        memoryMb: z.number().int().min(128).max(65_536).nullable(),
+    }).strict().optional(),
     // 200 MB is the hard floor: below that, operating systems fail in ways no
     // archive tool should be the cause of. null returns to automatic.
     diskReserveMb: z.number().min(200).max(102_400).nullable().optional(),

package/dist/src/machine-settings.d.ts

@@ -24,6 +24,27 @@ export type LocalSettings = {
      * every sealed copy locally; 0 lets a verified duplicate leave immediately.
      */
     localArchiveCacheDays: number | null;
+    /**
+     * Whether preserved history is volunteered into a session, or only written
+     * as notes the agent reads for itself. Injection is convenient and it is not
+     * free: everything already in a conversation is re-read on every later
+     * request, so a block added early is paid for again on every step after it.
+     */
+    recall: {
+        autoInject: boolean;
+    };
+    /** The local MCP server that lets an agent search this vault by itself. */
+    mcp: {
+        enabled: boolean;
+    };
+    /**
+     * Ceilings for background work on this machine. null means Sealkeep picks a
+     * safe value; the network limit lives in `bandwidth` beside them.
+     */
+    limits: {
+        cpuPercent: number | null;
+        memoryMb: number | null;
+    };
 };
 /**
  * True when an automatic watcher must leave this transcript alone.
@@ -44,8 +65,16 @@ export declare function defaultLocalSettings(): LocalSettings;
 export declare const DEFAULT_BACKGROUND_UPLOAD_LIMIT_MBPS = 8;
 export declare function backgroundUploadBytesPerSecond(settings: Pick<LocalSettings, "bandwidth">): number;
 export declare const localSettingsPath: (dataDir: string) => string;
-/** Missing/older fields inherit safe defaults; this file is preferences, not cryptographic state. */
 export declare function readLocalSettings(dataDir: string): Promise<LocalSettings>;
+/**
+ * The ceilings this machine should actually use for background work.
+ *
+ * A person who sets one means "be gentle on this machine", so a setting only
+ * ever tightens what Sealkeep already chose — it never raises a limit past the
+ * safe automatic value, and null means "you decide".
+ */
+export declare function effectiveCpuTarget(settings: LocalSettings, automatic: number): number;
+export declare function effectiveMaxRssBytes(settings: LocalSettings, automatic: number): number;
 /** Atomic and owner-only: per-machine preferences are never synced. */
 export declare function writeLocalSettings(dataDir: string, settings: LocalSettings): Promise<void>;
 export declare function resolvedTrashStrategy(settings: LocalSettings): TrashResult["strategy"];

package/dist/src/machine-settings.js

@@ -110,6 +110,12 @@ export function defaultLocalSettings() {
         // A week keeps recent memory restorable while offline without allowing a
         // second, encrypted copy of the whole history to grow forever on disk.
         localArchiveCacheDays: 7,
+        // On by default: an agent that is handed its history at the start of a
+        // session is the product. It is deduplicated and never repeats itself, so
+        // the standing cost is small — but it is a cost, and it is switchable.
+        recall: { autoInject: true },
+        mcp: { enabled: true },
+        limits: { cpuPercent: null, memoryMb: null },
     };
 }
 /** Automatic work must not infer "unlimited" from an older settings file.
@@ -125,6 +131,12 @@ export function backgroundUploadBytesPerSecond(settings) {
 }
 export const localSettingsPath = (dataDir) => join(dataDir, "local-settings.json");
 /** Missing/older fields inherit safe defaults; this file is preferences, not cryptographic state. */
+/** A bounded number, or null for "let Sealkeep choose". */
+function boundedOrNull(value, low, high, fallback) {
+    if (value === null)
+        return null;
+    return typeof value === "number" && Number.isFinite(value) && value >= low && value <= high ? value : fallback;
+}
 export async function readLocalSettings(dataDir) {
     const fallback = defaultLocalSettings();
     try {
@@ -139,6 +151,15 @@ export async function readLocalSettings(dataDir) {
             exclusions: Array.isArray(saved?.exclusions) ? saved.exclusions.filter((path) => typeof path === "string") : [],
             schedule: { ...fallback.schedule, ...saved?.schedule },
             bandwidth: { ...fallback.bandwidth, ...saved?.bandwidth },
+            recall: { autoInject: typeof saved?.recall?.autoInject === "boolean" ? saved.recall.autoInject : fallback.recall.autoInject },
+            mcp: { enabled: typeof saved?.mcp?.enabled === "boolean" ? saved.mcp.enabled : fallback.mcp.enabled },
+            limits: {
+                // A floor of 5% and 128 MB, because a ceiling below those would stall
+                // rather than pace, and a person setting one means "be gentle", not
+                // "never finish".
+                cpuPercent: boundedOrNull(saved?.limits?.cpuPercent, 5, 100, fallback.limits.cpuPercent),
+                memoryMb: boundedOrNull(saved?.limits?.memoryMb, 128, 65_536, fallback.limits.memoryMb),
+            },
             localArchiveCacheDays: saved?.localArchiveCacheDays === null
                 ? null
                 : typeof saved?.localArchiveCacheDays === "number"
@@ -153,6 +174,25 @@ export async function readLocalSettings(dataDir) {
         return fallback;
     }
 }
+/**
+ * The ceilings this machine should actually use for background work.
+ *
+ * A person who sets one means "be gentle on this machine", so a setting only
+ * ever tightens what Sealkeep already chose — it never raises a limit past the
+ * safe automatic value, and null means "you decide".
+ */
+export function effectiveCpuTarget(settings, automatic) {
+    const asked = settings.limits?.cpuPercent;
+    if (typeof asked !== "number")
+        return automatic;
+    return Math.min(automatic, Math.max(0.05, asked / 100));
+}
+export function effectiveMaxRssBytes(settings, automatic) {
+    const asked = settings.limits?.memoryMb;
+    if (typeof asked !== "number")
+        return automatic;
+    return Math.min(automatic, Math.max(128, asked) * 1024 * 1024);
+}
 /** Atomic and owner-only: per-machine preferences are never synced. */
 export async function writeLocalSettings(dataDir, settings) {
     await mkdir(dataDir, { recursive: true, mode: 0o700 });

package/dist/src/mcp.js

@@ -325,5 +325,14 @@ registerTool("sealkeep_bridge_inbox", {
     const waiting = await pendingCount(dataDir, channel);
     return text({ channel, messages: pending, stillWaiting: waiting, context: promptInjection(pending, waiting) || null });
 });
+// The Settings page can turn this server off for a machine. Exiting cleanly is
+// the honest behaviour: the agent sees a server that is simply not there,
+// rather than one that answers every question with a refusal.
+const { readLocalSettings } = await import("./machine-settings.js");
+const mcpEnabled = await readLocalSettings(dataDir).then((settings) => settings.mcp.enabled).catch(() => true);
+if (!mcpEnabled) {
+    console.error("Sealkeep's local MCP server is switched off for this machine (Settings → Agent access).");
+    process.exit(0);
+}
 const transport = new StdioServerTransport();
 server.connect(transport).catch((error) => { console.error(error); process.exit(1); });

package/dist/src/meter.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The context meter — what this session is costing you, per step.
+ *
+ * An AI coding session charges you for its own history on every request. A
+ * conversation that has been alive for months carries its whole transcript
+ * into each step, so a one-line question costs whatever the transcript costs,
+ * and an agent loop pays that once per command. Nothing tells you until the
+ * limit is gone.
+ *
+ * Sealkeep already holds the session files, so it can answer the question
+ * nobody else can: what is each live session costing per step, how much of
+ * that is re-read history, and what would the same work cost in a fresh
+ * session carrying a small context pack instead of a transcript.
+ *
+ * Everything here reads local files only. No key, no network, nothing leaves
+ * the machine to produce a number.
+ */
+/** A fork carries rules, a statement of what is true now, and the last handoff. */
+export declare const CONTEXT_PACK_TOKENS = 3000;
+/** Each of these fired on a real machine the night the limits died. */
+export type Signal = "BLOATED" | "STALE" | "POLLING";
+export type SessionCost = {
+    tool: "claude" | "codex";
+    file: string;
+    project: string;
+    sizeMB: number;
+    ageDays: number;
+    steps: number;
+    tools: number;
+    sleeps: number;
+    /** Everything sent into the model: re-read history plus genuinely new text. */
+    input: number;
+    /** The re-read part. Discounted by providers, still counted by limits. */
+    cached: number;
+    fresh: number;
+    output: number;
+    perStep: number;
+    historyShare: number;
+    /** The same steps, in a fresh session carrying a context pack. */
+    freshCost: number;
+    saving: number;
+    signals: Signal[];
+};
+export type MeterSummary = {
+    hours: number;
+    sessions: SessionCost[];
+    totalInput: number;
+    totalFreshCost: number;
+    totalSaving: number;
+    savingShare: number;
+    worst?: SessionCost;
+    polling: SessionCost[];
+};
+/**
+ * Which sessions are worth saying something about. Thresholds are deliberately
+ * boring: each one was true of a real session that ended a weekly allowance.
+ */
+export declare function signalsFor(input: Pick<SessionCost, "historyShare" | "perStep" | "ageDays" | "sizeMB" | "sleeps">): Signal[];
+/** Turns raw counters into the numbers a person can act on. */
+export declare function scoreSession(raw: Omit<SessionCost, "perStep" | "historyShare" | "freshCost" | "saving" | "signals">): SessionCost;
+export type MeterOptions = {
+    hours?: number;
+    /** Override for tests; defaults to this machine's agent session directories. */
+    roots?: {
+        claude?: string;
+        codex?: string;
+    };
+    now?: number;
+};
+/** Reads local session files and scores every session touched in the window. */
+export declare function meterSessions(options?: MeterOptions): Promise<MeterSummary>;
+/** The receipt for one session, in the words a person would use. */
+export declare function renderReceipt(session: SessionCost): string;
+/** The whole picture, for `sealkeep meter`. */
+export declare function renderMeter(summary: MeterSummary): string;