@posthog/wizard 2.44.0 → 2.46.0

package/dist/{agent-interface-BvTxWiol.js → agent-interface-B8roB2UP.js}

@@ -1,16 +1,21 @@
 import { n as __require } from "./rolldown-runtime-B_-DWIq7.js";
-import { G as POSTHOG_FLAG_HEADER_PREFIX, J as POSTHOG_PROPERTY_HEADER_PREFIX, a as getLogFilePath, at as WIZARD_ORCHESTRATOR_FLAG_KEY, f as getUI, lt as WIZARD_REMARK_EVENT_NAME, mt as wizardUserAgentForProgram, o as initLogFile, r as debug, s as logToFile, vt as runtimeEnv } from "./debug-DXfQFmcM.js";
-import { n as analytics } from "./analytics-DSlQuwOT.js";
-import { n as ADDITIONAL_FEATURE_PROMPTS } from "./wizard-session-BAZql11N.js";
-import { i as wizardAbort, n as registerCleanup, t as WizardError } from "./wizard-abort-C14PzXZ8.js";
-import { n as createWizardToolsServer, t as WIZARD_TOOL_NAMES } from "./wizard-tools-B7SLjCic.js";
-import { l as prewarmYaraScanner, n as createPostToolUseYaraHooks, r as createPreToolUseYaraHooks } from "./yara-hooks-CPH8N4yz.js";
+import { Ct as runtimeEnv, J as POSTHOG_FLAG_HEADER_PREFIX, Z as POSTHOG_PROPERTY_HEADER_PREFIX, a as getLogFilePath, f as getUI, lt as WIZARD_ORCHESTRATOR_FLAG_KEY, o as initLogFile, pt as WIZARD_REMARK_EVENT_NAME, r as debug, s as logToFile, yt as wizardUserAgentForProgram } from "./debug-C9HmIrwx.js";
+import { n as analytics } from "./analytics-k76OWsl0.js";
+import { n as ADDITIONAL_FEATURE_PROMPTS } from "./wizard-session-tp4Zdbwl.js";
+import { i as wizardAbort, n as registerCleanup, t as WizardError } from "./wizard-abort-FuyIaI_0.js";
+import { c as makeMutex, i as buildOrchestratorTools, l as writeJsonAtomic } from "./queue-tools-CTUgbOU8.js";
+import { _ as AUDIT_CHECKS_FILE, l as prewarmYaraScanner, n as createPostToolUseYaraHooks, r as createPreToolUseYaraHooks, x as coerceAuditChecks } from "./yara-hooks-DdYRRxfH.js";
+import { t as getWizardCommandments } from "./commandments-DSNrOeOC.js";
 import { createRequire } from "node:module";
 import * as fs$1 from "fs";
+import fs from "fs";
 import path from "path";
 import { spawnSync } from "node:child_process";
 import axios from "axios";
+import { z } from "zod";
 import * as os from "os";
+import { unzipSync } from "fflate";
+import { randomUUID } from "crypto";
 //#region src/utils/custom-headers.ts
 /**
 * Builds a list of custom headers for ANTHROPIC_CUSTOM_HEADERS.
@@ -160,6 +165,7 @@ const LINTING_TOOLS = [
 	"sql-formatter",
 	"sqlfmt",
 	"squawk",
+	"svelte-check",
 	"svgo",
 	"stringslint",
 	"swiftformat",
@@ -175,6 +181,1103 @@ const LINTING_TOOLS = [
 	"yamllint"
 ];
 //#endregion
+//#region src/lib/agent/bash-fence.ts
+/**
+* Bash command fence: exact per-manager allowlists + shell-shape gates.
+*
+* In effect this gates the pi harness only — on the Anthropic arm `Bash` is
+* pre-allowed (BASE_ALLOWED_TOOLS), so canUseTool never sees it and the SDK's
+* OS sandbox + YARA hooks gate execution instead. pi has no OS sandbox yet,
+* so this string fence is its only execution gate.
+*
+* Threat model: the agent can already Write project files, so commands that
+* execute project-defined code (installs, builds) are equivalent risk by
+* construction. The fence must prevent: direct arbitrary shell, outward
+* registry actions (publish/push/deploy), arbitrary-package execution
+* (`npx <anything>` downloads and runs it), and shell injection. Matching is
+* token-exact per manager — keyword prefixes admitted `npm publish` via `pub`.
+*/
+const NODE_MANAGERS = new Set([
+	"npm",
+	"pnpm",
+	"yarn",
+	"bun"
+]);
+const GRADLE_MANAGERS = new Set([
+	"gradle",
+	"gradlew",
+	"./gradlew"
+]);
+const MAVEN_MANAGERS = new Set([
+	"mvn",
+	"mvnw",
+	"./mvnw"
+]);
+const NODE_SUBCOMMANDS = [
+	"install",
+	"i",
+	"ci",
+	"add",
+	"remove",
+	"uninstall",
+	"update",
+	"view"
+];
+const NODE_SCRIPT_NAMES = [
+	"build",
+	"lint",
+	"format",
+	"tsc",
+	"typecheck",
+	"type-check",
+	"check-types",
+	"check",
+	"types"
+];
+const NPX_TOOLS = new Set([
+	...LINTING_TOOLS,
+	"tsc",
+	"expo",
+	"pod-install",
+	"cap"
+]);
+const PIP_SUBCOMMANDS = [
+	"install",
+	"uninstall",
+	"show",
+	"list",
+	"index"
+];
+const BUNDLE_SUBCOMMANDS = [
+	"install",
+	"add",
+	"remove",
+	"update",
+	"show"
+];
+const MAVEN_GOALS = [
+	"install",
+	"compile",
+	"package",
+	"verify",
+	"dependency:tree"
+];
+/** Managers whose first subcommand is checked exactly against a fixed set. */
+const SIMPLE_MANAGERS = {
+	pip: PIP_SUBCOMMANDS,
+	pip3: PIP_SUBCOMMANDS,
+	poetry: [
+		"install",
+		"add",
+		"remove",
+		"show",
+		"lock",
+		"update"
+	],
+	pipenv: ["install", "uninstall"],
+	uv: [
+		"add",
+		"remove",
+		"sync"
+	],
+	pdm: [
+		"install",
+		"add",
+		"remove"
+	],
+	conda: ["install", "remove"],
+	composer: [
+		"install",
+		"require",
+		"update",
+		"remove",
+		"show"
+	],
+	bundle: BUNDLE_SUBCOMMANDS,
+	bundler: BUNDLE_SUBCOMMANDS,
+	gem: [
+		"install",
+		"uninstall",
+		"list",
+		"search"
+	],
+	swift: ["package", "build"],
+	pod: [
+		"install",
+		"update",
+		"search"
+	],
+	carthage: ["bootstrap", "update"]
+};
+const GRADLE_EXACT_TASKS = new Set([
+	"build",
+	"clean",
+	"dependencies"
+]);
+const GRADLE_TASK_VERBS = [
+	"assemble",
+	"compile",
+	"bundle",
+	"lint"
+];
+const XCODEBUILD_DENIED_ACTIONS = new Set(["test", "test-without-building"]);
+const DANGEROUS_OPERATORS = /[;`$()]/;
+const ALLOWED_TOOLS_SUMMARY = "Allowed: npm/pnpm/yarn/bun (install|i|ci|add|remove|uninstall|update|view, run <build/lint/typecheck script>), npx <lint tool|tsc|expo|pod-install|cap>, pip/pip3/poetry/pipenv/uv/pdm/conda (install/add/remove/...), composer (install|require|update|remove|show), bundle (install|add|remove|update|show|exec <lint tool>), gem (install|uninstall|list|search), swift (package|build), pod (install|update|search), carthage (bootstrap|update), xcodebuild (build/clean/archive actions), gradle/gradlew (build|clean|dependencies|assemble*/compile*/bundle*/lint* tasks), mvn (install|compile|package|verify|dependency:tree).";
+function deny(analyticsReason, message) {
+	return {
+		allowed: false,
+		message,
+		analyticsReason
+	};
+}
+function denyCommand(command, feedback) {
+	return deny("not in allowlist", `Bash command not allowed: \`${command.length > 120 ? command.slice(0, 117) + "..." : command}\`. ${feedback}`);
+}
+function isNodeScriptName(token) {
+	return NODE_SCRIPT_NAMES.some((name) => token === name || token.startsWith(name + ":"));
+}
+function isLintingTool(token) {
+	return LINTING_TOOLS.includes(token) || token === "tsc";
+}
+function nodeDecision(parts, command) {
+	const bin = parts[0];
+	let i = 1;
+	if (bin === "yarn" && parts[i] === "workspace" && parts[i + 1]) i += 2;
+	for (;;) {
+		const t = parts[i];
+		if (t === "-r" || t === "--recursive") i++;
+		else if (t && (t.startsWith("--filter=") || t.startsWith("--workspace="))) i++;
+		else if ((t === "--filter" || t === "--workspace" || t === "-w" && bin === "npm") && parts[i + 1]) i += 2;
+		else if (t === "-w" && bin === "pnpm") i++;
+		else break;
+	}
+	const sub = parts[i];
+	const feedback = `Allowed ${bin} usage: ${bin} ${NODE_SUBCOMMANDS.join("|")} [args], ${bin} run <script named ${NODE_SCRIPT_NAMES.join("/")}>, ${bin} exec <lint tool>, or ${bin} <that script name or lint tool> directly.`;
+	if (!sub) return denyCommand(command, feedback);
+	if (sub === "run") {
+		const target = parts[i + 1];
+		if (target && isNodeScriptName(target)) return { allowed: true };
+		return denyCommand(command, feedback);
+	}
+	if (sub === "exec") {
+		const target = parts[i + 1];
+		if (target && isLintingTool(target)) return { allowed: true };
+		return denyCommand(command, feedback);
+	}
+	if (NODE_SUBCOMMANDS.includes(sub)) return { allowed: true };
+	if (isNodeScriptName(sub) || isLintingTool(sub)) return { allowed: true };
+	return denyCommand(command, feedback);
+}
+function npxDecision(parts, command) {
+	const target = parts[1];
+	if (!target || target.startsWith("-")) return denyCommand(command, "npx may only run a known tool directly: tsc, expo, pod-install, cap, or a lint/format tool (eslint, prettier, biome, ...).");
+	const name = target.replace(/@[^@/]*$/, "");
+	if (NPX_TOOLS.has(name)) return { allowed: true };
+	return denyCommand(command, "npx may only run a known tool directly: tsc, expo, pod-install, cap, or a lint/format tool (eslint, prettier, biome, ...).");
+}
+function gradleDecision(parts, command) {
+	let sawTask = false;
+	for (const raw of parts.slice(1)) {
+		if (raw.startsWith("-")) continue;
+		const task = raw.replace(/^(?::[\w.-]+)+:/, "");
+		if (!(GRADLE_EXACT_TASKS.has(task) || GRADLE_TASK_VERBS.some((verb) => task.startsWith(verb) && /^[A-Z]/.test(task.slice(verb.length))))) return denyCommand(command, "Allowed gradle tasks: build, clean, dependencies, or assemble*/compile*/bundle*/lint* variants (flags OK).");
+		sawTask = true;
+	}
+	return sawTask ? { allowed: true } : denyCommand(command, "Give gradle an allowed task: build, clean, dependencies, assembleDebug, ...");
+}
+function mavenDecision(parts, command) {
+	let sawGoal = false;
+	for (const raw of parts.slice(1)) {
+		if (raw.startsWith("-")) continue;
+		if (!MAVEN_GOALS.includes(raw)) return denyCommand(command, `Allowed mvn goals: ${MAVEN_GOALS.join(", ")} (flags OK).`);
+		sawGoal = true;
+	}
+	return sawGoal ? { allowed: true } : denyCommand(command, `Give mvn an allowed goal: ${MAVEN_GOALS.join(", ")}.`);
+}
+function xcodebuildDecision(parts, command) {
+	for (const t of parts.slice(1)) if (XCODEBUILD_DENIED_ACTIONS.has(t)) return denyCommand(command, "xcodebuild test actions are not allowed; build, clean, and archive are.");
+	return { allowed: true };
+}
+/** Grammar decision for a single operator-free, pipe-free command. */
+function commandDecision(command) {
+	const parts = command.split(/\s+/).filter(Boolean);
+	const bin = parts[0];
+	if (!bin) return denyCommand(command, ALLOWED_TOOLS_SUMMARY);
+	if (NODE_MANAGERS.has(bin)) return nodeDecision(parts, command);
+	if (bin === "npx") return npxDecision(parts, command);
+	if (GRADLE_MANAGERS.has(bin)) return gradleDecision(parts, command);
+	if (MAVEN_MANAGERS.has(bin)) return mavenDecision(parts, command);
+	if (bin === "xcodebuild") return xcodebuildDecision(parts, command);
+	if ((bin === "python" || bin === "python3") && parts[1] === "manage.py" && parts[2] === "check") return { allowed: true };
+	if (bin === "uv" && parts[1] === "pip") {
+		if (parts[2] && PIP_SUBCOMMANDS.includes(parts[2])) return { allowed: true };
+		return denyCommand(command, `Allowed uv pip subcommands: ${PIP_SUBCOMMANDS.join(", ")}.`);
+	}
+	if ((bin === "bundle" || bin === "bundler") && parts[1] === "exec") {
+		if (parts[2] && isLintingTool(parts[2])) return { allowed: true };
+		return denyCommand(command, `bundle exec may only run a lint/format tool (rubocop, ...). Allowed bundle subcommands: ${BUNDLE_SUBCOMMANDS.join(", ")}, exec <lint tool>.`);
+	}
+	const subs = SIMPLE_MANAGERS[bin];
+	if (subs) {
+		if (parts[1] && subs.includes(parts[1])) return { allowed: true };
+		const exec = bin === "bundle" || bin === "bundler" ? ", exec <lint tool>" : "";
+		return denyCommand(command, `Allowed ${bin} subcommands: ${subs.join(", ")}${exec}.`);
+	}
+	return denyCommand(command, `\`${bin}\` is not an allowed tool. ${ALLOWED_TOOLS_SUMMARY}`);
+}
+function tailArgsAreSafe(argStr) {
+	const args = argStr.trim().split(/\s+/).filter(Boolean);
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (/^-[nc]$/.test(a)) {
+			if (!/^[+-]?\d+$/.test(args[i + 1] ?? "")) return false;
+			i++;
+		} else if (!/^-[nc]?\+?\d+$/.test(a)) return false;
+	}
+	return true;
+}
+/**
+* Full fence decision for a Bash command: shell-shape gates (separators,
+* redirects, pipes) first, then the per-manager grammar.
+*/
+function evaluateBashCommand(rawCommand) {
+	const command = rawCommand.trim();
+	if (/[\r\n]/.test(command)) return deny("dangerous operators", "Bash command not allowed. Multi-line commands are not permitted — run one command at a time.");
+	if (DANGEROUS_OPERATORS.test(command)) return deny("dangerous operators", "Bash command not allowed. Shell operators like ; ` $ ( ) are not permitted.");
+	const normalized = command.replace(/\s*\d*>&\d+\s*/g, " ").replace(/\s*\d*>\s*\/dev\/null\s*/g, " ").trim();
+	if (/[<>]/.test(normalized)) return deny("disallowed redirect", "Bash command not allowed. Redirects are not permitted (only 2>&1 and >/dev/null).");
+	const pipeMatch = normalized.match(/^(.+?)\s*\|\s*(?:tail|head)((?:\s+\S+)*)\s*$/);
+	if (pipeMatch) {
+		const base = pipeMatch[1].trim();
+		if (/[|&]/.test(base)) return deny("multiple pipes", "Bash command not allowed. Only a single pipe to tail/head is permitted.");
+		if (!tailArgsAreSafe(pipeMatch[2])) return deny("disallowed pipe", "Bash command not allowed. tail/head may only take numeric flags (-n 50, -c 200) — no file arguments.");
+		return commandDecision(base);
+	}
+	if (/[|&]/.test(normalized)) return deny("disallowed pipe", "Bash command not allowed. Pipes are only permitted as a single | tail/head for output limiting.");
+	return commandDecision(normalized);
+}
+//#endregion
+//#region src/lib/wizard-ask-bridge.ts
+/**
+* WizardAskBridge — host-side promise broker for the `wizard_ask` MCP tool.
+*
+* The `wizard_ask` tool needs to (a) read information from the wizard
+* session (the active skill id, used as the analytics `source`) and
+* (b) drive the TUI overlay. Wiring `wizard-tools.ts` directly to either
+* would couple our pure-data MCP server to the runtime UI layer.
+*
+* The bridge is the seam: `wizard-tools.ts` depends on this interface,
+* and `agent-runner.ts` constructs an implementation that knows about
+* both the session and `getUI()`.
+*/
+/** Sentinel returned for unanswered fields on cancellation or timeout. */
+const CANCELLED_SENTINEL = "__cancelled__";
+function buildCancelledAnswers(questions) {
+	const out = {};
+	for (const q of questions) out[q.id] = CANCELLED_SENTINEL;
+	return out;
+}
+function isFullyCancelled(answers) {
+	const values = Object.values(answers);
+	if (values.length === 0) return false;
+	return values.every((v) => v === CANCELLED_SENTINEL);
+}
+function createWizardAskBridge(opts) {
+	const timeoutMs = opts.timeoutMs ?? 3e5;
+	return { async request({ questions }) {
+		const pending = {
+			id: randomUUID(),
+			questions,
+			source: opts.getSource(),
+			richLinks: opts.richLinks ?? false
+		};
+		const startedAt = Date.now();
+		let timer;
+		const timeoutPromise = new Promise((resolve) => {
+			timer = setTimeout(() => {
+				opts.cancelQuestion?.();
+				resolve(buildCancelledAnswers(questions));
+			}, timeoutMs);
+		});
+		try {
+			const answers = await Promise.race([opts.showQuestion(pending), timeoutPromise]);
+			const durationMs = Date.now() - startedAt;
+			if (isFullyCancelled(answers)) analytics.wizardCapture("wizard_ask cancelled", {
+				source: pending.source,
+				question_count: questions.length,
+				duration_ms: durationMs,
+				timed_out: durationMs >= timeoutMs
+			});
+			else analytics.wizardCapture("wizard_ask answered", {
+				source: pending.source,
+				question_count: questions.length,
+				duration_ms: durationMs
+			});
+			return answers;
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	} };
+}
+//#endregion
+//#region src/lib/fetch-retry.ts
+/**
+* Retry wrapper for fetching from the skills/agents server (GitHub releases in
+* production). GitHub releases blips transiently, so every fetch on the run's
+* critical path — skill menu, skill zips, agent menu, agent prompt bodies —
+* goes through here rather than a bare `fetch`.
+*/
+const DEFAULT_TIMEOUT_MS = 6e4;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_BACKOFF_MS = 500;
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Fetch a URL, retrying transient failures (network error or non-ok HTTP) with backoff. */
+async function fetchWithRetry(url, opts = {}) {
+	const { fetchImpl = fetch, sleepImpl = sleep, timeoutMs = DEFAULT_TIMEOUT_MS, maxAttempts = DEFAULT_MAX_ATTEMPTS, backoffMs = DEFAULT_BACKOFF_MS } = opts;
+	const failures = [];
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) try {
+		const resp = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+		if (!resp.ok) throw new Error(`HTTP ${resp.status} ${resp.statusText}`);
+		return resp;
+	} catch (err) {
+		failures.push(`attempt ${attempt}: ${err.message}`);
+		if (attempt < maxAttempts) await sleepImpl(backoffMs * 2 ** (attempt - 1));
+	}
+	throw new Error(`fetch ${url} failed — ${failures.join("; ")}`);
+}
+//#endregion
+//#region src/lib/wizard-tools/tools.ts
+/**
+* Shared wizard-tool behavior — skill discovery/install, env-file helpers,
+* the wizard_ask cap policy, secret-vault plumbing, and the audit ledger.
+* One implementation consumed by both protocol facades: the MCP server
+* (`./mcp`) and the pi-native tools (`harness/pi/tools.ts`) — tool behavior
+* cannot drift between harnesses.
+*/
+/** Expand a bundle entry into one entry per variant, so the menu reads the same whether a group ships bundled or as zips. */
+function expandBundleEntry(entry) {
+	if (!entry.bundle || !entry.variants) return [entry];
+	return entry.variants.map((variant) => ({
+		...variant,
+		name: entry.name,
+		group: entry.group,
+		bundle: true,
+		downloadUrl: entry.downloadUrl
+	}));
+}
+/**
+* Fetch the skill menu from the skills server.
+* Returns parsed data on success, `null` on failure.
+*/
+async function fetchSkillMenu(skillsBaseUrl, opts = {}) {
+	const menuUrl = `${skillsBaseUrl}/skill-menu.json`;
+	try {
+		logToFile(`fetchSkillMenu: fetching from ${menuUrl}`);
+		const data = await (await fetchWithRetry(menuUrl, opts)).json();
+		for (const [category, entries] of Object.entries(data.categories)) data.categories[category] = entries.flatMap(expandBundleEntry);
+		logToFile(`fetchSkillMenu: loaded (${Object.keys(data.categories).length} categories)`);
+		return data;
+	} catch (err) {
+		logToFile(`fetchSkillMenu: error: ${err.message}`);
+		return null;
+	}
+}
+/** Extract a zip buffer, refusing entries that escape destDir (zip-slip). */
+function extractZipArchive(zip, destDir) {
+	const root = path.resolve(destDir);
+	let written = 0;
+	for (const [entryPath, data] of Object.entries(unzipSync(zip))) {
+		const target = path.resolve(root, entryPath);
+		if (target !== root && !target.startsWith(root + path.sep)) throw new Error(`zip entry escapes destination: ${entryPath}`);
+		if (entryPath.endsWith("/")) {
+			fs.mkdirSync(target, { recursive: true });
+			continue;
+		}
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		fs.writeFileSync(target, data);
+		written++;
+	}
+	return written;
+}
+/** Unpack the one variant this entry names out of a bundle; the rest is noise and never hits disk. */
+function extractBundle(bundle, destDir, entryId) {
+	if (typeof bundle?.id !== "string" || typeof bundle?.variants !== "object" || bundle.variants === null) throw new Error("malformed bundle: expected { id, variants }");
+	const files = bundle.variants[entryId.slice(bundle.id.length + 1)];
+	if (!files) throw new Error(`bundle ${bundle.id} has no variant "${entryId}"`);
+	const root = path.resolve(destDir);
+	let written = 0;
+	for (const [entryPath, contents] of Object.entries(files)) {
+		const target = path.resolve(root, entryPath);
+		if (target !== root && !target.startsWith(root + path.sep)) throw new Error(`bundle entry escapes destination: ${entryPath}`);
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		fs.writeFileSync(target, contents);
+		written++;
+	}
+	return written;
+}
+/** Download a URL to a buffer, retrying transient failures with backoff. */
+async function downloadWithRetry(url, opts = {}) {
+	const resp = await fetchWithRetry(url, opts);
+	return new Uint8Array(await resp.arrayBuffer());
+}
+/**
+* Download and extract a skill.
+* By default installs to `<installDir>/.claude/skills/<id>/`.
+* Pass `skillsRoot` to override the base directory (e.g. `.posthog/skills`).
+*/
+async function downloadSkill(skillEntry, installDir, skillsRoot) {
+	const skillDir = skillsRoot ? path.join(installDir, skillsRoot, skillEntry.id) : path.join(installDir, ".claude", "skills", skillEntry.id);
+	let step = "download";
+	try {
+		fs.mkdirSync(skillDir, { recursive: true });
+		const data = await downloadWithRetry(skillEntry.downloadUrl);
+		step = "extract";
+		const fileCount = skillEntry.bundle ? extractBundle(JSON.parse(Buffer.from(data).toString("utf8")), skillDir, skillEntry.id) : extractZipArchive(data, skillDir);
+		fs.writeFileSync(path.join(skillDir, ".posthog-wizard"), "");
+		logToFile(`downloadSkill: installed ${skillEntry.id} from ${skillEntry.downloadUrl} (${fileCount} files)`);
+		return { success: true };
+	} catch (err) {
+		logToFile(`downloadSkill: error: ${err.message}`);
+		analytics.wizardCapture("skill install failed", {
+			skill_id: skillEntry.id,
+			step,
+			platform: process.platform,
+			error: String(err.message).slice(0, 500)
+		});
+		return {
+			success: false,
+			error: err.message
+		};
+	}
+}
+/**
+* High-level "install a skill by ID" helper. Fetches the skill menu,
+* finds the skill, downloads and extracts it. Programs should use this
+* instead of composing fetchSkillMenu + downloadSkill themselves.
+*/
+async function installSkillById(skillId, installDir, skillsBaseUrl, skillsRoot) {
+	const menu = await fetchSkillMenu(skillsBaseUrl);
+	if (!menu) return { kind: "menu-fetch-failed" };
+	const skill = Object.values(menu.categories).flat().find((s) => s.id === skillId);
+	if (!skill) return {
+		kind: "skill-not-found",
+		skillId
+	};
+	const result = await downloadSkill(skill, installDir, skillsRoot);
+	if (!result.success) return {
+		kind: "download-failed",
+		message: result.error ?? "unknown"
+	};
+	return {
+		kind: "ok",
+		path: skillsRoot ? `${skillsRoot}/${skillId}` : `.claude/skills/${skillId}`
+	};
+}
+/**
+* Pure decision function for the wizard_ask caps. Returns whether the
+* upcoming call should proceed and, if not, the error message to surface
+* to the agent. Extracted so the policy can be unit-tested without
+* spinning up an MCP server.
+*
+* The adjacency nudge fires exactly once per run (the caller records it
+* via `adjacencyNudged`) — flows that legitimately need several
+* sequential, answer-dependent asks then proceed up to `maxQuestions`.
+* Without the flag the rejected call would never advance the counter and
+* every later call would be rejected, making caps above the threshold
+* unreachable.
+*/
+function evaluateAskCap(callCount, maxQuestions, adjacencyNudged = false) {
+	if (callCount >= maxQuestions) return {
+		kind: "capped",
+		reason: "max_questions",
+		message: `Error: wizard_ask cap reached (${maxQuestions} calls in this run). Proceed with sensible defaults using the answers you already have, or emit [ABORT] requirements-incomplete.`
+	};
+	if (!adjacencyNudged && callCount >= 3) return {
+		kind: "capped",
+		reason: "adjacency",
+		message: `Error: too many wizard_ask calls in a row (${callCount} so far). Batch the remaining questions into a single call — the schema accepts up to 8 questions per invocation. If the remaining questions truly depend on earlier answers, ask again and they will go through.`
+	};
+	return { kind: "ok" };
+}
+const ENV_FILE_PATH_DESCRIPTION = "Path to the .env file, relative to the wizard working directory. Pass \".env\" for a file in that directory, or include the selected subproject path (for example, \"packages/app/.env\") for a nested project. Never prefix it with the wizard working directory's path inside an ancestor repository.";
+/**
+* Resolve filePath relative to workingDirectory, rejecting path traversal.
+*/
+function resolveEnvPath(workingDirectory, filePath) {
+	const resolved = path.resolve(workingDirectory, filePath);
+	if (!resolved.startsWith(workingDirectory + path.sep) && resolved !== workingDirectory) throw new Error(`Path traversal rejected: "${filePath}" resolves outside working directory`);
+	return resolved;
+}
+/**
+* Ensure the given env file basename is covered by .gitignore in the working directory.
+* Creates .gitignore if it doesn't exist; appends the entry if missing.
+*/
+function ensureGitignoreCoverage(workingDirectory, envFileName) {
+	const gitignorePath = path.join(workingDirectory, ".gitignore");
+	if (fs.existsSync(gitignorePath)) {
+		const content = fs.readFileSync(gitignorePath, "utf8");
+		if (content.split("\n").some((line) => line.trim() === envFileName)) return;
+		const newContent = content.endsWith("\n") ? `${content}${envFileName}\n` : `${content}\n${envFileName}\n`;
+		fs.writeFileSync(gitignorePath, newContent, "utf8");
+	} else fs.writeFileSync(gitignorePath, `${envFileName}\n`, "utf8");
+}
+/**
+* Parse a .env file's content and return the set of defined key names.
+*/
+function parseEnvKeys(content) {
+	const keys = /* @__PURE__ */ new Set();
+	for (const line of content.split("\n")) {
+		const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+		if (match) keys.add(match[1]);
+	}
+	return keys;
+}
+/**
+* Merge key-value pairs into existing .env content.
+* Updates existing keys in-place, appends new keys at the end.
+*/
+function mergeEnvValues(content, values) {
+	let result = content;
+	const updatedKeys = /* @__PURE__ */ new Set();
+	for (const [key, value] of Object.entries(values)) {
+		const regex = new RegExp(`^(\\s*${key}\\s*=).*$`, "m");
+		if (regex.test(result)) {
+			result = result.replace(regex, `$1${value}`);
+			updatedKeys.add(key);
+		}
+	}
+	const newKeys = Object.entries(values).filter(([key]) => !updatedKeys.has(key));
+	if (newKeys.length > 0) {
+		if (result.length > 0 && !result.endsWith("\n")) result += "\n";
+		for (const [key, value] of newKeys) result += `${key}=${value}\n`;
+	}
+	return result;
+}
+/**
+* Swap sensitive text answers for opaque vault refs before they return to
+* the agent — the raw value never enters the LLM conversation. Cancelled
+* answers pass through as the sentinel, unvaulted.
+*/
+function vaultSensitiveAnswers(questions, answers, vault) {
+	const sensitiveById = new Map(questions.filter((q) => q.sensitive).map((q) => [q.id, q.prompt]));
+	const sanitised = {};
+	for (const [id, answer] of Object.entries(answers)) {
+		const label = sensitiveById.get(id);
+		if (label !== void 0 && typeof answer === "string" && answer !== "__cancelled__") {
+			const ref = vault.put(answer, {
+				label,
+				source: "wizard_ask"
+			});
+			sanitised[id] = { secretRef: ref };
+			logToFile(`wizard_ask: vaulted answer for "${id}" as ${ref}`);
+		} else sanitised[id] = answer;
+	}
+	return sanitised;
+}
+/**
+* Resolve `{secretRef}` entries host-side, so the value is written but never
+* returned to the agent. Callers format their own error envelope from the
+* failing key/ref.
+*/
+function resolveEnvSecretRefs(values, vault) {
+	const resolved = {};
+	const refKeys = [];
+	for (const [key, val] of Object.entries(values)) {
+		if (typeof val === "string") {
+			resolved[key] = val;
+			continue;
+		}
+		const secret = vault.get(val.secretRef);
+		if (secret === void 0) return {
+			ok: false,
+			key,
+			secretRef: val.secretRef
+		};
+		resolved[key] = secret;
+		refKeys.push(key);
+	}
+	return {
+		ok: true,
+		values: resolved,
+		refKeys
+	};
+}
+const AUDIT_STATUSES = [
+	"pending",
+	"pass",
+	"error",
+	"warning",
+	"suggestion"
+];
+/** Atomically write the audit ledger. Thin typed wrapper over writeJsonAtomic. */
+function writeLedgerAtomic(targetPath, checks) {
+	writeJsonAtomic(targetPath, checks);
+}
+/**
+* Apply a batch of patches to the ledger by id. Returns the new array and the
+* list of update ids that didn't match any existing check.
+*/
+function applyAuditUpdates(current, updates) {
+	const byId = new Map(current.map((c) => [c.id, c]));
+	const unknown = [];
+	for (const u of updates) {
+		const existing = byId.get(u.id);
+		if (!existing) {
+			unknown.push(u.id);
+			continue;
+		}
+		byId.set(u.id, {
+			...existing,
+			status: u.status,
+			...u.file !== void 0 ? { file: u.file } : {},
+			...u.details !== void 0 ? { details: u.details } : {}
+		});
+	}
+	return {
+		next: current.map((c) => byId.get(c.id) ?? c),
+		unknown
+	};
+}
+/**
+* Append new checks to a seeded ledger. Duplicate ids are reported without
+* mutating the current ledger, including duplicates inside the additions.
+*/
+function applyAuditAdditions(current, additions) {
+	const existingIds = new Set(current.map((c) => c.id));
+	const additionIds = /* @__PURE__ */ new Set();
+	const duplicates = [];
+	for (const check of additions) {
+		if (existingIds.has(check.id) || additionIds.has(check.id)) {
+			duplicates.push(check.id);
+			continue;
+		}
+		additionIds.add(check.id);
+	}
+	if (duplicates.length > 0) return {
+		next: current,
+		duplicates
+	};
+	return {
+		next: [...current, ...additions],
+		duplicates: []
+	};
+}
+function readLedger(targetPath) {
+	if (!fs.existsSync(targetPath)) return [];
+	try {
+		return coerceAuditChecks(JSON.parse(fs.readFileSync(targetPath, "utf8")));
+	} catch {
+		return [];
+	}
+}
+function appendAuditChecksToLedger(targetPath, additions) {
+	if (!fs.existsSync(targetPath)) return {
+		ok: false,
+		reason: "missing-ledger"
+	};
+	const { next, duplicates } = applyAuditAdditions(readLedger(targetPath), additions);
+	if (duplicates.length > 0) return {
+		ok: false,
+		reason: "duplicate-ids",
+		ids: duplicates
+	};
+	writeLedgerAtomic(targetPath, next);
+	return {
+		ok: true,
+		added: additions.length
+	};
+}
+const SERVER_NAME = "wizard-tools";
+/** Tool names exposed by the wizard-tools server, keyed for selective use. */
+const WIZARD_TOOL_NAMES = {
+	checkEnvKeys: `mcp__${SERVER_NAME}__check_env_keys`,
+	setEnvValues: `mcp__${SERVER_NAME}__set_env_values`,
+	detectPackageManager: `mcp__${SERVER_NAME}__detect_package_manager`,
+	loadSkillMenu: `mcp__${SERVER_NAME}__load_skill_menu`,
+	installSkill: `mcp__${SERVER_NAME}__install_skill`,
+	auditSeedChecks: `mcp__${SERVER_NAME}__audit_seed_checks`,
+	auditAddChecks: `mcp__${SERVER_NAME}__audit_add_checks`,
+	auditResolveChecks: `mcp__${SERVER_NAME}__audit_resolve_checks`,
+	wizardAsk: `mcp__${SERVER_NAME}__wizard_ask`,
+	enqueueTask: `mcp__${SERVER_NAME}__enqueue_task`,
+	completeTask: `mcp__${SERVER_NAME}__complete_task`,
+	readHandoffs: `mcp__${SERVER_NAME}__read_handoffs`
+};
+//#endregion
+//#region src/lib/secret-vault.ts
+/**
+* Session-scoped secret vault.
+*
+* Tools that handle sensitive values (personal API keys pasted by the user
+* or minted by the wizard, OAuth tokens, etc.) store them here and return
+* an opaque `secret:<uuid>` ref to the agent. The agent passes the ref
+* around to subsequent tools — `set_env_values` resolves it host-side
+* before writing — but the raw value never enters the LLM conversation.
+*
+* The vault is created once per `createWizardToolsServer` call and lives
+* for the duration of a single wizard run. There is no persistence and
+* no cross-session sharing; refs minted in one run cannot be resolved in
+* another.
+*/
+const REF_PREFIX = "secret:";
+function createSecretVault() {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		put(value, meta) {
+			const ref = `${REF_PREFIX}${randomUUID()}`;
+			store.set(ref, {
+				value,
+				meta: {
+					ref,
+					label: meta.label,
+					source: meta.source,
+					createdAt: Date.now()
+				}
+			});
+			return ref;
+		},
+		get(ref) {
+			return store.get(ref)?.value;
+		},
+		has(ref) {
+			return store.has(ref);
+		},
+		list() {
+			return [...store.values()].map((s) => s.meta);
+		},
+		clear() {
+			store.clear();
+		}
+	};
+}
+//#endregion
+//#region src/lib/wizard-tools/mcp.ts
+/**
+* MCP facade over `./tools` — the unified in-process server the anthropic
+* harness mounts. Declarations (zod schemas, descriptions) and the MCP result
+* envelope live here; all behavior is imported from the shared core.
+*
+* Provides: check_env_keys, set_env_values, detect_package_manager,
+* load_skill_menu / install_skill, audit_* ledger tools, wizard_ask, and the
+* orchestrator queue tools. Secret values never leave the machine.
+*/
+const auditCheckSchema = z.object({
+	id: z.string().min(1),
+	area: z.string().min(1),
+	label: z.string().min(1),
+	status: z.enum(AUDIT_STATUSES),
+	file: z.string().optional(),
+	details: z.string().optional()
+});
+const auditUpdateSchema = z.object({
+	id: z.string().min(1),
+	status: z.enum(AUDIT_STATUSES),
+	file: z.string().optional(),
+	details: z.string().optional()
+});
+let _sdkModule$1 = null;
+async function getSDKModule$1() {
+	if (!_sdkModule$1) _sdkModule$1 = await import("@anthropic-ai/claude-agent-sdk");
+	return _sdkModule$1;
+}
+/** Default per-run cap on wizard_ask calls when no override is provided. */
+/**
+* Create the unified in-process MCP server with all wizard tools.
+* Must be called asynchronously because the SDK is an ESM module loaded via dynamic import.
+*/
+async function createWizardToolsServer(options) {
+	const { workingDirectory, detectPackageManager, skillsBaseUrl, askBridge, askMaxQuestions = 10, secretVault = createSecretVault(), orchestrator } = options;
+	const { tool, createSdkMcpServer } = await getSDKModule$1();
+	let askCallCount = 0;
+	let askAdjacencyNudged = false;
+	let cachedSkillMenu = {};
+	let categoryNames = ["integration"];
+	const menu = await fetchSkillMenu(skillsBaseUrl);
+	if (menu) cachedSkillMenu = menu.categories;
+	const keys = Object.keys(cachedSkillMenu);
+	if (keys.length > 0) categoryNames = keys;
+	const checkEnvKeys = tool("check_env_keys", "Check which environment variable keys are present or missing in a .env file. Never reveals values.", {
+		filePath: z.string().describe(ENV_FILE_PATH_DESCRIPTION),
+		keys: z.array(z.string()).describe("Environment variable key names to check")
+	}, (args) => {
+		const resolved = resolveEnvPath(workingDirectory, args.filePath);
+		logToFile(`check_env_keys: ${resolved}, keys: ${args.keys.join(", ")}`);
+		const existingKeys = fs.existsSync(resolved) ? parseEnvKeys(fs.readFileSync(resolved, "utf8")) : /* @__PURE__ */ new Set();
+		const results = {};
+		for (const key of args.keys) results[key] = existingKeys.has(key) ? "present" : "missing";
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(results, null, 2)
+		}] };
+	});
+	const setEnvValues = tool("set_env_values", "Create or update environment variable keys in a .env file. Creates the file if it does not exist. Ensures .gitignore coverage. Each value can be either a literal string or a secret reference of the form `{ \"secretRef\": \"secret:...\" }` returned by another tool (e.g. wizard_ask). Secret references are resolved locally — the actual value is written to the file but never returned to the agent.", {
+		filePath: z.string().describe(ENV_FILE_PATH_DESCRIPTION),
+		values: z.record(z.string(), z.union([z.string(), z.object({ secretRef: z.string() })])).describe("Key → (literal string OR { secretRef } pointing to a vaulted secret)")
+	}, (args) => {
+		const forbidden = Object.keys(args.values).find((k) => k.toUpperCase() === "POSTHOG_KEY");
+		if (forbidden) return {
+			content: [{
+				type: "text",
+				text: `Error: "${forbidden}" is not a valid PostHog env var name. Use the project-specific key name from your framework's integration guide (e.g. NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN).`
+			}],
+			isError: true
+		};
+		const resolution = resolveEnvSecretRefs(args.values, secretVault);
+		if (!resolution.ok) return {
+			content: [{
+				type: "text",
+				text: `Error: secret reference "${resolution.secretRef}" for key "${resolution.key}" is not known to the vault. The ref may have expired, been minted in a different run, or been mistyped.`
+			}],
+			isError: true
+		};
+		const { values: resolvedValues, refKeys: resolvedRefKeys } = resolution;
+		const resolved = resolveEnvPath(workingDirectory, args.filePath);
+		logToFile(`set_env_values: ${resolved}, keys: ${Object.keys(resolvedValues).join(", ")}${resolvedRefKeys.length > 0 ? ` (secret refs: ${resolvedRefKeys.join(", ")})` : ""}`);
+		const content = mergeEnvValues(fs.existsSync(resolved) ? fs.readFileSync(resolved, "utf8") : "", resolvedValues);
+		const dir = path.dirname(resolved);
+		if (!fs.existsSync(dir)) {
+			analytics.wizardCapture("set_env_values parent dir missing", { platform: process.platform });
+			return {
+				content: [{
+					type: "text",
+					text: `Error: parent directory does not exist: "${path.dirname(args.filePath)}". filePath is resolved against the wizard working directory — pass ".env" for a file there, or "<subproject>/.env" for an existing nested project.`
+				}],
+				isError: true
+			};
+		}
+		fs.writeFileSync(resolved, content, "utf8");
+		ensureGitignoreCoverage(workingDirectory, path.basename(resolved));
+		return { content: [{
+			type: "text",
+			text: `Updated ${Object.keys(args.values).length} key(s) in ${args.filePath}`
+		}] };
+	});
+	const detectPM = tool("detect_package_manager", "Detect which package manager(s) the project uses. Returns the name, install command, and run command for each detected package manager. Call this before running any install commands.", {}, async () => {
+		logToFile(`detect_package_manager: scanning ${workingDirectory}`);
+		const result = await detectPackageManager(workingDirectory);
+		logToFile(`detect_package_manager: detected ${result.detected.length} package manager(s)`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	const loadSkillMenu = tool("load_skill_menu", "Load available PostHog skills for a category. Returns skill IDs and names. Call this first, then use install_skill with the chosen ID.", { category: z.enum(categoryNames).describe("Skill category") }, (args) => {
+		const skills = cachedSkillMenu[args.category];
+		if (!skills || skills.length === 0) return {
+			content: [{
+				type: "text",
+				text: `No skills found for category "${args.category}".`
+			}],
+			isError: true
+		};
+		const menuText = skills.map((s) => `- ${s.id}: ${s.name}`).join("\n");
+		logToFile(`load_skill_menu: returning ${skills.length} skills for "${args.category}"`);
+		return { content: [{
+			type: "text",
+			text: menuText
+		}] };
+	});
+	const installSkill = tool("install_skill", "Download and install a PostHog skill by ID. Call load_skill_menu first to see available skills. Extracts the skill to .claude/skills/<skillId>/.", { skillId: z.string().describe("Skill ID from the skill menu (e.g., \"integration-nextjs-app-router\")") }, async (args) => {
+		if (!/^[a-z0-9][a-z0-9_-]*$/.test(args.skillId)) return {
+			content: [{
+				type: "text",
+				text: "Error: skillId must be lowercase alphanumeric with hyphens."
+			}],
+			isError: true
+		};
+		const skill = Object.values(cachedSkillMenu).flat().find((s) => s.id === args.skillId);
+		if (!skill) return {
+			content: [{
+				type: "text",
+				text: `Error: skill "${args.skillId}" not found. Use load_skill_menu to see available skills.`
+			}],
+			isError: true
+		};
+		const result = await downloadSkill(skill, workingDirectory);
+		if (result.success) return { content: [{
+			type: "text",
+			text: `Skill installed to .claude/skills/${args.skillId}/`
+		}] };
+		else {
+			analytics.captureException(/* @__PURE__ */ new Error("Skill install failed: download-failed"), {
+				source: "install_skill_tool",
+				skill_id: args.skillId,
+				error_detail: String(result.error).slice(0, 500),
+				platform: process.platform
+			});
+			return {
+				content: [{
+					type: "text",
+					text: `Error installing skill: ${result.error}`
+				}],
+				isError: true
+			};
+		}
+	});
+	const auditLedgerPath = path.join(workingDirectory, AUDIT_CHECKS_FILE);
+	const auditMutex = makeMutex();
+	const auditSeedChecks = tool("audit_seed_checks", "Seed the audit ledger at .posthog-audit-checks.json with the full set of pending checks. Call this once at the start of the audit. Atomically replaces any existing ledger.", { checks: z.array(auditCheckSchema).describe("Full pending checklist to write to the ledger") }, async (args) => {
+		return auditMutex(() => {
+			writeLedgerAtomic(auditLedgerPath, args.checks);
+			logToFile(`audit_seed_checks: wrote ${args.checks.length} entries`);
+			return { content: [{
+				type: "text",
+				text: `Seeded ${args.checks.length} audit checks.`
+			}] };
+		});
+	});
+	const auditAddChecks = tool("audit_add_checks", "Append one or more pending checks to the existing audit ledger at .posthog-audit-checks.json. Call audit_seed_checks first. Atomically rejects duplicate ids without changing the ledger.", { checks: z.array(auditCheckSchema).min(1).describe("Additional checks to append to the existing ledger") }, async (args) => {
+		return auditMutex(() => {
+			const result = appendAuditChecksToLedger(auditLedgerPath, args.checks);
+			if (!result.ok) {
+				if (result.reason === "missing-ledger") return {
+					content: [{
+						type: "text",
+						text: "Error: audit ledger does not exist. Run audit_seed_checks first."
+					}],
+					isError: true
+				};
+				return {
+					content: [{
+						type: "text",
+						text: `Error: duplicate check id(s): ${result.ids.join(", ")}. Check ids must be unique.`
+					}],
+					isError: true
+				};
+			}
+			logToFile(`audit_add_checks: added ${result.added} entries`);
+			return { content: [{
+				type: "text",
+				text: `Added ${result.added} audit check(s).`
+			}] };
+		});
+	});
+	const auditResolveChecks = tool("audit_resolve_checks", "Resolve one or more audit checks by id. Patches each entry's status (and optional file/details) and writes the ledger back atomically. Concurrent calls serialize.", { updates: z.array(auditUpdateSchema).min(1).describe("Patches to apply, keyed by check id") }, async (args) => {
+		return auditMutex(() => {
+			const { next, unknown } = applyAuditUpdates(readLedger(auditLedgerPath), args.updates);
+			if (unknown.length > 0) return {
+				content: [{
+					type: "text",
+					text: `Error: unknown check id(s): ${unknown.join(", ")}. Run audit_seed_checks first or check the id.`
+				}],
+				isError: true
+			};
+			writeLedgerAtomic(auditLedgerPath, next);
+			logToFile(`audit_resolve_checks: applied ${args.updates.length} update(s)`);
+			return { content: [{
+				type: "text",
+				text: `Resolved ${args.updates.length} check(s).`
+			}] };
+		});
+	});
+	const askQuestionSchema = z.object({
+		id: z.string().min(1).describe("Stable key for the answer in the response map"),
+		prompt: z.string().min(1).describe("Question text shown to the user"),
+		kind: z.enum([
+			"single",
+			"multi",
+			"text"
+		]).describe("'single' = pick one option, 'multi' = pick any, 'text' = free-form single-line answer"),
+		options: z.array(z.object({
+			label: z.string(),
+			value: z.string(),
+			description: z.string().optional().describe("Optional secondary line shown dimmed and wrapped beneath the label (multi-select only). Use when a choice needs more than a title — e.g. what a custom scout watches and what makes it speak up.")
+		})).optional().describe("Required for kind=single|multi; ignored for kind=text"),
+		required: z.boolean().optional().describe("Defaults to true"),
+		sensitive: z.boolean().optional().describe("Only valid for kind='text'. When true, the user's answer is stored in the wizard's secret vault and returned to you as { secretRef: 'secret:...' } instead of the raw string. Use for API keys, tokens, and any other secret the user types in. The secretRef is only resolved by wizard-tools that accept it (e.g. set_env_values) — it is NOT resolved when passed to other MCP tools (e.g. PostHog data-warehouse tools), which will reject it. For a secret that must reach another tool, write it to the env with set_env_values first, or use that tool's own credential-reference flow.")
+	});
+	return createSdkMcpServer({
+		name: SERVER_NAME,
+		version: "1.0.0",
+		tools: [
+			checkEnvKeys,
+			setEnvValues,
+			detectPM,
+			loadSkillMenu,
+			installSkill,
+			auditSeedChecks,
+			auditAddChecks,
+			auditResolveChecks,
+			tool("wizard_ask", "Ask the user one or more structured questions and wait for their answers. Use this whenever you would otherwise inline a question in your text output. Batch related questions into a single call (up to 8) rather than asking one at a time; sequential calls are fine when later questions genuinely depend on earlier answers. A fully cancelled or timed-out response does NOT count against the per-run cap — treat it as \"the user declined\" and fall back gracefully (e.g. hand over a deep link) without worrying about a wasted call.", { questions: z.array(askQuestionSchema).min(1).max(8) }, async (args) => {
+				if (!askBridge) return {
+					content: [{
+						type: "text",
+						text: "Error: wizard_ask is not available in this environment (CI / non-interactive). Proceed with sensible defaults or emit [ABORT] requirements-incomplete."
+					}],
+					isError: true
+				};
+				const capDecision = evaluateAskCap(askCallCount, askMaxQuestions, askAdjacencyNudged);
+				if (capDecision.kind === "capped") {
+					if (capDecision.reason === "adjacency") askAdjacencyNudged = true;
+					analytics.wizardCapture("wizard_ask capped", {
+						reason: capDecision.reason,
+						call_count: askCallCount,
+						max_questions: askMaxQuestions
+					});
+					return {
+						content: [{
+							type: "text",
+							text: capDecision.message
+						}],
+						isError: true
+					};
+				}
+				for (const q of args.questions) {
+					if ((q.kind === "single" || q.kind === "multi") && (!q.options || q.options.length === 0)) return {
+						content: [{
+							type: "text",
+							text: `Error: question "${q.id}" has kind="${q.kind}" but no options. Provide at least one { label, value } option, or change kind to "text".`
+						}],
+						isError: true
+					};
+					if (q.sensitive && q.kind !== "text") return {
+						content: [{
+							type: "text",
+							text: `Error: question "${q.id}" sets sensitive=true but kind="${q.kind}". Only kind="text" answers can be vaulted as secrets.`
+						}],
+						isError: true
+					};
+				}
+				const ids = /* @__PURE__ */ new Set();
+				for (const q of args.questions) {
+					if (ids.has(q.id)) return {
+						content: [{
+							type: "text",
+							text: `Error: duplicate question id "${q.id}". Each question must have a unique id.`
+						}],
+						isError: true
+					};
+					ids.add(q.id);
+				}
+				askCallCount += 1;
+				try {
+					const answers = await askBridge.request({ questions: args.questions });
+					if (isFullyCancelled(answers)) askCallCount -= 1;
+					const sanitised = vaultSensitiveAnswers(args.questions, answers, secretVault);
+					logToFile(`wizard_ask: resolved ${Object.keys(answers).length} answer(s) for ${args.questions.length} question(s)`);
+					return { content: [{
+						type: "text",
+						text: JSON.stringify({ answers: sanitised }, null, 2)
+					}] };
+				} catch (err) {
+					askCallCount -= 1;
+					logToFile(`wizard_ask: error: ${err?.message ?? err}`);
+					return {
+						content: [{
+							type: "text",
+							text: `Error: wizard_ask failed: ${err?.message ?? String(err)}`
+						}],
+						isError: true
+					};
+				}
+			}),
+			...orchestrator ? buildOrchestratorTools(tool, orchestrator) : []
+		]
+	});
+}
+//#endregion
 //#region src/lib/agent/triage-provider.ts
 /**
 * LLM provider for warlock security-scan triage.
@@ -231,44 +1334,6 @@ function createTriageLLMProvider(auth) {
 	};
 }
 //#endregion
-//#region src/lib/agent/commandments.ts
-/**
-* Wizard-wide commandments that are always appended as a system prompt.
-*
-* Keep this as a simple string so it can be inlined into the compiled bundle
-* without extra files, copying, or runtime I/O.
-*/
-const WIZARD_COMMANDMENTS = [
-	"Never hallucinate a PostHog project token, host, or any other secret. Always use the real values that have been configured for this project (for example via environment variables).",
-	"Never write API keys, access tokens, or other secrets directly into source code. Always reference environment variables instead, and rely on the wizard-tools MCP server (check_env_keys / set_env_values) to create or update .env files.",
-	"Always use the detect_package_manager tool from the wizard-tools MCP server to determine the package manager. Do not guess based on lockfiles or hard-code npm, yarn, pnpm, bun, pip, etc.",
-	"Before writing to any file, you MUST read that exact file immediately beforehand using the Read tool, even if you have already read it earlier in the run. This avoids tool failures and stale edits.",
-	"Treat feature flags, custom properties, and event names as part of an analytics contract. Prefer reusing existing names and patterns in the project. When you must introduce new ones, make them clear, descriptive, and consistent with existing conventions, and avoid scattering the same flag or property across many unrelated callsites.",
-	"Keep PostHog data capture at its defaults unless the user explicitly asks otherwise. Do not disable autocapture, do not disable session recording, and never set opt_out_capturing (or opted_out) to true in the SDK init config — these turn off data the user almost always wants. Note: posthog.opt_out_capturing() called at runtime for GDPR consent flows is legitimate; the rule is about the init configuration.",
-	"Never put personally identifiable information — emails, full or partial names, phone numbers, physical or IP addresses, or other user-entered PII — in capture() event properties. PII belongs on the PERSON: send it via identify()/$set (or the SDK's person-property API), and capture events with a stable distinct id derived from the authenticated user or session, never a raw email or name. This holds for every SDK, client and server.",
-	"Prefer minimal, targeted edits that achieve the requested behavior while preserving existing structure and style. Avoid large refactors, broad reformatting, or unrelated changes unless explicitly requested.",
-	"When you change a file that already exists, edit it in place. If an edit fails because the text you are matching is not unique, add just enough surrounding context to make it unique, or apply the change to each occurrence — never fall back to rewriting the whole file. Write a file in full only when you are creating it, never to modify one that already exists.",
-	"Before you overwrite or delete anything that already exists, look at what you would remove. This integration only adds instrumentation, so keep every part of the project unrelated to PostHog exactly as it was — never drop existing code, comments, or markup to make room for a change.",
-	"Do not spawn subagents unless explicitly instructed to do so.",
-	"Create tasks as soon as you understand the work you are going to carry out. Break the list into distinct stages of work that the user can follow through. Create all tasks in a single tool call, in the order you will be performing them. Drive the work with TaskUpdate: status in_progress when you begin a task, completed when done.",
-	"Keep task titles broad and stage-oriented — describe the purpose or area of work, not the specific files, paths, or symbols involved. Do not name individual files, modules, or directories inside task titles, and do not include illustrative examples within a task title.",
-	"Do not assume \"PostHog provider\" or \"PostHogProvider\" in task labels, status messages, or code. Only use a provider if the skill workflow explicitly requires one for the specific framework.",
-	"If you see a [YARA WARNING] or [YARA VIOLATION] message, handle it silently. Fix the issue (revert the write, avoid the flagged pattern) without mentioning security warnings or YARA to the user. These are internal guardrails, not user-facing alerts. Never show scary security language to the user.",
-	[
-		"When a skill instructs you to gather information from the user, use the `wizard_ask` MCP tool from the wizard-tools server. Never inline questions in your text output expecting a reply — the user has no way to answer text.",
-		"When a skill provides a numbered or bulleted list of questions, translate the entire list into a single `wizard_ask` tool call:",
-		"  - One tool call per skill step. Batch every question from that step into the `questions` array — never split into multiple calls.",
-		"  - Infer `kind` from the question phrasing: comma-separated alternatives (\"React, Vue, or vanilla JS?\") → `single`; phrasing like \"all that apply\" or \"any of\" → `multi`; everything else → `text`.",
-		"  - For `single` and `multi`, extract the alternatives from the prose into `options` as `{ label, value }` pairs. Use the human phrase as `label` and a lowercase-hyphenated form as `value` (e.g., `label: \"Vanilla JS\"`, `value: \"vanilla-js\"`).",
-		"  - Use a kebab-case slug of the question label as `id` (e.g., \"Tech stack\" → `tech-stack`, \"Show frequency\" → `show-frequency`).",
-		"  - Do not invent fields the schema does not define (no `source`, `category`, `priority`, etc.) — the tool rejects unknown fields and the wizard already knows which skill is running.",
-		"After `wizard_ask` returns, use the answers directly — do not re-ask in text or call `wizard_ask` again for the same fields."
-	].join("\n")
-].join("\n");
-function getWizardCommandments() {
-	return WIZARD_COMMANDMENTS;
-}
-//#endregion
 //#region src/lib/agent/agent-phase.ts
 /** Maps a Claude SDK tool name to the phase that tool implies. Returns null
 *  when the tool doesn't drive the visualizer (Task*, TodoWrite, etc.). */
@@ -959,62 +2024,9 @@ function buildAgentEnv(wizardMetadata, wizardFlags) {
 	return encoded;
 }
 /**
-* Package managers that can be used to run commands.
-*/
-const PACKAGE_MANAGERS = [
-	"npm",
-	"pnpm",
-	"yarn",
-	"bun",
-	"npx",
-	"pip",
-	"pip3",
-	"poetry",
-	"pipenv",
-	"uv"
-];
-/**
-* Safe scripts/commands that can be run with any package manager.
-* Uses startsWith matching, so 'build' matches 'build', 'build:prod', etc.
-* Note: Linting tools are in LINTING_TOOLS and checked separately.
-*/
-const SAFE_SCRIPTS = [
-	"install",
-	"add",
-	"ci",
-	"build",
-	"tsc",
-	"typecheck",
-	"type-check",
-	"check-types",
-	"types",
-	"lint",
-	"format"
-];
-/**
-* Dangerous shell operators that could allow command injection.
-* Note: We handle `2>&1` and `| tail/head` separately as safe patterns.
-*/
-const DANGEROUS_OPERATORS = /[;`$()]/;
-/**
-* Check if command is an allowed package manager command.
-* Matches: <pkg-manager> [run|exec] <safe-script> [args...]
-*/
-function matchesAllowedPrefix(command) {
-	const parts = command.split(/\s+/);
-	if (parts.length === 0 || !PACKAGE_MANAGERS.includes(parts[0])) return false;
-	let scriptIndex = 1;
-	if (parts[scriptIndex] === "run" || parts[scriptIndex] === "exec") scriptIndex++;
-	if (parts[scriptIndex] === "i") return true;
-	const scriptPart = parts.slice(scriptIndex).join(" ");
-	return SAFE_SCRIPTS.some((safe) => scriptPart.startsWith(safe)) || LINTING_TOOLS.some((tool) => scriptPart.startsWith(tool));
-}
-/**
-* Permission hook that allows only safe commands.
-* - Package manager install commands
-* - Build/typecheck/lint commands for verification
-* - Piping to tail/head for output limiting is allowed
-* - Stderr redirection (2>&1) is allowed
+* Permission hook that allows only safe commands. Bash commands are gated by
+* the exact per-manager fence in bash-fence.ts (install/build/typecheck/lint
+* commands, single | tail/head, 2>&1).
 *
 * `wizardAskPending` is true while a wizard_ask overlay is open — when set,
 * Write/Edit calls are denied as a defense-in-depth measure against a
@@ -1040,7 +2052,8 @@ function wizardCanUseTool(toolName, input, context = {}) {
 	if (toolName === "Read" || toolName === "Write" || toolName === "Edit") {
 		const filePath = typeof input.file_path === "string" ? input.file_path : "";
 		const basename = path.basename(filePath);
-		if (basename.startsWith(".env")) {
+		const isEnvExample = /^\.env\.(example|sample|template|dist)$/.test(basename);
+		if (basename.startsWith(".env") && !isEnvExample) {
 			logToFile(`Denying ${toolName} on env file: ${filePath}`);
 			return {
 				behavior: "deny",
@@ -1071,56 +2084,8 @@ function wizardCanUseTool(toolName, input, context = {}) {
 		updatedInput: input
 	};
 	const command = (typeof input.command === "string" ? input.command : "").trim();
-	if (DANGEROUS_OPERATORS.test(command)) {
-		logToFile(`Denying bash command with dangerous operators: ${command}`);
-		debug(`Denying bash command with dangerous operators: ${command}`);
-		analytics.wizardCapture("bash denied", {
-			reason: "dangerous operators",
-			command
-		});
-		return {
-			behavior: "deny",
-			message: `Bash command not allowed. Shell operators like ; \` $ ( ) are not permitted.`
-		};
-	}
-	const normalized = command.replace(/\s*\d*>&\d+\s*/g, " ").trim();
-	const pipeMatch = normalized.match(/^(.+?)\s*\|\s*(tail|head)(\s+\S+)*\s*$/);
-	if (pipeMatch) {
-		const baseCommand = pipeMatch[1].trim();
-		if (/[|&]/.test(baseCommand)) {
-			logToFile(`Denying bash command with multiple pipes: ${command}`);
-			debug(`Denying bash command with multiple pipes: ${command}`);
-			analytics.wizardCapture("bash denied", {
-				reason: "multiple pipes",
-				command
-			});
-			return {
-				behavior: "deny",
-				message: `Bash command not allowed. Only single pipe to tail/head is permitted.`
-			};
-		}
-		if (matchesAllowedPrefix(baseCommand)) {
-			logToFile(`Allowing bash command with output limiter: ${command}`);
-			debug(`Allowing bash command with output limiter: ${command}`);
-			return {
-				behavior: "allow",
-				updatedInput: input
-			};
-		}
-	}
-	if (/[|&]/.test(normalized)) {
-		logToFile(`Denying bash command with pipe/&: ${command}`);
-		debug(`Denying bash command with pipe/&: ${command}`);
-		analytics.wizardCapture("bash denied", {
-			reason: "disallowed pipe",
-			command
-		});
-		return {
-			behavior: "deny",
-			message: `Bash command not allowed. Pipes are only permitted with tail/head for output limiting.`
-		};
-	}
-	if (matchesAllowedPrefix(normalized)) {
+	const decision = evaluateBashCommand(command);
+	if (decision.allowed) {
 		logToFile(`Allowing bash command: ${command}`);
 		debug(`Allowing bash command: ${command}`);
 		return {
@@ -1128,15 +2093,15 @@ function wizardCanUseTool(toolName, input, context = {}) {
 			updatedInput: input
 		};
 	}
-	logToFile(`Denying bash command: ${command}`);
-	debug(`Denying bash command: ${command}`);
+	logToFile(`Denying bash command (${decision.analyticsReason}): ${command}`);
+	debug(`Denying bash command (${decision.analyticsReason}): ${command}`);
 	analytics.wizardCapture("bash denied", {
-		reason: "not in allowlist",
+		reason: decision.analyticsReason,
 		command
 	});
 	return {
 		behavior: "deny",
-		message: `Bash command not allowed. Only install, build, typecheck, lint, and formatting commands are permitted.`
+		message: decision.message
 	};
 }
 /**
@@ -1807,6 +2772,6 @@ function handleSDKMessage(message, options, spinner, signals, receivedSuccessRes
 	}
 }
 //#endregion
-export { wizardCanUseTool as a, classifySettingsConflicts as c, sanitizeAgentSubprocessEnv as d, AgentOutputSignals as f, createTriageLLMProvider as g, getWizardCommandments as h, runAgent as i, recoverOrphanedSettingsBackups as l, REMARK_INSTRUCTION as m, buildRunTags as n, backupAndFixClaudeSettings as o, AgentSignals as p, initializeAgent as r, checkAllSettingsConflicts as s, buildAgentEnv as t, restoreClaudeSettings as u };
+export { isFullyCancelled as A, mergeEnvValues as C, vaultSensitiveAnswers as D, resolveEnvSecretRefs as E, fetchWithRetry as O, installSkillById as S, resolveEnvPath as T, ENV_FILE_PATH_DESCRIPTION as _, wizardCanUseTool as a, evaluateAskCap as b, classifySettingsConflicts as c, sanitizeAgentSubprocessEnv as d, AgentOutputSignals as f, createSecretVault as g, createTriageLLMProvider as h, runAgent as i, createWizardAskBridge as k, recoverOrphanedSettingsBackups as l, REMARK_INSTRUCTION as m, buildRunTags as n, backupAndFixClaudeSettings as o, AgentSignals as p, initializeAgent as r, checkAllSettingsConflicts as s, buildAgentEnv as t, restoreClaudeSettings as u, WIZARD_TOOL_NAMES as v, parseEnvKeys as w, fetchSkillMenu as x, downloadSkill as y };
 
-//# sourceMappingURL=agent-interface-BvTxWiol.js.map
+//# sourceMappingURL=agent-interface-B8roB2UP.js.map