@polymorphism-tech/morph-spec 8.15.0 → 8.16.0

package/src/lib/telemetry/telemetry-reader.js

@@ -101,3 +101,216 @@ export function aggregateTelemetry(events, opts = {}) {
     features: [...features],
   };
 }
+
+// ─────────────────────────────────────────────────────────────────────────
+// Cost aggregation — sibling to aggregateTelemetry (kept separate rather than
+// folded in: aggregateTelemetry's return shape is pinned by
+// test/commands/telemetry.test.js, which spreads it wholesale into --json
+// output — adding fields there would leak into that contract).
+//
+// Turns the same raw event stream into a cost-facing view: how much
+// wall-clock time was spent inside measured tasks, how many context bytes
+// were re-ingested (by kind), and how many sub-agent dispatches happened
+// (and how many prompt chars they cost).
+//
+// "Bytes re-ingested" is a DETERMINISTIC PROXY for cost, not a token count —
+// hooks can only see what tools read off disk, never the model's actual
+// token usage. The `cost` command surfaces that caveat; this module only
+// computes the numbers.
+// ─────────────────────────────────────────────────────────────────────────
+
+// Sentinel used to key the open-task map when an event carries no feature
+// (e.g. telemetry-log's getActiveFeature() found none). Without this, a
+// TaskStart with feature: null would silently fail to open (map keyed on
+// undefined/null never matches itself across two different `null`-feature
+// pairs is fine, but `if (e.feature)` truthiness checks would just drop the
+// event) — keying explicitly avoids that class of "counter never increments"
+// bug.
+const NO_FEATURE = '\u0000no-feature';
+
+function featureKey(e) {
+  return e && e.feature ? e.feature : NO_FEATURE;
+}
+
+function tsToMs(ts) {
+  const t = Date.parse(ts);
+  return Number.isNaN(t) ? null : t;
+}
+
+/**
+ * Seconds between two ISO timestamps, rounded to millisecond precision to
+ * absorb float noise from the division. null if either ts is unparsable.
+ */
+function durationSeconds(startTs, endTs) {
+  const a = tsToMs(startTs);
+  const b = tsToMs(endTs);
+  if (a === null || b === null) return null;
+  return Math.round(((b - a) / 1000) * 1000) / 1000;
+}
+
+function mapToObj(map) {
+  const out = {};
+  for (const key of [...map.keys()].sort()) out[key] = map.get(key);
+  return out;
+}
+
+function sumValues(map) {
+  let total = 0;
+  for (const v of map.values()) total += v;
+  return total;
+}
+
+function newTaskState(feature, task, ts) {
+  return {
+    feature: feature ?? null,
+    task,
+    startTs: ts,
+    endTs: null,
+    status: null,
+    open: true,
+    tools: new Map(),
+    bytesByKind: new Map(),
+    dispatches: { count: 0, promptChars: 0 },
+  };
+}
+
+function finalizeTask(state) {
+  return {
+    feature: state.feature,
+    task: state.task,
+    startTs: state.startTs,
+    endTs: state.endTs,
+    durationSeconds: state.endTs ? durationSeconds(state.startTs, state.endTs) : null,
+    status: state.status,
+    open: state.open,
+    tools: rank(state.tools),
+    bytesByKind: mapToObj(state.bytesByKind),
+    bytesTotal: sumValues(state.bytesByKind),
+    dispatches: { ...state.dispatches },
+  };
+}
+
+/**
+ * Summarize an event stream for cost purposes: task segmentation (duration +
+ * per-task tool/byte/dispatch aggregates), bytes-re-ingested buckets by
+ * `kind` (global, per task, per phase), and sub-agent dispatch counts.
+ *
+ * Segmentation model: a task is "open" for a feature from its TaskStart
+ * event until the matching TaskEnd (same feature + task name). Only one task
+ * is assumed open per feature at a time — matches how the implement phase
+ * actually runs (auto-advance processes tasks sequentially, never two tasks
+ * of the same feature concurrently). Events for a feature with no open task
+ * simply don't attribute to any task (they still count toward the
+ * global/phase totals). A TaskEnd with no matching open TaskStart is ignored
+ * — a truncated stream or a legacy event mix never throws. A task left open
+ * at the end of the stream (TaskStart with no TaskEnd yet) is still reported,
+ * with `open: true` and `durationSeconds: null`, rather than silently
+ * dropped.
+ *
+ * Byte attribution keys off `typeof e.bytes === 'number'` alone (not a tool
+ * check) — today only Read events carry `bytes`, but this stays correct if
+ * that widens rather than reporting a silent 0.
+ *
+ * @param {Object[]} events - raw events (from loadTelemetry)
+ * @param {{ feature?: string }} [opts] - optional feature filter
+ * @returns {{
+ *   total: number,
+ *   features: string[],
+ *   taskDurationSeconds: number,
+ *   bytesByKind: Object<string, number>,
+ *   bytesTotal: number,
+ *   dispatches: {count:number, promptChars:number},
+ *   tools: Array<{name:string,count:number}>,
+ *   tasks: Array<Object>,
+ *   phases: Array<{phase:string, bytesByKind:Object<string,number>, bytesTotal:number}>,
+ * }}
+ */
+export function aggregateCost(events, opts = {}) {
+  const scoped = opts.feature
+    ? (events || []).filter(e => e.feature === opts.feature)
+    : (events || []);
+
+  const features = new Set();
+  const toolCounts = new Map();
+  const bytesByKindGlobal = new Map();
+  const dispatches = { count: 0, promptChars: 0 };
+  const phaseBytes = new Map(); // phase -> Map(kind -> bytes)
+  const activeByFeature = new Map(); // featureKey -> open task state
+  const tasks = [];
+
+  for (const e of scoped) {
+    if (!e || typeof e !== 'object') continue;
+    if (e.feature) features.add(e.feature);
+
+    if (e.event === 'TaskStart' && e.task) {
+      activeByFeature.set(featureKey(e), newTaskState(e.feature, e.task, e.ts));
+      continue;
+    }
+
+    if (e.event === 'TaskEnd' && e.task) {
+      const key = featureKey(e);
+      const state = activeByFeature.get(key);
+      if (state && state.task === e.task) {
+        state.endTs = e.ts;
+        state.status = e.status ?? null;
+        state.open = false;
+        activeByFeature.delete(key);
+        tasks.push(finalizeTask(state));
+      }
+      continue;
+    }
+
+    if (e.tool) toolCounts.set(e.tool, (toolCounts.get(e.tool) || 0) + 1);
+    const active = activeByFeature.get(featureKey(e));
+    if (active && e.tool) {
+      active.tools.set(e.tool, (active.tools.get(e.tool) || 0) + 1);
+    }
+
+    if (typeof e.bytes === 'number' && Number.isFinite(e.bytes)) {
+      const kind = e.kind || 'unknown';
+      bytesByKindGlobal.set(kind, (bytesByKindGlobal.get(kind) || 0) + e.bytes);
+      if (active) active.bytesByKind.set(kind, (active.bytesByKind.get(kind) || 0) + e.bytes);
+      if (e.phase) {
+        if (!phaseBytes.has(e.phase)) phaseBytes.set(e.phase, new Map());
+        const m = phaseBytes.get(e.phase);
+        m.set(kind, (m.get(kind) || 0) + e.bytes);
+      }
+    }
+
+    if ((e.tool === 'Agent' || e.tool === 'Task') && typeof e.prompt === 'string' && e.prompt) {
+      dispatches.count += 1;
+      dispatches.promptChars += e.prompt.length;
+      if (active) {
+        active.dispatches.count += 1;
+        active.dispatches.promptChars += e.prompt.length;
+      }
+    }
+  }
+
+  // Tasks still open when the stream ends (no TaskEnd observed yet) are
+  // reported, not dropped — see the "open" contract in the docstring above.
+  for (const state of activeByFeature.values()) tasks.push(finalizeTask(state));
+  tasks.sort((a, b) => (a.startTs || '').localeCompare(b.startTs || ''));
+
+  const phases = [...phaseBytes.entries()]
+    .map(([phase, kindMap]) => ({
+      phase,
+      bytesByKind: mapToObj(kindMap),
+      bytesTotal: sumValues(kindMap),
+    }))
+    .sort((a, b) => a.phase.localeCompare(b.phase));
+
+  const taskDurationSeconds = tasks.reduce((sum, t) => sum + (t.durationSeconds || 0), 0);
+
+  return {
+    total: scoped.length,
+    features: [...features],
+    taskDurationSeconds,
+    bytesByKind: mapToObj(bytesByKindGlobal),
+    bytesTotal: sumValues(bytesByKindGlobal),
+    dispatches,
+    tools: rank(toolCounts),
+    tasks,
+    phases,
+  };
+}

package/src/utils/hooks-installer.js

@@ -17,13 +17,18 @@ import { execSync } from 'child_process';
 /**
  * Current hooks schema version — bump when hook definitions change.
  *
- * 3.5.0 keeps the same registry entries but changes what the installed hooks
- * DO: state is now resolved from the target path's working tree instead of the
- * session's. The hook files are re-copied unconditionally (`copyDirectory`
- * defaults to `overwrite: true`), so the bump does not gate delivery — it makes
- * `morph-spec update` report the change honestly instead of "already current".
+ * 3.6.0 (R2 of the performance plan) consolidates spawns: every core hook now
+ * exports `run(payload)` (framework/hooks/claude-code/core/*.js) and the
+ * registry below routes multi-hook event+matcher groups through the new
+ * `core/chain.js`, which imports and runs several hooks' `run()` in ONE node
+ * process instead of one process per hook. Same events, same matchers, same
+ * observable behavior (block/warn/silent) — only the process count per
+ * Write/Edit drops (9 → 4). The hook files are re-copied unconditionally
+ * (`copyDirectory` defaults to `overwrite: true`), so the bump does not gate
+ * delivery — it makes `morph-spec update` report the change honestly instead
+ * of "already current".
  */
-const HOOKS_VERSION = '3.5.0';
+const HOOKS_VERSION = '3.6.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -83,11 +88,23 @@ const MORPH_PERMISSIONS = MORPH_DENY;
 /**
  * All MORPH-SPEC hook definitions.
  * Each entry maps to a Claude Code hook event.
+ *
+ * R2 consolidation: an entry whose group has more than one hook now declares
+ * ONE `core/chain.js` command with an `args` array (the hook base names, in
+ * the ORDER they run) instead of one command per hook — chain.js imports and
+ * calls each hook's `run(payload)` in that same process (see its own doc
+ * comment for the block-first-wins / context-concatenation rules). A group
+ * with exactly one hook stays a direct command — chaining a single link buys
+ * nothing. `args` must stay a SEPARATE field from `command`: `getHookSubpath()`
+ * below extracts the installed path from `command` alone via a regex anchored
+ * on `claude-code/`, and inlining args into that string would get captured
+ * into the quoted path.
  */
 const MORPH_HOOKS = [
   // === SessionStart — worktree feature identity (secondary worktree) or
   // active-feature summary (primary root). Fulfills the SessionStart
-  // injection role long documented but never wired (inject-morph-context.js). ===
+  // injection role long documented but never wired (inject-morph-context.js).
+  // Solo (only hook for this event) — nothing to chain. ===
   {
     event: 'SessionStart',
     matcher: null,
@@ -98,23 +115,24 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === PreToolUse: Write|Edit — phase + spec protection (silent on success) ===
+  // === PreToolUse: Write|Edit — phase + spec protection (silent on success).
+  // Chained in the SAME order the previous two-entry registry ran them:
+  // protect-spec-files (locked-file check) before enforce-phase-writes (phase
+  // folder check) — a block from either one wins and skips the other. Neither
+  // hook declared its own timeout (both are pure sync fs checks with no
+  // subprocess calls), so the chain declares none either — same platform
+  // default both relied on individually. ===
   {
     event: 'PreToolUse',
     matcher: 'Write|Edit',
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/protect-spec-files.js'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/enforce-phase-writes.js'
-      }
-    ]
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/chain.js',
+      args: ['protect-spec-files', 'enforce-phase-writes']
+    }]
   },
 
-  // === PreToolUse: Bash — denylist (irreversible commands only) ===
+  // === PreToolUse: Bash — denylist (irreversible commands only). Solo. ===
   {
     event: 'PreToolUse',
     matcher: 'Bash',
@@ -129,75 +147,63 @@ const MORPH_HOOKS = [
   // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) +
   // tasks.json schema guard (validate-and-warn; status enum, effort enum) +
   // trace auto-generation (tasks.json write → .morph/traces/, replaces the
-  // manual trace-writing step the skills used to carry) ===
+  // manual trace-writing step the skills used to carry). Chained in the same
+  // order as before. post-edit-typecheck declared no timeout of its own (it
+  // can legitimately spend up to its internal TSC_TIMEOUT_MS=30000 running
+  // `npx tsc --noEmit`), so the chain declares none rather than under-
+  // provisioning it with just the sum of the other two links' 3000ms each. ===
   {
     event: 'PostToolUse',
     matcher: 'Write|Edit',
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/post-edit-typecheck.js'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/tasks-json-guard.js',
-        timeout: 3000
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/trace-autogen.js',
-        timeout: 3000
-      }
-    ]
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/chain.js',
+      args: ['post-edit-typecheck', 'tasks-json-guard', 'trace-autogen']
+    }]
   },
 
-  // === PostToolUse: Write|Edit|AskUserQuestion — state-sync (autonomous state.json updates) ===
-  // gate-guard runs AFTER state-sync so it sees the gate that state-sync just
-  // recorded. Both are silent fail-open guardrails; gate-guard only warns
-  // (never blocks) when an observed gate action disagrees with the persisted
-  // gateDecisions (issue #63).
+  // === PostToolUse: Write|Edit|AskUserQuestion — state-sync (autonomous
+  // state.json updates) then gate-guard. gate-guard runs AFTER state-sync so
+  // it sees the gate that state-sync just recorded — now true within a single
+  // process too, because state-writer.js's persistFeature() invalidates
+  // state-reader.js's per-process loadState() memo on every write (R1.1 added
+  // that memo; without the invalidation, a chained gate-guard could read the
+  // pre-write snapshot). Both are silent fail-open guardrails; gate-guard only
+  // warns (never blocks) when an observed gate action disagrees with the
+  // persisted gateDecisions (issue #63). Both links declared 3000ms; sequential
+  // execution means the worst case is additive, so the chain declares the sum. ===
   {
     event: 'PostToolUse',
     matcher: 'Write|Edit|AskUserQuestion',
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/state-sync.js',
-        timeout: 3000
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/gate-guard.js',
-        timeout: 3000
-      }
-    ]
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/chain.js',
+      args: ['state-sync', 'gate-guard'],
+      timeout: 6000
+    }]
   },
 
-  // === PostToolUse: All — telemetry capture (silent) + loop detection ===
+  // === PostToolUse: All — telemetry capture (silent) + loop detection.
   // telemetry-log is the single generic vantage point of an NLH: it appends
   // every tool call (skill, sub-agent dispatch, knowledge-base read, …) to
   // .morph/logs/events.jsonl. Silent and fail-open — never blocks, never
-  // injects. `morph-spec telemetry` reads the stream back.
+  // injects. `morph-spec telemetry` reads the stream back. Both links
+  // declared 5000ms; chain declares the sum (sequential worst case). ===
   {
     event: 'PostToolUse',
     matcher: null,
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/telemetry-log.js',
-        timeout: 5000
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/loop-detect.js',
-        timeout: 5000
-      }
-    ]
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/chain.js',
+      args: ['telemetry-log', 'loop-detect'],
+      timeout: 10000
+    }]
   },
 
-  // === UserPromptSubmit — telemetry capture of the user's prompt (silent) ===
+  // === UserPromptSubmit — telemetry capture of the user's prompt (silent).
   // The only vantage point on the user's own prompt; completes the execution
-  // path alongside sub-agent prompts captured on PostToolUse.
+  // path alongside sub-agent prompts captured on PostToolUse. Solo (the only
+  // hook registered on this event) — nothing to chain. ===
   {
     event: 'UserPromptSubmit',
     matcher: null,
@@ -208,7 +214,7 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === Stop — build check + session snapshot ===
+  // === Stop — build check + session snapshot. Solo. ===
   {
     event: 'Stop',
     matcher: null,
@@ -269,17 +275,16 @@ export async function installClaudeHooks(targetPath) {
       entry.matcher = matcher;
     }
     entry.hooks = hooks.map(h => {
-      // Agent and prompt hooks: pass through as-is (no command path transform)
-      if (h.type === 'agent' || h.type === 'prompt') {
-        const agentHook = { type: h.type, prompt: h.prompt };
-        if (h.timeout !== undefined) agentHook.timeout = h.timeout;
-        return agentHook;
-      }
-      // Command hooks: transform path to use $CLAUDE_PROJECT_DIR
-      // Hooks are copied to .morph/framework/hooks/ during `morph-spec init/update`
+      // Command hooks: transform path to use $CLAUDE_PROJECT_DIR.
+      // Hooks are copied to .morph/framework/hooks/ during `morph-spec init/update`.
+      // `args` (chain.js's hook-name list) is appended AFTER the closing quote —
+      // getHookSubpath() below only ever sees the bare `h.command` path, never
+      // the args, so it can't accidentally capture them into the quoted command.
+      const quotedPath = `node "$CLAUDE_PROJECT_DIR/.morph/framework/hooks/claude-code/${getHookSubpath(h.command)}"`;
+      const command = h.args?.length ? `${quotedPath} ${h.args.join(' ')}` : quotedPath;
       return {
         type: h.type,
-        command: `node "$CLAUDE_PROJECT_DIR/.morph/framework/hooks/claude-code/${getHookSubpath(h.command)}"`,
+        command,
         ...(h.timeout !== undefined ? { timeout: h.timeout } : {})
       };
     });

package/framework/hooks/shared/session-snapshot.js

@@ -1,105 +0,0 @@
-/**
- * Session Snapshot — cross-session persistence utility
- *
- * Saves and loads session state for "getting up to speed" on next session.
- * Single file (overwrites) — history preserved via git.
- *
- * Fail-silent: never throws.
- */
-
-import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, unlinkSync } from 'fs';
-import { join } from 'path';
-
-const SNAPSHOT_PATH = '.morph/memory/session-snapshot.json';
-
-/**
- * Save session snapshot atomically.
- * @param {Object} data - Snapshot data
- * @param {string} [projectPath] - Project root (defaults to cwd)
- */
-export function saveSessionSnapshot(data, projectPath) {
-  try {
-    const root = projectPath || process.cwd();
-    const dir = join(root, '.morph', 'memory');
-    mkdirSync(dir, { recursive: true });
-
-    const snapshot = { ...data, savedAt: new Date().toISOString() };
-    const filePath = join(root, SNAPSHOT_PATH);
-    const tmpPath = `${filePath}.tmp.${process.pid}`;
-
-    writeFileSync(tmpPath, JSON.stringify(snapshot, null, 2), 'utf-8');
-    try {
-      renameSync(tmpPath, filePath);
-    } catch {
-      writeFileSync(filePath, JSON.stringify(snapshot, null, 2), 'utf-8');
-      try { unlinkSync(tmpPath); } catch { /* ignore */ }
-    }
-  } catch {
-    // Fail-silent
-  }
-}
-
-/**
- * Load session snapshot.
- * @param {string} [projectPath] - Project root (defaults to cwd)
- * @returns {Object|null} Parsed snapshot or null
- */
-export function loadSessionSnapshot(projectPath) {
-  try {
-    const filePath = join(projectPath || process.cwd(), SNAPSHOT_PATH);
-    if (!existsSync(filePath)) return null;
-    return JSON.parse(readFileSync(filePath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Format snapshot as concise context string for SessionStart injection.
- * Budget: max ~150 tokens (~600 chars).
- *
- * @param {Object|null} snapshot
- * @returns {string|null} Formatted context or null
- */
-export function formatPreviousSession(snapshot) {
-  if (!snapshot) return null;
-
-  const lines = ['=== PREVIOUS SESSION ==='];
-
-  // Header line
-  const date = snapshot.savedAt ? new Date(snapshot.savedAt).toISOString().slice(0, 16).replace('T', ' ') : '?';
-  const phase = snapshot.phase || '?';
-  const build = snapshot.buildStatus || 'unknown';
-  lines.push(`Last: ${date} | Phase: ${phase} | Build: ${build}`);
-
-  // Tasks (truncated)
-  const done = snapshot.tasksCompleted || [];
-  if (done.length > 0) {
-    const shown = done.slice(-5).join(', ');
-    const prefix = done.length > 5 ? `...${done.length} total, last: ` : '';
-    lines.push(`Done: ${prefix}${shown}`);
-  }
-
-  const wip = snapshot.tasksInProgress || [];
-  if (wip.length > 0) {
-    lines.push(`WIP: ${wip.join(', ')}`);
-  }
-
-  const remaining = snapshot.tasksRemaining || [];
-  if (remaining.length > 0) {
-    const shown = remaining.slice(0, 5).join(', ');
-    const suffix = remaining.length > 5 ? ` +${remaining.length - 5} more` : '';
-    lines.push(`Remaining: ${shown}${suffix}`);
-  }
-
-  // Files (truncated)
-  const files = snapshot.lastEditedFiles || [];
-  if (files.length > 0) {
-    const shown = files.slice(0, 3).join(', ');
-    const suffix = files.length > 3 ? ` +${files.length - 3} more` : '';
-    lines.push(`Files: ${shown}${suffix}`);
-  }
-
-  lines.push('===');
-  return lines.join('\n');
-}