@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

package/framework/hooks/claude-code/session-start/inject-morph-context.js

@@ -15,8 +15,11 @@ import { loadState, getActiveFeature, getPendingGates, getMissingOutputs, derive
 import { stateExists } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { resetActivity, logHookActivity } from '../../shared/activity-logger.js';
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync } from 'fs';
 import { join } from 'path';
+import { resetStaleTasks } from '../../shared/stale-task-reset.js';
+import { execSync as _execSync } from 'child_process';
+import { parseWorktreeResult, buildWorktreeContextLine } from '../../shared/worktree-helpers.js';
 
 const DEFAULT_SPEC_MAX_CHARS = 3000;
 
@@ -43,6 +46,26 @@ function getProjectConfig() {
 
 const SPEC_MAX_CHARS = getSpecMaxChars();
 
+/**
+ * Atomic state save for hook context.
+ * Same approach as state-manager.js saveState — write to tmp, then rename.
+ * Fail-open: any error is silently ignored.
+ * @param {Object} state - Full state object
+ * @param {string} cwd - Project root path
+ */
+function saveStateSync(state, cwd) {
+  const statePath = join(cwd, '.morph/state.json');
+  const tmpPath = `${statePath}.tmp.hook.${process.pid}`;
+  try {
+    state.metadata = state.metadata || {};
+    state.metadata.lastUpdated = new Date().toISOString();
+    writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
+    renameSync(tmpPath, statePath);
+  } catch {
+    try { unlinkSync(tmpPath); } catch { /* ignore cleanup errors */ }
+  }
+}
+
 try {
   if (!stateExists()) pass();
 
@@ -57,7 +80,19 @@ try {
   resetActivity(new Date().toISOString(), activeFeatureName, activePhase);
   logHookActivity('inject-morph-context', 'SessionStart', 'ok');
 
+  // ── Stale task cleanup ──────────────────────────────────────────────────────
+  // Reset any in_progress tasks older than 1 hour — they are orphans from an
+  // interrupted session and are no longer being actively implemented.
+  const staleResetLog = resetStaleTasks(state);
+  if (staleResetLog.length > 0) {
+    saveStateSync(state, process.cwd());
+  }
+  // ────────────────────────────────────────────────────────────────────────────
+
   const lines = ['MORPH-SPEC Status:'];
+  if (staleResetLog.length > 0) {
+    lines.push(`⚠️  ${staleResetLog.length} task(s) auto-reset in_progress → pending (orphaned from previous session): ${staleResetLog.join(', ')}`);
+  }
 
   if (active) {
     const { name, feature } = active;
@@ -129,6 +164,40 @@ try {
         // Non-blocking: skip spec injection on read error
       }
     }
+
+    // ── Worktree setup ──────────────────────────────────────────────────────────
+    // For the active feature, create or detect an existing git worktree.
+    // Trigger: uses getActiveFeature() (status-based) rather than checking
+    // activeAgents, because status is the canonical signal already used by the
+    // rest of this hook. activeAgents is populated later in the spec pipeline,
+    // so a status-based gate ensures the worktree is always created before work
+    // begins — even for features still in early phases.
+    // Fail-open: any error is silently ignored.
+    try {
+      let worktreeStdout = '';
+      try {
+        worktreeStdout = _execSync(`npx morph-spec worktree setup ${active.name}`, {
+          cwd: process.cwd(),
+          stdio: 'pipe',
+          timeout: 10000
+        }).toString();
+      } catch (execErr) {
+        // exit code 2 = already exists — stdout still has the JSON result
+        worktreeStdout = execErr.stdout?.toString() || '';
+      }
+      const worktreeResult = parseWorktreeResult(worktreeStdout);
+      if (worktreeResult) {
+        worktreeResult.feature = active.name; // enrich for context builder
+        const contextLine = buildWorktreeContextLine(worktreeResult);
+        if (contextLine) {
+          lines.push('');
+          lines.push(contextLine);
+        }
+      }
+    } catch {
+      // Fail-open — worktree setup must never block the session
+    }
+    // ────────────────────────────────────────────────────────────────────────────
   } else {
     // Show summary of all features
     const featureNames = Object.keys(state.features);
@@ -140,6 +209,59 @@ try {
     }
   }
 
+  // ── MCP status injection ────────────────────────────────────────────────────
+  // Cross-reference configured MCPs with phase recommendations from mcp-registry.json.
+  // Fail-open: all inside try/catch, no crash on missing files.
+  try {
+    const currentPhase = active ? derivePhaseForFeature(active.name) : '';
+    if (currentPhase) {
+      // Read configured MCPs from settings
+      const configuredMcps = new Set();
+      const settingsFiles = [
+        join(process.cwd(), '.claude', 'settings.local.json'),
+        join(process.cwd(), '.claude', 'settings.json'),
+      ];
+      for (const sf of settingsFiles) {
+        if (existsSync(sf)) {
+          try {
+            const s = JSON.parse(readFileSync(sf, 'utf8'));
+            for (const name of Object.keys(s.mcpServers || {})) {
+              configuredMcps.add(name.toLowerCase());
+            }
+          } catch { /* ignore */ }
+        }
+      }
+
+      // Read recommended MCPs from phases.json or mcp-registry.json
+      let recommended = [];
+      const registryPaths = [
+        join(process.cwd(), 'framework', 'skills', 'level-0-meta', 'mcp-registry.json'),
+        join(process.cwd(), '.morph', 'framework', 'skills', 'level-0-meta', 'mcp-registry.json'),
+      ];
+      for (const rp of registryPaths) {
+        if (existsSync(rp)) {
+          try {
+            const registry = JSON.parse(readFileSync(rp, 'utf8'));
+            recommended = registry.phaseMatrix?.[currentPhase] || [];
+            break;
+          } catch { /* ignore */ }
+        }
+      }
+
+      if (recommended.length > 0) {
+        const mcpStatus = recommended.map(name => {
+          const isConfigured = configuredMcps.has(name.toLowerCase());
+          return `${name} ${isConfigured ? '✓' : '✗ (recommended)'}`;
+        });
+        lines.push('');
+        lines.push(`MCPs: ${mcpStatus.join(', ')}`);
+      }
+    }
+  } catch {
+    // Fail-open — MCP status must never block the session
+  }
+  // ────────────────────────────────────────────────────────────────────────────
+
   // Remind about key commands
   lines.push('');
   lines.push('Key commands: morph-spec status <feature> | morph-spec phase advance <feature> | morph-spec approve <feature> <gate>');
@@ -151,7 +273,7 @@ try {
     lines.push('');
     lines.push('── MORPH SYSTEM MAP ─────────────────────────────────────────────');
     lines.push(`🪝 Hooks: 10 registrados  |  📏 Rules: em .claude/rules/  |  🎯 Skills: em .claude/skills/`);
-    lines.push(`   Execute \`morph-spec monitor\` em terminal separado para live view`);
+    lines.push(`   Use \`morph-spec doctor\` para health check  |  \`morph-spec status ${name}\` para dashboard`);
     lines.push('─────────────────────────────────────────────────────────────────');
   }
 

package/framework/hooks/claude-code/session-start/post-compact-restore.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart Hook: Post-Compact Context Restore
+ *
+ * Event: SessionStart | Matcher: compact
+ *
+ * Fires ONLY when a session starts after context compaction.
+ * Reads the latest pre-compact memory file and injects the richContext
+ * block (decisions.md snippet + task list) so Claude resumes with full
+ * morph awareness even if the compact summary was truncated.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { buildRestoreBlock, findLatestMemoryFile } from '../../shared/compact-restore.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const memoryDir = join(process.cwd(), '.morph', 'memory');
+  if (!existsSync(memoryDir)) pass();
+
+  const files = readdirSync(memoryDir);
+  const latest = findLatestMemoryFile(files);
+  if (!latest) pass();
+
+  const raw = readFileSync(join(memoryDir, latest), 'utf-8');
+  const snapshot = JSON.parse(raw);
+
+  const block = buildRestoreBlock(snapshot);
+  if (!block) pass();
+
+  injectContext(block);
+} catch {
+  process.exit(0);
+}

package/framework/hooks/claude-code/statusline.py

@@ -151,7 +151,10 @@ def get_session_feature_names(features_dict, entries):
 
 
 def get_all_active_features(cwd, entries):
-    """Return in_progress features that are active in the current session."""
+    """Return in_progress features that are active in the current session.
+
+    Caller is responsible for only calling this when inside a secondary worktree.
+    """
     state_path = Path(cwd) / '.morph' / 'state.json'
     if not state_path.exists():
         return []
@@ -162,11 +165,6 @@ def get_all_active_features(cwd, entries):
         # Filter to features belonging to this session (mentioned in transcript)
         session_names = get_session_feature_names(features, entries)
 
-        # Auto-detect: if only one feature is in_progress, show it regardless of transcript
-        in_progress = [n for n, f in features.items() if f.get('status') == 'in_progress']
-        if len(in_progress) == 1:
-            session_names.add(in_progress[0])
-
         if not session_names:
             return []
 
@@ -310,8 +308,14 @@ def get_git_info(cwd):
         return ""
 
 
-def get_worktree_info(cwd):
-    """Detect if running in a git worktree (not the main worktree)."""
+def get_worktree_data(cwd):
+    """Detect worktree status for cwd.
+
+    Returns (is_secondary: bool, display_str: str).
+    is_secondary is True only when cwd is a non-primary git worktree.
+    display_str is the formatted label (non-empty only when is_secondary).
+    Called once in main() to avoid duplicate git subprocess.
+    """
     try:
         out = _run_git(['worktree', 'list', '--porcelain'], cwd)
         entries, current = [], {}
@@ -329,10 +333,45 @@ def get_worktree_info(cwd):
             for entry in entries[1:]:
                 if str(Path(entry.get('path', '')).resolve()) == cwd_r:
                     branch = entry.get('branch', '').replace('refs/heads/', '')
-                    return f"{MAGENTA}worktree:{branch}{R}"
+                    return True, f"{MAGENTA}worktree:{branch}{R}"
     except Exception:
         pass
-    return ""
+    return False, ""
+
+
+def get_recent_tool_calls(entries):
+    """Scan the last 50 transcript entries for the most recent Skill and Agent tool calls.
+
+    Returns (last_skill_name, last_agent_name) — either may be None.
+    Looks at assistant messages containing tool_use blocks.
+    """
+    last_skill = None
+    last_agent = None
+    recent = entries[-50:] if len(entries) > 50 else entries
+    for entry in reversed(recent):
+        if entry.get('isSidechain') or entry.get('isApiErrorMessage'):
+            continue
+        msg = entry.get('message') or {}
+        content = msg.get('content') or []
+        if not isinstance(content, list):
+            continue
+        # Within each entry, scan content from last to first to get most-recent call
+        for item in reversed(content):
+            if not isinstance(item, dict) or item.get('type') != 'tool_use':
+                continue
+            tool = item.get('name', '')
+            inp = item.get('input') or {}
+            if tool == 'Skill' and last_skill is None:
+                last_skill = inp.get('skill') or ''
+            elif tool == 'Agent' and last_agent is None:
+                agent_name = inp.get('subagent_type') or ''
+                if not agent_name:
+                    desc = inp.get('description') or inp.get('prompt') or ''
+                    agent_name = (desc[:22] + '…') if len(desc) > 25 else desc
+                last_agent = agent_name
+        if last_skill is not None and last_agent is not None:
+            break
+    return last_skill or None, last_agent or None
 
 
 # ── Transcript / JSONL helpers ────────────────────────────────────────────────
@@ -493,12 +532,18 @@ def main():
         cwd             = data.get('cwd', os.getcwd())
         transcript_path = data.get('transcript_path')
 
-        # Read JSONL transcript once — shared by session clock, block timer,
-        # token metrics, and session name.
+        # Read JSONL transcript once — shared by session clock, token metrics,
+        # session name, and skill/agent detection.
         entries = read_transcript_jsonl(transcript_path) if transcript_path else []
 
+        # ── Worktree detection (single git call) ─────────────────────────────────
+        # Feature lines are only shown when inside a secondary git worktree.
+        # This prevents stale feature names showing up during unrelated work
+        # in the main worktree.
+        is_worktree, wt_display = get_worktree_data(cwd)
+
         # ── MORPH feature lines (one line per active feature) ────────────────────
-        features = get_all_active_features(cwd, entries)
+        features = get_all_active_features(cwd, entries) if is_worktree else []
         for feat in features:
             # Feature name with visual prefix
             parts = [f"{CYAN}{BOLD}► {feat['name']}{R}"]
@@ -536,19 +581,14 @@ def main():
 
             print('  |  '.join(parts))
 
-        # ── Activity info line (hooks + last event) ──────────────────────────────
-        if features:  # only show when a feature is active
+        # ── Activity info line (hooks; only shown when a feature is active) ───────
+        if features:
             activity = get_activity_info(cwd)
-            if activity and (activity['hook_count'] > 0 or activity['skill_count'] > 0):
-                act_parts = []
-                if activity['hook_count'] > 0:
-                    hook_label = activity['last_hook'] or '?'
-                    age_str = f"({activity['last_hook_age']})" if activity['last_hook_age'] else ''
-                    act_parts.append(f"{BLUE}🪝 {hook_label} {age_str}{R}".strip())
-                if activity['skill_count'] > 0:
-                    act_parts.append(f"{YELLOW}🎯 {activity['skill_count']} skill(s){R}")
-                if act_parts:
-                    print(f"  {GRAY}└{R} " + f"  {GRAY}|{R}  ".join(act_parts))
+            if activity and activity['hook_count'] > 0:
+                hook_label = activity['last_hook'] or '?'
+                age_str = f"({activity['last_hook_age']})" if activity['last_hook_age'] else ''
+                hook_str = f"{BLUE}🪝 {hook_label} {age_str}{R}".strip()
+                print(f"  {GRAY}└{R} {hook_str}")
 
         # ── Session info line (always shown) ─────────────────────────────────────
         parts2 = []
@@ -580,6 +620,14 @@ def main():
             }
             parts2.append(f"{YELLOW}{_perm_labels.get(perm, perm)}{R}")
 
+        # Last skill and agent invoked (parsed from transcript tool_use blocks)
+        if entries:
+            last_skill, last_agent = get_recent_tool_calls(entries)
+            if last_skill:
+                parts2.append(f"{YELLOW}🎯 {last_skill}{R}")
+            if last_agent:
+                parts2.append(f"{MAGENTA}⚡ {last_agent}{R}")
+
         # Session clock (elapsed time since session start, survives transcript transitions)
         session_start = get_session_start(cwd, transcript_path, entries)
         duration = get_session_duration(session_start)
@@ -611,16 +659,14 @@ def main():
                 line += f" ({toks})"
             parts2.append(line + suffix)
 
-
         # Git info (branch + diff stats)
         git = get_git_info(cwd)
         if git:
             parts2.append(git)
 
-        # Worktree info
-        wt = get_worktree_info(cwd)
-        if wt:
-            parts2.append(wt)
+        # Worktree label (already computed above — reuse result)
+        if wt_display:
+            parts2.append(wt_display)
 
         if parts2:
             print('  |  '.join(parts2))

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

@@ -21,7 +21,7 @@
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import {
-  stateExists, loadState, getActiveFeature, getMissingOutputs, derivePhaseForFeature,
+  stateExists, getActiveFeature, getMostRecentFeature, getMissingOutputs, derivePhaseForFeature,
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
@@ -40,20 +40,7 @@ try {
 
   // getActiveFeature() only returns in_progress/draft features.
   // Fall back to the most recently updated feature when all features are 'done'.
-  let active = getActiveFeature();
-  if (!active) {
-    const state = loadState();
-    if (state?.features) {
-      let latestUpdate = '';
-      for (const [name, feature] of Object.entries(state.features)) {
-        const updated = feature.updatedAt || feature.createdAt || '';
-        if (updated >= latestUpdate) {
-          latestUpdate = updated;
-          active = { name, feature };
-        }
-      }
-    }
-  }
+  let active = getActiveFeature() || getMostRecentFeature();
   if (!active) pass();
 
   const { name, feature } = active;

package/framework/hooks/claude-code/user-prompt/enrich-prompt.js

@@ -15,7 +15,7 @@
  */
 
 import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists, loadState, getActiveFeature, getFeature, getPendingGates } from '../../shared/state-reader.js';
+import { stateExists, loadState, getActiveFeature, getFeature, getPendingGates, derivePhaseForFeature } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 
@@ -37,7 +37,8 @@ try {
   // Check if a feature name is mentioned
   for (const [featureName, feature] of Object.entries(state.features)) {
     if (promptLower.includes(featureName.toLowerCase())) {
-      context.push(`[morph-spec] Feature '${featureName}': phase=${feature.phase}, status=${feature.status}`);
+      const featurePhase = feature.phase || derivePhaseForFeature(featureName);
+      context.push(`[morph-spec] Feature '${featureName}': phase=${featurePhase}, status=${feature.status}`);
       if (feature.tasks?.total > 0) {
         context.push(`  Tasks: ${feature.tasks.completed || 0}/${feature.tasks.total} completed`);
       }
@@ -50,16 +51,33 @@ try {
   if (active) {
     const { name, feature } = active;
 
+    const activePhase = feature.phase || derivePhaseForFeature(name);
     const codeKeywords = ['implement', 'code', 'start coding', 'write the code', 'build it', 'let\'s build'];
     const wantsToCode = codeKeywords.some(kw => promptLower.includes(kw));
 
-    if (wantsToCode && feature.phase !== 'implement' && feature.phase !== 'sync') {
+    if (wantsToCode && activePhase !== 'implement' && activePhase !== 'sync') {
       context.push(
-        `[morph-spec] WARNING: Feature '${name}' is in '${feature.phase}' phase, not 'implement'.` +
+        `[morph-spec] WARNING: Feature '${name}' is in '${activePhase}' phase, not 'implement'.` +
         ` Complete the current phase first or advance: morph-spec phase advance ${name}`
       );
     }
 
+    // Coding intent during implement phase but no task in_progress
+    if (wantsToCode && activePhase === 'implement') {
+      let hasActiveTask = feature.tasks?.inProgress > 0;
+      if (!hasActiveTask && feature.taskList) {
+        hasActiveTask = feature.taskList.some(t => t.status === 'in_progress');
+      }
+      if (!hasActiveTask) {
+        context.push(
+          `[morph-spec] REMINDER: No task is currently in_progress for '${name}'.` +
+          ` Start a task before coding:\n` +
+          `  npx morph-spec task next ${name}        # see what's next\n` +
+          `  npx morph-spec task start ${name} <id>   # mark it in progress`
+        );
+      }
+    }
+
     // Check for approval intent
     const approvalKeywords = ['approve', 'approved', 'looks good', 'lgtm', 'ship it'];
     const wantsToApprove = approvalKeywords.some(kw => promptLower.includes(kw));
@@ -75,7 +93,7 @@ try {
 
     // Check for "next task" intent
     if (promptLower.includes('next task') || promptLower.includes('what\'s next')) {
-      if (feature.phase === 'implement') {
+      if (activePhase === 'implement') {
         context.push(
           `[morph-spec] Use: morph-spec task next ${name}`
         );

package/framework/hooks/claude-code/user-prompt/set-terminal-title.js

@@ -40,21 +40,29 @@ try {
   const prefix = process.env.CLAUDE_TITLE_PREFIX ? `${process.env.CLAUDE_TITLE_PREFIX} ` : '';
   const finalTitle = `${prefix}${title}`;
 
-  // Save to ~/.claude/terminal_title (for shell hook integration)
+  // Save to session-specific file (MORPH_TERMINAL_TITLE_FILE) or fallback to global
+  // MORPH_TERMINAL_TITLE_FILE is set by the shell wrapper (Invoke-Claude / claude())
+  // per-session so multiple terminal windows don't interfere with each other.
   try {
+    const titleFilePath = process.env.MORPH_TERMINAL_TITLE_FILE
+      || join(homedir(), '.claude', 'terminal_title');
     const claudeDir = join(homedir(), '.claude');
     await mkdir(claudeDir, { recursive: true });
-    await writeFile(join(claudeDir, 'terminal_title'), finalTitle, 'utf-8');
+    await writeFile(titleFilePath, finalTitle, 'utf-8');
   } catch { /* non-critical */ }
 
-  // Write ANSI escape to /dev/tty (bypasses stdout capture by Claude Code)
+  // Write ANSI escape to terminal device (bypasses stdout capture by Claude Code)
+  // Windows uses \\.\CONOUT$ as the equivalent of /dev/tty
+  let wrote = false;
   try {
-    const tty = openSync('/dev/tty', 'w');
+    const devicePath = process.platform === 'win32' ? '\\\\.\\CONOUT$' : '/dev/tty';
+    const tty = openSync(devicePath, 'w');
     writeSync(tty, `\x1b]0;${finalTitle}\x07`);
     closeSync(tty);
-  } catch { /* terminal may not support /dev/tty */ }
+    wrote = true;
+  } catch { /* terminal may not support direct device access */ }
 
-  logHookActivity('set-terminal-title', 'UserPromptSubmit', 'ok');
+  logHookActivity('set-terminal-title', 'UserPromptSubmit', wrote ? 'ok' : 'failed');
 } catch { /* fail-open */ }
 
 process.exit(0);

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

@@ -64,30 +64,6 @@ export function logHookActivity(name, event, result, projectPath) {
   }
 }
 
-/**
- * Log a skill invocation to the session activity log.
- *
- * @param {string} name   - Skill name (e.g. 'brainstorming')
- * @param {string} [projectPath]
- */
-export function logSkillActivity(name, projectPath) {
-  try {
-    const activityPath = getActivityPath(projectPath);
-    ensureLogsDir(projectPath);
-
-    const now = new Date();
-    const ts = now.toTimeString().slice(0, 8);
-
-    const data = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], skills: [] };
-
-    data.skills = data.skills || [];
-    data.skills.push({ name, ts });
-
-    writeFileSync(activityPath, JSON.stringify(data, null, 2), 'utf-8');
-  } catch {
-    // Fail-silent
-  }
-}
 
 /**
  * Read the current activity log.

package/framework/hooks/shared/compact-restore.js

@@ -0,0 +1,100 @@
+/**
+ * Shared helpers for post-compact context restoration.
+ *
+ * Used by:
+ *   - pre-compact hook: buildRichContext() to enrich memory file
+ *   - post-compact-restore hook: buildRestoreBlock() + findLatestMemoryFile() to inject context
+ *
+ * Pure functions — no I/O.
+ */
+
+export const DECISIONS_MAX_CHARS = 1500;
+export const MAX_PENDING_TASKS   = 8;
+
+/**
+ * Build the richContext object to embed in pre-compact memory file.
+ * @param {Object} feature          - Feature state object (tasks, taskList)
+ * @param {string} phase            - Current derived phase string
+ * @param {string} decisionsContent - Raw text of decisions.md (may be empty string)
+ * @returns {Object} richContext
+ */
+export function buildRichContext(feature, phase, decisionsContent) {
+  const taskList = Array.isArray(feature.taskList) ? feature.taskList : [];
+
+  const inProgress = taskList
+    .filter(t => t.status === 'in_progress')
+    .map(t => t.id);
+
+  const nextPending = taskList
+    .filter(t => t.status === 'pending')
+    .slice(0, MAX_PENDING_TASKS)
+    .map(t => ({ id: t.id, title: t.title }));
+
+  const decisionsSnippet = decisionsContent.length > DECISIONS_MAX_CHARS
+    ? decisionsContent.slice(0, DECISIONS_MAX_CHARS)
+    : decisionsContent;
+
+  return {
+    phase,
+    tasks:            feature.tasks || {},
+    decisionsSnippet,
+    inProgress,
+    nextPending,
+  };
+}
+
+/**
+ * Build the context block string to inject in session-start after compact.
+ * @param {Object} memorySnapshot - Parsed pre-compact-*.json file contents
+ * @returns {string|null} Block string, or null if no richContext present
+ */
+export function buildRestoreBlock(memorySnapshot) {
+  const rc = memorySnapshot?.richContext;
+  if (!rc) return null;
+
+  const { timestamp, activeFeature } = memorySnapshot;
+  const { phase, tasks, decisionsSnippet, inProgress, nextPending } = rc;
+
+  const done  = tasks?.completed ?? '?';
+  const total = tasks?.total     ?? '?';
+
+  const lines = [
+    `\uD83D\uDD04 POST-COMPACT RESTORE \u2014 context from pre-compact snapshot (${timestamp})`,
+    `Active feature: ${activeFeature} | Phase: ${phase} | Tasks: ${done}/${total}`,
+  ];
+
+  if (decisionsSnippet) {
+    lines.push('');
+    lines.push('Key decisions (at time of compact):');
+    lines.push(decisionsSnippet);
+  }
+
+  if (inProgress.length > 0) {
+    lines.push('');
+    lines.push(`In progress at compact time: [${inProgress.join(', ')}]`);
+  }
+
+  if (nextPending.length > 0) {
+    lines.push('');
+    lines.push('Next pending at compact time:');
+    for (const t of nextPending) {
+      lines.push(`  [${t.id}] ${t.title}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Find the most recent pre-compact memory file from a list of filenames.
+ * Files named pre-compact-{ISO-timestamp-sanitized}.json — sort descending picks latest.
+ * @param {string[]} filenames - Array of filenames in the memory directory
+ * @returns {string|null} Latest filename, or null if none found
+ */
+export function findLatestMemoryFile(filenames) {
+  const matches = filenames
+    .filter(f => f.startsWith('pre-compact-') && f.endsWith('.json'))
+    .sort()
+    .reverse();
+  return matches.length > 0 ? matches[0] : null;
+}