@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/hooks/claude-code/core/telemetry-log.js

@@ -3,76 +3,80 @@
 /**
  * Telemetry Hook: harness execution-path capture
  *
- * Events: PostToolUse (all tools) + UserPromptSubmit
+ * Events: PostToolUse + PostToolUseFailure (all tools), PostToolBatch,
+ * SubagentStop, UserPromptSubmit
  *
  * morph-spec is a Natural Language Harness: there is no central runtime to
  * instrument — Claude Code executes the skills and sub-agents. The only
  * vantage points are hooks. This one is the generic capture point: every tool
  * call and every user prompt is appended (one JSON line) to
- * .morph/logs/events.jsonl, from which `morph-spec telemetry` reconstructs the
- * whole path — which skills ran, which personas were dispatched (with their
- * prompts), which standards/knowledge-base files were read.
+ * .morph/logs/events.jsonl, from which `morph-spec telemetry` and
+ * `morph-spec cost` reconstruct the path and measure it.
  *
  * Correlation is by an EXPLICIT key (feature + phase) written into each event,
  * not by ambient span context — hooks fire as separate node processes with no
- * shared trace context (the enrichment lesson from the observability standard:
- * propagate a correlation key, a TraceId does not survive the boundary).
+ * shared trace context. `sessionId` and `agentId` (present only inside a
+ * sub-agent) separate the orchestrator from the sub-agents it dispatched.
+ *
+ * PostToolUse fires only when a tool SUCCEEDS; a Bash command that exits
+ * non-zero fires PostToolUseFailure instead. Only the exit code parsed from
+ * its `error` first line is kept — the rest of `error` is the command's
+ * output, where a secret value can appear with no name beside it.
  *
  * SINK RESOLUTION: the event is appended to the `.morph/` tree that OWNS the
- * tool's target file, not to `process.cwd()`/`CLAUDE_PROJECT_DIR` — same
- * pattern as trace-autogen/state-sync (`resolveMorphRoot`). A session rooted
- * in the primary repo can legitimately touch a feature living in a secondary
- * git worktree; sinking on the session's cwd put those events in the WRONG
- * tree's events.jsonl, the mirror of the trace-autogen worktree defect. Tools
- * that carry no file_path (Bash, Skill, Agent…) have no target to resolve —
- * the session cwd stays the reference for those, same as before.
+ * tool's target file (`resolveMorphRoot`); tools with no file path sink on the
+ * nearest morph tree above the payload's `cwd`, so a sub-agent working in a
+ * worktree logs its Bash calls next to its Reads and Writes.
  *
  * SILENT: never blocks, never injects context — only appends. Fail-open on any
  * error (exit 0). Only active inside a morph project (stateExists gate).
  */
 
-import { statSync } from 'fs';
+import { statSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
 import { stateExists, getActiveFeature, derivePhaseForFeature } from '../../shared/state-reader.js';
 import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
 import { runStandalone } from '../../shared/hook-response.js';
 import { getFilePath, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
+import { redactSecrets } from '../../shared/redact-secrets.js';
+import { exitCodeMasked } from '../../shared/command-tokens.js';
+import { readTranscriptUsage, usageDelta } from '../../shared/transcript-usage.js';
 
 function normalize(p) {
   return (p || '').replace(/\\/g, '/');
 }
 
-// events.jsonl grows forever across a project's lifetime (R2 rotation caps
-// the FILE, not any single line) — a multi-KB sub-agent prompt or a long
-// Bash command written verbatim on every dispatch/call is the dominant per-
-// line cost. Capped AT THE WRITE SITE (not in the shared logger, so every
-// OTHER event type stays exactly as-is) to `MAX_FIELD_CHARS`, with the
-// ORIGINAL length preserved in a sibling `<field>Chars` key — `morph-spec
-// cost` sums prompt chars for its dispatch-cost view, and must prefer that
-// field over `prompt.length` once it's present (a truncated string's own
-// length would silently undercount every dispatch over the cap). This shape
-// is a CONTRACT with the telemetry reader — do not rename either half.
+// A multi-KB prompt or command written verbatim on every call dominates the
+// per-line cost. The ORIGINAL length travels in a sibling `<field>Chars` key,
+// which `morph-spec cost` prefers over the truncated string's own length —
+// a contract with the telemetry reader: do not rename either half.
 const MAX_FIELD_CHARS = 2000;
 const TRUNCATE_SUFFIX = '…[truncado]';
 
+// Read returns this many lines when the call passes no `limit`.
+const DEFAULT_READ_LINES = 2000;
+// Above this, measuring the slice would cost more than the hook budget allows.
+const MAX_SLICE_BYTES = 10 * 1024 * 1024;
+const BINARY_READ = /\.(png|jpe?g|gif|webp|bmp|ico|pdf)$/i;
+
 /**
- * Cap a free-text field (prompt/command) at MAX_FIELD_CHARS, always
- * reporting the field's true original length alongside it.
+ * Redact, then cap a free-text field, reporting its original length. Redacting
+ * first keeps a token cut at the cap from surviving as a recognizable prefix.
  *
  * @param {string} value
  * @returns {{ value: string, chars: number }}
  */
 function capField(value) {
   const str = typeof value === 'string' ? value : '';
-  if (str.length <= MAX_FIELD_CHARS) return { value: str, chars: str.length };
-  return { value: str.slice(0, MAX_FIELD_CHARS) + TRUNCATE_SUFFIX, chars: str.length };
+  const clean = redactSecrets(str);
+  if (clean.length <= MAX_FIELD_CHARS) return { value: clean, chars: str.length };
+  return { value: clean.slice(0, MAX_FIELD_CHARS) + TRUNCATE_SUFFIX, chars: str.length };
 }
 
 /**
  * Classify a Read target into the telemetry `kind` taxonomy — a contract with
- * the observability side (src/lib/telemetry/telemetry-reader.js), so these
- * values are pinned, not free-form. Order matters: check the specific
- * categories before falling back to 'code'. Case-insensitive; `/` and `\`
- * both normalize to `/` upstream via `normalize()`.
+ * src/lib/telemetry/telemetry-reader.js, so these values are pinned. Specific
+ * categories first, 'code' last.
  */
 function classifyReadKind(target) {
   const t = (target || '').toLowerCase();
@@ -82,9 +86,6 @@ function classifyReadKind(target) {
   if (t.endsWith('skill.md') || t.includes('/skills/')) return 'skill';
   if (t.split('/').pop() === 'agents.json') return 'agents';
 
-  // Inside a feature folder AND one of the named plan artifacts (or under a
-  // usecases/ or reports/ subfolder) — everything else in a feature folder
-  // (source files a task produced, say) is 'code'.
   const inFeature = t.match(/\.morph\/features\/[^/]+\/(.+)$/);
   if (inFeature) {
     const rel = inFeature[1];
@@ -101,60 +102,118 @@ function classifyReadKind(target) {
   return 'code';
 }
 
+/** Nearest directory at or above `dir` that is a morph project; `fallback` when none. */
+function morphRootAbove(dir, fallback) {
+  if (!dir) return fallback;
+  let current = normalize(dir);
+  for (let i = 0; i < 32; i++) {
+    if (stateExists(current)) return current;
+    const parent = normalize(dirname(current));
+    if (parent === current) break;
+    current = parent;
+  }
+  return fallback;
+}
+
+function featureFromPath(target) {
+  const m = /\/\.morph\/features\/([^/]+)\//.exec(`/${normalize(target)}`);
+  return m ? m[1] : null;
+}
+
 /**
- * @param {object} payload - parsed PostToolUse (any tool) or UserPromptSubmit payload
- * @returns {Promise<null>} always null — this hook is pure side-effect
- *   (appends to events.jsonl + claim heartbeat), never prints/injects context.
+ * What a Read actually put in context: the requested line window, not the
+ * whole file. Binary reads (images, PDFs) go in whole.
+ */
+function readSliceBytes(absPath, input, size) {
+  if (BINARY_READ.test(absPath)) return size;
+  if (size > MAX_SLICE_BYTES) return undefined;
+  const offset = Number.isInteger(input.offset) && input.offset > 1 ? input.offset : 1;
+  const limit = Number.isInteger(input.limit) && input.limit > 0 ? input.limit : DEFAULT_READ_LINES;
+  const lines = readFileSync(absPath, 'utf-8').split('\n');
+  if (offset === 1 && limit >= lines.length) return size;
+  return Buffer.byteLength(lines.slice(offset - 1, offset - 1 + limit).join('\n'), 'utf-8');
+}
+
+/** Exit code and outcome of a finished tool call, without keeping its output. */
+function outcomeOf(payload, input) {
+  if (payload.hook_event_name === 'PostToolUseFailure') {
+    const firstLine = String(payload.error ?? '').split('\n', 1)[0];
+    const code = /^exit code (\d+)/i.exec(firstLine);
+    const outcome = payload.is_interrupt === true ? 'interrupted'
+      : /timed? ?out/i.test(firstLine) ? 'timeout'
+        : 'error';
+    return { outcome, exitCode: code ? Number(code[1]) : null };
+  }
+  if (input.run_in_background === true) return { outcome: 'background', exitCode: null };
+  if (payload.tool_response?.interrupted === true) return { outcome: 'interrupted', exitCode: null };
+  return { outcome: 'ok', exitCode: 0 };
+}
+
+function countByName(calls) {
+  const out = {};
+  for (const call of calls) {
+    const name = call?.tool_name || 'unknown';
+    out[name] = (out[name] || 0) + 1;
+  }
+  return out;
+}
+
+/**
+ * Sub-agent tokens live in their own transcript; each stop emits the delta.
+ * One file per agent: two sub-agents stopping together never share a
+ * read-modify-write, and one agent never stops twice at once.
+ */
+function agentUsageEvent(payload, cwd) {
+  const usage = readTranscriptUsage(payload.agent_transcript_path);
+  if (!usage || !payload.agent_id) return null;
+  const dir = join(cwd, '.morph', 'memory', 'agent-usage');
+  const storePath = join(dir, `${String(payload.agent_id).replace(/[^A-Za-z0-9_-]/g, '_')}.json`);
+  let previous = null;
+  try {
+    if (existsSync(storePath)) previous = JSON.parse(readFileSync(storePath, 'utf-8'));
+  } catch { previous = null; }
+  const { delta, changed } = usageDelta(previous, usage);
+  if (!changed) return null;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(storePath, JSON.stringify(usage), 'utf-8');
+  } catch { /* the event still carries the delta */ }
+  return { event: 'AgentUsage', ...usage, delta };
+}
+
+/**
+ * @param {object} payload - parsed hook payload (PostToolUse, PostToolUseFailure,
+ *   PostToolBatch, SubagentStop or UserPromptSubmit)
+ * @returns {Promise<null>} always null — pure side effect (append + claim heartbeat)
  */
 export async function run(payload) {
   try {
     if (!payload) return null;
 
-    // Resolve the sink tree from the tool's target file (when it has one)
-    // BEFORE the stateExists gate below — otherwise a root session writing
-    // into a worktree would be gated on the ROOT's state instead of the
-    // worktree's.
     const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
     const targetFilePath = getFilePath(payload);
-    const cwd = targetFilePath ? resolveMorphRoot(targetFilePath, projectDir) : projectDir;
+    const cwd = targetFilePath
+      ? resolveMorphRoot(targetFilePath, projectDir)
+      : morphRootAbove(payload.cwd, projectDir);
 
     if (!stateExists(cwd)) return null;
 
-    // Correlation key: active feature + its phase (explicit, not ambient).
-    // NOTE (perf): getActiveFeature → loadState hydrates every .morph/features/*/
-    // feature.json, so enrichment is O(active-feature-count) per tool call. That
-    // is fine for realistic projects (archive removes finished features, so the
-    // dir holds only the few in-flight ones) but would grow on a project that
-    // keeps many un-archived features. If that ever bites, resolve the active
-    // feature from the thin state.json index alone. Kept accurate-over-cheap for
-    // now because phase is not stored in feature.json — it needs derivation.
+    // getActiveFeature → loadState hydrates every feature.json: O(active
+    // features) per call, fine while archive keeps that set small.
     let feature = null;
     let phase = null;
     try {
       const active = getActiveFeature(cwd);
-      if (active) {
-        feature = active.name;
-        phase = active.feature?.phase || derivePhaseForFeature(active.name, cwd);
-      }
+      feature = active?.name ?? featureFromPath(targetFilePath);
+      if (feature) phase = active?.feature?.phase || derivePhaseForFeature(feature, cwd);
     } catch {
       // enrichment is best-effort — a missing feature never blocks capture
     }
 
-    // Claim heartbeat (B1): this hook already fires on EVERY tool call, so it is
-    // the natural proof-of-life for the advisory feature claim — no extra hook,
-    // no discipline asked of the operator. Two throttles guard the cost:
-    //   1. shouldHeartbeat() — a LOCAL, git-independent pre-check (see its own
-    //      doc in claim-registry.js) that answers "is a heartbeat even due"
-    //      from a marker beside this project's own `.morph/logs/`. On ~99% of
-    //      calls it says no and NOTHING git-related happens — not even the
-    //      pure-FS walk below, let alone a subprocess.
-    //   2. Only when (1) says yes do we resolve the git common dir — via
-    //      git-paths.js, pure filesystem, no `git` subprocess spawn (this used
-    //      to be `execSync('git rev-parse --git-common-dir')`, ~34ms wasted on
-    //      ~99% of calls because the write below was ALREADY throttled) — and
-    //      call heartbeatClaim(), which has its own authoritative throttle
-    //      keyed to claims.json's stored heartbeatAt.
-    // Silent and fail-open, like everything else here.
+    // Claim heartbeat: this hook fires on every tool call, so it is the proof
+    // of life for the advisory feature claim. shouldHeartbeat() is a local,
+    // git-free pre-check that says no on ~99% of calls; only then is the git
+    // common dir resolved (pure filesystem, no subprocess).
     if (feature && payload.session_id) {
       try {
         const { shouldHeartbeat, heartbeatClaim } = await import('../../shared/claim-registry.js');
@@ -166,51 +225,77 @@ export async function run(payload) {
       } catch { /* fail-open — a missed heartbeat only shortens a claim's life */ }
     }
 
+    const hookEvent = payload.hook_event_name;
     let event;
 
-    // UserPromptSubmit carries the user's prompt and no tool_name.
-    if (payload.hook_event_name === 'UserPromptSubmit' || (!payload.tool_name && typeof payload.prompt === 'string')) {
+    if (hookEvent === 'UserPromptSubmit' || (!payload.tool_name && typeof payload.prompt === 'string' && !hookEvent)) {
       const userPrompt = capField(payload.prompt || '');
       event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: userPrompt.value, promptChars: userPrompt.chars };
+    } else if (hookEvent === 'PostToolBatch') {
+      const calls = Array.isArray(payload.tool_calls) ? payload.tool_calls : [];
+      event = { event: 'ToolBatch', size: calls.length, tools: countByName(calls) };
+    } else if (hookEvent === 'SubagentStop') {
+      event = agentUsageEvent(payload, cwd);
+      if (!event) return null;
     } else {
       const tool = payload.tool_name;
       if (!tool) return null;
       const input = payload.tool_input || {};
-      event = { event: 'PostToolUse', tool };
+      event = { event: hookEvent === 'PostToolUseFailure' ? 'PostToolUseFailure' : 'PostToolUse', tool };
 
       if (tool === 'Skill') {
         event.skill = input.skill || '';
       } else if (tool === 'Agent' || tool === 'Task') {
         event.persona = input.subagent_type || '';
-        if (input.description) event.desc = input.description;
+        if (input.description) event.desc = redactSecrets(input.description);
         const dispatchPrompt = capField(input.prompt || '');
         event.prompt = dispatchPrompt.value;
         event.promptChars = dispatchPrompt.chars;
+      } else if (tool === 'SendMessage') {
+        if (input.to) event.target = String(input.to);
+        event.messageChars = typeof input.message === 'string' ? input.message.length : 0;
       } else if (tool === 'Read') {
         event.target = targetFilePath || normalize(input.file_path || input.path);
         event.kind = classifyReadKind(event.target);
-        // bytes is best-effort: statSync races a file that got deleted/moved
-        // between the Read and this hook firing, or lacks permission — omit
-        // the field rather than fail the whole (silent, fail-open) capture.
-        try {
-          event.bytes = statSync(resolveTargetPath(event.target, cwd)).size;
-        } catch {
-          // omit bytes
+        if (Number.isInteger(input.offset)) event.offset = input.offset;
+        if (Number.isInteger(input.limit)) event.limit = input.limit;
+        // A failed Read ingested nothing. A stat/read race with a file deleted
+        // between the Read and this hook omits the numbers rather than fail.
+        if (hookEvent !== 'PostToolUseFailure') {
+          try {
+            const abs = resolveTargetPath(event.target, cwd);
+            event.bytes = statSync(abs).size;
+            const read = readSliceBytes(abs, input, event.bytes);
+            if (read !== undefined) event.bytesRead = read;
+          } catch {
+            // omit bytes
+          }
         }
-      } else if (tool === 'Bash') {
-        const bashCommand = capField(input.command || '');
-        event.command = bashCommand.value;
-        event.commandChars = bashCommand.chars;
+      } else if (tool === 'Bash' || tool === 'PowerShell') {
+        const command = capField(input.command || '');
+        event.command = command.value;
+        event.commandChars = command.chars;
+        Object.assign(event, outcomeOf(payload, input));
+        if (exitCodeMasked(input.command)) event.exitMasked = true;
       } else if (tool === 'Write' || tool === 'Edit') {
         event.target = normalize(input.file_path || input.path);
       } else {
-        // Every other tool still counts toward "the whole path" — record a
-        // compact target so Grep/Glob/WebFetch bursts remain distinguishable.
+        // Every other tool still counts toward "the whole path" — a compact
+        // target keeps Grep/Glob/WebFetch bursts distinguishable.
         const target = input.file_path || input.path || input.pattern || input.query || input.url || '';
         if (target) event.target = normalize(String(target));
       }
+
+      if (hookEvent === 'PostToolUseFailure' && event.outcome === undefined) event.outcome = 'error';
+      if (payload.tool_use_id) event.toolUseId = payload.tool_use_id;
+      if (Number.isFinite(payload.duration_ms)) event.durationMs = payload.duration_ms;
     }
 
+    if (payload.session_id) event.sessionId = payload.session_id;
+    if (payload.prompt_id) event.promptId = payload.prompt_id;
+    if (payload.agent_id) event.agentId = payload.agent_id;
+    if (payload.agent_type) event.agentType = payload.agent_type;
+    if (payload.cwd) event.cwd = normalize(payload.cwd);
     event.feature = feature;
     event.phase = phase;
 

package/framework/hooks/claude-code/core/validate-completion.js

@@ -21,7 +21,7 @@
  * Fail-open: exits 0 on any error.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, statSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { createHash } from 'crypto';
 import { runBuildCheck } from '../../shared/build-check.js';
@@ -31,6 +31,7 @@ import {
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
 import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
+import { readTranscriptUsage, usageDelta } from '../../shared/transcript-usage.js';
 
 /**
  * Audit recap.md against tasks.json + standard-citation rule.
@@ -122,80 +123,6 @@ function auditRecapAndTasks(featurePath) {
   return warnings;
 }
 
-// Safety valve for a pathological outlier transcript — NOT needed for the
-// normal case: a real 45 MB / ~16k-line transcript (inspected directly while
-// building this) parses+sums in ~350ms locally, well inside a Stop hook's
-// budget. Above this, skip rather than risk an unbounded read.
-const MAX_TRANSCRIPT_BYTES = 50 * 1024 * 1024; // 50 MB
-
-/**
- * Sum real token usage from a Claude Code session transcript (JSONL, the
- * `transcript_path` the Stop payload carries).
- *
- * Each assistant TURN is written to the transcript as MULTIPLE JSONL lines —
- * one per content block (thinking/text/tool_use) — every one of them
- * repeating the exact SAME turn-level `message.usage` object under the same
- * `message.id`. Verified against a real transcript: 5982 assistant lines but
- * only 3315 unique message ids, with byte-identical usage across duplicates
- * of the same id — summing every line naively double/triple-counts (measured
- * ~2x on output_tokens on that file). This is why a per-line sum is wrong and
- * a dedup-by-id sum is required; there is no running/cumulative total field
- * to lean on instead — each turn's `usage` is that turn's own cost.
- *
- * Tolerant to shape: any missing usage field reads as 0. A corrupt/truncated
- * line is skipped, not fatal — same discipline as telemetry-logger's reader.
- *
- * @param {string} [transcriptPath]
- * @returns {{inputTokens:number,outputTokens:number,cacheReadTokens:number,cacheCreationTokens:number}|null}
- *   null when there is nothing to report (no path, missing/oversized/
- *   unreadable file, or zero assistant messages carrying usage).
- */
-function computeSessionUsage(transcriptPath) {
-  if (!transcriptPath || typeof transcriptPath !== 'string') return null;
-  try {
-    if (!existsSync(transcriptPath)) return null;
-    if (statSync(transcriptPath).size > MAX_TRANSCRIPT_BYTES) return null;
-
-    const raw = readFileSync(transcriptPath, 'utf-8');
-    let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheCreationTokens = 0;
-    const seenMessageIds = new Set();
-    let sawAny = false;
-
-    for (const line of raw.split('\n')) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      let entry;
-      try {
-        entry = JSON.parse(trimmed);
-      } catch {
-        continue; // one corrupt/truncated line must not lose the whole transcript
-      }
-      if (entry?.type !== 'assistant') continue;
-      const usage = entry?.message?.usage;
-      if (!usage || typeof usage !== 'object') continue;
-
-      // Dedup by message.id (fallback to the line's own uuid when a message
-      // carries none) — first occurrence wins, duplicates carry identical
-      // values so which one wins never matters.
-      const dedupKey = entry?.message?.id || entry?.uuid;
-      if (dedupKey) {
-        if (seenMessageIds.has(dedupKey)) continue;
-        seenMessageIds.add(dedupKey);
-      }
-
-      sawAny = true;
-      inputTokens += Number(usage.input_tokens) || 0;
-      outputTokens += Number(usage.output_tokens) || 0;
-      cacheReadTokens += Number(usage.cache_read_input_tokens) || 0;
-      cacheCreationTokens += Number(usage.cache_creation_input_tokens) || 0;
-    }
-
-    return sawAny ? { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens } : null;
-  } catch {
-    return null; // fail-open
-  }
-}
-
 // Phases where compaction is strongly recommended before starting
 const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 
@@ -343,13 +270,11 @@ export async function run(payload) {
     // ────────────────────────────────────────────────────────────────────────
 
     // ── Session usage (real tokens, from the transcript) ──────────────────────
-    // Silent side effect — never contributes to `warnings`/additionalContext,
-    // same as telemetry-log.js's capture. Throttled: only re-emitted when the
-    // computed totals actually changed since the last SessionUsage recorded
-    // for this session_id, so an unchanged transcript across consecutive
-    // Stops (no new assistant turn) does not re-append an identical event.
+    // Silent side effect. The transcript total is cumulative, so each event
+    // also carries the `delta` since the previous sample of the same session:
+    // summing deltas per sessionId is the only sum that does not double-count.
     try {
-      const usage = computeSessionUsage(payload?.transcript_path);
+      const usage = readTranscriptUsage(payload?.transcript_path);
       if (usage) {
         const usagePath = join(memDir, 'session-usage.json');
         let stored = {};
@@ -358,15 +283,16 @@ export async function run(payload) {
         } catch { /* corrupt file — start fresh */ }
 
         const sessionKey = payload?.session_id || 'default';
-        const last = stored[sessionKey];
-        const unchanged = last
-          && last.inputTokens === usage.inputTokens
-          && last.outputTokens === usage.outputTokens
-          && last.cacheReadTokens === usage.cacheReadTokens
-          && last.cacheCreationTokens === usage.cacheCreationTokens;
-
-        if (!unchanged) {
-          appendTelemetryEvent({ event: 'SessionUsage', ...usage }, cwd);
+        const { delta, changed } = usageDelta(stored[sessionKey], usage);
+        if (changed) {
+          appendTelemetryEvent({
+            event: 'SessionUsage',
+            sessionId: payload?.session_id ?? null,
+            feature: name,
+            phase: currentPhase,
+            ...usage,
+            delta,
+          }, cwd);
           stored[sessionKey] = usage;
           try { writeFileSync(usagePath, JSON.stringify(stored, null, 2), 'utf-8'); } catch { /* non-blocking */ }
         }

package/framework/hooks/claude-code/core/worktree-context.js

@@ -50,6 +50,7 @@ import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { acquireClaim, foreignClaim, claimAge } from '../../shared/claim-registry.js';
 import { rotateActivityLogIfLarge } from '../../shared/activity-logger.js';
 import { rotateEventsLogIfLarge } from '../../shared/telemetry-logger.js';
+import { kickGraphRefresh, seedFromPrimary } from '../../shared/graph-refresh.js';
 
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -293,6 +294,15 @@ export async function run(payload) {
     // helpers are themselves fail-open (return false on any error).
     try { rotateActivityLogIfLarge(dir); } catch { /* non-blocking */ }
     try { rotateEventsLogIfLarge(dir); } catch { /* non-blocking */ }
+    // Between sessions is where commits made outside the agent (a terminal, an
+    // IDE, a `git pull`) are caught: the detached refresh brings the ROOT's
+    // graph to HEAD — never a worktree's (a detached process holding a
+    // worktree directory made `finish` fail on win32). A worktree that has no
+    // graph yet (created before seeding existed) gets the root's copy here;
+    // from then on it is refreshed by hand (`morph-spec graph refresh`).
+    // Returns immediately — nothing here waits on graphify.
+    try { seedFromPrimary(dir); } catch { /* non-blocking — a no-op on the root */ }
+    try { kickGraphRefresh(dir); } catch { /* non-blocking */ }
 
     if (isSecondaryWorktree(dir)) {
       const task = taskFromBranch(dir);

package/framework/hooks/shared/command-tokens.js

@@ -21,3 +21,99 @@ export function tokenize(command) {
   while ((m = re.exec(String(command || ''))) !== null) tokens.push(m[1] ?? m[2] ?? m[3]);
   return tokens;
 }
+
+/** Index of the first pipe (`|`, not `||` nor `>|`) outside quotes, or -1. */
+function firstUnquotedPipe(command) {
+  const s = String(command || '');
+  let quote = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      else if (ch === '\\' && quote === '"') i++;
+      continue;
+    }
+    if (ch === '\\') { i++; continue; }
+    if (ch === '"' || ch === "'") { quote = ch; continue; }
+    if (ch !== '|') continue;
+    if (s[i + 1] === '|') { i++; continue; }
+    if (s[i - 1] === '>') continue;
+    return i;
+  }
+  return -1;
+}
+
+/**
+ * Does the command pipe one process into another outside quotes? Without
+ * `pipefail` the shell reports the LAST command's status, so the exit code of
+ * `dotnet test … | grep …` is grep's, not the test run's.
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function hasUnquotedPipe(command) {
+  return firstUnquotedPipe(command) >= 0;
+}
+
+/**
+ * The work a command does, without the filter that shapes its output:
+ * `dotnet test 2>&1 | tail -25` and `dotnet test | tail -20` run the same
+ * tests. Whitespace collapsed, stderr redirections dropped.
+ * @param {string} command
+ * @returns {string}
+ */
+export function producerOf(command) {
+  const s = String(command || '');
+  const pipe = firstUnquotedPipe(s);
+  return (pipe >= 0 ? s.slice(0, pipe) : s)
+    .replace(/\s2>(&1|\/dev\/null|nul)\b/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * The command split at `;`, newline and background `&` outside quotes, plus
+ * whether a background `&` was seen. `&&`, `||` and `>&`/`&>` redirections
+ * stay inside their segment.
+ */
+function topLevelSegments(command) {
+  const s = String(command || '');
+  const segments = [];
+  let start = 0;
+  let background = false;
+  let quote = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      else if (ch === '\\' && quote === '"') i++;
+      continue;
+    }
+    if (ch === '\\') { i++; continue; }
+    if (ch === '"' || ch === "'") { quote = ch; continue; }
+    const isAmp = ch === '&' && s[i + 1] !== '&' && s[i - 1] !== '&' && s[i - 1] !== '>' && s[i + 1] !== '>';
+    if (ch !== ';' && ch !== '\n' && !isAmp) continue;
+    if (isAmp) background = true;
+    segments.push(s.slice(start, i));
+    start = i + 1;
+  }
+  segments.push(s.slice(start));
+  return { segments: segments.map((x) => x.trim()).filter(Boolean), background };
+}
+
+const REPORTER = /^(?:echo|printf|true|:|exit\s+0)\b/;
+
+/**
+ * Is the exit code of this command the exit code of the work it ran? The
+ * shell reports the last segment of a `;` sequence: `dotnet test > log;
+ * echo "exit=$?"` always exits 0, and so does `dotnet test || true`. A pipe
+ * without `pipefail` reports the filter, and a background `&` reports 0.
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function exitCodeMasked(command) {
+  const { segments, background } = topLevelSegments(command);
+  if (background) return true;
+  if (hasUnquotedPipe(command) && !/\bpipefail\b/.test(String(command || ''))) return true;
+  const last = segments[segments.length - 1] || '';
+  return (segments.length > 1 && REPORTER.test(last)) || /\|\|/.test(last.replace(/"[^"]*"|'[^']*'/g, ''));
+}