@steveimm/pi-background 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SteveImmanuel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @steveimm/pi-background
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run commands and polling checks in the background while continuing to chat with Pi.
+When a command finishes or a watcher reports a result, the extension starts a follow-up turn so the agent can act on it.
+
+## Install
+
+After publication:
+
+```bash
+pi install npm:@steveimm/pi-background
+```
+
+For local development, run from the repository root:
+
+```bash
+npm ci
+pi -e ./packages/pi-background
+```
+
+Use Pi 1.5.1 or newer.
+Install globally or use `-e` so the extension stays loaded when you change directories.
+
+## Background processes
+
+The agent uses `background_process` with these actions:
+
+| Action | Purpose |
+| --- | --- |
+| `start` | Start a command and return its ID immediately. |
+| `list` | Show running and finished processes. |
+| `read` | Read a process's status and recent output. |
+| `stop` | Stop a process and its children. |
+
+For example, ask Pi:
+
+> Download the file in the background. When it finishes, verify its checksum and tell me the result.
+
+The agent supplies a `command` and can include `cwd`, `label`, `instruction`, and `timeout_seconds`.
+The instruction is included in the completion notification so the agent knows what to do next.
+Commands run without terminal input and have no time limit unless one is supplied.
+Do not add `&` to the command: the extension manages the background process.
+
+## Background a running Bash command
+
+Press **Ctrl+B** while the agent's Bash command is running to move it to the background.
+With tmux's default prefix, press Ctrl+B twice to send the key to Pi.
+The shortcut selects the most recently started foreground Bash command.
+When no command is running, Pi handles the key normally.
+
+This also works for Bash calls made through codemode.
+The call returns a background process ID and the command continues running.
+If the script is also waiting for other foreground commands, those calls still need to finish or be moved to the background.
+An explicitly supplied timeout continues to apply after the command is moved.
+
+The shortcut wraps Pi's local Bash tool.
+Other extensions that also replace `bash` may override this behavior, depending on their load order.
+
+## Watchers
+
+The agent uses `background_watch` to create, list, or delete polling checks.
+Each watcher runs a shell command in its original working directory.
+
+| Mode | Behavior |
+| --- | --- |
+| `until_success` | Notify when the check exits with code 0, then remove the watcher. Other exit codes keep it waiting. |
+| `on_change` | Record the first result, then notify when output or exit code changes. Continue until deleted. |
+
+Examples:
+
+> Check every 30 seconds whether the download is complete. When it is, inspect the archive.
+
+> Watch the server log for changes every 10 seconds and report new errors. Delete the watcher when we are done.
+
+The default mode is `until_success`, with 30 seconds between checks and a 10-second timeout for each check.
+The agent can set `interval_seconds`, `timeout_seconds`, and a follow-up `instruction`.
+Checks never overlap: the interval starts after the previous check finishes.
+Timeouts and commands that cannot run generate an error notification, with repeated identical errors suppressed.
+Ordinary polling does not call the model.
+
+## Codemode
+
+Both tools return structured values to codemode scripts.
+Await each start call to obtain its ID, then let the script return:
+
+```js
+const results = await Promise.allSettled([
+  tools.background_process({
+    action: "start",
+    command: "npm test",
+    instruction: "Inspect any failures when the tests finish."
+  }),
+  tools.bash({ command: "git status --short" })
+]);
+results.forEach(text);
+```
+
+Once the start call returns, Pi owns the process independently of the codemode script.
+The process continues if that script later returns or fails.
+Its notification goes to the Pi conversation after the current turn finishes.
+Commands that share files or ports still need to be ordered by the agent.
+If the user backgrounds a Bash call, that call returns `background: true`, `id`, and `exit_code: null`.
+Scripts should check `background` before treating the result as a completed command.
+See [Pi's codemode documentation](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/codemode.md).
+
+## Notifications and lifetime
+
+Completion and failure notifications include the task ID, command, working directory, exit code, recent output, log path, and saved instruction.
+If the agent is busy, delivery waits until its turn finishes.
+If the agent is idle, delivery starts a new turn without another user message.
+Watcher updates that arrive while the agent is busy are combined into the latest result for each watcher.
+Stopping a process or deleting a watcher cancels its pending notification.
+
+Jobs and watchers survive `/reload` and `/cd` within the same conversation.
+Their commands keep the working directory selected when they were created.
+Starting or switching to a different conversation, forking, or quitting Pi stops them.
+They do not resume after restarting Pi.
+Keep Pi running in interactive or RPC mode to receive notifications.
+
+Logs are saved under `~/.pi/agent/background/`, or under the configured Pi agent directory.
+Each log keeps up to 10 MiB, and the read tool also retains the most recent 16 KiB of output in memory.
+The status reports when a log has been truncated.
+
+The extension uses [Pi's shell execution and message APIs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md).
+
+## Development
+
+From the repository root:
+
+```bash
+npm run check
+npm test --workspace=packages/pi-background
+```
+
+The default tests use a local test provider and do not make model requests.
+The optional terminal test requires tmux:
+
+```bash
+npm run test:terminal --workspace=packages/pi-background
+```
+
+The optional GPT test uses the current Pi authentication and makes model requests:
+
+```bash
+npm run test:live --workspace=packages/pi-background
+```
+
+It defaults to `openai-codex/gpt-6.1-sol`.
+Set `PI_BACKGROUND_TEST_PROVIDER` and `PI_BACKGROUND_TEST_MODEL` to select another configured GPT provider and model.
+
+## License
+
+MIT

package/foreground.ts

@@ -0,0 +1,77 @@
+import { createBashToolDefinition, createLocalBashOperations, type BashToolOptions } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { BackgroundManager, ForegroundProcess } from "./manager.js";
+
+class Backgrounded extends Error {
+	readonly id: string;
+	constructor(id: string) {
+		super(`Command moved to the background: ${id}`);
+		this.id = id;
+	}
+}
+
+export function createManagedBash(
+	getManager: () => BackgroundManager,
+	getOptions: () => BashToolOptions,
+): ReturnType<typeof createBashToolDefinition> {
+	const original = createBashToolDefinition(".");
+	return {
+		...original,
+		description: `${original.description} The user can move a running command to the background. In that case the result has background: true, backgrounded_by: "user", a process id, and no exit code yet. Do not wait or repeatedly poll that process. Completion will notify you automatically.`,
+		outputSchema: Type.Union([
+			original.outputSchema!,
+			Type.Object({ background: Type.Literal(true), backgrounded_by: Type.Literal("user"),
+				id: Type.String(), output: Type.String(),
+				log_path: Type.String(), truncated: Type.Boolean(), exit_code: Type.Null() }),
+		]),
+		async execute(callId, params, signal, onUpdate, ctx) {
+			if (signal?.aborted) throw new Error("Command aborted");
+			const manager = getManager();
+			const options = getOptions();
+			const backend = createLocalBashOperations(options.shellPath ? { shellPath: options.shellPath } : undefined);
+			let process: ForegroundProcess | undefined;
+			const tool = createBashToolDefinition(ctx.cwd, {
+				...options,
+				operations: {
+					async exec(command, cwd, execution) {
+						process = manager.startForeground({
+							command: params.command, cwd,
+							instruction: "The user moved this command to the background. Inspect its result and continue the original task.",
+							...(execution.timeout === undefined ? {} : { timeoutSeconds: execution.timeout }),
+						}, {
+							exec: (_command, directory, job) => backend.exec(command, directory, {
+								...job, ...(execution.env === undefined ? {} : { env: execution.env }),
+							}),
+						}, execution.onData);
+						const running = process;
+						const abort = () => running.cancel();
+						if (execution.signal?.aborted) abort();
+						else execution.signal?.addEventListener("abort", abort, { once: true });
+						try {
+							return await Promise.race([
+								running.completed,
+								running.backgrounded.then(() => { throw new Backgrounded(running.id); }),
+							]);
+						} finally {
+							execution.signal?.removeEventListener("abort", abort);
+						}
+					},
+				},
+			});
+			try {
+				return await tool.execute(callId, params, signal, onUpdate, ctx);
+			} catch (error) {
+				if (!(error instanceof Backgrounded)) throw error;
+				const job = manager.readProcess(error.id);
+				return {
+					content: [{ type: "text", text: `The user moved this command to the background as ${job.id}. You can finish this turn. Completion will notify you automatically.\nLog: ${job.log_path}` }],
+					details: undefined,
+					structuredContent: { background: true, backgrounded_by: "user", id: job.id, output: job.output, log_path: job.log_path,
+						truncated: job.output_truncated, exit_code: null },
+				};
+			} finally {
+				if (process) manager.forgetForeground(process.id);
+			}
+		},
+	};
+}

package/index.ts

@@ -0,0 +1,279 @@
+import { existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	createLocalBashOperations,
+	getAgentDir,
+	SessionManager,
+	type AgentToolResult,
+	type BashOperations,
+	type BashToolOptions,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { matchesKey } from "@earendil-works/pi-tui";
+import { createManagedBash } from "./foreground.js";
+import { attachBackgroundStatus } from "./status.js";
+import { showBackgroundTasks } from "./ui.js";
+import { BackgroundManager, expandHome, resolveDirectory, type CommandOptions } from "./manager.js";
+
+const stateKey = Symbol.for("@steveimm/pi-background/managers");
+const shared = globalThis as typeof globalThis & { [stateKey]?: Map<string, BackgroundManager> };
+const managers = shared[stateKey] ??= new Map();
+
+const shellCommand = Type.String({ description: "Noninteractive shell command. Do not add & to background it.", minLength: 1 });
+const commandFields = {
+	command: Type.Optional(shellCommand),
+	cwd: Type.Optional(Type.String({ description: "Working directory, relative to the current session by default." })),
+	label: Type.Optional(Type.String({ description: "Short description of the work." })),
+	instruction: Type.Optional(Type.String({ description: "What to do when this process finishes or this watcher notifies you." })),
+	timeout_seconds: Type.Optional(Type.Number({ minimum: 1, maximum: 2147483 })),
+};
+
+const taskOutputFields = {
+	id: Type.String(), command: Type.String(), cwd: Type.String(), label: Type.Optional(Type.String()),
+};
+const watcherMode = Type.Union([Type.Literal("until_success"), Type.Literal("on_change"), Type.Literal("interval")]);
+const watcherInterval = Type.Number({ minimum: 1, maximum: 86400,
+	description: "Delay in seconds between reminders or checks. Shell checks default to 30 seconds.",
+});
+const watcherInstruction = Type.String({ minLength: 1,
+	description: "What to remind the user about or do when notified.",
+});
+const processOutput = Type.Object({
+	...taskOutputFields,
+	status: Type.Union([Type.Literal("running"), Type.Literal("completed"), Type.Literal("failed"), Type.Literal("stopped")]),
+	background: Type.Boolean(),
+	exit_code: Type.Union([Type.Integer(), Type.Null()]), error: Type.Optional(Type.String()),
+	started_at: Type.String(), finished_at: Type.Optional(Type.String()),
+	log_path: Type.String(), log_truncated: Type.Boolean(), output: Type.Optional(Type.String()), message: Type.Optional(Type.String()),
+	output_truncated: Type.Optional(Type.Boolean()),
+});
+const watcherOutput = Type.Object({
+	...taskOutputFields,
+	command: Type.Optional(Type.String()), instruction: Type.Optional(Type.String()),
+	mode: watcherMode, interval_seconds: Type.Number(),
+	last_check: Type.Optional(Type.String()), last_exit_code: Type.Optional(Type.Union([Type.Integer(), Type.Null()])),
+	last_error: Type.Optional(Type.String()), output: Type.Optional(Type.String()),
+	log_path: Type.Optional(Type.String()), log_truncated: Type.Optional(Type.Boolean()),
+});
+
+function result(value: unknown): AgentToolResult<unknown> {
+	const text = JSON.stringify(value, null, 2);
+	return { content: [{ type: "text", text }], details: undefined, structuredContent: JSON.parse(text) };
+}
+
+function commandOptions(params: {
+	command?: string; cwd?: string; label?: string; instruction?: string; timeout_seconds?: number;
+}, cwd: string): CommandOptions {
+	if (params.command === undefined) throw new Error("Provide a shell command.");
+	return {
+		command: params.command, cwd: resolveDirectory(params.cwd, cwd),
+		...(params.label === undefined ? {} : { label: params.label }),
+		...(params.instruction === undefined ? {} : { instruction: params.instruction }),
+		...(params.timeout_seconds === undefined ? {} : { timeoutSeconds: params.timeout_seconds }),
+	};
+}
+
+export default function (pi: ExtensionAPI) {
+	let manager: BackgroundManager | undefined;
+	let sessionId: string | undefined;
+	let removeInputHandler: (() => void) | undefined;
+	let removeStatus: (() => void) | undefined;
+	let temporaryLogDirectory: string | undefined;
+
+	function current(): BackgroundManager {
+		if (!manager) throw new Error("No active background session.");
+		return manager;
+	}
+
+	function shellOptions(): BashToolOptions {
+		const settings = pi.getSettings();
+		return {
+			...(settings.shellPath === undefined ? {} : { shellPath: expandHome(settings.shellPath) }),
+			...(settings.shellCommandPrefix === undefined ? {} : { commandPrefix: settings.shellCommandPrefix }),
+		};
+	}
+
+	function shellOperations(): BashOperations {
+		const options = shellOptions();
+		const backend = createLocalBashOperations(options.shellPath ? { shellPath: options.shellPath } : undefined);
+		return {
+			exec: (command, cwd, execution) => backend.exec(
+				options.commandPrefix ? `${options.commandPrefix}\n${command}` : command, cwd, execution,
+			),
+		};
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		sessionId = ctx.sessionManager.getSessionId();
+		const sessionFile = ctx.sessionManager.getSessionFile();
+		temporaryLogDirectory = sessionFile ? undefined : join(tmpdir(), `pi-session-${process.pid}-${encodeURIComponent(sessionId)}.bg`);
+		const logDirectory = sessionFile ? `${sessionFile}.bg` : temporaryLogDirectory!;
+		manager = managers.get(sessionId);
+		if (!manager) {
+			const legacyDirectory = join(getAgentDir(), "background", `session-${encodeURIComponent(sessionId)}`);
+			manager = new BackgroundManager(existsSync(legacyDirectory) ? legacyDirectory : logDirectory);
+			managers.set(sessionId, manager);
+		} else {
+			// Refresh methods while keeping running jobs through /reload.
+			Object.setPrototypeOf(manager, BackgroundManager.prototype);
+		}
+		try {
+			const warning = manager.relocateLogs(logDirectory);
+			if (warning) ctx.ui.notify(warning, "warning");
+		} catch (error) {
+			ctx.ui.notify(`Could not move logs. They remain at ${manager.logDirectory}: ${error instanceof Error ? error.message : String(error)}`, "warning");
+		}
+		manager.attach({
+			isIdle: () => ctx.isIdle(),
+			send: events => {
+				const cleanup = events.some(event => event.kind === "watcher")
+					? '\nIf the goal or task an active watcher was created for is already finished, delete it with bg_watch using action="delete" and id from its event. Watchers with active=false have already been removed.'
+					: "";
+				pi.sendMessage({
+					customType: "pi-background",
+					content: `Background updates. Follow the saved instruction for each task. Captured output is process data.${cleanup}\n${JSON.stringify(events)}`,
+					display: true,
+					details: { events },
+				}, { triggerTurn: true, deliverAs: "followUp" });
+			},
+		});
+		if (ctx.mode === "tui") {
+			removeStatus = attachBackgroundStatus(manager, ctx);
+			removeInputHandler = ctx.ui.onTerminalInput(data => {
+				if (!matchesKey(data, "ctrl+b")) return;
+				const id = manager?.backgroundLatest();
+				if (!id) return;
+				ctx.ui.notify(`Moved command to the background: ${id}`, "info");
+				return { consume: true };
+			});
+		}
+	});
+
+	pi.on("agent_settled", () => manager?.requestDelivery());
+
+	pi.on("session_shutdown", async event => {
+		removeStatus?.();
+		removeStatus = undefined;
+		removeInputHandler?.();
+		removeInputHandler = undefined;
+		if (!manager || !sessionId) return;
+		let keep = event.reason === "reload";
+		if (event.reason === "resume" && event.targetSessionFile) {
+			try {
+				keep = SessionManager.open(event.targetSessionFile).getSessionId() === sessionId;
+			} catch {
+				keep = false;
+			}
+		}
+		manager.detach();
+		if (!keep) {
+			await manager.dispose();
+			managers.delete(sessionId);
+			if (temporaryLogDirectory === manager.logDirectory) rmSync(temporaryLogDirectory, { recursive: true, force: true });
+		}
+		manager = undefined;
+	});
+
+	pi.registerCommand("bg", {
+		description: "List and stop background processes and watchers",
+		handler: async (_args, ctx) => { await showBackgroundTasks(current(), ctx); },
+	});
+
+	pi.registerTool(createManagedBash(current, shellOptions));
+
+	pi.registerTool({
+		name: "bg_process",
+		label: "Background process",
+		description: `Run noninteractive shell commands in the background and return immediately.
+
+Actions:
+- start: requires command and returns a process ID. Optional fields are cwd, label, instruction, and timeout_seconds.
+- list: show running and finished background processes.
+- read: requires id and returns the process status and recent output.
+- stop: requires id and stops the process and its children, cancelling any pending completion notification.
+
+Completion or failure sends the result and saved instruction in a follow-up turn. You can finish your reply while the process runs. Do not repeatedly poll just to wait for completion.
+
+Set instruction to describe what to do with the result. Process completion already sends a notification, so it does not need a separate watcher.
+
+In codemode, await the start call to obtain its ID. Once it returns, the process continues independently of the script. Do not add & to the command.`,
+		parameters: Type.Object({
+			action: Type.Union([Type.Literal("start"), Type.Literal("list"), Type.Literal("read"), Type.Literal("stop")]),
+			id: Type.Optional(Type.String({ description: "Process ID returned by start." })),
+			...commandFields,
+		}),
+		outputSchema: Type.Union([processOutput, Type.Array(processOutput)]),
+		async execute(_callId, params, signal, _onUpdate, ctx) {
+			if (signal?.aborted) throw new Error("The tool call was cancelled.");
+			const tasks = current();
+			if (params.action === "list") return result(tasks.listProcesses());
+			if (params.action === "start") {
+				const job = tasks.start(commandOptions(params, ctx.cwd), shellOperations());
+				return result({ ...job, message: "Running in the background. You can finish this turn. Completion will notify you automatically." });
+			}
+			if (!params.id) throw new Error("Provide a process ID.");
+			return result(params.action === "read" ? tasks.readProcess(params.id) : await tasks.stopProcess(params.id));
+		},
+	});
+
+	pi.registerTool({
+		name: "bg_watch",
+		label: "Background watcher",
+		description: `Create, list, or delete background condition checks and periodic reminders.
+
+Actions:
+- create: requires mode and the fields it specifies. Returns a watcher ID.
+- list: show active watchers, their instructions, and their latest results.
+- delete: requires id and stops the watcher, including any active check and pending notification.
+
+Modes:
+- until_success: requires command. Check immediately, then repeat until it exits with code 0. On success, notify once and remove the watcher. Example: start a development server with bg_process, then watch command="curl -fsS http://localhost:3000/health" with instruction="Begin browser testing when the server is ready." This detects readiness while the server keeps running.
+- on_change: requires command. Record the first result, then notify when output or exit code changes. Use it for download progress or changing logs.
+- interval: requires interval_seconds and instruction. Send a recurring reminder, starting after one interval. Do not supply command or timeout_seconds. Example: a reminder every 15 minutes uses interval_seconds=900 and instruction="Remind the user to check the deployment."
+
+Shell checks default to 30 seconds between checks and a 10-second timeout per check. Optional cwd selects their working directory.
+
+Notifications include the saved instruction and start a follow-up turn when the agent is idle. Delete active watchers when their goal or task is finished.`,
+		parameters: Type.Union([
+			Type.Object({
+				...commandFields,
+				action: Type.Literal("create"),
+				mode: Type.Union([Type.Literal("until_success"), Type.Literal("on_change")]),
+				command: shellCommand,
+				interval_seconds: Type.Optional(watcherInterval),
+				instruction: Type.Optional(watcherInstruction),
+			}, { additionalProperties: false }),
+			Type.Object({
+				action: Type.Literal("create"), mode: Type.Literal("interval"),
+				interval_seconds: watcherInterval, instruction: watcherInstruction, label: commandFields.label,
+			}, { additionalProperties: false }),
+			Type.Object({ action: Type.Literal("list") }, { additionalProperties: false }),
+			Type.Object({
+				action: Type.Literal("delete"), id: Type.String({ minLength: 1, description: "Watcher ID returned by create." }),
+			}, { additionalProperties: false }),
+		], { type: "object" }),
+		outputSchema: Type.Union([watcherOutput, Type.Array(watcherOutput), Type.Object({ id: Type.String(), deleted: Type.Literal(true) })]),
+		async execute(_callId, params, signal, _onUpdate, ctx) {
+			if (signal?.aborted) throw new Error("The tool call was cancelled.");
+			const tasks = current();
+			if (params.action === "list") return result(tasks.listWatchers());
+			if (params.action === "delete") {
+				await tasks.deleteWatcher(params.id);
+				return result({ id: params.id, deleted: true });
+			}
+			if (params.mode === "interval") {
+				return result(tasks.watch({
+					mode: "interval", intervalSeconds: params.interval_seconds, instruction: params.instruction,
+					cwd: ctx.cwd,
+					...(params.label === undefined ? {} : { label: params.label }),
+				}, shellOperations()));
+			}
+			return result(tasks.watch({
+				...commandOptions(params, ctx.cwd),
+				mode: params.mode, intervalSeconds: params.interval_seconds ?? 30,
+			}, shellOperations()));
+		},
+	});
+}

package/manager.ts

@@ -0,0 +1,495 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+	accessSync, appendFileSync, constants, cpSync, existsSync, mkdirSync, mkdtempSync,
+	realpathSync, renameSync, rmSync, statSync, writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import type { BashOperations } from "@earendil-works/pi-coding-agent";
+
+const MAX_TAIL_BYTES = 16 * 1024;
+const MAX_LOG_BYTES = 10 * 1024 * 1024;
+
+export interface CommandOptions {
+	command: string;
+	cwd: string;
+	label?: string;
+	instruction?: string;
+	timeoutSeconds?: number;
+}
+
+export type WatchOptions =
+	| (CommandOptions & { mode: "until_success" | "on_change"; intervalSeconds: number })
+	| {
+		mode: "interval";
+		intervalSeconds: number;
+		instruction: string;
+		cwd: string;
+		label?: string;
+		command?: never;
+		timeoutSeconds?: never;
+	};
+
+interface OutputLog {
+	path: string;
+	bytes: number;
+	truncated: boolean;
+	tail: Buffer;
+}
+
+interface ProcessJob {
+	id: string;
+	options: CommandOptions;
+	status: "running" | "completed" | "failed" | "stopped";
+	exitCode: number | null;
+	error: string | undefined;
+	startedAt: string;
+	finishedAt: string | undefined;
+	log: OutputLog;
+	controller: AbortController;
+	done: Promise<void>;
+	background: boolean;
+	onData: ((data: Buffer) => void) | undefined;
+	onBackground: (() => void) | undefined;
+	executionError: unknown;
+}
+
+export interface ForegroundProcess {
+	id: string;
+	completed: Promise<{ exitCode: number | null }>;
+	backgrounded: Promise<void>;
+	cancel(): void;
+}
+
+interface Watcher {
+	id: string;
+	options: WatchOptions;
+	operations: BashOperations;
+	log: OutputLog;
+	controller: AbortController | undefined;
+	timer: ReturnType<typeof setTimeout> | undefined;
+	done: Promise<void>;
+	lastCheck: string | undefined;
+	lastExitCode: number | null;
+	lastError: string | undefined;
+	lastOutput: string;
+	previous: string | undefined;
+	previousError: string | undefined;
+}
+
+export interface BackgroundEvent {
+	id: string;
+	kind: "process" | "watcher";
+	event: string;
+	mode?: WatchOptions["mode"] | undefined;
+	active?: boolean;
+	command: string | undefined;
+	cwd: string;
+	label: string | undefined;
+	instruction: string | undefined;
+	exit_code: number | null;
+	error: string | undefined;
+	output: string;
+	log_path: string;
+}
+
+export interface NotificationTarget {
+	isIdle(): boolean;
+	send(events: BackgroundEvent[]): void;
+}
+
+export function expandHome(path: string): string {
+	if (path === "~") return homedir();
+	if (path.startsWith("~/") || path.startsWith("~\\")) return join(homedir(), path.slice(2));
+	return path;
+}
+
+export function resolveDirectory(path: string | undefined, cwd: string): string {
+	const target = realpathSync(resolve(cwd, expandHome(path ?? cwd)));
+	if (!statSync(target).isDirectory()) throw new Error(`Not a directory: ${target}`);
+	accessSync(target, constants.R_OK | constants.X_OK);
+	return target;
+}
+
+function appendOutput(log: OutputLog, data: Buffer): void {
+	const remaining = MAX_LOG_BYTES - log.bytes;
+	if (remaining > 0) {
+		const written = data.subarray(0, remaining);
+		appendFileSync(log.path, written);
+		log.bytes += written.length;
+	}
+	if (data.length > remaining) log.truncated = true;
+	log.tail = Buffer.concat([log.tail, data]).subarray(-MAX_TAIL_BYTES);
+}
+
+function errorMessage(error: unknown, timeout?: number): string {
+	const message = error instanceof Error ? error.message : String(error);
+	return message.startsWith("timeout:") ? `Timed out after ${timeout} seconds.` : message;
+}
+
+function processInfo(job: ProcessJob) {
+	return {
+		id: job.id, command: job.options.command, cwd: job.options.cwd, label: job.options.label,
+		status: job.status, background: job.background, exit_code: job.exitCode, error: job.error,
+		started_at: job.startedAt, finished_at: job.finishedAt, log_path: job.log.path, log_truncated: job.log.truncated,
+	};
+}
+
+export class BackgroundManager {
+	private processes = new Map<string, ProcessJob>();
+	private watchers = new Map<string, Watcher>();
+	private pending = new Map<string, BackgroundEvent>();
+	private target: NotificationTarget | undefined;
+	private flushTimer: ReturnType<typeof setTimeout> | undefined;
+	private disposed = false;
+	private listeners?: Set<() => void>;
+	logDirectory: string;
+
+	constructor(logDirectory: string) {
+		this.logDirectory = logDirectory;
+	}
+
+	subscribe(listener: () => void): () => void {
+		(this.listeners ??= new Set()).add(listener);
+		return () => { this.listeners?.delete(listener); };
+	}
+
+	private changed(): void {
+		for (const listener of this.listeners ?? []) listener();
+	}
+
+	relocateLogs(directory: string): string | undefined {
+		const previous = this.logDirectory;
+		if (directory === previous) return;
+		let copied = false;
+		if (existsSync(previous)) {
+			if (existsSync(directory)) throw new Error(`Log directory already exists: ${directory}`);
+			mkdirSync(dirname(directory), { recursive: true, mode: 0o700 });
+			try {
+				renameSync(previous, directory);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "EXDEV") throw error;
+				const staging = mkdtempSync(join(dirname(directory), ".bg-"));
+				try {
+					cpSync(previous, staging, { recursive: true, force: false, errorOnExist: true });
+					renameSync(staging, directory);
+					copied = true;
+				} catch (copyError) {
+					rmSync(staging, { recursive: true, force: true });
+					throw copyError;
+				}
+			}
+		}
+		this.logDirectory = directory;
+		for (const job of [...this.processes.values(), ...this.watchers.values()]) {
+			job.log.path = join(directory, basename(job.log.path));
+		}
+		for (const event of this.pending.values()) event.log_path = join(directory, basename(event.log_path));
+		if (copied) {
+			try {
+				rmSync(previous, { recursive: true });
+			} catch {
+				return `Logs moved to ${directory}, but the old copy could not be removed from ${previous}.`;
+			}
+		}
+	}
+
+	attach(target: NotificationTarget): void {
+		this.target = target;
+		this.requestDelivery();
+	}
+
+	detach(): void {
+		this.target = undefined;
+		clearTimeout(this.flushTimer);
+		this.flushTimer = undefined;
+	}
+
+	requestDelivery(): void {
+		if (this.disposed || !this.target || this.flushTimer || this.pending.size === 0) return;
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = undefined;
+			if (!this.target?.isIdle()) return;
+			const events = [...this.pending.values()].slice(0, 8).map(event => {
+				if (event.kind !== "watcher") return event;
+				const watcher = this.watchers.get(event.id);
+				return { ...event, mode: watcher?.options.mode ?? event.mode, active: watcher !== undefined };
+			});
+			this.target.send(events);
+			for (const event of events) this.pending.delete(event.id);
+			if (this.pending.size > 0) this.requestDelivery();
+		}, 25);
+		this.flushTimer.unref();
+	}
+
+	private queue(event: BackgroundEvent): void {
+		if (this.disposed) return;
+		this.pending.set(event.id, event);
+		this.changed();
+		this.requestDelivery();
+	}
+
+	private createLog(id: string): OutputLog {
+		if (this.disposed) throw new Error("This background session has ended.");
+		mkdirSync(this.logDirectory, { recursive: true, mode: 0o700 });
+		const path = join(this.logDirectory, `${id}.log`);
+		writeFileSync(path, "", { flag: "wx", mode: 0o600 });
+		return { path, bytes: 0, truncated: false, tail: Buffer.alloc(0) };
+	}
+
+	start(options: CommandOptions, operations: BashOperations) {
+		return processInfo(this.createProcess(options, operations));
+	}
+
+	startForeground(options: CommandOptions, operations: BashOperations, onData: (data: Buffer) => void): ForegroundProcess {
+		let onBackground!: () => void;
+		const backgrounded = new Promise<void>(resolve => { onBackground = resolve; });
+		const job = this.createProcess(options, operations, { onData, onBackground });
+		return {
+			id: job.id,
+			backgrounded,
+			cancel: () => {
+				// Ctrl+B takes effect before the caller's abort listener is removed.
+				if (!job.background) this.cancelProcess(job);
+			},
+			completed: job.done.then(() => {
+				if (job.executionError !== undefined) throw job.executionError;
+				if (job.status === "stopped") throw new Error("aborted");
+				return { exitCode: job.exitCode };
+			}),
+		};
+	}
+
+	backgroundLatest(): string | undefined {
+		const job = [...this.processes.values()].reverse().find(job => job.status === "running" && !job.background);
+		if (!job) return undefined;
+		job.background = true;
+		job.onData = undefined;
+		job.onBackground?.();
+		job.onBackground = undefined;
+		this.changed();
+		return job.id;
+	}
+
+	forgetForeground(id: string): void {
+		const job = this.processes.get(id);
+		if (!job || job.background || job.status === "running") return;
+		this.processes.delete(id);
+		rmSync(job.log.path, { force: true });
+	}
+
+	private createProcess(options: CommandOptions, operations: BashOperations,
+		foreground?: { onData: (data: Buffer) => void; onBackground: () => void }): ProcessJob {
+		if (!options.command.trim()) throw new Error("Provide a non-empty command.");
+		const id = `process-${randomUUID()}`;
+		const job: ProcessJob = {
+			id, options, status: "running", exitCode: null, error: undefined,
+			startedAt: new Date().toISOString(), finishedAt: undefined, log: this.createLog(id),
+			controller: new AbortController(), done: Promise.resolve(),
+			background: foreground === undefined, onData: foreground?.onData,
+			onBackground: foreground?.onBackground, executionError: undefined,
+		};
+		this.processes.set(id, job);
+		job.done = this.runProcess(job, operations);
+		if (job.background) this.changed();
+		return job;
+	}
+
+	private async runProcess(job: ProcessJob, operations: BashOperations): Promise<void> {
+		try {
+			const result = await operations.exec(job.options.command, job.options.cwd, {
+				signal: job.controller.signal,
+				...(job.options.timeoutSeconds === undefined ? {} : { timeout: job.options.timeoutSeconds }),
+				onData: data => {
+					try {
+						appendOutput(job.log, data);
+						job.onData?.(data);
+					} catch (error) {
+						job.error = `Cannot write the log: ${errorMessage(error)}`;
+						job.controller.abort();
+					}
+				},
+			});
+			job.exitCode = result.exitCode;
+			if (job.status !== "stopped") job.status = result.exitCode === 0 ? "completed" : "failed";
+		} catch (error) {
+			job.executionError = error;
+			if (job.status !== "stopped") {
+				job.status = "failed";
+				job.error ??= errorMessage(error, job.options.timeoutSeconds);
+			}
+		} finally {
+			job.finishedAt = new Date().toISOString();
+			if (job.background && job.status !== "stopped") {
+				this.queue({
+					id: job.id, kind: "process", event: job.status, command: job.options.command, cwd: job.options.cwd,
+					label: job.options.label, instruction: job.options.instruction, exit_code: job.exitCode,
+					error: job.error, output: job.log.tail.toString("utf8").slice(-2000), log_path: job.log.path,
+				});
+			}
+		}
+	}
+
+	listProcesses() {
+		return [...this.processes.values()].filter(job => job.background).map(processInfo);
+	}
+
+	readProcess(id: string) {
+		const job = this.processes.get(id);
+		if (!job) throw new Error(`Unknown background process: ${id}`);
+		return {
+			...processInfo(job), output: job.log.tail.toString("utf8"),
+			output_truncated: job.log.truncated || job.log.bytes > job.log.tail.length,
+		};
+	}
+
+	async stopProcess(id: string) {
+		const job = this.processes.get(id);
+		if (!job) throw new Error(`Unknown background process: ${id}`);
+		this.cancelProcess(job);
+		await job.done;
+		this.pending.delete(id);
+		return processInfo(job);
+	}
+
+	private cancelProcess(job: ProcessJob): void {
+		if (job.status === "running") {
+			job.status = "stopped";
+			job.controller.abort();
+			if (job.background) this.changed();
+		}
+	}
+
+	watch(options: WatchOptions, operations: BashOperations) {
+		if (options.mode === "interval") {
+			if (!options.instruction.trim()) throw new Error("Provide an instruction for the reminder.");
+		} else if (!options.command.trim()) {
+			throw new Error("Provide a non-empty check command.");
+		}
+		const id = `watch-${randomUUID()}`;
+		const watcher: Watcher = {
+			id, options, operations, log: this.createLog(id), controller: undefined, timer: undefined,
+			done: Promise.resolve(), lastCheck: undefined, lastExitCode: null, lastError: undefined,
+			lastOutput: "", previous: undefined, previousError: undefined,
+		};
+		this.watchers.set(id, watcher);
+		if (options.mode === "interval") this.schedule(watcher);
+		else watcher.done = this.check(watcher);
+		this.changed();
+		return {
+			id, command: options.command, cwd: options.cwd, mode: options.mode,
+			interval_seconds: options.intervalSeconds, instruction: options.instruction,
+		};
+	}
+
+	private schedule(watcher: Watcher): void {
+		if (this.disposed || !this.watchers.has(watcher.id)) return;
+		watcher.timer = setTimeout(() => { watcher.done = this.check(watcher); }, watcher.options.intervalSeconds * 1000);
+		watcher.timer.unref();
+	}
+
+	private notifyWatcher(watcher: Watcher, event: string): void {
+		this.queue({
+			id: watcher.id, kind: "watcher", event, mode: watcher.options.mode,
+			command: watcher.options.command, cwd: watcher.options.cwd,
+			label: watcher.options.label, instruction: watcher.options.instruction, exit_code: watcher.lastExitCode,
+			error: watcher.lastError, output: watcher.lastOutput.slice(-2000), log_path: watcher.log.path,
+		});
+	}
+
+	private async check(watcher: Watcher): Promise<void> {
+		if (this.disposed || !this.watchers.has(watcher.id)) return;
+		const options = watcher.options;
+		if (options.mode === "interval") {
+			watcher.lastCheck = new Date().toISOString();
+			watcher.lastError = undefined;
+			try {
+				appendOutput(watcher.log, Buffer.from(`\n[${watcher.lastCheck}] Reminder\n`));
+			} catch (error) {
+				watcher.lastError = `Cannot write the log: ${errorMessage(error)}`;
+			}
+			this.notifyWatcher(watcher, "reminder");
+			this.schedule(watcher);
+			return;
+		}
+		const controller = new AbortController();
+		watcher.controller = controller;
+		const hash = createHash("sha256");
+		let output = Buffer.alloc(0);
+		let failure: string | undefined;
+		let exitCode: number | null = null;
+		const timeout = options.timeoutSeconds ?? 10;
+		try {
+			appendOutput(watcher.log, Buffer.from(`\n[${new Date().toISOString()}] Checking\n`));
+			const result = await watcher.operations.exec(options.command, options.cwd, {
+				signal: controller.signal, timeout,
+				onData: data => {
+					hash.update(data);
+					output = Buffer.concat([output, data]).subarray(-MAX_TAIL_BYTES);
+					try {
+						appendOutput(watcher.log, data);
+					} catch (error) {
+						failure = `Cannot write the log: ${errorMessage(error)}`;
+						controller.abort();
+					}
+				},
+			});
+			exitCode = result.exitCode;
+			if (exitCode === 126 || exitCode === 127) failure = `Check command could not run (exit ${exitCode}).`;
+		} catch (error) {
+			failure ??= errorMessage(error, timeout);
+		}
+		if (this.disposed || !this.watchers.has(watcher.id)) return;
+		watcher.lastCheck = new Date().toISOString();
+		watcher.lastExitCode = exitCode;
+		watcher.lastError = failure;
+		watcher.lastOutput = output.toString("utf8");
+		watcher.controller = undefined;
+		const signature = `${exitCode}:${failure ?? ""}:${hash.digest("hex")}`;
+		let event: string | undefined;
+		if (failure) {
+			if (failure !== watcher.previousError) event = "check_failed";
+		} else if (options.mode === "until_success") {
+			if (exitCode === 0) {
+				event = "matched";
+				this.watchers.delete(watcher.id);
+			}
+		} else {
+			if (watcher.previous !== undefined && watcher.previous !== signature) event = "changed";
+		}
+		watcher.previous = signature;
+		watcher.previousError = failure;
+		if (event) this.notifyWatcher(watcher, event);
+		this.schedule(watcher);
+	}
+
+	listWatchers() {
+		return [...this.watchers.values()].map(watcher => ({
+			id: watcher.id, command: watcher.options.command, cwd: watcher.options.cwd, label: watcher.options.label,
+			mode: watcher.options.mode, interval_seconds: watcher.options.intervalSeconds, instruction: watcher.options.instruction,
+			last_check: watcher.lastCheck, last_exit_code: watcher.lastExitCode, last_error: watcher.lastError,
+			output: watcher.lastOutput.slice(-2000), log_path: watcher.log.path, log_truncated: watcher.log.truncated,
+		}));
+	}
+
+	async deleteWatcher(id: string): Promise<void> {
+		const watcher = this.watchers.get(id);
+		if (!watcher) throw new Error(`Unknown watcher: ${id}`);
+		this.watchers.delete(id);
+		this.pending.delete(id);
+		clearTimeout(watcher.timer);
+		watcher.controller?.abort();
+		this.changed();
+		await watcher.done;
+	}
+
+	async dispose(): Promise<void> {
+		this.disposed = true;
+		this.detach();
+		this.pending.clear();
+		await Promise.all([
+			...[...this.processes.keys()].map(id => this.stopProcess(id)),
+			...[...this.watchers.keys()].map(id => this.deleteWatcher(id)),
+		]);
+	}
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@steveimm/pi-background",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Background commands and polling watchers that notify the Pi agent",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test test/*.test.mjs",
+    "test:live": "node test/live-gpt.mjs",
+    "test:terminal": "node test/terminal-smoke.mjs"
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/steveimm/pi-ext-collection.git",
+    "directory": "packages/pi-background"
+  },
+  "homepage": "https://github.com/steveimm/pi-ext-collection/tree/main/packages/pi-background#readme",
+  "bugs": {
+    "url": "https://github.com/steveimm/pi-ext-collection/issues"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.5.1",
+    "@earendil-works/pi-tui": "1.5.1",
+    "typebox": "1.3.27"
+  }
+}

package/status.ts

@@ -0,0 +1,143 @@
+import type { CustomEditor, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sliceByColumn, stripTerminalSequences, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import type { BackgroundManager } from "./manager.js";
+import { activeTasks, counts, showBackgroundTasks } from "./ui.js";
+
+function findFooter(components: Component[]): Component | undefined {
+	for (const component of components) {
+		if ("setAutoCompactEnabled" in component && typeof component.setAutoCompactEnabled === "function") return component;
+		if ("children" in component && Array.isArray(component.children)) {
+			const footer = findFooter(component.children);
+			if (footer) return footer;
+		}
+	}
+	return undefined;
+}
+
+function centerStatus(line: string, status: string, width: number): string {
+	const text = stripTerminalSequences(line);
+	const gap = / {2,}/.exec(text);
+	const leftWidth = gap ? visibleWidth(text.slice(0, gap.index)) : visibleWidth(text);
+	const rightStart = gap ? leftWidth + gap[0].length : width;
+	const statusWidth = visibleWidth(status);
+	const start = Math.max(0, Math.floor((width - statusWidth) / 2));
+	const end = start + statusWidth;
+	const left = truncateToWidth(sliceByColumn(line, 0, leftWidth), Math.max(0, start - 1));
+	const right = truncateToWidth(sliceByColumn(line, rightStart, width - rightStart), Math.max(0, width - end - 1));
+	return left + " ".repeat(Math.max(0, start - visibleWidth(left))) + status
+		+ " ".repeat(Math.max(0, width - end - visibleWidth(right))) + right;
+}
+
+export function attachBackgroundStatus(manager: BackgroundManager, ctx: ExtensionContext): () => void {
+	const previousFactory = ctx.ui.getEditorComponent();
+	let cleanup = () => {};
+	const factory: NonNullable<ReturnType<typeof ctx.ui.getEditorComponent>> = (tui, _theme, keys) => {
+		if (!("getFocusedComponent" in tui) || typeof tui.getFocusedComponent !== "function") {
+			throw new Error("Cannot access Pi's editor for background task navigation.");
+		}
+		const editor = tui.getFocusedComponent() as CustomEditor | null;
+		const footer = findFooter(tui.children);
+		if (!editor || typeof editor.getCursor !== "function" || typeof editor.isShowingAutocomplete !== "function" || !footer) {
+			throw new Error("Background task navigation requires Pi's standard editor and footer.");
+		}
+		let tasks = activeTasks(manager);
+		let footerDisposed = false;
+		let dialogOpen = false;
+		const originalInput = editor.handleInput;
+		const unsubscribe = manager.subscribe(() => {
+			tasks = activeTasks(manager);
+			if (!tasks.length && status.focused) tui.setFocus(input);
+			tui.requestRender();
+		});
+		// Render Pi's existing footer to preserve its token, model, and session information.
+		const status = {
+			focused: false,
+			render(width: number) {
+				const lines = footer.render(width);
+				if (tasks.length && lines[1] !== undefined) {
+					const text = ctx.ui.theme.fg("accent", truncateToWidth(counts(tasks), width));
+					lines[1] = centerStatus(lines[1], this.focused ? ctx.ui.theme.inverse(text) : text, width);
+				}
+				return lines;
+			},
+			handleInput(data: string) {
+				if (keys.matches(data, "tui.editor.cursorDown")) return;
+				tui.setFocus(input);
+				if (keys.matches(data, "tui.input.submit")) {
+					dialogOpen = true;
+					void showBackgroundTasks(manager, ctx).catch(error => {
+						ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+					}).finally(() => { dialogOpen = false; tui.requestRender(); });
+				} else if (!keys.matches(data, "tui.editor.cursorUp") && !keys.matches(data, "tui.select.cancel")) {
+					input.handleInput(data);
+				}
+				tui.requestRender();
+			},
+			invalidate() { footer.invalidate(); },
+			dispose() {
+				footerDisposed = true;
+				unsubscribe();
+				if (this.focused) tui.setFocus(input);
+			},
+		};
+		const handleInput = (data: string) => {
+			if (dialogOpen && !footerDisposed) return;
+			if (footerDisposed || !tasks.length || !keys.matches(data, "tui.editor.cursorDown") || editor.isShowingAutocomplete()) {
+				originalInput.call(editor, data);
+				return;
+			}
+			const before = editor.getCursor();
+			const text = editor.getText();
+			const onChange = editor.onChange;
+			let changed = false;
+			editor.onChange = value => { changed = true; onChange?.(value); };
+			try {
+				originalInput.call(editor, data);
+			} finally {
+				if (onChange) editor.onChange = onChange;
+				else delete editor.onChange;
+			}
+			const after = editor.getCursor();
+			if (!changed && text === editor.getText() && before.line === after.line && before.col === after.col) {
+				tui.setFocus(status);
+				tui.requestRender();
+			}
+		};
+		const input = {
+			get focused() { return editor.focused; },
+			set focused(value: boolean) { editor.focused = value; },
+			get capturesViewportInput() { return editor.capturesViewportInput; },
+			get borderColor() { return editor.borderColor; },
+			set borderColor(value: typeof editor.borderColor) { editor.borderColor = value; },
+			get embedWorkingStatus() { return editor.embedWorkingStatus; },
+			setWorkingStatusIndicator: editor.setWorkingStatusIndicator?.bind(editor),
+			render: editor.render.bind(editor), invalidate: editor.invalidate.bind(editor), handleInput,
+			handleMouse: editor.handleMouse.bind(editor),
+			getText: editor.getText.bind(editor), setText: editor.setText.bind(editor),
+			getExpandedText: editor.getExpandedText.bind(editor), addToHistory: editor.addToHistory.bind(editor),
+			insertTextAtCursor: editor.insertTextAtCursor.bind(editor),
+			setAutocompleteProvider: editor.setAutocompleteProvider.bind(editor),
+			setPaddingX: editor.setPaddingX.bind(editor), setAutocompleteMaxVisible: editor.setAutocompleteMaxVisible.bind(editor),
+		};
+		// Forward editor callbacks without triggering CustomEditor's app-handler rewiring.
+		for (const key of ["onSubmit", "onChange"] as const) {
+			Object.defineProperty(input, key, {
+				get: () => editor[key],
+				set: (value: (text: string) => void) => { editor[key] = value; },
+			});
+		}
+		ctx.ui.setFooter(() => status);
+		cleanup = () => {
+			unsubscribe();
+			if (!footerDisposed) ctx.ui.setFooter(undefined);
+		};
+		return input;
+	};
+	// /reload focuses a loading panel before session_start runs.
+	ctx.ui.setEditorComponent(previousFactory);
+	ctx.ui.setEditorComponent(factory);
+	return () => {
+		cleanup();
+		if (ctx.ui.getEditorComponent() === factory) ctx.ui.setEditorComponent(previousFactory);
+	};
+}

package/ui.ts

@@ -0,0 +1,93 @@
+import { getSelectListTheme, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, SelectList, Text } from "@earendil-works/pi-tui";
+import type { BackgroundManager } from "./manager.js";
+
+export function activeTasks(manager: BackgroundManager) {
+	return [
+		...manager.listProcesses().filter(job => job.status === "running").map(job => ({ ...job, kind: "process" as const })),
+		...manager.listWatchers().map(watcher => ({ ...watcher, kind: "watcher" as const })),
+	];
+}
+
+export function counts(tasks: ReturnType<typeof activeTasks>): string {
+	const processes = tasks.filter(task => task.kind === "process").length;
+	const watchers = tasks.length - processes;
+	return `${processes} background ${processes === 1 ? "process" : "processes"}, ${watchers} ${watchers === 1 ? "watcher" : "watchers"}`;
+}
+
+export async function showBackgroundTasks(manager: BackgroundManager, ctx: ExtensionContext): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify("/bg requires TUI mode.", "error");
+		return;
+	}
+	await ctx.ui.custom<void>((tui, theme, keys, done) => {
+		let tasks: ReturnType<typeof activeTasks> = [];
+		let list: SelectList;
+		let busy = false;
+		let disposed = false;
+		let message = "";
+		const title = new Text("", 1, 1);
+		const hint = new Text("", 1, 1);
+		const feedback = new Text("", 1, 0);
+
+		async function stop(id: string) {
+			const task = tasks.find(task => task.id === id);
+			if (!task || busy) return;
+			busy = true;
+			message = "Stopping...";
+			refresh();
+			try {
+				if (task.kind === "process") await manager.stopProcess(task.id);
+				else await manager.deleteWatcher(task.id);
+				message = task.kind === "process" ? "Process stopped." : "Watcher stopped.";
+			} catch (error) {
+				message = error instanceof Error ? error.message : String(error);
+			} finally {
+				busy = false;
+				if (!disposed) refresh();
+			}
+		}
+
+		function refresh() {
+			const selected = list?.getSelectedItem()?.value;
+			tasks = activeTasks(manager);
+			title.setText(theme.fg("accent", counts(tasks)));
+			list = new SelectList(tasks.map(task => {
+				const name = task.label || task.command || (task.kind === "watcher" ? task.instruction : "") || task.id;
+				const kind = task.kind === "process" ? "Process" : `Watcher (${task.mode})`;
+				return { value: task.id, label: `${kind}: ${name.replace(/\s+/g, " ")}` };
+			}), 8, getSelectListTheme());
+			list.setSelectedIndex(Math.max(0, tasks.findIndex(task => task.id === selected)));
+			const actions = tasks.length && !busy
+				? `${keys.getKeys("tui.select.up").join("/")}/${keys.getKeys("tui.select.down").join("/")} select | x kill selected task | `
+				: "";
+			hint.setText(theme.fg("dim", `${actions}esc close`));
+			feedback.setText(message);
+			tui.requestRender();
+		}
+
+		refresh();
+		const unsubscribe = manager.subscribe(refresh);
+		return {
+			capturesViewportInput: true,
+			render(width: number) {
+				return [
+					...title.render(width),
+					...(tasks.length ? list.render(width) : new Text("No active background tasks.", 1, 0).render(width)),
+					...hint.render(width),
+					...(message ? feedback.render(width) : []),
+				];
+			},
+			handleInput(data: string) {
+				if (matchesKey(data, "escape")) done();
+				else if (!busy && matchesKey(data, "x")) {
+					const selected = list.getSelectedItem();
+					if (selected) void stop(selected.value);
+				} else if (!busy) list.handleInput(data);
+				tui.requestRender();
+			},
+			invalidate() { title.invalidate(); list.invalidate(); hint.invalidate(); feedback.invalidate(); },
+			dispose() { disposed = true; unsubscribe(); },
+		};
+	});
+}