@hadooppei/hwcode 1.0.9 → 1.0.10

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

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.js";
+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, delta) {
+    return `Project root: ${projectRoot}\n\n<conversation_delta>\n${delta}\n</conversation_delta>`;
+}
+export function parseCandidateEnvelope(text) {
+    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));
+    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) {
+    return createHash("sha256").update(delta).digest("hex");
+}

package/.pi/dist/lib/knowledge/review-worker.js

@@ -0,0 +1,292 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { createConnection, createServer } from "node:net";
+import { homedir } from "node:os";
+import { parentPort, workerData } from "node:worker_threads";
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.js";
+import { userRuntimePaths } from "../runtime/paths.js";
+import { parseCandidateEnvelope } from "./extractor.js";
+import { findNextReviewTask } from "./session-scanner.js";
+import { commitKnowledgeReview, ensureKnowledgeDirectories, loadCurrentManifest } from "./store.js";
+if (!parentPort)
+    throw new Error("Knowledge review worker requires a parent port");
+const home = workerData?.home ?? homedir();
+const paths = userRuntimePaths(home);
+const standbySockets = new Set();
+let eligible = false;
+let stopped = false;
+let sessionsRoot = "";
+let leaderServer;
+let leaderToken = "";
+let standbySocket;
+let electionPending = false;
+let activeTask;
+function send(message) {
+    parentPort.postMessage(message);
+}
+function coordinatorPath() {
+    return process.platform === "win32"
+        ? `\\\\.\\pipe\\hwcode-knowledge-v3-${Buffer.from(home).toString("hex").slice(0, 16)}`
+        : paths.knowledgeCoordinatorSocket;
+}
+function writeLeaderMetadata() {
+    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) {
+    try {
+        const current = JSON.parse(readFileSync(paths.knowledgeLeader, "utf8"));
+        if (current.leaderToken === token)
+            rmSync(paths.knowledgeLeader, { force: true });
+    }
+    catch { /* Another contender may already have replaced it. */ }
+}
+function broadcast(message) {
+    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)) {
+    if (!eligible || stopped || electionPending || leaderServer || standbySocket)
+        return;
+    electionPending = true;
+    const timer = setTimeout(() => {
+        electionPending = false;
+        attemptElection();
+    }, delay);
+    timer.unref();
+}
+function stepDown(reason) {
+    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) {
+    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);
+                if (message.type === "generation_changed")
+                    send(message);
+            }
+            catch { /* Ignore malformed coordinator notifications. */ }
+        }
+    });
+    socket.once("close", () => {
+        if (standbySocket === socket)
+            standbySocket = undefined;
+        scheduleElection();
+    });
+}
+function cleanStaleSocketAndRetry() {
+    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) {
+    if (!eligible || stopped || leaderServer || standbySocket)
+        return;
+    const socket = createConnection(coordinatorPath());
+    let connected = false;
+    socket.once("connect", () => { connected = true; becomeStandby(socket); });
+    socket.once("error", (error) => {
+        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) {
+    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() {
+    if (!eligible || stopped || leaderServer || standbySocket)
+        return;
+    ensureKnowledgeDirectories(home);
+    const server = createServer();
+    const electionError = (error) => {
+        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() {
+    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) {
+    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) => {
+    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);
+});
+send({ type: "ready" });

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

@@ -0,0 +1,24 @@
+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) {
+    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, separator) => `${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, maxChars) {
+    return sanitizeKnowledgeText(value)
+        .replace(/\r\n/gu, "\n")
+        .replace(/[ \t]+$/gmu, "")
+        .trim()
+        .slice(0, maxChars);
+}

package/.pi/dist/lib/knowledge/session-scanner.js

@@ -0,0 +1,165 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { buildContextEntries, parseSessionEntries, } from "@earendil-works/pi-coding-agent";
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.js";
+import { knowledgeDeltaDigest } from "./extractor.js";
+import { sanitizeKnowledgeText } from "./sanitize.js";
+import { projectKnowledgeKey } from "./store.js";
+function hash(value, length = 64) {
+    return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+function textContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.map((item) => {
+        if (!item || typeof item !== "object")
+            return "";
+        const value = item;
+        return typeof value.text === "string" ? value.text : "";
+    }).filter(Boolean).join("\n");
+}
+function reviewPiece(entry, index) {
+    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;
+    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) {
+    const pieces = entries.map(reviewPiece).filter((piece) => Boolean(piece));
+    const selected = [];
+    const categoryRemaining = {
+        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, branch) {
+    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.cwd;
+        if (typeof cwd === "string" && cwd)
+            return resolve(cwd);
+    }
+    return resolve(header.cwd);
+}
+export function discoverSessionFiles(root) {
+    const files = [];
+    const visit = (directory) => {
+        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, cursor, now = Date.now()) {
+    let stat;
+    try {
+        stat = statSync(sessionFile);
+    }
+    catch {
+        return undefined;
+    }
+    if (!stat.isFile() || now - stat.mtimeMs < KNOWLEDGE_RUNTIME_DEFAULTS.review.idleMs)
+        return undefined;
+    let content;
+    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.type === "session");
+    if (!header?.id || !header.cwd)
+        return undefined;
+    const allEntries = parsed.filter((entry) => 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, reviews, now = Date.now()) {
+    const files = discoverSessionFiles(sessionsRoot).map((path) => {
+        try {
+            return { path, mtimeMs: statSync(path).mtimeMs };
+        }
+        catch {
+            return undefined;
+        }
+    }).filter((item) => 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;
+}

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

@@ -0,0 +1,370 @@
+import { createHash, randomUUID } from "node:crypto";
+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";
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.js";
+import { userRuntimePaths } from "../runtime/paths.js";
+import { compactKnowledgeText, sanitizeKnowledgeText } from "./sanitize.js";
+const STORAGE = KNOWLEDGE_RUNTIME_DEFAULTS.storage;
+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() {
+    return { version: 3, updatedAt: new Date().toISOString(), items: [] };
+}
+function emptyManifest() {
+    return {
+        version: 3, generationId: "", createdAt: new Date().toISOString(), leaderToken: "",
+        catalog: emptyCatalog(), reviews: {},
+    };
+}
+function ensureDirectory(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    chmodSync(path, 0o700);
+}
+function atomicWrite(path, content) {
+    ensureDirectory(dirname(path));
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
+    renameSync(temporary, path);
+    chmodSync(path, 0o600);
+}
+export function ensureKnowledgeDirectories(home = homedir()) {
+    const paths = userRuntimePaths(home);
+    for (const path of [paths.knowledge, paths.knowledgeGenerations, paths.knowledgeRuntime])
+        ensureDirectory(path);
+}
+export function projectKnowledgeKey(projectRoot) {
+    return createHash("sha256").update(resolve(projectRoot)).digest("hex").slice(0, 16);
+}
+function generationDirectory(generationId, home) {
+    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) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        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 {
+        return undefined;
+    }
+}
+function validManifestAt(manifest, directory) {
+    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, home) {
+    const directory = generationDirectory(manifest.generationId, home);
+    return Boolean(directory && validManifestAt(manifest, directory));
+}
+export function loadCurrentManifest(home = homedir()) {
+    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 emptyManifest();
+}
+export function loadKnowledgeCatalog(home = homedir()) {
+    return loadCurrentManifest(home).catalog;
+}
+function normalizeSlug(value) {
+    return value.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^-+|-+$/gu, "").slice(0, STORAGE.slugMaxChars) || "knowledge";
+}
+function normalizedFingerprint(candidate) {
+    return createHash("sha256").update(`${candidate.scope}\0${candidate.key.trim().toLowerCase()}`).digest("hex");
+}
+function contentHash(candidate) {
+    return createHash("sha256").update(`${candidate.title}\0${candidate.summary}\0${candidate.body}`).digest("hex");
+}
+function asStringArray(value, maxItems) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.filter((item) => typeof item === "string")
+            .map((item) => compactKnowledgeText(item, 240)).filter(Boolean))].slice(0, maxItems);
+}
+function normalizeCandidate(value, projectKey) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const raw = value;
+    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 explicitUserDirective = raw.explicitUserDirective === true;
+    const scope = 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 requestedTrack = 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),
+        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: requestedTrack === "rule" && ruleEligible ? "rule" : "topic",
+        action: raw.action === "revise" ? "revise" : raw.action === "reinforce" ? "reinforce" : "add",
+        explicitUserDirective,
+    };
+}
+function renderKnowledgeFile(candidate) {
+    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}`), "",
+    ].join("\n");
+}
+function applicable(entry, projectKey) {
+    return entry.scope === "global" || entry.scope === `project:${projectKey}`;
+}
+function generateMemory(catalog, projectKey) {
+    const lines = [
+        "# 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));
+    for (const item of topics) {
+        const scope = item.scope === "global" ? "global" : "project";
+        const line = `- [${item.id}] (${scope}; ${item.keywords.join(", ")}) ${item.title}: ${item.summary}`;
+        if (lines.length + 1 >= STORAGE.maxMemoryLines || [...lines, line].join("\n").length > STORAGE.maxMemoryChars) {
+            lines.push("- Additional topics remain searchable through hwcode_knowledge_lookup(query: \"keywords\").");
+            break;
+        }
+        lines.push(line);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function acquireCommitLock(leaderToken, home) {
+    const paths = userRuntimePaths(home);
+    ensureDirectory(paths.knowledgeRuntime);
+    const attempt = () => {
+        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.code !== "EEXIST")
+                throw error;
+            return false;
+        }
+    };
+    if (!attempt()) {
+        try {
+            const owner = JSON.parse(readFileSync(join(paths.knowledgeCommitLock, "owner.json"), "utf8"));
+            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 (!attempt())
+            throw new KnowledgeCommitBusyError("Knowledge repository is busy");
+    }
+    return () => rmSync(paths.knowledgeCommitLock, { recursive: true, force: true });
+}
+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"])
+        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);
+            }
+        }
+    }
+}
+function storedRuleCharacters(directory) {
+    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) {
+    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,
+    };
+}
+export function commitKnowledgeReview(values, task, leaderToken, home = homedir()) {
+    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 = structuredClone(current.catalog);
+        const result = { 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 = {
+                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 = {
+            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, manifest, home) {
+    if (!SAFE_ID_RE.test(entry.id) || basename(entry.file) !== `${entry.id}.md`)
+        return undefined;
+    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, home = homedir()) {
+    const manifest = loadCurrentManifest(home);
+    if (!manifest.generationId) {
+        return { rulesPrompt: "", memoryPrompt: generateMemory(manifest.catalog, projectKey), catalog: manifest.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) => Boolean(content));
+    return {
+        generationId: manifest.generationId, rulesPrompt: rules.join("\n\n"),
+        memoryPrompt: generateMemory(manifest.catalog, projectKey), catalog: manifest.catalog,
+    };
+}
+export function loadKnowledgeById(id, projectKey, home = homedir()) {
+    if (!SAFE_ID_RE.test(id))
+        return undefined;
+    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, manifest, home);
+    return content ? { entry, content } : undefined;
+}

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

@@ -0,0 +1 @@
+export {};

package/.pi/dist/lib/knowledge/worker-protocol.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,50 @@
+/** Internal product defaults and safety limits. User-overridable settings stay in settings.json. */
+export const CLOUD_RUNTIME_DEFAULTS = Object.freeze({
+    workflow: Object.freeze({ maxFailedApproaches: 3, maxSuccessfulSteps: 100 }),
+    process: Object.freeze({
+        commandTimeoutMs: 120_000,
+        providerValidationTimeoutMs: 30_000,
+        forceKillGraceMs: 2_000,
+        maxOutputBytes: 50_000,
+    }),
+    runner: Object.freeze({
+        defaultUser: "ubuntu",
+        defaultPort: 22,
+        keyCandidates: Object.freeze(["id_ed25519", "id_rsa"]),
+        hostKeyScanTimeoutMs: 15_000,
+        connectTimeoutSeconds: 15,
+        commandTimeoutMs: 120_000,
+    }),
+    templates: Object.freeze({ slugMaxLength: 48, nameMaxLength: 80 }),
+    terraform: Object.freeze({ executable: "terraform", planFile: "hwcode.tfplan" }),
+});
+/**
+ * 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
+ * prompt cost stays stable as the complete machine catalog grows.
+ */
+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: 8,
+        minimumConfidence: 0.72,
+    }),
+    storage: Object.freeze({
+        maxRuleChars: 600,
+        maxRuleFileLines: 40,
+        maxRulesPromptChars: 12_000,
+        maxMemoryChars: 25_000,
+        maxMemoryLines: 200,
+        maxSummaryChars: 180,
+        maxTitleChars: 100,
+        maxKeywordCount: 12,
+        maxLookupResults: 5,
+        slugMaxChars: 64,
+    }),
+});

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

@@ -0,0 +1,55 @@
+import { homedir } from "node:os";
+import { join, posix, resolve } from "node:path";
+export const HWCODE_DATA_DIRECTORY = ".hwcode";
+export const PROJECT_SDD_SPECS_RELATIVE = `${HWCODE_DATA_DIRECTORY}/specs`;
+export const PROJECT_CLOUD_RUNS_RELATIVE = `${HWCODE_DATA_DIRECTORY}/cloud/runs`;
+// Canonical subpath layout under ~/.hwcode. Kept together so filesystem topology
+// stays in one place instead of scattered across cloud/knowledge modules.
+const CLOUD_SUBDIR = "cloud";
+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-v3";
+export function projectRuntimePaths(projectRoot) {
+    const root = resolve(projectRoot);
+    const hwcode = join(root, HWCODE_DATA_DIRECTORY);
+    const cloud = join(hwcode, CLOUD_SUBDIR);
+    return {
+        root,
+        hwcode,
+        specs: join(hwcode, "specs"),
+        cloud,
+        cloudRuns: join(cloud, "runs"),
+    };
+}
+export function userRuntimePaths(home = homedir()) {
+    const root = join(home, HWCODE_DATA_DIRECTORY);
+    const cloud = join(root, CLOUD_SUBDIR);
+    const knowledge = join(root, KNOWLEDGE_SUBDIR);
+    return {
+        root,
+        cloud,
+        cloudVault: join(cloud, CLOUD_VAULT_FILE),
+        cloudKnownHosts: join(cloud, CLOUD_KNOWN_HOSTS_FILE),
+        cloudTerraformTemplates: join(cloud, CLOUD_TEMPLATES_SUBDIR, CLOUD_TERRAFORM_SUBDIR),
+        knowledge,
+        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"),
+    };
+}
+export function remoteRunnerPaths(user) {
+    const root = posix.join("/home", user, HWCODE_DATA_DIRECTORY);
+    return { root, runs: posix.join(root, "runs") };
+}
+export function profileResourcePath(fileName) {
+    return process.env.HWCODE_PROFILE_DIR
+        ? join(process.env.HWCODE_PROFILE_DIR, fileName)
+        : undefined;
+}

package/.pi/extensions/knowledge.ts

@@ -1,5 +1,7 @@
 import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
 import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Worker } from "node:worker_threads";
 
 import { Type } from "@earendil-works/pi-ai";
@@ -27,11 +29,17 @@ interface ProcessKnowledgeRuntime {
   modelAvailable?: boolean;
   activeReview?: ActiveReview;
   capabilityTimer?: NodeJS.Timeout;
+  workerRetryTimer?: NodeJS.Timeout;
+  workerRetryAttempt: number;
+  lastWorkerIssue?: { message: string; reportedAt: number };
 }
 
 const RUNTIME_SYMBOL = Symbol.for("hwcode.knowledge.runtime.v3");
 const processGlobals = globalThis as unknown as Record<PropertyKey, unknown>;
-const runtime = (processGlobals[RUNTIME_SYMBOL] ??= {}) as ProcessKnowledgeRuntime;
+const runtime = (processGlobals[RUNTIME_SYMBOL] ??= { workerRetryAttempt: 0 }) as ProcessKnowledgeRuntime;
+runtime.workerRetryAttempt ??= 0;
+
+const WORKER_RETRY_DELAYS_MS = [1_000, 5_000, 30_000, 60_000] as const;
 
 function post(message: KnowledgeWorkerInput): void {
   runtime.worker?.postMessage(message);
@@ -54,6 +62,37 @@ function cancelActiveReview(): void {
   runtime.activeReview?.controller.abort();
 }
 
+function reportWorkerIssue(error: unknown): void {
+  const message = error instanceof Error ? error.message : String(error);
+  const now = Date.now();
+  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}`;
+  if (runtime.context?.hasUI) runtime.context.ui.notify(rendered, "error");
+  else console.error(rendered);
+}
+
+function scheduleWorkerRestart(): void {
+  if (!runtime.context || runtime.workerRetryTimer) return;
+  const index = Math.min(runtime.workerRetryAttempt, WORKER_RETRY_DELAYS_MS.length - 1);
+  const delay = WORKER_RETRY_DELAYS_MS[index];
+  runtime.workerRetryAttempt += 1;
+  runtime.workerRetryTimer = setTimeout(() => {
+    runtime.workerRetryTimer = undefined;
+    if (!runtime.context) return;
+    ensureWorker();
+    updateCapability();
+  }, delay);
+  runtime.workerRetryTimer.unref();
+}
+
+function workerEntryUrl(): URL {
+  const compiled = new URL("../dist/lib/knowledge/review-worker.js", import.meta.url);
+  if (existsSync(fileURLToPath(compiled))) return compiled;
+  return new URL("../lib/knowledge/review-worker.ts", import.meta.url);
+}
+
 async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review_request" }>): Promise<void> {
   const ctx = runtime.context;
   if (!ctx?.model || !ctx.modelRegistry.hasConfiguredAuth(ctx.model)) {
@@ -98,29 +137,41 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
 }
 
 function handleWorkerMessage(message: KnowledgeWorkerOutput): void {
+  if (message.type === "ready") {
+    runtime.workerRetryAttempt = 0;
+    runtime.lastWorkerIssue = undefined;
+    return;
+  }
   if (message.type === "review_request") { void runReview(message); return; }
   if (message.type === "review_cancel" && runtime.activeReview?.requestId === message.requestId) {
     runtime.activeReview.controller.abort();
+    return;
   }
+  if (message.type === "review_failed") reportWorkerIssue(message.error);
 }
 
-function ensureWorker(): Worker {
+function ensureWorker(): Worker | undefined {
   if (runtime.worker) return runtime.worker;
-  const worker = new Worker(new URL("../lib/knowledge/review-worker.ts", import.meta.url));
+  if (runtime.workerRetryTimer) return undefined;
+  const worker = new Worker(workerEntryUrl());
   worker.unref();
   runtime.worker = worker;
   worker.on("message", (message: KnowledgeWorkerOutput) => handleWorkerMessage(message));
-  worker.on("error", () => {
+  worker.on("error", (error) => {
+    reportWorkerIssue(error);
     cancelActiveReview();
     if (runtime.worker === worker) {
       runtime.worker = undefined;
       runtime.modelAvailable = undefined;
+      scheduleWorkerRestart();
     }
   });
-  worker.on("exit", () => {
+  worker.on("exit", (code) => {
     if (runtime.worker === worker) {
       runtime.worker = undefined;
       runtime.modelAvailable = undefined;
+      if (code !== 0) reportWorkerIssue(`worker exited with code ${code}`);
+      scheduleWorkerRestart();
     }
   });
   runtime.capabilityTimer ??= setInterval(updateCapability, KNOWLEDGE_RUNTIME_DEFAULTS.review.capabilityPollMs);

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

@@ -258,3 +258,5 @@ parentPort.on("message", (message: KnowledgeWorkerInput) => {
   stepDown("worker-stopped");
   process.exit(0);
 });
+
+send({ type: "ready" });

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

@@ -7,6 +7,7 @@ export type KnowledgeWorkerInput =
   | { type: "stop" };
 
 export type KnowledgeWorkerOutput =
+  | { type: "ready" }
   | { type: "leadership"; state: "leader" | "standby" | "ineligible"; leaderToken?: string }
   | { type: "review_request"; leaderToken: string; requestId: string; task: KnowledgeReviewTask }
   | { type: "review_cancel"; requestId: string; reason: string }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadooppei/hwcode",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "A customizable terminal coding agent with local-model support and HWCode workflows.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bin/hwcode.js",
     ".env.example",
     ".pi/APPEND_SYSTEM.md",
+    ".pi/dist",
     ".pi/settings.json",
     ".pi/extensions",
     ".pi/lib",
@@ -25,10 +26,12 @@
   "scripts": {
     "start": "node --env-file-if-exists=.env ./bin/hwcode.js",
     "pi": "node --env-file-if-exists=.env ./bin/hwcode.js",
+    "build:knowledge-worker": "node scripts/build-knowledge-worker.mjs",
     "test": "node scripts/run-tests.mjs",
+    "test:package": "node scripts/test-packed-worker.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "test:workflows": "npm test",
-    "prepack": "npm run typecheck && npm test && node scripts/audit-package.mjs"
+    "prepack": "npm run typecheck && npm test && npm run build:knowledge-worker && npm run test:package && node scripts/audit-package.mjs"
   },
   "engines": {
     "node": ">=22.19.0"