@nredd/pi-session-kit 0.0.0-stage → 0.3.0

package/src/monitor/pidfiles.ts

@@ -0,0 +1,410 @@
+/**
+ * Orphan safety. Each monitor writes `<root>/<sessionId>/<id>.json`; a clean exit removes it. When pi
+ * is SIGKILLed the files stay behind, and the next session's sweep kills the recorded process group.
+ *
+ * Safety rules, in order of importance:
+ * - never touch a file whose `ownerPid` is alive (`kill(pid, 0)` succeeds or fails with EPERM)
+ * - authenticate the leader or a spawn-second group/session anchor before recording identities
+ * - persist those identities before TERM; await cleanup before removing the recovery file
+ * - escalation/recovery requires an exact surviving member identity, not a surviving leader
+ *   (ps start times have one-second resolution; the check-to-signal race cannot be atomic)
+ */
+
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import {
+	chmodSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmdirSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { KILL_GRACE_MS, signalGroup } from "./process.ts";
+
+const execFileAsync = promisify(execFile);
+
+/** Allowed drift between the recorded spawn time and `ps -o lstart=` (1s resolution plus slack). */
+export const START_TOLERANCE_MS = 5_000;
+/** Malformed files and empty dirs older than this are cleaned up; younger ones may be mid-write. */
+const STALE_AFTER_MS = 24 * 60 * 60 * 1000;
+
+export interface PidRecord {
+	ownerPid: number;
+	childPid: number;
+	pgid: number;
+	startedAt: number;
+	name: string;
+	command: string;
+	/** Authenticated before TERM, retained for recovery if the leader exits first. */
+	members?: GroupMember[];
+}
+
+export interface GroupMember extends ProcInfo {
+	pid: number;
+}
+
+export interface ProcInfo {
+	pgid: number;
+	/** Linux session ID; macOS ps reports an unusable zero, so it is omitted there. */
+	sessionId?: number;
+	startedAt: number;
+	command: string;
+}
+
+export interface SweepDeps {
+	isAlive(pid: number): boolean;
+	procInfo(pid: number): Promise<ProcInfo | undefined>;
+	groupMembers(pgid: number): Promise<GroupMember[] | undefined>;
+	killGroup(record: PidRecord, deps: SweepDeps): Promise<boolean>;
+	signal(pgid: number, signal: NodeJS.Signals): void;
+	now(): number;
+}
+
+export interface SweepResult {
+	killed: string[];
+	removed: string[];
+	skippedLive: string[];
+	/** Recovery could not be authenticated or a cleaner owns the record. Files are retained. */
+	failed: string[];
+}
+
+export function rootDir(uid = process.getuid?.() ?? 0, base = tmpdir()): string {
+	return join(base, `pi-monitors-${uid}`);
+}
+
+export function sessionDirName(sessionId: string, ownerPid = process.pid): string {
+	return `${sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "session"}.${ownerPid}`;
+}
+
+/** Atomic write (temp + rename) so a sweeper never reads a half-written file. */
+export function writePidfile(sessionDir: string, id: string, record: PidRecord): string {
+	mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+	const path = join(sessionDir, `${id}.json`);
+	const tmp = `${path}.${process.pid}.tmp`;
+	writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+	renameSync(tmp, path);
+	return path;
+}
+
+export function removePidfile(sessionDir: string, id: string): void {
+	try {
+		unlinkSync(join(sessionDir, `${id}.json`));
+	} catch {
+		// already gone
+	}
+}
+
+/** Remove the session directory when nothing is left in it. */
+export function removeSessionDirIfEmpty(sessionDir: string): void {
+	try {
+		rmdirSync(sessionDir);
+	} catch {
+		// not empty or already gone
+	}
+}
+
+export function isAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== "ESRCH";
+	}
+}
+
+/** Process group and start time of `pid`, from `ps`. Undefined when the process does not exist. */
+export async function psInfo(pid: number): Promise<ProcInfo | undefined> {
+	try {
+		const { stdout } = await execFileAsync("/bin/ps", ["-o", "pgid=,sess=,lstart=,command=", "-p", String(pid)], {
+			env: { ...process.env, LC_ALL: "C" },
+			timeout: 5_000,
+		});
+		const match = /^\s*(\d+)\s+(\d+)\s+(.{24})\s+(.+?)\s*$/.exec(stdout);
+		if (!match) return undefined;
+		const startedAt = Date.parse(match[3] as string);
+		if (!Number.isFinite(startedAt)) return undefined;
+		return { pgid: Number(match[1]), sessionId: Number(match[2]) || undefined, startedAt, command: match[4] as string };
+	} catch {
+		return undefined;
+	}
+}
+
+/** Snapshot a group without relying on its leader still existing. Failure is not an empty group. */
+export async function psGroup(pgid: number): Promise<GroupMember[] | undefined> {
+	try {
+		const { stdout } = await execFileAsync("/bin/ps", ["-axo", "pid=,pgid=,sess=,lstart=,command="], {
+			env: { ...process.env, LC_ALL: "C" },
+			timeout: 5_000,
+			maxBuffer: 4 * 1024 * 1024,
+		});
+		const members: GroupMember[] = [];
+		for (const line of stdout.split("\n")) {
+			const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.{24})\s+(.+?)\s*$/.exec(line);
+			if (!match || Number(match[2]) !== pgid) continue;
+			const startedAt = Date.parse(match[4] as string);
+			if (!Number.isFinite(startedAt)) return undefined;
+			members.push({
+				pid: Number(match[1]),
+				pgid,
+				sessionId: Number(match[3]) || undefined,
+				startedAt,
+				command: match[5] as string,
+			});
+		}
+		return members;
+	} catch {
+		return undefined;
+	}
+}
+
+async function sameMember(record: PidRecord, d: SweepDeps): Promise<boolean> {
+	for (const member of record.members ?? []) {
+		const current = await d.procInfo(member.pid);
+		if (
+			current?.pgid === record.pgid &&
+			current.sessionId === member.sessionId &&
+			current.startedAt === member.startedAt &&
+			current.command === member.command
+		)
+			return true;
+	}
+	return false;
+}
+
+const defaultDeps: SweepDeps = {
+	isAlive,
+	procInfo: psInfo,
+	groupMembers: psGroup,
+	signal: signalGroup,
+	async killGroup(record, d) {
+		if (!(await sameMember(record, d))) return false;
+		d.signal(record.pgid, "SIGTERM");
+		await new Promise<void>((resolve) => setTimeout(resolve, KILL_GRACE_MS));
+		if (await sameMember(record, d)) d.signal(record.pgid, "SIGKILL");
+		// Give the OS a bounded interval to reap the killed members. Keep the file on uncertainty.
+		for (let attempt = 0; attempt < 20; attempt++) {
+			const remaining = await d.groupMembers(record.pgid);
+			if (remaining?.length === 0) return true;
+			if (!remaining) return false;
+			await new Promise<void>((resolve) => setTimeout(resolve, 50));
+		}
+		return false;
+	},
+	now: Date.now,
+};
+
+function parseRecord(text: string): PidRecord | undefined {
+	try {
+		const r = JSON.parse(text) as Partial<PidRecord>;
+		const ints = [r.ownerPid, r.childPid, r.pgid, r.startedAt];
+		if (!ints.every((v) => typeof v === "number" && Number.isInteger(v) && v > 0)) return undefined;
+		if (typeof r.command !== "string" || typeof r.name !== "string") return undefined;
+		if (
+			r.members !== undefined &&
+			(!Array.isArray(r.members) ||
+				!r.members.every(
+					(m) =>
+						Number.isInteger(m.pid) &&
+						m.pid > 0 &&
+						m.pgid === r.pgid &&
+						Number.isFinite(m.startedAt) &&
+						typeof m.command === "string",
+				))
+		)
+			return undefined;
+		return r as PidRecord;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Sweep every session directory under `root` whose recorded owner is dead. */
+export async function sweepOrphans(
+	root: string,
+	_ownSession: string,
+	deps: Partial<SweepDeps> = {},
+): Promise<SweepResult> {
+	const d: SweepDeps = { ...defaultDeps, ...deps };
+	const result: SweepResult = { killed: [], removed: [], skippedLive: [], failed: [] };
+	let sessions: string[];
+	try {
+		sessions = readdirSync(root);
+	} catch {
+		return result;
+	}
+	for (const session of sessions) {
+		const dir = join(root, session);
+		let files: string[];
+		try {
+			files = readdirSync(dir);
+		} catch {
+			continue;
+		}
+		let removedAny = false;
+		for (const file of files) {
+			if (!file.endsWith(".json")) continue;
+			const path = join(dir, file);
+			const release = acquireSweepGuard(path);
+			if (!release) {
+				result.failed.push(path);
+				continue;
+			}
+			try {
+				let text: string;
+				try {
+					text = readFileSync(path, "utf8");
+				} catch {
+					continue;
+				}
+				const record = parseRecord(text);
+				if (!record) {
+					if (isStale(path, d.now())) removedAny = unlinkQuiet(path, result) || removedAny;
+					continue;
+				}
+				if (d.isAlive(record.ownerPid)) {
+					result.skippedLive.push(path);
+					continue;
+				}
+				if (await looksLikeSame(record, d)) {
+					const members = await d.groupMembers(record.pgid);
+					if (!members || !(await looksLikeSame(record, d))) {
+						result.failed.push(path);
+						continue;
+					}
+					record.members = members;
+					// Atomic persistence MUST succeed before any signal; a killed sweeper can resume cleanup.
+					writePidfile(dir, file.slice(0, -5), record);
+				} else if (!(await sameMember(record, d))) {
+					const members = await d.groupMembers(record.pgid);
+					if (members?.length === 0) {
+						removedAny = unlinkQuiet(path, result) || removedAny;
+						continue;
+					}
+					// A member already present at spawn anchors this group to the recorded lifetime.
+					// Later-born survivors alone cannot distinguish a reused, now leaderless group.
+					const anchor = members?.find(
+						(m) =>
+							m.pgid === record.childPid &&
+							(m.sessionId === undefined || m.sessionId === record.childPid) &&
+							m.startedAt <= record.startedAt &&
+							record.startedAt - m.startedAt < 1_000,
+					);
+					if (
+						record.members?.length ||
+						!anchor ||
+						record.pgid !== record.childPid ||
+						d.isAlive(record.childPid) ||
+						members?.some((m) => m.pid === record.childPid) ||
+						(await d.procInfo(record.childPid))
+					) {
+						result.failed.push(path);
+						continue;
+					}
+					record.members = members;
+					writePidfile(dir, file.slice(0, -5), record);
+				}
+				if (!(await d.killGroup(record, d))) {
+					result.failed.push(path);
+					continue;
+				}
+				result.killed.push(path);
+				removedAny = unlinkQuiet(path, result) || removedAny;
+			} finally {
+				release();
+			}
+		}
+		if (removedAny || isStale(dir, d.now())) removeSessionDirIfEmpty(dir);
+	}
+	return result;
+}
+
+/** A live or unknown guard is never broken, regardless of age. Reread records only inside it. */
+function acquireSweepGuard(path: string): (() => void) | undefined {
+	const guard = `${path}.sweep`;
+	const token = randomUUID();
+	const ownerPath = join(guard, `${process.pid}.${token}`);
+	const read = (): { pid: number; token: string } | undefined => {
+		try {
+			const files = readdirSync(guard);
+			if (files.length !== 1) return undefined;
+			const match = /^(\d+)\.([a-f0-9-]+)$/.exec(files[0] ?? "");
+			return match && Number(match[1]) > 0 ? { pid: Number(match[1]), token: match[2] as string } : undefined;
+		} catch {
+			return undefined;
+		}
+	};
+	try {
+		mkdirSync(guard, { mode: 0o700 });
+	} catch {
+		const owner = read();
+		if (owner && !isAlive(owner.pid) && read()?.token === owner.token) {
+			try {
+				unlinkSync(join(guard, `${owner.pid}.${owner.token}`));
+				rmdirSync(guard);
+			} catch {
+				return undefined;
+			}
+			return acquireSweepGuard(path);
+		}
+		return undefined;
+	}
+	try {
+		writeFileSync(ownerPath, "", { mode: 0o600, flag: "wx" });
+	} catch {
+		return undefined;
+	}
+	return () => {
+		try {
+			unlinkSync(ownerPath);
+			rmdirSync(guard);
+		} catch {
+			// Never recursively remove a replacement owner's guard.
+		}
+	};
+}
+
+async function looksLikeSame(record: PidRecord, d: SweepDeps): Promise<boolean> {
+	if (record.pgid !== record.childPid) return false;
+	const info = await d.procInfo(record.childPid);
+	if (!info || info.pgid !== record.pgid || (info.sessionId !== undefined && info.sessionId !== record.childPid))
+		return false;
+	if (Math.abs(info.startedAt - record.startedAt) > START_TOLERANCE_MS) return false;
+	return (
+		info.command === record.command || info.command.endsWith(record.command) || record.command.endsWith(info.command)
+	);
+}
+
+function unlinkQuiet(path: string, result: SweepResult): boolean {
+	try {
+		unlinkSync(path);
+		result.removed.push(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function isStale(path: string, now: number): boolean {
+	try {
+		return now - statSync(path).mtimeMs > STALE_AFTER_MS;
+	} catch {
+		return false;
+	}
+}
+
+/** Create the root directory with owner-only permissions. */
+export function ensureRoot(root: string): void {
+	mkdirSync(root, { recursive: true, mode: 0o700 });
+	try {
+		chmodSync(root, 0o700);
+	} catch {
+		// not ours to chmod
+	}
+}

package/src/monitor/process.ts

@@ -0,0 +1,124 @@
+/**
+ * No-shell monitor process: argv spawn, stdin ignored, own process group (`detached`), SIGTERM then
+ * SIGKILL after a grace period, then a hard resolve so a grandchild holding the pipes open cannot
+ * hang the caller. Same conventions as `pi-dev-tools` (`src/core/process.ts`), re-implemented here
+ * because packages do not import each other. macOS and Linux only.
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+
+export const KILL_GRACE_MS = 2_000;
+/** After SIGKILL, how long to wait for the pipes to close before resolving anyway. */
+const CLOSE_GRACE_MS = 1_000;
+/** After the leader exits, how long to wait for its pipes to drain before moving on. */
+const DRAIN_GRACE_MS = 250;
+
+export interface ExitInfo {
+	exitCode: number | null;
+	signal: NodeJS.Signals | null;
+}
+
+export interface MonitorProcess {
+	pid: number;
+	startedAt: number;
+	/** Resolves once the leader exited and its output drained (or the grace ran out). Never rejects. */
+	exited: Promise<ExitInfo>;
+	/** SIGTERM the group, SIGKILL after `graceMs`. Idempotent. */
+	terminate(graceMs?: number): void;
+	/** SIGKILL the group right now, synchronously. Safe from a `process.on("exit")` handler. */
+	killNow(): void;
+}
+
+export interface SpawnOptions {
+	cwd: string;
+	onStdout: (chunk: Buffer) => void;
+	onStderr: (chunk: Buffer) => void;
+}
+
+/**
+ * Signal a whole process group. `detached` makes the child a group leader (pgid == pid), so there is
+ * deliberately no fallback to signalling the bare pid: once the leader is reaped that pid may belong
+ * to an unrelated process.
+ */
+export function signalGroup(pgid: number, sig: NodeJS.Signals): void {
+	try {
+		process.kill(-pgid, sig);
+	} catch {
+		// group already gone
+	}
+}
+
+/** Spawn `argv`. Rejects with the spawn error (e.g. ENOENT) when the process never started. */
+export function spawnMonitor(argv: readonly string[], opts: SpawnOptions): Promise<MonitorProcess> {
+	const [cmd, ...args] = argv;
+	if (cmd === undefined || cmd.trim() === "") return Promise.reject(new Error("argv[0] must be non-empty"));
+	return new Promise((resolve, reject) => {
+		const child: ChildProcess = spawn(cmd, args, {
+			cwd: opts.cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			detached: true,
+		});
+		child.once("error", (error) => reject(error));
+		child.once("spawn", () => {
+			child.removeAllListeners("error");
+			child.on("error", () => {
+				// post-spawn errors (kill failures) are non-fatal; `exit`/`close` still fire
+			});
+			resolve(wrap(child, opts));
+		});
+	});
+}
+
+function wrap(child: ChildProcess, opts: SpawnOptions): MonitorProcess {
+	const pid = child.pid as number;
+	const startedAt = Date.now();
+	let settled = false;
+	let termTimer: NodeJS.Timeout | undefined;
+	let hardTimer: NodeJS.Timeout | undefined;
+	let drainTimer: NodeJS.Timeout | undefined;
+	let exit: ExitInfo | undefined;
+	let finish: (info: ExitInfo) => void = () => {};
+	const exited = new Promise<ExitInfo>((resolve) => {
+		finish = resolve;
+	});
+
+	child.stdout?.on("data", opts.onStdout);
+	child.stderr?.on("data", opts.onStderr);
+
+	const settle = () => {
+		if (settled) return;
+		settled = true;
+		for (const t of [termTimer, hardTimer, drainTimer]) if (t) clearTimeout(t);
+		child.stdout?.destroy();
+		child.stderr?.destroy();
+		// The leader is gone; sweep any grandchildren it left in the group.
+		signalGroup(pid, "SIGKILL");
+		finish(exit ?? { exitCode: child.exitCode, signal: child.signalCode });
+	};
+
+	child.once("exit", (exitCode, signal) => {
+		exit = { exitCode, signal };
+		drainTimer = setTimeout(settle, DRAIN_GRACE_MS);
+		drainTimer.unref();
+	});
+	child.once("close", settle);
+
+	return {
+		pid,
+		startedAt,
+		exited,
+		terminate(graceMs = KILL_GRACE_MS) {
+			if (settled || termTimer) return;
+			signalGroup(pid, "SIGTERM");
+			termTimer = setTimeout(() => {
+				signalGroup(pid, "SIGKILL");
+				hardTimer = setTimeout(settle, CLOSE_GRACE_MS);
+				hardTimer.unref();
+			}, graceMs);
+			termTimer.unref();
+		},
+		killNow() {
+			signalGroup(pid, "SIGKILL");
+		},
+	};
+}

package/src/monitor/ring.ts

@@ -0,0 +1,52 @@
+/** Bounded line buffer with monotonically increasing line numbers, so `since` cursors survive eviction. */
+
+export const RING_CAPACITY = 2000;
+
+export interface NumberedLine {
+	/** 1-based, never reused, keeps counting after old lines are evicted. */
+	n: number;
+	text: string;
+}
+
+export interface RingRead {
+	lines: NumberedLine[];
+	/** Lines after `since` that were already evicted and so cannot be returned. */
+	missed: number;
+}
+
+export class RingBuffer {
+	private readonly slots: (string | undefined)[];
+	private total = 0;
+
+	constructor(readonly capacity = RING_CAPACITY) {
+		if (!Number.isInteger(capacity) || capacity < 1) throw new RangeError("capacity must be a positive integer");
+		this.slots = new Array<string | undefined>(capacity);
+	}
+
+	/** Append one line and return it with its number. */
+	push(text: string): NumberedLine {
+		this.total += 1;
+		this.slots[(this.total - 1) % this.capacity] = text;
+		return { n: this.total, text };
+	}
+
+	/** Number of the newest line, 0 when nothing was ever pushed. */
+	get lastLine(): number {
+		return this.total;
+	}
+
+	/** Number of the oldest retained line, `lastLine + 1` when empty. */
+	get firstLine(): number {
+		return Math.max(1, this.total - this.capacity + 1);
+	}
+
+	/** Lines numbered greater than `since` (default: everything retained). */
+	read(since = 0): RingRead {
+		const after = Math.max(0, Math.floor(Number.isFinite(since) ? since : 0));
+		const first = Math.max(this.firstLine, after + 1);
+		const lines: NumberedLine[] = [];
+		for (let n = first; n <= this.total; n++) lines.push({ n, text: this.slots[(n - 1) % this.capacity] ?? "" });
+		const missed = Math.max(0, this.firstLine - (after + 1));
+		return { lines, missed };
+	}
+}

package/src/monitor/splitter.ts

@@ -0,0 +1,57 @@
+/** Chunk -> complete lines, UTF-8 safe, with a per-line length cap so one endless line cannot eat memory. */
+
+import { StringDecoder } from "node:string_decoder";
+
+export const MAX_LINE_CHARS = 4096;
+const TRUNCATED = " ...[line truncated]";
+
+export class LineSplitter {
+	private readonly decoder = new StringDecoder("utf8");
+	private pending = "";
+	/** The current line already overflowed and was emitted; drop the rest of it. */
+	private skipping = false;
+
+	constructor(private readonly maxChars = MAX_LINE_CHARS) {}
+
+	push(chunk: Buffer): string[] {
+		return this.feed(this.decoder.write(chunk));
+	}
+
+	/** Emit the unterminated last line, if any. */
+	flush(): string[] {
+		const out = this.feed(this.decoder.end());
+		if (!this.skipping && this.pending) out.push(this.pending);
+		this.pending = "";
+		this.skipping = false;
+		return out;
+	}
+
+	private feed(text: string): string[] {
+		const out: string[] = [];
+		let start = 0;
+		while (start < text.length) {
+			const nl = text.indexOf("\n", start);
+			const end = nl < 0 ? text.length : nl;
+			if (this.skipping) {
+				if (nl >= 0) this.skipping = false;
+			} else {
+				this.pending += text.slice(start, end);
+				if (nl >= 0) {
+					out.push(this.finish(this.pending));
+					this.pending = "";
+				} else if (this.pending.length > this.maxChars) {
+					out.push(this.pending.slice(0, this.maxChars) + TRUNCATED);
+					this.pending = "";
+					this.skipping = true;
+				}
+			}
+			start = end + 1;
+		}
+		return out;
+	}
+
+	private finish(line: string): string {
+		const bare = line.endsWith("\r") ? line.slice(0, -1) : line;
+		return bare.length > this.maxChars ? bare.slice(0, this.maxChars) + TRUNCATED : bare;
+	}
+}

package/src/monitor/types.ts

@@ -0,0 +1,35 @@
+/** Shapes shared by the monitor manager, message formatter, tools and widget. */
+
+export type MonitorStatus = "running" | "exited" | "stopped" | "timeout";
+
+export interface MonitorMessageDetails {
+	id: string;
+	name: string;
+	firstLine: number;
+	lastLine: number;
+	matched: number[];
+	status: MonitorStatus;
+}
+
+export interface MonitorMessage {
+	text: string;
+	details: MonitorMessageDetails;
+	/** Trigger an agent turn (match, exit, timeout, or `wake: true`); otherwise passive context. */
+	wake: boolean;
+}
+
+export interface MonitorInfo {
+	id: string;
+	name: string;
+	argv: string[];
+	pid: number;
+	status: MonitorStatus;
+	startedAt: number;
+	endedAt?: number;
+	exitCode: number | null;
+	signal: NodeJS.Signals | null;
+	lines: number;
+	wake: boolean;
+	match?: string;
+	timeoutMs: number;
+}