pi-aia-asf 0.15.1 → 0.17.1

package/CHANGELOG.md

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.1] - 2026-11-07
+
+### Added
+
+- (describe changes for 0.17.1)
+
+## [0.17.0] - 2026-11-07
+
+### Added — the health gate ships its own toolchain
+
+The gate could not measure. `detectTools()` looked only in the **project's**
+`node_modules`, so on any repo without eslint/jscpd/madge it produced eight
+"tool not installed" skips and reported a level it never examined — and a run
+that changed source could be judged by metrics that were all missing.
+
+- **The tools are now ASF's own dependencies**: `eslint`, `eslint-plugin-sonarjs`,
+  `@typescript-eslint/parser`, `jscpd`, `madge`. Installing pi-aia-asf installs
+  them, so a fresh clone with an empty `node_modules` is still measured.
+- **ASF-first resolution** (`lib/code-health/tools.mjs`): ASF's copy, then the
+  project's, then PATH. The same metric means the same thing in every repo, and a
+  project pinning its own eslint still wins.
+- **No more `npx --no-install`.** Every metric tool is spawned by absolute path
+  from the resolved install; `npx` could silently run a different version or none.
+- **Deterministic eslint.** The gate writes its own flat config to a temp file and
+  runs with `--no-config-lookup`, so a project's eslint config cannot change what
+  is measured. The sonarjs plugin and TS parser are imported by absolute file URL
+  from ASF's install.
+- **Missing tools name the package** ("jscpd is not available — it ships with
+  pi-aia-asf; reinstall the package") instead of a bare "tool not installed".
+
+### Fixed
+
+- **A sonarjs metric counted the wrong rule id** (`cognitive-complexity` instead
+  of `sonarjs/cognitive-complexity`), so it always reported zero violations.
+- **Vendored trees were scanned as project source.** The model level walked
+  `.local`, `site-packages`, `.venv`, `vendor`, `third_party`, `target`, `Pods`
+  and every other dot-directory: from a home directory it produced 958 findings
+  from Python packages belonging to nobody's project. Those trees are skipped now.
+- **A circular dependency in ASF itself** (`code-health/model.mjs` ↔ `run.mjs`,
+  via a dynamic import) — found by madge the moment it could actually run. The
+  file walker moved to `lib/code-health/files.mjs`, imported by both.
+
+## [0.16.1] - 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

package/index.ts

@@ -12,19 +12,21 @@
  */
 
 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";
 import { evaluateBlockers, BLOCKERS, RULE_TEXT, refusalStage, __resetRefusals } from "./lib/gates/blockers.mjs";
 import { createAuthority, renderAuthority } from "./lib/gates/authority.mjs";
-import { decideSettlement, renderCompletionGate, MAX_STEERS, MAX_IDENTICAL_STEERS, steerFingerprint } from "./lib/gates/settle.mjs";
+import { decideSettlement, renderCompletionGate, MAX_STEERS, steerFingerprint } from "./lib/gates/settle.mjs";
 import { projectKey as resolveProjectKey, __clearProjectCache } from "./lib/project.mjs";
 import { classifyToolCall, activationDecision, isSourcePath, bashWritesSource } from "./lib/activation.mjs";
 import { renderRunCard, cardSummary, CARD_CEILING_BYTES } from "./lib/run-card.mjs";
@@ -189,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");
@@ -218,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) ────────────────────────────
@@ -373,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;
 
@@ -402,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 };
@@ -575,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.
 
@@ -1180,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
@@ -1204,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,
       });
@@ -1222,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
@@ -1265,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;
     }
   });
 
@@ -1335,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/code-health/files.mjs

@@ -0,0 +1,117 @@
+/**
+ * Source-file discovery for the health gate.
+ *
+ * Its own module so model.mjs can use it without importing run.mjs, which
+ * imports model.mjs — that pair was a real circular dependency the gate found
+ * in ASF itself once madge was actually installed.
+ */
+
+import { readdirSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+/** Recursively list source files under root, skipping ignored dirs/files. */
+export function listSourceFiles(root, ignorePatterns) {
+  const ignoreDirs = new Set([
+    "node_modules", ".git", "dist", "build", "coverage", "test", "tests", "__tests__", "fixtures",
+    ".next", ".cache",
+    // vendored / generated trees: measuring a dependency's code says nothing
+    // about this project, and on a home directory it produced 958 findings from
+    // Python site-packages.
+    "site-packages", "dist-packages", "venv", ".venv", "env", ".tox", "__pycache__",
+    "vendor", "third_party", "bower_components", "target", "Pods", ".gradle", ".m2",
+  ]);
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const abs = join(dir, e.name);
+      const rel = relative(root, abs);
+      if (e.isDirectory()) {
+        // Dot-directories (.git, .local, .cache, .venv …) are tool state, not
+        // project source.
+        if (e.name.startsWith(".") && e.name !== ".") continue;
+        if (ignoreDirs.has(e.name) || rel.split(sep).some((part) => ignoreDirs.has(part))) continue;
+        walk(abs);
+      } else if (e.isFile()) {
+        if (/\.(test|spec)\.[^.]+$/.test(e.name)) continue;
+        if (ignorePatterns && ignorePatterns.some((p) => p.includes(e.name))) continue;
+        out.push(rel);
+      }
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * Detect which metric tools are available. Resolution is ASF-first (see
+ * tools.mjs): the gate ships its own toolchain, so a project without eslint is
+ * still measured rather than skipped.
+ */
+export function detectTools(root) {
+  const tools = resolveTools(root);
+  return {
+    eslint: tools.eslint,
+    eslintSonarjs: tools.eslintSonarjs,
+    jscpd: tools.jscpd,
+    madge: tools.madge,
+    dependencyCruiser: tools.dependencyCruiser,
+    typescriptParser: tools.typescriptParser,
+    bins: tools.bins,
+    pkgs: tools.pkgs,
+    sources: tools.sources,
+    missing: missingTools(tools),
+  };
+}
+
+/**
+ * Build a flat-config eslint config for the requested rules and write it to a
+ * temp file. Deterministic on purpose: `--no-config-lookup` means the project's
+ * own config cannot change what the gate measures, and the plugin/parser are
+ * imported by absolute file URL so they resolve from ASF's install.
+ */
+function writeEslintConfig(rules, tools, root) {
+  const imports = [];
+  // flat config wants plugin OBJECTS, not names
+  let pluginsSrc = "{}";
+  const langOpts = ['ecmaVersion: "latest"', 'sourceType: "module"'];
+  // Resolve each package's real entry point instead of guessing a path: the
+  // plugin's main file moves between major versions (lib/index.js → cjs/plugin.js).
+  const entry = (name) => {
+    for (const base of [ASF_ROOT, root]) {
+      try {
+        return pathToFileURL(createRequire(join(base, "package.json")).resolve(name)).href;
+      } catch { /* try the next base */ }
+    }
+    return null;
+  };
+  const sonarjsEntry = tools.pkgs.sonarjs && entry("eslint-plugin-sonarjs");
+  if (sonarjsEntry) {
+    // CJS plugin with __esModule: the real object is a nested default.
+    imports.push(`import sonarjsMod from ${JSON.stringify(sonarjsEntry)};\nconst sonarjs = sonarjsMod.default || sonarjsMod;`);
+    pluginsSrc = "{ sonarjs }";
+  }
+  const tsParserEntry = tools.pkgs.tsParser && entry("@typescript-eslint/parser");
+  if (tsParserEntry) {
+    imports.push(`import tsParserMod from ${JSON.stringify(tsParserEntry)};\nconst tsParser = tsParserMod.default || tsParserMod;`);
+    langOpts.push("parser: tsParser");
+    langOpts.push('parserOptions: { ecmaVersion: "latest", sourceType: "module", ecmaFeatures: { jsx: true } }');
+  }
+  const body = `${imports.join("\n")}
+export default [{
+  files: ["**/*.js", "**/*.mjs", "**/*.cjs", "**/*.jsx", "**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
+  languageOptions: { ${langOpts.join(", ")} },
+  plugins: ${pluginsSrc},
+  rules: ${JSON.stringify(rules, null, 2)},
+}];
+`;
+  const file = join(tmpdir(), `asf-eslint-${process.pid}-${Math.random().toString(36).slice(2, 8)}.mjs`);
+  writeFileSync(file, body, "utf-8");
+  return file;
+}
+

package/lib/code-health/model.mjs

@@ -25,6 +25,10 @@
  * exception stays visible instead of becoming a silent pass.
  */
 
+// The walker lives in files.mjs: importing it from run.mjs made the pair circular.
+import { listSourceFiles } from "./files.mjs";
+
+
 /**
  * Declarations whose documented meaning is "deleting the parent takes the
  * children". Relational, ORM-mapped and object-store alike — the *concept* is
@@ -371,7 +375,7 @@ export function hasPersistenceFiles(files) {
  */
 export async function scanModel(root, { files, readFile, config } = {}) {
   const fs = readFile || (await import("node:fs/promises")).readFile;
-  const list = files || (await import("./run.mjs")).listSourceFiles(root, null);
+  const list = files || listSourceFiles(root, null);
   const findings = [];
   const errors = [];
   let scanned = 0;

package/lib/code-health/run.mjs

@@ -8,7 +8,15 @@
 import { readdirSync, statSync, existsSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { spawn } from "node:child_process";
+import { writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
 import { scanModel } from "./model.mjs";
+import { resolveTools, missingTools, ASF_ROOT } from "./tools.mjs";
+import { listSourceFiles } from "./files.mjs";
+
+export { listSourceFiles };
 
 /** Run a command with a hard timeout; resolve on exit. */
 export function exec(cmd, args, { cwd, timeoutMs = 120_000, env } = {}) {
@@ -34,45 +42,70 @@ export function exec(cmd, args, { cwd, timeoutMs = 120_000, env } = {}) {
   });
 }
 
-/** Recursively list source files under root, skipping ignored dirs/files. */
-export function listSourceFiles(root, ignorePatterns) {
-  const ignoreDirs = new Set(["node_modules", ".git", "dist", "build", "coverage", "test", "tests", "__tests__", "fixtures", ".next", ".cache"]);
-  const out = [];
-  const walk = (dir) => {
-    let entries;
-    try {
-      entries = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const e of entries) {
-      const abs = join(dir, e.name);
-      const rel = relative(root, abs);
-      if (e.isDirectory()) {
-        if (ignoreDirs.has(e.name) || rel.split(sep).some((part) => ignoreDirs.has(part))) continue;
-        walk(abs);
-      } else if (e.isFile()) {
-        if (/\.(test|spec)\.[^.]+$/.test(e.name)) continue;
-        if (ignorePatterns && ignorePatterns.some((p) => p.includes(e.name))) continue;
-        out.push(rel);
-      }
-    }
+/**
+ * Detect which metric tools are available. Resolution is ASF-first (see
+ * tools.mjs): the gate ships its own toolchain, so a project without eslint is
+ * still measured rather than skipped.
+ */
+export function detectTools(root) {
+  const tools = resolveTools(root);
+  return {
+    eslint: tools.eslint,
+    eslintSonarjs: tools.eslintSonarjs,
+    jscpd: tools.jscpd,
+    madge: tools.madge,
+    dependencyCruiser: tools.dependencyCruiser,
+    typescriptParser: tools.typescriptParser,
+    bins: tools.bins,
+    pkgs: tools.pkgs,
+    sources: tools.sources,
+    missing: missingTools(tools),
   };
-  walk(root);
-  return out;
 }
 
-/** Detect which metric tools are available in the project. */
-export function detectTools(root, { execFn = exec, timeoutMs = 30_000 } = {}) {
-  const bin = (name) => existsSync(join(root, "node_modules", ".bin", name));
-  const pkg = (name) => existsSync(join(root, "node_modules", name));
-  const eslint = bin("eslint");
-  const eslintSonarjs = eslint && pkg("eslint-plugin-sonarjs");
-  const jscpd = bin("jscpd") || pkg("jscpd");
-  const madge = bin("madge") || pkg("madge");
-  const dependencyCruiser = bin("depcruise") || pkg("dependency-cruiser");
-  const typescriptParser = pkg("@typescript-eslint/parser");
-  return { eslint, eslintSonarjs, jscpd, madge, dependencyCruiser, typescriptParser };
+/**
+ * Build a flat-config eslint config for the requested rules and write it to a
+ * temp file. Deterministic on purpose: `--no-config-lookup` means the project's
+ * own config cannot change what the gate measures, and the plugin/parser are
+ * imported by absolute file URL so they resolve from ASF's install.
+ */
+function writeEslintConfig(rules, tools, root) {
+  const imports = [];
+  let pluginsSrc = "{}";
+  const langOpts = ['ecmaVersion: "latest"', 'sourceType: "module"'];
+  // Resolve each package's real entry point instead of guessing a path: the
+  // plugin's main file moves between major versions (lib/index.js → cjs/plugin.js).
+  const entry = (name) => {
+    for (const base of [ASF_ROOT, root]) {
+      try {
+        return pathToFileURL(createRequire(join(base, "package.json")).resolve(name)).href;
+      } catch { /* try the next base */ }
+    }
+    return null;
+  };
+  const sonarjsEntry = tools.pkgs.sonarjs && entry("eslint-plugin-sonarjs");
+  if (sonarjsEntry) {
+    // CJS plugin with __esModule: the real plugin object is a nested default.
+    imports.push(`import sonarjsMod from ${JSON.stringify(sonarjsEntry)};\nconst sonarjs = sonarjsMod.default || sonarjsMod;`);
+    pluginsSrc = "{ sonarjs }";
+  }
+  const tsParserEntry = tools.pkgs.tsParser && entry("@typescript-eslint/parser");
+  if (tsParserEntry) {
+    imports.push(`import tsParserMod from ${JSON.stringify(tsParserEntry)};\nconst tsParser = tsParserMod.default || tsParserMod;`);
+    langOpts.push("parser: tsParser");
+    langOpts.push('parserOptions: { ecmaVersion: "latest", sourceType: "module", ecmaFeatures: { jsx: true } }');
+  }
+  const body = `${imports.join("\n")}
+export default [{
+  files: ["**/*.js", "**/*.mjs", "**/*.cjs", "**/*.jsx", "**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
+  languageOptions: { ${langOpts.join(", ")} },
+  plugins: ${pluginsSrc},
+  rules: ${JSON.stringify(rules, null, 2)},
+}];
+`;
+  const file = join(tmpdir(), `asf-eslint-${process.pid}-${Math.random().toString(36).slice(2, 8)}.mjs`);
+  writeFileSync(file, body, "utf-8");
+  return file;
 }
 
 const ESLINT_RULES = {
@@ -99,22 +132,30 @@ export async function runEslint(plans, root, { execFn = exec, timeoutMs = 120_00
   if (eslintPlans.length === 0) return {};
   const files = listSourceFiles(root, null).filter((f) => /\.(js|jsx|mjs|cjs|ts|tsx|mts|cts)$/.test(f));
   if (files.length === 0) return {};
+  const tools = resolveTools(root);
+  if (!tools.bins.eslint) {
+    return { __error: "eslint is not available — it ships with pi-aia-asf; reinstall the package" };
+  }
   const hasTs = files.some((f) => /\.tsx?$/.test(f));
-  const args = ["--no-eslintrc", "--format", "json"];
-  if (hasTs) {
-    if (!detectTools(root).typescriptParser) {
-      return { __error: "TypeScript parser (@typescript-eslint/parser) not installed — cannot lint .ts files" };
-    }
-    args.push("--parser", "@typescript-eslint/parser");
+  if (hasTs && !tools.typescriptParser) {
+    return { __error: "@typescript-eslint/parser is not available — it ships with pi-aia-asf; reinstall the package" };
   }
+  const rules = {};
   for (const p of eslintPlans) {
     const ruleId = ESLINT_RULE_IDS[p.key];
     if (!ruleId) continue;
-    const rule = ESLINT_RULES[p.key](p.threshold);
-    args.push("--rule", JSON.stringify({ [ruleId]: rule }));
+    // eslint 9 flat config uses the bare rule name; the plugin namespace is
+    // only for sonarjs.
+    rules[p.tool === "eslint-sonarjs" ? `sonarjs/${ruleId}` : ruleId] = ESLINT_RULES[p.key](p.threshold);
+  }
+  const configFile = writeEslintConfig(rules, tools, root);
+  const args = ["--no-config-lookup", "--config", configFile, "--format", "json", ...files];
+  let res;
+  try {
+    res = await execFn(tools.bins.eslint, args, { cwd: root, timeoutMs });
+  } finally {
+    try { rmSync(configFile, { force: true }); } catch { /* best effort */ }
   }
-  args.push(...files);
-  const res = await execFn("npx", ["--no-install", "eslint", ...args], { cwd: root, timeoutMs });
   if (res.timedOut) return { __error: `eslint timed out after ${timeoutMs / 1000}s` };
   if (res.code !== 0 && !res.stdout) return { __error: `eslint failed: ${(res.stderr || "").slice(0, 300)}` };
   let data;
@@ -135,7 +176,10 @@ export async function runEslint(plans, root, { execFn = exec, timeoutMs = 120_00
   }
   const out = {};
   for (const p of eslintPlans) {
-    const ruleId = ESLINT_RULE_IDS[p.key];
+    // The reported id carries the plugin namespace for sonarjs rules; counting
+    // the bare name silently reported 0 violations for every sonarjs metric.
+    const bare = ESLINT_RULE_IDS[p.key];
+    const ruleId = p.tool === "eslint-sonarjs" ? `sonarjs/${bare}` : bare;
     if (unavailable.has(ruleId)) {
       out[p.key] = { value: 0, unavailable: true };
     } else {
@@ -158,7 +202,9 @@ export async function runJscpd(plan, root, { execFn = exec, timeoutMs = 120_000,
     "--ignore", "**/node_modules/**,**/dist/**,**/build/**,**/coverage/**,**/test/**,**/tests/**,**/__tests__/**,**/fixtures/**,**/*.test.*,**/*.spec.*",
     root,
   ];
-  const res = await execFn("npx", ["--no-install", "jscpd", ...args], { cwd: root, timeoutMs });
+  const bin = resolveTools(root).bins.jscpd;
+  if (!bin) return { error: "jscpd is not available — it ships with pi-aia-asf; reinstall the package" };
+  const res = await execFn(bin, args, { cwd: root, timeoutMs });
   if (res.timedOut) return { error: `jscpd timed out after ${timeoutMs / 1000}s` };
   const reportPath = join(outDir, "jscpd-report.json");
   try {
@@ -174,7 +220,9 @@ export async function runJscpd(plan, root, { execFn = exec, timeoutMs = 120_000,
 
 /** Run madge --circular; return { value: cycle count } or { error }. */
 export async function runMadge(plan, root, { execFn = exec, timeoutMs = 120_000 } = {}) {
-  const res = await execFn("npx", ["--no-install", "madge", "--circular", "--extensions", "js,jsx,ts,tsx,mjs,cjs", root], { cwd: root, timeoutMs });
+  const bin = resolveTools(root).bins.madge;
+  if (!bin) return { error: "madge is not available — it ships with pi-aia-asf; reinstall the package" };
+  const res = await execFn(bin, ["--circular", "--extensions", "js,jsx,ts,tsx,mjs,cjs", root], { cwd: root, timeoutMs });
   if (res.timedOut) return { error: `madge timed out after ${timeoutMs / 1000}s` };
   const text = res.stdout + res.stderr;
   if (res.code === 0) return { value: 0 };
@@ -187,7 +235,9 @@ export async function runDepcruise(plan, root, { execFn = exec, timeoutMs = 120_
   const cfg = plan.args.config;
   const files = listSourceFiles(root, null).filter((f) => /\.(js|jsx|mjs|cjs|ts|tsx|mts|cts)$/.test(f));
   if (files.length === 0) return { value: 0 };
-  const res = await execFn("npx", ["--no-install", "depcruise", "--config", cfg, "--output-type", "err", "--fail-on", "error", ...files], { cwd: root, timeoutMs });
+  const bin = resolveTools(root).bins.depcruise;
+  if (!bin) return { error: "dependency-cruiser is not available — install it in the project to use this metric" };
+  const res = await execFn(bin, ["--config", cfg, "--output-type", "err", "--fail-on", "error", ...files], { cwd: root, timeoutMs });
   if (res.timedOut) return { error: `dependency-cruiser timed out after ${timeoutMs / 1000}s` };
   return { value: res.code === 0 ? 0 : 1 };
 }

package/lib/code-health/tools.mjs

@@ -0,0 +1,140 @@
+/**
+ * Code Health Gate — tool resolution.
+ *
+ * The gate measures nothing without its tools, and a project that happens not to
+ * ship eslint/jscpd/madge is not a project without complexity problems. So the
+ * tools are ASF's OWN dependencies (package.json) and are resolved from ASF
+ * first: the same metric means the same thing in every repo, and a fresh clone
+ * with an empty node_modules still gets a real measurement instead of eight
+ * "tool not installed" skips.
+ *
+ * Resolution order, per tool:
+ *   1. ASF's own node_modules  — deterministic, ships with the package
+ *   2. the project's node_modules — a project may pin its own version
+ *   3. PATH — a global install
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** ASF's package root (this file is <root>/lib/code-health/tools.mjs). */
+export const ASF_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+const TOOLS = {
+  eslint: { bin: "eslint", pkg: "eslint" },
+  sonarjs: { pkg: "eslint-plugin-sonarjs" },
+  tsParser: { pkg: "@typescript-eslint/parser" },
+  jscpd: { bin: "jscpd", pkg: "jscpd" },
+  madge: { bin: "madge", pkg: "madge" },
+  depcruise: { bin: "depcruise", pkg: "dependency-cruiser" },
+};
+
+function isExecutable(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function findBin(base, name) {
+  const p = join(base, "node_modules", ".bin", name);
+  return isExecutable(p) ? p : null;
+}
+
+function findPkg(base, name) {
+  const p = join(base, "node_modules", name);
+  return existsSync(p) ? p : null;
+}
+
+function findOnPath(name) {
+  for (const dir of String(process.env.PATH || "").split(":")) {
+    if (!dir) continue;
+    const p = join(dir, name);
+    if (isExecutable(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Resolve every tool. `bins` holds absolute paths to spawn (never `npx`, which
+ * silently installs a different version or nothing at all).
+ *
+ * @param {string} projectRoot
+ * @returns {{eslint:boolean, eslintSonarjs:boolean, jscpd:boolean, madge:boolean,
+ *            dependencyCruiser:boolean, typescriptParser:boolean,
+ *            bins:Record<string,string|null>, pkgs:Record<string,string|null>,
+ *            sources:Record<string,string>}}
+ */
+export function resolveTools(projectRoot) {
+  const bases = [
+    { dir: ASF_ROOT, source: "asf" },
+    { dir: projectRoot, source: "project" },
+  ];
+  const bins = {};
+  const pkgs = {};
+  const sources = {};
+
+  for (const [key, spec] of Object.entries(TOOLS)) {
+    if (spec.bin) {
+      bins[key] = null;
+      for (const b of bases) {
+        const found = findBin(b.dir, spec.bin);
+        if (found) {
+          bins[key] = found;
+          sources[key] = b.source;
+          break;
+        }
+      }
+      if (!bins[key]) {
+        const onPath = findOnPath(spec.bin);
+        if (onPath) {
+          bins[key] = onPath;
+          sources[key] = "path";
+        }
+      }
+    }
+    if (spec.pkg) {
+      pkgs[key] = null;
+      for (const b of bases) {
+        const found = findPkg(b.dir, spec.pkg);
+        if (found) {
+          pkgs[key] = found;
+          if (!sources[key]) sources[key] = b.source;
+          break;
+        }
+      }
+    }
+  }
+
+  // eslint is usable when its binary exists; the sonarjs rules only when the
+  // plugin package is there too. A missing plugin must not disable the six
+  // eslint metrics that do not need it.
+  const eslint = !!bins.eslint;
+  return {
+    eslint,
+    eslintSonarjs: eslint && !!pkgs.sonarjs,
+    jscpd: !!bins.jscpd,
+    madge: !!bins.madge,
+    dependencyCruiser: !!bins.depcruise,
+    typescriptParser: !!pkgs.tsParser,
+    bins,
+    pkgs,
+    sources,
+  };
+}
+
+/**
+ * Human-readable list of what is missing, for the "make them requirements"
+ * contract: the gate names the package, not just "tool not installed".
+ */
+export function missingTools(tools) {
+  const out = [];
+  if (!tools.eslint) out.push("eslint");
+  if (!tools.eslintSonarjs) out.push("eslint-plugin-sonarjs");
+  if (!tools.jscpd) out.push("jscpd");
+  if (!tools.madge) out.push("madge");
+  if (!tools.typescriptParser) out.push("@typescript-eslint/parser");
+  return out;
+}

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

@@ -28,12 +28,10 @@
 
 import { sessionFacts } from "./ledger.mjs";
 
-/** An identical steer is never issued twice. */
-export const MAX_IDENTICAL_STEERS = 1;
 /**
- * Absolute ceiling on distinct steers per session. Beyond it the gaps are
- * 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, and no longer referenced by any
+ * decision. It is kept so tooling that prints "steer N" has a number to name;
+ * there is no cap on warranted work, and a real gap is re-raised forever.
  */
 export const MAX_STEERS = 12;
 
@@ -51,6 +49,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 +123,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 +134,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 +144,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 +154,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 +186,7 @@ export function decideSettlement(ledger, opts = {}) {
     return {
       block: false,
       missing,
+      reported: reportedOnly,
       park,
       fingerprint,
       steer: continuationsSoFar,
@@ -144,46 +194,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 +228,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.1",
+  "version": "0.17.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",
@@ -72,5 +72,12 @@
     "jiti": "^2.7.0",
     "typebox": "1.3.27",
     "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@typescript-eslint/parser": "^8.72.1",
+    "eslint": "^9.39.5",
+    "eslint-plugin-sonarjs": "^4.2.2",
+    "jscpd": "^5.4.2",
+    "madge": "^8.0.0"
   }
 }