@hadooppei/hwcode 1.0.8 → 1.0.9

package/.pi/lib/knowledge/store.ts

@@ -1,5 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import {
+  chmodSync, copyFileSync, existsSync, linkSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync,
+  statSync, writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 
@@ -7,13 +10,27 @@ import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
 import { userRuntimePaths } from "../runtime/paths.ts";
 import { compactKnowledgeText, sanitizeKnowledgeText } from "./sanitize.ts";
 import type {
-  KnowledgeCandidate, KnowledgeCatalog, KnowledgeCatalogEntry, KnowledgeScope,
-  KnowledgeSnapshot, KnowledgeTrack, PersistKnowledgeResult,
+  KnowledgeCandidate, KnowledgeCatalog, KnowledgeCatalogEntry, KnowledgeManifest, KnowledgeReviewCursor,
+  KnowledgeReviewTask, KnowledgeScope, KnowledgeSnapshot, KnowledgeTrack, PersistKnowledgeResult,
 } from "./types.ts";
 
 const STORAGE = KNOWLEDGE_RUNTIME_DEFAULTS.storage;
-const EMPTY_CATALOG = (): KnowledgeCatalog => ({ version: 2, updatedAt: new Date().toISOString(), items: [] });
 const SAFE_ID_RE = /^[a-z0-9][a-z0-9-]{0,79}$/u;
+const SAFE_GENERATION_RE = /^[0-9TZ-]+-[a-f0-9]{12}$/u;
+const PROJECT_SCOPE_RE = /^project:[a-f0-9]{16}$/u;
+
+export class KnowledgeCommitBusyError extends Error {}
+
+function emptyCatalog(): KnowledgeCatalog {
+  return { version: 3, updatedAt: new Date().toISOString(), items: [] };
+}
+
+function emptyManifest(): KnowledgeManifest {
+  return {
+    version: 3, generationId: "", createdAt: new Date().toISOString(), leaderToken: "",
+    catalog: emptyCatalog(), reviews: {},
+  };
+}
 
 function ensureDirectory(path: string): void {
   mkdirSync(path, { recursive: true, mode: 0o700 });
@@ -30,30 +47,65 @@ function atomicWrite(path: string, content: string): void {
 
 export function ensureKnowledgeDirectories(home = homedir()): void {
   const paths = userRuntimePaths(home);
-  for (const path of [paths.knowledge, paths.knowledgeRules, paths.knowledgeTopics, paths.knowledgePending]) {
-    ensureDirectory(path);
-  }
+  for (const path of [paths.knowledge, paths.knowledgeGenerations, paths.knowledgeRuntime]) ensureDirectory(path);
 }
 
 export function projectKnowledgeKey(projectRoot: string): string {
   return createHash("sha256").update(resolve(projectRoot)).digest("hex").slice(0, 16);
 }
 
-export function loadKnowledgeCatalog(home = homedir()): KnowledgeCatalog {
-  const path = userRuntimePaths(home).knowledgeCatalog;
-  if (!existsSync(path)) return EMPTY_CATALOG();
+function generationDirectory(generationId: string, home: string): string | undefined {
+  if (!SAFE_GENERATION_RE.test(generationId)) return undefined;
+  const root = resolve(userRuntimePaths(home).knowledgeGenerations);
+  const directory = resolve(root, generationId);
+  return directory.startsWith(`${root}${sep}`) ? directory : undefined;
+}
+
+function parseManifest(path: string): KnowledgeManifest | undefined {
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8")) as KnowledgeCatalog;
-    if (parsed.version === 2 && Array.isArray(parsed.items)) return parsed;
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as KnowledgeManifest;
+    if (parsed.version !== 3 || !SAFE_GENERATION_RE.test(parsed.generationId)
+      || parsed.catalog?.version !== 3 || !Array.isArray(parsed.catalog.items)
+      || !parsed.reviews || typeof parsed.reviews !== "object") return undefined;
+    return parsed;
   } catch {
-    // The active schema never falls back to legacy index.json or records/ data.
+    return undefined;
+  }
+}
+
+function validManifestAt(manifest: KnowledgeManifest, directory: string): boolean {
+  return manifest.catalog.items.every((entry) => {
+    if (!SAFE_ID_RE.test(entry.id) || basename(entry.file) !== `${entry.id}.md`) return false;
+    if (entry.scope !== "global" && !PROJECT_SCOPE_RE.test(entry.scope)) return false;
+    const path = resolve(directory, entry.file);
+    return path.startsWith(`${directory}${sep}`) && existsSync(path);
+  });
+}
+
+function validManifest(manifest: KnowledgeManifest, home: string): boolean {
+  const directory = generationDirectory(manifest.generationId, home);
+  return Boolean(directory && validManifestAt(manifest, directory));
+}
+
+export function loadCurrentManifest(home = homedir()): KnowledgeManifest {
+  ensureKnowledgeDirectories(home);
+  const paths = userRuntimePaths(home);
+  const preferred = existsSync(paths.knowledgeCurrent) ? readFileSync(paths.knowledgeCurrent, "utf8").trim() : "";
+  const candidates = [preferred, ...readdirSync(paths.knowledgeGenerations, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && SAFE_GENERATION_RE.test(entry.name))
+    .map((entry) => entry.name).sort().reverse()]
+    .filter((value, index, values) => value && values.indexOf(value) === index);
+  for (const generationId of candidates) {
+    const directory = generationDirectory(generationId, home);
+    if (!directory) continue;
+    const manifest = parseManifest(join(directory, "manifest.json"));
+    if (manifest && manifest.generationId === generationId && validManifest(manifest, home)) return manifest;
   }
-  return EMPTY_CATALOG();
+  return emptyManifest();
 }
 
-function saveCatalog(catalog: KnowledgeCatalog, home: string): void {
-  catalog.updatedAt = new Date().toISOString();
-  atomicWrite(userRuntimePaths(home).knowledgeCatalog, `${JSON.stringify(catalog, null, 2)}\n`);
+export function loadKnowledgeCatalog(home = homedir()): KnowledgeCatalog {
+  return loadCurrentManifest(home).catalog;
 }
 
 function normalizeSlug(value: string): string {
@@ -81,26 +133,20 @@ function normalizeCandidate(value: unknown, projectKey: string): KnowledgeCandid
   if (typeof raw.key !== "string" || typeof raw.title !== "string" || typeof raw.summary !== "string"
     || typeof raw.body !== "string" || typeof raw.confidence !== "number") return undefined;
   if (raw.confidence < KNOWLEDGE_RUNTIME_DEFAULTS.review.minimumConfidence) return undefined;
-  const storageHint: KnowledgeTrack = raw.storageHint === "rule" ? "rule" : "topic";
   const explicitUserDirective = raw.explicitUserDirective === true;
-  const requestedScope = raw.scope === "global" ? "global" : `project:${projectKey}`;
-  const scope: KnowledgeScope = requestedScope === "global" && explicitUserDirective ? "global" : `project:${projectKey}`;
+  const scope: KnowledgeScope = raw.scope === "global" && explicitUserDirective ? "global" : `project:${projectKey}`;
   const body = compactKnowledgeText(raw.body, 20_000);
   const evidence = asStringArray(raw.evidence, 8);
   if (!body || evidence.length === 0) return undefined;
-  const ruleEligible = body.length <= STORAGE.maxRuleChars
-    && body.split("\n").length <= STORAGE.maxRuleFileLines
+  const requestedTrack: KnowledgeTrack = raw.storageHint === "rule" ? "rule" : "topic";
+  const ruleEligible = body.length <= STORAGE.maxRuleChars && body.split("\n").length <= STORAGE.maxRuleFileLines
     && (explicitUserDirective || raw.confidence >= 0.9);
   return {
-    key: compactKnowledgeText(raw.key, 160),
-    title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
+    key: compactKnowledgeText(raw.key, 160), title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
     summary: compactKnowledgeText(raw.summary, STORAGE.maxSummaryChars),
     keywords: asStringArray(raw.keywords, STORAGE.maxKeywordCount).map((keyword) => keyword.toLowerCase()),
-    scope,
-    body,
-    evidence,
-    confidence: Math.min(1, raw.confidence),
-    storageHint: storageHint === "rule" && ruleEligible ? "rule" : "topic",
+    scope, body, evidence, confidence: Math.min(1, raw.confidence),
+    storageHint: requestedTrack === "rule" && ruleEligible ? "rule" : "topic",
     action: raw.action === "revise" ? "revise" : raw.action === "reinforce" ? "reinforce" : "add",
     explicitUserDirective,
   };
@@ -109,41 +155,19 @@ function normalizeCandidate(value: unknown, projectKey: string): KnowledgeCandid
 function renderKnowledgeFile(candidate: KnowledgeCandidate): string {
   if (candidate.storageHint === "rule") return `# ${candidate.title}\n\n${candidate.body}\n`;
   return [
-    `# ${candidate.title}`,
-    "",
-    candidate.summary,
-    "",
-    `Keywords: ${candidate.keywords.join(", ")}`,
-    "",
-    candidate.body,
-    "",
-    "## Evidence",
-    "",
-    ...candidate.evidence.map((item) => `- ${item}`),
-    "",
+    `# ${candidate.title}`, "", candidate.summary, "", `Keywords: ${candidate.keywords.join(", ")}`, "",
+    candidate.body, "", "## Evidence", "", ...candidate.evidence.map((item) => `- ${item}`), "",
   ].join("\n");
 }
 
-function storedRuleCharacters(home: string): number {
-  const directory = userRuntimePaths(home).knowledgeRules;
-  if (!existsSync(directory)) return 0;
-  return readdirSync(directory, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
-    .reduce((total, entry) => total + readFileSync(join(directory, entry.name), "utf8").length, 0);
-}
-
-function savePending(candidate: KnowledgeCandidate, reason: string, home: string): void {
-  const paths = userRuntimePaths(home);
-  const name = `${Date.now()}-${normalizeSlug(candidate.title)}-${randomUUID().slice(0, 8)}.json`;
-  atomicWrite(join(paths.knowledgePending, name), `${JSON.stringify({ reason, candidate, createdAt: new Date().toISOString() }, null, 2)}\n`);
+function applicable(entry: KnowledgeCatalogEntry, projectKey: string): boolean {
+  return entry.scope === "global" || entry.scope === `project:${projectKey}`;
 }
 
 function generateMemory(catalog: KnowledgeCatalog, projectKey?: string): string {
   const lines = [
-    "# HWCode Knowledge Index",
-    "",
-    "Detailed topics are loaded only through hwcode_knowledge_lookup. Search by ID or keywords.",
-    "",
+    "# HWCode Knowledge Index", "",
+    "Detailed topics are loaded only through hwcode_knowledge_lookup. Search by ID or keywords.", "",
   ];
   const topics = catalog.items.filter((item) => item.track === "topic" && (!projectKey || applicable(item, projectKey)))
     .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
@@ -159,93 +183,183 @@ function generateMemory(catalog: KnowledgeCatalog, projectKey?: string): string
   return `${lines.join("\n")}\n`;
 }
 
-function writeMemory(catalog: KnowledgeCatalog, home: string): void {
-  atomicWrite(userRuntimePaths(home).knowledgeMemory, generateMemory(catalog));
+function processExists(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
 }
 
-export function persistKnowledgeCandidates(
-  values: unknown[],
-  projectKey: string,
-  home = homedir(),
-): PersistKnowledgeResult {
-  ensureKnowledgeDirectories(home);
-  const catalog = loadKnowledgeCatalog(home);
-  const result: PersistKnowledgeResult = { saved: 0, updated: 0, pending: 0, skipped: 0 };
-  for (const value of values.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates)) {
-    const candidate = normalizeCandidate(value, projectKey);
-    if (!candidate) { result.skipped++; continue; }
-    const fingerprint = normalizedFingerprint(candidate);
-    const hash = contentHash(candidate);
-    const existingIndex = catalog.items.findIndex((item) => item.fingerprint === fingerprint);
-    const existing = existingIndex >= 0 ? catalog.items[existingIndex] : undefined;
-    if (existing?.contentHash === hash) {
-      existing.evidenceCount += candidate.evidence.length;
-      existing.updatedAt = new Date().toISOString();
-      result.updated++;
-      continue;
+function acquireCommitLock(leaderToken: string, home: string): () => void {
+  const paths = userRuntimePaths(home);
+  ensureDirectory(paths.knowledgeRuntime);
+  const attempt = (): boolean => {
+    try {
+      mkdirSync(paths.knowledgeCommitLock, { mode: 0o700 });
+      writeFileSync(join(paths.knowledgeCommitLock, "owner.json"), JSON.stringify({ pid: process.pid, leaderToken }), { mode: 0o600 });
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      return false;
     }
-    if (existing && !(candidate.action === "revise" && (candidate.explicitUserDirective || candidate.confidence >= 0.92))) {
-      savePending(candidate, "conflicting-or-ambiguous-update", home);
-      result.pending++;
-      continue;
+  };
+  if (!attempt()) {
+    try {
+      const owner = JSON.parse(readFileSync(join(paths.knowledgeCommitLock, "owner.json"), "utf8")) as {
+        pid?: number; leaderToken?: string;
+      };
+      if (owner.leaderToken !== leaderToken || (typeof owner.pid === "number" && !processExists(owner.pid))) {
+        rmSync(paths.knowledgeCommitLock, { recursive: true, force: true });
+      }
+    } catch {
+      const age = Date.now() - statSync(paths.knowledgeCommitLock).mtimeMs;
+      if (age > KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs) rmSync(paths.knowledgeCommitLock, { recursive: true, force: true });
     }
-    if (!existing && candidate.storageHint === "rule"
-      && storedRuleCharacters(home) + renderKnowledgeFile(candidate).length > STORAGE.maxRulesPromptChars) {
-      candidate.storageHint = "topic";
+    if (!attempt()) throw new KnowledgeCommitBusyError("Knowledge repository is busy");
+  }
+  return () => rmSync(paths.knowledgeCommitLock, { recursive: true, force: true });
+}
+
+function newGenerationId(): string {
+  return `${new Date().toISOString().replace(/[:.]/gu, "-")}-${randomUUID().replace(/-/gu, "").slice(0, 12)}`;
+}
+
+function copyCurrentContent(manifest: KnowledgeManifest, target: string, home: string): void {
+  for (const name of ["rules", "topics", "pending"]) ensureDirectory(join(target, name));
+  if (!manifest.generationId) return;
+  const source = generationDirectory(manifest.generationId, home);
+  if (!source) return;
+  for (const name of ["rules", "topics", "pending"]) {
+    const sourceDirectory = join(source, name);
+    if (!existsSync(sourceDirectory)) continue;
+    for (const entry of readdirSync(sourceDirectory, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const sourceFile = join(sourceDirectory, entry.name);
+      const targetFile = join(target, name, entry.name);
+      try { linkSync(sourceFile, targetFile); } catch { copyFileSync(sourceFile, targetFile); }
     }
-    const now = new Date().toISOString();
-    const id = existing?.id ?? `${normalizeSlug(candidate.title)}-${fingerprint.slice(0, 8)}`;
-    const track = existing?.track ?? candidate.storageHint;
-    candidate.storageHint = track;
-    const relativeFile = `${track === "rule" ? "rules" : "topics"}/${id}.md`;
-    const absoluteFile = join(userRuntimePaths(home).knowledge, relativeFile);
-    atomicWrite(absoluteFile, renderKnowledgeFile(candidate));
-    const entry: KnowledgeCatalogEntry = {
-      id, fingerprint, contentHash: hash, title: candidate.title, summary: candidate.summary,
-      keywords: candidate.keywords, scope: candidate.scope, track, file: relativeFile,
-      evidenceCount: (existing?.evidenceCount ?? 0) + candidate.evidence.length,
-      createdAt: existing?.createdAt ?? now, updatedAt: now,
-    };
-    if (existingIndex >= 0) { catalog.items[existingIndex] = entry; result.updated++; }
-    else { catalog.items.push(entry); result.saved++; }
   }
-  saveCatalog(catalog, home);
-  writeMemory(catalog, home);
-  return result;
 }
 
-function applicable(entry: KnowledgeCatalogEntry, projectKey: string): boolean {
-  return entry.scope === "global" || entry.scope === `project:${projectKey}`;
+function storedRuleCharacters(directory: string): number {
+  return readdirSync(join(directory, "rules"), { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .reduce((total, entry) => total + readFileSync(join(directory, "rules", entry.name), "utf8").length, 0);
+}
+
+function reviewCursor(task: KnowledgeReviewTask): KnowledgeReviewCursor {
+  return {
+    sessionId: task.sessionId, sessionKey: task.sessionKey, sessionFileHash: task.sessionFileHash,
+    projectRoot: task.projectRoot, projectKey: task.projectKey, lastReviewedEntryId: task.lastEntryId,
+    lastReviewedAt: new Date().toISOString(), lastDeltaDigest: task.deltaDigest,
+    lastReviewKey: task.reviewKey, fileSize: task.fileSize, fileMtimeMs: task.fileMtimeMs,
+  };
 }
 
-function readCatalogFile(entry: KnowledgeCatalogEntry, home: string): string | undefined {
+export function commitKnowledgeReview(
+  values: unknown[], task: KnowledgeReviewTask, leaderToken: string, home = homedir(),
+): PersistKnowledgeResult {
+  ensureKnowledgeDirectories(home);
+  const release = acquireCommitLock(leaderToken, home);
+  const paths = userRuntimePaths(home);
+  let temporary = "";
+  try {
+    const current = loadCurrentManifest(home);
+    if (current.reviews[task.sessionKey]?.lastReviewKey === task.reviewKey) {
+      return { saved: 0, updated: 0, pending: 0, skipped: 0 };
+    }
+    const generationId = newGenerationId();
+    temporary = join(paths.knowledgeGenerations, `.tmp-${generationId}-${process.pid}`);
+    ensureDirectory(temporary);
+    copyCurrentContent(current, temporary, home);
+    const catalog: KnowledgeCatalog = structuredClone(current.catalog);
+    const result: PersistKnowledgeResult = { saved: 0, updated: 0, pending: 0, skipped: 0 };
+    for (const value of values.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates)) {
+      const candidate = normalizeCandidate(value, task.projectKey);
+      if (!candidate) { result.skipped++; continue; }
+      const fingerprint = normalizedFingerprint(candidate);
+      const hash = contentHash(candidate);
+      const existingIndex = catalog.items.findIndex((item) => item.fingerprint === fingerprint);
+      const existing = existingIndex >= 0 ? catalog.items[existingIndex] : undefined;
+      if (existing?.contentHash === hash) {
+        existing.evidenceCount += candidate.evidence.length;
+        existing.updatedAt = new Date().toISOString();
+        result.updated++;
+        continue;
+      }
+      if (existing && !(candidate.action === "revise" && (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++;
+        continue;
+      }
+      if (!existing && candidate.storageHint === "rule"
+        && storedRuleCharacters(temporary) + renderKnowledgeFile(candidate).length > STORAGE.maxRulesPromptChars) {
+        candidate.storageHint = "topic";
+      }
+      const now = new Date().toISOString();
+      const id = existing?.id ?? `${normalizeSlug(candidate.title)}-${fingerprint.slice(0, 8)}`;
+      const track = existing?.track ?? candidate.storageHint;
+      candidate.storageHint = track;
+      const relativeFile = `${track === "rule" ? "rules" : "topics"}/${id}.md`;
+      atomicWrite(join(temporary, relativeFile), renderKnowledgeFile(candidate));
+      const entry: KnowledgeCatalogEntry = {
+        id, fingerprint, contentHash: hash, title: candidate.title, summary: candidate.summary,
+        keywords: candidate.keywords, scope: candidate.scope, track, file: relativeFile,
+        evidenceCount: (existing?.evidenceCount ?? 0) + candidate.evidence.length,
+        createdAt: existing?.createdAt ?? now, updatedAt: now,
+      };
+      if (existingIndex >= 0) { catalog.items[existingIndex] = entry; result.updated++; }
+      else { catalog.items.push(entry); result.saved++; }
+    }
+    catalog.updatedAt = new Date().toISOString();
+    const manifest: KnowledgeManifest = {
+      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, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    if (!validManifestAt(manifest, temporary)) throw new Error("Refusing to publish an incomplete knowledge generation");
+    const finalDirectory = join(paths.knowledgeGenerations, generationId);
+    renameSync(temporary, finalDirectory);
+    temporary = "";
+    atomicWrite(paths.knowledgeCurrent, `${generationId}\n`);
+    return result;
+  } finally {
+    if (temporary) rmSync(temporary, { recursive: true, force: true });
+    release();
+  }
+}
+
+function readCatalogFile(entry: KnowledgeCatalogEntry, manifest: KnowledgeManifest, home: string): string | undefined {
   if (!SAFE_ID_RE.test(entry.id) || basename(entry.file) !== `${entry.id}.md`) return undefined;
-  const root = resolve(userRuntimePaths(home).knowledge);
+  const root = generationDirectory(manifest.generationId, home);
+  if (!root) return undefined;
   const path = resolve(root, entry.file);
   if (!path.startsWith(`${root}${sep}`) || !existsSync(path)) return undefined;
   return sanitizeKnowledgeText(readFileSync(path, "utf8"));
 }
 
 export function loadKnowledgeSnapshot(projectKey: string, home = homedir()): KnowledgeSnapshot {
-  ensureKnowledgeDirectories(home);
-  const catalog = loadKnowledgeCatalog(home);
-  const ruleParts: string[] = [];
-  const paths = userRuntimePaths(home);
-  for (const file of readdirSync(paths.knowledgeRules, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith(".md")).sort((left, right) => left.name.localeCompare(right.name))) {
-    const relativeFile = `rules/${file.name}`;
-    const entry = catalog.items.find((item) => item.file === relativeFile);
-    if (entry && !applicable(entry, projectKey)) continue;
-    ruleParts.push(sanitizeKnowledgeText(readFileSync(join(paths.knowledgeRules, file.name), "utf8")).trim());
+  const manifest = loadCurrentManifest(home);
+  if (!manifest.generationId) {
+    return { rulesPrompt: "", memoryPrompt: generateMemory(manifest.catalog, projectKey), catalog: manifest.catalog };
   }
-  const memoryPrompt = generateMemory(catalog, projectKey);
-  return { rulesPrompt: ruleParts.join("\n\n"), memoryPrompt, catalog };
+  const rules = manifest.catalog.items.filter((entry) => entry.track === "rule" && applicable(entry, projectKey))
+    .sort((left, right) => left.file.localeCompare(right.file))
+    .map((entry) => readCatalogFile(entry, manifest, home)).filter((content): content is string => Boolean(content));
+  return {
+    generationId: manifest.generationId, rulesPrompt: rules.join("\n\n"),
+    memoryPrompt: generateMemory(manifest.catalog, projectKey), catalog: manifest.catalog,
+  };
 }
 
-export function loadKnowledgeById(id: string, projectKey: string, home = homedir()): { entry: KnowledgeCatalogEntry; content: string } | undefined {
+export function loadKnowledgeById(
+  id: string, projectKey: string, home = homedir(),
+): { entry: KnowledgeCatalogEntry; content: string } | undefined {
   if (!SAFE_ID_RE.test(id)) return undefined;
-  const entry = loadKnowledgeCatalog(home).items.find((item) => item.id === id && applicable(item, projectKey));
+  const manifest = loadCurrentManifest(home);
+  const entry = manifest.catalog.items.find((item) => item.id === id && applicable(item, projectKey));
   if (!entry) return undefined;
-  const content = readCatalogFile(entry, home);
+  const content = readCatalogFile(entry, manifest, home);
   return content ? { entry, content } : undefined;
 }

package/.pi/lib/knowledge/types.ts

@@ -32,23 +32,39 @@ export interface KnowledgeCatalogEntry {
 }
 
 export interface KnowledgeCatalog {
-  version: 2;
+  version: 3;
   updatedAt: string;
   items: KnowledgeCatalogEntry[];
 }
 
 export interface KnowledgeSnapshot {
+  generationId?: string;
   rulesPrompt: string;
   memoryPrompt: string;
   catalog: KnowledgeCatalog;
 }
 
-export interface KnowledgeReviewState {
-  version: 1;
+export interface KnowledgeReviewCursor {
+  sessionId: string;
+  sessionKey: string;
+  sessionFileHash: string;
+  projectRoot: string;
+  projectKey: string;
   lastReviewedEntryId?: string;
   lastReviewedAt?: string;
-  lastDeltaDigest?: string;
-  lastResult?: "saved" | "noop";
+  lastDeltaDigest: string;
+  lastReviewKey: string;
+  fileSize: number;
+  fileMtimeMs: number;
+}
+
+export interface KnowledgeManifest {
+  version: 3;
+  generationId: string;
+  createdAt: string;
+  leaderToken: string;
+  catalog: KnowledgeCatalog;
+  reviews: Record<string, KnowledgeReviewCursor>;
 }
 
 export interface PersistKnowledgeResult {
@@ -57,3 +73,19 @@ export interface PersistKnowledgeResult {
   pending: number;
   skipped: number;
 }
+
+export interface KnowledgeReviewTask {
+  requestId: string;
+  reviewKey: string;
+  sessionId: string;
+  sessionKey: string;
+  sessionFileHash: string;
+  projectRoot: string;
+  projectKey: string;
+  firstEntryId: string;
+  lastEntryId: string;
+  delta: string;
+  deltaDigest: string;
+  fileSize: number;
+  fileMtimeMs: number;
+}

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

@@ -1,12 +1,20 @@
-import type { PersistKnowledgeResult } from "./types.ts";
+import type { KnowledgeReviewTask, PersistKnowledgeResult } from "./types.ts";
 
 export type KnowledgeWorkerInput =
-  | { type: "configure"; sessionId: string; projectKey: string; dirty: boolean }
-  | { type: "activity"; state: "busy" | "settled"; dirty?: boolean }
-  | { type: "review_result"; requestId: string; raw?: string; error?: string }
+  | { type: "configure"; modelAvailable: boolean; sessionsRoot: string }
+  | { type: "review_result"; leaderToken: string; requestId: string; raw?: string; error?: string }
+  | { type: "scan_now" }
   | { type: "stop" };
 
 export type KnowledgeWorkerOutput =
-  | { type: "review_due"; requestId: string }
-  | { type: "review_saved"; requestId: string; result: PersistKnowledgeResult }
-  | { type: "review_failed"; requestId: string; error: string };
+  | { type: "leadership"; state: "leader" | "standby" | "ineligible"; leaderToken?: string }
+  | { type: "review_request"; leaderToken: string; requestId: string; task: KnowledgeReviewTask }
+  | { type: "review_cancel"; requestId: string; reason: string }
+  | { type: "review_saved"; requestId: string; generationId?: string; result: PersistKnowledgeResult }
+  | { type: "review_failed"; requestId?: string; error: string }
+  | { type: "generation_changed"; generationId: string };
+
+export interface CoordinatorBroadcast {
+  type: "generation_changed";
+  generationId: string;
+}

package/.pi/lib/runtime/defaults.ts

@@ -20,7 +20,7 @@ export const CLOUD_RUNTIME_DEFAULTS = Object.freeze({
 });
 
 /**
- * Defaults for the cross-workflow knowledge base (`~/.hwcode/knowledge/`).
+ * Defaults for the cross-workflow knowledge base (`~/.hwcode/knowledge-v3/`).
  *
  * A Worker checks settled sessions on a fixed interval. Short rules are loaded
  * in full; detailed topics are routed through a bounded MEMORY.md index so the
@@ -29,8 +29,11 @@ export const CLOUD_RUNTIME_DEFAULTS = Object.freeze({
 export const KNOWLEDGE_RUNTIME_DEFAULTS = Object.freeze({
   review: Object.freeze({
     intervalMs: 60_000,
+    idleMs: 60_000,
+    capabilityPollMs: 5_000,
+    modelTimeoutMs: 120_000,
     maxDeltaChars: 30_000,
-    maxCandidates: 3,
+    maxCandidates: 8,
     minimumConfidence: 0.72,
   }),
   storage: Object.freeze({

package/.pi/lib/runtime/paths.ts

@@ -12,7 +12,7 @@ const CLOUD_VAULT_FILE = "credentials.enc";
 const CLOUD_KNOWN_HOSTS_FILE = "known_hosts";
 const CLOUD_TEMPLATES_SUBDIR = "templates";
 const CLOUD_TERRAFORM_SUBDIR = "terraform";
-const KNOWLEDGE_SUBDIR = "knowledge";
+const KNOWLEDGE_SUBDIR = "knowledge-v3";
 
 export interface ProjectRuntimePaths {
   root: string;
@@ -29,11 +29,13 @@ export interface UserRuntimePaths {
   cloudKnownHosts: string;
   cloudTerraformTemplates: string;
   knowledge: string;
-  knowledgeRules: string;
-  knowledgeTopics: string;
-  knowledgePending: string;
-  knowledgeCatalog: string;
-  knowledgeMemory: string;
+  knowledgeGenerations: string;
+  knowledgeCurrent: string;
+  knowledgeRuntime: string;
+  knowledgeCoordinatorSocket: string;
+  knowledgeLeader: string;
+  knowledgeCommitLock: string;
+  knowledgeElectionLock: string;
 }
 
 export function projectRuntimePaths(projectRoot: string): ProjectRuntimePaths {
@@ -60,11 +62,14 @@ export function userRuntimePaths(home = homedir()): UserRuntimePaths {
     cloudKnownHosts: join(cloud, CLOUD_KNOWN_HOSTS_FILE),
     cloudTerraformTemplates: join(cloud, CLOUD_TEMPLATES_SUBDIR, CLOUD_TERRAFORM_SUBDIR),
     knowledge,
-    knowledgeRules: join(knowledge, "rules"),
-    knowledgeTopics: join(knowledge, "topics"),
-    knowledgePending: join(knowledge, "pending"),
-    knowledgeCatalog: join(knowledge, "catalog.json"),
-    knowledgeMemory: join(knowledge, "MEMORY.md"),
+    knowledgeGenerations: join(knowledge, "generations"),
+    knowledgeCurrent: join(knowledge, "CURRENT"),
+    knowledgeRuntime: join(knowledge, "runtime"),
+    // Unix-domain socket paths are short on purpose (macOS caps them at roughly 104 bytes).
+    knowledgeCoordinatorSocket: join(root, "knowledge-v3.sock"),
+    knowledgeLeader: join(knowledge, "runtime", "leader.json"),
+    knowledgeCommitLock: join(knowledge, "runtime", "commit.lock"),
+    knowledgeElectionLock: join(knowledge, "runtime", "election.lock"),
   };
 }