topchester-ai 0.10.0 → 0.11.0

package/dist/cli.mjs

@@ -15,7 +15,7 @@ import { parse } from "yaml";
 import pino from "pino";
 import picomatch from "picomatch";
 import { uuidv7 } from "uuidv7";
-import { Input, Markdown, ProcessTerminal, TUI, isKeyRelease, isKeyRepeat, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, Markdown, ProcessTerminal, TUI, decodeKittyPrintable, isKeyRelease, isKeyRepeat, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { highlight, supportsLanguage } from "cli-highlight";
 //#region src/agent/tools/ai-sdk-tools.ts
 function toAiSdkToolSet(definitions) {
@@ -97,23 +97,26 @@ async function enqueueFileMutation(path, mutate) {
 }
 //#endregion
 //#region src/agent/tools/types.ts
+function isToolErrorResult(result) {
+	return "error" in result && typeof result.error === "string";
+}
 function defineTool(definition) {
 	return definition;
 }
 //#endregion
 //#region src/agent/tools/edit-file.ts
 const editFileEditSchema = z.object({
-	old_text: z.string(),
-	new_text: z.string()
+	old_text: z.string().describe("Exact current file text to replace; include whitespace exactly."),
+	new_text: z.string().describe("Replacement text for old_text.")
 });
 const editFileTool = defineTool({
 	name: "edit_file",
-	description: "Edit an existing UTF-8 file inside the workspace with exact text replacements.",
-	prompt: "edit_file: edit an existing UTF-8 file inside the workspace with exact old_text/new_text replacements; read the file first, keep old_text small but unique, and make multiple disjoint edits for one file in one call. To use it, reply with only JSON: {\"tool\":\"edit_file\",\"args\":{\"path\":\"src/example.ts\",\"expected_hash\":\"sha256:optional-current-file-hash\",\"edits\":[{\"old_text\":\"const enabled = false;\\n\",\"new_text\":\"const enabled = true;\\n\"}]}}",
+	description: "Edit an existing UTF-8 file inside the workspace with exact text replacements. Use expected_current_hash only as the current/pre-edit hash from read_file, never as a predicted post-edit hash.",
+	prompt: "edit_file: edit an existing UTF-8 file inside the workspace with exact old_text/new_text replacements; read the file first, keep old_text small but unique, and make multiple disjoint edits for one file in one call. expected_current_hash is optional and must be the current/pre-edit hash returned by the latest read_file for that file; never invent it or use a predicted after-edit hash. To use it, reply with only JSON: {\"tool\":\"edit_file\",\"args\":{\"path\":\"src/example.ts\",\"expected_current_hash\":\"sha256:current-file-hash-from-read_file\",\"edits\":[{\"old_text\":\"const enabled = false;\\n\",\"new_text\":\"const enabled = true;\\n\"}]}}",
 	argsSchema: z.object({
-		path: z.string(),
-		expected_hash: z.string().optional(),
-		edits: z.array(editFileEditSchema).min(1)
+		path: z.string().describe("Workspace-relative path to the existing UTF-8 file to edit."),
+		expected_current_hash: z.string().optional().describe("Optional current file hash returned by the latest read_file result for this file. This is checked before editing to catch stale reads; it is not the hash after the edit."),
+		edits: z.array(editFileEditSchema).min(1).describe("Exact text replacements to apply to the original file.")
 	}),
 	execute: (context, args) => editWorkspaceFile(context.workspaceRoot, args, { logger: context.logger })
 });
@@ -123,7 +126,7 @@ async function editWorkspaceFile(workspaceRoot, args, options = {}) {
 		const fileStat = await statExistingFile(scopedPath.path, args.path);
 		const beforeBytes = await readFile(scopedPath.path);
 		const beforeHash = hashBytes$1(beforeBytes);
-		if (args.expected_hash && args.expected_hash !== beforeHash) throw new Error(`edit_file expected_hash did not match ${scopedPath.relativePath}.`);
+		if (args.expected_current_hash && args.expected_current_hash !== beforeHash) throw new Error(`edit_file expected_current_hash did not match ${scopedPath.relativePath}.`);
 		const result = applyExactEdits(decodeUtf8$1(scopedPath.relativePath, beforeBytes), args.edits, scopedPath.relativePath);
 		const afterBytes = Buffer.from(result.newContent, "utf8");
 		const afterHash = hashBytes$1(afterBytes);
@@ -376,7 +379,7 @@ const ignoredDirectories = new Set([
 ]);
 const findFileTool = defineTool({
 	name: "find_file",
-	description: "Find files by fuzzy name inside the workspace.",
+	description: "Find files by fuzzy name inside the workspace. Results are file paths, not file contents; use read_file next when the user needs contents.",
 	prompt: "find_file: find existing files by fuzzy path or filename inside the workspace; matches may appear in the middle of a filename, and results are file paths, not file contents. To use it, reply with only JSON: {\"tool\":\"find_file\",\"args\":{\"query\":\"runtime\"}}",
 	argsSchema: findFileArgsSchema,
 	execute: (context, args) => findWorkspaceFilesByName(context.workspaceRoot, args, {
@@ -829,7 +832,7 @@ function parseGitLog(output) {
 		};
 	});
 }
-function truncateText(content, maxBytes) {
+function truncateText$1(content, maxBytes) {
 	if (Buffer.byteLength(content) <= maxBytes) return {
 		content,
 		truncated: false
@@ -1056,7 +1059,7 @@ async function inspectGitDiff(context, args) {
 			changedFiles.add(file);
 		}
 	}
-	const bounded = truncateText(sections.join("\n").trimEnd() || "No diff.", args.max_bytes);
+	const bounded = truncateText$1(sections.join("\n").trimEnd() || "No diff.", args.max_bytes);
 	return {
 		tool: "git_diff",
 		path: path ?? void 0,
@@ -1644,6 +1647,8 @@ const READ_ONLY_COMMANDS = new Set([
 	"find",
 	"fd",
 	"cat",
+	"sed",
+	"sort",
 	"head",
 	"tail",
 	"wc",
@@ -1851,6 +1856,7 @@ function validateSimpleCommand(command, context) {
 		case "git": return validateGitCommand(command, context);
 		case "find": return validateFindCommand(command, context);
 		case "fd": return validateGenericCommandArgs(command, context, FD_OPTIONS_WITH_VALUES);
+		case "sed": return validateSedCommand(command, context);
 		default: return validateGenericCommandArgs(command, context, COMMON_OPTIONS_WITH_VALUES);
 	}
 }
@@ -1873,6 +1879,88 @@ function validateGitCommand(command, context) {
 function validateFindCommand(command, context) {
 	return validateGenericCommandArgs(command, context, FIND_OPTIONS_WITH_VALUES);
 }
+function validateSedCommand(command, context) {
+	let sawScript = false;
+	for (let index = 0; index < command.args.length; index += 1) {
+		const arg = command.args[index] ?? "";
+		if (arg === "-i" || arg.startsWith("-i") || arg === "--in-place" || arg.startsWith("--in-place=")) return {
+			allowed: false,
+			reason: "inspect_command rejected 'sed' because in-place edits are unsafe."
+		};
+		if (arg === "-e" || arg === "--expression") {
+			const script = command.args[index + 1];
+			if (!script) return {
+				allowed: false,
+				reason: "inspect_command rejected 'sed' because -e requires a script."
+			};
+			const scriptResult = validateSedScript(script);
+			if (!scriptResult.allowed) return scriptResult;
+			sawScript = true;
+			index += 1;
+			continue;
+		}
+		if (arg === "-n" || arg === "--quiet" || arg === "--silent" || /^-[Erun]+$/.test(arg)) continue;
+		if (arg.startsWith("-")) return {
+			allowed: false,
+			reason: `inspect_command rejected 'sed' because '${arg}' is not allowed.`
+		};
+		if (!sawScript && looksLikeSedScript(arg)) {
+			const scriptResult = validateSedScript(arg);
+			if (!scriptResult.allowed) return scriptResult;
+			sawScript = true;
+			continue;
+		}
+		const scoped = resolveWorkspacePath$1(context.workspaceRoot, arg, context.cwd);
+		if (!scoped.allowed) return {
+			allowed: false,
+			reason: scoped.reason
+		};
+	}
+	return sawScript ? { allowed: true } : {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because it requires an inline script."
+	};
+}
+function looksLikeSedScript(arg) {
+	return arg.startsWith("s") || /^(\d+|\$)?(,(\d+|\$))?[pdq]$/.test(arg);
+}
+function validateSedScript(script) {
+	if (script.includes("\n")) return {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because multiline scripts are unsafe."
+	};
+	if (/^(\d+|\$)?(,(\d+|\$))?[pdq]$/.test(script)) return { allowed: true };
+	if (!script.startsWith("s") || script.length < 4) return {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because only simple read-only scripts are allowed."
+	};
+	const delimiter = script[1] ?? "";
+	if (!delimiter || /[A-Za-z0-9\\\n]/.test(delimiter)) return {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because the substitution delimiter is invalid."
+	};
+	const delimiters = findUnescapedDelimiterIndexes(script, delimiter);
+	if (delimiters.length < 3) return {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because the substitution script is incomplete."
+	};
+	const flags = script.slice(delimiters[2] + 1);
+	if (/[^gIpM0-9]/.test(flags) || /[ew]/.test(flags)) return {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because substitution flags are unsafe."
+	};
+	return { allowed: true };
+}
+function findUnescapedDelimiterIndexes(script, delimiter) {
+	const indexes = [];
+	for (let index = 0; index < script.length; index += 1) {
+		if (script[index] !== delimiter) continue;
+		let slashCount = 0;
+		for (let back = index - 1; back >= 0 && script[back] === "\\"; back -= 1) slashCount += 1;
+		if (slashCount % 2 === 0) indexes.push(index);
+	}
+	return indexes;
+}
 function validateGenericCommandArgs(command, context, optionsWithValues, knownPathlessWords = /* @__PURE__ */ new Set()) {
 	for (let index = 0; index < command.args.length; index += 1) {
 		const arg = command.args[index] ?? "";
@@ -2310,6 +2398,256 @@ function resolveWorkspaceScopedPath$1(workspaceRoot, path) {
 		relativePath: relativePath || "."
 	};
 }
+//#endregion
+//#region src/cli/ui.ts
+const colors = {
+	bgSoftGray: "\x1B[48;5;236m",
+	blue: "\x1B[34m",
+	cyan: "\x1B[36m",
+	darkGray: "\x1B[90m",
+	dim: "\x1B[2m",
+	green: "\x1B[32m",
+	orange: "\x1B[38;5;208m",
+	purple: "\x1B[35m",
+	red: "\x1B[31m",
+	reset: "\x1B[0m",
+	resetForeground: "\x1B[39m",
+	yellow: "\x1B[33m"
+};
+const ui = {
+	heading(text) {
+		return color(`Topchester ${text}`, "cyan");
+	},
+	label(text) {
+		return color(text, "dim");
+	},
+	muted(text) {
+		return color(text, "darkGray");
+	},
+	model(text) {
+		return color(text, "blue");
+	},
+	modelInline(text) {
+		if (!shouldUseColor()) return text;
+		return `${colors.blue}${text}${colors.resetForeground}`;
+	},
+	ok(text) {
+		return color(text, "green");
+	},
+	warn(text) {
+		return color(text, "yellow");
+	},
+	error(text) {
+		return color(text, "red");
+	},
+	softBackground(text) {
+		return color(text, "bgSoftGray");
+	},
+	async spinner(text, action) {
+		return withStatusLine(text, action, void 0, 80, false);
+	},
+	async progress(text, action) {
+		let latest = text;
+		return withStatusLine(text, () => action((message) => {
+			latest = message;
+		}), () => latest, 80, true);
+	}
+};
+async function withStatusLine(text, action, getText = () => text, progressEveryMs = 80, emitPlainProgress = false) {
+	if (!shouldUseColor()) {
+		if (!emitPlainProgress) return action();
+		const timer = setInterval(() => {
+			stderr.write(`${getText()}\n`);
+		}, Math.max(progressEveryMs, 5e3));
+		try {
+			return await action();
+		} finally {
+			clearInterval(timer);
+		}
+	}
+	const frames = [
+		"⠋",
+		"⠙",
+		"⠹",
+		"⠸",
+		"⠼",
+		"⠴",
+		"⠦",
+		"⠧",
+		"⠇",
+		"⠏"
+	];
+	let index = 0;
+	stderr.write(`${color(frames[index], "cyan")} ${getText()}`);
+	const timer = setInterval(() => {
+		index = (index + 1) % frames.length;
+		stderr.write(`\r\u001b[2K${color(frames[index], "cyan")} ${getText()}`);
+	}, progressEveryMs);
+	try {
+		return await action();
+	} finally {
+		clearInterval(timer);
+		stderr.write(`\r\u001b[2K`);
+	}
+}
+function color(text, colorName) {
+	if (!shouldUseColor()) return text;
+	return `${colors[colorName]}${text}${colors.reset}`;
+}
+function shouldUseColor() {
+	if (process.env.NO_COLOR) return false;
+	if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") return true;
+	return stdout.isTTY === true;
+}
+//#endregion
+//#region src/agent/task-plan.ts
+const planTodoStatusSchema = z.enum([
+	"pending",
+	"in_progress",
+	"completed"
+]);
+const taskPlanItemSchema = z.object({
+	text: z.string().trim().min(1, "Plan item text cannot be empty."),
+	status: planTodoStatusSchema
+});
+const planTodoArgsSchema = z.object({ items: z.array(taskPlanItemSchema).max(20, "Plan updates are limited to 20 items.") }).superRefine((args, context) => {
+	const seen = /* @__PURE__ */ new Set();
+	let inProgressCount = 0;
+	let incompleteCount = 0;
+	args.items.forEach((item, index) => {
+		const key = item.text.toLocaleLowerCase("en");
+		if (seen.has(key)) context.addIssue({
+			code: "custom",
+			message: "Plan item text must be unique.",
+			path: [
+				"items",
+				index,
+				"text"
+			]
+		});
+		seen.add(key);
+		if (item.status === "in_progress") inProgressCount += 1;
+		if (item.status !== "completed") incompleteCount += 1;
+	});
+	if (inProgressCount > 1) context.addIssue({
+		code: "custom",
+		message: "At most one plan item can be in_progress.",
+		path: ["items"]
+	});
+	if (args.items.length > 0 && incompleteCount > 0 && inProgressCount === 0) context.addIssue({
+		code: "custom",
+		message: "A non-completed plan must have exactly one in_progress item.",
+		path: ["items"]
+	});
+});
+function createEmptyTaskPlanState(now = /* @__PURE__ */ new Date()) {
+	return {
+		items: [],
+		updatedAt: now.toISOString()
+	};
+}
+function applyTaskPlanUpdate(_previous, args, now = /* @__PURE__ */ new Date()) {
+	return {
+		items: planTodoArgsSchema.parse(args).items.map((item) => ({
+			text: item.text,
+			status: item.status
+		})),
+		updatedAt: now.toISOString()
+	};
+}
+function createTaskPlanController(initialState = createEmptyTaskPlanState(), now = () => /* @__PURE__ */ new Date()) {
+	let state = initialState;
+	return {
+		update(args) {
+			state = applyTaskPlanUpdate(state, args, now());
+			return state;
+		},
+		get() {
+			return state;
+		}
+	};
+}
+function summarizeTaskPlan(state) {
+	const pendingCount = state.items.filter((item) => item.status === "pending").length;
+	const inProgressCount = state.items.filter((item) => item.status === "in_progress").length;
+	const completedCount = state.items.filter((item) => item.status === "completed").length;
+	const currentItem = state.items.find((item) => item.status === "in_progress")?.text;
+	return {
+		pendingCount,
+		inProgressCount,
+		completedCount,
+		...currentItem === void 0 ? {} : { currentItem }
+	};
+}
+function hasOpenTaskPlan(state) {
+	return Boolean(state && state.items.some((item) => item.status !== "completed"));
+}
+function formatTaskPlanForPrompt(state) {
+	const summary = summarizeTaskPlan(state);
+	return [
+		"Plan updated",
+		`pending: ${summary.pendingCount}`,
+		`in_progress: ${summary.inProgressCount}`,
+		`completed: ${summary.completedCount}`,
+		summary.currentItem ? `current: ${summary.currentItem}` : ""
+	].filter(Boolean).join("\n");
+}
+function detectTaskPlanChange(previous, next) {
+	const hadPlan = Boolean(previous && previous.items.length > 0);
+	const hasPlan = Boolean(next && next.items.length > 0);
+	if (!hadPlan && hasPlan) return "created";
+	if (hadPlan && !hasPlan) return "cleared";
+	if (hadPlan && hasPlan) return "updated";
+	return "unchanged";
+}
+function formatTaskPlanNotice(change, state) {
+	if (change === "unchanged") return;
+	if (change === "cleared" || state.items.length === 0) return "todo plan cleared";
+	const summary = summarizeTaskPlan(state);
+	if (summary.inProgressCount === 0 && summary.pendingCount === 0) return "todo plan completed";
+	const prefix = change === "created" ? "todo plan created" : "todo plan updated";
+	return summary.currentItem ? `${prefix}: ${summary.currentItem}` : prefix;
+}
+function formatTaskPlanForTui(state, width, visibleLimit = 6) {
+	if (state.items.length === 0) return [];
+	const itemWidth = Math.max(1, Math.max(12, width) - 6);
+	const visibleItems = state.items.slice(0, visibleLimit);
+	const lines = visibleItems.map((item) => formatTaskPlanTuiLine(item, truncateText(item.text, itemWidth)));
+	const remaining = state.items.length - visibleItems.length;
+	if (remaining > 0) lines.push(ui.muted(`  +${remaining} more`));
+	return lines;
+}
+function formatTaskPlanTuiLine(item, text) {
+	switch (item.status) {
+		case "completed": return `  ${ui.ok("[x]")} ${ui.muted(text)}`;
+		case "in_progress": return `  ${ui.ok("[>]")} ${ui.ok(text)}`;
+		case "pending": return `  ${ui.muted("[ ]")} ${text}`;
+	}
+}
+function truncateText(text, width) {
+	if (text.length <= width) return text;
+	if (width <= 3) return ".".repeat(Math.max(0, width));
+	return `${text.slice(0, width - 3)}...`;
+}
+//#endregion
+//#region src/agent/tools/plan-todo.ts
+const planTodoTool = defineTool({
+	name: "plan_todo",
+	description: "Replace the visible session task plan for multi-step work.",
+	prompt: "plan_todo: replace the visible session task plan for non-trivial multi-step work; keep 2-6 short items, exactly one in_progress item while work remains, and use [] only to clear. To use it, reply with only JSON: {\"tool\":\"plan_todo\",\"args\":{\"items\":[{\"text\":\"Inspect relevant files\",\"status\":\"in_progress\"},{\"text\":\"Implement focused change\",\"status\":\"pending\"}]}}",
+	argsSchema: planTodoArgsSchema,
+	async execute(context, args) {
+		if (!context.taskPlan) throw new Error("plan_todo requires runtime task-plan state.");
+		const plan = context.taskPlan.update(args);
+		const summary = summarizeTaskPlan(plan);
+		return {
+			tool: "plan_todo",
+			content: formatTaskPlanForPrompt(plan),
+			plan,
+			...summary
+		};
+	}
+});
 const readFileTool = defineTool({
 	name: "read_file",
 	description: "Read a UTF-8 file inside the workspace.",
@@ -2333,14 +2671,14 @@ async function readWorkspaceFile(workspaceRoot, path) {
 }
 const writeFileTool = defineTool({
 	name: "write_file",
-	description: "Create a new UTF-8 file inside the workspace, or explicitly replace one with an expected hash.",
-	prompt: "write_file: create a new UTF-8 file inside the workspace by default; use edit_file for targeted changes to existing files, pass create_parent_dirs:true only when creating the folder path is intended, and replace an existing whole file only with overwrite:true and expected_hash from read_file. To use it, reply with only JSON: {\"tool\":\"write_file\",\"args\":{\"path\":\"test/example.test.ts\",\"content\":\"import { it, expect } from \\\"vitest\\\";\\n\\nit(\\\"works\\\", () => {\\n  expect(true).toBe(true);\\n});\\n\",\"create_parent_dirs\":true}}",
+	description: "Create a new UTF-8 file inside the workspace, or explicitly replace one. For overwrite:true, expected_current_hash must be the current/pre-write hash from read_file, never a predicted post-write hash.",
+	prompt: "write_file: create a new UTF-8 file inside the workspace by default; use edit_file for targeted changes to existing files; pass create_parent_dirs:true only when creating the folder path is intended. Replace an existing whole file only with overwrite:true and expected_current_hash set to the current/pre-write hash returned by the latest read_file for that file; never invent it or use a predicted after-write hash. To create a file, reply with only JSON: {\"tool\":\"write_file\",\"args\":{\"path\":\"test/example.test.ts\",\"content\":\"import { it, expect } from \\\"vitest\\\";\\n\\nit(\\\"works\\\", () => {\\n  expect(true).toBe(true);\\n});\\n\",\"create_parent_dirs\":true}}",
 	argsSchema: z.object({
-		path: z.string(),
-		content: z.string(),
-		create_parent_dirs: z.boolean().optional(),
-		overwrite: z.boolean().optional(),
-		expected_hash: z.string().optional()
+		path: z.string().describe("Workspace-relative path to write."),
+		content: z.string().describe("Complete UTF-8 file content to write."),
+		create_parent_dirs: z.boolean().optional().describe("Create missing parent directories only when that is explicitly intended."),
+		overwrite: z.boolean().optional().describe("Set true only for intentional whole-file replacement."),
+		expected_current_hash: z.string().optional().describe("Required with overwrite:true. Use the current file hash returned by the latest read_file result for this file. This is checked before writing and is not the hash after the write.")
 	}),
 	execute: (context, args) => writeWorkspaceFile(context.workspaceRoot, args, { logger: context.logger })
 });
@@ -2396,12 +2734,12 @@ async function writeWorkspaceFile(workspaceRoot, args, options = {}) {
 	});
 }
 async function overwriteExistingFile(workspaceRoot, scopedPath, args, existingTarget, options) {
-	if (!args.expected_hash) throw new Error(`write_file overwrite requires expected_hash for ${scopedPath.relativePath}.`);
+	if (!args.expected_current_hash) throw new Error(`write_file overwrite requires expected_current_hash for ${scopedPath.relativePath}.`);
 	if (!existingTarget) throw new Error(`write_file overwrite requires an existing file: ${scopedPath.relativePath}`);
 	if (!existingTarget.isFile()) throw new Error(`write_file overwrite requires a regular file: ${scopedPath.relativePath}`);
 	const beforeBytes = await readFile(scopedPath.path);
 	const beforeHash = hashBytes(beforeBytes);
-	if (args.expected_hash !== beforeHash) throw new Error(`write_file expected_hash did not match ${scopedPath.relativePath}.`);
+	if (args.expected_current_hash !== beforeHash) throw new Error(`write_file expected_current_hash did not match ${scopedPath.relativePath}.`);
 	const beforeLineCount = countLogicalLines$1(decodeUtf8(scopedPath.relativePath, beforeBytes));
 	const afterBytes = encodeUtf8Text(args.content);
 	const afterHash = hashBytes(afterBytes);
@@ -2543,6 +2881,7 @@ function isNodeError$2(error) {
 //#endregion
 //#region src/agent/tools/registry.ts
 const toolRegistry = {
+	[planTodoTool.name]: planTodoTool,
 	[readFileTool.name]: readFileTool,
 	[listFilesTool.name]: listFilesTool,
 	[grepTool.name]: grepTool,
@@ -2769,16 +3108,23 @@ var ModelGateway = class ModelGateway {
 	}
 	async generateText(request) {
 		const resolved = this.resolveModel(request.purpose);
+		const result = await generateText({
+			model: resolved.model,
+			system: request.system,
+			prompt: request.prompt,
+			abortSignal: request.abortSignal
+		});
+		const usage = normalizeUsage(result.usage, {
+			providerId: resolved.providerId,
+			providerConfig: resolved.providerConfig,
+			responseBody: result.response.body
+		});
 		return {
-			text: (await generateText({
-				model: resolved.model,
-				system: request.system,
-				prompt: request.prompt,
-				abortSignal: request.abortSignal
-			})).text,
+			text: result.text,
 			providerId: resolved.providerId,
 			modelId: resolved.modelId,
-			purpose: resolved.purpose
+			purpose: resolved.purpose,
+			...usage ? { usage } : {}
 		};
 	}
 	async generateAgentStep(request) {
@@ -2811,7 +3157,7 @@ var ModelGateway = class ModelGateway {
 			}
 			return result;
 		} catch (error) {
-			const reason = formatErrorMessage$1(error);
+			const reason = formatErrorMessage$2(error);
 			attempts.push({
 				protocol: "native-openai-compatible",
 				status: "failed",
@@ -2847,6 +3193,11 @@ var ModelGateway = class ModelGateway {
 			providerOptions,
 			abortSignal: request.abortSignal
 		});
+		const usage = normalizeUsage(result.usage, {
+			providerId: resolved.providerId,
+			providerConfig: resolved.providerConfig,
+			responseBody: result.response.body
+		});
 		const toolCalls = result.toolCalls.map((call, index) => {
 			const parsed = parseNativeToolCall(call.toolName, call.input);
 			if (!parsed) throw new Error(`Native tool call for ${call.toolName} did not match the registered schema.`);
@@ -2866,6 +3217,7 @@ var ModelGateway = class ModelGateway {
 			providerId: resolved.providerId,
 			modelId: resolved.modelId,
 			purpose: resolved.purpose,
+			...usage ? { usage } : {},
 			toolCalls,
 			toolProtocol: "native-openai-compatible",
 			protocolAttempts: attempts,
@@ -2881,6 +3233,11 @@ var ModelGateway = class ModelGateway {
 			prompt: request.prompt,
 			abortSignal: request.abortSignal
 		});
+		const usage = normalizeUsage(result.usage, {
+			providerId: resolved.providerId,
+			providerConfig: resolved.providerConfig,
+			responseBody: result.response.body
+		});
 		const parsed = parseToolCallWithSource(result.text, allowedSources);
 		const defaultProtocol = allowedSources.length === 1 && allowedSources[0] === "text-xml" ? "text-xml" : "text-json";
 		const toolProtocol = parsed?.source === "text-xml" ? "text-xml" : parsed ? "text-json" : defaultProtocol;
@@ -2894,6 +3251,7 @@ var ModelGateway = class ModelGateway {
 			providerId: resolved.providerId,
 			modelId: resolved.modelId,
 			purpose: resolved.purpose,
+			...usage ? { usage } : {},
 			toolCalls: parsed ? [{
 				id: `${parsed.source}-0`,
 				tool: parsed.call.tool,
@@ -2922,6 +3280,9 @@ function buildNativeProviderOptions(providerId, config) {
 function shouldApplyOpenRouterRoutingOptions(providerId, config) {
 	if (config.openRouterToolRouting === "force") return true;
 	if (config.openRouterToolRouting === "off") return false;
+	return isOpenRouterProvider(providerId, config);
+}
+function isOpenRouterProvider(providerId, config) {
 	return providerId.toLowerCase().includes("openrouter") || config.baseURL.toLowerCase().includes("openrouter.ai");
 }
 function hasOpenRouterRoutingOptions(providerOptions, providerId) {
@@ -2929,14 +3290,32 @@ function hasOpenRouterRoutingOptions(providerOptions, providerId) {
 	return Boolean(options && typeof options === "object" && "provider" in options);
 }
 function isNativeToolFallbackError(error) {
-	const message = formatErrorMessage$1(error).toLowerCase();
+	const message = formatErrorMessage$2(error).toLowerCase();
 	return message.includes("tool") || message.includes("function") || message.includes("parallel_tool_calls") || message.includes("tool_choice") || message.includes("requested parameters") || message.includes("provider routing") || message.includes("provider-selection") || message.includes("invalid request");
 }
 function extractWarningMessages(warnings) {
 	if (!Array.isArray(warnings)) return [];
-	return warnings.map((warning) => formatErrorMessage$1(warning));
+	return warnings.map((warning) => formatErrorMessage$2(warning));
+}
+function normalizeUsage(usage, context) {
+	const costUsd = context && isOpenRouterProvider(context.providerId, context.providerConfig) ? extractOpenRouterCost(context.responseBody) : void 0;
+	if (!usage) return costUsd === void 0 ? void 0 : { costUsd };
+	const normalized = {
+		...typeof usage.inputTokens === "number" ? { inputTokens: usage.inputTokens } : {},
+		...typeof usage.outputTokens === "number" ? { outputTokens: usage.outputTokens } : {},
+		...typeof usage.totalTokens === "number" ? { totalTokens: usage.totalTokens } : {},
+		...costUsd === void 0 ? {} : { costUsd }
+	};
+	return Object.keys(normalized).length > 0 ? normalized : void 0;
 }
-function formatErrorMessage$1(error) {
+function extractOpenRouterCost(responseBody) {
+	if (!responseBody || typeof responseBody !== "object") return;
+	const usage = responseBody.usage;
+	if (!usage || typeof usage !== "object") return;
+	const cost = usage.cost;
+	return typeof cost === "number" && Number.isFinite(cost) ? cost : void 0;
+}
+function formatErrorMessage$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
@@ -2946,8 +3325,6 @@ const modelPurposeSchema = z.enum([
 	"agent.fast",
 	"kb.scan",
 	"kb.summarize",
-	"kb.extract",
-	"kb.embed",
 	"fallback"
 ]);
 const modelPurposes = modelPurposeSchema.options;
@@ -3042,7 +3419,7 @@ function readConfigFile(path) {
 	try {
 		return parse(readFileSync(path, "utf8"));
 	} catch (error) {
-		throw new Error(`Invalid Topchester config at ${path}: ${formatErrorMessage(error)}`);
+		throw new Error(`Invalid Topchester config at ${path}: ${formatErrorMessage$1(error)}`);
 	}
 }
 function parseConfigFile(path, value) {
@@ -3078,6 +3455,7 @@ function normalizeConfigInput(value) {
 		ensureKnownProvider(providers, kbSummarizeModelRef.provider);
 		delete models["kb.summarize"];
 	}
+	applyKnownProviderDefaults(providers);
 	return {
 		...value,
 		models: {
@@ -3134,6 +3512,20 @@ function ensureKnownProvider(providers, provider) {
 		}
 	};
 }
+function applyKnownProviderDefaults(providers) {
+	for (const [providerId, provider] of Object.entries(providers)) {
+		if (!isPlainObject(provider) || provider.type !== "openai-compatible" || typeof provider.baseURL !== "string") continue;
+		if (isOpenAIProvider(providerId, provider.baseURL)) {
+			provider.supportsStructuredOutputs ??= true;
+			provider.toolProtocol ??= "native";
+		}
+	}
+}
+function isOpenAIProvider(providerId, baseURL) {
+	const normalizedProvider = providerId.toLowerCase();
+	const normalizedBaseURL = baseURL.toLowerCase();
+	return normalizedProvider === "openai" || normalizedProvider === "gpt" || normalizedProvider.includes("openai") || normalizedBaseURL.includes("api.openai.com");
+}
 function deepMerge(base, override, path = []) {
 	if (Array.isArray(base) && Array.isArray(override)) return path.join(".") === "ignore.paths" ? [...base, ...override] : override;
 	if (!isPlainObject(base) || !isPlainObject(override)) return override;
@@ -3147,7 +3539,7 @@ function isPlainObject(value) {
 function formatZodIssue(issue) {
 	return `${issue.path.length > 0 ? issue.path.join(".") : "<root>"}: ${issue.message}`;
 }
-function formatErrorMessage(error) {
+function formatErrorMessage$1(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
@@ -3241,107 +3633,6 @@ function normalizeModelGatewayConfig(config) {
 	};
 }
 //#endregion
-//#region src/cli/ui.ts
-const colors = {
-	bgSoftGray: "\x1B[48;5;236m",
-	blue: "\x1B[34m",
-	cyan: "\x1B[36m",
-	darkGray: "\x1B[90m",
-	dim: "\x1B[2m",
-	green: "\x1B[32m",
-	orange: "\x1B[38;5;208m",
-	purple: "\x1B[35m",
-	red: "\x1B[31m",
-	reset: "\x1B[0m",
-	resetForeground: "\x1B[39m",
-	yellow: "\x1B[33m"
-};
-const ui = {
-	heading(text) {
-		return color(`Topchester ${text}`, "cyan");
-	},
-	label(text) {
-		return color(text, "dim");
-	},
-	muted(text) {
-		return color(text, "darkGray");
-	},
-	model(text) {
-		return color(text, "blue");
-	},
-	modelInline(text) {
-		if (!shouldUseColor()) return text;
-		return `${colors.blue}${text}${colors.resetForeground}`;
-	},
-	ok(text) {
-		return color(text, "green");
-	},
-	warn(text) {
-		return color(text, "yellow");
-	},
-	error(text) {
-		return color(text, "red");
-	},
-	softBackground(text) {
-		return color(text, "bgSoftGray");
-	},
-	async spinner(text, action) {
-		return withStatusLine(text, action, void 0, 80, false);
-	},
-	async progress(text, action) {
-		let latest = text;
-		return withStatusLine(text, () => action((message) => {
-			latest = message;
-		}), () => latest, 80, true);
-	}
-};
-async function withStatusLine(text, action, getText = () => text, progressEveryMs = 80, emitPlainProgress = false) {
-	if (!shouldUseColor()) {
-		if (!emitPlainProgress) return action();
-		const timer = setInterval(() => {
-			stderr.write(`${getText()}\n`);
-		}, Math.max(progressEveryMs, 5e3));
-		try {
-			return await action();
-		} finally {
-			clearInterval(timer);
-		}
-	}
-	const frames = [
-		"⠋",
-		"⠙",
-		"⠹",
-		"⠸",
-		"⠼",
-		"⠴",
-		"⠦",
-		"⠧",
-		"⠇",
-		"⠏"
-	];
-	let index = 0;
-	stderr.write(`${color(frames[index], "cyan")} ${getText()}`);
-	const timer = setInterval(() => {
-		index = (index + 1) % frames.length;
-		stderr.write(`\r\u001b[2K${color(frames[index], "cyan")} ${getText()}`);
-	}, progressEveryMs);
-	try {
-		return await action();
-	} finally {
-		clearInterval(timer);
-		stderr.write(`\r\u001b[2K`);
-	}
-}
-function color(text, colorName) {
-	if (!shouldUseColor()) return text;
-	return `${colors[colorName]}${text}${colors.reset}`;
-}
-function shouldUseColor() {
-	if (process.env.NO_COLOR) return false;
-	if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") return true;
-	return stdout.isTTY === true;
-}
-//#endregion
 //#region src/knowledge/status.ts
 function getKnowledgeStatus(workspaceRoot) {
 	const kbPathSource = process.env.TOPCHESTER_KB_DIR ? "env" : "default";
@@ -3674,6 +3965,14 @@ const l1ConfidenceLevels = [
 	"medium",
 	"high"
 ];
+const l1FileRoles = [
+	"source",
+	"test",
+	"config",
+	"doc",
+	"script",
+	"unknown"
+];
 const nonEmptyStringSchema = z.string().min(1);
 const sha256HashSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
 const isoUtcTimestampSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/).refine((value) => !Number.isNaN(Date.parse(value)), { message: "Expected a valid UTC ISO timestamp" });
@@ -3685,7 +3984,7 @@ const l1FileSymbolSchema = z.object({
 	kind: nonEmptyStringSchema,
 	name: nonEmptyStringSchema,
 	exported: z.boolean(),
-	summary: nonEmptyStringSchema
+	summary: nonEmptyStringSchema.optional()
 }).strict();
 const l1FileEvidenceSchema = z.object({
 	kind: nonEmptyStringSchema,
@@ -3702,6 +4001,7 @@ const l1FileEntrySchema = z.object({
 	size_bytes: z.number().int().nonnegative(),
 	last_scanned_at: isoUtcTimestampSchema,
 	scan_status: z.enum(l1FileScanStatuses),
+	file_role: z.enum(l1FileRoles).default("unknown"),
 	summary: nonEmptyStringSchema,
 	responsibilities: z.array(nonEmptyStringSchema),
 	symbols: z.array(l1FileSymbolSchema),
@@ -3710,6 +4010,9 @@ const l1FileEntrySchema = z.object({
 	module_ids: z.array(l1ModuleIdSchema),
 	feature_ids: z.array(l1FeatureIdSchema),
 	test_ids: z.array(l1FileIdSchema),
+	declared_test_targets: z.array(l1FileIdSchema).default([]),
+	likely_test_targets: z.array(l1FileIdSchema).default([]),
+	tested_by: z.array(l1FileIdSchema).default([]),
 	evidence: z.array(l1FileEvidenceSchema),
 	confidence: z.enum(l1ConfidenceLevels)
 }).strict().refine((entry) => entry.id === `file:${entry.path}`, {
@@ -3777,6 +4080,123 @@ function formatCountProgress(label, completed, total, detail) {
 	return `${label} [${formatProgressBar(safeCompleted, safeTotal)}] ${safeCompleted}/${safeTotal} (${percent}%)${suffix}`;
 }
 //#endregion
+//#region src/knowledge/compiler/l1-postprocess.ts
+async function postProcessL1Entries(kbPath) {
+	const entries = await loadL1Entries(kbPath);
+	const entriesById = new Map(entries.map(({ entry }) => [entry.id, entry]));
+	const entriesByPath = new Map(entries.map(({ entry }) => [entry.path, entry]));
+	const testTargetsById = /* @__PURE__ */ new Map();
+	for (const { entry } of entries) {
+		if (inferL1FileRole(entry.path) !== "test") {
+			testTargetsById.set(entry.id, {
+				declared: [],
+				likely: []
+			});
+			continue;
+		}
+		const declared = dedupeStrings$1([...entry.declared_test_targets.filter((id) => isExistingNonSelfFileId(id, entry.id, entriesById)), ...entry.imports.filter((id) => isExistingNonSelfFileId(id, entry.id, entriesById))]);
+		const likely = dedupeStrings$1([...entry.likely_test_targets.filter((id) => isExistingNonSelfFileId(id, entry.id, entriesById)), ...inferLikelyTestTargets(entry.path, entriesByPath)]);
+		testTargetsById.set(entry.id, {
+			declared,
+			likely
+		});
+	}
+	const testedBy = /* @__PURE__ */ new Map();
+	for (const [testId, links] of testTargetsById) for (const targetId of dedupeStrings$1([...links.declared, ...links.likely])) {
+		const list = testedBy.get(targetId) ?? [];
+		list.push(testId);
+		testedBy.set(targetId, list);
+	}
+	let entriesUpdated = 0;
+	let testLinksAdded = 0;
+	for (const { entry, entryPath } of entries) {
+		const fileRole = inferL1FileRole(entry.path);
+		const links = testTargetsById.get(entry.id) ?? {
+			declared: [],
+			likely: []
+		};
+		const nextEntry = parseL1FileEntry({
+			...entry,
+			file_role: fileRole,
+			declared_test_targets: links.declared,
+			likely_test_targets: links.likely,
+			tested_by: dedupeStrings$1(testedBy.get(entry.id) ?? []).sort()
+		});
+		testLinksAdded += nextEntry.declared_test_targets.length + nextEntry.likely_test_targets.length + nextEntry.tested_by.length;
+		if (JSON.stringify(nextEntry) !== JSON.stringify(entry)) {
+			await writeFile(entryPath, `${JSON.stringify(nextEntry, null, 2)}\n`);
+			entriesUpdated += 1;
+		}
+	}
+	return {
+		entriesRead: entries.length,
+		entriesUpdated,
+		testLinksAdded
+	};
+}
+function inferL1FileRole(path) {
+	const lowerPath = path.toLowerCase();
+	const name = basename(lowerPath);
+	if (isTestPath(lowerPath)) return "test";
+	if (lowerPath.startsWith("scripts/") || lowerPath.startsWith("script/") || lowerPath.endsWith(".sh")) return "script";
+	if (lowerPath.endsWith(".md") || lowerPath.endsWith(".mdx") || lowerPath.startsWith("docs/")) return "doc";
+	if (name === "package.json" || name.endsWith("lock.json") || name.endsWith("-lock.yaml") || name.endsWith(".config.ts") || name.endsWith(".config.js") || name.endsWith(".config.mjs") || name.endsWith(".config.cjs") || name === "tsconfig.json" || name.startsWith(".")) return "config";
+	if (/\.(ts|tsx|js|jsx|mts|cts)$/.test(lowerPath)) return "source";
+	return "unknown";
+}
+async function loadL1Entries(kbPath) {
+	const entryPaths = await listJsonFiles$1(join(kbPath, "l1-files")).catch((error) => {
+		if (isFileNotFoundError$3(error)) return [];
+		throw error;
+	});
+	const entries = [];
+	for (const entryPath of entryPaths) entries.push({
+		entryPath,
+		entry: parseL1FileEntry(JSON.parse(await readFile(entryPath, "utf8")))
+	});
+	return entries.sort((a, b) => a.entry.path.localeCompare(b.entry.path));
+}
+async function listJsonFiles$1(directory) {
+	const entries = await readdir(directory, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		const entryPath = join(directory, entry.name);
+		if (entry.isDirectory()) files.push(...await listJsonFiles$1(entryPath));
+		else if (entry.isFile() && entry.name.endsWith(".json")) files.push(entryPath);
+	}
+	return files.sort();
+}
+function inferLikelyTestTargets(testPath, entriesByPath) {
+	const candidates = /* @__PURE__ */ new Set();
+	const sourceLikePath = removeTestSuffix(testPath);
+	candidates.add(sourceLikePath);
+	for (const prefix of [
+		"test/",
+		"tests/",
+		"__tests__/"
+	]) if (testPath.startsWith(prefix)) candidates.add(`src/${removeTestSuffix(testPath.slice(prefix.length))}`);
+	if (testPath.includes("/__tests__/")) candidates.add(removeTestSuffix(testPath.replace("/__tests__/", "/")));
+	return [...candidates].filter((candidate) => candidate !== testPath).flatMap((candidate) => {
+		const entry = entriesByPath.get(candidate);
+		return entry ? [entry.id] : [];
+	});
+}
+function removeTestSuffix(path) {
+	return path.replace(/\.(test|spec)(\.[^./]+)$/i, "$2");
+}
+function isTestPath(path) {
+	return /\.(test|spec)\.(ts|tsx|js|jsx|mts|cts)$/.test(path) || path.startsWith("test/") || path.startsWith("tests/") || path.startsWith("__tests__/") || path.includes("/__tests__/");
+}
+function isExistingNonSelfFileId(id, selfId, entriesById) {
+	return id !== selfId && entriesById.has(id);
+}
+function dedupeStrings$1(values) {
+	return [...new Set(values)];
+}
+function isFileNotFoundError$3(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
 //#region src/knowledge/compiler/manifest.ts
 const knowledgeCompilerIdentity = {
 	name: "topchester-knowledge-compiler",
@@ -3819,6 +4239,8 @@ async function processL1Queue(options) {
 		await persistQueue(options.queuePath, queuedFiles, now().toISOString());
 		options.onProgress?.({ message: formatL1ProgressMessage("Processing L1 files", index + 1, queuedFiles.length, item.path) });
 	}
+	options.onProgress?.({ message: "Linking L1 file relationships..." });
+	await postProcessL1Entries(options.kbPath);
 	const summary = await summarizeL1Queue(options.kbPath, queuedFiles);
 	await writeManifest(options, summary, now().toISOString());
 	return {
@@ -3878,7 +4300,11 @@ async function processL1QueueItem(options) {
 }
 function buildL1FileEntrySystemPrompt() {
 	return [
-		"You summarize one repository file for Topchester's L1 knowledge base.",
+		"You create concise, structured repository knowledge for one file.",
+		"Prefer concrete facts visible in the file over generic descriptions.",
+		"Do not invent modules, features, tests, routes, or dependencies.",
+		"If uncertain, leave arrays empty and use lower confidence.",
+		"Avoid filler such as \"This file contains code\" or \"Symbol named X\".",
 		"Return exactly one JSON object and no markdown.",
 		"Do not include secrets, credentials, or raw provider payloads."
 	].join("\n");
@@ -3887,6 +4313,35 @@ function buildL1FileEntryPrompt(input) {
 	return [
 		"Create an L1 file entry for this workspace-relative path.",
 		"The compiler will overwrite id, path, content_hash, size_bytes, last_scanned_at, and scan_status.",
+		"",
+		"Extraction rules:",
+		"- summary: one specific sentence about the file's role in this project.",
+		"- responsibilities: 2-6 concrete responsibilities, no duplicates, no generic boilerplate.",
+		"- symbols: important declared or exported interfaces, types, classes, functions, constants, schemas, commands, routes, React components, tests, or config objects.",
+		"  For each symbol, set:",
+		"  - kind: interface | type | class | function | const | component | schema | command | route | test | config | symbol",
+		"  - name: exact identifier or stable label",
+		"  - exported: true only when exported from this file",
+		"  - summary: include only if it adds useful meaning beyond the name",
+		"- imports: only workspace-local file dependencies as file:<path>; omit packages and built-ins.",
+		"- exports: exact exported names from this file as strings.",
+		"- test_ids: only file:<path> when this file is clearly a test or clearly references a test target.",
+		"- file_role: source | test | config | doc | script | unknown.",
+		"- declared_test_targets: for test files, file:<path> entries that this test directly imports or names.",
+		"- likely_test_targets: for test files, file:<path> entries likely covered by path/name convention.",
+		"- tested_by: leave empty; the compiler fills reverse test links after all files are processed.",
+		"- module_ids and feature_ids: leave empty unless there is strong evidence.",
+		"- evidence: include at least { \"kind\": \"path\", \"value\": \"<path>\" } and any high-signal local evidence.",
+		"- confidence: high for simple files with clear structure, medium for normal files, low for vague/generated/config-heavy files.",
+		"",
+		"Quality rules:",
+		"- Return valid JSON only.",
+		"- Keep arrays concise.",
+		"- Deduplicate all arrays.",
+		"- Prefer exact names from source.",
+		"- Do not copy large code snippets.",
+		"- Do not include secrets or raw credentials.",
+		"",
 		"Use this JSON shape:",
 		JSON.stringify({
 			$schema: l1FileEntrySchemaPath,
@@ -3899,6 +4354,7 @@ function buildL1FileEntryPrompt(input) {
 			size_bytes: 0,
 			last_scanned_at: "2026-05-11T00:00:00Z",
 			scan_status: "current",
+			file_role: "source",
 			summary: "One clear sentence.",
 			responsibilities: ["What this file owns or does."],
 			symbols: [],
@@ -3907,6 +4363,9 @@ function buildL1FileEntryPrompt(input) {
 			module_ids: [],
 			feature_ids: [],
 			test_ids: [],
+			declared_test_targets: [],
+			likely_test_targets: [],
+			tested_by: [],
 			evidence: [{
 				kind: "path",
 				value: "<path>"
@@ -3944,41 +4403,49 @@ function normalizeL1FileEntry(value, deterministic) {
 }
 function normalizeModelOwnedL1Fields(value, path) {
 	const record = value;
+	const exports = normalizeStringArray(record.exports);
 	return {
 		...record,
+		file_role: inferL1FileRole(path),
 		responsibilities: normalizeStringArray(record.responsibilities),
-		symbols: normalizeSymbols(record.symbols, path),
+		symbols: normalizeSymbols(record.symbols, path, exports),
 		imports: normalizePrefixedIds(record.imports, "file:"),
-		exports: normalizeStringArray(record.exports),
+		exports,
 		module_ids: normalizePrefixedIds(record.module_ids, "module:"),
 		feature_ids: normalizePrefixedIds(record.feature_ids, "feature:"),
 		test_ids: normalizePrefixedIds(record.test_ids, "file:"),
+		declared_test_targets: normalizePrefixedIds(record.declared_test_targets, "file:"),
+		likely_test_targets: normalizePrefixedIds(record.likely_test_targets, "file:"),
+		tested_by: normalizePrefixedIds(record.tested_by, "file:"),
 		evidence: normalizeEvidence(record.evidence)
 	};
 }
 function normalizeStringArray(value) {
 	if (!Array.isArray(value)) return [];
-	return value.filter((item) => typeof item === "string" && item.trim().length > 0);
+	return dedupeStrings(value.filter((item) => typeof item === "string").map((item) => item.trim()));
 }
 function normalizePrefixedIds(value, prefix) {
 	return normalizeStringArray(value).filter((item) => item.startsWith(prefix));
 }
 function normalizeEvidence(value) {
 	if (!Array.isArray(value)) return [];
-	return value.flatMap((item) => {
+	return dedupeRecords(value.flatMap((item) => {
 		if (!item || typeof item !== "object" || Array.isArray(item)) return [];
 		const record = item;
-		if (typeof record.kind !== "string" || record.kind.trim().length === 0) return [];
-		if (typeof record.value !== "string" || record.value.trim().length === 0) return [];
+		const kind = typeof record.kind === "string" ? record.kind.trim() : "";
+		const recordValue = typeof record.value === "string" ? record.value.trim() : "";
+		if (kind.length === 0) return [];
+		if (recordValue.length === 0) return [];
 		return [{
-			kind: record.kind,
-			value: record.value
+			kind,
+			value: recordValue
 		}];
-	});
+	}), (item) => `${item.kind}\0${item.value}`);
 }
-function normalizeSymbols(value, path) {
+function normalizeSymbols(value, path, exports) {
 	if (!Array.isArray(value)) return [];
-	return value.flatMap((item) => {
+	const exportedNames = new Set(exports);
+	return dedupeRecords(value.flatMap((item) => {
 		if (typeof item === "string") {
 			const name = item.trim();
 			if (!name || !path) return [];
@@ -3986,8 +4453,7 @@ function normalizeSymbols(value, path) {
 				id: `symbol:${path}#${name}`,
 				kind: "symbol",
 				name,
-				exported: false,
-				summary: `Symbol named ${name}.`
+				exported: exportedNames.has(name)
 			}];
 		}
 		if (!item || typeof item !== "object" || Array.isArray(item)) return [];
@@ -3995,14 +4461,36 @@ function normalizeSymbols(value, path) {
 		const rawId = typeof record.id === "string" && record.id.startsWith("symbol:") ? record.id : void 0;
 		const name = typeof record.name === "string" && record.name.trim().length > 0 ? record.name : rawId?.slice(rawId.lastIndexOf("#") + 1);
 		if (!name || !path) return [];
-		return [{
+		const summary = typeof record.summary === "string" && record.summary.trim().length > 0 ? record.summary.trim() : "";
+		return [removeUndefinedValues({
 			id: rawId ?? `symbol:${path}#${name}`,
-			kind: typeof record.kind === "string" && record.kind.trim().length > 0 ? record.kind : "symbol",
+			kind: typeof record.kind === "string" && record.kind.trim().length > 0 ? record.kind.trim() : "symbol",
 			name,
-			exported: typeof record.exported === "boolean" ? record.exported : false,
-			summary: typeof record.summary === "string" && record.summary.trim().length > 0 ? record.summary : `Symbol named ${name}.`
-		}];
-	});
+			exported: exportedNames.has(name) || (typeof record.exported === "boolean" ? record.exported : false),
+			summary: summary && !isGenericSymbolSummary$1(summary, name) ? summary : void 0
+		})];
+	}), (item) => String(item.id));
+}
+function dedupeStrings(values) {
+	return [...new Set(values.filter((value) => value.length > 0))];
+}
+function dedupeRecords(values, keyFor) {
+	const seen = /* @__PURE__ */ new Set();
+	const deduped = [];
+	for (const value of values) {
+		const key = keyFor(value);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		deduped.push(value);
+	}
+	return deduped;
+}
+function removeUndefinedValues(record) {
+	return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== void 0));
+}
+function isGenericSymbolSummary$1(summary, name) {
+	const normalizedSummary = summary.trim().replace(/\s+/g, " ");
+	return normalizedSummary === `Symbol named ${name}.` || normalizedSummary === `Symbol named ${name}` || normalizedSummary === name;
 }
 function extractTopLevelJsonObjects(text) {
 	const objects = [];
@@ -4404,11 +4892,11 @@ async function getL1SyncStatus(kbPath, kbReady, file) {
 		if (entry.path !== file.path || entry.size_bytes !== file.sizeBytes || entry.content_hash !== file.hash) return "changed";
 		return entry.scan_status;
 	} catch (error) {
-		if (isFileNotFoundError$1(error)) return "missing_entry";
+		if (isFileNotFoundError$2(error)) return "missing_entry";
 		return "invalid";
 	}
 }
-function isFileNotFoundError$1(error) {
+function isFileNotFoundError$2(error) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
 function assertKbSummarizeModelConfigured(model) {
@@ -4522,6 +5010,430 @@ function isNodeError(error) {
 	return error instanceof Error && "code" in error;
 }
 //#endregion
+//#region src/knowledge/search.ts
+var L1InMemoryIndex = class {
+	entriesById = /* @__PURE__ */ new Map();
+	postingsByToken = /* @__PURE__ */ new Map();
+	prefixTokensByPrefix = /* @__PURE__ */ new Map();
+	constructor(entries) {
+		for (const entry of entries) {
+			this.entriesById.set(entry.id, entry);
+			this.indexEntry(entry);
+		}
+		this.indexPrefixTokens();
+	}
+	get size() {
+		return this.entriesById.size;
+	}
+	search(query, options = {}) {
+		const tokens = tokenizeQuery(query);
+		const scoresByEntryId = /* @__PURE__ */ new Map();
+		const reasonsByEntryId = /* @__PURE__ */ new Map();
+		for (const token of tokens) {
+			this.addMatches(token, 1, scoresByEntryId, reasonsByEntryId);
+			if (token.length >= 4) this.addPrefixMatches(token, scoresByEntryId, reasonsByEntryId);
+		}
+		const limit = options.limit ?? 10;
+		return [...scoresByEntryId.entries()].map(([entryId, score]) => {
+			const entry = this.entriesById.get(entryId);
+			if (!entry) return;
+			return {
+				id: entry.id,
+				path: entry.path,
+				score: Math.round(score * 100) / 100,
+				summary: entry.summary,
+				contentHash: entry.content_hash,
+				scanStatus: entry.scan_status,
+				reasons: [...(reasonsByEntryId.get(entryId) ?? /* @__PURE__ */ new Map()).entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([reason]) => reason).slice(0, 6)
+			};
+		}).filter((match) => Boolean(match)).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)).slice(0, limit);
+	}
+	getEntry(id) {
+		return this.entriesById.get(id);
+	}
+	indexEntry(entry) {
+		this.addField(entry, "path", [entry.path, basename(entry.path)], 6);
+		this.addField(entry, "symbol", entry.symbols.flatMap((symbol) => [
+			symbol.name,
+			symbol.kind,
+			symbol.summary
+		].filter(isString)), 10);
+		this.addField(entry, "export", entry.exports, 9);
+		this.addField(entry, "responsibility", entry.responsibilities, 6);
+		this.addField(entry, "summary", [entry.summary], 5);
+		this.addField(entry, "import", entry.imports, 4);
+		this.addField(entry, "test", entry.test_ids, 4);
+		this.addField(entry, "relationship", [...entry.module_ids, ...entry.feature_ids], 3);
+		this.addField(entry, "evidence", entry.evidence.map((evidence) => evidence.value), 3);
+	}
+	addField(entry, field, values, weight) {
+		const tokens = new Set(values.flatMap(tokenizeText));
+		for (const token of tokens) {
+			const postings = this.postingsByToken.get(token) ?? [];
+			postings.push({
+				entryId: entry.id,
+				weight,
+				reason: `${formatField(field)} matched ${token}`
+			});
+			this.postingsByToken.set(token, postings);
+		}
+	}
+	addMatches(token, multiplier, scoresByEntryId, reasonsByEntryId) {
+		for (const posting of this.postingsByToken.get(token) ?? []) {
+			scoresByEntryId.set(posting.entryId, (scoresByEntryId.get(posting.entryId) ?? 0) + posting.weight * multiplier);
+			const reasons = reasonsByEntryId.get(posting.entryId) ?? /* @__PURE__ */ new Map();
+			reasons.set(posting.reason, Math.max(reasons.get(posting.reason) ?? 0, posting.weight * multiplier));
+			reasonsByEntryId.set(posting.entryId, reasons);
+		}
+	}
+	addPrefixMatches(token, scoresByEntryId, reasonsByEntryId) {
+		const matchedTokens = /* @__PURE__ */ new Set();
+		for (const indexedToken of this.prefixTokensByPrefix.get(token) ?? []) matchedTokens.add(indexedToken);
+		for (let prefixLength = 1; prefixLength < token.length; prefixLength += 1) {
+			const prefix = token.slice(0, prefixLength);
+			if (this.postingsByToken.has(prefix)) matchedTokens.add(prefix);
+		}
+		for (const indexedToken of matchedTokens) {
+			if (indexedToken === token) continue;
+			this.addMatches(indexedToken, .6, scoresByEntryId, reasonsByEntryId);
+		}
+	}
+	indexPrefixTokens() {
+		for (const indexedToken of this.postingsByToken.keys()) for (let prefixLength = 4; prefixLength < indexedToken.length; prefixLength += 1) {
+			const prefix = indexedToken.slice(0, prefixLength);
+			const tokens = this.prefixTokensByPrefix.get(prefix) ?? [];
+			tokens.push(indexedToken);
+			this.prefixTokensByPrefix.set(prefix, tokens);
+		}
+	}
+};
+function buildL1InMemoryIndex(entries) {
+	return new L1InMemoryIndex(entries);
+}
+async function searchL1Knowledge(workspaceRoot, query, options = {}) {
+	const status = getKnowledgeStatus(workspaceRoot);
+	if (!status.kbExists || !status.kbIsDirectory) throw new Error("Run `topchester kb init` and `topchester kb compile` before searching the knowledge base.");
+	const loadResult = await loadL1FileEntries(status.kbPath);
+	const index = buildL1InMemoryIndex(loadResult.entries);
+	return {
+		workspaceRoot,
+		kbPath: status.kbPath,
+		query,
+		entryCount: index.size,
+		invalidEntryCount: loadResult.invalidEntryCount,
+		matches: index.search(query, options)
+	};
+}
+function createL1ContextPackFromIndex(source, query, options = {}) {
+	const limit = options.limit ?? 8;
+	const minScore = options.minScore ?? 12;
+	const relevantFiles = source.index.search(query, { limit: Math.max(limit * 3, limit) }).filter((match) => match.score >= minScore).slice(0, limit).map((match) => {
+		const entry = source.index.getEntry(match.id);
+		if (!entry) return;
+		return {
+			id: match.id,
+			path: match.path,
+			score: match.score,
+			reasons: match.reasons,
+			contentHash: match.contentHash,
+			scanStatus: match.scanStatus,
+			l1: compactL1Entry(entry),
+			fullL1: options.includeFullL1 ? entry : void 0
+		};
+	}).filter((file) => Boolean(file));
+	const warnings = relevantFiles.length === 0 ? ["No L1 entries met the context pack score threshold."] : [];
+	return {
+		workspaceRoot: source.workspaceRoot,
+		kbPath: source.kbPath,
+		query,
+		entryCount: source.index.size,
+		invalidEntryCount: source.invalidEntryCount,
+		selection: {
+			limit,
+			minScore
+		},
+		drift: {
+			status: "unchecked",
+			warnings: ["L1 context pack includes stored scan statuses; exact file-hash drift check has not run yet."]
+		},
+		summary: summarizeContextPack(query, relevantFiles),
+		warnings,
+		relevantFiles
+	};
+}
+async function createL1ContextPack(workspaceRoot, query, options = {}) {
+	const limit = options.limit ?? 8;
+	const minScore = options.minScore ?? 12;
+	const status = getKnowledgeStatus(workspaceRoot);
+	if (!status.kbExists || !status.kbIsDirectory) throw new Error("Run `topchester kb init` and `topchester kb compile` before creating a context pack.");
+	const loadResult = await loadL1FileEntries(status.kbPath);
+	const index = buildL1InMemoryIndex(loadResult.entries);
+	return createL1ContextPackFromIndex({
+		workspaceRoot,
+		kbPath: status.kbPath,
+		index,
+		invalidEntryCount: loadResult.invalidEntryCount
+	}, query, {
+		limit,
+		minScore,
+		includeFullL1: options.includeFullL1
+	});
+}
+function formatL1KnowledgeSearchResult(result) {
+	return [
+		"KB search",
+		`workspace: ${result.workspaceRoot}`,
+		`knowledge folder: ${result.kbPath} [ok]`,
+		`query: ${result.query}`,
+		`entries indexed: ${result.entryCount}`,
+		`invalid L1 entries skipped: ${result.invalidEntryCount}`,
+		`matches: ${result.matches.length}`,
+		...result.matches.length === 0 ? ["state: no L1 matches found"] : [""],
+		...result.matches.flatMap((match) => [
+			`${match.score}\t${match.path}\t${match.scanStatus}\t${match.contentHash}`,
+			`  reasons: ${match.reasons.join("; ") || "score match"}`,
+			`  summary: ${match.summary}`
+		]),
+		"----",
+		`total matches: ${result.matches.length}`
+	];
+}
+function formatL1ContextPackResult(result) {
+	return [
+		"KB context",
+		`workspace: ${result.workspaceRoot}`,
+		`knowledge folder: ${result.kbPath} [ok]`,
+		`query: ${result.query}`,
+		`entries indexed: ${result.entryCount}`,
+		`invalid L1 entries skipped: ${result.invalidEntryCount}`,
+		`selection: top ${result.selection.limit}, min score ${result.selection.minScore}`,
+		`drift: ${result.drift.status}`,
+		`relevant files: ${result.relevantFiles.length}`,
+		`summary: ${result.summary}`,
+		...result.warnings.map((warning) => `warning: ${warning}`),
+		"",
+		...result.relevantFiles.flatMap((file) => [
+			`${file.score}\t${file.path}\t${file.scanStatus}\t${file.contentHash}`,
+			`  reasons: ${file.reasons.join("; ") || "score match"}`,
+			`  responsibilities: ${(file.l1.responsibilities ?? []).join("; ") || "(none)"}`,
+			`  symbols: ${(file.l1.symbols ?? []).map((symbol) => symbol.name).join(", ") || "(none)"}`,
+			`  imports: ${(file.l1.imports ?? []).join(", ") || "(none)"}`,
+			`  exports: ${(file.l1.exports ?? []).join(", ") || "(none)"}`,
+			`  tests: ${(file.l1.test_ids ?? []).join(", ") || "(none)"}`
+		]),
+		"----",
+		`total relevant files: ${result.relevantFiles.length}`
+	];
+}
+function formatL1ContextPackForPrompt(result) {
+	return [
+		"Topchester KB context pack:",
+		"Use this as orientation only. For task-critical facts, read current source files before editing or making exact claims.",
+		"## -- kb summary start",
+		"```json",
+		JSON.stringify(stripEmptyContainers({
+			query: result.query,
+			summary: result.summary,
+			drift: result.drift,
+			warnings: result.warnings,
+			relevantFiles: result.relevantFiles.map((file) => ({
+				id: file.id,
+				path: file.path,
+				score: file.score,
+				reasons: file.reasons,
+				contentHash: file.contentHash,
+				scanStatus: file.scanStatus,
+				l1: {
+					summary: file.l1.summary,
+					file_role: file.l1.file_role,
+					responsibilities: file.l1.responsibilities,
+					symbols: file.l1.symbols,
+					imports: file.l1.imports,
+					exports: file.l1.exports,
+					module_ids: file.l1.module_ids,
+					feature_ids: file.l1.feature_ids,
+					test_ids: file.l1.test_ids,
+					declared_test_targets: file.l1.declared_test_targets,
+					likely_test_targets: file.l1.likely_test_targets,
+					tested_by: file.l1.tested_by,
+					confidence: file.l1.confidence
+				}
+			}))
+		})),
+		"```",
+		"## -- kb summary end"
+	].join("\n");
+}
+async function loadL1FileEntries(kbPath) {
+	const entryPaths = await listJsonFiles(join(kbPath, "l1-files")).catch((error) => {
+		if (isFileNotFoundError$1(error)) return [];
+		throw error;
+	});
+	const parsedEntries = await Promise.all(entryPaths.map(loadL1FileEntry));
+	const entries = parsedEntries.filter((entry) => Boolean(entry));
+	return {
+		entries,
+		invalidEntryCount: parsedEntries.length - entries.length
+	};
+}
+async function loadL1FileEntry(entryPath) {
+	try {
+		return parseL1FileEntry(JSON.parse(await readFile(entryPath, "utf8")));
+	} catch {
+		return;
+	}
+}
+function summarizeContextPack(query, files) {
+	if (files.length === 0) return `No strong L1 matches were found for "${query}".`;
+	const paths = files.slice(0, 5).map((file) => file.path);
+	return `Likely relevant L1 files for "${query}": ${paths.join(", ")}${files.length > paths.length ? ", ..." : ""}.`;
+}
+function compactL1Entry(entry) {
+	const responsibilities = take(entry.responsibilities, 5);
+	const symbols = take(entry.symbols, 12).map(compactSymbol);
+	const imports = take(entry.imports, 20);
+	const exports = take(entry.exports, 20);
+	const moduleIds = take(entry.module_ids, 10);
+	const featureIds = take(entry.feature_ids, 10);
+	const testIds = take(entry.test_ids, 10);
+	const declaredTestTargets = take(entry.declared_test_targets, 10);
+	const likelyTestTargets = take(entry.likely_test_targets, 10);
+	const testedBy = take(entry.tested_by, 10);
+	return stripUndefinedProperties({
+		file_role: entry.file_role,
+		summary: entry.summary,
+		responsibilities: nonEmptyArray(responsibilities),
+		symbols: nonEmptyArray(symbols),
+		imports: nonEmptyArray(imports),
+		exports: nonEmptyArray(exports),
+		module_ids: nonEmptyArray(moduleIds),
+		feature_ids: nonEmptyArray(featureIds),
+		test_ids: nonEmptyArray(testIds),
+		declared_test_targets: nonEmptyArray(declaredTestTargets),
+		likely_test_targets: nonEmptyArray(likelyTestTargets),
+		tested_by: nonEmptyArray(testedBy),
+		confidence: entry.confidence
+	});
+}
+function take(items, count) {
+	return items.slice(0, count);
+}
+function compactSymbol(symbol) {
+	const compacted = {
+		name: symbol.name,
+		exported: symbol.exported,
+		kind: symbol.kind === "symbol" ? void 0 : symbol.kind,
+		summary: symbol.summary && !isGenericSymbolSummary(symbol.summary, symbol.name) ? symbol.summary : void 0
+	};
+	return compacted.kind || compacted.summary ? compacted : {
+		name: compacted.name,
+		exported: compacted.exported
+	};
+}
+function stripEmptyContainers(value) {
+	if (Array.isArray(value)) {
+		const stripped = value.map(stripEmptyContainers).filter((item) => item !== void 0);
+		return stripped.length > 0 ? stripped : void 0;
+	}
+	if (value && typeof value === "object") {
+		const entries = Object.entries(value).map(([key, item]) => [key, stripEmptyContainers(item)]).filter(([, item]) => item !== void 0);
+		return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+	}
+	return value;
+}
+function stripUndefinedProperties(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+}
+function nonEmptyArray(items) {
+	return items.length > 0 ? items : void 0;
+}
+function isGenericSymbolSummary(summary, name) {
+	const normalizedSummary = summary.trim().replace(/\s+/g, " ");
+	return normalizedSummary === `Symbol named ${name}.` || normalizedSummary === `Symbol named ${name}` || normalizedSummary === name;
+}
+async function listJsonFiles(directory) {
+	const entries = await readdir(directory, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		const entryPath = join(directory, entry.name);
+		if (entry.isDirectory()) files.push(...await listJsonFiles(entryPath));
+		else if (entry.isFile() && entry.name.endsWith(".json")) files.push(entryPath);
+	}
+	return files.sort();
+}
+function tokenizeQuery(text) {
+	return [...new Set(tokenizeText(text).filter((token) => !queryStopWords.has(token)))];
+}
+function tokenizeText(text) {
+	const rawTokens = text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+	const tokens = [];
+	for (const rawToken of rawTokens) {
+		const token = rawToken.replace(/^_+|_+$/g, "");
+		if (!token || indexStopWords.has(token)) continue;
+		tokens.push(token);
+		const singular = singularizeToken(token);
+		if (singular !== token) tokens.push(singular);
+	}
+	return tokens;
+}
+function singularizeToken(token) {
+	if (token.length > 3 && token.endsWith("ies")) return `${token.slice(0, -3)}y`;
+	if (token.length > 3 && token.endsWith("s") && !token.endsWith("ss") && !token.endsWith("us")) return token.slice(0, -1);
+	return token;
+}
+function formatField(field) {
+	switch (field) {
+		case "path": return "path";
+		case "symbol": return "symbol";
+		case "export": return "export";
+		case "responsibility": return "responsibility";
+		case "summary": return "summary";
+		case "import": return "import";
+		case "test": return "test";
+		case "relationship": return "relationship";
+		case "evidence": return "evidence";
+	}
+}
+function isFileNotFoundError$1(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function isString(value) {
+	return typeof value === "string";
+}
+const indexStopWords = new Set([
+	"a",
+	"an",
+	"and",
+	"are",
+	"as",
+	"at",
+	"be",
+	"by",
+	"for",
+	"from",
+	"in",
+	"is",
+	"it",
+	"of",
+	"on",
+	"or",
+	"the",
+	"to",
+	"with"
+]);
+const queryStopWords = new Set([
+	...indexStopWords,
+	"error",
+	"here",
+	"log",
+	"see",
+	"se",
+	"tries",
+	"trying",
+	"user",
+	"when"
+]);
+//#endregion
 //#region src/tui/markdown.ts
 const codeFenceSentinel = "topchester-code-fence";
 function renderMarkdown(text, width) {
@@ -4753,6 +5665,19 @@ const toolCallPayloadSchema = z.object({
 	label: z.string(),
 	call: z.record(z.string(), jsonValueSchema)
 });
+const taskPlanItemPayloadSchema = z.object({
+	text: z.string(),
+	status: z.enum([
+		"pending",
+		"in_progress",
+		"completed"
+	])
+});
+const taskPlanPayloadSchema = z.object({
+	kind: z.literal("task_plan"),
+	items: z.array(taskPlanItemPayloadSchema),
+	updatedAt: isoTimestampSchema
+});
 const statusPayloadSchema = z.object({
 	kind: z.literal("status"),
 	status: z.string()
@@ -4774,6 +5699,7 @@ const choicePayloadSchema = z.object({
 const sessionEventPayloadSchema = z.discriminatedUnion("kind", [
 	messagePayloadSchema,
 	toolCallPayloadSchema,
+	taskPlanPayloadSchema,
 	statusPayloadSchema,
 	knowledgeStatusPayloadSchema,
 	choicePayloadSchema
@@ -4854,6 +5780,7 @@ async function resolveLatestSessionId(workspaceRoot) {
 function rehydrateSession(events) {
 	const messages = [];
 	let status;
+	let taskPlan;
 	let visibleOnlyActionValues = /* @__PURE__ */ new Set();
 	for (const event of events) switch (event.kind) {
 		case "message":
@@ -4869,6 +5796,12 @@ function rehydrateSession(events) {
 		case "tool_call":
 			messages.push(toolCallMessage(event.call, event.label));
 			break;
+		case "task_plan":
+			taskPlan = {
+				items: event.items,
+				updatedAt: event.updatedAt
+			};
+			break;
 		case "knowledge_status": break;
 		case "choice":
 			messages.push({
@@ -4886,7 +5819,8 @@ function rehydrateSession(events) {
 	}
 	return {
 		messages,
-		status
+		status,
+		...taskPlan === void 0 ? {} : { taskPlan }
 	};
 }
 function buildHandle(sessionDir, metadata) {
@@ -5264,6 +6198,71 @@ async function executeKbCommand(args, context) {
 	return { messages: ["Usage: /kb init, /kb compile, /kb sync, /kb reset, or /kb status"] };
 }
 //#endregion
+//#region src/agent/events.ts
+const ABORT_CHOICE_VALUE = "__topchester_abort__";
+const agentEvent = {
+	status(status) {
+		return {
+			type: "status",
+			status
+		};
+	},
+	systemMessage(text) {
+		return {
+			type: "message",
+			role: "system",
+			text
+		};
+	},
+	assistantMessage(text, meta) {
+		return meta === void 0 ? {
+			type: "message",
+			role: "assistant",
+			text
+		} : {
+			type: "message",
+			role: "assistant",
+			text,
+			meta
+		};
+	},
+	toolCall(call, label) {
+		return {
+			type: "tool_call",
+			call,
+			label
+		};
+	},
+	taskPlan(plan) {
+		return {
+			type: "task_plan",
+			plan
+		};
+	},
+	knowledgeStatus(status, guidance) {
+		return guidance === void 0 ? {
+			type: "knowledge_status",
+			status
+		} : {
+			type: "knowledge_status",
+			status,
+			guidance
+		};
+	},
+	choice(options) {
+		return {
+			type: "choice",
+			...options
+		};
+	}
+};
+function choiceAction(label, value) {
+	return value === void 0 ? { label } : {
+		label,
+		value
+	};
+}
+//#endregion
 //#region src/tui/keys.ts
 function isUpKey(data) {
 	return matchesKey(data, "up") || data === "\x1B[A";
@@ -5274,6 +6273,9 @@ function isDownKey(data) {
 function isEnterKey(data) {
 	return matchesKey(data, "enter") || data === "\n" || data === "\r";
 }
+function isNewLineKey(data) {
+	return matchesKey(data, "shift+enter") || matchesKey(data, "alt+enter") || matchesKey(data, "ctrl+enter") || data === "\x1B\r" || data === "\x1B[13;2~";
+}
 function isTabKey(data) {
 	return matchesKey(data, "tab") || data === "	";
 }
@@ -5380,12 +6382,14 @@ function getStartupThreadMessages(context) {
 	lines.push("Ask Topchester what you want to change.");
 	return [systemMessage(lines.join("\n"))];
 }
-function renderStaticLayout(messages, folderName = "", modelLabel = "") {
+function renderStaticLayout(messages, folderName = "", modelLabel = "", taskPlan) {
 	const threadLines = messages.flatMap((message) => renderChatMessage(message));
 	const status = formatStatusLine(folderName, modelLabel);
+	const planLines = taskPlan && taskPlan.items.length > 0 ? [...formatTaskPlanForTui(taskPlan, 72), ""] : [];
 	return [
 		...threadLines,
 		"",
+		...planLines,
 		"┌──────────────────────────────────────────────────────────────────────┐",
 		"│ >                                                                    │",
 		"└──────────────────────────────────────────────────────────────────────┘",
@@ -5467,23 +6471,35 @@ function stripAnsi(text) {
 }
 //#endregion
 //#region src/tui/layout.ts
+const PROMPT_VISIBLE_CONTENT_LINES = 5;
+const PASTE_PREVIEW_MIN_LINES = 6;
+const PASTE_PREVIEW_MIN_CHARS = 500;
+const BRACKETED_PASTE_START = "\x1B[200~";
+const BRACKETED_PASTE_END = "\x1B[201~";
 var ChatLayout = class {
 	terminal;
 	messages;
 	folderName;
 	modelLabel;
-	input = new Input();
+	inputFocused = false;
+	promptValue = "";
+	promptCursor = 0;
 	status = "ready";
 	knowledgeStatus;
 	ephemeralLine;
+	taskPlanNoticeLine;
 	noticeLine;
 	promptHint;
+	taskPlan;
 	cancelPending;
 	submitMessage;
 	submitCommand;
 	activeModalActionIndex = 0;
 	activeSlashSuggestionIndex = 0;
 	threadScrollOffset = 0;
+	pasteBuffer;
+	pasteCounter = 0;
+	pastedContent = /* @__PURE__ */ new Map();
 	promptHistory = new PromptHistory();
 	exitAgent;
 	transcriptMode;
@@ -5494,14 +6510,6 @@ var ChatLayout = class {
 		this.modelLabel = modelLabel;
 		this.exitAgent = typeof options === "function" ? options : options.exitAgent ?? (() => {});
 		this.transcriptMode = typeof options === "function" ? "viewport" : options.transcriptMode ?? "viewport";
-		this.input.onSubmit = (value) => {
-			if (value.trim().length > 0) {
-				const message = value.trim();
-				this.addMessage(userMessage(message));
-				this.input.setValue("");
-				this.submitUserInput(message);
-			}
-		};
 	}
 	addMessage(message) {
 		this.messages.push(message);
@@ -5514,6 +6522,24 @@ var ChatLayout = class {
 	setKnowledgeStatus(status) {
 		this.knowledgeStatus = formatKnowledgeFooterStatus(status);
 	}
+	setTaskPlan(plan) {
+		const change = detectTaskPlanChange(this.taskPlan, plan);
+		this.taskPlan = plan && plan.items.length > 0 ? plan : void 0;
+		return change;
+	}
+	setTaskPlanNotice(line) {
+		this.taskPlanNoticeLine = line;
+	}
+	clearTaskPlan(now = /* @__PURE__ */ new Date()) {
+		if (!this.taskPlan) return;
+		const cleared = {
+			items: [],
+			updatedAt: now.toISOString()
+		};
+		this.taskPlan = void 0;
+		this.taskPlanNoticeLine = void 0;
+		return cleared;
+	}
 	isReady() {
 		return this.status === "ready";
 	}
@@ -5536,7 +6562,10 @@ var ChatLayout = class {
 		this.submitCommand = submit;
 	}
 	setInputValue(value) {
-		this.input.setValue(value);
+		this.promptValue = value;
+		this.promptCursor = value.length;
+		this.pastedContent.clear();
+		this.pasteCounter = 0;
 	}
 	getConversationTurns() {
 		return this.messages.flatMap((message) => {
@@ -5556,10 +6585,10 @@ var ChatLayout = class {
 		});
 	}
 	get focused() {
-		return this.input.focused;
+		return this.inputFocused;
 	}
 	set focused(value) {
-		this.input.focused = value;
+		this.inputFocused = value;
 	}
 	handleInput(data) {
 		if (this.cancelPending && matchesKey(data, "escape")) {
@@ -5568,15 +6597,15 @@ var ChatLayout = class {
 		}
 		if (this.handleModalInput(data)) return;
 		if (this.handleSlashSuggestionInput(data)) return;
+		if (this.handlePromptPasteInput(data)) return;
+		if (this.handlePromptNewLineInput(data)) return;
+		if (this.handlePromptSubmitInput(data)) return;
 		if (this.handleThreadScrollInput(data)) return;
+		if (this.handlePromptVerticalCursorInput(data)) return;
 		if (this.handlePromptHistoryInput(data)) return;
-		const previousInput = this.input.getValue();
-		this.input.handleInput(data);
-		if (this.input.getValue() !== previousInput) this.promptHistory.resetBrowsing();
-	}
-	invalidate() {
-		this.input.invalidate();
+		this.handlePromptEditInput(data);
 	}
+	invalidate() {}
 	render(width) {
 		const safeWidth = Math.max(20, width);
 		const footerLines = this.getActiveModal() ? this.renderModalHelp(safeWidth) : this.renderPrompt(safeWidth);
@@ -5604,6 +6633,7 @@ var ChatLayout = class {
 			return [...this.renderThreadMessageLines(messageLines, innerWidth, width, message.kind === "user"), ...spacer];
 		});
 		if (this.ephemeralLine) lines.push(...this.renderThreadMessageLines([` ${this.ephemeralLine}`], innerWidth, width, false));
+		if (this.taskPlanNoticeLine) lines.push(...this.renderThreadMessageLines([` ${this.taskPlanNoticeLine}`], innerWidth, width, false));
 		if (this.noticeLine) lines.push(...this.renderThreadMessageLines([` ${this.noticeLine}`], innerWidth, width, false));
 		return lines;
 	}
@@ -5619,17 +6649,69 @@ var ChatLayout = class {
 		const bottom = `└${"─".repeat(Math.max(0, width - 2))}┘`;
 		const prefix = "> ";
 		const innerWidth = Math.max(1, width - 4 - 2);
-		const inputLine = this.promptHint ? truncateToWidth(ui.label(this.promptHint), innerWidth, "…", true) : truncateToWidth(renderInputWithoutPrompt(this.input, innerWidth), innerWidth, "…", true);
+		const inputLines = this.promptHint ? [truncateToWidth(ui.label(this.promptHint), innerWidth, "…", true)] : this.renderPromptInputLines(innerWidth);
 		const statusInnerWidth = Math.max(1, width - 2);
 		const status = truncateToWidth(` ${formatStatusLine(this.folderName, this.modelLabel, this.status, this.knowledgeStatus, statusInnerWidth)} `, width, "…", true);
 		return [
 			...this.renderSlashSuggestions(width),
+			...this.renderTaskPlan(width),
 			top,
-			`│ ${prefix}${inputLine} │`,
+			...inputLines.map((line, index) => `│ ${index === 0 ? prefix : "  "}${padPromptInputLine(line, innerWidth)} │`),
 			bottom,
 			status
 		];
 	}
+	renderPromptInputLines(innerWidth) {
+		const value = this.promptValue;
+		if (!value.includes("\n")) return [this.renderPromptLineWithCursor(value, this.promptCursor, innerWidth)];
+		const rows = this.getPromptRows(innerWidth);
+		const cursorRowIndex = rows.findIndex((row) => this.promptCursor >= row.start && this.promptCursor <= row.end);
+		const latestStart = Math.max(0, rows.length - PROMPT_VISIBLE_CONTENT_LINES);
+		const visibleStart = cursorRowIndex === -1 ? latestStart : Math.min(Math.max(0, cursorRowIndex - 2), latestStart);
+		return rows.slice(visibleStart, visibleStart + PROMPT_VISIBLE_CONTENT_LINES).map((row) => {
+			if (this.promptCursor >= row.start && this.promptCursor <= row.end) return this.renderPromptLineWithCursor(row.text, this.promptCursor - row.start, innerWidth);
+			return truncateToWidth(row.text.length === 0 ? " " : row.text, innerWidth, "…", true);
+		});
+	}
+	getPromptRows(width) {
+		const rows = [];
+		let offset = 0;
+		for (const line of this.promptValue.split("\n")) {
+			if (line.length === 0) rows.push({
+				text: "",
+				start: offset,
+				end: offset
+			});
+			else for (let index = 0; index < line.length; index += width) {
+				const text = line.slice(index, index + width);
+				rows.push({
+					text,
+					start: offset + index,
+					end: offset + index + text.length
+				});
+			}
+			offset += line.length + 1;
+		}
+		return rows.length > 0 ? rows : [{
+			text: "",
+			start: 0,
+			end: 0
+		}];
+	}
+	renderPromptLineWithCursor(text, cursor, width) {
+		const safeCursor = Math.max(0, Math.min(cursor, text.length));
+		const windowStart = safeCursor >= width ? safeCursor - width + 1 : 0;
+		const visibleText = text.slice(windowStart, windowStart + width);
+		const visibleCursor = safeCursor - windowStart;
+		const beforeCursor = visibleText.slice(0, visibleCursor);
+		const cursorChar = visibleText[visibleCursor] ?? " ";
+		const afterCursor = visibleText.slice(visibleCursor + cursorChar.length);
+		return truncateToWidth(`${beforeCursor}${this.inputFocused ? CURSOR_MARKER : ""}\u001b[7m${cursorChar}\u001b[27m${afterCursor}`, width, "…", true);
+	}
+	renderTaskPlan(width) {
+		if (!this.taskPlan) return [];
+		return formatTaskPlanForTui(this.taskPlan, Math.max(1, width));
+	}
 	renderSlashSuggestions(width) {
 		const suggestions = this.getSlashSuggestions();
 		if (suggestions.length === 0 || this.promptHint) return [];
@@ -5676,6 +6758,14 @@ var ChatLayout = class {
 				this.exitAgent();
 				return true;
 			}
+			if (action.value === "__topchester_abort__") {
+				this.addMessage({
+					kind: "user",
+					text: action.label,
+					modelContext: false
+				});
+				return true;
+			}
 			this.submitModalAction(action.value ?? action.label);
 			return true;
 		}
@@ -5718,17 +6808,196 @@ var ChatLayout = class {
 	handlePromptHistoryInput(data) {
 		if (this.promptHint) return false;
 		if (isUpKey(data)) {
-			const prompt = this.promptHistory.previous(this.input.getValue());
-			if (prompt !== void 0) this.input.setValue(prompt);
+			const prompt = this.promptHistory.previous(this.promptValue);
+			if (prompt !== void 0) {
+				this.promptValue = prompt;
+				this.promptCursor = prompt.length;
+			}
 			return true;
 		}
 		if (isDownKey(data)) {
 			const prompt = this.promptHistory.next();
-			if (prompt !== void 0) this.input.setValue(prompt);
+			if (prompt !== void 0) {
+				this.promptValue = prompt;
+				this.promptCursor = prompt.length;
+			}
 			return true;
 		}
 		return false;
 	}
+	handlePromptVerticalCursorInput(data) {
+		if (this.promptHint || !this.promptValue.includes("\n")) return false;
+		if (isUpKey(data)) {
+			if (this.canMovePromptCursorVertically(-1)) {
+				this.movePromptCursorVertically(-1);
+				return true;
+			}
+			if (this.promptCursor > 0) {
+				this.promptCursor = this.getCurrentPromptLineStart();
+				return true;
+			}
+			return false;
+		}
+		if (isDownKey(data)) {
+			if (this.canMovePromptCursorVertically(1)) {
+				this.movePromptCursorVertically(1);
+				return true;
+			}
+			if (this.promptCursor < this.promptValue.length) {
+				this.promptCursor = this.getCurrentPromptLineEnd();
+				return true;
+			}
+			return false;
+		}
+		return false;
+	}
+	canMovePromptCursorVertically(delta) {
+		const lines = this.promptValue.split("\n");
+		const current = this.getPromptLineCursor(lines);
+		if (delta === -1) return current.line > 0;
+		return current.line < lines.length - 1;
+	}
+	handlePromptNewLineInput(data) {
+		if (this.promptHint || !isNewLineKey(data)) return false;
+		this.insertPromptText("\n");
+		this.promptHistory.resetBrowsing();
+		return true;
+	}
+	handlePromptSubmitInput(data) {
+		if (this.promptHint || !isEnterKey(data)) return false;
+		this.submitPromptValue();
+		return true;
+	}
+	handlePromptPasteInput(data) {
+		if (this.promptHint) return false;
+		if (this.pasteBuffer !== void 0) {
+			this.pasteBuffer += data;
+			this.flushPromptPasteBuffer();
+			return true;
+		}
+		const startIndex = data.indexOf(BRACKETED_PASTE_START);
+		if (startIndex === -1) return false;
+		const beforePaste = data.slice(0, startIndex);
+		if (beforePaste.length > 0) this.insertPromptText(beforePaste);
+		this.pasteBuffer = data.slice(startIndex + 6);
+		this.flushPromptPasteBuffer();
+		this.promptHistory.resetBrowsing();
+		return true;
+	}
+	flushPromptPasteBuffer() {
+		if (this.pasteBuffer === void 0) return;
+		const endIndex = this.pasteBuffer.indexOf(BRACKETED_PASTE_END);
+		if (endIndex === -1) return;
+		const pasted = this.pasteBuffer.slice(0, endIndex);
+		const remaining = this.pasteBuffer.slice(endIndex + 6);
+		this.pasteBuffer = void 0;
+		this.insertPastedText(pasted);
+		if (remaining.length > 0) this.handleInput(remaining);
+	}
+	insertPastedText(text) {
+		const normalizedText = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\t/g, "    ");
+		const trimmedText = normalizedText.trim();
+		if (trimmedText.length === 0) return;
+		const lineCount = trimmedText.split("\n").length;
+		if (lineCount >= PASTE_PREVIEW_MIN_LINES || trimmedText.length >= PASTE_PREVIEW_MIN_CHARS) {
+			this.pasteCounter += 1;
+			const marker = `[Pasted #${this.pasteCounter} ${lineCount} lines ${trimmedText.length} chars]`;
+			this.pastedContent.set(marker, trimmedText);
+			this.insertPromptText(marker);
+			return;
+		}
+		this.insertPromptText(normalizedText);
+	}
+	insertPromptText(text) {
+		this.promptValue = `${this.promptValue.slice(0, this.promptCursor)}${text}${this.promptValue.slice(this.promptCursor)}`;
+		this.promptCursor += text.length;
+	}
+	expandPastedContent(value) {
+		let expanded = value;
+		for (const [marker, content] of this.pastedContent) expanded = expanded.split(marker).join(content);
+		return expanded;
+	}
+	submitPromptValue() {
+		if (this.promptValue.trim().length === 0) return;
+		const message = this.expandPastedContent(this.promptValue).trim();
+		this.addMessage(userMessage(message));
+		this.promptValue = "";
+		this.promptCursor = 0;
+		this.pastedContent.clear();
+		this.pasteCounter = 0;
+		this.submitUserInput(message);
+	}
+	handlePromptEditInput(data) {
+		if (this.promptHint) return false;
+		if (matchesKey(data, "left") || data === "\x1B[D") {
+			this.promptCursor = Math.max(0, this.promptCursor - 1);
+			return true;
+		}
+		if (matchesKey(data, "right") || data === "\x1B[C") {
+			this.promptCursor = Math.min(this.promptValue.length, this.promptCursor + 1);
+			return true;
+		}
+		if (isHomeKey(data)) {
+			this.promptCursor = this.getCurrentPromptLineStart();
+			return true;
+		}
+		if (isEndKey(data)) {
+			this.promptCursor = this.getCurrentPromptLineEnd();
+			return true;
+		}
+		if (matchesKey(data, "backspace") || data === "" || data === "\b") {
+			if (this.promptCursor > 0) {
+				this.promptValue = `${this.promptValue.slice(0, this.promptCursor - 1)}${this.promptValue.slice(this.promptCursor)}`;
+				this.promptCursor -= 1;
+				this.promptHistory.resetBrowsing();
+			}
+			return true;
+		}
+		if (matchesKey(data, "delete") || data === "\x1B[3~") {
+			if (this.promptCursor < this.promptValue.length) {
+				this.promptValue = `${this.promptValue.slice(0, this.promptCursor)}${this.promptValue.slice(this.promptCursor + 1)}`;
+				this.promptHistory.resetBrowsing();
+			}
+			return true;
+		}
+		const printable = decodeKittyPrintable(data) ?? (isPrintableInput(data) ? data : void 0);
+		if (printable !== void 0) {
+			this.insertPromptText(printable);
+			this.promptHistory.resetBrowsing();
+			return true;
+		}
+		return false;
+	}
+	movePromptCursorVertically(delta) {
+		const lines = this.promptValue.split("\n");
+		const current = this.getPromptLineCursor(lines);
+		const targetLine = Math.max(0, Math.min(lines.length - 1, current.line + delta));
+		const targetColumn = Math.min(current.column, lines[targetLine]?.length ?? 0);
+		this.promptCursor = lines.slice(0, targetLine).reduce((total, line) => total + line.length + 1, 0) + targetColumn;
+	}
+	getPromptLineCursor(lines = this.promptValue.split("\n")) {
+		let offset = 0;
+		for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+			const line = lines[lineIndex] ?? "";
+			const end = offset + line.length;
+			if (this.promptCursor <= end || lineIndex === lines.length - 1) return {
+				line: lineIndex,
+				column: Math.max(0, this.promptCursor - offset)
+			};
+			offset = end + 1;
+		}
+		return {
+			line: 0,
+			column: 0
+		};
+	}
+	getCurrentPromptLineStart() {
+		return this.promptValue.lastIndexOf("\n", Math.max(0, this.promptCursor - 1)) + 1;
+	}
+	getCurrentPromptLineEnd() {
+		const end = this.promptValue.indexOf("\n", this.promptCursor);
+		return end === -1 ? this.promptValue.length : end;
+	}
 	handleSlashSuggestionInput(data) {
 		const suggestions = this.getSlashSuggestions();
 		if (suggestions.length === 0) {
@@ -5747,19 +7016,19 @@ var ChatLayout = class {
 			this.completeSlashSuggestion(suggestions);
 			return true;
 		}
-		if (isEnterKey(data) && this.input.getValue().trim() !== suggestions[this.activeSlashSuggestionIndex]?.value) {
+		if (isEnterKey(data) && this.promptValue.trim() !== suggestions[this.activeSlashSuggestionIndex]?.value) {
 			this.completeSlashSuggestion(suggestions);
 			return true;
 		}
 		return false;
 	}
 	completeSlashSuggestion(suggestions) {
-		this.input.setValue(suggestions[this.activeSlashSuggestionIndex]?.value ?? this.input.getValue());
-		this.input.handleInput("\x1B[F");
+		this.promptValue = suggestions[this.activeSlashSuggestionIndex]?.value ?? this.promptValue;
+		this.promptCursor = this.promptValue.length;
 		this.promptHistory.resetBrowsing();
 	}
 	getSlashSuggestions() {
-		return getSlashCommandSuggestions(this.input.getValue());
+		return getSlashCommandSuggestions(this.promptValue);
 	}
 	getActiveModal() {
 		return this.messages[this.getActiveModalIndex()];
@@ -5772,6 +7041,7 @@ var ChatLayout = class {
 		this.submitUserInput(message);
 	}
 	submitUserInput(message) {
+		this.setTaskPlanNotice(void 0);
 		this.promptHistory.add(message);
 		if (message.startsWith("/")) this.submitCommand?.(message);
 		else this.submitMessage?.(message);
@@ -5780,8 +7050,15 @@ var ChatLayout = class {
 function colorUserMessageBorder(line) {
 	return line.replace("▌", ui.modelInline("▌"));
 }
-function renderInputWithoutPrompt(input, width) {
-	return (input.render(width + 2)[0] ?? "").replace(/^> /, "");
+function padPromptInputLine(line, width) {
+	return `${line}${" ".repeat(Math.max(0, width - stripAnsi(line).length))}`;
+}
+function isPrintableInput(data) {
+	if (data.length === 0) return false;
+	return [...data].every((char) => {
+		const code = char.charCodeAt(0);
+		return code >= 32 && code !== 127 && (code < 128 || code > 159);
+	});
 }
 //#endregion
 //#region src/agent/conversation.ts
@@ -5793,58 +7070,6 @@ function buildConversationPrompt(turns, latestMessage) {
 	return lines.join("\n\n");
 }
 //#endregion
-//#region src/agent/events.ts
-const agentEvent = {
-	status(status) {
-		return {
-			type: "status",
-			status
-		};
-	},
-	systemMessage(text) {
-		return {
-			type: "message",
-			role: "system",
-			text
-		};
-	},
-	assistantMessage(text, meta) {
-		return meta === void 0 ? {
-			type: "message",
-			role: "assistant",
-			text
-		} : {
-			type: "message",
-			role: "assistant",
-			text,
-			meta
-		};
-	},
-	toolCall(call, label) {
-		return {
-			type: "tool_call",
-			call,
-			label
-		};
-	},
-	knowledgeStatus(status, guidance) {
-		return guidance === void 0 ? {
-			type: "knowledge_status",
-			status
-		} : {
-			type: "knowledge_status",
-			status,
-			guidance
-		};
-	},
-	choice(options) {
-		return {
-			type: "choice",
-			...options
-		};
-	}
-};
-//#endregion
 //#region src/agent/health.ts
 async function checkAgentReady(modelGateway, abortSignal) {
 	const abortController = new AbortController();
@@ -5877,20 +7102,25 @@ function isAbortError(error) {
 //#endregion
 //#region src/agent/tools/executor.ts
 async function executeToolCall(workspaceRoot, call, options = {}) {
-	const definition = getToolDefinition(call.tool);
 	const startedAt = Date.now();
 	const context = {
 		workspaceRoot,
 		pathEnv: options.pathEnv,
-		logger: options.logger
+		logger: options.logger,
+		taskPlan: options.taskPlan
 	};
-	options.logger?.debug({
-		event: "tool_call",
-		tool: call.tool,
-		args: summarizeToolArgs(call)
-	}, "tool call");
 	try {
-		const result = await definition.execute(context, call.args);
+		const definition = getToolDefinition(call.tool);
+		const parsedCall = {
+			...call,
+			args: definition.argsSchema.parse(call.args)
+		};
+		options.logger?.debug({
+			event: "tool_call",
+			tool: parsedCall.tool,
+			args: summarizeToolArgs(parsedCall)
+		}, "tool call");
+		const result = await definition.execute(context, parsedCall.args);
 		const durationMs = Date.now() - startedAt;
 		options.logger?.debug({
 			event: "tool_result",
@@ -5910,23 +7140,40 @@ async function executeToolCall(workspaceRoot, call, options = {}) {
 		}, "tool result content");
 		return result;
 	} catch (error) {
-		options.logger?.error({
-			event: "tool_error",
+		const message = formatErrorMessage(error);
+		const logPayload = {
+			event: "tool_result",
 			tool: call.tool,
 			durationMs: Date.now() - startedAt,
+			error: message,
 			err: error
-		}, "tool failed");
-		throw error;
+		};
+		if (typeof options.logger?.warn === "function") options.logger.warn(logPayload, "tool returned error");
+		else options.logger?.debug(logPayload, "tool returned error");
+		return {
+			tool: call.tool,
+			content: `Tool ${call.tool} failed: ${message}`,
+			error: message,
+			warning: message
+		};
 	}
 }
 function summarizeToolArgs(call) {
+	if (call.tool === "plan_todo") {
+		const activeItem = call.args.items.find((item) => item.status === "in_progress")?.text;
+		return {
+			itemCount: call.args.items.length,
+			activeItem,
+			completedCount: call.args.items.filter((item) => item.status === "completed").length
+		};
+	}
 	if (call.tool === "write_file") return {
 		path: call.args.path,
 		contentLength: call.args.content.length,
 		lineCount: countLogicalLines(call.args.content),
 		createParentDirs: Boolean(call.args.create_parent_dirs),
 		overwrite: Boolean(call.args.overwrite),
-		expectedHashProvided: Boolean(call.args.expected_hash)
+		expectedCurrentHashProvided: Boolean(call.args.expected_current_hash)
 	};
 	if (call.tool !== "edit_file") return call.args;
 	return {
@@ -5934,10 +7181,15 @@ function summarizeToolArgs(call) {
 		editCount: call.args.edits.length,
 		oldTextLengths: call.args.edits.map((edit) => edit.old_text.length),
 		newTextLengths: call.args.edits.map((edit) => edit.new_text.length),
-		expectedHashProvided: Boolean(call.args.expected_hash)
+		expectedCurrentHashProvided: Boolean(call.args.expected_current_hash)
 	};
 }
 function summarizeToolResult(result) {
+	if (result.tool === "plan_todo") return {
+		itemCount: result.plan.items.length,
+		activeItem: result.currentItem,
+		completedCount: result.completedCount
+	};
 	if (result.tool === "inspect_command") return {
 		cwd: result.cwd,
 		exitCode: result.exitCode,
@@ -6006,6 +7258,9 @@ function countLogicalLines(content) {
 	const withoutTrailingLineEnding = content.replace(/\r?\n$/u, "");
 	return withoutTrailingLineEnding.length === 0 ? 1 : withoutTrailingLineEnding.split(/\r?\n/u).length;
 }
+function formatErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 //#endregion
 //#region src/agent/prompts.ts
 function getChatSystemPrompt() {
@@ -6029,6 +7284,11 @@ function getChatSystemPrompt() {
 		"",
 		"Tool use:",
 		"- When using a tool, output exactly one tool JSON object and no prose, markdown, or additional JSON. After the tool result, either output the next single tool JSON object or a final plain-text answer.",
+		"- You already have permission to use the available tools to handle the user's request. Do not ask the user to provide tool results or permission to use an available tool.",
+		"- Do not claim to have read, created, edited, staged, committed, or run anything unless a tool result in this turn confirms it.",
+		"- Use plan_todo for non-trivial multi-step work before the first substantive repository tool call.",
+		"- Keep plan_todo items short, user-safe, and usually 2 to 6 items. Maintain exactly one in_progress item while work remains, update it after major progress changes, and clear it only when abandoning the plan or when no visible plan is useful.",
+		"- Do not use plan_todo for simple one-step answers, tiny reads, or trivial edits.",
 		"- Use read/search tools when the user asks about files, code, symbols, usages, tests, or project behavior.",
 		"- Use find_file for path or filename lookup. Use grep for text inside files. If grep output mentions another path, treat that mentioned path as content until find_file or read_file confirms it exists.",
 		"- Use list_files, grep, find_file, and read_file for exact file listing, search, lookup, and reading tasks.",
@@ -6037,8 +7297,10 @@ function getChatSystemPrompt() {
 		"- Use inspect_command only for quick read-only repo orientation when a short familiar command chain is clearer than several dedicated tool calls.",
 		"- inspect_command is not a shell. Unsafe commands, shell expansion, scripts, installs, builds, tests, network access, and file mutation are not available through it.",
 		"- Use read_file before editing a file so your edit is based on current file content and hash metadata.",
+		"- When passing expected_current_hash to edit_file or write_file, use the current pre-edit/pre-write hash from the latest read_file result for that exact file. Never invent it and never use a predicted after-edit or after-write hash.",
 		"- Use edit_file for targeted edits to existing files. Make multiple disjoint edits for the same file in one call when possible.",
-		"- Use write_file to create new files by default. It fails when the file already exists unless you are replacing the whole file with overwrite:true and expected_hash from read_file.",
+		"- Use write_file to create new files by default. It fails when the file already exists unless you are replacing the whole file with overwrite:true and expected_current_hash from read_file.",
+		"- When the user asks you to create a new file, call write_file. Do not answer that the file was created until write_file succeeds.",
 		"- Pass write_file create_parent_dirs:true only when the user intent clearly includes creating that folder path.",
 		"- Do not use inspect_command for file creation or file mutation.",
 		"- Keep edit_file old_text small but unique. Do not include line labels or grep prefixes in old_text; use exact file text only.",
@@ -6050,34 +7312,83 @@ function getChatSystemPrompt() {
 }
 //#endregion
 //#region src/agent/runtime.ts
-const MAX_TOOL_CALLS_PER_TURN = 8;
+const MAX_TOOL_CALLS_PER_TURN = 75;
 var TopchesterAgentRuntime = class {
 	context;
+	taskPlan = createTaskPlanController();
+	/**
+	* Holds the shared application context for one runtime instance.
+	* The runtime does not own those dependencies; it coordinates the
+	* workspace, model gateway, logger, config, and task-plan state that
+	* are passed in by the CLI or TUI layer.
+	*/
 	constructor(context) {
 		this.context = context;
 	}
+	/**
+	* Performs the lightweight startup model check used by the interactive
+	* agent before accepting work. The check is intentionally non-blocking
+	* from the user's point of view: timeout and failure both produce a
+	* visible status message, but the runtime still moves to ready so the
+	* user can continue.
+	*/
 	async checkAgent(abortSignal) {
 		const result = await checkAgentReady(this.context.modelGateway, abortSignal);
 		if (result === "ready") return [agentEvent.status("ready")];
 		if (result === "timed-out") return [agentEvent.systemMessage("Agent is taking a while, so I skipped the startup check."), agentEvent.status("ready")];
 		return [agentEvent.systemMessage("Agent did not say it was ready."), agentEvent.status("ready")];
 	}
+	/**
+	* Builds the initial knowledge-base status events shown by the TUI.
+	* This wraps the raw filesystem status with the same non-clean file count
+	* used by `/kb status`, so startup messaging reflects whether project
+	* knowledge is ready, missing, stale, or waiting for a sync.
+	*/
 	async checkKnowledgeBase() {
 		return getKnowledgeStatusEvents(await this.getKnowledgeStatusWithNonCleanFileCount());
 	}
-	async submitMessage(conversation, message, abortSignal) {
-		const prompt = buildConversationPrompt(conversation, message);
+	/**
+	* Runs one user chat turn through the agent loop. It builds the model
+	* prompt with relevant KB context, calls the model, executes any requested
+	* tools, feeds tool results back into the next prompt, and repeats until
+	* the model returns a normal assistant message or the loop hits its safety
+	* limit.
+	*
+	* Events are accumulated for the caller and optionally streamed through
+	* `onEvent` as soon as tool calls, task-plan updates, choices, or final
+	* messages are available. The method also enforces visible task-plan
+	* closure before a final answer when the model leaves an open plan.
+	*/
+	async submitMessage(conversation, message, abortSignal, onEvent) {
+		const prompt = await this.buildPromptWithKnowledgeContext(buildConversationPrompt(conversation, message), message);
 		const events = [];
+		const emit = async (...nextEvents) => {
+			events.push(...nextEvents);
+			if (!onEvent) return;
+			for (const event of nextEvents) await onEvent(event);
+		};
 		let nextPrompt = prompt;
 		let totalDurationMs = 0;
 		let lastModelId = "model";
 		let afterTool;
 		let toolProtocolOverride = readToolProtocolEnvOverride();
+		let requestedPlanClosure = false;
 		for (let toolCalls = 0; toolCalls <= MAX_TOOL_CALLS_PER_TURN; toolCalls += 1) {
 			const startedAt = Date.now();
+			const system = getChatSystemPrompt();
+			this.context.logger.debug({
+				event: "model_prompt",
+				purpose: "agent.primary",
+				afterTool,
+				toolProtocol: toolProtocolOverride,
+				promptLength: nextPrompt.length,
+				systemLength: system.length,
+				prompt: nextPrompt,
+				system
+			}, afterTool ? "model prompt after tool" : "model prompt");
 			const result = await generateAgentStep(this.context, {
 				purpose: "agent.primary",
-				system: getChatSystemPrompt(),
+				system,
 				prompt: nextPrompt,
 				abortSignal,
 				toolProtocol: toolProtocolOverride
@@ -6093,6 +7404,11 @@ var TopchesterAgentRuntime = class {
 				durationMs,
 				totalDurationMs,
 				textLength: result.text.length,
+				usage: result.usage,
+				inputTokens: result.usage?.inputTokens,
+				outputTokens: result.usage?.outputTokens,
+				totalTokens: result.usage?.totalTokens,
+				costUsd: result.usage?.costUsd,
 				hasToolCall: Boolean(toolCall),
 				toolProtocol: result.toolProtocol,
 				protocolAttempts: result.protocolAttempts,
@@ -6113,25 +7429,45 @@ var TopchesterAgentRuntime = class {
 			if (result.providerRejectedTools && result.toolProtocol === "text-json") toolProtocolOverride = "text-json";
 			else if (result.providerRejectedTools && result.toolProtocol === "text-xml") toolProtocolOverride = "text-xml";
 			if (!toolCall) {
-				events.push(agentEvent.assistantMessage(result.text.trim() || "I got an empty response from the model.", formatAgentMessageMeta(result.modelId, totalDurationMs)), agentEvent.status("ready"));
+				if (hasOpenTaskPlan(this.taskPlan.get())) {
+					if (!requestedPlanClosure) {
+						requestedPlanClosure = true;
+						nextPrompt = `${nextPrompt}\n\n${formatOpenPlanClosureInstruction(result.text, result.toolProtocol)}`;
+						continue;
+					}
+					await emit(agentEvent.taskPlan(this.taskPlan.update({ items: [] })));
+				}
+				await emit(agentEvent.assistantMessage(result.text.trim() || "I got an empty response from the model.", formatAgentMessageMeta(result.modelId, totalDurationMs)), agentEvent.status("ready"));
 				return events;
 			}
 			if (toolCalls === MAX_TOOL_CALLS_PER_TURN) {
-				events.push(agentEvent.systemMessage(`Stopped after ${MAX_TOOL_CALLS_PER_TURN} tool calls in one turn.`), agentEvent.status("ready"));
+				await emit(agentEvent.choice({
+					tone: "warning",
+					title: "Tool call limit reached",
+					body: `Stopped after ${MAX_TOOL_CALLS_PER_TURN} tool calls in one turn. Continue starts another turn; abort leaves the call stopped.`,
+					actions: [choiceAction("Continue", "Continue the previous task from where you stopped."), choiceAction("Abort", ABORT_CHOICE_VALUE)]
+				}), agentEvent.status("ready"));
 				return events;
 			}
 			const executableToolCall = toolCall;
-			const toolResult = await executeToolCall(this.context.workspaceRoot, executableToolCall, { logger: this.context.logger });
-			events.push(agentEvent.toolCall(executableToolCall, formatToolCallMessage(executableToolCall, toolResult)));
+			const toolResult = await executeToolCall(this.context.workspaceRoot, executableToolCall, {
+				logger: this.context.logger,
+				taskPlan: this.taskPlan
+			});
+			await emit(agentEvent.toolCall(executableToolCall, formatToolCallMessage(executableToolCall, toolResult)));
+			if (!isToolErrorResult(toolResult) && toolResult.tool === "plan_todo") await emit(agentEvent.taskPlan(toolResult.plan));
 			afterTool = executableToolCall.tool;
-			nextPrompt = `${nextPrompt}\n\n${formatToolResultForPrompt(toolResult)}\n\n${formatContinuationInstruction(result.toolProtocol)}`;
+			nextPrompt = `${nextPrompt}\n\n${formatToolResultForPrompt(toolResult)}\n\n${formatContinuationInstruction(result.toolProtocol, toolResult)}`;
 		}
-		return [
-			...events,
-			agentEvent.assistantMessage("I stopped because the tool loop ended unexpectedly.", formatAgentMessageMeta(lastModelId, totalDurationMs)),
-			agentEvent.status("ready")
-		];
+		await emit(agentEvent.assistantMessage("I stopped because the tool loop ended unexpectedly.", formatAgentMessageMeta(lastModelId, totalDurationMs)), agentEvent.status("ready"));
+		return events;
 	}
+	/**
+	* Executes a slash command through the shared command dispatcher and maps
+	* the command output into runtime events. Commands that can change KB
+	* readiness also refresh the displayed knowledge status so the TUI footer
+	* and chat status stay aligned with the command result.
+	*/
 	async submitSlashCommand(command, onProgress) {
 		const result = await executeSlashCommand(command, {
 			workspaceRoot: this.context.workspaceRoot,
@@ -6145,6 +7481,12 @@ var TopchesterAgentRuntime = class {
 		events.push(agentEvent.status("ready"));
 		return events;
 	}
+	/**
+	* Reads the project KB status and augments it with a count of files that
+	* would be touched by a dry-run compile. The dry run is only performed for
+	* a ready KB directory, because missing or incomplete KB states already
+	* have enough information for the startup and status messages.
+	*/
 	async getKnowledgeStatusWithNonCleanFileCount() {
 		const status = getKnowledgeStatus(this.context.workspaceRoot);
 		if (!status.kbExists || !status.kbIsDirectory || status.kbContentState !== "ready") return status;
@@ -6154,7 +7496,50 @@ var TopchesterAgentRuntime = class {
 			nonCleanFileCount: result.files.length
 		};
 	}
+	/**
+	* Adds relevant L1 knowledge context to the conversation prompt when the
+	* compiled KB is present and ready. Search failures are logged and then
+	* ignored on purpose: stale or broken KB search should not prevent the
+	* user's chat turn from reaching the model.
+	*/
+	async buildPromptWithKnowledgeContext(prompt, message) {
+		const status = getKnowledgeStatus(this.context.workspaceRoot);
+		if (!status.kbExists || !status.kbIsDirectory || status.kbContentState !== "ready") return prompt;
+		try {
+			const contextPack = await createL1ContextPack(this.context.workspaceRoot, message, {
+				limit: 8,
+				minScore: 12
+			});
+			this.context.logger.debug({
+				event: "kb_context_pack",
+				query: message,
+				entryCount: contextPack.entryCount,
+				relevantFileCount: contextPack.relevantFiles.length,
+				paths: contextPack.relevantFiles.map((file) => file.path),
+				warnings: contextPack.warnings
+			}, "kb context pack");
+			this.context.logger.trace({
+				event: "kb_context_pack_payload",
+				contextPack
+			}, "kb context pack payload");
+			if (contextPack.relevantFiles.length === 0) return prompt;
+			return `${formatL1ContextPackForPrompt(contextPack)}\n\nConversation:\n${prompt}`;
+		} catch (error) {
+			this.context.logger.debug({
+				event: "kb_context_pack_failed",
+				error: error instanceof Error ? error.message : String(error)
+			}, "kb context pack failed");
+			return prompt;
+		}
+	}
 };
+/**
+* Calls the configured model gateway for a single agent step and normalizes
+* the result into the newer `ModelAgentResult` shape. Gateways that implement
+* native agent stepping receive the tool registry directly; older text-only
+* gateways fall back to parsing a JSON or XML tool call out of the model text
+* so the rest of the runtime can use the same tool loop.
+*/
 async function generateAgentStep(context, request) {
 	if ("generateAgentStep" in context.modelGateway && typeof context.modelGateway.generateAgentStep === "function") return context.modelGateway.generateAgentStep({
 		...request,
@@ -6183,15 +7568,33 @@ async function generateAgentStep(context, request) {
 		openRouterRoutingApplied: false
 	};
 }
+/**
+* Reads the optional environment override for the tool-calling protocol.
+* Invalid values are ignored instead of failing startup, which keeps local
+* experimentation contained to supported protocol names while preserving the
+* normal automatic negotiation path by default.
+*/
 function readToolProtocolEnvOverride() {
 	const value = process.env.TOPCHESTER_TOOL_PROTOCOL;
 	if (value === "auto" || value === "native" || value === "text-json" || value === "text-xml") return value;
 }
+/**
+* Applies TUI styling to per-file KB sync states. The raw scanner statuses
+* are preserved as text, but success, warning, and error categories get
+* different colors so slash-command output is readable without changing the
+* underlying command semantics.
+*/
 function formatTuiSyncStatus(status) {
 	if (status === "current") return ui.ok(status);
 	if (status === "invalid" || status === "missing_file") return ui.error(status);
 	return ui.warn(status);
 }
+/**
+* Decides whether a slash command should trigger a fresh KB status event.
+* Only KB subcommands that can initialize, rebuild, sync, reset, or inspect
+* the compiled knowledge state need the refresh; other commands can return
+* their output without doing extra filesystem work.
+*/
 function shouldRefreshKnowledgeStatus(command) {
 	const parsed = parseSlashCommand(command);
 	return parsed?.name === "kb" && [
@@ -6202,19 +7605,44 @@ function shouldRefreshKnowledgeStatus(command) {
 		"status"
 	].includes(parsed.args[0] ?? "");
 }
+/**
+* Converts a computed KB status into the startup event shape consumed by the
+* TUI. The event carries both the structured status and a short next-step
+* message, letting renderers show precise state while keeping user-facing
+* guidance in one place.
+*/
 function getKnowledgeStatusEvents(status) {
 	return [agentEvent.knowledgeStatus(status, formatStartupKnowledgeGuidance(status))];
 }
+/**
+* Produces the short guidance line shown with startup KB status. The message
+* is deliberately action-oriented: it points to the next command that would
+* fix the current state and returns nothing when the KB is ready and clean.
+*/
 function formatStartupKnowledgeGuidance(status) {
 	if (!status.kbExists) return "Next: run /kb init, then /kb compile to create project knowledge.";
 	if (!status.kbIsDirectory) return "Fix the KB path or config, then run /kb status.";
 	if (status.kbContentState !== "ready") return "Next: run /kb compile to build project knowledge.";
 	if ((status.nonCleanFileCount ?? 0) > 0) return "Next: run /kb sync to update project knowledge, or /kb status to inspect the files.";
 }
+/**
+* Serializes a tool execution result into the text that is fed back to the
+* model after a tool call. Each tool gets the metadata the model needs for
+* the next step, such as file hashes, diffs, command exit status, truncation
+* state, or KB dirty-state signals, while errors are presented in a uniform
+* error block.
+*/
 function formatToolResultForPrompt(result) {
 	const path = result.path ? ` ${JSON.stringify(result.path)}` : "";
 	const command = result.command ? ` via ${result.command}` : "";
 	const warning = result.warning ? `\nWarning: ${result.warning}` : "";
+	if (isToolErrorResult(result)) return [
+		`Tool result from ${result.tool}${path}${command}:`,
+		`Error: ${result.error}`,
+		"```",
+		result.content,
+		"```"
+	].join("\n");
 	if (result.tool === "read_file") return [
 		`Tool result from ${result.tool}${path}${command}:${warning}`,
 		`hash: ${result.hash}`,
@@ -6222,6 +7650,7 @@ function formatToolResultForPrompt(result) {
 		result.content,
 		"```"
 	].join("\n");
+	if (result.tool === "plan_todo") return [`Tool result from ${result.tool}:`, result.content].join("\n");
 	if (result.tool === "edit_file") return [
 		`Tool result from ${result.tool}${path}:`,
 		`before_hash: ${result.beforeHash}`,
@@ -6319,11 +7748,49 @@ function formatToolResultForPrompt(result) {
 		"```"
 	].join("\n");
 }
-function formatContinuationInstruction(protocol) {
-	return `Continue the user's request using the tool result above. ${protocol === "text-xml" ? "If another tool is needed, reply with only one XML tool call." : protocol === "text-json" ? "If another tool is needed, reply with only that tool JSON." : "If another tool is needed, use the available tool calling path."} Otherwise answer the user. Do not guess.`;
+/**
+* Builds the follow-up instruction appended after each tool result. It keeps
+* the model on the active task, reminds it to maintain the visible plan, and
+* restates the current tool-call protocol so the next model step remains
+* parseable by the runtime.
+*/
+function formatContinuationInstruction(protocol, result) {
+	const toolInstruction = protocol === "text-xml" ? "If another tool is needed, reply with only one XML tool call." : protocol === "text-json" ? "If another tool is needed, reply with only that tool JSON." : "If another tool is needed, use the available tool calling path.";
+	return [
+		"Continue the user's request using the tool result above and the visible plan when one is active.",
+		result.tool === "find_file" ? "find_file results are paths only; if the user asked to read or answer from file contents, call read_file on the relevant path before answering. Do not ask the user to provide the read_file result or permission." : "",
+		"Update plan_todo after major progress changes.",
+		"Before a final answer, close the visible plan by calling plan_todo with all finished items marked completed, or with [] if abandoning the plan.",
+		toolInstruction,
+		"Otherwise answer the user. Do not guess."
+	].filter(Boolean).join(" ");
+}
+/**
+* Creates the corrective prompt used when the model tries to answer while a
+* visible task plan is still open. The draft final answer is preserved so the
+* model can reuse it after closing the plan, but the immediate instruction is
+* to call `plan_todo` first.
+*/
+function formatOpenPlanClosureInstruction(draftAnswer, protocol) {
+	const toolInstruction = protocol === "text-xml" ? "Reply now with only one XML plan_todo tool call." : protocol === "text-json" ? "Reply now with only the plan_todo JSON object." : "Use the available tool calling path now to call plan_todo.";
+	const trimmedDraft = draftAnswer.trim();
+	return [
+		"The visible plan still has unfinished items, so do not provide the final answer yet.",
+		"First close the plan with plan_todo: mark completed work as completed, keep one item in_progress only if work truly remains, or use [] if abandoning the plan.",
+		toolInstruction,
+		trimmedDraft ? `After the plan_todo result, use this draft final answer if it is still accurate:\n${trimmedDraft}` : ""
+	].filter(Boolean).join("\n");
 }
+/**
+* Formats a compact, user-visible summary for a tool call event. When a
+* result is available the summary includes useful completion details, such as
+* changed-line counts, staged paths, commit subjects, or command failures,
+* instead of echoing the full tool payload.
+*/
 function formatToolCallMessage(call, result) {
+	if (result && isToolErrorResult(result)) return `${call.tool} failed: ${result.error}`;
 	switch (call.tool) {
+		case "plan_todo": return result?.tool === "plan_todo" ? `plan_todo: ${result.plan.items.length} items, ${result.inProgressCount} active` : `plan_todo: ${call.args.items.length} items`;
 		case "read_file": return `read_file: ${call.args.path}`;
 		case "list_files": return `list_files: ${call.args.path}${call.args.recursive ? " (recursive)" : ""}`;
 		case "grep": return `grep: ${call.args.pattern} in ${call.args.path ?? "."}`;
@@ -6338,21 +7805,48 @@ function formatToolCallMessage(call, result) {
 		case "inspect_command": return `inspect_command: ${call.args.command}`;
 	}
 }
+/**
+* Summarizes a `git_diff` call for the TUI event list. Successful results
+* report the resolved scope, file count, and truncation marker; pending or
+* failed calls fall back to the requested scope from the tool arguments.
+*/
 function formatGitDiffCallSummary(call, result) {
-	if (result?.tool === "git_diff") return `${result.scope} (${result.fileCount} files${result.truncated ? ", truncated" : ""})`;
+	if (result?.tool === "git_diff" && !isToolErrorResult(result)) return `${result.scope} (${result.fileCount} files${result.truncated ? ", truncated" : ""})`;
 	return call.args.scope;
 }
+/**
+* Returns the parenthesized change summary for a successful `edit_file`
+* result. Non-edit results and failed edits intentionally return an empty
+* suffix so the main tool-call formatter can keep one path for success,
+* failure, and pre-result display.
+*/
 function formatEditFileChangeSummary(result) {
-	if (result?.tool !== "edit_file") return "";
+	if (result?.tool !== "edit_file" || isToolErrorResult(result)) return "";
 	return ` (changed ${result.editEvent.diffSummary})`;
 }
+/**
+* Returns the parenthesized write summary for a successful `write_file`
+* result. The helper mirrors the edit summary helper, keeping write-specific
+* result details out of the larger switch that formats all tool-call messages.
+*/
 function formatWriteFileChangeSummary(result) {
-	if (result?.tool !== "write_file") return "";
+	if (result?.tool !== "write_file" || isToolErrorResult(result)) return "";
 	return ` (${result.writeEvent.writeSummary})`;
 }
+/**
+* Formats the assistant-message metadata shown next to the final response.
+* The model identifier and cumulative turn duration are kept together here
+* so callers do not need to know how agent-loop timing should be presented.
+*/
 function formatAgentMessageMeta(model, durationMs) {
 	return `${model} · ${formatDuration$1(durationMs)}`;
 }
+/**
+* Converts elapsed milliseconds into the short human-readable duration used
+* in assistant metadata. Very short turns keep one decimal place, normal
+* sub-minute turns round to seconds, and longer turns switch to minutes plus
+* remaining seconds.
+*/
 function formatDuration$1(durationMs) {
 	const totalSeconds = Math.max(0, durationMs / 1e3);
 	if (totalSeconds < 10) return `${formatNumber(totalSeconds, 1)} sec`;
@@ -6362,6 +7856,12 @@ function formatDuration$1(durationMs) {
 	if (seconds === 0) return `${minutes} min`;
 	return `${minutes} min ${seconds} sec`;
 }
+/**
+* Formats a number with a fixed number of fraction digits using the English
+* locale expected by the TUI metadata strings. Keeping this tiny wrapper
+* avoids repeating the minimum and maximum fraction-digit options at every
+* call site.
+*/
 function formatNumber(value, fractionDigits) {
 	return value.toLocaleString("en", {
 		minimumFractionDigits: fractionDigits,
@@ -6381,6 +7881,7 @@ function renderRuntimeEvent(event) {
 			body: event.body,
 			actions: event.actions
 		})];
+		case "task_plan": return [];
 		case "status": return [];
 	}
 }
@@ -6394,6 +7895,7 @@ var TopchesterTuiShell = class {
 	options;
 	runtime;
 	session;
+	taskPlanNoticeTimer;
 	constructor(context, runtime, options = {}) {
 		this.context = context;
 		this.options = options;
@@ -6410,7 +7912,7 @@ var TopchesterTuiShell = class {
 		const folderName = getFolderName(this.context.workspaceRoot);
 		const modelLabel = getModelLabel(this.context);
 		if (!process.stdin.isTTY || !process.stdout.isTTY) {
-			console.log(renderStaticLayout(messages, folderName, modelLabel));
+			console.log(renderStaticLayout(messages, folderName, modelLabel, this.options.initialTaskPlan));
 			return;
 		}
 		const terminal = new ProcessTerminal();
@@ -6429,6 +7931,7 @@ var TopchesterTuiShell = class {
 				process.exit(0);
 			}
 		});
+		app.setTaskPlan(this.options.initialTaskPlan);
 		app.setSubmitMessage((message) => {
 			this.submitChatMessage(app, tui, message);
 		});
@@ -6471,7 +7974,7 @@ var TopchesterTuiShell = class {
 		busy.start();
 		tui.requestRender();
 		try {
-			await this.applyRuntimeEvents(app, await this.runtime.checkAgent(abortController.signal));
+			await this.applyRuntimeEvents(app, await this.runtime.checkAgent(abortController.signal), tui);
 		} catch (error) {
 			if (cancelled) {
 				app.addMessage(systemMessage("Agent check stopped."));
@@ -6485,7 +7988,7 @@ var TopchesterTuiShell = class {
 			app.setCancelPending(void 0);
 			busy.stop();
 		}
-		if (app.isReady()) await this.applyRuntimeEvents(app, await this.runtime.checkKnowledgeBase());
+		if (app.isReady()) await this.applyRuntimeEvents(app, await this.runtime.checkKnowledgeBase(), tui);
 		tui.requestRender();
 	}
 	async submitChatMessage(app, tui, message) {
@@ -6507,12 +8010,16 @@ var TopchesterTuiShell = class {
 		busy.start();
 		tui.requestRender();
 		try {
+			await this.clearTaskPlanForNewTurn(app);
 			await this.persistPayloadWithWarning(app, {
 				kind: "message",
 				role: "user",
 				text: message
 			});
-			await this.applyRuntimeEvents(app, await this.runtime.submitMessage(app.getConversationTurns(), message, abortController.signal));
+			await this.runtime.submitMessage(app.getConversationTurns(), message, abortController.signal, async (event) => {
+				await this.applyRuntimeEvents(app, [event], tui);
+				tui.requestRender();
+			});
 		} catch (error) {
 			if (cancelled) {
 				app.addMessage(systemMessage("Response stopped."));
@@ -6542,10 +8049,11 @@ var TopchesterTuiShell = class {
 		busy.start();
 		tui.requestRender();
 		try {
+			await this.clearTaskPlanForNewTurn(app);
 			await this.persistPayloadWithWarning(app, slashCommandToSessionPayload(command));
 			await this.applyRuntimeEvents(app, await this.runtime.submitSlashCommand(command, (event) => {
 				busy.setActivity(event.message);
-			}));
+			}), tui);
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error);
 			app.addMessage(systemMessage(`Command failed: ${errorMessage}`));
@@ -6559,14 +8067,41 @@ var TopchesterTuiShell = class {
 			tui.requestRender();
 		}
 	}
-	async applyRuntimeEvents(app, events) {
+	async applyRuntimeEvents(app, events, renderRequester) {
 		for (const event of events) {
 			if (event.type === "status") app.setStatus(event.status);
 			if (event.type === "knowledge_status") app.setKnowledgeStatus(event.status);
+			if (event.type === "task_plan") {
+				const change = app.setTaskPlan(event.plan);
+				app.setTaskPlanNotice(formatTaskPlanNotice(change, event.plan));
+				this.scheduleTaskPlanNoticeClear(app, renderRequester);
+			}
 			for (const message of renderRuntimeEvent(event)) app.addMessage(message);
 			await this.persistPayloadWithWarning(app, runtimeEventToSessionPayload(event));
 		}
 	}
+	scheduleTaskPlanNoticeClear(app, renderRequester) {
+		if (this.taskPlanNoticeTimer) {
+			clearTimeout(this.taskPlanNoticeTimer);
+			this.taskPlanNoticeTimer = void 0;
+		}
+		if (!renderRequester) return;
+		this.taskPlanNoticeTimer = setTimeout(() => {
+			this.taskPlanNoticeTimer = void 0;
+			app.setTaskPlanNotice(void 0);
+			renderRequester.requestRender();
+		}, 2500);
+		this.taskPlanNoticeTimer.unref?.();
+	}
+	async clearTaskPlanForNewTurn(app) {
+		const clearedPlan = app.clearTaskPlan();
+		if (!clearedPlan) return;
+		await this.persistPayloadWithWarning(app, {
+			kind: "task_plan",
+			items: clearedPlan.items,
+			updatedAt: clearedPlan.updatedAt
+		});
+	}
 	async persistPayloadWithWarning(app, payload) {
 		if (!this.session || !payload) return;
 		try {
@@ -6626,6 +8161,11 @@ function runtimeEventToSessionPayload(event) {
 			label: event.label,
 			call: event.call
 		};
+		case "task_plan": return {
+			kind: "task_plan",
+			items: event.plan.items,
+			updatedAt: event.plan.updatedAt
+		};
 		case "knowledge_status": return;
 		case "choice": return {
 			kind: "choice",
@@ -6874,7 +8414,14 @@ function printPlainEvent(event) {
 		console.log(event.label);
 		return;
 	}
-	if (event.type === "knowledge_status" && event.guidance) console.log(event.guidance);
+	if (event.type === "knowledge_status" && event.guidance) {
+		console.log(event.guidance);
+		return;
+	}
+	if (event.type === "task_plan") {
+		const notice = formatTaskPlanNotice("updated", event.plan);
+		if (notice) console.log(notice);
+	}
 }
 function pushJson(events, runId, sessionId, type, fields) {
 	events.push({
@@ -6906,9 +8453,12 @@ program.action(async () => {
 	try {
 		if (options.resume) {
 			const loaded = await loadSession(context.workspaceRoot, options.resume);
+			const session = await loadSessionForAppend(context.workspaceRoot, loaded.sessionId);
+			const rehydrated = rehydrateSession(loaded.events);
 			await new TopchesterTuiShell(context, void 0, {
-				session: await loadSessionForAppend(context.workspaceRoot, loaded.sessionId),
-				initialMessages: rehydrateSession(loaded.events).messages
+				session,
+				initialMessages: rehydrated.messages,
+				initialTaskPlan: rehydrated.taskPlan
 			}).render();
 			return;
 		}
@@ -6940,6 +8490,9 @@ program.command("run").description("run one prompt or slash command without open
 		process.exitCode = 1;
 	}
 });
+program.command("search").description("search compiled L1 knowledge entries").argument("<query...>", "search query").option("--limit <count>", "maximum number of matches", parsePositiveInteger).option("--json", "write full JSON search result to stdout").action(async (queryParts, options) => {
+	await executeKbSearchCommand(queryParts, options);
+});
 const kbCommand = program.command("kb").description("knowledge base commands");
 kbCommand.command("init").description("initialize a project knowledge base").action(async () => {
 	const context = createContextFromOptions();
@@ -6973,6 +8526,12 @@ kbCommand.command("sync").description("sync non-clean project files into the kno
 	console.log(formatKnowledgeSyncResult(result).join("\n"));
 	if (isPartialKnowledgeCompileResult(result)) process.exitCode = 2;
 });
+kbCommand.command("search").alias("query").description("search compiled L1 knowledge entries").argument("<query...>", "search query").option("--limit <count>", "maximum number of matches", parsePositiveInteger).option("--json", "write full JSON search result to stdout").action(async (queryParts, options) => {
+	await executeKbSearchCommand(queryParts, options);
+});
+kbCommand.command("context").description("create an L1 context pack for a query").argument("<query...>", "context query").option("--limit <count>", "maximum number of relevant files", parsePositiveInteger).option("--min-score <score>", "minimum match score", parseNonNegativeNumber).option("--json", "write JSON context pack to stdout").option("--full-l1", "include full raw L1 entries in JSON output").action(async (queryParts, options) => {
+	await executeKbContextCommand(queryParts, options);
+});
 kbCommand.command("reset").description("delete the local project knowledge base and cache").action(async () => {
 	const context = createContextFromOptions();
 	const result = await ui.progress("Resetting project knowledge base...", (report) => resetKnowledgeBase(context.workspaceRoot, { onProgress: (event) => report(event.message) }));
@@ -7019,6 +8578,31 @@ function createContextFromOptions() {
 		devFlags: options.dev
 	});
 }
+async function executeKbSearchCommand(queryParts, options) {
+	const context = createContextFromOptions();
+	const query = queryParts.join(" ");
+	const result = options.json ? await searchL1Knowledge(context.workspaceRoot, query, { limit: options.limit }) : await ui.spinner("Searching L1 knowledge entries...", () => searchL1Knowledge(context.workspaceRoot, query, { limit: options.limit }));
+	if (options.json) {
+		console.log(JSON.stringify(stripEmptyContainers(result), null, 2));
+		return;
+	}
+	console.log(formatL1KnowledgeSearchResult(result).join("\n"));
+}
+async function executeKbContextCommand(queryParts, options) {
+	const context = createContextFromOptions();
+	const query = queryParts.join(" ");
+	const contextPackOptions = {
+		limit: options.limit,
+		minScore: options.minScore,
+		includeFullL1: options.fullL1
+	};
+	const result = options.json ? await createL1ContextPack(context.workspaceRoot, query, contextPackOptions) : await ui.spinner("Creating L1 context pack...", () => createL1ContextPack(context.workspaceRoot, query, contextPackOptions));
+	if (options.json) {
+		console.log(JSON.stringify(stripEmptyContainers(result), null, 2));
+		return;
+	}
+	console.log(formatL1ContextPackResult(result).join("\n"));
+}
 function formatStartupError(error) {
 	const message = error instanceof Error ? error.message : String(error);
 	if (message.includes("Could not read session metadata") || message.includes("Could not read session event") || message.includes("ENOENT")) return message.includes("metadata.json") || message.includes("events.jsonl") ? message : "Session not found";
@@ -7032,6 +8616,11 @@ function parsePositiveInteger(value) {
 	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error("Expected a positive integer.");
 	return parsed;
 }
+function parseNonNegativeNumber(value) {
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed < 0) throw new Error("Expected a non-negative number.");
+	return parsed;
+}
 function formatDryRunSyncStatus(status) {
 	if (status === "current") return ui.ok(status);
 	if (status === "invalid" || status === "missing_file") return ui.error(status);