@garygentry/feature-forge 0.3.5 → 0.3.7

package/adapters/gemini/skills/forge-verify/references/verifier-patterns/pattern_vacuous_self_reading_tests.md

@@ -0,0 +1,32 @@
+---
+name: pattern-vacuous-self-reading-tests
+description: Tests that read their own source file are near-always vacuous unless they assert absence or scope the read; verify by a PROPERTY-PRESERVING mutation and check WHICH line goes red
+metadata:
+  type: reference
+---
+
+A drift-guard test that does `source = read(Path(__file__).resolve())` and then asserts a
+**positive** substring is almost always vacuous: the searched literal sits on the assert
+line itself, so the whole-file read satisfies it unconditionally.
+
+**Why:** the trap catches even the *fix* for a prior vacuity finding, which often
+reproduces the identical defect while its own inline comment claims "this reads for a
+DIFFERENT string than the one it writes". The fix pass validates it with a mutation that
+changes a second property at the same time — replacing a derived roster with a *shrunken*
+hardcoded list goes red, but at a pre-existing floor assertion (`len(...) >= MIN`), not at
+the assertion under test. Seeing "red" is taken as proof; a roster-**preserving** hardcode
+leaves the test fully green.
+
+**How to apply:**
+
+- Grep every changed test for `read(Path(__file__)` / `inspect.getsource`. For each,
+  locate the searched literal's occurrences in the file. Two occurrences (guarded site +
+  assert line) = vacuous.
+- Never accept "the mutation went red". Demand the **line number** of the failing
+  assertion, and design the mutation to change exactly one property.
+- Acceptable forms: assert **absence** (write the banned tokens without the syntax that
+  makes them live), or scope the read away from the guarding test's own body
+  (`inspect.getsource(<the guarded function>)`). The best form for "this expression is
+  still derived" is an `ast` parse, which the assertion's own text cannot satisfy.
+
+See [[pattern-postfix-reverify]] and [[pattern-mechanical-rewrite-damage]].

package/adapters/pi/.feature-forge-bundle.json

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

package/adapters/pi/agents/forge-verifier.md

@@ -28,10 +28,11 @@ You have READ-ONLY access. You cannot and should not modify any files. Your outp
 ## How You Work
 
 1. Read the pipeline state file to understand what stage the feature is at
-2. Load all relevant artifacts for the current verification mode
-3. Read **only your dispatched mode's checklist** — `references/verification-checklists/{mode}.md` (the parent's dispatch prompt names your `{mode}`) — and execute every check in it. Do **not** read the other five mode files or `references/findings-template.md`; those are for other modes and for the parent orchestrator respectively.
-4. Return structured findings as your response in the Output Format specified below
-5. Generate a fix plan suitable for a fresh agent to execute
+2. Read the shipped verifier-patterns index — `references/verifier-patterns/MEMORY.md` — and open the patterns your dispatched mode makes relevant. These are the versioned, reviewed heuristics that ship with the pipeline (see "Using Your Memory" for how they relate to your per-project memory).
+3. Load all relevant artifacts for the current verification mode
+4. Read **only your dispatched mode's checklist** — `references/verification-checklists/{mode}.md` (the parent's dispatch prompt names your `{mode}`) — and execute every check in it. Do **not** read the other five mode files or `references/findings-template.md`; those are for other modes and for the parent orchestrator respectively.
+5. Return structured findings as your response in the Output Format specified below
+6. Generate a fix plan suitable for a fresh agent to execute
 
 ## Scoped / Parallel Operation
 
@@ -47,7 +48,17 @@ For large spec suites (>8 documents), process verification in phases: load share
 
 ## Using Your Memory
 
-You have persistent memory in your `MEMORY.md` file. Use it to track:
+You draw on two distinct layers, and they must not be confused:
+
+- **Shipped verifier patterns** (`references/verifier-patterns/`) — versioned, reviewed
+  heuristics that ship with the pipeline to every project. Read the index
+  (`references/verifier-patterns/MEMORY.md`) on start. **Treat these as read-only** — they
+  are canon, not your scratch memory; a genuinely new, general heuristic worth shipping is
+  a change proposed in review, not something you write here at run time.
+- **Per-project memory** (`memory: project`, below) — your own accumulating notes about
+  *this* project's specific blind spots, conventions, and confirmed false positives.
+
+You have persistent per-project memory in your `MEMORY.md` file. Use it to track:
 
 - **Recurring patterns**: If you keep finding the same type of gap across features, note it. Over time you'll learn this project's blind spots.
 - **Project conventions**: As you review more specs, capture conventions that should be consistent (naming patterns, error handling approaches, test strategies).

package/adapters/pi/extensions/forge-invocation-args/README.md

@@ -0,0 +1,106 @@
+# forge-invocation-args (Pi compatibility extension)
+
+First-party feature-forge extension that deterministically preserves the arguments
+supplied to `/skill:forge-*` commands on the Pi host. Fixes
+[issue #303](https://github.com/garygentry/feature-forge/issues/303).
+
+## The problem it works around
+
+Pi expands `/skill:<name> <args>` by appending the raw argument string after the
+skill body. Pi's documentation says arguments arrive as `User: <args>`, but the
+implementation appends them with only a bare `\n\n` separator and **no semantic
+boundary**:
+
+```text
+</skill>
+
+rendered-model-v2
+```
+
+So `/skill:forge-1-prd rendered-model-v2` reaches the model with the feature name
+as unlabeled trailing text. A model can read it as metadata or unrelated prose and
+wrongly trigger feature-forge's canonical "no feature name → STOP and ask" rule
+(`references/shared-conventions.md` § Feature Name Requirement). Because the feature
+name keys **directory resolution**, **branch naming**, and every
+**`.pipeline-state.json`** write, losing it silently is high-impact — not cosmetic.
+
+This is an upstream Pi implementation/documentation mismatch:
+
+- Prior to Pi commit `7868b25a2` (*"make skill invocation messages collapsible"*),
+  expansion used `` `${skillMessage}\n\n---\n\nUser: ${args}` ``.
+- That commit changed it to `` `${skillBlock}\n\n${args}` `` — dropping the `User:`
+  boundary.
+- The behavior began in Pi **v0.50.0** and is still present in
+  `@earendil-works/pi-coding-agent` **0.84.4** (the version this adapter builds
+  against) and **0.85.1** (latest tested).
+
+Restoring `User:` upstream would fix today's formatting, but feature-forge should
+not depend on model inference of an undocumented prompt layout. This extension is
+host-compatibility hardening that remains useful even after an upstream fix.
+
+## How it works
+
+Pi's `input` event fires **before** skill/template expansion (and after
+extension-command dispatch; `/skill:` is not an extension command, so it reaches
+us). The extension registers one `input` handler that, for a `/skill:forge*`
+invocation, rewrites the input to inject a versioned envelope, then lets Pi's
+built-in expansion append it as the skill's arguments:
+
+```xml
+<feature-forge-invocation version="1">
+  <skill>forge-1-prd</skill>
+  <arguments>rendered-model-v2</arguments>
+</feature-forge-invocation>
+```
+
+The forge skill bodies read the feature name from `<arguments>`. An empty element
+means no argument was supplied — for a skill that requires a feature name that means
+STOP and ask; the `forge` navigator (optional argument) proceeds as usual. That
+companion rule lives host-neutrally in `references/shared-conventions.md`.
+
+### Design decisions
+
+- **Inject-into-args, not own-expansion.** The handler returns
+  `{ action: "transform", text: "/skill:<name> <envelope>" }` and lets Pi expand
+  the skill. Verified against Pi's `_expandSkillCommand`
+  (`dist/core/agent-session.js`): the skill name is the text up to the first space,
+  and args are the **entire remainder** (newlines preserved), end-trimmed — so a
+  multiline envelope survives re-parse. This avoids replicating Pi's private
+  skill-block wrapper string, which can drift across versions.
+- **XML entity-escaping** of `&`, `<`, `>` in `<arguments>`. Total, lossless, and
+  collision-proof: a literal `</arguments>` in the raw args becomes
+  `&lt;/arguments&gt;` and cannot close the element. Flags, quotes, and multiline
+  text pass through unchanged.
+- **Always emit the envelope** for a matched command (empty `<arguments>` for zero
+  args) so the contract is uniform and deterministic.
+- **Skip `source: "extension"`.** Messages injected via `sendUserMessage` are
+  dispatched with `expandPromptTemplates: false` and never expand — there is no
+  boundary bug to fix, and rewriting them could corrupt a programmatic message.
+  `"interactive"` and `"rpc"` (including `-p` / `--mode json`) do expand and are
+  normalized.
+- **Fail loudly, never silently.** A thrown input handler makes the Pi runner fall
+  back to the *original untransformed* text — silently reintroducing the bug. On any
+  internal error the handler emits `ctx.ui.notify(..., "error")` and passes the
+  input through unchanged instead of throwing.
+- **Idempotent.** Input handlers chain; an already-enveloped invocation is left
+  untouched (never double-wrapped).
+
+## Supported Pi API / version assumptions
+
+- Requires the documented `input` event with `{ action: "transform" }`
+  (`pi.on("input", …)`), present in the pinned `@earendil-works/pi-coding-agent`
+  `^0.81.1` and confirmed through 0.85.1.
+- Depends only on Pi's **documented** contract that a skill command's arguments are
+  the remainder of the input after the command name — not on the specific
+  (buggy/unstable) way Pi separates them from the skill body. If a future Pi stops
+  treating the remainder as args, switch to owning expansion (replicating the
+  skill-block wrapper); until then, inject-into-args is the smaller-surface choice.
+
+## Tests
+
+`../../test/forge-invocation-args.test.mjs` (run by `npm run verify` in
+`adapter-src/pi`) loads the extension through jiti — the same loader Pi uses —
+asserts it registers exactly one `input` handler, and drives that handler across
+the documented input-before-skill-expansion lifecycle (zero/one/multiple args,
+flags, multiline, XML-special characters, non-forge passthrough, `source`
+routing, and idempotency).

package/adapters/pi/extensions/forge-invocation-args/index.ts

@@ -0,0 +1,31 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-invocation-args/index.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * forge-invocation-args — a first-party Pi compatibility extension that gives
+ * `/skill:forge-*` invocation arguments an explicit, versioned semantic boundary
+ * before Pi's skill expansion drops it (issue #303). See wiring.ts for the full
+ * rationale and mechanics.
+ *
+ * The pi-facing glue is thin: all logic lives in the injectable {@link
+ * createExtension} factory (wiring.ts), unit-tested with a fake pi. This file
+ * adapts 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 rather than a silent runtime failure.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createExtension, type InputResult, type PiLike } from "./wiring.js";
+
+export default function (pi: ExtensionAPI) {
+	const piLike: PiLike = {
+		on: (event, handler) =>
+			(
+				pi.on as unknown as (
+					e: string,
+					h: (ev: unknown, ctx: unknown) => InputResult | Promise<InputResult>,
+				) => void
+			)(event, handler as (ev: unknown, ctx: unknown) => InputResult | Promise<InputResult>),
+	};
+	createExtension(piLike);
+}

package/adapters/pi/extensions/forge-invocation-args/wiring.ts

@@ -0,0 +1,172 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-invocation-args/wiring.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * Pi wiring for forge-invocation-args — the injectable, unit-testable core of the
+ * extension. All logic lives here behind a structural {@link PiLike} so the whole
+ * thing is driven by a fake pi in test (mirroring how forge-loop-supervisor is
+ * tested headlessly). index.ts supplies the real ExtensionAPI.
+ *
+ * WHY THIS EXISTS (issue #303): Pi expands `/skill:<name> <args>` by appending the
+ * raw args after the `</skill>` block with only a bare `\n\n` separator — no
+ * semantic boundary. Pi's docs say args arrive as `User: <args>`, but the
+ * implementation has bare-appended since Pi v0.50.0 (commit 7868b25a2), true
+ * through the installed 0.84.4 and tested 0.85.1. With no boundary, a model can
+ * read a forge feature-name argument as trailing prose and wrongly trip
+ * feature-forge's "no feature name → STOP and ask" rule. The feature name keys
+ * directory resolution, branch naming, and every pipeline-state write, so losing
+ * it silently is high-impact.
+ *
+ * THE FIX: hook Pi's `input` event, which fires BEFORE skill/template expansion
+ * (and after extension-command dispatch — `/skill:` is not an extension command,
+ * so it reaches us). For a `/skill:forge*` invocation we rewrite the input to
+ * `/skill:<name> <envelope>`, wrapping the raw argument string in an explicit,
+ * versioned envelope. Pi then expands the skill and appends the envelope as args
+ * — verified against Pi's `_expandSkillCommand`: skill name is the text up to the
+ * first space, args are the ENTIRE remainder (newlines preserved) end-trimmed, so
+ * a multiline entity-escaped envelope survives re-parse. We keep Pi's built-in
+ * expansion rather than replicating its private skill-block wrapper (which would
+ * drift across versions).
+ *
+ * pi surface used: `pi.on("input", handler)` returning an `InputEventResult`
+ * (`continue` | `transform`), and `ctx.ui.notify` for the fail-loud path.
+ */
+
+/** The envelope element name and its schema version. Consumers (the forge skill
+ *  bodies, via references/shared-conventions.md) read the feature name from
+ *  <arguments> and treat an empty element as "no feature name supplied". */
+export const ENVELOPE_TAG = "feature-forge-invocation";
+export const ENVELOPE_VERSION = "1";
+
+/** Pi's skill-command prefix. Pi expands `/skill:<name> <args>` only when the
+ *  text starts with this literal at index 0 (verified in agent-session.js
+ *  `_expandSkillCommand`), and package skills register un-namespaced — the
+ *  command is `/skill:forge-1-prd`, never `/skill:<pkg>:forge-1-prd`. */
+const SKILL_PREFIX = "/skill:";
+
+/** A feature-forge skill NAME (not the whole command): `forge` or `forge-<...>`.
+ *  Applied to the name Pi itself would parse out (text up to the first space), so
+ *  our match set is exactly Pi's expansion set — no more, no less. Anchored end
+ *  (`$`) so `forgery` is not matched. */
+const FORGE_NAME_RE = /^forge(?:-[a-z0-9-]+)?$/;
+
+/** Result subset this extension ever returns (a strict subset of Pi's
+ *  InputEventResult — we never return `handled`, which would skip the agent). */
+export type InputResult = { action: "continue" } | { action: "transform"; text: string };
+
+interface InputEventLike {
+	text: string;
+	source?: string;
+	streamingBehavior?: string;
+}
+interface UiLike {
+	notify?(message: string, level?: "info" | "warning" | "error"): void;
+}
+interface CtxLike {
+	ui?: UiLike;
+}
+
+/** Minimal structural shape of the pi API this wiring needs. Kept loose so the
+ *  fake pi in tests satisfies it without importing pi; index.ts adapts the real
+ *  ExtensionAPI to it (a renamed/removed `on` becomes a compile error there). */
+export interface PiLike {
+	on(
+		event: string,
+		handler: (event: InputEventLike, ctx: CtxLike) => InputResult | Promise<InputResult>,
+	): void;
+}
+
+/** Entity-escape the three XML metacharacters. Total and lossless: every input is
+ *  representable, and a literal `</arguments>` in the raw args becomes
+ *  `&lt;/arguments&gt;`, which cannot close the real element (no injection). `&`
+ *  must be replaced first so already-escaped output is not double-escaped. Flags,
+ *  quotes, and newlines pass through untouched. */
+export function escapeXml(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Build the versioned invocation envelope for a matched forge skill. `skillName`
+ *  is a kebab token (no escaping needed); `rawArgs` is entity-escaped. Zero args
+ *  yields an empty <arguments> element — the deterministic "no feature name"
+ *  signal. */
+export function buildEnvelope(skillName: string, rawArgs: string): string {
+	return (
+		`<${ENVELOPE_TAG} version="${ENVELOPE_VERSION}">\n` +
+		`  <skill>${skillName}</skill>\n` +
+		`  <arguments>${escapeXml(rawArgs)}</arguments>\n` +
+		`</${ENVELOPE_TAG}>`
+	);
+}
+
+/** True only for a complete envelope this extension emits (open tag WITH the
+ *  version attribute AND the matching close tag) — not merely any argument that
+ *  happens to begin with the tag name. Keeps the idempotency guard from dropping
+ *  the boundary on a legitimate arg like `<feature-forge-invocation> is a tag`. */
+function isAlreadyEnveloped(rawArgs: string): boolean {
+	return (
+		rawArgs.startsWith(`<${ENVELOPE_TAG} version="`) && rawArgs.trimEnd().endsWith(`</${ENVELOPE_TAG}>`)
+	);
+}
+
+/**
+ * Pure normalization: given raw input text, return the transform (for a
+ * feature-forge skill command) or `continue` (for everything else). Exported for
+ * direct unit testing. The command is parsed EXACTLY as Pi's `_expandSkillCommand`
+ * does — the text must start with `/skill:` at index 0, the name is the text up to
+ * the first space (or the whole remainder if none), and args are the rest, trimmed
+ * — so our match set equals Pi's expansion set and the rewritten text re-expands
+ * identically. A name that is not a forge skill (or a `/skill:`-less prompt) is
+ * left untouched.
+ */
+export function normalizeInput(text: string): InputResult {
+	if (!text.startsWith(SKILL_PREFIX)) return { action: "continue" };
+
+	const spaceIndex = text.indexOf(" ");
+	const skillName =
+		spaceIndex === -1 ? text.slice(SKILL_PREFIX.length) : text.slice(SKILL_PREFIX.length, spaceIndex);
+	if (!FORGE_NAME_RE.test(skillName)) return { action: "continue" };
+
+	const rawArgs = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
+
+	// Idempotency: input handlers chain (each sees the prior's output), and a
+	// resend could re-enter here. Never re-wrap an invocation we already enveloped.
+	if (isAlreadyEnveloped(rawArgs)) return { action: "continue" };
+
+	const envelope = buildEnvelope(skillName, rawArgs);
+	return { action: "transform", text: `/skill:${skillName} ${envelope}` };
+}
+
+/**
+ * Register the single `input` handler on `pi`. Returns nothing; all behavior is
+ * in the handler and the pure helpers above.
+ */
+export function createExtension(pi: PiLike): void {
+	pi.on("input", (event, ctx) => {
+		// Only normalize user-typed ("interactive") and API ("rpc") input.
+		// Extension-injected messages ("extension", via sendUserMessage) are
+		// dispatched with expandPromptTemplates:false and never expand, so there is
+		// no boundary bug to fix — and rewriting a programmatic message could corrupt
+		// it. This mirrors Pi's own input-transform example.
+		if (event?.source === "extension") return { action: "continue" };
+
+		try {
+			return normalizeInput(event.text);
+		} catch (error) {
+			// Fail LOUDLY, never silently. A thrown input handler makes the Pi runner
+			// log the error and continue with the ORIGINAL untransformed text — which
+			// would silently reintroduce the dropped-argument bug this extension exists
+			// to prevent. So we surface it via notify and pass the input through
+			// unchanged rather than throwing. (Entity-escaping makes this path
+			// effectively unreachable; it is defense in depth.)
+			const message = error instanceof Error ? error.message : String(error);
+			try {
+				ctx?.ui?.notify?.(
+					`forge-invocation-args: could not normalize a /skill:forge invocation (${message}); passing it through unchanged.`,
+					"error",
+				);
+			} catch {
+				/* headless / no notify surface */
+			}
+			return { action: "continue" };
+		}
+	});
+}

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