packmind 0.1.0

package/dist/cli/init.js

@@ -0,0 +1,83 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import chalk from "chalk";
+import { findRoot, isHome } from "../state/project.js";
+import { brain } from "../state/files.js";
+import { loadConfig } from "../state/schema.js";
+import { scanProject } from "../state/mapper.js";
+import { registerHooks, registerMcp } from "../adapters/claude-code.js";
+import { ensureDir } from "../util/paths.js";
+import { TEMPLATES_DIR, HOOKS_DIST_DIR, pkgVersion } from "./locate.js";
+import { registerProject } from "./registry.js";
+const CREATE_IF_MISSING = [
+    "config.json", "knowledge.md", "journal.md", "map.md", "handoff.md",
+    "solutions.json", "usage.json", "identity.md", "policy.json",
+];
+const ALWAYS_OVERWRITE = ["PACKMIND.md"];
+const HOOK_SCRIPTS = [
+    "runtime.js", "session-start.js", "prompt-submit.js", "pre-read.js",
+    "post-read.js", "pre-write.js", "post-write.js", "stop.js",
+];
+function copy(src, dest) {
+    if (fs.existsSync(src))
+        fs.writeFileSync(dest, fs.readFileSync(src));
+}
+function seed(name, dir, overwrite) {
+    const dest = path.join(dir, name);
+    if (!overwrite && fs.existsSync(dest))
+        return;
+    let content = fs.readFileSync(path.join(TEMPLATES_DIR, name), "utf8");
+    if (name === "usage.json")
+        content = content.replace('"createdAt": ""', `"createdAt": "${new Date().toISOString()}"`);
+    fs.writeFileSync(dest, content);
+}
+function wireClaudeMd(projectRoot, claudeMdRel) {
+    const target = path.join(projectRoot, claudeMdRel);
+    const snippet = fs.readFileSync(path.join(TEMPLATES_DIR, "claude-md-snippet.md"), "utf8");
+    let existing = "";
+    try {
+        existing = fs.readFileSync(target, "utf8");
+    }
+    catch {
+        /* missing */
+    }
+    if (existing.includes("PACKMIND:START"))
+        return;
+    ensureDir(path.dirname(target));
+    fs.writeFileSync(target, existing ? existing.replace(/\s*$/, "\n\n") + snippet : snippet);
+}
+export function runInit() {
+    const projectRoot = findRoot();
+    if (isHome(projectRoot)) {
+        console.error(chalk.red("✗ Refusing to initialize in your home directory. Run inside a project."));
+        process.exit(1);
+    }
+    const b = brain(projectRoot);
+    ensureDir(b.hooksDir);
+    ensureDir(path.join(b.dir, "state"));
+    ensureDir(b.recallDir);
+    const fresh = !fs.existsSync(b.config);
+    for (const f of CREATE_IF_MISSING)
+        seed(f, b.dir, false);
+    for (const f of ALWAYS_OVERWRITE)
+        seed(f, b.dir, true);
+    for (const script of HOOK_SCRIPTS)
+        copy(path.join(HOOKS_DIST_DIR, script), path.join(b.hooksDir, script));
+    copy(path.join(TEMPLATES_DIR, "hooks-package.json"), path.join(b.hooksDir, "package.json"));
+    copy(path.join(TEMPLATES_DIR, "gitattributes"), path.join(b.dir, ".gitattributes"));
+    const config = loadConfig(b.config);
+    registerHooks(path.join(projectRoot, config.claude.settingsPath));
+    registerMcp(path.join(projectRoot, ".mcp.json"));
+    wireClaudeMd(projectRoot, config.claude.claudeMdPath);
+    if (config.map.autoScanOnInit) {
+        const count = scanProject(projectRoot, config);
+        console.log(chalk.cyan(`• Mapped ${count} files into map.md`));
+    }
+    registerProject(projectRoot, pkgVersion());
+    console.log("\n" + chalk.bold.cyan("PackMind") + ` ${fresh ? "initialized" : "updated"} in ` +
+        chalk.bold(path.relative(process.cwd(), projectRoot) || ".") + "\n" +
+        `  ${chalk.green("✓")} .packmind/ created (map, knowledge, journal, usage, policy, recall)\n` +
+        `  ${chalk.green("✓")} Claude Code hooks registered (tagged _managedBy: packmind)\n` +
+        `  ${chalk.green("✓")} packmind MCP server registered in .mcp.json\n\n` +
+        `Run ${chalk.bold("packmind index")} to build the semantic index, then use ${chalk.bold("claude")} as normal.\n`);
+}

package/dist/cli/insights-cmd.js

@@ -0,0 +1,28 @@
+import chalk from "chalk";
+import * as path from "node:path";
+import { requireProject } from "./ctx.js";
+import { computeInsights } from "../cost/insights.js";
+export function runInsights() {
+    const { projectRoot, config } = requireProject();
+    const r = computeInsights(projectRoot, config);
+    console.log(chalk.bold.cyan("\nPackMind insights — ") + chalk.bold(path.basename(projectRoot)));
+    console.log(`  cost so far:     ${chalk.green("$" + r.totalCost.toFixed(4))} ` +
+        chalk.dim(`(${r.inputTokens.toLocaleString()} in / ${r.outputTokens.toLocaleString()} out)`));
+    console.log(`  est. saved:      ${chalk.green("$" + r.estCostSaved.toFixed(4))} ` +
+        chalk.dim(`(~${r.estTokensSaved.toLocaleString()} tokens, ${r.reReadsAvoided} re-reads avoided)`));
+    console.log(`  map coverage:    ${r.mapCoverage === null ? "—" : Math.round(r.mapCoverage * 100) + "%"}`);
+    if (r.topFiles.length) {
+        console.log(chalk.bold("\n  Heaviest files:"));
+        for (const f of r.topFiles) {
+            console.log(`    ${chalk.dim(f.tokens.toString().padStart(6))} tok  ${chalk.dim("$" + f.cost.toFixed(4))}  ${f.file}`);
+        }
+    }
+    if (r.flags.length) {
+        console.log(chalk.bold("\n  Notes:"));
+        for (const f of r.flags) {
+            const icon = f.level === "good" ? chalk.green("✓") : chalk.yellow("!");
+            console.log(`    ${icon} ${f.title} — ${chalk.dim(f.detail)}`);
+        }
+    }
+    console.log("");
+}

package/dist/cli/locate.js

@@ -0,0 +1,15 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+const here = path.dirname(fileURLToPath(import.meta.url)); // dist/cli at runtime
+export const PACKAGE_ROOT = path.resolve(here, "..", "..");
+export const TEMPLATES_DIR = path.join(PACKAGE_ROOT, "src", "templates");
+export const HOOKS_DIST_DIR = path.join(PACKAGE_ROOT, "dist", "hooks");
+export function pkgVersion() {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}

package/dist/cli/maintain-cmd.js

@@ -0,0 +1,39 @@
+import chalk from "chalk";
+import { requireProject } from "./ctx.js";
+import { scanProject } from "../state/mapper.js";
+import { consolidateJournal } from "../state/maintain.js";
+import { buildIndex } from "../recall/indexer.js";
+import { LocalEmbedder } from "../recall/embedder.js";
+import { pruneSnapshots } from "../state/snapshot.js";
+/**
+ * One-shot maintenance: refresh the map, rebuild the recall index, archive an
+ * overgrown journal, and prune old backups. Designed to be run from the user's
+ * own scheduler (cron/launchd) — no persistent daemon, no ports, no state to
+ * leak. `--quiet` suppresses output for unattended runs.
+ */
+export async function runMaintain(opts = {}) {
+    const { projectRoot, config } = requireProject();
+    const say = (m) => {
+        if (!opts.quiet)
+            console.log(m);
+    };
+    const files = scanProject(projectRoot, config);
+    say(chalk.cyan(`• map refreshed — ${files} files`));
+    if (config.recall.enabled) {
+        try {
+            const n = await buildIndex(projectRoot, config, new LocalEmbedder(config.recall.embedModel));
+            say(chalk.cyan(`• recall reindexed — ${n} chunks`));
+        }
+        catch (err) {
+            say(chalk.yellow(`• recall skipped — ${err.message.split("\n")[0]}`));
+        }
+    }
+    const archived = consolidateJournal(projectRoot);
+    if (archived)
+        say(chalk.cyan(`• journal archived — ${archived} old lines`));
+    const keep = opts.keepBackups ? parseInt(opts.keepBackups, 10) : 10;
+    const pruned = pruneSnapshots(projectRoot, keep);
+    if (pruned)
+        say(chalk.cyan(`• backups pruned — ${pruned} removed (kept ${keep})`));
+    say(chalk.green("✓ maintenance complete"));
+}

package/dist/cli/mcp-cmd.js

@@ -0,0 +1,5 @@
+import { runMcpServer } from "../mcp/server.js";
+/** Start the PackMind MCP server over stdio (invoked by Claude Code via .mcp.json). */
+export async function runMcp() {
+    await runMcpServer();
+}

package/dist/cli/policy-cmd.js

@@ -0,0 +1,40 @@
+import chalk from "chalk";
+import { requireProject } from "./ctx.js";
+import { readJsonOr } from "../util/fs-atomic.js";
+import { brain } from "../state/files.js";
+export function runPolicyCheck() {
+    const { projectRoot } = requireProject();
+    const policy = readJsonOr(brain(projectRoot).policy, {});
+    const rules = policy.rules ?? [];
+    let problems = 0;
+    console.log(chalk.bold.cyan(`\nPolicy: ${rules.length} rule(s)\n`));
+    for (const r of rules) {
+        const issues = [];
+        if (!r.id)
+            issues.push("missing id");
+        if (!r.message)
+            issues.push("missing message");
+        if (r.severity !== "warn" && r.severity !== "block")
+            issues.push("severity must be warn|block");
+        if (!r.secretFile && !r.pathGlob && !r.content)
+            issues.push("rule matches nothing (need secretFile/pathGlob/content)");
+        if (r.content) {
+            try {
+                new RegExp(r.content);
+            }
+            catch {
+                issues.push("invalid content regex");
+            }
+        }
+        if (issues.length) {
+            problems++;
+            console.log(`  ${chalk.red("✗")} ${r.id || "(no id)"} — ${issues.join("; ")}`);
+        }
+        else {
+            console.log(`  ${chalk.green("✓")} ${r.id} (${r.severity})`);
+        }
+    }
+    console.log("");
+    if (problems)
+        process.exit(1);
+}

package/dist/cli/recall-cmd.js

@@ -0,0 +1,18 @@
+import chalk from "chalk";
+import { requireProject } from "./ctx.js";
+import { recall } from "../recall/indexer.js";
+import { LocalEmbedder } from "../recall/embedder.js";
+export async function runRecall(query) {
+    const { projectRoot, config } = requireProject();
+    const embedder = new LocalEmbedder(config.recall.embedModel);
+    const hits = await recall(projectRoot, config, embedder, query);
+    if (hits.length === 0) {
+        console.log(chalk.dim("No matches. Run `packmind index` if you haven't yet."));
+        return;
+    }
+    for (const h of hits) {
+        console.log(chalk.bold.cyan(`\n[${h.kind}] `) + chalk.dim(h.source) + chalk.green(`  ${h.score.toFixed(2)}`));
+        console.log("  " + h.text.slice(0, 400).replace(/\n/g, "\n  "));
+    }
+    console.log("");
+}

package/dist/cli/registry.js

@@ -0,0 +1,32 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { userRoot } from "../util/platform.js";
+import { toPosix } from "../util/paths.js";
+import { readJsonOr, writeJson } from "../util/fs-atomic.js";
+function registryPath() {
+    return path.join(userRoot(), "registry.json");
+}
+function norm(root) {
+    return toPosix(path.resolve(root));
+}
+export function readRegistry() {
+    const list = readJsonOr(registryPath(), []);
+    return Array.isArray(list) ? list : [];
+}
+export function registerProject(root, version) {
+    const existing = readRegistry();
+    const prior = existing.find((e) => norm(e.root) === norm(root));
+    const kept = existing.filter((e) => norm(e.root) !== norm(root));
+    kept.push({
+        root: norm(root),
+        name: path.basename(path.resolve(root)),
+        registeredAt: prior?.registeredAt ?? new Date().toISOString(),
+        version,
+    });
+    writeJson(registryPath(), kept);
+}
+export function pruneRegistry() {
+    const kept = readRegistry().filter((e) => fs.existsSync(path.join(e.root, ".packmind")));
+    writeJson(registryPath(), kept);
+    return kept;
+}

package/dist/cli/scan.js

@@ -0,0 +1,18 @@
+import chalk from "chalk";
+import { requireProject } from "./ctx.js";
+import { buildMap, scanProject, countMapEntries, currentMapEntries } from "../state/mapper.js";
+export function runScan(opts = {}) {
+    const { projectRoot, config } = requireProject();
+    if (opts.check) {
+        const fresh = buildMap(projectRoot, config);
+        const drift = Math.abs(countMapEntries(fresh.content) - currentMapEntries(projectRoot));
+        if (drift > 0) {
+            console.error(chalk.yellow(`map.md is stale (${drift} file(s) differ). Run \`packmind scan\`.`));
+            process.exit(1);
+        }
+        console.log(chalk.green("✓ map.md is up to date."));
+        return;
+    }
+    const count = scanProject(projectRoot, config);
+    console.log(chalk.cyan(`✓ Mapped ${count} files into map.md`));
+}

package/dist/cli/solutions-cmd.js

@@ -0,0 +1,24 @@
+import chalk from "chalk";
+import { requireProject } from "./ctx.js";
+import { readJsonOr } from "../util/fs-atomic.js";
+import { brain } from "../state/files.js";
+export function runSolutions(term) {
+    const { projectRoot } = requireProject();
+    const all = readJsonOr(brain(projectRoot).solutions, []);
+    const q = term.toLowerCase();
+    const hits = all.filter((s) => [s.error, s.cause, s.fix, ...(s.tags ?? [])].filter(Boolean).join(" ").toLowerCase().includes(q));
+    if (hits.length === 0) {
+        console.log(chalk.dim(`No solutions matching "${term}".`));
+        return;
+    }
+    for (const s of hits) {
+        console.log(chalk.bold(`\n${s.id}`) + (s.tags?.length ? chalk.dim(`  [${s.tags.join(", ")}]`) : ""));
+        if (s.error)
+            console.log(`  error: ${s.error}`);
+        if (s.cause)
+            console.log(`  cause: ${s.cause}`);
+        if (s.fix)
+            console.log(`  fix:   ${chalk.green(s.fix)}`);
+    }
+    console.log("");
+}

package/dist/cli/status.js

@@ -0,0 +1,28 @@
+import chalk from "chalk";
+import * as path from "node:path";
+import { requireProject } from "./ctx.js";
+import { readLedger, totalCost } from "../cost/ledger.js";
+import { readTextOr } from "../util/fs-atomic.js";
+import { brain } from "../state/files.js";
+import { countMapEntries } from "../state/mapper.js";
+import { VectorStore } from "../recall/store.js";
+import { peekQueue } from "../recall/queue.js";
+export function runStatus() {
+    const { projectRoot, config } = requireProject();
+    const ledger = readLedger(projectRoot, config.model);
+    const t = ledger.totals;
+    const files = countMapEntries(readTextOr(brain(projectRoot).map));
+    const vectors = new VectorStore(brain(projectRoot).vectors).size();
+    const pending = peekQueue(projectRoot).length;
+    console.log(chalk.bold.cyan("\nPackMind — ") + chalk.bold(path.basename(projectRoot)));
+    console.log(`  model:     ${ledger.model}`);
+    console.log(`  map:       ${files} files`);
+    console.log(`  recall:    ${vectors} vectors indexed` + (pending ? chalk.dim(` (${pending} queued)`) : ""));
+    console.log(`  sessions:  ${t.sessions}`);
+    console.log(`  reads:     ${t.reads}  ` + chalk.dim(`(${t.dedupedReads} re-reads avoided, ${t.mapHits} map hits)`));
+    console.log(`  writes:    ${t.writes}`);
+    console.log(`  tokens:    ${t.inputTokens.toLocaleString()} in / ${t.outputTokens.toLocaleString()} out`);
+    console.log(`  ${chalk.bold("cost:")}      ${chalk.green("$" + totalCost(ledger).toFixed(4))} ` +
+        chalk.dim(`($${t.inputCost.toFixed(4)} in / $${t.outputCost.toFixed(4)} out)`));
+    console.log("");
+}

package/dist/cli/update.js

@@ -0,0 +1,73 @@
+import * as path from "node:path";
+import * as fs from "node:fs";
+import chalk from "chalk";
+import { readJsonOr, writeJson } from "../util/fs-atomic.js";
+import { DEFAULT_CONFIG, deepMerge } from "../state/schema.js";
+import { brain } from "../state/files.js";
+import { registerHooks, registerMcp } from "../adapters/claude-code.js";
+import { TEMPLATES_DIR, HOOKS_DIST_DIR, pkgVersion } from "./locate.js";
+import { pruneRegistry, registerProject } from "./registry.js";
+import { createSnapshot } from "../state/snapshot.js";
+const ALWAYS_OVERWRITE = ["PACKMIND.md"];
+const HOOK_SCRIPTS = [
+    "runtime.js", "session-start.js", "prompt-submit.js", "pre-read.js",
+    "post-read.js", "pre-write.js", "post-write.js", "stop.js",
+];
+function copy(src, dest) {
+    if (fs.existsSync(src))
+        fs.writeFileSync(dest, fs.readFileSync(src));
+}
+function updateOne(entry, dryRun) {
+    const b = brain(entry.root);
+    if (!fs.existsSync(b.dir)) {
+        console.log(chalk.dim(`  skip ${entry.name} (no .packmind/)`));
+        return;
+    }
+    if (dryRun) {
+        console.log(chalk.dim(`  would update ${entry.name}`));
+        return;
+    }
+    // Safety net: snapshot before mutating anything.
+    try {
+        createSnapshot(entry.root);
+    }
+    catch {
+        /* backup is best-effort; never block an update on it */
+    }
+    for (const f of ALWAYS_OVERWRITE)
+        copy(path.join(TEMPLATES_DIR, f), path.join(b.dir, f));
+    // config.json: deep-merge template defaults UNDER the user's existing config,
+    // preserving any values they customized while adding new keys.
+    const existing = readJsonOr(b.config, {});
+    writeJson(b.config, deepMerge(DEFAULT_CONFIG, existing));
+    fs.mkdirSync(b.hooksDir, { recursive: true });
+    for (const s of HOOK_SCRIPTS)
+        copy(path.join(HOOKS_DIST_DIR, s), path.join(b.hooksDir, s));
+    copy(path.join(TEMPLATES_DIR, "hooks-package.json"), path.join(b.hooksDir, "package.json"));
+    const config = deepMerge(DEFAULT_CONFIG, existing);
+    registerHooks(path.join(entry.root, config.claude.settingsPath));
+    registerMcp(path.join(entry.root, ".mcp.json"));
+    registerProject(entry.root, pkgVersion());
+    console.log(`  ${chalk.green("✓")} ${entry.name}`);
+}
+export function runUpdate(opts = {}) {
+    const projects = pruneRegistry();
+    if (opts.list) {
+        console.log(chalk.bold.cyan("\nRegistered projects:\n"));
+        for (const p of projects)
+            console.log(`  ${p.name}  ${chalk.dim(p.root)}  v${p.version}`);
+        console.log("");
+        return;
+    }
+    const targets = opts.project
+        ? projects.filter((p) => p.name === opts.project || p.root.includes(opts.project))
+        : projects;
+    if (targets.length === 0) {
+        console.log(chalk.dim("No matching projects."));
+        return;
+    }
+    console.log(chalk.bold.cyan(`\nUpdating ${targets.length} project(s) to v${pkgVersion()}...\n`));
+    for (const t of targets)
+        updateOne(t, !!opts.dryRun);
+    console.log("");
+}

package/dist/cost/estimator.js

@@ -0,0 +1,21 @@
+import * as path from "node:path";
+const CODE_EXT = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".py", ".rs", ".go", ".java", ".kt", ".c",
+    ".cpp", ".h", ".hpp", ".cs", ".rb", ".php", ".swift", ".scala", ".sh",
+    ".css", ".scss", ".sql", ".json", ".yaml", ".yml", ".toml", ".xml", ".html",
+]);
+/**
+ * Local, offline token estimate. Blends a character-rate model with a word
+ * count, which tracks real BPE tokenization more closely than chars alone
+ * (whitespace-dense code over-counts on chars; prose under-counts on words).
+ */
+export function estimateTokens(text, hint) {
+    if (!text)
+        return 0;
+    const ext = hint ? path.extname(hint).toLowerCase() : "";
+    const charsPerToken = CODE_EXT.has(ext) ? 3.5 : 4.0;
+    const byChars = text.length / charsPerToken;
+    const words = text.trim().length ? text.trim().split(/\s+/).length : 0;
+    const byWords = words / 0.75; // ~1.33 tokens per word
+    return Math.max(1, Math.round((byChars + byWords) / 2));
+}

package/dist/cost/exact.js

@@ -0,0 +1,35 @@
+/**
+ * Exact token counting via Anthropic's count-tokens endpoint. Used only by the
+ * CLI and MCP server (never in the synchronous hook path). Returns null when no
+ * API key is configured or the request fails — callers fall back to estimates.
+ */
+export async function countTokensExact(text, model) {
+    const key = process.env.ANTHROPIC_API_KEY;
+    if (!key || !text)
+        return null;
+    try {
+        const res = await fetch("https://api.anthropic.com/v1/messages/count_tokens", {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-api-key": key,
+                "anthropic-version": "2023-06-01",
+            },
+            body: JSON.stringify({ model, messages: [{ role: "user", content: text }] }),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return typeof data.input_tokens === "number" ? data.input_tokens : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function exactEnabled(mode) {
+    if (mode === "never")
+        return false;
+    if (mode === "always")
+        return true;
+    return Boolean(process.env.ANTHROPIC_API_KEY);
+}

package/dist/cost/insights.js

@@ -0,0 +1,80 @@
+import * as fs from "node:fs";
+import { brain } from "../state/files.js";
+import { readLedger, totalCost } from "./ledger.js";
+import { inputCost } from "./pricing.js";
+import { parseMap } from "../state/formats.js";
+import { readTextOr } from "../util/fs-atomic.js";
+import { peekQueue } from "../recall/queue.js";
+function sizeOf(p) {
+    try {
+        return fs.statSync(p).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function ageDays(p) {
+    try {
+        return (Date.now() - fs.statSync(p).mtimeMs) / 86_400_000;
+    }
+    catch {
+        return null;
+    }
+}
+/** Derive the "where are tokens going / being saved" picture from existing state. */
+export function computeInsights(projectRoot, config) {
+    const b = brain(projectRoot);
+    const ledger = readLedger(projectRoot, config.model);
+    const t = ledger.totals;
+    // Map: average file size + top files by cost.
+    const map = parseMap(readTextOr(b.map));
+    const entries = [];
+    let mapTokens = 0;
+    for (const [section, list] of map) {
+        for (const e of list) {
+            const cost = e.cost ?? inputCost(config.model, e.tokens);
+            entries.push({ file: section + e.file, tokens: e.tokens, cost });
+            mapTokens += e.tokens;
+        }
+    }
+    const avgFileTokens = entries.length ? mapTokens / entries.length : 0;
+    const topFiles = entries.sort((a, b2) => b2.tokens - a.tokens).slice(0, 5);
+    const mapCoverage = t.reads > 0 ? Math.min(1, t.mapHits / t.reads) : null;
+    // Conservative savings estimate: map hits avoid ~half a file read on average;
+    // each deduped re-read avoids a whole one.
+    const estTokensSaved = Math.round(t.mapHits * avgFileTokens * 0.5 + t.dedupedReads * avgFileTokens);
+    const estCostSaved = inputCost(config.model, estTokensSaved);
+    const flags = [];
+    if (t.dedupedReads > 0) {
+        flags.push({ level: "good", title: "Re-reads avoided", detail: `${t.dedupedReads} redundant reads skipped this project.` });
+    }
+    if (mapCoverage !== null && mapCoverage < 0.6 && t.reads >= 10) {
+        flags.push({ level: "warn", title: "Low map coverage", detail: `Only ${Math.round(mapCoverage * 100)}% of reads hit a map description — run \`packmind scan\`.` });
+    }
+    const pending = peekQueue(projectRoot).length;
+    if (pending > 0) {
+        flags.push({ level: "warn", title: "Recall index stale", detail: `${pending} file(s) changed since the last index — run \`packmind index\` or \`packmind maintain\`.` });
+    }
+    const journalKB = Math.round(sizeOf(b.journal) / 1024);
+    if (journalKB > 60) {
+        flags.push({ level: "warn", title: "Journal is large", detail: `journal.md is ${journalKB}KB — run \`packmind maintain\` to archive old entries.` });
+    }
+    const ka = ageDays(b.knowledge);
+    if (ka !== null && ka > 21) {
+        flags.push({ level: "warn", title: "Knowledge is stale", detail: `knowledge.md hasn't changed in ${Math.round(ka)} days — capture recent decisions with the \`remember\` tool.` });
+    }
+    return {
+        model: ledger.model,
+        totalCost: totalCost(ledger),
+        inputTokens: t.inputTokens,
+        outputTokens: t.outputTokens,
+        reads: t.reads,
+        writes: t.writes,
+        mapCoverage,
+        reReadsAvoided: t.dedupedReads,
+        estTokensSaved,
+        estCostSaved,
+        topFiles,
+        flags,
+    };
+}

package/dist/cost/ledger.js

@@ -0,0 +1,47 @@
+import { readJsonOr, writeJson } from "../util/fs-atomic.js";
+import { brain } from "../state/files.js";
+export function emptyLedger(model) {
+    return {
+        version: 1,
+        model,
+        createdAt: new Date().toISOString(),
+        totals: {
+            inputTokens: 0, outputTokens: 0, inputCost: 0, outputCost: 0,
+            reads: 0, writes: 0, sessions: 0, dedupedReads: 0, mapHits: 0,
+        },
+        sessions: [],
+    };
+}
+export function readLedger(projectRoot, model) {
+    return readJsonOr(brain(projectRoot).usage, emptyLedger(model));
+}
+export function totalCost(l) {
+    return l.totals.inputCost + l.totals.outputCost;
+}
+/** Fold a finished session into the lifetime ledger. */
+export function commitSession(projectRoot, model, s) {
+    const ledger = readLedger(projectRoot, model);
+    const reads = Object.keys(s.reads).length;
+    ledger.sessions.push({
+        id: s.id,
+        started: s.started,
+        ended: new Date().toISOString(),
+        inputTokens: s.inputTokens,
+        outputTokens: s.outputTokens,
+        inputCost: s.inputCost,
+        outputCost: s.outputCost,
+        reads,
+        writes: s.writes.length,
+    });
+    const t = ledger.totals;
+    t.inputTokens += s.inputTokens;
+    t.outputTokens += s.outputTokens;
+    t.inputCost += s.inputCost;
+    t.outputCost += s.outputCost;
+    t.reads += reads;
+    t.writes += s.writes.length;
+    t.sessions += 1;
+    t.dedupedReads += s.dedupedReads;
+    t.mapHits += s.mapHits;
+    writeJson(brain(projectRoot).usage, ledger);
+}

package/dist/cost/pricing.js

@@ -0,0 +1,27 @@
+export const PRICES = {
+    "claude-opus-4-8": { inputPerMTok: 15, outputPerMTok: 75 },
+    "claude-sonnet-4-6": { inputPerMTok: 3, outputPerMTok: 15 },
+    "claude-haiku-4-5": { inputPerMTok: 1, outputPerMTok: 5 },
+    "claude-fable-5": { inputPerMTok: 5, outputPerMTok: 25 },
+};
+function normalizeModel(model) {
+    const m = model.toLowerCase();
+    if (m.includes("opus"))
+        return "claude-opus-4-8";
+    if (m.includes("sonnet"))
+        return "claude-sonnet-4-6";
+    if (m.includes("haiku"))
+        return "claude-haiku-4-5";
+    if (m.includes("fable"))
+        return "claude-fable-5";
+    return "claude-opus-4-8";
+}
+export function rateFor(model) {
+    return PRICES[normalizeModel(model)] ?? PRICES["claude-opus-4-8"];
+}
+export function inputCost(model, tokens) {
+    return (tokens / 1_000_000) * rateFor(model).inputPerMTok;
+}
+export function outputCost(model, tokens) {
+    return (tokens / 1_000_000) * rateFor(model).outputPerMTok;
+}