plan-assistant 1.4.5 → 1.6.0-alpha.1

package/dist/cli/commands/stop.js

@@ -1,16 +1,12 @@
 import { dirname } from "node:path";
-import { resolveSession } from "../session-resolver.js";
-import { stopServer, checkHealth, DEFAULT_BASE_PORT, MAX_PORT, } from "../server-client.js";
-import { outputJson, outputError } from "../output.js";
+import { requireSession } from "../session-resolver.js";
+import { stopServer, checkHealth, fetchWithTimeout, clearLock, DEFAULT_BASE_PORT, MAX_PORT, } from "../server-client.js";
+import { outputJson } from "../output.js";
 export async function stop(args) {
     const target = args.positional[0];
     if (target) {
         // Stop server for a specific session
-        const session = resolveSession(target);
-        if (!session) {
-            outputError(`Session not found: ${target}`, "NOT_FOUND");
-            process.exit(1);
-        }
+        const session = requireSession(target);
         const parentDir = dirname(session.sessionDir);
         const stopped = await stopServer(parentDir);
         if (stopped) {
@@ -30,13 +26,8 @@ export async function stop(args) {
         const health = await checkHealth(port);
         if (health) {
             try {
-                const controller = new AbortController();
-                const timeout = setTimeout(() => controller.abort(), 2000);
-                await fetch(`http://localhost:${port}/api/shutdown`, {
-                    method: "POST",
-                    signal: controller.signal,
-                });
-                clearTimeout(timeout);
+                await fetchWithTimeout(`http://localhost:${port}/api/shutdown`, { method: "POST" }, 2000);
+                clearLock(health.sessionDir);
                 results.push({ port, sessionDir: health.sessionDir });
                 stopped++;
             }
@@ -44,6 +35,7 @@ export async function stop(args) {
                 // Try SIGTERM
                 try {
                     process.kill(health.pid, "SIGTERM");
+                    clearLock(health.sessionDir);
                     results.push({ port, sessionDir: health.sessionDir });
                     stopped++;
                 }

package/dist/cli/errors.js

@@ -0,0 +1,23 @@
+/**
+ * Thrown by CLI commands to signal an error exit.
+ * Caught by main() which writes message to stderr and calls process.exit(exitCode).
+ */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "CliError";
+    }
+}
+/**
+ * Thrown by CLI commands to signal intentional non-error exit with a specific code.
+ * For example, `status` exits with code 3 for "needs-work" — not an error, just a signal.
+ * Caught by main() which calls process.exit(exitCode) without printing an error.
+ */
+export class CliExitCode {
+    exitCode;
+    constructor(exitCode) {
+        this.exitCode = exitCode;
+    }
+}

package/dist/cli/export-html.js

@@ -1,4 +1,4 @@
-function escapeHtml(text) {
+export function escapeHtml(text) {
     return text
         .replace(/&/g, "&")
         .replace(/</g, "&lt;")

package/dist/cli/index.js

@@ -130,8 +130,8 @@ Optional top-level sections (all H2):
   ## Testing Strategy
   ## References`);
 }
-export async function main(args) {
-    const parsed = parseArgs(args);
+import { CliError, CliExitCode } from "./errors.js";
+async function dispatch(parsed) {
     switch (parsed.command) {
         case "review": {
             const { review } = await import("./commands/review.js");
@@ -176,8 +176,24 @@ export async function main(args) {
             }
             return;
         default:
-            console.error(`Unknown command: ${parsed.command}`);
-            usage();
-            process.exit(1);
+            throw new CliError(`Unknown command: ${parsed.command}`, 1);
+    }
+}
+export async function main(args) {
+    const parsed = parseArgs(args);
+    try {
+        await dispatch(parsed);
+    }
+    catch (err) {
+        if (err instanceof CliExitCode) {
+            process.exit(err.exitCode);
+        }
+        if (err instanceof CliError) {
+            console.error(err.message);
+            process.exit(err.exitCode);
+        }
+        // Unexpected error
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
     }
 }

package/dist/cli/markdown-parser.js

@@ -260,7 +260,7 @@ export function tryMatchPhaseHeading(heading, autoNumber) {
     return null;
 }
 /** Known top-level section patterns that should NOT be treated as phases */
-const KNOWN_SECTION_PATTERNS = [
+export const KNOWN_SECTION_PATTERNS = [
     /^Overview$/i,
     /^Current\s+State/i,
     /What\s+We.*NOT\s+Doing/i,
@@ -274,147 +274,132 @@ const KNOWN_SECTION_PATTERNS = [
 ];
 const CHANGES_HEADING_PATTERN = /^(?:Changes\s+Required|Changes|File\s+Changes|Modifications):?$/i;
 const SUCCESS_CRITERIA_HEADING_PATTERN = /^(?:Success\s+Criteria|Criteria|Verification):?$/i;
+/**
+ * Detect whether a section is a phase heading.
+ * Handles canonical (## Phase N:), unnumbered H2s with phase-like content,
+ * and H3 phase headings (with warning).
+ * Returns null if the section is not a phase.
+ */
+function detectPhaseHeading(section, allSections, sectionIdx, autoNumber, ctx) {
+    if (section.level !== 2 && section.level !== 3)
+        return null;
+    const phaseMatch = tryMatchPhaseHeading(section.heading, autoNumber);
+    // Check for unnumbered H2s that look like phases
+    if (!phaseMatch && section.level === 2) {
+        if (KNOWN_SECTION_PATTERNS.some((p) => p.test(section.heading)))
+            return null;
+        const subSections = collectSectionsUntilLevel(allSections, sectionIdx, 2);
+        const hasChanges = subSections.some((s) => CHANGES_HEADING_PATTERN.test(s.heading));
+        const hasCriteria = subSections.some((s) => SUCCESS_CRITERIA_HEADING_PATTERN.test(s.heading) ||
+            /Automated\s+Verification/i.test(s.heading) ||
+            /Manual\s+Verification/i.test(s.heading));
+        const hasNumberedChanges = subSections.some((s) => (s.level === 4 || s.level === 3) && /^\d+\.\s/.test(s.heading));
+        if (hasChanges || hasCriteria || hasNumberedChanges) {
+            ctx.warn(`Unnumbered heading "${section.heading}" treated as Phase ${autoNumber}`);
+            return { number: autoNumber, name: section.heading, variant: "unnumbered" };
+        }
+        return null;
+    }
+    return phaseMatch;
+}
+// ── Phase content extraction ─────────────────────────────────────
+function extractPhaseChanges(subSections, allSections, phaseNumber, ctx) {
+    const changesSection = subSections.find((s) => CHANGES_HEADING_PATTERN.test(s.heading));
+    if (!changesSection)
+        return [];
+    if (!/^Changes\s+Required/i.test(changesSection.heading)) {
+        ctx.warn(`Phase ${phaseNumber}: "${changesSection.heading}" used instead of "Changes Required" — accepted`);
+    }
+    const changesIdx = allSections.indexOf(changesSection);
+    if (changesIdx < 0)
+        return [];
+    // Strategy 1: Heading-based changes (#### N. Name)
+    const changeSubs = collectSectionsUntilLevel(allSections, changesIdx, changesSection.level);
+    const changes = parseChangesFromHeadings(changeSubs, ctx);
+    // Strategy 2: List-based changes if no heading-based changes found
+    if (changes.length === 0) {
+        return parseChangesFromList(changesSection.tokens, ctx);
+    }
+    return changes;
+}
+function extractPhaseCriteria(subSections, allSections) {
+    const criteriaSection = subSections.find((s) => SUCCESS_CRITERIA_HEADING_PATTERN.test(s.heading));
+    const criteriaIdx = criteriaSection
+        ? allSections.indexOf(criteriaSection)
+        : -1;
+    const criteriaSubs = criteriaIdx >= 0 && criteriaSection
+        ? collectSectionsUntilLevel(allSections, criteriaIdx, criteriaSection.level)
+        : [];
+    const automatedSection = criteriaSubs.find((s) => /Automated\s+Verification/i.test(s.heading)) ??
+        subSections.find((s) => /Automated\s+Verification/i.test(s.heading));
+    const manualSection = criteriaSubs.find((s) => /Manual\s+Verification/i.test(s.heading)) ??
+        subSections.find((s) => /Manual\s+Verification/i.test(s.heading));
+    const automated = automatedSection
+        ? parseCriteria(automatedSection.tokens, "automated")
+        : [];
+    const manual = manualSection
+        ? parseCriteria(manualSection.tokens, "manual")
+        : [];
+    // If criteria section exists but no automated/manual sub-sections,
+    // treat all list items as manual criteria
+    if (criteriaSection &&
+        automated.length === 0 &&
+        manual.length === 0 &&
+        criteriaSubs.length === 0) {
+        manual.push(...parseCriteria(criteriaSection.tokens, "manual"));
+    }
+    return { automated, manual };
+}
+function extractPhaseContentAndSubItems(phaseSection, subSections, phaseId, phaseNumber) {
+    const recognizedPattern = /^(Overview|Changes\s+Required|Changes|File\s+Changes|Modifications|Automated\s+Verification|Manual\s+Verification|Success\s+Criteria|Criteria|Verification):?$/i;
+    const subItemPattern = /^(\d+)([a-z])\.\s+(.+)/i;
+    const contentParts = [];
+    const subItems = [];
+    const directText = tokensToMarkdown(phaseSection.tokens);
+    if (directText)
+        contentParts.push(directText);
+    for (const sub of subSections) {
+        if (recognizedPattern.test(sub.heading))
+            continue;
+        const siMatch = sub.heading.match(subItemPattern);
+        if (siMatch && parseInt(siMatch[1], 10) === phaseNumber) {
+            const letter = siMatch[2].toLowerCase();
+            subItems.push({
+                id: `${phaseId}-${letter}`,
+                letter,
+                name: siMatch[3].trim(),
+                content: tokensToMarkdown(sub.tokens),
+            });
+        }
+        else {
+            const subBody = tokensToMarkdown(sub.tokens);
+            contentParts.push(`### ${sub.heading}\n\n${subBody}`);
+        }
+    }
+    const content = contentParts.join("\n\n").trim() || undefined;
+    return { content, subItems };
+}
+// ── Main phase parser ────────────────────────────────────────────
 export function parsePhases(allSections, ctx) {
     const phases = [];
     let autoNumber = 1;
     for (let i = 0; i < allSections.length; i++) {
         const section = allSections[i];
-        // Try matching at level 2 (canonical) or level 3 (with warning)
-        if (section.level !== 2 && section.level !== 3)
+        const detected = detectPhaseHeading(section, allSections, i, autoNumber, ctx);
+        if (!detected)
             continue;
-        const phaseMatch = tryMatchPhaseHeading(section.heading, autoNumber);
-        // Also check for unnumbered H2s that look like phases
-        let isUnnumberedPhase = false;
-        if (!phaseMatch && section.level === 2) {
-            // Skip known section patterns
-            if (KNOWN_SECTION_PATTERNS.some((p) => p.test(section.heading)))
-                continue;
-            // Check if this H2 has subsections that look like phase content
-            // (has Changes Required, or Success Criteria, or numbered sub-headings)
-            const subSections = collectSectionsUntilLevel(allSections, i, 2);
-            const hasChanges = subSections.some((s) => CHANGES_HEADING_PATTERN.test(s.heading));
-            const hasCriteria = subSections.some((s) => SUCCESS_CRITERIA_HEADING_PATTERN.test(s.heading) ||
-                /Automated\s+Verification/i.test(s.heading) ||
-                /Manual\s+Verification/i.test(s.heading));
-            const hasNumberedChanges = subSections.some((s) => (s.level === 4 || s.level === 3) && /^\d+\.\s/.test(s.heading));
-            if (hasChanges || hasCriteria || hasNumberedChanges) {
-                isUnnumberedPhase = true;
-            }
-            else {
-                continue;
-            }
+        if (detected.variant !== "canonical" && detected.variant !== "unnumbered") {
+            ctx.warn(`Phase "${section.heading}" uses non-canonical format (${detected.variant}) — accepted`);
         }
-        if (!phaseMatch && !isUnnumberedPhase) {
-            // H3 with phase-like heading
-            if (section.level === 3) {
-                const h3Match = tryMatchPhaseHeading(section.heading, autoNumber);
-                if (h3Match) {
-                    ctx.warn(`Phase "${section.heading}" uses h3 instead of h2 — accepted but non-canonical`);
-                    // Fall through with h3Match
-                }
-                else {
-                    continue;
-                }
-            }
-            else {
-                continue;
-            }
-        }
-        const match = phaseMatch ?? {
-            number: autoNumber,
-            name: section.heading,
-            variant: "unnumbered",
-        };
-        if (match.variant !== "canonical" && match.variant !== "unnumbered") {
-            ctx.warn(`Phase "${section.heading}" uses non-canonical format (${match.variant}) — accepted`);
-        }
-        if (match.variant === "unnumbered") {
-            ctx.warn(`Unnumbered heading "${section.heading}" treated as Phase ${match.number}`);
-        }
-        const number = match.number;
-        const name = match.name;
+        const { number, name } = detected;
         const id = `phase-${number}`;
         autoNumber = number + 1;
         const subSections = collectSectionsUntilLevel(allSections, i, section.level);
         const overviewSection = subSections.find((s) => /^Overview$/i.test(s.heading));
-        const overview = overviewSection
-            ? tokensToMarkdown(overviewSection.tokens)
-            : "";
-        // Flexible changes section heading
-        const changesSection = subSections.find((s) => CHANGES_HEADING_PATTERN.test(s.heading));
-        if (changesSection &&
-            !/^Changes\s+Required/i.test(changesSection.heading)) {
-            ctx.warn(`Phase ${number}: "${changesSection.heading}" used instead of "Changes Required" — accepted`);
-        }
-        const changesIdx = changesSection
-            ? allSections.indexOf(changesSection)
-            : -1;
-        let changes = [];
-        if (changesIdx >= 0 && changesSection) {
-            // Strategy 1: Heading-based changes (#### N. Name)
-            const changeSubs = collectSectionsUntilLevel(allSections, changesIdx, changesSection.level);
-            changes = parseChangesFromHeadings(changeSubs, ctx);
-            // Strategy 2: List-based changes if no heading-based changes found
-            if (changes.length === 0) {
-                changes = parseChangesFromList(changesSection.tokens, ctx);
-            }
-        }
-        // Flexible success criteria heading
-        const criteriaSection = subSections.find((s) => SUCCESS_CRITERIA_HEADING_PATTERN.test(s.heading));
-        const criteriaIdx = criteriaSection
-            ? allSections.indexOf(criteriaSection)
-            : -1;
-        const criteriaSubs = criteriaIdx >= 0 && criteriaSection
-            ? collectSectionsUntilLevel(allSections, criteriaIdx, criteriaSection.level)
-            : [];
-        const automatedSection = criteriaSubs.find((s) => /Automated\s+Verification/i.test(s.heading)) ??
-            subSections.find((s) => /Automated\s+Verification/i.test(s.heading));
-        const manualSection = criteriaSubs.find((s) => /Manual\s+Verification/i.test(s.heading)) ??
-            subSections.find((s) => /Manual\s+Verification/i.test(s.heading));
-        const automated = automatedSection
-            ? parseCriteria(automatedSection.tokens, "automated")
-            : [];
-        const manual = manualSection
-            ? parseCriteria(manualSection.tokens, "manual")
-            : [];
-        // If criteria section exists but no automated/manual sub-sections,
-        // treat all list items as manual criteria
-        if (criteriaSection &&
-            automated.length === 0 &&
-            manual.length === 0 &&
-            criteriaSubs.length === 0) {
-            manual.push(...parseCriteria(criteriaSection.tokens, "manual"));
-        }
-        // Build content from direct tokens + unrecognized subsections
-        const recognizedPattern = /^(Overview|Changes\s+Required|Changes|File\s+Changes|Modifications|Automated\s+Verification|Manual\s+Verification|Success\s+Criteria|Criteria|Verification):?$/i;
-        const subItemPattern = /^(\d+)([a-z])\.\s+(.+)/i;
-        const contentParts = [];
-        const subItems = [];
-        // Direct tokens between phase heading and first sub-heading
-        const phaseSection = allSections[i];
-        const directText = tokensToMarkdown(phaseSection.tokens);
-        if (directText)
-            contentParts.push(directText);
-        // Unrecognized subsections — check for sub-items first
-        for (const sub of subSections) {
-            if (recognizedPattern.test(sub.heading))
-                continue;
-            const siMatch = sub.heading.match(subItemPattern);
-            if (siMatch && parseInt(siMatch[1], 10) === number) {
-                const letter = siMatch[2].toLowerCase();
-                subItems.push({
-                    id: `${id}-${letter}`,
-                    letter,
-                    name: siMatch[3].trim(),
-                    content: tokensToMarkdown(sub.tokens),
-                });
-            }
-            else {
-                const subBody = tokensToMarkdown(sub.tokens);
-                contentParts.push(`### ${sub.heading}\n\n${subBody}`);
-            }
-        }
-        const content = contentParts.join("\n\n").trim() || undefined;
+        const overview = overviewSection ? tokensToMarkdown(overviewSection.tokens) : "";
+        const changes = extractPhaseChanges(subSections, allSections, number, ctx);
+        const successCriteria = extractPhaseCriteria(subSections, allSections);
+        const { content, subItems } = extractPhaseContentAndSubItems(allSections[i], subSections, id, number);
         phases.push({
             id,
             number,
@@ -423,7 +408,7 @@ export function parsePhases(allSections, ctx) {
             content,
             subItems,
             changes,
-            successCriteria: { automated, manual },
+            successCriteria,
         });
     }
     return phases;

package/dist/cli/markdown-to-plan.js

@@ -2,7 +2,7 @@ import { Lexer } from "marked";
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
 import { generatePhaseFlowDiagram } from "./mermaid-gen.js";
-import { createParseContext, splitIntoSections, tokensToMarkdown, findSection, collectSectionsUntilLevel, parseKeyDiscoveries, parseScopeExclusions, parsePhases, parseTestingStrategy, parseReferences, tryMatchPhaseHeading, } from "./markdown-parser.js";
+import { createParseContext, splitIntoSections, tokensToMarkdown, findSection, collectSectionsUntilLevel, parseKeyDiscoveries, parseScopeExclusions, parsePhases, parseTestingStrategy, parseReferences, } from "./markdown-parser.js";
 export function sessionIdFromPath(absolutePath) {
     return createHash("sha256").update(absolutePath).digest("hex").slice(0, 8);
 }
@@ -77,54 +77,6 @@ export function parseMarkdownToPlan(markdown, markdownPath, projectDir, version
     // References
     const refsSection = findSection(sections, /^References$/i, 2);
     const references = refsSection ? parseReferences(refsSection.tokens) : [];
-    // Collect additional (unrecognized) H2 sections
-    const knownH2Indices = new Set();
-    const knownPatterns = [
-        /^Overview$/i,
-        /^Current\s+State/i,
-        /What\s+We.*NOT\s+Doing/i,
-        /Implementation\s+Approach/i,
-        /Testing\s+Strategy/i,
-        /^References$/i,
-    ];
-    for (let i = 0; i < sections.length; i++) {
-        if (sections[i].level === 1) {
-            knownH2Indices.add(i);
-            continue;
-        }
-        if (sections[i].level !== 2)
-            continue;
-        // Check if it's a known section
-        if (knownPatterns.some((p) => p.test(sections[i].heading))) {
-            knownH2Indices.add(i);
-            continue;
-        }
-        // Check if it was parsed as a phase
-        if (phases.some((p) => p.name === sections[i].heading ||
-            tryMatchPhaseHeading(sections[i].heading, 0))) {
-            knownH2Indices.add(i);
-            continue;
-        }
-    }
-    const additionalSections = [];
-    for (let i = 0; i < sections.length; i++) {
-        if (sections[i].level !== 2 || knownH2Indices.has(i))
-            continue;
-        // Double-check it's not a parsed phase
-        const isPhase = phases.some((p) => p.name === sections[i].heading ||
-            sections[i].heading.match(new RegExp(`Phase\\s+${p.number}`, "i")));
-        if (isPhase)
-            continue;
-        const subs = collectSectionsUntilLevel(sections, i, 2);
-        let content = tokensToMarkdown(sections[i].tokens);
-        for (const sub of subs) {
-            content += `\n\n${"#".repeat(sub.level)} ${sub.heading}\n\n${tokensToMarkdown(sub.tokens)}`;
-        }
-        additionalSections.push({
-            heading: sections[i].heading,
-            content: content.trim(),
-        });
-    }
     const now = new Date().toISOString();
     const plan = {
         schemaVersion: 1,
@@ -147,7 +99,6 @@ export function parseMarkdownToPlan(markdown, markdownPath, projectDir, version
         diagrams,
         testingStrategy,
         references,
-        ...(additionalSections.length > 0 ? { additionalSections } : {}),
     };
     return { plan, warnings: ctx.warnings };
 }

package/dist/cli/review-session.js

@@ -0,0 +1,130 @@
+/**
+ * Session setup for the review command.
+ * Extracted from review.ts to reduce god-function complexity.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { watch } from "chokidar";
+import { parseMarkdownToPlan, sessionIdFromPath, } from "./markdown-to-plan.js";
+import { CliError } from "./errors.js";
+/**
+ * Parse a markdown file, create/update the session directory, and write session files.
+ * Returns all the context needed by the rest of the review command.
+ */
+export function prepareSession(markdownFile) {
+    const absolutePath = resolve(markdownFile);
+    if (!existsSync(absolutePath)) {
+        throw new CliError(`File not found: ${absolutePath}`);
+    }
+    const sessionDir = join(dirname(absolutePath), ".plan-sessions");
+    const sessionId = sessionIdFromPath(absolutePath);
+    const sessionPath = join(sessionDir, sessionId);
+    const projectDir = process.cwd();
+    // Determine version
+    let version = 1;
+    const existingPlanPath = join(sessionPath, "plan.json");
+    if (existsSync(existingPlanPath)) {
+        try {
+            const existing = JSON.parse(readFileSync(existingPlanPath, "utf-8"));
+            version = (existing.meta?.version ?? 0) + 1;
+        }
+        catch {
+            // ignore, start at 1
+        }
+    }
+    // Parse markdown
+    const markdown = readFileSync(absolutePath, "utf-8");
+    const { plan, warnings } = parseMarkdownToPlan(markdown, absolutePath, projectDir, version);
+    // Display parser warnings
+    for (const warning of warnings) {
+        console.error(`Warning: ${warning}`);
+    }
+    if (plan.phases.length === 0) {
+        console.error(`
+⚠ No phases found — plan will appear empty in the browser.
+
+Use the correct format for phases:
+
+  ## Phase 1: Phase Name
+
+  ### Changes Required:
+
+  #### 1. Component Name
+  **File**: \`path/to/file.ext\`
+  Description of what to change.
+
+  ### Success Criteria:
+  - [ ] \`npm test\`
+
+Accepted phase keywords: "Phase N:", "Step N:", "Task N:" (H2 headings)
+Run \`npx plan-assistant init --output <file>\` to generate a correctly-formatted template.
+`);
+    }
+    // Write session files
+    mkdirSync(sessionPath, { recursive: true });
+    mkdirSync(join(sessionPath, "versions"), { recursive: true });
+    // Clear stale feedback from previous review cycle
+    const oldFeedbackPath = join(sessionPath, "feedback.json");
+    if (existsSync(oldFeedbackPath)) {
+        try {
+            unlinkSync(oldFeedbackPath);
+        }
+        catch {
+            // ignore
+        }
+    }
+    const meta = {
+        id: sessionId,
+        planTitle: plan.meta.title,
+        markdownPath: absolutePath,
+        projectDir,
+        status: "active",
+        planVersion: version,
+        createdAt: plan.meta.createdAt,
+        updatedAt: plan.meta.updatedAt,
+    };
+    writeFileSync(join(sessionPath, "meta.json"), JSON.stringify(meta, null, 2));
+    writeFileSync(join(sessionPath, "plan.json"), JSON.stringify(plan, null, 2));
+    writeFileSync(join(sessionPath, "versions", `v${version}.json`), JSON.stringify(plan, null, 2));
+    return {
+        sessionId,
+        sessionPath,
+        sessionDir,
+        plan,
+        version,
+        absolutePath,
+        projectDir,
+        existingPlanPath,
+    };
+}
+/**
+ * Create a chokidar watcher on the markdown file that re-parses and
+ * updates session files on change.
+ */
+export function watchMarkdownFile(absolutePath, sessionPath, projectDir, existingPlanPath, ensureServer) {
+    const mdWatcher = watch(absolutePath, {
+        awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 },
+    });
+    mdWatcher.on("change", async () => {
+        try {
+            await ensureServer();
+            const updated = readFileSync(absolutePath, "utf-8");
+            const existingPlan = JSON.parse(readFileSync(existingPlanPath, "utf-8"));
+            const newVersion = (existingPlan.meta?.version ?? 0) + 1;
+            const { plan: newPlan, warnings: newWarnings } = parseMarkdownToPlan(updated, absolutePath, projectDir, newVersion);
+            for (const warning of newWarnings) {
+                console.error(`Warning: ${warning}`);
+            }
+            if (newPlan.phases.length === 0) {
+                console.error(`⚠ No phases found after reload — check format. Run \`npx plan-assistant init\` for a template.`);
+            }
+            writeFileSync(join(sessionPath, "plan.json"), JSON.stringify(newPlan, null, 2));
+            writeFileSync(join(sessionPath, "versions", `v${newVersion}.json`), JSON.stringify(newPlan, null, 2));
+            console.error(`[${new Date().toLocaleTimeString()}] Plan updated (v${newVersion})`);
+        }
+        catch (err) {
+            console.error(`Error re-parsing markdown: ${err}`);
+        }
+    });
+    return mdWatcher;
+}