@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/framework/hooks/shared/state-reader.js

@@ -1,11 +1,4 @@
-/**
- * Shared read-only state accessor for Claude Code hooks.
- *
- * Wraps state.json reads with fail-open semantics:
- * - Returns null instead of throwing on missing/corrupt state
- * - Never writes to state.json (read-only)
- * - Uses synchronous reads for <100ms performance
- */
+// Fail-open: missing or corrupt state reads as null, never throws.
 
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
@@ -13,80 +6,15 @@ import { join } from 'path';
 const STATE_FILE = '.morph/state.json';
 const FEATURES_DIR = '.morph/features';
 
-/**
- * Module-level memoization of `loadState()`, keyed by `projectPath`.
- *
- * `loadState()` does a `readdirSync` of `.morph/features` plus a
- * `readFileSync` + `JSON.parse` of EVERY `feature.json` under it, on every
- * call. A single hook invocation calls it 1-3x (directly, or via
- * `getActiveFeature`/`derivePhaseForFeature`/`isGateApproved`/etc.) — re-doing
- * that full hydration each time is pure waste when nothing on disk changed
- * between those calls.
- *
- * SAFE because every hook process is short-lived and single-invocation: one
- * `node state-reader.js`-importing process handles exactly one tool call (or
- * one CLI command) and exits. There is no risk of the cache going stale
- * ACROSS invocations, because each invocation starts with an empty Map.
- * Within a SINGLE invocation, staleness would only matter if that same
- * process both reads and then writes a feature's `feature.json` and
- * expects a LATER read to see the write — verified (grep across every
- * consumer, 2026-08-11) that the one hook that writes feature.json
- * (`state-sync.js`) never re-reads through `loadState()` after writing in the
- * same invocation; its `AskUserQuestion` handler reads via
- * `readFeatureFile()` (a different, uncached module) as the PRIMARY path and
- * only falls back to `loadState()` for a feature that has NEVER had a
- * feature.json written — which, by construction, can't have just been
- * written to in this same invocation either.
- *
- * A directory-mtime-based invalidation was considered instead (so a
- * LONG-LIVED consumer could reuse this module safely too) but rejected on two
- * grounds: (1) verified — grep for every importer of this file — that none is
- * long-lived (they're all hooks, one process per tool call, or CLI commands,
- * one process per invocation; the dashboard is a separate Vite/React app and
- * the statusline is Python, neither imports this module); and (2) even if one
- * existed, `.morph/features`'s own mtime only changes when feature
- * DIRECTORIES are added/removed, not when an EXISTING feature.json's content
- * is overwritten in place — so mtime-of-the-dir can't actually detect the
- * mutation that matters here, and getting that right would mean stat'ing
- * every feature.json individually, which re-adds the very cost this cache
- * exists to remove. If a long-lived consumer is ever added, it should
- * re-derive state per request rather than lean on this cache.
- *
- * CAVEAT for any future consumer: the object returned by `loadState()` is the
- * SAME object on every cache hit, not a fresh copy — a caller that mutates it
- * (as `state-sync.js`'s `handleWriteEdit` does, in-place, before persisting)
- * is mutating the cached entry too. That's harmless today because nothing
- * currently reads the cache again after such a mutation within one process,
- * but treat the return value as read-only unless you've re-verified that.
- *
- * `clearStateCache()` is exported for tests that write/rewrite feature.json
- * and then call a `loadState()`-backed function again WITHIN THE SAME
- * process and need to see the fresh content — call it at the point of
- * mutation.
- */
+// Memoized per process: each hook/CLI process handles one call. The returned
+// object is shared, so treat it as read-only; writers call `clearStateCache()`.
 const stateCache = new Map();
 
-/** Drop all cached state — see `stateCache` above for when this is needed. */
 export function clearStateCache() {
   stateCache.clear();
 }
 
-/**
- * Load state from the project root, hydrating each feature from its
- * authoritative per-feature `feature.json`.
- *
- * The root `.morph/state.json` is a thin, gitignored index (status + updatedAt
- * per feature); the heavy feature data lives in `.morph/features/{name}/feature.json`
- * (committed). This reader merges them: it reads the thin index for project /
- * metadata and overlays each feature.json so callers see the full feature object.
- * A single corrupt feature.json is skipped, not fatal.
- *
- * Fail-open: returns null on any unexpected error or when there is no state at
- * all (no index and no feature files). Memoized per `projectPath` for the
- * lifetime of this process — see `stateCache` above.
- * @param {string} [projectPath] - Project root (defaults to cwd)
- * @returns {Object|null} State object or null
- */
+/** The thin `state.json` index overlaid with each authoritative `feature.json`; null when neither exists. */
 export function loadState(projectPath) {
   const base = projectPath || process.cwd();
   if (stateCache.has(base)) return stateCache.get(base);
@@ -119,7 +47,7 @@ export function loadState(projectPath) {
             state.features = state.features || {};
             state.features[name] = fj; // feature.json is authoritative
           } catch {
-            // skip a single corrupt feature.json — don't blind every hook
+            // one corrupt feature.json must not blind every hook
           }
         }
       }
@@ -134,17 +62,8 @@ export function loadState(projectPath) {
   return state;
 }
 
-/**
- * Check if there is state to read: either the thin `.morph/state.json` index
- * exists, or `.morph/features/` (committed, gitignore-exempt) already has at
- * least one feature with a `feature.json`. The latter case covers a freshly
- * checked-out worktree where state.json (gitignored) hasn't been materialized
- * yet, but `loadState()` can already self-heal from feature.json — so hooks
- * gating on `stateExists()` should be "on" there too, not dark.
- * Fail-open: any unexpected error (e.g. permission denied) returns false.
- * @param {string} [projectPath]
- * @returns {boolean}
- */
+// A fresh worktree has `feature.json` but no gitignored `state.json` yet; hooks
+// must stay on there.
 export function stateExists(projectPath) {
   try {
     const base = projectPath || process.cwd();
@@ -163,11 +82,6 @@ export function stateExists(projectPath) {
   }
 }
 
-/**
- * Get the active feature (most recently updated in_progress feature).
- * @param {string} [projectPath]
- * @returns {{ name: string, feature: Object }|null}
- */
 export function getActiveFeature(projectPath) {
   const state = loadState(projectPath);
   if (!state?.features) return null;
@@ -188,12 +102,6 @@ export function getActiveFeature(projectPath) {
   return active;
 }
 
-/**
- * Get the most recently updated feature (any status).
- * Useful as a fallback when getActiveFeature returns null (all features done).
- * @param {string} [projectPath]
- * @returns {{ name: string, feature: Object }|null}
- */
 export function getMostRecentFeature(projectPath) {
   const state = loadState(projectPath);
   if (!state?.features) return null;
@@ -212,39 +120,15 @@ export function getMostRecentFeature(projectPath) {
   return result;
 }
 
-/**
- * Get a specific feature by name.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Object|null}
- */
 export function getFeature(featureName, projectPath) {
   const state = loadState(projectPath);
   return state?.features?.[featureName] || null;
 }
 
-/**
- * Derive phase from filesystem (phase deleted from state).
- *
- * Walks the phase map in descending order and returns the first phase whose
- * CANONICAL ARTIFACT exists. An empty folder is not enough — a pre-created
- * sibling folder never advances the phase before its content is written.
- *
- * Canonical artifacts (one per phase) match MORPH.md §3:
- *   - 4-review    → verifier.md
- *   - 3-implement → any slice report (`reports/*.md`)
- *   - 1-design   → design-system.md
- *   - 2-plan      → plan.md
- *
- * If no canonical file is found, returns `'plan'` (the starting phase).
- */
 export const PHASE_INDEX = { plan: 0, uiux: 1, implement: 2, review: 3 };
 
-/**
- * The canonical artifact of each phase, descending. Exported so a caller that
- * holds the file list from somewhere OTHER than the local filesystem (a git
- * tree, say) can answer the same question without re-encoding the map.
- */
+// Descending. An empty folder is not an artifact: a pre-created folder must
+// not advance the phase.
 export const PHASE_ARTIFACTS = [
   ['4-review',    'review',    'verifier.md'],
   ['3-implement', 'implement', 'reports/'],
@@ -256,18 +140,6 @@ const DESIGN_DIR = '1-design';
 
 const gatesOf = (feature) => feature?.approvals || feature?.approvalGates;
 
-/**
- * Gate-implied phase from an ALREADY-LOADED feature object — no disk access.
- * An approved gate authorizes the NEXT phase:
- *   review approved → review (terminal)
- *   plan approved   → implement, or uiux while the design branch was taken
- *                     (`1-design/` exists) and its gate is still open
- *   otherwise       → plan
- *
- * @param {Object|null} feature
- * @param {boolean} [designStarted] - whether `1-design/` exists for the feature
- * @returns {string} phase name
- */
 export function gateImpliedPhaseFrom(feature, designStarted = false) {
   const gates = gatesOf(feature);
   const ok = (g) => gates?.[g]?.approved === true;
@@ -276,10 +148,7 @@ export function gateImpliedPhaseFrom(feature, designStarted = false) {
   return 'plan';
 }
 
-/**
- * Artifact predicate over a feature dir on disk. A path ending in `/` asks for
- * any `.md` file directly under it: an empty folder is not an artifact.
- */
+/** A path ending in `/` asks for any `.md` file directly under it. */
 export function diskArtifactProbe(featureDir) {
   return (rel) => {
     const abs = join(featureDir, ...rel.split('/').filter(Boolean));
@@ -292,7 +161,6 @@ export function diskArtifactProbe(featureDir) {
   };
 }
 
-/** The same predicate over a set of feature-relative POSIX paths (a git tree). */
 export function fileSetArtifactProbe(files) {
   return (rel) => {
     if (!rel.endsWith('/')) return files.has(rel);
@@ -303,30 +171,20 @@ export function fileSetArtifactProbe(files) {
   };
 }
 
-/**
- * Phase from an already-loaded feature plus an artifact predicate — no disk
- * access of its own, so the artifact universe can be a git tree.
- *
- * @param {Object|null} feature
- * @param {(relPath: string) => boolean} hasArtifact - {@link diskArtifactProbe}
- *   or {@link fileSetArtifactProbe}: POSIX paths relative to the feature dir
- * @returns {string} phase name
- */
+/** @param {(relPath: string) => boolean} hasArtifact - {@link diskArtifactProbe} or {@link fileSetArtifactProbe} */
 export function derivePhaseFrom(feature, hasArtifact) {
   let artifactPhase = 'plan';
   for (const [folder, phase, canonical] of PHASE_ARTIFACTS) {
     if (hasArtifact(`${folder}/${canonical}`)) { artifactPhase = phase; break; }
   }
 
-  // Gate-aware: an approved gate advances the phase even before the next
-  // phase's first canonical artifact exists, or that artifact could never be
-  // written. Take whichever of (artifact, gate-implied) is later.
+  // An approved gate advances the phase before the next artifact exists, or
+  // that artifact could never be written.
   const designStarted = hasArtifact(DESIGN_DIR) || hasArtifact(`${DESIGN_DIR}/design-system.md`);
   const implied = gateImpliedPhaseFrom(feature, designStarted);
   return PHASE_INDEX[implied] > PHASE_INDEX[artifactPhase] ? implied : artifactPhase;
 }
 
-/** The phase implied purely by approved gates — see {@link gateImpliedPhaseFrom}. */
 export function gateImpliedPhase(featureName, projectPath) {
   const designDir = join(projectPath || process.cwd(), '.morph/features', featureName, DESIGN_DIR);
   return gateImpliedPhaseFrom(getFeature(featureName, projectPath), existsSync(designDir));
@@ -337,41 +195,19 @@ export function derivePhaseForFeature(featureName, projectPath) {
   return derivePhaseFrom(getFeature(featureName, projectPath), diskArtifactProbe(basePath));
 }
 
-/**
- * Get the current phase of a feature.
- * Falls back to filesystem derivation when phase is not in state.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string|null}
- */
 export function getFeaturePhase(featureName, projectPath) {
   const feature = getFeature(featureName, projectPath);
   if (!feature) return null;
   return feature.phase || derivePhaseForFeature(featureName, projectPath);
 }
 
-/**
- * Get approval status for a gate.
- * @param {string} featureName
- * @param {string} gate - 'plan'|'uiux'|'review'
- * @param {string} [projectPath]
- * @returns {boolean}
- */
 export function isGateApproved(featureName, gate, projectPath) {
   const feature = getFeature(featureName, projectPath);
-  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
   const gates = feature?.approvals || feature?.approvalGates;
   return gates?.[gate]?.approved === true;
 }
 
-/**
- * Get all pending approval gates for a feature.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string[]} List of gate names that are not yet approved
- */
 export function pendingGatesFrom(feature) {
-  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
   const gates = gatesOf(feature);
   if (!gates) return [];
 
@@ -384,12 +220,6 @@ export function getPendingGates(featureName, projectPath) {
   return pendingGatesFrom(getFeature(featureName, projectPath));
 }
 
-/**
- * Get feature outputs status.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Object|null} outputs map or null
- */
 export function getOutputs(featureName, projectPath) {
   const feature = getFeature(featureName, projectPath);
   return feature?.outputs || null;

package/framework/hooks/shared/state-writer.js

@@ -1,14 +1,5 @@
-/**
- * Shared per-feature state writer for Claude Code hooks.
- *
- * Hooks run inside the user's project and cannot import the CLI's
- * src/core/state-manager.js. This module is the hook-side mirror of the core
- * writers: it persists a feature to its authoritative `feature.json` (committed)
- * and refreshes the thin, gitignored root index (`.morph/state.json`).
- *
- * Fail-open by contract: every function swallows errors and returns a boolean —
- * a hook must never break the agent over a state write.
- */
+// Hook-side mirror of the CLI state writers (hooks cannot import `src/`).
+// Fail-open: every function returns a boolean, never throws.
 
 import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
@@ -17,12 +8,10 @@ import { clearStateCache } from './state-reader.js';
 const STATE_FILE = '.morph/state.json';
 const STATE_VERSION = '5.0.0';
 
-/** Absolute path to a feature's authoritative feature.json. */
 export function featureJsonPath(featureName, projectPath) {
   return join(projectPath || process.cwd(), '.morph', 'features', featureName, 'feature.json');
 }
 
-/** Read a feature's feature.json, or null if missing/corrupt. */
 export function readFeatureFile(featureName, projectPath) {
   const p = featureJsonPath(featureName, projectPath);
   if (!existsSync(p)) return null;
@@ -33,7 +22,7 @@ export function readFeatureFile(featureName, projectPath) {
   }
 }
 
-/** Atomic JSON write: per-pid temp then rename, with an EPERM retry for Windows. */
+// EPERM retry: Windows rename fails while another process holds the target.
 function atomicWriteJson(targetPath, data) {
   const dir = dirname(targetPath);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
@@ -54,11 +43,6 @@ function atomicWriteJson(targetPath, data) {
   }
 }
 
-/**
- * Persist a feature to its authoritative feature.json and refresh the thin root
- * index entry (status + updatedAt) + aggregate metadata. Returns true on
- * success, false fail-open.
- */
 export function persistFeature(featureName, feature, projectPath) {
   try {
     atomicWriteJson(featureJsonPath(featureName, projectPath), feature);
@@ -75,19 +59,8 @@ export function persistFeature(featureName, feature, projectPath) {
     root.metadata.totalFeatures = Object.keys(root.features).length;
     atomicWriteJson(statePath, root);
 
-    // R1's loadState() memoizes per projectPath for the lifetime of the
-    // process. That was always safe when every hook was its own short-lived
-    // process (README history), but core/chain.js now runs multiple hooks
-    // — e.g. state-sync then gate-guard — IN ONE process. Without this,
-    // a loadState() call earlier in that same process (state-sync's
-    // handleWriteEdit reads via loadState before this write) would leave a
-    // stale snapshot cached, and gate-guard's loadState() right after this
-    // write would silently read the PRE-write state instead of what was
-    // just persisted — inverting the "gate-guard runs after state-sync so it
-    // sees the gate state-sync just recorded" ordering guarantee the
-    // registry comment documents. Invalidating here (the one place
-    // feature.json/state.json are actually written) covers every current
-    // and future caller, not just this one chain.
+    // chain.js runs several hooks in one process: the next link must not read
+    // the memoized pre-write snapshot.
     clearStateCache();
     return true;
   } catch {
@@ -95,16 +68,7 @@ export function persistFeature(featureName, feature, projectPath) {
   }
 }
 
-/**
- * Canonical gate-approval writer (hook-side mirror of CLI setApprovalGate).
- * Stamps approvalGates[gate] = { approved, timestamp, approvedBy } — the single
- * canonical shape — onto the feature and persists it. Returns true on success.
- *
- * @param {string} featureName
- * @param {string} gate - 'plan'|'uiux'|'review'
- * @param {{ approvedBy?: string, timestamp?: string }} [meta]
- * @param {string} [projectPath]
- */
+/** @param {{ approvedBy?: string, timestamp?: string, selfAssessed?: boolean }} [meta] */
 export function setGateApproved(featureName, gate, meta = {}, projectPath) {
   try {
     const feature = readFeatureFile(featureName, projectPath) || createDefaultFeature(featureName);
@@ -123,16 +87,8 @@ export function setGateApproved(featureName, gate, meta = {}, projectPath) {
   }
 }
 
-/**
- * Default feature shape (canonical object-form gates, incl. optional uiux).
- * Stamps identity — name (the slug), workType, createdAt — so the implicit
- * birth path (state-sync registering a feature on the first Write) never
- * produces an anonymous {status,updatedAt} shell. `description` stays absent
- * (a hook can't invent it); `list`/`doctor` flag its absence. Mirrors the CLI
- * createFeature's stamping.
- *
- * @param {string} [featureName] - the feature slug, stamped as `name`
- */
+// Stamps identity so a feature born implicitly by a hook is never an anonymous
+// shell; `description` stays absent because a hook cannot invent it.
 export function createDefaultFeature(featureName) {
   const now = new Date().toISOString();
   return {

package/framework/hooks/shared/stdin-reader.js

@@ -1,14 +1,4 @@
-/**
- * Shared stdin reader for Claude Code hooks.
- *
- * Reads JSON payload from stdin (provided by Claude Code to hooks).
- * Returns parsed object or null on failure.
- */
-
-/**
- * Read and parse JSON from stdin
- * @returns {Promise<Object|null>} Parsed JSON or null
- */
+/** @returns {Promise<Object|null>} the hook payload, or null when stdin is not JSON */
 export function readStdin() {
   return new Promise((resolve) => {
     let input = '';

package/framework/hooks/shared/telemetry-logger.js

@@ -1,20 +1,5 @@
-/**
- * Telemetry Logger — append-only harness event stream
- *
- * Writes one JSON line per event to .morph/logs/events.jsonl. This is the sink
- * for the `telemetry-log` hook, which fires on every tool call (PostToolUse,
- * all tools) and on every user prompt (UserPromptSubmit) — the only vantage
- * points an NLH exposes. The whole execution path (skills, sub-agent dispatch,
- * knowledge-base reads, prompts) is reconstructable by reading this file.
- *
- * Design constraints (same discipline as activity-logger, plus one):
- * - Synchronous only (hooks run in process, no async overhead)
- * - Fail-silent (never throws — hooks must not be blocked by the logger)
- * - APPEND-ONLY: one `appendFileSync` line per event, O(1) per call. The
- *   read-modify-write of a whole JSON doc (activity-logger) is O(n²) across a
- *   session and blows the ≤5ms budget once tool calls number in the hundreds.
- * - Windows-safe paths via path.join
- */
+// Append-only on purpose: rewriting a whole JSON doc per event is O(n²) across
+// a session, and this runs on every tool call. Fail-silent: never blocks a hook.
 
 import {
   appendFileSync, readFileSync, mkdirSync, existsSync, statSync, renameSync,
@@ -26,13 +11,7 @@ import { redactSecrets } from './redact-secrets.js';
 const LOGS_DIR = '.morph/logs';
 export const EVENTS_FILE = join(LOGS_DIR, 'events.jsonl');
 
-// SessionStart (worktree-context.js) rotates events.jsonl once it crosses
-// this size, alongside the pre-existing activity.jsonl rotation — same
-// call site, same "between sessions" checkpoint. events.jsonl has no natural
-// per-turn cap (prompts/commands are truncated at the write site, but the
-// LINE COUNT itself grows unbounded across a long-lived project), so without
-// this it grows forever the way activity.jsonl used to before R1.2.
-export const ROTATE_THRESHOLD_BYTES = 5 * 1024 * 1024; // 5 MB
+export const ROTATE_THRESHOLD_BYTES = 5 * 1024 * 1024;
 
 // Bumped when a field changes meaning. Readers key legacy handling off its
 // absence (v1 events carry no schemaVersion and no eventId).
@@ -49,15 +28,7 @@ function getEventsPath(projectPath) {
   return join(projectPath || process.cwd(), EVENTS_FILE);
 }
 
-/**
- * Append a single telemetry event as one JSON line.
- * Stamps `ts` (unless given), `schemaVersion` and a unique `eventId` — the
- * dedupe key when the same line is read back from a rotated archive or a
- * finish backup — and redacts secrets in the free-text fields.
- *
- * @param {Object} event - Event payload (tool, skill/persona/target/prompt, feature, phase…)
- * @param {string} [projectPath] - Project root (defaults to cwd)
- */
+// `eventId` dedupes the same line read back from a rotated archive or a finish backup.
 export function appendTelemetryEvent(event, projectPath) {
   try {
     const eventsPath = getEventsPath(projectPath);
@@ -75,17 +46,9 @@ export function appendTelemetryEvent(event, projectPath) {
     }
     appendFileSync(eventsPath, JSON.stringify(stamped) + '\n', 'utf-8');
   } catch {
-    // Fail-silent — never block hooks
   }
 }
 
-/**
- * Read the full event stream back into an array. A corrupt/truncated line
- * (e.g. a killed process mid-write) is skipped, not fatal.
- *
- * @param {string} [projectPath]
- * @returns {Object[]} events in write order (may be empty)
- */
 export function readTelemetryEvents(projectPath) {
   try {
     const eventsPath = getEventsPath(projectPath);
@@ -98,7 +61,7 @@ export function readTelemetryEvents(projectPath) {
       try {
         events.push(JSON.parse(trimmed));
       } catch {
-        // skip a single corrupt line — don't lose the whole stream
+        // a process killed mid-write leaves a truncated line
       }
     }
     return events;
@@ -107,19 +70,7 @@ export function readTelemetryEvents(projectPath) {
   }
 }
 
-/**
- * Archive the current events.jsonl to `.morph/logs/sessions/`, mirroring
- * activity-logger.js's `archiveSession()` — same directory, same rename-not-
- * rewrite mechanics (O(1) even at multi-MB sizes). Named with an `events-`
- * prefix (activity-logger's archives carry no prefix) so the two streams
- * never collide inside the shared `sessions/` directory and stay
- * distinguishable at a glance.
- *
- * Fail-silent — called only from `rotateEventsLogIfLarge` below, which has
- * already confirmed the file exists.
- *
- * @param {string} [projectPath]
- */
+// `events-` prefix: activity-logger archives share `sessions/` without one.
 function archiveEvents(projectPath) {
   try {
     const eventsPath = getEventsPath(projectPath);
@@ -132,21 +83,10 @@ function archiveEvents(projectPath) {
     const archivePath = join(sessionsDir, `events-${stamp}.jsonl`);
     renameSync(eventsPath, archivePath);
   } catch {
-    // Fail-silent
   }
 }
 
-/**
- * Rotate events.jsonl when it crosses `thresholdBytes`. Called from
- * worktree-context.js on SessionStart, right next to the existing
- * `rotateActivityLogIfLarge()` call — the only reliable "between sessions"
- * checkpoint the harness gets. `thresholdBytes` is injectable so a test can
- * force rotation without writing multiple megabytes.
- *
- * @param {string} [projectPath] - Project root (defaults to cwd)
- * @param {number} [thresholdBytes] - Rotate once the log is at least this large
- * @returns {boolean} true if a rotation was performed
- */
+/** @returns {boolean} true if a rotation was performed */
 export function rotateEventsLogIfLarge(projectPath, thresholdBytes = ROTATE_THRESHOLD_BYTES) {
   try {
     const eventsPath = getEventsPath(projectPath);

package/framework/hooks/shared/transcript-usage.js

@@ -1,28 +1,15 @@
-/**
- * Real token usage read from a Claude Code transcript (JSONL), shared by the
- * Stop hook (the main session's transcript) and SubagentStop (each
- * sub-agent's own transcript, which the main one does not include).
- */
+// Shared by Stop and SubagentStop: the main transcript does not include the
+// sub-agents' usage.
 
 import { readFileSync, existsSync, statSync } from 'fs';
 
-// A 45 MB / ~16k-line transcript parses in ~350 ms; above this, skip rather
-// than risk an unbounded read inside a hook.
+// Skip rather than risk an unbounded read inside a hook.
 const MAX_TRANSCRIPT_BYTES = 50 * 1024 * 1024;
 
 export const USAGE_KEYS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheCreationTokens'];
 
-/**
- * Sum `message.usage` over the assistant turns of a transcript.
- *
- * One turn is written as several lines (one per content block), each repeating
- * the same usage under the same `message.id`: summing lines double-counts, so
- * the sum is deduplicated by message id.
- *
- * @param {string} [transcriptPath]
- * @returns {{inputTokens:number,outputTokens:number,cacheReadTokens:number,cacheCreationTokens:number}|null}
- *   null when there is nothing to report (no/oversized/unreadable file, no usage)
- */
+// One turn spans several lines repeating the same usage under the same
+// `message.id`: summing lines double-counts, so the sum dedups by id.
 export function readTranscriptUsage(transcriptPath) {
   if (!transcriptPath || typeof transcriptPath !== 'string') return null;
   try {
@@ -61,17 +48,8 @@ export function readTranscriptUsage(transcriptPath) {
   }
 }
 
-/**
- * The usage added since the previous sample of the same transcript.
- *
- * A counter going DOWN means the transcript restarted (a new file under the
- * same key), so the whole current total is new usage — subtracting would
- * produce negative spend.
- *
- * @param {object|null|undefined} previous - last recorded totals for this key
- * @param {object} current - totals just read
- * @returns {{delta: object, changed: boolean}}
- */
+// A counter going DOWN means the transcript restarted: the whole current
+// total is new usage, and subtracting would produce negative spend.
 export function usageDelta(previous, current) {
   const reset = !previous || USAGE_KEYS.some((k) => (current[k] ?? 0) < (previous[k] ?? 0));
   const delta = {};