Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/activity/runtime.ts

Raw
import { type ChildProcess, spawn } from "node:child_process";
import { randomUUID } from "node:crypto";
import { type FSWatcher, watch } from "node:fs";
import { join, resolve } from "node:path";
import { StringDecoder } from "node:string_decoder";
import type {
	ActivityEvent,
	ActivitySnapshot,
	ActivityStart,
	ActivityStatus,
	ProcessStart,
	TerminalHandle,
	TerminalScreen,
} from "./types.ts";

const MAX_ACTIVE = 8;
const MAX_RETAINED = 32;
const MAX_INPUT_BYTES = 64 * 1024;
const MAX_OUTPUT_BYTES = 64 * 1024;
const MAX_READ_BYTES = 16 * 1024;
const MAX_EVENTS = 32;
const MAX_EVENT_TEXT = 256;
const DEFAULT_LIFETIME_MS = 60 * 60 * 1000;
const MAX_LIFETIME_MS = 24 * 60 * 60 * 1000;
const MAX_DELAY_MS = 24 * 60 * 60 * 1000;
const MIN_REPEAT_MS = 1000;
const COALESCE_MS = 100;

type Waiter = {
	after: number;
	resolve: (snapshot: ActivitySnapshot) => void;
	reject: (error: Error) => void;
	timer?: ReturnType<typeof setTimeout>;
	signal?: AbortSignal;
	abort?: () => void;
};

type Record = {
	id: string;
	spec: ActivityStart;
	title: string;
	createdAt: number;
	status: ActivityStatus;
	sequence: number;
	notify: boolean;
	pid?: number;
	exitCode?: number | null;
	error?: string;
	terminationWarning?: string;
	output: Buffer[];
	outputBytes: number;
	outputTruncated: boolean;
	events: ActivityEvent[];
	eventsTruncated: boolean;
	waiters: Set<Waiter>;
	child?: ChildProcess;
	killer?: ChildProcess;
	treeKillSucceeded?: boolean;
	terminal?: TerminalHandle;
	watcher?: FSWatcher;
	lifetime?: ReturnType<typeof setTimeout>;
	escalation?: ReturnType<typeof setTimeout>;
	tick?: ReturnType<typeof setTimeout>;
	coalesce?: ReturnType<typeof setTimeout>;
	pendingOutput: string;
	pendingChange: string;
	matchTail: string;
	matchSeen: boolean;
	acknowledged?: true;
	screen?: TerminalScreen;
};

function boundedText(value: string, bytes: number): string {
	const data = Buffer.from(value);
	if (data.byteLength <= bytes) return value;
	let end = bytes;
	while (end > 0 && (data[end] & 0xc0) === 0x80) end--;
	return data.subarray(0, end).toString("utf8");
}

function boundedTail(
	chunks: Buffer[],
	bytes: number,
): { text: string; truncated: boolean } {
	let used = 0;
	const kept: Buffer[] = [];
	for (let index = chunks.length - 1; index >= 0 && used < bytes; index -= 1) {
		const chunk = chunks[index];
		const room = bytes - used;
		if (chunk.byteLength <= room) {
			kept.unshift(chunk);
			used += chunk.byteLength;
		} else {
			let start = chunk.byteLength - room;
			while (start < chunk.byteLength && (chunk[start] & 0xc0) === 0x80)
				start += 1;
			const tail = chunk.subarray(start);
			kept.unshift(tail);
			used += tail.byteLength;
			break;
		}
	}
	return {
		text: Buffer.concat(kept, used).toString("utf8"),
		truncated: chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0) > used,
	};
}

function isTerminal(status: ActivityStatus): boolean {
	return status === "completed" || status === "failed" || status === "stopped";
}

function activityError(message: string): Error {
	return new Error(`Activity: ${message}`);
}

export class ActivityManager {
	readonly #records = new Map<string, Record>();
	readonly #listeners = new Set<() => void>();
	readonly #onEvent?: (id: string, event: ActivityEvent) => void;
	readonly #prefix = randomUUID().slice(0, 8);
	#nextId = 1;
	#disposed = false;
	readonly #openings = new Set<Promise<void>>();

	constructor(onEvent?: (id: string, event: ActivityEvent) => void) {
		this.#onEvent = onEvent;
	}

	async start(spec: ActivityStart, cwd: string): Promise<ActivitySnapshot> {
		if (this.#disposed) throw activityError("manager is disposed");
		this.#validate(spec);
		if (this.#activeCount() >= MAX_ACTIVE)
			throw activityError(`maximum ${MAX_ACTIVE} active activities`);
		const now = Date.now();
		const record: Record = {
			id: `activity-${this.#prefix}-${this.#nextId++}`,
			spec,
			title: boundedText(spec.title?.trim() || this.#defaultTitle(spec), 256),
			createdAt: now,
			status: "running",
			sequence: 0,
			notify: spec.notify === true,
			output: [],
			outputBytes: 0,
			outputTruncated: false,
			events: [],
			eventsTruncated: false,
			waiters: new Set(),
			pendingOutput: "",
			pendingChange: "",
			matchTail: "",
			matchSeen: false,
		};
		this.#records.set(record.id, record);
		this.#armLifetime(record);
		this.#publish(record);
		try {
			if (spec.kind === "process") this.#startProcess(record, spec, cwd);
			else if (spec.kind === "watch") this.#startWatch(record, spec, cwd);
			else if (spec.kind === "timer") this.#startTimer(record, spec);
			else {
				const opening = this.#startTerminal(record, spec, cwd);
				this.#openings.add(opening);
				try {
					await opening;
				} finally {
					this.#openings.delete(opening);
				}
			}
		} catch (error) {
			this.#finish(record, "failed", undefined, this.#message(error));
		}
		return this.#snapshot(record, false);
	}

	list(): ActivitySnapshot[] {
		return [...this.#records.values()].map((record) =>
			this.#snapshot(record, false),
		);
	}

	read(id: string): ActivitySnapshot {
		return this.#snapshot(this.#record(id), true);
	}

	/** Active work plus failures the human has not acknowledged. */
	attention(): ActivitySnapshot[] {
		return [...this.#records.values()]
			.filter(
				(record) =>
					!isTerminal(record.status) ||
					(record.status === "failed" && !record.acknowledged),
			)
			.map((record) => this.#snapshot(record, false));
	}

	/** Hide finished work from attention; active work and unknown IDs are ignored. */
	acknowledge(id: string): void {
		const record = this.#records.get(id);
		if (!record || !isTerminal(record.status) || record.acknowledged) return;
		record.acknowledged = true;
		this.#publish(record);
	}

	terminalView(id: string): import("./view.js").TerminalView | undefined {
		return this.#record(id).terminal?.view();
	}

	timerView(id: string): import("./types.js").TimerView | undefined {
		const record = this.#record(id);
		if (record.spec.kind !== "timer") return undefined;
		const lastTick = record.events.findLast((event) => event.type === "tick");
		return {
			delayMs: record.spec.delayMs,
			repeat: record.spec.repeat === true,
			nextAt: (lastTick?.time ?? record.createdAt) + record.spec.delayMs,
		};
	}

	write(id: string, text: string, paste = false, keyboard = false): void {
		const record = this.#record(id);
		if (record.status !== "running")
			throw activityError("activity is not running");
		if (Buffer.byteLength(text) > MAX_INPUT_BYTES)
			throw activityError("input exceeds 64 KiB");
		if (!record.terminal) throw activityError("activity does not accept input");
		if (paste) record.terminal.paste(text);
		else record.terminal.write(text, keyboard);
	}

	resize(id: string, cols: number, rows: number): void {
		const record = this.#record(id);
		if (
			!Number.isInteger(cols) ||
			!Number.isInteger(rows) ||
			cols < 20 ||
			rows < 5 ||
			cols > 200 ||
			rows > 60
		)
			throw activityError("invalid terminal dimensions");
		if (!record.terminal) throw activityError("activity is not a terminal");
		record.terminal.resize(cols, rows);
		record.screen = record.terminal.screen();
		this.#publish(record);
	}

	async stop(id: string): Promise<ActivitySnapshot> {
		const record = this.#record(id);
		if (isTerminal(record.status)) return this.#snapshot(record, true);
		if (record.status === "running") {
			record.status = "stopping";
			this.#event(record, "stop");
		}
		if (record.watcher) this.#finish(record, "stopped");
		else if (record.tick) this.#finish(record, "stopped");
		else if (record.spec.kind === "terminal" && !record.terminal)
			this.#finish(record, "stopped");
		else if (record.terminal) {
			try {
				if (!(await record.terminal.stop())) {
					record.error = "Termination requested but not confirmed.";
					this.#publish(record);
				}
			} catch (error) {
				record.error = boundedText(this.#message(error), 1024);
				this.#publish(record);
			}
		} else this.#terminateProcess(record);
		return this.#snapshot(record, true);
	}

	async wait(
		id: string,
		after: number,
		timeoutMs: number,
		signal?: AbortSignal,
	): Promise<ActivitySnapshot> {
		const record = this.#record(id);
		if (!Number.isSafeInteger(after) || after < 0)
			throw activityError("invalid sequence");
		if (
			!Number.isFinite(timeoutMs) ||
			timeoutMs < 0 ||
			timeoutMs > MAX_LIFETIME_MS
		)
			throw activityError("invalid wait timeout");
		if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
		if (record.sequence > after || isTerminal(record.status))
			return this.#snapshot(record, true);
		return new Promise<ActivitySnapshot>((resolve, reject) => {
			const waiter: Waiter = { after, resolve, reject, signal };
			waiter.timer = setTimeout(() => {
				this.#removeWaiter(record, waiter);
				resolve(this.#snapshot(record, true));
			}, timeoutMs);
			waiter.timer.unref?.();
			if (signal) {
				waiter.abort = () => {
					this.#removeWaiter(record, waiter);
					reject(new DOMException("Aborted", "AbortError"));
				};
				signal.addEventListener("abort", waiter.abort, { once: true });
			}
			record.waiters.add(waiter);
		});
	}

	subscribe(listener: () => void): () => void {
		if (this.#disposed) return () => {};
		this.#listeners.add(listener);
		return () => this.#listeners.delete(listener);
	}

	async dispose(): Promise<void> {
		if (this.#disposed) return;
		this.#disposed = true;
		this.#listeners.clear();
		const cleanup = [...this.#records.values()].map(async (record) => {
			if (!isTerminal(record.status)) record.status = "stopping";
			for (const waiter of record.waiters)
				this.#rejectWaiter(record, waiter, activityError("manager disposed"));
			this.#clearTimers(record);
			try {
				record.watcher?.close();
				if (record.terminal) await record.terminal.dispose();
				else if (record.child && !isTerminal(record.status)) {
					const child = record.child;
					const closed = new Promise<void>((resolve) =>
						child.once("close", () => resolve()),
					);
					this.#terminateProcess(record);
					const boundedCleanup = new Promise<void>((resolve) => {
						const timer = setTimeout(resolve, 1_500);
						timer.unref?.();
					});
					await Promise.race([closed, boundedCleanup]);
				}
			} catch {
				// Disposal is best-effort and must not create unhandled failures.
			}
		});
		await Promise.allSettled([...cleanup, ...this.#openings]);
	}

	#startProcess(record: Record, spec: ProcessStart, cwd: string): void {
		const child = spawn(spec.command, spec.args ?? [], {
			cwd: spec.cwd ? resolve(cwd, spec.cwd) : cwd,
			detached: process.platform !== "win32",
			shell: false,
			stdio: ["ignore", "pipe", "pipe"],
		});
		record.child = child;
		record.pid = child.pid;
		const stdout = new StringDecoder("utf8");
		const stderr = new StringDecoder("utf8");
		child.stdout.on("data", (chunk: Buffer) =>
			this.#output(record, stdout.write(chunk), "stdout"),
		);
		child.stderr.on("data", (chunk: Buffer) =>
			this.#output(record, stderr.write(chunk), "stderr"),
		);
		child.once("error", (error) =>
			this.#finish(record, "failed", undefined, this.#message(error)),
		);
		child.once("close", (code, signal) => {
			this.#output(record, stdout.end(), "stdout");
			this.#output(record, stderr.end(), "stderr");
			this.#flushOutput(record);
			if (!isTerminal(record.status))
				this.#finish(
					record,
					record.status === "stopping"
						? "stopped"
						: code === 0
							? "completed"
							: "failed",
					code,
					signal && record.status !== "stopping"
						? `Process exited from signal ${signal}.`
						: undefined,
				);
		});
		this.#publish(record);
	}

	async #startTerminal(
		record: Record,
		spec: ProcessStart,
		cwd: string,
	): Promise<void> {
		const { openTerminal } = await import("./terminal.ts");
		if (this.#disposed || record.status !== "running") return;
		const handle = await openTerminal(
			spec,
			spec.cwd ? resolve(cwd, spec.cwd) : cwd,
			{
				data: (text) => this.#output(record, text),
				changed: () => this.#publish(record),
				exit: (code, error) => {
					if (record.terminal) record.screen = record.terminal.screen();
					this.#refreshTerminalPid(record);
					this.#flushOutput(record);
					this.#finish(
						record,
						record.status === "stopping"
							? "stopped"
							: error
								? "failed"
								: code === 0
									? "completed"
									: "failed",
						code,
						error,
					);
				},
			},
		);
		if (this.#disposed || record.status !== "running") {
			record.screen = handle.screen();
			await handle.dispose();
			const pid = handle.pid;
			if (typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0)
				record.pid = pid;
			return;
		}
		record.terminal = handle;
		this.#refreshTerminalPid(record);
		record.screen = handle.screen();
		this.#publish(record);
	}

	#startWatch(
		record: Record,
		spec: Extract<ActivityStart, { kind: "watch" }>,
		cwd: string,
	): void {
		const path = resolve(cwd, spec.path);
		const watcher = watch(path, { recursive: false }, (eventType, filename) => {
			if (record.status !== "running") return;
			record.pendingChange = boundedText(
				`${eventType}${filename ? ` ${filename.toString()}` : ""}`,
				MAX_EVENT_TEXT,
			);
			this.#scheduleCoalesce(record);
		});
		record.watcher = watcher;
		watcher.once("error", (error) =>
			this.#finish(record, "failed", undefined, this.#message(error)),
		);
	}

	#startTimer(
		record: Record,
		spec: Extract<ActivityStart, { kind: "timer" }>,
	): void {
		const fire = (): void => {
			this.#event(record, "tick");
			if (!spec.repeat) this.#finish(record, "completed");
		};
		if (spec.repeat) {
			record.tick = setInterval(fire, spec.delayMs);
			record.tick.unref?.();
		} else {
			record.tick = setTimeout(fire, spec.delayMs);
			record.tick.unref?.();
		}
	}

	#output(record: Record, text: string, channel?: "stdout" | "stderr"): void {
		if (!text || isTerminal(record.status)) return;
		const spec = record.spec;
		if (
			(spec.kind === "process" || spec.kind === "terminal") &&
			spec.match &&
			!record.matchSeen
		) {
			const observed = record.matchTail + text;
			if (observed.includes(spec.match)) {
				record.matchSeen = true;
				record.matchTail = "";
				this.#event(record, "match", "Literal output condition matched.");
				if (spec.stopOnMatch) void this.stop(record.id);
			} else
				record.matchTail =
					spec.match.length > 1 ? observed.slice(1 - spec.match.length) : "";
		}
		const labelled = channel ? `[${channel}] ${text}` : text;
		let data = Buffer.from(labelled);
		if (data.byteLength > MAX_OUTPUT_BYTES) {
			let start = data.byteLength - MAX_OUTPUT_BYTES;
			while (start < data.byteLength && (data[start] & 0xc0) === 0x80)
				start += 1;
			data = data.subarray(start);
			record.output = [];
			record.outputBytes = 0;
			record.outputTruncated = true;
		}
		record.output.push(data);
		record.outputBytes += data.byteLength;
		if (record.output.length > 128) {
			const merged = Buffer.concat(record.output.splice(0, 64));
			record.output.unshift(merged);
		}
		while (record.outputBytes > MAX_OUTPUT_BYTES && record.output.length > 0) {
			const first = record.output[0];
			const excess = record.outputBytes - MAX_OUTPUT_BYTES;
			if (first.byteLength <= excess) {
				record.output.shift();
				record.outputBytes -= first.byteLength;
			} else {
				let cut = excess;
				while (cut < first.byteLength && (first[cut] & 0xc0) === 0x80) cut++;
				record.output[0] = first.subarray(cut);
				record.outputBytes -= cut;
			}
			record.outputTruncated = true;
		}
		record.pendingOutput = boundedText(
			record.pendingOutput + boundedText(labelled, MAX_EVENT_TEXT),
			MAX_EVENT_TEXT,
		);
		this.#scheduleCoalesce(record);
	}

	#scheduleCoalesce(record: Record): void {
		if (record.coalesce) return;
		record.coalesce = setTimeout(() => {
			record.coalesce = undefined;
			this.#flushOutput(record);
			if (record.pendingChange) {
				const text = record.pendingChange;
				record.pendingChange = "";
				this.#event(record, "change", text);
			}
		}, COALESCE_MS);
		record.coalesce.unref?.();
	}

	#flushOutput(record: Record): void {
		if (!record.pendingOutput) return;
		const text = record.pendingOutput;
		record.pendingOutput = "";
		this.#event(record, "output", text);
	}

	#terminateProcess(record: Record): void {
		const child = record.child;
		if (
			!child ||
			isTerminal(record.status) ||
			!child.pid ||
			record.escalation ||
			record.killer ||
			record.treeKillSucceeded
		)
			return;
		if (
			process.platform === "win32" &&
			(child.exitCode !== null || child.signalCode !== null)
		) {
			record.terminationWarning =
				"Process leader exited; descendant termination cannot be confirmed. Skipped taskkill to avoid targeting a reused PID.";
			record.error = record.terminationWarning;
			this.#publish(record);
			return;
		}
		let fallbackSent = false;
		const fallback = (): void => {
			if (fallbackSent) return;
			fallbackSent = true;
			if (process.platform === "win32") {
				record.terminationWarning =
					"taskkill could not confirm descendant termination; requested termination of process leader only.";
				record.error = record.terminationWarning;
				this.#publish(record);
			}
			try {
				child.kill();
			} catch {}
		};
		try {
			if (process.platform === "win32") {
				const killer = spawn(
					join(
						process.env["SystemRoot"] ?? "C:\\Windows",
						"System32",
						"taskkill.exe",
					),
					["/pid", String(child.pid), "/T", "/F"],
					{ stdio: "ignore", windowsHide: true, timeout: 1000 },
				);
				record.killer = killer;
				killer.once("error", fallback);
				killer.once("close", (code) => {
					record.killer = undefined;
					if (code !== 0) fallback();
					else {
						record.treeKillSucceeded = true;
						if (record.escalation) clearTimeout(record.escalation);
						record.escalation = undefined;
						if (record.error === record.terminationWarning)
							record.error = undefined;
						record.terminationWarning = undefined;
						this.#publish(record);
					}
				});
				killer.unref();
			} else {
				process.kill(-child.pid, "SIGTERM");
				record.terminationWarning = undefined;
			}
		} catch {
			fallback();
		}
		record.escalation = setTimeout(() => {
			record.escalation = undefined;
			if (isTerminal(record.status)) return;
			if (process.platform === "win32") {
				fallback();
				return;
			}
			try {
				if (process.platform !== "win32" && child.pid)
					process.kill(-child.pid, "SIGKILL");
				else child.kill("SIGKILL");
			} catch {}
		}, 1000);
		record.escalation.unref?.();
	}

	#finish(
		record: Record,
		status: ActivityStatus,
		code?: number | null,
		error?: string,
	): void {
		if (isTerminal(record.status)) return;
		record.status = status;
		record.exitCode = code;
		record.error = error ? boundedText(error, 1024) : record.terminationWarning;
		this.#clearTimers(record);
		try {
			record.watcher?.close();
		} catch {}
		this.#refreshTerminalPid(record);
		const handle = record.terminal;
		if (handle) {
			record.screen = handle.screen();
			record.terminal = undefined;
			void handle.dispose().catch(() => {});
		}
		const type = error ? "error" : "exit";
		this.#event(record, type, error);
		this.#trimRetained();
	}

	#event(record: Record, type: ActivityEvent["type"], text?: string): void {
		const event: ActivityEvent = {
			sequence: ++record.sequence,
			type,
			time: Date.now(),
			...(text ? { text: boundedText(text, MAX_EVENT_TEXT) } : {}),
		};
		if (record.events.length === MAX_EVENTS) {
			record.events.shift();
			record.eventsTruncated = true;
		}
		record.events.push(event);
		try {
			if (!this.#disposed) this.#onEvent?.(record.id, event);
		} catch {}
		this.#publish(record);
	}

	#publish(record: Record): void {
		for (const waiter of record.waiters)
			if (record.sequence > waiter.after || isTerminal(record.status))
				this.#resolveWaiter(record, waiter);
		for (const listener of this.#listeners)
			try {
				listener();
			} catch {}
	}

	#removeWaiter(record: Record, waiter: Waiter): void {
		record.waiters.delete(waiter);
		if (waiter.timer) clearTimeout(waiter.timer);
		if (waiter.signal && waiter.abort)
			waiter.signal.removeEventListener("abort", waiter.abort);
	}

	#resolveWaiter(record: Record, waiter: Waiter): void {
		this.#removeWaiter(record, waiter);
		waiter.resolve(this.#snapshot(record, true));
	}

	#rejectWaiter(record: Record, waiter: Waiter, error: Error): void {
		this.#removeWaiter(record, waiter);
		waiter.reject(error);
	}

	#snapshot(record: Record, includeDetails: boolean): ActivitySnapshot {
		this.#refreshTerminalPid(record);
		const snapshot: ActivitySnapshot = {
			id: record.id,
			kind: record.spec.kind,
			title: record.title,
			status: record.status,
			notify: record.notify,
			createdAt: record.createdAt,
			sequence: record.sequence,
			...(record.pid === undefined ? {} : { pid: record.pid }),
			...(record.exitCode === undefined ? {} : { exitCode: record.exitCode }),
			...(record.error ? { error: record.error } : {}),
		};
		if (!includeDetails) return snapshot;
		const output = boundedTail(record.output, MAX_READ_BYTES);
		const screen = record.terminal?.screen() ?? record.screen;
		return {
			...snapshot,
			output: output.text,
			outputTruncated: record.outputTruncated || output.truncated,
			...(screen ? { screen: { ...screen } } : {}),
			events: record.events.map((event) => ({ ...event })),
			eventsTruncated: record.eventsTruncated,
		};
	}

	#refreshTerminalPid(record: Record): void {
		const pid = record.terminal?.pid;
		if (typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0)
			record.pid = pid;
	}

	#record(id: string): Record {
		const record = this.#records.get(id);
		if (!record) throw activityError("unknown activity");
		return record;
	}

	#armLifetime(record: Record): void {
		const spec = record.spec;
		const timeout =
			spec.timeoutMs ??
			(spec.kind === "timer" && !spec.repeat ? undefined : DEFAULT_LIFETIME_MS);
		if (timeout === undefined) return;
		record.lifetime = setTimeout(() => {
			this.#event(record, "stop", "Activity lifetime expired.");
			void this.stop(record.id);
		}, timeout);
		record.lifetime.unref?.();
	}

	#clearTimers(record: Record): void {
		if (record.lifetime) clearTimeout(record.lifetime);
		if (record.escalation) clearTimeout(record.escalation);
		if (record.tick) {
			clearTimeout(record.tick);
			clearInterval(record.tick);
		}
		if (record.coalesce) clearTimeout(record.coalesce);
		record.lifetime = undefined;
		record.escalation = undefined;
		record.tick = undefined;
		record.coalesce = undefined;
	}

	#trimRetained(): void {
		const completed = [...this.#records.values()].filter((record) =>
			isTerminal(record.status),
		);
		while (completed.length > MAX_RETAINED) {
			const record = completed.shift();
			if (!record) break;
			this.#records.delete(record.id);
		}
	}

	#activeCount(): number {
		let count = 0;
		for (const record of this.#records.values())
			if (!isTerminal(record.status)) count += 1;
		return count;
	}

	#validate(spec: ActivityStart): void {
		if (
			spec.timeoutMs !== undefined &&
			(!Number.isFinite(spec.timeoutMs) ||
				spec.timeoutMs < 1 ||
				spec.timeoutMs > MAX_LIFETIME_MS)
		)
			throw activityError("timeout must be 1 ms through 24 h");
		if (spec.kind === "timer") {
			if (
				!Number.isFinite(spec.delayMs) ||
				spec.delayMs < 10 ||
				spec.delayMs > MAX_DELAY_MS
			)
				throw activityError("timer delay must be 10 ms through 24 h");
			if (spec.repeat && spec.delayMs < MIN_REPEAT_MS)
				throw activityError("repeating timer delay must be at least 1000 ms");
			return;
		}
		if (spec.kind === "watch") {
			if (
				!spec.path ||
				spec.recursive === true ||
				Buffer.byteLength(spec.path) > 4096
			)
				throw activityError("invalid watch path");
			return;
		}
		if (spec.match !== undefined && (!spec.match || spec.match.length > 256))
			throw activityError("output match must be 1–256 characters");
		if (spec.stopOnMatch && !spec.match)
			throw activityError("stopOnMatch requires an output match");
		if (
			!spec.command ||
			Buffer.byteLength(spec.command) > 4096 ||
			(spec.args?.length ?? 0) > 128 ||
			(spec.args ?? []).some((arg) => Buffer.byteLength(arg) > 4096) ||
			Buffer.byteLength((spec.args ?? []).join("\0")) > 16 * 1024
		)
			throw activityError("invalid command or arguments");
	}

	#defaultTitle(spec: ActivityStart): string {
		if (spec.kind === "timer") return spec.repeat ? "repeating timer" : "timer";
		if (spec.kind === "watch") return `watch ${spec.path}`;
		return [spec.command, ...(spec.args ?? [])].join(" ");
	}

	#message(error: unknown): string {
		return error instanceof Error ? error.message : String(error);
	}
}