pi-background-tasks 0.2.0 → 0.4.0

package/src/extension.ts

@@ -1,13 +1,30 @@
-import { spawn, type ChildProcess } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import { createWriteStream, existsSync, statSync, type WriteStream } from "node:fs";
-import { mkdir, open, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_MAX_BYTES, formatSize } from "@earendil-works/pi-coding-agent";
-import { Text, visibleWidth } from "@earendil-works/pi-tui";
-import { BackgroundTasksManager, type StopAllResult, type TaskManagerResult } from "./ui/background-tasks-manager.js";
-import { Type } from "typebox";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme, ThemeColor, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { formatSize } from "@earendil-works/pi-coding-agent";
+import { Text, type KeyId } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import {
+	DEFAULT_LOG_BYTES,
+	MAX_LOG_BYTES,
+	deriveTaskNameFromCommand,
+	formatSnapshotList,
+	formatUpdateSegment,
+	isNewerVersion,
+	normalizeMaxBytes,
+	normalizeTaskName,
+	parseBgCommandArgs,
+	taskDisplayName,
+	truncateChars,
+	type BgKillDetails,
+	type BgLogsDetails,
+	type BgRunDetails,
+	type BgStatusDetails,
+	type BgTask,
+	type BgTaskSnapshot,
+	type StartTaskOptions,
+} from "./core/common.js";
+import { fetchLatestVersion, readPackageInfo, type FetchLatestVersionOptions } from "./core/update-check.js";
+import { BackgroundTaskRegistry } from "./core/registry.js";
+import { BackgroundTasksManager, type BackgroundTaskForUi, type TaskManagerResult } from "./ui/background-tasks-manager.js";
 
 /**
  * Project-local Pi background task manager.
@@ -19,389 +36,80 @@ import { Type } from "typebox";
  *   extension runtime and are killed on session shutdown/reload.
  */
 
-type TaskStatus = "running" | "completed" | "failed" | "killed";
-type KillKind = "user" | "timeout" | "output_cap" | "shutdown";
-
-type TaskContextUsage = { tokens: number | null; contextWindow: number; percent: number | null };
-
-type BgTaskSnapshot = {
-	id: string;
-	name: string;
-	command: string;
-	description?: string;
-	status: TaskStatus;
-	outputPath: string;
-	cwd: string;
-	startTime: number;
-	endTime?: number;
-	exitCode?: number | null;
-	signal?: string | null;
-	pid?: number;
-	bytesWritten: number;
-	error?: string;
-	notified: boolean;
-	notifyOnCompletion: boolean;
-	triggerOnCompletion: boolean;
-	timeoutSeconds?: number;
-	contextUsage?: TaskContextUsage;
-};
-
-type BgTask = BgTaskSnapshot & {
-	outputAbsPath: string;
-	metadataAbsPath: string;
-	child?: ChildProcess;
-	stream?: WriteStream;
-	timeoutHandle?: NodeJS.Timeout;
-	killKind?: KillKind;
-	killSignalSent?: boolean;
-	capExceeded?: boolean;
-	finalized?: boolean;
-	contextUsageBuffer?: string;
-	waiters: Array<() => void>;
-};
-
-type BgRunDetails = {
-	task: BgTaskSnapshot;
-};
-
-type BgStatusDetails = {
-	tasks: BgTaskSnapshot[];
-};
-
-type BgLogsDetails = {
-	task: BgTaskSnapshot;
-	path: string;
-	bytesRead: number;
-	truncated: boolean;
-	tail: boolean;
-};
-
-type BgKillDetails = {
-	task: BgTaskSnapshot;
-	message: string;
-};
-
-type StartTaskOptions = {
-	name?: string;
-	description?: string;
-	timeoutSeconds?: number;
-	notifyOnCompletion?: boolean;
-	triggerOnCompletion?: boolean;
-};
-
-const DEFAULT_LOG_BYTES = Math.min(DEFAULT_MAX_BYTES, 50 * 1024);
-const MAX_LOG_BYTES = Math.min(DEFAULT_MAX_BYTES, 50 * 1024);
-const MAX_OUTPUT_BYTES = Number(process.env.PI_BG_MAX_OUTPUT_BYTES ?? 20 * 1024 * 1024);
-const KILL_GRACE_MS = 3000;
-const STOP_WAIT_MS = KILL_GRACE_MS + 1500;
-const MAX_RECENT_TASKS = 100;
 const STATUS_INTERVAL_MS = 1000;
 const COMMAND_PREVIEW_CHARS = 90;
-const DETAIL_TAIL_BYTES = 8 * 1024;
-const LIST_VISIBLE_ROWS = 14;
-const DETAIL_VISIBLE_OUTPUT_LINES = 12;
+const GIT_INSTALL_TARGET = "git:github.com/ismailsaleekh/pi-background-tasks";
+
+const packageInfo = readPackageInfo(new URL("../package.json", import.meta.url), (error) => {
+	console.error(`[background-tasks] failed to read package version: ${error.message}`);
+});
+const PACKAGE_NAME = packageInfo.name ?? "pi-background-tasks";
+const PACKAGE_VERSION = packageInfo.version;
 const LIGHT_BLUE_BG = "\x1b[48;2;183;223;255m";
 const LIGHT_BLUE_FG = "\x1b[38;2;11;70;110m";
-const LIGHT_BLUE_BORDER = "\x1b[38;2;83;160;215m";
 const ANSI_RESET = "\x1b[0m";
 
-function sanitizePathSegment(value: string): string {
-	const sanitized = value.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
-	return sanitized || "session";
-}
-
-function stripMatchingQuotes(value: string): string {
-	const trimmed = value.trim();
-	if (trimmed.length >= 2) {
-		const first = trimmed[0];
-		const last = trimmed[trimmed.length - 1];
-		if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
-			return trimmed.slice(1, -1);
-		}
-	}
-	return trimmed;
-}
-
-function compactWhitespace(value: string): string {
-	return value.replace(/\s+/g, " ").trim();
-}
-
-function truncateChars(value: string, maxChars: number): string {
-	if (value.length <= maxChars) return value;
-	return `${value.slice(0, Math.max(0, maxChars - 1))}…`;
-}
-
-function normalizeTaskName(value: unknown): string | undefined {
-	if (typeof value !== "string") return undefined;
-	const normalized = compactWhitespace(stripMatchingQuotes(value));
-	if (!normalized) return undefined;
-	return truncateChars(normalized, 80);
-}
-
-function deriveTaskNameFromCommand(command: string): string {
-	const normalized = compactWhitespace(stripMatchingQuotes(command));
-	if (!normalized) return "Background task";
-
-	const packageScript = normalized.match(/^(npm|pnpm|yarn|bun)\s+(?:(run)\s+)?([^\s;&|]+)/);
-	if (packageScript) {
-		const runner = packageScript[1];
-		const run = packageScript[2] ? " run" : "";
-		const script = packageScript[3];
-		return truncateChars(`${runner}${run} ${script}`, 48);
-	}
-
-	const words = normalized.split(/\s+/).slice(0, 5).join(" ");
-	return truncateChars(words || normalized, 48);
-}
-
-function taskDisplayName(task: { name?: string; description?: string; command?: string; id?: string }): string {
-	return normalizeTaskName(task.name) ?? normalizeTaskName(task.description) ?? (task.command ? deriveTaskNameFromCommand(task.command) : undefined) ?? task.id ?? "Background task";
-}
-
-function parseNameValueAndRest(valueAndRest: string): { value: string; rest: string } | undefined {
-	const input = valueAndRest.trimStart();
-	if (!input) return undefined;
-	const quote = input[0];
-	if (quote === '"' || quote === "'") {
-		let escaped = false;
-		let value = "";
-		for (let i = 1; i < input.length; i++) {
-			const char = input[i]!;
-			if (escaped) {
-				value += char;
-				escaped = false;
-				continue;
-			}
-			if (char === "\\") {
-				escaped = true;
-				continue;
-			}
-			if (char === quote) {
-				return { value, rest: input.slice(i + 1).trimStart() };
-			}
-			value += char;
-		}
-		return undefined;
-	}
-	const match = input.match(/^(\S+)(?:\s+([\s\S]*))?$/);
-	if (!match) return undefined;
-	return { value: match[1]!, rest: match[2]?.trimStart() ?? "" };
-}
-
-function parseBgCommandArgs(args: string): { name?: string; command: string } {
-	const input = args.trim();
-	for (const prefix of ["--name=", "-n="]) {
-		if (input.startsWith(prefix)) {
-			const parsed = parseNameValueAndRest(input.slice(prefix.length));
-			if (!parsed) throw new Error(`${prefix.slice(0, -1)} requires a task name`);
-			return { name: normalizeTaskName(parsed.value), command: parsed.rest };
-		}
-	}
-	for (const prefix of ["--name", "-n"]) {
-		if (input === prefix || input.startsWith(`${prefix} `) || input.startsWith(`${prefix}\t`)) {
-			const parsed = parseNameValueAndRest(input.slice(prefix.length));
-			if (!parsed) throw new Error(`${prefix} requires a task name`);
-			return { name: normalizeTaskName(parsed.value), command: parsed.rest };
-		}
-	}
-	return { command: input };
-}
-
-function formatDuration(ms: number): string {
-	if (ms < 1000) return `${ms}ms`;
-	const seconds = Math.floor(ms / 1000);
-	if (seconds < 60) return `${seconds}s`;
-	const minutes = Math.floor(seconds / 60);
-	const remSeconds = seconds % 60;
-	if (minutes < 60) return `${minutes}m${remSeconds ? `${remSeconds}s` : ""}`;
-	const hours = Math.floor(minutes / 60);
-	const remMinutes = minutes % 60;
-	return `${hours}h${remMinutes ? `${remMinutes}m` : ""}`;
-}
-
-function formatTime(timestamp: number): string {
-	return new Date(timestamp).toLocaleTimeString();
-}
-
-function padAnsi(value: string, width: number): string {
-	return value + " ".repeat(Math.max(0, width - visibleWidth(value)));
-}
-
 function lightBlue(value: string): string {
 	return `${LIGHT_BLUE_BG}${LIGHT_BLUE_FG}${value}${ANSI_RESET}`;
 }
 
-function blueBorder(value: string): string {
-	return `${LIGHT_BLUE_BORDER}${value}${ANSI_RESET}`;
-}
-
-function statusLabel(status: TaskStatus): string {
-	if (status === "completed") return "done";
-	if (status === "failed") return "error";
-	if (status === "killed") return "stopped";
-	return "running";
-}
-
-function statusColor(theme: Theme, status: TaskStatus, text = statusLabel(status)): string {
-	if (status === "completed") return theme.fg("success", text);
-	if (status === "failed") return theme.fg("error", text);
-	if (status === "killed") return theme.fg("warning", text);
-	return theme.fg("accent", text);
-}
-
-function sortTasksForUi(tasks: BgTask[]): BgTask[] {
-	const rank = (task: BgTask) => (task.status === "running" ? 0 : task.status === "failed" ? 1 : task.status === "killed" ? 2 : 3);
-	return [...tasks].sort((a, b) => {
-		const rankDiff = rank(a) - rank(b);
-		if (rankDiff !== 0) return rankDiff;
-		return (b.endTime ?? b.startTime) - (a.endTime ?? a.startTime);
-	});
-}
-
-function shellInvocation(command: string): { shell: string; args: string[] } {
-	if (process.platform === "win32") {
-		return { shell: process.env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", command] };
-	}
-	return { shell: process.env.SHELL || "/bin/sh", args: ["-c", command] };
-}
-
-function normalizeMaxBytes(value: unknown, fallback = DEFAULT_LOG_BYTES): number {
-	const raw = typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : fallback;
-	return Math.max(1, Math.min(MAX_LOG_BYTES, raw));
-}
-
-function snapshot(task: BgTask): BgTaskSnapshot {
-	return {
-		id: task.id,
-		name: taskDisplayName(task),
-		command: task.command,
-		description: task.description,
-		status: task.status,
-		outputPath: task.outputPath,
-		cwd: task.cwd,
-		startTime: task.startTime,
-		endTime: task.endTime,
-		exitCode: task.exitCode,
-		signal: task.signal,
-		pid: task.pid,
-		bytesWritten: task.bytesWritten,
-		error: task.error,
-		notified: task.notified,
-		notifyOnCompletion: task.notifyOnCompletion,
-		triggerOnCompletion: task.triggerOnCompletion,
-		timeoutSeconds: task.timeoutSeconds,
-		contextUsage: task.contextUsage,
-	};
-}
-
 function textContent(text: string) {
 	return [{ type: "text" as const, text }];
 }
 
-function taskAge(task: BgTask, now = Date.now()): string {
-	return formatDuration((task.endTime ?? now) - task.startTime);
-}
-
-function formatTaskLine(task: BgTask, now = Date.now()): string {
-	const statusIcon =
-		task.status === "running" ? "▶" : task.status === "completed" ? "✓" : task.status === "killed" ? "■" : "✗";
-	const code = task.exitCode !== undefined ? ` exit=${task.exitCode}` : "";
-	const pid = task.pid ? ` pid=${task.pid}` : "";
-	const error = task.error ? ` error=${truncateChars(task.error, 80)}` : "";
-	const label = taskDisplayName(task);
-	return `${statusIcon} ${task.id} ${task.status} ${taskAge(task, now)}${code}${pid} — ${truncateChars(label, COMMAND_PREVIEW_CHARS)}${error}\n    output: ${task.outputPath}`;
-}
-
-function formatTaskList(tasks: BgTask[], now = Date.now()): string {
-	if (tasks.length === 0) return "No background tasks in this Pi extension runtime.";
-	const running = tasks.filter((task) => task.status === "running");
-	const finished = tasks
-		.filter((task) => task.status !== "running")
-		.sort((a, b) => (b.endTime ?? b.startTime) - (a.endTime ?? a.startTime))
-		.slice(0, 20);
-	const ordered = [...running.sort((a, b) => a.startTime - b.startTime), ...finished];
-	return ordered.map((task) => formatTaskLine(task, now)).join("\n");
-}
-
-function formatSnapshotList(tasks: BgTaskSnapshot[], now = Date.now()): string {
-	if (tasks.length === 0) return "No background tasks in this Pi extension runtime.";
-	return tasks
-		.map((task) => {
-			const statusIcon =
-				task.status === "running" ? "▶" : task.status === "completed" ? "✓" : task.status === "killed" ? "■" : "✗";
-			const age = formatDuration((task.endTime ?? now) - task.startTime);
-			const code = task.exitCode !== undefined ? ` exit=${task.exitCode}` : "";
-			const pid = task.pid ? ` pid=${task.pid}` : "";
-			const error = task.error ? ` error=${truncateChars(task.error, 80)}` : "";
-			const label = taskDisplayName(task);
-			return `${statusIcon} ${task.id} ${task.status} ${age}${code}${pid} — ${truncateChars(label, COMMAND_PREVIEW_CHARS)}${error}\n    output: ${task.outputPath}`;
-		})
-		.join("\n");
-}
-
-async function boundedRead(filePath: string, maxBytes: number, tail: boolean): Promise<{ content: string; truncated: boolean; bytesRead: number; totalBytes: number }> {
-	const stat = statSync(filePath);
-	const totalBytes = stat.size;
-	const bytesToRead = Math.min(totalBytes, maxBytes);
-	if (bytesToRead === 0) {
-		return { content: "", truncated: false, bytesRead: 0, totalBytes };
-	}
-
-	const file = await open(filePath, "r");
-	try {
-		const buffer = Buffer.alloc(bytesToRead);
-		const position = tail ? Math.max(0, totalBytes - bytesToRead) : 0;
-		const { bytesRead } = await file.read(buffer, 0, bytesToRead, position);
-		return {
-			content: buffer.subarray(0, bytesRead).toString("utf8"),
-			truncated: totalBytes > bytesRead,
-			bytesRead,
-			totalBytes,
-		};
-	} finally {
-		await file.close();
-	}
-}
-
-function renderPlainResult(result: { content?: Array<{ type: string; text?: string }> }, _options: ToolRenderResultOptions, _theme: any) {
-	const first = result.content?.find((part) => part.type === "text");
-	return new Text(first?.text ?? "", 0, 0);
+type TextToolResult = { content?: readonly { type: string; text?: string }[] };
+
+const BgRunParams = Type.Object({
+	name: Type.String({ description: "Short human-readable task name shown in the bg footer dock. Required; use 2-6 words, not the raw command." }),
+	command: Type.String({ description: "Shell command to start in the background" }),
+	isAgent: Type.Boolean({ description: "Required. Set true only when this background task launches an LLM/agent process, such as a child `pi -p ...` or `pi --mode json ...`, so Pi-agent telemetry can be collected. Set false for scripts, tests, servers, sleeps, and ordinary shell commands." }),
+	description: Type.Optional(Type.String({ description: "Optional longer human-readable context for the task" })),
+	timeoutSeconds: Type.Optional(Type.Number({ description: "Optional timeout; task is failed and killed when exceeded" })),
+	notifyOnCompletion: Type.Optional(Type.Boolean({ description: "Whether to show a completion notification. Default: true." })),
+	triggerOnCompletion: Type.Optional(Type.Boolean({ description: "Whether completion should trigger a follow-up agent turn. Default: true for bg_run." })),
+});
+
+const BgStatusParams = Type.Object({
+	taskId: Type.Optional(Type.String({ description: "Optional task ID or unambiguous prefix. If omitted, all running/recent tasks are returned." })),
+});
+
+const BgLogsParams = Type.Object({
+	taskId: Type.String({ description: "Task ID or unambiguous prefix" }),
+	maxBytes: Type.Optional(Type.Number({ description: `Maximum bytes to return, capped at ${formatSize(MAX_LOG_BYTES)}. Default: ${formatSize(DEFAULT_LOG_BYTES)}.` })),
+	tail: Type.Optional(Type.Boolean({ description: "Read the tail of the log when true, head when false. Default: true." })),
+});
+
+const BgKillParams = Type.Object({
+	taskId: Type.String({ description: "Task ID or unambiguous prefix to stop" }),
+});
+
+type BgRunParamsValue = Static<typeof BgRunParams>;
+type BgStatusParamsValue = Static<typeof BgStatusParams>;
+type BgLogsParamsValue = Static<typeof BgLogsParams>;
+type BgKillParamsValue = Static<typeof BgKillParams>;
+
+function renderPlainResult(result: TextToolResult, _options: ToolRenderResultOptions, _theme: Theme) {
+	const text = result.content?.map((part) => part.type === "text" ? (part.text ?? "") : "").join("\n") ?? "";
+	return new Text(text, 0, 0);
 }
 
 export default function backgroundTasksExtension(pi: ExtensionAPI): void {
-	const tasks = new Map<string, BgTask>();
-	let runtimeDirAbs: string | undefined;
-	let runtimeDirDisplay: string | undefined;
+	const seenTaskIds = new Set<string>();
 	let currentCtx: ExtensionContext | undefined;
 	let dockOpen = false;
-	let shuttingDown = false;
 	let statusInterval: NodeJS.Timeout | undefined;
-	const seenTaskIds = new Set<string>();
-
-	function makeTaskId(): string {
-		for (let attempt = 0; attempt < 20; attempt++) {
-			const id = `b${randomBytes(4).toString("hex")}`;
-			if (!tasks.has(id)) return id;
-		}
-		throw new Error("Could not generate a unique background task ID after 20 attempts");
-	}
+	let latestKnownVersion: string | undefined;
+	let updateCheckStarted = false;
 
-	async function ensureRuntimeDir(ctx: ExtensionContext): Promise<{ abs: string; display: string }> {
-		if (runtimeDirAbs && runtimeDirDisplay) return { abs: runtimeDirAbs, display: runtimeDirDisplay };
-		const sessionId = sanitizePathSegment(ctx.sessionManager.getSessionId?.() || "session");
-		const runId = `${sessionId}-${process.pid}`;
-		runtimeDirAbs = join(ctx.cwd, ".pi", "tasks", runId);
-		runtimeDirDisplay = join(".pi", "tasks", runId);
-		await mkdir(runtimeDirAbs, { recursive: true });
-		return { abs: runtimeDirAbs, display: runtimeDirDisplay };
-	}
-
-	async function writeMetadata(task: BgTask): Promise<void> {
-		await writeFile(task.metadataAbsPath, `${JSON.stringify(snapshot(task), null, 2)}\n`, "utf8");
-	}
+	const registry = new BackgroundTaskRegistry({
+		onChange: () => updateUi(),
+		sendCompletionNotification: (message, options) => {
+			pi.sendMessage(message, options);
+		},
+	});
 
 	function unseenFinishedTasks(): BgTask[] {
-		return [...tasks.values()].filter((task) => task.status !== "running" && !seenTaskIds.has(task.id));
+		return registry.allTasks().filter((task) => task.status !== "running" && !seenTaskIds.has(task.id));
 	}
 
 	function clearFinishedNotices(ctx = currentCtx): number {
@@ -411,19 +119,32 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		return unseen.length;
 	}
 
+	function notifyClearFinishedNotices(ctx: ExtensionContext): void {
+		currentCtx = ctx;
+		const cleared = clearFinishedNotices(ctx);
+		if (!ctx.hasUI) return;
+		ctx.ui.notify(
+			cleared > 0
+				? `Cleared ${cleared} finished background task notice${cleared === 1 ? "" : "s"}.`
+				: "No finished background task notices to clear.",
+			cleared > 0 ? "info" : "warning",
+		);
+	}
+
 	function updateUi(ctx = currentCtx): void {
-		if (shuttingDown || !ctx) return;
+		if (registry.isShuttingDown() || !ctx) return;
 		try {
 			if (!ctx.hasUI) return;
-			const allTasks = [...tasks.values()];
+			const allTasks = registry.allTasks();
 			const running = allTasks.filter((task) => task.status === "running");
 			const unseenFailed = allTasks.filter((task) => task.status === "failed" && !seenTaskIds.has(task.id));
 			const unseenStopped = allTasks.filter((task) => task.status === "killed" && !seenTaskIds.has(task.id));
 			const unseenDone = allTasks.filter((task) => task.status === "completed" && !seenTaskIds.has(task.id));
 			const unseenFinishedCount = unseenFailed.length + unseenStopped.length + unseenDone.length;
+			const updateSegment = formatUpdateSegment(latestKnownVersion, PACKAGE_VERSION ?? "");
 			ctx.ui.setWidget("background-tasks", undefined);
 			if (running.length === 0 && unseenFinishedCount === 0) {
-				ctx.ui.setStatus("background-tasks", undefined);
+				ctx.ui.setStatus("background-tasks", updateSegment ? lightBlue(` bg ${updateSegment} `) : undefined);
 				return;
 			}
 
@@ -432,8 +153,10 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 			if (unseenFailed.length > 0) parts.push(`${unseenFailed.length} failed`);
 			if (unseenStopped.length > 0) parts.push(`${unseenStopped.length} stopped`);
 			if (unseenDone.length > 0) parts.push(`${unseenDone.length} done`);
-			const entryHint = dockOpen ? "focused" : `Shift↓${unseenFinishedCount > 0 ? " · C clear" : ""}`;
-			const label = ` bg ${parts.join(" · ")} · ${entryHint} `;
+			const entryHint = dockOpen ? "focused" : `Shift↓${unseenFinishedCount > 0 ? " · /bg-clear" : ""}`;
+			const segments = [...parts, entryHint];
+			if (updateSegment) segments.push(updateSegment);
+			const label = ` bg ${segments.join(" · ")} `;
 			ctx.ui.setStatus("background-tasks", lightBlue(label));
 		} catch (error) {
 			console.error(`[background-tasks] UI update failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -441,434 +164,9 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		}
 	}
 
-	function normalizeContextUsage(value: unknown): TaskContextUsage | undefined {
-		if (!value || typeof value !== "object") return undefined;
-		const input = value as { tokens?: unknown; contextWindow?: unknown; percent?: unknown };
-		const contextWindow = typeof input.contextWindow === "number" && Number.isFinite(input.contextWindow) && input.contextWindow > 0
-			? Math.floor(input.contextWindow)
-			: undefined;
-		if (!contextWindow) return undefined;
-		const tokens = input.tokens === null
-			? null
-			: typeof input.tokens === "number" && Number.isFinite(input.tokens) && input.tokens >= 0
-				? Math.floor(input.tokens)
-				: null;
-		const percent = input.percent === null
-			? null
-			: typeof input.percent === "number" && Number.isFinite(input.percent) && input.percent >= 0
-				? input.percent
-				: tokens === null
-					? null
-					: (tokens / contextWindow) * 100;
-		return { tokens, contextWindow, percent };
-	}
-
-	function parseContextUsageXml(xml: string): TaskContextUsage | undefined {
-		const readNumber = (tag: string): number | null | undefined => {
-			const match = xml.match(new RegExp(`<${tag}>(.*?)</${tag}>`, "i"));
-			if (!match) return undefined;
-			const raw = match[1]?.trim();
-			if (raw === "null" || raw === "?") return null;
-			const parsed = Number(raw);
-			return Number.isFinite(parsed) ? parsed : undefined;
-		};
-		const tokens = readNumber("tokens");
-		const contextWindow = readNumber("context-window") ?? readNumber("contextWindow");
-		const percent = readNumber("percent");
-		return normalizeContextUsage({ tokens, contextWindow, percent });
-	}
-
-	function ingestContextUsageTelemetry(task: BgTask, text: string): void {
-		if (!text) return;
-		task.contextUsageBuffer = `${task.contextUsageBuffer ?? ""}${text}`.slice(-16 * 1024);
-		let latest: TaskContextUsage | undefined;
-		for (const line of task.contextUsageBuffer.split(/\r?\n/)) {
-			if (!line.includes("background-task-context-usage")) continue;
-			const trimmed = line.trim();
-			if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
-				try {
-					const parsed = JSON.parse(trimmed);
-					if (parsed?.type === "background-task-context-usage") latest = normalizeContextUsage(parsed) ?? latest;
-				} catch {
-					// Ignore malformed optional telemetry; task output remains authoritative for debugging.
-				}
-			}
-		}
-		const xmlMatches = task.contextUsageBuffer.matchAll(/<background-task-context-usage>[\s\S]*?<\/background-task-context-usage>/gi);
-		for (const match of xmlMatches) latest = parseContextUsageXml(match[0]) ?? latest;
-		if (latest) {
-			task.contextUsage = latest;
-			updateUi();
-			void writeMetadata(task).catch((error) => {
-				console.error(`[background-tasks] failed to write context usage metadata for ${task.id}:`, error);
-			});
-		}
-	}
-
-	function appendToOutput(task: BgTask, data: Buffer | string): void {
-		if (!task.stream || task.stream.destroyed) return;
-		const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, "utf8");
-		if (buffer.length === 0) return;
-		ingestContextUsageTelemetry(task, buffer.toString("utf8"));
-
-		const nextBytes = task.bytesWritten + buffer.length;
-		if (nextBytes <= MAX_OUTPUT_BYTES) {
-			task.stream.write(buffer);
-			task.bytesWritten = nextBytes;
-			return;
-		}
-
-		const remaining = Math.max(0, MAX_OUTPUT_BYTES - task.bytesWritten);
-		if (remaining > 0) {
-			task.stream.write(buffer.subarray(0, remaining));
-			task.bytesWritten += remaining;
-		}
-
-		if (!task.capExceeded) {
-			task.capExceeded = true;
-			task.error = `Output exceeded cap of ${formatSize(MAX_OUTPUT_BYTES)}; terminating task`;
-			const notice = `\n\n[background task error: ${task.error}]\n`;
-			task.stream.write(notice);
-			task.bytesWritten += Buffer.byteLength(notice, "utf8");
-			task.killKind = "output_cap";
-			try {
-				requestKill(task, "SIGTERM");
-			} catch (error) {
-				task.error = `${task.error}; kill failed: ${error instanceof Error ? error.message : String(error)}`;
-				void finalizeTask(task, "failed", null, undefined, task.error);
-			}
-		}
-	}
-
-	function requestKill(task: BgTask, signal: NodeJS.Signals = "SIGTERM"): void {
-		if (task.status !== "running") {
-			throw new Error(`Task ${task.id} is ${task.status}, not running`);
-		}
-		if (!task.child) {
-			throw new Error(`Task ${task.id} has no child process handle`);
-		}
-		if (!task.pid) {
-			throw new Error(`Task ${task.id} has no process id`);
-		}
-		if (task.killSignalSent && signal === "SIGTERM") return;
-
-		const errors: string[] = [];
-		let killed = false;
-
-		if (process.platform !== "win32") {
-			try {
-				process.kill(-task.pid, signal);
-				killed = true;
-			} catch (error) {
-				errors.push(`process group kill failed: ${error instanceof Error ? error.message : String(error)}`);
-			}
-		}
-
-		if (!killed) {
-			try {
-				task.child.kill(signal);
-				killed = true;
-			} catch (error) {
-				errors.push(`child kill failed: ${error instanceof Error ? error.message : String(error)}`);
-			}
-		}
-
-		if (!killed) {
-			throw new Error(`Could not kill task ${task.id}: ${errors.join("; ")}`);
-		}
-
-		task.killSignalSent = true;
-		setTimeout(() => {
-			if (task.status !== "running") return;
-			try {
-				requestKill(task, "SIGKILL");
-			} catch (error) {
-				task.error = `SIGKILL failed: ${error instanceof Error ? error.message : String(error)}`;
-				void writeMetadata(task).catch((metadataError) => {
-					console.error(`[background-tasks] failed to write metadata for ${task.id}:`, metadataError);
-				});
-			}
-		}, KILL_GRACE_MS).unref?.();
-	}
-
-	function waitForEnd(task: BgTask, timeoutMs: number): Promise<boolean> {
-		if (task.status !== "running") return Promise.resolve(true);
-		return new Promise((resolve) => {
-			const timeout = setTimeout(() => {
-				const idx = task.waiters.indexOf(done);
-				if (idx >= 0) task.waiters.splice(idx, 1);
-				resolve(false);
-			}, timeoutMs);
-			const done = () => {
-				clearTimeout(timeout);
-				resolve(true);
-			};
-			task.waiters.push(done);
-		});
-	}
-
-	async function stopTask(task: BgTask, kind: KillKind, reason?: string): Promise<BgTask> {
-		if (task.status !== "running") {
-			throw new Error(`Task ${task.id} is ${task.status}, not running`);
-		}
-		task.killKind = kind;
-		if (reason) task.error = reason;
-		requestKill(task, "SIGTERM");
-		const stopped = await waitForEnd(task, STOP_WAIT_MS);
-		if (!stopped) {
-			throw new Error(`Task ${task.id} did not exit within ${formatDuration(STOP_WAIT_MS)} after SIGTERM/SIGKILL`);
-		}
-		return task;
-	}
-
-	async function notifyCompletion(task: BgTask): Promise<void> {
-		if (!task.notifyOnCompletion || task.notified || shuttingDown) return;
-		task.notified = true;
-		const exit = task.exitCode === undefined ? "" : `\n  <exit-code>${task.exitCode}</exit-code>`;
-		const error = task.error ? `\n  <error>${escapeXml(task.error)}</error>` : "";
-		const taskName = taskDisplayName(task);
-		const content = [
-			"<background-task-notification>",
-			`  <task-id>${task.id}</task-id>`,
-			`  <task-name>${escapeXml(taskName)}</task-name>`,
-			`  <status>${task.status}</status>`,
-			exit,
-			error,
-			`  <output-file>${escapeXml(task.outputPath)}</output-file>`,
-			`  <summary>${escapeXml(`Background task ${JSON.stringify(taskName)} ${task.status}`)}</summary>`,
-			"</background-task-notification>",
-		]
-			.filter(Boolean)
-			.join("\n");
-
-		try {
-			pi.sendMessage(
-				{
-					customType: "background-task-notification",
-					content,
-					display: true,
-					details: snapshot(task),
-				},
-				{ deliverAs: "followUp", triggerTurn: task.triggerOnCompletion },
-			);
-		} catch (error) {
-			task.notified = false;
-			throw new Error(`Failed to send background task notification for ${task.id}: ${error instanceof Error ? error.message : String(error)}`);
-		}
-	}
-
-	function escapeXml(value: string): string {
-		return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-	}
-
-	async function finalizeTask(task: BgTask, status: TaskStatus, exitCode: number | null, signal?: string | null, error?: string): Promise<void> {
-		if (task.finalized) return;
-		task.finalized = true;
-		if (task.timeoutHandle) clearTimeout(task.timeoutHandle);
-		task.status = status;
-		task.exitCode = exitCode;
-		task.signal = signal ?? null;
-		task.endTime = Date.now();
-		if (error) task.error = error;
-		if (task.stream && !task.stream.destroyed) task.stream.end();
-
-		for (const waiter of task.waiters.splice(0)) waiter();
-
-		try {
-			await writeMetadata(task);
-		} catch (metadataError) {
-			console.error(`[background-tasks] failed to write metadata for ${task.id}:`, metadataError);
-		}
-
-		updateUi();
-		try {
-			await notifyCompletion(task);
-		} catch (notificationError) {
-			console.error(`[background-tasks] notification failed for ${task.id}:`, notificationError);
-		}
-		try {
-			await writeMetadata(task);
-		} catch (metadataError) {
-			console.error(`[background-tasks] failed to update notification metadata for ${task.id}:`, metadataError);
-		}
-		pruneOldTasks();
-	}
-
-	function pruneOldTasks(): void {
-		if (tasks.size <= MAX_RECENT_TASKS) return;
-		const removable = [...tasks.values()]
-			.filter((task) => task.status !== "running")
-			.sort((a, b) => (a.endTime ?? a.startTime) - (b.endTime ?? b.startTime));
-		while (tasks.size > MAX_RECENT_TASKS && removable.length > 0) {
-			const task = removable.shift();
-			if (task) tasks.delete(task.id);
-		}
-	}
-
-	async function startTask(
-		ctx: ExtensionContext,
-		command: string,
-		options: StartTaskOptions = {},
-	): Promise<BgTask> {
-		const normalizedCommand = stripMatchingQuotes(command);
-		if (!normalizedCommand) throw new Error("Background command is empty");
-		if (shuttingDown) throw new Error("Cannot start a background task while Pi is shutting down");
-
+	async function startTask(ctx: ExtensionContext, command: string, options: StartTaskOptions = {}): Promise<BgTask> {
 		currentCtx = ctx;
-		const dir = await ensureRuntimeDir(ctx);
-		const id = makeTaskId();
-		const outputAbsPath = join(dir.abs, `${id}.output`);
-		const metadataAbsPath = join(dir.abs, `${id}.json`);
-		const outputPath = join(dir.display, `${id}.output`);
-		const timeoutSeconds =
-			typeof options.timeoutSeconds === "number" && Number.isFinite(options.timeoutSeconds) && options.timeoutSeconds > 0
-				? Math.floor(options.timeoutSeconds)
-				: undefined;
-		const taskName = normalizeTaskName(options.name) ?? normalizeTaskName(options.description) ?? deriveTaskNameFromCommand(normalizedCommand);
-
-		const task: BgTask = {
-			id,
-			name: taskName,
-			command: normalizedCommand,
-			description: options.description?.trim() || undefined,
-			status: "running",
-			outputPath,
-			outputAbsPath,
-			metadataAbsPath,
-			cwd: ctx.cwd,
-			startTime: Date.now(),
-			exitCode: undefined,
-			pid: undefined,
-			bytesWritten: 0,
-			notified: false,
-			notifyOnCompletion: options.notifyOnCompletion ?? true,
-			triggerOnCompletion: options.triggerOnCompletion ?? false,
-			timeoutSeconds,
-			waiters: [],
-		};
-		tasks.set(id, task);
-
-		const stream = createWriteStream(outputAbsPath, { flags: "a", encoding: "utf8" });
-		task.stream = stream;
-		stream.on("error", (error) => {
-			task.error = `Output file write failed: ${error.message}`;
-			if (task.status === "running") {
-				task.killKind = "output_cap";
-				try {
-					requestKill(task, "SIGTERM");
-				} catch (killError) {
-					void finalizeTask(
-						task,
-						"failed",
-						null,
-						undefined,
-						`${task.error}; kill failed: ${killError instanceof Error ? killError.message : String(killError)}`,
-					);
-				}
-			}
-		});
-
-		try {
-			const invocation = shellInvocation(normalizedCommand);
-			const child = spawn(invocation.shell, invocation.args, {
-				cwd: ctx.cwd,
-				detached: process.platform !== "win32",
-				stdio: ["ignore", "pipe", "pipe"],
-				env: process.env,
-				windowsHide: true,
-			});
-
-			task.child = child;
-			task.pid = child.pid;
-
-			child.stdout?.on("data", (data) => appendToOutput(task, data));
-			child.stderr?.on("data", (data) => appendToOutput(task, data));
-
-			child.on("error", (error) => {
-				appendToOutput(task, `\n[background task spawn error: ${error.message}]\n`);
-				void finalizeTask(task, "failed", null, undefined, error.message);
-			});
-
-			child.on("close", (code, signalName) => {
-				let status: TaskStatus;
-				let error: string | undefined;
-				if (task.killKind === "user" || task.killKind === "shutdown") {
-					status = "killed";
-				} else if (task.killKind === "timeout") {
-					status = "failed";
-					error = task.error || `Timed out after ${task.timeoutSeconds}s`;
-				} else if (task.killKind === "output_cap") {
-					status = "failed";
-					error = task.error || `Output exceeded cap of ${formatSize(MAX_OUTPUT_BYTES)}`;
-				} else if ((code ?? 0) === 0) {
-					status = "completed";
-				} else {
-					status = "failed";
-					error = `Exited with code ${code ?? "null"}${signalName ? ` (${signalName})` : ""}`;
-				}
-				void finalizeTask(task, status, code, signalName, error);
-			});
-
-			if (timeoutSeconds) {
-				task.timeoutHandle = setTimeout(() => {
-					if (task.status !== "running") return;
-					task.killKind = "timeout";
-					task.error = `Timed out after ${timeoutSeconds}s`;
-					appendToOutput(task, `\n[background task timeout: ${task.error}]\n`);
-					try {
-						requestKill(task, "SIGTERM");
-					} catch (error) {
-						void finalizeTask(task, "failed", null, undefined, `${task.error}; kill failed: ${error instanceof Error ? error.message : String(error)}`);
-					}
-				}, timeoutSeconds * 1000);
-			}
-
-			await writeMetadata(task);
-			updateUi(ctx);
-			return task;
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			appendToOutput(task, `\n[background task spawn exception: ${message}]\n`);
-			await finalizeTask(task, "failed", null, undefined, message);
-			throw new Error(`Failed to start background task: ${message}`);
-		}
-	}
-
-	function resolveTask(idOrPrefix: string): BgTask {
-		const id = idOrPrefix.trim();
-		if (!id) throw new Error("Task ID is required");
-		const exact = tasks.get(id);
-		if (exact) return exact;
-		const matches = [...tasks.values()].filter((task) => task.id.startsWith(id));
-		if (matches.length === 1) return matches[0];
-		if (matches.length > 1) throw new Error(`Ambiguous task ID prefix "${id}": ${matches.map((task) => task.id).join(", ")}`);
-		throw new Error(`Unknown background task ID: ${id}`);
-	}
-
-	async function getTaskLogs(task: BgTask, maxBytes: number, tail: boolean): Promise<{ text: string; details: BgLogsDetails }> {
-		if (!existsSync(task.outputAbsPath)) {
-			throw new Error(`Output file does not exist for ${task.id}: ${task.outputPath}`);
-		}
-		const read = await boundedRead(task.outputAbsPath, maxBytes, tail);
-		const direction = tail ? "tail" : "head";
-		let text = read.content || "(no output yet)";
-		if (read.truncated) {
-			const omitted = read.totalBytes - read.bytesRead;
-			const notice = `\n\n[Showing ${direction} ${formatSize(read.bytesRead)} of ${formatSize(read.totalBytes)}; ${formatSize(omitted)} omitted. Full output: ${task.outputPath}]`;
-			text = tail ? `${notice}\n\n${text}` : `${text}${notice}`;
-		} else {
-			text += `\n\n[Full output: ${task.outputPath}]`;
-		}
-		return {
-			text,
-			details: {
-				task: snapshot(task),
-				path: task.outputPath,
-				bytesRead: read.bytesRead,
-				truncated: read.truncated,
-				tail,
-			},
-		};
+		return registry.startTask(ctx, command, options);
 	}
 
 	async function openTaskManager(ctx: ExtensionCommandContext | ExtensionContext, initialTaskId?: string): Promise<void> {
@@ -881,55 +179,47 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		updateUi(ctx);
 		try {
 			await ctx.ui.custom<TaskManagerResult>(
-				(tui, theme, _keybindings, done) =>
-					new BackgroundTasksManager(tui, theme, done, {
-						initialTaskId,
-						getTasks: () => [...tasks.values()],
-						stopTask: async (task) => {
-							await stopTask(resolveTask(task.id), "user");
+				(tui, theme, _keybindings, done) => {
+					const managerOptions = {
+						getTasks: () => registry.allTasks(),
+						stopTask: async (task: BackgroundTaskForUi) => {
+							await registry.stopTask(registry.resolveTask(task.id), "user");
 							updateUi(ctx);
 						},
 						stopAllRunning: async () => {
-							const running = [...tasks.values()].filter((task) => task.status === "running");
-							const failures: string[] = [];
-							let stopped = 0;
-							await Promise.all(
-								running.map(async (task) => {
-									try {
-										await stopTask(task, "user");
-										stopped++;
-									} catch (error) {
-										failures.push(`${taskDisplayName(task)} (${task.id}): ${error instanceof Error ? error.message : String(error)}`);
-									}
-								}),
-							);
+							const result = await registry.stopAllRunning("user");
 							updateUi(ctx);
-							return { stopped, failures };
+							return result;
 						},
-						rerunTask: async (task) => {
-							const rerun = await startTask(ctx, task.command, {
+						rerunTask: async (task: BackgroundTaskForUi) => {
+							const rerunOptions: StartTaskOptions = {
 								name: taskDisplayName(task),
-								description: task.description,
-								timeoutSeconds: task.timeoutSeconds,
+								isAgent: task.isAgent,
 								notifyOnCompletion: true,
 								triggerOnCompletion: false,
-							});
+							};
+							if (task.description !== undefined) rerunOptions.description = task.description;
+							if (task.timeoutSeconds !== undefined) rerunOptions.timeoutSeconds = task.timeoutSeconds;
+							const rerun = await startTask(ctx, task.command, rerunOptions);
 							updateUi(ctx);
 							return rerun;
 						},
-						showOutputPath: (task) => {
+						showOutputPath: (task: BackgroundTaskForUi) => {
 							ctx.ui.notify(`Output path for ${taskDisplayName(task)} (${task.id}):\n${task.outputPath}`, "info");
 						},
-						markSeen: (taskId) => {
+						markSeen: (taskId: string) => {
 							seenTaskIds.add(taskId);
 							updateUi(ctx);
 						},
-						markFinishedSeen: (taskIds) => {
+						markFinishedSeen: (taskIds: string[]) => {
 							for (const taskId of taskIds) seenTaskIds.add(taskId);
 							updateUi(ctx);
 						},
-						isSeen: (taskId) => seenTaskIds.has(taskId),
-					}),
+						isSeen: (taskId: string) => seenTaskIds.has(taskId),
+					};
+					if (initialTaskId) return new BackgroundTasksManager(tui, theme, done, { ...managerOptions, initialTaskId });
+					return new BackgroundTasksManager(tui, theme, done, managerOptions);
+				},
 				{
 					overlay: true,
 					overlayOptions: { anchor: "bottom-center", width: "96%", minWidth: 64, maxHeight: "60%", margin: { bottom: 1, left: 1, right: 1 } },
@@ -944,38 +234,60 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 	pi.registerMessageRenderer<BgTaskSnapshot>("background-task-notification", (message, _options, theme) => {
 		const task = message.details;
 		const status = task?.status ?? "completed";
-		const color = status === "completed" ? "success" : status === "failed" ? "error" : status === "killed" ? "warning" : "accent";
+		const color: ThemeColor = status === "completed" ? "success" : status === "failed" ? "error" : status === "killed" ? "warning" : "accent";
 		const id = task?.id ?? "background task";
 		const name = task ? taskDisplayName(task) : "Background task";
 		const output = task?.outputPath ? `\n${theme.fg("dim", `Output: ${task.outputPath}`)}` : "";
 		const error = task?.error ? `\n${theme.fg("error", task.error)}` : "";
-		return new Text(`${theme.fg(color as any, `[bg ${status}]`)} ${theme.fg("accent", name)} ${theme.fg("dim", `(${id})`)}${output}${error}`, 0, 0);
+		return new Text(`${theme.fg(color, `[bg ${status}]`)} ${theme.fg("accent", name)} ${theme.fg("dim", `(${id})`)}${output}${error}`, 0, 0);
 	});
 
+	async function scheduleUpdateCheck(ctx: ExtensionContext): Promise<void> {
+		if (updateCheckStarted) return;
+		updateCheckStarted = true;
+		const env = process.env;
+		if (env["PI_BG_DISABLE_UPDATE_CHECK"] === "1") return;
+		if (env["PI_OFFLINE"] === "1") return;
+		if (!PACKAGE_VERSION) return;
+		const options: FetchLatestVersionOptions = {
+			packageName: PACKAGE_NAME,
+			onError: (error) => console.error(`[background-tasks] update check skipped: ${error.message}`),
+		};
+		const registryUrl = env["PI_BG_REGISTRY_URL"];
+		if (registryUrl) options.registryUrl = registryUrl;
+		const latest = await fetchLatestVersion(options);
+		if (latest && isNewerVersion(latest, PACKAGE_VERSION)) {
+			latestKnownVersion = latest;
+			updateUi(ctx);
+		}
+	}
+
 	pi.on("session_start", async (_event, ctx) => {
-		shuttingDown = false;
+		registry.setShuttingDown(false);
 		currentCtx = ctx;
-		await ensureRuntimeDir(ctx);
+		await registry.ensureRuntimeDir(ctx);
 		updateUi(ctx);
 		if (statusInterval) clearInterval(statusInterval);
 		statusInterval = setInterval(() => updateUi(), STATUS_INTERVAL_MS);
+		// One-shot, non-blocking: never awaited on the session-start path or the status tick.
+		void scheduleUpdateCheck(ctx);
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
-		shuttingDown = true;
+		registry.setShuttingDown(true);
 		currentCtx = undefined;
 		if (statusInterval) {
 			clearInterval(statusInterval);
 			statusInterval = undefined;
 		}
-		const running = [...tasks.values()].filter((task) => task.status === "running");
+		const running = registry.allTasks().filter((task) => task.status === "running");
 		if (running.length === 0) return;
 
 		const failures: string[] = [];
 		await Promise.all(
 			running.map(async (task) => {
 				try {
-					await stopTask(task, "shutdown", "Killed during Pi session shutdown/reload");
+					await registry.stopTask(task, "shutdown", "Killed during Pi session shutdown/reload");
 				} catch (error) {
 					const message = `${task.id}: ${error instanceof Error ? error.message : String(error)}`;
 					failures.push(message);
@@ -989,11 +301,13 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.registerCommand("bg", {
-		description: "Start a shell command as a tracked background task: /bg [--name \"Task name\"] <command>",
+		description: "Start a shell command as a tracked background task: /bg [--agent] [--name \"Task name\"] <command>",
 		handler: async (args, ctx) => {
 			try {
 				const parsed = parseBgCommandArgs(args);
-				const task = await startTask(ctx, parsed.command, { name: parsed.name, notifyOnCompletion: true, triggerOnCompletion: false });
+				const taskOptions: StartTaskOptions = { isAgent: parsed.isAgent, notifyOnCompletion: true, triggerOnCompletion: false };
+				if (parsed.name !== undefined) taskOptions.name = parsed.name;
+				const task = await startTask(ctx, parsed.command, taskOptions);
 				ctx.ui.notify(`Started ${taskDisplayName(task)} (${task.id})\nOutput: ${task.outputPath}\nCommand: ${task.command}`, "info");
 			} catch (error) {
 				ctx.ui.notify(`Background task failed to start: ${error instanceof Error ? error.message : String(error)}`, "error");
@@ -1017,34 +331,52 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerShortcut("shift+down" as any, {
+	pi.registerCommand("bg-clear", {
+		description: "Clear finished background task footer notices",
+		handler: async (_args, ctx) => {
+			notifyClearFinishedNotices(ctx);
+		},
+	});
+
+	pi.registerCommand("bg-update", {
+		description: "Show how to update pi-background-tasks to the latest published version",
+		handler: async (_args, ctx) => {
+			const current = PACKAGE_VERSION ?? "unknown";
+			const latest = latestKnownVersion;
+			const pinnedNpm = latest ? `${PACKAGE_NAME}@${latest}` : `${PACKAGE_NAME}@<version>`;
+			const pinnedGit = latest ? `${GIT_INSTALL_TARGET}@v${latest}` : `${GIT_INSTALL_TARGET}@<tag>`;
+			const lines = [
+				latest
+					? `pi-background-tasks ${current} is installed; ${latest} is the latest published version.`
+					: `pi-background-tasks ${current} is installed.`,
+				"Update from npm:",
+				`  pi install npm:${PACKAGE_NAME}@latest`,
+				`  pi install npm:${pinnedNpm}`,
+				"Or update from git tags:",
+				`  pi install ${pinnedGit}`,
+				"This command only prints update instructions; it does not install or self-update.",
+			];
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
+	pi.registerShortcut("shift+down" satisfies KeyId, {
 		description: "Open focused background task footer dock",
 		handler: async (ctx) => {
 			await openTaskManager(ctx);
 		},
 	});
 
-	pi.registerShortcut("shift+c" as any, {
-		description: "Clear finished background task footer notices",
-		handler: (ctx) => {
-			currentCtx = ctx;
-			const cleared = clearFinishedNotices(ctx);
-			if (ctx.hasUI) {
-				ctx.ui.notify(
-					cleared > 0
-						? `Cleared ${cleared} finished background task notice${cleared === 1 ? "" : "s"}.`
-						: "No finished background task notices to clear.",
-					cleared > 0 ? "info" : "warning",
-				);
-			}
-		},
+	pi.registerShortcut("ctrl+alt+c" satisfies KeyId, {
+		description: "Clear finished background task footer notices (terminal-dependent fallback for /bg-clear)",
+		handler: (ctx) => notifyClearFinishedNotices(ctx),
 	});
 
 	pi.registerCommand("jobs", {
 		description: "List running and recent background tasks",
 		handler: async (_args, ctx) => {
 			currentCtx = ctx;
-			ctx.ui.notify(formatTaskList([...tasks.values()]), "info");
+			ctx.ui.notify(formatSnapshotList(registry.allTasks().map((task) => registry.snapshot(task))), "info");
 			updateUi(ctx);
 		},
 	});
@@ -1052,7 +384,7 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 	pi.registerCommand("logs", {
 		description: "Show bounded output from a background task: /logs <id> [maxBytes]",
 		getArgumentCompletions: (prefix) => {
-			const matches = [...tasks.values()]
+			const matches = registry.allTasks()
 				.filter((task) => task.id.startsWith(prefix.trim()))
 				.slice(0, 20)
 				.map((task) => ({ value: task.id, label: `${task.id} ${taskDisplayName(task)}`, description: `${task.status} — ${truncateChars(task.command, 60)}` }));
@@ -1062,9 +394,9 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 			try {
 				currentCtx = ctx;
 				const [id, bytes] = args.trim().split(/\s+/, 2);
-				const task = resolveTask(id || "");
-				const maxBytes = normalizeMaxBytes(Number(bytes));
-				const logs = await getTaskLogs(task, maxBytes, true);
+				const task = registry.resolveTask(id || "");
+				const maxBytes = normalizeMaxBytes(Number(bytes), DEFAULT_LOG_BYTES);
+				const logs = await registry.getTaskLogs(task, maxBytes, true);
 				ctx.ui.notify(logs.text, "info");
 			} catch (error) {
 				ctx.ui.notify(`Background logs error: ${error instanceof Error ? error.message : String(error)}`, "error");
@@ -1075,7 +407,7 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 	pi.registerCommand("kill", {
 		description: "Stop a running background task: /kill <id>",
 		getArgumentCompletions: (prefix) => {
-			const matches = [...tasks.values()]
+			const matches = registry.allTasks()
 				.filter((task) => task.status === "running" && task.id.startsWith(prefix.trim()))
 				.slice(0, 20)
 				.map((task) => ({ value: task.id, label: `${task.id} ${taskDisplayName(task)}`, description: truncateChars(task.command, 70) }));
@@ -1084,8 +416,8 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		handler: async (args, ctx) => {
 			try {
 				currentCtx = ctx;
-				const task = resolveTask(args.trim());
-				await stopTask(task, "user");
+				const task = registry.resolveTask(args.trim());
+				await registry.stopTask(task, "user");
 				ctx.ui.notify(`Killed ${taskDisplayName(task)} (${task.id}). Output: ${task.outputPath}`, "info");
 				updateUi(ctx);
 			} catch (error) {
@@ -1094,15 +426,6 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		},
 	});
 
-	const BgRunParams = Type.Object({
-		name: Type.String({ description: "Short human-readable task name shown in the bg footer dock. Required; use 2-6 words, not the raw command." }),
-		command: Type.String({ description: "Shell command to start in the background" }),
-		description: Type.Optional(Type.String({ description: "Optional longer human-readable context for the task" })),
-		timeoutSeconds: Type.Optional(Type.Number({ description: "Optional timeout; task is failed and killed when exceeded" })),
-		notifyOnCompletion: Type.Optional(Type.Boolean({ description: "Whether to show a completion notification. Default: true." })),
-		triggerOnCompletion: Type.Optional(Type.Boolean({ description: "Whether completion should trigger a follow-up agent turn. Default: true for bg_run." })),
-	});
-
 	pi.registerTool<typeof BgRunParams, BgRunDetails>({
 		name: "bg_run",
 		label: "Background Run",
@@ -1110,37 +433,50 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		promptSnippet: "Start named long-running shell commands in the background and return a task ID plus output file path",
 		promptGuidelines: [
 			"Use bg_run instead of bash for commands expected to run for a long time, such as test suites, dev servers, watchers, builds, or sleeps.",
+			"Always set isAgent: true only when the background task launches an LLM/agent process; set isAgent: false for scripts, tests, dev servers, sleeps, and ordinary shell commands.",
 			"When using bg_run, always set name to a concise 2-6 word human-readable label for the footer task dock; do not use the raw command as the name unless it is already short and meaningful.",
 			"After bg_run, use bg_status and bg_logs to inspect progress; do not assume the background task completed until status says completed, failed, or killed.",
 			"When a <background-task-notification> appears, react to it: inspect bg_status/bg_logs as needed, then report completion, failure, or next steps to the user.",
 		],
 		parameters: BgRunParams,
-		prepareArguments(args) {
-			const fallback = { name: "Background task", command: "" };
-			if (!args || typeof args !== "object") return fallback;
-			const input = args as { name?: unknown; command?: unknown; description?: unknown };
-			if (normalizeTaskName(input.name) && typeof input.command === "string") return input as any;
-			if (typeof input.command !== "string") return fallback;
-			return {
-				...input,
-				name: normalizeTaskName(input.description) ?? deriveTaskNameFromCommand(input.command),
+		prepareArguments(args): BgRunParamsValue {
+			if (!args || typeof args !== "object") throw new Error("bg_run arguments must be an object");
+			const input = args as Record<string, unknown>;
+			if (typeof input["command"] !== "string") throw new Error("bg_run requires command string");
+			if (typeof input["isAgent"] !== "boolean") {
+				throw new Error("bg_run requires isAgent boolean. Set true only for LLM/agent tasks; set false for scripts, tests, servers, sleeps, and ordinary shell commands.");
+			}
+			const prepared: BgRunParamsValue = {
+				command: input["command"],
+				name: normalizeTaskName(input["name"]) ?? normalizeTaskName(input["description"]) ?? deriveTaskNameFromCommand(input["command"]),
+				isAgent: input["isAgent"],
 			};
+			if (typeof input["description"] === "string") prepared.description = input["description"];
+			if (typeof input["timeoutSeconds"] === "number") prepared.timeoutSeconds = input["timeoutSeconds"];
+			if (typeof input["notifyOnCompletion"] === "boolean") prepared.notifyOnCompletion = input["notifyOnCompletion"];
+			if (typeof input["triggerOnCompletion"] === "boolean") prepared.triggerOnCompletion = input["triggerOnCompletion"];
+			return prepared;
 		},
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const task = await startTask(ctx, params.command, {
+			if (typeof params.isAgent !== "boolean") {
+				throw new Error("bg_run requires isAgent boolean. Set true only for LLM/agent tasks; set false for scripts, tests, servers, sleeps, and ordinary shell commands.");
+			}
+			const taskOptions: StartTaskOptions = {
 				name: params.name,
-				description: params.description,
-				timeoutSeconds: params.timeoutSeconds,
+				isAgent: params.isAgent,
 				notifyOnCompletion: params.notifyOnCompletion ?? true,
 				triggerOnCompletion: params.triggerOnCompletion ?? true,
-			});
+			};
+			if (params.description !== undefined) taskOptions.description = params.description;
+			if (params.timeoutSeconds !== undefined) taskOptions.timeoutSeconds = params.timeoutSeconds;
+			const task = await startTask(ctx, params.command, taskOptions);
 			return {
 				content: textContent(`Started background task ${taskDisplayName(task)} (${task.id})\nStatus: ${task.status}\nPID: ${task.pid ?? "unknown"}\nOutput: ${task.outputPath}`),
-				details: { task: snapshot(task) },
+				details: { task: registry.snapshot(task) },
 			};
 		},
 		renderCall(args, theme) {
-			return new Text(`${theme.fg("toolTitle", theme.bold("bg_run "))}${theme.fg("muted", truncateChars(taskDisplayName(args), 90))}`, 0, 0);
+			return new Text(`${theme.fg("toolTitle", theme.bold("bg_run "))}${theme.fg("muted", truncateChars(taskDisplayName(args), COMMAND_PREVIEW_CHARS))}`, 0, 0);
 		},
 		renderResult(result, _options, theme) {
 			const task = result.details?.task;
@@ -1149,10 +485,6 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		},
 	});
 
-	const BgStatusParams = Type.Object({
-		taskId: Type.Optional(Type.String({ description: "Optional task ID or unambiguous prefix. If omitted, all running/recent tasks are returned." })),
-	});
-
 	pi.registerTool<typeof BgStatusParams, BgStatusDetails>({
 		name: "bg_status",
 		label: "Background Status",
@@ -1161,8 +493,8 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		promptGuidelines: ["Use bg_status before bg_logs when you need to know whether a background task is still running or has finished."],
 		parameters: BgStatusParams,
 		async execute(_toolCallId, params) {
-			const selected = params.taskId ? [resolveTask(params.taskId)] : [...tasks.values()];
-			const snapshots = selected.map(snapshot);
+			const selected = params.taskId ? [registry.resolveTask(params.taskId)] : registry.allTasks();
+			const snapshots = selected.map((task) => registry.snapshot(task));
 			return {
 				content: textContent(formatSnapshotList(snapshots)),
 				details: { tasks: snapshots },
@@ -1174,12 +506,6 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		renderResult: renderPlainResult,
 	});
 
-	const BgLogsParams = Type.Object({
-		taskId: Type.String({ description: "Task ID or unambiguous prefix" }),
-		maxBytes: Type.Optional(Type.Number({ description: `Maximum bytes to return, capped at ${formatSize(MAX_LOG_BYTES)}. Default: ${formatSize(DEFAULT_LOG_BYTES)}.` })),
-		tail: Type.Optional(Type.Boolean({ description: "Read the tail of the log when true, head when false. Default: true." })),
-	});
-
 	pi.registerTool<typeof BgLogsParams, BgLogsDetails>({
 		name: "bg_logs",
 		label: "Background Logs",
@@ -1188,8 +514,8 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		promptGuidelines: ["Use bg_logs with a modest maxBytes value to inspect background task progress without flooding context."],
 		parameters: BgLogsParams,
 		async execute(_toolCallId, params) {
-			const task = resolveTask(params.taskId);
-			const logs = await getTaskLogs(task, normalizeMaxBytes(params.maxBytes), params.tail ?? true);
+			const task = registry.resolveTask(params.taskId);
+			const logs = await registry.getTaskLogs(task, normalizeMaxBytes(params.maxBytes), params.tail ?? true);
 			return {
 				content: textContent(logs.text),
 				details: logs.details,
@@ -1212,10 +538,6 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		},
 	});
 
-	const BgKillParams = Type.Object({
-		taskId: Type.String({ description: "Task ID or unambiguous prefix to stop" }),
-	});
-
 	pi.registerTool<typeof BgKillParams, BgKillDetails>({
 		name: "bg_kill",
 		label: "Background Kill",
@@ -1224,12 +546,12 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		promptGuidelines: ["Use bg_kill when the user asks to stop a background task or when a bg_run command is no longer needed."],
 		parameters: BgKillParams,
 		async execute(_toolCallId, params) {
-			const task = resolveTask(params.taskId);
-			await stopTask(task, "user");
+			const task = registry.resolveTask(params.taskId);
+			await registry.stopTask(task, "user");
 			const message = `Killed background task ${taskDisplayName(task)} (${task.id}). Output: ${task.outputPath}`;
 			return {
 				content: textContent(message),
-				details: { task: snapshot(task), message },
+				details: { task: registry.snapshot(task), message },
 			};
 		},
 		renderCall(args, theme) {