muonroi-cli 1.8.4 → 1.9.0

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

@@ -7,11 +7,75 @@
  */
 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";
+import { stageProgress } from "./progress.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 +84,35 @@ 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, modelId, customInstructions, onProgress) {
+    // Callers reach this through @ts-nocheck UI code, so an argument-order drift
+    // is invisible to tsc. It is NOT invisible at runtime: a non-string modelId
+    // makes resolveModelRuntime throw, compressChat catches it, and /compact
+    // silently degrades to truncation — which is how commit e2100fb7 shipped a
+    // broken /compact. Fail loudly instead of summarizing nothing.
+    if (modelId !== undefined && typeof modelId !== "string") {
+        throw new TypeError(`deliberateCompact: modelId must be a model id string, got ${typeof modelId}. ` +
+            `Check the argument order at the call site.`);
+    }
+    const report = (stage, fraction) => {
+        if (!onProgress)
+            return;
+        try {
+            onProgress(stageProgress(stage, fraction));
+        }
+        catch (err) {
+            // A broken progress sink must never fail the compaction it is reporting.
+            logger.error("orchestrator", "compact progress callback threw", { stage, message: err?.message });
+        }
+    };
+    report("artifacts");
+    // 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);
+    report("extract");
+    const extracted = await extractDecisions(messages, modelId, customInstructions);
     const totalExtracted = extracted.decisions.length + extracted.facts.length + extracted.constraints.length;
     // Append to decisions.md
     if (totalExtracted > 0) {
@@ -43,6 +133,7 @@ export async function deliberateCompact(flowDir, messages, systemPrompt, tokenBu
         await writeArtifact(flowDir, "decisions.md", existing, ["Decisions", "Facts", "Constraints"]);
     }
     // Snapshot full chat to history/
+    report("snapshot");
     const historyDir = path.join(flowDir, "history");
     await fs.mkdir(historyDir, { recursive: true });
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
@@ -55,7 +146,9 @@ 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);
+    report("compress");
+    const compressed = await compressChat(messages, systemPrompt, tokenBudget, modelId, customInstructions, (f) => report("compress", f));
+    report("done");
     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/compaction/progress.d.ts

@@ -0,0 +1,35 @@
+/**
+ * src/flow/compaction/progress.ts
+ *
+ * Progress model for deliberate (/compact) compaction.
+ *
+ * A compaction is a fixed pipeline of stages (see index.ts), so the percentage
+ * is stage-weighted rather than invented: each stage owns a span of the bar and
+ * only advances when that stage really advances. The two LLM passes dominate the
+ * wall-clock, which is why they own most of the span; the compress pass streams,
+ * so it reports a genuine within-stage fraction instead of freezing.
+ *
+ * Weights are ordered spans covering 0..100 with no gaps — asserted in tests so
+ * a new stage can't silently make the bar jump or stall.
+ */
+export type CompactStage = "artifacts" | "extract" | "snapshot" | "compress" | "done";
+export interface CompactProgress {
+    stage: CompactStage;
+    /** 0..100, monotonic across the run. */
+    percent: number;
+    /** Human-readable current step, e.g. "Compressing history…". */
+    label: string;
+}
+export type CompactProgressFn = (progress: CompactProgress) => void;
+interface StageSpan {
+    from: number;
+    to: number;
+    label: string;
+}
+export declare const COMPACT_STAGE_SPANS: Record<CompactStage, StageSpan>;
+/**
+ * Percent for a stage at `fraction` (0..1) of its own work. Callers that cannot
+ * measure within-stage progress pass 0 and land on the stage's start.
+ */
+export declare function stageProgress(stage: CompactStage, fraction?: number): CompactProgress;
+export {};

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

@@ -0,0 +1,35 @@
+/**
+ * src/flow/compaction/progress.ts
+ *
+ * Progress model for deliberate (/compact) compaction.
+ *
+ * A compaction is a fixed pipeline of stages (see index.ts), so the percentage
+ * is stage-weighted rather than invented: each stage owns a span of the bar and
+ * only advances when that stage really advances. The two LLM passes dominate the
+ * wall-clock, which is why they own most of the span; the compress pass streams,
+ * so it reports a genuine within-stage fraction instead of freezing.
+ *
+ * Weights are ordered spans covering 0..100 with no gaps — asserted in tests so
+ * a new stage can't silently make the bar jump or stall.
+ */
+export const COMPACT_STAGE_SPANS = {
+    artifacts: { from: 0, to: 5, label: "Preserving tool artifacts…" },
+    extract: { from: 5, to: 40, label: "Extracting decisions…" },
+    snapshot: { from: 40, to: 50, label: "Snapshotting history…" },
+    compress: { from: 50, to: 100, label: "Compressing history…" },
+    done: { from: 100, to: 100, label: "Compacted" },
+};
+/**
+ * Percent for a stage at `fraction` (0..1) of its own work. Callers that cannot
+ * measure within-stage progress pass 0 and land on the stage's start.
+ */
+export function stageProgress(stage, fraction = 0) {
+    const span = COMPACT_STAGE_SPANS[stage];
+    const clamped = Math.max(0, Math.min(1, Number.isFinite(fraction) ? fraction : 0));
+    return {
+        stage,
+        percent: Math.round(span.from + (span.to - span.from) * clamped),
+        label: span.label,
+    };
+}
+//# sourceMappingURL=progress.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>;