mindforge-cc 11.9.1 → 11.9.2

package/bin/dashboard/server.js

@@ -37,6 +37,7 @@ const SSE    = require('./sse-bridge');
 const API    = require('./api-router');
 const TemporalAPI = require('./temporal-api');
 const RevOpsAPI   = require('./revops-api');
+const { newCorrelationId } = require('./error-response');
 
 // ── Express app ───────────────────────────────────────────────────────────────
 const app = express();
@@ -190,6 +191,73 @@ app.post('/api/v1/token/refresh', requireAuth, (req, res) => {
 // ── Register API routes ───────────────────────────────────────────────────────
 API.register(app);
 app.use('/api/temporal', TemporalAPI);
+// RevOpsAPI was required at the top of this file but never mounted, so /api/revops
+// returned 404 while the AgRevOps dashboard panels and docs described it as live.
+app.use('/api/revops', RevOpsAPI);
+
+// ── Terminal error handler (LEAK-01) ─────────────────────────────────────────
+// MUST stay last, after every route, and MUST keep its 4-arg signature or express
+// will treat it as ordinary middleware. Without it, express's default handler
+// renders err.stack into the response body whenever NODE_ENV !== 'production':
+// a single unauthenticated malformed-JSON POST (express.json() is mounted BEFORE
+// requireAuth, and requireAuth exempts GET anyway) returned the absolute paths of
+// node_modules and the repo — the operator's username and home directory — to any
+// local caller. Log server-side; return a generic body plus a correlation id.
+app.use((err, req, res, next) => {
+  if (res.headersSent) return next(err); // e.g. an SSE stream already flushed headers
+  const status = Number.isInteger(err && err.status) && err.status >= 400 && err.status < 600
+    ? err.status
+    : 500;
+  const correlationId = newCorrelationId();
+  console.error(
+    `[dashboard] unhandled ${req.method} ${req.originalUrl} -> ${status} [cid=${correlationId}]:`,
+    err && err.stack ? err.stack : err
+  );
+  res.status(status).json({
+    error: status >= 500 ? 'Internal server error' : 'Invalid request',
+    correlation_id: correlationId
+  });
+});
+
+// ── Crash guards ──────────────────────────────────────────────────────────────
+// Both guards log and exit. That is deliberate and symmetric.
+//
+// unhandledRejection: an escaped rejection is the ONLY reliable signal that an
+// async call was left un-awaited — the ASYNC-01 class this release fixes. Measured
+// on v11.9.1: an un-awaited rollbackTo() rejected, and by the time the rejection
+// surfaced a hash-chained `hindsight_injected` entry had already been fsync'd and
+// auto-state.json flipped to awaiting_regeneration for a rollback that never
+// happened; the client got ECONNRESET at ~16ms and the process exited 1. The
+// durable damage is committed before any handler can run, so a 500-and-continue
+// response would answer the request while leaving the audit chain asserting an
+// event that did not occur.
+// Keeping it survivable is also not free: express 4.22.1 does not route async
+// handler rejections to its error middleware (measured: a 4-arity app.use never
+// fires), so log-and-continue leaves the client socket open until the CLIENT gives
+// up — 2.5s, 4s and 8s clients all timed out with no response — versus a ~15ms
+// connection reset when the process exits. A silent hang is worse than a restart.
+// Cost accepted: one faulting request takes the observability surface down. The
+// dashboard is a 127.0.0.1-only single-operator tool, and an audit chain that
+// verifies as valid while recording events that did not happen is not a survivable
+// state to keep serving from.
+process.on('unhandledRejection', (reason) => {
+  console.error('[Dashboard] Unhandled rejection — exiting:',
+    reason instanceof Error ? reason.stack : reason);
+  process.exit(1);
+});
+
+// uncaughtException MUST exit. After an uncaught throw the process state is
+// undefined, and log-and-continue actively broke shutdown: a throw anywhere in the
+// first half of shutdown() (SSE.stop(), or unlinking the token file) was swallowed,
+// so server.close() was never reached and the forced-exit timer was never armed.
+// The result was a dashboard that IGNORED SIGTERM while still serving the
+// token-authenticated mutation endpoints, with the bearer token left on disk and
+// still valid in memory — i.e. the operator's documented stop command silently
+// failed while reporting success. Only SIGKILL stopped it.
+process.on('uncaughtException', (err) => {
+  console.error('[Dashboard] Uncaught exception — exiting:', err && err.stack ? err.stack : err);
+  process.exit(1);
+});
 
 // ── Start SSE bridge ──────────────────────────────────────────────────────────
 SSE.start();
@@ -231,14 +299,26 @@ server.on('error', err => {
 // ── Graceful shutdown ─────────────────────────────────────────────────────────
 function shutdown(signal) {
   console.log(`\n[dashboard] ${signal} received — shutting down`);
-  SSE.stop();
-  // Remove sensitive token file on shutdown
-  if (fs.existsSync(TOKEN_FILE)) fs.unlinkSync(TOKEN_FILE);
+
+  // Arm the forced exit FIRST. Every step below can throw (permission drift on the
+  // token path, a read-only .mindforge, an SSE listener error), and if any of them
+  // does before this timer is set, the process would keep serving the authenticated
+  // mutation API after the operator asked it to stop.
+  const forced = setTimeout(() => process.exit(0), 3000);
+  forced.unref();
+
+  try { SSE.stop(); } catch (err) { console.error('[dashboard] SSE.stop failed:', err.message); }
+
+  // Destroying the bearer token is a security step, not housekeeping — never let it
+  // throw. rmSync with force tolerates a missing path and most permission cases.
+  try { fs.rmSync(TOKEN_FILE, { force: true }); } catch (err) {
+    console.error('[dashboard] could not remove token file:', err.message);
+  }
+
   server.close(() => {
-    if (fs.existsSync(PID_FILE)) fs.unlinkSync(PID_FILE);
+    try { fs.rmSync(PID_FILE, { force: true }); } catch { /* best effort */ }
     process.exit(0);
   });
-  setTimeout(() => process.exit(0), 3000);
 }
 
 process.on('SIGTERM', () => shutdown('SIGTERM'));

package/bin/dashboard/temporal-api.js

@@ -8,6 +8,7 @@ const express = require('express');
 const router = express.Router();
 const TemporalHub = require('../engine/temporal-hub');
 const HindsightInjector = require('../hindsight-injector');
+const { sendServerError } = require('./error-response');
 
 /**
  * GET /api/temporal/history
@@ -18,7 +19,7 @@ router.get('/history', (req, res) => {
     const history = TemporalHub.getHistory();
     res.json(history);
   } catch (err) {
-    res.status(500).json({ error: 'Failed to retrieve temporal history', detail: err.message });
+    sendServerError(res, 'GET /api/temporal/history', err, 'Failed to retrieve temporal history');
   }
 });
 
@@ -37,7 +38,7 @@ router.get('/snapshot/:auditId/:file', (req, res) => {
     
     res.send(content);
   } catch (err) {
-    res.status(500).json({ error: 'Failed to retrieve snapshot file', detail: err.message });
+    sendServerError(res, 'GET /api/temporal/snapshot/:auditId/:file', err, 'Failed to retrieve snapshot file');
   }
 });
 
@@ -52,7 +53,9 @@ router.get('/snapshot/:auditId/meta', (req, res) => {
     if (!snap) return res.status(404).json({ error: 'Snapshot not found' });
     res.json(snap);
   } catch (err) {
-    res.status(500).json({ error: 'Failed to retrieve snapshot metadata' });
+    // Previously swallowed the error entirely — no client detail, but no server log
+    // either, so a broken history dir was undiagnosable.
+    sendServerError(res, 'GET /api/temporal/snapshot/:auditId/meta', err, 'Failed to retrieve snapshot metadata');
   }
 });
 
@@ -72,10 +75,13 @@ router.post('/inject', async (req, res) => {
     if (result.success) {
       res.json(result);
     } else {
-      res.status(500).json(result);
+      // result.error is HindsightInjector's own `err.message` (hindsight-injector.js:59)
+      // and can be an fs error carrying an absolute path — never forward it verbatim.
+      sendServerError(res, 'POST /api/temporal/inject', result.error, 'Hindsight injection failed',
+        { success: false });
     }
   } catch (err) {
-    res.status(500).json({ error: 'Hindsight injection failed', detail: err.message });
+    sendServerError(res, 'POST /api/temporal/inject', err, 'Hindsight injection failed');
   }
 });
 

package/bin/engine/remediation-engine.js

@@ -109,7 +109,18 @@ class RemediationEngine {
       }
 
       await SemanticHub.ensureInit();
-      const goldenTraces = await SemanticHub.getGoldenTraces({ limit: 3 });
+      // SemanticHub.getGoldenTraces(skillFilter = null) takes a STRING filter,
+      // not an options object: `{ limit: 3 }` flowed straight through to
+      // vectorHub.searchTraces() as the query text. That used to stringify to
+      // "[object Object]" and silently search for that literal; FTS-01 makes a
+      // non-string query throw a TypeError, so the call shape is corrected here
+      // in the same change. The cap the old `{ limit: 3 }` intended is applied
+      // locally, because getGoldenTraces() has no limit parameter.
+      const GOLDEN_TRACE_LIMIT = 3;
+      const allGoldenTraces = await SemanticHub.getGoldenTraces();
+      const goldenTraces = Array.isArray(allGoldenTraces)
+        ? allGoldenTraces.slice(0, GOLDEN_TRACE_LIMIT)
+        : [];
 
       if (!goldenTraces || goldenTraces.length === 0) {
         return { strategy: 'GOLDEN_TRACE_INJECTION', result: 'no_traces_found' };

package/bin/engine/temporal-hub.js

@@ -32,12 +32,23 @@ class TemporalHub {
   }
 
   static _verifyMetadata(metadata) {
-    if (!metadata.integrity) return false;
+    if (!metadata || typeof metadata.integrity !== 'string') return false;
     const { integrity, ...rest } = metadata;
     const expected = crypto.createHmac('sha256', HMAC_KEY)
       .update(JSON.stringify(rest))
       .digest('hex');
-    return crypto.timingSafeEqual(Buffer.from(integrity), Buffer.from(expected));
+    // timingSafeEqual throws RangeError on unequal BYTE lengths. A String's `.length`
+    // counts UTF-16 code units, NOT bytes, so a 64-unit `integrity` containing any
+    // non-ASCII character is 65+ bytes and still produced unequal Buffers and still
+    // threw. Materialise both Buffers and compare their real byte lengths.
+    // NOTE: this is a CORRECTNESS fix, not a security guarantee — HMAC_KEY is a
+    // literal in shipped source, the HMAC covers only metadata and not snapshot file
+    // CONTENTS, and an absent SNAPSHOT-META.json still bypasses verification. This
+    // was never an authenticity control.
+    const actual = Buffer.from(integrity, 'utf8');
+    const expectedBuf = Buffer.from(expected, 'utf8');
+    if (actual.length !== expectedBuf.length) return false;
+    return crypto.timingSafeEqual(actual, expectedBuf);
   }
 
   /**
@@ -124,20 +135,41 @@ class TemporalHub {
     }
 
     const metaPath = path.join(snapshotDir, 'SNAPSHOT-META.json');
+    // Read and verify as two SEPARATE stages so only one specific, expected condition
+    // (the metadata file genuinely not existing) can reach the tolerant legacy path.
+    // The previous single try/catch sniffed err.message for 'integrity verification',
+    // so ANY other throw — a JSON.parse SyntaxError, or the crypto RangeError from a
+    // non-ASCII `integrity` — fell through to 'proceeding without integrity check' and
+    // restored the snapshot anyway. Unexpected throws must fail CLOSED.
+    //
+    // Error messages deliberately carry no err.message: JSON.parse embeds file content
+    // and fs errors embed absolute paths, and these strings reach an HTTP response via
+    // hindsight-injector -> temporal-api. Detail goes to the server log only.
+    let metaRaw = null;
     try {
-      const metaRaw = await fsPromises.readFile(metaPath, 'utf8');
-      const metaData = JSON.parse(metaRaw);
-      if (!TemporalHub._verifyMetadata(metaData)) {
-        throw new Error(`Snapshot ${auditId} failed integrity verification — metadata may be tampered.`);
-      }
+      metaRaw = await fsPromises.readFile(metaPath, 'utf8');
     } catch (err) {
-      if (err.message.includes('integrity verification') || err.message.includes('tampered')) {
-        throw err;
+      if (err.code !== 'ENOENT') {
+        console.error(`[temporal-hub] metadata read failed for ${auditId}:`, err);
+        throw new Error(`Snapshot ${auditId} metadata could not be read (${err.code || err.name}) — refusing to restore.`);
       }
       // Missing metadata file on legacy snapshots — allow rollback with warning
       console.warn(`[temporal-hub] No verifiable metadata for ${auditId}, proceeding without integrity check.`);
     }
 
+    if (metaRaw !== null) {
+      let verified = false;
+      try {
+        verified = TemporalHub._verifyMetadata(JSON.parse(metaRaw));
+      } catch (err) {
+        console.error(`[temporal-hub] metadata parse/verify failed for ${auditId}:`, err);
+        throw new Error(`Snapshot ${auditId} failed integrity verification — metadata unreadable or malformed (${err.name}).`);
+      }
+      if (!verified) {
+        throw new Error(`Snapshot ${auditId} failed integrity verification — metadata may be tampered.`);
+      }
+    }
+
     try {
       const allEntries = await fsPromises.readdir(snapshotDir);
       const files = allEntries.filter(f => f !== 'SNAPSHOT-META.json');

package/bin/eval/eval-harness.js

@@ -1,5 +1,16 @@
 'use strict';
 
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Repo root derived from THIS file's location, never from cwd.
+// bin/utils/paths.js resolves PROJECT_ROOT by walking up from process.cwd(),
+// which on a consumer install lands inside node_modules — the wrong root for a
+// corpus scan, and it would silently yield an empty corpus. __dirname is always
+// <root>/bin/eval.
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
 /**
  * Recall@K — fraction of relevant items found in the top-k retrieved results.
  * @param {string[]} retrieved - IDs in ranked order
@@ -79,4 +90,204 @@ async function runEval({ goldenSet, retriever, k }) {
   return { meanRecallAtK, meanNDCG, perQuery };
 }
 
-module.exports = { recallAtK, ndcg, runEval };
+// ── Corpus + runnable golden-set gate (FTS-01) ───────────────────────────────
+// Before this block the file had NO require.main guard, so the documented
+// command `node bin/eval/eval-harness.js --set golden-set-retrieval.json`
+// printed nothing and exited 0 — a gate that could not fail, and therefore not
+// a gate. golden-set-retrieval.json and this harness had zero callers.
+//
+// The shipped golden set names documents by BASENAME (`audit-hash`,
+// `model-router`, `stuck-detector`, …). Those ids exist nowhere in
+// .mindforge/celestial.db, so recall measured against the live trace DB is 0.00
+// by construction whatever the query builder does. The corpus the golden set
+// actually describes is the repo's own module/skill documentation — so build it,
+// index it into a THROWAWAY database under os.tmpdir(), and measure that.
+
+const CORPUS_ROOTS = [
+  { dir: 'bin', exts: ['.js'] },
+  { dir: '.mindforge/skills', exts: ['.md'] },
+  { dir: '.mindforge/engine', exts: ['.md'] },
+  { dir: '.agent/hooks', exts: ['.js'] },
+];
+const CORPUS_MAX_BYTES = 20000;
+const CORPUS_SKIP_DIRS = new Set(['node_modules', 'dist', 'coverage']);
+
+function _walk(dir, exts, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out; // a missing corpus root is reported via corpusSize, not a throw
+  }
+  for (const entry of entries) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!CORPUS_SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+        _walk(p, exts, out);
+      }
+    } else if (exts.includes(path.extname(entry.name))) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Doc id for a corpus file: its basename, except SKILL.md, which is keyed by its
+ * containing skill directory (that is the name the golden set uses).
+ * @param {string} file - absolute or relative file path
+ * @returns {string} document id
+ */
+function docIdForFile(file) {
+  const base = path.basename(file, path.extname(file));
+  return base === 'SKILL' ? path.basename(path.dirname(file)) : base;
+}
+
+/**
+ * Enumerate the document corpus the golden set's `relevant` ids refer to.
+ * @param {string} [root] - project root; defaults to REPO_ROOT
+ * @returns {Map<string, {id: string, file: string, content: string}>}
+ */
+function buildDocCorpus(root = REPO_ROOT) {
+  const corpus = new Map();
+  for (const { dir, exts } of CORPUS_ROOTS) {
+    for (const file of _walk(path.join(root, dir), exts, [])) {
+      const id = docIdForFile(file);
+      if (corpus.has(id)) continue; // first wins; basename collisions are rare
+      let text = '';
+      try {
+        text = fs.readFileSync(file, 'utf8').slice(0, CORPUS_MAX_BYTES);
+      } catch {
+        continue;
+      }
+      const rel = path.relative(root, file);
+      corpus.set(id, { id, file: rel, content: `${id} ${rel}\n${text}` });
+    }
+  }
+  return corpus;
+}
+
+/**
+ * Index the doc corpus into a throwaway VectorHub and score the golden set.
+ * NEVER touches .mindforge/celestial.db — the database lives in os.tmpdir() and
+ * is deleted again before this resolves.
+ * @param {Object} [opts]
+ * @param {string} [opts.goldenSetPath] - defaults to ./golden-set-retrieval.json
+ * @param {string} [opts.root] - corpus root; defaults to REPO_ROOT
+ * @param {number} [opts.k] - cutoff; defaults to 10
+ * @returns {Promise<Object>} runEval metrics plus corpus/coverage diagnostics
+ */
+async function runGoldenSetEval(opts = {}) {
+  const goldenSetPath = opts.goldenSetPath || path.join(__dirname, 'golden-set-retrieval.json');
+  const root = opts.root || REPO_ROOT;
+  const k = opts.k || 10;
+
+  const golden = JSON.parse(fs.readFileSync(goldenSetPath, 'utf8'));
+  const goldenSet = golden.queries || [];
+  const corpus = buildDocCorpus(root);
+
+  const relevantIds = [...new Set(goldenSet.flatMap(q => q.relevant || []))];
+  const unresolved = relevantIds.filter(id => !corpus.has(id));
+
+  const { VectorHub } = require('../memory/vector-hub');
+  const dbDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mindforge-eval-'));
+  const hub = new VectorHub(path.join(dbDir, 'eval-corpus.db'));
+  await hub.init();
+  try {
+    // The hub is throwaway, so raise the autosave batch size: the default of 10
+    // exports the whole growing database to disk every 10 documents, which turns
+    // a 0.5 s index build into a quadratic one for no durability benefit here.
+    hub._batchSize = Number.MAX_SAFE_INTEGER;
+    for (const doc of corpus.values()) {
+      await hub.saveKnowledge({ id: doc.id, type: 'doc', content: doc.content, source: doc.file });
+    }
+    const retriever = async (query) =>
+      (await hub.searchKnowledge(query, { limit: k })).map(r => r.id);
+    const metrics = await runEval({ goldenSet, retriever, k });
+    return {
+      ...metrics,
+      k,
+      corpusSize: corpus.size,
+      relevantIdCount: relevantIds.length,
+      unresolvedRelevantIds: unresolved,
+      baseline: golden.baseline || null,
+    };
+  } finally {
+    await hub.close();
+    fs.rmSync(dbDir, { recursive: true, force: true });
+  }
+}
+
+module.exports = {
+  recallAtK,
+  ndcg,
+  runEval,
+  buildDocCorpus,
+  docIdForFile,
+  runGoldenSetEval,
+};
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+// node bin/eval/eval-harness.js [--set golden-set-retrieval.json] [--k 10]
+//                               [--min-recall 0.55] [--json]
+// Exits 1 when mean recall@k is below --min-recall, or when any golden
+// `relevant` id no longer resolves to a real document (golden-set drift).
+// `npm run eval:retrieval` runs this with the committed baseline floor.
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const flag = (name, fallback) => {
+    const i = argv.indexOf(name);
+    return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : fallback;
+  };
+  const setArg = flag('--set', 'golden-set-retrieval.json');
+  const goldenSetPath = path.isAbsolute(setArg)
+    ? setArg
+    : path.join(__dirname, path.basename(setArg));
+  const num = (name, fallback) => {
+    const raw = flag(name, String(fallback));
+    const n = Number(raw);
+    // Fail closed: an unparseable threshold must never silently become 0.
+    if (!Number.isFinite(n) || n < 0) {
+      console.error(`[eval] ERROR: ${name} must be a non-negative number, got ${JSON.stringify(raw)}`);
+      process.exit(1);
+    }
+    return n;
+  };
+  const k = Math.max(1, Math.trunc(num('--k', 10)));
+  const minRecall = num('--min-recall', 0);
+
+  runGoldenSetEval({ goldenSetPath, k })
+    .then((res) => {
+      if (argv.includes('--json')) {
+        console.log(JSON.stringify(res, null, 2));
+      } else {
+        console.log(`[eval] corpus: ${res.corpusSize} docs · golden queries: ${res.perQuery.length} · k=${res.k}`);
+        for (const q of res.perQuery) {
+          console.log(`  recall=${q.recall.toFixed(3)} nDCG=${q.ndcg.toFixed(3)} hits=${q.retrieved.length}  ${q.query}`);
+        }
+        console.log(`[eval] mean recall@${res.k} = ${res.meanRecallAtK.toFixed(4)}`);
+        console.log(`[eval] mean nDCG@${res.k}   = ${res.meanNDCG.toFixed(4)}`);
+        if (res.baseline && typeof res.baseline.meanRecallAtK === 'number') {
+          // Round BEFORE choosing the sign, so a difference smaller than the
+          // printed precision reads as +0.0000 rather than a bogus -0.0000.
+          const delta = Number((res.meanRecallAtK - res.baseline.meanRecallAtK).toFixed(4));
+          console.log(`[eval] committed baseline recall@${res.baseline.k || res.k} = ${res.baseline.meanRecallAtK.toFixed(4)} (delta ${delta >= 0 ? '+' : ''}${delta.toFixed(4)})`);
+        }
+      }
+      if (res.unresolvedRelevantIds.length > 0) {
+        console.error(`[eval] FAIL: ${res.unresolvedRelevantIds.length} golden id(s) no longer resolve to a document: ${res.unresolvedRelevantIds.join(', ')}`);
+        process.exit(1);
+      }
+      if (res.meanRecallAtK < minRecall) {
+        console.error(`[eval] FAIL: mean recall@${res.k} ${res.meanRecallAtK.toFixed(4)} < --min-recall ${minRecall}`);
+        process.exit(1);
+      }
+    })
+    .catch((err) => {
+      // sql.js throws bare strings for some binding errors, so an Error-shaped
+      // formatter alone would print "undefined" and hide the real failure.
+      const detail = (err && (err.stack || err.message)) || String(err);
+      console.error(`[eval] ERROR: ${detail}`);
+      process.exit(1);
+    });
+}

package/bin/eval/golden-set-retrieval.json

@@ -1,6 +1,15 @@
 {
   "description": "Golden set for retrieval quality evaluation. Each entry has a natural-language query and the IDs of documents that SHOULD be retrieved.",
   "version": "1.0.0",
+  "baseline": {
+    "note": "Committed measurement so a retrieval regression is detectable. Reproduce with `npm run eval:retrieval`. Corpus = repo docs enumerated by buildDocCorpus() in bin/eval/eval-harness.js; retriever = VectorHub.searchKnowledge (OR-joined terms, ranked by tf-idf over FTS4 matchinfo('pcnx')). Before FTS-01 both figures were 0.0000 because the whole query was one FTS phrase.",
+    "k": 10,
+    "meanRecallAtK": 0.6417,
+    "meanNDCG": 0.5698,
+    "corpusSize": 517,
+    "gateMinRecall": 0.55,
+    "measuredOn": "v11.9.2 (fix/v11.9.2-ship-blockers), sql.js 1.14.1 / SQLite 3.49.1"
+  },
   "queries": [
     {
       "query": "how does the audit hash chain work",

package/bin/governance/policy-engine.js

@@ -165,6 +165,12 @@ class PolicyEngine {
   }
 
   logAudit(intent, impactScore, verdict) {
+    // LOCK-01: AuditWriter.write -> appendAuditEntrySync now takes a FAIL-CLOSED lock,
+    // so this can reject under contention. It is intentionally not awaited (the verdict
+    // path is synchronous), so catch here — otherwise the rejection escapes to a global
+    // unhandledRejection handler and the lost audit record is invisible at this site.
+    // The verdict is still returned: promoting an audit-write failure to an implicit
+    // DENY is a behaviour change for v12, not a patch.
     this._auditWriter.write({
       timestamp: new Date().toISOString(),
       requestId: verdict.requestId,
@@ -175,6 +181,8 @@ class PolicyEngine {
       impactScore,
       verdict: verdict.verdict,
       reason: verdict.reason
+    }).catch(err => {
+      console.error(`[APO-AUDIT-FAIL] [${verdict.requestId}] RISK-AUDIT append failed — decision NOT recorded: ${err.message}`);
     });
   }
 

package/bin/hindsight-injector.js

@@ -18,8 +18,14 @@ class HindsightInjector {
     console.log(`[hindsight] Injecting fix at ${auditId}: "${fixDescription}"`);
 
     try {
-      // 1. Rollback .planning directory
-      TemporalHub.rollbackTo(auditId);
+      // 1. Rollback .planning directory.
+      //    MUST be awaited: rollbackTo is async (engine/temporal-hub.js), so without
+      //    await its rejection escapes this try/catch entirely, the process dies on an
+      //    unhandled rejection, AND execution still falls through to steps 2-3 — which
+      //    fsync a hash-chained `hindsight_injected` entry and flip auto-state.json for
+      //    a rollback that never happened. The chain then verifies as valid but records
+      //    an event that did not occur.
+      await TemporalHub.rollbackTo(auditId);
 
       // 2. Append the "Hindsight" event to AUDIT.jsonl via the unified, hash-chained,
       //    durable append (UC-04b) so this entry links into the single verifiable chain.

package/bin/hooks/instinct-capture-hook.js

@@ -189,7 +189,13 @@ function main() {
     if (!fs.existsSync(storeDir)) {
       fs.mkdirSync(storeDir, { recursive: true });
     }
-    fs.appendFileSync(storePath, JSON.stringify(entry) + '\n');
+    // LOCK-01: instinct-cli's prune/import does read-modify-atomic-rename under this
+    // same lock, so an unlocked append here can be clobbered by that rename. Low
+    // maxTries because this is a hook fast path — the catch below keeps it non-fatal.
+    const { withFileLock } = require('../utils/file-lock');
+    withFileLock(storePath, () => {
+      fs.appendFileSync(storePath, JSON.stringify(entry) + '\n');
+    }, { maxTries: 10, label: 'instinct-store' });
     incrementSessionCount();
   } catch {
     // Non-fatal — hooks must not block

package/bin/learning/instinct-cli.js

@@ -24,6 +24,7 @@ const path = require('path');
 
 const guard = require('./lib/ssrf-guard');
 const { detectProject } = require('../hooks/lib/detect-project');
+const { withFileLock } = require('../utils/file-lock');
 
 const CONFIG_PATH = path.join(process.cwd(), '.mindforge', 'config.json');
 
@@ -71,33 +72,15 @@ function writeStoreAtomic(p, entries) {
 }
 
 /**
- * Advisory lock (Node has no fcntl): exclusive lockfile create, spin-with-timeout,
- * stale-break after 10s by mtime. Runs fn() while held, releases in finally.
+ * Advisory lock — now a thin delegate to the shared fail-closed lock (LOCK-01).
+ * The implementation moved to bin/utils/file-lock.js so the audit chain and the
+ * knowledge graph use the SAME lock semantics as the instinct store. Behaviour is
+ * unchanged: O_EXCL create, 50 tries, ~20ms waits, 10s stale reclaim, unlink in
+ * finally, THROW (never write anyway) when unacquirable — same error text.
  * Read the store INSIDE this so a prune/import rewrite can't race a hook append.
  */
 function withStoreLock(p, fn) {
-  const lock = `${p}.lock`;
-  const maxTries = 50, waitMs = 20, staleMs = 10000;
-  let held = false;
-  for (let i = 0; i < maxTries && !held; i++) {
-    try {
-      const fd = fs.openSync(lock, 'wx');
-      fs.closeSync(fd);
-      held = true;
-    } catch (err) {
-      if (err.code !== 'EEXIST') throw err;
-      // stale-break: if the lockfile is older than staleMs, remove it.
-      try {
-        const age = Date.now() - fs.statSync(lock).mtimeMs;
-        if (age > staleMs) { fs.unlinkSync(lock); continue; }
-      } catch { /* lock vanished — retry */ }
-      const until = Date.now() + waitMs;
-      while (Date.now() < until) { /* busy-wait (short) */ }
-    }
-  }
-  if (!held) throw new Error(`could not acquire instinct-store lock: ${lock}`);
-  try { return fn(); }
-  finally { try { fs.unlinkSync(lock); } catch { /* already gone */ } }
+  return withFileLock(p, fn, { label: 'instinct-store' });
 }
 
 function currentProjectId() {

package/bin/memory/knowledge-capture.js

@@ -133,7 +133,14 @@ function createCausalEdges(bugId, allEntries, vectors) {
           weight: sim,
           reason: `Bug pattern potentially caused by code pattern (sim: ${sim.toFixed(3)})`,
         });
-      } catch { /* skip duplicates or self-refs */ }
+      } catch (err) {
+        // LOCK-01: this catch predates the graph-edges lock. Without the guard below,
+        // an edge LOST to lock contention is reported as a skipped duplicate — a
+        // silent write loss wearing the label of a no-op.
+        if (/could not acquire/.test(err.message)) {
+          console.warn(`[KnowledgeCapture] edge NOT written — graph-edges lock unavailable: ${err.message}`);
+        }
+      }
     }
   }
 }
@@ -165,7 +172,14 @@ function createInformsEdges(decisionId, allEntries, vectors) {
           weight: sim,
           reason: `Decision informs domain knowledge (sim: ${sim.toFixed(3)})`,
         });
-      } catch { /* skip duplicates or self-refs */ }
+      } catch (err) {
+        // LOCK-01: this catch predates the graph-edges lock. Without the guard below,
+        // an edge LOST to lock contention is reported as a skipped duplicate — a
+        // silent write loss wearing the label of a no-op.
+        if (/could not acquire/.test(err.message)) {
+          console.warn(`[KnowledgeCapture] edge NOT written — graph-edges lock unavailable: ${err.message}`);
+        }
+      }
     }
   }
 }
@@ -180,7 +194,13 @@ function reinforceRelatedEdges(nodeId) {
     for (const edge of edges.slice(0, 3)) { // Top 3 edges only
       Graph.reinforceEdge(edge.id);
     }
-  } catch { /* non-critical */ }
+  } catch (err) {
+    // LOCK-01: reinforceEdge now takes the graph-edges lock, so "non-critical" would
+    // also absorb a contention failure. Surface that one; keep the rest quiet.
+    if (/could not acquire/.test(err.message)) {
+      console.warn(`[KnowledgeCapture] reinforcement NOT recorded — graph-edges lock unavailable: ${err.message}`);
+    }
+  }
 }
 
 // ── Event-specific capture functions ─────────────────────────────────────────