mindforge-cc 11.9.1 → 11.9.3

package/bin/dashboard/server.js

@@ -5,7 +5,7 @@
  *
  * Usage:
  *   node bin/dashboard/server.js [--port 7339] [--open]
- *   /mindforge:dashboard [--port 7339] [--open] [--stop]
+ *   /mindforge:dashboard [--port 7339] [--open] [--stop] [--status]
  *
  * Security: binds to 127.0.0.1 only (ADR-017 policy).
  * Bearer token auth on all mutating endpoints (POST/PUT/DELETE).
@@ -22,6 +22,143 @@ const ARGS   = process.argv.slice(2);
 const PORT     = parseInt(ARGS.find((_, i, a) => a[i-1] === '--port') || '7339', 10);
 const OPEN_BROWSER = ARGS.includes('--open');
 const PID_FILE = path.join(process.cwd(), '.planning', 'dashboard-server.pid');
+
+// ── Lifecycle flags: --status and --stop ──────────────────────────────────────
+//
+// THE DEFECT. `--stop` and `--status` were documented in four places and implemented in none. The
+// shipped slash command `.claude/commands/mindforge/dashboard.md` listed both in its Usage line and
+// gave each a worked example; docs/user-guide.md documented a `--start` that never existed either.
+// Worst of all, THIS FILE told the operator to run one of them: on EADDRINUSE it printed
+// "[dashboard] Stop it: /mindforge:dashboard --stop". Only `--port` and `--open` were ever parsed,
+// so every one of those instructions did nothing but start a second server.
+//
+// They are implemented rather than deleted because the PID file below already exists to support
+// them — it is written on listen and removed on shutdown, so the information was there all along.
+//
+// This runs BEFORE express is required, deliberately. This module has no `require.main` guard and
+// starts a server as a side effect of loading, so a lifecycle flag has to be handled and exited
+// here or `--stop` would stop the old server and start a new one. It also means `--status` works
+// when express is not installed, which is exactly when an operator is most likely to ask.
+if (ARGS.includes('--status') || ARGS.includes('--stop')) {
+  const { execFileSync } = require('child_process');
+
+  /** Read the recorded pid, or null when there is no usable PID file. */
+  const readPid = () => {
+    try {
+      const pid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
+      return Number.isInteger(pid) && pid > 0 ? pid : null;
+    } catch { return null; }
+  };
+
+  /** Signal 0 tests for existence and permission without delivering anything. */
+  const isAlive = (pid) => {
+    try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+  };
+
+  /**
+   * Confirm the pid is THIS dashboard before signalling it.
+   *
+   * A PID file is not proof: the recorded process can exit without cleanup (a SIGKILL, a power
+   * loss) and the operating system will reuse the number. Sending SIGTERM on the strength of a
+   * stale file means killing an unrelated process the operator never asked about — so identity is
+   * verified from the process table and, when it cannot be verified, this REFUSES. That is the same
+   * choice the audit writer and the vector-hub conflict path make: declining loudly beats acting on
+   * a guess.
+   *
+   * Returns the command line on success, or null when identity could not be established.
+   */
+  const identify = (pid) => {
+    if (process.platform === 'win32') return null;      // no ps; --stop refuses below
+    try {
+      const cmd = execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' }).trim();
+
+      // IDENTITY, not shape. Two earlier versions of this check were both too loose, and the second
+      // was the more dangerous:
+      //
+      //   /dashboard[/\\]server\.js/                       matched any process whose command line
+      //                                                    MENTIONED the path — a shell running a
+      //                                                    script that referenced it got a SIGTERM
+      //   /^\S*node...\S*dashboard[/\\]server\.js(\s|$)/   matched any `node <anything>/dashboard/
+      //                                                    server.js`. `dashboard/server.js` is an
+      //                                                    utterly ordinary path: this would have
+      //                                                    signalled an UNRELATED app's dashboard
+      //                                                    (verified against
+      //                                                    `node /var/www/unrelated_app/dashboard/server.js`)
+      //
+      // Anchoring made the first mistake unreachable and left a worse one, because both were asking
+      // "does this look like a dashboard server" when the only safe question is "is this THE one I am".
+      // So the script argument is resolved and compared against this file's own realpath.
+      //
+      // A relative script path cannot be resolved from here — it would need the target process's cwd,
+      // which ps does not give us — so that case REFUSES rather than guessing. Same choice as
+      // commitDb's conflict path: declining loudly beats acting on a guess, and the cost of being
+      // wrong here is someone else's process dying.
+      const m = /^\S*node(?:\.exe)?\s+(\S+)/.exec(cmd);
+      if (!m) return null;
+      const script = m[1];
+      if (!path.isAbsolute(script)) return null;        // unresolvable without the target's cwd
+      let resolved;
+      let self;
+      try {
+        resolved = fs.realpathSync(script);
+        self = fs.realpathSync(__filename);
+      } catch { return null; }                          // script gone, or unreadable — refuse
+      return resolved === self ? cmd : null;
+    } catch { return null; }
+  };
+
+  const pid = readPid();
+  const alive = pid !== null && isAlive(pid);
+
+  if (ARGS.includes('--status')) {
+    if (!alive) {
+      console.log(pid === null
+        ? '[dashboard] not running (no PID file)'
+        : `[dashboard] not running (stale PID file records ${pid})`);
+      process.exit(1);
+    }
+    const cmd = identify(pid);
+    // No port claimed. PORT here is whatever THIS invocation was told, not what the running
+    // process bound — measured, `--status` on a server started with --port 7466 printed "port 7339",
+    // the default this process happened to receive. The PID file records only the pid, so the port is
+    // not knowable from here, and stating a number we cannot know is the defect this file is full of
+    // fixes for.
+    console.log(`[dashboard] running — pid ${pid}`);
+    if (!cmd && process.platform !== 'win32') {
+      console.log(`[dashboard] warning: pid ${pid} is alive but does not look like this server, so `
+        + 'the PID file may be stale and the number reused');
+    }
+    process.exit(0);
+  }
+
+  // --stop
+  if (!alive) {
+    console.error(pid === null
+      ? '[dashboard] nothing to stop (no PID file)'
+      : `[dashboard] nothing to stop (stale PID file records ${pid})`);
+    if (pid !== null) { try { fs.rmSync(PID_FILE, { force: true }); } catch { /* best effort */ } }
+    process.exit(1);
+  }
+  if (process.platform === 'win32') {
+    console.error(`[dashboard] REFUSING to stop pid ${pid}: process identity cannot be verified on `
+      + 'this platform. Stop the server with CTRL+C in its own terminal.');
+    process.exit(1);
+  }
+  if (!identify(pid)) {
+    console.error(`[dashboard] REFUSING to stop pid ${pid}: it is running, but is not this `
+      + 'dashboard. The PID file is stale and the number has been reused — signalling it would kill '
+      + `an unrelated process. Delete ${PID_FILE} if you are sure it is obsolete.`);
+    process.exit(1);
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+    console.log(`[dashboard] SIGTERM sent to pid ${pid}`);
+    process.exit(0);
+  } catch (err) {
+    console.error(`[dashboard] could not stop pid ${pid}: ${err.message}`);
+    process.exit(1);
+  }
+}
 const FRONTEND = path.join(__dirname, 'frontend', 'index.html');
 
 // ── Load dependencies gracefully ──────────────────────────────────────────────
@@ -37,6 +174,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();
@@ -178,6 +316,28 @@ app.get('/', (req, res) => {
   res.sendFile(FRONTEND);
 });
 
+// The application itself, as an EXTERNAL script. It used to be an inline <script> in index.html,
+// which this server's own CSP (`script-src 'self'`, set above) blocks — so the whole front end never
+// executed while the static shell displayed "● Connected". Measured in a headless browser:
+// "Executing inline script violates ... 'script-src 'self''. The action has been blocked.",
+// typeof window.showPage === undefined, and GET /api/connections === {"clients":0}.
+//
+// Serving it from the same origin satisfies the existing policy WITHOUT weakening it — no
+// 'unsafe-inline', no hash, no nonce. An explicit route rather than express.static: the frontend
+// directory is the only thing that should be reachable, and a static mount would expose whatever else
+// lands there later.
+const FRONTEND_ASSETS = new Set(['app.js']);
+app.get('/:asset', (req, res, next) => {
+  if (!FRONTEND_ASSETS.has(req.params.asset)) return next();
+  const file = path.join(path.dirname(FRONTEND), req.params.asset);
+  // Defence in depth: the allowlist already forbids traversal, but resolve and re-check anyway so a
+  // future edit to FRONTEND_ASSETS cannot turn this into a file-read primitive.
+  if (path.dirname(path.resolve(file)) !== path.dirname(path.resolve(FRONTEND))) return next();
+  if (!fs.existsSync(file)) return res.status(404).send('// asset not found');
+  res.type('application/javascript');
+  return res.sendFile(file);
+});
+
 // ── Token refresh endpoint (requires valid existing token) ───────────────────
 app.post('/api/v1/token/refresh', requireAuth, (req, res) => {
   const newToken = crypto.randomBytes(32).toString('hex');
@@ -190,6 +350,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 +458,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/sse-bridge.js

@@ -136,21 +136,24 @@ function pollApprovals() {
     if (mtime === _lastMtimes[APPROVAL_DIR]) return; // unchanged
     _lastMtimes[APPROVAL_DIR] = mtime;
 
+    // Reads `approval-*.json`, the name the only producer (bin/governance/approve.js) actually
+    // writes. The old filter was startsWith('APPROVAL-'), which matched nothing on any platform:
+    // String.prototype.startsWith is case-sensitive regardless of the filesystem, so macOS's
+    // case-insensitive lookup (which affects fs.open, not this comparison) did not save it.
     const files  = fs.readdirSync(APPROVAL_DIR)
-      .filter(f => f.startsWith('APPROVAL-') && f.endsWith('.json'))
+      .filter(f => f.endsWith('.json'))
       .sort();
     const key = files.join(',');
     if (key === _lastApprovals) return;
     _lastApprovals = key;
 
-    // Find new pending approvals
+    // Announce records as they appear. The previous condition was `data.status === 'pending'`, a
+    // field no producer has ever written, so this loop could never broadcast. There is no
+    // pending-request concept to restore either — approve.js records an already-made decision.
+    // Only the filename is sent; a listener that wants contents calls GET /api/approvals, which
+    // returns each record with its verified integrity state.
     for (const f of files) {
-      try {
-        const data = JSON.parse(fs.readFileSync(path.join(APPROVAL_DIR, f), 'utf8'));
-        if (data.status === 'pending') {
-          broadcast('approval:new', data);
-        }
-      } catch { /* skip */ }
+      broadcast('approval:new', { file: f });
     }
   } catch { /* ignore */ }
 }

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/sre-manager.js

@@ -69,7 +69,7 @@ class SREManager {
       return { status: 'PLAINTEXT', content: thoughtChain };
     }
 
-    // v5 Pillar VI: Merkle-style Cumulative Hash Chain
+    // v5 Pillar VI: cumulative SHA-256 hash chain (linear back-links, no hash tree)
     const enclaveData = this.activeEnclaves.get(enclaveId);
     const prevHash = enclaveData.cumulativeHash;
     const digest = crypto.createHash('sha256').update(thoughtChain).digest('hex');

package/bin/engine/temporal-cli.js

@@ -22,17 +22,67 @@ async function main() {
       break;
     }
 
-    case 'cleanup':
-      console.log('🧹 Cleaning up old temporal snapshots...');
-      // Logic for cleanup (e.g., keep last 100)
-      console.log('✅ Cleanup complete.');
+    // WAS TWO console.log CALLS AROUND A COMMENT. Verbatim:
+    //
+    //     console.log('🧹 Cleaning up old temporal snapshots...');
+    //     // Logic for cleanup (e.g., keep last 100)
+    //     console.log('✅ Cleanup complete.');
+    //
+    // It printed "✅ Cleanup complete." and deleted nothing, on every invocation, while
+    // `.planning/history/` grew without bound. The collector it should have called has existed all
+    // along — TemporalHub.gc, which auto-runner.js:702 and the 10.7.0 migration already use.
+    //
+    // DEFAULTS MATCH THE EXISTING CALLERS, not gc's own fallback. gc defaults maxAgeDays to 7; the
+    // migration passes 30. Seven days would make a first interactive run delete far more than an
+    // operator expects from a command that has never deleted anything, so 30 is used here.
+    //
+    // gc is bounded to `<cwd>/.planning/history/` and only ever removes DIRECTORIES directly inside
+    // it, returning early when that path does not exist. That matters now that the router runs
+    // children in the CALLER's directory: the blast radius is the caller's own snapshots, which is
+    // what a cleanup verb is for. It is still a recursive delete, so --dry-run reports the plan
+    // without touching anything.
+    case 'cleanup': {
+      const dryRun = ARGS.includes('--dry-run');
+      const before = TemporalHub.getHistory().length;
+
+      if (dryRun) {
+        // Recomputed here rather than by calling gc, because gc has no preview mode and adding one
+        // would mean a second code path that could drift from the one that deletes.
+        console.log('\n🧹  Temporal cleanup — DRY RUN, nothing will be deleted');
+        console.log(`    Snapshots now:   ${before}`);
+        console.log('    Policy:          keep newest 50, drop anything older than 30 days');
+        console.log('    Run without --dry-run to apply.\n');
+        break;
+      }
+
+      const result = await TemporalHub.gc({ maxSnapshots: 50, maxAgeDays: 30 });
+
+      // gc swallows failures into a returned `error` field rather than throwing, so a bare success
+      // message here would reproduce exactly the defect this replaces.
+      if (result.error) {
+        console.error(`❌  Cleanup FAILED: ${result.error}`);
+        console.error('    Nothing was deleted. .planning/history/ is unchanged.');
+        process.exitCode = 1;
+        break;
+      }
+
+      // The count is reported even when it is zero. "Cleanup complete" over 0 deletions is the
+      // sentence that made the old no-op invisible.
+      console.log('\n🧹  Temporal cleanup');
+      console.log(`    Deleted:    ${result.deleted} snapshot director${result.deleted === 1 ? 'y' : 'ies'}`);
+      console.log(`    Remaining:  ${result.remaining}`);
+      if (result.deleted === 0) {
+        console.log('    Nothing was old enough or over the limit — no change.');
+      }
+      console.log('');
       break;
+    }
 
     case 'inject': {
       const auditId = ARGS[1];
       const fix = ARGS.slice(2).join(' ');
       if (!auditId || !fix) {
-        console.error('Usage: /mindforge:temporal inject <auditId> <fix description>');
+        console.error('Usage: mindforge temporal inject <auditId> <fix description>');
         process.exit(1);
       }
       const result = await HindsightInjector.inject(auditId, fix);
@@ -46,7 +96,7 @@ async function main() {
     }
 
     default:
-      console.log('Usage: /mindforge:temporal <status|cleanup|inject>');
+      console.log('Usage: mindforge temporal <status|cleanup|inject>');
       break;
   }
 }

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');