freeharness 0.4.1 → 0.4.2

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

@@ -12,9 +12,15 @@ import { fileURLToPath } from "node:url";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
-/** Per-session subagent scan bounds (never read an unbounded directory). */
+/** Per-session subagent scan bounds (never read an unbounded directory); a long SDD session holds hundreds of transcripts. */
 const MAX_SUBAGENT_FILE_BYTES = 64 * 1024 * 1024;
-const MAX_SUBAGENT_FILES = 200;
+export const MAX_SUBAGENT_FILES = 2000;
+const MAX_SUBAGENT_CACHE_BYTES = 8 * 1024 * 1024;
+/** Per-file read caps: a file past its cap is treated as absent rather than read inside the hook timeout. */
+const MAX_MAIN_TRANSCRIPT_BYTES = 256 * 1024 * 1024;
+const MAX_USAGE_LOG_BYTES = 256 * 1024 * 1024;
+const MAX_LEDGER_BYTES = 16 * 1024 * 1024;
+const MAX_BRIEF_BYTES = 1024 * 1024;
 
 /** Usage log path: FREEHARNESS_COST_LOG override, else ~/.claude/freeharness/cost/usage.jsonl. */
 function logPath() {
@@ -46,44 +52,137 @@ function loadPrices(file) {
   }
 }
 
-/** Price row for `model`: exact key, else the longest prefix key, else `default`. */
-function priceFor(prices, model) {
-  if (prices[model]) return prices[model];
+/** An id new to the table (a new version, a retried alias) is priced at its family's rate, not
+ * at `default`, which misprices an opus call several times over. */
+const PRICE_FAMILY_RE = /^claude-(?:opus|sonnet|haiku|fable)-/;
+
+/** Leading numeric `-` segments of `key` after `prefix`: `claude-opus-5-5` gives [5, 5]. */
+function versionSegments(key, prefix) {
+  const out = [];
+  for (const seg of key.slice(prefix.length).split("-")) {
+    if (!/^\d+$/.test(seg)) break;
+    out.push(Number(seg));
+  }
+  return out;
+}
+
+/** Positive when version `a` is newer than `b`; a missing segment counts lower, so 5-5 beats 5. */
+function compareVersions(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = i < a.length ? a[i] : -1;
+    const y = i < b.length ? b[i] : -1;
+    if (x !== y) return x - y;
+  }
+  return 0;
+}
+
+/** Exact key, else the longest prefix key, else the id's family's newest key (estimated), else
+ * `default`. `priceMatch` in packages/cli/src/cli/cost.ts is a copy: this hook imports nothing
+ * from the CLI, and a parity test holds the two together.
+ * @returns {{key: string|null, row: object|undefined, estimated: boolean}} key null when no row matches.
+ */
+export function priceMatch(prices, model) {
+  const has = (key) => Object.prototype.hasOwnProperty.call(prices, key) && Boolean(prices[key]);
+  if (has(model)) return { key: model, row: prices[model], estimated: false };
   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;
+  if (best) return { key: best, row: prices[best], estimated: false };
+  const family = PRICE_FAMILY_RE.exec(model);
+  if (family) {
+    let newest;
+    let newestVersion = [];
+    for (const key of Object.keys(prices)) {
+      if (!key.startsWith(family[0]) || !has(key)) continue;
+      const version = versionSegments(key, family[0]);
+      const order = newest === undefined ? 1 : compareVersions(version, newestVersion);
+      if (order > 0 || (order === 0 && key.length > newest.length)) {
+        newest = key;
+        newestVersion = version;
+      }
+    }
+    if (newest !== undefined) return { key: newest, row: prices[newest], estimated: true };
+  }
+  return has("default") ? { key: "default", row: prices.default, estimated: false } : { key: null, row: undefined, estimated: false };
 }
 
-/** Estimated USD for one bucket at `row`'s per-MTok prices (0 when no row). */
-function estimate(u, row) {
+/** Estimated USD for one bucket at `row`'s per-MTok prices (0 when no row); `cache_write_1h` prices at the row's 1-hour rate, derived at 1.6x `cache_write` when the row has none. */
+export 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);
+  const per = (n, price) => ((Number(n) || 0) * (Number(price) || 0)) / 1e6;
+  const write1h = Math.max(0, Math.min(Number(u.cache_write_1h) || 0, Number(u.cache_write) || 0));
+  const write5m = (Number(u.cache_write) || 0) - write1h;
+  const rate1h = row.cache_write_1h ?? (Number(row.cache_write) || 0) * 1.6;
+  return per(u.input, row.input) + per(u.output, row.output) + per(u.cache_read, row.cache_read) + per(write5m, row.cache_write) + per(write1h, rate1h);
 }
 
-/** @returns {{input:number,output:number,cache_read:number,cache_write:number,messages:number}} Zeroed bucket. */
+/** @returns {{input:number,output:number,cache_read:number,cache_write:number,cache_write_1h:number,messages:number}} Zeroed bucket. */
 function bucket() {
-  return { input: 0, output: 0, cache_read: 0, cache_write: 0, messages: 0 };
+  return { input: 0, output: 0, cache_read: 0, cache_write: 0, cache_write_1h: 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 = {};
+/** Bytes per `readSync` call of the bounded read. */
+const READ_CHUNK = 1024 * 1024;
+
+/** Text of `file` through one fd opened without following a symlink leaf or blocking on a FIFO; the fstat on that same fd decides, so the checked file is the one read. The fstat size is only a fast refusal: a file still growing is bounded by the bytes actually read, and one byte past `maxBytes` yields "too-large". One buffer sized from the fstat holds the text, so peak memory stays near the file size rather than a multiple of the cap. `reason` is "missing" (ENOENT), "unreadable" (symlink, non-regular, I/O error) or "too-large". */
+function readContained(file, maxBytes) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | (fs.constants.O_NONBLOCK || 0));
+  } catch (e) {
+    return { text: null, reason: errCode(e) === "ENOENT" ? "missing" : "unreadable" };
+  }
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile()) return { text: null, reason: "unreadable" };
+    if (stat.size > maxBytes) return { text: null, reason: "too-large" };
+    let buf = Buffer.allocUnsafe(stat.size + 1);
+    let total = 0;
+    for (;;) {
+      if (total === buf.length) {
+        if (total > maxBytes) return { text: null, reason: "too-large" };
+        const grown = Buffer.allocUnsafe(Math.min(buf.length * 2, maxBytes + 1));
+        buf.copy(grown, 0, 0, total);
+        buf = grown;
+      }
+      const n = fs.readSync(fd, buf, total, Math.min(READ_CHUNK, buf.length - total), total);
+      if (n === 0) break;
+      total += n;
+    }
+    return { text: buf.toString("utf8", 0, total), reason: null };
+  } catch {
+    return { text: null, reason: "unreadable" };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+const CC_VERSION_RE = /^\d{1,4}\.\d{1,4}\.\d{1,6}(-[0-9A-Za-z.]{1,16})?$/;
+
+/** A transcript `version` verbatim, or null: clients before 2.1.307 wrote placeholder subagent output tokens, so a cost needs a trusted version. */
+export function ccVersionOf(value) {
+  return typeof value === "string" && CC_VERSION_RE.test(value) ? value : null;
+}
+
+/** 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. `effort` and `ccVersion` are the last valid values, the ones the run used. An unusable file yields `found: false` and the `reason` ("no-transcript" or "too-large"). */
+function sumTranscript(file, maxBytes) {
+  // Tool and model names come from the untrusted transcript: without a prototype, `__proto__` or
+  // `constructor` is an ordinary key instead of a path into Object.prototype.
+  const byModel = Object.create(null);
+  const byTool = Object.create(null);
   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 };
-  }
+  let effort = null;
+  let firstUserText = null;
+  let ccVersion = null;
+  const signals = { commands: [], skills: [], openspec: [] };
+  const { text, reason } = readContained(file, maxBytes);
+  if (text === null) return { byModel, byTool, turns, lines, contextTokens, contextModel, toolOutputChars, toolCalls, effort, firstUserText, ccVersion, signals, found: false, reason: reason === "too-large" ? "too-large" : "no-transcript" };
   const seen = new Map(); // message.id -> { model, usage }
   const toolNames = new Map(); // tool_use id -> name
   let anon = 0;
@@ -96,7 +195,11 @@ function sumTranscript(file) {
     } catch {
       continue;
     }
-    const msg = rec && typeof rec === "object" ? rec.message : undefined;
+    if (!rec || typeof rec !== "object" || Array.isArray(rec)) continue;
+    const msg = rec.message;
+    if (rec.type === "user" || rec.type === "assistant") ccVersion = ccVersionOf(rec.version) ?? ccVersion;
+    if (rec.type === "user" && firstUserText === null) firstUserText = messageText(msg);
+    addSignals(rec, signals);
     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");
@@ -114,7 +217,9 @@ function sumTranscript(file) {
       }
       continue;
     }
-    if (msg && Array.isArray(msg.content)) {
+    if (rec.type === "assistant" && typeof rec.effort === "string" && EFFORT_LEVELS.has(rec.effort)) effort = rec.effort;
+    // Request blobs repeat the conversation's tool_use blocks; only the assistant record is the call.
+    if (rec.type === "assistant" && msg && Array.isArray(msg.content)) {
       for (const c of msg.content) {
         if (c && c.type === "tool_use" && typeof c.name === "string") {
           toolCalls += 1;
@@ -138,13 +243,112 @@ function sumTranscript(file) {
   }
   for (const { model, usage } of seen.values()) {
     const b = (byModel[model] ??= bucket());
+    const cacheWrite = Number(usage.cache_creation_input_tokens) || 0;
+    const raw1h = usage.cache_creation && typeof usage.cache_creation === "object" ? Number(usage.cache_creation.ephemeral_1h_input_tokens) || 0 : 0;
     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.cache_write += cacheWrite;
+    b.cache_write_1h += Math.max(0, Math.min(raw1h, cacheWrite));
     b.messages += 1;
   }
-  return { byModel, byTool, turns, lines, contextTokens, contextModel, toolOutputChars, toolCalls, found: true };
+  return { byModel, byTool, turns, lines, contextTokens, contextModel, toolOutputChars, toolCalls, effort, firstUserText, ccVersion, signals, found: true };
+}
+
+/** A message's text: a string content as is, else its text blocks joined; "" for any other shape. */
+function messageText(msg) {
+  const content = msg && typeof msg === "object" ? msg.content : null;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((c) => c && c.type === "text" && typeof c.text === "string")
+    .map((c) => c.text)
+    .join("\n");
+}
+
+const COMMAND_NAME_RE = /<command-name>\/?([A-Za-z0-9:_.-]{1,64})<\/command-name>/;
+const MAX_SIGNALS = 200;
+const MAX_SIGNAL_ARG = 256;
+
+const signalArg = (v) => (typeof v === "string" && v.length <= MAX_SIGNAL_ARG ? v : null);
+
+/** A lazy regex rescans to the end once per unclosed opener; two indexOf scans stay linear. */
+function commandArg(text) {
+  const open = text.indexOf("<command-args>");
+  const close = open < 0 ? -1 : text.indexOf("</command-args>", open + 14);
+  return close < 0 ? null : signalArg(text.slice(open + 14, close));
+}
+
+/** `openspec` interleaves both kinds in transcript order, since the last invocation names the change. */
+function pushSignal(into, kind, prefix, signal) {
+  if (into[kind].length < MAX_SIGNALS) into[kind].push(signal);
+  if (signal.name.startsWith(prefix) && into.openspec.length < MAX_SIGNALS) into.openspec.push(signal);
+}
+
+/** Adds one record's workflow signals to `into`. Only user-typed command elements and Skill calls
+ * count: tool_result and assistant text quote files and output, which anyone can forge. */
+function addSignals(rec, into) {
+  const content = rec.message && typeof rec.message === "object" ? rec.message.content : null;
+  if (rec.type === "user") {
+    const texts = typeof content === "string" ? [content] : Array.isArray(content) ? content.filter((c) => c && c.type === "text" && typeof c.text === "string").map((c) => c.text) : [];
+    for (const text of texts) {
+      const m = text.includes("<command-name>") ? COMMAND_NAME_RE.exec(text) : null;
+      if (m) pushSignal(into, "commands", "opsx:", { name: m[1], arg: commandArg(text) });
+    }
+  } else if (rec.type === "assistant" && Array.isArray(content)) {
+    for (const c of content) {
+      const input = c && c.type === "tool_use" && c.name === "Skill" && c.input && typeof c.input === "object" ? c.input : null;
+      if (input && typeof input.skill === "string" && input.skill.length >= 1 && input.skill.length <= 64) pushSignal(into, "skills", "openspec-", { name: input.skill, arg: signalArg(input.args) });
+    }
+  }
+}
+
+/** Command and Skill signals of parsed transcript records, the first 200 of each. */
+export function sessionSignals(records) {
+  const into = { commands: [], skills: [], openspec: [] };
+  for (const rec of Array.isArray(records) ? records : []) if (rec && typeof rec === "object" && !Array.isArray(rec)) addSignals(rec, into);
+  return into;
+}
+
+const SESSION_TRIGGERS = Object.freeze(
+  Object.assign(Object.create(null), {
+    "subagent-driven-development": "sdd",
+    "opsx:apply": "sdd",
+    "openspec-apply-change": "sdd",
+    "opsx:propose": "plan",
+    "opsx:update": "plan",
+    "opsx:explore": "plan",
+    "openspec-propose": "plan",
+    "openspec-update-change": "plan",
+    "openspec-explore": "plan",
+    "opsx:archive": "archive",
+    "opsx:sync": "archive",
+    "openspec-archive-change": "archive",
+    "openspec-sync-specs": "archive",
+    "code-review": "review",
+    "security-review": "review",
+    review: "review",
+    "systematic-debugging": "debug",
+  }),
+);
+const SESSION_CLASS_ORDER = Object.freeze(["sdd", "plan", "archive", "review", "debug"]);
+
+/** The session's workflow classes from its signals and its ledger dispatch counts per role. */
+export function classifySession(signals, roleCounts) {
+  const hit = new Set();
+  for (const list of [signals?.commands, signals?.skills]) {
+    if (!Array.isArray(list)) continue;
+    for (const s of list) if (s && typeof s.name === "string" && SESSION_TRIGGERS[s.name]) hit.add(SESSION_TRIGGERS[s.name]);
+  }
+  const counts = roleCounts && typeof roleCounts === "object" ? roleCounts : {};
+  if (["impl", "fix", "review"].some((r) => Number(counts[r]) > 0)) hit.add("sdd");
+  const session_classes = SESSION_CLASS_ORDER.filter((c) => hit.has(c));
+  return { session_class: session_classes[0] ?? "untagged", session_classes };
+}
+
+/** Effort level a subagent transcript ran at; null for an unusable or over-cap file, or no known level. The hook itself takes the effort from `sumTranscript`'s single pass; this export isolates that read for tests. */
+export function effortFromTranscript(file) {
+  return sumTranscript(file, MAX_SUBAGENT_FILE_BYTES).effort;
 }
 
 /** Character count of a tool_result content. */
@@ -162,12 +366,15 @@ function modelSuffix(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. */
+/** Token window: an explicit `[1m]` suffix means 1,000,000, else the price row's `window`, defaulting to 200,000.
+ * The family step is skipped: a newer model's window would overstate an older model's, so such
+ * an id takes the `default` row's window instead. */
 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 match = priceMatch(prices, base || raw);
+  const row = match.estimated ? prices.default : match.row;
   const w = row && Number.isInteger(row.window) && row.window > 0 ? row.window : null;
   return w ?? 200_000;
 }
@@ -177,6 +384,20 @@ function userConfigDir() {
   return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
 }
 
+/** True only when `file` resolves strictly under the real `<config>/projects` and still is the inode `stat` (taken from the open descriptor) names, so a parent swapped after the open cannot redirect a transcript read. */
+export function underProjectsDir(file, stat) {
+  try {
+    const base = fs.realpathSync(path.resolve(userConfigDir(), "projects"));
+    const real = fs.realpathSync(file);
+    const rel = path.relative(base, real);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return false;
+    const entry = fs.lstatSync(real);
+    return entry.dev === stat.dev && entry.ino === stat.ino;
+  } catch {
+    return false;
+  }
+}
+
 /** settings.json's `model` field, or null when absent, unreadable or unset. */
 function settingsModel(file) {
   try {
@@ -192,7 +413,12 @@ 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. */
+/** Current Claude Code transcript name, `agent-<hex id>.jsonl`; its name lives only in the meta. Tried first, and it never overlaps the legacy shape (no `-` in the id). */
+const CURRENT_TRANSCRIPT_RE = /^agent-([A-Za-z0-9]+)\.jsonl$/;
+/** Older builds embedded the agent name: `agent-<name>-<hash>.jsonl`. */
+const LEGACY_TRANSCRIPT_RE = /^agent-(.+)-[^-]+\.jsonl$/;
+
+/** Subagent transcripts under `<dirname>/<session-id>/subagents/` in either name shape, sorted by file name; `name` is the legacy parsed name, else null. Empty when the directory is missing. */
 export function subagentTranscripts(transcriptPath) {
   if (!transcriptPath) return [];
   const dir = path.dirname(transcriptPath);
@@ -206,11 +432,16 @@ export function subagentTranscripts(transcriptPath) {
   }
   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) });
+    let name = null;
+    if (!CURRENT_TRANSCRIPT_RE.test(entry)) {
+      const legacy = LEGACY_TRANSCRIPT_RE.exec(entry);
+      if (!legacy) continue;
+      name = legacy[1];
+    }
+    const stem = entry.slice(0, -".jsonl".length);
+    out.push({ id: stem.slice("agent-".length), name, file: path.join(subDir, entry), metaFile: path.join(subDir, `${stem}.meta.json`) });
   }
-  return out.sort((a, b) => a.name.localeCompare(b.name));
+  return out.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
 }
 
 /** Merges per-model sums into one `by_agent` bucket, picking the model with the most tokens (ties break alphabetically). */
@@ -224,6 +455,7 @@ function mergeAgentUsage(byModel) {
     total.output += u.output;
     total.cache_read += u.cache_read;
     total.cache_write += u.cache_write;
+    total.cache_write_1h += u.cache_write_1h;
     total.messages += u.messages;
     const t = u.input + u.output + u.cache_read + u.cache_write;
     if (t > bestTotal) {
@@ -233,7 +465,7 @@ function mergeAgentUsage(byModel) {
   }
   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 },
+    usage: { input: total.input, output: total.output, cache_read: total.cache_read, cache_write: total.cache_write, cache_write_1h: total.cache_write_1h, total: total.input + total.output + total.cache_read + total.cache_write },
     messages: total.messages,
   };
 }
@@ -243,8 +475,35 @@ 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) {
+/** True when `<cwd>/openspec/changes/<dir>` is a directory; false for `archive`, an unsafe segment, or a stat error. */
+export function inFlight(cwd, dir) {
+  if (typeof dir !== "string" || !dir || dir === "archive") return false;
+  if (!safeChangeSegment(path.join(cwd, ".freeharness", "sdd"), dir)) return false;
+  const changesRoot = path.join(cwd, "openspec", "changes");
+  const target = path.join(changesRoot, dir);
+  let stat;
+  try {
+    stat = fs.lstatSync(target);
+  } catch {
+    return false;
+  }
+  if (!stat.isSymbolicLink()) return stat.isDirectory();
+  let real;
+  try {
+    real = fs.realpathSync(target);
+  } catch {
+    return false;
+  }
+  if (!containedIn(realPathOr(changesRoot), real)) return false;
+  try {
+    return fs.statSync(real).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Tags a session from the newest `*.brief.md` under an in-flight change, or under `only` when given: `Change:`, `Task:`, `Tier:`, `Class:`, sanitized. No in-flight brief yields every field null and `task_class: "untagged"`. */
+export function briefTags(cwd, only = null) {
   const root = path.join(cwd, ".freeharness", "sdd");
   let newest = null;
   let newestMtime = -Infinity;
@@ -274,15 +533,19 @@ export function briefTags(cwd) {
       }
     }
   };
-  walk(root);
-  const empty = { change: null, task: null, tier: null, task_class: "untagged" };
-  if (!newest) return empty;
-  let text;
+  let topEntries;
   try {
-    text = fs.readFileSync(newest, "utf8");
+    topEntries = fs.readdirSync(root, { withFileTypes: true });
   } catch {
-    return empty;
+    topEntries = [];
   }
+  for (const top of topEntries) {
+    if (top.isDirectory() && (only === null || top.name === only) && inFlight(cwd, top.name)) walk(path.join(root, top.name));
+  }
+  const empty = { change: null, task: null, tier: null, task_class: "untagged" };
+  if (!newest) return empty;
+  const { text } = readContained(newest, MAX_BRIEF_BYTES);
+  if (text === null) return empty;
   const field = (key) => {
     const m = new RegExp(`^${key}:\\s*(.+)$`, "m").exec(text);
     return m ? sanitizeTag(m[1]) : null;
@@ -312,6 +575,96 @@ function realPathOr(p) {
   }
 }
 
+/** A walk-up past this depth is a loop or a hostile path, never a project. */
+const MAX_ROOT_LEVELS = 64;
+
+/** A marker reached through a symlink could name another tree as this project. */
+function realDirChain(dir, parts) {
+  let p = dir;
+  for (const part of parts) {
+    p = path.join(p, part);
+    try {
+      if (!fs.lstatSync(p).isDirectory()) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+function holdsProjectMarker(dir) {
+  return realDirChain(dir, ["openspec", "changes"]) || realDirChain(dir, [".freeharness", "sdd"]);
+}
+
+/** Git pointer files are one short line; a larger one is forged. */
+const MAX_GIT_POINTER_BYTES = 4 * 1024;
+
+/** The single line of a git pointer file, or null. */
+function pointerLine(file) {
+  const { text } = readContained(file, MAX_GIT_POINTER_BYTES);
+  if (text === null) return null;
+  const line = text.trimEnd();
+  return line && !line.includes("\n") ? line : null;
+}
+
+/**
+ * A task worktree checks out openspec/changes/ but not the gitignored workspace, so its records belong to the main worktree.
+ * Only a directory lexically under a real `<main>/.worktrees/` maps, so a forged `.git` can name only a root that already holds it, and a symlinked `.worktrees` cannot pull an outside tree in.
+ * @param {string} dir Real path of a directory holding a project marker.
+ * @returns {string | null} Real path of the main worktree; null on any read or parse failure.
+ */
+export function mainWorktreeOf(dir) {
+  try {
+    const dotGit = path.join(dir, ".git");
+    if (!fs.lstatSync(dotGit).isFile()) return null;
+    const m = /^gitdir: (.+)$/.exec(pointerLine(dotGit) ?? "");
+    if (!m) return null;
+    const gitDir = fs.realpathSync(path.resolve(dir, m[1]));
+    const common = pointerLine(path.join(gitDir, "commondir"));
+    if (common === null) return null;
+    const main = path.dirname(fs.realpathSync(path.resolve(gitDir, common)));
+    const trees = path.join(main, ".worktrees");
+    if (!fs.lstatSync(trees).isDirectory() || !containedIn(trees, path.resolve(dir))) return null;
+    return holdsProjectMarker(main) ? main : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A hook payload's `cwd` is the lead shell's directory, which may sit anywhere inside the project, so the workspace is found above it.
+ * CLAUDE_PROJECT_DIR wins only as the cwd or an ancestor of it, so the environment cannot point a dispatch at an unrelated tree.
+ * @param {string} cwd Payload cwd.
+ * @returns {string | null} Real path of the project root, a task worktree's being its main worktree; null when the cwd is not an absolute string or its real path cannot be resolved, when no marker holds at or above it up to the filesystem root, or when none holds within MAX_ROOT_LEVELS levels.
+ */
+export function projectRootFor(cwd) {
+  if (typeof cwd !== "string" || !path.isAbsolute(cwd)) return null;
+  let real;
+  try {
+    real = fs.realpathSync(cwd);
+  } catch {
+    return null;
+  }
+  const preferred = process.env.CLAUDE_PROJECT_DIR;
+  if (typeof preferred === "string" && path.isAbsolute(preferred)) {
+    let dir = null;
+    try {
+      dir = fs.realpathSync(preferred);
+    } catch {
+      dir = null;
+    }
+    if (dir !== null && (dir === real || containedIn(dir, real)) && holdsProjectMarker(dir)) return mainWorktreeOf(dir) ?? dir;
+  }
+  let dir = real;
+  for (let level = 0; level < MAX_ROOT_LEVELS; level += 1) {
+    if (holdsProjectMarker(dir)) return mainWorktreeOf(dir) ?? dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
 /** 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;
@@ -341,22 +694,41 @@ function agentMetaPathFor(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) {
+/** A meta is a few hundred bytes; the cap bounds what a hostile file in the subagents directory can cost. */
+const MAX_AGENT_META_BYTES = 64 * 1024;
+
+/** The meta's fields plus why it gave none: `reason` is null for a JSON object, "missing", or "unreadable" (symlink, non-regular, over cap, invalid or non-object JSON). */
+function loadAgentMeta(file) {
+  const empty = { name: null, agentType: null, description: null, customAgentType: null };
+  const { text, reason } = readContained(file, MAX_AGENT_META_BYTES);
+  if (text === null) return { meta: empty, reason: reason === "missing" ? "missing" : "unreadable" };
   let parsed;
   try {
-    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    parsed = JSON.parse(text);
   } catch {
-    return { name: null, agentType: null };
+    return { meta: empty, reason: "unreadable" };
   }
-  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 };
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { meta: empty, reason: "unreadable" };
+  const field = (key) => (typeof parsed[key] === "string" && parsed[key] ? parsed[key] : null);
+  return { meta: { name: field("name"), agentType: field("agentType"), description: field("description"), customAgentType: field("customAgentType") }, reason: null };
+}
+
+/** Dispatch name, agent type, description and agent definition (`customAgentType`, null when built-in); every field null when the meta cannot be read. */
+export function readAgentMeta(file) {
+  return loadAgentMeta(file).meta;
 }
 
-/** 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. */
+/** Dispatch name from a meta `description`: Claude Code fills it from the dispatching prompt, so it is untrusted and only a full dispatch-pattern match, after one optional `Dispatch: ` prefix, counts. */
+function descriptionDispatchName(description) {
+  if (typeof description !== "string") return null;
+  const candidate = description.startsWith("Dispatch: ") ? description.slice("Dispatch: ".length) : description;
+  return DISPATCH_RE.test(candidate) ? candidate : null;
+}
+
+/** 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. A current-shape name carries only an id, so it never names a dispatch. */
 function fallbackDispatchName(base) {
-  const m = /^agent-(.+)-[^-]+\.jsonl$/.exec(base);
+  if (CURRENT_TRANSCRIPT_RE.test(base)) return null;
+  const m = LEGACY_TRANSCRIPT_RE.exec(base);
   if (!m) return null;
   const candidate = m[1];
   if (DISPATCH_RE.test(candidate)) return candidate;
@@ -373,8 +745,8 @@ export function parseDispatchName(name) {
   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) {
+/** Every `*.brief.md` under an in-flight `.freeharness/sdd/` directory, with change directory and mtime; empty when the root is absent. */
+function changeBriefs(root, cwd) {
   const out = [];
   let topEntries;
   try {
@@ -383,7 +755,7 @@ function changeBriefs(root) {
     return out;
   }
   for (const top of topEntries) {
-    if (!top.isDirectory()) continue;
+    if (!top.isDirectory() || !inFlight(cwd, top.name)) continue;
     const change = top.name;
     const walk = (dir) => {
       let entries;
@@ -435,30 +807,113 @@ export function safeChangeSegment(root, change) {
   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) {
+/** Change segment of a prompt brief path: kebab-case only, stricter than `safeChangeSegment` since the prompt is free text. Checked without a nested quantifier, as the text is untrusted. */
+function kebabSegment(s) {
+  return typeof s === "string" && /^[a-z0-9-]+$/.test(s) && !s.startsWith("-") && !s.endsWith("-") && !s.includes("--");
+}
+
+/** Leading characters of a prompt the brief-path scan reads: the dispatch prompt names its brief near the top, and the bound keeps an untrusted message from spending the hook's timeout. */
+const PROMPT_SCAN_CHARS = 16 * 1024;
+const PROMPT_BRIEF_MARK = ".freeharness/sdd/";
+const PROMPT_BRIEF_SUFFIX = ".brief.md";
+/** Characters that end a path token besides whitespace; `<` among them so a `<change>` placeholder never matches. */
+const PROMPT_TOKEN_STOPS = new Set(['"', "'", "`", "(", ")", "<", ">", "[", "]"]);
+/** Sentence punctuation trimmed from a token's end, so a path closing a sentence still names its brief. */
+const PROMPT_TOKEN_TRAIL = new Set([".", ",", ";", ":", "!", "?"]);
+
+function promptTokenStop(ch) {
+  return PROMPT_TOKEN_STOPS.has(ch) || ch.trim() === "";
+}
+
+/** Whether a prompt path prefix names this project: relative (empty or `./`), the project root itself, lexical or real, or the shell's spelling of it: a lexical ancestor of the shell cwd that resolves to the root. */
+function promptRootAccepted(prefix, root, cwd) {
+  if (prefix === "" || prefix === "./") return true;
+  if (!path.isAbsolute(prefix) || !prefix.endsWith("/") || typeof root !== "string" || !root) return false;
+  const withSep = (p) => (p.endsWith("/") ? p : `${p}/`);
+  const base = path.resolve(root);
+  if (prefix === withSep(base) || prefix === withSep(realPathOr(base))) return true;
+  if (typeof cwd !== "string" || !path.isAbsolute(cwd) || !withSep(path.resolve(cwd)).startsWith(prefix)) return false;
+  return realPathOr(prefix) === realPathOr(base);
+}
+
+/** The brief a dispatch prompt names, from the first path token holding `.freeharness/sdd/` and ending in `.brief.md`: the dispatch prompt carries the change, which a task id shared by two changes cannot. An invalid first match yields null rather than a later match, so a prompt cannot steer past a refused path. The scan walks each character a bounded number of times over the leading slice, since a backtracking pattern on untrusted text can outrun the hook timeout. */
+export function briefPathFromText(text, root, cwd = root) {
+  if (typeof text !== "string" || !text) return null;
+  const truncated = text.length > PROMPT_SCAN_CHARS;
+  const scan = truncated ? text.slice(0, PROMPT_SCAN_CHARS) : text;
+  let from = 0;
+  for (;;) {
+    const at = scan.indexOf(PROMPT_BRIEF_MARK, from);
+    if (at < 0) return null;
+    let start = at;
+    while (start > from && !promptTokenStop(scan[start - 1])) start -= 1;
+    const restStart = at + PROMPT_BRIEF_MARK.length;
+    let end = restStart;
+    while (end < scan.length && !promptTokenStop(scan[end])) end += 1;
+    // A token cut by the bound has an unknown end, so it cannot be a match.
+    if (truncated && end === scan.length) return null;
+    let stop = end;
+    while (stop > restStart && PROMPT_TOKEN_TRAIL.has(scan[stop - 1])) stop -= 1;
+    if (stop - PROMPT_BRIEF_SUFFIX.length >= restStart && scan.endsWith(PROMPT_BRIEF_SUFFIX, stop)) {
+      const token = scan.slice(start, stop);
+      if (token.includes("..") || token.includes("\\")) return null;
+      const parts = scan.slice(restStart, stop - PROMPT_BRIEF_SUFFIX.length).split("/");
+      if (parts.length !== 2 || !kebabSegment(parts[0]) || !parts[1]) return null;
+      if (!promptRootAccepted(scan.slice(start, at), root, cwd)) return null;
+      return { change: parts[0], file: `${parts[1]}${PROMPT_BRIEF_SUFFIX}` };
+    }
+    from = end;
+  }
+}
+
+/** The brief named by a subagent transcript's first user message, or null for an unusable transcript or no user line. The hook takes the text from `sumTranscript`'s single pass; this export isolates that read. */
+export function briefPathFromPrompt(transcriptFile, cwd) {
+  return briefPathFromText(sumTranscript(transcriptFile, MAX_SUBAGENT_FILE_BYTES).firstUserText, cwd);
+}
+
+/** Whether a prompt brief decides the ledger: its change is in flight and the brief is a regular file there; else the task rule applies. */
+function promptBriefApplies(cwd, brief) {
+  if (!brief || typeof brief.change !== "string" || typeof brief.file !== "string") return false;
+  if (!kebabSegment(brief.change) ||!brief.file.endsWith(".brief.md") || brief.file.includes("/") || brief.file.includes("\\")) return false;
+  if (!inFlight(cwd, brief.change)) return false;
+  try {
+    return fs.lstatSync(path.join(cwd, ".freeharness", "sdd", brief.change, brief.file)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Ledger file for a dispatch: the prompt's brief change when it applies; else the in-flight change whose brief declares the task id, newest when several match; null when none does, so another change's dispatch never lands in the active one. Only a dispatch without a task falls back to the newest in-flight brief's change. */
+export function ledgerPathFor(cwd, task, tags, promptBrief = null) {
   const root = path.join(cwd, ".freeharness", "sdd");
+  if (promptBriefApplies(cwd, promptBrief)) return path.join(root, promptBrief.change, "ledger.jsonl");
   if (task) {
     let best = null;
-    for (const b of changeBriefs(root)) {
-      let text;
-      try {
-        text = fs.readFileSync(b.file, "utf8");
-      } catch {
-        continue;
-      }
+    for (const b of changeBriefs(root, cwd)) {
+      const { text } = readContained(b.file, MAX_BRIEF_BYTES);
+      if (text === null) 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");
+    return best ? path.join(root, best.change, "ledger.jsonl") : null;
   }
-  if (tags && tags.change && safeChangeSegment(root, tags.change)) return path.join(root, tags.change, "ledger.jsonl");
+  if (tags && tags.change && inFlight(cwd, 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 EFFORT_LEVELS = new Set(["low", "medium", "high", "xhigh", "max"]);
+
+/** `payload.effort.level` when it is one of the five known levels, else null. */
+function effortFromPayload(payload) {
+  const effort = payload && typeof payload === "object" ? payload.effort : null;
+  const level = effort && typeof effort === "object" && !Array.isArray(effort) ? effort.level : null;
+  return typeof level === "string" && EFFORT_LEVELS.has(level) ? level : null;
+}
+
+/** One dispatch ledger line, or a skip reason for a missing payload, transcript or brief. Model
+ * is the transcript's dominant model, never the meta alias. `late` marks a Stop backfill line. */
+export function ledgerLine(payload, cwd, prices, { late = false } = {}) {
   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" };
@@ -466,33 +921,43 @@ export function ledgerLine(payload, cwd, prices) {
   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 sums = sumTranscript(file, MAX_SUBAGENT_FILE_BYTES);
+  if (!sums.found) return { ok: false, reason: sums.reason, file };
 
   const merged = mergeAgentUsage(sums.byModel);
-  const est = estimate(merged.usage, priceFor(prices, merged.model));
+  const match = priceMatch(prices, merged.model);
+  const est = estimate(merged.usage, match.row);
 
   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);
+  // A plain (unnamed) dispatch names itself on its prompt's first line. The prompt is untrusted,
+  // so only the exact `Dispatch: <name>` form with a name of the dispatch pattern counts.
+  const promptLine = typeof sums.firstUserText === "string" ? /^Dispatch: (\S+)$/.exec(sums.firstUserText.split(/\r?\n/, 1)[0]) : null;
+  const promptName = promptLine && DISPATCH_RE.test(promptLine[1]) ? promptLine[1] : null;
+  const name = meta.name || promptName || descriptionDispatchName(meta.description) || fallbackDispatchName(path.basename(file));
+  const agentType = meta.customAgentType ?? 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);
+  const shellCwd = typeof payload.cwd === "string" ? payload.cwd : cwd;
+  const ledgerFile = ledgerPathFor(cwd, parsed.task, tags, briefPathFromText(sums.firstUserText, cwd, shellCwd));
   if (!ledgerFile) {
     const root = path.join(cwd, ".freeharness", "sdd");
-    const unsafe = Boolean(tags.change) && !safeChangeSegment(root, tags.change);
+    const unsafe = !parsed.task && Boolean(tags.change) && !safeChangeSegment(root, tags.change);
     return { ok: false, reason: unsafe ? "unsafe-change" : "no-brief" };
   }
 
+  // `late` has no payload; the transcript records the level the dispatch ran at. An in-process
+  // team dispatch inherits the session effort, so the agent definition's frontmatter is no source.
+  let effort = null;
+  let effort_source = null;
+  if (late) {
+    effort = sums.effort;
+    if (effort) effort_source = "transcript";
+  } else {
+    effort = effortFromPayload(payload);
+    if (effort) effort_source = "payload";
+  }
+
   const line = {
     ts: new Date().toISOString(),
     session: typeof payload.session_id === "string" ? payload.session_id : "",
@@ -503,32 +968,116 @@ export function ledgerLine(payload, cwd, prices) {
     task: parsed.task,
     round: parsed.round,
     model: merged.model,
+    cc_version: sums.ccVersion,
+    effort,
+    effort_source,
+    // A snapshot of the transcript's cumulative totals, not a delta; readers take the latest
+    // line per agent_id.
     input: merged.usage.input,
     cache_read: merged.usage.cache_read,
     cache_write: merged.usage.cache_write,
+    cache_write_1h: merged.usage.cache_write_1h,
     output: merged.usage.output,
     est_usd: round(est),
-    late: false,
+    ...(match.estimated ? { price_estimated: true } : {}),
+    late,
     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");
+/** A thrown fs error's `E...` code only: its message carries an absolute path. */
+function errCode(e) {
+  const code = e && typeof e === "object" && "code" in e ? String(e.code) : "";
+  return /^E[A-Z0-9_]+$/.test(code) ? code : "EUNKNOWN";
 }
 
-/** `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;
+/** Refusal unless `.freeharness`, `sdd` and `changeDir` are real directories, `changeDir`
+ * directly under `<realpath(cwd)>/.freeharness/sdd`. */
+function changeDirContained(cwd, changeDir) {
+  const root = path.join(cwd, ".freeharness", "sdd");
+  if (path.dirname(changeDir) !== root) return { ok: false, reason: "outside-workspace" };
+  let real;
   try {
-    text = fs.readFileSync(file, "utf8");
-  } catch {
-    return ids;
+    for (const dir of [path.dirname(root), root, changeDir]) {
+      const stat = fs.lstatSync(dir);
+      if (stat.isSymbolicLink()) return { ok: false, reason: "symlinked-dir" };
+      if (!stat.isDirectory()) return { ok: false, reason: "not-dir" };
+    }
+    real = { root: path.join(fs.realpathSync(cwd), ".freeharness", "sdd"), dir: fs.realpathSync(changeDir) };
+  } catch (e) {
+    return { ok: false, reason: `dir-unreadable ${errCode(e)}` };
   }
+  return containedIn(real.root, real.dir) ? { ok: true } : { ok: false, reason: "outside-workspace" };
+}
+
+/** Post-open refusal unless the directory chain still passes and `fd` is the one-link regular
+ * file `file` names (dev/ino), so a swap after the first check writes nothing. */
+function verifyOpenedLedger(cwd, file, fd) {
+  const dirCheck = changeDirContained(cwd, path.dirname(file));
+  if (!dirCheck.ok) return dirCheck;
+  let opened, named;
+  try {
+    opened = fs.fstatSync(fd);
+    named = fs.lstatSync(file);
+  } catch (e) {
+    return { ok: false, reason: `stat-failed ${errCode(e)}` };
+  }
+  if (!opened.isFile()) return { ok: false, reason: "not-regular" };
+  if (opened.nlink > 1) return { ok: false, reason: "hard-link" };
+  if (opened.dev !== named.dev || opened.ino !== named.ino) return { ok: false, reason: "swapped" };
+  return { ok: true };
+}
+
+/** Opens `file` for a contained append, never following a final symlink or blocking on a FIFO
+ * (ELOOP, ENXIO); the caller closes `fd`. */
+function openContainedLedger(cwd, file) {
+  const dirCheck = changeDirContained(cwd, path.dirname(file));
+  if (!dirCheck.ok) return dirCheck;
+  const flags = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW | (fs.constants.O_NONBLOCK || 0);
+  let fd;
+  try {
+    fd = fs.openSync(file, flags, 0o644);
+  } catch (e) {
+    return { ok: false, reason: `open-refused ${errCode(e)}` };
+  }
+  const verdict = verifyOpenedLedger(cwd, file, fd);
+  if (verdict.ok) return { ok: true, fd };
+  fs.closeSync(fd);
+  return verdict;
+}
+
+/** One stderr line per refusal; `reason` is a code, never a path. */
+function reportLedgerRefusal(reason) {
+  process.stderr.write(`freeharness-cost-tracker: ledger append refused: ${reason}\n`);
+}
+
+/** Appends one ledger line inside the SDD workspace, never creating the change directory or
+ * throwing; the caller reports a refusal once per hook run.
+ * @returns {{ok:true}|{ok:false, reason:string}}
+ */
+export function appendLedgerLine(file, line, cwd) {
+  const opened = openContainedLedger(cwd, file);
+  if (!opened.ok) return opened;
+  try {
+    fs.writeSync(opened.fd, `${JSON.stringify(line)}\n`);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: `write-failed ${errCode(e)}` };
+  } finally {
+    fs.closeSync(opened.fd);
+  }
+}
+
+/** `agent_id`s already in a ledger file: an empty set for a missing ledger or an uncontained
+ * change directory (the append refuses the latter), null for an existing ledger that is a
+ * symlink, non-regular or over its cap, so no caller mistakes its unknown ids for none. */
+function readLedgerAgentIds(file, cwd) {
+  const ids = new Set();
+  if (!changeDirContained(cwd, path.dirname(file)).ok) return ids;
+  const { text, reason } = readContained(file, MAX_LEDGER_BYTES);
+  if (text === null) return reason === "missing" ? ids : null;
   for (const raw of text.split("\n")) {
     if (!raw.trim()) continue;
     try {
@@ -540,33 +1089,45 @@ function readLedgerAgentIds(file) {
   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`. */
+/** Backfills a `late: true` line for every subagent transcript missing one (a crash or timeout can skip SubagentStop); failures push onto `snapshotWarnings`. The shell may sit below the project root, so the ledgers are found from the root above `cwd`. */
 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 root = projectRootFor(cwd) ?? cwd;
+  const recorded = recordedAgentIds(root);
   const done = new Set();
-  for (const { file } of subagentTranscripts(transcriptPath)) {
-    const m = /^agent-(.+)\.jsonl$/.exec(path.basename(file));
-    if (!m) continue;
+  // Target ledger -> whether its ids can be read, decided on the target path itself: a
+  // `Change:` header may name the directory in another case, which a path comparison misses.
+  const targetReadable = new Map();
+  let reported = false;
+  let skipReported = false;
+  for (const { id, file } of subagentTranscripts(transcriptPath)) {
     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 (done.has(key) || recorded.has(id)) continue;
+    const result = ledgerLine({ transcript_path: transcriptPath, agent_id: id, session_id: sessionId, cwd }, root, prices, { late: true });
     if (!result.ok) continue;
-    if (recorded.has(result.line.agent_id)) continue;
-    const line = { ...result.line, late: true };
-    try {
-      appendLedgerLine(result.file, line);
+    if (!targetReadable.has(result.file)) targetReadable.set(result.file, readLedgerAgentIds(result.file, root) !== null);
+    // Its recorded ids are unknown, so a backfill line could duplicate one already there.
+    if (!targetReadable.get(result.file)) {
+      if (!skipReported) snapshotWarnings.push("ledger backfill skipped: ledger unreadable");
+      skipReported = true;
+      continue;
+    }
+    const line = result.line;
+    const appended = appendLedgerLine(result.file, line, root);
+    if (appended.ok) {
       recorded.add(line.agent_id);
       done.add(key);
-    } catch (e) {
-      snapshotWarnings.push(`ledger backfill write failed: ${e instanceof Error ? e.message : String(e)}`);
+    } else {
+      snapshotWarnings.push(`ledger backfill append refused: ${appended.reason}`);
+      if (!reported) reportLedgerRefusal(appended.reason);
+      reported = true;
     }
   }
 }
 
-/** Agent ids recorded in any ledger under the SDD workspace; the union across changes proves a transcript already has its line. */
+/** Agent ids recorded in any readable 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");
@@ -578,31 +1139,25 @@ function recordedAgentIds(cwd) {
   }
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    for (const id of readLedgerAgentIds(path.join(root, entry.name, "ledger.jsonl"))) ids.add(id);
+    for (const id of readLedgerAgentIds(path.join(root, entry.name, "ledger.jsonl"), cwd) ?? []) 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;
+/** Calls `visit(changeDir, rec)` for the session's lines in every change's ledger, archived changes' included. */
+function eachSessionLedgerLine(cwd, sessionId, visit) {
+  if (!sessionId) return;
   const root = path.join(cwd, ".freeharness", "sdd");
   let topEntries;
   try {
     topEntries = fs.readdirSync(root, { withFileTypes: true });
   } catch {
-    return counts;
+    return;
   }
-  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;
-    }
+    const { text } = readContained(path.join(root, top.name, "ledger.jsonl"), MAX_LEDGER_BYTES);
+    if (text === null) continue;
     for (const raw of text.split("\n")) {
       if (!raw.trim()) continue;
       let rec;
@@ -611,26 +1166,164 @@ export function dispatchesByRole(cwd, sessionId) {
       } 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;
+      if (rec && rec.session === sessionId) visit(top.name, rec);
     }
   }
+}
+
+/** Counts dispatches per role, one distinct `agent_id` per dispatch so a resumed worker's second line adds nothing. */
+export function dispatchesByRole(cwd, sessionId) {
+  // Roles are ledger text; a `__proto__` role must stay a key, not a prototype assignment.
+  const counts = Object.create(null);
+  const seenByRole = new Map();
+  eachSessionLedgerLine(cwd, sessionId, (_dir, rec) => {
+    if (typeof rec.agent_id !== "string") return;
+    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)) return;
+    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`. */
+/** Per change directory, the session's distinct dispatches and latest `ts`; a line without an `agent_id` still records a dispatch, so it counts as its own. */
+export function sessionLedger(root, sessionId) {
+  const out = new Map();
+  let anon = 0;
+  eachSessionLedgerLine(root, sessionId, (dir, rec) => {
+    let entry = out.get(dir);
+    if (!entry) out.set(dir, (entry = { agents: new Set(), lastTs: null }));
+    entry.agents.add(typeof rec.agent_id === "string" ? rec.agent_id : `\0anon-${anon++}`);
+    if (typeof rec.ts === "string" && (entry.lastTs === null || rec.ts > entry.lastTs)) entry.lastTs = rec.ts;
+  });
+  return out;
+}
+
+const MAX_CHANGE_ID = 64;
+const MAX_SESSION_CHANGES = 8;
+const DATED_ARCHIVE_RE = /^\d{4}-\d{2}-\d{2}-(.+)$/;
+
+/** Ledger directories and invocation arguments are untrusted text, so an id counts only as a real directory, never through a symlink, under openspec/changes/ or its archive. */
+function changeLookup(root) {
+  let dated = null;
+  return (id) => {
+    if (typeof id !== "string" || id.length > MAX_CHANGE_ID || id === "archive" || !kebabSegment(id)) return false;
+    if (realDirChain(root, ["openspec", "changes", id]) || realDirChain(root, ["openspec", "changes", "archive", id])) return true;
+    if (dated === null) {
+      dated = new Set();
+      try {
+        if (realDirChain(root, ["openspec", "changes", "archive"])) {
+          for (const e of fs.readdirSync(path.join(root, "openspec", "changes", "archive"), { withFileTypes: true })) {
+            const m = e.isDirectory() ? DATED_ARCHIVE_RE.exec(e.name) : null;
+            if (m) dated.add(m[1]);
+          }
+        }
+      } catch {
+        // An unreadable archive names no change.
+      }
+    }
+    return dated.has(id);
+  };
+}
+
+const tsOf = (v) => (typeof v === "string" ? v : null);
+const tsOrder = (a, b) => (a === b ? 0 : a === null ? -1 : b === null ? 1 : a < b ? -1 : 1);
+
+/** The session's change: a lead archives its change before it ends, so its own ledger lines decide first, then its last OpenSpec invocation argument, then the newest in-flight brief. */
+export function resolveSessionChange(root, signals, ledger) {
+  const known = changeLookup(root);
+  const ranked = [...(ledger instanceof Map ? ledger : [])]
+    .filter(([dir, e]) => e && e.agents instanceof Set && known(dir))
+    .sort(([da, a], [db, b]) => b.agents.size - a.agents.size || tsOrder(tsOf(b.lastTs), tsOf(a.lastTs)) || (da < db ? -1 : 1))
+    .map(([dir]) => dir);
+  const named = [];
+  for (const s of Array.isArray(signals?.openspec) ? signals.openspec : []) {
+    const token = typeof s?.arg === "string" ? s.arg.trim().split(/\s+/, 1)[0] : null;
+    if (known(token)) named.push(token);
+  }
+  const change = ranked[0] ?? named[named.length - 1] ?? null;
+  if (change === null) {
+    // A brief header is free text, so it passes the same validity rule as the other signals.
+    const fallback = briefTags(root).change;
+    return known(fallback) ? { change: fallback, changes: [fallback] } : { change: null, changes: [] };
+  }
+  return { change, changes: [...new Set([change, ...ranked, ...named])].slice(0, MAX_SESSION_CHANGES) };
+}
+
+/** Task fields come from the resolved change's own brief, so a newer brief of another change never relabels the session. */
+function sessionTags(root, sessionId, signals) {
+  const { change, changes } = resolveSessionChange(root, signals, sessionLedger(root, sessionId));
+  const brief = change === null ? null : briefTags(root, change);
+  return { change, changes, task: brief?.task ?? null, tier: brief?.tier ?? null, task_class: brief?.task_class ?? "untagged" };
+}
+
+const MEM_DATA_DIR_KEYS = ["FREE_MEM_DATA_DIR", "CLAUDE_MEM_DATA_DIR"];
+const BOM = 0xfeff;
+
+function expandMemHome(p, home) {
+  if (p === "~") return home;
+  return p.startsWith("~/") ? path.join(home, p.slice(2)) : p;
+}
+
+function isMemDirectory(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Keys as the engine reads them: BOM dropped, `env` first. */
+function readMemSettings(file) {
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    const raw = JSON.parse(text.charCodeAt(0) === BOM ? text.slice(1) : text);
+    const s = raw && (raw.env ?? raw);
+    return s && typeof s === "object" ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The memory data directory from `env` and `home` alone (the engine's rule), so a test can pass fake values. */
+export function resolveMemoryDataDir(env, home) {
+  for (const key of MEM_DATA_DIR_KEYS) {
+    if (typeof env[key] === "string" && env[key]) return expandMemHome(env[key], home);
+  }
+  const freeDir = path.join(home, ".free-mem");
+  const legacyDir = path.join(home, ".claude-mem");
+  const defaults = [path.resolve(freeDir), path.resolve(legacyDir)];
+  for (const dir of [freeDir, legacyDir]) {
+    const s = readMemSettings(path.join(dir, "settings.json"));
+    for (const key of MEM_DATA_DIR_KEYS) {
+      const value = s ? s[key] : undefined;
+      if (typeof value !== "string" || !value) continue;
+      const target = expandMemHome(value, home);
+      // A seeded default is not a redirect; honoring it would pin the directory choice.
+      if (!defaults.includes(path.resolve(target))) return target;
+    }
+  }
+  return isMemDirectory(freeDir) || !isMemDirectory(legacyDir) ? freeDir : legacyDir;
+}
+
+/** A resolver error falls back to the legacy default directory. */
 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");
+  try {
+    return resolveMemoryDataDir(process.env, os.homedir());
+  } catch {
+    return path.join(os.homedir(), ".claude-mem");
+  }
+}
+
+/** `free-mem.db` when present, else the `claude-mem.db` an unmigrated engine still writes. */
+function memoryDatabase(dataDir) {
+  const db = path.join(dataDir, "free-mem.db");
+  return fs.existsSync(db) ? db : path.join(dataDir, "claude-mem.db");
 }
 
 /** The `sqlite3` binary from an absolute PATH entry only, never a bare name handed to the child process's PATH search. */
@@ -653,15 +1346,23 @@ 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`. */
+/** A database the consolidation migration has not reached lacks these tables; its observation rows still count. */
+const MISSING_CONSOLIDATION_TABLE = /no such table: (?:main\.)?consolidation_(?:calls|jobs)\b/;
+
+/** Observer spend for one session via a read-only `sqlite3` spawn: observation discovery tokens plus the session's consolidation provider calls. Failures and an unsafe id 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 (typeof sessionId !== "string" || !SAFE_SESSION_RE.test(sessionId)) return { reason: "unsafe session id" };
+  const db = memoryDatabase(dataDir);
   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;`;
+  const escaped = sessionId.replace(/'/g, "''");
+  // The consolidation statement runs last: sqlite3 prints each statement's rows before it prepares the next, so a missing table there leaves the observation rows intact.
+  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;`,
+    `SELECT c.model, COALESCE(SUM(c.tokens),0) FROM consolidation_calls c JOIN consolidation_jobs j ON c.job_id = j.id JOIN sdk_sessions s ON j.memory_session_id = s.memory_session_id WHERE s.content_session_id = '${escaped}' GROUP BY 1;`,
+  ].join(" ");
   let r;
   try {
     r = spawnSync(bin, ["-readonly", db, sql], { encoding: "utf8", timeout: 2000 });
@@ -669,9 +1370,8 @@ export function observerSink(sessionId, dataDir = memoryDataDir()) {
     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 };
+  if (r.status !== 0 && !MISSING_CONSOLIDATION_TABLE.test(r.stderr || "")) return { reason: `sqlite3 exited ${r.status}: ${(r.stderr || "").trim().slice(0, 200)}` };
+  const byModel = new Map();
   for (const raw of (r.stdout || "").split("\n")) {
     const line = raw.trim();
     if (!line) continue;
@@ -679,6 +1379,11 @@ export function observerSink(sessionId, dataDir = memoryDataDir()) {
     const tokens = Number.parseInt(tokensRaw, 10);
     if (!Number.isFinite(tokens)) continue;
     const model = modelRaw && modelRaw.trim() ? modelRaw.trim() : null;
+    byModel.set(model, (byModel.get(model) || 0) + tokens);
+  }
+  const claude = { tokens: 0, model: /** @type {string | null} */ (null), top: -1 };
+  const local = { tokens: 0, model: /** @type {string | null} */ (null), top: -1 };
+  for (const [model, tokens] of byModel) {
     const bucket = model && isClaudeModelId(model) ? claude : local;
     bucket.tokens += tokens;
     if (tokens > bucket.top) {
@@ -692,12 +1397,8 @@ export function observerSink(sessionId, dataDir = memoryDataDir()) {
 /** 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 };
-  }
+  const { text } = readContained(file, MAX_USAGE_LOG_BYTES);
+  if (text === null) return { started: null, contextMax: 0 };
   let started = null;
   let contextMax = 0;
   for (const raw of text.split("\n")) {
@@ -715,17 +1416,17 @@ function sessionState(file, sessionId) {
   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) {
+/** One telemetry record from the SessionEnd snapshot; `root` holds the SubagentStop ledgers. */
+export function telemetryRecord(snapshot, tags, observer, warnings, root = snapshot.cwd, signals = null) {
   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 zero = { input: 0, output: 0, cache_read: 0, cache_write: 0, cache_write_1h: 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 : "");
+  const dispatches = dispatchesByRole(typeof root === "string" ? root : "", typeof snapshot.session_id === "string" ? snapshot.session_id : "");
   return {
     ts: snapshot.ts,
     session_id: snapshot.session_id,
@@ -734,9 +1435,15 @@ export function telemetryRecord(snapshot, tags, observer, warnings) {
     ended: snapshot.ts,
     turns: snapshot.turns ?? 0,
     change: tags.change ?? null,
+    changes: Array.isArray(tags.changes) ? tags.changes : tags.change ? [tags.change] : [],
     task: tags.task ?? null,
     tier: tags.tier ?? null,
     task_class: tags.task_class ?? "untagged",
+    ...classifySession(signals, dispatches),
+    activity: snapshot.activity ?? "measured",
+    end_reason: snapshot.end_reason ?? null,
+    cc_version: ccVersionOf(snapshot.cc_version),
+    by_model: snapshot.by_model || {},
     sinks: {
       main: snapshot.usage || zero,
       subagents: snapshot.subagents || zero,
@@ -751,6 +1458,7 @@ export function telemetryRecord(snapshot, tags, observer, warnings) {
     est_usd: round(estUsdMain + estUsdSubagents),
     est_usd_main: estUsdMain,
     est_usd_subagents: estUsdSubagents,
+    ...(snapshot.price_estimated === true ? { price_estimated: true } : {}),
     context_max: snapshot.context_max ?? snapshot.context_tokens ?? 0,
     context_window: snapshot.context_window ?? 200_000,
     context_window_source: snapshot.context_window_source ?? "model",
@@ -759,39 +1467,63 @@ export function telemetryRecord(snapshot, tags, observer, warnings) {
   };
 }
 
-/** 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;
+/** Appends `text` to `file` without following a symlink leaf or blocking on a FIFO; only a
+ * regular file is written, since a cloned repository controls the telemetry path and the
+ * environment controls the usage-log path.
+ * @returns {{ok:true}|{ok:false, reason:string}} `reason` is a code, never a path.
+ */
+function appendContainedLine(file, text) {
+  const flags = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW | (fs.constants.O_NONBLOCK || 0);
+  let fd;
   try {
-    exists = fs.statSync(dir).isDirectory();
-  } catch {
-    exists = false;
+    fd = fs.openSync(file, flags, 0o644);
+  } catch (e) {
+    return { ok: false, reason: `open-refused ${errCode(e)}` };
   }
-  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");
+    if (!fs.fstatSync(fd).isFile()) return { ok: false, reason: "not-regular" };
+    fs.writeSync(fd, text);
+    return { ok: true };
   } catch (e) {
-    const msg = `telemetry write failed: ${e instanceof Error ? e.message : String(e)}`;
-    record.warnings = Array.isArray(record.warnings) ? [...record.warnings, msg] : [msg];
+    return { ok: false, reason: `write-failed ${errCode(e)}` };
+  } finally {
+    fs.closeSync(fd);
   }
 }
 
-/** 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;
+/** Appends one telemetry record when `.freeharness/` already exists as a real directory; never
+ * creates it. A refused or failed write lands as a snapshot warning. */
+function writeTelemetryIfPossible(record, root) {
+  const dir = path.join(root, ".freeharness");
+  let stat;
   try {
-    text = fs.readFileSync(logPath(), "utf8");
+    stat = fs.lstatSync(dir);
   } catch {
-    return 0;
+    return;
   }
+  const warn = (reason) => {
+    const msg = `telemetry write failed: ${reason}`;
+    record.warnings = Array.isArray(record.warnings) ? [...record.warnings, msg] : [msg];
+  };
+  if (stat.isSymbolicLink()) return warn("symlinked-dir");
+  if (!stat.isDirectory()) 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 tags = sessionTags(root, sessionId, record.signals);
+  const tel = telemetryRecord({ ...record, started, context_max: contextMax }, tags, observer, Array.isArray(record.warnings) ? record.warnings : [], root, record.signals);
+  const appended = appendContainedLine(path.join(dir, "telemetry.jsonl"), `${JSON.stringify(tel)}\n`);
+  if (!appended.ok) warn(appended.reason);
+}
+
+/** Bytes the output pruner recovered: the sum of `{kind:"pruned"}` lines with this session id in
+ * the cost log. A log over its cap counts 0 and pushes one warning onto `warnings` when given. */
+export function prunedBytesFor(sessionId, warnings) {
+  if (!sessionId) return 0;
+  const { text, reason } = readContained(logPath(), MAX_USAGE_LOG_BYTES);
+  if (reason === "too-large" && Array.isArray(warnings)) warnings.push("usage log over cap");
+  if (text === null) return 0;
   let total = 0;
   for (const raw of text.split("\n")) {
     if (!raw.includes('"pruned"') || !raw.includes(sessionId)) continue;
@@ -805,78 +1537,218 @@ export function prunedBytesFor(sessionId) {
   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) {
+/** The context monitor's rule, so both hooks keep per-session state in one directory. */
+function stateDir() {
+  return process.env.FREEHARNESS_STATE_DIR || path.join(os.homedir(), ".claude", "freeharness", "state");
+}
+
+/** The id becomes a file name, so one that could leave the state dir runs uncached. */
+const SAFE_SESSION_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const CACHE_COUNTS = ["input", "output", "cache_read", "cache_write", "cache_write_1h"];
+
+function subagentCachePath(sessionId) {
+  return typeof sessionId === "string" && SAFE_SESSION_RE.test(sessionId) ? path.join(stateDir(), `${sessionId}.subagents.json`) : null;
+}
+
+function isRecordObject(v) {
+  return Boolean(v) && typeof v === "object" && !Array.isArray(v);
+}
+
+function countOk(n) {
+  return typeof n === "number" && Number.isFinite(n) && n >= 0;
+}
+
+/** Rebuilds one entry field by field: the file sits in a user-writable dir and its totals are trusted unread. */
+function cacheEntry(raw) {
+  if (!isRecordObject(raw) || !countOk(raw.size) || !countOk(raw.mtimeMs) || !countOk(raw.messages)) return null;
+  if (typeof raw.key !== "string" || typeof raw.metaUnreadable !== "boolean" || !isRecordObject(raw.byModel)) return null;
+  const byModel = Object.create(null);
+  for (const [model, u] of Object.entries(raw.byModel)) {
+    if (!isRecordObject(u) || !CACHE_COUNTS.every((k) => countOk(u[k]))) return null;
+    byModel[model] = { input: u.input, output: u.output, cache_read: u.cache_read, cache_write: u.cache_write, cache_write_1h: u.cache_write_1h };
+  }
+  return { size: raw.size, mtimeMs: raw.mtimeMs, key: raw.key, metaUnreadable: raw.metaUnreadable, messages: raw.messages, byModel };
+}
+
+/** `{v, session, files}` or null; one off-shape entry voids the whole file, since a partial trust would mix forged and real totals. */
+export function readSubagentCache(sessionId) {
+  const file = subagentCachePath(sessionId);
+  if (!file) return null;
+  const { text } = readContained(file, MAX_SUBAGENT_CACHE_BYTES);
+  if (text === null) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecordObject(parsed) || parsed.v !== 1 || parsed.session !== sessionId || !isRecordObject(parsed.files)) return null;
+  const files = Object.create(null);
+  for (const [name, raw] of Object.entries(parsed.files)) {
+    const entry = cacheEntry(raw);
+    if (!entry) return null;
+    files[name] = entry;
+  }
+  return { v: 1, session: sessionId, files };
+}
+
+/** Temp file then rename: a reader never sees half a file and a symlink at the cache path is replaced, not followed. Failure is silent because the cache only saves time. */
+export function writeSubagentCache(sessionId, files) {
+  const file = subagentCachePath(sessionId);
+  if (!file) return;
+  const tmp = `${file}.${process.pid}.tmp`;
+  let fd;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.rmSync(tmp, { force: true });
+    fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    fs.writeFileSync(fd, JSON.stringify({ v: 1, session: sessionId, files }));
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(tmp, file);
+  } catch {
+    try {
+      if (fd !== undefined) fs.closeSync(fd);
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      // Nothing left to undo.
+    }
+  }
+}
+
+/** One subagent transcript reduced to what the snapshot and the cache share, or null when unusable. */
+function readSubagentEntry(file, metaFile, legacyName, stat) {
+  const sums = sumTranscript(file, MAX_SUBAGENT_FILE_BYTES);
+  if (!sums.found) return { entry: null, tooLarge: sums.reason === "too-large" };
+  let key = legacyName;
+  let metaUnreadable = false;
+  if (key === null) {
+    // A missing meta is an ordinary gap, so only a present but unusable one counts.
+    const { meta, reason } = loadAgentMeta(metaFile);
+    metaUnreadable = reason === "unreadable";
+    key = (meta.agentType && sanitizeTag(meta.agentType)) || "unknown";
+  }
+  let messages = 0;
+  const byModel = Object.create(null);
+  for (const [model, u] of Object.entries(sums.byModel)) {
+    messages += u.messages;
+    byModel[model] = { input: u.input, output: u.output, cache_read: u.cache_read, cache_write: u.cache_write, cache_write_1h: u.cache_write_1h };
+  }
+  const entry = { key, metaUnreadable, messages, byModel };
+  return { entry: stat ? { size: stat.size, mtimeMs: stat.mtimeMs, ...entry } : entry, tooLarge: false };
+}
+
+/**
+ * Builds the usage line for one hook invocation. `tags` is a param so `main()` computes it once and reuses it.
+ * `useCache` is the hook's alone: an in-process caller must not write session state.
+ * @returns The record, or null for a main transcript over its cap: a zeroed snapshot would
+ *   become the session's last one, and cost aggregation keeps only the last.
+ */
+export function buildRecord(payload, tags, { useCache = false } = {}) {
   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 };
+    ? sumTranscript(transcript, MAX_MAIN_TRANSCRIPT_BYTES)
+    : { byModel: Object.create(null), byTool: Object.create(null), turns: 0, lines: 0, contextTokens: 0, contextModel: "", toolOutputChars: 0, toolCalls: 0, found: false };
+  if (sums.reason === "too-large") return null;
   const total = bucket();
-  const byModel = {};
+  // Model names are transcript text, `by_agent` keys subagent meta `agentType` or a
+  // legacy file name; both are prototype-free.
+  const byModel = Object.create(null);
   let usd = 0;
+  let priceEstimated = false;
   for (const [model, u] of Object.entries(sums.byModel)) {
-    const est = estimate(u, priceFor(prices, model));
+    const match = priceMatch(prices, model);
+    const est = estimate(u, match.row);
     usd += est;
-    byModel[model] = { ...u, est_usd: round(est) };
+    if (match.estimated) priceEstimated = true;
+    byModel[model] = { ...u, est_usd: round(est), ...(match.estimated ? { price_estimated: true } : {}) };
     total.input += u.input;
     total.output += u.output;
     total.cache_read += u.cache_read;
     total.cache_write += u.cache_write;
+    total.cache_write_1h += u.cache_write_1h;
     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.
+  // dispatches of one key pool per-model sums, merged once. A current-shape file is keyed by its
+  // meta agent type, a legacy one by its parsed name. A transcript over 64 MB or past the cap is
+  // skipped with a warning. Stop fires every turn, so a file whose size and mtime match the
+  // session cache is summed from it unread.
   const subagentFiles = transcript ? subagentTranscripts(transcript) : [];
-  const by_agent = {};
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : "";
+  const cache = useCache ? readSubagentCache(sessionId) : null;
+  const prior = cache ? cache.files : Object.create(null);
+  const cacheFiles = Object.create(null);
+  let reused = 0;
+  let reread = false;
+  const by_agent = Object.create(null);
   const subagentsTotal = bucket();
   let subagentsUsd = 0;
-  const perAgentModelSums = {};
-  const dispatchCounts = {};
+  const perAgentModelSums = Object.create(null);
+  const dispatchCounts = Object.create(null);
+  const agentMessages = Object.create(null);
   let subagentsScanned = 0;
   let subagentsSkippedLarge = 0;
   let subagentsSkippedCap = 0;
-  for (const { name, file } of subagentFiles) {
+  let metasUnreadable = 0;
+  for (const { name: legacyName, file, metaFile } of subagentFiles) {
     if (subagentsScanned >= MAX_SUBAGENT_FILES) {
       subagentsSkippedCap += 1;
       continue;
     }
-    let size;
+    const base = path.basename(file);
+    let stat = null;
     try {
-      size = fs.statSync(file).size;
+      stat = fs.lstatSync(file);
+      if (!stat.isFile()) stat = null;
     } catch {
-      continue;
+      // The read below reports the file as unusable.
     }
-    if (size > MAX_SUBAGENT_FILE_BYTES) {
-      subagentsSkippedLarge += 1;
-      continue;
+    let entry = prior[base];
+    if (entry && stat && entry.size === stat.size && entry.mtimeMs === stat.mtimeMs) {
+      reused += 1;
+    } else {
+      reread = true;
+      const fresh = readSubagentEntry(file, metaFile, legacyName, stat);
+      if (!fresh.entry) {
+        if (fresh.tooLarge) subagentsSkippedLarge += 1;
+        continue;
+      }
+      entry = fresh.entry;
     }
-    const subSums = sumTranscript(file);
-    if (!subSums.found) continue;
     subagentsScanned += 1;
+    if (entry.size !== undefined) cacheFiles[base] = entry;
+    if (entry.metaUnreadable) metasUnreadable += 1;
+    const name = entry.key;
     dispatchCounts[name] = (dispatchCounts[name] || 0) + 1;
-    const acc = (perAgentModelSums[name] ??= {});
-    for (const [model, u] of Object.entries(subSums.byModel)) {
+    agentMessages[name] = (agentMessages[name] || 0) + entry.messages;
+    const acc = (perAgentModelSums[name] ??= Object.create(null));
+    for (const [model, u] of Object.entries(entry.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));
+      b.cache_write_1h += u.cache_write_1h;
+      const match = priceMatch(prices, model);
+      if (match.estimated) priceEstimated = true;
+      subagentsUsd += estimate(u, match.row);
     }
   }
+  const cacheChanged = cache ? reread || reused !== Object.keys(prior).length : Object.keys(cacheFiles).length > 0;
+  if (useCache && cacheChanged) writeSubagentCache(sessionId, cacheFiles);
   for (const [name, byModelForAgent] of Object.entries(perAgentModelSums)) {
     const merged = mergeAgentUsage(byModelForAgent);
-    by_agent[name] = { ...merged, dispatches: dispatchCounts[name] };
+    by_agent[name] = { ...merged, messages: agentMessages[name], 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;
+    subagentsTotal.cache_write_1h += merged.usage.cache_write_1h;
   }
 
   // The transcript's model id never carries a `[1m]` suffix, so one from settings.json is
@@ -902,15 +1774,28 @@ export function buildRecord(payload, tags) {
   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 (metasUnreadable > 0) warnings.push(`subagent meta unreadable: ${metasUnreadable}`);
   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 eventName = typeof payload.hook_event_name === "string" ? payload.hook_event_name : "Stop";
+  // A session with tokens (main or subagent) is measured; no-model-calls gates on main-context
+  // tokens, not the assistant message count, so a zero-usage <synthetic> line never counts as one.
+  const subagentTokens = subagentsTotal.input + subagentsTotal.output + subagentsTotal.cache_read + subagentsTotal.cache_write;
+  const mainTokens = total.input + total.output + total.cache_read + total.cache_write;
+  let activity;
+  if (!sums.found && subagentTokens === 0) activity = "no-transcript";
+  else if (sums.found && mainTokens === 0 && subagentTokens === 0) activity = "no-model-calls";
+  else activity = "measured";
+  const reasonRaw = typeof payload.reason === "string" && payload.reason !== "" ? payload.reason : null;
+  const sanitizedReason = eventName === "SessionEnd" && reasonRaw ? sanitizeTag(reasonRaw) : "";
+  const end_reason = sanitizedReason || null;
   const record = {
     ts: new Date().toISOString(),
-    event: typeof payload.hook_event_name === "string" ? payload.hook_event_name : "Stop",
+    event: eventName,
     session_id: typeof payload.session_id === "string" ? payload.session_id : "",
     project: path.basename(cwd),
     cwd,
@@ -921,6 +1806,7 @@ export function buildRecord(payload, tags) {
       output: total.output,
       cache_read: total.cache_read,
       cache_write: total.cache_write,
+      cache_write_1h: total.cache_write_1h,
       total: total.input + total.output + total.cache_read + total.cache_write,
     },
     by_model: byModel,
@@ -930,7 +1816,7 @@ export function buildRecord(payload, tags) {
     prices_file: pricesFile,
     cumulative: true,
     task_class: resolvedTags.task_class,
-    pruned_bytes: prunedBytesFor(typeof payload.session_id === "string" ? payload.session_id : ""),
+    pruned_bytes: prunedBytesFor(typeof payload.session_id === "string" ? payload.session_id : "", warnings),
     context_tokens: sums.contextTokens,
     tool_calls: sums.toolCalls,
     tool_output_chars: sums.toolOutputChars,
@@ -941,14 +1827,21 @@ export function buildRecord(payload, tags) {
       output: subagentsTotal.output,
       cache_read: subagentsTotal.cache_read,
       cache_write: subagentsTotal.cache_write,
+      cache_write_1h: subagentsTotal.cache_write_1h,
       total: subagentsTotal.input + subagentsTotal.output + subagentsTotal.cache_read + subagentsTotal.cache_write,
     },
     subagents_est_usd: round(subagentsUsd),
+    ...(priceEstimated ? { price_estimated: true } : {}),
     context_window,
     model_suffix,
     context_window_source,
+    activity,
+    end_reason,
+    cc_version: sums.ccVersion ?? null,
   };
   if (warnings.length > 0) record.warnings = warnings;
+  // Non-enumerable: telemetry reads the signals, JSON.stringify leaves them out of usage.jsonl.
+  Object.defineProperty(record, "signals", { value: sums.signals ?? { commands: [], skills: [], openspec: [] }, enumerable: false });
   return record;
 }
 
@@ -957,11 +1850,18 @@ function round(n) {
   return Math.round(n * 1e6) / 1e6;
 }
 
-/** Appends one record to the usage log, creating the directory on first use. */
+/** Appends one record to the usage log, creating the directory on first use; a refused mkdir
+ * or append writes one code-only stderr line. */
 export function appendRecord(record) {
   const file = logPath();
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.appendFileSync(file, `${JSON.stringify(record)}\n`, "utf8");
+  let appended;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    appended = appendContainedLine(file, `${JSON.stringify(record)}\n`);
+  } catch (e) {
+    appended = { ok: false, reason: `mkdir-failed ${errCode(e)}` };
+  }
+  if (!appended.ok) process.stderr.write(`freeharness-cost-tracker: usage log append refused: ${appended.reason}\n`);
   return file;
 }
 
@@ -981,15 +1881,16 @@ function main() {
     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);
+      // With no project above it the cwd stands in as the root, so ledgerLine reports its own refusals.
+      const root = projectRootFor(cwd) ?? cwd;
+      const result = ledgerLine(payload, root, 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`);
-        }
+        const recorded = readLedgerAgentIds(result.file, root);
+        const line = { ...result.line, resumed: recorded !== null && recorded.has(result.line.agent_id) };
+        const appended = appendLedgerLine(result.file, line, root);
+        // A refused append already reports once; the unknown-resumed line only qualifies a line that landed.
+        if (!appended.ok) reportLedgerRefusal(appended.reason);
+        else if (recorded === null) process.stderr.write("freeharness-cost-tracker: ledger ids unreadable; resumed unknown\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") {
@@ -999,20 +1900,30 @@ function main() {
       } 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.
+      // "no-brief": no in-flight brief declares the parsed task (a final review needs final.brief.md), or an unnamed dispatch finds no in-flight brief; silent.
       return;
     }
-    const tags = briefTags(cwd);
-    const record = buildRecord(payload, tags);
+    const root = projectRootFor(cwd) ?? cwd;
+    const tags = briefTags(root);
+    const record = buildRecord(payload, tags, { useCache: true });
     // 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 : [];
+    const warnings = record && Array.isArray(record.warnings) ? record.warnings : [];
     backfillLedger(payload, cwd, prices, warnings);
+    if (record === null) {
+      // No snapshot carries the backfill's warnings on this run, so stderr does; a refused
+      // append is already there once.
+      for (const warning of new Set(warnings)) {
+        if (!warning.startsWith("ledger backfill append refused:")) process.stderr.write(`freeharness-cost-tracker: ${warning}\n`);
+      }
+      process.stderr.write(`freeharness-cost-tracker: main transcript over ${MAX_MAIN_TRANSCRIPT_BYTES / (1024 * 1024)} MB cap, no snapshot\n`);
+      return;
+    }
     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);
+    if (record.event === "SessionEnd") writeTelemetryIfPossible(record, root);
     appendRecord(record);
   } catch (e) {
     // Last resort: say why on stderr (Claude Code shows it in debug mode), never fail.