cclaw-cli 0.48.15 → 0.48.17

package/dist/content/flow-map.js

@@ -118,6 +118,11 @@ Hook-driven guards respect the \`strictness\` field in
 
 Override per-session with \`CCLAW_STRICTNESS=advisory|strict\`.
 
+Hook wiring itself comes from a **single manifest** (\`src/content/hook-manifest.ts\`):
+the per-harness documents at \`.claude/hooks/hooks.json\`, \`.cursor/hooks.json\`,
+\`.codex/hooks.json\` are all derived from it. Inspect the live bindings with
+\`cclaw internal hook-manifest\` (add \`--json\` for machine-readable output).
+
 ## When in doubt
 
 1. Read \`${RUNTIME_ROOT}/state/flow-state.json\` to know where you are.

package/dist/content/hook-events.d.ts

@@ -1,4 +1,9 @@
 import type { HarnessId } from "../types.js";
-export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_checkpoint", "precompact_digest"];
-export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
+import { type HookSemanticEvent } from "./hook-manifest.js";
+export { HOOK_SEMANTIC_EVENTS, type HookSemanticEvent } from "./hook-manifest.js";
+/**
+ * Public semantic coverage map derived from `HOOK_MANIFEST` for
+ * claude/cursor/codex, plus the static OpenCode descriptor. Consumers
+ * should treat this as read-only.
+ */
 export declare const HOOK_EVENTS_BY_HARNESS: Record<HarnessId, Partial<Record<HookSemanticEvent, string>>>;

package/dist/content/hook-events.js

@@ -1,47 +1,31 @@
-export const HOOK_SEMANTIC_EVENTS = [
-    "session_rehydrate",
-    "pre_tool_prompt_guard",
-    "pre_tool_workflow_guard",
-    "post_tool_context_monitor",
-    "stop_checkpoint",
-    "precompact_digest"
-];
-export const HOOK_EVENTS_BY_HARNESS = {
-    claude: {
-        session_rehydrate: "SessionStart matcher startup|resume|clear|compact",
-        pre_tool_prompt_guard: "PreToolUse -> prompt-guard",
-        pre_tool_workflow_guard: "PreToolUse -> workflow-guard",
-        post_tool_context_monitor: "PostToolUse -> context-monitor",
-        stop_checkpoint: "Stop -> stop-checkpoint",
-        precompact_digest: "PreCompact -> pre-compact"
-    },
-    cursor: {
-        session_rehydrate: "sessionStart/sessionResume/sessionClear/sessionCompact",
-        pre_tool_prompt_guard: "preToolUse -> prompt-guard",
-        pre_tool_workflow_guard: "preToolUse -> workflow-guard",
-        post_tool_context_monitor: "postToolUse -> context-monitor",
-        stop_checkpoint: "stop -> stop-checkpoint",
-        precompact_digest: "sessionCompact -> pre-compact"
-    },
-    opencode: {
-        session_rehydrate: "plugin event handlers + transform rehydration",
-        pre_tool_prompt_guard: "plugin tool.execute.before -> prompt-guard",
-        pre_tool_workflow_guard: "plugin tool.execute.before -> workflow-guard",
-        post_tool_context_monitor: "plugin tool.execute.after -> context-monitor",
-        stop_checkpoint: "plugin session.idle -> stop-checkpoint",
-        precompact_digest: "plugin session.compacted -> pre-compact"
-    },
-    codex: {
-        // Codex CLI v0.114+ exposes lifecycle hooks via `.codex/hooks.json`,
-        // gated by `[features] codex_hooks = true` in `~/.codex/config.toml`.
-        // SessionStart, Stop, and UserPromptSubmit fire for every turn;
-        // PreToolUse/PostToolUse are **Bash-only** (Write/Edit/WebSearch/MCP
-        // calls do not trigger them). `precompact_digest` is unmapped —
-        // Codex has no PreCompact event; cclaw covers it via `/cc-ops retro`.
-        session_rehydrate: "SessionStart matcher startup|resume",
-        pre_tool_prompt_guard: "PreToolUse matcher Bash -> prompt-guard (plus UserPromptSubmit for non-Bash prompts)",
-        pre_tool_workflow_guard: "PreToolUse matcher Bash -> workflow-guard (Bash-only)",
-        post_tool_context_monitor: "PostToolUse matcher Bash -> context-monitor (Bash-only)",
-        stop_checkpoint: "Stop -> stop-checkpoint"
-    }
+import { HOOK_MANIFEST_HARNESSES, semanticEventCoverage } from "./hook-manifest.js";
+export { HOOK_SEMANTIC_EVENTS } from "./hook-manifest.js";
+function isManifestHarness(value) {
+    return HOOK_MANIFEST_HARNESSES.includes(value);
+}
+/**
+ * OpenCode is covered by the inline plugin (`opencode-plugin.ts`), not
+ * by the generated `run-hook.mjs` dispatcher. We keep its semantic
+ * coverage table here as an explicit descriptor, since it does not
+ * flow through the hook manifest.
+ */
+const OPENCODE_SEMANTIC_COVERAGE = {
+    session_rehydrate: "plugin event handlers + transform rehydration",
+    pre_tool_prompt_guard: "plugin tool.execute.before -> prompt-guard",
+    pre_tool_workflow_guard: "plugin tool.execute.before -> workflow-guard",
+    post_tool_context_monitor: "plugin tool.execute.after -> context-monitor",
+    stop_checkpoint: "plugin session.idle -> stop-checkpoint",
+    precompact_digest: "plugin session.compacted -> pre-compact"
 };
+/**
+ * Public semantic coverage map derived from `HOOK_MANIFEST` for
+ * claude/cursor/codex, plus the static OpenCode descriptor. Consumers
+ * should treat this as read-only.
+ */
+export const HOOK_EVENTS_BY_HARNESS = Object.freeze({
+    claude: semanticEventCoverage("claude"),
+    cursor: semanticEventCoverage("cursor"),
+    codex: semanticEventCoverage("codex"),
+    opencode: OPENCODE_SEMANTIC_COVERAGE
+});
+void isManifestHarness;

package/dist/content/hook-manifest.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Canonical operational manifest for cclaw hooks.
+ *
+ * This is the **single source of truth** for:
+ *
+ *  - the per-harness JSON generators in `./observe.ts`
+ *    (claude/cursor/codex hook documents),
+ *  - the semantic coverage map in `./hook-events.ts` (docs + doctor),
+ *  - the `requiredEvents` list embedded in `src/hook-schemas/*.v1.json`
+ *    (enforced by a parity test).
+ *
+ * When adding a new hook handler or rerouting an existing one, edit
+ * this file and let the downstream modules rebuild from it. Never
+ * hard-code a `SessionStart`, `PreToolUse`, etc. mapping outside of
+ * this manifest.
+ *
+ * OpenCode is deliberately out of scope here: its plugin
+ * (`opencode-plugin.ts`) implements the handlers inline rather than
+ * dispatching through `run-hook.mjs`, so its coverage is tracked
+ * separately in `HOOK_EVENTS_BY_HARNESS`.
+ */
+export declare const HOOK_MANIFEST_HARNESSES: readonly ["claude", "cursor", "codex"];
+export type HookManifestHarness = (typeof HOOK_MANIFEST_HARNESSES)[number];
+export declare const HOOK_HANDLERS: readonly ["session-start", "prompt-guard", "workflow-guard", "context-monitor", "stop-checkpoint", "pre-compact", "verify-current-state"];
+export type HookHandlerId = (typeof HOOK_HANDLERS)[number];
+export interface HookBinding {
+    /**
+     * Harness-native event name (exact string; PascalCase for
+     * claude/codex, camelCase for cursor). Do not normalize casing.
+     */
+    event: string;
+    matcher?: string;
+    timeout?: number;
+    /**
+     * Within a single (harness, event) group, entries are sorted by
+     * `priority` ASC, ties broken by manifest-declaration order. Use
+     * this to express "this handler must run BEFORE/AFTER that handler
+     * on the same event" (e.g. pre-compact must run before session-start
+     * on cursor `sessionCompact`). Default `0`.
+     */
+    priority?: number;
+}
+export interface HookHandlerSpec {
+    handler: HookHandlerId;
+    description: string;
+    /**
+     * Semantic event id used by `HOOK_EVENTS_BY_HARNESS` / docs.
+     * `null` means this handler contributes no semantic coverage row
+     * (e.g. `verify-current-state` on codex is a supplementary guard,
+     * not a top-level semantic event).
+     */
+    semantic: HookSemanticEvent | null;
+    bindings: Partial<Record<HookManifestHarness, HookBinding[]>>;
+}
+export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_checkpoint", "precompact_digest"];
+export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
+export declare const HOOK_MANIFEST: readonly HookHandlerSpec[];
+export interface EventGroup {
+    event: string;
+    /**
+     * Entries sorted by (priority ASC, declaration order). Default
+     * priority is 0. Stable — ties preserve manifest order.
+     */
+    entries: Array<{
+        handler: HookHandlerId;
+        matcher?: string;
+        timeout?: number;
+    }>;
+}
+/**
+ * Group manifest bindings by harness-native event name. This is the
+ * core projection that observe.ts generators consume to emit the
+ * harness-specific JSON document.
+ */
+export declare function groupBindingsByEvent(harness: HookManifestHarness): EventGroup[];
+/** Distinct harness-native event names covered by the manifest. */
+export declare function requiredEventsFor(harness: HookManifestHarness): string[];
+/**
+ * Human-readable per-harness semantic coverage used by docs and by
+ * the doctor's `harness-gaps.json` synthesis.
+ */
+export declare function semanticEventCoverage(harness: HookManifestHarness): Partial<Record<HookSemanticEvent, string>>;

package/dist/content/hook-manifest.js

@@ -0,0 +1,208 @@
+/**
+ * Canonical operational manifest for cclaw hooks.
+ *
+ * This is the **single source of truth** for:
+ *
+ *  - the per-harness JSON generators in `./observe.ts`
+ *    (claude/cursor/codex hook documents),
+ *  - the semantic coverage map in `./hook-events.ts` (docs + doctor),
+ *  - the `requiredEvents` list embedded in `src/hook-schemas/*.v1.json`
+ *    (enforced by a parity test).
+ *
+ * When adding a new hook handler or rerouting an existing one, edit
+ * this file and let the downstream modules rebuild from it. Never
+ * hard-code a `SessionStart`, `PreToolUse`, etc. mapping outside of
+ * this manifest.
+ *
+ * OpenCode is deliberately out of scope here: its plugin
+ * (`opencode-plugin.ts`) implements the handlers inline rather than
+ * dispatching through `run-hook.mjs`, so its coverage is tracked
+ * separately in `HOOK_EVENTS_BY_HARNESS`.
+ */
+export const HOOK_MANIFEST_HARNESSES = ["claude", "cursor", "codex"];
+export const HOOK_HANDLERS = [
+    "session-start",
+    "prompt-guard",
+    "workflow-guard",
+    "context-monitor",
+    "stop-checkpoint",
+    "pre-compact",
+    "verify-current-state"
+];
+export const HOOK_SEMANTIC_EVENTS = [
+    "session_rehydrate",
+    "pre_tool_prompt_guard",
+    "pre_tool_workflow_guard",
+    "post_tool_context_monitor",
+    "stop_checkpoint",
+    "precompact_digest"
+];
+export const HOOK_MANIFEST = [
+    {
+        handler: "session-start",
+        description: "Rehydrate flow state, refresh Ralph Loop + compound readiness, emit bootstrap digest.",
+        semantic: "session_rehydrate",
+        bindings: {
+            claude: [{ event: "SessionStart", matcher: "startup|resume|clear|compact" }],
+            cursor: [
+                { event: "sessionStart" },
+                { event: "sessionResume" },
+                { event: "sessionClear" },
+                { event: "sessionCompact" }
+            ],
+            codex: [{ event: "SessionStart", matcher: "startup|resume" }]
+        }
+    },
+    {
+        handler: "prompt-guard",
+        description: "Stage-aware prompt gate (iron-laws + strictness).",
+        semantic: "pre_tool_prompt_guard",
+        bindings: {
+            claude: [{ event: "PreToolUse", matcher: "*" }],
+            cursor: [{ event: "preToolUse", matcher: "*" }],
+            codex: [
+                { event: "UserPromptSubmit" },
+                { event: "PreToolUse", matcher: "Bash|bash" }
+            ]
+        }
+    },
+    {
+        handler: "workflow-guard",
+        description: "TDD and workflow gate on Write/Edit/Bash style tool invocations.",
+        semantic: "pre_tool_workflow_guard",
+        bindings: {
+            claude: [{ event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash" }],
+            cursor: [{ event: "preToolUse", matcher: "*" }],
+            codex: [
+                { event: "UserPromptSubmit" },
+                { event: "PreToolUse", matcher: "Bash|bash" }
+            ]
+        }
+    },
+    {
+        handler: "context-monitor",
+        description: "Post-tool context usage + stage signal monitor.",
+        semantic: "post_tool_context_monitor",
+        bindings: {
+            claude: [{ event: "PostToolUse", matcher: "*" }],
+            cursor: [{ event: "postToolUse", matcher: "*" }],
+            codex: [{ event: "PostToolUse", matcher: "Bash|bash" }]
+        }
+    },
+    {
+        handler: "stop-checkpoint",
+        description: "Persist checkpoint with stage + run context on session stop.",
+        semantic: "stop_checkpoint",
+        bindings: {
+            claude: [{ event: "Stop", timeout: 10 }],
+            cursor: [{ event: "stop", timeout: 10 }],
+            codex: [{ event: "Stop", timeout: 10 }]
+        }
+    },
+    {
+        handler: "pre-compact",
+        description: "Write pre-compact digest (Claude+Cursor have a native event; Codex has no PreCompact — covered by `/cc-ops retro`).",
+        semantic: "precompact_digest",
+        bindings: {
+            claude: [{ event: "PreCompact", matcher: "manual|auto", timeout: 10 }],
+            // pre-compact must capture the digest BEFORE session-start
+            // rehydrates on cursor `sessionCompact`.
+            cursor: [{ event: "sessionCompact", priority: -10 }]
+        }
+    },
+    {
+        handler: "verify-current-state",
+        description: "Supplementary codex guard that runs on UserPromptSubmit to assert the live state matches the flow.",
+        semantic: null,
+        bindings: {
+            codex: [{ event: "UserPromptSubmit" }]
+        }
+    }
+];
+/** Sanity: every harness in HOOK_MANIFEST_HARNESSES must be a HarnessId. */
+const _harnessIdCheck = HOOK_MANIFEST_HARNESSES;
+void _harnessIdCheck;
+/**
+ * Group manifest bindings by harness-native event name. This is the
+ * core projection that observe.ts generators consume to emit the
+ * harness-specific JSON document.
+ */
+export function groupBindingsByEvent(harness) {
+    const order = [];
+    const byEvent = new Map();
+    let seq = 0;
+    for (const spec of HOOK_MANIFEST) {
+        const bindings = spec.bindings[harness];
+        if (!bindings)
+            continue;
+        for (const binding of bindings) {
+            let group = byEvent.get(binding.event);
+            if (!group) {
+                group = { event: binding.event, entries: [] };
+                byEvent.set(binding.event, group);
+                order.push(binding.event);
+            }
+            group.entries.push({
+                handler: spec.handler,
+                ...(binding.matcher !== undefined ? { matcher: binding.matcher } : {}),
+                ...(binding.timeout !== undefined ? { timeout: binding.timeout } : {}),
+                priority: binding.priority ?? 0,
+                seq: seq++
+            });
+        }
+    }
+    return order.map((event) => {
+        const group = byEvent.get(event);
+        const sorted = [...group.entries].sort((a, b) => {
+            if (a.priority !== b.priority)
+                return a.priority - b.priority;
+            return a.seq - b.seq;
+        });
+        return {
+            event: group.event,
+            entries: sorted.map(({ priority: _p, seq: _s, ...entry }) => entry)
+        };
+    });
+}
+/** Distinct harness-native event names covered by the manifest. */
+export function requiredEventsFor(harness) {
+    const seen = new Set();
+    const ordered = [];
+    for (const spec of HOOK_MANIFEST) {
+        for (const binding of spec.bindings[harness] ?? []) {
+            if (seen.has(binding.event))
+                continue;
+            seen.add(binding.event);
+            ordered.push(binding.event);
+        }
+    }
+    return ordered;
+}
+/**
+ * Human-readable per-harness semantic coverage used by docs and by
+ * the doctor's `harness-gaps.json` synthesis.
+ */
+export function semanticEventCoverage(harness) {
+    const out = {};
+    for (const spec of HOOK_MANIFEST) {
+        if (spec.semantic === null)
+            continue;
+        const bindings = spec.bindings[harness];
+        if (!bindings || bindings.length === 0)
+            continue;
+        out[spec.semantic] = describeBindings(bindings);
+    }
+    return out;
+}
+function describeBindings(bindings) {
+    return bindings
+        .map((binding) => {
+        const pieces = [binding.event];
+        if (binding.matcher)
+            pieces.push(`matcher=${binding.matcher}`);
+        if (binding.timeout)
+            pieces.push(`timeout=${binding.timeout}s`);
+        return pieces.join(" ");
+    })
+        .join(" | ");
+}

package/dist/content/node-hooks.js

@@ -53,19 +53,145 @@ function safeParseJson(raw, fallback = {}) {
   }
 }
 
-async function readJsonFile(filePath, fallback = {}) {
+// === atomic/locked state I/O =========================================
+//
+// The generated hook script runs OUTSIDE the cclaw CLI process, so it
+// cannot import \`fs-utils.ts\`. These helpers mirror \`writeFileSafe\` and
+// \`withDirectoryLock\` just enough to keep hook-owned state files
+// atomic and free of interleaved concurrent writes.
+
+function hookSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function withDirectoryLockInline(lockPath, fn, options = {}) {
+  const retries = Number.isFinite(options.retries) ? options.retries : 200;
+  const retryDelayMs = Number.isFinite(options.retryDelayMs) ? options.retryDelayMs : 20;
+  const staleAfterMs = Number.isFinite(options.staleAfterMs) ? options.staleAfterMs : 60000;
+  try {
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+  } catch {
+    // parent may already exist
+  }
+  let acquired = false;
+  let lastError = null;
+  for (let attempt = 0; attempt < retries; attempt += 1) {
+    try {
+      await fs.mkdir(lockPath);
+      acquired = true;
+      break;
+    } catch (error) {
+      lastError = error;
+      const code = error && typeof error === "object" && "code" in error ? error.code : null;
+      if (code !== "EEXIST") {
+        throw error;
+      }
+      try {
+        const stat = await fs.stat(lockPath);
+        if (Date.now() - stat.mtimeMs > staleAfterMs) {
+          await fs.rm(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        // lock vanished between retries
+      }
+      await hookSleep(retryDelayMs);
+    }
+  }
+  if (!acquired) {
+    const details = lastError instanceof Error ? lastError.message : String(lastError);
+    throw new Error(
+      "cclaw hook: failed to acquire lock " + lockPath + " (attempts=" + retries + ", lastError=" + details + ")"
+    );
+  }
+  try {
+    return await fn();
+  } finally {
+    await fs.rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
+async function writeFileAtomic(filePath, content, options = {}) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = path.join(
+    path.dirname(filePath),
+    "." + path.basename(filePath) + ".tmp-" + process.pid + "-" + Date.now() + "-" + Math.random().toString(36).slice(2, 8)
+  );
+  await fs.writeFile(tempPath, content, { encoding: "utf8" });
+  try {
+    await fs.rename(tempPath, filePath);
+    if (options.mode !== undefined) {
+      await fs.chmod(filePath, options.mode).catch(() => undefined);
+    }
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : null;
+    if (code === "EXDEV") {
+      try {
+        await fs.copyFile(tempPath, filePath);
+      } finally {
+        await fs.unlink(tempPath).catch(() => undefined);
+      }
+      if (options.mode !== undefined) {
+        await fs.chmod(filePath, options.mode).catch(() => undefined);
+      }
+      return;
+    }
+    await fs.unlink(tempPath).catch(() => undefined);
+    throw error;
+  }
+}
+
+function lockPathFor(filePath) {
+  return filePath + ".lock";
+}
+
+async function recordHookError(root, stage, detail) {
+  try {
+    const errorsPath = path.join(root, RUNTIME_ROOT, "state", "hook-errors.jsonl");
+    await fs.mkdir(path.dirname(errorsPath), { recursive: true });
+    const payload = JSON.stringify({
+      ts: new Date().toISOString(),
+      stage: typeof stage === "string" ? stage : "unknown",
+      detail: typeof detail === "string" ? detail : String(detail)
+    });
+    await fs.appendFile(errorsPath, payload + "\\n", "utf8");
+  } catch {
+    // diagnostics must never cascade
+  }
+}
+
+async function readJsonFile(filePath, fallback = {}, options = {}) {
   try {
     const raw = await fs.readFile(filePath, "utf8");
-    return safeParseJson(raw, fallback);
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+      return fallback;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed === undefined ? fallback : parsed;
+    } catch (parseErr) {
+      // Emit a diagnostic breadcrumb instead of silently returning fallback.
+      // The hook must still continue (soft-fail), but the corruption is
+      // now visible in \`state/hook-errors.jsonl\` and to \`cclaw doctor\`.
+      if (options.root) {
+        await recordHookError(
+          options.root,
+          options.stage || "read-json",
+          "corrupt-json file=" + filePath + " error=" + (parseErr instanceof Error ? parseErr.message : String(parseErr))
+        );
+      }
+      return fallback;
+    }
   } catch {
     return fallback;
   }
 }
 
 async function writeJsonFile(filePath, value) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
   const next = JSON.stringify(value, null, 2) + "\\n";
-  await fs.writeFile(filePath, next, "utf8");
+  await withDirectoryLockInline(lockPathFor(filePath), async () => {
+    await writeFileAtomic(filePath, next);
+  });
 }
 
 async function fileExists(filePath) {
@@ -86,8 +212,17 @@ async function readTextFile(filePath, fallback = "") {
 }
 
 async function appendJsonLine(filePath, value) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.appendFile(filePath, JSON.stringify(value) + "\\n", "utf8");
+  const payload = JSON.stringify(value) + "\\n";
+  await withDirectoryLockInline(lockPathFor(filePath), async () => {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.appendFile(filePath, payload, "utf8");
+  });
+}
+
+async function writeTextFileAtomic(filePath, content) {
+  await withDirectoryLockInline(lockPathFor(filePath), async () => {
+    await writeFileAtomic(filePath, content);
+  });
 }
 
 async function readStdin() {
@@ -532,7 +667,10 @@ function extractCodePathsFromText(value) {
 
 async function readFlowState(root) {
   const statePath = path.join(root, RUNTIME_ROOT, "state", "flow-state.json");
-  const parsed = await readJsonFile(statePath, {});
+  // Loud-on-corrupt: if flow-state.json exists but fails JSON.parse, log
+  // a breadcrumb into state/hook-errors.jsonl before falling back to an
+  // empty object. Silent fallbacks used to mask stale CLI+hook drift.
+  const parsed = await readJsonFile(statePath, {}, { root, stage: "read-flow-state" });
   const obj = toObject(parsed) || {};
   const completed = Array.isArray(obj.completedStages) ? obj.completedStages : [];
   return {
@@ -602,11 +740,9 @@ async function buildKnowledgeDigest(root, currentStage) {
     });
   const body =
     relevant.length > 0 ? relevant.join("\\n") : "(no matching entries for current stage)";
-  await fs.mkdir(path.dirname(digestFile), { recursive: true });
-  await fs.writeFile(
+  await writeTextFileAtomic(
     digestFile,
-    "# Knowledge digest (auto-generated)\\n\\n" + body + "\\n",
-    "utf8"
+    "# Knowledge digest (auto-generated)\\n\\n" + body + "\\n"
   );
   return {
     digestLines: relevant,
@@ -1069,8 +1205,7 @@ async function handlePreCompact(runtime) {
     digest.push("", "## Knowledge tail", knowledgeTail);
   }
   const digestFile = path.join(stateDir, "session-digest.md");
-  await fs.mkdir(path.dirname(digestFile), { recursive: true });
-  await fs.writeFile(digestFile, digest.join("\\n") + "\\n", "utf8");
+  await writeTextFileAtomic(digestFile, digest.join("\\n") + "\\n");
   return 0;
 }
 

package/dist/content/observe.d.ts

@@ -1,3 +1,19 @@
+import { type HookHandlerId, type HookManifestHarness } from "./hook-manifest.js";
 export declare function claudeHooksJsonWithObservation(): string;
 export declare function cursorHooksJsonWithObservation(): string;
 export declare function codexHooksJsonWithObservation(): string;
+/**
+ * Public accessor so diagnostic CLIs and tests can inspect the
+ * manifest without importing the private generator helpers.
+ */
+export declare function hookManifestSnapshot(): Array<{
+    harness: HookManifestHarness;
+    events: Array<{
+        event: string;
+        entries: Array<{
+            handler: HookHandlerId;
+            matcher?: string;
+            timeout?: number;
+        }>;
+    }>;
+}>;