@garygentry/feature-forge 0.3.5 → 0.3.6

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": {

package/adapters/pi/references/forge-config-schema.json

@@ -235,8 +235,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.14.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.14.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.14.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.15.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.15.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.15.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",
@@ -245,8 +245,8 @@
         },
         "minRunnerVersion": {
           "type": "string",
-          "default": "0.6.0",
-          "description": "Minimum runner version (semver). 0.6.0 is the AGENT-SURFACE FLOOR: the rauf version that ships the coding-agent selection surface (the --agent flag, the `agents` availability probe, and the preset agent registry) that this config's agentArgument/agentsProbeCommand consume. Flooring here guarantees a successful gate implies those surfaces exist. (0.5.0 was the prior grammar/contract-flip floor — unified exit codes, `loop run --detached`, explicit `review` signal, versioned events.ndjson — which predates the agent surface and so could not guarantee it.) forge-5 enforces this via versionCommand before any loop side-effects."
+          "default": "0.14.0",
+          "description": "Minimum runner version (semver). 0.14.0 is the CAPABILITY FLOOR the shipped stage actually depends on — it is the version needed for full post-run needs-human recovery: rauf 0.14's `backlog answer` injects a recorded answer into the next iteration (RECOVERY_MIN_RUNNER_VERSION in forge-session.py). Below it, recovery silently degrades to `backlog unblock` (answer not injected) and large Codex prompts retain the pre-0.14 argv-size (E2BIG) failure mode. Earlier surfaces are subsumed: 0.6.0 first shipped the coding-agent selection surface (--agent flag, `agents` availability probe, preset registry consumed by agentArgument/agentsProbeCommand); 0.5.0 added unified exit codes, `loop run --detached`, the explicit `review` signal, and versioned events.ndjson. Flooring at 0.14.0 guarantees a successful gate implies the recovery + agent surfaces both exist. The floor is distinct from the installer's `RAUF_PIN` (installHint) — the pin may sit ahead of the floor when a newer rauf ships nothing this floor's dependents need; it only rises when rauf ships a surface a shipped stage actually depends on. forge-5 enforces the floor via versionCommand before any loop side-effects."
         }
       }
     }

package/adapters/pi/references/ralph-loop-contract.md

@@ -156,11 +156,13 @@ to today. Degradation is **silent, not an error**, keeping alternate (non-rauf)
 runners first-class. The gate condition is owned by
 `02-config-schema-and-gating.md`.
 
-Independently, the **version gate** floors at the runner version that ships the
-agent surface. For rauf that is **0.6.0** (`loopRunner.minRunnerVersion`): the
-`--agent` flag, the `agents` probe, and the preset agent registry are present in
-rauf source at 0.6.0. A successful gate therefore guarantees those surfaces
-exist before any run. See `## Version gating` and
+Independently, the **version gate** floors at the runner version the stage
+depends on. For rauf that is **0.14.0** (`loopRunner.minRunnerVersion`): the
+version the package pins and the floor for full needs-human recovery (0.14's
+`backlog answer`). The agent surface — the `--agent` flag, the `agents` probe,
+and the preset agent registry — has been present since rauf 0.6.0 and is
+subsumed by the higher floor, so a successful gate guarantees both the recovery
+and agent surfaces exist before any run. See `## Version gating` and
 `05-runner-discovery-version-gate.md`.
 
 **This document — the `## Agent selection` section, the `## Per-stage agent
@@ -210,9 +212,11 @@ belongs to execution only. If you find yourself adding `--agent` near a
 
 feature-forge requires a runner exposing `backlog validate` + backlog
 `schemaVersion`, and the unified exit-code/status contract it reads. The floor is
-now the **agent-surface floor**: the runner version that ships the `--agent`
-flag, the `agents` probe, and the preset agent registry. For rauf that is
-**0.6.0** (`loopRunner.minRunnerVersion`).
+now the **capability floor** the stage actually depends on: the version the
+package pins and the floor for full needs-human recovery (0.14's `backlog
+answer`). It subsumes the older agent-surface floor (the `--agent` flag, the
+`agents` probe, and the preset agent registry, present since 0.6.0). For rauf
+that is **0.14.0** (`loopRunner.minRunnerVersion`).
 `forge-5-loop` runs `{bin} version --json`, semver-compares the reported version
 against `minRunnerVersion`, and on a missing-or-too-old runner stops with
 `loopRunner.installHint` (the CLI install/upgrade command) — **before** invoking

package/adapters/pi/references/shared-conventions.md

@@ -206,7 +206,7 @@ If a `state-*` verb exits 2, surface the plain `Error:` line from stderr verbati
 
 ### `state-verify` — verification results and provenance
 
-`state-verify` writes exactly one `stages.forge-verify-{token}` entry — the verification result for the production stage named by `--stage` — plus the top-level `updatedAt`, and nothing else. `--stage` takes the **served production stage** (`forge-0-epic` through `forge-5-loop`; `forge-6-docs` has no verification token and is rejected). Add `--epic "{epic}"` when the feature is an epic member — required, per the member rule above. Result mode passes `--status` (`auto-verify-pending`, `passed`, `findings-reported`, `findings-applied`, or `skipped`) with whatever `--findings-file`, `--findings-count`, and `--verified-stage-version` that status requires; contradictory metadata is refused before any write. `passed` may additionally carry `--findings-file` + `--findings-count` together for an **advisory-only** report (`inconsistency`/`improvement` findings only, per forge-verify's severity floor) — the stage resolves without a fix round and the report stays attached:
+`state-verify` writes exactly one `stages.forge-verify-{token}` entry — the verification result for the production stage named by `--stage` — plus the top-level `updatedAt`, and nothing else. `--stage` takes the **served production stage** (`forge-0-epic` through `forge-5-loop`; `forge-6-docs` has no verification token and is rejected). Add `--epic "{epic}"` when the feature is an epic member — required, per the member rule above. Result mode passes `--status` (`auto-verify-pending`, `passed`, `findings-reported`, `findings-applied`, or `skipped`) with whatever `--findings-file`, `--findings-count`, and `--verified-stage-version` that status requires; contradictory metadata is refused before any write. `passed` may carry `--findings-file` + `--findings-count` for a clean report (count `0`), an **advisory-only** report (`inconsistency`/`improvement` findings only), or accepted residual findings. The stage resolves without a fix round and the report stays attached, making a completed verification round directly resumable if provenance recording is interrupted. A bare `passed` remains accepted for backward compatibility:
 
 **`auto-verify-pending` is not a skill-facing status.** It is written by `stage-exit`'s scheduling boundary, which records the debt automatically when auto-verify is effective for a stage. The value is accepted on this CLI so the entry stays inspectable and repairable, not so a skill can hand-schedule verification: no skill body and no reference passes it, and none should. Every other status in the list is the recorded *result* of a verification that ran (or was explicitly skipped); this one records that one was *owed*.
 

package/adapters/pi/scripts/forge-session.py

@@ -461,8 +461,12 @@ TOPOLOGY_DEPTH_WARN_RATIO: Final[float] = 0.5
 #: The forge-side capability threshold for the runner's `backlog answer` apply
 #: surface: at or above this rauf version the recovery procedure applies answers
 #: via `rauf backlog answer`; below it, it degrades to `rauf backlog unblock`.
-#: It never hard-fails recovery, and it is NOT ``loopRunner.minRunnerVersion``
-#: (the install floor in references/forge-config-schema.json, which stays 0.6.0).
+#: It never hard-fails recovery. As of the 0.14.0 floor bump it now COINCIDES with
+#: ``loopRunner.minRunnerVersion`` (the install floor in
+#: references/forge-config-schema.json, also 0.14.0) — the launch gate was raised so
+#: it no longer green-lights a runner too old to inject a recovered answer — but the
+#: two remain conceptually distinct: this one selects the recovery apply surface and
+#: only degrades, while the install floor hard-stops the launch.
 RECOVERY_MIN_RUNNER_VERSION: Final[str] = "0.14.0"
 #: The fixed final line of the NEXT-STEPS block. The stamp instructs the skill
 #: to print the block verbatim as its absolute last output — nothing after this.
@@ -5694,8 +5698,9 @@ def _verify_result_entry(
     the one status that carries prior state forward — the report metadata — and it
     deliberately writes no ``verifiedStageVersion``: fixes landed, nothing
     re-verified them, so freshness stays unresolved until a later ``passed``.
-    ``passed`` may record NEW attached-report metadata of its own (the
-    advisory-only and escalation-acceptance rules in ``cmd_state_verify``).
+    ``passed`` may record NEW attached-report metadata of its own (a clean report,
+    an advisory-only report, or the escalation-acceptance rules in
+    ``cmd_state_verify``).
 
     Args:
         status: The validated result status.
@@ -5719,11 +5724,11 @@ def _verify_result_entry(
     if status == "passed":
         entry: dict = {"status": status}
         if findings_file is not None:
-            # An attached report — advisory-only, or residual findings the user
-            # explicitly accepted at the escalation gate — resolves as `passed`
-            # so it never routes to forge-fix, while the report stays attached
-            # for later pickup. A bare zero count records no report keys, keeping
-            # the plain "verified clean" shape byte-identical to before.
+            # An attached clean/advisory report, or residual findings the user
+            # explicitly accepted at the escalation gate, resolves as `passed`
+            # so it never routes to forge-fix while the audit artifact stays
+            # attached. A bare zero count records no report keys, preserving the
+            # legacy plain "verified clean" shape.
             entry["findingsFile"] = findings_file
             entry["findingsCount"] = findings_count
         entry["verifiedAt"] = now
@@ -5779,15 +5784,19 @@ def cmd_state_verify(
             write, so a contradictory call never lands a partial entry:
 
             - `passed` — REQUIRES `verified_stage_version`. MAY carry an attached
-              report (`findings_file` + `findings_count` together, count >= 1) in
-              two protocol cases: an ADVISORY-ONLY report (no blocking
-              `error`/`gap` findings), and residual findings the user explicitly
-              ACCEPTED at the round-ledger escalation (recorded first as a
-              `state-decision`; see "Escalation" in stage-exit-protocol.md).
-              Either way the stage resolves without routing to forge-fix and the
-              report stays attached. Half a pairing is refused: a file without a
-              count, a positive count without a file, or a file with a zero
-              count. Unaccepted blocking findings belong to `findings-reported`.
+              report (`findings_file` + `findings_count` together, count >= 0) in
+              three protocol cases: a CLEAN zero-finding round report (a fix
+              pass's re-verify — valid audit evidence that lets the stage advance
+              instead of stranding at `findings-applied`, #237), an ADVISORY-ONLY
+              report (no blocking `error`/`gap` findings, count >= 1), and
+              residual findings the user explicitly ACCEPTED at the round-ledger
+              escalation (recorded first as a `state-decision`; see "Escalation"
+              in stage-exit-protocol.md). In every case the stage resolves
+              without routing to forge-fix and the report stays attached. Half a
+              pairing is refused: a file without a count, or a positive count
+              without a file. A bare `passed` (neither flag) is also accepted and
+              records the report-free clean shape. Unaccepted blocking findings
+              belong to `findings-reported`.
             - `findings-reported` — REQUIRES all three of `verified_stage_version`,
               `findings_file`, and a non-negative `findings_count`.
             - `findings-applied` — REFUSES `verified_stage_version`. Applying fixes
@@ -5914,8 +5923,9 @@ def cmd_state_verify(
     elif status == "passed":
         if findings_file is not None and findings_count is None:
             raise UsageError(
-                "--status passed with an advisory --findings-file requires "
-                "--findings-count N (the number of advisory findings it lists)"
+                "--status passed with --findings-file requires --findings-count N "
+                "(zero for a clean report, or the number of advisory/residual "
+                "findings it lists)"
             )
         if findings_count is not None:
             if findings_count < 0:
@@ -5929,12 +5939,6 @@ def cmd_state_verify(
                     f"report to read is unrecoverable. Blocking findings belong to "
                     f"--status findings-reported instead."
                 )
-            if findings_count == 0 and findings_file is not None:
-                raise UsageError(
-                    "--status passed with --findings-file requires --findings-count "
-                    ">= 1: an attached report claiming zero findings is "
-                    "self-contradictory — omit both for a clean pass"
-                )
         if verified_stage_version is None:
             raise UsageError(
                 "--status passed requires --verified-stage-version <current version>"

package/adapters/pi/skills/forge/SKILL.md

@@ -247,4 +247,7 @@ This Pi bundle preserves Claude's `AskUserQuestion` references because it ships
 - **User input:** use `AskUserQuestion` for genuine user decisions. It supports multiple questions, option descriptions, recommended ordering, multi-select, previews, and free-form Other/custom answers.
 - **Skill dispatch:** Pi uses `/skill:<name>` commands. If you cannot invoke a skill directly, print the exact `/skill:<name> ...` command for the user to run.
 - **Subagents:** this bundle declares its custom agents (`forge-researcher`, `forge-spec-writer`, `forge-verifier`) as package agents. If a `subagent` tool is registered, dispatch one with `{ agent: "forge-verifier", task: "..." }`, or fan several out concurrently with `{ tasks: [{ agent: "forge-spec-writer", task: "..." }, ...] }`. If no `subagent` tool is available, run that step inline yourself.
-- **Background / monitoring:** run long-lived commands in the foreground and report progress as it arrives.
+- **Background / monitoring (forge-5-loop):** Pi has no built-in background bash, persistent monitor, or push-notification, so do **not** run the loop runner in the foreground and do **not** try to arm one. This bundle registers a **forge-loop-supervisor** extension that IS the "background-execution mechanism" and "monitoring mechanism" Steps 3b–3f refer to. Concretely:
+  - **Launch (Step 3b):** call **`forge_loop_launch`** with the backlog dir (and `review` / `agent` / `iterations` as resolved from config). It starts the loop **detached** — it runs in rauf's server and outlives this session — and returns immediately; you do not build or redirect a command yourself.
+  - **Supervise (Steps 3d–3f):** the extension then watches the runner's `events.ndjson` for you. It reports each completed item as one quiet line and **wakes this session automatically** on needs-human, blocked, stuck, review-failed, error, and completion — so do **not** arm a monitor, set a continuous tail, send a notification, poll, or foreground-sleep, and do not treat any manual stop as the terminal signal. When completion wakes you, go straight to Step 4 and read the authoritative counts with the status/list command. Use **`forge_loop_status`** to check progress on demand.
+  - **Stop / session end:** **`forge_loop_stop`** deliberately stops the runner; use it only when the user wants the loop to actually stop. Ending the Pi session does **not** stop the loop (it is detached), and the next session **reattaches automatically** without re-reporting what you already saw.

package/adapters/pi/skills/forge/references/shared-conventions.md

@@ -206,7 +206,7 @@ If a `state-*` verb exits 2, surface the plain `Error:` line from stderr verbati
 
 ### `state-verify` — verification results and provenance
 
-`state-verify` writes exactly one `stages.forge-verify-{token}` entry — the verification result for the production stage named by `--stage` — plus the top-level `updatedAt`, and nothing else. `--stage` takes the **served production stage** (`forge-0-epic` through `forge-5-loop`; `forge-6-docs` has no verification token and is rejected). Add `--epic "{epic}"` when the feature is an epic member — required, per the member rule above. Result mode passes `--status` (`auto-verify-pending`, `passed`, `findings-reported`, `findings-applied`, or `skipped`) with whatever `--findings-file`, `--findings-count`, and `--verified-stage-version` that status requires; contradictory metadata is refused before any write. `passed` may additionally carry `--findings-file` + `--findings-count` together for an **advisory-only** report (`inconsistency`/`improvement` findings only, per forge-verify's severity floor) — the stage resolves without a fix round and the report stays attached:
+`state-verify` writes exactly one `stages.forge-verify-{token}` entry — the verification result for the production stage named by `--stage` — plus the top-level `updatedAt`, and nothing else. `--stage` takes the **served production stage** (`forge-0-epic` through `forge-5-loop`; `forge-6-docs` has no verification token and is rejected). Add `--epic "{epic}"` when the feature is an epic member — required, per the member rule above. Result mode passes `--status` (`auto-verify-pending`, `passed`, `findings-reported`, `findings-applied`, or `skipped`) with whatever `--findings-file`, `--findings-count`, and `--verified-stage-version` that status requires; contradictory metadata is refused before any write. `passed` may carry `--findings-file` + `--findings-count` for a clean report (count `0`), an **advisory-only** report (`inconsistency`/`improvement` findings only), or accepted residual findings. The stage resolves without a fix round and the report stays attached, making a completed verification round directly resumable if provenance recording is interrupted. A bare `passed` remains accepted for backward compatibility:
 
 **`auto-verify-pending` is not a skill-facing status.** It is written by `stage-exit`'s scheduling boundary, which records the debt automatically when auto-verify is effective for a stage. The value is accepted on this CLI so the entry stays inspectable and repairable, not so a skill can hand-schedule verification: no skill body and no reference passes it, and none should. Every other status in the list is the recorded *result* of a verification that ran (or was explicitly skipped); this one records that one was *owed*.