sparda-mcp 0.5.0 → 0.5.2

package/src/server/persistence.js

@@ -0,0 +1,269 @@
+// server/persistence.js — durable, pluggable state persistence (Chantier 1).
+//
+// Two clearly-separated concerns live here:
+//
+//   1. THE MANIFEST (`sparda.json`) is a LOCAL git artifact: `remove`, `sync`,
+//      `doctor` and carry-over all read it from disk, and it is committed. It
+//      must never move to a remote store. What it needs is durability — a crash
+//      mid-write must never leave it truncated. `atomicWriteFileSync` writes to
+//      a temp file, fsyncs it, then renames (rename is atomic on POSIX/NTFS), so
+//      a reader sees either the old bytes or the new bytes, never a half-file.
+//
+//   2. PLUGGABLE STATE DRIVERS (Memory / LocalFile / Redis) persist arbitrary,
+//      engine-agnostic state by instanceId. This is the seam for the future
+//      living-engine state (the bounded brain snapshot) and for multi-node
+//      deployments — not for `sparda.json`. Redis is a LAZY import: it is never
+//      a hard dependency (hard rule #8 — the 4 pinned deps stay 4), it only
+//      loads if a user explicitly selects SPARDA_DRIVER=redis.
+//
+// Host never pays (hard rule #1): nothing here sits on the request path.
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+// ───────────────────────────────────────────────────────────────────────────
+// ATOMIC FILE WRITE  (the single source of truth — generators + bridge use it)
+// temp file → fsync → rename. fsync is the part the old `atomicWrite` lacked:
+// without it, rename can land before the data is flushed and a power loss
+// leaves a zero-length file. The temp sits next to the target (same fs) so the
+// rename is a real atomic move, not a cross-device copy.
+// ───────────────────────────────────────────────────────────────────────────
+
+// Windows reality: Defender or the search indexer can hold a sub-second lock on the
+// target mid-rename, surfacing as a transient EPERM/EACCES/EBUSY (seen as a ~1-in-N
+// flake in the byte-for-byte fixture tests). A bounded retry with a short, non-
+// spinning backoff clears it. A genuine failure (ENOENT, ENOSPC, EROFS) is NOT a
+// lock — it is surfaced immediately, never retried. Off the hot path (rule #1), so
+// the few ms of blocking on the rare retry never touch a request.
+export const RENAME_MAX_ATTEMPTS = 5;
+const RENAME_BACKOFF_MS = 10;
+const TRANSIENT_LOCK_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+
+// synchronous, non-spinning wait — blocks this thread for ms without burning CPU.
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export function atomicWriteFileSync(file, content) {
+  const tmp = `${file}.sparda-tmp`;
+  let fd;
+  try {
+    fd = fs.openSync(tmp, 'w');
+    fs.writeSync(fd, content);
+    fs.fsyncSync(fd);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+  for (let attempt = 1; ; attempt++) {
+    try {
+      fs.renameSync(tmp, file);
+      return;
+    } catch (err) {
+      if (!TRANSIENT_LOCK_CODES.has(err.code) || attempt >= RENAME_MAX_ATTEMPTS) {
+        try { fs.unlinkSync(tmp); } catch { /* best effort */ }
+        throw err;
+      }
+      sleepSync(RENAME_BACKOFF_MS * attempt); // 10, 20, 30, 40 ms — clears a brief AV/indexer lock
+    }
+  }
+}
+
+// Convenience for the manifest: pretty JSON + trailing newline, written atomically.
+// Mirrors the exact byte shape the generators produce so diffs stay clean.
+export function writeManifestSync(manifestPath, manifest) {
+  atomicWriteFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+// Merge-write a single top-level key into the on-disk manifest without
+// clobbering keys another writer (immune, sparding, labs, semantic) may have
+// touched since. Re-reads, sets one field, writes atomically. Silent on a brief
+// disk hiccup — the in-memory copy is the source of truth and will retry.
+export function mergeManifestKeySync(manifestPath, key, value) {
+  try {
+    const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    onDisk[key] = value;
+    writeManifestSync(manifestPath, onDisk);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// PLUGGABLE STATE DRIVERS  (engine-agnostic key/value by instanceId)
+// Interface: save(id, data) load(id) delete(id) listInstances()  → all async.
+// ───────────────────────────────────────────────────────────────────────────
+
+// Driver 1 — in-memory. Zero setup, ephemeral. Default for tests and for runs
+// that don't want any state on disk.
+export class MemoryDriver {
+  #store = new Map();
+  async save(instanceId, data) {
+    this.#store.set(instanceId, JSON.parse(JSON.stringify(data)));
+    return true;
+  }
+  async load(instanceId) {
+    return this.#store.get(instanceId) ?? null;
+  }
+  async delete(instanceId) {
+    return this.#store.delete(instanceId);
+  }
+  async listInstances() {
+    return [...this.#store.keys()];
+  }
+}
+
+// Driver 2 — local file, one JSON per instance under baseDir, written with the
+// same atomic+fsync guarantee as the manifest. Filenames are hashed so an
+// instanceId can be any string without path-injection risk.
+export class LocalFileDriver {
+  #baseDir;
+  #ttlMs;
+  constructor(baseDir = './sparda_state/', ttlDays = 0) {
+    this.#baseDir = path.resolve(baseDir);
+    this.#ttlMs = ttlDays > 0 ? ttlDays * 86_400_000 : 0;
+    fs.mkdirSync(this.#baseDir, { recursive: true });
+  }
+  #filePath(instanceId) {
+    const hash = crypto.createHash('sha256').update(instanceId).digest('hex').slice(0, 16);
+    return path.join(this.#baseDir, `sparda_${hash}.json`);
+  }
+  async save(instanceId, data) {
+    try {
+      atomicWriteFileSync(this.#filePath(instanceId), JSON.stringify(data, null, 2));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async load(instanceId) {
+    const target = this.#filePath(instanceId);
+    try {
+      if (this.#ttlMs > 0) {
+        const stat = await fsp.stat(target);
+        if (Date.now() - stat.mtimeMs > this.#ttlMs) {
+          await fsp.unlink(target).catch(() => {});
+          return null;
+        }
+      }
+      return JSON.parse(await fsp.readFile(target, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+  async delete(instanceId) {
+    try {
+      await fsp.unlink(this.#filePath(instanceId));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async listInstances() {
+    try {
+      const files = await fsp.readdir(this.#baseDir);
+      return files
+        .filter((f) => f.startsWith('sparda_') && f.endsWith('.json'))
+        .map((f) => f.slice('sparda_'.length, -'.json'.length));
+    } catch {
+      return [];
+    }
+  }
+}
+
+// Driver 3 — Redis, for distributed/multi-pod nodes. ioredis is imported lazily
+// and is NOT a package dependency: selecting this driver without ioredis
+// installed throws a clear, actionable error rather than failing at import.
+export class RedisDriver {
+  #prefix;
+  #ttl;
+  #client = null;
+  #ready;
+  constructor(options = {}) {
+    this.#prefix = options.keyPrefix ?? 'sparda:';
+    this.#ttl = options.ttlSeconds ?? 0;
+    this.#ready = this.#init(options);
+  }
+  async #init(options) {
+    let Redis;
+    try {
+      ({ default: Redis } = await import('ioredis'));
+    } catch {
+      throw Object.assign(
+        new Error('RedisDriver requires the optional "ioredis" package.'),
+        { code: 'USER', hint: 'Run `npm install ioredis`, or use the default file driver.' },
+      );
+    }
+    this.#client = new Redis({
+      host: options.host ?? 'localhost',
+      port: options.port ?? 6379,
+      password: options.password,
+      db: options.db ?? 0,
+      tls: options.tls ? {} : undefined,
+      lazyConnect: true,
+    });
+  }
+  #key(instanceId) {
+    return `${this.#prefix}${instanceId}`;
+  }
+  async save(instanceId, data) {
+    try {
+      await this.#ready;
+      const payload = JSON.stringify(data);
+      if (this.#ttl > 0) await this.#client.setex(this.#key(instanceId), this.#ttl, payload);
+      else await this.#client.set(this.#key(instanceId), payload);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async load(instanceId) {
+    try {
+      await this.#ready;
+      const raw = await this.#client.get(this.#key(instanceId));
+      return raw ? JSON.parse(raw) : null;
+    } catch {
+      return null;
+    }
+  }
+  async delete(instanceId) {
+    try {
+      await this.#ready;
+      return (await this.#client.del(this.#key(instanceId))) > 0;
+    } catch {
+      return false;
+    }
+  }
+  async listInstances() {
+    try {
+      await this.#ready;
+      const keys = await this.#client.keys(`${this.#prefix}*`);
+      return keys.map((k) => k.slice(this.#prefix.length));
+    } catch {
+      return [];
+    }
+  }
+}
+
+// Factory from env. Default is the local file driver — survives restarts with
+// zero setup, no new dependency. `memory` for tests, `redis` opts into the lazy
+// dependency. Unknown values fall back to file (fail safe, not silent crash).
+export function createStateDriverFromEnv(env = process.env) {
+  switch ((env.SPARDA_DRIVER ?? 'file').toLowerCase()) {
+    case 'memory':
+      return new MemoryDriver();
+    case 'redis':
+      return new RedisDriver({
+        host: env.SPARDA_REDIS_HOST ?? 'localhost',
+        port: env.SPARDA_REDIS_PORT ? Number(env.SPARDA_REDIS_PORT) : 6379,
+        password: env.SPARDA_REDIS_PASSWORD,
+        keyPrefix: env.SPARDA_REDIS_PREFIX ?? 'sparda:',
+      });
+    case 'file':
+    default:
+      return new LocalFileDriver(env.SPARDA_STATE_DIR ?? './sparda_state/');
+  }
+}

package/src/server/stdio.js

@@ -12,6 +12,10 @@ import { sanitizeDescription } from '../security/sanitize.js';
 import { createIdleHarvester } from './idle.js';
 import { createSequenceRecorder, sequenceRecordingEnabled } from './condenser.js';
 import { eligibleForCrystallization, fallbackComposite, normalizeCompositeName, compositeSchema, runComposite } from './crystallize.js';
+import { writeManifestSync, mergeManifestKeySync } from './persistence.js';
+import { createSpardaEngine } from './engine.js';
+import { initiateWrite, preapproveWrite, confirmWrite } from './confirmation.js';
+import { resolveContext, injectContext, fingerprintContext } from './context-carrier.js';
 
 const EVENT_POLL_MS = Number(process.env.SPARDA_EVENT_POLL_MS ?? 5000);
 // the sampling budgets below are also what the recycling gauge counts as "avoided"
@@ -35,16 +39,29 @@ export async function startStdioBridge({ cwd, portOverride }) {
   if (!key) {
     throw Object.assign(new Error('localKey missing from sparda.json.'), { code: 'USER', hint: 'Re-run `npx sparda-mcp init` to regenerate it.' });
   }
-  const base = await waitForHost(port, key, framework);
+
+  // Brief #4 — tenant context carrier. Resolved ONCE, here, from operator-pinned
+  // sources (CLI --context > env SPARDA_CONTEXT_* > sparda.json names the headers).
+  // The AI is the adversary and can forge anything it sends; pinning at launch (not
+  // per call) is the only scope it cannot choose. Throws USER on CRLF/over-bound so
+  // a malformed scope stops the bridge instead of degrading to "no scope". Absent
+  // config → frozen empty map → injectContext is a no-op (byte-identical forwarding).
+  const ctx = resolveContext({ argv: process.argv, env: process.env, config: manifest.contextPropagation ?? null });
+  const ctxFp = fingerprintContext(ctx); // value-free: names + 8-hex SHA-256 only (R2/R7)
+  if (Object.keys(ctxFp).length > 0) {
+    console.error(`[sparda] context carrier active (forwarded verbatim on every host call): ${JSON.stringify(ctxFp)}`);
+  }
+
+  const base = await waitForHost(port, key, framework, ctx);
 
   // full tool specs live in the generated router; fetch them (single source of truth)
-  const toolSpecs = await (await fetch(`${base}/mcp/tools`, { headers: { 'x-sparda-key': key } })).json();
+  const toolSpecs = await (await fetch(`${base}/mcp/tools`, { headers: hostHeaders(key, ctx) })).json();
 
   const enabled = () => Object.entries(toolSpecs).filter(([, t]) => t.enabled);
   const disabled = () => Object.entries(toolSpecs).filter(([, t]) => !t.enabled);
 
   const server = new Server(
-    { name: `sparda-${path.basename(cwd)}`, version: '0.5.0' },
+    { name: `sparda-${path.basename(cwd)}`, version: '0.5.2' },
     { capabilities: { tools: { listChanged: true }, prompts: { listChanged: true }, logging: {} } },
   );
 
@@ -55,6 +72,16 @@ export async function startStdioBridge({ cwd, portOverride }) {
 
   // R4.4: every internal organ works only when the event loop is quiet
   const harvester = createIdleHarvester();
+  // engine (Bloc B, slice 1 — "cerveau de stabilité"): a passive per-tool read of
+  // which response fields stay put vs move. Fed off the hot path via the harvester,
+  // holds field fingerprints only (never values, ADR-014), runtime-only — no
+  // carry-over, same posture as the router's purity detector.
+  const engine = createSpardaEngine();
+  // R4.3 kill-switch (decision A, ADR-020): the flywheel SERVES proven-stable reads
+  // from memory by default. SPARDA_FLYWHEEL=off keeps every organ learning but stops
+  // serving, so a suspect cache can be cut without losing the brain. Gated here at the
+  // bridge; the engine itself stays env-free.
+  const flywheelServes = process.env.SPARDA_FLYWHEEL !== 'off';
   // R2.1 (Labs, default OFF): record the current of calls, detect circuits;
   // R2.2: at the observation threshold a circuit crystallizes into a composite tool
   const composites = new Map(); // composite tool name -> { sig, circuit }
@@ -163,6 +190,17 @@ export async function startStdioBridge({ cwd, portOverride }) {
         description: 'Call this FIRST. Returns the full living context of this app: every tool with its description, known workflows, runtime telemetry (per-tool calls/errors/latency), quarantined tools, and the immune memory of past diagnosed failures. Lets any AI session resume exactly where the previous one stopped.',
         inputSchema: { type: 'object', properties: {} },
       },
+      {
+        name: 'sparda_confirm',
+        description: 'Confirms a pending write or delete operation gated by human-in-the-loop policies using its confirmation token.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            token: { type: 'string', description: 'The confirmation token returned by the gated invoke response.' }
+          },
+          required: ['token']
+        }
+      },
     ],
   }));
 
@@ -204,7 +242,7 @@ export async function startStdioBridge({ cwd, portOverride }) {
       }, null, 2));
     }
     if (name === 'sparda_get_context') {
-      const headers = { 'x-sparda-key': key };
+      const headers = hostHeaders(key, ctx);
       const [stats, events] = await Promise.all([
         fetch(`${base}/mcp/stats`, { headers, signal: AbortSignal.timeout(2000) }).then((r) => (r.ok ? r.json() : null)).catch(() => null),
         fetch(`${base}/mcp/events?since=0`, { headers, signal: AbortSignal.timeout(2000) }).then((r) => (r.ok ? r.json() : null)).catch(() => null),
@@ -213,6 +251,8 @@ export async function startStdioBridge({ cwd, portOverride }) {
       // the first hit paid the diagnosis, every later one was served from memory
       const antibodyHits = Object.values(manifest.immune?.antibodies ?? {})
         .reduce((n, a) => n + Math.max(0, (a.hits ?? 1) - 1), 0);
+      const behavior = engine.snapshot();
+      const fly = behavior.flywheel.stats;
       return text(JSON.stringify({
         project: path.basename(cwd),
         framework: manifest.framework,
@@ -224,14 +264,19 @@ export async function startStdioBridge({ cwd, portOverride }) {
         immuneMemory: manifest.immune?.antibodies ?? {},
         recycling: {
           compute: stats?.recycle ?? null,
+          // R4.3: host calls the flywheel answered from its own RAM — a category the
+          // router cannot count, because the request never reached it. armed = reads
+          // proven stable enough to serve right now.
+          flywheel: { servedFromMemory: fly.served, armed: fly.ready },
           intelligence: {
             session: { samplingAvoided: intel.samplingAvoided, tokensAvoidedEst: intel.tokensAvoidedEst },
             lifetime: { antibodyHits, tokensAvoidedEst: antibodyHits * DIAGNOSIS_TOKENS },
           },
         },
         sparding: manifest.sparding ?? {},
+        behavior,
         labs: { recordSequences: Boolean(recorder), compositeTools: [...composites.keys()], circuits: manifest.labs?.circuits ?? {} },
-        hint: 'runtime.quarantine lists tools temporarily blocked by the immune system (503 until cooldown). immuneMemory maps failure signatures (source|tool|status) to cached diagnoses — same failure later costs zero tokens. recycling measures how much compute/intelligence was served from SPARDA\'s own memory instead of being paid again. runtime.purity classifies each route by observation: pure = same args keep returning the same response (recyclable), volatile = it changed, erasing = writes. labs.circuits are observed call sequences where one tool\'s output fed the next one\'s input.',
+        hint: 'runtime.quarantine lists tools temporarily blocked by the immune system (503 until cooldown). immuneMemory maps failure signatures (source|tool|status) to cached diagnoses — same failure later costs zero tokens. recycling measures how much compute/intelligence was served from SPARDA\'s own memory instead of being paid again. runtime.purity classifies each route by observation: pure = same args keep returning the same response (recyclable), volatile = it changed, erasing = writes. labs.circuits are observed call sequences where one tool\'s output fed the next one\'s input. behavior.stability is the engine\'s passive read of each tool across this session: stable lists response fields that never changed (predictable — future recycling candidates), volatile lists fields that moved; calls is how many responses were observed. behavior.rhythm flags tools called on a steady cadence (periodMs = the beat, confidence 0-1, nextEstimate = when the next call is expected) — a regular rhythm plus a stable result is the textbook pre-fetch candidate. behavior.myelin learns habitual tool succession: an edge "A-->B" means B tends to be called right after A; strength (0-10) grows with every traversal and myelinated edges (strength>=3) are entrenched habits — succession candidates the condenser misses because no data flows between the two tools. behavior.dependencies is the engine\'s map of what the other observers cannot see: invariants are response fields that stayed conserved (>=85% over >=5 reads) even while writes hit the app — true constants, the safest thing to cache hard; ghosts are hidden couplings where a write tool reliably MOVES some unrelated read (writeTool affects a different read tool, correlation 0-1), discovered purely by observation — no data flows between them and they need not be adjacent, yet the write keeps perturbing that read. behavior.flywheel is Bloc B acting on all of the above: once a read has returned the identical response >=3 times for the same arguments it is served straight from memory and the host call is skipped entirely (R4.3), with ready = how many reads are armed to serve right now; recycling.flywheel.servedFromMemory counts how many host calls were already answered from RAM this session — the one recycling category the router cannot see, because the request never reached it (SPARDA_FLYWHEEL=off stops serving while every organ keeps learning).',
       }, null, 2));
     }
     if (name === 'sparda_list_disabled_tools') {
@@ -239,12 +284,33 @@ export async function startStdioBridge({ cwd, portOverride }) {
         ? `Disabled (write-safety):\n${disabled().map(([n, t]) => `- ${n} (${t.method} ${t.path})`).join('\n')}\n\nTo enable: set "enabled": true in sparda.json, then re-run \`npx sparda-mcp init\` and restart this bridge.`
         : 'No disabled tools.');
     }
+    if (name === 'sparda_confirm') {
+      const token = args.token;
+      if (typeof token !== 'string' || !token) {
+        return { content: [{ type: 'text', text: 'Error: missing or invalid confirmation token.' }], isError: true };
+      }
+      // SIGNAL 2 (Brief #1): the AI holds the token (Signal 1, reachable over stdio) but the
+      // write proceeds only if a human approved out-of-band — an OS-dialog click, or a prior
+      // native-elicitation accept. Neither channel is reachable by the AI, so a self-issued
+      // confirm can no longer pass. Necessary-but-not-sufficient by construction.
+      const gate = confirmWrite(token);
+      if (!gate.ok) {
+        return { content: [{ type: 'text', text: signal2Denial(gate.reason) }], isError: true };
+      }
+      const payload = await confirmInvoke(base, key, token, ctx);
+      if (payload === null) {
+        return { content: [{ type: 'text', text: `Host app error. Check that your server is still running on :${port}.` }], isError: true };
+      }
+      const pretty = JSON.stringify(payload, null, 2);
+      const isError = payload.upstreamStatus !== undefined ? payload.upstreamStatus >= 400 : Boolean(payload.error);
+      return { content: [{ type: 'text', text: pretty }], isError };
+    }
 
     // composite tools run their whole chain (GET-only by construction — no
     // write confirmation to bypass), auto-feeding linked args between steps
     const comp = composites.get(name);
     if (comp) {
-      const result = await runComposite({ circuit: comp.circuit, args, toolSpecs, invokeFn: (tool, a) => invoke(base, key, tool, a) });
+      const result = await runComposite({ circuit: comp.circuit, args, toolSpecs, invokeFn: (tool, a) => invoke(base, key, tool, a, ctx) });
       const pretty = JSON.stringify(result, null, 2);
       return {
         content: [{ type: 'text', text: pretty.length > 8000 ? `${pretty.slice(0, 8000)}\n[truncated — ${pretty.length} chars total]` : pretty }],
@@ -255,7 +321,10 @@ export async function startStdioBridge({ cwd, portOverride }) {
     const spec = toolSpecs[name];
     const isWrite = spec && spec.method !== 'GET';
 
-    // human-in-the-loop: confirm writes natively in the client UI when supported
+    // human-in-the-loop, channel 1: confirm writes natively in the client UI when supported.
+    // A native accept is a real out-of-band human yes — it pre-approves Signal 2 below, so the
+    // host's confirm round-trip never prompts the operator a second time.
+    let elicitationApproved = false;
     if (isWrite && server.getClientCapabilities()?.elicitation) {
       const answer = await server.elicitInput({
         message: `SPARDA: allow ${spec.method} ${spec.path}? This is a write operation on your live app.`,
@@ -275,9 +344,26 @@ export async function startStdioBridge({ cwd, portOverride }) {
         recordSparding(manifestPath, manifest, name, mockProof);
         return { content: [{ type: 'text', text: `Write declined by user: ${spec.method} ${spec.path} was NOT executed.` }], isError: true };
       }
+      elicitationApproved = true;
+    }
+
+    // Bloc B flywheel (R4.3): the first organ that ACTS. For a read proven stable —
+    // the same response >=3x for these exact args, within TTL — serve straight from the
+    // engine's RAM and never make the host call. Writes always fall through to the host
+    // (and still pass write-confirmation above), so hard rule #3 is untouched. The served
+    // `data` is byte-identical to what the host returned; servedByFlywheel marks the
+    // envelope so a hit is observable. Not re-observed (that would feed the cache itself).
+    if (spec && !isWrite && flywheelServes) {
+      const cached = engine.preCall(name, args);
+      if (cached.hit) {
+        const body = { data: cached.value, upstreamStatus: 200, servedByFlywheel: true };
+        const pretty = JSON.stringify(body, null, 2);
+        const truncated = pretty.length > 8000 ? `${pretty.slice(0, 8000)}\n[truncated — ${pretty.length} chars total]` : pretty;
+        return { content: [{ type: 'text', text: truncated }], isError: false };
+      }
     }
 
-    const payload = await invoke(base, key, name, args);
+    const payload = await invoke(base, key, name, args, ctx);
     if (payload === null) {
       const mockProof = {
         version: 'sparding-proof/v0.1',
@@ -289,6 +375,16 @@ export async function startStdioBridge({ cwd, portOverride }) {
       return { content: [{ type: 'text', text: `Host app error. Check that your server is still running on :${port}.` }], isError: true };
     }
 
+    // human-in-the-loop, channel 2 (Brief #1): the host gated this write and minted a single-use
+    // confirm token. Arm Signal 2 NOW, keyed by that token. Elicitation clients already have a
+    // human yes → pre-approve (no second prompt). Everyone else gets an OS dialog (fires async,
+    // R1) that `sparda_confirm` will require before the write can run. This is what closes the
+    // forgeable-confirmation hole on clients without elicitation.
+    if (isWrite && payload.status === 'awaiting_confirmation' && typeof payload.confirm === 'string') {
+      if (elicitationApproved) preapproveWrite(payload.confirm);
+      else initiateWrite({ token: payload.confirm, label: `${spec.method} ${spec.path}` });
+    }
+
     const proofForRecord = payload.spardingProof ? { ...payload.spardingProof } : { version: 'sparding-proof/v0.1', decision: 'allow', risk: 'low', reasons: [] };
     if (payload.upstreamStatus !== undefined && payload.upstreamStatus >= 400) {
       proofForRecord.isExecutionError = true;
@@ -299,18 +395,33 @@ export async function startStdioBridge({ cwd, portOverride }) {
     }
     recordSparding(manifestPath, manifest, name, proofForRecord);
 
-    // condenser tap (Labs): only AI-driven calls that succeeded feed the current —
-    // internal read-backs and failures are not workflow steps
-    if (recorder && payload.upstreamStatus !== undefined && payload.upstreamStatus < 400) {
-      recorder.record(name, args, payload.data);
+    // successful AI-driven reads feed SPARDA's passive observers, both off the hot
+    // path (idle harvester). Internal read-backs and failures are not workflow steps.
+    if (payload.upstreamStatus !== undefined && payload.upstreamStatus < 400) {
+      // engine: stability + rhythm + myelin (Blocs A/B) and the dependency map
+      // (Bloc D — invariants conserved across writes, ghost write->read couplings).
+      // isWrite lets Bloc D tell a state read from a mutation. Capture the call time
+      // here on the hot path; classify in idle. (The proof-after-write read-back below
+      // is internal, not an AI workflow step, so it is deliberately not observed.)
+      const observedAt = Date.now();
+      harvester.enqueue(() => engine.observe(name, payload.data, observedAt, isWrite, args));
+      // condenser tap (Labs, opt-in): detect circuits where one output feeds the next
+      if (recorder) recorder.record(name, args, payload.data);
     }
 
     // proof-after-write: re-read the same path so the AI sees the effect of its write
     let proof = null;
     if (isWrite && payload.upstreamStatus < 400) {
+      // flywheel coherence (5b): this write just moved whatever a GET on the same path
+      // returns, so drop that GET's cached answer NOW — synchronous, before the next read
+      // can be served stale. The engine purges by learned ghost couplings in idle; this
+      // covers the structural same-path case it can't see (no path info in the engine).
+      for (const [n, t] of Object.entries(toolSpecs)) {
+        if (t.method === 'GET' && t.path === spec.path) engine.invalidateCache(n);
+      }
       const getter = Object.entries(toolSpecs).find(([, t]) => t.enabled && t.method === 'GET' && t.path === spec.path);
       if (getter) {
-        const after = await invoke(base, key, getter[0], pickPathArgs(spec, args));
+        const after = await invoke(base, key, getter[0], pickPathArgs(spec, args), ctx);
         if (after && after.upstreamStatus < 400) proof = { readBack: getter[0], state: after.data };
       }
     }
@@ -327,7 +438,7 @@ export async function startStdioBridge({ cwd, portOverride }) {
   server.oninitialized = () => {
     // a session resumed on a cached semantic pass skipped the enrichment sampling call
     if (manifest.semantic) { intel.samplingAvoided += 1; intel.tokensAvoidedEst += SEMANTIC_TOKENS; }
-    pollTimer = startEventPolling(server, base, key, manifest, manifestPath, intel);
+    pollTimer = startEventPolling(server, base, key, manifest, manifestPath, intel, ctx);
     runSemanticEnrichment({ server, manifest, manifestPath, toolSpecs }).catch((e) => console.error(`[sparda] semantic pass skipped: ${e.message}`));
   };
   server.onclose = () => {
@@ -341,11 +452,22 @@ export async function startStdioBridge({ cwd, portOverride }) {
   console.error(`[sparda] MCP bridge running. ${enabled().length} tools enabled, ${disabled().length} disabled (write-safety).${recorder ? ' Labs: sequence recording ON.' : ''} Host: ${base}`);
 }
 
-async function invoke(base, key, tool, args) {
+// One place to build the outbound header set for any bridge→host call. The
+// operator-pinned tenant context (Brief #4) is copied on LAST so it is always
+// present and can never be shadowed by a per-call header — the AI cannot forge
+// the scope. When context is off, injectContext is a no-op and the headers are
+// byte-identical to before.
+function hostHeaders(key, ctx, extra) {
+  const h = { 'x-sparda-key': key, ...(extra ?? {}) };
+  injectContext(h, ctx);
+  return h;
+}
+
+async function invoke(base, key, tool, args, ctx) {
   try {
     const res = await fetch(`${base}/mcp/invoke`, {
       method: 'POST',
-      headers: { 'content-type': 'application/json', 'x-sparda-key': key },
+      headers: hostHeaders(key, ctx, { 'content-type': 'application/json' }),
       body: JSON.stringify({ tool, args }),
       signal: AbortSignal.timeout(30_000),
     });
@@ -355,6 +477,20 @@ async function invoke(base, key, tool, args) {
   }
 }
 
+async function confirmInvoke(base, key, token, ctx) {
+  try {
+    const res = await fetch(`${base}/mcp/invoke/confirm`, {
+      method: 'POST',
+      headers: hostHeaders(key, ctx, { 'content-type': 'application/json' }),
+      body: JSON.stringify({ confirm: token }),
+      signal: AbortSignal.timeout(30_000),
+    });
+    return await res.json().catch(() => ({ upstreamStatus: res.status, error: 'non-JSON response from host' }));
+  } catch {
+    return null;
+  }
+}
+
 // keep only the path params of the original call so the read-back targets the same resource
 function pickPathArgs(spec, args) {
   const out = {};
@@ -365,11 +501,11 @@ function pickPathArgs(spec, args) {
 // live error feed: host app errors reach the AI as MCP logging notifications.
 // immune memory: known failure signatures carry their cached diagnosis (zero tokens);
 // new signatures wake the client's LLM once, and the antibody is stored in sparda.json.
-function startEventPolling(server, base, key, manifest, manifestPath, intel) {
+function startEventPolling(server, base, key, manifest, manifestPath, intel, ctx) {
   let lastSeq = null; // first poll sets the baseline; only NEW errors are reported
   const timer = setInterval(async () => {
     try {
-      const r = await fetch(`${base}/mcp/events?since=${lastSeq ?? 0}`, { headers: { 'x-sparda-key': key }, signal: AbortSignal.timeout(2000) });
+      const r = await fetch(`${base}/mcp/events?since=${lastSeq ?? 0}`, { headers: hostHeaders(key, ctx), signal: AbortSignal.timeout(2000) });
       if (!r.ok) return;
       const { seq, events } = await r.json();
       if (lastSeq === null) { lastSeq = seq; return; }
@@ -433,11 +569,10 @@ async function diagnoseAndRemember({ server, manifest, manifestPath, ev, sig })
 }
 
 function persistImmune(manifestPath, manifest) {
-  try {
-    const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    onDisk.immune = manifest.immune;
-    fs.writeFileSync(manifestPath, JSON.stringify(onDisk, null, 2) + '\n');
-  } catch { /* disk briefly unavailable — the antibody stays in memory */ }
+  // merge-write (atomic + fsync): re-read so we never clobber sparding/labs/
+  // semantic written by another path; on a brief disk hiccup the antibody
+  // stays in memory and the next write retries.
+  mergeManifestKeySync(manifestPath, 'immune', manifest.immune);
 }
 
 function recordSparding(manifestPath, manifest, tool, proof) {
@@ -493,18 +628,16 @@ function recordSparding(manifestPath, manifest, tool, proof) {
 }
 
 function persistSparding(manifestPath, manifest) {
-  try {
-    const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    onDisk.sparding = manifest.sparding;
-    fs.writeFileSync(manifestPath, JSON.stringify(onDisk, null, 2) + '\n');
-  } catch { /* disk briefly unavailable */ }
+  mergeManifestKeySync(manifestPath, 'sparding', manifest.sparding);
 }
 
 function persistLabs(manifestPath, manifest) {
+  // value depends on the re-read (merge into labs, keep other labs fields), so
+  // this can't use mergeManifestKeySync — but the write is still atomic+fsync.
   try {
     const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
     onDisk.labs = { ...onDisk.labs, circuits: manifest.labs.circuits };
-    fs.writeFileSync(manifestPath, JSON.stringify(onDisk, null, 2) + '\n');
+    writeManifestSync(manifestPath, onDisk);
   } catch { /* disk briefly unavailable — the circuit stays in memory */ }
 }
 
@@ -546,9 +679,7 @@ async function runSemanticEnrichment({ server, manifest, manifestPath, toolSpecs
     .filter((w) => w.steps.length > 0);
 
   manifest.semantic = { enrichedAt: new Date().toISOString(), source: 'mcp-sampling', descriptions, workflows };
-  const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-  onDisk.semantic = manifest.semantic;
-  fs.writeFileSync(manifestPath, JSON.stringify(onDisk, null, 2) + '\n');
+  mergeManifestKeySync(manifestPath, 'semantic', manifest.semantic);
 
   await server.sendToolListChanged().catch(() => {});
   await server.sendPromptListChanged().catch(() => {});
@@ -577,12 +708,29 @@ function schemaFor(t) {
 
 function text(t) { return { content: [{ type: 'text', text: t }] }; }
 
-async function waitForHost(port, key, framework) {
+// AI-facing message when the Signal-2 gate (Brief #1) refuses a `sparda_confirm`. Each reason
+// tells the model what to do next without implying it can approve the write itself.
+function signal2Denial(reason) {
+  switch (reason) {
+    case 'awaiting_human':
+      return 'Awaiting human approval. A confirmation dialog is open on the host machine — the operator must click Allow. You cannot approve this yourself. Call sparda_confirm again with the same token once the operator has approved.';
+    case 'human_denied':
+      return 'The operator DENIED this write at the host confirmation dialog. It was NOT executed. Do not retry this token.';
+    case 'unknown_token':
+      return 'Unknown or already-used confirmation token. Re-issue the write to mint a fresh token (which opens a new human approval dialog).';
+    case 'expired':
+      return 'The confirmation expired before a human approved it. Re-issue the write to try again.';
+    default:
+      return 'Confirmation could not be validated. Re-issue the write to mint a fresh token.';
+  }
+}
+
+async function waitForHost(port, key, framework, ctx) {
   const hosts = ['127.0.0.1', 'localhost'];
   for (let attempt = 0; attempt < 40; attempt++) {
     for (const h of hosts) {
       try {
-        const r = await fetch(`http://${h}:${port}/mcp/tools`, { headers: { 'x-sparda-key': key }, signal: AbortSignal.timeout(1500) });
+        const r = await fetch(`http://${h}:${port}/mcp/tools`, { headers: hostHeaders(key, ctx), signal: AbortSignal.timeout(1500) });
         if (r.ok) return `http://${h}:${port}`;
         if (r.status === 401) throw Object.assign(new Error('Host app reachable but key mismatch — re-run `npx sparda-mcp init`.'), { code: 'USER' });
       } catch (e) { if (e.code === 'USER') throw e; }