@hadooppei/hwcode 1.0.15 → 1.0.19

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

@@ -0,0 +1,308 @@
+import { createHash } from "node:crypto";
+
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+import { 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;
+const VERIFICATION_RE = /(?:\b(?:verified|verification|active|running|succeeded|success|http\s*=?\s*200|downloaded newer image)\b|验证通过|运行成功|成功创建|已恢复)/iu;
+const CORRECTION_RE = /(?:\b(?:must|should|always|never|correction|most valuable)\b|必须|应该|不应该|纠正|最有价值|不要|务必)/iu;
+const REVERSAL_RE = /(?:\b(?:actually|instead|not the|turns out|root cause)\b|实为|并非|不是.*而是|误判|转机|根因|重大进展)/iu;
+
+interface ToolCallRecord {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+}
+
+interface EpisodeDefinition {
+  id: string;
+  title: string;
+  patterns: RegExp[];
+}
+
+const EPISODE_DEFINITIONS: EpisodeDefinition[] = [
+  {
+    id: "container-image-runtime",
+    title: "Container image retrieval and runtime verification",
+    patterns: [/docker(?:\.io)?/iu, /registry/iu, /imagepull/iu, /image pull/iu, /镜像拉取/u, /hello-world/iu, /nginx/iu, /container/iu, /容器/u, /daemon\.json/iu],
+  },
+  {
+    id: "cloud-network-egress",
+    title: "Cloud network, DNS, and outbound reachability",
+    patterns: [/\bdns\b/iu, /servfail/iu, /egress/iu, /outbound/iu, /route table/iu, /公网出口/u, /出站/u, /解析/u, /\bnat\b/iu, /security group/iu],
+  },
+  {
+    id: "cloud-compute-deployment",
+    title: "Cloud compute provisioning and deployment verification",
+    patterns: [/\becs\b/iu, /createservers/iu, /showserver/iu, /virtual machine/iu, /虚拟机/u, /云主机/u],
+  },
+  {
+    id: "cli-api-contract",
+    title: "CLI operation, version, and parameter contracts",
+    patterns: [/hcloud/iu, /koocli/iu, /\/v[23]\b/iu, /operation .*not supported/iu, /parameter/iu, /参数/u, /listsecuritygroups/iu, /listroutetables/iu],
+  },
+  {
+    id: "package-installation",
+    title: "Package installation and repository recovery",
+    patterns: [/apt-get/iu, /apt update/iu, /package/iu, /dpkg/iu, /404\s+not found/iu, /软件包/u, /镜像源/u],
+  },
+  {
+    id: "testing-verification",
+    title: "Testing and runtime verification",
+    patterns: [/test/iu, /typecheck/iu, /smoke/iu, /http\s*=?\s*200/iu, /验证/u, /测试/u],
+  },
+  {
+    id: "software-debugging",
+    title: "Software debugging and verified repair",
+    patterns: [/\b(?:bug|debug|exception|stack trace|compile|build failed|regression)\b/iu, /报错/u, /异常/u, /编译/u, /构建失败/u, /修复/u, /回归/u],
+  },
+  {
+    id: "architecture-refactoring",
+    title: "Architecture, API, and refactoring decisions",
+    patterns: [/\b(?:architecture|refactor|schema|interface|design decision|migration)\b/iu, /架构/u, /重构/u, /接口设计/u, /数据结构/u, /迁移/u],
+  },
+  {
+    id: "deployment-operations",
+    title: "Deployment and operational procedures",
+    patterns: [/\b(?:deploy|release|rollback|systemd|kubernetes|terraform|service health)\b/iu, /部署/u, /发布/u, /回滚/u, /运维/u, /健康检查/u],
+  },
+  {
+    id: "general-reusable-work",
+    title: "General reusable workflow or user guidance",
+    patterns: [/[\s\S]+/u],
+  },
+];
+
+function digest(value: string, length = 12): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+
+function messageRecord(entry: SessionEntry): Record<string, unknown> | undefined {
+  return entry.type === "message" && entry.message && typeof entry.message === "object"
+    ? entry.message as unknown as Record<string, unknown>
+    : undefined;
+}
+
+function textContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((item) => {
+    if (!item || typeof item !== "object") return "";
+    const value = item as Record<string, unknown>;
+    return typeof value.text === "string" ? value.text : "";
+  }).filter(Boolean).join("\n");
+}
+
+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)];
+  return [...new Set(selected)].join("\n").slice(0, limit);
+}
+
+function compactArguments(args: Record<string, unknown>): string {
+  const parts: string[] = [];
+  for (const key of ["approach", "intent", "operation", "command"]) {
+    const value = args[key];
+    if (typeof value === "string" && value.trim()) parts.push(`${key}=${value}`);
+  }
+  if (Array.isArray(args.args)) {
+    const values = args.args.filter((item): item is string => typeof item === "string").slice(0, 6);
+    if (values.length > 0) parts.push(`args=${values.join(" ")}`);
+  }
+  if (parts.length === 0) parts.push(JSON.stringify(args));
+  return boundedExcerpt(parts.join("; "), 700);
+}
+
+function operationName(call: ToolCallRecord | undefined): string | undefined {
+  if (!call) return undefined;
+  const command = typeof call.args.command === "string" ? call.args.command : "";
+  const args = Array.isArray(call.args.args)
+    ? call.args.args.filter((item): item is string => typeof item === "string")
+    : [];
+  if (command && args.length >= 2) return `${command} ${args[0]} ${args[1]}`;
+  if (call.name === "bash" && command) {
+    if (/docker\s+(?:pull|run|ps)|daemon\.json/iu.test(command)) return "bash docker registry/runtime";
+    if (/(?:nslookup|\bdig\b|getent hosts).*docker|registry-1\.docker\.io/iu.test(command)) return "bash docker registry DNS diagnostic";
+    if (/apt-get/iu.test(command)) return "bash apt package operation";
+  }
+  if (command) return command.split(/\s+/u).slice(0, 3).join(" ");
+  return call.name;
+}
+
+function evidenceSubject(call: ToolCallRecord | undefined, result: string): string {
+  if (call) {
+    const intent = call.args.intent;
+    if (typeof intent === "string" && intent.trim()) return boundedExcerpt(intent, 220);
+    const approach = call.args.approach;
+    if (typeof approach === "string" && approach.trim()) return approach.slice(0, 120);
+    const operation = operationName(call);
+    if (operation?.includes("docker registry DNS")) return "Diagnose Docker registry DNS resolution and direct reachability";
+    if (operation?.includes("docker registry/runtime")) return "Configure or verify Docker image retrieval and container runtime";
+    if (operation?.includes("apt package")) return "Install Docker packages and recover package repository failures";
+    return operation ?? call.name;
+  }
+  return boundedExcerpt(result.split("\n").find(Boolean) ?? "tool result", 220);
+}
+
+function timestampOf(entry: SessionEntry): string {
+  const value = (entry as unknown as Record<string, unknown>).timestamp;
+  return typeof value === "string" ? value : "";
+}
+
+function entryIdOf(entry: SessionEntry, index: number): string {
+  const value = (entry as unknown as Record<string, unknown>).id;
+  return typeof value === "string" && value ? value : `entry-${index}`;
+}
+
+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 userKind(text: string): KnowledgeEvidenceKind {
+  return CORRECTION_RE.test(text) ? "user-correction" : "user-directive";
+}
+
+export function buildKnowledgeEvidence(entries: SessionEntry[]): KnowledgeEvidence[] {
+  const calls = new Map<string, ToolCallRecord>();
+  const evidence: KnowledgeEvidence[] = [];
+
+  entries.forEach((entry, index) => {
+    const message = messageRecord(entry);
+    if (!message) return;
+    const entryId = entryIdOf(entry, index);
+    const timestamp = timestampOf(entry);
+    const content = message.content;
+    if (Array.isArray(content)) {
+      for (const raw of content) {
+        if (!raw || typeof raw !== "object") continue;
+        const item = raw as Record<string, unknown>;
+        if (item.type !== "toolCall" || typeof item.id !== "string" || typeof item.name !== "string") continue;
+        calls.set(item.id, {
+          id: item.id,
+          name: item.name,
+          args: item.arguments && typeof item.arguments === "object"
+            ? item.arguments as Record<string, unknown>
+            : {},
+        });
+      }
+    }
+
+    const role = typeof message.role === "string" ? message.role : "";
+    const text = textContent(content).trim();
+    if (role === "user" && text) {
+      evidence.push({
+        id: evidenceId(entryId, "user"), entryId, timestamp, kind: userKind(text),
+        subject: "User requirement or correction", outcome: "unknown", excerpt: boundedExcerpt(text, 700),
+      });
+      return;
+    }
+    if (role === "toolResult" && text) {
+      const toolCallId = typeof message.toolCallId === "string" ? message.toolCallId : "";
+      const call = calls.get(toolCallId);
+      const outcome = outcomeFor(message, text);
+      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",
+        subject: evidenceSubject(call, text), operation: operationName(call), outcome,
+        excerpt: boundedExcerpt(`${callText}[result] ${text}`),
+      });
+      return;
+    }
+    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",
+        subject: "Assistant diagnosis or conclusion", outcome: "unknown", excerpt: boundedExcerpt(text, 800),
+      });
+    }
+  });
+  const userEvidence = evidence.filter((item) => item.kind === "user-correction" || item.kind === "user-directive").slice(-12);
+  const recentEvidence = evidence.filter((item) => item.kind !== "user-correction" && item.kind !== "user-directive").slice(-68);
+  return [...userEvidence, ...recentEvidence].sort((left, right) => left.timestamp.localeCompare(right.timestamp));
+}
+
+function definitionScore(evidence: KnowledgeEvidence, definition: EpisodeDefinition): number {
+  const value = `${evidence.subject}\n${evidence.operation ?? ""}\n${evidence.excerpt}`;
+  return definition.patterns.filter((pattern) => pattern.test(value)).length;
+}
+
+function timeValue(value: string): number {
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function episodeScore(items: KnowledgeEvidence[]): Omit<KnowledgeEpisode, "id" | "title" | "query" | "evidenceIds"> {
+  const failures = items.filter((item) => item.outcome === "failure").length;
+  const successes = items.filter((item) => item.outcome === "success" || item.kind === "verification").length;
+  const reversals = items.filter((item) => REVERSAL_RE.test(item.excerpt)).length;
+  const userSignal = items.some((item) => item.kind === "user-correction");
+  const times = items.map((item) => timeValue(item.timestamp)).filter((value) => value > 0).sort((a, b) => a - b);
+  const elapsedMs = times.length > 1 ? times[times.length - 1]! - times[0]! : 0;
+  const score = Math.min(100,
+    (userSignal ? 25 : items.some((item) => item.kind === "user-directive") ? 8 : 0)
+    + Math.min(20, failures * 5)
+    + Math.min(20, successes * 3 + (failures > 0 && successes > 0 ? 5 : 0))
+    + Math.min(15, reversals * 5)
+    + Math.min(10, Math.floor(elapsedMs / 120_000))
+    + (items.length >= 3 ? 10 : 4));
+  return {
+    score, failureCount: failures, successCount: successes,
+    hypothesisReversalCount: reversals, elapsedMs, userSignal,
+  };
+}
+
+export function buildKnowledgeEpisodes(evidence: KnowledgeEvidence[]): KnowledgeEpisode[] {
+  const buckets = new Map(EPISODE_DEFINITIONS.map((definition) => [definition.id, [] as KnowledgeEvidence[]]));
+  for (const item of evidence) {
+    const value = `${item.subject}\n${item.operation ?? ""}\n${item.excerpt}`;
+    if (/(?:docker(?:\.io)?|registry-1\.docker|daemon\.json|imagepullbackoff|镜像拉取)/iu.test(value)) {
+      buckets.get("container-image-runtime")!.push(item);
+      continue;
+    }
+    const ranked = EPISODE_DEFINITIONS.map((definition) => ({ definition, score: definitionScore(item, definition) }))
+      .filter(({ score }) => score > 0)
+      .sort((left, right) => right.score - left.score);
+    const primary = ranked[0]?.definition;
+    if (primary) buckets.get(primary.id)!.push(item);
+  }
+  const episodes: KnowledgeEpisode[] = [];
+  for (const definition of EPISODE_DEFINITIONS) {
+    const items = buckets.get(definition.id) ?? [];
+    if (items.length === 0) continue;
+    const metrics = episodeScore(items);
+    const queryItems = items.map((item, index) => ({
+      item, index,
+      priority: item.kind === "user-correction" ? 0 : REVERSAL_RE.test(item.excerpt) ? 1
+        : item.outcome === "failure" ? 2 : item.kind === "verification" ? 3 : 4,
+    })).sort((left, right) => left.priority - right.priority || right.index - left.index).slice(0, 10)
+      .map(({ item }) => item);
+    const queryParts = queryItems.flatMap((item) => [
+      item.subject, item.operation ?? "", boundedExcerpt(item.excerpt, 180),
+    ])
+      .map((item) => item.replace(/\s+/gu, " ").trim()).filter(Boolean);
+    episodes.push({
+      id: `ep-${definition.id}-${digest(items.map((item) => item.id).join("\0"), 8)}`,
+      title: definition.title,
+      query: [...new Set(queryParts)].join("; ").slice(0, 1_200),
+      evidenceIds: items.map((item) => item.id),
+      ...metrics,
+    });
+  }
+  const hasSpecificEpisode = episodes.some((episode) => !episode.id.includes("-general-reusable-work-"));
+  const retained = hasSpecificEpisode
+    ? episodes.filter((episode) => !episode.id.includes("-general-reusable-work-") || episode.userSignal)
+    : episodes;
+  return retained.sort((left, right) => right.score - left.score || right.evidenceIds.length - left.evidenceIds.length)
+    .slice(0, 6);
+}

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
+import type { KnowledgeEpisode, KnowledgeEpisodeDecision, KnowledgeEvidence } from "./types.ts";
 
 export interface ExistingKnowledgeContext {
   id: string;
@@ -8,11 +9,18 @@ export interface ExistingKnowledgeContext {
   summary: string;
   keywords: string[];
   track: "rule" | "topic";
+  identityKey?: string;
+  claimKeys?: string[];
   content?: string;
 }
 
+export interface KnowledgeReviewEnvelope {
+  episodeDecisions: KnowledgeEpisodeDecision[];
+  candidates: unknown[];
+}
+
 export const KNOWLEDGE_EXTRACTION_SYSTEM_PROMPT = `You are HWCode's background knowledge reviewer.
-Review only the supplied conversation delta. Return strict JSON and no markdown.
+Review the supplied structured evidence and conversation delta. Return strict JSON and no markdown.
 Persist only knowledge that is likely to be useful in future sessions:
 - explicit user corrections or stable preferences;
 - verified engineering rules, successful procedures, or expensive failed approaches;
@@ -22,19 +30,23 @@ Do not persist mutable inventory such as current cloud resources, names, availab
 Do not persist hypotheses, suspected causes, or statements marked as possible, pending validation, or unconfirmed. Omit them until direct evidence verifies them.
 Treat failed, unsupported, invalid, or corrected operations as negative evidence. Never present an operation as valid when the supplied evidence says it failed; use only a verified alternative or record an explicit warning. Never invent commands or parameters absent from successful 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.
-Relevant existing knowledge may be supplied. If a candidate has the same intent as an existing item, do not add a translated, renamed, or reformatted duplicate. Set targetId to that exact existing ID and action to "reinforce" when the existing content remains correct, or "revise" only when the delta explicitly proves a correction. Use targetId null only for genuinely new knowledge.
+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.
 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.
 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: {"candidates":[{"key":"stable semantic key","targetId":"existing-id or null","title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body","evidence":["verified evidence"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|revise","explicitUserDirective":false,"durability":"stable"}]}
-Return {"candidates":[]} when nothing meets the threshold.`;
+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"}]}
+Return {"episodeDecisions":[],"candidates":[]} only when there are no mandatory episodes and nothing meets the threshold.`;
 
 export function buildKnowledgeExtractionPrompt(
   projectRoot: string,
   delta: string,
   context = "",
   existing: ExistingKnowledgeContext[] = [],
+  evidence: KnowledgeEvidence[] = [],
+  episodes: KnowledgeEpisode[] = [],
 ): string {
   const related = existing.length > 0 ? JSON.stringify(existing) : "[]";
   return [
@@ -44,10 +56,45 @@ export function buildKnowledgeExtractionPrompt(
     "",
     "<prior_validation_context>", context, "</prior_validation_context>",
     "",
+    "<problem_episodes>", JSON.stringify(episodes), "</problem_episodes>",
+    "",
+    "<evidence_ledger>", JSON.stringify(evidence), "</evidence_ledger>",
+    "",
     "<conversation_delta>", delta, "</conversation_delta>",
   ].join("\n");
 }
 
+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) };
+  }
+}
+
+function parseEnvelopeObject(text: string): Record<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");
+  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, "");

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

@@ -6,7 +6,7 @@ import { parentPort, workerData } from "node:worker_threads";
 
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
 import { userRuntimePaths } from "../runtime/paths.ts";
-import { parseCandidateEnvelope } from "./extractor.ts";
+import { parseKnowledgeReviewEnvelope } from "./extractor.ts";
 import { type KnowledgeReviewStatus, writeKnowledgeReviewStatus } from "./review-status.ts";
 import { sanitizeKnowledgeText } from "./sanitize.ts";
 import { findNextReviewTask } from "./session-scanner.ts";
@@ -331,7 +331,8 @@ function handleReviewResult(message: Extract<KnowledgeWorkerInput, { type: "revi
   let committed = false;
   try {
     if (message.error || message.raw === undefined) throw new Error(message.error || "Knowledge review returned no content");
-    const result = commitKnowledgeReview(parseCandidateEnvelope(message.raw), task, leaderToken, home);
+    const envelope = parseKnowledgeReviewEnvelope(message.raw);
+    const result = commitKnowledgeReview(envelope.candidates, task, leaderToken, home, envelope.episodeDecisions);
     const generationId = loadCurrentManifest(home).generationId;
     finishReview(task, "saved", { generationId, result });
     send({ type: "review_saved", requestId: task.requestId, generationId, result });

package/.pi/lib/knowledge/session-scanner.ts

@@ -1,13 +1,14 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFileSync, readdirSync, statSync } from "node:fs";
-import { resolve, sep } from "node:path";
+import { resolve } from "node:path";
 
 import {
   buildContextEntries, parseSessionEntries, type SessionEntry, type SessionHeader,
 } from "@earendil-works/pi-coding-agent";
 
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
-import { findLatestWorkflowRoot } from "../working-directory.ts";
+import { canonicalizeDirectory } from "../working-directory.ts";
+import { buildKnowledgeEpisodes, buildKnowledgeEvidence } from "./evidence.ts";
 import { knowledgeDeltaDigest } from "./extractor.ts";
 import { sanitizeKnowledgeText } from "./sanitize.ts";
 import { projectKnowledgeKey } from "./store.ts";
@@ -198,24 +199,8 @@ function buildRecallQuery(entries: SessionEntry[], ids: string[]): string {
   return lines.join("\n").slice(0, MAX_RECALL_QUERY_CHARS);
 }
 
-function projectRootForSession(header: SessionHeader, branch: SessionEntry[]): string {
-  const sessionRoot = resolve(header.cwd);
-  const workflowRootValue = findLatestWorkflowRoot(branch);
-  const workflowRoot = workflowRootValue ? resolve(workflowRootValue) : undefined;
-  let workingDirectory = sessionRoot;
-  for (const entry of branch.slice().reverse()) {
-    if (entry.type !== "custom" || entry.customType !== "hwcode-working-directory"
-      || !entry.data || typeof entry.data !== "object") continue;
-    const cwd = (entry.data as Record<string, unknown>).cwd;
-    if (typeof cwd !== "string" || !cwd) continue;
-    workingDirectory = resolve(cwd);
-    break;
-  }
-  if (workflowRoot && (workingDirectory === workflowRoot || workingDirectory.startsWith(`${workflowRoot}${sep}`))) {
-    return workflowRoot;
-  }
-  if (workingDirectory === sessionRoot || workingDirectory.startsWith(`${sessionRoot}${sep}`)) return sessionRoot;
-  return workingDirectory;
+function projectRootForSession(header: SessionHeader): string {
+  try { return canonicalizeDirectory(header.cwd); } catch { return resolve(header.cwd); }
 }
 
 export function discoverSessionFiles(root: string): string[] {
@@ -256,21 +241,29 @@ export function readReviewTask(
     : -1;
   const pending = branch.slice(cursorIndex + 1);
   if (pending.length === 0) return undefined;
+  const pendingEntryIds = new Set(pending.map((entry) => entry.id));
+  const evidenceWindow = cursorIndex >= 0 ? branch.slice(Math.max(0, cursorIndex - 40)) : pending;
+  const evidence = buildKnowledgeEvidence(evidenceWindow).filter((item) => pendingEntryIds.has(item.entryId));
+  const episodes = buildKnowledgeEpisodes(evidence);
   const delta = buildDelta(pending);
   const loadedIds = loadedKnowledgeIds(pending);
   const recallQuery = buildRecallQuery(pending, loadedIds);
   const context = cursorIndex >= 0 ? buildValidationContext(branch.slice(0, cursorIndex + 1)) : "";
   const firstEntryId = pending[0].id;
   const lastEntryId = pending[pending.length - 1].id;
-  const deltaDigest = knowledgeDeltaDigest(`${delta || `${firstEntryId}\0${lastEntryId}`}\0${recallQuery}\0${loadedIds.join("\0")}`);
+  const deltaDigest = knowledgeDeltaDigest([
+    delta || `${firstEntryId}\0${lastEntryId}`, recallQuery, loadedIds.join("\0"),
+    JSON.stringify(evidence), JSON.stringify(episodes),
+  ].join("\0"));
   const sessionFileHash = hash(resolve(sessionFile), 16);
   const sessionKey = hash(header.id, 24);
   const reviewKey = hash(`${header.id}\0${firstEntryId}\0${lastEntryId}\0${deltaDigest}`);
-  const projectRoot = projectRootForSession(header, branch);
+  const projectRoot = projectRootForSession(header);
   return {
     requestId: randomUUID(), reviewKey, sessionId: header.id, sessionKey, sessionFileHash,
     projectRoot, projectKey: projectKnowledgeKey(projectRoot),
     firstEntryId, lastEntryId, context, delta, recallQuery, loadedKnowledgeIds: loadedIds,
+    evidence, episodes,
     deltaDigest, fileSize: stat.size, fileMtimeMs: stat.mtimeMs,
   };
 }