muonroi-cli 1.8.3 → 1.8.5

package/dist/src/flow/compaction/compress.js

@@ -4,7 +4,11 @@
  * Serializes messages, extracts preserved blocks, compresses if over budget,
  * then restores preserved blocks into the output.
  */
+import { generateText } from "ai";
 import { serializeConversation } from "../../orchestrator/compaction.js";
+import { resolveModelRuntime, resolveTemperatureParam, } from "../../providers/runtime.js";
+import { logger } from "../../utils/logger.js";
+import { capCompactionInput } from "./input-guard.js";
 import { extractPreservedBlocks, restorePreservedBlocks } from "./preserve.js";
 /**
  * Compress chat messages within a token budget.
@@ -12,9 +16,9 @@ import { extractPreservedBlocks, restorePreservedBlocks } from "./preserve.js";
  * 1. Serialize messages via serializeConversation().
  * 2. Extract preserved blocks.
  * 3. If under budget, return as-is (with preserved blocks restored).
- * 4. If over budget, truncate/compress and restore preserved blocks.
+ * 4. If over budget, compress via LLM (if provider given) or truncate, and restore blocks.
  */
-export async function compressChat(messages, _systemPrompt, tokenBudget, _provider, _modelId) {
+export async function compressChat(messages, _systemPrompt, tokenBudget, provider, modelId, customInstructions) {
     const serialized = serializeConversation(messages);
     const { cleaned, blocks } = extractPreservedBlocks(serialized);
     // Estimate tokens of cleaned text
@@ -28,16 +32,49 @@ export async function compressChat(messages, _systemPrompt, tokenBudget, _provid
             tokensAfter: Math.ceil(restored.length / 4),
         };
     }
-    // Over budget — truncate to fit budget while keeping preserved blocks
     // Calculate space taken by preserved blocks
     const preservedTokens = blocks.reduce((sum, b) => sum + Math.ceil(b.content.length / 4), 0);
     const availableTokens = Math.max(0, tokenBudget - preservedTokens);
     const availableChars = availableTokens * 4;
-    // Truncate the cleaned text to fit
-    const truncated = cleaned.length > availableChars
-        ? `${cleaned.slice(0, availableChars)}\n\n[... ${cleaned.length - availableChars} characters truncated]`
-        : cleaned;
-    const restored = restorePreservedBlocks(truncated, blocks);
+    let compressedContent = cleaned;
+    let usedLLM = false;
+    if (provider && modelId) {
+        try {
+            const runtime = resolveModelRuntime(provider, modelId);
+            const extraPrompt = customInstructions ? `\n\nUSER FOCUS/INSTRUCTIONS:\n${customInstructions}\n` : "";
+            // Guard the compaction INPUT against the model's own context window —
+            // compaction fires when history is large, which is exactly when the full
+            // serialized text can overflow the summarizer. Keep head + tail.
+            const guardedInput = capCompactionInput(cleaned, runtime.modelInfo?.contextWindow ?? 0);
+            const result = await generateText({
+                model: runtime.model,
+                system: "You are an AI context compaction agent. Your job is to heavily summarize a chat history. Keep the core outcomes, the final state, and the technical context. Remove verbose pleasantries, step-by-step thinking, and irrelevant intermediate steps. Do NOT wrap in markdown unless it's code.",
+                prompt: `The following conversation exceeds the token budget. Please summarize it concisely, maintaining the essence of what was discussed, what code was written, and what decisions were reached:${extraPrompt}\n\n${guardedInput}`,
+                ...resolveTemperatureParam(runtime, 0.1),
+            });
+            compressedContent = result.text.trim();
+            usedLLM = true;
+        }
+        catch (e) {
+            // Fall back to deterministic truncation below, but do NOT swallow the
+            // reason — a hidden compaction-LLM failure (auth, overflow, provider
+            // 400) is exactly what makes "why did compaction do nothing" undebuggable.
+            logger.error("orchestrator", "compressChat LLM summarize failed — falling back to truncation", {
+                modelId,
+                inputChars: cleaned.length,
+                message: e?.message,
+                stack: e?.stack?.split("\n").slice(0, 3),
+            });
+        }
+    }
+    if (!usedLLM) {
+        // Over budget — truncate to fit budget while keeping preserved blocks
+        compressedContent =
+            cleaned.length > availableChars
+                ? `${cleaned.slice(0, availableChars)}\n\n[... ${cleaned.length - availableChars} characters truncated]`
+                : cleaned;
+    }
+    const restored = restorePreservedBlocks(compressedContent, blocks);
     return {
         summary: restored,
         preservedBlocks: blocks,

package/dist/src/flow/compaction/extract.d.ts

@@ -5,7 +5,7 @@
  * Scans for "Decision:", "Decided:", "Fact:", "Constraint:" patterns
  * and content inside <!-- preserve --> blocks.
  */
-import type { ModelMessage } from "ai";
+import { type ModelMessage } from "ai";
 export interface ExtractedDecisions {
     decisions: string[];
     facts: string[];
@@ -14,10 +14,7 @@ export interface ExtractedDecisions {
 /**
  * Extract decisions, facts, and constraints from messages.
  *
- * Scans serialized conversation text for:
- * - Lines matching "Decision:" or "Decided:" -> decisions
- * - Lines matching "Fact:" -> facts
- * - Lines matching "Constraint:" -> constraints
- * - All content inside <!-- preserve --> blocks -> decisions (verbatim)
+ * Scans serialized conversation text for explicit markers, but if provider
+ * and modelId are given, it asks the LLM to intelligently extract them.
  */
-export declare function extractDecisions(messages: ModelMessage[]): ExtractedDecisions;
+export declare function extractDecisions(messages: ModelMessage[], provider?: unknown, modelId?: string, customInstructions?: string): Promise<ExtractedDecisions>;

package/dist/src/flow/compaction/extract.js

@@ -5,7 +5,11 @@
  * Scans for "Decision:", "Decided:", "Fact:", "Constraint:" patterns
  * and content inside <!-- preserve --> blocks.
  */
+import { generateText } from "ai";
 import { serializeConversation } from "../../orchestrator/compaction.js";
+import { resolveModelRuntime, resolveTemperatureParam, } from "../../providers/runtime.js";
+import { logger } from "../../utils/logger.js";
+import { capCompactionInput } from "./input-guard.js";
 import { extractPreservedBlocks } from "./preserve.js";
 const DECISION_RE = /(?:Decision|Decided):\s*(.+)/gi;
 const FACT_RE = /Fact:\s*(.+)/gi;
@@ -23,13 +27,10 @@ function matchAll(text, re) {
 /**
  * Extract decisions, facts, and constraints from messages.
  *
- * Scans serialized conversation text for:
- * - Lines matching "Decision:" or "Decided:" -> decisions
- * - Lines matching "Fact:" -> facts
- * - Lines matching "Constraint:" -> constraints
- * - All content inside <!-- preserve --> blocks -> decisions (verbatim)
+ * Scans serialized conversation text for explicit markers, but if provider
+ * and modelId are given, it asks the LLM to intelligently extract them.
  */
-export function extractDecisions(messages) {
+export async function extractDecisions(messages, provider, modelId, customInstructions) {
     if (messages.length === 0) {
         return { decisions: [], facts: [], constraints: [] };
     }
@@ -37,10 +38,49 @@ export function extractDecisions(messages) {
     // Extract preserved blocks as decisions
     const { blocks } = extractPreservedBlocks(serialized);
     const preservedDecisions = blocks.map((b) => b.content);
-    // Pattern-match for explicit markers
-    const decisions = [...matchAll(serialized, DECISION_RE), ...preservedDecisions];
-    const facts = matchAll(serialized, FACT_RE);
-    const constraints = matchAll(serialized, CONSTRAINT_RE);
+    const decisions = [];
+    const facts = [];
+    const constraints = [];
+    let usedLLM = false;
+    if (provider && modelId) {
+        try {
+            const runtime = resolveModelRuntime(provider, modelId);
+            const extraPrompt = customInstructions ? `\n\nUSER FOCUS/INSTRUCTIONS:\n${customInstructions}\n` : "";
+            // Guard input against the summarizer's context window (see input-guard).
+            const guardedInput = capCompactionInput(serialized, runtime.modelInfo?.contextWindow ?? 0);
+            const result = await generateText({
+                model: runtime.model,
+                system: 'You are an AI context compaction agent. Extract all core decisions, technical facts, and project constraints from this conversation. Return strict JSON with { "decisions": string[], "facts": string[], "constraints": string[] }.',
+                prompt: `Current conversation messages:\n\n${guardedInput}\n\nExtract decisions, facts, and constraints.${extraPrompt} Return strict JSON ONLY.`,
+                ...resolveTemperatureParam(runtime, 0.1),
+            });
+            const match = result.text.match(/\{[\s\S]*\}/);
+            if (match) {
+                const parsed = JSON.parse(match[0]);
+                if (Array.isArray(parsed.decisions))
+                    decisions.push(...parsed.decisions);
+                if (Array.isArray(parsed.facts))
+                    facts.push(...parsed.facts);
+                if (Array.isArray(parsed.constraints))
+                    constraints.push(...parsed.constraints);
+                usedLLM = true;
+            }
+        }
+        catch (e) {
+            // Fall back to regex extraction, but log the reason — a swallowed failure
+            // here silently degrades /compact to marker-only extraction.
+            logger.error("orchestrator", "extractDecisions LLM failed — falling back to regex", {
+                modelId,
+                message: e?.message,
+            });
+        }
+    }
+    if (!usedLLM) {
+        decisions.push(...matchAll(serialized, DECISION_RE));
+        facts.push(...matchAll(serialized, FACT_RE));
+        constraints.push(...matchAll(serialized, CONSTRAINT_RE));
+    }
+    decisions.push(...preservedDecisions);
     return { decisions, facts, constraints };
 }
 //# sourceMappingURL=extract.js.map

package/dist/src/flow/compaction/index.d.ts

@@ -6,6 +6,18 @@
  * Snapshot full chat to history/<timestamp>.md before compressing.
  */
 import type { ModelMessage } from "ai";
+/**
+ * Anti-mù for the deliberate (/compact) path — parity with the auto/tool-loop
+ * compaction which persists every elided tool output via persistArtifact.
+ *
+ * deliberateCompact rewrites the whole history into a prose summary, so without
+ * this the model loses the ability to `ee_query "tool-artifact id=<id>"` a
+ * specific tool result after /compact. We record each tool result into the
+ * in-process + disk artifact cache (the tier ee_query reads FIRST, before EE),
+ * and fire a best-effort EE extract so cross-session rehydrate also survives.
+ * Fail-open: a cache/EE hiccup never blocks the compaction.
+ */
+export declare function recordToolArtifactsForRehydrate(messages: ModelMessage[], projectPath: string): number;
 export interface CompactionResult {
     decisionsExtracted: number;
     tokensBeforeCompress: number;
@@ -21,4 +33,4 @@ export interface CompactionResult {
  * 3. Pass 2: compressChat -> compressed output
  * 4. Return metrics
  */
-export declare function deliberateCompact(flowDir: string, messages: ModelMessage[], systemPrompt: string, tokenBudget: number, provider?: unknown, modelId?: string): Promise<CompactionResult>;
+export declare function deliberateCompact(flowDir: string, messages: ModelMessage[], systemPrompt: string, tokenBudget: number, provider?: unknown, modelId?: string, customInstructions?: string): Promise<CompactionResult>;

package/dist/src/flow/compaction/index.js

@@ -7,11 +7,74 @@
  */
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
+import { recordArtifact } from "../../ee/artifact-cache.js";
+import { getDefaultEEClient } from "../../ee/intercept.js";
 import { estimateConversationTokens, serializeConversation } from "../../orchestrator/compaction.js";
 import { atomicWriteText } from "../../storage/atomic-io.js";
+import { logger } from "../../utils/logger.js";
 import { readArtifact, writeArtifact } from "../artifact-io.js";
 import { compressChat } from "./compress.js";
 import { extractDecisions } from "./extract.js";
+/**
+ * Anti-mù for the deliberate (/compact) path — parity with the auto/tool-loop
+ * compaction which persists every elided tool output via persistArtifact.
+ *
+ * deliberateCompact rewrites the whole history into a prose summary, so without
+ * this the model loses the ability to `ee_query "tool-artifact id=<id>"` a
+ * specific tool result after /compact. We record each tool result into the
+ * in-process + disk artifact cache (the tier ee_query reads FIRST, before EE),
+ * and fire a best-effort EE extract so cross-session rehydrate also survives.
+ * Fail-open: a cache/EE hiccup never blocks the compaction.
+ */
+export function recordToolArtifactsForRehydrate(messages, projectPath) {
+    let recorded = 0;
+    for (const msg of messages) {
+        if (msg.role !== "tool" || !Array.isArray(msg.content))
+            continue;
+        for (const part of msg.content) {
+            if (part?.type !== "tool-result")
+                continue;
+            const toolCallId = typeof part.toolCallId === "string" ? part.toolCallId : "";
+            if (!toolCallId)
+                continue;
+            const toolName = typeof part.toolName === "string" ? part.toolName : "";
+            // AI SDK v5 tool-result payloads live under `output` (typed) or `result`.
+            const payload = part.output ?? part.result;
+            const content = typeof payload === "string"
+                ? payload
+                : payload == null
+                    ? ""
+                    : (() => {
+                        try {
+                            return JSON.stringify(payload);
+                        }
+                        catch {
+                            return String(payload);
+                        }
+                    })();
+            if (!content)
+                continue;
+            try {
+                recordArtifact(toolCallId, toolName, content);
+                recorded++;
+                getDefaultEEClient()
+                    .extract({
+                    transcript: content.slice(0, 8000),
+                    projectPath,
+                    meta: { source: "tool-artifact", toolCallId, toolName, reason: "deliberate-compact" },
+                }, AbortSignal.timeout(700))
+                    .catch(() => { });
+            }
+            catch (err) {
+                logger.error("orchestrator", "deliberate-compact artifact record failed", {
+                    toolCallId,
+                    message: err?.message,
+                });
+            }
+        }
+    }
+    return recorded;
+}
 /**
  * Orchestrate two-pass deliberate compaction.
  *
@@ -20,9 +83,13 @@ import { extractDecisions } from "./extract.js";
  * 3. Pass 2: compressChat -> compressed output
  * 4. Return metrics
  */
-export async function deliberateCompact(flowDir, messages, systemPrompt, tokenBudget, provider, modelId) {
+export async function deliberateCompact(flowDir, messages, systemPrompt, tokenBudget, provider, modelId, customInstructions) {
+    // Anti-mù parity: persist every tool result to the artifact cache (+ EE)
+    // BEFORE we summarize the history away, so the model can still rehydrate a
+    // specific tool output via ee_query "tool-artifact id=<id>" after /compact.
+    recordToolArtifactsForRehydrate(messages, flowDir);
     // Pass 1: Extract decisions/facts/constraints
-    const extracted = extractDecisions(messages);
+    const extracted = await extractDecisions(messages, provider, modelId, customInstructions);
     const totalExtracted = extracted.decisions.length + extracted.facts.length + extracted.constraints.length;
     // Append to decisions.md
     if (totalExtracted > 0) {
@@ -55,7 +122,7 @@ export async function deliberateCompact(flowDir, messages, systemPrompt, tokenBu
     // Token estimation before
     const tokensBefore = estimateConversationTokens(systemPrompt, messages);
     // Pass 2: Compress
-    const compressed = await compressChat(messages, systemPrompt, tokenBudget, provider, modelId);
+    const compressed = await compressChat(messages, systemPrompt, tokenBudget, provider, modelId, customInstructions);
     return {
         decisionsExtracted: totalExtracted,
         tokensBeforeCompress: tokensBefore,

package/dist/src/flow/compaction/input-guard.d.ts

@@ -0,0 +1,24 @@
+/**
+ * src/flow/compaction/input-guard.ts
+ *
+ * Guard the INPUT of the deliberate-compaction LLM calls (extractDecisions +
+ * compressChat) against context-window overflow.
+ *
+ * Compaction fires precisely when a conversation has grown large — which is
+ * exactly when the full serialized history can EXCEED the compaction model's
+ * own context window. Both passes previously sent the whole serialized text as
+ * a single prompt with no bound, so on a very long session the summarizing call
+ * would fail (or the provider would hard-truncate the tail, dropping the most
+ * recent — most relevant — context) and fall back to a dumb truncation.
+ *
+ * This keeps the HEAD (task setup / early decisions) and the TAIL (most recent
+ * work) and elides the middle, so the summarizer always gets a coherent,
+ * in-window view of both ends. Pure + dependency-free.
+ */
+/**
+ * Cap `text` to a safe char budget derived from the compaction model's context
+ * window. Returns the text unchanged when it already fits (or the window is
+ * unknown and the text is under the floor). Otherwise keeps head+tail and marks
+ * the elided middle.
+ */
+export declare function capCompactionInput(text: string, contextWindowTokens: number): string;

package/dist/src/flow/compaction/input-guard.js

@@ -0,0 +1,43 @@
+/**
+ * src/flow/compaction/input-guard.ts
+ *
+ * Guard the INPUT of the deliberate-compaction LLM calls (extractDecisions +
+ * compressChat) against context-window overflow.
+ *
+ * Compaction fires precisely when a conversation has grown large — which is
+ * exactly when the full serialized history can EXCEED the compaction model's
+ * own context window. Both passes previously sent the whole serialized text as
+ * a single prompt with no bound, so on a very long session the summarizing call
+ * would fail (or the provider would hard-truncate the tail, dropping the most
+ * recent — most relevant — context) and fall back to a dumb truncation.
+ *
+ * This keeps the HEAD (task setup / early decisions) and the TAIL (most recent
+ * work) and elides the middle, so the summarizer always gets a coherent,
+ * in-window view of both ends. Pure + dependency-free.
+ */
+/** Fraction of the model window we allow the compaction INPUT to occupy. */
+const INPUT_WINDOW_FRACTION = 0.55;
+/** Chars-per-token estimate (matches the rest of the compaction code). */
+const CHARS_PER_TOKEN = 4;
+/** Absolute floor so a tiny/unknown window never collapses the input to nothing. */
+const MIN_INPUT_CHARS = 24_000;
+/**
+ * Cap `text` to a safe char budget derived from the compaction model's context
+ * window. Returns the text unchanged when it already fits (or the window is
+ * unknown and the text is under the floor). Otherwise keeps head+tail and marks
+ * the elided middle.
+ */
+export function capCompactionInput(text, contextWindowTokens) {
+    const windowBudget = contextWindowTokens > 0 ? Math.floor(contextWindowTokens * CHARS_PER_TOKEN * INPUT_WINDOW_FRACTION) : 0;
+    const budget = Math.max(MIN_INPUT_CHARS, windowBudget);
+    if (text.length <= budget)
+        return text;
+    // Split the budget between head and tail, reserving room for the marker.
+    const headChars = Math.floor(budget * 0.5);
+    const tailChars = budget - headChars;
+    const head = text.slice(0, headChars);
+    const tail = text.slice(text.length - tailChars);
+    const elided = text.length - headChars - tailChars;
+    return `${head}\n\n[... ${elided} characters of the middle of the conversation elided to fit the compaction model's context window; the head (task setup) and tail (most recent work) are preserved ...]\n\n${tail}`;
+}
+//# sourceMappingURL=input-guard.js.map

package/dist/src/flow/fold-planning.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Fold `.planning/` into `.muonroi-flow/planning/` — net-new, non-destructive
+ * consolidation migration (Sprint-2 Part A, staged per REV-3 Kill B).
+ *
+ * WHY staged / copy-only:
+ *   GSD phases are still CREATED by the external `gsd-tools.cjs` subprocess,
+ *   which writes to `.planning/` (hardcoded). Until that writer is removed
+ *   (Part B — deferred), `.planning/` must remain the live tree. So this
+ *   migration COPIES `.planning/` into the consolidated location and NEVER
+ *   deletes the original — the read layer (`paths.ts::planningRoot`) keeps
+ *   preferring `.planning/` while it exists, so there is zero desync risk.
+ *   Once Part B stops writing `.planning/`, the folded tree becomes the live
+ *   source transparently via the same read fallback.
+ *
+ * Guarantees:
+ *   - Idempotent: guarded by a `.migrated` marker (NOT by directory existence —
+ *     an empty `.muonroi-flow/planning/` must not make the fold skip forever;
+ *     see REV-2 Kill #2).
+ *   - Non-destructive: source `.planning/` is left untouched.
+ *   - Byte-preserving: every copied file is asserted equal in size to its source.
+ */
+export interface FoldResult {
+    /** True when a fold copy was performed this call. */
+    migrated: boolean;
+    /** Reason a fold was skipped (marker present / no source). */
+    skipReason?: "already-migrated" | "no-source";
+    /** Number of files copied. */
+    filesCopied: number;
+    /** Absolute path to the folded planning root. */
+    foldedRoot: string;
+}
+/**
+ * Perform the fold. Safe to call repeatedly; returns `{migrated:false}` when the
+ * marker is already present or there is no `.planning/` to fold.
+ */
+export declare function foldPlanningIntoFlow(cwd: string): Promise<FoldResult>;

package/dist/src/flow/fold-planning.js

@@ -0,0 +1,83 @@
+/**
+ * Fold `.planning/` into `.muonroi-flow/planning/` — net-new, non-destructive
+ * consolidation migration (Sprint-2 Part A, staged per REV-3 Kill B).
+ *
+ * WHY staged / copy-only:
+ *   GSD phases are still CREATED by the external `gsd-tools.cjs` subprocess,
+ *   which writes to `.planning/` (hardcoded). Until that writer is removed
+ *   (Part B — deferred), `.planning/` must remain the live tree. So this
+ *   migration COPIES `.planning/` into the consolidated location and NEVER
+ *   deletes the original — the read layer (`paths.ts::planningRoot`) keeps
+ *   preferring `.planning/` while it exists, so there is zero desync risk.
+ *   Once Part B stops writing `.planning/`, the folded tree becomes the live
+ *   source transparently via the same read fallback.
+ *
+ * Guarantees:
+ *   - Idempotent: guarded by a `.migrated` marker (NOT by directory existence —
+ *     an empty `.muonroi-flow/planning/` must not make the fold skip forever;
+ *     see REV-2 Kill #2).
+ *   - Non-destructive: source `.planning/` is left untouched.
+ *   - Byte-preserving: every copied file is asserted equal in size to its source.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+const FLOW_DIR = ".muonroi-flow";
+const PLANNING_DIR = ".planning";
+const FOLDED_SUBDIR = "planning";
+const MARKER = ".migrated";
+/** Recursively copy a directory, asserting byte-size preservation per file. */
+async function copyTreePreserving(src, dest) {
+    let copied = 0;
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    await fs.mkdir(dest, { recursive: true });
+    for (const entry of entries) {
+        const from = path.join(src, entry.name);
+        const to = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copied += await copyTreePreserving(from, to);
+        }
+        else if (entry.isFile()) {
+            await fs.copyFile(from, to);
+            const [srcStat, destStat] = await Promise.all([fs.stat(from), fs.stat(to)]);
+            if (srcStat.size !== destStat.size) {
+                throw new Error(`fold-planning: byte mismatch copying ${from} (${srcStat.size} != ${destStat.size})`);
+            }
+            copied += 1;
+        }
+        // Symlinks / other node types are intentionally skipped — .planning holds
+        // only regular files and dirs; a stray symlink is not worth following.
+    }
+    return copied;
+}
+/**
+ * Perform the fold. Safe to call repeatedly; returns `{migrated:false}` when the
+ * marker is already present or there is no `.planning/` to fold.
+ */
+export async function foldPlanningIntoFlow(cwd) {
+    const foldedRoot = path.join(cwd, FLOW_DIR, FOLDED_SUBDIR);
+    const markerPath = path.join(foldedRoot, MARKER);
+    // Marker guard — idempotent regardless of whether the folded dir is empty.
+    try {
+        await fs.access(markerPath);
+        return { migrated: false, skipReason: "already-migrated", filesCopied: 0, foldedRoot };
+    }
+    catch {
+        /* marker absent → proceed */
+    }
+    const source = path.join(cwd, PLANNING_DIR);
+    try {
+        const st = await fs.stat(source);
+        if (!st.isDirectory()) {
+            return { migrated: false, skipReason: "no-source", filesCopied: 0, foldedRoot };
+        }
+    }
+    catch {
+        return { migrated: false, skipReason: "no-source", filesCopied: 0, foldedRoot };
+    }
+    const filesCopied = await copyTreePreserving(source, foldedRoot);
+    // Stamp the marker LAST so a crash mid-copy leaves no false "migrated" flag —
+    // the next call re-copies (copyFile overwrites, byte-assert still holds).
+    await fs.writeFile(markerPath, JSON.stringify({ migratedFrom: PLANNING_DIR, filesCopied, note: "copy-only; original left in place" }, null, 2), "utf8");
+    return { migrated: true, filesCopied, foldedRoot };
+}
+//# sourceMappingURL=fold-planning.js.map

package/dist/src/flow/hierarchy.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Milestone → Phase → Run hierarchy for the Product Ideal Loop.
+ *
+ * Sprint-2 Part A (full plan, item 2 of the deferred list). Built as an ADDITIVE
+ * INDEX LAYER on top of `runs/<runId>/` (per REV-3 Kill B / REV-2 Kill #7): it
+ * groups runs under phases under milestones for navigation and cross-run memory,
+ * but does NOT reroute the numeric ROADMAP phases that phase-sync depends on. A
+ * phase here simply *references* the run IDs executed under it; the run
+ * artifacts remain the source of truth for sprint/verify state.
+ *
+ *   .muonroi-flow/milestones/<mid>/milestone.json   ← canonical record (read)
+ *   .muonroi-flow/milestones/<mid>/milestone.md     ← human-reviewable render
+ *   .muonroi-flow/milestones/<mid>/phases/<pid>/phase.json
+ *   .muonroi-flow/milestones/<mid>/phases/<pid>/phase.md
+ *
+ * The active milestone/phase pointers live in the top-level `state.md`
+ * ("Active Milestone" / "Active Phase" sections), alongside "Active Run".
+ *
+ * Records are JSON for reliable machine reads; the paired `.md` is a rendered
+ * summary only (never parsed back). Writes are atomic. Reads are tolerant: a
+ * missing/corrupt record returns null, never throws.
+ */
+export interface MilestoneRecord {
+    /** Sortable slug id, e.g. "m01-native-state". */
+    id: string;
+    /** Human title. */
+    title: string;
+    /** One-line goal / outcome the milestone delivers. */
+    goal: string;
+    /** Ordinal (1-based) — mirrors the numeric prefix in the id for stable sort. */
+    ordinal: number;
+    /** lifecycle status. */
+    status: "active" | "done" | "archived";
+    /** ISO creation timestamp. */
+    createdAt: string;
+    /** ISO last-update timestamp. */
+    updatedAt: string;
+}
+export interface PhaseRecord {
+    /** Sortable slug id, e.g. "p01-scoping". */
+    id: string;
+    /** Parent milestone id. */
+    milestoneId: string;
+    /** Human title. */
+    title: string;
+    /** One-line goal. */
+    goal: string;
+    /** Ordinal (1-based) within the milestone. */
+    ordinal: number;
+    /** lifecycle status. */
+    status: "active" | "done" | "archived";
+    /** Run IDs executed under this phase (the index link; runs stay canonical). */
+    runIds: string[];
+    /** ISO creation timestamp. */
+    createdAt: string;
+    /** ISO last-update timestamp. */
+    updatedAt: string;
+}
+export declare const MILESTONES_DIR = "milestones";
+/** List all milestones, sorted by ordinal ascending. */
+export declare function listMilestones(flowDir: string): Promise<MilestoneRecord[]>;
+export declare function loadMilestone(flowDir: string, milestoneId: string): Promise<MilestoneRecord | null>;
+/**
+ * Create a milestone. `nowIso` is injected (never Date.now here) so callers
+ * control the clock and tests stay deterministic. Ordinal is next-highest+1.
+ */
+export declare function createMilestone(flowDir: string, input: {
+    title: string;
+    goal?: string;
+}, nowIso: string): Promise<MilestoneRecord>;
+export declare function updateMilestone(flowDir: string, milestoneId: string, patch: Partial<Pick<MilestoneRecord, "title" | "goal" | "status">>, nowIso: string): Promise<MilestoneRecord | null>;
+/** List phases under a milestone, sorted by ordinal ascending. */
+export declare function listPhases(flowDir: string, milestoneId: string): Promise<PhaseRecord[]>;
+export declare function loadPhase(flowDir: string, milestoneId: string, phaseId: string): Promise<PhaseRecord | null>;
+export declare function createPhase(flowDir: string, milestoneId: string, input: {
+    title: string;
+    goal?: string;
+    runId?: string;
+}, nowIso: string): Promise<PhaseRecord>;
+export declare function updatePhase(flowDir: string, milestoneId: string, phaseId: string, patch: Partial<Pick<PhaseRecord, "title" | "goal" | "status">>, nowIso: string): Promise<PhaseRecord | null>;
+/** Link a run to a phase (idempotent — no duplicate run ids). */
+export declare function attachRunToPhase(flowDir: string, milestoneId: string, phaseId: string, runId: string, nowIso: string): Promise<PhaseRecord | null>;
+/**
+ * Find the milestone+phase a run is already indexed under, scanning every
+ * milestone. Returns null when the run is not yet linked anywhere. Used to keep
+ * scoping wiring idempotent across `/ideal resume` (the scoping stage re-runs).
+ */
+export declare function findPhaseForRun(flowDir: string, runId: string): Promise<{
+    milestoneId: string;
+    phaseId: string;
+} | null>;
+/**
+ * Idempotently place a run in the hierarchy and mark it active. First call for a
+ * run creates (or reuses the active) milestone, opens a phase for the run, links
+ * it, and points the active-milestone/active-phase pointers at it. Subsequent
+ * calls (resume) are no-ops that just re-assert the pointers.
+ *
+ * The milestone groups an idea/product; the phase is one scoped iteration under
+ * it. This is purely an INDEX over `runs/<runId>/` — it never moves or rewrites
+ * run artifacts, and the numeric ROADMAP phases that phase-sync reads are
+ * untouched.
+ */
+export declare function ensureRunScoped(flowDir: string, input: {
+    runId: string;
+    milestoneTitle: string;
+    milestoneGoal?: string;
+    phaseTitle: string;
+    phaseGoal?: string;
+}, nowIso: string): Promise<{
+    milestoneId: string;
+    phaseId: string;
+}>;
+/**
+ * One-time backfill: index any `runs/<id>/` not yet linked to a phase under a
+ * synthetic `m00-legacy` milestone (one phase per orphan run). Idempotent — runs
+ * already indexed are skipped, and re-running adds only newly-orphaned runs.
+ * Returns the number of runs newly indexed.
+ *
+ * `m00` (ordinal 0) sorts before any real milestone so legacy work stays visible
+ * but out of the way. The clock is injected for deterministic tests.
+ */
+export declare function migrateLegacyRuns(flowDir: string, nowIso: string): Promise<number>;
+export interface ActivePointer {
+    milestoneId: string | null;
+    phaseId: string | null;
+}
+/**
+ * F8 — the active milestone/phase are DERIVED from the single canonical focus,
+ * the active run, via the hierarchy index; they are NOT separately persisted.
+ *
+ * Previously `state.md` carried independent `Active Run` (set for chat-runs) and
+ * `Active Milestone`/`Active Phase` (set by `ensureRunScoped` for product-runs)
+ * pointers that routinely drifted out of sync — `/ideal` never updated `Active
+ * Run`, so it pointed at a stale skeleton run while the milestone/phase pointed
+ * at the product run. Council decision (5/5): collapse to one truth. Whatever run
+ * is active, its phase (and that phase's milestone) is the active one; a
+ * chat/skeleton run that was never indexed resolves to nulls.
+ */
+export declare function getActivePointer(flowDir: string): Promise<ActivePointer>;
+/**
+ * Blank the legacy `Active Milestone`/`Active Phase` sections if an old
+ * `state.md` still carries them, so a stale value can never be mistaken for the
+ * (now derived) truth. One-time, idempotent; no-op when the sections are absent
+ * or already empty. Legacy files are otherwise read-as-junk — never migrated.
+ */
+export declare function clearLegacyActivePointerSections(flowDir: string): Promise<void>;