pi-ui-extend 1.0.42 → 1.0.46

package/external/pi-tools-suite/src/resource-registry/index.ts

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
 import { existsSync, promises as fs } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, relative } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { applyEdits, modify } from "jsonc-parser";
 
@@ -19,8 +20,10 @@ const REGISTRY_AGENTS_DIR = "agents";
 const REGISTRY_PROJECTS_DIR = "projects";
 const SKILL_FILE = "SKILL.md";
 const PROJECT_TASKS_FILE = "tasks.jsonc";
+const PROJECT_TASK_ATTACHMENTS_DIR = "task-attachments";
 const PROJECT_PLANS_DIR = "plans";
 const PROJECT_TODO_FILE = "TODO.md";
+const REGISTRY_TASK_ATTACHMENT_SCHEME = "pix-task-attachment:";
 const PROVENANCE_FILE = "registry.json";
 const PROVENANCE_VERSION = 1;
 const SYSTEM_CUSTOM_MESSAGE_TYPE = "pix-system";
@@ -240,6 +243,10 @@ function projectArtifactLocalPath(cwd: string, artifact: ProjectArtifact): strin
 	}
 }
 
+function projectTaskAttachmentsLocalPath(cwd: string): string {
+	return join(cwd, PROJECT_DIR, PROJECT_TASK_ATTACHMENTS_DIR);
+}
+
 function projectArtifactRelativePath(projectKey: string, artifact: ProjectArtifact): string {
 	validateName(projectKey);
 	switch (artifact) {
@@ -249,6 +256,18 @@ function projectArtifactRelativePath(projectKey: string, artifact: ProjectArtifa
 	}
 }
 
+function projectTaskAttachmentsRelativePath(projectKey: string): string {
+	validateName(projectKey);
+	return `${REGISTRY_PROJECTS_DIR}/${projectKey}/${PROJECT_TASK_ATTACHMENTS_DIR}`;
+}
+
+function projectArtifactRelativePaths(projectKey: string, artifact: ProjectArtifact): string[] {
+	const primary = projectArtifactRelativePath(projectKey, artifact);
+	return artifact === "tasks"
+		? [primary, projectTaskAttachmentsRelativePath(projectKey)]
+		: [primary];
+}
+
 function projectArtifactDisplayName(artifact: ProjectArtifact): string {
 	switch (artifact) {
 		case "tasks": return PROJECT_TASKS_FILE;
@@ -261,6 +280,10 @@ function projectArtifactRegistryPath(cacheDir: string, projectKey: string, artif
 	return join(cacheDir, ...projectArtifactRelativePath(projectKey, artifact).split("/"));
 }
 
+function projectTaskAttachmentsRegistryPath(cacheDir: string, projectKey: string): string {
+	return join(cacheDir, ...projectTaskAttachmentsRelativePath(projectKey).split("/"));
+}
+
 function canonicalGitRemote(remote: string): string | undefined {
 	const trimmed = remote.trim();
 	if (!trimmed) return undefined;
@@ -510,6 +533,22 @@ async function pathRevision(pi: ExtensionAPI, runtime: RegistryRuntime, rel: str
 	return revision || undefined;
 }
 
+async function projectArtifactRevision(
+	pi: ExtensionAPI,
+	runtime: RegistryRuntime,
+	projectKey: string,
+	artifact: ProjectArtifact,
+): Promise<string | undefined> {
+	const result = await runGit(
+		pi,
+		runtime.cacheDir,
+		["log", "-1", "--format=%H", "--", ...projectArtifactRelativePaths(projectKey, artifact)],
+		{ allowFailure: true },
+	);
+	const revision = result.stdout.trim();
+	return revision || undefined;
+}
+
 async function resourceRevision(pi: ExtensionAPI, runtime: RegistryRuntime, type: ResourceType, name: string): Promise<string | undefined> {
 	return pathRevision(pi, runtime, registryResourceRelativePath(type, name));
 }
@@ -666,6 +705,226 @@ async function hashPath(path: string): Promise<string> {
 	return hash.digest("hex");
 }
 
+type TaskBundle = {
+	source: string;
+	attachments: Map<string, string>;
+};
+
+function pathIsWithin(parent: string, child: string): boolean {
+	const rel = relative(parent, child);
+	return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+
+function registryTaskAttachmentMarker(name: string): string {
+	return `[Pix attachment: ${REGISTRY_TASK_ATTACHMENT_SCHEME}${encodeURIComponent(name)}]`;
+}
+
+function registryTaskAttachmentName(encoded: string): string {
+	let name: string;
+	try {
+		name = decodeURIComponent(encoded);
+	} catch {
+		throw new Error(`Invalid registry task attachment name: ${encoded}`);
+	}
+	if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\") || basename(name) !== name) {
+		throw new Error(`Invalid registry task attachment name: ${encoded}`);
+	}
+	return name;
+}
+
+async function readLocalTaskBundle(cwd: string): Promise<TaskBundle> {
+	const tasksPath = projectArtifactLocalPath(cwd, "tasks");
+	const source = await fs.readFile(tasksPath, "utf8");
+	const attachmentsRoot = projectTaskAttachmentsLocalPath(cwd);
+	const attachments = new Map<string, string>();
+	const replacements = new Map<string, string>();
+	const rootExists = await pathExists(attachmentsRoot);
+	let canonicalRoot: string | undefined;
+	if (rootExists) {
+		const rootStat = await fs.lstat(attachmentsRoot);
+		if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+			throw new Error(`Project task attachment storage must be a regular directory: ${attachmentsRoot}`);
+		}
+		const [canonicalCwd, resolvedRoot] = await Promise.all([
+			fs.realpath(cwd),
+			fs.realpath(attachmentsRoot),
+		]);
+		if (!pathIsWithin(canonicalCwd, resolvedRoot)) {
+			throw new Error(`Project task attachment storage resolves outside the project: ${attachmentsRoot}`);
+		}
+		canonicalRoot = resolvedRoot;
+	}
+
+	for (const match of source.matchAll(/\[Pix attachment: (file:\/\/[^\]]+)\]/g)) {
+		const marker = match[0];
+		const uri = match[1];
+		if (!uri || replacements.has(marker)) continue;
+		let candidate: string;
+		try {
+			candidate = fileURLToPath(uri);
+		} catch {
+			continue;
+		}
+		if (!canonicalRoot) continue;
+		const lexicalProjectAttachment = pathIsWithin(attachmentsRoot, candidate);
+
+		let canonicalFile: string;
+		try {
+			canonicalFile = await fs.realpath(candidate);
+		} catch (error) {
+			if (lexicalProjectAttachment) {
+				throw new Error(`Task attachment is missing: ${candidate}. ${error instanceof Error ? error.message : String(error)}`);
+			}
+			continue;
+		}
+		if (!pathIsWithin(canonicalRoot, canonicalFile)) {
+			if (lexicalProjectAttachment) throw new Error(`Task attachment resolves outside project task storage: ${candidate}`);
+			continue;
+		}
+		const stat = await fs.lstat(candidate);
+		if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`Task attachment is not a regular file: ${candidate}`);
+		const name = basename(canonicalFile);
+		const previous = attachments.get(name);
+		if (previous && previous !== canonicalFile) {
+			throw new Error(`Task attachments contain duplicate file name "${name}".`);
+		}
+		attachments.set(name, canonicalFile);
+		replacements.set(marker, registryTaskAttachmentMarker(name));
+	}
+
+	let normalizedSource = source;
+	for (const [marker, portableMarker] of replacements) {
+		normalizedSource = normalizedSource.split(marker).join(portableMarker);
+	}
+	return { source: normalizedSource, attachments };
+}
+
+async function readRemoteTaskBundle(runtime: RegistryRuntime, projectKey: string): Promise<TaskBundle> {
+	const tasksPath = projectArtifactRegistryPath(runtime.cacheDir, projectKey, "tasks");
+	const source = await fs.readFile(tasksPath, "utf8");
+	const attachmentsRoot = projectTaskAttachmentsRegistryPath(runtime.cacheDir, projectKey);
+	const attachments = new Map<string, string>();
+	for (const match of source.matchAll(/\[Pix attachment: pix-task-attachment:([^\]]+)\]/g)) {
+		const encoded = match[1];
+		if (!encoded) continue;
+		const name = registryTaskAttachmentName(encoded);
+		if (attachments.has(name)) continue;
+		const filePath = join(attachmentsRoot, name);
+		let stat: import("node:fs").Stats;
+		try {
+			stat = await fs.lstat(filePath);
+		} catch (error) {
+			throw new Error(`Registry task attachment is missing: ${name}. ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (stat.isSymbolicLink() || !stat.isFile()) {
+			throw new Error(`Registry task attachment is not a regular file: ${name}`);
+		}
+		attachments.set(name, filePath);
+	}
+	return { source, attachments };
+}
+
+async function hashTaskBundle(bundle: TaskBundle): Promise<string> {
+	const hash = createHash("sha256");
+	hash.update("tasks-bundle\0");
+	hash.update(bundle.source);
+	for (const name of [...bundle.attachments.keys()].sort()) {
+		hash.update(`\0attachment\0${name}\0`);
+		hash.update(await fs.readFile(bundle.attachments.get(name)!));
+	}
+	return hash.digest("hex");
+}
+
+async function hashProjectArtifactLocal(cwd: string, artifact: ProjectArtifact): Promise<string> {
+	return artifact === "tasks"
+		? hashTaskBundle(await readLocalTaskBundle(cwd))
+		: hashPath(projectArtifactLocalPath(cwd, artifact));
+}
+
+async function hashProjectArtifactRemote(
+	runtime: RegistryRuntime,
+	projectKey: string,
+	artifact: ProjectArtifact,
+): Promise<string> {
+	return artifact === "tasks"
+		? hashTaskBundle(await readRemoteTaskBundle(runtime, projectKey))
+		: hashPath(projectArtifactRegistryPath(runtime.cacheDir, projectKey, artifact));
+}
+
+async function replaceRemoteTaskBundle(cwd: string, runtime: RegistryRuntime, projectKey: string): Promise<void> {
+	const bundle = await readLocalTaskBundle(cwd);
+	const tasksPath = projectArtifactRegistryPath(runtime.cacheDir, projectKey, "tasks");
+	const attachmentsPath = projectTaskAttachmentsRegistryPath(runtime.cacheDir, projectKey);
+	await fs.rm(tasksPath, { recursive: true, force: true });
+	await fs.rm(attachmentsPath, { recursive: true, force: true });
+	await fs.mkdir(dirname(tasksPath), { recursive: true });
+	await fs.writeFile(tasksPath, bundle.source, "utf8");
+	if (bundle.attachments.size === 0) return;
+	await fs.mkdir(attachmentsPath, { recursive: true });
+	for (const name of [...bundle.attachments.keys()].sort()) {
+		await fs.copyFile(bundle.attachments.get(name)!, join(attachmentsPath, name));
+	}
+}
+
+async function replaceLocalTaskBundle(cwd: string, runtime: RegistryRuntime, projectKey: string): Promise<void> {
+	const bundle = await readRemoteTaskBundle(runtime, projectKey);
+	const tasksPath = projectArtifactLocalPath(cwd, "tasks");
+	const attachmentsPath = projectTaskAttachmentsLocalPath(cwd);
+	await fs.mkdir(dirname(tasksPath), { recursive: true });
+
+	let materializedSource = bundle.source;
+	for (const name of bundle.attachments.keys()) {
+		materializedSource = materializedSource
+			.split(registryTaskAttachmentMarker(name))
+			.join(`[Pix attachment: ${pathToFileURL(join(attachmentsPath, name)).href}]`);
+	}
+
+	const stamp = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+	const stagedTasks = join(dirname(tasksPath), `.tasks.registry-${stamp}.tmp`);
+	const stagedAttachments = join(dirname(tasksPath), `.task-attachments.registry-${stamp}.tmp`);
+	const backupTasks = join(dirname(tasksPath), `.tasks.registry-${stamp}.bak`);
+	const backupAttachments = join(dirname(tasksPath), `.task-attachments.registry-${stamp}.bak`);
+	let tasksBackedUp = false;
+	let attachmentsBackedUp = false;
+	let tasksInstalled = false;
+	let attachmentsInstalled = false;
+	try {
+		await fs.writeFile(stagedTasks, materializedSource, "utf8");
+		if (bundle.attachments.size > 0) {
+			await fs.mkdir(stagedAttachments, { recursive: true });
+			for (const name of [...bundle.attachments.keys()].sort()) {
+				await fs.copyFile(bundle.attachments.get(name)!, join(stagedAttachments, name));
+			}
+		}
+
+		if (await pathExists(tasksPath)) {
+			await fs.rename(tasksPath, backupTasks);
+			tasksBackedUp = true;
+		}
+		if (await pathExists(attachmentsPath)) {
+			await fs.rename(attachmentsPath, backupAttachments);
+			attachmentsBackedUp = true;
+		}
+		if (bundle.attachments.size > 0) {
+			await fs.rename(stagedAttachments, attachmentsPath);
+			attachmentsInstalled = true;
+		}
+		await fs.rename(stagedTasks, tasksPath);
+		tasksInstalled = true;
+	} catch (error) {
+		if (tasksInstalled) await fs.rm(tasksPath, { recursive: true, force: true }).catch(() => undefined);
+		if (attachmentsInstalled) await fs.rm(attachmentsPath, { recursive: true, force: true }).catch(() => undefined);
+		if (tasksBackedUp) await fs.rename(backupTasks, tasksPath).catch(() => undefined);
+		if (attachmentsBackedUp) await fs.rename(backupAttachments, attachmentsPath).catch(() => undefined);
+		throw error;
+	} finally {
+		await fs.rm(stagedTasks, { recursive: true, force: true }).catch(() => undefined);
+		await fs.rm(stagedAttachments, { recursive: true, force: true }).catch(() => undefined);
+	}
+	await fs.rm(backupTasks, { recursive: true, force: true }).catch(() => undefined);
+	await fs.rm(backupAttachments, { recursive: true, force: true }).catch(() => undefined);
+}
+
 async function readProvenance(project: ProjectContext): Promise<Provenance> {
 	try {
 		const parsed = JSON.parse(await fs.readFile(provenancePath(project), "utf8")) as Partial<Provenance>;
@@ -872,10 +1131,9 @@ async function collectProjectStatuses(
 			statuses.push({ artifact, kind: "removed-remote", localExists, remoteExists, provenance: tracked });
 			continue;
 		}
-		const rel = projectArtifactRelativePath(projectKey, artifact);
 		const [localHash, remoteRevision] = await Promise.all([
-			hashPath(localPath),
-			pathRevision(pi, runtime, rel),
+			hashProjectArtifactLocal(cwd, artifact),
+			projectArtifactRevision(pi, runtime, projectKey, artifact),
 		]);
 		const localChanged = localHash !== tracked.hash;
 		const remoteChanged = remoteRevision !== tracked.revision;
@@ -1518,18 +1776,21 @@ async function pushProjectState(pi: ExtensionAPI, ctx: ExtensionCommandContext,
 	for (const { artifact, deleteRemote } of targets) {
 		const localPath = projectArtifactLocalPath(ctx.cwd, artifact);
 		const remotePath = projectArtifactRegistryPath(runtime.cacheDir, projectKey, artifact);
-		const rel = projectArtifactRelativePath(projectKey, artifact);
 		const tracked = provenance.projectResources[artifact];
 		if (tracked && (tracked.remote !== runtime.remote || tracked.branch !== runtime.branch || tracked.projectKey !== projectKey)) {
 			throw new Error(`${artifact} state is tracked under another registry/branch/project key. Run /${COMMAND} status before pushing.`);
 		}
 		const remoteExists = await pathExists(remotePath);
-		const remoteRevision = remoteExists ? await pathRevision(pi, runtime, rel) : undefined;
+		const remoteRevision = remoteExists
+			? await projectArtifactRevision(pi, runtime, projectKey, artifact)
+			: undefined;
 		if (tracked && remoteRevision && remoteRevision !== tracked.revision) {
 			throw new Error(`${artifact} state changed in the registry since revision ${tracked.revision.slice(0, 8)}. Pull or resolve it before pushing.`);
 		}
-		const localHash = await hashPath(localPath);
-		if (!tracked && remoteExists && (deleteRemote || await hashPath(remotePath) !== localHash)) overwriteConflicts.push(artifact);
+		const localHash = await hashProjectArtifactLocal(ctx.cwd, artifact);
+		if (!tracked && remoteExists && (deleteRemote || await hashProjectArtifactRemote(runtime, projectKey, artifact) !== localHash)) {
+			overwriteConflicts.push(artifact);
+		}
 		localHashes.set(artifact, localHash);
 	}
 
@@ -1543,18 +1804,18 @@ async function pushProjectState(pi: ExtensionAPI, ctx: ExtensionCommandContext,
 		if (!confirmed) throw new Error(`Project state push cancelled because remote state already exists for: ${names}.`);
 	}
 
-	const rels: string[] = [];
 	for (const { artifact, deleteRemote } of targets) {
 		const localPath = projectArtifactLocalPath(ctx.cwd, artifact);
 		const remotePath = projectArtifactRegistryPath(runtime.cacheDir, projectKey, artifact);
 		if (deleteRemote) await fs.rm(remotePath, { recursive: true, force: true });
+		else if (artifact === "tasks") await replaceRemoteTaskBundle(ctx.cwd, runtime, projectKey);
 		else await replaceResource(localPath, remotePath);
-		rels.push(projectArtifactRelativePath(projectKey, artifact));
 	}
-	await runGit(pi, runtime.cacheDir, ["add", "-A", "--", ...rels]);
-	const changed = (await runGit(pi, runtime.cacheDir, ["status", "--porcelain", "--", ...rels])).stdout.trim();
+	const projectRel = `${REGISTRY_PROJECTS_DIR}/${projectKey}`;
+	await runGit(pi, runtime.cacheDir, ["add", "-A", "--", projectRel]);
+	const changed = (await runGit(pi, runtime.cacheDir, ["status", "--porcelain", "--", projectRel])).stdout.trim();
 	if (changed) {
-		await runGit(pi, runtime.cacheDir, ["commit", "-m", `Sync project state ${projectKey}`, "--", ...rels]);
+		await runGit(pi, runtime.cacheDir, ["commit", "-m", `Sync project state ${projectKey}`, "--", projectRel]);
 		try {
 			await runGit(pi, runtime.cacheDir, ["push", "-u", "origin", runtime.branch], { timeout: 180_000 });
 		} catch (error) {
@@ -1568,8 +1829,7 @@ async function pushProjectState(pi: ExtensionAPI, ctx: ExtensionCommandContext,
 			removedArtifacts.push(artifact);
 			continue;
 		}
-		const rel = projectArtifactRelativePath(projectKey, artifact);
-		const revision = await pathRevision(pi, runtime, rel);
+		const revision = await projectArtifactRevision(pi, runtime, projectKey, artifact);
 		if (!revision) throw new Error(`Cannot determine registry revision for project ${artifact} state.`);
 		await recordProjectProvenance(ctx, runtime, projectKey, artifact, revision, localHashes.get(artifact)!);
 	}
@@ -1599,16 +1859,15 @@ async function pullProjectState(pi: ExtensionAPI, ctx: ExtensionCommandContext,
 	for (const artifact of targets) {
 		const localPath = projectArtifactLocalPath(ctx.cwd, artifact);
 		const remotePath = projectArtifactRegistryPath(runtime.cacheDir, projectKey, artifact);
-		const rel = projectArtifactRelativePath(projectKey, artifact);
 		const tracked = provenance.projectResources[artifact];
 		if (tracked && (tracked.remote !== runtime.remote || tracked.branch !== runtime.branch || tracked.projectKey !== projectKey)) {
 			throw new Error(`${artifact} state is tracked under another registry/branch/project key. Run /${COMMAND} status before pulling.`);
 		}
-		const remoteRevision = await pathRevision(pi, runtime, rel);
+		const remoteRevision = await projectArtifactRevision(pi, runtime, projectKey, artifact);
 		if (!remoteRevision) throw new Error(`Cannot determine registry revision for project ${artifact} state.`);
-		const remoteHash = await hashPath(remotePath);
+		const remoteHash = await hashProjectArtifactRemote(runtime, projectKey, artifact);
 		if (await pathExists(localPath)) {
-			const localHash = await hashPath(localPath);
+			const localHash = await hashProjectArtifactLocal(ctx.cwd, artifact);
 			if (tracked && localHash !== tracked.hash) {
 				throw new Error(`Project ${artifact} state has local changes. Push or resolve them before pulling.`);
 			}
@@ -1630,9 +1889,11 @@ async function pullProjectState(pi: ExtensionAPI, ctx: ExtensionCommandContext,
 	for (const artifact of targets) {
 		const localPath = projectArtifactLocalPath(ctx.cwd, artifact);
 		const remotePath = projectArtifactRegistryPath(runtime.cacheDir, projectKey, artifact);
-		await replaceResource(remotePath, localPath);
+		if (artifact === "tasks") await replaceLocalTaskBundle(ctx.cwd, runtime, projectKey);
+		else await replaceResource(remotePath, localPath);
 		const item = metadata.get(artifact)!;
-		await recordProjectProvenance(ctx, runtime, projectKey, artifact, item.remoteRevision, item.remoteHash);
+		const localHash = await hashProjectArtifactLocal(ctx.cwd, artifact);
+		await recordProjectProvenance(ctx, runtime, projectKey, artifact, item.remoteRevision, localHash);
 	}
 	notify(ctx, `Pulled ${targets.join(" + ")} for ${projectKey}. Reloading project state…`);
 	await reloadAfterResourceChange(ctx);

package/external/pi-tools-suite/src/session-recovery/index.ts

@@ -201,6 +201,14 @@ function toolResultFrom(entry: EntryLike): UnknownRecord | undefined {
 	return message?.role === "toolResult" ? message : undefined;
 }
 
+function recoverableGatewayDetails(message: UnknownRecord): UnknownRecord | undefined {
+	const toolName = typeof message.toolName === "string" ? message.toolName.toLowerCase() : "";
+	if (toolName !== "web_search" && toolName !== "web_fetch") return undefined;
+	if (!isRecord(message.details) || !isRecord(message.details.contextGateway)) return undefined;
+	if (message.details.contextGateway.representation !== "web-recoverable-compact") return undefined;
+	return message.details;
+}
+
 function summaryFrom(entry: EntryLike): string {
 	if ((entry.type === "compaction" || entry.type === "branch_summary") && typeof entry.summary === "string") {
 		return entry.summary;
@@ -218,6 +226,11 @@ function entryText(entry: EntryLike): string {
 		for (const call of toolCallsFrom(entry)) {
 			chunks.push(call.name, serializeJson(call.arguments));
 		}
+		if (message.role === "toolResult") {
+			const toolName = typeof message.toolName === "string" ? message.toolName : "unknown";
+			const callId = typeof message.toolCallId === "string" ? message.toolCallId : "unknown";
+			chunks.push(`tool_result ${toolName}#${callId}`);
+		}
 	} else if (entry.type === "custom_message") {
 		const text = textFromContent(entry.content);
 		if (text) chunks.push(text);
@@ -416,6 +429,10 @@ function renderEntryFull(entry: EntryLike): string {
 			const toolName = typeof message.toolName === "string" ? message.toolName : "unknown";
 			const callId = typeof message.toolCallId === "string" ? message.toolCallId : "unknown";
 			lines.push(`tool_result ${toolName}#${callId}${message.isError === true ? " error" : ""}`);
+			const recoverableDetails = recoverableGatewayDetails(message);
+			if (recoverableDetails) {
+				lines.push("recoverable_raw_details:", serializeJson(recoverableDetails));
+			}
 		}
 	} else if (entry.type === "compaction") {
 		lines.push(summaryFrom(entry));

package/external/pi-tools-suite/src/todo/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { loadPiToolsSuiteConfig, type TodoThinkingLevel as ConfigTodoThinkingLevel } from "../config.js";
 import { isAgentBusyRaceError } from "../context-usage.js";
+import { hasAvailableIndexedProjectRoot } from "../lib/project.js";
 import { autoClearCompletedTodos } from "./state/auto-clear.js";
 import { loadPersistedPlan, syncPersistedPlan } from "./state/persistence.js";
 import { replayFromBranch } from "./state/replay.js";
@@ -32,6 +33,25 @@ const TODO_NUDGE_IDLE_RETRY_DELAY_MS = 100;
 const TODO_NUDGE_MAX_IDLE_ATTEMPTS = 40;
 const ASK_USER_TOOL_NAMES = new Set(["ask_user", "ask_user_question", "question"]);
 const TODO_THINKING_RESTORE_METADATA_KEY = "__piTodoRestoreThinking";
+const REPO_KNOWLEDGE_FINALIZATION_REMINDER =
+	"📚 Before completing the final todo: if behavior/contracts changed, reconcile affected specs and repo knowledge; skip for mechanical changes.";
+
+function completesTodo(info: { action: string; params: TaskMutationParams }): boolean {
+	if (info.action === "update") return info.params.status === "completed";
+	if (info.action !== "batch_update") return false;
+	return (info.params.items ?? []).some((item) => item.status === "completed");
+}
+
+function repoKnowledgeFinalizationReminder(
+	state: ReturnType<typeof getState>,
+	ctx: ExtensionContext,
+	info: { action: string; params: TaskMutationParams },
+): string | undefined {
+	if (!hasAvailableIndexedProjectRoot(ctx.cwd)) return undefined;
+	if (!completesTodo(info)) return undefined;
+	const remainingActive = selectVisibleTasks(state).filter((task) => ACTIVE_STATUSES.has(task.status));
+	return remainingActive.length === 1 ? REPO_KNOWLEDGE_FINALIZATION_REMINDER : undefined;
+}
 
 function isStaleExtensionContextError(error: unknown): boolean {
 	return error instanceof Error && /ctx is stale|stale ctx|stale after session replacement|stale after.*reload/i.test(error.message);
@@ -241,6 +261,7 @@ export default function (pi: ExtensionAPI) {
 		registerTodoTool(pi, {
 			...thinkingPrompt,
 			...(availableThinkingLevels ? { parameters: todoParamsSchemaForThinkingLevels(availableThinkingLevels) } : {}),
+			resultReminder: repoKnowledgeFinalizationReminder,
 			prepareMutation: (state, ctx, info) => {
 				if (!todoThinkingEnabled) return info.params;
 				if (info.action === "create" || info.action === "update") return prepareTodoThinkingMutation(state, ctx, info.params);

package/external/pi-tools-suite/src/todo/todo.ts

@@ -84,6 +84,11 @@ interface TodoToolHooks {
 		ctx: ExtensionContext,
 		info: { action: TaskAction; params: TaskMutationParams },
 	) => TaskMutationParams | Promise<TaskMutationParams>;
+	resultReminder?: (
+		state: ReturnType<typeof getState>,
+		ctx: ExtensionContext,
+		info: { action: TaskAction; params: TaskMutationParams },
+	) => string | undefined | Promise<string | undefined>;
 	afterCommit?: (
 		state: ReturnType<typeof getState>,
 		ctx: ExtensionContext,
@@ -448,7 +453,20 @@ export function registerTodoTool(pi: ExtensionAPI, hooks: TodoToolRegistrationOp
 				params: preparedParams,
 				committedState: autoClear.state,
 			});
-			const toolResult = buildToolResult(params.action, preparedParams, autoClear.state, result.op);
+			let toolResult = buildToolResult(params.action, preparedParams, autoClear.state, result.op);
+			const resultReminder = await hooks.resultReminder?.(result.state, _ctx as ExtensionContext, {
+				action: params.action,
+				params: preparedParams,
+			});
+			if (resultReminder?.trim()) {
+				toolResult = {
+					...toolResult,
+					content: [{
+						type: "text" as const,
+						text: `${toolResult.content[0]?.text ?? ""}\n\n${resultReminder.trim()}`.trim(),
+					}],
+				};
+			}
 			if (!autoClear.cleared) return toolResult;
 			return {
 				...toolResult,

package/external/pi-tools-suite/src/tool-descriptions.ts

@@ -17,6 +17,8 @@ export type RepoDiscoveryToolDescription = ToolDescription & Required<Pick<ToolD
 	targetDescription?: string;
 };
 
+export type RepoKnowledgeToolDescription = ToolDescription & Required<Pick<ToolDescription, "promptSnippet" | "promptGuidelines">>;
+
 export type ToolDescriptionSetOptions = {
 	repoDiscovery?: boolean;
 };
@@ -69,9 +71,9 @@ export function asyncSubagentToolDescriptions(options: ToolDescriptionSetOptions
 			name: "subagents",
 			label: "Subagents",
 			description: [
-				"For every real-browser QA request, immediately spawn subagentType='browser-qa' before checking files, URLs, servers, or other prerequisites; the QA sub-agent owns feasibility checks and blocked reports, so the parent must not attempt browser QA itself.",
-				"If browser-qa reports that credentials are required, it must identify the generated project-local template and explicitly ask the user to fill it; the parent relays that request without reading or editing the credential file.",
-				"After browser testing, browser-qa must return clickable links for every available screenshot, video, and trace; the parent must preserve those links in its user-facing report.",
+				"For every real user-interface QA request (browser, terminal/TUI, or desktop GUI), immediately spawn subagentType='ui-qa' before checking files, URLs, servers, launch commands, or other prerequisites; the QA sub-agent owns feasibility checks and blocked reports, so the parent must not substitute static checks for requested UI QA.",
+				"If ui-qa browser testing reports that credentials are required, it must identify the generated project-local template and explicitly ask the user to fill it; the parent relays that request without reading or editing the credential file.",
+				"After UI testing, ui-qa must return clickable links for every available screenshot, terminal capture, video, trace, or other retained evidence; the parent must preserve those links in its user-facing report.",
 				SUBAGENT_DELEGATION_GUIDANCE,
 				"Presets declare available models; each agent's ordered models selects the first usable model in that pool. AGENTS_PRESET or /subagent-preset session <name> selects the current session pool. Bundled pools live with agent files, and projects can override/add pools in .pi/agents/presets.jsonc. Do not override the model merely to choose a role.",
 				SUBAGENT_TYPE_SELECTION_GUIDANCE,
@@ -82,18 +84,18 @@ export function asyncSubagentToolDescriptions(options: ToolDescriptionSetOptions
 				"Results are compact with artifact links. Agents run isolated pi processes with extensions disabled to prevent recursive spawning; spawn/task timeoutSeconds can shorten the default 30m watchdog, project concurrency queues excess agents, and retry backoff/fallback models/Antigravity account rotation are config-driven.",
 			].join(" "),
 			promptSnippet:
-				"For every browser-based visual QA, UI bug reproduction, or real-browser fix-verification request, immediately spawn subagentType='browser-qa' even for a single track and before inspecting files or checking prerequisites. The browser-qa sub-agent must discover the target and report missing prerequisites; do not preflight, perform, or substitute browser QA in the parent agent. " +
-				"Give browser-qa a concise acceptance brief: the known target URL/app, user-visible flow, expected observable result, and required artifacts. Do not prescribe repository files, searches, commands, server setup, or mock/synthetic substitutes; unknown setup belongs to the QA sub-agent's discovery. " +
+				"For every real UI QA, UI bug reproduction, or user-facing fix-verification request across browser, terminal/TUI, or desktop GUI, immediately spawn subagentType='ui-qa' even for a single track and before inspecting files or checking prerequisites. The ui-qa sub-agent must discover the actual target/control path and report missing prerequisites; do not preflight, perform, or substitute requested UI QA in the parent agent. " +
+				"Give ui-qa a concise acceptance brief: the known target URL/app/command, user-visible flow, expected observable result, and required artifacts. Do not prescribe repository files, searches, commands, server setup, or mock/synthetic substitutes; unknown setup belongs to the QA sub-agent's discovery. " +
 				"For other work, use subagents action='spawn' for economical execution or context isolation, including one bounded sequential task or explicit delegate/parallelize/split work requests. " +
 				SUBAGENT_TYPE_SELECTION_GUIDANCE + " Avoid trivial reads/edits and do not call status/wait immediately after spawn just for progress. " +
 				(repoDiscovery
 					? "For one semantic code-discovery question, use repo_search; for independent tracks/hypotheses/review axes, delegate even when repo_* tools exist. Read result only after completion when findings are needed."
 					: "For one focused code-discovery question, use direct read/grep. Without repo_* tools, delegate bounded research tracks for broad discovery rather than flooding parent context. Read result only after completion when findings are needed."),
 			promptGuidelines: [
-				"Treat every real-browser QA request as a mandatory delegation trigger and an explicit exception to the large/parallel threshold: immediately spawn with `subagentType: \"browser-qa\"` before checking prerequisites. The QA sub-agent owns target discovery, feasibility checks, browser automation, evidence, and blocked reports; the parent must not inspect the project first or substitute non-browser checks.",
-				"Keep the browser-qa task payload at the user-visible acceptance level: known target URL/app, actions to perform, expected observable outcome, and requested evidence. Do not turn it into a repository investigation plan, name internal files or commands, dictate server setup, or invent a mock/synthetic target. Leave unknown prerequisites to the QA sub-agent.",
-				"When browser-qa reports missing credentials, relay its explicit request and generated `.pi/qa_auth.jsonc` template path; never inspect, populate, or edit that credential file in the parent.",
-				"After browser-qa completes a test, preserve its clickable screenshot, video, and trace links in the final user-facing response whenever those artifacts exist.",
+				"Treat every real UI QA request as a mandatory delegation trigger and an explicit exception to the large/parallel threshold: immediately spawn with `subagentType: \"ui-qa\"` before checking prerequisites. The QA sub-agent owns target discovery, feasibility checks, UI automation, evidence, and blocked reports; the parent must not inspect the project first or substitute non-UI checks.",
+				"Keep the ui-qa task payload at the user-visible acceptance level: known target URL/app/command, actions to perform, expected observable outcome, and requested evidence. Do not turn it into a repository investigation plan, name internal files or commands, dictate setup, or invent a mock/synthetic target. Leave unknown prerequisites to the QA sub-agent.",
+				"When ui-qa browser testing reports missing credentials, relay its explicit request and generated `.pi/qa_auth.jsonc` template path; never inspect, populate, or edit that credential file in the parent.",
+				"After ui-qa completes a test, preserve its clickable screenshot, terminal capture, video, trace, and other evidence links in the final user-facing response whenever those artifacts exist.",
 				SUBAGENT_DELEGATION_GUIDANCE,
 				repoDiscovery
 					? "For one discovery question, use repo_search; spawn for independent tracks/hypotheses/review axes, and do not let repo_* availability suppress delegation."
@@ -221,7 +223,24 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 	},
 ];
 
-export const REPO_DISCOVERY_TOOL_NAMES = REPO_DISCOVERY_TOOLS.map((tool) => tool.name);
+export const REPO_KNOWLEDGE_TOOL_DESCRIPTION: RepoKnowledgeToolDescription = {
+	name: "repo_knowledge",
+	label: "Repo Knowledge",
+	description:
+		"Project behavioral knowledge/spec maintenance backed by idx. Query contracts with context/search/show/status, review task-scoped impact after material behavior changes, discover new/moved docs, and explicitly record/relate/verify metadata only after semantic evidence review. This tool is exposed only when idx is available and the project is indexed.",
+	promptSnippet:
+		"Use repo_knowledge for project behavior/contracts and their maintenance. For a behavior/contract question that also needs implementation/tests/freshness, prefer action=context; use action=search when only the relevant specs/contracts are needed. Before a material behavior change, find the current primary contract; after implementation, run action=impact on this task's changed paths. Update the existing spec, or create a focused new spec with Edit/Write/apply_patch when no suitable contract exists, then record/relate and verify only after checking code/tests. Skip this lifecycle for mechanical/non-behavioral edits.",
+	promptGuidelines: [
+		"Primary specs/contracts are authoritative; catalog/search summaries, embeddings, graph proximity and semantic candidates are routing evidence only. record is classification, not verification; non-fresh status requires review before presenting behavior as current.",
+		"For material externally visible or project-contract behavior changes: query existing knowledge before/while implementing, keep the authoritative spec aligned in the same task, create a focused primary spec when no suitable contract exists, then run task-scoped impact and reconcile uncovered/new/moved docs before finishing.",
+		"Never persist a relation from similarity alone and never add one just to make coverage non-empty. A reviewed no-impact outcome is valid. verify only after reading the primary source and checking relevant implementation/tests; changed code never auto-rewrites spec semantics.",
+	],
+};
+
+export const REPO_DISCOVERY_TOOL_NAMES = [
+	...REPO_DISCOVERY_TOOLS.map((tool) => tool.name),
+	REPO_KNOWLEDGE_TOOL_DESCRIPTION.name,
+];
 
 export const TODO_TOOL_DESCRIPTION: ToolDescription = {
 	name: "todo",
@@ -332,12 +351,16 @@ export function claudeAliasToolDescriptions(options: ToolDescriptionSetOptions |
 		Edit: {
 			name: "Edit",
 			label: "Edit",
-			description: "Replace exact text in an existing file. Use for surgical edits; use Write only for intentional whole-file replacement.",
+			description: repoDiscovery
+				? "Replace exact text in an existing file. Use for surgical edits; use Write only for whole-file replacement. After a material behavior change, do not finish until repo_knowledge impact reviews this task's changed paths and the authoritative spec is updated or created and verified; skip that lifecycle for mechanical/non-behavioral edits."
+				: "Replace exact text in an existing file. Use for surgical edits; use Write only for intentional whole-file replacement.",
 		},
 		Write: {
 			name: "Write",
 			label: "Write",
-			description: "Create or overwrite a file with complete contents. Use only when replacing the whole file is intended.",
+			description: repoDiscovery
+				? "Create or overwrite a file with complete contents. Use only for intentional whole-file writes. When creating/changing material project behavior, keep or create the primary spec in the same task and finish with task-scoped repo_knowledge impact + semantic verification; mechanical/non-behavioral writes do not require it."
+				: "Create or overwrite a file with complete contents. Use only when replacing the whole file is intended.",
 		},
 		Bash: {
 			name: "Bash",
@@ -364,7 +387,9 @@ export function claudeAliasToolDescriptions(options: ToolDescriptionSetOptions |
 export const CLAUDE_ALIAS_TOOL_DESCRIPTIONS = claudeAliasToolDescriptions(false);
 export const CLAUDE_ALIAS_TOOL_DESCRIPTIONS_WITH_REPO = claudeAliasToolDescriptions(true);
 
-export const CODEX_ALIAS_TOOL_DESCRIPTIONS = {
+export function codexAliasToolDescriptions(options: ToolDescriptionSetOptions | boolean = false) {
+	const repoDiscovery = hasRepoDiscovery(options);
+	return {
 	shellCommand: {
 		name: "shell",
 		label: "shell",
@@ -373,7 +398,7 @@ export const CODEX_ALIAS_TOOL_DESCRIPTIONS = {
 	applyPatch: {
 		name: "apply_patch",
 		label: "apply_patch",
-		description: `Apply file edits with a relative-path patch or standard unified diff. Use for creating, updating, moving, or deleting files; keep each patch focused.
+		description: `Apply file edits with a relative-path patch or standard unified diff. Use for creating, updating, moving, or deleting files; keep each patch focused.${repoDiscovery ? " After a material behavior change, keep/create the authoritative primary spec in the same task and finish with task-scoped repo_knowledge impact plus semantic verification; skip this for mechanical/non-behavioral edits." : ""}
 
 Begin-patch format:
 *** Begin Patch
@@ -387,4 +412,8 @@ Sections: *** Add File (new lines start with +), *** Update File (optionally ***
 
 Unified diff with ---/+++ headers is also supported. Paths must be workspace-relative, never absolute. Provide the complete patch in input.`,
 	},
-} satisfies Record<string, ToolDescription>;
+	} satisfies Record<string, ToolDescription>;
+}
+
+export const CODEX_ALIAS_TOOL_DESCRIPTIONS = codexAliasToolDescriptions(false);
+export const CODEX_ALIAS_TOOL_DESCRIPTIONS_WITH_REPO = codexAliasToolDescriptions(true);