@algosuite/vo-mcp 0.1.0 → 0.2.0-beta.0

package/dist/index.js

@@ -1,4 +1,291 @@
 import { createRequire as __cr } from 'module'; const require = __cr(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/cloud/auth-token-source.ts
+var auth_token_source_exports = {};
+__export(auth_token_source_exports, {
+  FIREBASE_SECURETOKEN_URL: () => FIREBASE_SECURETOKEN_URL,
+  FIREBASE_TOKEN_REFERER: () => FIREBASE_TOKEN_REFERER,
+  createAuthTokenSourceFromEnv: () => createAuthTokenSourceFromEnv,
+  createFirebaseRefreshTokenSource: () => createFirebaseRefreshTokenSource,
+  createStaticTokenSource: () => createStaticTokenSource
+});
+function createStaticTokenSource(token, kind = "admin-token") {
+  const value = token.trim();
+  return { kind, getToken: async () => value.length > 0 ? value : null };
+}
+function createFirebaseRefreshTokenSource(opts) {
+  const refreshToken = opts.refreshToken.trim();
+  const apiKey = opts.apiKey.trim();
+  const now = opts.now ?? (() => Date.now());
+  const fetchFn = opts.fetchFn ?? globalThis.fetch;
+  let cachedToken = null;
+  let expiresAtMs = 0;
+  let inFlight = null;
+  async function refresh() {
+    try {
+      const res = await fetchFn(`${FIREBASE_SECURETOKEN_URL}?key=${encodeURIComponent(apiKey)}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          referer: FIREBASE_TOKEN_REFERER
+        },
+        body: `grant_type=refresh_token&refresh_token=${encodeURIComponent(refreshToken)}`
+      });
+      const text = await res.text();
+      if (res.status < 200 || res.status >= 300) {
+        cachedToken = null;
+        return null;
+      }
+      const parsed = JSON.parse(text);
+      const idToken = typeof parsed.id_token === "string" ? parsed.id_token : "";
+      if (!idToken) {
+        cachedToken = null;
+        return null;
+      }
+      const expiresInSec = Number(parsed.expires_in);
+      const ttlMs = Number.isFinite(expiresInSec) && expiresInSec > 0 ? expiresInSec * 1e3 : 36e5;
+      cachedToken = idToken;
+      expiresAtMs = now() + ttlMs;
+      return idToken;
+    } catch {
+      cachedToken = null;
+      return null;
+    }
+  }
+  return {
+    kind: "firebase-refresh",
+    async getToken() {
+      if (cachedToken && now() < expiresAtMs - REFRESH_SKEW_MS) return cachedToken;
+      if (!inFlight) {
+        inFlight = refresh().finally(() => {
+          inFlight = null;
+        });
+      }
+      return inFlight;
+    }
+  };
+}
+function createAuthTokenSourceFromEnv(env = process.env, fetchFn, readStoredCred = () => null) {
+  const refreshToken = env["VO_USER_REFRESH_TOKEN"]?.trim();
+  const apiKey = env["VO_FIREBASE_API_KEY"]?.trim();
+  const idToken = env["VO_USER_ID_TOKEN"]?.trim();
+  const adminToken = env["VO_CONTROL_PLANE_ADMIN_TOKEN"]?.trim();
+  if (refreshToken || apiKey) {
+    if (!refreshToken || !apiKey) {
+      throw new Error(
+        "Per-user refresh auth requires BOTH VO_USER_REFRESH_TOKEN and VO_FIREBASE_API_KEY"
+      );
+    }
+    return createFirebaseRefreshTokenSource({
+      refreshToken,
+      apiKey,
+      ...fetchFn ? { fetchFn } : {}
+    });
+  }
+  if (idToken) return createStaticTokenSource(idToken, "firebase-id-token");
+  const stored = readStoredCred();
+  if (stored?.vo_credential && stored.vo_credential.trim()) {
+    return createStaticTokenSource(stored.vo_credential.trim(), "vo-credential");
+  }
+  if (stored && stored.refresh_token?.trim() && stored.api_key?.trim()) {
+    return createFirebaseRefreshTokenSource({
+      refreshToken: stored.refresh_token.trim(),
+      apiKey: stored.api_key.trim(),
+      ...fetchFn ? { fetchFn } : {}
+    });
+  }
+  if (adminToken) return createStaticTokenSource(adminToken, "admin-token");
+  return null;
+}
+var FIREBASE_SECURETOKEN_URL, FIREBASE_TOKEN_REFERER, REFRESH_SKEW_MS;
+var init_auth_token_source = __esm({
+  "src/cloud/auth-token-source.ts"() {
+    "use strict";
+    FIREBASE_SECURETOKEN_URL = "https://securetoken.googleapis.com/v1/token";
+    FIREBASE_TOKEN_REFERER = "https://algosuite.ai/";
+    REFRESH_SKEW_MS = 6e4;
+  }
+});
+
+// src/cloud/keychain.ts
+import { createRequire } from "node:module";
+function loadKeyring() {
+  if (cached !== void 0) return cached;
+  try {
+    const req = createRequire(import.meta.url);
+    const mod = req("@napi-rs/keyring");
+    cached = mod && typeof mod.Entry === "function" ? mod : null;
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+function keychainAvailable() {
+  return loadKeyring() !== null;
+}
+function keychainGet() {
+  const k = loadKeyring();
+  if (!k) return null;
+  try {
+    return new k.Entry(SERVICE, ACCOUNT).getPassword();
+  } catch {
+    return null;
+  }
+}
+function keychainSet(secret) {
+  const k = loadKeyring();
+  if (!k) return false;
+  try {
+    new k.Entry(SERVICE, ACCOUNT).setPassword(secret);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function keychainDelete() {
+  const k = loadKeyring();
+  if (!k) return false;
+  try {
+    return new k.Entry(SERVICE, ACCOUNT).deletePassword();
+  } catch {
+    return false;
+  }
+}
+var SERVICE, ACCOUNT, cached;
+var init_keychain = __esm({
+  "src/cloud/keychain.ts"() {
+    "use strict";
+    SERVICE = "vo-mcp";
+    ACCOUNT = "refresh-credential";
+  }
+});
+
+// src/cloud/credential-store.ts
+var credential_store_exports = {};
+__export(credential_store_exports, {
+  KEYCHAIN_LOCATION: () => KEYCHAIN_LOCATION,
+  credentialPath: () => credentialPath,
+  readStoredCredential: () => readStoredCredential,
+  writeStoredCredential: () => writeStoredCredential
+});
+import { homedir as homedir3 } from "node:os";
+import { join as join5, dirname as dirname4 } from "node:path";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync5,
+  writeFileSync as writeFileSync2,
+  chmodSync as chmodSync2,
+  rmSync
+} from "node:fs";
+function credentialPath(env = process.env) {
+  const override = env["VO_MCP_CREDENTIALS_PATH"]?.trim();
+  if (override) return override;
+  return join5(homedir3(), ".config", "vo-mcp", "credentials.json");
+}
+function keychainEnabled(env, keychain) {
+  const disabled = (env["VO_MCP_DISABLE_KEYCHAIN"] ?? "").trim().toLowerCase();
+  if (disabled === "1" || disabled === "true" || disabled === "yes") return false;
+  return keychain.available();
+}
+function deserialize(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    const refresh = typeof parsed.refresh_token === "string" ? parsed.refresh_token.trim() : "";
+    const apiKey = typeof parsed.api_key === "string" ? parsed.api_key.trim() : "";
+    const voCred = typeof parsed.vo_credential === "string" ? parsed.vo_credential.trim() : "";
+    if (!voCred && (!refresh || !apiKey)) return null;
+    return {
+      ...refresh ? { refresh_token: refresh } : {},
+      ...apiKey ? { api_key: apiKey } : {},
+      ...voCred ? { vo_credential: voCred } : {},
+      ...typeof parsed.vo_credential_expires_at === "string" ? { vo_credential_expires_at: parsed.vo_credential_expires_at } : {},
+      ...typeof parsed.email === "string" ? { email: parsed.email } : {},
+      ...typeof parsed.stored_at === "string" ? { stored_at: parsed.stored_at } : {}
+    };
+  } catch {
+    return null;
+  }
+}
+function readFromFile(env) {
+  try {
+    const p = credentialPath(env);
+    if (!existsSync3(p)) return null;
+    return deserialize(readFileSync5(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function readStoredCredential(env = process.env, keychain = realKeychain) {
+  if (keychainEnabled(env, keychain)) {
+    const raw = keychain.get();
+    const fromKeychain = raw ? deserialize(raw) : null;
+    if (fromKeychain) return fromKeychain;
+  }
+  return readFromFile(env);
+}
+function deleteFile(env) {
+  try {
+    rmSync(credentialPath(env), { force: true });
+  } catch {
+  }
+}
+function writeToFile(payload, env) {
+  const p = credentialPath(env);
+  mkdirSync2(dirname4(p), { recursive: true });
+  writeFileSync2(p, `${JSON.stringify(payload, null, 2)}
+`, { mode: 384 });
+  try {
+    chmodSync2(p, 384);
+  } catch {
+  }
+  return p;
+}
+function writeStoredCredential(cred, storedAt, env = process.env, keychain = realKeychain) {
+  const payload = {
+    ...cred.refresh_token ? { refresh_token: cred.refresh_token } : {},
+    ...cred.api_key ? { api_key: cred.api_key } : {},
+    ...cred.vo_credential ? { vo_credential: cred.vo_credential } : {},
+    ...cred.vo_credential_expires_at ? { vo_credential_expires_at: cred.vo_credential_expires_at } : {},
+    ...cred.email ? { email: cred.email } : {},
+    stored_at: cred.stored_at ?? storedAt
+  };
+  if (keychainEnabled(env, keychain) && keychain.set(JSON.stringify(payload))) {
+    deleteFile(env);
+    return KEYCHAIN_LOCATION;
+  }
+  const p = writeToFile(payload, env);
+  if (keychainEnabled(env, keychain)) keychain.delete();
+  return p;
+}
+var realKeychain, KEYCHAIN_LOCATION;
+var init_credential_store = __esm({
+  "src/cloud/credential-store.ts"() {
+    "use strict";
+    init_keychain();
+    realKeychain = {
+      available: keychainAvailable,
+      get: keychainGet,
+      set: keychainSet,
+      delete: keychainDelete
+    };
+    KEYCHAIN_LOCATION = 'OS keychain (service "vo-mcp")';
+  }
+});
 
 // src/server.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
@@ -987,10 +1274,10 @@ async function handleCheckAssertionStrength(deps, rawInput, _signal) {
   const key = deps.cache.keyFor(TOOL_NAME, rawInput);
   const excerpt = rawInput.source.slice(0, 300);
   const inputSizeBytes = bytesOf(rawInput.source);
-  const cached = deps.cache.get(key);
-  if (cached) {
+  const cached2 = deps.cache.get(key);
+  if (cached2) {
     const envelope2 = {
-      ...cached.value,
+      ...cached2.value,
       cache: { hit: true, key }
     };
     deps.events.append({
@@ -1210,8 +1497,8 @@ async function handleCheckHollowTest(deps, rawInput, signal) {
   const key = deps.cache.keyFor(TOOL_NAME2, rawInput);
   const excerpt = rawInput.source.slice(0, 300);
   const inputSizeBytes = bytesOf(rawInput.source);
-  const cached = deps.cache.get(key);
-  if (cached !== null) {
+  const cached2 = deps.cache.get(key);
+  if (cached2 !== null) {
     const replayEvent = {
       ...buildBaseEvent({
         tool: TOOL_NAME2,
@@ -1222,14 +1509,14 @@ async function handleCheckHollowTest(deps, rawInput, signal) {
         session: deps.session,
         now: deps.now()
       }),
-      per_model_verdicts: cached.value.payload.per_model_verdicts,
-      synthesized_verdict: cached.value.payload.synthesized_verdict ?? null,
-      consensus_confidence: cached.value.payload.synthesized_verdict?.confidence ?? null,
-      consensus_engine_version: cached.value.payload.engine_version ?? null,
+      per_model_verdicts: cached2.value.payload.per_model_verdicts,
+      synthesized_verdict: cached2.value.payload.synthesized_verdict ?? null,
+      consensus_confidence: cached2.value.payload.synthesized_verdict?.confidence ?? null,
+      consensus_engine_version: cached2.value.payload.engine_version ?? null,
       cache_hit: true
     };
     deps.events.append(replayEvent);
-    return jsonContent({ ...cached.value, cache: { hit: true, key } });
+    return jsonContent({ ...cached2.value, cache: { hit: true, key } });
   }
   const kbResult = findRulesByMetadata({ category: "testing" });
   const { topRules, truncated: kbTruncated } = prepareKBRules(kbResult.rules);
@@ -1394,8 +1681,8 @@ async function handleVerifyAnswer(deps, rawInput, signal) {
   const isDeep = gateType === DEEP_GATE;
   const kbResult = isDeep ? findRulesByMetadata({ category: "security" }) : { rules: [], error: null };
   const { topRules, truncated: kbTruncated } = prepareKBRules(kbResult.rules);
-  const cached = deps.cache.get(key);
-  if (cached !== null) {
+  const cached2 = deps.cache.get(key);
+  if (cached2 !== null) {
     const replayEvent = {
       ...buildBaseEvent({
         tool: TOOL_NAME3,
@@ -1406,14 +1693,14 @@ async function handleVerifyAnswer(deps, rawInput, signal) {
         session: deps.session,
         now: deps.now()
       }),
-      per_model_verdicts: cached.value.payload.per_model_verdicts,
-      synthesized_verdict: cached.value.payload.synthesized_verdict ?? null,
-      consensus_confidence: cached.value.payload.synthesized_verdict?.confidence ?? null,
-      consensus_engine_version: cached.value.payload.engine_version ?? null,
+      per_model_verdicts: cached2.value.payload.per_model_verdicts,
+      synthesized_verdict: cached2.value.payload.synthesized_verdict ?? null,
+      consensus_confidence: cached2.value.payload.synthesized_verdict?.confidence ?? null,
+      consensus_engine_version: cached2.value.payload.engine_version ?? null,
       cache_hit: true
     };
     deps.events.append(replayEvent);
-    return jsonContent({ ...cached.value, cache: { hit: true, key } });
+    return jsonContent({ ...cached2.value, cache: { hit: true, key } });
   }
   const baseEvent = buildBaseEvent({
     tool: TOOL_NAME3,
@@ -1519,6 +1806,45 @@ var ALL_RECOGNIZED_GATE_TYPES = [
   ...KNOWN_GATE_TYPES
 ];
 
+// src/tools/consensus-judgment-source-grounded.ts
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((e) => typeof e === "string");
+}
+function isToolSourceGrounded(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v;
+  if (o["enable_citation_grading"] !== void 0 && typeof o["enable_citation_grading"] !== "boolean") {
+    return false;
+  }
+  if (o["escalate_below"] !== void 0 && typeof o["escalate_below"] !== "number") return false;
+  return true;
+}
+function normalizeSourceGrounded(input) {
+  const sourceUrls = input.source_urls !== void 0 ? input.source_urls.filter((u) => u.trim().length > 0) : [];
+  const active = sourceUrls.length > 0;
+  const gradingEnabled = active && input.source_grounded?.enable_citation_grading === true;
+  const escalateBelow = input.source_grounded?.escalate_below;
+  const config = gradingEnabled ? {
+    citation_grader: {
+      enabled: true,
+      ...escalateBelow !== void 0 ? { escalate_below: escalateBelow } : {}
+    }
+  } : void 0;
+  const cacheFragments = {};
+  if (active) cacheFragments["source_urls"] = sourceUrls;
+  if (gradingEnabled) {
+    cacheFragments["citation_grading"] = true;
+    if (escalateBelow !== void 0) cacheFragments["escalate_below"] = escalateBelow;
+  }
+  return {
+    active,
+    sourceUrls,
+    gradingEnabled,
+    ...config !== void 0 ? { config } : {},
+    cacheFragments
+  };
+}
+
 // src/tools/consensus-judgment.ts
 var TOOL_NAME4 = "vo_consensus_judgment";
 var MAX_PROMPT_BYTES = 64 * 1024;
@@ -1541,6 +1867,26 @@ var inputSchema4 = {
       type: "object",
       description: "Tool-specific context (e.g. source file, diff, observed value).",
       additionalProperties: true
+    },
+    source_urls: {
+      type: "array",
+      items: { type: "string" },
+      description: "Authoritative source URLs to ground the judgment against (Tier-4). When NON-EMPTY, the engine routes to its source-grounded path: it fetches the sources, flags low-confidence retrievals (surfaced as low_confidence_sources), and \u2014 when source_grounded.enable_citation_grading is true \u2014 grades each claim against the cited source text. When absent/empty the call uses the unchanged sourceless consensus path."
+    },
+    source_grounded: {
+      type: "object",
+      description: "Optional source-grounded behaviour toggles. Only meaningful when source_urls is non-empty.",
+      properties: {
+        enable_citation_grading: {
+          type: "boolean",
+          description: "Opt IN to deterministic citation grading (default OFF). A failing grade raises an escalation signal, so this is behaviour-changing. When true, a real claim classifier (a single cheap model call) grades each claim against the cited sources."
+        },
+        escalate_below: {
+          type: "number",
+          description: "Uncertain-claim escalation floor [0..1]; an uncertain claim with confidence below this triggers escalation. Engine default 0.85 when omitted."
+        }
+      },
+      additionalProperties: false
     }
   },
   required: ["prompt"],
@@ -1552,6 +1898,8 @@ function isToolInput4(v) {
   const o = v;
   if (typeof o["prompt"] !== "string") return false;
   if (o["gate_type"] !== void 0 && typeof o["gate_type"] !== "string") return false;
+  if (o["source_urls"] !== void 0 && !isStringArray(o["source_urls"])) return false;
+  if (o["source_grounded"] !== void 0 && !isToolSourceGrounded(o["source_grounded"])) return false;
   return true;
 }
 function isAcceptedGateType(v) {
@@ -1577,15 +1925,20 @@ async function handleConsensusJudgment(deps, rawInput, signal) {
   const rawGate = rawInput.gate_type ?? DEFAULT_GATE_TYPE;
   const gateType = isAcceptedGateType(rawGate) ? rawGate : DEFAULT_GATE_TYPE;
   const inputSizeBytes = bytesOf(rawInput.prompt) + bytesOf(contextStrForSize);
+  const sg = normalizeSourceGrounded({
+    ...rawInput.source_urls !== void 0 ? { source_urls: rawInput.source_urls } : {},
+    ...rawInput.source_grounded !== void 0 ? { source_grounded: rawInput.source_grounded } : {}
+  });
   const cacheInput = {
     prompt: rawInput.prompt,
     gate_type: gateType,
-    ...rawInput.context !== void 0 ? { context: rawInput.context } : {}
+    ...rawInput.context !== void 0 ? { context: rawInput.context } : {},
+    ...sg.cacheFragments
   };
   const key = deps.cache.keyFor(TOOL_NAME4, cacheInput);
   const excerpt = rawInput.prompt.slice(0, 300);
-  const cached = deps.cache.get(key);
-  if (cached !== null) {
+  const cached2 = deps.cache.get(key);
+  if (cached2 !== null) {
     const replayEvent = buildBaseEvent({
       tool: TOOL_NAME4,
       gateType,
@@ -1597,15 +1950,15 @@ async function handleConsensusJudgment(deps, rawInput, signal) {
     });
     const enrichedReplay = {
       ...replayEvent,
-      per_model_verdicts: cached.value.payload.per_model_verdicts,
-      synthesized_verdict: cached.value.payload.synthesized_verdict ?? null,
-      consensus_confidence: cached.value.payload.synthesized_verdict?.confidence ?? null,
-      consensus_engine_version: cached.value.payload.engine_version ?? null,
+      per_model_verdicts: cached2.value.payload.per_model_verdicts,
+      synthesized_verdict: cached2.value.payload.synthesized_verdict ?? null,
+      consensus_confidence: cached2.value.payload.synthesized_verdict?.confidence ?? null,
+      consensus_engine_version: cached2.value.payload.engine_version ?? null,
       cache_hit: true
     };
     deps.events.append(enrichedReplay);
     const replayEnvelope = {
-      ...cached.value,
+      ...cached2.value,
       cache: { hit: true, key }
     };
     return jsonContent(replayEnvelope);
@@ -1626,7 +1979,9 @@ async function handleConsensusJudgment(deps, rawInput, signal) {
       gate_type: gateType,
       prompt: rawInput.prompt,
       ...rawInput.context !== void 0 ? { caller_context: rawInput.context } : {},
-      ...signal !== void 0 ? { signal } : {}
+      ...signal !== void 0 ? { signal } : {},
+      ...sg.active ? { source_urls: sg.sourceUrls } : {},
+      ...sg.config !== void 0 ? { source_grounded: sg.config } : {}
     });
   } catch (err) {
     engineThrew = true;
@@ -1679,7 +2034,23 @@ async function handleConsensusJudgment(deps, rawInput, signal) {
     synthesized_verdict: synthForEvent,
     engine_version: engineResult.engine_version,
     degraded: engineResult.degraded,
-    gate_type: gateType
+    gate_type: gateType,
+    // ─── Consensus-engine feature outputs (additive; 2026-06-13) ─────────────
+    // Feature 2 (calibrated-confidence) — ON by default; the engine attaches
+    // calibrated_confidence + confidence_badge to the synthesized verdict on the
+    // plain runConsensus path. Surface them at the top level so callers don't
+    // have to know the engine's internal SynthesizedVerdict shape.
+    ...engineResult.synthesized_verdict.calibrated_confidence !== void 0 ? { calibrated_confidence: engineResult.synthesized_verdict.calibrated_confidence } : {},
+    ...engineResult.synthesized_verdict.confidence_badge !== void 0 ? { confidence_badge: engineResult.synthesized_verdict.confidence_badge } : {},
+    // Feature 1 (agreement-gate) — fan-out diagnostics (present iff the gate ran).
+    ...engineResult.fan_out_diagnostics !== void 0 ? { fan_out_diagnostics: engineResult.fan_out_diagnostics } : {},
+    // Source-grounded Tier-4 outputs (present iff the call was source-grounded).
+    ...engineResult.source_grounded === true ? { source_grounded: true } : {},
+    ...engineResult.citation_grade !== void 0 ? { citation_grade: engineResult.citation_grade } : {},
+    ...engineResult.low_confidence_sources !== void 0 ? { low_confidence_sources: engineResult.low_confidence_sources } : {},
+    // Escalation (from citation grade or human-tiebreak synthesizer).
+    ...engineResult.escalation_required !== void 0 ? { escalation_required: engineResult.escalation_required } : {},
+    ...engineResult.escalation_reason !== void 0 ? { escalation_reason: engineResult.escalation_reason } : {}
   };
   const envelope = {
     tool: TOOL_NAME4,
@@ -1771,8 +2142,8 @@ async function handleArchitectureReview(deps, rawInput, signal) {
   const key = deps.cache.keyFor(TOOL_NAME5, cacheInput);
   const excerpt = rawInput.diff.slice(0, 300);
   const inputSizeBytes = bytesOf(rawInput.diff) + (rawInput.summary !== void 0 ? bytesOf(rawInput.summary) : 0);
-  const cached = deps.cache.get(key);
-  if (cached !== null) {
+  const cached2 = deps.cache.get(key);
+  if (cached2 !== null) {
     const replayEvent = {
       ...buildBaseEvent({
         tool: TOOL_NAME5,
@@ -1783,14 +2154,14 @@ async function handleArchitectureReview(deps, rawInput, signal) {
         session: deps.session,
         now: deps.now()
       }),
-      per_model_verdicts: cached.value.payload.per_model_verdicts,
-      synthesized_verdict: cached.value.payload.synthesized_verdict ?? null,
-      consensus_confidence: cached.value.payload.synthesized_verdict?.confidence ?? null,
-      consensus_engine_version: cached.value.payload.engine_version ?? null,
+      per_model_verdicts: cached2.value.payload.per_model_verdicts,
+      synthesized_verdict: cached2.value.payload.synthesized_verdict ?? null,
+      consensus_confidence: cached2.value.payload.synthesized_verdict?.confidence ?? null,
+      consensus_engine_version: cached2.value.payload.engine_version ?? null,
       cache_hit: true
     };
     deps.events.append(replayEvent);
-    return jsonContent({ ...cached.value, cache: { hit: true, key } });
+    return jsonContent({ ...cached2.value, cache: { hit: true, key } });
   }
   const kbResult = findRulesForDiff(rawInput.diff);
   const { topRules, truncated: kbTruncated } = prepareKBRules(kbResult.rules);
@@ -1902,8 +2273,11 @@ var ratchetIdSchema = z3.enum([
 ]);
 var thresholdSchema = z3.enum(["strict", "medium", "permissive"]);
 var userConfigSchema = z3.object({
-  enabled: z3.record(ratchetIdSchema, z3.boolean()).optional(),
-  thresholds: z3.record(ratchetIdSchema, thresholdSchema).optional(),
+  // zod v4: z.record with ENUM keys validates exhaustively (every key
+  // required); these are user OVERRIDE maps merged over DEFAULT_CONFIG,
+  // so partial-by-design — z.partialRecord restores the v3 semantics.
+  enabled: z3.partialRecord(ratchetIdSchema, z3.boolean()).optional(),
+  thresholds: z3.partialRecord(ratchetIdSchema, thresholdSchema).optional(),
   allowlist: z3.object({
     paths: z3.array(z3.string()).optional(),
     rules: z3.array(z3.string()).optional()
@@ -3205,8 +3579,8 @@ async function handleDecomposeDispatch(deps, rawInput, signal) {
   const key = deps.cache.keyFor(TOOL_NAME7, cacheInput);
   const excerpt = rawInput.customer_goal.slice(0, 300);
   const inputSizeBytes = bytesOf(rawInput.customer_goal) + bytesOf(contextStrForSize);
-  const cached = deps.cache.get(key);
-  if (cached !== null) {
+  const cached2 = deps.cache.get(key);
+  if (cached2 !== null) {
     const replayEvent = {
       ...buildBaseEvent({
         tool: TOOL_NAME7,
@@ -3217,7 +3591,7 @@ async function handleDecomposeDispatch(deps, rawInput, signal) {
         session: deps.session,
         now: deps.now()
       }),
-      per_model_verdicts: cached.value.payload.per_model_plans.map((p) => ({
+      per_model_verdicts: cached2.value.payload.per_model_plans.map((p) => ({
         model: p.model_id,
         model_id: p.model_id,
         provider: "cache-replay",
@@ -3230,12 +3604,12 @@ async function handleDecomposeDispatch(deps, rawInput, signal) {
         cited_sources: [],
         error: null
       })),
-      consensus_engine_version: cached.value.payload.engine_version ?? null,
+      consensus_engine_version: cached2.value.payload.engine_version ?? null,
       cache_hit: true
     };
     deps.events.append(replayEvent);
     const replayEnvelope = {
-      ...cached.value,
+      ...cached2.value,
       cache: { hit: true, key }
     };
     return jsonContent(replayEnvelope);
@@ -3343,22 +3717,9 @@ Produce the JSON dispatch plan now.`;
   return jsonContent(envelope);
 }
 
-// src/cloud/credential-store.ts
-import { homedir as homedir3 } from "node:os";
-import { join as join5, dirname as dirname4 } from "node:path";
-import {
-  existsSync as existsSync3,
-  mkdirSync as mkdirSync2,
-  readFileSync as readFileSync5,
-  writeFileSync as writeFileSync2,
-  chmodSync as chmodSync2,
-  rmSync
-} from "node:fs";
-
-// src/cloud/keychain.ts
-import { createRequire } from "node:module";
-
 // src/cloud/admin-callable-client.ts
+init_auth_token_source();
+init_credential_store();
 var AdminCallableError = class extends Error {
   constructor(status, path3, message) {
     super(message);
@@ -4178,7 +4539,7 @@ var inputSchema19 = {
   additionalProperties: false
 };
 var description19 = "Reports per-session context-window utilization to VO and returns a directive: 'continue' (under 70%), 'prepare_handoff' (70-84%), or 'execute_handoff_now' (\u226585%). Implements V1 launch gate #9 (fleet context lifecycle management) per the official VO roadmap. V1 backend is stub-local \u2014 computes the directive purely from `context_used_pct` against the documented thresholds without a network call. Phase 3 wires this to the deployed vo-control-plane HTTP API; the response shape stays stable across the cutover (`backend_mode` field in the payload tells the caller which mode produced the verdict).";
-function isStringArray(v, maxItems) {
+function isStringArray2(v, maxItems) {
   if (!Array.isArray(v)) return false;
   if (v.length > maxItems) return false;
   return v.every((item) => typeof item === "string");
@@ -4194,14 +4555,64 @@ function isToolInput19(v) {
   if (!Number.isFinite(o["context_used_pct"])) return false;
   if (o["context_used_pct"] < 0 || o["context_used_pct"] > 100) return false;
   if (o["current_goal"] !== void 0 && typeof o["current_goal"] !== "string") return false;
-  if (o["recent_files_touched"] !== void 0 && !isStringArray(o["recent_files_touched"], MAX_RECENT_FILES)) {
+  if (o["recent_files_touched"] !== void 0 && !isStringArray2(o["recent_files_touched"], MAX_RECENT_FILES)) {
     return false;
   }
-  if (o["recent_tool_uses"] !== void 0 && !isStringArray(o["recent_tool_uses"], MAX_RECENT_TOOLS)) {
+  if (o["recent_tool_uses"] !== void 0 && !isStringArray2(o["recent_tool_uses"], MAX_RECENT_TOOLS)) {
     return false;
   }
   return true;
 }
+function getCloudConfig() {
+  const url = process.env["VO_CONTROL_PLANE_URL"];
+  const token = process.env["VO_CONTROL_PLANE_ADMIN_TOKEN"];
+  if (!url || !token) return null;
+  return { url, token };
+}
+async function tryCloudReportState(cloud, input) {
+  try {
+    const body = {
+      context_used_pct: input.context_used_pct
+    };
+    if (input.current_goal !== void 0) body["current_goal"] = input.current_goal;
+    if (input.recent_files_touched !== void 0) {
+      body["recent_files_touched"] = input.recent_files_touched;
+    }
+    if (input.recent_tool_uses !== void 0) {
+      body["recent_tool_uses"] = input.recent_tool_uses;
+    }
+    const url = `${cloud.url}/api/v1/session/${input.session_id}/report-state`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${cloud.token}`
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const data = await response.json();
+    if (!data.ok || !data.session || !data.directive) {
+      return null;
+    }
+    return {
+      directive: data.directive.action,
+      message: data.directive.message,
+      session_id: data.session.session_id,
+      operator_id: data.session.operator_id,
+      agent_type: input.agent_type,
+      context_used_pct: data.session.context_used_pct,
+      backend_mode: "cloud-control-plane",
+      ts: data.session.last_seen_at,
+      schema_version: 1,
+      ...data.directive.action === "execute_handoff_now" ? { handoff_path: suggestedHandoffPath(data.session.session_id, data.session.last_seen_at) } : {}
+    };
+  } catch {
+    return null;
+  }
+}
 async function handleReportSessionState(deps, rawInput, _signal) {
   if (!isToolInput19(rawInput)) {
     throw invalidParams(
@@ -4209,6 +4620,13 @@ async function handleReportSessionState(deps, rawInput, _signal) {
       `invalid input. Required fields: operator_id (non-empty string), session_id (non-empty string), agent_type (one of: ${VALID_AGENT_TYPES.join(" | ")}), context_used_pct (number 0-100). Optional: current_goal (string \u2264${MAX_GOAL_CHARS} chars), recent_files_touched (string[] \u2264${MAX_RECENT_FILES}), recent_tool_uses (string[] \u2264${MAX_RECENT_TOOLS}).`
     );
   }
+  const cloud = getCloudConfig();
+  if (cloud !== null) {
+    const cloudPayload = await tryCloudReportState(cloud, rawInput);
+    if (cloudPayload !== null) {
+      return jsonContent(cloudPayload);
+    }
+  }
   const directive = computeDirective(rawInput.context_used_pct);
   const ts = deps.now().toISOString();
   const payload = {
@@ -4226,6 +4644,141 @@ async function handleReportSessionState(deps, rawInput, _signal) {
   return jsonContent(payload);
 }
 
+// src/tools/session/spawn-successor.ts
+import { spawn } from "node:child_process";
+import { homedir as homedir4 } from "node:os";
+import { join as join6 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, openSync, readFileSync as readFileSync6, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
+var TOOL_NAME20 = "vo_spawn_successor";
+var MAX_HANDOFF_BYTES = 64e3;
+var inputSchema20 = {
+  type: "object",
+  properties: {
+    handoff_path: {
+      type: "string",
+      description: "Path to the handoff doc to pre-inject. Default: the newest .md in ~/.vo/handoffs/."
+    },
+    goal: {
+      type: "string",
+      description: "Optional one-line goal override appended after the handoff."
+    },
+    cwd: {
+      type: "string",
+      description: "Working directory for the successor (default: the repo the handoff names, else process cwd)."
+    },
+    max_turns: {
+      type: "number",
+      description: "Optional --max-turns bound for the successor."
+    }
+  },
+  required: [],
+  additionalProperties: false
+};
+var description20 = "Mode B auto-handoff (roadmap \xA73.4): spawn a DETACHED headless `claude -p` successor with a handoff doc pre-injected into its prompt. Defaults to the newest handoff in ~/.vo/handoffs/. Returns {spawned, pid, log_path, handoff_path}. The successor works under the same gates as any session (ADR-001: verify-before-act, human merge approval) \u2014 this tool never fires autonomously.";
+function isToolInput20(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v;
+  if (o["handoff_path"] !== void 0 && typeof o["handoff_path"] !== "string") return false;
+  if (o["goal"] !== void 0 && typeof o["goal"] !== "string") return false;
+  if (o["cwd"] !== void 0 && typeof o["cwd"] !== "string") return false;
+  if (o["max_turns"] !== void 0 && typeof o["max_turns"] !== "number") return false;
+  return true;
+}
+function newestHandoff(dir = join6(homedir4(), ".vo", "handoffs")) {
+  try {
+    const entries = readdirSync3(dir).filter((f) => f.endsWith(".md")).map((f) => ({ f, m: statSync3(join6(dir, f)).mtimeMs })).sort((a, b) => b.m - a.m);
+    return entries.length > 0 && entries[0] ? join6(dir, entries[0].f) : null;
+  } catch {
+    return null;
+  }
+}
+var MANDATORY_READS = [
+  "CLAUDE.md + AGENTS.md + README.md (repo root)",
+  "docs/current/virtual-office-agent-charter.md, -operating-model.md, -test-architect.md",
+  "docs/current/evidence-grounded-consensus-testing.md",
+  "docs/vo/ADR-001-* (verify + sign, human approves merge; no autonomous bot-merge / headless triggers) + docs/vo/vo-adr-002-two-plane-moat.md",
+  "docs/vo/vo-roadmap-2026-05-26.md (read the Change log tail for current state)",
+  "the operator memory index ~/.claude/projects/C--Users-greyl/memory/MEMORY.md"
+];
+function buildSuccessorPrompt(handoffMarkdown, goal) {
+  const reads = MANDATORY_READS.map((r, i) => `  ${i + 1}. ${r}`).join("\n");
+  const lines = [
+    "You are the SUCCESSOR agent for a Virtual Office lane. The previous session",
+    "exhausted its context and wrote the handoff below. Read it fully, verify its",
+    '"verification needed" items against live state (a handoff is a claim, not',
+    "evidence \u2014 verify via `git show origin/main:<path>`), then continue the lane.",
+    "",
+    "MANDATORY READS before writing any code (NOT all auto-loaded \u2014 open them):",
+    reads,
+    "",
+    "NON-NEGOTIABLES: multi-model consensus verification is the core; test honesty",
+    "(verified-answer-only, no fake green); verify-before-act + human merge approval;",
+    "never a full functions-shared deploy; Gen2 only; work in a worktree on your own",
+    "branch; finish line is MERGED + DEPLOYED + LIVE-VERIFIED, and VO changes update",
+    "the roadmap in the same PR.",
+    "",
+    "--- HANDOFF ---",
+    handoffMarkdown,
+    "--- END HANDOFF ---"
+  ];
+  if (goal && goal.trim().length > 0) lines.push("", `OPERATOR GOAL OVERRIDE: ${goal.trim()}`);
+  return lines.join("\n");
+}
+function buildSuccessorArgs(maxTurns) {
+  const args = ["-p", "--permission-mode", "acceptEdits"];
+  if (Number.isInteger(maxTurns) && maxTurns > 0) {
+    args.push("--max-turns", String(maxTurns));
+  }
+  return args;
+}
+async function handleSpawnSuccessor(_deps, rawInput, _signal, spawnImpl = spawn) {
+  if (!isToolInput20(rawInput)) {
+    throw invalidParams(TOOL_NAME20, "invalid input. Optional: { handoff_path, goal, cwd, max_turns }.");
+  }
+  const handoffPath = rawInput.handoff_path?.trim() || newestHandoff();
+  if (!handoffPath || !existsSync4(handoffPath)) {
+    return jsonContent({
+      tool: TOOL_NAME20,
+      schema_version: 1,
+      payload: {
+        spawned: false,
+        reason: rawInput.handoff_path ? `handoff not found: ${rawInput.handoff_path}` : "no handoff docs in ~/.vo/handoffs \u2014 write one first (the 85% directive does this)"
+      }
+    });
+  }
+  const handoff = readFileSync6(handoffPath, "utf8").slice(0, MAX_HANDOFF_BYTES);
+  const prompt = buildSuccessorPrompt(handoff, rawInput.goal);
+  const logDir = process.env["VO_MCP_SUCCESSOR_LOG_DIR"]?.trim() || join6(homedir4(), ".vo", "successors");
+  mkdirSync3(logDir, { recursive: true });
+  const logPath = join6(logDir, `successor-${Date.now()}.log`);
+  const logFd = openSync(logPath, "a");
+  const child = spawnImpl("claude", buildSuccessorArgs(rawInput.max_turns), {
+    cwd: rawInput.cwd?.trim() || process.cwd(),
+    detached: true,
+    stdio: ["pipe", logFd, logFd],
+    // Windows: `claude` is a .cmd shim — needs a shell to resolve. The prompt
+    // goes via STDIN below, never argv, so the shell never sees it.
+    shell: process.platform === "win32",
+    windowsHide: true
+  });
+  let spawnError = null;
+  child.on("error", (e) => {
+    spawnError = e.message;
+  });
+  try {
+    child.stdin.write(prompt);
+    child.stdin.end();
+  } catch {
+  }
+  child.unref();
+  await new Promise((r) => setTimeout(r, 150));
+  return jsonContent({
+    tool: TOOL_NAME20,
+    schema_version: 1,
+    payload: spawnError ? { spawned: false, reason: `spawn failed: ${spawnError}`, handoff_path: handoffPath } : { spawned: true, pid: child.pid ?? null, log_path: logPath, handoff_path: handoffPath }
+  });
+}
+
 // src/tools/concierge/common-concierge.ts
 var CONCIERGE_STUB_REASON = "cloud mode not active in this MCP runtime \u2014 set VO_CONTROL_PLANE_URL + VO_CONTROL_PLANE_ADMIN_TOKEN to enable. The server-side /api/v1/admin/concierge/dispatch endpoint IS built + deployed (vo-control-plane #5724/#5734); in cloud mode this tool returns the routed pack README + file index.";
 var CONCIERGE_GATE_TYPE = "concierge-dispatch";
@@ -4244,10 +4797,10 @@ function isKnownConciergePack(value) {
 }
 
 // src/tools/concierge/dispatch.ts
-var TOOL_NAME20 = "vo_concierge_dispatch";
+var TOOL_NAME21 = "vo_concierge_dispatch";
 var CALLABLE_NAME10 = "voConciergeDispatch";
 var ADMIN_PATH10 = "/api/v1/admin/concierge/dispatch";
-var inputSchema20 = {
+var inputSchema21 = {
   type: "object",
   properties: {
     pack: {
@@ -4262,8 +4815,8 @@ var inputSchema20 = {
   },
   additionalProperties: false
 };
-var description20 = "Dispatches a provider-scoped knowledge pack (gcp | firebase | aws | cloudflare | vercel | netlify | tax | hybrid). Cross-vendor MCP equivalent of the /vo-concierge Claude-Code slash command. Route explicitly via `pack`, or via tenant.cloud_provider by passing `tenant_id`. Returns the pack's README (`readme_markdown`) + file index. In cloud mode, dispatches via vo-control-plane and returns `verdict: 'pass'` with the pack/directory data; without cloud config, returns `verdict: 'unimplemented'`.";
-function isToolInput20(v) {
+var description21 = "Dispatches a provider-scoped knowledge pack (gcp | firebase | aws | cloudflare | vercel | netlify | tax | hybrid). Cross-vendor MCP equivalent of the /vo-concierge Claude-Code slash command. Route explicitly via `pack`, or via tenant.cloud_provider by passing `tenant_id`. Returns the pack's README (`readme_markdown`) + file index. In cloud mode, dispatches via vo-control-plane and returns `verdict: 'pass'` with the pack/directory data; without cloud config, returns `verdict: 'unimplemented'`.";
+function isToolInput21(v) {
   if (typeof v !== "object" || v === null) return false;
   const obj = v;
   if (obj.pack !== void 0 && typeof obj.pack !== "string") return false;
@@ -4271,15 +4824,15 @@ function isToolInput20(v) {
   return true;
 }
 async function handleConciergeDispatch(deps, rawInput, _signal) {
-  if (!isToolInput20(rawInput)) {
+  if (!isToolInput21(rawInput)) {
     throw invalidParams(
-      TOOL_NAME20,
+      TOOL_NAME21,
       "invalid input. Expected { pack?: string, tenant_id?: string }."
     );
   }
   if (rawInput.pack !== void 0 && rawInput.pack !== "" && !isKnownConciergePack(rawInput.pack)) {
     throw invalidParams(
-      TOOL_NAME20,
+      TOOL_NAME21,
       `unknown pack: ${JSON.stringify(rawInput.pack)}. Known packs: ${KNOWN_CONCIERGE_PACKS.join(", ")}.`
     );
   }
@@ -4290,7 +4843,7 @@ async function handleConciergeDispatch(deps, rawInput, _signal) {
   if (rawInput.pack) cloudBody.pack = rawInput.pack;
   if (rawInput.tenant_id) cloudBody.tenantId = rawInput.tenant_id;
   return buildCloudOrStubResponse({
-    toolName: TOOL_NAME20,
+    toolName: TOOL_NAME21,
     callableName: CALLABLE_NAME10,
     adminPath: ADMIN_PATH10,
     normalizedInput,
@@ -4307,6 +4860,254 @@ async function handleConciergeDispatch(deps, rawInput, _signal) {
   });
 }
 
+// src/tools/memory/sync-config.ts
+import { homedir as homedir5 } from "node:os";
+import { join as join7 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync3, readdirSync as readdirSync4 } from "node:fs";
+var TOOL_NAME22 = "vo_sync_config";
+var inputSchema22 = {
+  type: "object",
+  properties: {
+    action: {
+      type: "string",
+      enum: ["pull", "push"],
+      description: "pull: download cloud memory to local files. push: upload local files to cloud."
+    },
+    cwd: {
+      type: "string",
+      description: "Working directory to derive project slug from (default: process.cwd())."
+    }
+  },
+  required: ["action"],
+  additionalProperties: false
+};
+var description22 = "Syncs memory entries between local ~/.claude/projects/<slug>/memory/ and cloud control-plane /api/v1/agent-config/memory/me. Requires operator auth (vo-mcp login). Actions: pull (cloud\u2192local), push (local\u2192cloud). Idempotent; push creates/updates as needed.";
+function isToolInput22(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v;
+  if (o["action"] !== "pull" && o["action"] !== "push") return false;
+  if (o["cwd"] !== void 0 && typeof o["cwd"] !== "string") return false;
+  return true;
+}
+function deriveProjectSlug(cwd) {
+  const normalized = cwd.replace(/\\/g, "/");
+  return normalized.replace(/^([A-Z]):/i, (_, drive) => `${drive.toUpperCase()}-`).replace(/\/$/g, "").split("/").join("--").replace(/\s+/g, "-");
+}
+function getMemoryDir(cwd) {
+  const slug = deriveProjectSlug(cwd);
+  return join7(homedir5(), ".claude", "projects", slug, "memory");
+}
+async function pullMemory(controlPlaneUrl, token, memoryDir, sessionId, fetchFn) {
+  const url = `${controlPlaneUrl}/api/v1/agent-config/memory/me`;
+  const response = await fetchFn(url, {
+    method: "GET",
+    headers: {
+      authorization: `Bearer ${token}`
+    }
+  });
+  if (response.status !== 200) {
+    const text = await response.text();
+    throw new Error(`GET /api/v1/agent-config/memory/me returned HTTP ${response.status}: ${text.slice(0, 200)}`);
+  }
+  const data = JSON.parse(await response.text());
+  if (!data.ok || !Array.isArray(data.entries)) {
+    throw new Error("GET /api/v1/agent-config/memory/me response missing ok=true or entries array");
+  }
+  mkdirSync4(memoryDir, { recursive: true });
+  const files = [];
+  for (const entry of data.entries) {
+    const filePath = join7(memoryDir, entry.file_name);
+    writeFileSync3(filePath, entry.content, "utf8");
+    files.push(entry.file_name);
+  }
+  return { pulled: data.entries.length, files };
+}
+async function pushMemory(controlPlaneUrl, token, memoryDir, sessionId, fetchFn) {
+  if (!existsSync5(memoryDir)) {
+    return { pushed: 0, created: 0, updated: 0 };
+  }
+  const localFiles = readdirSync4(memoryDir).filter((f) => f.endsWith(".md")).map((f) => ({
+    file_name: f,
+    content: readFileSync7(join7(memoryDir, f), "utf8"),
+    entry_type: f === "MEMORY.md" ? "index" : "topic"
+  }));
+  if (localFiles.length === 0) {
+    return { pushed: 0, created: 0, updated: 0 };
+  }
+  const getUrl = `${controlPlaneUrl}/api/v1/agent-config/memory/me`;
+  const getResponse = await fetchFn(getUrl, {
+    method: "GET",
+    headers: {
+      authorization: `Bearer ${token}`
+    }
+  });
+  const existingMap = /* @__PURE__ */ new Map();
+  if (getResponse.status === 200) {
+    const getData = JSON.parse(await getResponse.text());
+    if (getData.ok && Array.isArray(getData.entries)) {
+      for (const entry of getData.entries) {
+        existingMap.set(entry.file_name, entry.memory_id);
+      }
+    }
+  }
+  let created = 0;
+  let updated = 0;
+  for (const localFile of localFiles) {
+    const memoryId = existingMap.get(localFile.file_name);
+    if (memoryId) {
+      const updateUrl = `${controlPlaneUrl}/api/v1/agent-config/memory/${memoryId}`;
+      const updateBody = {
+        content: localFile.content,
+        session_id: sessionId
+      };
+      const updateResponse = await fetchFn(updateUrl, {
+        method: "PUT",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify(updateBody)
+      });
+      if (updateResponse.status !== 200) {
+        const text = await updateResponse.text();
+        throw new Error(
+          `PUT /api/v1/agent-config/memory/${memoryId} returned HTTP ${updateResponse.status}: ${text.slice(0, 200)}`
+        );
+      }
+      const updateData = JSON.parse(await updateResponse.text());
+      if (!updateData.ok) {
+        throw new Error(`PUT /api/v1/agent-config/memory/${memoryId} returned ok=false`);
+      }
+      updated++;
+    } else {
+      const createUrl = `${controlPlaneUrl}/api/v1/agent-config/memory/me`;
+      const createBody = {
+        entry_type: localFile.entry_type,
+        file_name: localFile.file_name,
+        content: localFile.content,
+        session_id: sessionId
+      };
+      const createResponse = await fetchFn(createUrl, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify(createBody)
+      });
+      if (createResponse.status !== 200 && createResponse.status !== 201) {
+        const text = await createResponse.text();
+        throw new Error(
+          `POST /api/v1/agent-config/memory/me returned HTTP ${createResponse.status}: ${text.slice(0, 200)}`
+        );
+      }
+      const createData = JSON.parse(await createResponse.text());
+      if (!createData.ok) {
+        throw new Error("POST /api/v1/agent-config/memory/me returned ok=false");
+      }
+      created++;
+    }
+  }
+  return { pushed: localFiles.length, created, updated };
+}
+async function handleSyncConfig(deps, rawInput, _signal, fetchFn = globalThis.fetch) {
+  if (!isToolInput22(rawInput)) {
+    throw invalidParams(
+      TOOL_NAME22,
+      'invalid input. Required: { action: "pull" | "push" }. Optional: { cwd: "<path>" }.'
+    );
+  }
+  const controlPlaneUrl = process.env["VO_CONTROL_PLANE_URL"];
+  if (!controlPlaneUrl) {
+    return jsonContent({
+      tool: TOOL_NAME22,
+      schema_version: 1,
+      payload: {
+        synced: false,
+        reason: "VO_CONTROL_PLANE_URL not set \u2014 cloud mode disabled"
+      }
+    });
+  }
+  const { createAuthTokenSourceFromEnv: createAuthTokenSourceFromEnv2 } = await Promise.resolve().then(() => (init_auth_token_source(), auth_token_source_exports));
+  const { readStoredCredential: readStoredCredential2 } = await Promise.resolve().then(() => (init_credential_store(), credential_store_exports));
+  const tokenSource = createAuthTokenSourceFromEnv2(process.env, fetchFn, () => readStoredCredential2(process.env));
+  if (!tokenSource) {
+    return jsonContent({
+      tool: TOOL_NAME22,
+      schema_version: 1,
+      payload: {
+        synced: false,
+        reason: "No auth configured. Run `vo-mcp login` to authenticate as an operator."
+      }
+    });
+  }
+  const token = await tokenSource.getToken();
+  if (!token) {
+    return jsonContent({
+      tool: TOOL_NAME22,
+      schema_version: 1,
+      payload: {
+        synced: false,
+        reason: "Failed to obtain auth token. Run `vo-mcp login` to re-authenticate."
+      }
+    });
+  }
+  const cwd = rawInput.cwd?.trim() || process.cwd();
+  const memoryDir = getMemoryDir(cwd);
+  try {
+    if (rawInput.action === "pull") {
+      const result = await pullMemory(
+        controlPlaneUrl.replace(/\/+$/, ""),
+        token,
+        memoryDir,
+        deps.sessionId,
+        fetchFn
+      );
+      return jsonContent({
+        tool: TOOL_NAME22,
+        schema_version: 1,
+        payload: {
+          synced: true,
+          action: "pull",
+          pulled: result.pulled,
+          files: result.files,
+          memory_dir: memoryDir
+        }
+      });
+    } else {
+      const result = await pushMemory(
+        controlPlaneUrl.replace(/\/+$/, ""),
+        token,
+        memoryDir,
+        deps.sessionId,
+        fetchFn
+      );
+      return jsonContent({
+        tool: TOOL_NAME22,
+        schema_version: 1,
+        payload: {
+          synced: true,
+          action: "push",
+          pushed: result.pushed,
+          created: result.created,
+          updated: result.updated,
+          memory_dir: memoryDir
+        }
+      });
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return jsonContent({
+      tool: TOOL_NAME22,
+      schema_version: 1,
+      payload: {
+        synced: false,
+        reason: `Sync failed: ${message}`
+      }
+    });
+  }
+}
+
 // src/server.ts
 function buildToolRegistry() {
   return {
@@ -4468,7 +5269,23 @@ function buildToolRegistry() {
         description: description20,
         inputSchema: inputSchema20
       },
+      handler: handleSpawnSuccessor
+    },
+    [TOOL_NAME21]: {
+      definition: {
+        name: TOOL_NAME21,
+        description: description21,
+        inputSchema: inputSchema21
+      },
       handler: handleConciergeDispatch
+    },
+    [TOOL_NAME22]: {
+      definition: {
+        name: TOOL_NAME22,
+        description: description22,
+        inputSchema: inputSchema22
+      },
+      handler: handleSyncConfig
     }
   };
 }
@@ -4526,7 +5343,7 @@ function listToolNames() {
 
 // src/cache/sqlite-cache.ts
 import { createHash as createHash3 } from "node:crypto";
-import { chmodSync as chmodSync3, mkdirSync as mkdirSync3 } from "node:fs";
+import { chmodSync as chmodSync3, mkdirSync as mkdirSync5 } from "node:fs";
 import { dirname as dirname5 } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 
@@ -4572,7 +5389,7 @@ function normalizeString(s) {
 function createSqliteCache(options) {
   const fileBacked = options.dbPath !== ":memory:";
   if (fileBacked) {
-    mkdirSync3(dirname5(options.dbPath), { recursive: true, mode: 448 });
+    mkdirSync5(dirname5(options.dbPath), { recursive: true, mode: 448 });
   }
   const versionNamespace = options.cacheVersionNamespace ?? "";
   const db = new DatabaseSync(options.dbPath);
@@ -4757,6 +5574,143 @@ function createNullConsensusEngineClient(reason = NULL_CLIENT_DEFAULT_REASON) {
 
 // src/consensus/engine-client.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
+
+// src/consensus/engine-options.ts
+var AGREEMENT_GATE_ENV_VAR = "VO_CONSENSUS_AGREEMENT_GATE";
+function isTruthyFlag(raw) {
+  if (raw === void 0) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+function resolveAgreementGate(args) {
+  const env = args.env ?? process.env;
+  const enabled = args.configEnabled === true || args.configEnabled === void 0 && isTruthyFlag(env[AGREEMENT_GATE_ENV_VAR]);
+  if (!enabled) return void 0;
+  return {
+    enabled: true,
+    ...args.probeSize !== void 0 ? { probe_size: args.probeSize } : {},
+    ...args.modalAgreementThreshold !== void 0 ? { modal_agreement_threshold: args.modalAgreementThreshold } : {},
+    ...args.minConfidence !== void 0 ? { min_confidence: args.minConfidence } : {}
+  };
+}
+function buildSourceGroundedFields(config, defaultClassifier) {
+  if (config === void 0) return {};
+  const out = {};
+  const grader = config.citation_grader;
+  if (grader !== void 0 && grader.enabled === true) {
+    const classifier = grader.classifier ?? defaultClassifier;
+    if (classifier !== void 0) {
+      out.citation_grader = {
+        enabled: true,
+        classifier,
+        ...grader.escalate_below !== void 0 ? { escalate_below: grader.escalate_below } : {}
+      };
+    }
+  }
+  if (config.allow_url !== void 0) {
+    out.allow_url = config.allow_url;
+  }
+  return out;
+}
+function mapFanOutDiagnostics(fd) {
+  if (fd === void 0) return void 0;
+  return {
+    models_called: fd.models_called,
+    panel_size: fd.panel_size,
+    early_exit: fd.early_exit,
+    refused: fd.refused
+  };
+}
+function mapCitationGrade(cg) {
+  if (cg === void 0) return void 0;
+  return {
+    ok: cg.ok,
+    unsupported_count: cg.unsupported_count,
+    uncertain_count: cg.uncertain_count,
+    graded_claims: cg.graded_claims.map((g) => ({
+      claim: g.claim,
+      label: g.label,
+      confidence: g.confidence,
+      cited_ids: [...g.cited_ids]
+    }))
+  };
+}
+
+// src/consensus/claim-classifier.ts
+var CLASSIFIER_SYSTEM_PROMPT = [
+  "You are a citation-grading judge. You are given a CLAIM and the full text of the SOURCES it cites.",
+  "Decide whether the SOURCES directly support the CLAIM. Judge ONLY against the supplied sources \u2014 do not use outside knowledge.",
+  "pass = the sources clearly support the claim; fail = the sources contradict or do not support it; uncertain = the sources are insufficient or ambiguous.",
+  "After a one-sentence justification, conclude with EXACTLY one of these lines:",
+  "  VERDICT: pass",
+  "  VERDICT: fail",
+  "  VERDICT: uncertain",
+  "Then on a new line, exactly:",
+  "  CONFIDENCE: <0..1>",
+  "Do not include any other VERDICT or CONFIDENCE lines."
+].join("\n");
+function verdictToLabel(verdict) {
+  switch (verdict) {
+    case "pass":
+      return "supported";
+    case "fail":
+      return "unsupported";
+    case "uncertain":
+      return "uncertain";
+    default:
+      return "uncertain";
+  }
+}
+function clampConfidence(raw) {
+  if (!Number.isFinite(raw)) return 0;
+  if (raw < 0) return 0;
+  if (raw > 1) return 1;
+  return raw;
+}
+function buildClassifyPrompt(claim, sources) {
+  return [
+    "CLAIM:",
+    claim,
+    "",
+    "SOURCES:",
+    sources,
+    "",
+    "Does the cited SOURCES text support the CLAIM? Reply with your verdict (pass = supported, fail = unsupported, uncertain = insufficient)."
+  ].join("\n");
+}
+function createClaimClassifier(model, options = {}) {
+  return {
+    async classify(args) {
+      try {
+        const result = await model.call({
+          system_prompt: CLASSIFIER_SYSTEM_PROMPT,
+          user_prompt: buildClassifyPrompt(args.claim, args.sources),
+          ...options.signal !== void 0 ? { abort_signal: options.signal } : {}
+        });
+        if (result.verdict === "error") {
+          return { label: "uncertain", confidence: 0 };
+        }
+        return {
+          label: verdictToLabel(result.verdict),
+          confidence: clampConfidence(result.confidence)
+        };
+      } catch {
+        return { label: "uncertain", confidence: 0 };
+      }
+    }
+  };
+}
+
+// src/consensus/engine-client.ts
+function raceAbort(signal) {
+  return new Promise((_, reject) => {
+    const onAbort = () => {
+      reject(new Error("__VO_MCP_CANCELLED__"));
+    };
+    if (signal.aborted) onAbort();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
 async function loadEngineModule() {
   try {
     const moduleName = ["@algosuite", "consensus-engine"].join("/");
@@ -4800,36 +5754,73 @@ function createEngineConsensusClient(options) {
           ...adapter,
           call: (args) => adapter.call({ ...args, abort_signal: signal })
         }));
+        const agreementGate = resolveAgreementGate({
+          ...options.agreement_gate_enabled !== void 0 ? { configEnabled: options.agreement_gate_enabled } : {},
+          ...options.env !== void 0 ? { env: options.env } : {}
+        });
         const engineOptions = {
           panel,
-          ...options.per_model_timeout_ms !== void 0 ? { per_model_timeout_ms: options.per_model_timeout_ms } : {}
+          ...options.per_model_timeout_ms !== void 0 ? { per_model_timeout_ms: options.per_model_timeout_ms } : {},
+          ...agreementGate !== void 0 ? { agreement_gate: agreementGate } : {}
         };
-        const result = signal === void 0 ? await engine.runConsensus(engineRequest, engineOptions) : await Promise.race([
-          engine.runConsensus(engineRequest, engineOptions),
-          new Promise((_, reject) => {
-            const onAbort = () => {
-              reject(new Error("__VO_MCP_CANCELLED__"));
-            };
-            if (signal.aborted) onAbort();
-            else signal.addEventListener("abort", onAbort, { once: true });
-          })
-        ]);
-        if (!result.ok || result.response === void 0) {
-          return {
-            ok: false,
-            reason: result.error?.reason ?? "engine-returned-not-ok"
+        const sources = request.source_urls;
+        const useSourceGrounded = sources !== void 0 && sources.length > 0 && typeof engine.runSourceGroundedConsensus === "function";
+        let response;
+        let sourceExtras;
+        if (useSourceGrounded) {
+          const [firstAdapter] = panel;
+          const classifierOptions = signal === void 0 ? {} : { signal };
+          const defaultClassifier = firstAdapter === void 0 ? void 0 : createClaimClassifier(firstAdapter, classifierOptions);
+          const sgFields = buildSourceGroundedFields(request.source_grounded, defaultClassifier);
+          const sgOptions = {
+            ...engineOptions,
+            source_urls: sources,
+            ...sgFields.allow_url !== void 0 ? { allow_url: sgFields.allow_url } : {},
+            ...sgFields.citation_grader !== void 0 ? { citation_grader: sgFields.citation_grader } : {}
+          };
+          if (typeof engine.runSourceGroundedConsensus !== "function") {
+            return { ok: false, reason: "source-grounded engine missing runSourceGroundedConsensus" };
+          }
+          const sgCall = engine.runSourceGroundedConsensus(engineRequest, sgOptions);
+          const sgResult = signal === void 0 ? await sgCall : await Promise.race([sgCall, raceAbort(signal)]);
+          if (!sgResult.ok) {
+            return { ok: false, reason: sgResult.reason };
+          }
+          response = sgResult.engine.response;
+          sourceExtras = {
+            ...sgResult.citation_grade !== void 0 ? { citation_grade: mapCitationGrade(sgResult.citation_grade) } : {},
+            ...sgResult.low_confidence_sources !== void 0 ? { low_confidence_sources: sgResult.low_confidence_sources } : {},
+            ...sgResult.escalation_required !== void 0 ? { escalation_required: sgResult.escalation_required } : {},
+            ...sgResult.escalation_reason !== void 0 ? { escalation_reason: sgResult.escalation_reason } : {}
           };
+        } else {
+          const result = signal === void 0 ? await engine.runConsensus(engineRequest, engineOptions) : await Promise.race([engine.runConsensus(engineRequest, engineOptions), raceAbort(signal)]);
+          if (!result.ok || result.response === void 0) {
+            return {
+              ok: false,
+              reason: result.error?.reason ?? "engine-returned-not-ok"
+            };
+          }
+          response = result.response;
         }
         return {
           ok: true,
-          synthesized_verdict: result.response.synthesized_verdict,
-          per_model_verdicts: result.response.per_model_verdicts,
-          degraded: result.response.degraded,
-          duration_ms: result.response.duration_ms,
-          engine_version: result.response.engine_version,
-          // Phase 2 Lane D-1 — forward escalation signal when present.
-          ...result.response.escalation_required !== void 0 ? { escalation_required: result.response.escalation_required } : {},
-          ...result.response.escalation_reason !== void 0 ? { escalation_reason: result.response.escalation_reason } : {}
+          synthesized_verdict: response.synthesized_verdict,
+          per_model_verdicts: response.per_model_verdicts,
+          degraded: response.degraded,
+          duration_ms: response.duration_ms,
+          engine_version: response.engine_version,
+          // Phase 2 Lane D-1 — forward escalation signal when present. The
+          // source-grounded layer's own escalation (from the citation grade)
+          // takes precedence when set, else the synthesizer's.
+          ...sourceExtras?.escalation_required !== void 0 ? { escalation_required: sourceExtras.escalation_required } : response.escalation_required !== void 0 ? { escalation_required: response.escalation_required } : {},
+          ...sourceExtras?.escalation_reason !== void 0 ? { escalation_reason: sourceExtras.escalation_reason } : response.escalation_reason !== void 0 ? { escalation_reason: response.escalation_reason } : {},
+          // Feature 1 (agreement-gate) — fan-out diagnostics (additive telemetry).
+          ...mapFanOutDiagnostics(response.fan_out_diagnostics) !== void 0 ? { fan_out_diagnostics: mapFanOutDiagnostics(response.fan_out_diagnostics) } : {},
+          // Source-grounded additive outputs (Tier-4 features).
+          ...useSourceGrounded ? { source_grounded: true } : {},
+          ...sourceExtras?.citation_grade !== void 0 ? { citation_grade: sourceExtras.citation_grade } : {},
+          ...sourceExtras?.low_confidence_sources !== void 0 ? { low_confidence_sources: sourceExtras.low_confidence_sources } : {}
         };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);