@oh-my-pi/pi-coding-agent 17.0.9 → 17.1.0

package/src/tools/read.ts

@@ -11,12 +11,14 @@ import type {
 	ToolTier,
 } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
-import { glob, type SummaryResult, summarizeCode } from "@oh-my-pi/pi-natives";
+import { type SummaryResult, summarizeCode } from "@oh-my-pi/pi-natives";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import {
 	getRemoteDir,
 	type ImageMetadata,
+	isEexist,
+	isEnotempty,
 	isProbablyBinary,
 	logger,
 	prompt,
@@ -40,7 +42,7 @@ import { InternalUrlRouter, resolveLocalUrlToFile, resolveLocalUrlToPath } from
 import { type ResolvedArtifactFile, resolveArtifactFile } from "../internal-urls/artifact-protocol";
 import { parseInternalUrl } from "../internal-urls/parse";
 import type { InternalUrl } from "../internal-urls/types";
-import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
+import { getLanguageFromPath, isMarkdownPath, type Theme } from "../modes/theme/theme";
 import readDescription from "../prompts/tools/read.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
 import {
@@ -94,6 +96,7 @@ import {
 } from "./output-meta";
 import {
 	expandPath,
+	findUniqueWorkspaceSuffix,
 	formatPathRelativeToCwd,
 	isReadableUrlPath,
 	type LineRange,
@@ -155,12 +158,13 @@ const MAX_SUMMARY_BYTES = 2 * 1024 * 1024;
 const MAX_SUMMARY_LINES = 20_000;
 const MAX_ARTIFACT_RAW_INLINE_BYTES = DEFAULT_MAX_BYTES;
 /**
- * Per-line column cap for file reads. Lines wider than the value of
- * `tools.outputMaxColumns` are ellipsis-truncated at display time; the file
- * on disk is unchanged. Shared with the streaming sink path so one setting
- * covers `bash`/`ssh`/`python`/`js eval` and `read` uniformly.
+ * Prose files (Markdown flavors and plain text) skip code-block summarization
+ * unless `read.summarize.prose` opts them in.
  */
-const PROSE_SUMMARY_EXTENSIONS = new Set([".md", ".txt"]);
+function isProseSummaryPath(filePath: string): boolean {
+	return isMarkdownPath(filePath) || path.extname(filePath).toLowerCase() === ".txt";
+}
+
 // Remote mount path prefix (sshfs mounts) - skip fuzzy matching to avoid hangs
 const REMOTE_MOUNT_PREFIX = getRemoteDir() + path.sep;
 
@@ -639,7 +643,6 @@ async function streamLinesFromFile(
 
 // Maximum image file size (20MB) - larger images will be rejected to prevent OOM during serialization
 const MAX_IMAGE_SIZE = MAX_IMAGE_INPUT_BYTES;
-const GLOB_TIMEOUT_MS = 5000;
 
 function isNotFoundError(error: unknown): boolean {
 	if (!error || typeof error !== "object") return false;
@@ -647,61 +650,6 @@ function isNotFoundError(error: unknown): boolean {
 	return code === "ENOENT" || code === "ENOTDIR";
 }
 
-/**
- * Escape glob metacharacters so a literal path (e.g. `foo[1].ts`) interpolated
- * into a suffix-glob pattern matches itself. Each metachar is wrapped in a
- * character class (the native glob engine rewrites `\` to `/`, so backslash
- * escaping is unavailable). `]`/`}` need no escaping once their openers are
- * neutralized — unmatched closers are literal.
- */
-function escapeGlobMetachars(value: string): string {
-	return value.replace(/[*?[{]/g, "[$&]");
-}
-
-/**
- * Attempt to resolve a non-existent path by finding a unique suffix match within the workspace.
- * Uses a glob suffix pattern so the native engine handles matching directly.
- * Returns null when 0 or >1 candidates match (ambiguous = no auto-resolution).
- */
-async function findUniqueSuffixMatch(
-	rawPath: string,
-	cwd: string,
-	signal?: AbortSignal,
-): Promise<{ absolutePath: string; displayPath: string } | null> {
-	const normalized = rawPath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
-	if (!normalized) return null;
-	const pattern = `**/${escapeGlobMetachars(normalized)}`;
-
-	const timeoutSignal = AbortSignal.timeout(GLOB_TIMEOUT_MS);
-	const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
-
-	let matches: string[];
-	try {
-		const result = await untilAborted(combinedSignal, () =>
-			glob({
-				pattern,
-				path: cwd,
-				// No fileType filter: matches both files and directories
-				hidden: true,
-			}),
-		);
-		matches = result.matches.map(m => m.path);
-	} catch (error) {
-		if (error instanceof Error && error.name === "AbortError") {
-			if (!signal?.aborted) return null; // timeout — give up silently
-			throw new ToolAbortError();
-		}
-		return null;
-	}
-
-	if (matches.length !== 1) return null;
-
-	return {
-		absolutePath: path.resolve(cwd, matches[0]),
-		displayPath: matches[0],
-	};
-}
-
 function decodeUtf8Text(bytes: Uint8Array): string | null {
 	if (bytes.indexOf(0) !== -1) return null;
 
@@ -721,6 +669,22 @@ function prependSuffixResolutionNotice(text: string, suffixResolution?: { from:
 const PDF_IMAGE_PLACEHOLDER_RE = /<!--\s*image:\s*([^\s<>]+)(.*?)-->/g;
 const PDF_IMAGE_MEMBER_RE = /^(.*\.pdf):(.*)$/i;
 const PDF_IMAGE_MEMBER_EXTENSION_RE = /\.png$/i;
+const PDF_IMAGE_CACHE_BASENAME_MAX_LENGTH = 96;
+
+interface PdfImageSnapshot {
+	directory: string;
+	filePath: string;
+	digest: string;
+}
+
+interface PdfImageExtraction {
+	controller: AbortController;
+	promise: Promise<string>;
+	settled: boolean;
+	waiters: number;
+}
+
+const pdfImageExtractions = new Map<string, PdfImageExtraction>();
 
 function pdfImageMemberPath(pdfPath: string, imageId: string): string {
 	const member = PDF_IMAGE_MEMBER_EXTENSION_RE.test(imageId) ? imageId : `${imageId}.png`;
@@ -779,7 +743,6 @@ export interface ReadToolDetails {
 	/** Paths recovered from a delimited read argument; used only by the TUI to render one call as multiple read rows. */
 	displayReadTargets?: string[];
 }
-
 type ReadParams = ReadToolInput;
 
 /** Parsed representation of a path-embedded selector. */
@@ -991,7 +954,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 	}
 
 	/**
-	 * Memoized {@link findUniqueSuffixMatch} for a single read call. A missing
+	 * Memoized {@link findUniqueWorkspaceSuffix} for a single read call. A missing
 	 * path with archive/sqlite extensions probes the workspace once per stage
 	 * (archive candidates, sqlite candidates, plain path) — each glob carries a
 	 * 5s timeout, so repeated lookups of the same string stack into a long
@@ -1004,7 +967,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 	): Promise<{ absolutePath: string; displayPath: string } | null> {
 		const hit = cache.get(rawPath);
 		if (hit !== undefined) return hit;
-		const result = await findUniqueSuffixMatch(rawPath, this.session.cwd, signal);
+		const result = await findUniqueWorkspaceSuffix(rawPath, this.session.cwd, signal);
 		cache.set(rawPath, result);
 		return result;
 	}
@@ -1106,7 +1069,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		return null;
 	}
 
-	#pdfImageCacheDir(absolutePdfPath: string): string {
+	#pdfImageCacheDir(absolutePdfPath: string, contentDigest: string): string {
 		const artifactsDir = this.session.getArtifactsDir?.();
 		let root = artifactsDir ?? undefined;
 		if (root === undefined) {
@@ -1115,8 +1078,28 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				? sessionFile.slice(0, -6)
 				: path.join(os.tmpdir(), "omp-read-pdf-images");
 		}
-		const basename = path.basename(absolutePdfPath).replace(/[^A-Za-z0-9._-]/g, "_");
-		return path.join(root, "read-pdf-images", `${basename}-${Bun.hash(absolutePdfPath).toString(36)}`);
+		const basename = path
+			.basename(absolutePdfPath)
+			.replace(/[^A-Za-z0-9._-]/g, "_")
+			.slice(0, PDF_IMAGE_CACHE_BASENAME_MAX_LENGTH);
+		const pathDigest = Bun.hash(absolutePdfPath).toString(36);
+		return path.join(root, "read-pdf-images", `${basename}-${pathDigest}-${contentDigest}`);
+	}
+
+	async #snapshotPdfSource(absolutePdfPath: string, signal?: AbortSignal): Promise<PdfImageSnapshot> {
+		const directory = await fs.mkdtemp(path.join(os.tmpdir(), "omp-read-pdf-"));
+		try {
+			const bytes = await untilAborted(signal, () => Bun.file(absolutePdfPath).bytes());
+			signal?.throwIfAborted();
+			const digest = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+			const filePath = path.join(directory, "source.pdf");
+			await Bun.write(filePath, bytes);
+			signal?.throwIfAborted();
+			return { directory, filePath, digest };
+		} catch (error) {
+			await fs.rm(directory, { recursive: true, force: true });
+			throw error;
+		}
 	}
 
 	async #listPdfImageMembers(imageDir: string): Promise<string[]> {
@@ -1133,8 +1116,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 	}
 
-	async #ensurePdfImageCache(absolutePdfPath: string, signal?: AbortSignal): Promise<string> {
-		const imageDir = this.#pdfImageCacheDir(absolutePdfPath);
+	async #extractPdfImages(snapshot: PdfImageSnapshot, imageDir: string, signal: AbortSignal): Promise<string> {
 		const markerPath = path.join(imageDir, ".extracted");
 		try {
 			await fs.stat(markerPath);
@@ -1143,15 +1125,74 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			if (!isNotFoundError(error)) throw error;
 		}
 
-		await fs.rm(imageDir, { recursive: true, force: true });
-		await fs.mkdir(imageDir, { recursive: true });
-		const result = await convertFileWithMarkit(absolutePdfPath, signal, { imageDir });
-		if (!result.ok) {
-			await fs.rm(imageDir, { recursive: true, force: true });
-			throw new ToolError(`Cannot extract images from PDF: ${result.error ?? "conversion failed"}`);
+		await fs.mkdir(path.dirname(imageDir), { recursive: true });
+		const stagingDir = await fs.mkdtemp(`${imageDir}.tmp-`);
+		let published = false;
+		try {
+			const result = await convertFileWithMarkit(snapshot.filePath, signal, { imageDir: stagingDir });
+			if (!result.ok) {
+				throw new ToolError(`Cannot extract images from PDF: ${result.error ?? "conversion failed"}`);
+			}
+			await Bun.write(path.join(stagingDir, ".extracted"), "ok");
+			try {
+				await fs.rename(stagingDir, imageDir);
+				published = true;
+			} catch (error) {
+				if (!isEexist(error) && !isEnotempty(error)) throw error;
+				try {
+					await fs.stat(markerPath);
+				} catch (markerError) {
+					if (isNotFoundError(markerError)) throw error;
+					throw markerError;
+				}
+			}
+			return imageDir;
+		} finally {
+			if (!published) await fs.rm(stagingDir, { recursive: true, force: true });
+		}
+	}
+
+	#createPdfImageExtraction(snapshot: PdfImageSnapshot, imageDir: string): PdfImageExtraction {
+		const controller = new AbortController();
+		const promise = this.#extractPdfImages(snapshot, imageDir, controller.signal).finally(() =>
+			fs.rm(snapshot.directory, { recursive: true, force: true }),
+		);
+		const extraction: PdfImageExtraction = { controller, promise, settled: false, waiters: 0 };
+		const settle = () => {
+			extraction.settled = true;
+			if (pdfImageExtractions.get(imageDir) === extraction) pdfImageExtractions.delete(imageDir);
+		};
+		void promise.then(settle, settle);
+		return extraction;
+	}
+
+	async #waitForPdfImageExtraction(extraction: PdfImageExtraction, signal: AbortSignal | undefined): Promise<string> {
+		extraction.waiters++;
+		try {
+			return await untilAborted(signal, extraction.promise);
+		} finally {
+			extraction.waiters--;
+			if (extraction.waiters === 0 && !extraction.settled) {
+				extraction.controller.abort();
+				try {
+					await extraction.promise;
+				} catch {}
+			}
 		}
-		await Bun.write(markerPath, "ok");
-		return imageDir;
+	}
+
+	async #ensurePdfImageCache(absolutePdfPath: string, signal?: AbortSignal): Promise<string> {
+		const snapshot = await this.#snapshotPdfSource(absolutePdfPath, signal);
+		const imageDir = this.#pdfImageCacheDir(absolutePdfPath, snapshot.digest);
+		const existing = pdfImageExtractions.get(imageDir);
+		if (existing && !existing.settled && !existing.controller.signal.aborted) {
+			await fs.rm(snapshot.directory, { recursive: true, force: true });
+			return this.#waitForPdfImageExtraction(existing, signal);
+		}
+
+		const extraction = this.#createPdfImageExtraction(snapshot, imageDir);
+		pdfImageExtractions.set(imageDir, extraction);
+		return this.#waitForPdfImageExtraction(extraction, signal);
 	}
 
 	async #readPdfImageMember(
@@ -1598,7 +1639,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			try {
 				const bridgeText = await bridgePromise;
 				const bridgeResult = this.#buildInMemoryMultiRangeResult(bridgeText, ranges, {
-					details: { resolvedPath: absolutePath, suffixResolution },
+					details: this.#markMarkdownContentType({ resolvedPath: absolutePath, suffixResolution }, absolutePath),
 					sourcePath: absolutePath,
 					entityLabel: "file",
 					raw: rawSelector,
@@ -1781,10 +1822,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const archive = await openArchive(resolvedArchivePath.absolutePath);
 		throwIfAborted(signal);
 
-		const details: ReadToolDetails = {
-			resolvedPath: resolvedArchivePath.absolutePath,
-			suffixResolution: resolvedArchivePath.suffixResolution,
-		};
+		const details: ReadToolDetails = this.#markMarkdownContentType(
+			{
+				resolvedPath: resolvedArchivePath.absolutePath,
+				suffixResolution: resolvedArchivePath.suffixResolution,
+			},
+			resolvedArchivePath.archiveSubPath,
+		);
 
 		let archiveSubPath = resolvedArchivePath.archiveSubPath;
 		let sel = parsedSel;
@@ -1995,6 +2039,20 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		return bridge.readTextFile({ path: absolutePath, ...options });
 	}
 
+	/**
+	 * Tag Markdown reads for the TUI's formatted preview, gated on the opt-in
+	 * `read.renderMarkdown` setting. Off by default; when disabled, no local
+	 * read is tagged `text/markdown`, so the renderer output is identical to
+	 * the pre-setting behavior. Internal-URL reads keep their protocol-supplied
+	 * `contentType` and render as Markdown regardless of the setting.
+	 */
+	#markMarkdownContentType(details: ReadToolDetails, filePath: string): ReadToolDetails {
+		if (!details.contentType && this.session.settings.get("read.renderMarkdown") && isMarkdownPath(filePath)) {
+			details.contentType = "text/markdown";
+		}
+		return details;
+	}
+
 	async #trySummarize(absolutePath: string, fileSize: number, signal?: AbortSignal): Promise<SummaryResult | null> {
 		if (fileSize > MAX_SUMMARY_BYTES) return null;
 
@@ -2419,14 +2477,20 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				// because only `truncateHead` was being applied.
 				if (isMultiRange(parsed) && parsed.kind === "lines") {
 					return this.#buildInMemoryMultiRangeResult(renderedContent, parsed.ranges, {
-						details: { resolvedPath: absolutePath },
+						details: {
+							resolvedPath: absolutePath,
+							contentType: this.session.settings.get("read.renderMarkdown") ? "text/markdown" : undefined,
+						},
 						sourcePath: absolutePath,
 						entityLabel: "document",
 					});
 				}
 				const { offset, limit } = selToOffsetLimit(parsed);
 				return this.#buildInMemoryTextResult(renderedContent, offset, limit, {
-					details: { resolvedPath: absolutePath },
+					details: {
+						resolvedPath: absolutePath,
+						contentType: this.session.settings.get("read.renderMarkdown") ? "text/markdown" : undefined,
+					},
 					sourcePath: absolutePath,
 					entityLabel: "document",
 					raw: isRawSelector(parsed),
@@ -2459,7 +2523,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			if (
 				parsed.kind === "none" &&
 				this.session.settings.get("read.summarize.enabled") &&
-				(this.session.settings.get("read.summarize.prose") || !PROSE_SUMMARY_EXTENSIONS.has(ext))
+				(this.session.settings.get("read.summarize.prose") || !isProseSummaryPath(absolutePath))
 			) {
 				const summary = await this.#trySummarize(absolutePath, fileSize, signal);
 				if (summary?.parsed && summary.elided) {
@@ -2519,7 +2583,10 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						try {
 							const bridgeText = await bridgePromise;
 							const bridgeResult = this.#buildInMemoryTextResult(bridgeText, offset, limit, {
-								details: { resolvedPath: absolutePath, suffixResolution },
+								details: this.#markMarkdownContentType(
+									{ resolvedPath: absolutePath, suffixResolution },
+									absolutePath,
+								),
 								sourcePath: absolutePath,
 								entityLabel: "file",
 								raw: isRawSelector(parsed),
@@ -2818,6 +2885,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			}
 		}
 
+		this.#markMarkdownContentType(details, absolutePath);
 		if (suffixResolution) {
 			details.suffixResolution = suffixResolution;
 			// Inline resolution notice into first text block so the model sees the actual path

package/src/tools/renderers.ts

@@ -90,7 +90,13 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	grep: grepToolRenderer as ToolRenderer,
 	lsp: lspToolRenderer as ToolRenderer,
 	inspect_image: inspectImageToolRenderer as ToolRenderer,
-	hub: hubToolRenderer as ToolRenderer,
+	// Lazy getter: `hubToolRenderer` lives in a module whose deps (messaging →
+	// persisted-agents → vibe/runtime → task/executor → sdk) close an import
+	// cycle back here, so reading it at init order-dependently hits its
+	// temporal dead zone. Deferring the read to first access sidesteps it.
+	get hub(): ToolRenderer {
+		return hubToolRenderer as ToolRenderer;
+	},
 	read: readToolRenderer as ToolRenderer,
 	// Keyed by xd:// resolution-device names: the write dispatch delegates here
 	// by dispatch tool, and historical `resolve` tool transcripts still render

package/src/tools/todo.ts

@@ -2,7 +2,7 @@ import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallb
 import type { ToolExample } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
-import { prompt } from "@oh-my-pi/pi-utils";
+import { isRecord, prompt } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
 import chalk from "chalk";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
@@ -18,13 +18,15 @@ import { formatErrorDetail, formatMoreItems, PREVIEW_LIMITS, pluralize } from ".
 // Types
 // =============================================================================
 
-export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
+export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned" | "blocked";
 /** Operation names accepted by the todo tool and echoed in successful result details. */
-export type TodoOperation = "init" | "start" | "done" | "rm" | "drop" | "append" | "view";
+export type TodoOperation = "init" | "start" | "done" | "rm" | "drop" | "block" | "unblock" | "append" | "view";
 
 export interface TodoItem {
 	content: string;
 	status: TodoStatus;
+	/** When `status === "blocked"`, an optional note on what the task is waiting for. */
+	blocker?: string;
 }
 
 export interface TodoPhase {
@@ -32,6 +34,21 @@ export interface TodoPhase {
 	tasks: TodoItem[];
 }
 
+/** Whether an unknown value is a persisted todo phase. */
+export function isTodoPhase(value: unknown): value is TodoPhase {
+	if (!isRecord(value) || typeof value.name !== "string" || !Array.isArray(value.tasks)) return false;
+	return value.tasks.every(
+		task =>
+			isRecord(task) &&
+			typeof task.content === "string" &&
+			(task.status === "pending" ||
+				task.status === "in_progress" ||
+				task.status === "completed" ||
+				task.status === "abandoned" ||
+				task.status === "blocked"),
+	);
+}
+
 export interface TodoCompletionTransition {
 	phase: string;
 	content: string;
@@ -49,7 +66,9 @@ export interface TodoToolDetails {
 // Schema
 // =============================================================================
 
-const TodoOp = type('"init" | "start" | "done" | "rm" | "drop" | "append" | "view"').describe("operation to apply");
+const TodoOp = type('"init" | "start" | "done" | "rm" | "drop" | "block" | "unblock" | "append" | "view"').describe(
+	"operation to apply",
+);
 
 const InitListEntry = type({
 	phase: type("string").describe("phase name"),
@@ -65,6 +84,7 @@ const todoSchema = type({
 	// and both enforce non-empty with op-specific errors. A stray `items: []` on
 	// an op that ignores it (e.g. `view`) must not be a hard schema rejection.
 	"items?": type("string").describe("task content").array().describe("tasks to append"),
+	"reason?": type("string").describe("blocker note (block op)"),
 }).describe("apply a single todo operation");
 
 type TodoParams = TodoSchema;
@@ -89,7 +109,9 @@ function findPhaseByName(phases: TodoPhase[], name: string): TodoPhase | undefin
 }
 
 function cloneTask(task: TodoItem): TodoItem {
-	return { content: task.content, status: task.status };
+	return task.blocker !== undefined
+		? { content: task.content, status: task.status, blocker: task.blocker }
+		: { content: task.content, status: task.status };
 }
 
 function clonePhases(phases: TodoPhase[]): TodoPhase[] {
@@ -256,7 +278,9 @@ export function selectCollapsedTodos<T extends { status: TodoStatus }>(
 	isMatched: (task: T) => boolean,
 	cap: number,
 ): CollapsedTodoSelection<T> {
-	const open = tasks.filter(task => task.status === "pending" || task.status === "in_progress");
+	const open = tasks.filter(
+		task => task.status === "pending" || task.status === "in_progress" || task.status === "blocked",
+	);
 	// No open work: fall back to the closed tasks so a settled phase still
 	// renders (HUD closed-todo persistence). Closed tasks are never active.
 	const base = open.length > 0 ? open : tasks;
@@ -456,6 +480,41 @@ function applyEntry(phases: TodoPhase[], entry: TodoOpEntryValue, errors: string
 			}
 			return phases;
 		}
+		case "block": {
+			if (!entry.task && !entry.phase) {
+				errors.push("block requires a task or phase target");
+				return phases;
+			}
+			// Collapse whitespace runs (incl. newlines) to single spaces: a blocker
+			// note rides on one Markdown checklist line (as a trailing HTML comment)
+			// and one HUD/summary line, so an embedded newline from a multi-line
+			// external error or user question would corrupt the round-trip parse and
+			// the rendered line. Normalizing here keeps every consumer one-line-safe.
+			const reason = entry.reason?.replace(/\s+/g, " ").trim() || undefined;
+			for (const task of getTaskTargets(phases, entry, errors)) {
+				// Only actionable open work can be blocked: blocking a phase must not
+				// reopen completed/abandoned tasks or erase finished progress. An
+				// already-blocked task stays eligible so a later block can refine its
+				// blocker note (e.g. first blocked without a reason, then with one).
+				if (task.status !== "pending" && task.status !== "in_progress" && task.status !== "blocked") continue;
+				task.status = "blocked";
+				task.blocker = reason;
+			}
+			return phases;
+		}
+		case "unblock": {
+			if (!entry.task && !entry.phase) {
+				errors.push("unblock requires a task or phase target");
+				return phases;
+			}
+			for (const task of getTaskTargets(phases, entry, errors)) {
+				if (task.status === "blocked") {
+					task.status = "pending";
+					task.blocker = undefined;
+				}
+			}
+			return phases;
+		}
 		case "rm":
 			return removeTasks(phases, entry, errors);
 		case "append":
@@ -495,6 +554,7 @@ const STATUS_TO_MARKER: Record<TodoStatus, string> = {
 	in_progress: "/",
 	completed: "x",
 	abandoned: "-",
+	blocked: "!",
 };
 
 export function resolveTodoMarkdownPath(input: string, cwd: string): string {
@@ -510,7 +570,12 @@ export function phasesToMarkdown(phases: TodoPhase[]): string {
 		if (i > 0) out.push("");
 		out.push(`# ${phases[i].name}`);
 		for (const task of phases[i].tasks) {
-			out.push(`- [${STATUS_TO_MARKER[task.status]}] ${task.content}`);
+			// A blocked task's reason rides in a trailing HTML comment: invisible in
+			// rendered markdown, unambiguous to parse back (task content can't
+			// contain the comment delimiters), so the note survives `/todo edit` and
+			// export/import round-trips.
+			const blockerNote = task.status === "blocked" && task.blocker ? ` <!-- blocker: ${task.blocker} -->` : "";
+			out.push(`- [${STATUS_TO_MARKER[task.status]}] ${task.content}${blockerNote}`);
 		}
 	}
 	return `${out.join("\n")}\n`;
@@ -525,6 +590,7 @@ const MARKER_TO_STATUS: Record<string, TodoStatus> = {
 	">": "in_progress",
 	"-": "abandoned",
 	"~": "abandoned",
+	"!": "blocked",
 };
 
 /** Parse a Markdown checklist back into todo phases. */
@@ -556,10 +622,18 @@ export function markdownToPhases(md: string): { phases: TodoPhase[]; errors: str
 			const marker = taskMatch[1];
 			const status = MARKER_TO_STATUS[marker];
 			if (!status) {
-				errors.push(`Line ${lineNum + 1}: unknown status marker "[${marker}]" (use [ ], [x], [/], [-])`);
+				errors.push(`Line ${lineNum + 1}: unknown status marker "[${marker}]" (use [ ], [x], [/], [-], [!])`);
 				continue;
 			}
-			currentPhase.tasks.push({ content: taskMatch[2].trim(), status });
+			// Recover a blocked task's reason from its trailing HTML comment (see
+			// phasesToMarkdown), then strip the comment from the visible content.
+			const rawContent = taskMatch[2].trim();
+			const blockerMatch = /^(.*?)\s*<!--\s*blocker:\s*(.*?)\s*-->$/.exec(rawContent);
+			if (status === "blocked" && blockerMatch) {
+				currentPhase.tasks.push({ content: blockerMatch[1].trim(), status, blocker: blockerMatch[2].trim() });
+			} else {
+				currentPhase.tasks.push({ content: rawContent, status });
+			}
 			continue;
 		}
 
@@ -604,6 +678,7 @@ function formatSummary(phases: TodoPhase[], errors: string[], readOnly = false):
 	}
 	// Closed = completed + abandoned, mirroring the per-phase `done` count.
 	const closedAll = tasks.filter(task => task.status === "completed" || task.status === "abandoned").length;
+	const blockedAll = tasks.filter(task => task.status === "blocked").length;
 	// The active phase is the EARLIEST one still holding open work, so the
 	// in-progress pointer can sit in a phase whose successors already have
 	// completed tasks. Detect that "worked ahead" case to explain the
@@ -613,7 +688,9 @@ function formatSummary(phases: TodoPhase[], errors: string[], readOnly = false):
 		(phase, idx) =>
 			idx > currentIdx && phase.tasks.some(task => task.status === "completed" || task.status === "abandoned"),
 	);
-	lines.push(`Overall: ${closedAll}/${tasks.length} done, ${remainingTasks.length} open.`);
+	lines.push(
+		`Overall: ${closedAll}/${tasks.length} done, ${remainingTasks.length} open${blockedAll > 0 ? `, ${blockedAll} blocked` : ""}.`,
+	);
 	lines.push(
 		`Active phase ${currentIdx + 1}/${phases.length} "${current.name}" (${done}/${current.tasks.length})${
 			workedAhead
@@ -625,7 +702,16 @@ function formatSummary(phases: TodoPhase[], errors: string[], readOnly = false):
 		lines.push(`  ${phase.name}:`);
 		for (const task of phase.tasks) {
 			const checkbox = task.status === "completed" ? "[X]" : "[ ]";
-			const tag = task.status === "in_progress" ? " (in progress)" : task.status === "abandoned" ? " (dropped)" : "";
+			const tag =
+				task.status === "in_progress"
+					? " (in progress)"
+					: task.status === "abandoned"
+						? " (dropped)"
+						: task.status === "blocked"
+							? task.blocker
+								? ` (blocked: ${task.blocker})`
+								: " (blocked)"
+							: "";
 			lines.push(`    - ${checkbox} ${task.content}${tag}`);
 		}
 	}
@@ -845,6 +931,10 @@ function formatTodoLine(
 			return uiTheme.fg("accent", `${prefix}${checkbox.unchecked} ${item.content}`);
 		case "abandoned":
 			return uiTheme.fg("error", `${prefix}${checkbox.unchecked} ${strikethroughText(item.content)}`);
+		case "blocked": {
+			const note = item.blocker ? `blocked: ${item.blocker}` : "blocked";
+			return uiTheme.fg("warning", `${prefix}${checkbox.unchecked} ${item.content} (${note})`);
+		}
 		default:
 			// A pending todo lit by a live subagent match renders accent, matching
 			// the sticky HUD's convention (#5873).

package/src/tools/vibe.ts

@@ -23,7 +23,6 @@ import vibeListDescription from "../prompts/tools/vibe-list.md" with { type: "te
 import vibeSendDescription from "../prompts/tools/vibe-send.md" with { type: "text" };
 import vibeSpawnDescription from "../prompts/tools/vibe-spawn.md" with { type: "text" };
 import vibeWaitDescription from "../prompts/tools/vibe-wait.md" with { type: "text" };
-import { MAIN_AGENT_ID } from "../registry/agent-registry";
 import { oneLineLabel } from "../task/types";
 import { renderStatusLine } from "../tui";
 import {
@@ -93,7 +92,7 @@ export interface VibeToolDetails {
 }
 
 function screensOf(session: ToolSession, ids?: string[]): VibeScreenSnapshot[] {
-	return VibeSessionRegistry.global().screens(session.getAgentId?.() ?? MAIN_AGENT_ID, ids);
+	return VibeSessionRegistry.global().screens(session, ids);
 }
 
 function textResult(text: string, details: VibeToolDetails): AgentToolResult<VibeToolDetails> {