@hadooppei/hwcode 1.0.12 → 1.0.13

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

@@ -104,6 +104,25 @@ function finishReview(task, outcome, detail) {
         reviewAttempts.delete(task.reviewKey);
     publishReviewStatus();
 }
+function deferReview(task, reason) {
+    clearTimeout(activeDeadlineTimer);
+    activeDeadlineTimer = undefined;
+    const attempts = reviewAttempts.get(task.reviewKey) ?? 1;
+    if (attempts <= 1)
+        reviewAttempts.delete(task.reviewKey);
+    else
+        reviewAttempts.set(task.reviewKey, attempts - 1);
+    if (!reviewStatus)
+        return;
+    reviewStatus.activeReview = undefined;
+    reviewStatus.lastDeferred = {
+        reviewKey: task.reviewKey,
+        sessionKey: task.sessionKey,
+        deferredAt: new Date().toISOString(),
+        reason: boundedError(reason),
+    };
+    publishReviewStatus();
+}
 function removeLeaderMetadata(token) {
     try {
         const current = JSON.parse(readFileSync(paths.knowledgeLeader, "utf8"));
@@ -355,6 +374,13 @@ function handleReviewResult(message) {
             queueMicrotask(() => void scanForReview());
     }
 }
+function handleReviewDeferred(message) {
+    const task = activeTask;
+    if (!task || message.requestId !== task.requestId || message.leaderToken !== leaderToken || !leaderServer)
+        return;
+    deferReview(task, message.reason);
+    activeTask = undefined;
+}
 const scanTimer = setInterval(() => { void scanForReview(); }, KNOWLEDGE_RUNTIME_DEFAULTS.review.intervalMs);
 scanTimer.unref();
 parentPort.on("message", (message) => {
@@ -373,6 +399,10 @@ parentPort.on("message", (message) => {
             scheduleElection(0);
         return;
     }
+    if (message.type === "review_deferred") {
+        handleReviewDeferred(message);
+        return;
+    }
     if (message.type === "review_result") {
         handleReviewResult(message);
         return;

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

@@ -1,8 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFileSync, readdirSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { resolve, sep } from "node:path";
 import { buildContextEntries, parseSessionEntries, } from "@earendil-works/pi-coding-agent";
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.js";
+import { findLatestWorkflowRoot } from "../working-directory.js";
 import { knowledgeDeltaDigest } from "./extractor.js";
 import { sanitizeKnowledgeText } from "./sanitize.js";
 import { projectKnowledgeKey } from "./store.js";
@@ -98,15 +99,26 @@ function buildValidationContext(entries) {
         .slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxPriorContextChars);
 }
 function projectRootForSession(header, branch) {
+    const sessionRoot = resolve(header.cwd);
+    const workflowRootValue = findLatestWorkflowRoot(branch);
+    const workflowRoot = workflowRootValue ? resolve(workflowRootValue) : undefined;
+    let workingDirectory = sessionRoot;
     for (const entry of branch.slice().reverse()) {
         if (entry.type !== "custom" || entry.customType !== "hwcode-working-directory"
             || !entry.data || typeof entry.data !== "object")
             continue;
         const cwd = entry.data.cwd;
-        if (typeof cwd === "string" && cwd)
-            return resolve(cwd);
+        if (typeof cwd !== "string" || !cwd)
+            continue;
+        workingDirectory = resolve(cwd);
+        break;
+    }
+    if (workflowRoot && (workingDirectory === workflowRoot || workingDirectory.startsWith(`${workflowRoot}${sep}`))) {
+        return workflowRoot;
     }
-    return resolve(header.cwd);
+    if (workingDirectory === sessionRoot || workingDirectory.startsWith(`${sessionRoot}${sep}`))
+        return sessionRoot;
+    return workingDirectory;
 }
 export function discoverSessionFiles(root) {
     const files = [];

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

@@ -137,16 +137,22 @@ function semanticDuplicateIndex(candidate, catalog) {
     return bestIndex;
 }
 function unsupportedOperations(value) {
-    return [...value.matchAll(/\bOperation\s+([A-Za-z][A-Za-z0-9]+)\s+is not supported\b/gu)]
-        .map((match) => match[1].toLowerCase());
+    return [...value.matchAll(/\bOperation\s+([A-Za-z][A-Za-z0-9]+)\s+is not supported\b/gu)].map((match) => {
+        const suffix = value.slice(match.index + match[0].length, match.index + match[0].length + 500);
+        const service = /\bhcloud\s+([A-Za-z][A-Za-z0-9-]*)\s+--help\b/iu.exec(suffix)?.[1]?.toLowerCase();
+        return { operation: match[1].toLowerCase(), service };
+    });
 }
 function contradictsVerifiedFailures(body, validationText) {
     const normalizedBody = body.toLowerCase();
-    for (const operation of unsupportedOperations(validationText)) {
-        const index = normalizedBody.search(new RegExp(`\\b${operation}\\b`, "u"));
+    for (const unsupported of unsupportedOperations(validationText)) {
+        const operationExpression = unsupported.service
+            ? new RegExp(`\\b(?:hcloud\\s+)?${unsupported.service}\\b[^\\n]{0,120}\\b${unsupported.operation}\\b`, "u")
+            : new RegExp(`\\b${unsupported.operation}\\b`, "u");
+        const index = normalizedBody.search(operationExpression);
         if (index < 0)
             continue;
-        const context = normalizedBody.slice(Math.max(0, index - 80), index + operation.length + 80);
+        const context = normalizedBody.slice(Math.max(0, index - 80), index + 240);
         if (!/(?:not supported|unsupported|do not|don't|avoid|不支持|不要|避免)/u.test(context))
             return true;
     }
@@ -163,38 +169,58 @@ function asStringArray(value, maxItems) {
 }
 function normalizeCandidate(value, projectKey, validationText) {
     if (!value || typeof value !== "object")
-        return undefined;
+        return { reason: "invalid-schema" };
     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;
+        return { reason: "invalid-schema" };
     if (raw.durability !== "stable")
-        return undefined;
+        return { reason: "unstable" };
     if (raw.confidence < KNOWLEDGE_RUNTIME_DEFAULTS.review.minimumConfidence)
-        return undefined;
+        return { reason: "low-confidence" };
+    if (raw.targetId !== undefined && raw.targetId !== null
+        && (typeof raw.targetId !== "string" || !SAFE_ID_RE.test(raw.targetId)))
+        return { reason: "unknown-target" };
     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;
+        return { reason: "missing-body-or-evidence" };
     if (contradictsVerifiedFailures(body, validationText))
-        return undefined;
+        return { reason: "contradicts-verified-failure" };
     const requestedTrack = raw.storageHint === "rule" ? "rule" : "topic";
     const ruleEligible = body.length <= STORAGE.maxRuleChars && body.split("\n").length <= STORAGE.maxRuleFileLines
         && body.split(/\n\s*\n/gu).length === 1
         && (explicitUserDirective || raw.confidence >= 0.9);
     const targetId = typeof raw.targetId === "string" && SAFE_ID_RE.test(raw.targetId) ? raw.targetId : undefined;
-    return {
-        key: compactKnowledgeText(raw.key, 160), targetId,
-        title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
-        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, durability: "stable",
-    };
+    return { candidate: {
+            key: compactKnowledgeText(raw.key, 160), targetId,
+            title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
+            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, durability: "stable",
+        } };
+}
+function recordSkip(result, reason) {
+    result.skipped++;
+    result.skippedReasons ??= {};
+    result.skippedReasons[reason] = (result.skippedReasons[reason] ?? 0) + 1;
+}
+function writeRejectedPending(directory, reason, value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        serialized = String(value);
+    }
+    const candidate = sanitizeKnowledgeText(serialized).slice(0, 10_000);
+    const name = `${Date.now()}-rejected-${reason}-${randomUUID().slice(0, 8)}.json`;
+    atomicWrite(join(directory, "pending", name), `${JSON.stringify({ reason, candidate }, null, 2)}\n`);
 }
 function renderKnowledgeFile(candidate) {
     if (candidate.storageHint === "rule")
@@ -324,19 +350,23 @@ export function commitKnowledgeReview(values, task, leaderToken, home = homedir(
         copyCurrentContent(current, temporary, home);
         const catalog = structuredClone(current.catalog);
         const result = { saved: 0, updated: 0, pending: 0, skipped: 0 };
+        const rejected = [];
         for (const value of values.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates)) {
-            const candidate = normalizeCandidate(value, task.projectKey, `${task.context ?? ""}\n${task.delta}`);
-            if (!candidate) {
-                result.skipped++;
+            const normalized = normalizeCandidate(value, task.projectKey, `${task.context ?? ""}\n${task.delta}`);
+            if (!("candidate" in normalized)) {
+                recordSkip(result, normalized.reason);
+                rejected.push({ reason: normalized.reason, value });
                 continue;
             }
+            const candidate = normalized.candidate;
             const fingerprint = normalizedFingerprint(candidate);
             const hash = contentHash(candidate);
             const targetIndex = candidate.targetId
                 ? catalog.items.findIndex((item) => item.id === candidate.targetId && applicable(item, task.projectKey))
                 : -1;
             if (candidate.targetId && targetIndex < 0) {
-                result.skipped++;
+                recordSkip(result, "unknown-target");
+                rejected.push({ reason: "unknown-target", value });
                 continue;
             }
             let existingIndex = targetIndex >= 0
@@ -386,6 +416,11 @@ export function commitKnowledgeReview(values, task, leaderToken, home = homedir(
                 result.saved++;
             }
         }
+        if (result.skipped > 0 && result.saved === 0 && result.updated === 0 && result.pending === 0) {
+            for (const item of rejected)
+                writeRejectedPending(temporary, item.reason, item.value);
+            result.pending += rejected.length;
+        }
         catalog.updatedAt = new Date().toISOString();
         const manifest = {
             version: 3, generationId, createdAt: new Date().toISOString(), leaderToken, catalog,

package/.pi/dist/lib/runtime/session-state.js

@@ -0,0 +1,9 @@
+export function findLatestState(entries, codec) {
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry.type !== "custom" || entry.customType !== codec.customType)
+            continue;
+        return { found: true, value: codec.decode(entry.data) };
+    }
+    return { found: false };
+}

package/.pi/dist/lib/workflows/state.js

@@ -0,0 +1,159 @@
+import { findLatestState } from "../runtime/session-state.js";
+export const WORKFLOW_STATE_TYPE = "hwcode-workflow-state";
+export const WORKFLOW_EXTERNAL_AUDIT_TYPE = "hwcode-workflow-external-approval";
+function isCloudTemplateSource(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const data = value;
+    return typeof data.id === "string"
+        && typeof data.name === "string"
+        && typeof data.createdAt === "string"
+        && typeof data.updatedAt === "string";
+}
+function isCloudRunnerSummary(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const data = value;
+    return typeof data.id === "string"
+        && typeof data.name === "string"
+        && typeof data.vendor === "string"
+        && typeof data.region === "string"
+        && typeof data.host === "string"
+        && Number.isInteger(data.port)
+        && typeof data.user === "string"
+        && typeof data.remoteRoot === "string"
+        && typeof data.hostKeyFingerprint === "string"
+        && ["instance-role", "agency", "ssh-only"].includes(data.identityType);
+}
+function isTerraformRunState(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const data = value;
+    const summary = data.planSummary;
+    return typeof data.runId === "string"
+        && typeof data.runnerId === "string"
+        && ["synced", "validated", "planned", "applied", "failed"].includes(data.phase)
+        && typeof data.sourceDigest === "string"
+        && typeof data.remoteWorkspace === "string"
+        && typeof data.startedAt === "string"
+        && typeof data.updatedAt === "string"
+        && (data.planDigest === undefined || typeof data.planDigest === "string")
+        && (summary === undefined || (summary !== null && typeof summary === "object"
+            && Object.values(summary).every((entry) => Number.isInteger(entry))));
+}
+function isCloudDetails(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const data = value;
+    return typeof data.vendor === "string"
+        && typeof data.deployCurrentProject === "boolean"
+        && typeof data.request === "string"
+        && typeof data.allowNonDeleteChanges === "boolean"
+        && Array.isArray(data.failedApproaches)
+        && Array.isArray(data.successfulSteps)
+        && (data.resources === undefined || (Array.isArray(data.resources) && data.resources.every((resource) => {
+            if (!resource || typeof resource !== "object")
+                return false;
+            const entry = resource;
+            return typeof entry.id === "string" && typeof entry.type === "string" && typeof entry.region === "string"
+                && ["existing", "workflow-created"].includes(entry.ownership)
+                && ["active", "deleted"].includes(entry.status)
+                && typeof entry.updatedAt === "string";
+        })))
+        && typeof data.terminalFailure === "boolean"
+        && (data.artifactDirectory === undefined || typeof data.artifactDirectory === "string")
+        && (data.templateGuidance === undefined || typeof data.templateGuidance === "string")
+        && (data.terraformSourcePath === undefined || typeof data.terraformSourcePath === "string")
+        && (data.sourceTemplate === undefined || isCloudTemplateSource(data.sourceTemplate))
+        && (data.runner === undefined || isCloudRunnerSummary(data.runner))
+        && (data.runnerPreference === undefined || ["automatic", "deferred", "existing"].includes(data.runnerPreference))
+        && (data.terraformRun === undefined || isTerraformRunState(data.terraformRun));
+}
+export function decodeWorkflowState(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const data = value;
+    if (data.version === 2) {
+        if (!["active", "completed", "cancelled", "failed"].includes(data.status)
+            || !["vibe", "sdd", "cloud"].includes(data.mode)
+            || typeof data.root !== "string"
+            || typeof data.phase !== "string"
+            || typeof data.activatedAt !== "string"
+            || typeof data.updatedAt !== "string")
+            return undefined;
+        if (data.mode === "cloud" && !isCloudDetails(data.details))
+            return undefined;
+        if (data.mode === "sdd" && data.sdd !== undefined) {
+            const sdd = data.sdd;
+            if (!["discovery", "requirements", "design", "test-plan", "tasks", "tests", "implementation", "verification"].includes(sdd.phase)
+                || !Array.isArray(sdd.approvals))
+                return undefined;
+        }
+        return data;
+    }
+    return undefined;
+}
+export const WORKFLOW_STATE_CODEC = {
+    customType: WORKFLOW_STATE_TYPE,
+    decode: decodeWorkflowState,
+};
+export function restoreWorkflowState(entries) {
+    return findLatestState(entries, WORKFLOW_STATE_CODEC).value;
+}
+export function activeWorkflow(entries) {
+    const state = restoreWorkflowState(entries);
+    return state?.status === "active" ? state : undefined;
+}
+export function cloudDetails(state) {
+    return state.mode === "cloud" ? state.details : undefined;
+}
+export function createWorkflowState(mode, root, phase = "activated") {
+    const now = new Date().toISOString();
+    return {
+        version: 2,
+        status: "active",
+        mode,
+        root,
+        phase,
+        activatedAt: now,
+        updatedAt: now,
+        ...(mode === "sdd" ? { sdd: { phase: "discovery", approvals: [] } } : {}),
+    };
+}
+export function createCloudWorkflowState(root, vendor, deployCurrentProject, request, template, artifactDirectory) {
+    const now = new Date().toISOString();
+    return {
+        version: 2,
+        status: "active",
+        mode: "cloud",
+        root,
+        phase: "connected",
+        activatedAt: now,
+        updatedAt: now,
+        details: {
+            vendor,
+            deployCurrentProject,
+            request,
+            allowNonDeleteChanges: false,
+            failedApproaches: [],
+            successfulSteps: [],
+            resources: [],
+            terminalFailure: false,
+            ...(artifactDirectory ? { artifactDirectory } : {}),
+            ...(template ? {
+                templateGuidance: template.guidance,
+                sourceTemplate: template.source,
+            } : {}),
+        },
+    };
+}
+export function updateWorkflowState(state, changes) {
+    return { ...state, ...changes, version: 2, updatedAt: new Date().toISOString() };
+}
+export function workflowLabel(mode) {
+    if (mode === "vibe")
+        return "HWCode Vibe";
+    if (mode === "sdd")
+        return "HWCode SDD";
+    return "HWCode Cloud";
+}

package/.pi/dist/lib/working-directory.js

@@ -0,0 +1,170 @@
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import { activeWorkflow } from "./workflows/state.js";
+export const WORKING_DIRECTORY_STATE_TYPE = "hwcode-working-directory";
+const workingDirectories = new Map();
+function isWorkingDirectoryState(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const data = value;
+    return data.version === 1
+        && typeof data.cwd === "string"
+        && (data.previousCwd === undefined || typeof data.previousCwd === "string");
+}
+export function findPersistedWorkingDirectory(entries) {
+    for (const entry of [...entries].reverse()) {
+        if (entry.type !== "custom" || entry.customType !== WORKING_DIRECTORY_STATE_TYPE)
+            continue;
+        if (isWorkingDirectoryState(entry.data))
+            return entry.data;
+    }
+    return undefined;
+}
+export function canonicalizeDirectory(path) {
+    const canonical = realpathSync(path);
+    if (!statSync(canonical).isDirectory())
+        throw new Error(`Not a directory: ${path}`);
+    return canonical;
+}
+function initialState(source) {
+    const persisted = findPersistedWorkingDirectory(source.getEntries());
+    if (persisted)
+        return { ...persisted, cwd: canonicalizeDirectory(persisted.cwd) };
+    return { version: 1, cwd: canonicalizeDirectory(source.getCwd()) };
+}
+export function getWorkingDirectoryState(source) {
+    return workingDirectories.get(source.getSessionId()) ?? initialState(source);
+}
+export function getWorkingDirectory(source) {
+    return getWorkingDirectoryState(source).cwd;
+}
+export function setWorkingDirectoryState(source, state) {
+    workingDirectories.set(source.getSessionId(), state);
+}
+export function resetWorkingDirectoryState(source) {
+    const state = initialState(source);
+    setWorkingDirectoryState(source, state);
+    return state;
+}
+export function clearWorkingDirectoryState(source) {
+    workingDirectories.delete(source.getSessionId());
+}
+function expandHome(path, home) {
+    if (path === "~" || path === "$HOME" || path === "${HOME}")
+        return home;
+    if (path.startsWith("~/"))
+        return resolve(home, path.slice(2));
+    if (path.startsWith("$HOME/"))
+        return resolve(home, path.slice(6));
+    if (path.startsWith("${HOME}/"))
+        return resolve(home, path.slice(8));
+    return path;
+}
+export function resolveDirectoryArgument(base, argument, previousCwd, home = homedir()) {
+    if (argument === "-") {
+        if (!previousCwd)
+            throw new Error("No previous working directory is available.");
+        return canonicalizeDirectory(previousCwd);
+    }
+    const expanded = expandHome(argument || home, home);
+    return canonicalizeDirectory(isAbsolute(expanded) ? expanded : resolve(base, expanded));
+}
+export function resolveWorkingPath(base, path, home = homedir()) {
+    const expanded = expandHome(path, home);
+    return isAbsolute(expanded) ? expanded : resolve(base, expanded);
+}
+function readShellWord(command, start) {
+    let value = "";
+    let quote;
+    let index = start;
+    for (; index < command.length; index += 1) {
+        const character = command[index];
+        if (quote) {
+            if (character === quote) {
+                quote = undefined;
+                continue;
+            }
+            if (character === "\\" && quote === '"' && index + 1 < command.length) {
+                index += 1;
+                value += command[index];
+                continue;
+            }
+            value += character;
+            continue;
+        }
+        if (character === "'" || character === '"') {
+            quote = character;
+            continue;
+        }
+        if (character === "\\" && index + 1 < command.length) {
+            index += 1;
+            value += command[index];
+            continue;
+        }
+        if (/\s/u.test(character) || character === ";" || character === "&")
+            break;
+        if ("|<>`".includes(character) || character === "$" && command[index + 1] === "(")
+            return undefined;
+        value += character;
+    }
+    if (quote || value.length === 0)
+        return undefined;
+    return { value, end: index };
+}
+/** Parse a leading persistent `cd`, optionally followed by `&&` or `;`. */
+export function parseLeadingDirectoryChange(command) {
+    let index = 0;
+    while (/\s/u.test(command[index] ?? ""))
+        index += 1;
+    if (command.slice(index, index + 2) !== "cd")
+        return undefined;
+    const next = command[index + 2];
+    if (next && !/\s/u.test(next) && next !== ";" && command.slice(index + 2, index + 4) !== "&&") {
+        return undefined;
+    }
+    index += 2;
+    while (/\s/u.test(command[index] ?? ""))
+        index += 1;
+    if (command.slice(index, index + 2) === "--") {
+        index += 2;
+        while (/\s/u.test(command[index] ?? ""))
+            index += 1;
+    }
+    let argument = "";
+    if (index < command.length && command[index] !== ";" && command.slice(index, index + 2) !== "&&") {
+        const word = readShellWord(command, index);
+        if (!word)
+            return undefined;
+        argument = word.value;
+        index = word.end;
+    }
+    while (/\s/u.test(command[index] ?? ""))
+        index += 1;
+    if (index >= command.length)
+        return { argument, remainder: "" };
+    if (command.slice(index, index + 2) === "&&")
+        index += 2;
+    else if (command[index] === ";")
+        index += 1;
+    else
+        return undefined;
+    return { argument, remainder: command.slice(index).trimStart() };
+}
+export function getActiveWorkflowRoot(entries) {
+    return activeWorkflow(entries)?.root;
+}
+export function findLatestWorkflowRoot(entries) {
+    for (const entry of [...entries].reverse()) {
+        if (entry.type !== "custom" || entry.customType !== "hwcode-workflow-state"
+            || !entry.data || typeof entry.data !== "object")
+            continue;
+        const root = entry.data.root;
+        if (typeof root === "string" && root)
+            return root;
+    }
+    return undefined;
+}
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}

package/.pi/extensions/knowledge.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Worker } from "node:worker_threads";
 
@@ -14,7 +14,7 @@ import { matchKnowledge } from "../lib/knowledge/matcher.ts";
 import { loadKnowledgeById, loadKnowledgeSnapshot, projectKnowledgeKey } from "../lib/knowledge/store.ts";
 import type { KnowledgeWorkerInput, KnowledgeWorkerOutput } from "../lib/knowledge/worker-protocol.ts";
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../lib/runtime/defaults.ts";
-import { getWorkingDirectory } from "../lib/working-directory.ts";
+import { findLatestWorkflowRoot, getWorkingDirectory } from "../lib/working-directory.ts";
 
 interface ActiveReview {
   requestId: string;
@@ -98,15 +98,29 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
   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");
+    if (!ctx.isIdle() || ctx.hasPendingMessages()) {
+      post({
+        type: "review_deferred",
+        leaderToken: message.leaderToken,
+        requestId: message.requestId,
+        reason: "model-executor-is-busy",
+      });
+      return;
+    }
     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 snapshot = loadKnowledgeSnapshot(message.task.projectKey);
+    const applicableCatalog = {
+      ...snapshot.catalog,
+      items: snapshot.catalog.items.filter((entry) => (
+        entry.scope === "global" || entry.scope === `project:${message.task.projectKey}`
+      )),
+    };
     const related: ExistingKnowledgeContext[] = matchKnowledge(
       message.task.delta,
-      snapshot.catalog,
+      applicableCatalog,
       KNOWLEDGE_RUNTIME_DEFAULTS.review.maxExistingContextItems,
     ).map((entry, index) => {
       const reference: ExistingKnowledgeContext = {
@@ -146,10 +160,12 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
       .map((item) => item.text).join("\n");
     post({ type: "review_result", leaderToken: message.leaderToken, requestId: message.requestId, raw });
   } catch (error) {
-    post({
-      type: "review_result", leaderToken: message.leaderToken, requestId: message.requestId,
-      error: error instanceof Error ? error.message : String(error),
-    });
+    const reason = error instanceof Error ? error.message : String(error);
+    if (reason === "model-executor-is-busy") {
+      post({ type: "review_deferred", leaderToken: message.leaderToken, requestId: message.requestId, reason });
+    } else {
+      post({ type: "review_result", leaderToken: message.leaderToken, requestId: message.requestId, error: reason });
+    }
     try { updateCapability(); } catch { /* The worker lease will recover even if the extension context changed. */ }
   } finally {
     clearTimeout(timeout);
@@ -210,7 +226,13 @@ function configureForContext(ctx: ExtensionContext): void {
 }
 
 function currentProject(ctx: ExtensionContext): { root: string; key: string } {
-  const root = getWorkingDirectory(ctx.sessionManager);
+  const workingDirectory = resolve(getWorkingDirectory(ctx.sessionManager));
+  const workflowRootValue = findLatestWorkflowRoot(ctx.sessionManager.getEntries());
+  const workflowRoot = workflowRootValue ? resolve(workflowRootValue) : undefined;
+  const root = workflowRoot
+    && (workingDirectory === workflowRoot || workingDirectory.startsWith(`${workflowRoot}${sep}`))
+    ? workflowRoot
+    : workingDirectory;
   return { root, key: projectKnowledgeKey(root) };
 }
 

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

@@ -23,6 +23,12 @@ export interface KnowledgeReviewStatus {
     attempt: number;
     startedAt: string;
   };
+  lastDeferred?: {
+    reviewKey: string;
+    sessionKey: string;
+    deferredAt: string;
+    reason: string;
+  };
   lastReview?: {
     reviewKey: string;
     sessionKey: string;

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

@@ -113,6 +113,23 @@ function finishReview(
   publishReviewStatus();
 }
 
+function deferReview(task: KnowledgeReviewTask, reason: string): void {
+  clearTimeout(activeDeadlineTimer);
+  activeDeadlineTimer = undefined;
+  const attempts = reviewAttempts.get(task.reviewKey) ?? 1;
+  if (attempts <= 1) reviewAttempts.delete(task.reviewKey);
+  else reviewAttempts.set(task.reviewKey, attempts - 1);
+  if (!reviewStatus) return;
+  reviewStatus.activeReview = undefined;
+  reviewStatus.lastDeferred = {
+    reviewKey: task.reviewKey,
+    sessionKey: task.sessionKey,
+    deferredAt: new Date().toISOString(),
+    reason: boundedError(reason),
+  };
+  publishReviewStatus();
+}
+
 function removeLeaderMetadata(token: string): void {
   try {
     const current = JSON.parse(readFileSync(paths.knowledgeLeader, "utf8")) as { leaderToken?: string };
@@ -332,6 +349,13 @@ function handleReviewResult(message: Extract<KnowledgeWorkerInput, { type: "revi
   }
 }
 
+function handleReviewDeferred(message: Extract<KnowledgeWorkerInput, { type: "review_deferred" }>): void {
+  const task = activeTask;
+  if (!task || message.requestId !== task.requestId || message.leaderToken !== leaderToken || !leaderServer) return;
+  deferReview(task, message.reason);
+  activeTask = undefined;
+}
+
 const scanTimer = setInterval(() => { void scanForReview(); }, KNOWLEDGE_RUNTIME_DEFAULTS.review.intervalMs);
 scanTimer.unref();
 
@@ -348,6 +372,7 @@ parentPort.on("message", (message: KnowledgeWorkerInput) => {
     } else scheduleElection(0);
     return;
   }
+  if (message.type === "review_deferred") { handleReviewDeferred(message); return; }
   if (message.type === "review_result") { handleReviewResult(message); return; }
   if (message.type === "scan_now") { void scanForReview(); return; }
   stopped = true;

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

@@ -1,12 +1,13 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFileSync, readdirSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { resolve, sep } from "node:path";
 
 import {
   buildContextEntries, parseSessionEntries, type SessionEntry, type SessionHeader,
 } from "@earendil-works/pi-coding-agent";
 
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
+import { findLatestWorkflowRoot } from "../working-directory.ts";
 import { knowledgeDeltaDigest } from "./extractor.ts";
 import { sanitizeKnowledgeText } from "./sanitize.ts";
 import { projectKnowledgeKey } from "./store.ts";
@@ -105,13 +106,23 @@ function buildValidationContext(entries: SessionEntry[]): string {
 }
 
 function projectRootForSession(header: SessionHeader, branch: SessionEntry[]): string {
+  const sessionRoot = resolve(header.cwd);
+  const workflowRootValue = findLatestWorkflowRoot(branch);
+  const workflowRoot = workflowRootValue ? resolve(workflowRootValue) : undefined;
+  let workingDirectory = sessionRoot;
   for (const entry of branch.slice().reverse()) {
     if (entry.type !== "custom" || entry.customType !== "hwcode-working-directory"
       || !entry.data || typeof entry.data !== "object") continue;
     const cwd = (entry.data as Record<string, unknown>).cwd;
-    if (typeof cwd === "string" && cwd) return resolve(cwd);
+    if (typeof cwd !== "string" || !cwd) continue;
+    workingDirectory = resolve(cwd);
+    break;
   }
-  return resolve(header.cwd);
+  if (workflowRoot && (workingDirectory === workflowRoot || workingDirectory.startsWith(`${workflowRoot}${sep}`))) {
+    return workflowRoot;
+  }
+  if (workingDirectory === sessionRoot || workingDirectory.startsWith(`${sessionRoot}${sep}`)) return sessionRoot;
+  return workingDirectory;
 }
 
 export function discoverSessionFiles(root: string): string[] {

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

@@ -11,7 +11,8 @@ import { userRuntimePaths } from "../runtime/paths.ts";
 import { compactKnowledgeSummary, compactKnowledgeText, sanitizeKnowledgeText } from "./sanitize.ts";
 import type {
   KnowledgeCandidate, KnowledgeCatalog, KnowledgeCatalogEntry, KnowledgeManifest, KnowledgeReviewCursor,
-  KnowledgeReviewTask, KnowledgeScope, KnowledgeSnapshot, KnowledgeTrack, PersistKnowledgeResult,
+  KnowledgeReviewTask, KnowledgeScope, KnowledgeSkipReason, KnowledgeSnapshot, KnowledgeTrack,
+  PersistKnowledgeResult,
 } from "./types.ts";
 
 const STORAGE = KNOWLEDGE_RUNTIME_DEFAULTS.storage;
@@ -151,17 +152,28 @@ function semanticDuplicateIndex(candidate: KnowledgeCandidate, catalog: Knowledg
   return bestIndex;
 }
 
-function unsupportedOperations(value: string): string[] {
-  return [...value.matchAll(/\bOperation\s+([A-Za-z][A-Za-z0-9]+)\s+is not supported\b/gu)]
-    .map((match) => match[1]!.toLowerCase());
+interface UnsupportedOperation {
+  operation: string;
+  service?: string;
+}
+
+function unsupportedOperations(value: string): UnsupportedOperation[] {
+  return [...value.matchAll(/\bOperation\s+([A-Za-z][A-Za-z0-9]+)\s+is not supported\b/gu)].map((match) => {
+    const suffix = value.slice(match.index + match[0].length, match.index + match[0].length + 500);
+    const service = /\bhcloud\s+([A-Za-z][A-Za-z0-9-]*)\s+--help\b/iu.exec(suffix)?.[1]?.toLowerCase();
+    return { operation: match[1]!.toLowerCase(), service };
+  });
 }
 
 function contradictsVerifiedFailures(body: string, validationText: string): boolean {
   const normalizedBody = body.toLowerCase();
-  for (const operation of unsupportedOperations(validationText)) {
-    const index = normalizedBody.search(new RegExp(`\\b${operation}\\b`, "u"));
+  for (const unsupported of unsupportedOperations(validationText)) {
+    const operationExpression = unsupported.service
+      ? new RegExp(`\\b(?:hcloud\\s+)?${unsupported.service}\\b[^\\n]{0,120}\\b${unsupported.operation}\\b`, "u")
+      : new RegExp(`\\b${unsupported.operation}\\b`, "u");
+    const index = normalizedBody.search(operationExpression);
     if (index < 0) continue;
-    const context = normalizedBody.slice(Math.max(0, index - 80), index + operation.length + 80);
+    const context = normalizedBody.slice(Math.max(0, index - 80), index + 240);
     if (!/(?:not supported|unsupported|do not|don't|avoid|不支持|不要|避免)/u.test(context)) return true;
   }
   return false;
@@ -177,25 +189,29 @@ function asStringArray(value: unknown, maxItems: number): string[] {
     .map((item) => compactKnowledgeText(item, 240)).filter(Boolean))].slice(0, maxItems);
 }
 
-function normalizeCandidate(value: unknown, projectKey: string, validationText: string): KnowledgeCandidate | undefined {
-  if (!value || typeof value !== "object") return undefined;
+type CandidateNormalization = { candidate: KnowledgeCandidate } | { reason: KnowledgeSkipReason };
+
+function normalizeCandidate(value: unknown, projectKey: string, validationText: string): CandidateNormalization {
+  if (!value || typeof value !== "object") return { reason: "invalid-schema" };
   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;
+    || typeof raw.body !== "string" || typeof raw.confidence !== "number") return { reason: "invalid-schema" };
+  if (raw.durability !== "stable") return { reason: "unstable" };
+  if (raw.confidence < KNOWLEDGE_RUNTIME_DEFAULTS.review.minimumConfidence) return { reason: "low-confidence" };
+  if (raw.targetId !== undefined && raw.targetId !== null
+    && (typeof raw.targetId !== "string" || !SAFE_ID_RE.test(raw.targetId))) return { reason: "unknown-target" };
   const explicitUserDirective = raw.explicitUserDirective === true;
   const scope: KnowledgeScope = raw.scope === "global" && explicitUserDirective ? "global" : `project:${projectKey}`;
   const body = compactKnowledgeText(raw.body, 20_000);
   const evidence = asStringArray(raw.evidence, 8);
-  if (!body || evidence.length === 0) return undefined;
-  if (contradictsVerifiedFailures(body, validationText)) return undefined;
+  if (!body || evidence.length === 0) return { reason: "missing-body-or-evidence" };
+  if (contradictsVerifiedFailures(body, validationText)) return { reason: "contradicts-verified-failure" };
   const requestedTrack: KnowledgeTrack = raw.storageHint === "rule" ? "rule" : "topic";
   const ruleEligible = body.length <= STORAGE.maxRuleChars && body.split("\n").length <= STORAGE.maxRuleFileLines
     && body.split(/\n\s*\n/gu).length === 1
     && (explicitUserDirective || raw.confidence >= 0.9);
   const targetId = typeof raw.targetId === "string" && SAFE_ID_RE.test(raw.targetId) ? raw.targetId : undefined;
-  return {
+  return { candidate: {
     key: compactKnowledgeText(raw.key, 160), targetId,
     title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
     summary: compactKnowledgeSummary(raw.summary, STORAGE.maxSummaryChars),
@@ -204,7 +220,21 @@ function normalizeCandidate(value: unknown, projectKey: string, validationText:
     storageHint: requestedTrack === "rule" && ruleEligible ? "rule" : "topic",
     action: raw.action === "revise" ? "revise" : raw.action === "reinforce" ? "reinforce" : "add",
     explicitUserDirective, durability: "stable",
-  };
+  } };
+}
+
+function recordSkip(result: PersistKnowledgeResult, reason: KnowledgeSkipReason): void {
+  result.skipped++;
+  result.skippedReasons ??= {};
+  result.skippedReasons[reason] = (result.skippedReasons[reason] ?? 0) + 1;
+}
+
+function writeRejectedPending(directory: string, reason: KnowledgeSkipReason, value: unknown): void {
+  let serialized: string;
+  try { serialized = JSON.stringify(value); } catch { serialized = String(value); }
+  const candidate = sanitizeKnowledgeText(serialized).slice(0, 10_000);
+  const name = `${Date.now()}-rejected-${reason}-${randomUUID().slice(0, 8)}.json`;
+  atomicWrite(join(directory, "pending", name), `${JSON.stringify({ reason, candidate }, null, 2)}\n`);
 }
 
 function renderKnowledgeFile(candidate: KnowledgeCandidate): string {
@@ -328,15 +358,25 @@ export function commitKnowledgeReview(
     copyCurrentContent(current, temporary, home);
     const catalog: KnowledgeCatalog = structuredClone(current.catalog);
     const result: PersistKnowledgeResult = { saved: 0, updated: 0, pending: 0, skipped: 0 };
+    const rejected: Array<{ reason: KnowledgeSkipReason; value: unknown }> = [];
     for (const value of values.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates)) {
-      const candidate = normalizeCandidate(value, task.projectKey, `${task.context ?? ""}\n${task.delta}`);
-      if (!candidate) { result.skipped++; continue; }
+      const normalized = normalizeCandidate(value, task.projectKey, `${task.context ?? ""}\n${task.delta}`);
+      if (!("candidate" in normalized)) {
+        recordSkip(result, normalized.reason);
+        rejected.push({ reason: normalized.reason, value });
+        continue;
+      }
+      const candidate = normalized.candidate;
       const fingerprint = normalizedFingerprint(candidate);
       const hash = contentHash(candidate);
       const targetIndex = candidate.targetId
         ? catalog.items.findIndex((item) => item.id === candidate.targetId && applicable(item, task.projectKey))
         : -1;
-      if (candidate.targetId && targetIndex < 0) { result.skipped++; continue; }
+      if (candidate.targetId && targetIndex < 0) {
+        recordSkip(result, "unknown-target");
+        rejected.push({ reason: "unknown-target", value });
+        continue;
+      }
       let existingIndex = targetIndex >= 0
         ? targetIndex
         : catalog.items.findIndex((item) => item.fingerprint === fingerprint);
@@ -378,6 +418,10 @@ export function commitKnowledgeReview(
       if (existingIndex >= 0) { catalog.items[existingIndex] = entry; result.updated++; }
       else { catalog.items.push(entry); result.saved++; }
     }
+    if (result.skipped > 0 && result.saved === 0 && result.updated === 0 && result.pending === 0) {
+      for (const item of rejected) writeRejectedPending(temporary, item.reason, item.value);
+      result.pending += rejected.length;
+    }
     catalog.updatedAt = new Date().toISOString();
     const manifest: KnowledgeManifest = {
       version: 3, generationId, createdAt: new Date().toISOString(), leaderToken, catalog,

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

@@ -75,8 +75,17 @@ export interface PersistKnowledgeResult {
   updated: number;
   pending: number;
   skipped: number;
+  skippedReasons?: Partial<Record<KnowledgeSkipReason, number>>;
 }
 
+export type KnowledgeSkipReason =
+  | "invalid-schema"
+  | "unstable"
+  | "low-confidence"
+  | "missing-body-or-evidence"
+  | "contradicts-verified-failure"
+  | "unknown-target";
+
 export interface KnowledgeReviewTask {
   requestId: string;
   reviewKey: string;

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

@@ -2,6 +2,7 @@ import type { KnowledgeReviewTask, PersistKnowledgeResult } from "./types.ts";
 
 export type KnowledgeWorkerInput =
   | { type: "configure"; modelAvailable: boolean; sessionsRoot: string }
+  | { type: "review_deferred"; leaderToken: string; requestId: string; reason: string }
   | { type: "review_result"; leaderToken: string; requestId: string; raw?: string; error?: string }
   | { type: "scan_now" }
   | { type: "stop" };

package/.pi/lib/working-directory.ts

@@ -189,6 +189,16 @@ export function getActiveWorkflowRoot(entries: readonly SessionEntry[]): string
 	return activeWorkflow(entries)?.root;
 }
 
+export function findLatestWorkflowRoot(entries: readonly SessionEntry[]): string | undefined {
+	for (const entry of [...entries].reverse()) {
+		if (entry.type !== "custom" || entry.customType !== "hwcode-workflow-state"
+			|| !entry.data || typeof entry.data !== "object") continue;
+		const root = (entry.data as Record<string, unknown>).root;
+		if (typeof root === "string" && root) return root;
+	}
+	return undefined;
+}
+
 export function shellQuote(value: string): string {
 	return `'${value.replaceAll("'", `'"'"'`)}'`;
 }

package/package.json

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