@polymorphism-tech/morph-spec 8.15.1 → 8.17.0

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

@@ -1,21 +1,41 @@
 /**
  * Activity Logger — Session-scoped hook event log
  *
- * Writes hook activity to .morph/logs/activity.json for live consumption
- * by `morph-spec monitor`.
+ * Writes hook activity to .morph/logs/activity.jsonl for live consumption
+ * (statusline, `morph-spec fleet`, etc).
  *
  * Design constraints:
  * - Synchronous only (hooks run in process, no async overhead)
- * - Fail-silent (never throws — hooks must not be blocked by logger)
+ * - Fail-silent (never throws — hooks must not be blocked by the logger)
  * - ≤5ms per call (no retries, no network)
+ * - APPEND-ONLY: one `appendFileSync` line per event, O(1) per call. The
+ *   previous format did a read-modify-write of the WHOLE JSON doc per call
+ *   (logHookActivity/logEvent both read, mutated, and rewrote the entire
+ *   file) — O(n²) across a session once tool calls number in the hundreds,
+ *   with 6 hooks each calling this 3-5x per Write. Same discipline as
+ *   telemetry-logger.js's events.jsonl.
  * - Windows-safe paths via path.join
+ *
+ * Exported names/signatures are unchanged from the previous doc-based
+ * implementation on purpose — hooks outside this file's ownership
+ * (gate-guard.js, tasks-json-guard.js, enforce-phase-writes.js,
+ * loop-detect.js, protect-spec-files.js, validate-completion.js) call
+ * logHookActivity/logEvent and must keep working untouched. Only the
+ * on-disk format changed.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
+import {
+  appendFileSync, readFileSync, mkdirSync, existsSync, statSync, renameSync, writeFileSync,
+} from 'fs';
 import { join } from 'path';
 
 const LOGS_DIR = '.morph/logs';
-const ACTIVITY_FILE = join(LOGS_DIR, 'activity.json');
+export const ACTIVITY_FILE = join(LOGS_DIR, 'activity.jsonl');
+
+// SessionStart (worktree-context.js) rotates the log once it crosses this
+// size — the archive/rotation call site resetActivity()/archiveSession()
+// were written for but never got until now.
+export const ROTATE_THRESHOLD_BYTES = 2 * 1024 * 1024; // 2 MB
 
 function getActivityPath(projectPath) {
   return join(projectPath || process.cwd(), ACTIVITY_FILE);
@@ -28,12 +48,39 @@ function ensureLogsDir(projectPath) {
   }
 }
 
-function readRaw(activityPath) {
+function nowTs() {
+  return new Date().toTimeString().slice(0, 8); // HH:MM:SS — matches the previous format
+}
+
+/** Append one JSON line. Fail-silent, O(1) regardless of file size. */
+function appendLine(projectPath, line) {
+  try {
+    ensureLogsDir(projectPath);
+    appendFileSync(getActivityPath(projectPath), JSON.stringify(line) + '\n', 'utf-8');
+  } catch {
+    // Fail-silent — never block hooks
+  }
+}
+
+/** Read every parseable line back. A corrupt/truncated line is skipped, not fatal. */
+function readLines(projectPath) {
   try {
-    if (!existsSync(activityPath)) return null;
-    return JSON.parse(readFileSync(activityPath, 'utf-8'));
+    const activityPath = getActivityPath(projectPath);
+    if (!existsSync(activityPath)) return [];
+    const raw = readFileSync(activityPath, 'utf-8');
+    const lines = [];
+    for (const l of raw.split('\n')) {
+      const trimmed = l.trim();
+      if (!trimmed) continue;
+      try {
+        lines.push(JSON.parse(trimmed));
+      } catch {
+        // skip a single corrupt line — don't lose the whole stream
+      }
+    }
+    return lines;
   } catch {
-    return null;
+    return [];
   }
 }
 
@@ -46,42 +93,50 @@ function readRaw(activityPath) {
  * @param {string} [projectPath] - Project root (defaults to cwd)
  */
 export function logHookActivity(name, event, result, projectPath) {
-  try {
-    const activityPath = getActivityPath(projectPath);
-    ensureLogsDir(projectPath);
-
-    const now = new Date();
-    const ts = now.toTimeString().slice(0, 8); // HH:MM:SS
-
-    const data = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], skills: [] };
-
-    data.hooks = data.hooks || [];
-    data.hooks.push({ name, event, result, ts });
-
-    writeFileSync(activityPath, JSON.stringify(data, null, 2), 'utf-8');
-  } catch {
-    // Fail-silent — never block hooks
-  }
+  appendLine(projectPath, { kind: 'hook', name, event, result, ts: nowTs() });
 }
 
+/**
+ * Log a structured event to the session activity log.
+ *
+ * @param {string} type   - Event type (e.g., 'task_start', 'loop_detected')
+ * @param {Object} data   - Event data payload
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ */
+export function logEvent(type, data, projectPath) {
+  appendLine(projectPath, { kind: 'event', type, data, ts: nowTs() });
+}
 
 /**
- * Read the current activity log.
+ * Read the current activity log, reconstructed into the aggregate shape
+ * older consumers expect: `{ sessionId, feature, phase, hooks, events }`.
+ * `sessionId`/`feature`/`phase` come from the synthetic 'session' header
+ * line `resetActivity()` writes, when present.
  *
  * @param {string} [projectPath]
- * @returns {{ sessionId: string, feature: string, phase: string, hooks: Array, skills: Array }|null}
+ * @returns {{ sessionId: string, feature: string, phase: string, hooks: Array, events: Array }|null}
  */
 export function readActivity(projectPath) {
-  try {
-    return readRaw(getActivityPath(projectPath));
-  } catch {
-    return null;
-  }
+  const lines = readLines(projectPath);
+  if (lines.length === 0) return null;
+
+  const session = lines.find((l) => l.kind === 'session') || {};
+  const strip = ({ kind, ...rest }) => rest;
+
+  return {
+    sessionId: session.sessionId || '',
+    feature: session.feature || '',
+    phase: session.phase || '',
+    hooks: lines.filter((l) => l.kind === 'hook').map(strip),
+    events: lines.filter((l) => l.kind === 'event').map(strip),
+  };
 }
 
 /**
- * Reset the activity log for a new session.
- * Called from SessionStart hook to clear stale data.
+ * Reset the activity log for a new session — the one operation in this file
+ * that is NOT append-only (a session boundary, not a log entry). Truncates
+ * the file and writes a 'session' header line so `readActivity()` can
+ * recover sessionId/feature/phase.
  *
  * @param {string} sessionId  - ISO timestamp of new session
  * @param {string} feature    - Active feature name (empty string if none)
@@ -91,70 +146,66 @@ export function readActivity(projectPath) {
 export function resetActivity(sessionId, feature, phase, projectPath) {
   try {
     ensureLogsDir(projectPath);
-    const data = {
+    const session = {
+      kind: 'session',
       sessionId: sessionId || new Date().toISOString(),
       feature: feature || '',
       phase: phase || '',
-      hooks: [],
-      skills: []
     };
-    writeFileSync(getActivityPath(projectPath), JSON.stringify(data, null, 2), 'utf-8');
+    writeFileSync(getActivityPath(projectPath), JSON.stringify(session) + '\n', 'utf-8');
   } catch {
     // Fail-silent
   }
 }
 
 /**
- * Log a structured event to the session activity log.
+ * Archive the current activity log to sessions/ for historical logging.
+ * Only archives when there is at least one hook or event line — a bare (or
+ * absent) log is not worth preserving. `renameSync` keeps this O(1) even at
+ * the multi-MB sizes rotation is meant to catch (no read+rewrite of content).
  *
- * @param {string} type   - Event type (e.g., 'task_start', 'loop_detected')
- * @param {Object} data   - Event data payload
  * @param {string} [projectPath] - Project root (defaults to cwd)
  */
-export function logEvent(type, data, projectPath) {
+export function archiveSession(projectPath) {
   try {
     const activityPath = getActivityPath(projectPath);
-    ensureLogsDir(projectPath);
+    if (!existsSync(activityPath)) return;
 
-    const now = new Date();
-    const ts = now.toTimeString().slice(0, 8); // HH:MM:SS
+    const lines = readLines(projectPath);
+    const hasMeaningfulContent = lines.some((l) => l.kind === 'hook' || l.kind === 'event');
+    if (!hasMeaningfulContent) return;
 
-    const activity = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], events: [] };
-    activity.events = activity.events || [];
-    activity.events.push({ type, data, ts });
+    const session = lines.find((l) => l.kind === 'session') || {};
+    const sessionsDir = join(projectPath || process.cwd(), LOGS_DIR, 'sessions');
+    mkdirSync(sessionsDir, { recursive: true });
 
-    writeFileSync(activityPath, JSON.stringify(activity, null, 2), 'utf-8');
+    const stamp = (session.sessionId || new Date().toISOString()).replace(/[:.]/g, '-');
+    const archivePath = join(sessionsDir, `${stamp}.jsonl`);
+    renameSync(activityPath, archivePath);
   } catch {
     // Fail-silent
   }
 }
 
 /**
- * Archive current activity.json to sessions/ directory for historical logging.
- * Called at the start of a new session.
+ * Rotate the activity log when it crosses `thresholdBytes` — the real call
+ * site for archiveSession() (previously written but never invoked anywhere).
+ * Called from worktree-context.js on SessionStart, the only reliable
+ * "between sessions" checkpoint the harness gets.
  *
  * @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
  */
-export function archiveSession(projectPath) {
+export function rotateActivityLogIfLarge(projectPath, thresholdBytes = ROTATE_THRESHOLD_BYTES) {
   try {
     const activityPath = getActivityPath(projectPath);
-    if (!existsSync(activityPath)) return;
-
-    const data = readRaw(activityPath);
-    if (!data) return;
-
-    // Only archive if there are meaningful events
-    if ((!data.hooks || data.hooks.length === 0) && (!data.events || data.events.length === 0)) return;
-
-    const sessionsDir = join(projectPath || process.cwd(), LOGS_DIR, 'sessions');
-    mkdirSync(sessionsDir, { recursive: true });
-
-    const sessionId = (data.sessionId || new Date().toISOString()).replace(/[:.]/g, '-');
-    const archivePath = join(sessionsDir, `${sessionId}.json`);
-    writeFileSync(archivePath, JSON.stringify(data, null, 2), 'utf-8');
-
-    unlinkSync(activityPath);
+    if (!existsSync(activityPath)) return false;
+    const { size } = statSync(activityPath);
+    if (size < thresholdBytes) return false;
+    archiveSession(projectPath);
+    return true;
   } catch {
-    // Fail-silent
+    return false;
   }
 }

package/framework/hooks/shared/claim-registry.js

@@ -26,7 +26,7 @@
  */
 
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { dirname, join } from 'path';
 
 /**
  * A claim with no heartbeat for this long is considered dead. The heartbeat
@@ -119,6 +119,66 @@ export function heartbeatClaim(feature, { gitCommonDir, sessionId }) {
   return true;
 }
 
+/** Local, git-independent heartbeat pre-check marker — see `shouldHeartbeat`. */
+function heartbeatMarkPath(cwd) {
+  return join(cwd, '.morph', 'logs', '.heartbeat-check.json');
+}
+
+/**
+ * Cheap, git-independent pre-check for whether a heartbeat is even worth
+ * ATTEMPTING. `heartbeatClaim` already throttles the WRITE to `claims.json`,
+ * but that registry lives under the git COMMON dir — resolving it (even via
+ * the pure-FS `git-paths.js`, never mind the old `execSync('git rev-parse
+ * --git-common-dir')`) is work `telemetry-log.js` pays on every tool call.
+ * This answers "is it due" from a tiny marker colocated with the CALLER's own
+ * `.morph/logs/` (already known, no git lookup of any kind) so that on ~99%
+ * of calls NOTHING git-related happens at all — not the subprocess, not even
+ * the FS walk.
+ *
+ * Side effect: when it returns `true` (heartbeat IS due), it immediately
+ * stamps the marker — mirroring `heartbeatClaim`'s own check-and-write
+ * pattern — so the NEXT call within the throttle window short-circuits here
+ * even if the caller's subsequent git resolution then fails (not actually a
+ * git repo, say): a failed attempt should not be retried on every single tool
+ * call either.
+ *
+ * This is a SEPARATE, LOCAL throttle from `claims.json`'s own authoritative
+ * `heartbeatAt` (keyed by git-common-dir, enforced inside `heartbeatClaim`) —
+ * the two can drift by up to one throttle window with no consequence: a
+ * missed local pre-check only costs a claim heartbeat that gets written on
+ * the very next call, and claims are advisory to begin with.
+ *
+ * Fail-open: any read/write error is treated as "due" — a broken marker must
+ * never permanently suppress the actual (authoritative) heartbeat. Not
+ * tmp+rename like `claims.json` — this file is low-stakes (worst case from a
+ * torn write is corrupt JSON, which just reads back as "due" next time) and
+ * shared by nobody outside this one project tree.
+ *
+ * @param {string} feature
+ * @param {{ cwd: string, sessionId: string, now?: number }} opts
+ * @returns {boolean}
+ */
+export function shouldHeartbeat(feature, { cwd, sessionId, now = Date.now() }) {
+  const markPath = heartbeatMarkPath(cwd);
+  try {
+    const mark = JSON.parse(readFileSync(markPath, 'utf8'));
+    if (mark.feature === feature && mark.sessionId === sessionId) {
+      const at = Date.parse(mark.at ?? '');
+      if (Number.isFinite(at) && now - at < HEARTBEAT_THROTTLE_MS) return false;
+    }
+  } catch {
+    // missing/corrupt marker — treat as due
+  }
+
+  try {
+    mkdirSync(dirname(markPath), { recursive: true });
+    writeFileSync(markPath, JSON.stringify({ feature, sessionId, at: new Date(now).toISOString() }));
+  } catch {
+    // best-effort — a failed stamp only costs a repeated attempt next call
+  }
+  return true;
+}
+
 /**
  * The LIVE claim on this feature held by a session that is not us — the thing
  * worth warning about. Returns null when the feature is unclaimed, claimed by

package/framework/hooks/shared/git-paths.js

@@ -0,0 +1,94 @@
+/**
+ * git-paths.js — pure-filesystem git common-dir resolution (no subprocess).
+ *
+ * `telemetry-log.js`'s claim heartbeat used to pay `execSync('git rev-parse
+ * --git-common-dir')` on every tool call to learn where `claims.json` lives —
+ * a ~34ms subprocess spawn, wasted on ~99% of calls because the heartbeat
+ * write itself is throttled (see `claim-registry.js`'s `shouldHeartbeat`).
+ * This module answers the SAME question — mirroring `git rev-parse
+ * --git-common-dir` — by reading the two on-disk shapes git itself uses,
+ * without spawning `git` at all:
+ *
+ *   1. PRIMARY checkout: `<root>/.git` is a DIRECTORY. That directory IS the
+ *      common dir. (A directory `.git` is never a linked worktree's own —
+ *      git always represents a worktree's `.git` as a FILE — so this case is
+ *      unambiguous.)
+ *   2. LINKED WORKTREE (`git worktree add`): `<root>/.git` is a FILE
+ *      containing `gitdir: <path>`, pointing at this worktree's PRIVATE
+ *      gitdir (normally `<primary>/.git/worktrees/<name>`). Inside that
+ *      private gitdir, a `commondir` file holds a path — relative to the
+ *      private gitdir, or absolute — to the real common dir (normally
+ *      `../..`, i.e. back up to `<primary>/.git`).
+ *
+ * Verified against a real `git worktree add` fixture: `commondir` held
+ * `../..`, `.git`'s `gitdir:` line held an absolute path, and the resolved
+ * result matched `git rev-parse --git-common-dir` exactly (see
+ * `test/hooks/git-paths.test.js`, which asserts that parity directly rather
+ * than against a hand-computed path).
+ *
+ * Fail-open: any missing file, unreadable path, or shape that doesn't match
+ * either case above resolves to `null`. Callers must treat `null` as "not
+ * resolvable right now" and skip whatever git-dependent step they were
+ * guarding — never throw.
+ */
+
+import { readFileSync, statSync } from 'fs';
+import { dirname, isAbsolute, join, resolve } from 'path';
+
+/**
+ * Find the nearest `.git` entry (file or directory) at or above `startDir`,
+ * climbing exactly like git itself does to find the repo root.
+ *
+ * @param {string} startDir
+ * @returns {{ path: string, isDirectory: boolean }|null}
+ */
+function findDotGit(startDir) {
+  let dir = resolve(startDir);
+  for (;;) {
+    const candidate = join(dir, '.git');
+    try {
+      const st = statSync(candidate);
+      return { path: candidate, isDirectory: st.isDirectory() };
+    } catch {
+      // not here — keep climbing
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null; // reached the filesystem root
+    dir = parent;
+  }
+}
+
+/**
+ * Resolve the git COMMON dir for `startDir` — pure filesystem, no subprocess.
+ * Always returns an absolute path (unlike `git rev-parse --git-common-dir`,
+ * which returns a path relative to the CALLER's cwd when run from the
+ * primary checkout — callers of this function never need their own
+ * `resolve(cwd, ...)` step afterward).
+ *
+ * @param {string} startDir
+ * @returns {string|null}
+ */
+export function resolveGitCommonDir(startDir) {
+  try {
+    const found = findDotGit(startDir);
+    if (!found) return null;
+
+    if (found.isDirectory) {
+      return found.path;
+    }
+
+    // `.git` is a FILE: `gitdir: <path>` → this worktree's private gitdir.
+    const content = readFileSync(found.path, 'utf8');
+    const match = content.match(/^gitdir:\s*(.+?)\s*$/m);
+    if (!match) return null;
+    const privateGitDir = isAbsolute(match[1]) ? match[1] : resolve(dirname(found.path), match[1]);
+
+    // Inside the private gitdir, `commondir` points (relative to itself, or
+    // absolute) at the real common dir.
+    const commonRaw = readFileSync(join(privateGitDir, 'commondir'), 'utf8').trim();
+    if (!commonRaw) return null;
+    return isAbsolute(commonRaw) ? commonRaw : resolve(privateGitDir, commonRaw);
+  } catch {
+    return null;
+  }
+}

package/framework/hooks/shared/hook-response.js

@@ -55,3 +55,70 @@ export function injectContext(text, eventName) {
 export function pass() {
   process.exit(0);
 }
+
+// ── Pure (non-exiting) result builders ──────────────────────────────────────
+//
+// Every core hook used to run inline at module scope and call block()/pass()/
+// injectContext() above to print+exit(0) the moment it knew its verdict. That
+// stops being safe once a hook's logic moves into an exported `run(payload)`
+// that can ALSO be called by framework/hooks/claude-code/core/chain.js — which
+// imports several hooks' run() into ONE process and cannot have any of them
+// call process.exit() mid-chain (it would kill the other links). run() must
+// instead RETURN the verdict object; chain.js (or this file's own
+// runStandalone(), below) is what actually prints it and exits.
+//
+// These builders produce the exact same JSON shapes as block()/approve()/
+// injectContext() above — keep them in sync if that shape ever changes.
+
+/** Pure equivalent of block(reason) — returns the verdict instead of printing+exiting. */
+export function blockResult(reason) {
+  return { decision: 'block', reason };
+}
+
+/** Pure equivalent of approve(context) — null means "pass" (nothing to say). */
+export function approveResult(context) {
+  return context ? { decision: 'approve', additionalContext: context } : null;
+}
+
+/** Pure equivalent of injectContext(text, eventName). */
+export function contextResult(text, eventName) {
+  return { hookSpecificOutput: { hookEventName: eventName, additionalContext: text } };
+}
+
+/**
+ * Standalone tail every core hook calls as its last line:
+ * `await runStandalone(run);`
+ *
+ * Reads stdin once, calls the hook's `run(payload)`, prints the JSON verdict
+ * (if any) and exits 0 — reproducing exactly what block()/injectContext()/
+ * pass() used to do when a hook's logic lived inline at module scope.
+ *
+ * No-ops when MORPH_HOOK_CHAINED is set: that means core/chain.js already
+ * imported this module and will call run() itself with a payload it read
+ * once for the whole chain — this file must not ALSO read stdin or exit here
+ * (doing so would race chain.js's own stdin read and kill the chain process
+ * after the first link). chain.js sets the flag BEFORE its first dynamic
+ * import, so every hook it loads sees it already set at call time.
+ *
+ * Fail-open: any error (including a rejected run()) prints nothing and exits
+ * 0 — the same silent-pass behavior every hook's own outer try/catch used to
+ * produce on an unexpected error.
+ *
+ * @param {(payload: object) => Promise<object|null>} run
+ */
+export async function runStandalone(run) {
+  if (process.env.MORPH_HOOK_CHAINED) return;
+
+  const { readStdin } = await import('./stdin-reader.js');
+  let result = null;
+  try {
+    const payload = await readStdin();
+    result = await run(payload);
+  } catch {
+    result = null; // fail-open
+  }
+  if (result) {
+    console.log(JSON.stringify(result));
+  }
+  process.exit(0);
+}

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

@@ -13,6 +13,64 @@ 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.
+ */
+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`.
@@ -24,48 +82,56 @@ const FEATURES_DIR = '.morph/features';
  * 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).
+ * 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
  */
 export function loadState(projectPath) {
-  try {
-    const base = projectPath || process.cwd();
-    const statePath = join(base, STATE_FILE);
+  const base = projectPath || process.cwd();
+  if (stateCache.has(base)) return stateCache.get(base);
 
-    let state = null;
-    if (existsSync(statePath)) {
-      state = JSON.parse(readFileSync(statePath, 'utf-8'));
-    }
+  const state = (() => {
+    try {
+      const statePath = join(base, STATE_FILE);
 
-    const featuresDir = join(base, FEATURES_DIR);
-    if (existsSync(featuresDir)) {
-      let names = [];
-      try {
-        names = readdirSync(featuresDir, { withFileTypes: true })
-          .filter((e) => e.isDirectory())
-          .map((e) => e.name);
-      } catch {
-        names = [];
+      let state = null;
+      if (existsSync(statePath)) {
+        state = JSON.parse(readFileSync(statePath, 'utf-8'));
       }
-      for (const name of names) {
-        const fjPath = join(featuresDir, name, 'feature.json');
-        if (!existsSync(fjPath)) continue;
+
+      const featuresDir = join(base, FEATURES_DIR);
+      if (existsSync(featuresDir)) {
+        let names = [];
         try {
-          const fj = JSON.parse(readFileSync(fjPath, 'utf-8'));
-          state = state || { features: {} };
-          state.features = state.features || {};
-          state.features[name] = fj; // feature.json is authoritative
+          names = readdirSync(featuresDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
         } catch {
-          // skip a single corrupt feature.json — don't blind every hook
+          names = [];
+        }
+        for (const name of names) {
+          const fjPath = join(featuresDir, name, 'feature.json');
+          if (!existsSync(fjPath)) continue;
+          try {
+            const fj = JSON.parse(readFileSync(fjPath, 'utf-8'));
+            state = state || { features: {} };
+            state.features = state.features || {};
+            state.features[name] = fj; // feature.json is authoritative
+          } catch {
+            // skip a single corrupt feature.json — don't blind every hook
+          }
         }
       }
+
+      return state;
+    } catch {
+      return null;
     }
+  })();
 
-    return state;
-  } catch {
-    return null;
-  }
+  stateCache.set(base, state);
+  return state;
 }
 
 /**