@hadooppei/hwcode 1.0.19 → 1.0.22

package/.pi/extensions/knowledge.ts

@@ -1,4 +1,3 @@
-import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -22,6 +21,7 @@ interface ActiveReview {
   leaderToken: string;
   controller: AbortController;
   abortReason?: string;
+  diagnostic?: string;
 }
 
 interface ProcessKnowledgeRuntime {
@@ -53,7 +53,7 @@ function compactReviewEvidence(task: KnowledgeReviewTask): {
   let characters = 0;
   const add = (item: KnowledgeEvidence | undefined): void => {
     if (!item || seen.has(item.id) || selected.length >= KNOWLEDGE_RUNTIME_DEFAULTS.review.maxEvidenceItems) return;
-    const compact = { ...item, excerpt: item.excerpt.slice(0, 500) };
+    const compact = { ...item, excerpt: item.excerpt.slice(0, 800) };
     const size = JSON.stringify(compact).length;
     if (characters + size > KNOWLEDGE_RUNTIME_DEFAULTS.review.maxEvidenceChars) return;
     selected.push(compact);
@@ -117,7 +117,7 @@ function reportWorkerIssue(error: unknown): void {
   const prior = runtime.lastWorkerIssue;
   if (prior?.message === message && now - prior.reportedAt < 60_000) return;
   runtime.lastWorkerIssue = { message, reportedAt: now };
-  const rendered = `HWCode knowledge worker failed: ${message}`;
+  const rendered = `HWCode knowledge worker failed: ${message.slice(0, 600)}`;
   if (runtime.context?.hasUI) runtime.context.ui.notify(rendered, "error");
   else console.error(rendered);
 }
@@ -162,7 +162,7 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
     runtime.activeReview = review;
     timeout = setTimeout(() => {
       if (controller.signal.aborted) return;
-      review!.abortReason = "knowledge-review-model-timeout";
+      review!.abortReason = `knowledge-review-model-timeout after ${KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs}ms${review!.diagnostic ? `; ${review!.diagnostic}` : ""}`;
       controller.abort();
     }, KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs);
     timeout.unref();
@@ -182,13 +182,20 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
       seenRelated.add(entry.id);
     };
     const episodeMatches = (message.task.episodes ?? []).map((episode) => (
-      matchKnowledge(`${episode.title}\n${episode.query}`, applicableCatalog, 2)
+      matchKnowledge(
+        `${episode.title}\n${episode.query}`,
+        applicableCatalog,
+        KNOWLEDGE_RUNTIME_DEFAULTS.review.maxExistingContextItems,
+      )
     ));
-    for (const matches of episodeMatches.slice(0, 3)) addRelated(matches[0]);
+    for (const matches of episodeMatches) addRelated(matches[0]);
     for (const id of message.task.loadedKnowledgeIds ?? []) {
       addRelated(applicableCatalog.items.find((entry) => entry.id === id));
     }
-    for (const matches of episodeMatches) for (const entry of matches.slice(1)) addRelated(entry);
+    const matchDepth = Math.max(0, ...episodeMatches.map((matches) => matches.length));
+    for (let rank = 1; rank < matchDepth; rank++) {
+      for (const matches of episodeMatches) addRelated(matches[rank]);
+    }
     for (const entry of matchKnowledge(
       message.task.recallQuery || message.task.delta,
       applicableCatalog,
@@ -210,6 +217,28 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
         .slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxExistingBodyChars);
       return content ? { ...reference, content } : reference;
     });
+    const prompt = buildKnowledgeExtractionPrompt(
+      message.task.projectRoot,
+      message.task.delta.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxNarrativeChars),
+      message.task.context,
+      related,
+      promptContext.evidence,
+      promptContext.episodes,
+    );
+    const diagnostic = [
+      `reviewKey=${message.task.reviewKey}`,
+      `model=${ctx.model.provider}/${ctx.model.id}`,
+      `promptChars=${prompt.length}`,
+      `deltaChars=${message.task.delta.length}`,
+      `evidenceItems=${promptContext.evidence.length}`,
+      `episodeItems=${promptContext.episodes.length}`,
+      `existingItems=${related.length}`,
+    ];
+    const requestStartedAt = Date.now();
+    const setRequestPhase = (phase: string): void => {
+      review!.diagnostic = [...diagnostic, `phase=${phase}`, `requestElapsedMs=${Date.now() - requestStartedAt}`].join("; ");
+    };
+    setRequestPhase("preparing-request");
     const response = await ctx.modelRegistry.complete(
       ctx.model,
       {
@@ -218,29 +247,41 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
           role: "user",
           content: [{
             type: "text",
-            text: buildKnowledgeExtractionPrompt(
-              message.task.projectRoot,
-              message.task.delta.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxNarrativeChars),
-              message.task.context,
-              related,
-              promptContext.evidence,
-              promptContext.episodes,
-            ),
+            text: prompt,
           }],
           timestamp: Date.now(),
         }],
       },
-      { signal: controller.signal, reasoningEffort: "low", cacheRetention: "none", sessionId: randomUUID() },
+      {
+        signal: controller.signal,
+        reasoningEffort: "low",
+        cacheRetention: "none",
+        temperature: 0,
+        maxTokens: KNOWLEDGE_RUNTIME_DEFAULTS.review.maxOutputTokens,
+        timeoutMs: KNOWLEDGE_RUNTIME_DEFAULTS.review.requestTimeoutMs,
+        maxRetries: 0,
+        onPayload: () => { setRequestPhase("awaiting-http-response"); },
+        onResponse: (providerResponse: { status: number }) => {
+          setRequestPhase(`streaming-response-http-${providerResponse.status}`);
+        },
+      },
     );
     if (controller.signal.aborted) throw new Error(review.abortReason ?? "knowledge-review-interrupted");
+    if (response.stopReason === "error" || response.stopReason === "aborted") {
+      throw new Error(response.errorMessage ?? `knowledge-review-model-${response.stopReason}`);
+    }
     const raw = response.content.filter((item): item is { type: "text"; text: string } => item.type === "text")
       .map((item) => item.text).join("\n");
     post({ type: "review_result", leaderToken: message.leaderToken, requestId: message.requestId, raw });
   } catch (error) {
-    const reason = review?.controller.signal.aborted
+    const baseReason = review?.controller.signal.aborted
       ? review.abortReason ?? "knowledge-review-interrupted"
       : error instanceof Error ? error.message : String(error);
-    if (reason === "model-executor-is-busy" || isExpectedReviewInterruption(reason)) {
+    const expectedInterruption = baseReason === "model-executor-is-busy" || isExpectedReviewInterruption(baseReason);
+    const reason = review?.diagnostic && !expectedInterruption && !baseReason.includes("reviewKey=")
+      ? `${baseReason}; ${review.diagnostic}`
+      : baseReason;
+    if (expectedInterruption) {
       post({ type: "review_deferred", leaderToken: message.leaderToken, requestId: message.requestId, reason });
     } else {
       post({ type: "review_result", leaderToken: message.leaderToken, requestId: message.requestId, error: reason });
@@ -263,7 +304,7 @@ function handleWorkerMessage(message: KnowledgeWorkerOutput): void {
     cancelActiveReview(message.reason);
     return;
   }
-  if (message.type === "review_failed") reportWorkerIssue(message.error);
+  if (message.type === "review_failed" && message.terminal !== false) reportWorkerIssue(message.error);
 }
 
 function ensureWorker(): Worker | undefined {

package/.pi/extensions/workflows/cloud/provider-tools.ts

@@ -8,7 +8,9 @@ import { toolError, toolOk } from "../../../lib/tool-result.ts";
 import { evaluateCommandArgumentsAccess } from "../../../lib/workspace/access-policy.ts";
 import { prepareCloudExecution } from "../../../lib/workflows/cloud/adapters.ts";
 import { cloudExecutionBlockReason, recordStrategyFailure } from "../../../lib/workflows/cloud/execution.ts";
-import { runProcess, truncateOutput, type ProcessResult } from "../../../lib/workflows/cloud/process.ts";
+import {
+  cloudProviderFailureReason, runProcess, truncateOutput, type ProcessResult,
+} from "../../../lib/workflows/cloud/process.ts";
 import { CLOUD_EXECUTABLES, classifyCloudOperation, getCloudProvider, redactCredentialValues, type CloudOperation } from "../../../lib/workflows/cloud/providers.ts";
 import { cloudArtifactDirectory } from "../../../lib/workflows/cloud/workspace.ts";
 import { WORKFLOW_EXTERNAL_AUDIT_TYPE, cloudDetails } from "../../../lib/workflows/state.ts";
@@ -106,16 +108,44 @@ export function registerCloudProviderTools(pi: ExtensionAPI, runtime: CloudExten
           : await runProcess(params.command, prepared.args, { cwd: cloudArtifactDirectory(activeState), env: prepared.env, signal });
       } finally { prepared.cleanup?.(); }
 
-      const stdout = truncateOutput(redactCredentialValues(result.stdout, credentials));
-      const stderr = truncateOutput(redactCredentialValues(result.stderr, credentials));
-      pi.appendEntry(CLOUD_AUDIT_TYPE, { vendor: details.vendor, command: params.command, operation, intent: params.intent, approach: params.approach, exitCode: result.code, executedAt: new Date().toISOString() });
-      if (result.code !== 0) {
-        const failed = recordStrategyFailure(details, params.approach, params.command, stderr.trim() || stdout.trim() || `exit code ${result.code}`, CLOUD_RUNTIME_DEFAULTS.workflow.maxFailedApproaches);
+      const redactedStdout = redactCredentialValues(result.stdout, credentials);
+      const redactedStderr = redactCredentialValues(result.stderr, credentials);
+      const providerFailure = cloudProviderFailureReason(redactedStdout, redactedStderr);
+      const stdout = truncateOutput(redactedStdout);
+      const stderr = truncateOutput(redactedStderr);
+      const failureReason = result.code !== 0
+        ? stderr.trim() || stdout.trim() || `exit code ${result.code}`
+        : providerFailure;
+      pi.appendEntry(CLOUD_AUDIT_TYPE, {
+        vendor: details.vendor,
+        command: params.command,
+        operation,
+        intent: params.intent,
+        approach: params.approach,
+        exitCode: result.code,
+        outcome: failureReason ? "failed" : "succeeded",
+        providerFailure: providerFailure ? safeStepText(providerFailure, credentials) : undefined,
+        executedAt: new Date().toISOString(),
+      });
+      if (failureReason) {
+        const failed = recordStrategyFailure(details, params.approach, params.command, failureReason, CLOUD_RUNTIME_DEFAULTS.workflow.maxFailedApproaches);
         runtime.replaceDetails(activeState, failed, failed.terminalFailure ? "failed" : "executing");
         const suffix = failed.terminalFailure
           ? "\n\nTERMINAL FAILURE: Three materially different approaches failed. Explain causes and summarize progress and changes. Do not try another cloud operation."
           : `\n\nDistinct failed approaches: ${failed.failedApproaches.length}/${CLOUD_RUNTIME_DEFAULTS.workflow.maxFailedApproaches}.`;
-        return { content: [{ type: "text" as const, text: `Cloud command failed with exit code ${result.code}.\n${stderr || stdout}${suffix}` }], isError: true, details: { operation, exitCode: result.code, terminalFailure: failed.terminalFailure } };
+        const heading = result.code !== 0
+          ? `Cloud command failed with exit code ${result.code}.`
+          : "Cloud provider reported a failure despite exit code 0.";
+        return {
+          content: [{ type: "text" as const, text: `${heading}\n${stderr || stdout || providerFailure}${suffix}` }],
+          isError: true,
+          details: {
+            operation,
+            exitCode: result.code,
+            providerFailure: Boolean(providerFailure),
+            terminalFailure: failed.terminalFailure,
+          },
+        };
       }
 
       const successfulSteps = [...details.successfulSteps, {

package/.pi/lib/knowledge/evidence.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 
-import { sanitizeKnowledgeText } from "./sanitize.ts";
+import { containsInjectedSkill, sanitizeKnowledgeText } from "./sanitize.ts";
 import type { KnowledgeEpisode, KnowledgeEvidence, KnowledgeEvidenceKind } from "./types.ts";
 
 const FAILURE_RE = /(?:\b(?:error|failed|failure|invalid|unsupported|timeout|timed out|unreachable|servfail|refused)\b|not supported|失败|错误|不支持|超时|无法|不可达)/iu;
@@ -99,8 +99,13 @@ function boundedExcerpt(value: string, limit = 900): string {
   const clean = sanitizeKnowledgeText(value).replace(/\n{3,}/gu, "\n\n").trim();
   if (clean.length <= limit) return clean;
   const lines = clean.split("\n");
-  const significant = lines.filter((line) => FAILURE_RE.test(line) || VERIFICATION_RE.test(line));
-  const selected = [...lines.slice(0, 3), ...significant.slice(0, 5), ...lines.slice(-3)];
+  const priority = (line: string): number => REVERSAL_RE.test(line) ? 0
+    : FAILURE_RE.test(line) && VERIFICATION_RE.test(line) ? 1
+      : FAILURE_RE.test(line) ? 2 : 3;
+  const significant = lines.filter((line) => (
+    REVERSAL_RE.test(line) || FAILURE_RE.test(line) || VERIFICATION_RE.test(line)
+  )).sort((left, right) => priority(left) - priority(right));
+  const selected = [...lines.slice(0, 2), ...significant.slice(0, 7), ...lines.slice(-2)];
   return [...new Set(selected)].join("\n").slice(0, limit);
 }
 
@@ -163,9 +168,8 @@ function evidenceId(entryId: string, suffix: string): string {
   return `ev-${digest(`${entryId}\0${suffix}`)}`;
 }
 
-function outcomeFor(message: Record<string, unknown>, text: string): "success" | "failure" {
-  if (message.isError === true || FAILURE_RE.test(text)) return "failure";
-  return "success";
+function outcomeFor(message: Record<string, unknown>): "success" | "failure" {
+  return message.isError === true ? "failure" : "success";
 }
 
 function userKind(text: string): KnowledgeEvidenceKind {
@@ -200,6 +204,9 @@ export function buildKnowledgeEvidence(entries: SessionEntry[]): KnowledgeEviden
     const role = typeof message.role === "string" ? message.role : "";
     const text = textContent(content).trim();
     if (role === "user" && text) {
+      // Skill bodies and workflow activation envelopes are injected as user-role messages by
+      // the host. They are execution context, not an explicit human directive to persist.
+      if (containsInjectedSkill(text)) return;
       evidence.push({
         id: evidenceId(entryId, "user"), entryId, timestamp, kind: userKind(text),
         subject: "User requirement or correction", outcome: "unknown", excerpt: boundedExcerpt(text, 700),
@@ -209,11 +216,14 @@ export function buildKnowledgeEvidence(entries: SessionEntry[]): KnowledgeEviden
     if (role === "toolResult" && text) {
       const toolCallId = typeof message.toolCallId === "string" ? message.toolCallId : "";
       const call = calls.get(toolCallId);
-      const outcome = outcomeFor(message, text);
+      // Recalled knowledge is comparison context, not fresh execution evidence. Treating a
+      // lookup result as verification would let knowledge reinforce itself merely by loading it.
+      if (call?.name === "hwcode_knowledge_lookup") return;
+      const outcome = outcomeFor(message);
       const callText = call ? `[call] ${call.name}: ${compactArguments(call.args)}\n` : "";
       evidence.push({
         id: evidenceId(entryId, toolCallId || "tool"), entryId, timestamp,
-        kind: outcome === "failure" ? "tool-failure" : VERIFICATION_RE.test(text) ? "verification" : "tool-success",
+        kind: outcome === "failure" ? "tool-failure" : "tool-success",
         subject: evidenceSubject(call, text), operation: operationName(call), outcome,
         excerpt: boundedExcerpt(`${callText}[result] ${text}`),
       });
@@ -222,7 +232,7 @@ export function buildKnowledgeEvidence(entries: SessionEntry[]): KnowledgeEviden
     if (role === "assistant" && text && (FAILURE_RE.test(text) || VERIFICATION_RE.test(text) || REVERSAL_RE.test(text))) {
       evidence.push({
         id: evidenceId(entryId, "assistant"), entryId, timestamp,
-        kind: VERIFICATION_RE.test(text) ? "verification" : "assistant-claim",
+        kind: "assistant-claim",
         subject: "Assistant diagnosis or conclusion", outcome: "unknown", excerpt: boundedExcerpt(text, 800),
       });
     }

package/.pi/lib/knowledge/extractor.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
+import { compactKnowledgeText } from "./sanitize.ts";
 import type { KnowledgeEpisode, KnowledgeEpisodeDecision, KnowledgeEvidence } from "./types.ts";
 
 export interface ExistingKnowledgeContext {
@@ -32,9 +33,11 @@ Treat failed, unsupported, invalid, or corrected operations as negative evidence
 Use storageHint "rule" only for one short imperative instruction of at most 240 characters. A rule must not contain incident narration, example resource names, IDs, timestamps, or evidence details. Use "topic" for multi-step SOPs and detailed experience.
 Rank knowledge by future time saved, repeated failures, hypothesis reversals, user corrections, verified resolution, reuse, and novelty. Do not favor the final task result merely because it completed the objective. Every supplied episode scoring 45 or higher must have an episodeDecisions entry, even when skipped.
 Relevant existing knowledge may be supplied. Cheap recall only proposes related items; it does not prove duplication. Compare execution environment, symptom, and root cause. Use action "reinforce" only when the exact target already covers every claim and there is no new content. Use "extend" for new compatible claims, "correct" when direct evidence disproves old content, "retire" when the whole target is invalid, and "add" for a distinct environment or root cause. Never turn lexical similarity into reinforcement.
+Prefer the most specific existing topic that already covers a claim over a broad conventions or SOP topic.
 Scope may be "global" only for an explicit user directive intended across projects; otherwise use "project".
 The prior validation context is only for checking facts and contradictions; do not persist it again unless the new delta independently reinforces it. Prefer accumulated workflow successfulSteps and failedApproaches over assistant narration.
 Every technical claim must have a stable claim key and cite evidenceIds from the supplied evidence ledger. Tool success, tool failure, and verification evidence outrank assistant narration. Do not support a service-wide or universal claim with one operation-specific failure. Evidence for an unrelated parameter error cannot support an API-version claim.
+Keep each candidate atomic: put separable claim sets in separate candidates, omit any claim without direct cited evidence, and prioritize the highest-value supported candidates. One unsupported claim rejects its entire candidate.
 Each summary must be one complete sentence of at most 160 characters. Keep each topic body under 2200 characters. Escape line breaks and quotes inside JSON strings. Set durability to "stable" only after removing facts likely to change or be cheaply rediscovered. Return at most 3 candidates.
 The body must not repeat the title as a Markdown H1. The storage renderer supplies the H1. Replace any necessary example resource value with an obvious placeholder instead of a real project, namespace, image, network, or resource name.
 Return: {"episodeDecisions":[{"episodeId":"ep-id","decision":"add|reinforce|extend|correct|retire|skip","targetId":"existing-id or omitted","reason":"..."}],"candidates":[{"key":"stable semantic key","identityKey":"platform/runtime/problem/root-cause","targetId":"existing-id or null","episodeIds":["ep-id"],"title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body or only the new section for extend","claims":[{"key":"stable claim key","text":"one precise claim","evidenceIds":["ev-id"]}],"evidenceIds":["ev-id"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|extend|correct|retire","explicitUserDirective":false,"durability":"stable"}]}
@@ -65,25 +68,21 @@ export function buildKnowledgeExtractionPrompt(
 }
 
 export function parseKnowledgeReviewEnvelope(text: string): KnowledgeReviewEnvelope {
-  try {
-    const parsed = parseEnvelopeObject(text);
-    if (!Array.isArray(parsed.candidates)) throw new Error("Knowledge reviewer response is missing candidates[]");
-    const validDecisions = new Set(["add", "reinforce", "extend", "correct", "retire", "skip"]);
-    const decisions = Array.isArray(parsed.episodeDecisions)
-      ? parsed.episodeDecisions.filter((item): item is KnowledgeEpisodeDecision => {
-        if (!item || typeof item !== "object") return false;
-        const value = item as Record<string, unknown>;
-        return typeof value.episodeId === "string" && validDecisions.has(String(value.decision))
-          && typeof value.reason === "string";
-      })
-      : [];
-    return {
-      episodeDecisions: decisions,
-      candidates: parsed.candidates.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates),
-    };
-  } catch {
-    return { episodeDecisions: [], candidates: parseCandidateEnvelope(text) };
-  }
+  const parsed = parseEnvelopeObject(text);
+  if (!Array.isArray(parsed.candidates)) throw new Error("Knowledge reviewer response is missing candidates[]");
+  const validDecisions = new Set(["add", "reinforce", "extend", "correct", "retire", "skip"]);
+  const decisions = Array.isArray(parsed.episodeDecisions)
+    ? parsed.episodeDecisions.filter((item): item is KnowledgeEpisodeDecision => {
+      if (!item || typeof item !== "object") return false;
+      const value = item as Record<string, unknown>;
+      return typeof value.episodeId === "string" && validDecisions.has(String(value.decision))
+        && typeof value.reason === "string";
+    })
+    : [];
+  return {
+    episodeDecisions: decisions,
+    candidates: parsed.candidates.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates),
+  };
 }
 
 function parseEnvelopeObject(text: string): Record<string, unknown> {
@@ -91,68 +90,30 @@ function parseEnvelopeObject(text: string): Record<string, unknown> {
   const unfenced = trimmed.replace(/^```(?:json)?\s*/iu, "").replace(/\s*```$/u, "");
   const start = unfenced.indexOf("{");
   const end = unfenced.lastIndexOf("}");
-  if (start < 0 || end <= start) throw new Error("Knowledge reviewer did not return a JSON object");
-  return JSON.parse(unfenced.slice(start, end + 1)) as Record<string, unknown>;
-}
-
-export function parseCandidateEnvelope(text: string): unknown[] {
-  const trimmed = text.trim();
-  const unfenced = trimmed.replace(/^```(?:json)?\s*/iu, "").replace(/\s*```$/u, "");
-  const start = unfenced.indexOf("{");
-  const end = unfenced.lastIndexOf("}");
-  if (start < 0 || end <= start) throw new Error("Knowledge reviewer did not return a JSON object");
-  let strictError: unknown;
+  if (start < 0 || end <= start) {
+    throw new Error([
+      "Knowledge reviewer did not return a complete JSON object",
+      `responseChars=${unfenced.length}`,
+      `responseExcerpt=${JSON.stringify(compactKnowledgeText(unfenced, 1_200))}`,
+    ].join("; "));
+  }
+  const payload = unfenced.slice(start, end + 1);
   try {
-    const parsed = JSON.parse(unfenced.slice(start, end + 1)) as { candidates?: unknown };
-    if (!Array.isArray(parsed.candidates)) throw new Error("Knowledge reviewer response is missing candidates[]");
-    return parsed.candidates.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates);
+    return JSON.parse(payload) as Record<string, unknown>;
   } catch (error) {
-    strictError = error;
-  }
-
-  const arrayKey = /["']candidates["']\s*:/gu.exec(unfenced);
-  const arrayStart = arrayKey ? unfenced.indexOf("[", arrayKey.index + arrayKey[0].length) : -1;
-  if (arrayStart >= 0) {
-    const candidates: unknown[] = [];
-    let inString = false;
-    let escaped = false;
-    for (let index = arrayStart + 1; index < unfenced.length && candidates.length < KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates; index++) {
-      const character = unfenced[index];
-      if (inString) {
-        if (escaped) escaped = false;
-        else if (character === "\\") escaped = true;
-        else if (character === '"') inString = false;
-        continue;
-      }
-      if (character === '"') { inString = true; continue; }
-      if (character !== "{") continue;
-      const objectEnd = balancedObjectEnd(unfenced, index);
-      if (objectEnd < 0) break;
-      try { candidates.push(JSON.parse(unfenced.slice(index, objectEnd + 1))); } catch { /* Salvage other complete candidates. */ }
-      index = objectEnd;
-    }
-    if (candidates.length > 0) return candidates;
-  }
-  throw strictError;
-}
-
-function balancedObjectEnd(value: string, start: number): number {
-  let depth = 0;
-  let inString = false;
-  let escaped = false;
-  for (let index = start; index < value.length; index++) {
-    const character = value[index];
-    if (inString) {
-      if (escaped) escaped = false;
-      else if (character === "\\") escaped = true;
-      else if (character === '"') inString = false;
-      continue;
-    }
-    if (character === '"') { inString = true; continue; }
-    if (character === "{") depth++;
-    else if (character === "}" && --depth === 0) return index;
+    const message = error instanceof Error ? error.message : String(error);
+    const offsetMatch = /position\s+(\d+)/iu.exec(message);
+    const offset = offsetMatch ? Number.parseInt(offsetMatch[1]!, 10) : -1;
+    const excerptStart = offset >= 0 ? Math.max(0, offset - 600) : 0;
+    const excerptEnd = offset >= 0 ? Math.min(payload.length, offset + 600) : Math.min(payload.length, 1_200);
+    const excerpt = compactKnowledgeText(payload.slice(excerptStart, excerptEnd), 1_200);
+    throw new Error([
+      `Knowledge reviewer returned invalid JSON: ${message}`,
+      `responseChars=${payload.length}`,
+      offset >= 0 ? `errorOffset=${offset}` : undefined,
+      `responseExcerpt=${JSON.stringify(excerpt)}`,
+    ].filter(Boolean).join("; "));
   }
-  return -1;
 }
 
 export function knowledgeDeltaDigest(delta: string): string {

package/.pi/lib/knowledge/review-status.ts

@@ -40,6 +40,24 @@ export interface KnowledgeReviewStatus {
     result?: PersistKnowledgeResult;
     error?: string;
   };
+  reviewFailures?: Record<string, {
+    sessionKey: string;
+    sessionFileHash: string;
+    attempts: Array<{
+      attempt: number;
+      failedAt: string;
+      durationMs: number;
+      error: string;
+    }>;
+  }>;
+  blockedReviews?: Record<string, {
+    reviewKey: string;
+    sessionKey: string;
+    sessionFileHash: string;
+    blockedAt: string;
+    attempts: number;
+    error: string;
+  }>;
 }
 
 export function writeKnowledgeReviewStatus(status: KnowledgeReviewStatus, home: string): void {