kc-beta 0.5.6 → 0.6.1

package/src/agent/llm-client.js

@@ -1,5 +1,20 @@
 import { withRetry } from "./retry.js";
 
+// A5: SSE accumulator safety cap. If a provider ever sends an abnormally
+// large `data: ...` line without a newline terminator, the parser's
+// `buffer += decoder.decode(chunk)` + `buffer.split("\n")` would grow
+// unbounded and trigger O(n²) splitting once it gets into the hundreds
+// of MB. 8 MB is multiple orders of magnitude above any legitimate single
+// SSE frame (largest seen in the wild: ~80 KB for multi-tool-call deltas).
+const SSE_BUFFER_CAP_BYTES = 8 * 1024 * 1024;
+
+class SseOverflowError extends Error {
+  constructor(bytes) {
+    super(`SSE buffer overflow (${bytes} bytes without newline) — aborting stream`);
+    this.code = "SSE_BUFFER_OVERFLOW";
+  }
+}
+
 /**
  * Multi-protocol LLM client using native fetch + SSE parsing.
  * Supports OpenAI-compatible APIs and Anthropic Messages API.
@@ -144,26 +159,56 @@ export class LLMClient {
   async *streamChat({ model, messages, tools, maxTokens }) {
     const body = this._buildStreamBody({ model, messages, tools, maxTokens });
 
-    const resp = await withRetry(async () => {
-      const r = await fetch(this._getEndpoint(), {
-        method: "POST",
-        headers: this._buildHeaders(),
-        body: JSON.stringify(body),
+    let resp;
+    try {
+      resp = await withRetry(async () => {
+        const r = await fetch(this._getEndpoint(), {
+          method: "POST",
+          headers: this._buildHeaders(),
+          body: JSON.stringify(body),
+        });
+        if (!r.ok) {
+          const text = await r.text();
+          const err = new Error(`LLM API error ${r.status}: ${text}`);
+          err.status = r.status;
+          err.retryAfter = r.headers.get("retry-after");
+          err.streamTermination = "http_error";
+          throw err;
+        }
+        return r;
       });
-      if (!r.ok) {
-        const text = await r.text();
-        const err = new Error(`LLM API error ${r.status}: ${text}`);
-        err.status = r.status;
-        err.retryAfter = r.headers.get("retry-after");
-        throw err;
-      }
-      return r;
-    });
+    } catch (err) {
+      // A8: Any pre-stream failure (network, auth, 4xx/5xx after retry) is
+      // tagged and re-thrown. Engine's outer catch sees exactly one tagged
+      // error event.
+      if (!err.streamTermination) err.streamTermination = "connect_error";
+      throw err;
+    }
 
-    if (this.apiFormat === "anthropic") {
-      yield* this._parseAnthropicSSE(resp.body);
-    } else {
-      yield* this._parseOpenaiSSE(resp.body);
+    // A8: Wrap the SSE consumption so ALL termination paths — clean EOS,
+    // mid-token abort, SSE overflow, provider disconnect — surface as a
+    // single tagged error the engine can report consistently. The inner
+    // parsers throw for overflow (A5) and return silently on clean EOS;
+    // mid-stream socket errors (undici "terminated") raise here.
+    try {
+      if (this.apiFormat === "anthropic") {
+        yield* this._parseAnthropicSSE(resp.body);
+      } else {
+        yield* this._parseOpenaiSSE(resp.body);
+      }
+    } catch (err) {
+      if (!err.streamTermination) {
+        if (err.code === "SSE_BUFFER_OVERFLOW") err.streamTermination = "sse_overflow";
+        else if (err.name === "AbortError") err.streamTermination = "aborted";
+        else if (/terminated|reset|ECONNRESET|UND_ERR_ABORTED/i.test(err.message || err.code || ""))
+          err.streamTermination = "stream_terminated";
+        else err.streamTermination = "stream_error";
+      }
+      throw err;
+    } finally {
+      // Best-effort: cancel the body so the underlying socket returns to the
+      // connection pool even if the consumer bailed mid-stream.
+      try { await resp.body?.cancel?.(); } catch { /* ignore */ }
     }
   }
 
@@ -261,6 +306,8 @@ export class LLMClient {
 
     for await (const chunk of body) {
       buffer += decoder.decode(chunk, { stream: true });
+      // A5: bail out before O(n²) split explodes on pathological input.
+      if (buffer.length > SSE_BUFFER_CAP_BYTES) throw new SseOverflowError(buffer.length);
       const lines = buffer.split("\n");
       buffer = lines.pop();
 
@@ -313,6 +360,8 @@ export class LLMClient {
 
     for await (const rawChunk of body) {
       buffer += decoder.decode(rawChunk, { stream: true });
+      // A5: cap applies to both SSE parsers.
+      if (buffer.length > SSE_BUFFER_CAP_BYTES) throw new SseOverflowError(buffer.length);
       const lines = buffer.split("\n");
       buffer = lines.pop();
 

package/src/agent/pipelines/distillation.js

@@ -40,6 +40,13 @@ export class DistillationEngine extends Pipeline {
   }
 
   _scanWorkflows() {
+    // v0.6.1 A6: preserve engine-emitted entries across filesystem rescans.
+    // workflow_run hook bumps workflowsTested[ruleId] and adds to
+    // workflowsPassing on success — without this preservation, those entries
+    // get clobbered on the next describeState() / onToolResult() rescan.
+    const engineWfTested = { ...this.workflowsTested };
+    const engineWfPassing = [...this.workflowsPassing];
+
     this.workflowsCreated = {};
     this.workflowsTested = {};
     this.workflowsPassing = [];
@@ -68,6 +75,14 @@ export class DistillationEngine extends Pipeline {
         this.workflowsCreated[path.parse(e.name).name] = 1;
       }
     }
+
+    // Re-merge engine-emitted entries on top of filesystem-derived state
+    for (const [k, v] of Object.entries(engineWfTested)) {
+      if (!(k in this.workflowsTested)) this.workflowsTested[k] = v;
+    }
+    for (const id of engineWfPassing) {
+      if (!this.workflowsPassing.includes(id)) this.workflowsPassing.push(id);
+    }
   }
 
   describeState() {

package/src/agent/pipelines/extraction.js

@@ -11,6 +11,11 @@ export class RuleExtractionPipeline extends Pipeline {
     this.rulesExtracted = [];
     this.rulesWithTests = [];
     this.coverageAudited = false;
+    // v0.6.1 A1: track which rules in catalog.json have non-empty
+    // source_chunk_ids — D1 grounded skill_authoring prompts on these but
+    // exit didn't require them, so a sloppy extraction could leave rules
+    // unmoored.
+    this.rulesWithChunkRefs = [];
     this._scanWorkspace();
   }
 
@@ -28,11 +33,21 @@ export class RuleExtractionPipeline extends Pipeline {
 
   _scanRules() {
     this.rulesExtracted = [];
+    this.rulesWithChunkRefs = [];
     const catalogPath = path.join(this._workspace.cwd, "rules", "catalog.json");
     if (fs.existsSync(catalogPath)) {
       try {
         const data = JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
-        if (Array.isArray(data)) this.rulesExtracted = data.map((r, i) => r.id || `rule_${i}`);
+        if (Array.isArray(data)) {
+          this.rulesExtracted = data.map((r, i) => r.id || `rule_${i}`);
+          // A1: collect ids whose entry has non-empty source_chunk_ids
+          for (const r of data) {
+            const ids = r?.source_chunk_ids;
+            if (Array.isArray(ids) && ids.length > 0 && r?.id) {
+              this.rulesWithChunkRefs.push(r.id);
+            }
+          }
+        }
       } catch { /* skip */ }
     }
     const skillsDir = path.join(this._workspace.cwd, "rule_skills");
@@ -67,10 +82,43 @@ export class RuleExtractionPipeline extends Pipeline {
       parts.push("### Exit\nExtraction complete. Proceed to SKILL_AUTHORING.");
     }
 
-    parts.push(`### Exit criteria\n- [${this.regulationsScanned ? "x" : " "}] All regulations read\n- [${this.rulesExtracted.length > 0 ? "x" : " "}] Rules decomposed into atomic units\n- [${this.rulesWithTests.length >= Math.max(this.rulesExtracted.length * 0.8, 1) ? "x" : " "}] >=80% of rules have test stubs\n- [${this.coverageAudited ? "x" : " "}] Coverage audit completed`);
+    const chunkRefsOk = this._chunkRefsCriterionMet();
+    parts.push(
+      `### Exit criteria\n` +
+      `- [${this.regulationsScanned ? "x" : " "}] All regulations read\n` +
+      `- [${this.rulesExtracted.length > 0 ? "x" : " "}] Rules decomposed into atomic units\n` +
+      `- [${this.rulesWithTests.length >= Math.max(this.rulesExtracted.length * 0.8, 1) ? "x" : " "}] >=80% of rules have test stubs\n` +
+      `- [${this.coverageAudited ? "x" : " "}] Coverage audit completed\n` +
+      `- [${chunkRefsOk ? "x" : " "}] Every rule has source_chunk_ids in catalog.json (${this.rulesWithChunkRefs.length}/${this._catalogRuleCount()})`,
+    );
     return parts.join("\n\n");
   }
 
+  /**
+   * v0.6.1 A1: number of rules currently in catalog.json (not the union with
+   * rule_skills/ dirs that rulesExtracted carries). Used by the chunk-refs
+   * gate so we compare apples to apples.
+   */
+  _catalogRuleCount() {
+    const catalogPath = path.join(this._workspace.cwd, "rules", "catalog.json");
+    if (!fs.existsSync(catalogPath)) return 0;
+    try {
+      const data = JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+      return Array.isArray(data) ? data.length : 0;
+    } catch { return 0; }
+  }
+
+  /**
+   * v0.6.1 A1: pass when every rule in catalog.json has a non-empty
+   * source_chunk_ids array. Empty catalog (legacy / pre-D1 sessions) passes
+   * trivially so resume of v0.6.0 sessions doesn't get trapped.
+   */
+  _chunkRefsCriterionMet() {
+    const total = this._catalogRuleCount();
+    if (total === 0) return true; // backwards-compat for sessions pre-D1
+    return this.rulesWithChunkRefs.length >= total;
+  }
+
   onToolResult(toolName, toolInput, result) {
     if (result.isError) return null;
     const wasReady = this.exitCriteriaMet();
@@ -85,7 +133,12 @@ export class RuleExtractionPipeline extends Pipeline {
 
   exitCriteriaMet() {
     return this.regulationsScanned && this.rulesExtracted.length > 0 &&
-      this.rulesWithTests.length >= Math.max(this.rulesExtracted.length * 0.8, 1) && this.coverageAudited;
+      this.rulesWithTests.length >= Math.max(this.rulesExtracted.length * 0.8, 1) &&
+      this.coverageAudited &&
+      // v0.6.1 A1: hard tracking — D1 source-context auto-attach requires
+      // catalog.json entries to carry source_chunk_ids. Without them the
+      // skill_authoring prompts are blind.
+      this._chunkRefsCriterionMet();
   }
 
   exportState() {
@@ -93,6 +146,7 @@ export class RuleExtractionPipeline extends Pipeline {
       regulationsScanned: this.regulationsScanned,
       rulesExtracted: this.rulesExtracted,
       rulesWithTests: this.rulesWithTests,
+      rulesWithChunkRefs: this.rulesWithChunkRefs,
       coverageAudited: this.coverageAudited,
     };
   }
@@ -107,5 +161,8 @@ export class RuleExtractionPipeline extends Pipeline {
     if (Array.isArray(data.rulesWithTests) && data.rulesWithTests.length > this.rulesWithTests.length) {
       this.rulesWithTests = data.rulesWithTests;
     }
+    if (Array.isArray(data.rulesWithChunkRefs) && data.rulesWithChunkRefs.length > this.rulesWithChunkRefs.length) {
+      this.rulesWithChunkRefs = data.rulesWithChunkRefs;
+    }
   }
 }

package/src/agent/pipelines/finalization.js

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PipelineEvent } from "./index.js";
+import { Pipeline } from "./base.js";
+import { normalizeRuleCatalog } from "../rule-catalog-normalize.js";
+
+/**
+ * E1: FINALIZATION — the 7th phase. Runs after PRODUCTION_QC has shown
+ * the system working. Goal: turn the working system into a shippable
+ * deliverable.
+ *
+ * Responsibilities (observed via this pipeline's describeState + exit
+ * criteria; the agent does the actual work using workspace_file +
+ * sandbox_exec):
+ *   1. rule_skills/README.md  — inventory + how-to-run section.
+ *   2. rule_skills/coverage_report.md  — rule-id → skill-file mapping,
+ *      including which rules are "not_applicable" per D6 classification.
+ *   3. output/final_dashboard.html  — snapshot of the final metrics.
+ *   4. (Optional) Reorganized rule_skills/<rule_id>/ canonical layout:
+ *      when skills were written grouped (check_r002_r007.py), create
+ *      thin-link dirs for each constituent rule_id pointing at the
+ *      grouped file. Skipped if rule_skills/ is already per-rule.
+ *
+ * Exit criteria: all three deliverable files exist. The agent is free
+ * to produce more artifacts; these are the minimum-viable finalization
+ * set the pipeline requires before marking the release-ready.
+ *
+ * No successor phase — this is the terminal state. The agent can
+ * continue working in this phase (e.g. producing additional dashboards
+ * on request), but auto-advance stops here.
+ */
+export class FinalizationPipeline extends Pipeline {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+    this.readmeWritten = false;
+    this.coverageReportWritten = false;
+    this.finalDashboardWritten = false;
+    this.canonicalLayoutDone = false;
+    this._scanWorkspace();
+  }
+
+  _scanWorkspace() {
+    const cwd = this._workspace.cwd;
+    this.readmeWritten = fs.existsSync(path.join(cwd, "rule_skills", "README.md"));
+    this.coverageReportWritten = fs.existsSync(path.join(cwd, "rule_skills", "coverage_report.md"));
+    this.finalDashboardWritten = fs.existsSync(path.join(cwd, "output", "final_dashboard.html"));
+    // Canonical layout: every rule_id in the catalog has a dedicated
+    // directory OR a thin-link stub under rule_skills/<rule_id>/. When
+    // skills are already per-rule (every rule has its own dir) this is
+    // trivially true. When skills are grouped, the agent creates
+    // per-rule stub dirs that reference the grouped file. We approximate
+    // "canonical" by checking: does every catalog rule_id have a
+    // matching directory under rule_skills/?
+    this.canonicalLayoutDone = this._checkCanonicalLayout();
+  }
+
+  _checkCanonicalLayout() {
+    const cwd = this._workspace.cwd;
+    const catalogPath = path.join(cwd, "rules", "catalog.json");
+    const skillsDir = path.join(cwd, "rule_skills");
+    if (!fs.existsSync(catalogPath) || !fs.existsSync(skillsDir)) return false;
+    let rules;
+    try {
+      rules = normalizeRuleCatalog(JSON.parse(fs.readFileSync(catalogPath, "utf-8")));
+    } catch { return false; }
+    if (rules.length === 0) return false;
+
+    let existingDirs;
+    try {
+      existingDirs = new Set(
+        fs.readdirSync(skillsDir, { withFileTypes: true })
+          .filter((e) => e.isDirectory())
+          .map((e) => e.name),
+      );
+    } catch { return false; }
+
+    // Every rule id should have a matching directory. Directory name
+    // matches rule id (R014) OR falls inside a range dir (R078_R128).
+    const rangeDirs = [...existingDirs].map((name) => {
+      const m = name.match(/^R0*(\d+)[_-]R0*(\d+)$/i);
+      if (m) return { name, lo: parseInt(m[1], 10), hi: parseInt(m[2], 10) };
+      return null;
+    }).filter(Boolean);
+
+    for (const r of rules) {
+      if (!r.id) continue;
+      if (existingDirs.has(r.id)) continue;
+      const m = r.id.match(/^R0*(\d+)$/i);
+      if (m) {
+        const n = parseInt(m[1], 10);
+        if (rangeDirs.some((rd) => rd.lo <= n && n <= rd.hi)) continue;
+      }
+      return false;
+    }
+    return true;
+  }
+
+  describeState() {
+    this._scanWorkspace();
+    const checklist = [
+      `- ${this.readmeWritten ? "✅" : "⏳"}  rule_skills/README.md`,
+      `- ${this.coverageReportWritten ? "✅" : "⏳"}  rule_skills/coverage_report.md`,
+      `- ${this.finalDashboardWritten ? "✅" : "⏳"}  output/final_dashboard.html`,
+      `- ${this.canonicalLayoutDone ? "✅" : "⏳"}  rule_skills/ canonical per-rule layout`,
+    ];
+    const parts = [
+      "## Phase: FINALIZATION\n" +
+      "Turn the working verification system into a shippable deliverable. The " +
+      "pipeline has completed end-to-end; now package it for handoff. This is " +
+      "the terminal phase — no successor. You can continue producing artifacts " +
+      "here on request.\n\n" +
+      "**Tasks to complete** (the pipeline considers the phase done when all " +
+      "four checkmarks are green):\n\n" +
+      checklist.join("\n") + "\n\n" +
+      "### What each artifact should contain\n\n" +
+      "- **README.md**: top of `rule_skills/` with file inventory, how to run " +
+      "  `run_all_checks.py` (if present), input format, expected output format, " +
+      "  dependencies, and a short 'what this does' for a reader who hasn't " +
+      "  seen the project.\n" +
+      "- **coverage_report.md**: one row per rule_id in catalog.json. Columns: " +
+      "  rule_id, source_ref, skill file (`check_r014.py` or `check_r002_r007.py`), " +
+      "  tested (Y/N), latest accuracy, retries, applicable-to-this-bundle " +
+      "  (Y/N from D6 classification). Rules marked not_applicable should be " +
+      "  grouped at the bottom with a note explaining which bundle-type " +
+      "  filtered them out.\n" +
+      "- **final_dashboard.html**: single-page snapshot. Reuse the " +
+      "  `dashboard_render` tool — it knows the metrics shape. This is the " +
+      "  hand-off artifact the developer user opens to see the final state.\n" +
+      "- **canonical layout**: the simplest check is `ls rule_skills/ | " +
+      "  wc -l` ≈ number of rules in the catalog. When grouped files exist " +
+      "  (`check_r002_r007.py`), create stub `rule_skills/R002/` through " +
+      "  `rule_skills/R007/` each containing a one-line SKILL.md that points " +
+      "  at the grouped file. This keeps downstream per-rule lookups simple.",
+    ];
+    return parts.join("\n\n");
+  }
+
+  onToolResult(toolName, toolInput, result) {
+    if (result.isError) return null;
+    const wasReady = this.exitCriteriaMet();
+    const touchedPath = String(
+      toolInput?.path || toolInput?.command || "",
+    );
+    // Re-scan when the agent writes to any relevant path
+    if (
+      touchedPath.includes("rule_skills/") ||
+      touchedPath.includes("output/final_dashboard") ||
+      touchedPath.includes("coverage_report")
+    ) {
+      this._scanWorkspace();
+    }
+    if (!wasReady && this.exitCriteriaMet()) {
+      // Terminal phase — no nextPhase. Pipeline event signals "done."
+      return new PipelineEvent({
+        type: "phase_ready",
+        message: "Finalization artifacts complete. Session deliverable is ready.",
+        nextPhase: null,
+      });
+    }
+    return null;
+  }
+
+  exitCriteriaMet() {
+    return this.readmeWritten &&
+      this.coverageReportWritten &&
+      this.finalDashboardWritten &&
+      this.canonicalLayoutDone;
+  }
+
+  exportState() {
+    return {
+      readmeWritten: this.readmeWritten,
+      coverageReportWritten: this.coverageReportWritten,
+      finalDashboardWritten: this.finalDashboardWritten,
+      canonicalLayoutDone: this.canonicalLayoutDone,
+    };
+  }
+
+  importState(data) {
+    if (typeof data?.readmeWritten === "boolean") this.readmeWritten = data.readmeWritten;
+    if (typeof data?.coverageReportWritten === "boolean") this.coverageReportWritten = data.coverageReportWritten;
+    if (typeof data?.finalDashboardWritten === "boolean") this.finalDashboardWritten = data.finalDashboardWritten;
+    if (typeof data?.canonicalLayoutDone === "boolean") this.canonicalLayoutDone = data.canonicalLayoutDone;
+  }
+}

package/src/agent/pipelines/index.js

@@ -1,5 +1,12 @@
 /**
  * Pipeline phases — sequential workflow of the KC Agent methodology.
+ *
+ * v0.6.0 E1: FINALIZATION added as the 7th phase. It's a cleanup /
+ * deliverable-packaging phase that runs after PRODUCTION_QC has
+ * established the system is operating correctly: reorganize
+ * rule_skills/ into a canonical layout, write README + coverage
+ * report, snapshot a final dashboard, archive stale retry outputs.
+ * Short phase, a handful of tasks, driven by a finalization skill.
  */
 export const Phase = Object.freeze({
   BOOTSTRAP: "bootstrap",
@@ -8,6 +15,7 @@ export const Phase = Object.freeze({
   SKILL_TESTING: "skill_testing",
   DISTILLATION: "distillation",
   PRODUCTION_QC: "production_qc",
+  FINALIZATION: "finalization",
 });
 
 /**

package/src/agent/pipelines/initializer.js

@@ -138,6 +138,31 @@ export class ProjectInitializer extends Pipeline {
     this.configReady = !!gc.api_key;
   }
 
+  /**
+   * F1b: Worker LLM health snapshot. Static check only — inspect whether
+   * TIER1-4 and OCR_MODEL_TIER1 are populated in .env. Does NOT make
+   * network calls — a live ping would be invasive for bootstrap (slow,
+   * charges money, and the worker LLM isn't actually used until
+   * DISTILLATION). Surfacing the config state is enough for bootstrap.
+   * The agent can then decide to validate via worker_llm_call later if
+   * warranted. Returns null when no .env exists yet.
+   */
+  _workerConfigSnapshot() {
+    const envPath = path.join(this._workspace.cwd, ".env");
+    if (!fs.existsSync(envPath)) return null;
+    const tiers = { TIER1: "", TIER2: "", TIER3: "", TIER4: "", OCR_MODEL_TIER1: "" };
+    try {
+      for (const line of fs.readFileSync(envPath, "utf-8").split("\n")) {
+        for (const k of Object.keys(tiers)) {
+          if (line.startsWith(`${k}=`)) {
+            tiers[k] = line.slice(k.length + 1).trim();
+          }
+        }
+      }
+    } catch { return null; }
+    return tiers;
+  }
+
   _loadGlobalConfig() {
     const p = path.join(os.homedir(), ".kc_agent", "config.json");
     if (fs.existsSync(p)) { try { return JSON.parse(fs.readFileSync(p, "utf-8")); } catch { /* skip */ } }
@@ -158,6 +183,21 @@ export class ProjectInitializer extends Pipeline {
     if (completed.length) parts.push("### Done\n" + completed.map((c) => `- [x] ${c}`).join("\n"));
     if (pending.length) parts.push("### Needed\n" + pending.map((p) => `- [ ] ${p}`).join("\n"));
 
+    // F1b: surface worker-LLM tier status as part of bootstrap state so
+    // the agent can flag missing tiers to the developer user upfront,
+    // rather than hitting "worker LLM unreachable" hours later during
+    // DISTILLATION. Static inspection only — no network calls.
+    const workerConfig = this._workerConfigSnapshot();
+    if (workerConfig) {
+      const tierLines = [];
+      for (const [k, v] of Object.entries(workerConfig)) {
+        if (v) tierLines.push(`- ${k}: ${v}`);
+        else tierLines.push(`- ${k}: ⚠️ (empty — set before DISTILLATION, or worker_llm_call tools will fail)`);
+      }
+      parts.push("### Worker LLM tiers (.env snapshot)\n" + tierLines.join("\n") +
+        "\n\nThese drive `worker_llm_call`, `workflow_run`, `document_parse` OCR, etc. Empty tiers don't block bootstrap — but DISTILLATION requires at least TIER1 to be live. Discuss with the developer user if any are missing.");
+    }
+
     if (this.exitCriteriaMet()) {
       parts.push("### Exit\nBootstrap requirements met. Proceed to EXTRACTION.");
     }

package/src/agent/pipelines/production-qc.js

@@ -36,6 +36,11 @@ export class ProductionQCPipeline extends Pipeline {
   }
 
   _scanQcResults() {
+    // v0.6.1 A5/A6: don't reset documentsReviewed if engine emission has
+    // bumped it since last scan — workflow_run hooks call _recordMilestone
+    // and the increment lives in this same field. Other counters (batches,
+    // accuracy, issues) come solely from filesystem scan and reset cleanly.
+    const engineDocsReviewed = this.documentsReviewed;
     this.batchesProcessed = 0;
     this.totalDocuments = 0;
     this.documentsReviewed = 0;
@@ -43,23 +48,57 @@ export class ProductionQCPipeline extends Pipeline {
     this.confidenceDistribution = { low: 0, medium: 0, high: 0 };
     this.issuesFound = [];
 
+    // Existing canonical path: output/qc/*.json (formal QC batch reports)
     const qcDir = path.join(this._workspace.cwd, "output", "qc");
-    if (!fs.existsSync(qcDir)) return;
+    if (fs.existsSync(qcDir)) {
+      for (const f of fs.readdirSync(qcDir).filter((f) => f.endsWith(".json")).sort()) {
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(qcDir, f), "utf-8"));
+          this.batchesProcessed++;
+          this.totalDocuments += typeof data.documents === "number" ? data.documents : (data.total || 0);
+          this.documentsReviewed += data.reviewed || 0;
+          if (data.accuracy_by_rule) Object.assign(this.accuracyByRule, data.accuracy_by_rule);
+          if (data.confidence) {
+            for (const band of ["low", "medium", "high"]) this.confidenceDistribution[band] += data.confidence[band] || 0;
+          }
+          if (Array.isArray(data.issues)) this.issuesFound.push(...data.issues);
+        } catch { /* skip */ }
+      }
+    }
 
-    for (const f of fs.readdirSync(qcDir).filter((f) => f.endsWith(".json")).sort()) {
-      try {
-        const data = JSON.parse(fs.readFileSync(path.join(qcDir, f), "utf-8"));
+    // v0.6.1 A5: also pick up batch-style results in output/results/. E2E #4
+    // showed agents writing batch QC outputs to output/results/qc_*.json
+    // (e.g. unified_qc.py) instead of output/qc/, so the formal scanner
+    // missed them. Heuristic match: filename starts with "qc_" or contains
+    // "_batch_". Each match counts as one batch; total_checks → totalDocuments.
+    const resultsDir = path.join(this._workspace.cwd, "output", "results");
+    if (fs.existsSync(resultsDir)) {
+      const seen = new Set();
+      for (const f of fs.readdirSync(resultsDir).filter((f) => f.endsWith(".json"))) {
+        const lower = f.toLowerCase();
+        if (!(lower.startsWith("qc_") || lower.includes("_batch_"))) continue;
+        // Dedupe near-duplicate filenames that differ only by timestamp
+        // suffix (qc_full_batch_20260424_141642.json vs _141921.json
+        // — both are real batches, keep both. But qc_pt_x.json and
+        // qc_pt_x_<ts>.json are usually the same batch saved twice; key
+        // on the prefix before any 8-digit date.)
+        const key = f.replace(/_\d{8}_\d{6}/g, "").replace(/\.json$/, "");
+        if (seen.has(key)) continue;
+        seen.add(key);
         this.batchesProcessed++;
-        this.totalDocuments += typeof data.documents === "number" ? data.documents : (data.total || 0);
-        this.documentsReviewed += data.reviewed || 0;
-        if (data.accuracy_by_rule) Object.assign(this.accuracyByRule, data.accuracy_by_rule);
-        if (data.confidence) {
-          for (const band of ["low", "medium", "high"]) this.confidenceDistribution[band] += data.confidence[band] || 0;
-        }
-        if (Array.isArray(data.issues)) this.issuesFound.push(...data.issues);
-      } catch { /* skip */ }
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(resultsDir, f), "utf-8"));
+          // Best-effort metric extraction; tolerate missing keys
+          this.totalDocuments += typeof data.sample_count === "number" ? data.sample_count
+            : typeof data.documents === "number" ? data.documents
+            : typeof data.total === "number" ? data.total : 0;
+        } catch { /* skip */ }
+      }
     }
 
+    // Restore engine-emitted documentsReviewed if filesystem reported less
+    if (engineDocsReviewed > this.documentsReviewed) this.documentsReviewed = engineDocsReviewed;
+
     // Determine monitoring phase
     if (this.batchesProcessed < 3) this.monitoringPhase = "initial";
     else if (this.issuesFound.length > 0) this.monitoringPhase = "active";
@@ -93,7 +132,18 @@ export class ProductionQCPipeline extends Pipeline {
     return null;
   }
 
-  exitCriteriaMet() { return this.monitoringPhase === "stable"; }
+  /**
+   * v0.6.1 A5: gate requires at least one batch processed (real telemetry)
+   * AND the legacy stable-monitoring criterion. Without the batch floor, the
+   * agent could declare PRODUCTION_QC done from a clean session-state file
+   * (E2E #4: phase advanced into PRODUCTION_QC, agent ran 6,930 checks via
+   * sandbox_exec to non-canonical paths, batchesProcessed stayed 0, exit
+   * fired anyway because monitoringPhase defaults can flip to "stable" with
+   * empty accuracyByRule + zero issues).
+   */
+  exitCriteriaMet() {
+    return this.batchesProcessed > 0 && this.monitoringPhase === "stable";
+  }
 
   exportState() {
     return {