/**
 * plan-html — Global pi extension.
 *
 * Workflow: /plan <prompt>  →  model writes a structured plan-json block
 *           → extension renders it as a commentable HTML page via the
 *           plan-design-system, opens it in the default browser, and
 *           keeps tools locked to read-only.
 *
 *           /iterate          →  loads .pi/plans/feedback.md, asks the
 *           model to revise; new version is rendered & opened.
 *
 *           /approve          →  unlocks edit/write, asks the model
 *           to execute the latest plan; [DONE:n] markers tick a footer
 *           progress widget.
 *
 *           /plan-off         →  cancel planning, restore full tools.
 *
 * Model-agnostic: relies only on the assistant emitting a fenced
 * ```plan-json``` block. Works on Claude, OpenAI, Gemini, etc.
 *
 * Design system: ~/.pi/agent/plan-design-system/
 */

import { execFile } from "node:child_process";
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { createServer, type Server } from "node:http";
import { platform } from "node:os";
import { dirname, join, relative, resolve as resolvePath } from "node:path";
import { fileURLToPath } from "node:url";
import { randomBytes } from "node:crypto";

import type { AgentMessage } from "@earendil-works/pi-agent-core";
import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
import { Key } from "@earendil-works/pi-tui";

// ============================================================
// Constants
// ============================================================

// Design system ships inside this package so the extension is self-contained.
// Resolves to <package-root>/design-system regardless of where npm installs us.
const DESIGN_SYSTEM_DIR = join(dirname(fileURLToPath(import.meta.url)), "design-system");
const PLAN_MODE_TOOLS = ["read", "bash", "grep", "find", "ls", "questionnaire"];
const NORMAL_MODE_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
const FEEDBACK_FILENAME = "feedback.md";
const STATE_ENTRY = "plan-html-state";

type Phase = "idle" | "planning" | "executing";

type MockupFrame = "window" | "browser" | "phone" | "none";
type MockupViewport = "desktop" | "mobile" | "auto";

interface MockupObject {
	frame?: MockupFrame;
	title?: string;
	viewport?: MockupViewport;
	html: string;
	css?: string;
}

interface PlanStep {
	key: string;
	title: string;
	body?: string;
	files?: string[];
	callouts?: Array<{ tone?: string; title?: string; body: string }>;
	code?: Array<{ lang?: string; label?: string; source: string }>;
	mockup?: string | MockupObject;
	diagram?: string;
	verification?: string;
}

interface PlanDoc {
	title: string;
	context: string;
	header_chips?: Array<{ label: string; tone?: string }>;
	steps: PlanStep[];
	risks?: string[];
	open_questions?: string[];
}

interface SessionState {
	phase: Phase;
	planBase: string | null;           // e.g. "plan-2026-05-20T14-23-15"
	version: number;                   // 1, 2, …
	executionTodos: Array<{ step: number; text: string; completed: boolean }>;
}

// ============================================================
// Safe bash patterns (subset of bundled plan-mode example)
// ============================================================

const DESTRUCTIVE_PATTERNS: RegExp[] = [
	/\brm\b/i, /\brmdir\b/i, /\bmv\b/i, /\bcp\b/i, /\bmkdir\b/i, /\btouch\b/i,
	/\bchmod\b/i, /\bchown\b/i, /\btee\b/i, /\btruncate\b/i, /\bdd\b/i,
	/(^|[^<])>(?!>)/, />>/,
	/\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
	/\byarn\s+(add|remove|install|publish)/i,
	/\bpnpm\s+(add|remove|install|publish)/i,
	/\bpip\s+(install|uninstall)/i,
	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|stash|cherry-pick|revert|tag|init|clone)/i,
	/\bsudo\b/i, /\bsu\b/i, /\bkill\b/i, /\bpkill\b/i, /\bkillall\b/i,
	/\breboot\b/i, /\bshutdown\b/i,
];

const SAFE_PATTERNS: RegExp[] = [
	/^\s*cat\b/, /^\s*head\b/, /^\s*tail\b/, /^\s*less\b/, /^\s*more\b/,
	/^\s*grep\b/, /^\s*find\b/, /^\s*ls\b/, /^\s*pwd\b/, /^\s*echo\b/,
	/^\s*printf\b/, /^\s*wc\b/, /^\s*sort\b/, /^\s*uniq\b/, /^\s*diff\b/,
	/^\s*file\b/, /^\s*stat\b/, /^\s*du\b/, /^\s*df\b/, /^\s*tree\b/,
	/^\s*which\b/, /^\s*whereis\b/, /^\s*type\b/, /^\s*env\b/, /^\s*printenv\b/,
	/^\s*uname\b/, /^\s*whoami\b/, /^\s*id\b/, /^\s*date\b/, /^\s*uptime\b/,
	/^\s*ps\b/, /^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get|ls-)/i,
	/^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
	/^\s*node\s+--version/i, /^\s*python3?\s+--version/i,
	/^\s*jq\b/, /^\s*sed\s+-n/i, /^\s*awk\b/, /^\s*rg\b/, /^\s*fd\b/, /^\s*bat\b/,
];

function isSafeBash(command: string): boolean {
	const destructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(command));
	const safe = SAFE_PATTERNS.some((p) => p.test(command));
	return !destructive && safe;
}

// ============================================================
// String / HTML helpers
// ============================================================

function escHtml(s: string): string {
	return s
		.replace(/&/g, "&amp;")
		.replace(/</g, "&lt;")
		.replace(/>/g, "&gt;")
		.replace(/"/g, "&quot;")
		.replace(/'/g, "&#39;");
}

function escAttr(s: string): string {
	return escHtml(s);
}

function slugify(s: string): string {
	return s
		.toLowerCase()
		.replace(/[^a-z0-9]+/g, "-")
		.replace(/^-+|-+$/g, "")
		.slice(0, 48) || "section";
}

function timestampSlug(d = new Date()): string {
	const pad = (n: number) => String(n).padStart(2, "0");
	return (
		`${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T` +
		`${pad(d.getHours())}-${pad(d.getMinutes())}-${pad(d.getSeconds())}`
	);
}

function isAssistant(m: AgentMessage): m is AssistantMessage {
	return m.role === "assistant" && Array.isArray(m.content);
}

function assistantText(m: AssistantMessage): string {
	return m.content
		.filter((b): b is TextContent => b.type === "text")
		.map((b) => b.text)
		.join("\n");
}

// ============================================================
// Plan-JSON extraction
// ============================================================

const PLAN_FENCE_RE = /```(?:plan-json|json)\s*\n([\s\S]*?)\n```/i;

function extractPlanJson(text: string): { plan: PlanDoc | null; rawProse: string } {
	const m = text.match(PLAN_FENCE_RE);
	if (!m) return { plan: null, rawProse: text };

	const before = text.slice(0, m.index ?? 0).trim();
	try {
		const data = JSON.parse(m[1]) as PlanDoc;
		// Backfill required fields & step keys
		if (typeof data.title !== "string") data.title = "Plan";
		if (typeof data.context !== "string") data.context = "";
		if (!Array.isArray(data.steps)) data.steps = [];
		data.steps.forEach((s, i) => {
			if (typeof s.title !== "string" || !s.title) s.title = `Step ${i + 1}`;
			if (typeof s.key !== "string" || !s.key) s.key = slugify(s.title);
		});
		// Ensure unique keys
		const seen = new Set<string>();
		data.steps.forEach((s) => {
			let k = s.key;
			let n = 2;
			while (seen.has(k)) k = `${s.key}-${n++}`;
			s.key = k;
			seen.add(k);
		});
		return { plan: data, rawProse: before };
	} catch {
		return { plan: null, rawProse: text };
	}
}

// ============================================================
// Tiny markdown renderer
// Supports: headings, paragraphs, lists, blockquotes, fenced code,
// tables, inline code/strong/em/links, line breaks.
// ============================================================

function renderMarkdown(src: string): string {
	if (!src) return "";
	const lines = src.replace(/\r\n/g, "\n").split("\n");
	const out: string[] = [];
	let i = 0;

	function inline(s: string): string {
		// Escape first, then re-introduce inline markup.
		let t = escHtml(s);
		// Code (must come before * / _)
		t = t.replace(/`([^`]+)`/g, "<code>$1</code>");
		// Bold
		t = t.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
		t = t.replace(/__([^_]+)__/g, "<strong>$1</strong>");
		// Italic (basic)
		t = t.replace(/(^|[\s(])\*([^*\n]+)\*/g, "$1<em>$2</em>");
		t = t.replace(/(^|[\s(])_([^_\n]+)_/g, "$1<em>$2</em>");
		// Links
		t = t.replace(
			/\[([^\]]+)\]\(([^)\s]+)\)/g,
			(_m, label, url) =>
				`<a href="${escAttr(String(url))}" target="_blank" rel="noopener">${label}</a>`,
		);
		return t;
	}

	while (i < lines.length) {
		const line = lines[i];

		if (/^\s*$/.test(line)) { i++; continue; }

		// Headings
		const h = line.match(/^(#{1,6})\s+(.*)$/);
		if (h) {
			const level = Math.min(h[1].length, 4) + 2; // h1→h3, h2→h4, …
			out.push(`<h${level}>${inline(h[2])}</h${level}>`);
			i++; continue;
		}

		// Fenced code
		const fence = line.match(/^```(\w+)?\s*$/);
		if (fence) {
			const lang = fence[1] || "";
			const code: string[] = [];
			i++;
			while (i < lines.length && !/^```\s*$/.test(lines[i])) {
				code.push(lines[i]); i++;
			}
			i++; // consume closing fence
			out.push(renderCodeBlock({ lang, source: code.join("\n") }));
			continue;
		}

		// Tables (very simple: pipe-delimited with header sep row)
		if (/^\s*\|.*\|\s*$/.test(line) && /^\s*\|?\s*[-:]+\s*\|/.test(lines[i + 1] || "")) {
			const headers = line.trim().replace(/^\||\|$/g, "").split("|").map((c) => c.trim());
			i += 2;
			const rows: string[][] = [];
			while (i < lines.length && /^\s*\|.*\|\s*$/.test(lines[i])) {
				rows.push(
					lines[i].trim().replace(/^\||\|$/g, "").split("|").map((c) => c.trim()),
				);
				i++;
			}
			out.push("<table><thead><tr>");
			headers.forEach((h) => out.push(`<th>${inline(h)}</th>`));
			out.push("</tr></thead><tbody>");
			rows.forEach((r) => {
				out.push("<tr>");
				r.forEach((c) => out.push(`<td>${inline(c)}</td>`));
				out.push("</tr>");
			});
			out.push("</tbody></table>");
			continue;
		}

		// Blockquote
		if (/^\s*>/.test(line)) {
			const buf: string[] = [];
			while (i < lines.length && /^\s*>/.test(lines[i])) {
				buf.push(lines[i].replace(/^\s*>\s?/, ""));
				i++;
			}
			out.push(`<blockquote>${inline(buf.join(" "))}</blockquote>`);
			continue;
		}

		// Unordered list
		if (/^\s*[-*+]\s+/.test(line)) {
			const items: string[] = [];
			while (i < lines.length && /^\s*[-*+]\s+/.test(lines[i])) {
				items.push(lines[i].replace(/^\s*[-*+]\s+/, ""));
				i++;
			}
			out.push("<ul>");
			items.forEach((t) => out.push(`<li>${inline(t)}</li>`));
			out.push("</ul>");
			continue;
		}

		// Ordered list
		if (/^\s*\d+[.)]\s+/.test(line)) {
			const items: string[] = [];
			while (i < lines.length && /^\s*\d+[.)]\s+/.test(lines[i])) {
				items.push(lines[i].replace(/^\s*\d+[.)]\s+/, ""));
				i++;
			}
			out.push("<ol>");
			items.forEach((t) => out.push(`<li>${inline(t)}</li>`));
			out.push("</ol>");
			continue;
		}

		// Paragraph (collapse subsequent non-empty, non-block lines)
		const buf: string[] = [line];
		i++;
		while (
			i < lines.length &&
			!/^\s*$/.test(lines[i]) &&
			!/^(#{1,6}\s|```|\s*[-*+]\s|\s*\d+[.)]\s|\s*>|\s*\|)/.test(lines[i])
		) {
			buf.push(lines[i]); i++;
		}
		out.push(`<p>${inline(buf.join(" "))}</p>`);
	}

	return out.join("\n");
}

// ============================================================
// Component renderers
// ============================================================

function renderChip(label: string, tone?: string): string {
	const toneClass = tone ? ` pds-chip--${escAttr(tone)}` : "";
	return `<span class="pds-chip${toneClass}">${escHtml(label)}</span>`;
}

function renderHeaderChips(chips?: Array<{ label: string; tone?: string }>): string {
	if (!chips || !chips.length) return "";
	return chips.map((c) => renderChip(c.label, c.tone)).join("");
}

function renderFiles(files?: string[]): string {
	if (!files || !files.length) return "";
	return `<div class="plan-files">${files
		.map((f) => `<span class="pds-chip">${escHtml(f)}</span>`)
		.join("")}</div>`;
}

const CALLOUT_ICONS: Record<string, string> = {
	note: "i",
	warn: "!",
	risk: "!",
	danger: "!",
	ok: "✓",
	success: "✓",
};

function renderCallout(c: { tone?: string; title?: string; body: string }): string {
	const tone = (c.tone || "note").toLowerCase();
	const icon = CALLOUT_ICONS[tone] || "•";
	const title = c.title ? `<strong>${escHtml(c.title)}</strong> ` : "";
	return `<aside class="plan-callout plan-callout--${escAttr(tone)}">
  <span class="plan-callout__icon" aria-hidden="true">${icon}</span>
  <div class="plan-callout__body">${title}${renderMarkdown(c.body)}</div>
</aside>`;
}

function renderCodeBlock(c: { lang?: string; label?: string; source: string }): string {
	const lang = (c.lang || "").toLowerCase();
	const langClass = lang ? ` class="language-${escAttr(lang)}"` : "";
	const label = c.label ? escHtml(c.label) : (lang || "code");
	return `<div class="plan-code">
  <div class="plan-code__head"><span>${label}</span><button type="button" class="plan-code__copy">copy</button></div>
  <pre${langClass}><code${langClass}>${escHtml(c.source)}</code></pre>
</div>`;
}

// --- Mockup preset cache ---
let MOCKUP_PRESET_CACHE: string | null = null;
function loadMockupPreset(): string {
	if (MOCKUP_PRESET_CACHE != null) return MOCKUP_PRESET_CACHE;
	const p = join(DESIGN_SYSTEM_DIR, "vendor", "mockup-preset.css");
	try {
		MOCKUP_PRESET_CACHE = readFileSync(p, "utf8");
	} catch {
		MOCKUP_PRESET_CACHE = "";
	}
	return MOCKUP_PRESET_CACHE;
}

// Encode for a double-quoted srcdoc attribute. Leaves `<`/`>` alone so
// the iframe parses the contained HTML normally.
function escSrcdoc(s: string): string {
	return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
}

function stripScripts(html: string): string {
	return html.replace(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, "");
}

let MOCK_ID_COUNTER = 0;
function nextMockId(): string {
	MOCK_ID_COUNTER += 1;
	return `mk${Date.now().toString(36)}${MOCK_ID_COUNTER.toString(36)}`;
}

const MOCK_RESIZE_SCRIPT = `
(function(){
  var id = ${JSON.stringify("__MOCK_ID__")};
  function h(){ return document.documentElement.scrollHeight || document.body.scrollHeight || 0; }
  function post(){ try { parent.postMessage({type:"mock-height", id:id, h:h()}, "*"); } catch(e){} }
  window.addEventListener("load", post);
  window.addEventListener("resize", post);
  if (window.ResizeObserver) {
    try { new ResizeObserver(post).observe(document.body); } catch(e){}
  }
  setTimeout(post, 50);
  setTimeout(post, 250);
  setTimeout(post, 800);
  window.addEventListener("message", function(e){
    if (e && e.data && e.data.type === "mock-remeasure") post();
  });
})();`;

function buildMockSrcdoc(mock: MockupObject, mockId: string): string {
	const preset = loadMockupPreset();
	const userCss = (mock.css || "").trim();
	const userHtml = stripScripts(mock.html || "");
	const script = MOCK_RESIZE_SCRIPT.replace("__MOCK_ID__", mockId);
	return `<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: https:; font-src data:; connect-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors *;">
<style>${preset}</style>
${userCss ? `<style>${userCss}</style>` : ""}
</head>
<body>
${userHtml}
<script>${script}</script>
</body>
</html>`;
}

function renderMockupString(m: string): string {
	return `<div class="plan-mockup">
  <div class="plan-mockup__label">Mockup</div>
  <pre>${escHtml(m)}</pre>
</div>`;
}

function renderMockupObject(m: MockupObject): string {
	const frame: MockupFrame = (m.frame as MockupFrame) || "window";
	const validFrames: MockupFrame[] = ["window", "browser", "phone", "none"];
	const safeFrame = validFrames.includes(frame) ? frame : "window";
	const requested: MockupViewport = (m.viewport as MockupViewport) || "auto";
	const viewport: MockupViewport =
		requested === "auto" ? (safeFrame === "phone" ? "mobile" : "desktop") : requested;
	const title = m.title || "";
	const mockId = nextMockId();
	const srcdoc = buildMockSrcdoc(m, mockId);

	let chrome: string;
	if (safeFrame === "browser") {
		chrome = `<div class="mock-frame__chrome">
      <span class="mock-frame__dots"><span></span><span></span><span></span></span>
      <span class="mock-frame__urlbar">${escHtml(title || "preview")}</span>
    </div>`;
	} else if (safeFrame === "window") {
		chrome = `<div class="mock-frame__chrome">
      <span class="mock-frame__dots"><span></span><span></span><span></span></span>
      <span class="mock-frame__title">${escHtml(title)}</span>
      <span class="mock-frame__dots" aria-hidden="true" style="visibility:hidden"><span></span><span></span><span></span></span>
    </div>`;
	} else if (safeFrame === "phone") {
		chrome = `<div class="mock-frame__chrome"></div>`;
	} else {
		chrome = "";
	}

	return `<figure class="mock-frame mock-frame--${escAttr(safeFrame)}" data-viewport="${escAttr(viewport)}">
  <div class="mock-frame__label">Mockup${title ? ` · ${escHtml(title)}` : ""}</div>
  <div class="mock-frame__shell">
    ${chrome}
    <iframe
      class="mock-frame__iframe"
      data-mock-id="${escAttr(mockId)}"
      sandbox="allow-scripts"
      loading="lazy"
      title="${escAttr(title || "mockup")}"
      srcdoc="${escSrcdoc(srcdoc)}"
    ></iframe>
  </div>
</figure>`;
}

function renderMockup(m?: string | MockupObject): string {
	if (!m) return "";
	if (typeof m === "string") return renderMockupString(m);
	if (typeof m === "object" && typeof (m as MockupObject).html === "string") {
		return renderMockupObject(m as MockupObject);
	}
	return "";
}

function renderDiagram(d?: string): string {
	if (!d) return "";
	return `<div class="plan-diagram"><pre class="mermaid">${escHtml(d)}</pre></div>`;
}

function renderStep(step: PlanStep, index: number): string {
	const num = String(index + 1).padStart(2, "0");
	const bodyHtml = renderMarkdown(step.body || "");
	const files = renderFiles(step.files);
	const callouts = (step.callouts || []).map(renderCallout).join("\n");
	const code = (step.code || []).map(renderCodeBlock).join("\n");
	const mockup = renderMockup(step.mockup);
	const diagram = renderDiagram(step.diagram);
	const verification = step.verification
		? renderCallout({ tone: "ok", title: "Verify", body: step.verification })
		: "";

	return `<section class="plan-section" id="step-${escAttr(step.key)}" data-step-key="${escAttr(step.key)}">
  <div class="plan-section__head">
    <span class="plan-section__num">${num}</span>
    <h2 class="plan-section__title">${escHtml(step.title)}</h2>
    <span class="plan-section__actions">
      <button type="button" class="comment-btn" data-count="0" title="Add a comment">💬 comment</button>
    </span>
  </div>
  <div class="plan-section__body">
    ${files}
    ${bodyHtml}
    ${callouts}
    ${code}
    ${mockup}
    ${diagram}
    ${verification}
  </div>
</section>`;
}

function renderPanelItems(items: string[], keyPrefix: string, markerFn: (i: number) => string): string {
	return items
		.map((text, i) => {
			const key = `${keyPrefix}-${i}`;
			return `<li class="plan-panel__item" data-step-key="${escAttr(key)}">
  <div class="plan-panel__item-head">
    <span class="plan-panel__item-marker">${markerFn(i)}</span>
    <div class="plan-panel__item-text">${renderMarkdown(text)}</div>
    <button type="button" class="comment-btn" data-count="0" title="Add a comment / answer">💬 comment</button>
  </div>
</li>`;
		})
		.join("\n");
}

function renderRisks(risks?: string[]): string {
	if (!risks || !risks.length) return "";
	return `<aside class="plan-panel plan-panel--risks">
  <h2 class="plan-panel__title">Risks</h2>
  <ul class="plan-panel__list">
${renderPanelItems(risks, "risk", () => "!")}
  </ul>
</aside>`;
}

function renderOpenQuestions(qs?: string[]): string {
	if (!qs || !qs.length) return "";
	return `<aside class="plan-panel plan-panel--questions">
  <h2 class="plan-panel__title">Open Questions</h2>
  <ul class="plan-panel__list">
${renderPanelItems(qs, "question", () => "?")}
  </ul>
</aside>`;
}

function renderToc(plan: PlanDoc): string {
	return plan.steps
		.map((s, i) => {
			const n = String(i + 1).padStart(2, "0");
			return `<li class="plan-toc__item" data-step-key="${escAttr(s.key)}">
        <a href="#step-${escAttr(s.key)}">
          <span>${n}. ${escHtml(s.title)}</span>
          <span class="count" data-count="0"></span>
        </a>
      </li>`;
		})
		.join("\n");
}

// ============================================================
// Top-level rendering
// ============================================================

function renderPlanHtml(plan: PlanDoc, options: {
	planId: string;
	version: number;
	assetBase: string;
	cwd: string;
	feedbackUrl?: string;
	feedbackToken?: string;
	previousPlan?: PlanDoc | null;
	previousVersion?: number;
}): string {
	const tplPath = join(DESIGN_SYSTEM_DIR, "template.html");
	if (!existsSync(tplPath)) {
		throw new Error(
			`plan-html: design system template not found at ${tplPath}. ` +
				"Did the design-system files get installed?",
		);
	}
	const template = readFileSync(tplPath, "utf8");

	const body = plan.steps.map(renderStep).join("\n\n");
	const hasPrev = !!options.previousPlan;
	const meta = {
		planId: options.planId,
		version: options.version,
		title: plan.title,
		steps: plan.steps.map((s) => ({ key: s.key, title: s.title })),
		risks: (plan.risks || []).map((text, i) => ({ key: `risk-${i}`, text })),
		questions: (plan.open_questions || []).map((text, i) => ({ key: `question-${i}`, text })),
		cwd: options.cwd,
		feedbackUrl: options.feedbackUrl || "",
		feedbackToken: options.feedbackToken || "",
		hasPrevious: hasPrev,
		previousVersion: hasPrev
			? (options.previousVersion ?? Math.max(1, options.version - 1))
			: null,
	};

	return template
		.replace(/\{\{TITLE\}\}/g, escHtml(plan.title))
		.replace(/\{\{VERSION\}\}/g, String(options.version))
		.replace(/\{\{GENERATED_AT\}\}/g, new Date().toLocaleString())
		.replace(/\{\{CONTEXT\}\}/g, escHtml(plan.context))
		.replace(/\{\{HEADER_CHIPS\}\}/g, renderHeaderChips(plan.header_chips))
		.replace(/\{\{TOC\}\}/g, renderToc(plan))
		.replace(/\{\{BODY\}\}/g, body)
		.replace(/\{\{RISKS\}\}/g, renderRisks(plan.risks))
		.replace(/\{\{OPEN_QUESTIONS\}\}/g, renderOpenQuestions(plan.open_questions))
		.replace(/\{\{PLAN_JSON\}\}/g, JSON.stringify(plan).replace(/</g, "\\u003c"))
		.replace(/\{\{PLAN_META\}\}/g, JSON.stringify(meta).replace(/</g, "\\u003c"))
		.replace(/\{\{PREVIOUS_PLAN\}\}/g, hasPrev
			? JSON.stringify(options.previousPlan).replace(/</g, "\\u003c")
			: "null")
		.replace(/\{\{ASSET_BASE\}\}/g, options.assetBase);
}

// ============================================================
// Plan storage & open
// ============================================================

function plansDir(cwd: string): string {
	return join(cwd, ".pi", "plans");
}

function ensurePlansDir(cwd: string): string {
	const dir = plansDir(cwd);
	mkdirSync(dir, { recursive: true });
	return dir;
}

function planFiles(cwd: string, base: string, version: number): { json: string; html: string } {
	const dir = ensurePlansDir(cwd);
	return {
		json: join(dir, `${base}-v${version}.json`),
		html: join(dir, `${base}-v${version}.html`),
	};
}

function assetBaseFor(htmlPath: string): string {
	const rel = relative(dirname(htmlPath), DESIGN_SYSTEM_DIR);
	// HTML wants forward slashes even on Windows.
	return (rel || ".").split(/[\\/]/).join("/");
}

function openInBrowser(target: string): void {
	const plat = platform();
	let cmd: string;
	let args: string[];
	if (plat === "darwin") { cmd = "open"; args = [target]; }
	else if (plat === "win32") { cmd = "cmd"; args = ["/c", "start", "", target]; }
	else { cmd = "xdg-open"; args = [target]; }
	try {
		execFile(cmd, args, () => { /* ignore */ });
	} catch { /* ignore */ }
}

// Returns the HTTP URL for a plan id when the server is up, else the file path.
function planViewUrl(planBase: string, version: number, fallbackPath: string): string {
	if (feedbackInfo && feedbackInfo.planBase) {
		return `${feedbackInfo.planBase}${encodeURIComponent(`${planBase}-v${version}`)}`;
	}
	return fallbackPath;
}

// ============================================================
// Local feedback server
// One per pi process. Accepts POSTs from rendered plan HTML pages
// and writes feedback.md to <registered-cwd>/.pi/plans/feedback.md.
// Bound to 127.0.0.1 on a random port; token-protected.
// ============================================================

const FEEDBACK_MAX_BODY = 1_000_000; // 1MB

interface FeedbackServerInfo {
	port: number;
	token: string;
	url: string;       // POST /feedback
	planBase: string;  // http://127.0.0.1:PORT/plan/<id>
}

let feedbackServer: Server | null = null;
let feedbackInfo: FeedbackServerInfo | null = null;
let feedbackStarting: Promise<FeedbackServerInfo | null> | null = null;
const allowedCwds = new Set<string>();

// MIME map for /asset/* responses.
const ASSET_MIME: Record<string, string> = {
	".html": "text/html; charset=utf-8",
	".css": "text/css; charset=utf-8",
	".js": "application/javascript; charset=utf-8",
	".json": "application/json; charset=utf-8",
	".svg": "image/svg+xml",
	".png": "image/png",
	".jpg": "image/jpeg",
	".jpeg": "image/jpeg",
	".gif": "image/gif",
	".woff": "font/woff",
	".woff2": "font/woff2",
};

function mimeFor(p: string): string {
	const dot = p.lastIndexOf(".");
	if (dot < 0) return "application/octet-stream";
	return ASSET_MIME[p.slice(dot).toLowerCase()] || "application/octet-stream";
}

// Look up a plan HTML file across registered cwds.
function findPlanHtml(planId: string): string | null {
	if (!/^[A-Za-z0-9._-]+$/.test(planId)) return null; // sanitize
	for (const cwd of allowedCwds) {
		const candidate = join(cwd, ".pi", "plans", `${planId}.html`);
		if (existsSync(candidate)) return candidate;
	}
	return null;
}

function registerCwd(cwd: string): string {
	const abs = resolvePath(cwd);
	allowedCwds.add(abs);
	return abs;
}

async function ensureFeedbackServer(): Promise<FeedbackServerInfo | null> {
	if (feedbackInfo) return feedbackInfo;
	if (feedbackStarting) return feedbackStarting;
	feedbackStarting = new Promise((resolveP) => {
		const token = randomBytes(16).toString("hex");
		const srv = createServer((req, res) => {
			res.setHeader("Access-Control-Allow-Origin", "*");
			res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
			res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
			res.setHeader("Cache-Control", "no-store");
			if (req.method === "OPTIONS") { res.writeHead(204); return res.end(); }

			const url = req.url || "";

			// --- GET /plan/<id> — serve a rendered plan from its disk file ---
			if (req.method === "GET" && url.startsWith("/plan/")) {
				const id = decodeURIComponent(url.slice("/plan/".length).replace(/\?.*$/, ""));
				const filepath = findPlanHtml(id);
				if (!filepath) {
					res.writeHead(404, { "Content-Type": "text/plain" });
					return res.end("plan not found");
				}
				try {
					const body = readFileSync(filepath);
					res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
					return res.end(body);
				} catch (err) {
					res.writeHead(500, { "Content-Type": "text/plain" });
					return res.end(String((err as Error).message || err));
				}
			}

			// --- GET /asset/<path-under-design-system> ---
			if (req.method === "GET" && url.startsWith("/asset/")) {
				const rel = decodeURIComponent(url.slice("/asset/".length).replace(/\?.*$/, ""));
				// Strict: only allow [A-Za-z0-9._/-] components, no traversal.
				if (rel.split("/").some((seg) => seg === ".." || seg === "" || !/^[A-Za-z0-9._-]+$/.test(seg))) {
					res.writeHead(400, { "Content-Type": "text/plain" });
					return res.end("bad asset path");
				}
				const fullPath = resolvePath(join(DESIGN_SYSTEM_DIR, rel));
				if (!fullPath.startsWith(resolvePath(DESIGN_SYSTEM_DIR))) {
					res.writeHead(400, { "Content-Type": "text/plain" });
					return res.end("path escape");
				}
				if (!existsSync(fullPath)) {
					res.writeHead(404, { "Content-Type": "text/plain" });
					return res.end("asset not found");
				}
				try {
					const body = readFileSync(fullPath);
					res.writeHead(200, { "Content-Type": mimeFor(fullPath), "Cache-Control": "public, max-age=600" });
					return res.end(body);
				} catch (err) {
					res.writeHead(500, { "Content-Type": "text/plain" });
					return res.end(String((err as Error).message || err));
				}
			}

			if (req.method !== "POST" || url !== "/feedback") {
				res.writeHead(404, { "Content-Type": "application/json" });
				return res.end(JSON.stringify({ ok: false, error: "not found" }));
			}
			const auth = req.headers["authorization"];
			const provided = typeof auth === "string" && auth.startsWith("Bearer ")
				? auth.slice(7)
				: "";
			if (provided !== token) {
				res.writeHead(401, { "Content-Type": "application/json" });
				return res.end(JSON.stringify({ ok: false, error: "unauthorized" }));
			}
			let body = "";
			let aborted = false;
			req.on("data", (chunk) => {
				body += String(chunk);
				if (body.length > FEEDBACK_MAX_BODY) {
					aborted = true;
					res.writeHead(413, { "Content-Type": "application/json" });
					res.end(JSON.stringify({ ok: false, error: "body too large" }));
					req.destroy();
				}
			});
			req.on("end", () => {
				if (aborted) return;
				let parsed: { cwd?: unknown; markdown?: unknown };
				try { parsed = JSON.parse(body); }
				catch {
					res.writeHead(400, { "Content-Type": "application/json" });
					return res.end(JSON.stringify({ ok: false, error: "bad json" }));
				}
				const cwd = typeof parsed.cwd === "string" ? parsed.cwd : "";
				const markdown = typeof parsed.markdown === "string" ? parsed.markdown : "";
				if (!cwd || !markdown) {
					res.writeHead(400, { "Content-Type": "application/json" });
					return res.end(JSON.stringify({ ok: false, error: "missing cwd or markdown" }));
				}
				const absCwd = resolvePath(cwd);
				if (!allowedCwds.has(absCwd)) {
					res.writeHead(403, { "Content-Type": "application/json" });
					return res.end(JSON.stringify({ ok: false, error: "cwd not registered" }));
				}
				try {
					const plansDirPath = join(absCwd, ".pi", "plans");
					mkdirSync(plansDirPath, { recursive: true });
					const target = join(plansDirPath, FEEDBACK_FILENAME);
					// Final containment check: target must remain inside absCwd
					if (!resolvePath(target).startsWith(absCwd)) {
						res.writeHead(400, { "Content-Type": "application/json" });
						return res.end(JSON.stringify({ ok: false, error: "path escape" }));
					}
					writeFileSync(target, markdown);
					res.writeHead(200, { "Content-Type": "application/json" });
					res.end(JSON.stringify({ ok: true, path: target }));
				} catch (err) {
					res.writeHead(500, { "Content-Type": "application/json" });
					res.end(JSON.stringify({ ok: false, error: String((err as Error).message || err) }));
				}
			});
		});
		srv.on("error", () => {
			feedbackInfo = null;
			feedbackServer = null;
			resolveP(null);
		});
		srv.listen(0, "127.0.0.1", () => {
			const addr = srv.address();
			if (addr && typeof addr === "object" && typeof addr.port === "number") {
				feedbackServer = srv;
				feedbackInfo = {
					port: addr.port,
					token,
					url: `http://127.0.0.1:${addr.port}/feedback`,
					planBase: `http://127.0.0.1:${addr.port}/plan/`,
				};
				resolveP(feedbackInfo);
			} else {
				try { srv.close(); } catch { /* ignore */ }
				resolveP(null);
			}
		});
	});
	const info = await feedbackStarting;
	feedbackStarting = null;
	return info;
}

function stopFeedbackServer(): void {
	if (feedbackServer) {
		try { feedbackServer.close(); } catch { /* ignore */ }
		feedbackServer = null;
		feedbackInfo = null;
	}
}

// ============================================================
// Planning system prompt (injected each turn while in planning phase)
// ============================================================

function planningPrompt(designSystemPath: string): string {
	return `[PLAN MODE — HTML PLAN]
You are in plan mode. Write-tools are disabled (no edit, no write). Bash is restricted to a read-only allowlist. Use read, grep, find, ls to explore.

Your task: produce a plan that will be rendered into a beautiful, commentable HTML page using the plan-design-system at ${designSystemPath}. Read its README.md to understand the available components.

OUTPUT REQUIREMENTS:
- End your reply with a single fenced block:
  \`\`\`plan-json
  { ...strict JSON matching the schema below... }
  \`\`\`
- Strict JSON only — no comments, no trailing commas, no unquoted keys.
- Prose BEFORE the fenced block is fine and visible to the user; nothing after the closing fence.
- Use components meaningfully — mockups for UI changes, diagrams for structural changes, code snippets only for illustrative micro-examples, files chips for every file you will create/edit/delete.

SCHEMA:
{
  "title":         string,                  // short, specific
  "context":       string,                  // 1–3 sentences: why, what changes, what success looks like
  "header_chips":  [{ "label": string, "tone": "info|ok|warn|bad|accent" }],   // optional, max 4
  "steps": [
    {
      "key":         string,                // short kebab-case slug, stable across iterations
      "title":       string,
      "body":        string,                // markdown
      "files":       [string],              // files to create/edit/delete (not read-only)
      "callouts":    [{ "tone": "note|warn|risk|ok", "title": string?, "body": string }],
      "code":        [{ "lang": string, "label": string?, "source": string }],
      "mockup":      {                      // HTML mockup, rendered inside a sandboxed iframe with chrome
                         "frame":    "window" | "browser" | "phone" | "none",   // default: "window"
                         "title":    string?,                                    // shown inside window/browser chrome
                         "viewport": "desktop" | "mobile" | "auto",              // default: "auto" (phone→mobile, else desktop)
                         "html":     string,                                     // body HTML — lean on the mockup preset's defaults
                         "css":      string?                                     // optional, scoped to this mockup's iframe
                       },
      "diagram":     string,                // mermaid source (flowchart, sequence, ...)
      "verification":string                 // how to validate this step works
    }
  ],
  "risks":          [string],
  "open_questions": [string]
}

GUIDANCE:
- Prefer many small steps with stable \`key\`s over one big step — comments are anchored per step, and stable keys let user comments persist across /iterate cycles.
- Don't invent generic risks. Skip the field if no concrete risk applies.
- Don't include files only being read.
- For UI changes: include a mockup using the OBJECT form (\`{frame, title, html, ...}\`). Write real HTML and lean on the iframe's built-in preset stylesheet — plain \`<header>\`, \`<main>\`, \`<section>\`, \`<button>\`, \`<input>\`, \`<nav>\`, \`<table>\`, \`.row\`, \`.col\`, \`.pill\`, \`button[data-variant="primary"]\`, etc. already look polished. Only add a \`css\` field when the preset isn't enough. Prefer minimal markup over verbose Tailwind/utility classes. ASCII string mockups still render for legacy plans but should not be used for new ones unless you're actually designing a CLI/text UI.
- For structural changes: include a diagram. For tricky business logic: include a small code snippet showing the key idea.
`;
}

function feedbackPrompt(feedbackMd: string, currentVersion: number): string {
	return `The user reviewed plan v${currentVersion} and left the following feedback. Revise the plan to address every point, then re-emit the FULL revised plan in the same plan-json schema (keep step \`key\`s stable when the step still exists, so the user's other comments remain anchored).

--- FEEDBACK ---
${feedbackMd.trim()}
--- END FEEDBACK ---
`;
}

function executionPrompt(planSummary: string): string {
	return `[EXECUTING PLAN — full tool access restored]

Execute the following plan in order. After completing each step, include a \`[DONE:n]\` tag (where n is the step number) on its own line so progress can be tracked.

${planSummary}
`;
}

function summarizeForExecution(plan: PlanDoc): string {
	return plan.steps
		.map((s, i) => `${i + 1}. ${s.title}${s.body ? `\n   ${s.body.split("\n")[0]}` : ""}`)
		.join("\n");
}

// ============================================================
// Extension entrypoint
// ============================================================

export default function planHtmlExtension(pi: ExtensionAPI): void {
	const state: SessionState = {
		phase: "idle",
		planBase: null,
		version: 0,
		executionTodos: [],
	};
	let lastPlan: PlanDoc | null = null;

	// --- helpers bound to closure ---

	function persist(): void {
		pi.appendEntry(STATE_ENTRY, { ...state });
	}

	function updateStatus(ctx: ExtensionContext): void {
		if (!ctx.hasUI) return;
		if (state.phase === "planning") {
			ctx.ui.setStatus(
				"plan-html",
				ctx.ui.theme.fg("warning", `📝 plan v${state.version || "?"}`),
			);
		} else if (state.phase === "executing" && state.executionTodos.length) {
			const done = state.executionTodos.filter((t) => t.completed).length;
			ctx.ui.setStatus(
				"plan-html",
				ctx.ui.theme.fg("accent", `▶ executing ${done}/${state.executionTodos.length}`),
			);
		} else {
			ctx.ui.setStatus("plan-html", undefined);
		}

		if (state.phase === "executing" && state.executionTodos.length) {
			const lines = state.executionTodos.map((t) =>
				t.completed
					? ctx.ui.theme.fg("success", "☑ ") +
					  ctx.ui.theme.fg("muted", ctx.ui.theme.strikethrough(t.text))
					: `${ctx.ui.theme.fg("muted", "☐ ")}${t.text}`,
			);
			ctx.ui.setWidget("plan-html-todos", lines);
		} else {
			ctx.ui.setWidget("plan-html-todos", undefined);
		}
	}

	function enterPlanning(ctx: ExtensionContext): void {
		state.phase = "planning";
		if (!state.planBase) {
			state.planBase = `plan-${timestampSlug()}`;
			state.version = 0;
		}
		pi.setActiveTools(PLAN_MODE_TOOLS);
		updateStatus(ctx);
		persist();
	}

	function exitPlanning(ctx: ExtensionContext): void {
		state.phase = "idle";
		state.planBase = null;
		state.version = 0;
		state.executionTodos = [];
		lastPlan = null;
		pi.setActiveTools(NORMAL_MODE_TOOLS);
		updateStatus(ctx);
		persist();
	}

	function enterExecution(ctx: ExtensionContext): void {
		state.phase = "executing";
		state.executionTodos = (lastPlan?.steps || []).map((s, i) => ({
			step: i + 1,
			text: s.title,
			completed: false,
		}));
		pi.setActiveTools(NORMAL_MODE_TOOLS);
		updateStatus(ctx);
		persist();
	}

	// ============================================================
	// Commands
	// ============================================================

	pi.registerCommand("plan", {
		description: "Plan first: explore read-only and produce a commentable HTML plan",
		handler: async (args, ctx) => {
			if (state.phase === "executing") {
				ctx.ui.notify("Currently executing. Use /plan-off to stop, then /plan again.", "warning");
				return;
			}
			const prompt = args.trim();
			enterPlanning(ctx);
			ctx.ui.notify(`Plan mode on (tools: ${PLAN_MODE_TOOLS.join(", ")}).`, "info");
			if (prompt) {
				pi.sendUserMessage(prompt);
			} else {
				ctx.ui.notify("Type your request — I'll explore read-only and produce a plan.", "info");
			}
		},
	});

	pi.registerCommand("iterate", {
		description: "Revise the current plan using comments saved in .pi/plans/feedback.md",
		handler: async (_args, ctx) => {
			if (state.phase !== "planning" || !state.planBase) {
				ctx.ui.notify("No active plan. Run /plan first.", "warning");
				return;
			}
			const fbPath = join(plansDir(ctx.cwd), FEEDBACK_FILENAME);
			if (!existsSync(fbPath)) {
				ctx.ui.notify(
					`No feedback found at ${fbPath}. In the browser, click "Export feedback" to save it.`,
					"warning",
				);
				return;
			}
			const fb = readFileSync(fbPath, "utf8");
			// Archive so we don't double-feed
			const archived = join(plansDir(ctx.cwd), `${state.planBase}-v${state.version}-feedback.md`);
			try { renameSync(fbPath, archived); } catch { /* ignore */ }
			ctx.ui.notify("Iterating on feedback…", "info");
			pi.sendUserMessage(feedbackPrompt(fb, state.version));
		},
	});

	pi.registerCommand("approve", {
		description: "Approve the latest plan and start executing it",
		handler: async (_args, ctx) => {
			if (state.phase !== "planning" || !lastPlan) {
				ctx.ui.notify("No plan ready to approve. Run /plan first.", "warning");
				return;
			}
			const summary = summarizeForExecution(lastPlan);
			enterExecution(ctx);
			ctx.ui.notify(
				`Executing plan v${state.version} with full tools (${NORMAL_MODE_TOOLS.join(", ")}).`,
				"info",
			);
			pi.sendUserMessage(executionPrompt(summary));
		},
	});

	pi.registerCommand("plan-off", {
		description: "Cancel plan / execution mode and restore full tools",
		handler: async (_args, ctx) => {
			exitPlanning(ctx);
			ctx.ui.notify("Plan mode cancelled. Full tools restored.", "info");
		},
	});

	// `/cancel` — discoverable cancel command. Behaves slightly differently
	// from /plan-off: it reports what was cancelled and (when applicable)
	// stops a streaming agent first.
	pi.registerCommand("cancel", {
		description: "Cancel the active plan or execution",
		handler: async (_args, ctx) => {
			if (state.phase === "idle") {
				ctx.ui.notify("Nothing to cancel — no active plan or execution.", "info");
				return;
			}

			const wasExecuting = state.phase === "executing";
			const wasPlanning = state.phase === "planning";
			const completedSteps = state.executionTodos.filter((t) => t.completed).length;
			const totalSteps = state.executionTodos.length;
			const version = state.version;

			// Interrupt a streaming agent so the cancel feels immediate.
			if (!ctx.isIdle()) {
				try { ctx.abort(); } catch { /* ignore */ }
			}

			exitPlanning(ctx);

			if (wasExecuting) {
				ctx.ui.notify(
					totalSteps > 0
						? `Execution cancelled at ${completedSteps}/${totalSteps}. Full tools restored.`
						: "Execution cancelled. Full tools restored.",
					"info",
				);
			} else if (wasPlanning) {
				ctx.ui.notify(
					version > 0
						? `Plan v${version} cancelled. Drafts kept in .pi/plans/. Full tools restored.`
						: "Plan cancelled. Full tools restored.",
					"info",
				);
			}
		},
	});

	pi.registerCommand("plan-open", {
		description: "Re-open the latest plan HTML in the browser",
		handler: async (_args, ctx) => {
			if (!state.planBase || state.version < 1) {
				ctx.ui.notify("No plan rendered yet.", "warning");
				return;
			}
			const { html } = planFiles(ctx.cwd, state.planBase, state.version);
			if (!existsSync(html)) {
				ctx.ui.notify(`Plan file not found: ${html}`, "warning");
				return;
			}
			// Make sure the cwd is in the allowlist for this re-open.
			registerCwd(ctx.cwd);
			await ensureFeedbackServer();
			openInBrowser(planViewUrl(state.planBase, state.version, html));
		},
	});

	pi.registerShortcut(Key.ctrlAlt("p"), {
		description: "Toggle plan mode",
		handler: (ctx) => {
			if (state.phase === "planning") exitPlanning(ctx);
			else enterPlanning(ctx);
		},
	});

	pi.registerFlag("plan", {
		description: "Start in plan mode",
		type: "boolean",
		default: false,
	});

	// ============================================================
	// Hooks
	// ============================================================

	// Inject hidden planning / execution context before each agent turn.
	pi.on("before_agent_start", async () => {
		if (state.phase === "planning") {
			return {
				message: {
					customType: "plan-html-context",
					content: planningPrompt(DESIGN_SYSTEM_DIR),
					display: false,
				},
			};
		}
		// Execution context is delivered as a visible user message, so no
		// per-turn injection here (the [DONE:n] convention is self-evident
		// from the user message that started execution).
	});

	// Block destructive bash while planning.
	pi.on("tool_call", async (event) => {
		if (state.phase !== "planning" || event.toolName !== "bash") return;
		const command = (event.input as { command?: string }).command || "";
		if (!isSafeBash(command)) {
			return {
				block: true,
				reason: `Plan mode: command not on read-only allowlist. Use /plan-off first.\nCommand: ${command}`,
			};
		}
	});

	// After each turn while executing, scan for [DONE:n] markers.
	pi.on("turn_end", async (event, ctx) => {
		if (state.phase !== "executing" || !state.executionTodos.length) return;
		if (!isAssistant(event.message)) return;
		const text = assistantText(event.message);
		let changed = false;
		for (const m of text.matchAll(/\[DONE:(\d+)\]/gi)) {
			const n = Number(m[1]);
			const t = state.executionTodos.find((x) => x.step === n);
			if (t && !t.completed) { t.completed = true; changed = true; }
		}
		if (changed) {
			updateStatus(ctx);
			persist();
			if (state.executionTodos.every((t) => t.completed)) {
				pi.sendMessage(
					{
						customType: "plan-html-complete",
						content: `**Plan v${state.version} complete.** ✓ All ${state.executionTodos.length} steps done.`,
						display: true,
					},
					{ triggerTurn: false },
				);
				state.phase = "idle";
				state.executionTodos = [];
				pi.setActiveTools(NORMAL_MODE_TOOLS);
				updateStatus(ctx);
				persist();
			}
		}
	});

	// When the agent finishes a turn in planning mode, try to capture &
	// render a plan from its last assistant message.
	pi.on("agent_end", async (event, ctx) => {
		if (state.phase !== "planning") return;

		const lastAssistant = [...event.messages].reverse().find(isAssistant);
		if (!lastAssistant) return;
		const text = assistantText(lastAssistant);
		const { plan } = extractPlanJson(text);
		if (!plan) {
			ctx.ui.notify(
				"No plan-json block found in the model's reply. Use /iterate with notes asking for one, or /plan-off to cancel.",
				"warning",
			);
			return;
		}

		lastPlan = plan;
		state.version += 1;
		const planBase = state.planBase || `plan-${timestampSlug()}`;
		const { json: jsonPath, html: htmlPath } = planFiles(
			ctx.cwd,
			planBase,
			state.version,
		);

		// Start the feedback server (idempotent) and register this cwd.
		const absCwd = registerCwd(ctx.cwd);
		const serverInfo = await ensureFeedbackServer();

		// Asset paths: when the server is up, serve assets from /asset so the
		// page can be opened over HTTP (same-origin with /feedback). Otherwise
		// fall back to relative paths to the on-disk design system.
		const assetBase = serverInfo ? "/asset" : assetBaseFor(htmlPath);

		const html = renderPlanHtml(plan, {
			planId: state.planBase || "plan",
			version: state.version,
			assetBase,
			cwd: absCwd,
			feedbackUrl: serverInfo?.url,
			feedbackToken: serverInfo?.token,
		});
		writeFileSync(jsonPath, JSON.stringify(plan, null, 2));
		writeFileSync(htmlPath, html);
		persist();
		openInBrowser(planViewUrl(planBase, state.version, htmlPath));

		const relPath = relative(ctx.cwd, htmlPath);
		pi.sendMessage(
			{
				customType: "plan-html-rendered",
				content:
					`📋 **Plan v${state.version}** → \`${relPath}\` (opened in browser)\n\n` +
					"Review, comment, then in the browser click **Export feedback** — it'll save `feedback.md` straight into `.pi/plans/`.\n" +
					"Then back here:\n" +
					"- `/iterate` — revise based on saved feedback\n" +
					"- `/approve` — accept and execute\n" +
					"- `/plan-off` — cancel",
				display: true,
			},
			{ triggerTurn: false },
		);
	});

	// Filter stale planning context from history when not planning.
	pi.on("context", async (event) => {
		if (state.phase === "planning") return;
		const filtered = event.messages.filter((m) => {
			const meta = m as AgentMessage & { customType?: string };
			return meta.customType !== "plan-html-context";
		});
		if (filtered.length !== event.messages.length) {
			return { messages: filtered };
		}
	});

	// Restore state across sessions.
	pi.on("session_start", async (_event, ctx) => {
		try {
			const entries = ctx.sessionManager.getEntries() as Array<{
				type?: string;
				customType?: string;
				data?: SessionState;
			}>;
			const restored = entries
				.filter((e) => e.type === "custom" && e.customType === STATE_ENTRY)
				.pop();
			if (restored?.data) {
				Object.assign(state, restored.data);
			}
		} catch { /* ignore */ }

		if (pi.getFlag("plan") === true && state.phase === "idle") {
			enterPlanning(ctx);
		} else if (state.phase === "planning") {
			pi.setActiveTools(PLAN_MODE_TOOLS);
		}
		updateStatus(ctx);

		// Re-register cwd so plan HTML opened from this session can post feedback
		// even before /plan runs again. Starts the server lazily.
		try {
			registerCwd(ctx.cwd);
			ensureFeedbackServer().catch(() => { /* silent */ });
		} catch { /* ignore */ }
	});

	// Stop the feedback server when pi shuts down.
	pi.on("session_shutdown", async () => {
		stopFeedbackServer();
	});
}