@garygentry/feature-forge 0.3.4 → 0.3.6

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;
+}

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

@@ -0,0 +1,423 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-loop-supervisor/wiring.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * Pi wiring for the forge-loop-supervisor — builds the host, the three tools
+ * (launch / status / stop) and the session-lifecycle hooks on a given
+ * `ExtensionAPI`. Every side-effecting dependency (process spawn, file watch,
+ * clock) is injected so the whole extension is unit-testable with a fake pi and
+ * fake deps, mirroring how the vendored ask-user-question extension is driven
+ * headlessly in its own test.
+ *
+ * pi surface used (resolved against the installed pi types, stable across the
+ * pinned 0.81.x): `pi.registerTool`, `pi.on("session_start"|"session_shutdown")`,
+ * `pi.sendMessage(msg, { triggerTurn })` (wake the session — the file-trigger.ts
+ * pattern), `pi.appendEntry(type, data)` (durable task record), `pi.exec` (run
+ * `rauf status --json` / `rauf loop stop`), and `ctx.ui.notify` (quiet toasts).
+ * rauf's `--detached` loop is server-owned and outlives the session, so cleanup
+ * on shutdown tears down watchers only — never the runner.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { Type } from "typebox";
+
+import { clearMirror, discoverMirrors, readMirror, writeMirror } from "./registry.js";
+import { LoopSupervisor, type TaskHandle } from "./supervisor.js";
+import { NdjsonTailer } from "./tailer.js";
+import type { SupervisorHost, SupervisorTask } from "./types.js";
+
+/** The custom-entry type under which task identity is persisted into the pi
+ *  session (read back on `session_start` for reattach). */
+export const TASK_ENTRY_TYPE = "forge-loop-task";
+/** The custom-message type used to wake the session on exception/terminal. */
+export const WAKE_MESSAGE_TYPE = "forge-loop";
+
+/** A live poll trigger for one watched file: `close()` stops it. The real
+ *  factory wires `fs.watch` on the containing directory (so rotation-by-rename
+ *  is caught) plus a low-frequency backstop; a test injects a manual trigger. */
+export interface WatchHandle {
+	close(): void;
+}
+
+/** Injectable side effects. Production values live in index.ts. */
+export interface Deps {
+	/** Launch the runner DETACHED so it outlives the session. Returns nothing —
+	 *  the loop is owned by the runner's server, not by a tracked child. `onError`
+	 *  reports an ASYNCHRONOUS spawn failure (e.g. ENOENT for a bad bin, which
+	 *  Node surfaces on the child's 'error' event, not as a throw). */
+	spawnDetached(bin: string, args: string[], cwd: string, onError?: (message: string) => void): void;
+	/** Watch `filePath` for changes, calling `onChange` on each (real: fs.watch
+	 *  on its directory + backstop interval). */
+	watch(filePath: string, onChange: () => void): WatchHandle;
+	/** Current time as ISO-8601. */
+	now(): string;
+}
+
+/** Minimal shape of the pi API this wiring needs (kept structural so the fake pi
+ *  in tests satisfies it without importing pi). */
+export interface PiLike {
+	registerTool(def: unknown): void;
+	on(event: string, handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
+	sendMessage(
+		message: { customType: string; content: string; display?: boolean },
+		options?: { triggerTurn?: boolean },
+	): void;
+	appendEntry(customType: string, data?: unknown): void;
+	exec?(
+		command: string,
+		args: string[],
+		options?: { cwd?: string; timeout?: number },
+	): Promise<{ stdout: string; stderr: string; code: number }>;
+}
+
+interface UiLike {
+	notify?(message: string, level?: "info" | "warning" | "error"): void;
+}
+interface CtxLike {
+	cwd?: string;
+	hasUI?: boolean;
+	ui?: UiLike;
+	sessionManager?: { getEntries?(): Array<{ type?: string; customType?: string; data?: unknown }> };
+}
+
+function textResult(text: string, details: Record<string, unknown>) {
+	return { content: [{ type: "text" as const, text }], details };
+}
+
+/** Best-effort count of backlog items for the `[N/M]` progress line. */
+function countBacklog(cwd: string, backlogDir: string): number | undefined {
+	for (const candidate of [join(cwd, backlogDir, "backlog.json"), join(backlogDir, "backlog.json")]) {
+		try {
+			if (!existsSync(candidate)) continue;
+			const parsed = JSON.parse(readFileSync(candidate, "utf8")) as { items?: unknown[] };
+			if (Array.isArray(parsed.items)) return parsed.items.length;
+		} catch {
+			// unreadable/unparseable backlog → no total, not an error
+		}
+	}
+	return undefined;
+}
+
+/** Resolve `dir` against `cwd` unless it is already absolute. */
+function resolveDir(cwd: string, dir: string): string {
+	return dir.startsWith("/") ? dir : join(cwd, dir);
+}
+
+/**
+ * Register the supervisor's tools and lifecycle hooks on `pi`. Returns a small
+ * control object (used by tests) exposing the live supervisor and watcher map.
+ */
+export function createExtension(pi: PiLike, deps: Deps) {
+	const watchers = new Map<string, { handle: TaskHandle; watch: WatchHandle; backlogDir: string }>();
+	let ui: UiLike | null = null;
+
+	const host: SupervisorHost = {
+		notify(message, level) {
+			try {
+				ui?.notify?.(message, level);
+			} catch {
+				/* headless / no dialog UI */
+			}
+		},
+		wake(message) {
+			try {
+				pi.sendMessage({ customType: WAKE_MESSAGE_TYPE, content: message, display: true }, { triggerTurn: true });
+			} catch {
+				/* sendMessage unavailable — nothing else to do */
+			}
+		},
+		persist(task) {
+			try {
+				pi.appendEntry(TASK_ENTRY_TYPE, task);
+			} catch {
+				/* appendEntry best-effort */
+			}
+			writeMirror(task);
+		},
+		now: () => deps.now(),
+	};
+
+	const supervisor = new LoopSupervisor(host);
+
+	/** Keep the notify target current from whatever ctx we last saw (tool call or
+	 *  session_start). ctx can go stale across a session replacement, so we always
+	 *  prefer the most recent one. */
+	function refreshUi(ctx: CtxLike): void {
+		if (ctx?.ui) ui = ctx.ui;
+	}
+
+	/** Begin watching a task's event file. Idempotent per stateDir (the dedup
+	 *  guard against duplicate watchers). Does an initial poll to replay history. */
+	function startWatch(task: SupervisorTask): void {
+		if (watchers.has(task.stateDir)) return;
+		const handle = supervisor.attach(task, (onRecord, onRotate) =>
+			new NdjsonTailer(task.eventsFile, onRecord, undefined, onRotate, task.eventsIno),
+		);
+		// Poll, then tear the watcher down once a terminal event has closed the task
+		// (its wake was already sent inside poll). This stops the fs.watch + backstop
+		// interval for a finished loop and frees a relaunch on the same backlog — the
+		// detached runner is untouched, exactly as on session end.
+		const pump = () => {
+			handle.poll();
+			if (supervisor.progress(task.stateDir)?.closed) stopWatch(task.stateDir);
+		};
+		const watch = deps.watch(task.eventsFile, pump);
+		watchers.set(task.stateDir, { handle, watch, backlogDir: task.backlogDir });
+		pump();
+	}
+
+	/** Stop watching a task (teardown / stop) WITHOUT touching the runner. */
+	function stopWatch(stateDir: string): void {
+		const w = watchers.get(stateDir);
+		if (!w) return;
+		try {
+			w.watch.close();
+		} catch {
+			/* ignore */
+		}
+		w.handle.close();
+		watchers.delete(stateDir);
+	}
+
+	// ---- Tools -------------------------------------------------------------
+
+	pi.registerTool({
+		name: "forge_loop_launch",
+		label: "Launch forge loop",
+		description:
+			"Launch the forge autonomous coding loop (rauf) DETACHED and supervise it. " +
+			"The loop runs in rauf's server and outlives this session; this tool returns " +
+			"immediately. It then reports each completed backlog item as a quiet line and " +
+			"WAKES this session on needs-human, blocked, stuck, review-failed, error, or " +
+			"completion. Use this for forge-5-loop's loop run on Pi instead of running the " +
+			"runner in the foreground.",
+		promptSnippet:
+			"Start a forge/rauf loop without blocking the session and supervise its events.ndjson.",
+		parameters: Type.Object({
+			backlogDir: Type.String({ description: "Forge backlog directory passed to --backlog (e.g. specs/auth)." }),
+			bin: Type.Optional(Type.String({ description: "Runner binary. Default 'rauf'." })),
+			stateDir: Type.Optional(
+				Type.String({ description: "Runner state dir holding events.ndjson. Default '<backlogDir>/.rauf'." }),
+			),
+			iterations: Type.Optional(Type.Number({ description: "Max iterations (--iterations). Omit for the runner default." })),
+			review: Type.Optional(Type.Boolean({ description: "Append --review to run the loop's review pass." })),
+			agent: Type.Optional(Type.String({ description: "Coding-agent id passed as --agent." })),
+		}),
+		async execute(_id: string, params: unknown, _signal: unknown, _onUpdate: unknown, ctx: CtxLike) {
+			const p = params as {
+				backlogDir: string;
+				bin?: string;
+				stateDir?: string;
+				iterations?: number;
+				review?: boolean;
+				agent?: string;
+			};
+			refreshUi(ctx);
+			const cwd = ctx.cwd ?? process.cwd();
+			const bin = p.bin || "rauf";
+			const stateDir = resolveDir(cwd, p.stateDir || join(p.backlogDir, ".rauf"));
+			const eventsFile = join(stateDir, "events.ndjson");
+
+			if (supervisor.isActive(stateDir)) {
+				return textResult(
+					`A forge loop is already being supervised for ${stateDir}. Use forge_loop_status to check it, or forge_loop_stop first.`,
+					{ launched: false, stateDir },
+				);
+			}
+
+			const args = ["loop", "run", ".", "--backlog", p.backlogDir, "--detached"];
+			if (typeof p.iterations === "number") args.push("--iterations", String(p.iterations));
+			if (p.review) args.push("--review");
+			if (p.agent) args.push("--agent", p.agent);
+
+			try {
+				// A synchronous throw is a definite failure. An ASYNC spawn error
+				// (ENOENT for a bad bin) arrives after this returns, so surface it as
+				// a notification when it fires rather than silently claiming success.
+				deps.spawnDetached(bin, args, cwd, (msg) =>
+					host.notify(`forge loop: failed to launch ${bin} — ${msg}. The loop did not start.`, "error"),
+				);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return textResult(`Failed to launch ${bin}: ${msg}`, { launched: false, stateDir, error: msg });
+			}
+
+			const task: SupervisorTask = {
+				backlogDir: p.backlogDir,
+				stateDir,
+				eventsFile,
+				launchedAt: host.now(),
+				total: countBacklog(cwd, p.backlogDir),
+				lastSeq: -1,
+				closed: false,
+			};
+			host.persist(task);
+			startWatch(task);
+
+			return textResult(
+				`Launched \`${bin} ${args.join(" ")}\` detached; now supervising ${eventsFile}. ` +
+					"I'll report each completed item and wake this session on needs-human / blocked / " +
+					"stuck / review-failed / error / completion. Run forge_loop_status to confirm it started. " +
+					"Do NOT run the loop in the foreground.",
+				{ launched: true, stateDir, eventsFile },
+			);
+		},
+	});
+
+	pi.registerTool({
+		name: "forge_loop_status",
+		label: "Forge loop status",
+		description:
+			"Report the status of a supervised forge/rauf loop: how many items are done, " +
+			"whether it has finished, and the runner's authoritative counts (via " +
+			"`rauf status --json`). Use to confirm a launch or check progress on demand.",
+		parameters: Type.Object({
+			backlogDir: Type.Optional(Type.String({ description: "Backlog dir of the loop to report. Omit for the only supervised loop." })),
+			stateDir: Type.Optional(Type.String({ description: "State dir of the loop. Overrides backlogDir when set." })),
+			bin: Type.Optional(Type.String({ description: "Runner binary for the status query. Default 'rauf'." })),
+		}),
+		async execute(_id: string, params: unknown, _signal: unknown, _onUpdate: unknown, ctx: CtxLike) {
+			const p = params as { backlogDir?: string; stateDir?: string; bin?: string };
+			refreshUi(ctx);
+			const cwd = ctx.cwd ?? process.cwd();
+			const stateDir = p.stateDir
+				? resolveDir(cwd, p.stateDir)
+				: p.backlogDir
+					? resolveDir(cwd, join(p.backlogDir, ".rauf"))
+					: [...watchers.keys()][0];
+
+			const progress = stateDir ? supervisor.progress(stateDir) : null;
+			// Scope the runner query to the supervised backlog so status reflects the
+			// right loop, not whatever sits at the default project root.
+			const backlogDir = p.backlogDir ?? (stateDir ? watchers.get(stateDir)?.backlogDir : undefined);
+			let runnerLine = "";
+			if (pi.exec) {
+				const statusArgs = ["status", "--json"];
+				if (backlogDir) statusArgs.push("--backlog", backlogDir);
+				try {
+					const res = await pi.exec(p.bin || "rauf", statusArgs, { cwd, timeout: 15000 });
+					runnerLine = res.code === 0 ? ` Runner: ${res.stdout.trim()}` : ` Runner status exited ${res.code}.`;
+				} catch {
+					runnerLine = " (could not query the runner for authoritative status)";
+				}
+			}
+
+			if (!progress) {
+				return textResult(
+					`No forge loop is being supervised in this session${stateDir ? ` for ${stateDir}` : ""}.${runnerLine}`,
+					{ supervised: false, stateDir, runner: runnerLine.trim() },
+				);
+			}
+			const totalPart = typeof progress.total === "number" ? `/${progress.total}` : "";
+			return textResult(
+				`Forge loop ${progress.closed ? "finished" : "running"}: ${progress.done}${totalPart} items completed so far.${runnerLine}`,
+				{ supervised: true, stateDir, done: progress.done, total: progress.total, closed: progress.closed },
+			);
+		},
+	});
+
+	pi.registerTool({
+		name: "forge_loop_stop",
+		label: "Stop forge loop",
+		description:
+			"Stop a supervised forge/rauf loop and stop watching it. This DELIBERATELY " +
+			"terminates the runner (via `rauf loop stop`) — unlike ending the session, " +
+			"which leaves the detached loop running. Use only when the user wants the loop " +
+			"to actually stop.",
+		parameters: Type.Object({
+			backlogDir: Type.Optional(Type.String({ description: "Backlog dir of the loop to stop. Omit for the only supervised loop." })),
+			stateDir: Type.Optional(Type.String({ description: "State dir of the loop. Overrides backlogDir when set." })),
+			bin: Type.Optional(Type.String({ description: "Runner binary. Default 'rauf'." })),
+		}),
+		async execute(_id: string, params: unknown, _signal: unknown, _onUpdate: unknown, ctx: CtxLike) {
+			const p = params as { backlogDir?: string; stateDir?: string; bin?: string };
+			refreshUi(ctx);
+			const cwd = ctx.cwd ?? process.cwd();
+			const stateDir = p.stateDir
+				? resolveDir(cwd, p.stateDir)
+				: p.backlogDir
+					? resolveDir(cwd, join(p.backlogDir, ".rauf"))
+					: [...watchers.keys()][0];
+
+			// Refuse a blind stop: with nothing supervised AND no explicit target we
+			// must NOT run `rauf loop stop`, which would kill whatever loop happens to
+			// be running in this project — one this extension never launched. Require
+			// a supervised task or an explicit backlogDir/stateDir.
+			const watcherRec = stateDir ? watchers.get(stateDir) : undefined;
+			if (!watcherRec && !p.backlogDir && !p.stateDir) {
+				return textResult(
+					"No forge loop is being supervised in this session, and no backlog/stateDir was given — nothing to stop. Ending the session already leaves any detached loop running by design; pass a backlogDir to stop a specific loop.",
+					{ stopped: false },
+				);
+			}
+
+			// Scope the stop to the specific backlog so it targets the intended loop,
+			// not the default project root.
+			const backlogDir = p.backlogDir ?? watcherRec?.backlogDir;
+			let stopLine = "";
+			if (pi.exec) {
+				const stopArgs = ["loop", "stop"];
+				if (backlogDir) stopArgs.push("--backlog", backlogDir);
+				try {
+					const res = await pi.exec(p.bin || "rauf", stopArgs, { cwd, timeout: 30000 });
+					stopLine = res.code === 0 ? "Runner stop requested." : `Runner stop exited ${res.code}: ${res.stderr.trim()}`;
+				} catch (e) {
+					stopLine = `Could not run the stop command: ${e instanceof Error ? e.message : String(e)}`;
+				}
+			}
+			if (stateDir) {
+				stopWatch(stateDir);
+				supervisor.detach(stateDir);
+				clearMirror(stateDir);
+			}
+			return textResult(`Stopped supervising${stateDir ? ` ${stateDir}` : ""}. ${stopLine}`, {
+				stopped: true,
+				stateDir,
+			});
+		},
+	});
+
+	// ---- Lifecycle ---------------------------------------------------------
+
+	// Reattach on every session start (startup / reload / resume / fork): rebuild
+	// the watcher for any loop this session (or a previous one) launched, without
+	// duplicate reporting — the dedup cursor (lastSeq) makes replayed history silent.
+	pi.on("session_start", (_event: unknown, ctx: unknown) => {
+		const c = ctx as CtxLike;
+		ui = c.ui ?? null;
+		const seen = new Set<string>();
+		const consider = (task: SupervisorTask | null) => {
+			if (!task || seen.has(task.stateDir) || watchers.has(task.stateDir)) return;
+			seen.add(task.stateDir);
+			// Prefer the on-disk mirror (most current lastSeq/closed/eventsIno); fall
+			// back to the session entry's own copy.
+			const fresh = readMirror(task.stateDir) ?? task;
+			if (fresh.closed) return; // already surfaced its terminal — nothing to resume
+			startWatch(fresh);
+		};
+		// (1) Session entries carry tasks across reload/resume/fork within a session
+		// lineage (pi.appendEntry survives those).
+		const entries = c.sessionManager?.getEntries?.() ?? [];
+		for (const entry of entries) {
+			if (entry?.type === "custom" && entry?.customType === TASK_ENTRY_TYPE) {
+				consider(entry.data as SupervisorTask);
+			}
+		}
+		// (2) A BRAND-NEW session file has no such entry, so also discover the disk
+		// mirrors under the project root — this is what lets a fresh session reattach
+		// to a loop a previous session launched (issue #236's "reconcile after
+		// session restart"). Bounded scan; `consider` dedups and skips closed tasks.
+		const cwd = c.cwd ?? process.cwd();
+		for (const task of discoverMirrors(cwd)) consider(task);
+	});
+
+	// Cleanup on shutdown: close every watcher, but LEAVE the detached runner
+	// running (it is server-owned and meant to outlive the session) and leave the
+	// mirror in place so the next session reattaches.
+	pi.on("session_shutdown", () => {
+		for (const stateDir of [...watchers.keys()]) stopWatch(stateDir);
+	});
+
+	return { supervisor, watchers, startWatch, stopWatch, host };
+}

package/adapters/pi/package.json

@@ -10,7 +10,8 @@
       "./skills"
     ],
     "extensions": [
-      "./extensions/ask-user-question/index.ts"
+      "./extensions/ask-user-question/index.ts",
+      "./extensions/forge-loop-supervisor/index.ts"
     ]
   },
   "pi-subagents": {