@garygentry/feature-forge 0.3.4 → 0.3.6

package/adapters/gemini/skills/forge-verify/references/findings-template.md

@@ -131,10 +131,10 @@ violate REQ-STATE-02; per-feature status is always derived live from each member
 `.pipeline-state.json`).
 
 Set `stages.forge-verify-epic.status` to `findings-reported` when the report lists at
-least one **blocking** finding (`error`/`gap`), else `passed` — for an advisory-only
-report pass `--findings-file`/`--findings-count` alongside `--status passed`, exactly
-as in feature mode (the severity floor in `skills/forge-verify/SKILL.md`) — recording
-`findingsFile`, `findingsCount`, and `verifiedAt`.
+least one **blocking** finding (`error`/`gap`), else `passed`. Always attach the report
+and its total count, including count `0` for a clean report, exactly as in feature mode
+(the severity floor in `skills/forge-verify/SKILL.md`) — recording `findingsFile`,
+`findingsCount`, and `verifiedAt`.
 
 **Write it with `state-verify`, never by hand.** `--stage forge-0-epic` is the sanctioned
 epic writer: it creates the file lazily, mutates only `stages.forge-verify-epic` plus the
@@ -149,8 +149,8 @@ R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-session.py" state-verify \
   --feature "{epic}" --stage forge-0-epic \
-  --status "{passed|findings-reported}" \
-  --findings-file "{relative findings path}" --findings-count {n} \
+  --status "{outcome-specific status}" \
+  --findings-file "{relative findings path}" --findings-count {outcome-specific count} \
   --verified-stage-version {manifest revision} --specs-dir "{specsDir}"
 ```
 

package/adapters/gemini/skills/forge-verify/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/.feature-forge-bundle.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-forge",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "agent": "pi",
   "generatedBy": "python3 scripts/build-adapters.py"
 }

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

@@ -0,0 +1,90 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-loop-supervisor/events.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * Event classification + display formatting — pure functions over one rauf event.
+ *
+ * The classification mirrors the coverage-complete filter the generic
+ * forge-5-loop contract arms on Claude (`Monitor` on events.ndjson): every
+ * terminal and exception state is surfaced (silence is never success), while
+ * routine milestones stay quiet. See rauf's event union in
+ * `packages/core/src/schemas.ts` for the authoritative field list.
+ */
+
+import type { EventClass, RaufEvent } from "./types.js";
+
+/** Events that mean "the run is over" — the supervisor wakes the session so the
+ *  loop stage runs its post-run close-out (Steps 4–7), then stops watching. */
+const TERMINAL = new Set(["loop_completed", "loop_error", "loop_cancelled"]);
+
+/** Events a human must see immediately. `loop_paused` carries `reason` and only
+ *  the needs-human pause is surfaced here (the runner sets the item aside and
+ *  keeps going — it is not a full stop). Everything else in this set is an
+ *  unconditional exception. */
+const EXCEPTION = new Set([
+	"needs_human",
+	"item_blocked",
+	"llm_stuck_warning",
+	"review_failed",
+]);
+
+/** The single routine milestone that earns a quiet progress line. */
+const PROGRESS = new Set(["item_completed"]);
+
+/** Classify one event. Unknown/interior/firehose types (token updates, tool
+ *  activity, iteration boundaries, review start, usage-limit chatter, …) are
+ *  `ignore` — the supervisor never surfaces them. */
+export function classifyEvent(evt: RaufEvent): EventClass {
+	const type = evt?.type;
+	if (typeof type !== "string") return "ignore";
+	if (TERMINAL.has(type)) return "terminal";
+	if (EXCEPTION.has(type)) return "exception";
+	// `loop_paused` is an exception ONLY when it is the needs-human pause.
+	if (type === "loop_paused" && evt.reason === "needs_human") return "exception";
+	if (PROGRESS.has(type)) return "progress";
+	return "ignore";
+}
+
+/** A concise, deterministic one-line report for a routine `item_completed`.
+ *  `done`/`total` are threaded in when known so the line reads `[3/10] …`. */
+export function formatProgress(
+	evt: RaufEvent,
+	done?: number,
+	total?: number,
+): string {
+	const count =
+		typeof done === "number" && typeof total === "number" ? `[${done}/${total}] ` : "";
+	const title = typeof evt.title === "string" && evt.title ? evt.title : evt.itemId ?? "item";
+	return `${count}forge loop: completed ${title}`;
+}
+
+/** A human-facing line for an exception or terminal event, used both for the
+ *  toast and for the wake message that triggers the session's next turn. */
+export function formatSignal(evt: RaufEvent): string {
+	switch (evt.type) {
+		case "needs_human":
+			return `forge loop: item ${evt.itemId ?? "?"} needs a human — ${evt.reason ?? "no reason given"}`;
+		case "loop_paused":
+			return `forge loop: paused for human input on ${evt.itemId ?? "an item"}`;
+		case "item_blocked":
+			return `forge loop: item ${evt.itemId ?? "?"} blocked — ${evt.reason ?? "no reason given"}`;
+		case "llm_stuck_warning":
+			return `forge loop: item ${evt.itemId ?? "?"} looks stuck (no output for ${Math.round((evt.silentMs ?? 0) / 1000)}s)`;
+		case "review_failed":
+			return `forge loop: review failed — ${evt.reason ?? "no reason given"}`;
+		case "loop_error":
+			return `forge loop: the run errored — ${evt.reason ?? "see the runner log"}`;
+		case "loop_cancelled":
+			return "forge loop: the run was cancelled";
+		case "loop_completed": {
+			const done = evt.completedCount ?? 0;
+			const blocked = evt.blockedCount ?? 0;
+			const needsHuman = evt.needsHumanCount ?? 0;
+			const parts = [`${done} done`];
+			if (blocked) parts.push(`${blocked} blocked`);
+			if (needsHuman) parts.push(`${needsHuman} need a human`);
+			return `forge loop: run complete — ${parts.join(", ")}. Read the authoritative counts (status --json) and run the post-run close-out.`;
+		}
+		default:
+			return `forge loop: ${evt.type}`;
+	}
+}

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