cclaw-cli 0.48.22 → 0.48.24

package/dist/content/node-hooks.js

@@ -103,11 +103,20 @@ async function withDirectoryLockInline(lockPath, fn, options = {}) {
       }
       try {
         const stat = await fs.stat(lockPath);
+        if (!stat.isDirectory()) {
+          throw new Error("Lock path exists but is not a directory: " + lockPath);
+        }
         if (Date.now() - stat.mtimeMs > staleAfterMs) {
           await fs.rm(lockPath, { recursive: true, force: true });
           continue;
         }
-      } catch {
+      } catch (statError) {
+        if (
+          statError instanceof Error &&
+          statError.message.startsWith("Lock path exists but is not a directory")
+        ) {
+          throw statError;
+        }
         // lock vanished between retries
       }
       await hookSleep(retryDelayMs);
@@ -254,6 +263,24 @@ async function readTextFile(filePath, fallback = "") {
   }
 }
 
+// CLI-compatible knowledge lock. Must match
+// src/knowledge-store.ts::knowledgeLockPath exactly so the hook and the
+// CLI serialize on the same mutex when reading / appending
+// knowledge.jsonl. Drift here re-introduces the race we just closed.
+function knowledgeLockPathInline(root) {
+  return path.join(root, RUNTIME_ROOT, "state", ".knowledge.lock");
+}
+
+async function readTextFileLocked(lockPath, filePath, fallback = "") {
+  return withDirectoryLockInline(lockPath, async () => {
+    try {
+      return await fs.readFile(filePath, "utf8");
+    } catch {
+      return fallback;
+    }
+  });
+}
+
 async function appendJsonLine(filePath, value) {
   const payload = JSON.stringify(value) + "\\n";
   await withDirectoryLockInline(lockPathFor(filePath), async () => {
@@ -904,10 +931,16 @@ async function handleSessionStart(runtime) {
   const sessionDigest = (await readTextFile(sessionDigestFile, "")).trim();
   const activitySummary = await readRecentActivityLines(activityFile);
   const contextWarning = await readLatestContextWarningLine(contextWarningsFile);
-  // Read knowledge.jsonl exactly once per session-start; both the digest
-  // and compound-readiness derive from the same snapshot.
+  // Read knowledge.jsonl exactly once per session-start while holding the
+  // SAME lock CLI writers acquire in \`appendKnowledge\`. Guarantees we never
+  // see a partial (mid-write) snapshot. Both the digest and
+  // compound-readiness derive from this single read.
   const knowledgeFilePath = path.join(runtime.root, RUNTIME_ROOT, "knowledge.jsonl");
-  const knowledgeRaw = await readTextFile(knowledgeFilePath, "");
+  const knowledgeRaw = await readTextFileLocked(
+    knowledgeLockPathInline(runtime.root),
+    knowledgeFilePath,
+    ""
+  );
   const knowledge = await buildKnowledgeDigest(runtime.root, state.currentStage, knowledgeRaw);
 
   // Refresh Ralph Loop status each session-start so /cc-next and the model
@@ -925,8 +958,16 @@ async function handleSessionStart(runtime) {
         ", slices=" + String(ralphStatus.sliceCount) +
         ", acClosed=" + String(ralphStatus.acClosed.length) +
         ", redOpen=" + redOpen;
-    } catch (_err) {
-      // best-effort — a malformed cycle log should never break session-start.
+    } catch (err) {
+      // Best-effort — a malformed cycle log should never break
+      // session-start. But we DO leave a breadcrumb in
+      // hook-errors.jsonl so \`cclaw doctor\` can surface chronic
+      // failures (previously this was a silent swallow).
+      await recordHookError(
+        runtime.root,
+        "session-start:ralph-loop",
+        err instanceof Error ? err.message : String(err)
+      );
     }
   }
 
@@ -952,8 +993,16 @@ async function handleSessionStart(runtime) {
           ", ready=" + String(readiness.readyCount) + criticalSuffix;
       }
     }
-  } catch (_err) {
-    // best-effort — a malformed knowledge.jsonl must never break session-start.
+  } catch (err) {
+    // Best-effort — a malformed knowledge.jsonl must never break
+    // session-start. But we DO leave a breadcrumb in
+    // hook-errors.jsonl so config/IO problems become visible in
+    // \`cclaw doctor\` instead of silently degrading readiness output.
+    await recordHookError(
+      runtime.root,
+      "session-start:compound-readiness",
+      err instanceof Error ? err.message : String(err)
+    );
   }
 
   const suggestionMemory = toObject(await readJsonFile(suggestionMemoryFile, {})) || {};

package/dist/doctor-registry.js

@@ -85,7 +85,7 @@ const RULES = [
         }
     },
     {
-        test: /^(meta_skill:|protocol:|stage_skill:|context_mode:|reference:)/,
+        test: /^(meta_skill:|protocol:|stage_skill:|context_mode:)/,
         metadata: {
             severity: "error",
             summary: "Routing skill and protocol integrity check.",
@@ -93,6 +93,21 @@ const RULES = [
             docRef: ref("harness-and-routing.md")
         }
     },
+    {
+        // `reference:*` checks (flow-map.md and similar overview documents)
+        // are useful to detect drift from the generated baseline, but they
+        // document the surface rather than gate it. A missing section here
+        // means the map is out of date, not that a runtime contract is
+        // broken — so they report as a warning instead of hard-failing
+        // doctor / CI. `cclaw sync` rewrites the file.
+        test: /^reference:/,
+        metadata: {
+            severity: "warning",
+            summary: "Reference/overview doc integrity (non-blocking).",
+            fix: "Run `cclaw sync` to regenerate the reference doc from the canonical source.",
+            docRef: ref("harness-and-routing.md")
+        }
+    },
     {
         test: /^delegation:/,
         metadata: {

package/dist/fs-utils.js

@@ -42,12 +42,24 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
             }
             try {
                 const stat = await fs.stat(lockPath);
+                if (!stat.isDirectory()) {
+                    // A non-directory lives at the lock path (e.g. a stray file).
+                    // Retrying mkdir() will keep returning EEXIST forever, and no
+                    // other cclaw process is holding the lock - the path is simply
+                    // unusable. Fail loudly rather than burning the full retry
+                    // budget, so the caller sees a deterministic error.
+                    throw new Error(`Lock path exists but is not a directory: ${lockPath}`);
+                }
                 if (Date.now() - stat.mtimeMs > staleAfterMs) {
                     await fs.rm(lockPath, { recursive: true, force: true });
                     continue;
                 }
             }
-            catch {
+            catch (statError) {
+                if (statError instanceof Error &&
+                    statError.message.startsWith("Lock path exists but is not a directory")) {
+                    throw statError;
+                }
                 // Lock directory disappeared between retries.
             }
             await sleep(retryDelayMs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.48.22",
+  "version": "0.48.24",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {