pi-aia-asf 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -7,6 +7,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.1] - 2026-11-07
+
+### Added
+
+- (describe changes for 0.16.1)
+
+## [0.16.0] - 2026-11-07
+
+### Fixed — the 2026-11-07 endless completion-gate loop
+
+The gate could steer forever for **no reason the agent could act on**. Two defects
+compounded: it demanded `/asf health`, a pi slash command an extension has no tool
+to invoke (so the gap could never close), and the "never the same steer twice" rule
+keyed on a fingerprint that concurrent saves kept wiping, so the identical ask was
+re-issued indefinitely. Both are now structurally impossible.
+
+- **A gate can only block on something the agent can close.** `splitGaps()` sorts
+  every gap into blocking (agent-closable) and reported (needs a human), and it
+  runs **once, after all gaps are assembled** — splitting earlier let gaps pushed
+  afterwards skip the filter. A human-only gap is rendered as "not verified / not
+  blocking" and never resumes the run.
+- **`asf_health` tool.** The health gate's only demand is now an agent-side tool
+  call, which records a verdict in the ledger. No gate asks for a slash command.
+- **A warranted loop has no ceiling.** A real, agent-closable gap is steered for as
+  long as it stays open; the old `exhausted` paths that settled the run with gaps
+  still open are gone. Repeats are worded as repeats ("still open after N previous
+  steers") instead of pretending to be new information, and no message claims a
+  bound ("of at most 12") the gate does not have.
+- **The steer count is in-process memory, and state.json is only its record.** A
+  corrupt, raced or hand-edited file can no longer reset the count or erase a
+  fingerprint; `Math.max` on read plus a monotonic merge on write make it
+  non-decreasing.
+- **Saves are serialized per project and merged under the lock.** Eleven paths
+  read-modify-write the state file; the write is now queued per project and
+  re-reads the file inside the lock, merging the monotonic fields (steer count,
+  fingerprints, touched files, last mutation). Write-to-temp-then-`rename` means a
+  reader never sees a half-written file.
+- **A corrupt state file can no longer disable the gate.** Wrong-typed fields used
+  to throw inside the settle handler, and the catch-all returned `undefined` —
+  which settled the run as if the gate had passed. Fields are coerced on load and
+  on both sides of a merge, and an internal error is now surfaced once as
+  `asf-gate-error` (deduped by error class, since an I/O message carries a random
+  tmp filename) instead of being swallowed.
+- **A park is asked once per (run, reason)**, and guidance-only continuations are
+  bounded per run, so no secondary nudge can hold a session open on its own.
+
+Every guard above is pinned by a test that fails when the guard is removed.
+
+## [0.15.1] - 2026-11-06
+
+### Fixed
+
+- **Specs are read under the same project key as run state.** 0.15.0 moved run state
+  to the git-root key but still read pi-vigilant's spec store by cwd basename. From
+  a subdirectory, the trace floor for specs met in the run therefore looked in the
+  wrong store and found nothing. pi-vigilant 0.9.0 writes the store under the root
+  key, and ASF reads it there. It falls back to the basename location, so an older
+  pi-vigilant does not leave ASF unable to see specs. Both suites pin the same
+  key vectors.
+
 ## [0.15.0] - 2026-11-06
 
 ### Added

package/index.ts

@@ -12,13 +12,15 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { mkdir, readFile, writeFile, rename } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { cpus, loadavg } from "node:os";
+import { Type } from "typebox";
 import { execFileSync } from "node:child_process";
 
 import { createLedger, deriveSuiteRun, renderLedger } from "./lib/gates/ledger.mjs";
@@ -143,11 +145,10 @@ function stateFileFor(project: string): string {
 }
 
 /**
- * The key pi-vigilant uses for spec-memory and feedback (cwd basename). Specs are
- * a shared contract between the two extensions, so ASF reads them where
- * vigilant writes them; only ASF's OWN run state moved to the root-based key.
+ * The pre-0.15 key (cwd basename). Used only to find run state written by an
+ * older ASF, and spec memory written by pi-vigilant < 0.9.
  */
-function sharedSpecKey(): string {
+function legacyKey(): string {
   try {
     return basename(process.cwd()) || "default";
   } catch {
@@ -155,12 +156,22 @@ function sharedSpecKey(): string {
   }
 }
 
+/**
+ * The spec store for this project. pi-vigilant >= 0.9 writes it under the same
+ * root-based key ASF uses (pinned vectors in both suites); older versions wrote
+ * it under the basename, which is read as a fallback so an un-upgraded
+ * pi-vigilant does not make ASF go blind to specs.
+ */
+async function loadProjectSpecs(): Promise<SpecItem[] | null> {
+  return (await loadSpecs(projectName())) ?? (await loadSpecs(legacyKey()));
+}
+
 async function loadState(project: string): Promise<ProjectStateFile> {
   const file = stateFileFor(project);
   if (!existsSync(file)) {
     // One-time migration: a run opened under the old basename key is adopted,
     // not orphaned — an upgrade must never silently end an active run.
-    const legacy = stateFileFor(sharedSpecKey());
+    const legacy = stateFileFor(legacyKey());
     if (legacy !== file && existsSync(legacy)) {
       try {
         const data = JSON.parse(await readFile(legacy, "utf-8")) as ProjectStateFile;
@@ -180,6 +191,7 @@ async function loadState(project: string): Promise<ProjectStateFile> {
     if (!data || typeof data !== "object") return restoreFromMirror(project, { current: null, history: [] }, "corrupt");
     if (!data.history) data.history = [];
     if (!data.current) return restoreFromMirror(project, data, "cleared");
+    sanitizeSteerFields(data.current);
     return data;
   } catch {
     return restoreFromMirror(project, { current: null, history: [] }, "corrupt");
@@ -209,12 +221,137 @@ async function restoreFromMirror(project: string, data: ProjectStateFile, how: s
  */
 const runMirror = new Map<string, AsfState>();
 
+/**
+ * How much each run has been steered, held IN THIS PROCESS.
+ *
+ * The 2026-11-07 loop: the bound on identical steers lived only in state.json.
+ * A concurrent writer (the tool_call handler saves the same file on every source
+ * mutation) could put an older copy back, and the counter restarted — so the
+ * same gap was re-asked forever and the autonomous loop never ended. The state
+ * file is now a *record*; this map is the *authority* for this session. A run's
+ * steer count can go up, never down, and an identical steer is never issued
+ * twice in the same process no matter what the file says.
+ */
+const steerMemory = new Map<string, { count: number; seen: Set<string>; guidance: number }>();
+/** (runId|reason) already parked in this process — a park is asked once. */
+const parkedAlready = new Set<string>();
+
+/**
+ * Guidance-only continuations (card, steers) are capped per session. The
+ * completion gate has its own bound; this one covers the paths that continue a
+ * run merely to say something.
+ */
+const MAX_GUIDANCE_CONTINUATIONS = 24;
+/**
+ * Per-RUN, not per-process: a long session runs many runs, and each deserves
+ * its cards. A run kept alive purely by its own advice is the pathology.
+ */
+function steerContinuationsAllowed(mem: { guidance: number }): boolean {
+  if (mem.guidance >= MAX_GUIDANCE_CONTINUATIONS) {
+    appendEvidence({ kind: "steer", gate: "guidance-cap", suppressed: true });
+    return false;
+  }
+  mem.guidance++;
+  return true;
+}
+function steerLedgerFor(key: string): { count: number; seen: Set<string>; guidance: number } {
+  let m = steerMemory.get(key);
+  if (!m) {
+    m = { count: 0, seen: new Set<string>(), guidance: 0 };
+    if (steerMemory.size > 64) steerMemory.clear();
+    steerMemory.set(key, m);
+  }
+  return m;
+}
+
+/** Coerce a loaded run state's steer fields — a hand-edited or raced file must not disable the bound. */
+/**
+ * Coerce the fields the gate reads into the types it assumes. A hand-edited or
+ * older-version file must never be able to (a) throw inside the handler or
+ * (b) make every later save fail — so this runs on load AND on both sides of a
+ * merge, not only on the steer fields it was originally written for.
+ */
+function sanitizeSteerFields(state: AsfState | null | undefined): void {
+  if (!state) return;
+  if (typeof state.steers !== "number" || !Number.isFinite(state.steers) || state.steers < 0) state.steers = 0;
+  if (!Array.isArray(state.seenSteers)) state.seenSteers = [];
+  state.seenSteers = (state.seenSteers as unknown[]).filter((x): x is string => typeof x === "string" && x.trim().length > 0);
+  if (!Array.isArray(state.filesTouched)) state.filesTouched = [];
+  else state.filesTouched = (state.filesTouched as unknown[]).filter((f): f is string => typeof f === "string" && f.trim().length > 0).slice(-10);
+  if (typeof state.lastMutationAt !== "number" || !Number.isFinite(state.lastMutationAt)) state.lastMutationAt = 0;
+}
+
+/**
+ * Saves are SERIALIZED per project.
+ *
+ * Eleven code paths save the same file (activation, settle, park, close, abort,
+ * restore…). Each one read-modify-writes it, so two overlapping saves let an
+ * older copy land last — which is how the 2026-11-07 loop survived its own
+ * bound: the settle handler wrote the steer counter, a source-mutation save put
+ * an older copy back, and the counter restarted. Writes are now queued per
+ * project, so a save cannot interleave with another.
+ */
+const saveQueue = new Map<string, Promise<void>>();
+
+/**
+ * Monotonic fields: once a run has been steered, or has touched a file, an older
+ * copy of the state must never erase that. Eleven code paths read-modify-write
+ * this file; the queue serializes the WRITES, and this merge closes the window
+ * the queue cannot: a caller that loaded the state before another caller saved
+ * it still writes a stale snapshot. Re-reading inside the lock and merging the
+ * monotonic fields makes a lost update impossible for the fields that matter to
+ * the completion gate.
+ */
+function mergeMonotonic(incoming: ProjectStateFile, onDisk: ProjectStateFile | null): ProjectStateFile {
+  const a = incoming.current;
+  const b = onDisk?.current;
+  // Both sides are sanitized: the on-disk copy can be hand-edited or written by
+  // an older version, and spreading a non-array field here threw inside the
+  // settle handler — which then settled the run silently (a gate bypass).
+  sanitizeSteerFields(a);
+  sanitizeSteerFields(b);
+  if (!a || !b) return incoming;
+  if (a.runId !== b.runId) return incoming; // a different run: no merge
+  a.steers = Math.max(Number(a.steers) || 0, Number(b.steers) || 0);
+  a.seenSteers = [...new Set([...(a.seenSteers || []), ...(b.seenSteers || [])])].filter((x) => typeof x === "string" && x.trim()).slice(-50);
+  // Chronological: the on-disk list is older, the incoming one carries the new
+  // entry. Appending the incoming entries AFTER the on-disk ones keeps
+  // newest-last, which is what the slice(-10) below trims.
+  const touched = [...(b.filesTouched || [])];
+  for (const f of a.filesTouched || []) if (!touched.includes(f)) touched.push(f);
+  a.filesTouched = touched.slice(-10);
+  if (typeof b.lastMutationAt === "number") a.lastMutationAt = Math.max(Number(a.lastMutationAt) || 0, b.lastMutationAt);
+  if (!a.parked && b.parked) a.parked = b.parked;
+  return incoming;
+}
+
+async function readStateFile(file: string): Promise<ProjectStateFile | null> {
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf-8")) as ProjectStateFile;
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeStateFile(project: string, data: ProjectStateFile): Promise<void> {
+  const file = stateFileFor(project);
+  await mkdir(join(STATE_DIR, project), { recursive: true });
+  const merged = mergeMonotonic(data, await readStateFile(file));
+  // Write-then-rename: a reader never sees a half-written file.
+  const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+  await writeFile(tmp, JSON.stringify(merged, null, 2), "utf-8");
+  await rename(tmp, file);
+}
+
 async function saveState(project: string, data: ProjectStateFile): Promise<void> {
   if (data.current) runMirror.set(project, JSON.parse(JSON.stringify(data.current)));
   else runMirror.delete(project);
-  const file = stateFileFor(project);
-  await mkdir(join(STATE_DIR, project), { recursive: true });
-  await writeFile(file, JSON.stringify(data, null, 2), "utf-8");
+  const snapshot = JSON.parse(JSON.stringify(data)) as ProjectStateFile;
+  const prev = saveQueue.get(project) || Promise.resolve();
+  const next = prev.then(() => writeStateFile(project, snapshot), () => writeStateFile(project, snapshot));
+  saveQueue.set(project, next.catch(() => undefined));
+  await next;
 }
 
 // ─── Spec-memory read (shared with pi-vigilant) ────────────────────────────
@@ -364,7 +501,7 @@ const suiteRuns: Array<{ scope: string; exitCode: number; command: string; durat
 /** Memoised dirty-tree answer, refreshed at most once per tool call. */
 let dirtyCache: { at: number; dirty: boolean } | null = null;
 
-let lastSettleDecision: { missing: string[]; exhausted?: boolean } | null = null;
+let lastSettleDecision: { missing: string[] } | null = null;
 let webTouched = false;
 let impactStated = false;
 
@@ -393,9 +530,12 @@ const deliveredSteers = new Set<string>();
  * information. Events (gate-block, suite-run, transitions) are never deduped:
  * they are what a trace study measures.
  */
-const EVENT_KINDS = new Set(["run-restored", "gate-block", "suite-run", "spec-transition", "browser-verify", "browser-na", "health-run", "perf-scenario", "run-open", "run-close", "park", "steer", "passive"]);
+const EVENT_KINDS = new Set(["gate-error", "run-restored", "gate-block", "suite-run", "spec-transition", "browser-verify", "browser-na", "health-run", "perf-scenario", "run-open", "run-close", "park", "steer", "passive"]);
 const persistedVerdicts = new Set<string>();
 let passiveHeartbeatWritten = false;
+/** Re-anchoring is time-rate-limited AND count-limited per run. */
+const MAX_REANCHORS_PER_RUN = 5;
+let reanchorsThisRun = 0;
 
 function verdictSignature(entry: Record<string, unknown>): string {
   const { ts, at, timestamp, ...rest } = entry as Record<string, unknown> & { ts?: unknown; at?: unknown; timestamp?: unknown };
@@ -566,6 +706,67 @@ let lastScaleWasSmall = false;
 
 export default function register(pi: ExtensionAPI): void {
   piRef = pi;
+
+  // ── asf_health: the agent's own way to produce a health verdict ───────────
+  // The completion gate requires a recorded health verdict, and until 0.15.2 the
+  // ONLY way one was recorded was the ledger recognising a bash command that
+  // looked like `/asf health` — a pi slash command the agent cannot type. An
+  // autonomous run was therefore steered forever at a gap it had no hands for
+  // (the 2026-11-07 loop). Any gate that blocks must have an agent-side action;
+  // this is that action for the health gate.
+  pi.registerTool({
+    name: "asf_health",
+    label: "ASF Health",
+    description:
+      "Run ASF's code health gate (function/module/architecture) on this project and " +
+      "record the verdict as evidence. This is the agent-side equivalent of /asf health " +
+      "and it is what clears the completion gate's health gap — call it instead of " +
+      "waiting for a human to type /asf health.",
+    promptSnippet: "Run the code health gate and record its verdict",
+    parameters: Type.Object({
+      level: Type.Optional(
+        StringEnum(["small", "standard", "major"] as const, {
+          description: "Health level to record; defaults to the run's scale.",
+        }),
+      ),
+      scope: Type.Optional(
+        Type.String({ description: "Optional scope passed to the health gate (e.g. 'function')." }),
+      ),
+    }),
+    async execute(_toolCallId: string, params: { level?: unknown; scope?: unknown }) {
+      try {
+        const levelIn = typeof params?.level === "string" ? params.level : "";
+        const scopeIn = typeof params?.scope === "string" ? params.scope : "";
+        const { runHealth } = await import("./lib/code-health/index.mjs");
+        const args = scopeIn ? [`--scope=${scopeIn}`] : [];
+        const res = await runHealth(process.cwd(), args);
+        const verdict = res.exitCode === 1 ? "fail" : res.healthy ? "pass" : "warn";
+        const scanned = Array.isArray(res.rows) ? res.rows.length : 0;
+        const level: string = ["small", "standard", "major"].includes(levelIn) ? levelIn : currentScale();
+        const appended = ledger.append({ kind: "health-run", level, verdict, scanned });
+        appendEvidence({ kind: "health-run", level, verdict, scanned, by: "tool" });
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `${res.text}\n\nverdict: ${verdict} (${scanned} metric(s) measured, level ${level}) — ` +
+                (appended.ok
+                  ? "recorded as evidence; the completion gate's health gap is now closed."
+                  : `NOT recorded (${appended.error})`),
+            },
+          ],
+          details: { verdict, scanned, level, recorded: appended.ok, by: "tool", error: "" },
+        };
+      } catch (e) {
+        return {
+          content: [{ type: "text", text: `asf_health failed: ${(e && (e as Error).message) || String(e)}` }],
+          details: { verdict: "unknown", scanned: 0, level: "standard", recorded: false, by: "tool", error: String((e as Error)?.message || e) },
+        };
+      }
+    },
+  });
+
   // Startup check: warn once per session if deps are missing (unless disabled)
   // The extension loads at startup; log to console so it surfaces in logs.
 
@@ -665,7 +866,7 @@ export default function register(pi: ExtensionAPI): void {
         ];
 
         if (scale === "large") {
-          const specs = await loadSpecs(sharedSpecKey());
+          const specs = await loadProjectSpecs();
           lines.push("\nSPEC-TO-CODE TRACEABILITY (M1 — large work):");
           if (!specs || specs.length === 0) {
             lines.push(
@@ -1171,7 +1372,7 @@ export default function register(pi: ExtensionAPI): void {
           passiveHeartbeatWritten = true;
           appendEvidence({ kind: "passive", by: "no-run" });
         }
-        return (steerEntries.length > priorCount ? { entries: steerEntries, continue: true } : undefined) as never;
+        return (steerEntries.length > priorCount && steerContinuationsAllowed(steerLedgerFor(`${project}|no-run`)) ? { entries: steerEntries, continue: true } : undefined) as never;
       }
 
       // Only a passing test that STARTED after the last source change validates
@@ -1183,7 +1384,7 @@ export default function register(pi: ExtensionAPI): void {
       let untracedMet: string[] = [];
       try {
         const runStart = Date.parse(state.startedAt || "") || 0;
-        const specs = (await loadSpecs(sharedSpecKey())) || [];
+        const specs = (await loadProjectSpecs()) || [];
         untracedMet = specs
           .filter((sp) => sp.status === "met")
           .filter((sp) => {
@@ -1195,12 +1396,16 @@ export default function register(pi: ExtensionAPI): void {
       } catch {
         /* spec memory unreadable: this item cannot be judged, the rest still is */
       }
+      // The in-process ledger is the authority; the file is a record that may be
+      // stale, raced or hand-edited. max() means a counter can never go down.
+      const mem = steerLedgerFor(`${project}|${state.runId || "run"}`);
+      sanitizeSteerFields(state);
       const decision = decideSettlement(ledger, {
         untracedMet,
         scale: currentScale(state),
         webTouched,
-        continuationsSoFar: state.steers || 0,
-        seenSteers: state.seenSteers || [],
+        continuationsSoFar: Math.max(state.steers || 0, mem.count),
+        seenSteers: [...new Set([...(state.seenSteers || []), ...mem.seen])],
         sourceMutated: !!state.sourceMutated,
         testRunRecorded,
       });
@@ -1213,22 +1418,36 @@ export default function register(pi: ExtensionAPI): void {
       });
 
       if (decision.park) {
+        // Park the SAME reason once. An autonomous run has no PO waiting to
+        // answer, so re-parking every settle would be the same endless loop in
+        // a different costume: ask, get nothing, settle, ask again.
+        const parkKey = `${state.runId || "run"}|${decision.park.reason}`;
+        if (parkedAlready.has(parkKey)) {
+          appendEvidence({ kind: "park-suppressed", reason: decision.park.reason });
+        } else {
+          parkedAlready.add(parkKey);
+          steerEntries.push({
+            type: "custom_message",
+            customType: "asf-park",
+            content: `ASF: this needs input ASF cannot supply — ${decision.park.question}\nAsk the PO through the project's input channel (for ticket work: park the ticket), then continue with anything that does not depend on it.`,
+            display: true,
+            details: { park: decision.park },
+          });
+        }
         state.parked = { reason: decision.park.reason, question: decision.park.question, at: new Date().toISOString() };
         await saveState(project, file);
         appendEvidence({ kind: "park", reason: decision.park.reason, question: decision.park.question });
-        steerEntries.push({
-          type: "custom_message",
-          customType: "asf-park",
-          content: `ASF: this needs input ASF cannot supply — ${decision.park.question}\nAsk the PO through the project's input channel (for ticket work: park the ticket), then continue with anything that does not depend on it.`,
-          display: true,
-          details: { park: decision.park },
-        });
-        return { entries: steerEntries, continue: true } as never;
+        const parkedEntry = steerEntries.find((e) => e.customType === "asf-park");
+        // Only continue while there is something NEW to say; a repeat park is
+        // recorded and the run settles.
+        return (parkedEntry ? { entries: steerEntries, continue: true } : undefined) as never;
       }
 
       if (decision.block) {
-        state.steers = decision.steer;
-        state.seenSteers = [...(state.seenSteers || []), decision.fingerprint || ""].slice(-50);
+        mem.count += 1;
+        if (decision.fingerprint) mem.seen.add(decision.fingerprint);
+        state.steers = Math.max(typeof decision.steer === "number" ? decision.steer : 0, mem.count);
+        state.seenSteers = [...new Set([...(state.seenSteers || []), ...(decision.fingerprint ? [decision.fingerprint] : [])])].slice(-50);
         state.updatedAt = new Date().toISOString();
         await saveState(project, file);
         // The continuation MUST carry content. pi commits `entries` and only
@@ -1256,9 +1475,25 @@ export default function register(pi: ExtensionAPI): void {
         file.current = null;
         await saveState(project, file);
       }
-      return (steerEntries.length > priorCount ? { entries: steerEntries, continue: true } : undefined) as never;
-    } catch {
-      return undefined;
+      // A continuation for guidance alone (card/steers) is also bounded: an
+      // agent that keeps producing new distinct steers must not be kept alive
+      // by its own advice.
+      const wantsContinue = steerEntries.length > priorCount && steerContinuationsAllowed(mem);
+      return (wantsContinue ? { entries: steerEntries, continue: true } : undefined) as never;
+    } catch (e) {
+      // An internal error is NOT a pass. Silently returning undefined let the
+      // run settle with its evidence gaps unexamined — the gate simply vanished.
+      // The error is recorded, surfaced once (deduped like every other steer),
+      // and the run is left to settle only after the agent has been told.
+      const msg = `ASF: the completion gate hit an internal error and could not judge this run: ${(e && (e as Error).message) || String(e)}. Record it and continue; the gate did not pass, it failed to run.`;
+      appendEvidence({ kind: "gate-error", error: String((e && (e as Error).message) || e).slice(0, 300) });
+      // Keyed on the error CLASS, not the message: an I/O error's message carries
+      // a random tmp filename, so keying on it would make every occurrence look
+      // new and the gate would apologise forever.
+      const key = `gate-error|${(e && (e as { code?: string }).code) || (e && (e as Error).name) || "unknown"}`;
+      if (deliveredSteers.has(key)) return undefined;
+      deliveredSteers.add(key);
+      return { entries: [{ type: "custom_message", customType: "asf-gate-error", content: msg, display: true }], continue: true } as never;
     }
   });
 
@@ -1326,9 +1561,10 @@ export default function register(pi: ExtensionAPI): void {
         machineTurnsSinceHuman++;
         if (machineTurnsSinceHuman >= REANCHOR_AFTER_MACHINE_TURNS && Date.now() - lastReanchorAt >= REANCHOR_MIN_INTERVAL_MS) {
           const file = await loadState(projectName());
-          if (file.current && file.current.phase !== "none") {
+          if (file.current && file.current.phase !== "none" && reanchorsThisRun < MAX_REANCHORS_PER_RUN) {
             lastReanchorAt = Date.now();
             machineTurnsSinceHuman = 0;
+            reanchorsThisRun++;
             pendingCard = { text: cardFor(file.current), reason: "reanchor" };
             appendEvidence({ kind: "steer", gate: "reanchor", machineTurns: REANCHOR_AFTER_MACHINE_TURNS });
           }

package/lib/gates/blockers.mjs

@@ -82,7 +82,10 @@ export function blockTestSubset(input, ctx = {}) {
     scanned: 1,
     rule: "test-subset-without-impact",
     reason:
-      `this runs a test SUBSET without stating the impact area. ` +
+      // The command is part of the text on purpose: two different subsets are
+      // two different steers (the agent must be told WHICH run it skipped the
+      // suite for), and the dedupe in index.ts keys on this exact string.
+      `"${String(command).replace(/\s+/g, " ").slice(0, 120)}" runs a test SUBSET without stating the impact area. ` +
       `Autonomous exit: run the full suite (the default), or re-issue with the ` +
       `impact area stated so the subset is a decision rather than a shortcut.`,
   };

package/lib/gates/ledger.mjs

@@ -242,9 +242,9 @@ export function sessionFacts(ledger, { scale = "standard", webTouched = false }
   const health = ledger.latest("health-run");
   if (scale !== "small") {
     if (!health) {
-      missing.push("/asf health was not run this session (run it; its verdict is recorded, not claimed)");
+      missing.push("the code health gate has not been run this session — call the asf_health tool (its verdict is recorded, not claimed)");
     } else if (health.verdict === "unknown") {
-      missing.push("/asf health ran but produced no verdict — a run without a verdict is not a pass");
+      missing.push("the code health gate ran but produced no verdict — call the asf_health tool again; a run without a verdict is not a pass");
     }
   }
 

package/lib/gates/settle.mjs

@@ -35,6 +35,10 @@ export const MAX_IDENTICAL_STEERS = 1;
  * reported and the run is allowed to settle — this is a reporting boundary, not
  * a stop: the work is never halted, only the asking.
  */
+/**
+ * A REPORTING number only — never a stop. It exists so the steer text can say
+ * "steer N" without inventing a bound; there is no cap on warranted work.
+ */
 export const MAX_STEERS = 12;
 
 /**
@@ -51,6 +55,39 @@ const PARK_PATTERNS = [
 /** A lint or a typecheck is not a test run; the floor must not be closable by one. */
 const CHECK_ONLY = /\b(eslint|tsc|typecheck|lint|prettier|biome|check)\b/;
 
+/**
+ * Gaps an autonomous agent CANNOT close, because closing them means a human
+ * typing something ASF has no tool for (a slash command, a click, a key).
+ *
+ * This is the 2026-11-07 loop: the gate demanded "/asf health", which is a pi
+ * slash command. The agent has no tool that records a health verdict, so it
+ * could never clear the gap, and every settle asked again — an autonomous loop
+ * steered forever at a wall. A gap of that shape is a REPORTING item, never a
+ * blocker: the delivery report says it is unverified, and the run settles.
+ *
+ * Anything the agent CAN do (run tests, run the asf_health tool, verify in the
+ * browser, add a trace) stays a blocker. When you add a gate, it must have an
+ * agent-side action; if it does not, it belongs here.
+ */
+const HUMAN_ONLY = /\/asf\s+\w+|type\s+\/|ask the (po|user|human)|needs? (your|the po's?) (input|approval|key)/i;
+
+/** Can the agent close this gap itself? */
+export function agentClosable(gap) {
+  return !HUMAN_ONLY.test(String(gap || ""));
+}
+
+/**
+ * Split gaps into what may BLOCK and what is only REPORTED. Every caller that
+ * builds a missing list goes through this, so a gate cannot quietly start
+ * blocking on something the agent has no hands for.
+ */
+export function splitGaps(gaps = []) {
+  const blocking = [];
+  const reported = [];
+  for (const g of gaps) (agentClosable(g) ? blocking : reported).push(g);
+  return { blocking, reported };
+}
+
 export function classifyPark(missing = []) {
   for (const m of missing) {
     for (const p of PARK_PATTERNS) {
@@ -92,7 +129,10 @@ export function decideSettlement(ledger, opts = {}) {
   } = opts;
 
   const facts = sessionFacts(ledger, { scale, webTouched });
-  const missing = [...facts.missing];
+  // Every gap is collected here, then split ONCE at the end. Splitting earlier
+  // was a bug: gaps pushed after the split skipped the human-only filter and
+  // could block on something the agent has no hands for.
+  const gaps = [...facts.missing];
 
   // The floor for an active run: source changed ⇒ a *test* run, not a check.
   // 50% of the runs ASF will own (61 of 121) contained no validation at all.
@@ -100,7 +140,7 @@ export function decideSettlement(ledger, opts = {}) {
     const hasOnlyChecks = (ledger.entries || []).some(
       (e) => e.kind === "suite-run" && CHECK_ONLY.test(String(e.command || "")),
     );
-    missing.push(
+    gaps.push(
       hasOnlyChecks
         ? "source changed but only a lint/typecheck ran — run the tests (a check does not close this)"
         : "source changed this run but no passing test run was recorded (run the tests that cover the change)",
@@ -110,7 +150,7 @@ export function decideSettlement(ledger, opts = {}) {
   // A spec marked met during this run must say what it delivers and where.
   // Specs met in earlier runs are not re-litigated here.
   if (untracedMet.length) {
-    missing.push(
+    gaps.push(
       `spec(s) marked met this run without a trace (outcome + codePath): ${untracedMet.slice(0, 6).join(", ")}${untracedMet.length > 6 ? ` +${untracedMet.length - 6}` : ""} — add it with update_spec_status trace`,
     );
   }
@@ -120,13 +160,28 @@ export function decideSettlement(ledger, opts = {}) {
     const seen = new Set(
       ledger.entries.filter((e) => e.kind === "spec-transition" || e.kind === "perf-scenario" || e.kind === "browser-verify" || e.kind === "browser-na").map((e) => e.kind),
     );
-    if (!recorded) missing.push("the delivery report cannot be rendered: no health verdict was recorded this session");
+    if (!recorded) gaps.push("the delivery report cannot be rendered: no health verdict was recorded this session");
     if (webTouched && !seen.has("browser-verify") && !seen.has("browser-na")) {
-      missing.push("the delivery report is missing its browser section");
+      gaps.push("the delivery report is missing its browser section");
     }
   }
 
-  if (missing.length === 0) return { block: false, missing: [], report: null, fingerprint: "", steer: continuationsSoFar };
+  const split = splitGaps(gaps);
+  const missing = split.blocking;
+  const reportedOnly = split.reported;
+
+  if (missing.length === 0) {
+    return {
+      block: false,
+      missing: [],
+      reported: reportedOnly,
+      report: reportedOnly.length
+        ? `completion gate: ${reportedOnly.length} gap(s) need a human action ASF cannot take — reported as unverified, not blocking: ${reportedOnly.join("; ")}`
+        : null,
+      fingerprint: "",
+      steer: continuationsSoFar,
+    };
+  }
 
   const fingerprint = steerFingerprint(missing);
 
@@ -137,6 +192,7 @@ export function decideSettlement(ledger, opts = {}) {
     return {
       block: false,
       missing,
+      reported: reportedOnly,
       park,
       fingerprint,
       steer: continuationsSoFar,
@@ -144,46 +200,30 @@ export function decideSettlement(ledger, opts = {}) {
     };
   }
 
-  // Never issue the same steer twice. If the identical gap came back, the agent
-  // either fixed it (it would not be missing) or the steer did not land; asking
-  // again in the same words is the definition of a loop. Report and let settle.
-  if (seenSteers.includes(fingerprint) && MAX_IDENTICAL_STEERS <= 1) {
-    return {
-      block: false,
-      missing,
-      exhausted: true,
-      fingerprint,
-      steer: continuationsSoFar,
-      report:
-        `completion gate: ${missing.length} evidence gap(s) remain and this exact gap was already raised — ` +
-        `it is not asked twice. The delivery report must state these as unverified.`,
-    };
-  }
-
-  // Reporting boundary, not a stop.
-  if (continuationsSoFar >= MAX_STEERS) {
-    return {
-      block: false,
-      missing,
-      exhausted: true,
-      fingerprint,
-      steer: continuationsSoFar,
-      report:
-        `completion gate: ${missing.length} evidence gap(s) remain after ${MAX_STEERS} steers. ` +
-        `Reported rather than re-requested — the delivery report must state these as unverified.`,
-    };
-  }
+  // A REAL gap is never a stop. The 2026-11-07 loop was unwarranted (it steered
+  // over a pi slash command the agent has no tool for) — the cure is to remove
+  // unclosable and repeated-no-reason steers, NOT to cap warranted work. So this
+  // gate keeps asking for as long as the gap is real: it re-raises the same gap
+  // with an escalating count instead of settling, and it never claims an upper
+  // bound it does not have.
+  const attempt = continuationsSoFar + 1;
+  const repeat = seenSteers.includes(fingerprint);
+  const lead = repeat
+    ? `ASF completion gate: still open after ${attempt - 1} previous steer(s). Missing:`
+    : `ASF completion gate: this run cannot be declared done yet. Missing:`;
 
   return {
     block: true,
     missing,
+    reported: reportedOnly,
     fingerprint,
-    steer: continuationsSoFar + 1,
+    steer: attempt,
     continuation:
-      `ASF completion gate: this run cannot be declared done yet. Missing:\n- ${missing.join(
+      `${lead}\n- ${missing.join(
         "\n- ",
-      )}\n\nAddress exactly these and finish. Nothing here stops you — keep working. ` +
-      `This gap has not been raised before, so it is raised once (steer ${continuationsSoFar + 1} of at most ${MAX_STEERS}); an identical one never comes back.`,
+      )}\n\nAddress exactly these and finish. Nothing here stops you, and there is no ` +
+      `ceiling on warranted work: this gap is re-raised until it is closed (steer ${attempt}). ` +
+      `Only an action ASF cannot take is ever parked or dropped.`,
     report: null,
   };
 }
@@ -194,13 +234,17 @@ export function decideSettlement(ledger, opts = {}) {
  */
 export function renderCompletionGate(decision) {
   const lines = ["## Completion gate"];
+  const reported = (decision && decision.reported) || [];
   if (!decision || !decision.missing || !decision.missing.length) {
-    lines.push("- all session facts recorded: health verdict, full-suite green run, browser verification or structured n/a, delivery-report sections");
+    lines.push(reported.length
+      ? `- ${reported.length} gap(s) need a human action ASF has no tool for — reported, not blocking:` + reported.map((g) => `\n  - ${g} (not verified)`).join("")
+      : "- all session facts recorded: health verdict, full-suite green run, browser verification or structured n/a, delivery-report sections");
     return lines.join("\n");
   }
-  const why = decision.park ? ` (parked for the PO: ${decision.park.reason})` : decision.exhausted ? " (raised once, not re-requested — reported, not blocking)" : "";
+  const why = decision.park ? ` (parked for the PO: ${decision.park.reason})` : "";
   lines.push(`- ${decision.missing.length} evidence gap(s)${why}:`);
   for (const m of decision.missing) lines.push(`  - ${m}`);
+  for (const r of reported) lines.push(`  - ${r} (needs a human action; reported, not blocking)`);
   lines.push("- these are **not verified**; the delivery report must not present them as done");
   return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
   "keywords": [
     "pi-package",