@hadooppei/hwcode 1.0.7 → 1.0.9

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

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
+
+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.
+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;
+- reusable architecture, testing, debugging, deployment, or operational knowledge.
+Do not persist task summaries, guesses, temporary IDs, credentials, secrets, private data, or facts recoverable by simply reading the repository.
+Use storageHint "rule" only for short, precise, high-value instructions. Use "topic" for multi-step SOPs and detailed experience.
+Use action "revise" only when the delta explicitly corrects prior knowledge; otherwise use "add" or "reinforce".
+Scope may be "global" only for an explicit user directive intended across projects; otherwise use "project".
+Return: {"candidates":[{"key":"stable semantic key","title":"...","summary":"...","keywords":["..."],"scope":"global|project","body":"markdown body","evidence":["verified evidence"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|revise","explicitUserDirective":false}]}
+Return {"candidates":[]} when nothing meets the threshold.`;
+
+export function buildKnowledgeExtractionPrompt(projectRoot: string, delta: string): string {
+  return `Project root: ${projectRoot}\n\n<conversation_delta>\n${delta}\n</conversation_delta>`;
+}
+
+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");
+  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);
+}
+
+export function knowledgeDeltaDigest(delta: string): string {
+  return createHash("sha256").update(delta).digest("hex");
+}

package/.pi/lib/knowledge/matcher.ts

@@ -0,0 +1,122 @@
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
+import type { KnowledgeCatalog, KnowledgeCatalogEntry } from "./types.ts";
+
+const MAX_QUERY_TERMS = 64;
+const HAN_RUN = /^\p{Script=Han}+$/u;
+
+interface SearchField {
+  compact: string;
+  terms: Set<string>;
+}
+
+function normalizeSearchText(value: string): string {
+  return value
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim()
+    .replace(/\s+/gu, " ");
+}
+
+function searchTerms(value: string): string[] {
+  const normalized = normalizeSearchText(value);
+  const terms = new Set<string>();
+  for (const segment of normalized.match(/\p{Script=Han}+|[\p{L}\p{N}]+/gu) ?? []) {
+    if (segment.length < 2) continue;
+    terms.add(segment);
+    if (HAN_RUN.test(segment) && segment.length > 2) {
+      for (let index = 0; index < segment.length - 1; index += 1) {
+        terms.add(segment.slice(index, index + 2));
+      }
+    }
+    if (terms.size >= MAX_QUERY_TERMS) break;
+  }
+  return [...terms].slice(0, MAX_QUERY_TERMS);
+}
+
+function searchField(value: string): SearchField {
+  const normalized = normalizeSearchText(value);
+  return {
+    compact: normalized.replace(/\s+/gu, ""),
+    terms: new Set(searchTerms(normalized)),
+  };
+}
+
+function supportsPartialMatch(term: string): boolean {
+  return HAN_RUN.test(term) ? term.length >= 2 : term.length >= 3;
+}
+
+function fieldMatch(term: string, field: SearchField): "exact" | "partial" | undefined {
+  if (field.terms.has(term)) return "exact";
+  if (!supportsPartialMatch(term)) return undefined;
+  if (field.compact.includes(term)) return "partial";
+  for (const candidate of field.terms) {
+    if (!supportsPartialMatch(candidate)) continue;
+    if (term.includes(candidate) || candidate.includes(term)) return "partial";
+  }
+  return undefined;
+}
+
+function containsSearchPhrase(container: string, phrase: string): boolean {
+  return supportsPartialMatch(phrase) && container.includes(phrase);
+}
+
+function phraseScore(query: string, title: SearchField, summary: SearchField, keywords: SearchField[]): number {
+  if (query.length < 2) return 0;
+  if (keywords.some((keyword) => keyword.compact === query)) return 18;
+  if (title.compact === query) return 14;
+  if (keywords.some((keyword) => (
+    containsSearchPhrase(keyword.compact, query) || containsSearchPhrase(query, keyword.compact)
+  ))) return 10;
+  if (containsSearchPhrase(title.compact, query) || containsSearchPhrase(query, title.compact)) return 8;
+  if (containsSearchPhrase(summary.compact, query)) return 4;
+  return 0;
+}
+
+/**
+ * Cheaply recalls plausible catalog entries. The agent sees these entries and
+ * remains responsible for deciding whether a detailed topic is actually relevant.
+ */
+export function matchKnowledge(
+  query: string,
+  catalog: KnowledgeCatalog,
+  limit = KNOWLEDGE_RUNTIME_DEFAULTS.storage.maxLookupResults,
+): KnowledgeCatalogEntry[] {
+  const normalizedQuery = normalizeSearchText(query);
+  const compactQuery = normalizedQuery.replace(/\s+/gu, "");
+  const terms = searchTerms(normalizedQuery);
+  if (terms.length === 0 || limit <= 0) return [];
+
+  return catalog.items
+    .map((item) => {
+      const title = searchField(item.title);
+      const summary = searchField(item.summary);
+      const keywords = item.keywords.map(searchField);
+      let score = phraseScore(compactQuery, title, summary, keywords);
+      let matchedTerms = 0;
+
+      for (const term of terms) {
+        const keywordMatch = keywords.some((keyword) => fieldMatch(term, keyword) === "exact")
+          ? "exact"
+          : keywords.some((keyword) => fieldMatch(term, keyword) === "partial") ? "partial" : undefined;
+        const titleMatch = fieldMatch(term, title);
+        const summaryMatch = fieldMatch(term, summary);
+        const termScore = Math.max(
+          keywordMatch === "exact" ? 10 : keywordMatch === "partial" ? 7 : 0,
+          titleMatch === "exact" ? 7 : titleMatch === "partial" ? 5 : 0,
+          summaryMatch === "exact" ? 3 : summaryMatch === "partial" ? 1 : 0,
+        );
+        if (termScore > 0) {
+          score += termScore;
+          matchedTerms += 1;
+        }
+      }
+
+      score += (matchedTerms / terms.length) * 6;
+      return { item, score };
+    })
+    .filter(({ score }) => score > 0)
+    .sort((left, right) => right.score - left.score || right.item.updatedAt.localeCompare(left.item.updatedAt))
+    .slice(0, limit)
+    .map(({ item }) => item);
+}

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

@@ -0,0 +1,260 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { createConnection, createServer, type Server, type Socket } from "node:net";
+import { homedir } from "node:os";
+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 { findNextReviewTask } from "./session-scanner.ts";
+import { commitKnowledgeReview, ensureKnowledgeDirectories, loadCurrentManifest } from "./store.ts";
+import type { KnowledgeReviewTask } from "./types.ts";
+import type { CoordinatorBroadcast, KnowledgeWorkerInput, KnowledgeWorkerOutput } from "./worker-protocol.ts";
+
+if (!parentPort) throw new Error("Knowledge review worker requires a parent port");
+
+const home = (workerData as { home?: string } | null)?.home ?? homedir();
+const paths = userRuntimePaths(home);
+const standbySockets = new Set<Socket>();
+let eligible = false;
+let stopped = false;
+let sessionsRoot = "";
+let leaderServer: Server | undefined;
+let leaderToken = "";
+let standbySocket: Socket | undefined;
+let electionPending = false;
+let activeTask: KnowledgeReviewTask | undefined;
+
+function send(message: KnowledgeWorkerOutput): void {
+  parentPort!.postMessage(message);
+}
+
+function coordinatorPath(): string {
+  return process.platform === "win32"
+    ? `\\\\.\\pipe\\hwcode-knowledge-v3-${Buffer.from(home).toString("hex").slice(0, 16)}`
+    : paths.knowledgeCoordinatorSocket;
+}
+
+function writeLeaderMetadata(): void {
+  writeFileSync(paths.knowledgeLeader, `${JSON.stringify({
+    protocolVersion: 3, leaderToken, pid: process.pid, electedAt: new Date().toISOString(),
+  }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  chmodSync(paths.knowledgeLeader, 0o600);
+}
+
+function removeLeaderMetadata(token: string): void {
+  try {
+    const current = JSON.parse(readFileSync(paths.knowledgeLeader, "utf8")) as { leaderToken?: string };
+    if (current.leaderToken === token) rmSync(paths.knowledgeLeader, { force: true });
+  } catch { /* Another contender may already have replaced it. */ }
+}
+
+function broadcast(message: CoordinatorBroadcast): void {
+  const line = `${JSON.stringify(message)}\n`;
+  for (const socket of standbySockets) {
+    if (socket.writable) socket.write(line);
+  }
+}
+
+function scheduleElection(delay = Math.floor(Math.random() * 500)): void {
+  if (!eligible || stopped || electionPending || leaderServer || standbySocket) return;
+  electionPending = true;
+  const timer = setTimeout(() => {
+    electionPending = false;
+    attemptElection();
+  }, delay);
+  timer.unref();
+}
+
+function stepDown(reason: string): void {
+  if (activeTask) send({ type: "review_cancel", requestId: activeTask.requestId, reason });
+  activeTask = undefined;
+  const token = leaderToken;
+  leaderToken = "";
+  for (const socket of standbySockets) socket.destroy();
+  standbySockets.clear();
+  const server = leaderServer;
+  leaderServer = undefined;
+  if (server) {
+    try { server.close(); } catch { /* The failing server may already be closed. */ }
+    if (process.platform !== "win32") {
+      try { unlinkSync(coordinatorPath()); } catch { /* Socket may already be gone. */ }
+    }
+  }
+  if (token) removeLeaderMetadata(token);
+}
+
+function becomeStandby(socket: Socket): void {
+  standbySocket = socket;
+  socket.unref();
+  send({ type: "leadership", state: "standby" });
+  let buffer = "";
+  socket.on("data", (chunk) => {
+    buffer += chunk.toString("utf8");
+    for (;;) {
+      const newline = buffer.indexOf("\n");
+      if (newline < 0) break;
+      const line = buffer.slice(0, newline);
+      buffer = buffer.slice(newline + 1);
+      try {
+        const message = JSON.parse(line) as CoordinatorBroadcast;
+        if (message.type === "generation_changed") send(message);
+      } catch { /* Ignore malformed coordinator notifications. */ }
+    }
+  });
+  socket.once("close", () => {
+    if (standbySocket === socket) standbySocket = undefined;
+    scheduleElection();
+  });
+}
+
+function cleanStaleSocketAndRetry(): void {
+  if (process.platform === "win32") { scheduleElection(250); return; }
+  try {
+    mkdirSync(paths.knowledgeElectionLock, { mode: 0o700 });
+  } catch {
+    scheduleElection(250);
+    return;
+  }
+  try {
+    if (existsSync(coordinatorPath())) unlinkSync(coordinatorPath());
+  } catch { /* Retrying listen will surface persistent failures. */ }
+  finally { rmSync(paths.knowledgeElectionLock, { recursive: true, force: true }); }
+  scheduleElection();
+}
+
+function connectToLeader(probe = 0): void {
+  if (!eligible || stopped || leaderServer || standbySocket) return;
+  const socket = createConnection(coordinatorPath());
+  let connected = false;
+  socket.once("connect", () => { connected = true; becomeStandby(socket); });
+  socket.once("error", (error: NodeJS.ErrnoException) => {
+    socket.destroy();
+    if (connected) return;
+    if (error.code === "ECONNREFUSED" || error.code === "ENOENT") {
+      if (probe < 2) {
+        const timer = setTimeout(() => connectToLeader(probe + 1), 100);
+        timer.unref();
+      } else cleanStaleSocketAndRetry();
+    } else {
+      send({ type: "review_failed", error: `Coordinator connection failed: ${error.message}` });
+      scheduleElection(1_000);
+    }
+  });
+}
+
+function becomeLeader(server: Server): void {
+  leaderServer = server;
+  leaderToken = randomUUID();
+  server.unref();
+  server.on("connection", (socket) => {
+    standbySockets.add(socket);
+    socket.unref();
+    socket.once("close", () => standbySockets.delete(socket));
+    const generationId = loadCurrentManifest(home).generationId;
+    if (generationId) socket.write(`${JSON.stringify({ type: "generation_changed", generationId })}\n`);
+  });
+  server.on("error", (error) => {
+    send({ type: "review_failed", error: `Coordinator server failed: ${error.message}` });
+    stepDown("coordinator-server-failed");
+    scheduleElection();
+  });
+  writeLeaderMetadata();
+  send({ type: "leadership", state: "leader", leaderToken });
+  void scanForReview();
+}
+
+function attemptElection(): void {
+  if (!eligible || stopped || leaderServer || standbySocket) return;
+  ensureKnowledgeDirectories(home);
+  const server = createServer();
+  const electionError = (error: NodeJS.ErrnoException): void => {
+    if (error.code === "EADDRINUSE") connectToLeader();
+    else {
+      send({ type: "review_failed", error: `Coordinator election failed: ${error.message}` });
+      scheduleElection(1_000);
+    }
+  };
+  server.once("error", electionError);
+  server.listen(coordinatorPath(), () => {
+    server.off("error", electionError);
+    if (process.platform !== "win32") chmodSync(coordinatorPath(), 0o600);
+    becomeLeader(server);
+  });
+}
+
+async function scanForReview(): Promise<void> {
+  if (!leaderServer || !leaderToken || activeTask || !sessionsRoot || !eligible) return;
+  try {
+    const manifest = loadCurrentManifest(home);
+    const task = findNextReviewTask(sessionsRoot, manifest.reviews);
+    if (!task) return;
+    activeTask = task;
+    if (!task.delta) {
+      const result = commitKnowledgeReview([], task, leaderToken, home);
+      const generationId = loadCurrentManifest(home).generationId;
+      send({ type: "review_saved", requestId: task.requestId, generationId, result });
+      if (generationId) {
+        send({ type: "generation_changed", generationId });
+        broadcast({ type: "generation_changed", generationId });
+      }
+      activeTask = undefined;
+      queueMicrotask(() => void scanForReview());
+      return;
+    }
+    send({ type: "review_request", leaderToken, requestId: task.requestId, task });
+  } catch (error) {
+    activeTask = undefined;
+    send({ type: "review_failed", error: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+function handleReviewResult(message: Extract<KnowledgeWorkerInput, { type: "review_result" }>): void {
+  const task = activeTask;
+  if (!task || message.requestId !== task.requestId || message.leaderToken !== leaderToken || !leaderServer) return;
+  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 generationId = loadCurrentManifest(home).generationId;
+    send({ type: "review_saved", requestId: task.requestId, generationId, result });
+    if (generationId) {
+      send({ type: "generation_changed", generationId });
+      broadcast({ type: "generation_changed", generationId });
+    }
+    committed = true;
+  } catch (error) {
+    send({ type: "review_failed", requestId: task.requestId, error: error instanceof Error ? error.message : String(error) });
+  } finally {
+    activeTask = undefined;
+    if (committed) queueMicrotask(() => void scanForReview());
+  }
+}
+
+const scanTimer = setInterval(() => { void scanForReview(); }, KNOWLEDGE_RUNTIME_DEFAULTS.review.intervalMs);
+scanTimer.unref();
+
+parentPort.on("message", (message: KnowledgeWorkerInput) => {
+  if (message.type === "configure") {
+    sessionsRoot = message.sessionsRoot;
+    if (eligible === message.modelAvailable) return;
+    eligible = message.modelAvailable;
+    if (!eligible) {
+      standbySocket?.destroy();
+      standbySocket = undefined;
+      stepDown("model-unavailable");
+      send({ type: "leadership", state: "ineligible" });
+    } else scheduleElection(0);
+    return;
+  }
+  if (message.type === "review_result") { handleReviewResult(message); return; }
+  if (message.type === "scan_now") { void scanForReview(); return; }
+  stopped = true;
+  eligible = false;
+  clearInterval(scanTimer);
+  standbySocket?.destroy();
+  standbySocket = undefined;
+  stepDown("worker-stopped");
+  process.exit(0);
+});

package/.pi/lib/knowledge/sanitize.ts

@@ -0,0 +1,26 @@
+const PRIVATE_KEY_RE = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/giu;
+const BEARER_RE = /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/giu;
+const JWT_RE = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/gu;
+const SECRET_ASSIGNMENT_RE = /\b(access[_-]?key|secret(?:[_-]?(?:access|key))?|password|passwd|token|credential|client[_-]?secret)\b(\s*[:=]\s*)[^\s,;]+/giu;
+const URL_CREDENTIAL_RE = /(https?:\/\/)[^\s/@:]+:[^\s/@]+@/giu;
+
+export function sanitizeKnowledgeText(value: string): string {
+  return value
+    .replace(PRIVATE_KEY_RE, "<redacted-private-key>")
+    .replace(BEARER_RE, "Bearer <redacted>")
+    .replace(JWT_RE, "<redacted-jwt>")
+    .replace(SECRET_ASSIGNMENT_RE, (_match, key: string, separator: string) => `${key}${separator}<redacted>`)
+    .replace(URL_CREDENTIAL_RE, "$1<redacted>@")
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/giu, "<runtime-uuid>")
+    .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/gu, "<runtime-ip>")
+    .replace(/\b(vpc|subnet|secgroup|sg|vol|snap|img|inst|eip)-[0-9a-zA-Z]+/gu, "<$1-runtime-id>")
+    .replace(/\/(?:Users|home)\/[a-zA-Z0-9_-]+/gu, "~");
+}
+
+export function compactKnowledgeText(value: string, maxChars: number): string {
+  return sanitizeKnowledgeText(value)
+    .replace(/\r\n/gu, "\n")
+    .replace(/[ \t]+$/gmu, "")
+    .trim()
+    .slice(0, maxChars);
+}

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

@@ -0,0 +1,155 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+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 { knowledgeDeltaDigest } from "./extractor.ts";
+import { sanitizeKnowledgeText } from "./sanitize.ts";
+import { projectKnowledgeKey } from "./store.ts";
+import type { KnowledgeReviewCursor, KnowledgeReviewTask } from "./types.ts";
+
+interface ReviewPiece {
+  index: number;
+  priority: number;
+  category: "user" | "workflow" | "summary" | "assistant" | "tool";
+  text: string;
+}
+
+function hash(value: string, length = 64): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+
+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 reviewPiece(entry: SessionEntry, index: number): ReviewPiece | undefined {
+  if (entry.type === "compaction" || entry.type === "branch_summary") {
+    return { index, priority: 1, category: "summary", text: `[summary]\n${sanitizeKnowledgeText(entry.summary).slice(0, 6_000)}` };
+  }
+  if (entry.type === "custom" && entry.customType.startsWith("hwcode-workflow")) {
+    return {
+      index, priority: 0, category: "workflow",
+      text: `[workflow_state:${entry.customType}]\n${sanitizeKnowledgeText(JSON.stringify(entry.data ?? {})).slice(0, 6_000)}`,
+    };
+  }
+  if (entry.type !== "message" || !entry.message || typeof entry.message !== "object") return undefined;
+  const message = entry.message as unknown as Record<string, unknown>;
+  const role = typeof message.role === "string" ? message.role : "message";
+  const content = sanitizeKnowledgeText(textContent(message.content));
+  if (!content) return undefined;
+  const priority = role === "user" ? 0 : role === "toolResult" ? 3 : 2;
+  const cap = role === "user" ? 8_000 : role === "toolResult" ? 1_500 : 4_000;
+  const category = role === "user" ? "user" : role === "toolResult" ? "tool" : "assistant";
+  return { index, priority, category, text: `[${role}]\n${content.slice(0, cap)}` };
+}
+
+function buildDelta(entries: SessionEntry[]): string {
+  const pieces = entries.map(reviewPiece).filter((piece): piece is ReviewPiece => Boolean(piece));
+  const selected: ReviewPiece[] = [];
+  const categoryRemaining: Record<ReviewPiece["category"], number> = {
+    user: 14_000, workflow: 6_000, summary: 4_000, assistant: 8_000, tool: 4_000,
+  };
+  let remaining = KNOWLEDGE_RUNTIME_DEFAULTS.review.maxDeltaChars;
+  for (const piece of pieces.slice().sort((left, right) => left.priority - right.priority || left.index - right.index)) {
+    if (remaining <= 0) break;
+    const text = piece.text.slice(0, Math.min(remaining, categoryRemaining[piece.category]));
+    if (text) selected.push({ ...piece, text });
+    remaining -= text.length;
+    categoryRemaining[piece.category] -= text.length;
+  }
+  return selected.sort((left, right) => left.index - right.index).map((piece) => piece.text).join("\n\n");
+}
+
+function projectRootForSession(header: SessionHeader, branch: SessionEntry[]): string {
+  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) return resolve(cwd);
+  }
+  return resolve(header.cwd);
+}
+
+export function discoverSessionFiles(root: string): string[] {
+  const files: string[] = [];
+  const visit = (directory: string): void => {
+    let entries;
+    try { entries = readdirSync(directory, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile() && entry.name.endsWith(".jsonl")) files.push(path);
+    }
+  };
+  visit(resolve(root));
+  return files.sort();
+}
+
+export function readReviewTask(
+  sessionFile: string,
+  cursor: KnowledgeReviewCursor | undefined,
+  now = Date.now(),
+): KnowledgeReviewTask | undefined {
+  let stat;
+  try { stat = statSync(sessionFile); } catch { return undefined; }
+  if (!stat.isFile() || now - stat.mtimeMs < KNOWLEDGE_RUNTIME_DEFAULTS.review.idleMs) return undefined;
+  let content: string;
+  try { content = readFileSync(sessionFile, "utf8"); } catch { return undefined; }
+  const lastNewline = content.lastIndexOf("\n");
+  if (lastNewline < 0) return undefined;
+  const parsed = parseSessionEntries(content.slice(0, lastNewline + 1));
+  const header = parsed.find((entry): entry is SessionHeader => entry.type === "session");
+  if (!header?.id || !header.cwd) return undefined;
+  const allEntries = parsed.filter((entry): entry is SessionEntry => entry.type !== "session");
+  const branch = buildContextEntries(allEntries);
+  if (branch.length === 0) return undefined;
+  const cursorIndex = cursor?.lastReviewedEntryId
+    ? branch.findIndex((entry) => entry.id === cursor.lastReviewedEntryId)
+    : -1;
+  const pending = branch.slice(cursorIndex + 1);
+  if (pending.length === 0) return undefined;
+  const delta = buildDelta(pending);
+  const firstEntryId = pending[0].id;
+  const lastEntryId = pending[pending.length - 1].id;
+  const deltaDigest = knowledgeDeltaDigest(delta || `${firstEntryId}\0${lastEntryId}`);
+  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);
+  return {
+    requestId: randomUUID(), reviewKey, sessionId: header.id, sessionKey, sessionFileHash,
+    projectRoot, projectKey: projectKnowledgeKey(projectRoot),
+    firstEntryId, lastEntryId, delta, deltaDigest, fileSize: stat.size, fileMtimeMs: stat.mtimeMs,
+  };
+}
+
+export function findNextReviewTask(
+  sessionsRoot: string,
+  reviews: Record<string, KnowledgeReviewCursor>,
+  now = Date.now(),
+): KnowledgeReviewTask | undefined {
+  const files = discoverSessionFiles(sessionsRoot).map((path) => {
+    try { return { path, mtimeMs: statSync(path).mtimeMs }; } catch { return undefined; }
+  }).filter((item): item is { path: string; mtimeMs: number } => Boolean(item))
+    .sort((left, right) => left.mtimeMs - right.mtimeMs);
+  for (const file of files) {
+    const fileHash = hash(resolve(file.path), 16);
+    const cursor = Object.values(reviews).find((item) => item.sessionFileHash === fileHash);
+    let task = readReviewTask(file.path, cursor, now);
+    const stableCursor = task ? reviews[task.sessionKey] : undefined;
+    if (task && stableCursor && stableCursor !== cursor) task = readReviewTask(file.path, stableCursor, now);
+    if (task) return task;
+  }
+  return undefined;
+}