@hadooppei/hwcode 1.0.10 → 1.0.11

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

@@ -7,10 +7,12 @@ Persist only knowledge that is likely to be useful in future sessions:
 - 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.
+Do not persist mutable inventory such as current cloud resources, names, availability, status, timestamps, or account snapshots. Preserve the discovery method or selection rule instead. If useful procedure is mixed with volatile facts, remove the volatile facts.
 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}]}
+Each summary must be one complete sentence of at most 160 characters. Keep each body under 3000 characters. Escape line breaks and quotes inside JSON strings. Set durability to "stable" only after removing facts likely to change or be cheaply rediscovered.
+Return: {"candidates":[{"key":"stable semantic key","title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body","evidence":["verified evidence"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|revise","explicitUserDirective":false,"durability":"stable"}]}
 Return {"candidates":[]} when nothing meets the threshold.`;
 export function buildKnowledgeExtractionPrompt(projectRoot, delta) {
     return `Project root: ${projectRoot}\n\n<conversation_delta>\n${delta}\n</conversation_delta>`;
@@ -22,10 +24,78 @@ export function parseCandidateEnvelope(text) {
     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);
+    let strictError;
+    try {
+        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);
+    }
+    catch (error) {
+        strictError = error;
+    }
+    const arrayKey = /["']candidates["']\s*:/gu.exec(unfenced);
+    const arrayStart = arrayKey ? unfenced.indexOf("[", arrayKey.index + arrayKey[0].length) : -1;
+    if (arrayStart >= 0) {
+        const candidates = [];
+        let inString = false;
+        let escaped = false;
+        for (let index = arrayStart + 1; index < unfenced.length && candidates.length < KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates; index++) {
+            const character = unfenced[index];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (character === "\\")
+                    escaped = true;
+                else if (character === '"')
+                    inString = false;
+                continue;
+            }
+            if (character === '"') {
+                inString = true;
+                continue;
+            }
+            if (character !== "{")
+                continue;
+            const objectEnd = balancedObjectEnd(unfenced, index);
+            if (objectEnd < 0)
+                break;
+            try {
+                candidates.push(JSON.parse(unfenced.slice(index, objectEnd + 1)));
+            }
+            catch { /* Salvage other complete candidates. */ }
+            index = objectEnd;
+        }
+        if (candidates.length > 0)
+            return candidates;
+    }
+    throw strictError;
+}
+function balancedObjectEnd(value, start) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < value.length; index++) {
+        const character = value[index];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (character === '"')
+                inString = false;
+            continue;
+        }
+        if (character === '"') {
+            inString = true;
+            continue;
+        }
+        if (character === "{")
+            depth++;
+        else if (character === "}" && --depth === 0)
+            return index;
+    }
+    return -1;
 }
 export function knowledgeDeltaDigest(delta) {
     return createHash("sha256").update(delta).digest("hex");

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

@@ -0,0 +1,20 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { userRuntimePaths } from "../runtime/paths.js";
+export function writeKnowledgeReviewStatus(status, home) {
+    const path = userRuntimePaths(home).knowledgeStatus;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(status, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    renameSync(temporary, path);
+    chmodSync(path, 0o600);
+}
+export function readKnowledgeReviewStatus(home) {
+    try {
+        const parsed = JSON.parse(readFileSync(userRuntimePaths(home).knowledgeStatus, "utf8"));
+        return parsed.version === 1 && parsed.protocolVersion === 3 ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -6,6 +6,8 @@ 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 { writeKnowledgeReviewStatus } from "./review-status.js";
+import { sanitizeKnowledgeText } from "./sanitize.js";
 import { findNextReviewTask } from "./session-scanner.js";
 import { commitKnowledgeReview, ensureKnowledgeDirectories, loadCurrentManifest } from "./store.js";
 if (!parentPort)
@@ -21,6 +23,11 @@ let leaderToken = "";
 let standbySocket;
 let electionPending = false;
 let activeTask;
+let activeAttempt = 0;
+let activeStartedAt = 0;
+let activeDeadlineTimer;
+let reviewStatus;
+const reviewAttempts = new Map();
 function send(message) {
     parentPort.postMessage(message);
 }
@@ -29,12 +36,74 @@ function coordinatorPath() {
         ? `\\\\.\\pipe\\hwcode-knowledge-v3-${Buffer.from(home).toString("hex").slice(0, 16)}`
         : paths.knowledgeCoordinatorSocket;
 }
-function writeLeaderMetadata() {
+function writeLeaderMetadata(electedAt) {
     writeFileSync(paths.knowledgeLeader, `${JSON.stringify({
-        protocolVersion: 3, leaderToken, pid: process.pid, electedAt: new Date().toISOString(),
+        protocolVersion: 3, leaderToken, pid: process.pid, electedAt,
     }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
     chmodSync(paths.knowledgeLeader, 0o600);
 }
+function publishReviewStatus() {
+    if (!reviewStatus)
+        return;
+    reviewStatus.updatedAt = new Date().toISOString();
+    try {
+        writeKnowledgeReviewStatus(reviewStatus, home);
+    }
+    catch (error) {
+        send({ type: "review_failed", error: `Unable to write knowledge status: ${error instanceof Error ? error.message : String(error)}` });
+    }
+}
+function boundedError(error) {
+    return sanitizeKnowledgeText(error instanceof Error ? error.message : String(error)).slice(0, 1_000);
+}
+function beginReview(task) {
+    activeAttempt = (reviewAttempts.get(task.reviewKey) ?? 0) + 1;
+    reviewAttempts.set(task.reviewKey, activeAttempt);
+    activeStartedAt = Date.now();
+    clearTimeout(activeDeadlineTimer);
+    activeDeadlineTimer = setTimeout(() => {
+        if (activeTask?.requestId !== task.requestId)
+            return;
+        const error = "knowledge-review-result-timeout";
+        finishReview(task, "failed", { error });
+        activeTask = undefined;
+        send({ type: "review_cancel", requestId: task.requestId, reason: error });
+        send({ type: "review_failed", requestId: task.requestId, error });
+    }, KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs + 5_000);
+    activeDeadlineTimer.unref();
+    if (reviewStatus) {
+        reviewStatus.activeReview = {
+            reviewKey: task.reviewKey,
+            sessionKey: task.sessionKey,
+            sessionFileHash: task.sessionFileHash,
+            projectKey: task.projectKey,
+            attempt: activeAttempt,
+            startedAt: new Date(activeStartedAt).toISOString(),
+        };
+        publishReviewStatus();
+    }
+}
+function finishReview(task, outcome, detail) {
+    clearTimeout(activeDeadlineTimer);
+    activeDeadlineTimer = undefined;
+    if (!reviewStatus)
+        return;
+    reviewStatus.activeReview = undefined;
+    reviewStatus.lastReview = {
+        reviewKey: task.reviewKey,
+        sessionKey: task.sessionKey,
+        attempt: activeAttempt,
+        outcome,
+        completedAt: new Date().toISOString(),
+        durationMs: Math.max(0, Date.now() - activeStartedAt),
+        generationId: detail.generationId,
+        result: detail.result,
+        error: detail.error === undefined ? undefined : boundedError(detail.error),
+    };
+    if (outcome === "saved")
+        reviewAttempts.delete(task.reviewKey);
+    publishReviewStatus();
+}
 function removeLeaderMetadata(token) {
     try {
         const current = JSON.parse(readFileSync(paths.knowledgeLeader, "utf8"));
@@ -63,7 +132,17 @@ function scheduleElection(delay = Math.floor(Math.random() * 500)) {
 function stepDown(reason) {
     if (activeTask)
         send({ type: "review_cancel", requestId: activeTask.requestId, reason });
+    if (reviewStatus) {
+        reviewStatus.state = "stepped-down";
+        reviewStatus.stepDownReason = reason;
+        reviewStatus.activeReview = undefined;
+        publishReviewStatus();
+    }
     activeTask = undefined;
+    clearTimeout(activeDeadlineTimer);
+    activeDeadlineTimer = undefined;
+    activeAttempt = 0;
+    activeStartedAt = 0;
     const token = leaderToken;
     leaderToken = "";
     for (const socket of standbySockets)
@@ -85,6 +164,7 @@ function stepDown(reason) {
     }
     if (token)
         removeLeaderMetadata(token);
+    reviewStatus = undefined;
 }
 function becomeStandby(socket) {
     standbySocket = socket;
@@ -162,6 +242,7 @@ function connectToLeader(probe = 0) {
 function becomeLeader(server) {
     leaderServer = server;
     leaderToken = randomUUID();
+    const electedAt = new Date().toISOString();
     server.unref();
     server.on("connection", (socket) => {
         standbySockets.add(socket);
@@ -176,7 +257,11 @@ function becomeLeader(server) {
         stepDown("coordinator-server-failed");
         scheduleElection();
     });
-    writeLeaderMetadata();
+    writeLeaderMetadata(electedAt);
+    reviewStatus = {
+        version: 1, protocolVersion: 3, state: "leader", pid: process.pid, leaderToken, electedAt, updatedAt: electedAt,
+    };
+    publishReviewStatus();
     send({ type: "leadership", state: "leader", leaderToken });
     void scanForReview();
 }
@@ -204,15 +289,22 @@ function attemptElection() {
 async function scanForReview() {
     if (!leaderServer || !leaderToken || activeTask || !sessionsRoot || !eligible)
         return;
+    if (reviewStatus) {
+        reviewStatus.lastScanAt = new Date().toISOString();
+        reviewStatus.lastScanError = undefined;
+        publishReviewStatus();
+    }
     try {
         const manifest = loadCurrentManifest(home);
         const task = findNextReviewTask(sessionsRoot, manifest.reviews);
         if (!task)
             return;
         activeTask = task;
+        beginReview(task);
         if (!task.delta) {
             const result = commitKnowledgeReview([], task, leaderToken, home);
             const generationId = loadCurrentManifest(home).generationId;
+            finishReview(task, "saved", { generationId, result });
             send({ type: "review_saved", requestId: task.requestId, generationId, result });
             if (generationId) {
                 send({ type: "generation_changed", generationId });
@@ -225,8 +317,14 @@ async function scanForReview() {
         send({ type: "review_request", leaderToken, requestId: task.requestId, task });
     }
     catch (error) {
+        if (activeTask)
+            finishReview(activeTask, "failed", { error });
+        else if (reviewStatus) {
+            reviewStatus.lastScanError = { at: new Date().toISOString(), error: boundedError(error) };
+            publishReviewStatus();
+        }
         activeTask = undefined;
-        send({ type: "review_failed", error: error instanceof Error ? error.message : String(error) });
+        send({ type: "review_failed", error: boundedError(error) });
     }
 }
 function handleReviewResult(message) {
@@ -239,6 +337,7 @@ function handleReviewResult(message) {
             throw new Error(message.error || "Knowledge review returned no content");
         const result = commitKnowledgeReview(parseCandidateEnvelope(message.raw), task, leaderToken, home);
         const generationId = loadCurrentManifest(home).generationId;
+        finishReview(task, "saved", { generationId, result });
         send({ type: "review_saved", requestId: task.requestId, generationId, result });
         if (generationId) {
             send({ type: "generation_changed", generationId });
@@ -247,7 +346,8 @@ function handleReviewResult(message) {
         committed = true;
     }
     catch (error) {
-        send({ type: "review_failed", requestId: task.requestId, error: error instanceof Error ? error.message : String(error) });
+        finishReview(task, "failed", { error });
+        send({ type: "review_failed", requestId: task.requestId, error: boundedError(error) });
     }
     finally {
         activeTask = undefined;

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

@@ -22,3 +22,23 @@ export function compactKnowledgeText(value, maxChars) {
         .trim()
         .slice(0, maxChars);
 }
+export function compactKnowledgeSummary(value, maxChars) {
+    const normalized = sanitizeKnowledgeText(value).replace(/\s+/gu, " ").trim();
+    if (normalized.length <= maxChars || maxChars <= 0)
+        return normalized.slice(0, Math.max(0, maxChars));
+    if (maxChars === 1)
+        return "…";
+    const limit = maxChars - 1;
+    const prefix = normalized.slice(0, limit);
+    const minimumBoundary = Math.floor(limit * 0.6);
+    const sentenceEnd = Math.max(prefix.lastIndexOf("。"), prefix.lastIndexOf("！"), prefix.lastIndexOf("？"), prefix.lastIndexOf("."), prefix.lastIndexOf("!"), prefix.lastIndexOf("?"));
+    if (sentenceEnd >= minimumBoundary)
+        return prefix.slice(0, sentenceEnd + 1).trimEnd();
+    const next = normalized.charAt(limit);
+    if (/[A-Za-z0-9]/u.test(prefix.at(-1) ?? "") && /[A-Za-z0-9]/u.test(next)) {
+        const wordBoundary = Math.max(prefix.lastIndexOf(" "), prefix.lastIndexOf("-"), prefix.lastIndexOf("/"));
+        if (wordBoundary >= minimumBoundary)
+            return `${prefix.slice(0, wordBoundary).trimEnd()}…`;
+    }
+    return `${prefix.trimEnd()}…`;
+}

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

@@ -4,7 +4,7 @@ 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";
+import { compactKnowledgeSummary, 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;
@@ -117,6 +117,8 @@ function normalizeCandidate(value, projectKey) {
     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.durability !== "stable")
+        return undefined;
     if (raw.confidence < KNOWLEDGE_RUNTIME_DEFAULTS.review.minimumConfidence)
         return undefined;
     const explicitUserDirective = raw.explicitUserDirective === true;
@@ -130,12 +132,12 @@ function normalizeCandidate(value, projectKey) {
         && (explicitUserDirective || raw.confidence >= 0.9);
     return {
         key: compactKnowledgeText(raw.key, 160), title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
-        summary: compactKnowledgeText(raw.summary, STORAGE.maxSummaryChars),
+        summary: compactKnowledgeSummary(raw.summary, STORAGE.maxSummaryChars),
         keywords: asStringArray(raw.keywords, STORAGE.maxKeywordCount).map((keyword) => keyword.toLowerCase()),
         scope, body, evidence, confidence: Math.min(1, raw.confidence),
         storageHint: requestedTrack === "rule" && ruleEligible ? "rule" : "topic",
         action: raw.action === "revise" ? "revise" : raw.action === "reinforce" ? "reinforce" : "add",
-        explicitUserDirective,
+        explicitUserDirective, durability: "stable",
     };
 }
 function renderKnowledgeFile(candidate) {

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

@@ -30,9 +30,9 @@ export const KNOWLEDGE_RUNTIME_DEFAULTS = Object.freeze({
         intervalMs: 60_000,
         idleMs: 60_000,
         capabilityPollMs: 5_000,
-        modelTimeoutMs: 120_000,
-        maxDeltaChars: 30_000,
-        maxCandidates: 8,
+        modelTimeoutMs: 180_000,
+        maxDeltaChars: 20_000,
+        maxCandidates: 5,
         minimumConfidence: 0.72,
     }),
     storage: Object.freeze({

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

@@ -40,6 +40,7 @@ export function userRuntimePaths(home = homedir()) {
         // 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"),
+        knowledgeStatus: join(knowledge, "runtime", "status.json"),
         knowledgeCommitLock: join(knowledge, "runtime", "commit.lock"),
         knowledgeElectionLock: join(knowledge, "runtime", "election.lock"),
     };

package/.pi/extensions/knowledge.ts

@@ -94,21 +94,15 @@ function workerEntryUrl(): URL {
 }
 
 async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review_request" }>): Promise<void> {
-  const ctx = runtime.context;
-  if (!ctx?.model || !ctx.modelRegistry.hasConfiguredAuth(ctx.model)) {
-    post({ type: "review_result", leaderToken: message.leaderToken, requestId: message.requestId, error: "no-configured-model" });
-    updateCapability();
-    return;
-  }
-  if (!ctx.isIdle() || ctx.hasPendingMessages()) {
-    post({ type: "review_result", leaderToken: message.leaderToken, requestId: message.requestId, error: "model-executor-is-busy" });
-    return;
-  }
-  const controller = new AbortController();
-  runtime.activeReview = { requestId: message.requestId, leaderToken: message.leaderToken, controller };
-  const timeout = setTimeout(() => controller.abort(), KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs);
-  timeout.unref();
+  let timeout: NodeJS.Timeout | undefined;
   try {
+    const ctx = runtime.context;
+    if (!ctx?.model || !ctx.modelRegistry.hasConfiguredAuth(ctx.model)) throw new Error("no-configured-model");
+    if (!ctx.isIdle() || ctx.hasPendingMessages()) throw new Error("model-executor-is-busy");
+    const controller = new AbortController();
+    runtime.activeReview = { requestId: message.requestId, leaderToken: message.leaderToken, controller };
+    timeout = setTimeout(() => controller.abort(), KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs);
+    timeout.unref();
     const response = await ctx.modelRegistry.complete(
       ctx.model,
       {
@@ -130,6 +124,7 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
       type: "review_result", leaderToken: message.leaderToken, requestId: message.requestId,
       error: error instanceof Error ? error.message : String(error),
     });
+    try { updateCapability(); } catch { /* The worker lease will recover even if the extension context changed. */ }
   } finally {
     clearTimeout(timeout);
     if (runtime.activeReview?.requestId === message.requestId) runtime.activeReview = undefined;

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

@@ -9,10 +9,12 @@ Persist only knowledge that is likely to be useful in future sessions:
 - 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.
+Do not persist mutable inventory such as current cloud resources, names, availability, status, timestamps, or account snapshots. Preserve the discovery method or selection rule instead. If useful procedure is mixed with volatile facts, remove the volatile facts.
 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}]}
+Each summary must be one complete sentence of at most 160 characters. Keep each body under 3000 characters. Escape line breaks and quotes inside JSON strings. Set durability to "stable" only after removing facts likely to change or be cheaply rediscovered.
+Return: {"candidates":[{"key":"stable semantic key","title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body","evidence":["verified evidence"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|revise","explicitUserDirective":false,"durability":"stable"}]}
 Return {"candidates":[]} when nothing meets the threshold.`;
 
 export function buildKnowledgeExtractionPrompt(projectRoot: string, delta: string): string {
@@ -25,9 +27,58 @@ export function parseCandidateEnvelope(text: string): unknown[] {
   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);
+  let strictError: unknown;
+  try {
+    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);
+  } catch (error) {
+    strictError = error;
+  }
+
+  const arrayKey = /["']candidates["']\s*:/gu.exec(unfenced);
+  const arrayStart = arrayKey ? unfenced.indexOf("[", arrayKey.index + arrayKey[0].length) : -1;
+  if (arrayStart >= 0) {
+    const candidates: unknown[] = [];
+    let inString = false;
+    let escaped = false;
+    for (let index = arrayStart + 1; index < unfenced.length && candidates.length < KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates; index++) {
+      const character = unfenced[index];
+      if (inString) {
+        if (escaped) escaped = false;
+        else if (character === "\\") escaped = true;
+        else if (character === '"') inString = false;
+        continue;
+      }
+      if (character === '"') { inString = true; continue; }
+      if (character !== "{") continue;
+      const objectEnd = balancedObjectEnd(unfenced, index);
+      if (objectEnd < 0) break;
+      try { candidates.push(JSON.parse(unfenced.slice(index, objectEnd + 1))); } catch { /* Salvage other complete candidates. */ }
+      index = objectEnd;
+    }
+    if (candidates.length > 0) return candidates;
+  }
+  throw strictError;
+}
+
+function balancedObjectEnd(value: string, start: number): number {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = start; index < value.length; index++) {
+    const character = value[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"') { inString = true; continue; }
+    if (character === "{") depth++;
+    else if (character === "}" && --depth === 0) return index;
+  }
+  return -1;
 }
 
 export function knowledgeDeltaDigest(delta: string): string {

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

@@ -0,0 +1,55 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { userRuntimePaths } from "../runtime/paths.ts";
+import type { PersistKnowledgeResult } from "./types.ts";
+
+export interface KnowledgeReviewStatus {
+  version: 1;
+  protocolVersion: 3;
+  state: "leader" | "stepped-down";
+  pid: number;
+  leaderToken: string;
+  electedAt: string;
+  updatedAt: string;
+  stepDownReason?: string;
+  lastScanAt?: string;
+  lastScanError?: { at: string; error: string };
+  activeReview?: {
+    reviewKey: string;
+    sessionKey: string;
+    sessionFileHash: string;
+    projectKey: string;
+    attempt: number;
+    startedAt: string;
+  };
+  lastReview?: {
+    reviewKey: string;
+    sessionKey: string;
+    attempt: number;
+    outcome: "saved" | "failed";
+    completedAt: string;
+    durationMs: number;
+    generationId?: string;
+    result?: PersistKnowledgeResult;
+    error?: string;
+  };
+}
+
+export function writeKnowledgeReviewStatus(status: KnowledgeReviewStatus, home: string): void {
+  const path = userRuntimePaths(home).knowledgeStatus;
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(status, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  renameSync(temporary, path);
+  chmodSync(path, 0o600);
+}
+
+export function readKnowledgeReviewStatus(home: string): KnowledgeReviewStatus | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(userRuntimePaths(home).knowledgeStatus, "utf8")) as KnowledgeReviewStatus;
+    return parsed.version === 1 && parsed.protocolVersion === 3 ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}

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

@@ -7,9 +7,11 @@ 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 { type KnowledgeReviewStatus, writeKnowledgeReviewStatus } from "./review-status.ts";
+import { sanitizeKnowledgeText } from "./sanitize.ts";
 import { findNextReviewTask } from "./session-scanner.ts";
 import { commitKnowledgeReview, ensureKnowledgeDirectories, loadCurrentManifest } from "./store.ts";
-import type { KnowledgeReviewTask } from "./types.ts";
+import type { KnowledgeReviewTask, PersistKnowledgeResult } from "./types.ts";
 import type { CoordinatorBroadcast, KnowledgeWorkerInput, KnowledgeWorkerOutput } from "./worker-protocol.ts";
 
 if (!parentPort) throw new Error("Knowledge review worker requires a parent port");
@@ -25,6 +27,11 @@ let leaderToken = "";
 let standbySocket: Socket | undefined;
 let electionPending = false;
 let activeTask: KnowledgeReviewTask | undefined;
+let activeAttempt = 0;
+let activeStartedAt = 0;
+let activeDeadlineTimer: NodeJS.Timeout | undefined;
+let reviewStatus: KnowledgeReviewStatus | undefined;
+const reviewAttempts = new Map<string, number>();
 
 function send(message: KnowledgeWorkerOutput): void {
   parentPort!.postMessage(message);
@@ -36,13 +43,76 @@ function coordinatorPath(): string {
     : paths.knowledgeCoordinatorSocket;
 }
 
-function writeLeaderMetadata(): void {
+function writeLeaderMetadata(electedAt: string): void {
   writeFileSync(paths.knowledgeLeader, `${JSON.stringify({
-    protocolVersion: 3, leaderToken, pid: process.pid, electedAt: new Date().toISOString(),
+    protocolVersion: 3, leaderToken, pid: process.pid, electedAt,
   }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
   chmodSync(paths.knowledgeLeader, 0o600);
 }
 
+function publishReviewStatus(): void {
+  if (!reviewStatus) return;
+  reviewStatus.updatedAt = new Date().toISOString();
+  try { writeKnowledgeReviewStatus(reviewStatus, home); } catch (error) {
+    send({ type: "review_failed", error: `Unable to write knowledge status: ${error instanceof Error ? error.message : String(error)}` });
+  }
+}
+
+function boundedError(error: unknown): string {
+  return sanitizeKnowledgeText(error instanceof Error ? error.message : String(error)).slice(0, 1_000);
+}
+
+function beginReview(task: KnowledgeReviewTask): void {
+  activeAttempt = (reviewAttempts.get(task.reviewKey) ?? 0) + 1;
+  reviewAttempts.set(task.reviewKey, activeAttempt);
+  activeStartedAt = Date.now();
+  clearTimeout(activeDeadlineTimer);
+  activeDeadlineTimer = setTimeout(() => {
+    if (activeTask?.requestId !== task.requestId) return;
+    const error = "knowledge-review-result-timeout";
+    finishReview(task, "failed", { error });
+    activeTask = undefined;
+    send({ type: "review_cancel", requestId: task.requestId, reason: error });
+    send({ type: "review_failed", requestId: task.requestId, error });
+  }, KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs + 5_000);
+  activeDeadlineTimer.unref();
+  if (reviewStatus) {
+    reviewStatus.activeReview = {
+      reviewKey: task.reviewKey,
+      sessionKey: task.sessionKey,
+      sessionFileHash: task.sessionFileHash,
+      projectKey: task.projectKey,
+      attempt: activeAttempt,
+      startedAt: new Date(activeStartedAt).toISOString(),
+    };
+    publishReviewStatus();
+  }
+}
+
+function finishReview(
+  task: KnowledgeReviewTask,
+  outcome: "saved" | "failed",
+  detail: { generationId?: string; result?: PersistKnowledgeResult; error?: unknown },
+): void {
+  clearTimeout(activeDeadlineTimer);
+  activeDeadlineTimer = undefined;
+  if (!reviewStatus) return;
+  reviewStatus.activeReview = undefined;
+  reviewStatus.lastReview = {
+    reviewKey: task.reviewKey,
+    sessionKey: task.sessionKey,
+    attempt: activeAttempt,
+    outcome,
+    completedAt: new Date().toISOString(),
+    durationMs: Math.max(0, Date.now() - activeStartedAt),
+    generationId: detail.generationId,
+    result: detail.result,
+    error: detail.error === undefined ? undefined : boundedError(detail.error),
+  };
+  if (outcome === "saved") reviewAttempts.delete(task.reviewKey);
+  publishReviewStatus();
+}
+
 function removeLeaderMetadata(token: string): void {
   try {
     const current = JSON.parse(readFileSync(paths.knowledgeLeader, "utf8")) as { leaderToken?: string };
@@ -69,7 +139,17 @@ function scheduleElection(delay = Math.floor(Math.random() * 500)): void {
 
 function stepDown(reason: string): void {
   if (activeTask) send({ type: "review_cancel", requestId: activeTask.requestId, reason });
+  if (reviewStatus) {
+    reviewStatus.state = "stepped-down";
+    reviewStatus.stepDownReason = reason;
+    reviewStatus.activeReview = undefined;
+    publishReviewStatus();
+  }
   activeTask = undefined;
+  clearTimeout(activeDeadlineTimer);
+  activeDeadlineTimer = undefined;
+  activeAttempt = 0;
+  activeStartedAt = 0;
   const token = leaderToken;
   leaderToken = "";
   for (const socket of standbySockets) socket.destroy();
@@ -83,6 +163,7 @@ function stepDown(reason: string): void {
     }
   }
   if (token) removeLeaderMetadata(token);
+  reviewStatus = undefined;
 }
 
 function becomeStandby(socket: Socket): void {
@@ -147,6 +228,7 @@ function connectToLeader(probe = 0): void {
 function becomeLeader(server: Server): void {
   leaderServer = server;
   leaderToken = randomUUID();
+  const electedAt = new Date().toISOString();
   server.unref();
   server.on("connection", (socket) => {
     standbySockets.add(socket);
@@ -160,7 +242,11 @@ function becomeLeader(server: Server): void {
     stepDown("coordinator-server-failed");
     scheduleElection();
   });
-  writeLeaderMetadata();
+  writeLeaderMetadata(electedAt);
+  reviewStatus = {
+    version: 1, protocolVersion: 3, state: "leader", pid: process.pid, leaderToken, electedAt, updatedAt: electedAt,
+  };
+  publishReviewStatus();
   send({ type: "leadership", state: "leader", leaderToken });
   void scanForReview();
 }
@@ -186,14 +272,21 @@ function attemptElection(): void {
 
 async function scanForReview(): Promise<void> {
   if (!leaderServer || !leaderToken || activeTask || !sessionsRoot || !eligible) return;
+  if (reviewStatus) {
+    reviewStatus.lastScanAt = new Date().toISOString();
+    reviewStatus.lastScanError = undefined;
+    publishReviewStatus();
+  }
   try {
     const manifest = loadCurrentManifest(home);
     const task = findNextReviewTask(sessionsRoot, manifest.reviews);
     if (!task) return;
     activeTask = task;
+    beginReview(task);
     if (!task.delta) {
       const result = commitKnowledgeReview([], task, leaderToken, home);
       const generationId = loadCurrentManifest(home).generationId;
+      finishReview(task, "saved", { generationId, result });
       send({ type: "review_saved", requestId: task.requestId, generationId, result });
       if (generationId) {
         send({ type: "generation_changed", generationId });
@@ -205,8 +298,13 @@ async function scanForReview(): Promise<void> {
     }
     send({ type: "review_request", leaderToken, requestId: task.requestId, task });
   } catch (error) {
+    if (activeTask) finishReview(activeTask, "failed", { error });
+    else if (reviewStatus) {
+      reviewStatus.lastScanError = { at: new Date().toISOString(), error: boundedError(error) };
+      publishReviewStatus();
+    }
     activeTask = undefined;
-    send({ type: "review_failed", error: error instanceof Error ? error.message : String(error) });
+    send({ type: "review_failed", error: boundedError(error) });
   }
 }
 
@@ -218,6 +316,7 @@ function handleReviewResult(message: Extract<KnowledgeWorkerInput, { type: "revi
     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;
+    finishReview(task, "saved", { generationId, result });
     send({ type: "review_saved", requestId: task.requestId, generationId, result });
     if (generationId) {
       send({ type: "generation_changed", generationId });
@@ -225,7 +324,8 @@ function handleReviewResult(message: Extract<KnowledgeWorkerInput, { type: "revi
     }
     committed = true;
   } catch (error) {
-    send({ type: "review_failed", requestId: task.requestId, error: error instanceof Error ? error.message : String(error) });
+    finishReview(task, "failed", { error });
+    send({ type: "review_failed", requestId: task.requestId, error: boundedError(error) });
   } finally {
     activeTask = undefined;
     if (committed) queueMicrotask(() => void scanForReview());

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

@@ -24,3 +24,23 @@ export function compactKnowledgeText(value: string, maxChars: number): string {
     .trim()
     .slice(0, maxChars);
 }
+
+export function compactKnowledgeSummary(value: string, maxChars: number): string {
+  const normalized = sanitizeKnowledgeText(value).replace(/\s+/gu, " ").trim();
+  if (normalized.length <= maxChars || maxChars <= 0) return normalized.slice(0, Math.max(0, maxChars));
+  if (maxChars === 1) return "…";
+  const limit = maxChars - 1;
+  const prefix = normalized.slice(0, limit);
+  const minimumBoundary = Math.floor(limit * 0.6);
+  const sentenceEnd = Math.max(
+    prefix.lastIndexOf("。"), prefix.lastIndexOf("！"), prefix.lastIndexOf("？"),
+    prefix.lastIndexOf("."), prefix.lastIndexOf("!"), prefix.lastIndexOf("?"),
+  );
+  if (sentenceEnd >= minimumBoundary) return prefix.slice(0, sentenceEnd + 1).trimEnd();
+  const next = normalized.charAt(limit);
+  if (/[A-Za-z0-9]/u.test(prefix.at(-1) ?? "") && /[A-Za-z0-9]/u.test(next)) {
+    const wordBoundary = Math.max(prefix.lastIndexOf(" "), prefix.lastIndexOf("-"), prefix.lastIndexOf("/"));
+    if (wordBoundary >= minimumBoundary) return `${prefix.slice(0, wordBoundary).trimEnd()}…`;
+  }
+  return `${prefix.trimEnd()}…`;
+}

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

@@ -8,7 +8,7 @@ import { basename, dirname, join, resolve, sep } from "node:path";
 
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
 import { userRuntimePaths } from "../runtime/paths.ts";
-import { compactKnowledgeText, sanitizeKnowledgeText } from "./sanitize.ts";
+import { compactKnowledgeSummary, compactKnowledgeText, sanitizeKnowledgeText } from "./sanitize.ts";
 import type {
   KnowledgeCandidate, KnowledgeCatalog, KnowledgeCatalogEntry, KnowledgeManifest, KnowledgeReviewCursor,
   KnowledgeReviewTask, KnowledgeScope, KnowledgeSnapshot, KnowledgeTrack, PersistKnowledgeResult,
@@ -132,6 +132,7 @@ function normalizeCandidate(value: unknown, projectKey: string): KnowledgeCandid
   const raw = value as Record<string, unknown>;
   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.durability !== "stable") return undefined;
   if (raw.confidence < KNOWLEDGE_RUNTIME_DEFAULTS.review.minimumConfidence) return undefined;
   const explicitUserDirective = raw.explicitUserDirective === true;
   const scope: KnowledgeScope = raw.scope === "global" && explicitUserDirective ? "global" : `project:${projectKey}`;
@@ -143,12 +144,12 @@ function normalizeCandidate(value: unknown, projectKey: string): KnowledgeCandid
     && (explicitUserDirective || raw.confidence >= 0.9);
   return {
     key: compactKnowledgeText(raw.key, 160), title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
-    summary: compactKnowledgeText(raw.summary, STORAGE.maxSummaryChars),
+    summary: compactKnowledgeSummary(raw.summary, STORAGE.maxSummaryChars),
     keywords: asStringArray(raw.keywords, STORAGE.maxKeywordCount).map((keyword) => keyword.toLowerCase()),
     scope, body, evidence, confidence: Math.min(1, raw.confidence),
     storageHint: requestedTrack === "rule" && ruleEligible ? "rule" : "topic",
     action: raw.action === "revise" ? "revise" : raw.action === "reinforce" ? "reinforce" : "add",
-    explicitUserDirective,
+    explicitUserDirective, durability: "stable",
   };
 }
 

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

@@ -1,6 +1,7 @@
 export type KnowledgeTrack = "rule" | "topic";
 export type KnowledgeScope = "global" | `project:${string}`;
 export type KnowledgeAction = "add" | "reinforce" | "revise";
+export type KnowledgeDurability = "stable";
 
 export interface KnowledgeCandidate {
   key: string;
@@ -14,6 +15,7 @@ export interface KnowledgeCandidate {
   storageHint: KnowledgeTrack;
   action: KnowledgeAction;
   explicitUserDirective: boolean;
+  durability: KnowledgeDurability;
 }
 
 export interface KnowledgeCatalogEntry {

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

@@ -31,9 +31,9 @@ export const KNOWLEDGE_RUNTIME_DEFAULTS = Object.freeze({
     intervalMs: 60_000,
     idleMs: 60_000,
     capabilityPollMs: 5_000,
-    modelTimeoutMs: 120_000,
-    maxDeltaChars: 30_000,
-    maxCandidates: 8,
+    modelTimeoutMs: 180_000,
+    maxDeltaChars: 20_000,
+    maxCandidates: 5,
     minimumConfidence: 0.72,
   }),
   storage: Object.freeze({

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

@@ -34,6 +34,7 @@ export interface UserRuntimePaths {
   knowledgeRuntime: string;
   knowledgeCoordinatorSocket: string;
   knowledgeLeader: string;
+  knowledgeStatus: string;
   knowledgeCommitLock: string;
   knowledgeElectionLock: string;
 }
@@ -68,6 +69,7 @@ export function userRuntimePaths(home = homedir()): UserRuntimePaths {
     // 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"),
+    knowledgeStatus: join(knowledge, "runtime", "status.json"),
     knowledgeCommitLock: join(knowledge, "runtime", "commit.lock"),
     knowledgeElectionLock: join(knowledge, "runtime", "election.lock"),
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadooppei/hwcode",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "A customizable terminal coding agent with local-model support and HWCode workflows.",
   "type": "module",
   "bin": {