@maxiaochao/pi-toolkit 0.12.2 → 0.13.0

package/packages/background-tasks/tests/helpers.mjs

@@ -0,0 +1,55 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BackgroundTasks } from "../src/background-tasks.ts";
+
+export class FakeClock {
+	time = 1000;
+	next = 0;
+	timers = new Map();
+	now = () => this.time;
+	setTimeout = (callback, delay) => {
+		const id = ++this.next;
+		this.timers.set(id, { at: this.time + delay, callback });
+		return id;
+	};
+	clearTimeout = (id) => this.timers.delete(id);
+	advance(ms) {
+		const target = this.time + ms;
+		for (;;) {
+			const due = [...this.timers].filter(([, t]) => t.at <= target).sort((a, b) => a[1].at - b[1].at)[0];
+			if (!due) break;
+			this.time = due[1].at;
+			this.timers.delete(due[0]);
+			due[1].callback();
+		}
+		this.time = target;
+	}
+}
+
+export function fixture(options = {}) {
+	const root = mkdtempSync(join(tmpdir(), "pi-bg-test-"));
+	const clock = new FakeClock();
+	const calls = [];
+	const completed = [];
+	const operations = {
+		exec(command, cwd, opts) {
+			return new Promise((resolve, reject) => {
+				calls.push({ command, cwd, ...opts, resolve: (exitCode = 0) => resolve({ exitCode }), reject });
+			});
+		},
+	};
+	const tasks = new BackgroundTasks({ operations, clock, logRoot: root, onComplete: (task) => completed.push(task), ...options });
+	return {
+		root, clock, calls, completed, tasks, operations,
+		async close() {
+			for (const call of calls) call.resolve();
+			await tasks.shutdown();
+			rmSync(root, { recursive: true, force: true });
+		},
+	};
+}
+
+export async function flush() {
+	for (let i = 0; i < 8; i++) await Promise.resolve();
+}

package/packages/background-tasks/tests/load.mjs

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { piBinary } from "./runtime.mjs";
+
+const directory = mkdtempSync(join(tmpdir(), "pi-bg-load-"));
+const pkg = fileURLToPath(new URL("..", import.meta.url));
+const toolkit = process.argv.includes("--toolkit");
+const source = toolkit ? resolve(pkg, "../..") : resolve(pkg, "extensions/background-tasks.ts");
+try {
+	writeFileSync(join(directory, "settings.json"), JSON.stringify({ quietStartup: true, defaultTools: ["+codemode"] }));
+	const output = execFileSync(piBinary, [
+		"--no-extensions", "--no-skills", "--no-prompt-templates", "--no-themes", "--no-context-files",
+		"--no-session", "--offline", "-e", source,
+		"-e", resolve(pkg, "tests/fixtures/provider.ts"), "--model", "bg-fixture/deterministic", "-p", "ping",
+	], { cwd: directory, encoding: "utf8", timeout: 30000, env: { ...process.env, PI_CODING_AGENT_DIR: directory, PI_OFFLINE: "1", BG_SMOKE_EVENTS: join(directory, "events.jsonl") }, stdio: ["ignore", "pipe", "pipe"] });
+	assert.match(output, /Main agent is ready/);
+	assert.doesNotMatch(output, /Failed to load|Error loading/);
+	const events = readFileSync(join(directory, "events.jsonl"), "utf8").trim().split("\n").map((line) => JSON.parse(line));
+	const loaded = events.find((entry) => entry.event === "loaded");
+	assert.equal(loaded.tools.filter((name) => name === "background_task").length, 1, "the real host registered exactly one background-task tool");
+	const request = events.find((entry) => entry.event === "request");
+	assert.equal(request.tools.filter((name) => name === "background_task").length, 1, "background_task is active in the model request without manual activation");
+	console.log(`Real Pi loaded ${toolkit ? "the toolkit default loadout" : "the standalone background-task extension"} with exactly one background-task tool and an offline fixture provider.`);
+} finally { rmSync(directory, { recursive: true, force: true }); }

package/packages/background-tasks/tests/output.mjs

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createBashTool } from "@earendil-works/pi-coding-agent";
+import { fixture, flush } from "./helpers.mjs";
+
+const cases = [
+	["empty", Buffer.alloc(0)],
+	["small", Buffer.from("first\nsecond\n")],
+	["no-newline", Buffer.from("last")],
+	["line-limit", Buffer.from(Array.from({ length: 2500 }, (_, i) => `line ${i}`).join("\n"))],
+	["byte-limit", Buffer.from(("x".repeat(200) + "\n").repeat(500))],
+	["long-last-line", Buffer.from("before\n" + "z".repeat(300000))],
+	["long-line-with-newline", Buffer.from("z".repeat(150000) + "\n")],
+	["huge-utf8", Buffer.from("中文🙂\n".repeat(160000))],
+	["utf8-long-line", Buffer.from("中文🙂".repeat(130000))],
+	["invalid-utf8", Buffer.from([65, 0xf0, 0x9f])],
+];
+for (const [name, data] of cases) {
+	test(`output matches native bash model/structured views: ${name}`, async () => {
+		const f = fixture();
+		try {
+			const path = join(f.root, "fixture.log");
+			writeFileSync(path, data);
+			const native = await createBashTool(f.root).execute("reference", { command: `cat '${path}'` });
+			const job = f.tasks.start({ command: "fixture" }, f.root);
+			// Deliberately split multi-byte UTF-8 across chunks.
+			for (let offset = 0; offset < data.length; offset += 8191) f.calls[0].onData(data.subarray(offset, offset + 8191));
+			f.calls[0].resolve();
+			await flush();
+			const actual = f.tasks.output(job.id);
+			const normalize = (text) => text.replace(/Full output: [^\]]+/g, "Full output: <log>");
+			assert.equal(normalize(actual.text), normalize(native.content[0].text));
+			assert.equal(actual.output, native.structuredContent.output);
+			assert.equal(actual.truncated, native.structuredContent.truncated);
+			assert.equal(actual.capture_complete, true);
+			assert.ok(Buffer.byteLength(actual.truncation.content) <= 51200);
+			assert.ok(Buffer.byteLength(actual.output) < 1024 * 1024 + 100);
+		} finally { await f.close(); }
+	});
+}
+
+test("running output is a consistent snapshot and does not flush incomplete UTF-8", async () => {
+	const f = fixture();
+	try {
+		const job = f.tasks.start({ command: "stream" }, f.root);
+		const bytes = Buffer.from("中文");
+		f.calls[0].onData(bytes.subarray(0, 2));
+		assert.equal(f.tasks.output(job.id).output, "");
+		f.calls[0].onData(bytes.subarray(2));
+		assert.equal(f.tasks.output(job.id).output, "中文");
+		assert.equal(f.tasks.output(job.id).capture_complete, false);
+	} finally { await f.close(); }
+});

package/packages/background-tasks/tests/processes.mjs

@@ -0,0 +1,96 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
+import { BackgroundTasks } from "../src/background-tasks.ts";
+
+async function waitFor(check) {
+	const deadline = Date.now() + 5000;
+	while (!check()) {
+		if (Date.now() > deadline) throw new Error("Real process did not reach expected state within 5 seconds");
+		await delay(20);
+	}
+}
+function alive(pid) {
+	try {
+		process.kill(pid, 0);
+		// A reaped parent can temporarily leave a zombie child owned by PID 1.
+		if (existsSync(`/proc/${pid}/stat`) && readFileSync(`/proc/${pid}/stat`, "utf8").split(") ")[1].startsWith("Z ")) return false;
+		return true;
+	} catch (error) { if (error.code === "ESRCH") return false; throw error; }
+}
+
+test("native backend starts immediately and executes heredoc/PID/exit-file checks", async () => {
+	const root = mkdtempSync(join(tmpdir(), "pi-bg-process-"));
+	const completed = [];
+	const tasks = new BackgroundTasks({ operations: createLocalBashOperations(), onComplete: (task) => completed.push(task) });
+	try {
+		writeFileSync(join(root, "build.log"), "> Task :compile\nnoise\nBUILD SUCCESSFUL\n");
+		writeFileSync(join(root, "build.exit"), "0\n");
+		const task = tasks.start({ command: `sleep 1; python3 - <<'PY'
+from pathlib import Path
+p=Path('build.log')
+lines=p.read_text(errors='replace').splitlines()
+s=[x for x in lines if x.startswith('> Task') or 'BUILD SUCCESS' in x]
+print('\\n'.join(s[-35:])); print('log bytes:',p.stat().st_size)
+PY
+ps -p $$ -o pid,etime; test ! -f build.exit || cat build.exit` }, root);
+		assert.equal(task.status, "running");
+		const other = tasks.start({ command: "printf concurrent" }, root);
+		await waitFor(() => tasks.get(other.id).status !== "running");
+		assert.equal(tasks.get(task.id).status, "running", "other work completed before the sleeping job");
+		await waitFor(() => tasks.get(task.id).status !== "running");
+		assert.equal(tasks.get(task.id).status, "succeeded");
+		assert.match(tasks.output(task.id).output, /> Task :compile\nBUILD SUCCESSFUL\nlog bytes:/);
+		assert.equal(completed.length, 2);
+	} finally { await tasks.shutdown(); rmSync(root, { recursive: true, force: true }); }
+});
+
+for (const stop of ["timeout", "cancel", "shutdown"]) {
+	test(`native ${stop} stops silent shell and its waiting child`, async () => {
+		const root = mkdtempSync(join(tmpdir(), "pi-bg-tree-"));
+		const tasks = new BackgroundTasks({ operations: createLocalBashOperations() });
+		let pids = [];
+		try {
+			const task = tasks.start({
+				command: `echo $$ > shell.pid; sleep 300 & echo $! > child.pid; wait`,
+				timeout: stop === "timeout" ? 1 : 30,
+			}, root);
+			await waitFor(() => existsSync(join(root, "child.pid")));
+			pids = ["shell.pid", "child.pid"].map((file) => Number(readFileSync(join(root, file), "utf8").trim()));
+			if (stop === "shutdown") await tasks.shutdown();
+			else if (stop === "cancel") await tasks.cancel(task.id);
+			else await waitFor(() => tasks.get(task.id).status !== "running");
+			await waitFor(() => pids.every((pid) => !alive(pid)));
+			assert.equal(tasks.get(task.id).status, stop === "timeout" ? "timed_out" : "cancelled");
+		} finally { await tasks.shutdown(); rmSync(root, { recursive: true, force: true }); }
+	});
+}
+
+test("silent busy loop times out without any agent polling or output", async () => {
+	const tasks = new BackgroundTasks({ operations: createLocalBashOperations() });
+	try {
+		const job = tasks.start({ command: "while :; do :; done", timeout: 1 }, process.cwd());
+		await waitFor(() => tasks.get(job.id).status !== "running");
+		assert.equal(tasks.get(job.id).status, "timed_out");
+		assert.equal(tasks.output(job.id).output, "");
+	} finally { await tasks.shutdown(); }
+});
+
+test("native large output truncates display, then stops at the 32 MiB disk budget", async () => {
+	const tasks = new BackgroundTasks({ operations: createLocalBashOperations() });
+	try {
+		const job = tasks.start({ command: "python3 -c \"import sys; sys.stdout.buffer.write(b'x' * (40 * 1024 * 1024))\"" }, process.cwd());
+		await waitFor(() => tasks.get(job.id).status !== "running");
+		const result = tasks.output(job.id);
+		assert.equal(result.status, "output_limit");
+		assert.equal(result.bytes, 32 * 1024 * 1024);
+		assert.equal(result.capture_complete, false);
+		assert.equal(result.truncated, true);
+		assert.ok(result.truncation.outputBytes <= 51200);
+		assert.ok(Buffer.byteLength(result.output) < 1024 * 1024 + 100);
+	} finally { await tasks.shutdown(); }
+});

package/packages/background-tasks/tests/runtime.mjs

@@ -0,0 +1,30 @@
+// Resolve host peers from the selected installed Pi; never install a second runtime.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { delimiter, dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// npm prepends workspace .bin paths, which may contain an older development Pi.
+const hostPath = (process.env.PATH ?? "").split(delimiter).filter((entry) => !entry.endsWith("node_modules/.bin")).join(delimiter);
+const binary = process.env.PI_TEST_BINARY || execFileSync("sh", ["-c", "command -v pi"], { encoding: "utf8", env: { ...process.env, PATH: hostPath } }).trim();
+let root = dirname(realpathSync(binary));
+while (!existsSync(join(root, "package.json")) || JSON.parse(readFileSync(join(root, "package.json"), "utf8")).name !== "@earendil-works/pi-coding-agent") {
+	const parent = dirname(root);
+	if (parent === root) throw new Error(`Cannot locate Pi runtime next to ${binary}`);
+	root = parent;
+}
+const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+const [major, minor] = version.split(".").map(Number);
+if (major < 1 || (major === 1 && minor < 3)) throw new Error(`Background Tasks checks require Pi >=1.3.0; selected ${version} at ${binary}. Set PI_TEST_BINARY to a supported host.`);
+export const piBinary = binary;
+export const piEntry = join(root, "dist/index.js");
+const hostURL = pathToFileURL(piEntry).href;
+const peers = new Set(["@earendil-works/pi-coding-agent", "@earendil-works/pi-ai", "@earendil-works/pi-tui", "typebox"]);
+registerHooks({
+	resolve(specifier, context, nextResolve) {
+		return peers.has(specifier)
+			? nextResolve(specifier, { ...context, parentURL: hostURL })
+			: nextResolve(specifier, context);
+	},
+});

package/packages/background-tasks/tests/tasks.mjs

@@ -0,0 +1,201 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { existsSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { BackgroundTasks } from "../src/background-tasks.ts";
+import { fixture, flush } from "./helpers.mjs";
+
+test("start returns while execution is pending; two tasks own independent slots", async () => {
+	const f = fixture();
+	try {
+		const first = f.tasks.start({ command: "sleep 60; printf done" }, f.root);
+		const second = f.tasks.start({ command: "other", timeout: 60 }, f.root);
+		assert.equal(first.status, "running");
+		assert.equal(first.timeout, 1800);
+		assert.notEqual(first.id, second.id);
+		assert.equal(f.calls.length, 2);
+		assert.throws(() => f.tasks.start({ command: "third" }, f.root), /two|2.*running/i);
+		f.calls[0].onData(Buffer.from("hello\n"));
+		assert.equal(f.tasks.output(first.id).output, "hello\n");
+		f.calls[0].resolve();
+		await flush();
+		assert.equal(f.tasks.get(first.id).status, "succeeded");
+		assert.equal(f.completed.length, 1);
+		assert.equal(f.tasks.list().running, 1);
+		assert.equal(f.tasks.get(first.id).capture_complete, true);
+		assert.equal(readFileSync(first.log_path, "utf8"), "hello\n");
+	} finally { await f.close(); }
+});
+
+test("timeout records its cause, aborts without a model, and retains the slot until cleanup", async () => {
+	const f = fixture();
+	try {
+		const a = f.tasks.start({ command: "loop", timeout: 1 }, f.root);
+		f.tasks.start({ command: "second" }, f.root);
+		f.clock.advance(1000);
+		assert.equal(f.calls[0].signal.aborted, true);
+		assert.equal(f.tasks.get(a.id).status, "running");
+		assert.throws(() => f.tasks.start({ command: "third" }, f.root), /two|2.*running/i);
+		const cancel = f.tasks.cancel(a.id);
+		f.calls[0].reject(new Error("aborted"));
+		await cancel;
+		assert.equal(f.tasks.get(a.id).status, "timed_out");
+		assert.equal(f.completed.length, 1);
+		await f.tasks.cancel(a.id);
+		assert.equal(f.completed.length, 1);
+	} finally { await f.close(); }
+});
+
+test("invalid inputs have no execution or log side effects", async () => {
+	const f = fixture();
+	try {
+		for (const timeout of [0, -1, 1.5, 7201, Infinity, NaN, "30"]) {
+			assert.throws(() => f.tasks.start({ command: "x", timeout }, f.root), /timeout/i);
+		}
+		assert.throws(() => f.tasks.start({ command: " " }, f.root), /command/i);
+		assert.throws(() => f.tasks.start({ command: "x", cwd: "missing" }, f.root), /directory/i);
+		assert.throws(() => f.tasks.get("not-mine"), /unknown/i);
+		assert.equal(f.calls.length, 0);
+		assert.equal(f.tasks.list().total, 0);
+	} finally { await f.close(); }
+});
+
+test("shutdown is idempotent, suppresses notifications and removes only owned logs", async () => {
+	const f = fixture();
+	const task = f.tasks.start({ command: "pending" }, f.root);
+	const shutdown = f.tasks.shutdown();
+	assert.equal(f.calls[0].signal.aborted, true);
+	f.calls[0].resolve();
+	await shutdown;
+	assert.equal(f.completed.length, 0);
+	assert.equal(f.clock.timers.size, 0);
+	assert.equal(existsSync(task.log_path), false);
+	assert.equal(existsSync(f.root), true);
+	assert.throws(() => f.tasks.start({ command: "x" }, f.root), /closed/i);
+	await f.close();
+});
+
+for (const mode of ["task", "session"]) {
+	test(`${mode} byte budget stops only the overflowing task and marks captured output incomplete`, async () => {
+		const f = fixture({ limits: { taskBytes: mode === "task" ? 4 : 100, sessionBytes: mode === "session" ? 4 : 100 } });
+		try {
+			const job = f.tasks.start({ command: "large" }, f.root);
+			f.calls[0].onData(Buffer.from("1234567"));
+			assert.equal(f.calls[0].signal.aborted, true);
+			f.calls[0].reject(new Error("aborted"));
+			await flush();
+			const result = f.tasks.output(job.id);
+			assert.equal(result.status, "output_limit");
+			assert.equal(result.output, "1234");
+			assert.equal(result.bytes, 4);
+			assert.equal(result.capture_complete, false);
+			assert.equal(f.completed.length, 1);
+			if (mode === "session") assert.throws(() => f.tasks.start({ command: "more" }, f.root), /budget/i);
+			else assert.equal(f.tasks.start({ command: "more" }, f.root).status, "running");
+		} finally { await f.close(); }
+	});
+}
+
+test("log write failure aborts the job and reports bounded failure without escaping onData", async () => {
+	const f = fixture({ logWrite() { throw new Error("disk full " + "x".repeat(10000)); } });
+	try {
+		const job = f.tasks.start({ command: "write" }, f.root);
+		assert.doesNotThrow(() => f.calls[0].onData(Buffer.from("hello")));
+		assert.equal(f.calls[0].signal.aborted, true);
+		f.calls[0].reject(new Error("aborted"));
+		await flush();
+		assert.equal(f.tasks.get(job.id).status, "failed");
+		assert.match(f.tasks.get(job.id).reason, /disk full/);
+		assert.ok(f.tasks.get(job.id).reason.length <= 500);
+		assert.equal(f.tasks.get(job.id).capture_complete, false);
+	} finally { await f.close(); }
+});
+
+test("nonzero exit, null exit and spawn errors are final failures; first stop reason wins", async () => {
+	const f = fixture();
+	try {
+		for (const outcome of [12, null, "spawn failed"]) {
+			const task = f.tasks.start({ command: "failure" }, f.root);
+			const call = f.calls.at(-1);
+			if (typeof outcome === "string") call.reject(new Error(outcome));
+			else call.resolve(outcome);
+			await flush();
+			assert.equal(f.tasks.get(task.id).status, "failed");
+		}
+		const job = f.tasks.start({ command: "cancel race", timeout: 1 }, f.root);
+		const cancelled = f.tasks.cancel(job.id);
+		f.clock.advance(1000);
+		f.calls.at(-1).resolve(0);
+		assert.equal((await cancelled).status, "cancelled");
+		assert.equal(f.completed.length, 4);
+	} finally { await f.close(); }
+});
+
+test("history is bounded in list, but older task outputs remain addressable; previews are safe", async () => {
+	const f = fixture();
+	try {
+		let first;
+		for (let i = 0; i < 25; i++) {
+			const job = f.tasks.start({ command: "x".repeat(10000), description: "\u001b]0;bad\u0007hello\n" + "中".repeat(300), timeout: 7200 }, f.root);
+			first ??= job;
+			assert.ok(Array.from(job.description).length <= 200);
+			assert.ok(!/[\x00-\x1f]/.test(job.description));
+			f.calls.at(-1).resolve();
+			await flush();
+		}
+		assert.equal(f.tasks.list().tasks.length, 20);
+		assert.equal(f.tasks.list().total, 25);
+		assert.equal(f.tasks.list().omitted, 5);
+		assert.equal(f.tasks.output(first.id).status, "succeeded");
+	} finally { await f.close(); }
+});
+
+test("explicit null timeout is not an unlimited/default timeout", async () => {
+	const f = fixture();
+	try { assert.throws(() => f.tasks.start({ command: "x", timeout: null }, f.root), /timeout/i); }
+	finally { await f.close(); }
+});
+
+test("a log failure while cancellation drains output preserves the stop cause and reports lost capture", async () => {
+	const f = fixture({ logWrite() { throw new Error("disk full while draining"); } });
+	try {
+		const job = f.tasks.start({ command: "write" }, f.root);
+		const cancel = f.tasks.cancel(job.id);
+		f.calls[0].onData(Buffer.from("buffered output"));
+		f.calls[0].reject(new Error("aborted"));
+		const result = await cancel;
+		assert.equal(result.status, "cancelled");
+		assert.equal(result.capture_complete, false);
+		assert.match(result.reason, /disk full while draining/);
+	} finally { await f.close(); }
+});
+
+test("short OS writes preserve all UTF-8 output in owner-only logs", async () => {
+	const f = fixture({ logWrite: (fd, data) => writeSync(fd, data.subarray(0, 2)) });
+	try {
+		const job = f.tasks.start({ command: "unicode" }, f.root);
+		f.calls[0].onData(Buffer.from("中文🙂\n"));
+		f.calls[0].resolve();
+		await flush();
+		assert.equal(f.tasks.output(job.id).output, "中文🙂\n");
+		assert.equal(statSync(job.log_path).mode & 0o777, 0o600);
+		assert.equal(statSync(dirname(job.log_path)).mode & 0o777, 0o700);
+	} finally { await f.close(); }
+});
+
+test("log creation failure rejects before execution; missing active logs abort visibly", async () => {
+	const f = fixture();
+	const invalid = new BackgroundTasks({ operations: f.operations, logRoot: join(f.root, "missing") });
+	try {
+		assert.throws(() => invalid.start({ command: "x" }, f.root), /ENOENT/);
+		assert.equal(f.calls.length, 0);
+		const job = f.tasks.start({ command: "pending" }, f.root);
+		unlinkSync(job.log_path);
+		assert.throws(() => f.tasks.output(job.id), /Cannot read/);
+		assert.equal(f.calls[0].signal.aborted, true);
+		f.calls[0].reject(new Error("aborted"));
+		await flush();
+		assert.equal(f.tasks.get(job.id).status, "failed");
+		assert.equal(f.tasks.get(job.id).capture_complete, false);
+	} finally { await invalid.shutdown(); await f.close(); }
+});

package/packages/background-tasks/tests/tui-smoke.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Exercise a real Pi TUI through a PTY and an offline fixture provider.
+
+BG_SMOKE_RENDER=1 relays the actual ANSI stream into an isolated terminal window.
+BG_SMOKE_CAPTURE=1 captures only that named window (requires X11 + ImageMagick).
+"""
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import traceback
+import termios
+import tty
+
+import pexpect
+
+PKG = Path(__file__).resolve().parents[1]
+ROOT = PKG.parents[1]
+OUT = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else ROOT / '.cache/verification/background-tui'
+OUT.mkdir(parents=True, exist_ok=True)
+work = Path(tempfile.mkdtemp(prefix='pi-bg-tui-'))
+events_path = work / 'events.jsonl'
+render = os.environ.get('BG_SMOKE_RENDER') == '1'
+capture = os.environ.get('BG_SMOKE_CAPTURE') == '1'
+env = dict(os.environ, PI_CODING_AGENT_DIR=str(work), PI_OFFLINE='1', BG_SMOKE_EVENTS=str(events_path), TERM='xterm-256color', COLORTERM='truecolor')
+env.pop('PI_HERDR_SUBAGENTS_CHILD', None)
+(work / 'settings.json').write_text(json.dumps({'quietStartup': True}))
+args = ['--no-extensions', '--no-skills', '--no-prompt-templates', '--no-themes', '--no-context-files', '--no-session', '--offline',
+        '-e', 'builtin:codemode', '-e', str(PKG / 'extensions/background-tasks.ts'),
+        '-e', str(ROOT / 'packages/scheduler/extensions/scheduler.ts'), '-e', str(PKG / 'tests/fixtures/provider.ts'),
+        '--tools', 'codemode,background_task,schedule', '--model', 'bg-fixture/deterministic', '--tui-mode', 'fullscreen']
+size = os.get_terminal_size(sys.stdout.fileno()) if render else os.terminal_size((140, 42))
+terminal_settings = termios.tcgetattr(sys.stdin.fileno()) if render else None
+if render:
+    tty.setraw(sys.stdin.fileno())
+child = pexpect.spawn(os.environ.get('PI_TEST_BINARY', shutil.which('pi')), args, cwd=str(work), env=env,
+                      encoding='utf-8', codec_errors='replace', dimensions=(size.lines, size.columns), timeout=20)
+child.linesep = '\r'
+raw = ''
+raw_file = (OUT / 'terminal.ansi').open('w')
+screens = []
+
+
+def pump(seconds=0.1):
+    global raw
+    deadline = time.monotonic() + seconds
+    while time.monotonic() < deadline:
+        try:
+            data = child.read_nonblocking(65536, timeout=min(0.05, max(0.001, deadline - time.monotonic())))
+            raw += data
+            raw_file.write(data)
+            raw_file.flush()
+            if render:
+                sys.stdout.write(data)
+                sys.stdout.flush()
+        except pexpect.TIMEOUT:
+            pass
+        except pexpect.EOF:
+            break
+
+
+def events():
+    if not events_path.exists():
+        return []
+    return [json.loads(line) for line in events_path.read_text().splitlines() if line]
+
+
+def wait(check, label, timeout=20):
+    deadline = time.monotonic() + timeout
+    while not check():
+        pump()
+        if not child.isalive():
+            raise AssertionError('Pi exited before ' + label)
+        if time.monotonic() > deadline:
+            raise AssertionError('Timeout waiting for ' + label + '\n' + raw[-4000:])
+    pump(0.15)
+
+
+def send(text):
+    child.sendline(text)
+    pump(0.1)
+
+
+def tools(name='background_task'):
+    return [e for e in events() if e.get('event') == 'tool_end' and e.get('name') == name]
+
+
+def finished(status):
+    return [e for e in events() if e.get('event') == 'custom' and e.get('type') == 'background-task-finished'
+            and e.get('details', {}).get('task', {}).get('status') == status]
+
+
+def shot(name):
+    pump(0.2)
+    if capture:
+        info = subprocess.check_output(['xwininfo', '-name', 'π - ' + work.name], text=True)
+        window = next(line.split()[3] for line in info.splitlines() if 'Window id:' in line)
+        path = OUT / (name + '.png')
+        subprocess.run(['import', '-window', window, str(path)], check=True)
+        screens.append(str(path))
+
+
+def alive(pid):
+    try:
+        os.kill(pid, 0)
+        stat = Path(f'/proc/{pid}/stat')
+        return not (stat.exists() and stat.read_text().split(') ', 1)[1].startswith('Z '))
+    except ProcessLookupError:
+        return False
+
+
+def start_long():
+    before = len(tools())
+    send('SMOKE_LONG')
+    wait(lambda: len(tools()) > before and (work / 'child.pid').exists(), 'lifecycle task')
+    return [int((work / file).read_text()) for file in ['shell.pid', 'child.pid']]
+
+
+try:
+    wait(lambda: any(e.get('event') == 'loaded' for e in events()), 'extension startup')
+    loaded = next(e for e in events() if e.get('event') == 'loaded')
+    assert loaded['tools'].count('background_task') == 1
+    send('/schedule add 1h Check release status')
+    wait(lambda: 'active schedule' in raw, 'Scheduler widget')
+    send('SMOKE_START')
+    wait(lambda: len(tools()) >= 3 and any(e.get('name') == 'codemode' for e in tools('codemode')), 'Codemode startup batch')
+    starts = tools()[:3]
+    assert not starts[0]['isError'] and not starts[1]['isError'] and starts[2]['isError'], starts
+    first = starts[0]['result']['structuredContent']['task']
+    second = starts[1]['result']['structuredContent']['task']
+    assert first['status'] == second['status'] == 'running'
+    assert any('Script completed' in str(e.get('result')) for e in tools('codemode')), tools('codemode')
+    assert not finished('succeeded'), 'Sleeping job must survive Codemode completion'
+    shot('running')
+    send('/bg output ' + first['id'])
+    send('SMOKE_CANCEL')
+    wait(lambda: bool(finished('cancelled')), 'cancel follow-up')
+    wait(lambda: bool(finished('succeeded')), 'successful background follow-up')
+    shot('completed')
+    send('SMOKE_OUTPUT')
+    wait(lambda: any(e.get('result', {}).get('structuredContent', {}).get('output') == 'BUILD SUCCESSFUL\n' for e in tools()), 'explicit output query')
+    wait(lambda: 'BACKGROUND_FOLLOWUP_RECEIVED' in raw, 'main agent automatic response')
+    pump(5.3)
+    shot('history')
+
+    pids = start_long()
+    loaded_count = len([e for e in events() if e.get('event') == 'loaded'])
+    send('/reload')
+    wait(lambda: len([e for e in events() if e.get('event') == 'loaded']) > loaded_count, 'reload')
+    wait(lambda: all(not alive(pid) for pid in pids), 'reload process cleanup')
+    (work / 'child.pid').unlink(missing_ok=True)
+    pids = start_long()
+    send('/new')
+    wait(lambda: all(not alive(pid) for pid in pids), 'new-session process cleanup')
+    (work / 'child.pid').unlink(missing_ok=True)
+    pids = start_long()
+    child.sendcontrol('d')
+    pump(0.15)
+    if child.isalive():
+        child.sendcontrol('d')
+    deadline = time.monotonic() + 10
+    while child.isalive() and time.monotonic() < deadline:
+        pump()
+    assert not child.isalive(), 'Pi did not exit cleanly'
+    assert all(not alive(pid) for pid in pids), 'Quit leaked a shell or child process'
+    records = events()
+    logs = [e['result']['structuredContent']['task']['log_path'] for e in tools()
+            if e.get('result', {}).get('structuredContent', {}).get('task')]
+    assert all(not Path(path).exists() for path in logs), 'Session logs were not removed'
+    (OUT / 'events.jsonl').write_text('\n'.join(json.dumps(e) for e in records) + '\n')
+    (OUT / 'result.json').write_text(json.dumps({'passed': True, 'screenshots': screens,
+        'checks': ['two jobs', 'third rejected', 'Codemode returns while jobs live', 'Scheduler coexistence', '/bg output',
+                   'cancel notification', 'success notification', 'main agent follow-up', '5-second terminal row', 'reload cleanup', 'new-session cleanup', 'quit cleanup']}, indent=2))
+except Exception:
+    (OUT / 'error.txt').write_text(traceback.format_exc())
+    raise
+finally:
+    if child.isalive():
+        child.sendcontrol('d')
+        pump(0.1)
+        if child.isalive():
+            child.sendcontrol('d')
+            pump(0.5)
+        if child.isalive():
+            child.terminate(force=True)
+    raw_file.close()
+    if terminal_settings is not None:
+        termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, terminal_settings)
+    if events_path.exists() and not (OUT / 'events.jsonl').exists():
+        shutil.copyfile(events_path, OUT / 'events.jsonl')
+    shutil.rmtree(work)