@hadooppei/hwcode 1.0.16 → 1.0.20

package/.pi/dist/lib/knowledge/store.js

@@ -11,10 +11,6 @@ const SAFE_GENERATION_RE = /^[0-9TZ-]+-[a-f0-9]{12}$/u;
 const PROJECT_SCOPE_RE = /^project:[a-f0-9]{16}$/u;
 const UNVERIFIED_CLAIM_RE = /(?:待验证|尚未(?:验证|确认)|未经(?:验证|确认)|未(?:经)?证实|推测|猜测|疑似|可能是|可能由于|可能导致|或许|unverified|unconfirmed|speculat(?:e|ive|ion)|hypothes(?:is|ize)|suspect(?:ed|ion)?|possibly|probably)/iu;
 const VOLATILE_ARGUMENT_RE = /--(?:namespace|name|server_name|security_group_id|subnet_id|vpc_id|image_id|project_id)(?:\.\d+)?=(?!<[^>]+>|\$?\{)[^\s`"']+/iu;
-const DISTINCTIVE_COMMON_TERMS = new Set([
-    "cloud", "huawei", "huaweicloud", "hcloud", "topic", "rule", "sop", "project", "region", "create",
-    "deploy", "deployment", "service", "workflow", "cn", "south",
-]);
 export class KnowledgeCommitBusyError extends Error {
 }
 function emptyCatalog() {
@@ -105,47 +101,8 @@ function normalizeSlug(value) {
         .replace(/^-+|-+$/gu, "").slice(0, STORAGE.slugMaxChars) || "knowledge";
 }
 function normalizedFingerprint(candidate) {
-    return createHash("sha256").update(`${candidate.scope}\0${candidate.key.trim().toLowerCase()}`).digest("hex");
-}
-function comparisonTerms(value) {
-    return new Set((value.normalize("NFKC").toLowerCase().match(/\p{Script=Han}+|[\p{L}\p{N}]+/gu) ?? [])
-        .filter((term) => term.length >= 2));
-}
-function containment(left, right) {
-    const minimum = Math.min(left.size, right.size);
-    if (minimum === 0)
-        return 0;
-    let shared = 0;
-    for (const term of left)
-        if (right.has(term))
-            shared++;
-    return shared / minimum;
-}
-function semanticDuplicateScore(candidate, entry) {
-    if (candidate.scope !== entry.scope || candidate.storageHint !== entry.track)
-        return 0;
-    const titleScore = containment(comparisonTerms(candidate.title), comparisonTerms(entry.title));
-    const keywordScore = containment(comparisonTerms(candidate.keywords.join(" ")), comparisonTerms(entry.keywords.join(" ")));
-    if (titleScore >= 0.8 && keywordScore >= 0.5)
-        return titleScore * 0.7 + keywordScore * 0.3;
-    const candidateTerms = comparisonTerms(`${candidate.title} ${candidate.keywords.join(" ")}`);
-    const entryTerms = comparisonTerms(`${entry.title} ${entry.keywords.join(" ")}`);
-    const distinctiveShared = [...candidateTerms].filter((term) => (entryTerms.has(term) && term.length >= 3 && !DISTINCTIVE_COMMON_TERMS.has(term))).length;
-    if (keywordScore < 0.5 || distinctiveShared < 3)
-        return 0;
-    return keywordScore * 0.7 + Math.min(distinctiveShared / 6, 1) * 0.3;
-}
-function semanticDuplicateIndex(candidate, catalog) {
-    let bestIndex = -1;
-    let bestScore = 0;
-    for (const [index, entry] of catalog.items.entries()) {
-        const score = semanticDuplicateScore(candidate, entry);
-        if (score > bestScore) {
-            bestIndex = index;
-            bestScore = score;
-        }
-    }
-    return bestIndex;
+    const identity = candidate.identityKey?.trim().toLowerCase() || candidate.key.trim().toLowerCase();
+    return createHash("sha256").update(`${candidate.scope}\0${candidate.storageHint}\0${identity}`).digest("hex");
 }
 function unsupportedOperations(value) {
     return [...value.matchAll(/\bOperation\s+([A-Za-z][A-Za-z0-9]+)\s+is not supported\b/gu)].map((match) => {
@@ -178,6 +135,71 @@ function asStringArray(value, maxItems) {
     return [...new Set(value.filter((item) => typeof item === "string")
             .map((item) => compactKnowledgeText(item, 240)).filter(Boolean))].slice(0, maxItems);
 }
+function asSafeReferenceArray(value, maxItems) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.filter((item) => (typeof item === "string" && /^[a-z0-9][a-z0-9-]{0,127}$/u.test(item))))].slice(0, maxItems);
+}
+function normalizedClaimKey(value) {
+    return compactKnowledgeText(value, 160).toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ".").replace(/^\.+|\.+$/gu, "");
+}
+function parseClaims(value) {
+    if (!Array.isArray(value))
+        return [];
+    const claims = [];
+    for (const raw of value.slice(0, 12)) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const item = raw;
+        if (typeof item.text !== "string")
+            continue;
+        const text = compactKnowledgeText(item.text, 500);
+        const key = typeof item.key === "string" ? normalizedClaimKey(item.key) : normalizedClaimKey(text);
+        const evidenceIds = asSafeReferenceArray(item.evidenceIds, 12);
+        if (key && text && evidenceIds.length > 0)
+            claims.push({ key, text, evidenceIds });
+    }
+    return claims;
+}
+function evidenceMap(task) {
+    return new Map((task.evidence ?? []).map((item) => [item.id, item]));
+}
+const UNIVERSAL_CLAIM_RE = /(?:\b(?:all|always|any|every)\b|全部|所有|任何|始终|均需)/iu;
+const BROAD_REQUIRED_CLAIM_RE = /(?:\b(?:apis?|operations?|services?)\b|接口|操作|服务)[^\n]{0,80}(?:\b(?:must|require[sd]?)\b|必须)/iu;
+const TECHNICAL_TOKEN_RE = /\p{Script=Han}{2,}|[a-z][a-z0-9_.\/-]{2,}/giu;
+const CLAIM_COMMON_TERMS = new Set(["should", "must", "always", "before", "after", "使用", "必须", "应该", "需要", "首先"]);
+function claimTerms(value) {
+    return new Set((value.toLowerCase().match(TECHNICAL_TOKEN_RE) ?? [])
+        .filter((term) => !CLAIM_COMMON_TERMS.has(term)));
+}
+function claimHasDirectSupport(claim, ledger) {
+    const terms = claimTerms(claim.text);
+    if (terms.size === 0)
+        return false;
+    for (const id of claim.evidenceIds) {
+        const evidence = ledger.get(id);
+        if (!evidence || evidence.kind === "assistant-claim")
+            continue;
+        const haystack = `${evidence.subject}\n${evidence.operation ?? ""}\n${evidence.excerpt}`.toLowerCase();
+        if ([...terms].some((term) => haystack.includes(term)))
+            return true;
+    }
+    return false;
+}
+function claimIsOverbroad(claim, ledger) {
+    if (!UNIVERSAL_CLAIM_RE.test(claim.text) && !BROAD_REQUIRED_CLAIM_RE.test(claim.text))
+        return false;
+    const operations = new Set(claim.evidenceIds.map((id) => ledger.get(id)?.operation).filter(Boolean));
+    return operations.size <= 1;
+}
+function claimContradictsSuccess(claim, task) {
+    if (!/(?:not supported|unsupported|不支持|不可用|必须.*\/v\d|must.*\/v\d)/iu.test(claim.text))
+        return false;
+    const claimLower = claim.text.toLowerCase();
+    return (task.evidence ?? []).some((item) => item.outcome === "success" && item.operation
+        && claimLower.includes(item.operation.split(/\s+/u).at(-1).toLowerCase().replace(/\/v\d$/u, ""))
+        && !item.operation.toLowerCase().match(/\/v\d$/u));
+}
 function withoutLeadingTitle(body) {
     return body.replace(/^#\s+[^\n]*(?:\n+|$)/u, "").trim();
 }
@@ -190,7 +212,7 @@ function containsVolatileDetail(body, projectRoot) {
         || namedProject
         || /\.hwcode\/cloud\/runs\//iu.test(body);
 }
-function normalizeCandidate(value, projectKey, projectRoot, validationText) {
+function normalizeCandidate(value, task, validationText) {
     if (!value || typeof value !== "object")
         return { reason: "invalid-schema" };
     const raw = value;
@@ -205,15 +227,50 @@ function normalizeCandidate(value, projectKey, projectRoot, validationText) {
         && (typeof raw.targetId !== "string" || !SAFE_ID_RE.test(raw.targetId)))
         return { reason: "unknown-target" };
     const explicitUserDirective = raw.explicitUserDirective === true;
-    const scope = raw.scope === "global" && explicitUserDirective ? "global" : `project:${projectKey}`;
+    const scope = raw.scope === "global" && explicitUserDirective ? "global" : `project:${task.projectKey}`;
     const body = withoutLeadingTitle(compactKnowledgeText(raw.body, 20_000));
-    const evidence = asStringArray(raw.evidence, 8);
+    const ledger = evidenceMap(task);
+    const claims = parseClaims(raw.claims);
+    const episodeIds = asSafeReferenceArray(raw.episodeIds, 8);
+    const evidenceIds = [...new Set([
+            ...asSafeReferenceArray(raw.evidenceIds, 16),
+            ...claims.flatMap((claim) => claim.evidenceIds),
+        ])];
+    let evidence = asStringArray(raw.evidence, 8);
+    if (ledger.size > 0) {
+        if (typeof raw.identityKey !== "string" || !raw.identityKey.trim())
+            return { reason: "invalid-schema" };
+        if (claims.length === 0 || evidenceIds.length === 0)
+            return { reason: "missing-body-or-evidence" };
+        if (evidenceIds.some((id) => !ledger.has(id)))
+            return { reason: "unknown-evidence" };
+        if (episodeIds.length === 0 || episodeIds.some((id) => !(task.episodes ?? []).some((episode) => episode.id === id))) {
+            return { reason: "invalid-schema" };
+        }
+        const episodeEvidenceIds = new Set((task.episodes ?? [])
+            .filter((episode) => episodeIds.includes(episode.id)).flatMap((episode) => episode.evidenceIds));
+        if (evidenceIds.some((id) => !episodeEvidenceIds.has(id)))
+            return { reason: "unknown-evidence" };
+        if (!explicitUserDirective && claims.some((claim) => !claimHasDirectSupport(claim, ledger))) {
+            return { reason: "unsupported-claim" };
+        }
+        if (!explicitUserDirective && claims.some((claim) => claimIsOverbroad(claim, ledger))) {
+            return { reason: "overbroad-claim" };
+        }
+        if (claims.some((claim) => claimContradictsSuccess(claim, task))) {
+            return { reason: "contradicts-verified-failure" };
+        }
+        evidence = evidenceIds.slice(0, 8).map((id) => {
+            const item = ledger.get(id);
+            return `${id}: ${compactKnowledgeText(`${item.subject}: ${item.excerpt}`, 220)}`;
+        });
+    }
     if (!body || evidence.length === 0)
         return { reason: "missing-body-or-evidence" };
     const candidateClaims = `${raw.title}\n${raw.summary}\n${body}`;
     if (!explicitUserDirective && UNVERIFIED_CLAIM_RE.test(candidateClaims))
         return { reason: "unverified-claim" };
-    if (containsVolatileDetail(body, projectRoot))
+    if (containsVolatileDetail(body, task.projectRoot))
         return { reason: "volatile-detail" };
     if (contradictsVerifiedFailures(body, validationText))
         return { reason: "contradicts-verified-failure" };
@@ -222,14 +279,18 @@ function normalizeCandidate(value, projectKey, projectRoot, validationText) {
         && body.split(/\n\s*\n/gu).length === 1
         && (explicitUserDirective || raw.confidence >= 0.9);
     const targetId = typeof raw.targetId === "string" && SAFE_ID_RE.test(raw.targetId) ? raw.targetId : undefined;
+    const action = raw.action === "reinforce" || raw.action === "extend" || raw.action === "correct"
+        || raw.action === "retire" ? raw.action : "add";
     return { candidate: {
-            key: compactKnowledgeText(raw.key, 160), targetId,
+            key: compactKnowledgeText(raw.key, 160),
+            identityKey: typeof raw.identityKey === "string" ? compactKnowledgeText(raw.identityKey, 240).toLowerCase() : undefined,
+            targetId,
             title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
             summary: compactKnowledgeSummary(raw.summary, STORAGE.maxSummaryChars),
             keywords: asStringArray(raw.keywords, STORAGE.maxKeywordCount).map((keyword) => keyword.toLowerCase()),
-            scope, body, evidence, confidence: Math.min(1, raw.confidence),
+            scope, body, evidence, evidenceIds, episodeIds, claims, confidence: Math.min(1, raw.confidence),
             storageHint: requestedTrack === "rule" && ruleEligible ? "rule" : "topic",
-            action: raw.action === "revise" ? "revise" : raw.action === "reinforce" ? "reinforce" : "add",
+            action,
             explicitUserDirective, durability: "stable",
         } };
 }
@@ -258,6 +319,17 @@ function renderKnowledgeFile(candidate) {
         candidate.body, "", "## Evidence", "", ...candidate.evidence.map((item) => `- ${item}`), "",
     ].join("\n");
 }
+function extendKnowledgeFile(content, candidate) {
+    const evidenceHeading = "\n## Evidence\n";
+    const index = content.indexOf(evidenceHeading);
+    const addition = candidate.body.trim();
+    const evidenceLines = candidate.evidence.map((item) => `- ${item}`).join("\n");
+    if (index < 0)
+        return `${content.trim()}\n\n${addition}\n\n## Evidence\n\n${evidenceLines}\n`;
+    const before = content.slice(0, index).trim();
+    const after = content.slice(index + evidenceHeading.length).trim();
+    return `${before}\n\n${addition}\n\n## Evidence\n\n${after}${after ? "\n" : ""}${evidenceLines}\n`;
+}
 function applicable(entry, projectKey) {
     return entry.scope === "global" || entry.scope === `project:${projectKey}`;
 }
@@ -324,14 +396,14 @@ function newGenerationId() {
     return `${new Date().toISOString().replace(/[:.]/gu, "-")}-${randomUUID().replace(/-/gu, "").slice(0, 12)}`;
 }
 function copyCurrentContent(manifest, target, home) {
-    for (const name of ["rules", "topics", "pending"])
+    for (const name of ["rules", "topics", "pending", "audits"])
         ensureDirectory(join(target, name));
     if (!manifest.generationId)
         return;
     const source = generationDirectory(manifest.generationId, home);
     if (!source)
         return;
-    for (const name of ["rules", "topics", "pending"]) {
+    for (const name of ["rules", "topics", "pending", "audits"]) {
         const sourceDirectory = join(source, name);
         if (!existsSync(sourceDirectory))
             continue;
@@ -362,7 +434,17 @@ function reviewCursor(task) {
         lastReviewKey: task.reviewKey, fileSize: task.fileSize, fileMtimeMs: task.fileMtimeMs,
     };
 }
-export function commitKnowledgeReview(values, task, leaderToken, home = homedir()) {
+function validateEpisodeDecisions(task, decisions) {
+    const mandatory = (task.episodes ?? []).filter((episode) => (episode.score >= KNOWLEDGE_RUNTIME_DEFAULTS.review.mandatoryEpisodeScore));
+    for (const episode of mandatory) {
+        const decision = decisions.find((item) => item.episodeId === episode.id);
+        if (!decision || typeof decision.reason !== "string" || !decision.reason.trim()) {
+            throw new Error(`Knowledge reviewer omitted mandatory episode ${episode.id}`);
+        }
+    }
+}
+export function commitKnowledgeReview(values, task, leaderToken, home = homedir(), decisions = []) {
+    validateEpisodeDecisions(task, decisions);
     ensureKnowledgeDirectories(home);
     const release = acquireCommitLock(leaderToken, home);
     const paths = userRuntimePaths(home);
@@ -380,7 +462,7 @@ export function commitKnowledgeReview(values, task, leaderToken, home = homedir(
         const result = { saved: 0, updated: 0, pending: 0, skipped: 0 };
         const rejected = [];
         for (const value of values.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates)) {
-            const normalized = normalizeCandidate(value, task.projectKey, task.projectRoot, `${task.context ?? ""}\n${task.delta}`);
+            const normalized = normalizeCandidate(value, task, `${task.context ?? ""}\n${task.delta}`);
             if (!("candidate" in normalized)) {
                 recordSkip(result, normalized.reason);
                 rejected.push({ reason: normalized.reason, value });
@@ -399,20 +481,73 @@ export function commitKnowledgeReview(values, task, leaderToken, home = homedir(
             }
             let existingIndex = targetIndex >= 0
                 ? targetIndex
-                : catalog.items.findIndex((item) => item.fingerprint === fingerprint);
-            let semanticReinforcement = false;
-            if (existingIndex < 0) {
-                existingIndex = semanticDuplicateIndex(candidate, catalog);
-                semanticReinforcement = existingIndex >= 0;
-            }
+                : catalog.items.findIndex((item) => item.fingerprint === fingerprint
+                    || Boolean(candidate.identityKey && item.identityKey === candidate.identityKey && item.track === candidate.storageHint));
             const existing = existingIndex >= 0 ? catalog.items[existingIndex] : undefined;
-            if (existing && (existing.contentHash === hash || candidate.action === "reinforce" || semanticReinforcement)) {
+            if (candidate.action === "reinforce") {
+                const claimKeys = candidate.claims?.map((claim) => claim.key) ?? [];
+                const covered = claimKeys.length > 0 && claimKeys.every((key) => existing?.claimKeys?.includes(key));
+                if (!existing || (!covered && existing.contentHash !== hash)) {
+                    recordSkip(result, "unsafe-reinforcement");
+                    rejected.push({ reason: "unsafe-reinforcement", value });
+                    continue;
+                }
                 existing.evidenceCount += candidate.evidence.length;
                 existing.updatedAt = new Date().toISOString();
                 result.updated++;
                 continue;
             }
-            if (existing && !(candidate.action === "revise" && (candidate.explicitUserDirective || candidate.confidence >= 0.92))) {
+            if (candidate.action === "retire") {
+                if (!existing || !candidate.targetId || (!candidate.explicitUserDirective && candidate.confidence < 0.98)) {
+                    recordSkip(result, "unsafe-reinforcement");
+                    rejected.push({ reason: "unsafe-reinforcement", value });
+                    continue;
+                }
+                const existingPath = resolve(temporary, existing.file);
+                if (existingPath.startsWith(`${temporary}${sep}`))
+                    rmSync(existingPath, { force: true });
+                catalog.items.splice(existingIndex, 1);
+                result.updated++;
+                continue;
+            }
+            if (candidate.action === "extend") {
+                if (!existing || !candidate.targetId || existing.track !== "topic") {
+                    recordSkip(result, "unknown-target");
+                    rejected.push({ reason: "unknown-target", value });
+                    continue;
+                }
+                const newClaimKeys = (candidate.claims ?? []).map((claim) => claim.key)
+                    .filter((key) => !existing.claimKeys?.includes(key));
+                if (newClaimKeys.length === 0 && existing.claimKeys?.length) {
+                    existing.evidenceCount += candidate.evidence.length;
+                    existing.updatedAt = new Date().toISOString();
+                    result.updated++;
+                    continue;
+                }
+                const existingPath = resolve(temporary, existing.file);
+                if (!existingPath.startsWith(`${temporary}${sep}`) || !existsSync(existingPath)) {
+                    recordSkip(result, "unknown-target");
+                    rejected.push({ reason: "unknown-target", value });
+                    continue;
+                }
+                const content = extendKnowledgeFile(readFileSync(existingPath, "utf8"), candidate);
+                atomicWrite(existingPath, content);
+                existing.contentHash = createHash("sha256").update(content).digest("hex");
+                existing.keywords = [...new Set([...existing.keywords, ...candidate.keywords])].slice(0, STORAGE.maxKeywordCount);
+                existing.claimKeys = [...new Set([...(existing.claimKeys ?? []), ...newClaimKeys])];
+                existing.evidenceCount += candidate.evidence.length;
+                existing.updatedAt = new Date().toISOString();
+                result.updated++;
+                continue;
+            }
+            if (existing && candidate.action !== "correct") {
+                const name = `${Date.now()}-${normalizeSlug(candidate.title)}-${randomUUID().slice(0, 8)}.json`;
+                atomicWrite(join(temporary, "pending", name), `${JSON.stringify({ reason: "conflicting-or-ambiguous-update", candidate }, null, 2)}\n`);
+                result.pending++;
+                continue;
+            }
+            if (existing && candidate.action === "correct"
+                && (!candidate.targetId || (!candidate.explicitUserDirective && candidate.confidence < 0.92))) {
                 const name = `${Date.now()}-${normalizeSlug(candidate.title)}-${randomUUID().slice(0, 8)}.json`;
                 atomicWrite(join(temporary, "pending", name), `${JSON.stringify({ reason: "conflicting-or-ambiguous-update", candidate }, null, 2)}\n`);
                 result.pending++;
@@ -433,6 +568,8 @@ export function commitKnowledgeReview(values, task, leaderToken, home = homedir(
                 title: candidate.title, summary: candidate.summary,
                 keywords: candidate.keywords, scope: existing?.scope ?? candidate.scope, track, file: relativeFile,
                 evidenceCount: (existing?.evidenceCount ?? 0) + candidate.evidence.length,
+                identityKey: candidate.identityKey ?? existing?.identityKey,
+                claimKeys: candidate.claims?.map((claim) => claim.key) ?? existing?.claimKeys,
                 createdAt: existing?.createdAt ?? now, updatedAt: now,
             };
             if (existingIndex >= 0) {
@@ -444,17 +581,26 @@ export function commitKnowledgeReview(values, task, leaderToken, home = homedir(
                 result.saved++;
             }
         }
-        if (result.skipped > 0 && result.saved === 0 && result.updated === 0 && result.pending === 0) {
-            for (const item of rejected)
-                writeRejectedPending(temporary, item.reason, item.value);
-            result.pending += rejected.length;
-        }
+        for (const item of rejected)
+            writeRejectedPending(temporary, item.reason, item.value);
+        result.pending += rejected.length;
         catalog.updatedAt = new Date().toISOString();
         const manifest = {
             version: 3, generationId, createdAt: new Date().toISOString(), leaderToken, catalog,
             reviews: { ...current.reviews, [task.sessionKey]: reviewCursor(task) },
         };
         atomicWrite(join(temporary, "MEMORY.md"), generateMemory(catalog));
+        atomicWrite(join(temporary, "audits", `${task.reviewKey}.json`), `${JSON.stringify({
+            reviewKey: task.reviewKey,
+            sessionKey: task.sessionKey,
+            episodes: (task.episodes ?? []).map((episode) => ({
+                id: episode.id, title: episode.title, score: episode.score,
+                failureCount: episode.failureCount, successCount: episode.successCount,
+            })),
+            decisions,
+            result,
+            rejected: rejected.map((item) => ({ reason: item.reason })),
+        }, null, 2)}\n`);
         atomicWrite(join(temporary, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
         if (!validManifestAt(manifest, temporary))
             throw new Error("Refusing to publish an incomplete knowledge generation");

package/.pi/dist/lib/runtime/defaults.js

@@ -31,8 +31,14 @@ export const KNOWLEDGE_RUNTIME_DEFAULTS = Object.freeze({
         idleMs: 60_000,
         capabilityPollMs: 5_000,
         modelTimeoutMs: 180_000,
+        maxAttempts: 2,
+        maxFailureDetailChars: 4_000,
         maxDeltaChars: 12_000,
         maxPriorContextChars: 4_000,
+        maxNarrativeChars: 6_000,
+        maxEvidenceItems: 24,
+        maxEvidenceChars: 12_000,
+        mandatoryEpisodeScore: 45,
         maxExistingContextItems: 5,
         maxExistingBodyItems: 2,
         maxExistingBodyChars: 600,

package/.pi/extensions/knowledge.ts

@@ -10,8 +10,9 @@ import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-
 import {
   buildKnowledgeExtractionPrompt, type ExistingKnowledgeContext, KNOWLEDGE_EXTRACTION_SYSTEM_PROMPT,
 } from "../lib/knowledge/extractor.ts";
-import { matchKnowledge, recallKnowledge } from "../lib/knowledge/matcher.ts";
+import { matchKnowledge } from "../lib/knowledge/matcher.ts";
 import { loadKnowledgeById, loadKnowledgeSnapshot, projectKnowledgeKey } from "../lib/knowledge/store.ts";
+import type { KnowledgeEpisode, KnowledgeEvidence, KnowledgeReviewTask } from "../lib/knowledge/types.ts";
 import type { KnowledgeWorkerInput, KnowledgeWorkerOutput } from "../lib/knowledge/worker-protocol.ts";
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../lib/runtime/defaults.ts";
 import { getSessionProjectRoot } from "../lib/working-directory.ts";
@@ -21,6 +22,7 @@ interface ActiveReview {
   leaderToken: string;
   controller: AbortController;
   abortReason?: string;
+  diagnostic?: string;
 }
 
 interface ProcessKnowledgeRuntime {
@@ -42,6 +44,44 @@ runtime.workerRetryAttempt ??= 0;
 
 const WORKER_RETRY_DELAYS_MS = [1_000, 5_000, 30_000, 60_000] as const;
 
+function compactReviewEvidence(task: KnowledgeReviewTask): {
+  evidence: KnowledgeEvidence[];
+  episodes: KnowledgeEpisode[];
+} {
+  const ledger = new Map((task.evidence ?? []).map((item) => [item.id, item]));
+  const selected: KnowledgeEvidence[] = [];
+  const seen = new Set<string>();
+  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 size = JSON.stringify(compact).length;
+    if (characters + size > KNOWLEDGE_RUNTIME_DEFAULTS.review.maxEvidenceChars) return;
+    selected.push(compact);
+    seen.add(item.id);
+    characters += size;
+  };
+  for (const item of task.evidence ?? []) if (item.kind === "user-correction") add(item);
+  (task.episodes ?? []).forEach((episode, index) => {
+    const items = episode.evidenceIds.map((id) => ledger.get(id)).filter((item): item is KnowledgeEvidence => Boolean(item));
+    const quota = index === 0 ? 10 : index < 3 ? 4 : 2;
+    const representative = [
+      ...items.filter((item) => item.outcome === "failure").slice(-Math.max(1, Math.floor(quota * 0.4))),
+      ...items.filter((item) => item.kind === "assistant-claim").slice(-Math.max(1, Math.floor(quota * 0.2))),
+      ...items.filter((item) => item.kind === "verification").slice(-Math.max(1, Math.floor(quota * 0.3))),
+      ...items.filter((item) => item.outcome === "success").slice(-quota),
+    ];
+    for (const item of representative.slice(0, quota)) add(item);
+  });
+  const selectedIds = new Set(selected.map((item) => item.id));
+  return {
+    evidence: selected,
+    episodes: (task.episodes ?? []).map((episode) => ({
+      ...episode, evidenceIds: episode.evidenceIds.filter((id) => selectedIds.has(id)),
+    })),
+  };
+}
+
 function post(message: KnowledgeWorkerInput): void {
   runtime.worker?.postMessage(message);
 }
@@ -78,7 +118,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);
 }
@@ -123,7 +163,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();
@@ -134,24 +174,60 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
         entry.scope === "global" || entry.scope === `project:${message.task.projectKey}`
       )),
     };
-    const related: ExistingKnowledgeContext[] = recallKnowledge(
+    const relatedEntries = [] as typeof applicableCatalog.items;
+    const seenRelated = new Set<string>();
+    const addRelated = (entry: typeof applicableCatalog.items[number] | undefined): void => {
+      if (!entry || seenRelated.has(entry.id)
+        || relatedEntries.length >= KNOWLEDGE_RUNTIME_DEFAULTS.review.maxExistingContextItems) return;
+      relatedEntries.push(entry);
+      seenRelated.add(entry.id);
+    };
+    const episodeMatches = (message.task.episodes ?? []).map((episode) => (
+      matchKnowledge(`${episode.title}\n${episode.query}`, applicableCatalog, 2)
+    ));
+    for (const matches of episodeMatches.slice(0, 3)) 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);
+    for (const entry of matchKnowledge(
       message.task.recallQuery || message.task.delta,
       applicableCatalog,
-      message.task.loadedKnowledgeIds ?? [],
       KNOWLEDGE_RUNTIME_DEFAULTS.review.maxExistingContextItems,
-    ).map((entry, index) => {
+    )) addRelated(entry);
+    const promptContext = compactReviewEvidence(message.task);
+    const related: ExistingKnowledgeContext[] = relatedEntries.map((entry, index) => {
       const reference: ExistingKnowledgeContext = {
         id: entry.id,
         title: entry.title,
         summary: entry.summary,
         keywords: entry.keywords,
         track: entry.track,
+        identityKey: entry.identityKey,
+        claimKeys: entry.claimKeys,
       };
       if (index >= KNOWLEDGE_RUNTIME_DEFAULTS.review.maxExistingBodyItems) return reference;
       const content = loadKnowledgeById(entry.id, message.task.projectKey)?.content
         .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,
+    );
+    review.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}`,
+    ].join("; ");
     const response = await ctx.modelRegistry.complete(
       ctx.model,
       {
@@ -160,12 +236,7 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
           role: "user",
           content: [{
             type: "text",
-            text: buildKnowledgeExtractionPrompt(
-              message.task.projectRoot,
-              message.task.delta,
-              message.task.context,
-              related,
-            ),
+            text: prompt,
           }],
           timestamp: Date.now(),
         }],
@@ -177,10 +248,14 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
       .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 });
@@ -203,7 +278,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 {