freeharness 0.4.1

package/canonical/hooks/freeharness-cost-tracker.mjs

@@ -0,0 +1,1027 @@
+// FreeHarness cost tracker (Claude Code Stop / SessionEnd / SubagentStop hook).
+// Sums transcript token usage, prices it with cost-prices.json, and appends a cumulative
+// usage.jsonl snapshot on Stop/SessionEnd (last snapshot per session wins, so firing on every
+// Stop never double counts) plus a per-project telemetry.jsonl record on SessionEnd. On
+// SubagentStop it appends one line per finished subagent to a change's ledger.jsonl instead.
+// Never blocks: exit 0 on every path. Snapshot fields are additive-only once shipped.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** Per-session subagent scan bounds (never read an unbounded directory). */
+const MAX_SUBAGENT_FILE_BYTES = 64 * 1024 * 1024;
+const MAX_SUBAGENT_FILES = 200;
+
+/** Usage log path: FREEHARNESS_COST_LOG override, else ~/.claude/freeharness/cost/usage.jsonl. */
+function logPath() {
+  return process.env.FREEHARNESS_COST_LOG || path.join(os.homedir(), ".claude", "freeharness", "cost", "usage.jsonl");
+}
+
+/** Price table path: FREEHARNESS_COST_PRICES override, else cost-prices.json next to this script. */
+function pricesPath() {
+  return process.env.FREEHARNESS_COST_PRICES || path.join(HERE, "cost-prices.json");
+}
+
+/** All of stdin as text; empty when stdin is closed or not a pipe. */
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** Price table from `file`; missing or malformed yields an empty table (estimate degrades to 0 USD, never fails). */
+function loadPrices(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    const prices = parsed && typeof parsed.prices === "object" && parsed.prices ? parsed.prices : {};
+    return { prices, ok: Object.keys(prices).length > 0 };
+  } catch {
+    return { prices: {}, ok: false };
+  }
+}
+
+/** Price row for `model`: exact key, else the longest prefix key, else `default`. */
+function priceFor(prices, model) {
+  if (prices[model]) return prices[model];
+  let best;
+  for (const key of Object.keys(prices)) {
+    if (key !== "default" && model.startsWith(key) && (!best || key.length > best.length)) best = key;
+  }
+  return best ? prices[best] : prices.default;
+}
+
+/** Estimated USD for one bucket at `row`'s per-MTok prices (0 when no row). */
+function estimate(u, row) {
+  if (!row) return 0;
+  const per = (n, price) => (n * (Number(price) || 0)) / 1e6;
+  return per(u.input, row.input) + per(u.output, row.output) + per(u.cache_read, row.cache_read) + per(u.cache_write, row.cache_write);
+}
+
+/** @returns {{input:number,output:number,cache_read:number,cache_write:number,messages:number}} Zeroed bucket. */
+function bucket() {
+  return { input: 0, output: 0, cache_read: 0, cache_write: 0, messages: 0 };
+}
+
+/** Sums a transcript's token usage per model. Assistant messages may share one `message.id`; the last line per id wins, so nothing is counted twice. */
+function sumTranscript(file) {
+  const byModel = {};
+  const byTool = {};
+  let turns = 0;
+  let lines = 0;
+  let contextTokens = 0;
+  let contextModel = "";
+  let toolOutputChars = 0;
+  let toolCalls = 0;
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return { byModel, byTool, turns, lines, contextTokens, contextModel, toolOutputChars, toolCalls, found: false };
+  }
+  const seen = new Map(); // message.id -> { model, usage }
+  const toolNames = new Map(); // tool_use id -> name
+  let anon = 0;
+  for (const raw of text.split("\n")) {
+    if (!raw.trim()) continue;
+    lines += 1;
+    let rec;
+    try {
+      rec = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    const msg = rec && typeof rec === "object" ? rec.message : undefined;
+    if (rec.type === "user" && msg) {
+      const content = msg.content;
+      const isToolResult = Array.isArray(content) && content.length > 0 && content.every((c) => c && c.type === "tool_result");
+      if (!isToolResult) {
+        turns += 1;
+        continue;
+      }
+      // Tool output size, attributed to the tool that produced it (chars; ~4 chars per token).
+      for (const c of content) {
+        const chars = resultChars(c.content);
+        toolOutputChars += chars;
+        const name = toolNames.get(c.tool_use_id) || "unknown";
+        const t = (byTool[name] ??= { calls: 0, output_chars: 0 });
+        t.output_chars += chars;
+      }
+      continue;
+    }
+    if (msg && Array.isArray(msg.content)) {
+      for (const c of msg.content) {
+        if (c && c.type === "tool_use" && typeof c.name === "string") {
+          toolCalls += 1;
+          if (typeof c.id === "string") toolNames.set(c.id, c.name);
+          const t = (byTool[c.name] ??= { calls: 0, output_chars: 0 });
+          t.calls += 1;
+        }
+      }
+    }
+    if (!msg || !msg.usage || typeof msg.usage !== "object") continue;
+    const id = typeof msg.id === "string" && msg.id ? msg.id : `anon-${anon++}`;
+    const model = typeof msg.model === "string" && msg.model ? msg.model : "unknown";
+    seen.set(id, { model, usage: msg.usage });
+    // Prompt size of the latest assistant message = current context; a zero-usage trailing
+    // <synthetic> message never resets an already-observed context size.
+    const promptSize = (Number(msg.usage.input_tokens) || 0) + (Number(msg.usage.cache_read_input_tokens) || 0) + (Number(msg.usage.cache_creation_input_tokens) || 0);
+    if (promptSize > 0) {
+      contextTokens = promptSize;
+      contextModel = model;
+    }
+  }
+  for (const { model, usage } of seen.values()) {
+    const b = (byModel[model] ??= bucket());
+    b.input += Number(usage.input_tokens) || 0;
+    b.output += Number(usage.output_tokens) || 0;
+    b.cache_read += Number(usage.cache_read_input_tokens) || 0;
+    b.cache_write += Number(usage.cache_creation_input_tokens) || 0;
+    b.messages += 1;
+  }
+  return { byModel, byTool, turns, lines, contextTokens, contextModel, toolOutputChars, toolCalls, found: true };
+}
+
+/** Character count of a tool_result content. */
+function resultChars(content) {
+  if (typeof content === "string") return content.length;
+  if (!Array.isArray(content)) return 0;
+  let n = 0;
+  for (const b of content) if (b && typeof b.text === "string") n += b.text.length;
+  return n;
+}
+
+/** The `[suffix]` tag trailing a model id (e.g. `claude-fable-5-1[1m]` -> `"1m"`), or null. */
+function modelSuffix(model) {
+  const m = /\[([^\]]+)\]$/.exec(typeof model === "string" ? model : "");
+  return m ? m[1] : null;
+}
+
+/** Token window: an explicit `[1m]` suffix means 1,000,000, else the price row's `window`, defaulting to 200,000. */
+export function windowFor(model, prices) {
+  const raw = typeof model === "string" ? model : "";
+  if (/\[1m\]$/i.test(raw)) return 1_000_000;
+  const base = raw.replace(/\[[^\]]*\]$/, "");
+  const row = priceFor(prices, base || raw);
+  const w = row && Number.isInteger(row.window) && row.window > 0 ? row.window : null;
+  return w ?? 200_000;
+}
+
+/** User's Claude Code config directory: `CLAUDE_CONFIG_DIR` override, else `~/.claude`. */
+function userConfigDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+}
+
+/** settings.json's `model` field, or null when absent, unreadable or unset. */
+function settingsModel(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return parsed && typeof parsed.model === "string" && parsed.model ? parsed.model : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Configured model id: project `.claude/settings.json` `model`, else the user's. The transcript's own id is always bare; a suffix is visible only here. */
+function configuredModel(cwd) {
+  return settingsModel(path.join(cwd, ".claude", "settings.json")) ?? settingsModel(path.join(userConfigDir(), "settings.json"));
+}
+
+/** Subagent transcripts at `<dirname>/<session-id>/subagents/agent-<name>-<hash>.jsonl`; empty when the directory is missing. */
+export function subagentTranscripts(transcriptPath) {
+  if (!transcriptPath) return [];
+  const dir = path.dirname(transcriptPath);
+  const sessionId = path.basename(transcriptPath, path.extname(transcriptPath));
+  const subDir = path.join(dir, sessionId, "subagents");
+  let entries;
+  try {
+    entries = fs.readdirSync(subDir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    const m = /^agent-(.+)-[^-]+\.jsonl$/.exec(entry);
+    if (!m) continue;
+    out.push({ name: m[1], file: path.join(subDir, entry) });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Merges per-model sums into one `by_agent` bucket, picking the model with the most tokens (ties break alphabetically). */
+function mergeAgentUsage(byModel) {
+  const total = bucket();
+  let model = "unknown";
+  let bestTotal = -1;
+  for (const key of Object.keys(byModel).sort()) {
+    const u = byModel[key];
+    total.input += u.input;
+    total.output += u.output;
+    total.cache_read += u.cache_read;
+    total.cache_write += u.cache_write;
+    total.messages += u.messages;
+    const t = u.input + u.output + u.cache_read + u.cache_write;
+    if (t > bestTotal) {
+      bestTotal = t;
+      model = key;
+    }
+  }
+  return {
+    model,
+    usage: { input: total.input, output: total.output, cache_read: total.cache_read, cache_write: total.cache_write, total: total.input + total.output + total.cache_read + total.cache_write },
+    messages: total.messages,
+  };
+}
+
+/** Sanitizes a brief-header tag: trims, keeps only `[\w.\-/ ,()]`, caps at 64 chars. The brief is untrusted input to the telemetry tail. */
+function sanitizeTag(raw) {
+  return String(raw).trim().replace(/[^\w.\-/ ,()]/g, "").slice(0, 64).trim();
+}
+
+/** Tags a session from the newest `*.brief.md`: `Change:`, `Task:`, `Tier:`, `Class:`, sanitized. No brief yields every field null and `task_class: "untagged"`. */
+export function briefTags(cwd) {
+  const root = path.join(cwd, ".freeharness", "sdd");
+  let newest = null;
+  let newestMtime = -Infinity;
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith(".brief.md")) continue;
+      let stat;
+      try {
+        stat = fs.statSync(full);
+      } catch {
+        continue;
+      }
+      if (stat.mtimeMs > newestMtime || (stat.mtimeMs === newestMtime && (!newest || full > newest))) {
+        newestMtime = stat.mtimeMs;
+        newest = full;
+      }
+    }
+  };
+  walk(root);
+  const empty = { change: null, task: null, tier: null, task_class: "untagged" };
+  if (!newest) return empty;
+  let text;
+  try {
+    text = fs.readFileSync(newest, "utf8");
+  } catch {
+    return empty;
+  }
+  const field = (key) => {
+    const m = new RegExp(`^${key}:\\s*(.+)$`, "m").exec(text);
+    return m ? sanitizeTag(m[1]) : null;
+  };
+  const cls = field("Class");
+  return { change: field("Change"), task: field("Task"), tier: field("Tier"), task_class: cls || "untagged" };
+}
+
+/** `<role>-<task>[-r<round>][-<slug>]` dispatch name pattern; the slug distinguishes parallel reviewers of one round independent of the round number. */
+const DISPATCH_RE = /^(impl|review|fix)-(\d+(?:_\d+)*b?|final)(?:-r(\d+))?(?:-[a-z0-9]+(?:-[a-z0-9]+)*)?$/;
+
+/** Safe SubagentStop `agent_id` shape: no `/`, so it can never introduce a path segment. */
+const AGENT_ID_RE = /^[A-Za-z0-9_.-]+$/;
+
+/** Whether `target` sits strictly inside `dir`: false for `dir` itself or any escape. */
+function containedIn(dir, target) {
+  const rel = path.relative(dir, target);
+  return Boolean(rel) && !path.isAbsolute(rel) && rel.split(path.sep)[0] !== "..";
+}
+
+/** The real path of `p`, or `p` itself when it cannot be resolved. */
+function realPathOr(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/** Resolves a finished subagent's transcript. The untrusted `agent_id` must be a safe shape, and the resolved path must stay inside `subagents` both lexically and after `realpathSync`. */
+export function subagentTranscriptFor(transcriptPath, agentId, payload) {
+  if (!transcriptPath || !agentId || !AGENT_ID_RE.test(agentId)) return null;
+  const dir = path.dirname(transcriptPath);
+  const sessionId = path.basename(transcriptPath, path.extname(transcriptPath));
+  const subagentsDir = path.resolve(path.join(dir, sessionId, "subagents"));
+  const override = payload && typeof payload.agent_transcript_path === "string" && payload.agent_transcript_path ? payload.agent_transcript_path : null;
+  const candidate = override
+    ? path.isAbsolute(override)
+      ? path.resolve(override)
+      : path.resolve(subagentsDir, override)
+    : path.join(subagentsDir, `agent-${agentId}.jsonl`);
+  if (!containedIn(subagentsDir, candidate)) return null;
+  let real;
+  try {
+    real = fs.realpathSync(candidate);
+  } catch {
+    // Not on disk: the lexical fence above is the whole answer, and the caller reports the miss.
+    return candidate;
+  }
+  return containedIn(realPathOr(subagentsDir), real) ? candidate : null;
+}
+
+/** The `.meta.json` path next to a subagent transcript: the same path with its extension replaced. */
+function agentMetaPathFor(transcriptFile) {
+  const ext = path.extname(transcriptFile);
+  return `${ext ? transcriptFile.slice(0, -ext.length) : transcriptFile}.meta.json`;
+}
+
+/** A subagent's dispatch name and agent type; the model always comes from the transcript, never this file's alias (`sonnet`, `opus`). */
+export function readAgentMeta(file) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return { name: null, agentType: null };
+  }
+  const name = parsed && typeof parsed.name === "string" && parsed.name ? parsed.name : null;
+  const agentType = parsed && typeof parsed.agentType === "string" && parsed.agentType ? parsed.agentType : null;
+  return { name, agentType };
+}
+
+/** Dispatch name from `agent-<candidate>-<hash>.jsonl` when no meta names it; kept only if it, or with one leading `a` stripped, matches the dispatch pattern. */
+function fallbackDispatchName(base) {
+  const m = /^agent-(.+)-[^-]+\.jsonl$/.exec(base);
+  if (!m) return null;
+  const candidate = m[1];
+  if (DISPATCH_RE.test(candidate)) return candidate;
+  if (candidate.startsWith("a") && DISPATCH_RE.test(candidate.slice(1))) return candidate.slice(1);
+  return null;
+}
+
+/** Parses a dispatch name into role, task and round; underscores become dots (`impl-1_3b` -> `1.3b`). A non-matching name yields every field null. */
+export function parseDispatchName(name) {
+  const empty = { role: null, task: null, round: null };
+  if (typeof name !== "string" || !name) return empty;
+  const m = DISPATCH_RE.exec(name);
+  if (!m) return empty;
+  return { role: m[1], task: m[2] === "final" ? "final" : m[2].replace(/_/g, "."), round: m[3] ? Number(m[3]) : null };
+}
+
+/** Every `*.brief.md` under `.freeharness/sdd/`, with change directory and mtime; empty when the root is absent. */
+function changeBriefs(root) {
+  const out = [];
+  let topEntries;
+  try {
+    topEntries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const top of topEntries) {
+    if (!top.isDirectory()) continue;
+    const change = top.name;
+    const walk = (dir) => {
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+          continue;
+        }
+        if (!entry.isFile() || !entry.name.endsWith(".brief.md")) continue;
+        let stat;
+        try {
+          stat = fs.statSync(full);
+        } catch {
+          continue;
+        }
+        out.push({ file: full, mtimeMs: stat.mtimeMs, change });
+      }
+    };
+    walk(path.join(root, change));
+  }
+  return out;
+}
+
+/** An id token shaped like a dispatch task: digits and dots, an optional trailing batch `b`, or `final`. */
+const TASK_ID_RE = /^(?:\d+(?:\.\d+)*b?|final)$/;
+
+/** Whether a `Task:` header declares the task: exact match, a batch id token, or a `b` task matching the batch's first token (else `2.10` wrongly matches `2.1`). */
+function matchesTaskHeader(headerValue, task) {
+  const raw = headerValue.trim();
+  if (raw === task) return true;
+  const ids = raw
+    .split(/[,\s]+/)
+    .map((s) => s.trim())
+    .filter((s) => TASK_ID_RE.test(s));
+  if (ids.includes(task)) return true;
+  if (task.endsWith("b") && ids[0] === task.slice(0, -1)) return true;
+  return false;
+}
+
+/** Whether a `Change:` header names one contained directory (`sanitizeTag` keeps `.` and `/`, so `..` could otherwise escape it). */
+export function safeChangeSegment(root, change) {
+  if (!change || change.includes("/") || change.includes("\\") || change.includes("..")) return false;
+  return containedIn(root, path.resolve(root, change));
+}
+
+/** Ledger file for a dispatch task: the change whose brief declares the id, newest when several match; else the newest brief's own change. */
+export function ledgerPathFor(cwd, task, tags) {
+  const root = path.join(cwd, ".freeharness", "sdd");
+  if (task) {
+    let best = null;
+    for (const b of changeBriefs(root)) {
+      let text;
+      try {
+        text = fs.readFileSync(b.file, "utf8");
+      } catch {
+        continue;
+      }
+      const m = /^Task:\s*(.+)$/m.exec(text);
+      if (!m || !matchesTaskHeader(m[1], task)) continue;
+      if (!best || b.mtimeMs > best.mtimeMs || (b.mtimeMs === best.mtimeMs && b.file > best.file)) best = b;
+    }
+    if (best) return path.join(root, best.change, "ledger.jsonl");
+  }
+  if (tags && tags.change && safeChangeSegment(root, tags.change)) return path.join(root, tags.change, "ledger.jsonl");
+  return null;
+}
+
+/** Builds one dispatch ledger line, or a skip reason when the payload, transcript or brief is missing. Model is the transcript's dominant model, never the meta alias. */
+export function ledgerLine(payload, cwd, prices) {
+  const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
+  const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+  if (!agentId) return { ok: false, reason: "missing-payload" };
+  if (!AGENT_ID_RE.test(agentId)) return { ok: false, reason: "unsafe-agent-id" };
+  const file = subagentTranscriptFor(transcriptPath, agentId, payload);
+  if (!file) return { ok: false, reason: "missing-payload" };
+
+  let size;
+  try {
+    size = fs.statSync(file).size;
+  } catch {
+    return { ok: false, reason: "no-transcript", file };
+  }
+  if (size > MAX_SUBAGENT_FILE_BYTES) return { ok: false, reason: "too-large", file };
+
+  const sums = sumTranscript(file);
+  if (!sums.found) return { ok: false, reason: "no-transcript", file };
+
+  const merged = mergeAgentUsage(sums.byModel);
+  const est = estimate(merged.usage, priceFor(prices, merged.model));
+
+  const meta = readAgentMeta(agentMetaPathFor(file));
+  const name = meta.name || fallbackDispatchName(path.basename(file));
+  const agentType = meta.agentType ?? (typeof payload.agent_type === "string" && payload.agent_type ? payload.agent_type : null);
+  const parsed = parseDispatchName(name);
+
+  const tags = briefTags(cwd);
+  const ledgerFile = ledgerPathFor(cwd, parsed.task, tags);
+  if (!ledgerFile) {
+    const root = path.join(cwd, ".freeharness", "sdd");
+    const unsafe = Boolean(tags.change) && !safeChangeSegment(root, tags.change);
+    return { ok: false, reason: unsafe ? "unsafe-change" : "no-brief" };
+  }
+
+  const line = {
+    ts: new Date().toISOString(),
+    session: typeof payload.session_id === "string" ? payload.session_id : "",
+    agent_id: agentId,
+    name: name ?? null,
+    agent_type: agentType,
+    role: parsed.role,
+    task: parsed.task,
+    round: parsed.round,
+    model: merged.model,
+    input: merged.usage.input,
+    cache_read: merged.usage.cache_read,
+    cache_write: merged.usage.cache_write,
+    output: merged.usage.output,
+    est_usd: round(est),
+    late: false,
+    transcript: file,
+    resumed: false,
+  };
+  return { ok: true, file: ledgerFile, line };
+}
+
+/** Appends one ledger line; never creates the change directory (`ledgerPathFor` returns a path only once a brief lives there). */
+export function appendLedgerLine(file, line) {
+  fs.appendFileSync(file, `${JSON.stringify(line)}\n`, "utf8");
+}
+
+/** `agent_id`s already in a ledger file; unreadable or malformed lines contribute nothing rather than failing. */
+function readLedgerAgentIds(file) {
+  const ids = new Set();
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return ids;
+  }
+  for (const raw of text.split("\n")) {
+    if (!raw.trim()) continue;
+    try {
+      const rec = JSON.parse(raw);
+      if (rec && typeof rec.agent_id === "string") ids.add(rec.agent_id);
+    } catch {
+    }
+  }
+  return ids;
+}
+
+/** Backfills a `late: true` line for every subagent transcript whose `agent_id` never landed one (a crash or timeout can skip SubagentStop); failures push onto `snapshotWarnings`. */
+export function backfillLedger(payload, cwd, prices, snapshotWarnings) {
+  const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
+  if (!transcriptPath) return;
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : "";
+  const recorded = recordedAgentIds(cwd);
+  const done = new Set();
+  for (const { file } of subagentTranscripts(transcriptPath)) {
+    const m = /^agent-(.+)\.jsonl$/.exec(path.basename(file));
+    if (!m) continue;
+    const key = realPathOr(path.resolve(file));
+    if (done.has(key)) continue;
+    const result = ledgerLine({ transcript_path: transcriptPath, agent_id: m[1], session_id: sessionId, cwd }, cwd, prices);
+    if (!result.ok) continue;
+    if (recorded.has(result.line.agent_id)) continue;
+    const line = { ...result.line, late: true };
+    try {
+      appendLedgerLine(result.file, line);
+      recorded.add(line.agent_id);
+      done.add(key);
+    } catch (e) {
+      snapshotWarnings.push(`ledger backfill write failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+}
+
+/** Agent ids recorded in any ledger under the SDD workspace; the union across changes proves a transcript already has its line. */
+function recordedAgentIds(cwd) {
+  const ids = new Set();
+  const root = path.join(cwd, ".freeharness", "sdd");
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return ids;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    for (const id of readLedgerAgentIds(path.join(root, entry.name, "ledger.jsonl"))) ids.add(id);
+  }
+  return ids;
+}
+
+/** Counts dispatches per role, one distinct `agent_id` per dispatch so a resumed worker's second line adds nothing. */
+export function dispatchesByRole(cwd, sessionId) {
+  const counts = {};
+  if (!sessionId) return counts;
+  const root = path.join(cwd, ".freeharness", "sdd");
+  let topEntries;
+  try {
+    topEntries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return counts;
+  }
+  const seenByRole = new Map();
+  for (const top of topEntries) {
+    if (!top.isDirectory()) continue;
+    let text;
+    try {
+      text = fs.readFileSync(path.join(root, top.name, "ledger.jsonl"), "utf8");
+    } catch {
+      continue;
+    }
+    for (const raw of text.split("\n")) {
+      if (!raw.trim()) continue;
+      let rec;
+      try {
+        rec = JSON.parse(raw);
+      } catch {
+        continue;
+      }
+      if (!rec || rec.session !== sessionId || typeof rec.agent_id !== "string") continue;
+      const role = typeof rec.role === "string" && rec.role ? rec.role : "other";
+      let seen = seenByRole.get(role);
+      if (!seen) {
+        seen = new Set();
+        seenByRole.set(role, seen);
+      }
+      if (seen.has(rec.agent_id)) continue;
+      seen.add(rec.agent_id);
+      counts[role] = (counts[role] || 0) + 1;
+    }
+  }
+  return counts;
+}
+
+/** Memory database directory: `CLAUDE_MEM_DATA_DIR` when set, else `~/.claude-mem`. */
+function memoryDataDir() {
+  const env = process.env.CLAUDE_MEM_DATA_DIR;
+  if (env) return env.startsWith("~/") ? path.join(os.homedir(), env.slice(2)) : env;
+  return path.join(os.homedir(), ".claude-mem");
+}
+
+/** The `sqlite3` binary from an absolute PATH entry only, never a bare name handed to the child process's PATH search. */
+function resolveSqlite3() {
+  const bin = process.platform === "win32" ? "sqlite3.exe" : "sqlite3";
+  for (const dir of String(process.env.PATH || "").split(path.delimiter)) {
+    if (!dir || !path.isAbsolute(dir)) continue;
+    const candidate = path.join(dir, bin);
+    try {
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch {
+      // not in this PATH entry
+    }
+  }
+  return null;
+}
+
+/** Model ids naming metered Claude spend: `claude-*`, a bare tier alias, `$TIER:` (else `haiku` alone would file as free spend). */
+export function isClaudeModelId(model) {
+  return /^(?:claude|\$TIER:|(?:haiku|sonnet|opus)(?:-|$))/.test(model);
+}
+
+/** Observer discovery-token spend via a read-only `sqlite3` spawn; failures report as `{reason}`. Claude ids fold into subscription, others into `local`. */
+export function observerSink(sessionId, dataDir = memoryDataDir()) {
+  if (!sessionId) return { reason: "no session id" };
+  const db = path.join(dataDir, "claude-mem.db");
+  if (!fs.existsSync(db)) return { reason: `database not found: ${db}` };
+  const bin = resolveSqlite3();
+  if (!bin) return { reason: "sqlite3 not found on an absolute PATH entry" };
+  const escaped = String(sessionId).replace(/'/g, "''");
+  const sql = `SELECT COALESCE(o.generated_by_model, s.observed_model), COALESCE(SUM(o.discovery_tokens),0) FROM observations o JOIN sdk_sessions s ON o.memory_session_id = s.memory_session_id WHERE s.content_session_id = '${escaped}' GROUP BY 1;`;
+  let r;
+  try {
+    r = spawnSync(bin, ["-readonly", db, sql], { encoding: "utf8", timeout: 2000 });
+  } catch (e) {
+    return { reason: e instanceof Error ? e.message : String(e) };
+  }
+  if (!r || r.error) return { reason: r && r.error ? r.error.message : "spawn failed" };
+  if (r.status !== 0) return { reason: `sqlite3 exited ${r.status}: ${(r.stderr || "").trim().slice(0, 200)}` };
+  const claude = { tokens: 0, model: /** @type {string | null} */ (null), top: -1 };
+  const local = { tokens: 0, model: /** @type {string | null} */ (null), top: -1 };
+  for (const raw of (r.stdout || "").split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const [modelRaw, tokensRaw] = line.split("|");
+    const tokens = Number.parseInt(tokensRaw, 10);
+    if (!Number.isFinite(tokens)) continue;
+    const model = modelRaw && modelRaw.trim() ? modelRaw.trim() : null;
+    const bucket = model && isClaudeModelId(model) ? claude : local;
+    bucket.tokens += tokens;
+    if (tokens > bucket.top) {
+      bucket.top = tokens;
+      bucket.model = model;
+    }
+  }
+  return { tokens: claude.tokens, model: claude.model, local: { tokens: local.tokens, model: local.model } };
+}
+
+/** One pass over the usage log: earliest `ts` and the largest `context_tokens` seen (context can fall after a compaction, so the peak isn't just the last snapshot). */
+function sessionState(file, sessionId) {
+  if (!sessionId) return { started: null, contextMax: 0 };
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return { started: null, contextMax: 0 };
+  }
+  let started = null;
+  let contextMax = 0;
+  for (const raw of text.split("\n")) {
+    if (!raw.trim() || !raw.includes(sessionId)) continue;
+    try {
+      const rec = JSON.parse(raw);
+      if (!rec || rec.session_id !== sessionId) continue;
+      if (typeof rec.ts === "string" && (!started || rec.ts < started)) started = rec.ts;
+      const c = Number(rec.context_tokens) || 0;
+      if (c > contextMax) contextMax = c;
+    } catch {
+      // Malformed line: same tolerance as readUsage on the reader side.
+    }
+  }
+  return { started, contextMax };
+}
+
+/** Builds one telemetry record from the SessionEnd snapshot, brief tags and observer sink. An observer failure adds its reason to the warnings. */
+export function telemetryRecord(snapshot, tags, observer, warnings) {
+  const merged = Array.isArray(warnings) ? [...warnings] : [];
+  const observerOk = observer && typeof observer === "object" && Number.isFinite(observer.tokens);
+  if (!observerOk) merged.push(`observer sink unreadable: ${observer && observer.reason ? observer.reason : "unknown"}`);
+  const zero = { input: 0, output: 0, cache_read: 0, cache_write: 0, total: 0 };
+  const byTool = snapshot.by_tool || {};
+  const dispatchCalls = (name) => (byTool[name] && byTool[name].calls) || 0;
+  const estUsdMain = Number(snapshot.est_usd) || 0;
+  const estUsdSubagents = Number(snapshot.subagents_est_usd) || 0;
+  const dispatches = dispatchesByRole(typeof snapshot.cwd === "string" ? snapshot.cwd : "", typeof snapshot.session_id === "string" ? snapshot.session_id : "");
+  return {
+    ts: snapshot.ts,
+    session_id: snapshot.session_id,
+    project: snapshot.project,
+    started: snapshot.started ?? null,
+    ended: snapshot.ts,
+    turns: snapshot.turns ?? 0,
+    change: tags.change ?? null,
+    task: tags.task ?? null,
+    tier: tags.tier ?? null,
+    task_class: tags.task_class ?? "untagged",
+    sinks: {
+      main: snapshot.usage || zero,
+      subagents: snapshot.subagents || zero,
+      by_agent: snapshot.by_agent || {},
+      observer: observerOk ? { tokens: observer.tokens, model: observer.model ?? null } : null,
+      observer_local: observerOk ? { tokens: observer.local?.tokens ?? 0, model: observer.local?.model ?? null } : null,
+      tool_output_chars: snapshot.tool_output_chars ?? 0,
+      pruned_bytes: snapshot.pruned_bytes ?? 0,
+      // The subagent-dispatch tool is named "Agent" or "Task" depending on the client build.
+      agent_calls: dispatchCalls("Agent") + dispatchCalls("Task"),
+    },
+    est_usd: round(estUsdMain + estUsdSubagents),
+    est_usd_main: estUsdMain,
+    est_usd_subagents: estUsdSubagents,
+    context_max: snapshot.context_max ?? snapshot.context_tokens ?? 0,
+    context_window: snapshot.context_window ?? 200_000,
+    context_window_source: snapshot.context_window_source ?? "model",
+    ...(Object.keys(dispatches).length > 0 ? { dispatches_by_role: dispatches } : {}),
+    warnings: merged,
+  };
+}
+
+/** Appends one telemetry record when `.freeharness/` already exists; never creates it. A write failure lands as a snapshot warning. */
+function writeTelemetryIfPossible(record, payload, tags) {
+  const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+  const dir = path.join(cwd, ".freeharness");
+  let exists = false;
+  try {
+    exists = fs.statSync(dir).isDirectory();
+  } catch {
+    exists = false;
+  }
+  if (!exists) return;
+  const sessionId = typeof record.session_id === "string" ? record.session_id : "";
+  const observer = observerSink(sessionId);
+  const { started, contextMax: priorMax } = sessionState(logPath(), sessionId);
+  const contextMax = Math.max(priorMax, Number(record.context_tokens) || 0);
+  const tel = telemetryRecord({ ...record, started, context_max: contextMax }, tags, observer, Array.isArray(record.warnings) ? record.warnings : []);
+  try {
+    fs.appendFileSync(path.join(dir, "telemetry.jsonl"), `${JSON.stringify(tel)}\n`, "utf8");
+  } catch (e) {
+    const msg = `telemetry write failed: ${e instanceof Error ? e.message : String(e)}`;
+    record.warnings = Array.isArray(record.warnings) ? [...record.warnings, msg] : [msg];
+  }
+}
+
+/** Bytes the output pruner recovered: the sum of `{kind:"pruned"}` lines with this session id in the cost log. */
+export function prunedBytesFor(sessionId) {
+  if (!sessionId) return 0;
+  let text;
+  try {
+    text = fs.readFileSync(logPath(), "utf8");
+  } catch {
+    return 0;
+  }
+  let total = 0;
+  for (const raw of text.split("\n")) {
+    if (!raw.includes('"pruned"') || !raw.includes(sessionId)) continue;
+    try {
+      const rec = JSON.parse(raw);
+      if (rec && rec.kind === "pruned" && rec.session_id === sessionId) total += Number(rec.bytes) || 0;
+    } catch {
+      // skip
+    }
+  }
+  return total;
+}
+
+/** Builds the usage line for one hook invocation. `tags` is a param so `main()` computes it once and reuses it. */
+export function buildRecord(payload, tags) {
+  const pricesFile = pricesPath();
+  const { prices, ok: pricesOk } = loadPrices(pricesFile);
+  const transcript = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
+  const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+  const sums = transcript
+    ? sumTranscript(transcript)
+    : { byModel: {}, byTool: {}, turns: 0, lines: 0, contextTokens: 0, contextModel: "", toolOutputChars: 0, toolCalls: 0, found: false };
+  const total = bucket();
+  const byModel = {};
+  let usd = 0;
+  for (const [model, u] of Object.entries(sums.byModel)) {
+    const est = estimate(u, priceFor(prices, model));
+    usd += est;
+    byModel[model] = { ...u, est_usd: round(est) };
+    total.input += u.input;
+    total.output += u.output;
+    total.cache_read += u.cache_read;
+    total.cache_write += u.cache_write;
+    total.messages += u.messages;
+  }
+
+  // Subagent transcripts stay in their own bucket; `usage` above is main-only. Repeated
+  // dispatches of one agent name pool per-model sums, merged once. A transcript over 64 MB or
+  // past the 200th file is skipped with a warning: an unbounded scan would block the hook.
+  const subagentFiles = transcript ? subagentTranscripts(transcript) : [];
+  const by_agent = {};
+  const subagentsTotal = bucket();
+  let subagentsUsd = 0;
+  const perAgentModelSums = {};
+  const dispatchCounts = {};
+  let subagentsScanned = 0;
+  let subagentsSkippedLarge = 0;
+  let subagentsSkippedCap = 0;
+  for (const { name, file } of subagentFiles) {
+    if (subagentsScanned >= MAX_SUBAGENT_FILES) {
+      subagentsSkippedCap += 1;
+      continue;
+    }
+    let size;
+    try {
+      size = fs.statSync(file).size;
+    } catch {
+      continue;
+    }
+    if (size > MAX_SUBAGENT_FILE_BYTES) {
+      subagentsSkippedLarge += 1;
+      continue;
+    }
+    const subSums = sumTranscript(file);
+    if (!subSums.found) continue;
+    subagentsScanned += 1;
+    dispatchCounts[name] = (dispatchCounts[name] || 0) + 1;
+    const acc = (perAgentModelSums[name] ??= {});
+    for (const [model, u] of Object.entries(subSums.byModel)) {
+      const b = (acc[model] ??= bucket());
+      b.input += u.input;
+      b.output += u.output;
+      b.cache_read += u.cache_read;
+      b.cache_write += u.cache_write;
+      b.messages += u.messages;
+      subagentsUsd += estimate(u, priceFor(prices, model));
+    }
+  }
+  for (const [name, byModelForAgent] of Object.entries(perAgentModelSums)) {
+    const merged = mergeAgentUsage(byModelForAgent);
+    by_agent[name] = { ...merged, dispatches: dispatchCounts[name] };
+    subagentsTotal.input += merged.usage.input;
+    subagentsTotal.output += merged.usage.output;
+    subagentsTotal.cache_read += merged.usage.cache_read;
+    subagentsTotal.cache_write += merged.usage.cache_write;
+  }
+
+  // The transcript's model id never carries a `[1m]` suffix, so one from settings.json is
+  // folded on before resolving the window. A context past the resolved window raises it to
+  // 1,000,000 rather than silently clipping it; `context_window_source` names the origin.
+  const contextModel = sums.contextModel || Object.keys(sums.byModel).sort()[0] || "unknown";
+  const configured = configuredModel(cwd);
+  const configuredSuffix = configured ? modelSuffix(configured) : null;
+  let windowModel;
+  if (modelSuffix(contextModel) || !configuredSuffix) {
+    windowModel = contextModel;
+  } else {
+    windowModel = `${contextModel}[${configuredSuffix}]`;
+  }
+  let context_window = windowFor(windowModel, prices);
+  let model_suffix = modelSuffix(windowModel);
+  let context_window_source = modelSuffix(contextModel) ? "model" : configuredSuffix ? "settings" : "model";
+  const resolvedTags = tags || briefTags(cwd);
+
+  const warnings = [];
+  if (!transcript) warnings.push("no transcript_path in payload");
+  else if (!sums.found) warnings.push(`transcript not readable: ${transcript}`);
+  if (!pricesOk) warnings.push(`price table not loaded: ${pricesFile}`);
+  if (subagentsSkippedLarge > 0) warnings.push(`${subagentsSkippedLarge} subagent transcript(s) over 64 MB skipped`);
+  if (subagentsSkippedCap > 0) warnings.push(`subagent transcript scan capped at ${MAX_SUBAGENT_FILES} files; ${subagentsSkippedCap} skipped`);
+  if (context_window < 1_000_000 && sums.contextTokens > context_window) {
+    context_window = 1_000_000;
+    model_suffix = null;
+    context_window_source = "inferred";
+    warnings.push("context exceeded the resolved window; assumed 1m");
+  }
+  const record = {
+    ts: new Date().toISOString(),
+    event: typeof payload.hook_event_name === "string" ? payload.hook_event_name : "Stop",
+    session_id: typeof payload.session_id === "string" ? payload.session_id : "",
+    project: path.basename(cwd),
+    cwd,
+    transcript,
+    models: Object.keys(byModel).sort(),
+    usage: {
+      input: total.input,
+      output: total.output,
+      cache_read: total.cache_read,
+      cache_write: total.cache_write,
+      total: total.input + total.output + total.cache_read + total.cache_write,
+    },
+    by_model: byModel,
+    turns: sums.turns,
+    assistant_messages: total.messages,
+    est_usd: round(usd),
+    prices_file: pricesFile,
+    cumulative: true,
+    task_class: resolvedTags.task_class,
+    pruned_bytes: prunedBytesFor(typeof payload.session_id === "string" ? payload.session_id : ""),
+    context_tokens: sums.contextTokens,
+    tool_calls: sums.toolCalls,
+    tool_output_chars: sums.toolOutputChars,
+    by_tool: sums.byTool,
+    by_agent,
+    subagents: {
+      input: subagentsTotal.input,
+      output: subagentsTotal.output,
+      cache_read: subagentsTotal.cache_read,
+      cache_write: subagentsTotal.cache_write,
+      total: subagentsTotal.input + subagentsTotal.output + subagentsTotal.cache_read + subagentsTotal.cache_write,
+    },
+    subagents_est_usd: round(subagentsUsd),
+    context_window,
+    model_suffix,
+    context_window_source,
+  };
+  if (warnings.length > 0) record.warnings = warnings;
+  return record;
+}
+
+/** Rounds to 6 decimals (micro-dollars are enough for per-session estimates). */
+function round(n) {
+  return Math.round(n * 1e6) / 1e6;
+}
+
+/** Appends one record to the usage log, creating the directory on first use. */
+export function appendRecord(record) {
+  const file = logPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, `${JSON.stringify(record)}\n`, "utf8");
+  return file;
+}
+
+/** Entry point: parse stdin, build, append; never throws out. */
+function main() {
+  let payload = {};
+  try {
+    const raw = readStdin();
+    if (raw.trim()) {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") payload = parsed;
+    }
+  } catch {
+    payload = {};
+  }
+  try {
+    const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+    if (payload.hook_event_name === "SubagentStop") {
+      const { prices } = loadPrices(pricesPath());
+      const result = ledgerLine(payload, cwd, prices);
+      if (result.ok) {
+        const recorded = readLedgerAgentIds(result.file);
+        const line = { ...result.line, resumed: recorded.has(result.line.agent_id) };
+        try {
+          appendLedgerLine(result.file, line);
+        } catch (e) {
+          process.stderr.write(`freeharness-cost-tracker: ledger write failed: ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+      } else if (result.reason === "unsafe-agent-id") {
+        process.stderr.write("freeharness-cost-tracker: SubagentStop agent_id refused\n");
+      } else if (result.reason === "missing-payload") {
+        process.stderr.write("freeharness-cost-tracker: SubagentStop payload missing transcript_path or agent_id\n");
+      } else if (result.reason === "no-transcript" || result.reason === "too-large") {
+        process.stderr.write(`freeharness-cost-tracker: subagent transcript not usable: ${result.file}\n`);
+      } else if (result.reason === "unsafe-change") {
+        process.stderr.write("freeharness-cost-tracker: SubagentStop brief Change header refused\n");
+      }
+      // "no-brief": the project has no active brief to attribute the dispatch to; silent.
+      return;
+    }
+    const tags = briefTags(cwd);
+    const record = buildRecord(payload, tags);
+    // Backfill runs between build and append, so a missing SubagentStop line still lands
+    // (late: true) in time for this run's own telemetry count.
+    const { prices } = loadPrices(pricesPath());
+    const warnings = Array.isArray(record.warnings) ? record.warnings : [];
+    backfillLedger(payload, cwd, prices, warnings);
+    if (warnings.length > 0) record.warnings = warnings;
+    // The telemetry write is attempted before the snapshot is appended, so its failure lands
+    // as a warning on the appended snapshot itself.
+    if (record.event === "SessionEnd") writeTelemetryIfPossible(record, payload, tags);
+    appendRecord(record);
+  } catch (e) {
+    // Last resort: say why on stderr (Claude Code shows it in debug mode), never fail.
+    process.stderr.write(`freeharness-cost-tracker: ${e instanceof Error ? e.message : String(e)}\n`);
+  }
+}
+
+// Run only when executed directly (importable from tests without side effects).
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  main();
+  process.exit(0);
+}