@garygentry/feature-forge 0.3.5 → 0.3.6

package/adapters/pi/extensions/forge-loop-supervisor/index.ts

@@ -0,0 +1,114 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-loop-supervisor/index.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * forge-loop-supervisor — a first-party Pi extension that lets forge-5-loop run
+ * the rauf autonomous coding loop WITHOUT blocking the Pi session, and supervises
+ * its native event stream.
+ *
+ * Pi has no built-in background bash, persistent monitor, or push-notification
+ * surface, so the generic Claude-first forge-5-loop contract (background the
+ * process, arm a `Monitor` on events.ndjson, `PushNotification` on exceptions)
+ * cannot be followed literally on Pi. This extension provides the real mechanism:
+ * `forge_loop_launch` starts the runner detached (it runs in rauf's server and
+ * outlives the session), then a rotation-aware NDJSON watcher turns each
+ * `item_completed` into a quiet progress line and wakes the session — via
+ * `pi.sendMessage(..., { triggerTurn: true })` — only on needs-human / blocked /
+ * stuck / review-failed / error / completion. `forge_loop_status` and
+ * `forge_loop_stop` round out the launch/attach/status/stop surface. Task
+ * identity is persisted (session entry + a file mirror beside the runner state)
+ * so a restarted session reattaches without duplicate reporting, and shutdown
+ * tears down watchers only — never the runner.
+ *
+ * The pi-facing glue is thin: all logic lives in the injectable {@link
+ * createExtension} factory (see wiring.ts), so the extension is unit-tested with
+ * a fake pi and fake deps. This file supplies the production dependencies.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawn } from "node:child_process";
+import { watch as fsWatch } from "node:fs";
+import { basename, dirname } from "node:path";
+
+import { createExtension, type Deps, type PiLike, type WatchHandle } from "./wiring.js";
+
+/** How often the backstop poll fires (ms). fs.watch can miss events or drop on
+ *  some platforms; a low-frequency interval guarantees the tail keeps up without
+ *  busy-waiting. */
+const BACKSTOP_MS = 2000;
+/** Debounce window (ms) coalescing a burst of fs.watch events into one poll. */
+const DEBOUNCE_MS = 120;
+
+const productionDeps: Deps = {
+	spawnDetached(bin, args, cwd, onError) {
+		// detached + unref + ignored stdio: the child is fully decoupled from the
+		// Pi process and survives session shutdown. rauf hands the loop to its
+		// server and this launcher exits quickly; a non-self-detaching runner still
+		// stays off the session.
+		const child = spawn(bin, args, { cwd, detached: true, stdio: "ignore" });
+		// ENOENT (bad bin) and other spawn failures arrive here asynchronously —
+		// report them so a launch that never happened does not look successful.
+		child.on("error", (err) => onError?.(err instanceof Error ? err.message : String(err)));
+		child.unref();
+	},
+	watch(filePath, onChange): WatchHandle {
+		const dir = dirname(filePath);
+		const base = basename(filePath);
+		let debounce: NodeJS.Timeout | null = null;
+		const fire = () => {
+			if (debounce) return;
+			debounce = setTimeout(() => {
+				debounce = null;
+				onChange();
+			}, DEBOUNCE_MS);
+		};
+		let fsw: ReturnType<typeof fsWatch> | null = null;
+		try {
+			// Watch the DIRECTORY (not the file) so rotation-by-rename — rauf moves
+			// events.ndjson into archive/ and recreates it each run — keeps firing.
+			fsw = fsWatch(dir, (_evt, name) => {
+				if (!name || name === base) fire();
+			});
+			fsw.on?.("error", () => {
+				/* directory vanished; the backstop interval keeps polling */
+			});
+		} catch {
+			fsw = null;
+		}
+		const interval = setInterval(onChange, BACKSTOP_MS);
+		return {
+			close() {
+				try {
+					fsw?.close();
+				} catch {
+					/* ignore */
+				}
+				if (debounce) clearTimeout(debounce);
+				clearInterval(interval);
+			},
+		};
+	},
+	now: () => new Date().toISOString(),
+};
+
+export default function (pi: ExtensionAPI) {
+	// Adapt the real ExtensionAPI to the structural PiLike the wiring consumes.
+	// Each member is accessed by name off the concrete `pi`, so a method renamed
+	// or removed in a future pi is a COMPILE error here (not a silent runtime
+	// failure hidden behind a blanket cast) — while PiLike stays loose enough for
+	// the fake pi in tests. Argument casts bridge PiLike's minimal shapes to pi's
+	// stricter generic signatures; the pi-API contract this was built against
+	// pins the exact shapes.
+	const piLike: PiLike = {
+		registerTool: (def) => (pi.registerTool as (d: unknown) => void)(def),
+		on: (event, handler) =>
+			(pi.on as unknown as (e: string, h: (ev: unknown, ctx: unknown) => void | Promise<void>) => void)(event, handler),
+		sendMessage: (message, options) =>
+			pi.sendMessage(message as Parameters<typeof pi.sendMessage>[0], options),
+		appendEntry: (customType, data) => pi.appendEntry(customType, data),
+		exec:
+			typeof pi.exec === "function"
+				? (command, args, opts) => pi.exec(command, args, opts)
+				: undefined,
+	};
+	createExtension(piLike, productionDeps);
+}

package/adapters/pi/extensions/forge-loop-supervisor/registry.ts

@@ -0,0 +1,137 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-loop-supervisor/registry.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * Durable task registry — a small JSON mirror of the supervised task, written
+ * beside the runner's own state so a brand-new Pi session (or a full pi restart,
+ * where the session file itself differs) can rediscover a loop it did not launch.
+ *
+ * Why a file and not only `pi.appendEntry`: appendEntry records survive session
+ * reload/branch within pi, but a cold restart may open a different session file.
+ * The mirror lives at `<stateDir>/.forge-supervisor.json`, next to rauf's own
+ * `state.json` / `events.ndjson`, so it is discoverable from the backlog dir
+ * alone. rauf's detached loop is server-managed (no single child pid to signal),
+ * so liveness is judged from the event stream and `rauf status --json`, never a
+ * tracked pid — the mirror deliberately stores no pid.
+ */
+
+import {
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { SupervisorTask } from "./types.js";
+
+/** The mirror filename, discoverable by scanning (see {@link discoverMirrors}). */
+export const MIRROR_NAME = ".forge-supervisor.json";
+
+/** Directory names never worth descending into during a mirror scan. */
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "archive", ".pi", ".claude"]);
+/** How deep the scan descends from the project root — mirrors live at
+ *  `<backlogDir>/.rauf/.forge-supervisor.json`, so a shallow bound reaches the
+ *  common `specs/<feature>/.rauf/` layout without walking the whole tree. */
+const SCAN_MAX_DEPTH = 5;
+
+/** Path of the registry mirror for a runner state directory. */
+export function mirrorPath(stateDir: string): string {
+	return join(stateDir, MIRROR_NAME);
+}
+
+/** Read the mirrored task for a state dir, or null if absent/unreadable/corrupt.
+ *  A corrupt mirror is treated as "no task" rather than throwing — a half-written
+ *  file must never wedge session startup. */
+export function readMirror(stateDir: string): SupervisorTask | null {
+	const path = mirrorPath(stateDir);
+	if (!existsSync(path)) return null;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<SupervisorTask>;
+		if (
+			parsed &&
+			typeof parsed.stateDir === "string" &&
+			typeof parsed.eventsFile === "string" &&
+			typeof parsed.backlogDir === "string"
+		) {
+			return {
+				backlogDir: parsed.backlogDir,
+				stateDir: parsed.stateDir,
+				eventsFile: parsed.eventsFile,
+				launchedAt: typeof parsed.launchedAt === "string" ? parsed.launchedAt : "",
+				total: typeof parsed.total === "number" ? parsed.total : undefined,
+				eventsIno: typeof parsed.eventsIno === "number" ? parsed.eventsIno : undefined,
+				lastSeq: typeof parsed.lastSeq === "number" ? parsed.lastSeq : -1,
+				closed: parsed.closed === true,
+			};
+		}
+	} catch {
+		// fall through — corrupt mirror is "no task"
+	}
+	return null;
+}
+
+/** Persist the task mirror atomically (write-temp + rename), creating the state
+ *  dir if the launcher raced ahead of the runner. */
+export function writeMirror(task: SupervisorTask): void {
+	const path = mirrorPath(task.stateDir);
+	try {
+		// Stamp the CURRENT events-file inode so a later session can tell whether the
+		// file was rotated (a new run) while it was away — see SupervisorTask.eventsIno.
+		let eventsIno = task.eventsIno;
+		try {
+			eventsIno = statSync(task.eventsFile).ino;
+		} catch {
+			// events file not present yet — keep whatever the task carried (if any)
+		}
+		const record: SupervisorTask = { ...task, eventsIno };
+		mkdirSync(dirname(path), { recursive: true });
+		const tmp = `${path}.tmp-${process.pid}`;
+		writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+		renameSync(tmp, path);
+	} catch {
+		// Best-effort durability; a failed mirror write must not break the tool.
+	}
+}
+
+/** Remove the mirror (on an explicit stop of a task the session owns). */
+export function clearMirror(stateDir: string): void {
+	try {
+		rmSync(mirrorPath(stateDir), { force: true });
+	} catch {
+		// best-effort
+	}
+}
+
+/**
+ * Find every supervised-task mirror under `root`, so a BRAND-NEW Pi session (a
+ * fresh session file with no `forge-loop-task` entry of its own) can still
+ * rediscover and reattach to a loop a previous session launched. Bounded, cheap,
+ * and failure-tolerant: skips heavy directories, caps depth, and treats any
+ * unreadable dir or corrupt mirror as absent rather than throwing.
+ */
+export function discoverMirrors(root: string): SupervisorTask[] {
+	const found: SupervisorTask[] = [];
+	const walk = (dir: string, depth: number): void => {
+		if (depth > SCAN_MAX_DEPTH) return;
+		let entries: import("node:fs").Dirent[];
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (entry.isFile() && entry.name === MIRROR_NAME) {
+				const task = readMirror(dir); // mirror lives AT <stateDir>/<MIRROR_NAME>
+				if (task) found.push(task);
+			} else if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+				walk(join(dir, entry.name), depth + 1);
+			}
+		}
+	};
+	walk(root, 0);
+	return found;
+}

package/adapters/pi/extensions/forge-loop-supervisor/supervisor.ts

@@ -0,0 +1,185 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-loop-supervisor/supervisor.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * LoopSupervisor — the host-agnostic core that turns a stream of rauf events
+ * into the right user-facing behavior, with exactly-once reporting across
+ * session restarts.
+ *
+ * Reporting rule (issue #236):
+ *   - routine `item_completed` → one quiet deterministic line, no model turn;
+ *   - exception (`needs_human` / block / stuck / review-failed / error /
+ *     cancellation) → notify AND wake the session;
+ *   - terminal (`loop_completed` / error / cancelled) → wake the session so the
+ *     loop stage runs its post-run close-out, then stop watching.
+ *
+ * Dedup + reattach: every rauf record carries a monotonic per-run `seq`. A task
+ * persists the highest `seq` it has already surfaced (`lastSeq`). When a fresh
+ * Pi session reattaches, its tailer re-reads events.ndjson from the top; records
+ * with `seq <= lastSeq` are REPLAYED SILENTLY — they still rebuild the in-memory
+ * `done` counter, but they are never re-notified — while records past `lastSeq`
+ * are surfaced live. That is what lets a restart reconcile a running loop without
+ * duplicate reports.
+ *
+ * Duplicate watchers are prevented by keying active tasks on their stateDir: a
+ * second `attach` for the same stateDir returns the existing handle.
+ */
+
+import { classifyEvent, formatProgress, formatSignal } from "./events.js";
+import type { RaufEvent, SupervisorHost, SupervisorTask } from "./types.js";
+
+/** A live watch handle the host drives: `poll()` on file change, `close()` on
+ *  teardown. Reattach-safe and idempotent. */
+export interface TaskHandle {
+	poll(): void;
+	close(): void;
+	readonly stateDir: string;
+}
+
+interface ActiveTask {
+	task: SupervisorTask;
+	/** Running count of completed items, rebuilt from replayed history. */
+	done: number;
+	/** Highest item_completed seq already counted into `done` — guards the counter
+	 *  against a re-read double-count independently of the notify cursor. */
+	doneCursor: number;
+	/** Total backlog items, when the launcher recorded it (`task.total`). */
+	total?: number;
+	closed: boolean;
+}
+
+export class LoopSupervisor {
+	private readonly active = new Map<string, ActiveTask>();
+
+	constructor(private readonly host: SupervisorHost) {}
+
+	/** Whether a task for this stateDir is already being supervised. */
+	isActive(stateDir: string): boolean {
+		return this.active.has(stateDir);
+	}
+
+	/** Snapshot of the current progress for a task (for the status tool). */
+	progress(stateDir: string): { done: number; total?: number; closed: boolean } | null {
+		const a = this.active.get(stateDir);
+		return a ? { done: a.done, total: a.total, closed: a.closed } : null;
+	}
+
+	/**
+	 * Begin (or reattach) supervision of one task. The returned handle's `poll`
+	 * feeds new NDJSON records through {@link handleRecord}; the host is expected
+	 * to call it on file-change and once immediately (to replay history). A
+	 * second attach for the same stateDir is a no-op that returns the live handle
+	 * — the dedup guard against duplicate watchers.
+	 *
+	 * @param makeReader  Builds a reader (typically an NdjsonTailer bound to
+	 *   `task.eventsFile`) whose `poll` dispatches each parsed record to `onRecord`.
+	 */
+	attach(
+		task: SupervisorTask,
+		makeReader: (
+			onRecord: (rec: RaufEvent) => void,
+			onRotate: () => void,
+		) => { poll(): void },
+	): TaskHandle {
+		const existing = this.active.get(task.stateDir);
+		if (existing) return this.handleFor(task.stateDir);
+
+		const entry: ActiveTask = {
+			task: { ...task },
+			done: 0,
+			doneCursor: -1,
+			total: task.total,
+			closed: task.closed,
+		};
+		this.active.set(task.stateDir, entry);
+		const reader = makeReader(
+			(rec) => this.handleRecord(task.stateDir, rec),
+			() => this.handleRotate(task.stateDir),
+		);
+		return {
+			stateDir: task.stateDir,
+			poll: () => reader.poll(),
+			close: () => this.detach(task.stateDir),
+		};
+	}
+
+	/** Stop tracking a task in memory (watcher teardown / stop). Does NOT touch
+	 *  the detached runner — the loop is server-owned and outlives the session. */
+	detach(stateDir: string): void {
+		this.active.delete(stateDir);
+	}
+
+	/** Process one parsed rauf record for a task: dedup, classify, dispatch. */
+	private handleRecord(stateDir: string, rec: RaufEvent): void {
+		const entry = this.active.get(stateDir);
+		if (!entry) return;
+		const seq = typeof rec.seq === "number" ? rec.seq : null;
+		const alreadySeen = seq !== null && seq <= entry.task.lastSeq;
+		const cls = classifyEvent(rec);
+
+		// Count completed items for the [N/M] line. Guard against double-counting a
+		// replayed item: only count when its seq is past the counter's cursor. On a
+		// fresh attach the cursor is -1 so the whole history counts; on a re-read of
+		// the same run (a spurious re-poll) already-counted items are skipped. A
+		// genuine new run arrives via handleRotate, which resets the cursor first.
+		if (rec.type === "item_completed") {
+			if (seq === null || seq > entry.doneCursor) {
+				entry.done += 1;
+				if (seq !== null) entry.doneCursor = seq;
+			}
+		}
+
+		if (alreadySeen) return; // replayed history — rebuilt state, never re-notify
+
+		let surfaced = true;
+		switch (cls) {
+			case "progress":
+				this.host.notify(formatProgress(rec, entry.done, entry.total), "info");
+				break;
+			case "exception":
+				this.host.notify(formatSignal(rec), "warning");
+				this.host.wake(formatSignal(rec));
+				break;
+			case "terminal":
+				this.host.notify(formatSignal(rec), "info");
+				this.host.wake(formatSignal(rec));
+				entry.closed = true;
+				entry.task.closed = true;
+				break;
+			case "ignore":
+				surfaced = false;
+				break;
+		}
+
+		// Advance the cursor and persist ONLY for a surfaced event. A firehose
+		// (`ignore`) event must not trigger a disk write + session entry per record
+		// (rauf emits many per second); ignored events re-classify as `ignore` on
+		// any later replay, so not persisting their seq is harmless. A terminal
+		// event persists `closed`, letting a later session know the run is done.
+		if (surfaced && seq !== null && seq > entry.task.lastSeq) {
+			entry.task.lastSeq = seq;
+			this.host.persist({ ...entry.task });
+		}
+	}
+
+	/** A rotation was detected (rauf started a new run — event `seq` restarts at
+	 *  0). Reset the per-run cursor and counters so the new run is surfaced from
+	 *  its start instead of being swallowed by the previous run's high-water seq. */
+	private handleRotate(stateDir: string): void {
+		const entry = this.active.get(stateDir);
+		if (!entry) return;
+		entry.task.lastSeq = -1;
+		entry.doneCursor = -1;
+		entry.done = 0;
+		entry.closed = false;
+		entry.task.closed = false;
+		this.host.persist({ ...entry.task });
+	}
+
+	private handleFor(stateDir: string): TaskHandle {
+		return {
+			stateDir,
+			poll: () => {},
+			close: () => this.detach(stateDir),
+		};
+	}
+}

package/adapters/pi/extensions/forge-loop-supervisor/tailer.ts

@@ -0,0 +1,137 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-loop-supervisor/tailer.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * NdjsonTailer — a rotation-aware, malformed-tolerant tail of an append-only
+ * NDJSON file, decoupled from any watch mechanism so it is unit-testable by
+ * driving {@link NdjsonTailer.poll} against a temp file.
+ *
+ * rauf is the single writer of `events.ndjson` and rotates it at the START of
+ * each run — the old file is moved to `<stateDir>/archive/{ts}-events.ndjson`
+ * and a fresh empty file takes its place (rauf `packages/core/src/events-log.ts`).
+ * So a live supervisor must survive the file being replaced by name mid-watch.
+ * Two independent signals catch a rotation: the file's inode changing, and its
+ * size shrinking below our read cursor. Either resets the cursor to 0 and
+ * re-reads from the top of the new file.
+ *
+ * Reads are incremental from a byte offset (never re-reading the whole file), a
+ * trailing partial line with no newline yet is buffered until its newline
+ * arrives, and a line that is not valid JSON is skipped rather than throwing —
+ * a half-flushed or corrupt record must never stall the tail.
+ */
+
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+
+import type { RaufEvent } from "./types.js";
+
+export class NdjsonTailer {
+	private offset = 0;
+	private ino: number | null = null;
+	private partial = "";
+	// A StringDecoder holds back an incomplete trailing multibyte sequence between
+	// reads, so a UTF-8 character split across two polls (e.g. an accented char or
+	// emoji in an event's `reason`/`title`) decodes correctly instead of turning
+	// into replacement chars on each half.
+	private decoder = new StringDecoder("utf8");
+
+	/**
+	 * @param filePath  Absolute path to the NDJSON file (may not exist yet).
+	 * @param onRecord  Called once per successfully-parsed JSON line, in order.
+	 * @param onError   Optional; called with a short reason when a line is
+	 *                  skipped as malformed (for observability/tests).
+	 * @param onRotate  Optional; called when a rotation is detected (a new inode,
+	 *                  or the file shrank below the cursor) — the signal a NEW run
+	 *                  has started, so the consumer can reset per-run state (rauf's
+	 *                  event `seq` restarts at 0 each run).
+	 * @param initialIno  Optional; the inode the file had when the consumer last
+	 *                  watched it (from the persisted mirror). Seeding it lets the
+	 *                  FIRST poll on reattach detect a rotation that happened while
+	 *                  no session was watching — the current file having a
+	 *                  different inode fires `onRotate`, so a stale cursor from a
+	 *                  previous run does not silently swallow the new run.
+	 */
+	constructor(
+		private readonly filePath: string,
+		private readonly onRecord: (rec: RaufEvent) => void,
+		private readonly onError?: (reason: string) => void,
+		private readonly onRotate?: () => void,
+		initialIno?: number,
+	) {
+		this.ino = typeof initialIno === "number" ? initialIno : null;
+	}
+
+	/**
+	 * Read whatever is new since the last poll and dispatch each complete record.
+	 * Idempotent and cheap when nothing changed. Safe to call before the file
+	 * exists (no-op) and across a rotation (resets and re-reads the new file).
+	 */
+	poll(): void {
+		let size: number;
+		let ino: number;
+		try {
+			const st = statSync(this.filePath);
+			size = st.size;
+			ino = st.ino;
+		} catch {
+			// File gone (pre-launch, or mid-rotation between unlink and recreate).
+			// Reset so the next existing file is read from its start.
+			this.offset = 0;
+			this.ino = null;
+			this.partial = "";
+			return;
+		}
+
+		// Rotation: a new inode, or the file shrank below our cursor (truncate /
+		// replace). Re-read from the top of whatever file is there now, reset the
+		// multibyte decoder, and signal the consumer so it can reset per-run state
+		// (rauf restarts `seq` at 0 each run — without this a stale cursor from a
+		// previous run would silently swallow the whole new run). This only fires
+		// on a genuine rotation: the first poll has ino === null, so neither branch
+		// trips on initial attach.
+		if ((this.ino !== null && ino !== this.ino) || size < this.offset) {
+			this.offset = 0;
+			this.partial = "";
+			this.decoder = new StringDecoder("utf8");
+			this.onRotate?.();
+		}
+		this.ino = ino;
+
+		if (size <= this.offset) return; // nothing new
+
+		let chunk: string;
+		let fd: number | null = null;
+		try {
+			fd = openSync(this.filePath, "r");
+			const length = size - this.offset;
+			const buf = Buffer.allocUnsafe(length);
+			const read = readSync(fd, buf, 0, length, this.offset);
+			// Decode through the StringDecoder so a multibyte char straddling this
+			// read's end is held back until its continuation bytes arrive next poll.
+			chunk = this.decoder.write(buf.subarray(0, read));
+			this.offset += read;
+		} catch {
+			return; // transient read failure; try again next poll
+		} finally {
+			if (fd !== null) closeSync(fd);
+		}
+
+		this.partial += chunk;
+		const lines = this.partial.split("\n");
+		// The last element is an incomplete trailing line (empty when the chunk
+		// ended on a newline) — hold it until its newline arrives.
+		this.partial = lines.pop() ?? "";
+
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			let rec: RaufEvent;
+			try {
+				rec = JSON.parse(trimmed) as RaufEvent;
+			} catch {
+				this.onError?.(`skipped malformed NDJSON line (${trimmed.length} chars)`);
+				continue;
+			}
+			if (rec && typeof rec === "object") this.onRecord(rec);
+		}
+	}
+}

package/adapters/pi/extensions/forge-loop-supervisor/types.ts

@@ -0,0 +1,87 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-loop-supervisor/types.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * Shared types for the forge-loop-supervisor Pi extension.
+ *
+ * The extension launches a rauf loop in rauf's own detached/server-managed mode
+ * (`rauf loop run . --backlog <dir> --detached`), which returns immediately and
+ * leaves the loop running inside rauf's server daemon — so the loop outlives the
+ * Pi session by design. The supervisor then watches rauf's native, single-writer
+ * event stream (`<stateDir>/events.ndjson`), turning routine milestones into
+ * quiet deterministic progress and waking the session only on the events that
+ * need a human or the loop's own close-out.
+ *
+ * These types are host-agnostic on purpose: the core (classification, the NDJSON
+ * tailer, the task registry) takes a {@link SupervisorHost} so it can be unit
+ * tested with a fake host and a temp file, exactly as the vendored
+ * ask-user-question extension decouples its questionnaire from the live TUI.
+ */
+
+/** A rauf persisted loop event. Only the fields this extension reads are typed;
+ *  every record also carries `timestamp`, `projectPath`, and a per-run `seq`
+ *  (rauf `packages/core/src/schemas.ts`). Unknown/extra fields are preserved. */
+export interface RaufEvent {
+	type: string;
+	seq?: number;
+	timestamp?: string;
+	itemId?: string;
+	title?: string;
+	reason?: string;
+	silentMs?: number;
+	completedCount?: number;
+	blockedCount?: number;
+	needsHumanCount?: number;
+	[key: string]: unknown;
+}
+
+/** How the supervisor treats one event.
+ *  - `progress`: a routine per-item milestone → one quiet deterministic line, NO
+ *    model turn.
+ *  - `exception`: something a human should see now (needs-human, block, stuck,
+ *    review failure, error, cancellation) → notify AND wake the session.
+ *  - `terminal`: the run finished → wake the session so the loop stage resumes
+ *    its post-run steps.
+ *  - `ignore`: firehose/interior events the supervisor does not surface. */
+export type EventClass = "progress" | "exception" | "terminal" | "ignore";
+
+/** Durable identity of one supervised loop, persisted so a later Pi session can
+ *  reattach to a still-running (or already-finished) loop without relaunching. */
+export interface SupervisorTask {
+	/** Backlog directory passed to `--backlog` (the forge {backlogDir}). */
+	backlogDir: string;
+	/** The runner state directory holding events.ndjson (default `<backlogDir>/.rauf`). */
+	stateDir: string;
+	/** Absolute path to the watched event file (`<stateDir>/events.ndjson`). */
+	eventsFile: string;
+	/** Inode of `eventsFile` when the mirror was last written. On reattach the
+	 *  tailer seeds its rotation check from this: a different inode means the file
+	 *  was rotated (a NEW run — rauf renames the old file to archive/ and recreates
+	 *  it) while no session was watching, so the per-run cursor must reset instead
+	 *  of stale-swallowing the new run. Absent on a fresh launch. */
+	eventsIno?: number;
+	/** ISO timestamp of the launch (for display + staleness reasoning). */
+	launchedAt: string;
+	/** Total backlog items at launch, when known — enables the `[N/M]` progress
+	 *  line. Absent when the launcher could not count the backlog. */
+	total?: number;
+	/** Highest event `seq` already surfaced — the dedup cursor across reattach. */
+	lastSeq: number;
+	/** Whether the supervisor has already surfaced a terminal event for this task. */
+	closed: boolean;
+}
+
+/** The narrow surface the pure core needs from its host (pi, or a test stub).
+ *  Everything the supervisor does to the outside world goes through this, so the
+ *  core carries no pi import and is unit-testable. */
+export interface SupervisorHost {
+	/** A non-turn, user-visible line (routine progress + startup/info). */
+	notify(message: string, level: "info" | "warning" | "error"): void;
+	/** Wake the active session with a message that triggers a model turn when
+	 *  idle (pi `sendMessage(..., { triggerTurn: true })`). Used ONLY for
+	 *  exception and terminal events — never routine progress. */
+	wake(message: string): void;
+	/** Persist the task record durably (pi `appendEntry` + a file mirror). */
+	persist(task: SupervisorTask): void;
+	/** Current time as ISO-8601, injectable for deterministic tests. */
+	now(): string;
+}