@viloforge/vfkb 0.4.0 → 0.5.0

package/dist/bundles/vfkb.mjs

@@ -7,6 +7,9 @@ var __export = (target, all) => {
 
 // src/engine.ts
 import { randomBytes as randomBytes2 } from "node:crypto";
+import { existsSync as existsSync4 } from "node:fs";
+import { dirname as dirname3, join as join6, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
 
 // src/storage.ts
 import { basename, dirname as dirname2, join as join4, resolve } from "node:path";
@@ -15496,6 +15499,16 @@ function latestCrossRepo(all = readAll(), today = nowIso().slice(0, 10), superse
   }
   return latest;
 }
+var CLI_FACES = ["vfkb.mjs", "cli.js", "cli.mjs"];
+function resolveCliFace(engineDir) {
+  return CLI_FACES.map((f) => join6(engineDir, f)).find((p) => existsSync4(p));
+}
+function renderCaptureFallback(engineDir = dirname3(fileURLToPath(import.meta.url))) {
+  const cli = resolveCliFace(engineDir);
+  const target = cli ? `node "${cli}"` : `node <vfkb CLI not found beside the engine at ${engineDir} \u2014 locate vfkb.mjs or cli.js>`;
+  return `capture fallback: if the kb_* tools error or disappear, the CLI still writes (same engine, separate process; journaled per ADR-0064) \u2014
+  VFKB_DATA_DIR="${resolvePath(brainDir())}" ${target} add <type> "\u2026" [--tags a,b] [--why "\u2026"]`;
+}
 function renderContextBundle(project = defaultProject(), budget = SESSION_BUDGET_CHARS) {
   const all = readAll();
   const today = nowIso().slice(0, 10);
@@ -15534,6 +15547,7 @@ function renderContextBundle(project = defaultProject(), budget = SESSION_BUDGET
 `;
   }
   body += renderContextMap() + "\n\n";
+  body += renderCaptureFallback() + "\n\n";
   const kept = [];
   let keptLen = 0;
   let dropped = 0;
@@ -15741,7 +15755,7 @@ ${bundle}`;
 
 // src/export.ts
 import {
-  existsSync as existsSync4,
+  existsSync as existsSync5,
   mkdirSync as mkdirSync5,
   readdirSync as readdirSync2,
   readFileSync as readFileSync5,
@@ -15749,7 +15763,7 @@ import {
   statSync as statSync2,
   writeFileSync as writeFileSync3
 } from "node:fs";
-import { dirname as dirname3, join as join6 } from "node:path";
+import { dirname as dirname4, join as join7 } from "node:path";
 var GENERATED_MARKER = "generated by vfkb export";
 var MARKER_LINE_RE = /^<!-- generated by vfkb export /m;
 var EXPORT_BUDGET_CHARS = 4e4;
@@ -15798,7 +15812,7 @@ function listFiles(dir) {
   const out = [];
   const walk = (d) => {
     for (const name of readdirSync2(d)) {
-      const p = join6(d, name);
+      const p = join7(d, name);
       if (statSync2(p).isDirectory()) walk(p);
       else out.push(p);
     }
@@ -15815,7 +15829,7 @@ function isGenerated(path) {
   }
 }
 function prepareTree(dir) {
-  if (!existsSync4(dir)) {
+  if (!existsSync5(dir)) {
     mkdirSync5(dir, { recursive: true });
     return;
   }
@@ -15831,7 +15845,7 @@ function prepareTree(dir) {
   const dirs = [];
   const collect = (d) => {
     for (const name of readdirSync2(d)) {
-      const p = join6(d, name);
+      const p = join7(d, name);
       if (statSync2(p).isDirectory()) {
         collect(p);
         dirs.push(p);
@@ -15847,8 +15861,8 @@ function exportAgentsMd(opts = {}) {
   const { superseded, asOf, eligible } = projectionInputs();
   const project = opts.project ?? defaultProject();
   const budget = opts.budget ?? EXPORT_BUDGET_CHARS;
-  const out = opts.out ?? join6(process.cwd(), "AGENTS.md");
-  if (existsSync4(out) && !MARKER_LINE_RE.test(readFileSync5(out, "utf8"))) {
+  const out = opts.out ?? join7(process.cwd(), "AGENTS.md");
+  if (existsSync5(out) && !MARKER_LINE_RE.test(readFileSync5(out, "utf8"))) {
     throw new Error(
       `vfkb export: refusing to overwrite ${out} \u2014 it is not a previous export (no generated marker)`
     );
@@ -15907,7 +15921,7 @@ ${spine.trim()}
   }
   if (dropped > 0) body += `<!-- ${dropped} entries omitted for the ${budget}-char budget -->
 `;
-  mkdirSync5(dirname3(out), { recursive: true });
+  mkdirSync5(dirname4(out), { recursive: true });
   writeFileSync3(out, head + body);
   return { path: out };
 }
@@ -16005,13 +16019,13 @@ function deriveLog(eligibleIds, records, live) {
 function exportOkf(opts = {}) {
   const { superseded, asOf, eligible } = projectionInputs();
   const project = opts.project ?? defaultProject();
-  const dir = opts.out ?? join6(process.cwd(), ".okf");
+  const dir = opts.out ?? join7(process.cwd(), ".okf");
   prepareTree(dir);
   const marker = `<!-- ${GENERATED_MARKER} okf; regenerate with \`vfkb export okf\`, do not hand-edit (as-of ${asOf}) -->`;
   const files = [];
   const write = (rel, content) => {
-    const p = join6(dir, rel);
-    mkdirSync5(dirname3(p), { recursive: true });
+    const p = join7(dir, rel);
+    mkdirSync5(dirname4(p), { recursive: true });
     writeFileSync3(p, content);
     files.push(rel);
   };
@@ -16068,41 +16082,57 @@ function runExport(target, opts = {}) {
 
 // src/broadcast.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { existsSync as existsSync6, readFileSync as readFileSync7 } from "node:fs";
-import { basename as basename2, join as join8, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:fs";
+import { basename as basename2, join as join9, resolve as resolve2 } from "node:path";
 
 // src/manifest.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
-import { dirname as dirname4, join as join7 } from "node:path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname5, join as join8 } from "node:path";
 
 // src/version.ts
 var SCHEMA_VERSION = 1;
-var ENGINE_VERSION = true ? "0.4.0" : ownPackageVersion();
-var ENGINE_COMMIT = true ? "63659e5" : "dev";
+var ENGINE_VERSION = true ? "0.5.0" : ownPackageVersion();
+var ENGINE_COMMIT = true ? "aeaa5fa" : "dev";
 
 // src/manifest.ts
 function manifestPath(brainDir2) {
-  return join7(brainDir2, "manifest.json");
+  return join8(brainDir2, "manifest.json");
+}
+function isUnknownCommit(commit) {
+  return !commit || commit === "dev";
 }
-function currentManifest() {
-  return { schema_version: SCHEMA_VERSION, engine_version: ENGINE_VERSION, engine_commit: ENGINE_COMMIT };
+function currentManifest(opts = {}) {
+  return {
+    schema_version: SCHEMA_VERSION,
+    engine_version: opts.engineVersion ?? ENGINE_VERSION,
+    engine_commit: opts.engineCommit ?? ENGINE_COMMIT
+  };
 }
 function readManifest(brainDir2) {
   const p = manifestPath(brainDir2);
-  if (!existsSync5(p)) return void 0;
+  if (!existsSync6(p)) return void 0;
   try {
     return JSON.parse(readFileSync6(p, "utf8"));
   } catch {
     return void 0;
   }
 }
-function writeManifest(brainDir2) {
+function manifestNeedsStamp(brainDir2, engineCommit = ENGINE_COMMIT) {
+  const cur = readManifest(brainDir2);
+  if (!cur) return true;
+  return isUnknownCommit(cur.engine_commit) && !isUnknownCommit(engineCommit);
+}
+function writeManifest(brainDir2, opts = {}) {
   const p = manifestPath(brainDir2);
-  const existed = existsSync5(p);
+  const existed = existsSync6(p);
   const cur = readManifest(brainDir2);
-  const next = currentManifest();
+  const next = currentManifest(opts);
+  if (cur && isUnknownCommit(next.engine_commit) && !isUnknownCommit(cur.engine_commit)) {
+    next.engine_commit = cur.engine_commit;
+    next.engine_version = cur.engine_version;
+  }
   if (cur && JSON.stringify(cur) === JSON.stringify(next)) return "skipped";
-  mkdirSync6(dirname4(p), { recursive: true });
+  mkdirSync6(dirname5(p), { recursive: true });
   writeFileSync4(p, JSON.stringify(next, null, 2) + "\n");
   return existed ? "updated" : "created";
 }
@@ -16111,7 +16141,7 @@ function writeManifest(brainDir2) {
 var FORBIDDEN_TAGS = /* @__PURE__ */ new Set(["handoff", "next"]);
 function targetBrainDir(target) {
   const abs = resolve2(target);
-  return basename2(abs) === ".vfkb" ? abs : join8(abs, ".vfkb");
+  return basename2(abs) === ".vfkb" ? abs : join9(abs, ".vfkb");
 }
 function gitPosture(repoDir) {
   const git2 = (...a) => execFileSync2("git", ["-C", repoDir, ...a], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
@@ -16152,20 +16182,24 @@ function broadcast(text, targets, opts = {}) {
       continue;
     }
     const repoDir = resolve2(brain, "..");
-    const manifestPath2 = join8(brain, "manifest.json");
+    const manifestPath2 = join9(brain, "manifest.json");
     let healed = false;
-    if (!existsSync6(manifestPath2)) {
-      if (!existsSync6(join8(brain, "entries.jsonl"))) {
+    let upgraded = false;
+    const needsStamp = manifestNeedsStamp(brain, opts.engineCommit ?? ENGINE_COMMIT);
+    if (needsStamp) {
+      if (!existsSync7(join9(brain, "entries.jsonl"))) {
         results.push({ target, ok: false, reason: `no brain (no entries.jsonl in ${brain}) \u2014 never bootstrap a wire-less brain (ADR-0063 \xA73)` });
         continue;
       }
+      const absent = !existsSync7(manifestPath2);
       try {
-        writeManifest(brain);
+        writeManifest(brain, { engineCommit: opts.engineCommit, engineVersion: opts.engineVersion });
       } catch (err) {
-        results.push({ target, ok: false, reason: `manifest heal failed: ${err.message}` });
+        results.push({ target, ok: false, reason: `manifest ${absent ? "heal" : "provenance upgrade"} failed: ${err.message}` });
         continue;
       }
-      healed = true;
+      if (absent) healed = true;
+      else upgraded = true;
     }
     let schema;
     try {
@@ -16183,9 +16217,9 @@ function broadcast(text, targets, opts = {}) {
       process.env.VFKB_DATA_DIR = brain;
       const e = addEntry("fact", stamped, { role: "executor", tags: [.../* @__PURE__ */ new Set(["cross-repo", ...extraTags])] });
       written.add(brain);
-      results.push({ target, ok: true, id: e.id, posture: gitPosture(repoDir), ...healed ? { healed } : {} });
+      results.push({ target, ok: true, id: e.id, posture: gitPosture(repoDir), ...healed ? { healed } : {}, ...upgraded ? { upgraded } : {} });
     } catch (err) {
-      results.push({ target, ok: false, reason: err.message, ...healed ? { healed } : {} });
+      results.push({ target, ok: false, reason: err.message, ...healed ? { healed } : {}, ...upgraded ? { upgraded } : {} });
     } finally {
       if (prev === void 0) delete process.env.VFKB_DATA_DIR;
       else process.env.VFKB_DATA_DIR = prev;
@@ -16419,7 +16453,7 @@ var GATING_REASON = "vfkb: edit the brain via the engine/CLI/MCP, not by writing
 // src/stop-reminder.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
 import { readFileSync as readFileSync8 } from "node:fs";
-import { join as join9, relative as relative2 } from "node:path";
+import { join as join10, relative as relative2 } from "node:path";
 var STOP_REMINDER = 'vfkb decision-capture check: this turn changed code/docs but no `decision` was recorded to the brain. If a load-bearing decision was made, capture it now via `mcp__vfkb__kb_add` (type=decision, why=<rationale>, role=human) \u2014 or `vfkb add decision "\u2026" --why "\u2026" --role human` \u2014 and add an ADR under docs/adr/ for anything architectural. If NO decision was made this turn, just finish normally.';
 var HANDOFF_MIN_ENTRIES = 3;
 var HANDOFF_REMINDER = 'vfkb handoff check: this session has recorded knowledge but no `handoff`/`next` entry. If you are WRAPPING UP, record a durable handoff now \u2014 `mcp__vfkb__kb_add` (type=fact, tags=handoff,next, role=human) naming what the NEXT session should pick up (a real "next:", not just a summary). If you are still mid-session, ignore this and finish normally \u2014 the SessionEnd floor will leave a fallback if you never do.';
@@ -16448,7 +16482,7 @@ function hasUncommittedWork(cwd = process.cwd(), brain = brainDir()) {
   });
 }
 function newBrainEntriesSinceHead(brain = brainDir(), cwd = process.cwd()) {
-  const file2 = join9(brain, "entries.jsonl");
+  const file2 = join10(brain, "entries.jsonl");
   let current2;
   try {
     current2 = readFileSync8(file2, "utf8").split("\n").filter(Boolean);
@@ -16484,13 +16518,13 @@ function gatherStopContext(cwd = process.cwd(), brain = brainDir()) {
 
 // src/git.ts
 import { execFileSync as execFileSync4 } from "node:child_process";
-import { existsSync as existsSync7 } from "node:fs";
-import { join as join10 } from "node:path";
+import { existsSync as existsSync8 } from "node:fs";
+import { join as join11 } from "node:path";
 function git(args, cwd) {
   return execFileSync4("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
 }
 function ensureRepo(brain) {
-  if (!existsSync7(join10(brain, ".git"))) {
+  if (!existsSync8(join11(brain, ".git"))) {
     git(["init", "-q"], brain);
   }
 }
@@ -16518,10 +16552,10 @@ function save(message = "vfkb: update", role = "engine", brain = brainDir()) {
 // src/session-end.ts
 import { execFileSync as execFileSync5 } from "node:child_process";
 import { readFileSync as readFileSync9 } from "node:fs";
-import { join as join11, isAbsolute } from "node:path";
+import { join as join12, isAbsolute } from "node:path";
 var realGit = (args, cwd) => execFileSync5("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
 function brainEntriesRelPath(dataDir2) {
-  return join11(dataDir2, "entries.jsonl").replace(/\\/g, "/");
+  return join12(dataDir2, "entries.jsonl").replace(/\\/g, "/");
 }
 function tryGit(git2, args, cwd) {
   try {
@@ -16622,8 +16656,8 @@ function runSessionEnd(opts = {}) {
         systemMessage: `vfkb: ${added2} new brain entr${added2 === 1 ? "y" : "ies"} on \`${branch}\` left uncommitted \u2014 branch + commit to preserve continuity (vfkb never auto-commits the default branch).`
       };
     }
-    const absBrain = isAbsolute(dataDir2) ? dataDir2 : join11(cwd, dataDir2);
-    const fresh = newEntriesSinceHead(git2, cwd, entries, join11(absBrain, "entries.jsonl"));
+    const absBrain = isAbsolute(dataDir2) ? dataDir2 : join12(cwd, dataDir2);
+    const fresh = newEntriesSinceHead(git2, cwd, entries, join12(absBrain, "entries.jsonl"));
     let autoHandoff = false;
     if (fresh.length > 0 && !fresh.some(isHandoff2)) {
       try {
@@ -16643,8 +16677,8 @@ function runSessionEnd(opts = {}) {
 }
 
 // src/init.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync7, readFileSync as readFileSync10, writeFileSync as writeFileSync5 } from "node:fs";
-import { basename as basename3, join as join12 } from "node:path";
+import { existsSync as existsSync9, mkdirSync as mkdirSync7, readFileSync as readFileSync10, writeFileSync as writeFileSync5 } from "node:fs";
+import { basename as basename3, join as join13 } from "node:path";
 var AGENTS_MARKER = "<!-- vfkb:how-we-track-work -->";
 var BOOTSTRAP_REL = ".vfkb/bin/bootstrap.mjs";
 function mcpConfig(project) {
@@ -16720,8 +16754,9 @@ This repo uses **vfkb** as its knowledge substrate (project \`${project}\`). Kno
 - **Record knowledge** with the \`mcp__vfkb__kb_add\` tool (or \`node .vfkb/bin/bootstrap.mjs cli add \u2026\`):
   \`decision\`, \`fact\`, \`gotcha\`, \`pattern\`, \`link\` \u2014 put a decision's rationale in its text.
   **Capture load-bearing decisions immediately \u2014 don't defer.**
-- Only \`.vfkb/entries.jsonl\`, \`.vfkb/manifest.json\`, and \`.vfkb/bin/\` are committed;
-  \`.vfkb/index-meta.json\`, \`.sessions/\`, \`.signals/\` are derived/gitignored.
+- Committed: \`.vfkb/entries.jsonl\`, \`.vfkb/manifest.json\` (the ADR-0030 engine stamp \u2014
+  **never gitignore \`manifest.json\`**), and \`.vfkb/bin/\`. Derived/gitignored, all five:
+  \`.vfkb/index-meta.json\`, \`.vfkb/.sessions/\`, \`.vfkb/.signals/\`, \`.vfkb/.journal/\`, \`.vfkb/.lock\`.
 
 Two env vars: **\`VFKB_DATA_DIR\`** = this repo's brain (\`.vfkb\`, set by the wiring) \xB7 **\`VFKB_BUNDLE_DIR\`**
 = the shared vfkb engine bundles \u2014 set it once per machine, e.g. \`export VFKB_BUNDLE_DIR=/path/to/vfkb/dist/bundles\`.
@@ -16729,7 +16764,7 @@ If it is unset, a session-start banner tells you; run \`vfkb doctor\` to check.
 `;
 }
 function readJson(path) {
-  if (!existsSync8(path)) return void 0;
+  if (!existsSync9(path)) return void 0;
   try {
     return JSON.parse(readFileSync10(path, "utf8"));
   } catch {
@@ -16745,9 +16780,9 @@ function eventHasVfkb(arr2) {
 function initProject(root, opts = {}) {
   const project = opts.project || basename3(root) || "project";
   const changes = [];
-  const brainDir2 = join12(root, ".vfkb");
-  const entries = join12(brainDir2, "entries.jsonl");
-  if (!existsSync8(entries)) {
+  const brainDir2 = join13(root, ".vfkb");
+  const entries = join13(brainDir2, "entries.jsonl");
+  if (!existsSync9(entries)) {
     mkdirSync7(brainDir2, { recursive: true });
     writeFileSync5(entries, "");
     changes.push({ path: ".vfkb/entries.jsonl", action: "created" });
@@ -16756,9 +16791,9 @@ function initProject(root, opts = {}) {
   }
   changes.push({ path: ".vfkb/manifest.json", action: writeManifest(brainDir2) });
   {
-    const binDir = join12(brainDir2, "bin");
-    const path = join12(binDir, "bootstrap.mjs");
-    const existed = existsSync8(path);
+    const binDir = join13(brainDir2, "bin");
+    const path = join13(binDir, "bootstrap.mjs");
+    const existed = existsSync9(path);
     const same = existed && readFileSync10(path, "utf8") === BOOTSTRAP_SRC;
     if (same) {
       changes.push({ path: BOOTSTRAP_REL, action: "skipped" });
@@ -16769,8 +16804,8 @@ function initProject(root, opts = {}) {
     }
   }
   {
-    const path = join12(root, ".mcp.json");
-    const existed = existsSync8(path);
+    const path = join13(root, ".mcp.json");
+    const existed = existsSync9(path);
     const cfg = readJson(path) ?? {};
     cfg.mcpServers = cfg.mcpServers ?? {};
     const desired = mcpConfig(project);
@@ -16784,9 +16819,9 @@ function initProject(root, opts = {}) {
     }
   }
   {
-    const dir = join12(root, ".claude");
-    const path = join12(dir, "settings.json");
-    const existed = existsSync8(path);
+    const dir = join13(root, ".claude");
+    const path = join13(dir, "settings.json");
+    const existed = existsSync9(path);
     const cfg = readJson(path) ?? {};
     cfg.hooks = cfg.hooks ?? {};
     const want = settingsHooks(project);
@@ -16809,16 +16844,37 @@ function initProject(root, opts = {}) {
     }
   }
   {
-    const path = join12(root, ".gitignore");
-    const lines = [".vfkb/index-meta.json", ".vfkb/.sessions/", ".vfkb/.signals/", ".vfkb/.journal/"];
-    const existed = existsSync8(path);
+    const path = join13(root, ".gitignore");
+    const lines = [
+      ".vfkb/index-meta.json",
+      ".vfkb/.sessions/",
+      ".vfkb/.signals/",
+      ".vfkb/.journal/",
+      ".vfkb/.lock"
+    ];
+    const HEADER = [
+      "# vfkb \u2014 entries.jsonl + manifest.json (the ADR-0030 engine stamp) are committed;",
+      "# the vfkb paths below are derived/operational and stay out of git"
+    ];
+    const STALE_HEADER = /^#\s*vfkb\s*—\s*derived\/operational \(only \.vfkb\/entries\.jsonl is committed\)\s*$/;
+    const existed = existsSync9(path);
     const cur = existed ? readFileSync10(path, "utf8") : "";
-    const missing = lines.filter((l) => !cur.split(/\r?\n/).includes(l));
-    if (missing.length === 0) {
+    const curLines = cur.split(/\r?\n/);
+    const missing = lines.filter((l) => !curLines.includes(l));
+    const staleAt = curLines.findIndex((l) => STALE_HEADER.test(l));
+    if (missing.length === 0 && staleAt === -1) {
       changes.push({ path: ".gitignore", action: "skipped" });
+    } else if (staleAt !== -1) {
+      const out = [...curLines];
+      out.splice(staleAt, 1, ...HEADER);
+      let last = staleAt + HEADER.length - 1;
+      for (let i = last + 1; i < out.length && /^\.vfkb\//.test(out[i].trim()); i++) last = i;
+      out.splice(last + 1, 0, ...missing);
+      writeFileSync5(path, out.join("\n"));
+      changes.push({ path: ".gitignore", action: "updated" });
     } else {
       const prefix = cur && !cur.endsWith("\n") ? "\n" : "";
-      const block = `${prefix}${cur ? "\n" : ""}# vfkb \u2014 derived/operational (only .vfkb/entries.jsonl is committed)
+      const block = `${prefix}${cur ? "\n" : ""}${HEADER.join("\n")}
 ${missing.join("\n")}
 `;
       writeFileSync5(path, cur + block);
@@ -16826,9 +16882,9 @@ ${missing.join("\n")}
     }
   }
   {
-    const path = join12(root, ".gitattributes");
+    const path = join13(root, ".gitattributes");
     const line = ".vfkb/entries.jsonl merge=union";
-    const existed = existsSync8(path);
+    const existed = existsSync9(path);
     const cur = existed ? readFileSync10(path, "utf8") : "";
     if (cur.split(/\r?\n/).includes(line)) {
       changes.push({ path: ".gitattributes", action: "skipped" });
@@ -16842,8 +16898,8 @@ ${line}
     }
   }
   {
-    const path = join12(root, "AGENTS.md");
-    const existed = existsSync8(path);
+    const path = join13(root, "AGENTS.md");
+    const existed = existsSync9(path);
     const cur = existed ? readFileSync10(path, "utf8") : "";
     if (cur.includes(AGENTS_MARKER)) {
       changes.push({ path: "AGENTS.md", action: "skipped" });
@@ -16869,10 +16925,10 @@ function approvalNotice(project) {
 
 // src/doctor.ts
 import { execFileSync as execFileSync6 } from "node:child_process";
-import { existsSync as existsSync9, readFileSync as readFileSync11, writeFileSync as writeFileSync6, mkdirSync as mkdirSync8 } from "node:fs";
-import { join as join13, dirname as dirname5 } from "node:path";
+import { existsSync as existsSync10, readFileSync as readFileSync11, writeFileSync as writeFileSync6, mkdirSync as mkdirSync8, realpathSync } from "node:fs";
+import { join as join14, dirname as dirname6, relative as relative3, resolve as resolve4, isAbsolute as isAbsolute2 } from "node:path";
 function readJson2(path) {
-  if (!existsSync9(path)) return void 0;
+  if (!existsSync10(path)) return void 0;
   try {
     return JSON.parse(readFileSync11(path, "utf8"));
   } catch {
@@ -16907,16 +16963,16 @@ function detectPluginWiring(settings, root, pluginsFile) {
 }
 function claudeConfigDir(env) {
   if (env.CLAUDE_CONFIG_DIR) return env.CLAUDE_CONFIG_DIR;
-  return env.HOME ? join13(env.HOME, ".claude") : void 0;
+  return env.HOME ? join14(env.HOME, ".claude") : void 0;
 }
 function localHeadSha(cloneDir) {
-  const head = readFileMaybe(join13(cloneDir, ".git", "HEAD"));
+  const head = readFileMaybe(join14(cloneDir, ".git", "HEAD"));
   if (!head) return void 0;
   const ref = head.trim().match(/^ref:\s*(\S+)$/)?.[1];
   if (!ref) return /^[0-9a-f]{40}$/.test(head.trim()) ? head.trim() : void 0;
-  const loose = readFileMaybe(join13(cloneDir, ".git", ...ref.split("/")));
+  const loose = readFileMaybe(join14(cloneDir, ".git", ...ref.split("/")));
   if (loose) return loose.trim();
-  const packed = readFileMaybe(join13(cloneDir, ".git", "packed-refs"));
+  const packed = readFileMaybe(join14(cloneDir, ".git", "packed-refs"));
   for (const line of packed?.split("\n") ?? []) {
     const [sha, name] = line.trim().split(/\s+/);
     if (name === ref) return sha;
@@ -16939,14 +16995,14 @@ var realGit2 = (args, cwd) => execFileSync6("git", args, {
 });
 function checkCurrency(plugin, opts, configDir) {
   const marketplace = plugin.key.split("@")[1];
-  const kmFile = opts.knownMarketplacesFile ?? (configDir ? join13(configDir, "plugins", "known_marketplaces.json") : void 0);
+  const kmFile = opts.knownMarketplacesFile ?? (configDir ? join14(configDir, "plugins", "known_marketplaces.json") : void 0);
   const entry = kmFile ? readJson2(kmFile)?.[marketplace] : void 0;
   const skip = (detail) => ({ status: "skip", detail });
   if (!entry) return skip(`no marketplace "${marketplace}" in ${kmFile ?? "the plugin registry"} \u2014 cannot check currency`);
   if (entry.source?.source !== "github") {
     return skip(`marketplace "${marketplace}" is a ${entry.source?.source ?? "unknown"}-source \u2014 no clone to compare`);
   }
-  if (!entry.installLocation || !existsSync9(join13(entry.installLocation, ".git"))) {
+  if (!entry.installLocation || !existsSync10(join14(entry.installLocation, ".git"))) {
     return skip(`marketplace clone not found at ${entry.installLocation ?? "(unset installLocation)"}`);
   }
   const clone2 = entry.installLocation;
@@ -16977,7 +17033,7 @@ var NPM_REGISTRY_URL = "https://registry.npmjs.org/@viloforge%2Fvfkb/latest";
 var NPM_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 var NPM_CACHE_FILE = "npm-currency-cache.json";
 function npmCacheFilePath(opts) {
-  return opts.cacheFile ?? join13(opts.brainDir, ".signals", NPM_CACHE_FILE);
+  return opts.cacheFile ?? join14(opts.brainDir, ".signals", NPM_CACHE_FILE);
 }
 function readNpmCache(path) {
   const raw = readJson2(path);
@@ -16987,7 +17043,7 @@ function readNpmCache(path) {
 }
 function writeNpmCache(path, entry) {
   try {
-    mkdirSync8(dirname5(path), { recursive: true });
+    mkdirSync8(dirname6(path), { recursive: true });
     writeFileSync6(path, JSON.stringify(entry));
   } catch {
   }
@@ -17065,21 +17121,64 @@ async function checkNpmCurrency(opts) {
     clearTimeout(timer);
   }
 }
+var HOOK_SUBCOMMANDS = ["session-start", "pre-tool-use", "post-tool-use", "stop", "session-end"];
+function isEngineWiring(hookJson) {
+  const text = hookJson.replace(/\\[tnr]/g, " ").replace(/\\(.)/g, "$1");
+  if (/bootstrap\.mjs/.test(text)) return true;
+  return new RegExp(`\\bhook["'\\s]+(${HOOK_SUBCOMMANDS.join("|")})\\b`).test(text);
+}
+function engineDrift(manifestCommit, runningCommit) {
+  if (!manifestCommit || manifestCommit === "dev") return false;
+  if (!runningCommit || runningCommit === "dev") return false;
+  return manifestCommit !== runningCommit;
+}
+function repoToplevel(root) {
+  try {
+    return execFileSync6("git", ["-C", root, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return void 0;
+  }
+}
+function isUnder(parent, child) {
+  if (!parent) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return resolve4(p);
+    }
+  };
+  const rel = relative3(real(parent), real(child));
+  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+}
 function runDoctor(opts) {
   const { root, brainDir: brainDir2, env } = opts;
+  const runningCommit = opts.engineCommit ?? ENGINE_COMMIT;
   const checks = [];
   const add = (name, status, detail) => checks.push({ name, status, detail });
-  add("engine", "ok", `version ${ENGINE_VERSION} \xB7 commit ${ENGINE_COMMIT} \xB7 schema v${SCHEMA_VERSION}`);
-  const settings = readJson2(join13(root, ".claude", "settings.json"));
+  add("engine", "ok", `version ${ENGINE_VERSION} \xB7 commit ${runningCommit} \xB7 schema v${SCHEMA_VERSION}`);
+  const settings = readJson2(join14(root, ".claude", "settings.json"));
   const configDir = claudeConfigDir(env);
-  const pluginsFile = opts.pluginsFile ?? (configDir ? join13(configDir, "plugins", "installed_plugins.json") : void 0);
+  const pluginsFile = opts.pluginsFile ?? (configDir ? join14(configDir, "plugins", "installed_plugins.json") : void 0);
   const plugin = detectPluginWiring(settings, root, pluginsFile);
   const mf = readManifest(brainDir2);
   if (!mf) {
     add(
       "brain manifest",
       "warn",
-      plugin ? `no manifest.json in ${brainDir2} \u2014 it will be stamped on the next write` : `no manifest.json in ${brainDir2} \u2014 run \`vfkb init\` (or it will be stamped on next write)`
+      // #188 — the ordinary write path (addEntry → appendRecord → backend.append)
+      // never touches manifest.json. `writeManifest` has exactly two callers:
+      // `vfkb init` (init.ts) and the broadcast heal, which fires only when the
+      // manifest is ABSENT (broadcast.ts). Saying "on the next write" claimed
+      // behaviour the code does not have.
+      // On a PLUGIN-wired repo the message must not prescribe `vfkb init` — that
+      // advice is what scaffolds double wiring (issue #77), and the invariant is
+      // asserted in doctor.test.ts. A plugin-born brain simply has no manifest
+      // until a cross-repo broadcast heals it (vfkb#193).
+      plugin ? `no manifest.json in ${brainDir2} \u2014 plugin-born brains have none until a cross-repo broadcast heals it (vfkb#193); the ordinary write path never creates one` : `no manifest.json in ${brainDir2} \u2014 run \`vfkb init\` to stamp it (the ordinary write path never creates one)`
     );
   } else if (typeof mf.schema_version !== "number") {
     add("brain manifest", "warn", "manifest has no numeric schema_version");
@@ -17088,9 +17187,10 @@ function runDoctor(opts) {
   } else if (mf.schema_version < SCHEMA_VERSION) {
     add("brain\u2194engine compat", "warn", `brain schema v${mf.schema_version} is older than engine v${SCHEMA_VERSION} \u2014 migration may be needed`);
   } else {
-    add("brain\u2194engine compat", "ok", `schema v${mf.schema_version} matches`);
-    if (mf.engine_commit && ENGINE_COMMIT !== "dev" && mf.engine_commit !== ENGINE_COMMIT) {
-      add("engine drift", "warn", `brain last stamped by engine ${mf.engine_commit}, running ${ENGINE_COMMIT} \u2014 possible dual-clone drift`);
+    const sentinel = mf.engine_commit === "dev" ? ` \xB7 stamped by a build that did not know its own commit ("dev") \u2014 provenance unknown (#212)` : "";
+    add("brain\u2194engine compat", "ok", `schema v${mf.schema_version} matches${sentinel}`);
+    if (engineDrift(mf.engine_commit, runningCommit)) {
+      add("engine drift", "warn", `brain last stamped by engine ${mf.engine_commit}, running ${runningCommit} \u2014 possible dual-clone drift`);
     }
   }
   {
@@ -17110,9 +17210,9 @@ function runDoctor(opts) {
     } else {
       add("journal", "ok", `${js.walLines} line(s) in the uncommitted window, nothing to restore`);
     }
-    if (existsSync9(join13(brainDir2, ".journal"))) {
+    if (existsSync10(join14(brainDir2, ".journal")) && isUnder(repoToplevel(root), join14(brainDir2, ".journal"))) {
       try {
-        execFileSync6("git", ["-C", root, "check-ignore", "-q", join13(brainDir2, ".journal", "wal.jsonl")], {
+        execFileSync6("git", ["-C", root, "check-ignore", "-q", join14(brainDir2, ".journal", "wal.jsonl")], {
           stdio: "ignore"
         });
       } catch {
@@ -17135,7 +17235,7 @@ function runDoctor(opts) {
     } else {
       add("$VFKB_BUNDLE_DIR", "warn", "unset \u2014 set it once per machine to the vfkb bundles dir (so the wiring resolves the engine)");
     }
-  } else if (!existsSync9(join13(home, "vfkb.mjs")) || !existsSync9(join13(home, "vfkb-mcp.mjs"))) {
+  } else if (!existsSync10(join14(home, "vfkb.mjs")) || !existsSync10(join14(home, "vfkb-mcp.mjs"))) {
     add("$VFKB_BUNDLE_DIR", "warn", `set to ${home} but vfkb.mjs / vfkb-mcp.mjs not found there (run \`npm run build:bundles\`)`);
   } else {
     add("$VFKB_BUNDLE_DIR", "ok", home);
@@ -17146,7 +17246,7 @@ function runDoctor(opts) {
   if (env.VFKB_HOME && !env.VFKB_BUNDLE_DIR) {
     add("env (deprecated)", "warn", "VFKB_HOME is a deprecated alias \u2014 rename it to VFKB_BUNDLE_DIR");
   }
-  const mcp = readJson2(join13(root, ".mcp.json"));
+  const mcp = readJson2(join14(root, ".mcp.json"));
   const mcpProject = mcp?.mcpServers?.vfkb?.env?.VFKB_PROJECT;
   const mcpPresent = Boolean(mcp?.mcpServers?.vfkb);
   if (plugin && mcpPresent) {
@@ -17160,7 +17260,7 @@ function runDoctor(opts) {
   }
   const hooks = settings?.hooks ?? {};
   const expected = ["SessionStart", "PreToolUse", "Stop", "SessionEnd"];
-  const have = expected.filter((e) => JSON.stringify(hooks[e] ?? "").includes("vfkb"));
+  const have = expected.filter((e) => isEngineWiring(JSON.stringify(hooks[e] ?? "")));
   if (plugin && have.length > 0) {
     add(".claude/settings.json", "warn", `vfkb hooks present ALONGSIDE the plugin (double wiring) \u2014 remove them; the plugin's hooks are primary (ADR-0045)`);
   } else if (plugin) {
@@ -17176,7 +17276,7 @@ function runDoctor(opts) {
   if (!plugin && have.length > 0 && hooksBlob.includes("bootstrap.mjs") && !hooksBlob.includes("CLAUDE_PROJECT_DIR")) {
     add("hooks anchor", "warn", "vfkb hooks use a CWD-relative bootstrap path \u2014 they break when the session cd's out of the repo root; re-run `vfkb init` to anchor them to $CLAUDE_PROJECT_DIR (issue #22)");
   }
-  if (existsSync9(join13(root, ".vfkb", "bin", "bootstrap.mjs"))) {
+  if (existsSync10(join14(root, ".vfkb", "bin", "bootstrap.mjs"))) {
     add("bootstrap", "ok", ".vfkb/bin/bootstrap.mjs present");
   } else if (!plugin && (mcpPresent || have.length > 0)) {
     add("bootstrap", "warn", "wiring present but .vfkb/bin/bootstrap.mjs is missing \u2014 run `vfkb init`");
@@ -17216,9 +17316,9 @@ function renderDoctor(report) {
 }
 
 // src/import.ts
-import { existsSync as existsSync10, readdirSync as readdirSync3, readFileSync as readFileSync12, statSync as statSync3 } from "node:fs";
+import { existsSync as existsSync11, readdirSync as readdirSync3, readFileSync as readFileSync12, statSync as statSync3 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { basename as basename4, extname, join as join14 } from "node:path";
+import { basename as basename4, extname, join as join15 } from "node:path";
 var MYKB_FILES = {
   "decisions.jsonl": "decision",
   "facts.jsonl": "fact",
@@ -17243,15 +17343,15 @@ function mykbText(type, e) {
   return parts.filter(Boolean).join("\n\n");
 }
 function resolveMykbArea(nameOrDir) {
-  if (existsSync10(nameOrDir) && statSync3(nameOrDir).isDirectory()) return nameOrDir;
-  return join14(homedir2(), ".mykb", "areas", nameOrDir);
+  if (existsSync11(nameOrDir) && statSync3(nameOrDir).isDirectory()) return nameOrDir;
+  return join15(homedir2(), ".mykb", "areas", nameOrDir);
 }
 function fromMykb(areaDir) {
-  if (!existsSync10(areaDir)) throw new Error(`mykb area not found: ${areaDir}`);
+  if (!existsSync11(areaDir)) throw new Error(`mykb area not found: ${areaDir}`);
   const out = [];
   for (const [file2, type] of Object.entries(MYKB_FILES)) {
-    const path = join14(areaDir, file2);
-    if (!existsSync10(path)) continue;
+    const path = join15(areaDir, file2);
+    if (!existsSync11(path)) continue;
     for (const line of readFileSync12(path, "utf8").split(/\r?\n/)) {
       const trimmed = line.trim();
       if (!trimmed) continue;
@@ -17278,17 +17378,17 @@ function mdTitle(path) {
   return basename4(path, extname(path));
 }
 function fromAdr(dir = "docs/adr") {
-  if (!existsSync10(dir)) throw new Error(`ADR dir not found: ${dir}`);
+  if (!existsSync11(dir)) throw new Error(`ADR dir not found: ${dir}`);
   const out = [];
   for (const file2 of readdirSync3(dir).sort()) {
     if (extname(file2) !== ".md" || /readme/i.test(file2)) continue;
-    const rel = join14(dir, file2);
+    const rel = join15(dir, file2);
     out.push(stamp("link", `${mdTitle(rel)} \u2192 ${rel}`, ["adr"], false));
   }
   return out;
 }
 function fromMarkdown(file2) {
-  if (!existsSync10(file2)) throw new Error(`markdown file not found: ${file2}`);
+  if (!existsSync11(file2)) throw new Error(`markdown file not found: ${file2}`);
   return [stamp("link", `${mdTitle(file2)} \u2192 ${file2}`, ["doc"], false)];
 }
 
@@ -17368,25 +17468,35 @@ var DECISION_STATUSES = ["proposed", "accepted", "deprecated", "superseded"];
 
 // src/cli.ts
 import { readFileSync as readFileSync13 } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname as dirname6, join as join15 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { dirname as dirname7, join as join16 } from "node:path";
 function packageVersion() {
   try {
-    const here = dirname6(fileURLToPath(import.meta.url));
-    const pkg = JSON.parse(readFileSync13(join15(here, "..", "package.json"), "utf8"));
+    const here = dirname7(fileURLToPath2(import.meta.url));
+    const pkg = JSON.parse(readFileSync13(join16(here, "..", "package.json"), "utf8"));
     return pkg.version || ENGINE_VERSION;
   } catch {
     return ENGINE_VERSION;
   }
 }
+var STDIN_WATCHDOG_MS = 2e3;
 function readStdin() {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     let data = "";
-    if (process.stdin.isTTY) return resolve4("");
+    if (process.stdin.isTTY) return resolve5("");
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      process.stdin.pause();
+      process.stdin.unref?.();
+      resolve5(data);
+    };
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (c) => data += c);
-    process.stdin.on("end", () => resolve4(data));
-    setTimeout(() => resolve4(data), 2e3).unref?.();
+    process.stdin.on("end", finish);
+    process.stdin.on("error", finish);
+    setTimeout(finish, STDIN_WATCHDOG_MS).unref?.();
   });
 }
 function flag(args, name) {
@@ -17482,7 +17592,8 @@ async function dispatch() {
       let failed = 0;
       for (const r of results) {
         if (r.ok) {
-          process.stdout.write(`written	${r.target}	${r.id}	${r.posture}${r.healed ? "	(manifest healed \u2014 brain was wired but manifest-less, vfkb#193)" : ""}
+          const repair = r.healed ? "	(manifest healed \u2014 brain was wired but manifest-less, vfkb#193)" : r.upgraded ? '	(manifest provenance upgraded \u2014 engine identity was unknown ("dev"), now the running sha, vfkb#212)' : "";
+          process.stdout.write(`written	${r.target}	${r.id}	${r.posture}${repair}
 `);
         } else {
           failed++;