sparda-mcp 0.5.0 → 0.5.2

package/templates/express-router.txt

@@ -55,6 +55,51 @@ function spardaPuritySnapshot() {
   }
   return out;
 }
+// ── horizontal scale (Brief #2): Quorum Sensing × G-Map CRDT ──────────────────
+// N host replicas each learn purity locally; gossip converges the grow-only counts so a
+// route observed-pure on ANY replica becomes pure on ALL — no coordinator, no shared
+// store, no new dependency. "Zero infra" holds: solo (no SPARDA_PEERS) starts no timer and
+// pays nothing. CRDT merge = max() per counter (commutative, associative, idempotent →
+// eventual convergence). value-free: only tool NAMES (already public via /tools) and integer
+// counts cross the wire — never an argument, never a body.
+const SPARDA_PEERS = (process.env.SPARDA_PEERS ?? '').split(',').map((s__ANY_TYPE__) => s.trim().replace(/\/$/, '')).filter((s__ANY_TYPE__) => /^https?:\/\//.test(s));
+const SPARDA_GOSSIP_MS = Math.max(50, Number(process.env.SPARDA_GOSSIP_MS) || 30000);
+const SPARDA_GOSSIP_TIMEOUT_MS = Math.max(250, Number(process.env.SPARDA_GOSSIP_TIMEOUT_MS) || 2000);
+function spardaGossipSnapshot() {
+  const out__STATS_TYPE__ = {};
+  for (const [name, pu] of Object.entries(SPARDA_PURITY)) out[name] = { repeats: pu.repeats, mismatches: pu.mismatches };
+  return out;
+}
+// merge a peer's snapshot: max() per counter, ONLY for tools we already know (bounded — the
+// map can never grow past the tool count; an unknown or injected key is silently dropped).
+function spardaMergeGossip(remote__ANY_TYPE__) {
+  if (!remote || typeof remote !== 'object' || Array.isArray(remote)) return 0;
+  let merged = 0;
+  for (const [name, rv] of Object.entries(remote)) {
+    if (!SPARDA_TOOLS[name] || !rv || typeof rv !== 'object') continue;
+    const r = Number(rv.repeats), m = Number(rv.mismatches);
+    if (!Number.isFinite(r) || !Number.isFinite(m) || r < 0 || m < 0) continue;
+    const pu = SPARDA_PURITY[name] ?? (SPARDA_PURITY[name] = { sigs: {}, repeats: 0, mismatches: 0 });
+    if (r > pu.repeats) pu.repeats = r;       // grow-only: a count never shrinks on merge
+    if (m > pu.mismatches) pu.mismatches = m; // a mismatch anywhere → volatile everywhere (safe)
+    merged += 1;
+  }
+  return merged;
+}
+// background tick: push our snapshot to every peer. Fire-and-forget, off the request path,
+// AbortSignal-bounded; a peer being down is silence and the next tick retries (R1).
+function spardaGossipTick() {
+  if (SPARDA_PEERS.length === 0) return;
+  const body = JSON.stringify(spardaGossipSnapshot());
+  for (const peer of SPARDA_PEERS) {
+    fetch(`${peer}/mcp/gossip`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-sparda-key': SPARDA_LOCAL_KEY },
+      body,
+      signal: AbortSignal.timeout(SPARDA_GOSSIP_TIMEOUT_MS),
+    }).catch(() => {}); // peer unreachable → ignore; convergence is eventual, not urgent
+  }
+}
 function spardaEvent(source__ANY_TYPE__, tool__ANY_TYPE__, status__ANY_TYPE__, message__ANY_TYPE__) {
   SPARDA_EVENTS.push({ seq: ++SPARDA_SEQ, ts: new Date().toISOString(), source, tool, status, message: String(message ?? '').slice(0, 500) });
   if (SPARDA_EVENTS.length > 100) SPARDA_EVENTS.shift();
@@ -62,6 +107,20 @@ function spardaEvent(source__ANY_TYPE__, tool__ANY_TYPE__, status__ANY_TYPE__, m
 // observe-only: uncaughtExceptionMonitor never changes the host app's crash behavior
 process.on('uncaughtExceptionMonitor', (err__ANY_TYPE__) => spardaEvent('process', null, null, err && err.message ? err.message : err));
 
+// two-phase commit: a write/delete flagged require_human is NOT executed on /invoke.
+// It mints a single-use nonce + a preview contract; the host route is touched only after
+// an explicit /invoke/confirm replays the token. This is the gate the proof always described
+// but never enforced — the difference between a receipt and a contract.
+const SPARDA_PENDING__STATS_TYPE__ = {};
+const SPARDA_CONFIRM_TTL_MS = Number(process.env.SPARDA_CONFIRM_TTL_MS ?? 120000);
+function spardaNonce() {
+  return 'cfm_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
+}
+function spardaSweepPending() {
+  const now = Date.now();
+  for (const k of Object.keys(SPARDA_PENDING)) if (now > SPARDA_PENDING[k].expiresAt) delete SPARDA_PENDING[k];
+}
+
 function spardaProof(tool__ANY_TYPE__, spec__ANY_TYPE__, args__ANY_TYPE__) {
   const checks = {
     knownTool: spec !== undefined,
@@ -190,6 +249,53 @@ function spardaProof(tool__ANY_TYPE__, spec__ANY_TYPE__, args__ANY_TYPE__) {
   };
 }
 
+// captured once so the JSON-middleware placeholder appears a single time in the template
+// (the generator's replace is non-global).
+const SPARDA_JSON_MW__ANY_TYPE__ = __JSON_MW__;
+// SPARDA owns its own endpoints' body parsing AND the parse error: a malformed JSON body
+// returns JSON 400 locally instead of bubbling up to Express' HTML error page (stack leak).
+function SPARDA_JSON(req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) {
+  SPARDA_JSON_MW(req, res, (err__ANY_TYPE__) => {
+    if (err) { spardaEvent('router', null, 400, 'invalid JSON body'); return res.status(400).json({ error: 'invalid JSON body' }); }
+    next();
+  });
+}
+
+// the actual host-route call, shared by the allow-path and the confirm-path so a
+// confirmed write runs through the exact same execution + observation as a direct one.
+async function spardaExecute(tool__ANY_TYPE__, spec__ANY_TYPE__, args__ANY_TYPE__, proof__ANY_TYPE__, t0__ANY_TYPE__, res__RES_TYPE__) {
+  try {
+    let url = spec.path.replace(/:(\w+)/g, (_, name) => encodeURIComponent(String(args[name])));
+    const query = [];
+    for (const [k, v] of Object.entries(args)) {
+      if (k === 'body' || (spec.pathParams ?? []).includes(k) || v === undefined) continue;
+      query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+    if (query.length) url += `?${query.join('&')}`;
+
+    const init = { method: spec.method, headers: {} };
+    if (spec.method !== 'GET' && args.body !== undefined) {
+      init.headers['content-type'] = 'application/json';
+      init.body = JSON.stringify(args.body);
+    }
+    SPARDA_RECYCLE.paidFull += 1; // the host route is about to be exercised — full price
+    const upstream = await fetch(`http://127.0.0.1:${SPARDA_PORT}${url}`, { ...init, signal: AbortSignal.timeout(30_000) });
+    const text = await upstream.text();
+    let data; try { data = JSON.parse(text); } catch { data = text; }
+    spardaRecord(tool, upstream.status, Date.now() - t0);
+    if (spec.method === 'GET' && upstream.status === 200) {
+      // canonical argsig: sorted entries, so the AI's argument order never splits a signature
+      spardaObservePurity(tool, JSON.stringify(Object.entries(args).filter((e__ANY_TYPE__) => e[1] !== undefined).sort()), text);
+    }
+    if (upstream.status >= 500) spardaEvent('invoke', tool, upstream.status, text.slice(0, 200));
+    return res.status(200).json({ upstreamStatus: upstream.status, data, spardingProof: proof });
+  } catch (err__ANY_TYPE__) {
+    spardaRecord(tool, err.status ?? 502, Date.now() - t0);
+    spardaEvent('invoke', tool, err.status ?? 502, err.message);
+    return res.status(err.status ?? 502).json({ error: err.message, spardingProof: proof });
+  }
+}
+
 __ROUTER_DECL__
 
 spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) => {
@@ -208,9 +314,25 @@ spardaRouter.get('/events', (req__REQ_TYPE__, res__RES_TYPE__) => {
   res.json({ seq: SPARDA_SEQ, events: SPARDA_EVENTS.filter((e__ANY_TYPE__) => e.seq > since) });
 });
 
-spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE__) => {
-  const { tool, args = {} } = req.body ?? {};
+// peer-to-peer convergence (Brief #2). Behind the same x-sparda-key as every route above
+// (replicas share the generated key). Absorbs a peer's grow-only counts via CRDT max-merge;
+// 204 on success. An unknown tool or malformed count is silently dropped (bounded, no injection).
+spardaRouter.post('/gossip', SPARDA_JSON, (req__REQ_TYPE__, res__RES_TYPE__) => {
+  spardaMergeGossip(req.body);
+  res.status(204).end();
+});
+
+spardaRouter.post('/invoke', SPARDA_JSON, async (req__REQ_TYPE__, res__RES_TYPE__) => {
   const t0 = Date.now();
+  const reqBody = req.body ?? {};
+  const tool = reqBody.tool;
+  // type confusion guard: the old `args = {}` default only caught `undefined`. A `null`
+  // (or array/scalar) slipped through and crashed spardaProof on null[name] → Express HTML
+  // 500 with a full stack trace. We reject non-objects with clean JSON instead.
+  if (reqBody.args !== undefined && (reqBody.args === null || typeof reqBody.args !== 'object' || Array.isArray(reqBody.args))) {
+    return res.status(400).json({ error: 'args must be a JSON object', got: reqBody.args === null ? 'null' : Array.isArray(reqBody.args) ? 'array' : typeof reqBody.args });
+  }
+  const args = reqBody.args ?? {};
   const spec = SPARDA_TOOLS[tool];
 
   const proof = spardaProof(tool, spec, args);
@@ -249,41 +371,69 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE_
     return res.status(status).json({ error, spardingProof: proof });
   }
 
-  try {
-    let url = spec.path.replace(/:(\w+)/g, (_, name) => {
-      const v = args[name];
-      return encodeURIComponent(String(v));
+  if (proof.decision === 'require_human') {
+    // THE GATE THE PROOF ALWAYS LACKED.
+    // v0.5.0 had no branch here, so a require_human decision fell straight through to the
+    // host route below: the write happened, THEN the proof said "confirmation required".
+    // We stop here. The host route is not touched. We mint a single-use nonce and a preview
+    // the LLM reads in its tool-result, and only /invoke/confirm replays it.
+    spardaSweepPending();
+    const confirm = spardaNonce();
+    SPARDA_PENDING[confirm] = { tool, args, expiresAt: Date.now() + SPARDA_CONFIRM_TTL_MS, createdAt: new Date().toISOString() };
+    let siblingName = null;
+    for (const [n, t] of Object.entries(SPARDA_TOOLS)) { if (t.method === 'GET' && t.path === spec.path) { siblingName = n; break; } }
+    spardaEvent('confirm', tool, 202, `gated, awaiting confirmation (risk: ${proof.risk})`);
+    return res.status(202).json({
+      status: 'awaiting_confirmation',
+      confirm,
+      expiresInMs: SPARDA_CONFIRM_TTL_MS,
+      preview: {
+        tool,
+        method: spec.method,
+        path: spec.path,
+        willSendBody: spec.method !== 'GET' && args.body !== undefined,
+        reversibleHint: proof.checks.reversibleHint,
+        inspectFirst: siblingName ? { tool: siblingName, why: 'GET on the same path — read current state before committing this write' } : null,
+      },
+      // this string is what the LLM reads: the security decision IS the instruction.
+      instruction: `NOT EXECUTED. ${spec.method} ${spec.path} is gated by policy (${proof.reasons[0] || 'require_human'}); the host route was not touched.${siblingName ? ` First call "${siblingName}" to inspect current state, then` : ' To'} confirm via POST /invoke/confirm { "confirm": "${confirm}" }. Single-use, expires in ${Math.round(SPARDA_CONFIRM_TTL_MS / 1000)}s.`,
+      spardingProof: proof,
     });
-    const query = [];
-    for (const [k, v] of Object.entries(args)) {
-      if (k === 'body' || spec.pathParams.includes(k) || v === undefined) continue;
-      query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
-    }
-    if (query.length) url += `?${query.join('&')}`;
+  }
 
-    const init = { method: spec.method, headers: {} };
-    if (spec.method !== 'GET' && args.body !== undefined) {
-      init.headers['content-type'] = 'application/json';
-      init.body = JSON.stringify(args.body);
-    }
-    SPARDA_RECYCLE.paidFull += 1; // the host route is about to be exercised — full price
-    const upstream = await fetch(`http://127.0.0.1:${SPARDA_PORT}${url}`, { ...init, signal: AbortSignal.timeout(30_000) });
-    const text = await upstream.text();
-    let data; try { data = JSON.parse(text); } catch { data = text; }
-    spardaRecord(tool, upstream.status, Date.now() - t0);
-    if (spec.method === 'GET' && upstream.status === 200) {
-      // canonical argsig: sorted entries, so the AI's argument order never splits a signature
-      spardaObservePurity(tool, JSON.stringify(Object.entries(args).filter((e__ANY_TYPE__) => e[1] !== undefined).sort()), text);
-    }
-    if (upstream.status >= 500) spardaEvent('invoke', tool, upstream.status, text.slice(0, 200));
-    return res.status(200).json({ upstreamStatus: upstream.status, data, spardingProof: proof });
-  } catch (err__ANY_TYPE__) {
-    spardaRecord(tool, err.status ?? 502, Date.now() - t0);
-    spardaEvent('invoke', tool, err.status ?? 502, err.message);
-    return res.status(err.status ?? 502).json({ error: err.message, spardingProof: proof });
+  // proof.decision === 'allow' — exercise the host route
+  return spardaExecute(tool, spec, args, proof, t0, res);
+});
+
+spardaRouter.post('/invoke/confirm', SPARDA_JSON, async (req__REQ_TYPE__, res__RES_TYPE__) => {
+  const t0 = Date.now();
+  const confirm = (req.body ?? {}).confirm;
+  if (typeof confirm !== 'string' || !confirm) {
+    return res.status(400).json({ error: 'missing confirm token (expected { confirm: "..." })' });
   }
+  spardaSweepPending();
+  const pending = SPARDA_PENDING[confirm];
+  if (pending) delete SPARDA_PENDING[confirm]; // consume first — a token can never replay
+  if (!pending) {
+    return res.status(409).json({ error: 'unknown or expired confirmation token', hint: 're-issue the write via /invoke to mint a fresh token' });
+  }
+  if (Date.now() > pending.expiresAt) {
+    return res.status(409).json({ error: 'confirmation token expired', hint: 're-issue the write via /invoke' });
+  }
+  const spec = SPARDA_TOOLS[pending.tool];
+  // re-judge at commit time: the tool may have been quarantined or disabled since minting
+  const proof = spardaProof(pending.tool, spec, pending.args);
+  if (proof.decision === 'block') {
+    return res.status(403).json({ error: 'confirmation no longer valid', reason: proof.reasons[0] || 'blocked', spardingProof: proof });
+  }
+  spardaEvent('confirm', pending.tool, 200, 'confirmed -> executing');
+  return spardaExecute(pending.tool, spec, pending.args, proof, t0, res);
 });
 
+// verb safety: any non-POST on the invoke endpoints returns JSON 405 (was bare Express HTML — bug #5)
+spardaRouter.all('/invoke', (req__REQ_TYPE__, res__RES_TYPE__) => res.status(405).json({ error: 'method not allowed', allow: 'POST' }));
+spardaRouter.all('/invoke/confirm', (req__REQ_TYPE__, res__RES_TYPE__) => res.status(405).json({ error: 'method not allowed', allow: 'POST' }));
+
 function spardaRecord(tool__ANY_TYPE__, status__ANY_TYPE__, ms__ANY_TYPE__) {
   const st = SPARDA_STATS[tool] ?? (SPARDA_STATS[tool] = { calls: 0, errors: 0, clientErrors: 0, totalMs: 0, lastStatus: null, lastTs: null, consecutive5xx: 0 });
   // innate immunity: latency far beyond the learned baseline is an antigen
@@ -304,3 +454,24 @@ function spardaRecord(tool__ANY_TYPE__, status__ANY_TYPE__, ms__ANY_TYPE__) {
     spardaEvent('immune', tool, 503, `quarantined after ${st.consecutive5xx} consecutive 5xx (cooldown ${SPARDA_QUARANTINE_MS}ms)`);
   }
 }
+
+// anything unmatched under the router → JSON 404, never bare Express HTML
+spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__) => res.status(404).json({ error: 'not found', path: req.path }));
+
+// error envelope (must stay last). body-parser throws SyntaxError on malformed JSON, and
+// anything thrown downstream used to fall through to Express' HTML error page — leaking the
+// internal stack trace. Every response stays JSON; the stack stays server-side, correlated
+// to /events by errorId.
+spardaRouter.use((err__ANY_TYPE__, req__REQ_TYPE__, res__RES_TYPE__, _next__NEXT_TYPE__) => {
+  const errorId = 'err_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+  spardaEvent('router', null, (err && err.status) || 500, `[${errorId}] ${err && err.message ? err.message : err}`);
+  const status = err && (err.type === 'entity.parse.failed' || err instanceof SyntaxError) ? 400 : (err && err.status) || 500;
+  res.status(status).json({ error: status === 400 ? 'invalid JSON body' : 'internal error', errorId });
+});
+
+// start gossiping only when peers are configured — solo deployments pay nothing (zero infra).
+// .unref(): the tick timer never keeps the host process alive on its own.
+if (SPARDA_PEERS.length > 0) {
+  spardaEvent('gossip', null, null, `horizontal scale: gossiping to ${SPARDA_PEERS.length} peer(s) every ${SPARDA_GOSSIP_MS}ms`);
+  setInterval(spardaGossipTick, SPARDA_GOSSIP_MS).unref();
+}

package/templates/fastapi-router.txt

@@ -14,6 +14,7 @@ import time
 import datetime
 import os
 import zlib
+import threading
 
 # json.loads, not a Python literal: JSON true/false/null are not valid Python (E-009)
 SPARDA_TOOLS = json.loads(__TOOLS_JSON__)
@@ -32,6 +33,23 @@ SPARDA_QUARANTINE_MS = int(os.environ.get("SPARDA_QUARANTINE_MS", "60000"))
 # Day 1 it reads 0% — the circle fills with usage (a measure, never a promise).
 SPARDA_RECYCLE = {"servedByCircle": 0, "paidFull": 0}
 
+# two-phase commit: a write/delete flagged require_human is NOT executed on /invoke.
+# It mints a single-use nonce + a preview contract; the host route is touched only after
+# an explicit /invoke/confirm replays the token.
+SPARDA_PENDING = {}
+SPARDA_CONFIRM_TTL_MS = int(os.environ.get("SPARDA_CONFIRM_TTL_MS", "120000"))
+
+def sparda_nonce():
+    import base64
+    import uuid
+    return "cfm_" + base64.urlsafe_b64encode(uuid.uuid4().bytes).decode("ascii").rstrip("=")
+
+def sparda_sweep_pending():
+    now = time.time() * 1000
+    expired = [k for k, v in SPARDA_PENDING.items() if now > v["expiresAt"]]
+    for k in expired:
+        del SPARDA_PENDING[k]
+
 def sparda_recycle_rate():
     total = SPARDA_RECYCLE["servedByCircle"] + SPARDA_RECYCLE["paidFull"]
     return round(SPARDA_RECYCLE["servedByCircle"] * 100 / total) if total else 0
@@ -43,7 +61,10 @@ SPARDA_PURITY = {}
 
 def sparda_observe_purity(tool, argsig, body_bytes):
     pu = SPARDA_PURITY.setdefault(tool, {"sigs": {}, "repeats": 0, "mismatches": 0})
-    h = zlib.crc32(body_bytes[:65536])  # a fingerprint, not a checksum of megabytes
+    # memoryview slice is zero-copy: crc32 reads the first 64KB in place, with no
+    # transient 64KB bytes copy per GET+200 (HFT technique 3, the one that fits the
+    # proxy router — same fingerprint, one fewer allocation on the response path).
+    h = zlib.crc32(memoryview(body_bytes)[:65536])  # a fingerprint, not a checksum of megabytes
     known = pu["sigs"].get(argsig)
     if known is None:
         if len(pu["sigs"]) >= 20:  # bounded: enough sigs to judge
@@ -73,6 +94,74 @@ def sparda_purity_snapshot():
         out[name] = {"class": cls, "repeats": pu["repeats"] if pu else 0, "mismatches": pu["mismatches"] if pu else 0}
     return out
 
+# ── horizontal scale (Brief #2): Quorum Sensing × G-Map CRDT ──────────────────
+# Same mechanism as the Express router, Python side. N replicas gossip their grow-only
+# purity counts so a route observed-pure on ANY replica converges everywhere — no
+# coordinator, no store, stdlib only. Solo (no SPARDA_PEERS) starts no thread, costs
+# nothing. Merge = max() per counter (commutative/associative/idempotent). value-free:
+# only tool NAMES (already public via /tools) and integer counts cross the wire.
+SPARDA_PEERS = [p.strip().rstrip("/") for p in os.environ.get("SPARDA_PEERS", "").split(",") if p.strip().startswith("http")]
+try:
+    SPARDA_GOSSIP_INTERVAL = max(50, int(os.environ.get("SPARDA_GOSSIP_MS", "30000"))) / 1000.0
+except ValueError:
+    SPARDA_GOSSIP_INTERVAL = 30.0
+try:
+    SPARDA_GOSSIP_TIMEOUT = max(1, int(os.environ.get("SPARDA_GOSSIP_TIMEOUT_MS", "2000")) // 1000)
+except ValueError:
+    SPARDA_GOSSIP_TIMEOUT = 2
+
+def sparda_gossip_snapshot():
+    # per-tool {repeats, mismatches} — both monotonic, safe to max-merge.
+    # dict(SPARDA_PURITY) is an atomic C-level copy under the GIL: the push runs on a daemon
+    # thread while the event loop mutates SPARDA_PURITY, so we never iterate the live dict
+    # (that would risk "dictionary changed size during iteration"). The int reads are atomic.
+    return {name: {"repeats": pu["repeats"], "mismatches": pu["mismatches"]} for name, pu in dict(SPARDA_PURITY).items()}
+
+def sparda_merge_gossip(remote):
+    # max() per counter, ONLY for known tools (bounded; unknown/injected keys ignored).
+    # bool is a subclass of int in Python — reject it so a JSON `true` can't pose as a count.
+    if not isinstance(remote, dict):
+        return 0
+    merged = 0
+    for name, rv in remote.items():
+        if name not in SPARDA_TOOLS or not isinstance(rv, dict):
+            continue
+        r = rv.get("repeats")
+        m = rv.get("mismatches")
+        if not isinstance(r, int) or isinstance(r, bool) or r < 0:
+            continue
+        if not isinstance(m, int) or isinstance(m, bool) or m < 0:
+            continue
+        pu = SPARDA_PURITY.setdefault(name, {"sigs": {}, "repeats": 0, "mismatches": 0})
+        if r > pu["repeats"]:
+            pu["repeats"] = r          # grow-only: never shrinks on merge
+        if m > pu["mismatches"]:
+            pu["mismatches"] = m       # a mismatch anywhere → volatile everywhere (safe)
+        merged += 1
+    return merged
+
+def sparda_gossip_push():
+    # one round: push our snapshot to every peer. Fire-and-forget, off the request path.
+    if not SPARDA_PEERS:
+        return
+    payload = json.dumps(sparda_gossip_snapshot()).encode("utf-8")
+    for peer in SPARDA_PEERS:
+        try:
+            req = urllib.request.Request(
+                peer + "/mcp/gossip",
+                data=payload,
+                headers={"content-type": "application/json", "x-sparda-key": SPARDA_LOCAL_KEY},
+                method="POST",
+            )
+            urllib.request.urlopen(req, timeout=SPARDA_GOSSIP_TIMEOUT).close()
+        except Exception:
+            pass  # peer down → silence; the next tick retries (eventual convergence)
+
+def _sparda_gossip_loop():
+    while True:
+        time.sleep(SPARDA_GOSSIP_INTERVAL)
+        sparda_gossip_push()
+
 def sparda_event(source, tool, status, message):
     global SPARDA_SEQ
     SPARDA_SEQ += 1
@@ -263,6 +352,20 @@ async def get_events(request: Request):
         since = 0
     return {"seq": SPARDA_SEQ, "events": [e for e in SPARDA_EVENTS if e["seq"] > since]}
 
+@sparda_router.post("/gossip")
+async def gossip(request: Request):
+    # peer-to-peer convergence (Brief #2), behind the same x-sparda-key as every route.
+    # Absorbs a peer's grow-only counts via CRDT max-merge; 204 on success. An unknown tool
+    # or malformed count is silently dropped (bounded, no injection).
+    if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=401, content={"error": "unauthorized"})
+    try:
+        body = await request.json()
+    except Exception:
+        body = {}
+    sparda_merge_gossip(body)
+    return Response(status_code=204)
+
 @sparda_router.post("/invoke")
 async def invoke_tool(request: Request):
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
@@ -314,6 +417,45 @@ async def invoke_tool(request: Request):
                 status = 403
         return JSONResponse(status_code=status, content={"error": error, "spardingProof": proof})
 
+    if proof["decision"] == "require_human":
+        sparda_sweep_pending()
+        confirm = sparda_nonce()
+        SPARDA_PENDING[confirm] = {
+            "tool": tool,
+            "args": args,
+            "expiresAt": time.time() * 1000 + SPARDA_CONFIRM_TTL_MS,
+            "createdAt": datetime.datetime.now(datetime.timezone.utc).isoformat()
+        }
+        sibling_name = None
+        for n, t in SPARDA_TOOLS.items():
+            if t.get("method") == "GET" and t.get("path") == spec.get("path"):
+                sibling_name = n
+                break
+        # Build the conditional hint OUTSIDE the instruction f-string below: on
+        # Python < 3.12 an f-string expression part may not contain a backslash
+        # or the delimiting quote (PEP 701 lifted this in 3.12). Pre-computing it
+        # here keeps the generated router valid on every supported Python (3.9+).
+        sparda_hint = (
+            f' First call "{sibling_name}" to inspect current state, then'
+            if sibling_name else ' To'
+        )
+        sparda_event("confirm", tool, 202, f"gated, awaiting confirmation (risk: {proof['risk']})")
+        return JSONResponse(status_code=202, content={
+            "status": "awaiting_confirmation",
+            "confirm": confirm,
+            "expiresInMs": SPARDA_CONFIRM_TTL_MS,
+            "preview": {
+                "tool": tool,
+                "method": spec.get("method"),
+                "path": spec.get("path"),
+                "willSendBody": spec.get("method") != "GET" and args.get("body") is not None,
+                "reversibleHint": proof["checks"]["reversibleHint"],
+                "inspectFirst": {"tool": sibling_name, "why": "GET on the same path — read current state before committing this write"} if sibling_name else None,
+            },
+            "instruction": f"NOT EXECUTED. {spec.get('method')} {spec.get('path')} is gated by policy ({proof['reasons'][0] if proof['reasons'] else 'require_human'}); the host route was not touched.{sparda_hint} confirm via POST /invoke/confirm {{ \"confirm\": \"{confirm}\" }}. Single-use, expires in {round(SPARDA_CONFIRM_TTL_MS / 1000)}s.",
+            "spardingProof": proof,
+        })
+
     t0 = time.time()
     try:
         path_params = spec.get("pathParams", [])
@@ -369,3 +511,98 @@ async def invoke_tool(request: Request):
         sparda_record(tool, 502, round((time.time() - t0) * 1000))
         sparda_event("invoke", tool, 502, str(e))
         return JSONResponse(status_code=502, content={"error": str(e), "spardingProof": proof})
+
+@sparda_router.post("/invoke/confirm")
+async def confirm_tool_invocation(request: Request):
+    if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=401, content={"error": "unauthorized"})
+    
+    t0 = time.time()
+    try:
+        body = await request.json()
+    except Exception:
+        body = {}
+        
+    confirm = body.get("confirm")
+    if not isinstance(confirm, str) or not confirm:
+        return JSONResponse(status_code=400, content={"error": "missing confirm token (expected { confirm: \"...\" })"})
+        
+    sparda_sweep_pending()
+    pending = SPARDA_PENDING.get(confirm)
+    if pending:
+        del SPARDA_PENDING[confirm] # consume first
+    
+    if not pending:
+        return JSONResponse(status_code=409, content={"error": "unknown or expired confirmation token", "hint": "re-issue the write via /invoke to mint a fresh token"})
+        
+    if time.time() * 1000 > pending["expiresAt"]:
+        return JSONResponse(status_code=409, content={"error": "confirmation token expired", "hint": "re-issue the write via /invoke"})
+        
+    spec = SPARDA_TOOLS.get(pending["tool"])
+    proof = sparda_proof(pending["tool"], spec, pending["args"])
+    
+    if proof["decision"] == "block":
+        return JSONResponse(status_code=403, content={"error": "confirmation no longer valid", "reason": proof["reasons"][0] if proof["reasons"] else "blocked", "spardingProof": proof})
+        
+    sparda_event("confirm", pending["tool"], 200, "confirmed -> executing")
+    
+    try:
+        path_params = spec.get("pathParams", [])
+        path = spec.get("path")
+
+        def repl(match):
+            name = match.group(1)
+            val = pending["args"].get(name)
+            return urllib.parse.quote(str(val))
+
+        resolved_path = re.sub(r'\{(\w+)\}', repl, path)
+
+        query_params = []
+        for k, v in pending["args"].items():
+            if k == 'body' or k in path_params or v is None:
+                continue
+            query_params.append(f"{urllib.parse.quote(k)}={urllib.parse.quote(str(v))}")
+        
+        if query_params:
+            resolved_path += "?" + "&".join(query_params)
+
+        url = f"http://127.0.0.1:{SPARDA_PORT}{resolved_path}"
+        method = spec.get("method", "GET")
+        
+        headers = {}
+        body_bytes = None
+        
+        if method != "GET" and pending["args"].get("body") is not None:
+            headers["content-type"] = "application/json"
+            body_bytes = json.dumps(pending["args"]["body"]).encode("utf-8")
+
+        SPARDA_RECYCLE["paidFull"] += 1
+        loop = asyncio.get_running_loop()
+        status, content_type, data_bytes = await loop.run_in_executor(
+            executor, sync_fetch, url, method, headers, body_bytes
+        )
+        
+        text_data = data_bytes.decode("utf-8", errors="ignore")
+        try:
+            data = json.loads(text_data)
+        except Exception:
+            data = text_data
+
+        sparda_record(pending["tool"], status, round((time.time() - t0) * 1000))
+        if method == "GET" and status == 200:
+            argsig = json.dumps(sorted((k, str(v)) for k, v in pending["args"].items() if v is not None))
+            sparda_observe_purity(pending["tool"], argsig, data_bytes)
+        if status >= 500:
+            sparda_event("invoke", pending["tool"], status, text_data[:200])
+        return {"upstreamStatus": status, "data": data, "spardingProof": proof}
+    except Exception as e:
+        sparda_record(pending["tool"], 502, round((time.time() - t0) * 1000))
+        sparda_event("invoke", pending["tool"], 502, str(e))
+        return JSONResponse(status_code=502, content={"error": str(e), "spardingProof": proof})
+
+# start gossiping only when peers are configured — solo deployments pay nothing (zero infra).
+# daemon=True: the background thread never blocks interpreter shutdown.
+if SPARDA_PEERS:
+    sparda_event("gossip", None, None, f"horizontal scale: gossiping to {len(SPARDA_PEERS)} peer(s) every {SPARDA_GOSSIP_INTERVAL}s")
+    threading.Thread(target=_sparda_gossip_loop, daemon=True).start()
+