@suveren/gateway 0.3.17 → 0.4.0

package/dist/mcp-server/http.mjs

@@ -34,6 +34,19 @@ var SPClient = class {
   setSessionCookie(cookie) {
     this.sessionCookie = cookie;
   }
+  /**
+   * Has anyone signed in yet this run?
+   *
+   * The control-plane pushes the session cookie on login, so its absence means
+   * the vault is locked — the gateway is up and answering, but it cannot read
+   * authorizations or credentials. Callers MUST distinguish that from "this
+   * user has no authorizations": the two look identical from the outside, and
+   * reporting the latter sends someone off to create authorizations when all
+   * they needed to do was enter their API key.
+   */
+  isUnlocked() {
+    return this.sessionCookie !== "";
+  }
   async fetch(path, init) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
@@ -643,11 +656,131 @@ function windowCutoff(window, now) {
       return now - 24 * 60 * 60;
     case "weekly":
       return now - 7 * 24 * 60 * 60;
-    case "monthly":
-      return now - 30 * 24 * 60 * 60;
+    case "monthly": {
+      const d = new Date(now * 1e3);
+      return Math.floor(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1, 0, 0, 0, 0) / 1e3);
+    }
   }
 }
 
+// src/lib/denial-log.ts
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3, existsSync as existsSync3, unlinkSync as unlinkSync3 } from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname3, join as join3 } from "path";
+import { createCipheriv as createCipheriv3, createDecipheriv as createDecipheriv3, randomBytes as randomBytes3 } from "crypto";
+var DEFAULT_DIR3 = process.env.SUVEREN_DATA_DIR ?? join3(homedir3(), ".suveren");
+var MAX_RECORDS = 200;
+var MAX_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
+var DenialLog = class {
+  records = [];
+  baseDir;
+  vaultKey = null;
+  constructor(filePath) {
+    this.baseDir = filePath && filePath.endsWith(".json") ? dirname3(filePath) : filePath ?? DEFAULT_DIR3;
+    this.loadPlaintext();
+  }
+  setVaultKey(key) {
+    this.vaultKey = key;
+    if (existsSync3(this.encryptedFilePath)) {
+      this.loadEncrypted();
+    } else if (this.records.length > 0) {
+      this.persistEncrypted();
+      if (existsSync3(this.plaintextFilePath)) {
+        try {
+          unlinkSync3(this.plaintextFilePath);
+        } catch {
+        }
+      }
+    }
+  }
+  /** Record a read denial. Never throws — recording must not break the denial. */
+  record(rec) {
+    try {
+      this.records.push(rec);
+      this.prune(rec.ts);
+      this.persist();
+    } catch (err) {
+      console.error("[DenialLog] failed to record denial:", err);
+    }
+  }
+  /** Recent denials, newest first. `sinceMs` and `limit` are optional filters. */
+  getRecent(sinceMs, limit = MAX_RECORDS) {
+    let out = [...this.records].sort((a, b) => b.ts - a.ts);
+    if (sinceMs !== void 0) out = out.filter((r) => r.ts >= sinceMs);
+    return out.slice(0, limit);
+  }
+  get size() {
+    return this.records.length;
+  }
+  // ─── Retention ────────────────────────────────────────────────────────────
+  prune(now) {
+    const cutoff = now - MAX_AGE_MS;
+    this.records = this.records.filter((r) => r.ts >= cutoff);
+    if (this.records.length > MAX_RECORDS) {
+      this.records = this.records.slice(this.records.length - MAX_RECORDS);
+    }
+  }
+  // ─── Encryption (mirrors ExecutionLog) ──────────────────────────────────────
+  encrypt(plaintext) {
+    if (!this.vaultKey) throw new Error("No vault key");
+    const iv = randomBytes3(12);
+    const cipher = createCipheriv3("aes-256-gcm", this.vaultKey, iv);
+    const enc = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    return { iv: iv.toString("hex"), ciphertext: enc.toString("hex"), tag: cipher.getAuthTag().toString("hex") };
+  }
+  decrypt(blob) {
+    if (!this.vaultKey) throw new Error("No vault key");
+    const decipher = createDecipheriv3("aes-256-gcm", this.vaultKey, Buffer.from(blob.iv, "hex"));
+    decipher.setAuthTag(Buffer.from(blob.tag, "hex"));
+    return Buffer.concat([decipher.update(Buffer.from(blob.ciphertext, "hex")), decipher.final()]).toString("utf8");
+  }
+  get plaintextFilePath() {
+    return join3(this.baseDir, "denials.json");
+  }
+  get encryptedFilePath() {
+    return join3(this.baseDir, "denials.enc.json");
+  }
+  loadPlaintext() {
+    if (!existsSync3(this.plaintextFilePath)) {
+      mkdirSync3(this.baseDir, { recursive: true });
+      return;
+    }
+    try {
+      const data = JSON.parse(readFileSync3(this.plaintextFilePath, "utf-8"));
+      this.records = data.records ?? [];
+    } catch {
+      console.error(`[DenialLog] Could not parse ${this.plaintextFilePath}, starting fresh`);
+      this.records = [];
+    }
+  }
+  loadEncrypted() {
+    if (!existsSync3(this.encryptedFilePath)) return;
+    try {
+      const data = JSON.parse(readFileSync3(this.encryptedFilePath, "utf-8"));
+      const logFile = JSON.parse(this.decrypt(data.blob));
+      this.records = logFile.records ?? [];
+    } catch (err) {
+      console.error(`[DenialLog] Could not decrypt ${this.encryptedFilePath}:`, err);
+      this.records = [];
+    }
+  }
+  persist() {
+    if (this.vaultKey) this.persistEncrypted();
+    else this.persistPlaintext();
+  }
+  persistPlaintext() {
+    const data = { version: 1, records: this.records };
+    mkdirSync3(this.baseDir, { recursive: true, mode: 448 });
+    writeFileSync3(this.plaintextFilePath, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 384 });
+  }
+  persistEncrypted() {
+    const logFile = { version: 1, records: this.records };
+    const data = { version: 1, blob: this.encrypt(JSON.stringify(logFile)) };
+    mkdirSync3(this.baseDir, { recursive: true, mode: 448 });
+    writeFileSync3(this.encryptedFilePath, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 384 });
+  }
+};
+
 // src/lib/gatekeeper.ts
 import { verify } from "@hap/core";
 var MCPGatekeeper = class {
@@ -699,7 +832,15 @@ var MCPGatekeeper = class {
       frame,
       attestations: auth.attestations.map((a) => a.blob),
       execution,
-      context: resolvedContext
+      context: resolvedContext,
+      // Scopes the local cumulative check to the same (profileId, path) key the
+      // ExecutionLog records under (see tool-proxy's record call). It cannot go
+      // inside `frame`: that is validated against the profile's boundsSchema,
+      // which declares no `path` field in any shipped profile, so an extra key
+      // there fails verification with "Unknown field". Omitting it entirely —
+      // the previous behaviour — made every cumulative lookup return zero, so
+      // the local gate never fired and the AS was doing all the enforcing.
+      path: auth.path
     };
     const result = await verify(request, publicKeyHex, void 0, this.executionLog);
     return { result, authorization: auth };
@@ -712,12 +853,14 @@ var SharedState = class {
   cache;
   gateStore;
   executionLog;
+  denialLog;
   gatekeeper;
   constructor(spUrl2, gateStorePath) {
     this.spClient = new SPClient(spUrl2);
     this.cache = new AttestationCache(this.spClient);
     this.gateStore = new GateStore(gateStorePath);
     this.executionLog = new ExecutionLog(gateStorePath);
+    this.denialLog = new DenialLog(gateStorePath);
     this.gatekeeper = new MCPGatekeeper(this.cache, this.executionLog);
   }
   setGateContent(path, authorizationId, profileId, content, opts) {
@@ -771,6 +914,7 @@ function getConsumptionState(auth, executionLog, profile) {
     const fieldDef = rawFieldDef;
     const bt = fieldDef.boundType;
     if (!bt) continue;
+    if (fieldDef.enforced === false) continue;
     if (bt.kind !== "cumulative_sum" && bt.kind !== "cumulative_count") continue;
     const boundValue = auth.frame[fieldName];
     const limit = typeof boundValue === "number" ? boundValue : null;
@@ -783,7 +927,10 @@ function getConsumptionState(auth, executionLog, profile) {
       now
     );
     entries.push({
-      label: fieldDef.description ?? fieldName,
+      // displayName FIRST: description is prose meant for a human reading the
+      // profile, and rendering it here produced a paragraph where a label
+      // belongs ("Not currently enforced: reads carry no receipt… : 0 / 7").
+      label: fieldDef.displayName ?? fieldDef.description ?? fieldName,
       current,
       limit,
       window: bt.window,
@@ -821,17 +968,17 @@ function formatConsumptionFull(entries) {
 }
 
 // src/lib/context-loader.ts
-import { readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
-import { homedir as homedir3 } from "os";
-import { join as join3 } from "path";
-var DEFAULT_DIR3 = process.env.SUVEREN_DATA_DIR ?? join3(homedir3(), ".suveren");
+import { readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join4 } from "path";
+var DEFAULT_DIR4 = process.env.SUVEREN_DATA_DIR ?? join4(homedir4(), ".suveren");
 var BRIEF_MAX_CHARS = 16 * 1024;
 function readContextFile(dataDir) {
-  const dir = dataDir ?? DEFAULT_DIR3;
-  const filePath = join3(dir, "context.md");
-  if (!existsSync3(filePath)) return null;
+  const dir = dataDir ?? DEFAULT_DIR4;
+  const filePath = join4(dir, "context.md");
+  if (!existsSync4(filePath)) return null;
   try {
-    const content = readFileSync3(filePath, "utf-8").trim();
+    const content = readFileSync4(filePath, "utf-8").trim();
     return content || null;
   } catch {
     return null;
@@ -929,8 +1076,22 @@ function buildMandateBrief(opts) {
   return lines.join("\n");
 }
 
+// src/lib/locked-notice.ts
+function uiUrl() {
+  const port2 = process.env.SUVEREN_CP_PORT ?? "3400";
+  return `http://localhost:${port2}`;
+}
+function lockedNotice(action) {
+  const what = action ? `Cannot ${action}: the` : "The";
+  return `${what} Suveren gateway is running but LOCKED, so it cannot read any authorizations or credentials.
+
+This is not the same as having no authorizations \u2014 yours are on disk, encrypted, and unreadable until someone unlocks them.
+
+TELL THE USER: open ${uiUrl()} and enter your Suveren API key to unlock the gateway. It boots locked by design after every restart; the key is never stored.`;
+}
+
 // src/tools/authorizations.ts
-import { getProfile as getProfile3 } from "@hap/core";
+import { getProfile as getProfile4 } from "@hap/core";
 
 // src/lib/receipt-footer.ts
 import { deriveIdentityLine } from "@hap/core";
@@ -1012,7 +1173,168 @@ function attachReceiptId(tool, args, receiptId) {
   return { ...args, receipt_id: receiptId };
 }
 
+// src/lib/scope-specificity.ts
+function tokenSet(value) {
+  if (value === void 0 || value === null) return /* @__PURE__ */ new Set();
+  return new Set(
+    String(value).split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)
+  );
+}
+function subsetOrEqual(a, b) {
+  if (b.size === 0) return true;
+  if (a.size === 0) return false;
+  for (const x of a) if (!b.has(x)) return false;
+  return true;
+}
+function atLeastAsSpecific(keys, a, b) {
+  for (const k of keys) {
+    if (!subsetOrEqual(tokenSet(a[k]), tokenSet(b[k]))) return false;
+  }
+  return true;
+}
+function strictlyMoreSpecific(keys, a, b) {
+  return atLeastAsSpecific(keys, a, b) && !atLeastAsSpecific(keys, b, a);
+}
+function selectAuthorization(contextKeys, passers) {
+  if (passers.length === 1) {
+    return { chosen: passers[0], superseded: [], reason: "sole" };
+  }
+  const dominators = passers.filter(
+    (a) => passers.every((b) => b === a || strictlyMoreSpecific(contextKeys, a.context, b.context))
+  );
+  if (dominators.length === 1) {
+    const chosen2 = dominators[0];
+    return { chosen: chosen2, superseded: passers.filter((p) => p !== chosen2), reason: "most-specific" };
+  }
+  const approvers = passers.filter((p) => p.requiresApproval);
+  const pool = approvers.length > 0 ? approvers : passers;
+  const chosen = pool.slice().sort((a, b) => a.id.localeCompare(b.id))[0];
+  return {
+    chosen,
+    superseded: passers.filter((p) => p !== chosen),
+    reason: approvers.length > 0 ? "fail-safe-approval" : "fail-safe-tiebreak"
+  };
+}
+
+// src/lib/read-gate.ts
+function boundsSatisfyReadGate(bounds, gate) {
+  if (!gate.boundField) return true;
+  const actual = bounds?.[gate.boundField];
+  return actual !== void 0 && String(actual) === gate.requiredValue;
+}
+function readToolIsGoverned(g) {
+  if (!g) return false;
+  return Boolean(g.boundField) || g.read != null || g.readGovernance === "none";
+}
+function allowedResources(contexts, boundField) {
+  const out = /* @__PURE__ */ new Set();
+  for (const ctx of contexts) {
+    for (const v of tokenSet(ctx?.[boundField])) out.add(v);
+  }
+  return out;
+}
+function deniedResources(requested, allowed) {
+  return requested.filter((r) => !allowed.has(r));
+}
+function filterItemsByResource(items, idPath, allowed) {
+  return items.filter((it) => {
+    const id = getByDottedPath(it, idPath);
+    return typeof id === "string" && allowed.has(id);
+  });
+}
+function hasBlockedValue(item, valuesPath, blocked) {
+  const v = getByDottedPath(item, valuesPath);
+  const arr = Array.isArray(v) ? v : v != null ? [v] : [];
+  return arr.some((x) => typeof x === "string" && blocked.has(x));
+}
+var MS_PER_DAY = 24 * 60 * 60 * 1e3;
+function parseMessageTimestamp(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+    const iso = Date.parse(value);
+    if (Number.isFinite(iso)) return iso;
+  }
+  return null;
+}
+function ageInDays(timestampMs, nowMs) {
+  return Math.floor((nowMs - timestampMs) / MS_PER_DAY);
+}
+function maxReadAgeDays(boundsList, field) {
+  let max = null;
+  for (const b of boundsList) {
+    const raw = b?.[field];
+    const n = typeof raw === "number" ? raw : raw !== void 0 ? Number(raw) : NaN;
+    if (Number.isFinite(n)) max = max === null ? n : Math.max(max, n);
+  }
+  return max;
+}
+function isOlderThanMaxAge(timestampMs, maxAgeDays, nowMs) {
+  if (timestampMs === null) return true;
+  return ageInDays(timestampMs, nowMs) > maxAgeDays;
+}
+var TRAILING_OPERATOR = /(?:^|\s)(?:OR|AND|NOT)$|[-+|&:]$/i;
+function parensBalanced(s) {
+  let depth = 0;
+  let inQuote = false;
+  for (const c of s) {
+    if (c === '"') {
+      inQuote = !inQuote;
+      continue;
+    }
+    if (inQuote) continue;
+    if (c === "(") depth++;
+    else if (c === ")" && --depth < 0) return false;
+  }
+  return !inQuote && depth === 0;
+}
+function composeReadQuery(agentQuery, clauses) {
+  const injected = clauses.filter((c) => typeof c === "string" && c.trim() !== "").map((c) => c.trim());
+  const base = (agentQuery ?? "").trim();
+  if (base === "") return { ok: true, query: injected.join(" ") };
+  if (!parensBalanced(base)) {
+    return { ok: false, reason: "the requested search query has unbalanced parentheses" };
+  }
+  if (TRAILING_OPERATOR.test(base)) {
+    return { ok: false, reason: "the requested search query ends in a dangling operator" };
+  }
+  if (injected.length === 0) return { ok: true, query: base };
+  return { ok: true, query: `(${base}) ${injected.join(" ")}` };
+}
+function detectAgeConflict(agentQuery, conflictPattern, maxAgeDays) {
+  if (!agentQuery || !conflictPattern || maxAgeDays === null) return null;
+  let re;
+  try {
+    re = new RegExp(conflictPattern, "gi");
+  } catch {
+    return null;
+  }
+  let worst = null;
+  for (const match of agentQuery.matchAll(re)) {
+    const days = Number(match[1]);
+    if (!Number.isFinite(days)) continue;
+    if (days >= maxAgeDays && (worst === null || days > worst)) worst = days;
+  }
+  return worst;
+}
+function resolveAgeBoundField(boundsSchema, ageExecField) {
+  const fields = boundsSchema?.fields;
+  if (!fields) return null;
+  for (const [name, def] of Object.entries(fields)) {
+    if (def?.boundType?.kind === "per_transaction" && def.boundType.of === ageExecField) return name;
+  }
+  return null;
+}
+function getByDottedPath(obj, path) {
+  return path.split(".").reduce(
+    (o, k) => o == null ? void 0 : o[k],
+    obj
+  );
+}
+
 // src/lib/tool-proxy.ts
+import { getProfile as getProfile3 } from "@hap/core";
 import { readFile } from "fs/promises";
 import { extname } from "path";
 import { randomUUID } from "crypto";
@@ -1075,6 +1397,30 @@ function applyMapping(m, value, execution) {
 function profileMatches(profileId, shortName) {
   return profileId === shortName || profileId.includes("/" + shortName + "@") || profileId.endsWith("/" + shortName);
 }
+function parseFirstJson(result) {
+  const text = result.content?.find((c) => c.type === "text")?.text;
+  if (typeof text !== "string") return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function denyRead(state2, tool, reason, detail, target) {
+  try {
+    state2.denialLog?.record({
+      ts: Date.now(),
+      tool: tool.originalName,
+      integrationId: tool.integrationId,
+      profile: tool.gating?.profile ?? null,
+      reason,
+      detail,
+      target
+    });
+  } catch {
+  }
+  return { content: [{ type: "text", text: `Read blocked by Gatekeeper: ${detail}` }], isError: true };
+}
 function createGatedToolHandler(tool, integrationManager2, state2) {
   if (!tool.gating || !tool.gating.profile) {
     return async () => {
@@ -1088,8 +1434,37 @@ function createGatedToolHandler(tool, integrationManager2, state2) {
     };
   }
   const { profile, executionMapping, staticExecution, category } = tool.gating;
+  const lockedGuard = (inner) => async (args) => {
+    if (!state2.spClient.isUnlocked()) {
+      return {
+        content: [{ type: "text", text: lockedNotice(`use ${tool.namespacedName}`) }],
+        isError: true
+      };
+    }
+    return inner(args);
+  };
+  if (category === "disabled") {
+    return async () => ({
+      content: [{
+        type: "text",
+        text: `Tool "${tool.namespacedName}" is disabled by the integration manifest and cannot be used.`
+      }],
+      isError: true
+    });
+  }
   if (category === "read") {
-    return async (args) => {
+    const readGate = { boundField: tool.gating.boundField, requiredValue: tool.gating.requiredValue };
+    const readAdapter = tool.gating.read;
+    const governed = readToolIsGoverned(tool.gating);
+    return lockedGuard(async (args) => {
+      if (!governed) {
+        return denyRead(
+          state2,
+          tool,
+          "ungoverned",
+          `${tool.originalName} declares no read governance (no static gate, no read adapter, no explicit exemption), so the gateway cannot bound what it returns. This is a manifest defect \u2014 the tool must declare how its reads are limited before it can be used.`
+        );
+      }
       const auths = state2.getEnrichedAuthorizations();
       const matchingAuths = auths.filter(
         (a) => a.complete && profileMatches(a.profileId, profile)
@@ -1103,10 +1478,135 @@ function createGatedToolHandler(tool, integrationManager2, state2) {
           isError: true
         };
       }
-      return integrationManager2.callTool(tool.integrationId, tool.originalName, args);
-    };
+      if (readGate.boundField) {
+        const permitted = matchingAuths.some(
+          (a) => boundsSatisfyReadGate(a.bounds ?? a.frame, readGate)
+        );
+        if (!permitted) {
+          return denyRead(
+            state2,
+            tool,
+            "read_gate",
+            `using ${tool.originalName} requires an authorization with "${readGate.boundField}: ${readGate.requiredValue}", but no active authorization grants it.`
+          );
+        }
+      }
+      const readProfile = readAdapter ? getProfile3(matchingAuths[0].profileId) : void 0;
+      const boundsSchema = readProfile?.boundsSchema;
+      const ageBoundField = readAdapter?.ageField ? resolveAgeBoundField(boundsSchema, readAdapter.ageField) : null;
+      let readMaxAge = null;
+      if (ageBoundField) {
+        readMaxAge = maxReadAgeDays(
+          matchingAuths.map((a) => a.bounds ?? a.frame),
+          ageBoundField
+        );
+        if (readMaxAge === null) {
+          return denyRead(
+            state2,
+            tool,
+            "unset_age",
+            `no read-age window is set on your authorization (${ageBoundField}). Reads are not permitted with an unbounded window \u2014 set how far back the agent may read, then try again. Nothing was read.`
+          );
+        }
+      }
+      let outgoing = args;
+      if (readAdapter?.resourceBound && (readAdapter.resourceArg || readAdapter.resourceArrayArg)) {
+        const allowed = allowedResources(
+          matchingAuths.map((a) => a.context ?? {}),
+          readAdapter.resourceBound
+        );
+        const isArray = Boolean(readAdapter.resourceArrayArg);
+        const argName = readAdapter.resourceArrayArg ?? readAdapter.resourceArg;
+        const raw = args[argName];
+        let requested;
+        if (isArray) {
+          requested = Array.isArray(raw) && raw.length > 0 ? raw.map(String) : readAdapter.resourceDefault ? [readAdapter.resourceDefault] : [];
+        } else {
+          requested = typeof raw === "string" && raw.trim() !== "" ? [raw] : readAdapter.resourceDefault ? [readAdapter.resourceDefault] : [];
+        }
+        const denied = deniedResources(requested, allowed);
+        if (requested.length === 0 || denied.length > 0) {
+          const why = requested.length === 0 ? "no container was resolved for this read" : `not in your permitted set (${denied.join(", ")})`;
+          return denyRead(
+            state2,
+            tool,
+            "resource",
+            `${tool.originalName} may only read the containers your authorization permits (${readAdapter.resourceBound}); the requested one is ${why}. Nothing was read.`,
+            denied.length > 0 ? denied.join(", ") : void 0
+          );
+        }
+        outgoing = { ...args, [argName]: isArray ? requested : requested[0] };
+      }
+      if (readAdapter?.pinnedArgs) {
+        outgoing = { ...outgoing, ...readAdapter.pinnedArgs };
+      }
+      if (readAdapter?.queryArg) {
+        const clauses = [];
+        if (ageBoundField && readAdapter.ageConstraint && readMaxAge !== null) {
+          clauses.push(readAdapter.ageConstraint.replace("{days}", String(readMaxAge)));
+        }
+        if (clauses.length > 0) {
+          const base = typeof args[readAdapter.queryArg] === "string" ? args[readAdapter.queryArg] : "";
+          const conflictDays = detectAgeConflict(base, readAdapter.ageConflictPattern, readMaxAge);
+          if (conflictDays !== null) {
+            return denyRead(
+              state2,
+              tool,
+              "age_window",
+              `you asked for items older than ${conflictDays} days, but this authorization allows ${readMaxAge} days. Nothing outside that window can be read, so the search was not run \u2014 it would have returned an empty result that looks like "none exist". Items may well exist beyond ${readMaxAge} days; widen read_max_age_days if you need them.`
+            );
+          }
+          const composed = composeReadQuery(base, clauses);
+          if (!composed.ok) {
+            return denyRead(
+              state2,
+              tool,
+              "query_unsafe",
+              `${composed.reason}. The gateway must AND its read limits onto your search, and this query could not be safely combined. Re-send it without a trailing operator or unbalanced parenthesis.`
+            );
+          }
+          outgoing = { ...outgoing, [readAdapter.queryArg]: composed.query };
+        }
+      }
+      const result = await integrationManager2.callTool(tool.integrationId, tool.originalName, outgoing);
+      if (readAdapter?.blockResultValues && readAdapter.resultValuesPath) {
+        const parsed = parseFirstJson(result);
+        const blocked = new Set(readAdapter.blockResultValues);
+        if (parsed !== void 0 && hasBlockedValue(parsed, readAdapter.resultValuesPath, blocked)) {
+          return denyRead(
+            state2,
+            tool,
+            "spam",
+            `this item is in a container your authorization excludes (e.g. spam/trash). Its contents were not returned.`
+          );
+        }
+      }
+      if (readAdapter && ageBoundField && readAdapter.resultDatePath && readMaxAge !== null) {
+        const parsed = parseFirstJson(result);
+        const rawDate = parsed === void 0 ? void 0 : getByDottedPath(parsed, readAdapter.resultDatePath);
+        if (isOlderThanMaxAge(parseMessageTimestamp(rawDate), readMaxAge, Date.now())) {
+          return denyRead(
+            state2,
+            tool,
+            "age",
+            `this item is older than the ${readMaxAge}-day read window your authorization grants (read_max_age_days). Its contents were not returned.`
+          );
+        }
+      }
+      if (readAdapter?.resourceBound && readAdapter.resultResourcePath && !readAdapter.resourceArg && !readAdapter.resourceArrayArg) {
+        const allowed = allowedResources(
+          matchingAuths.map((a) => a.context ?? {}),
+          readAdapter.resourceBound
+        );
+        const parsed = parseFirstJson(result);
+        const items = Array.isArray(parsed) ? parsed : [];
+        const kept = filterItemsByResource(items, readAdapter.resultResourcePath, allowed);
+        return { ...result, content: [{ type: "text", text: JSON.stringify(kept) }] };
+      }
+      return result;
+    });
   }
-  return async (args) => {
+  return lockedGuard(async (args) => {
     const execution = { ...staticExecution };
     for (const [argName, mapping] of Object.entries(executionMapping)) {
       const value = args[argName];
@@ -1137,170 +1637,191 @@ function createGatedToolHandler(tool, integrationManager2, state2) {
       };
     }
     const errors = [];
-    for (const auth of matchingAuths) {
-      const { result } = await state2.gatekeeper.verifyExecution(auth.authorizationId, execution, {
-        bounds: auth.bounds,
-        context: auth.context
+    const passers = [];
+    for (const candidate of matchingAuths) {
+      const { result } = await state2.gatekeeper.verifyExecution(candidate.authorizationId, execution, {
+        bounds: candidate.bounds,
+        context: candidate.context
       });
-      if (!result.approved) {
-      }
       if (result.approved) {
-        const authzId = auth.authorizationId;
-        if (isCommitmentDowngrade(auth)) {
+        passers.push(candidate);
+      } else {
+        const reasons = result.errors.map((e) => {
+          if (e.code === "BOUND_EXCEEDED") {
+            return `${candidate.path}: ${e.field}: ${e.message}`;
+          }
+          return `${candidate.path}: ${e.message}`;
+        });
+        errors.push(...reasons);
+      }
+    }
+    if (passers.length === 0) {
+      return {
+        content: [{
+          type: "text",
+          text: `Tool call rejected by Gatekeeper. Tried ${matchingAuths.length} authorization(s):
+` + errors.map((e) => `  - ${e}`).join("\n")
+        }],
+        isError: true
+      };
+    }
+    const contextKeys = getProfile3(passers[0].profileId)?.contextSchema?.keyOrder ?? [];
+    const selection = selectAuthorization(
+      contextKeys,
+      passers.map((a) => ({
+        id: a.authorizationId,
+        auth: a,
+        context: a.context ?? {},
+        requiresApproval: (a.deferredCommitmentDomains ?? []).length > 0
+      }))
+    );
+    const auth = selection.chosen.auth;
+    if (selection.superseded.length > 0) {
+      console.error(
+        `[Suveren MCP] selection(${tool.namespacedName}): chose ${auth.authorizationId} (${selection.reason}) over [${selection.superseded.map((s) => s.id).join(", ")}]`
+      );
+    }
+    {
+      const authzId = auth.authorizationId;
+      if (isCommitmentDowngrade(auth)) {
+        return {
+          content: [{
+            type: "text",
+            text: `Refusing to execute ${tool.originalName}: the signed authorization requires review (commitment_mode="${auth.signedCommitmentMode}") but the Authority Server returned no pending approvers. This inconsistency (a possible commitment-mode downgrade) is rejected fail-closed. Re-fetch the authorization or contact the Authority Server operator.`
+          }],
+          isError: true
+        };
+      }
+      if ((auth.deferredCommitmentDomains ?? []).length > 0) {
+        try {
+          const enrichedArgs = await attachImagePreview(args);
+          const { proposal } = await state2.spClient.submitProposal({
+            authorizationId: authzId,
+            profileId: auth.profileId,
+            path: auth.path,
+            pendingDomains: auth.deferredCommitmentDomains,
+            tool: tool.namespacedName,
+            toolArgs: enrichedArgs,
+            executionContext: { ...execution }
+          });
           return {
             content: [{
               type: "text",
-              text: `Refusing to execute ${tool.originalName}: the signed authorization requires review (commitment_mode="${auth.signedCommitmentMode}") but the Authority Server returned no pending approvers. This inconsistency (a possible commitment-mode downgrade) is rejected fail-closed. Re-fetch the authorization or contact the Authority Server operator.`
-            }],
+              text: `Awaiting commitment from domain${auth.deferredCommitmentDomains.length > 1 ? "s" : ""} "${auth.deferredCommitmentDomains.join('", "')}" for tool ${tool.originalName}.
+Proposal ID: ${proposal.id}. Check status with check-pending-commitments(proposal_id: "${proposal.id}").`
+            }]
+          };
+        } catch (err) {
+          return {
+            content: [{ type: "text", text: `Failed to submit proposal: ${err instanceof Error ? err.message : String(err)}` }],
             isError: true
           };
         }
-        if ((auth.deferredCommitmentDomains ?? []).length > 0) {
+      }
+      let receiptId;
+      try {
+        const actionType = typeof execution.action_type === "string" ? execution.action_type : void 0;
+        if (!actionType) {
+          console.error(
+            `[Suveren MCP] Warning: tool ${tool.namespacedName} has no action_type in staticExecution. Bounds check may be skipped. Fix the integration manifest.`
+          );
+        }
+        const binding = computeContentBinding(auth.profileId, tool, args);
+        const { receipt } = await state2.spClient.postReceipt({
+          authorizationId: authzId,
+          // Optional cross-check — the AS fails closed on a mismatch.
+          boundsHash: auth.boundsHash,
+          profileId: auth.profileId,
+          action: tool.namespacedName,
+          actionType,
+          executionContext: { ...execution },
+          amount: typeof execution.amount === "number" ? execution.amount : void 0,
+          idempotencyKey: randomUUID(),
+          ...binding ?? {}
+        });
+        receiptId = typeof receipt?.id === "string" ? receipt.id : void 0;
+      } catch (err) {
+        if (err instanceof SPReceiptError && err.statusCode === 409) {
+          const spBody = err.body;
+          let pendingApprovers = spBody.approvers ?? [];
+          if (pendingApprovers.length === 0) {
+            try {
+              const summary = await state2.spClient.getAuthorizationSummary(authzId);
+              if (summary?.approvers_frozen) {
+                pendingApprovers = summary.approvers_frozen;
+              }
+              if (summary?.created_by) {
+                pendingApprovers = [summary.created_by, ...pendingApprovers];
+              }
+            } catch {
+            }
+          } else {
+            try {
+              const summary = await state2.spClient.getAuthorizationSummary(authzId);
+              if (summary?.created_by) {
+                pendingApprovers = [summary.created_by, ...pendingApprovers];
+              }
+            } catch {
+            }
+          }
+          const uniqueApprovers = [...new Set(pendingApprovers)];
           try {
             const enrichedArgs = await attachImagePreview(args);
             const { proposal } = await state2.spClient.submitProposal({
               authorizationId: authzId,
               profileId: auth.profileId,
               path: auth.path,
-              pendingDomains: auth.deferredCommitmentDomains,
+              pendingDomains: [],
               tool: tool.namespacedName,
               toolArgs: enrichedArgs,
-              executionContext: { ...execution }
+              executionContext: { ...execution },
+              pendingApprovers: uniqueApprovers
             });
             return {
               content: [{
                 type: "text",
-                text: `Awaiting commitment from domain${auth.deferredCommitmentDomains.length > 1 ? "s" : ""} "${auth.deferredCommitmentDomains.join('", "')}" for tool ${tool.originalName}.
-Proposal ID: ${proposal.id}. Check status with check-pending-commitments(proposal_id: "${proposal.id}").`
+                text: `Action exceeds team cap. Approval required from ${uniqueApprovers.length} reviewer(s).
+Proposal ID: ${proposal.id}. Use check-pending-commitments to track status.`
               }]
             };
-          } catch (err) {
+          } catch (proposalErr) {
             return {
-              content: [{ type: "text", text: `Failed to submit proposal: ${err instanceof Error ? err.message : String(err)}` }],
+              content: [{ type: "text", text: `Failed to submit approval proposal: ${proposalErr instanceof Error ? proposalErr.message : String(proposalErr)}` }],
               isError: true
             };
           }
         }
-        let receiptId;
-        try {
-          const actionType = typeof execution.action_type === "string" ? execution.action_type : void 0;
-          if (!actionType) {
-            console.error(
-              `[Suveren MCP] Warning: tool ${tool.namespacedName} has no action_type in staticExecution. Bounds check may be skipped. Fix the integration manifest.`
-            );
-          }
-          const binding = computeContentBinding(auth.profileId, tool, args);
-          const { receipt } = await state2.spClient.postReceipt({
-            authorizationId: authzId,
-            // Optional cross-check — the AS fails closed on a mismatch.
-            boundsHash: auth.boundsHash,
-            profileId: auth.profileId,
-            action: tool.namespacedName,
-            actionType,
-            executionContext: { ...execution },
-            amount: typeof execution.amount === "number" ? execution.amount : void 0,
-            idempotencyKey: randomUUID(),
-            ...binding ?? {}
-          });
-          receiptId = typeof receipt?.id === "string" ? receipt.id : void 0;
-        } catch (err) {
-          if (err instanceof SPReceiptError && err.statusCode === 409) {
-            const spBody = err.body;
-            let pendingApprovers = spBody.approvers ?? [];
-            if (pendingApprovers.length === 0) {
-              try {
-                const summary = await state2.spClient.getAuthorizationSummary(authzId);
-                if (summary?.approvers_frozen) {
-                  pendingApprovers = summary.approvers_frozen;
-                }
-                if (summary?.created_by) {
-                  pendingApprovers = [summary.created_by, ...pendingApprovers];
-                }
-              } catch {
-              }
-            } else {
-              try {
-                const summary = await state2.spClient.getAuthorizationSummary(authzId);
-                if (summary?.created_by) {
-                  pendingApprovers = [summary.created_by, ...pendingApprovers];
-                }
-              } catch {
-              }
-            }
-            const uniqueApprovers = [...new Set(pendingApprovers)];
-            try {
-              const enrichedArgs = await attachImagePreview(args);
-              const { proposal } = await state2.spClient.submitProposal({
-                authorizationId: authzId,
-                profileId: auth.profileId,
-                path: auth.path,
-                pendingDomains: [],
-                tool: tool.namespacedName,
-                toolArgs: enrichedArgs,
-                executionContext: { ...execution },
-                pendingApprovers: uniqueApprovers
-              });
-              return {
-                content: [{
-                  type: "text",
-                  text: `Action exceeds team cap. Approval required from ${uniqueApprovers.length} reviewer(s).
-Proposal ID: ${proposal.id}. Use check-pending-commitments to track status.`
-                }]
-              };
-            } catch (proposalErr) {
-              return {
-                content: [{ type: "text", text: `Failed to submit approval proposal: ${proposalErr instanceof Error ? proposalErr.message : String(proposalErr)}` }],
-                isError: true
-              };
-            }
-          }
-          if (err instanceof SPReceiptError && err.statusCode === 422) {
-            return {
-              content: [{ type: "text", text: `Action blocked: ${err.message} (hard team ceiling \u2014 contact the team admin)` }],
-              isError: true
-            };
-          }
-          if (err instanceof SPReceiptError && err.statusCode === 403) {
-            if (/revoked/i.test(err.message)) {
-              state2.cache.invalidate(auth.authorizationId);
-            }
-            return {
-              content: [{ type: "text", text: `Blocked by SP: ${err.message}` }],
-              isError: true
-            };
+        if (err instanceof SPReceiptError && err.statusCode === 422) {
+          return {
+            content: [{ type: "text", text: `Action blocked: ${err.message} (hard team ceiling \u2014 contact the team admin)` }],
+            isError: true
+          };
+        }
+        if (err instanceof SPReceiptError && err.statusCode === 403) {
+          if (/revoked/i.test(err.message)) {
+            state2.cache.invalidate(auth.authorizationId);
           }
           return {
-            content: [{ type: "text", text: `SP unavailable \u2014 tool call blocked. ${err instanceof Error ? err.message : ""}` }],
+            content: [{ type: "text", text: `Blocked by SP: ${err.message}` }],
             isError: true
           };
         }
-        state2.executionLog.record({
-          profileId: auth.profileId,
-          path: auth.path,
-          execution: { ...execution },
-          timestamp: Math.floor(Date.now() / 1e3)
-        });
-        let outgoingArgs = shouldAttachFooter() && receiptId ? appendVerificationFooter(tool, args, receiptId, auth.subjects?.[0]) : args;
-        if (receiptId) outgoingArgs = attachReceiptId(tool, outgoingArgs, receiptId);
-        return integrationManager2.callTool(tool.integrationId, tool.originalName, outgoingArgs);
+        return {
+          content: [{ type: "text", text: `SP unavailable \u2014 tool call blocked. ${err instanceof Error ? err.message : ""}` }],
+          isError: true
+        };
       }
-      const reasons = result.errors.map((e) => {
-        if (e.code === "BOUND_EXCEEDED") {
-          return `${auth.path}: ${e.field}: ${e.message}`;
-        }
-        return `${auth.path}: ${e.message}`;
+      state2.executionLog.record({
+        profileId: auth.profileId,
+        path: auth.path,
+        execution: { ...execution },
+        timestamp: Math.floor(Date.now() / 1e3)
       });
-      errors.push(...reasons);
+      let outgoingArgs = shouldAttachFooter() && receiptId ? appendVerificationFooter(tool, args, receiptId, auth.subjects?.[0]) : args;
+      if (receiptId) outgoingArgs = attachReceiptId(tool, outgoingArgs, receiptId);
+      return integrationManager2.callTool(tool.integrationId, tool.originalName, outgoingArgs);
     }
-    return {
-      content: [{
-        type: "text",
-        text: `Tool call rejected by Gatekeeper. Tried ${matchingAuths.length} authorization(s):
-` + errors.map((e) => `  - ${e}`).join("\n")
-      }],
-      isError: true
-    };
-  };
+  });
 }
 function buildProxiedToolDescription(tool, state2) {
   if (!tool.gating || !tool.gating.profile) {
@@ -1392,6 +1913,9 @@ function buildCapabilityMap(profileId, toolGating, integrationManager2) {
 }
 function listAuthorizationsHandler(state2, integrationManager2, contextDir) {
   return async (args) => {
+    if (!state2.spClient.isUnlocked()) {
+      return { content: [{ type: "text", text: lockedNotice("list authorizations") }] };
+    }
     const authorizations = state2.getEnrichedAuthorizations();
     const now = Math.floor(Date.now() / 1e3);
     const domain = args?.domain;
@@ -1435,7 +1959,7 @@ function listAuthorizationsHandler(state2, integrationManager2, contextDir) {
         } catch {
         }
         const shortName = shortProfileName2(auth.profileId);
-        const profile = getProfile3(auth.profileId) ?? getProfile3(shortName);
+        const profile = getProfile4(auth.profileId) ?? getProfile4(shortName);
         if (profile) {
           const consumption = getConsumptionState(auth, state2.executionLog, profile);
           const consumptionText = formatConsumptionFull(consumption);
@@ -1491,7 +2015,7 @@ function listAuthorizationsHandler(state2, integrationManager2, contextDir) {
           lines.push("    Mode: review (each action requires your approval)");
         }
         const shortName = shortProfileName2(auth.profileId);
-        const profile = getProfile3(auth.profileId) ?? getProfile3(shortName);
+        const profile = getProfile4(auth.profileId) ?? getProfile4(shortName);
         if (profile) {
           const consumption = getConsumptionState(auth, state2.executionLog, profile);
           const compact = formatConsumptionCompact(consumption);
@@ -1583,6 +2107,9 @@ function shortProfileName3(profileId) {
 }
 function listIntegrationsHandler(state2, integrationManager2) {
   return async () => {
+    if (!state2.spClient.isUnlocked()) {
+      return { content: [{ type: "text", text: lockedNotice("list integrations") }] };
+    }
     if (!integrationManager2) {
       return { content: [{ type: "text", text: "No integration manager available." }] };
     }
@@ -1700,6 +2227,9 @@ Result: ${resultText}` };
 }
 function checkPendingCommitmentsHandler(state2, integrationManager2) {
   return async (args) => {
+    if (!state2.spClient.isUnlocked()) {
+      return { content: [{ type: "text", text: lockedNotice("check commitments") }] };
+    }
     try {
       if (args.proposal_id) {
         const committed2 = await state2.spClient.getCommittedProposals();
@@ -1938,16 +2468,16 @@ function verifyGateContentHashes(content, auth) {
 }
 
 // src/lib/integration-registry.ts
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync4 } from "fs";
-import { homedir as homedir4 } from "os";
-import { dirname as dirname3, join as join4 } from "path";
-var DEFAULT_DATA_DIR = process.env.SUVEREN_DATA_DIR ?? join4(homedir4(), ".suveren");
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync4, existsSync as existsSync5 } from "fs";
+import { homedir as homedir5 } from "os";
+import { dirname as dirname4, join as join5 } from "path";
+var DEFAULT_DATA_DIR = process.env.SUVEREN_DATA_DIR ?? join5(homedir5(), ".suveren");
 var IntegrationRegistry = class {
   integrations = /* @__PURE__ */ new Map();
   filePath;
   constructor(dataDir) {
     const dir = dataDir ?? DEFAULT_DATA_DIR;
-    this.filePath = join4(dir, "integrations.json");
+    this.filePath = join5(dir, "integrations.json");
     this.load();
   }
   // ─── CRUD ───────────────────────────────────────────────────────────────
@@ -1978,12 +2508,12 @@ var IntegrationRegistry = class {
   }
   // ─── Load / Save ────────────────────────────────────────────────────────
   load() {
-    if (!existsSync4(this.filePath)) {
-      mkdirSync3(dirname3(this.filePath), { recursive: true });
+    if (!existsSync5(this.filePath)) {
+      mkdirSync4(dirname4(this.filePath), { recursive: true });
       return;
     }
     try {
-      const raw = readFileSync4(this.filePath, "utf-8");
+      const raw = readFileSync5(this.filePath, "utf-8");
       const data = JSON.parse(raw);
       const migrated = data.integrations.map((i) => {
         if ("toolGating" in i && !("profile" in i)) {
@@ -2012,37 +2542,38 @@ var IntegrationRegistry = class {
       version: 1,
       integrations: Array.from(this.integrations.values())
     };
-    mkdirSync3(dirname3(this.filePath), { recursive: true });
-    writeFileSync3(this.filePath, JSON.stringify(data, null, 2), { encoding: "utf-8" });
+    mkdirSync4(dirname4(this.filePath), { recursive: true });
+    writeFileSync4(this.filePath, JSON.stringify(data, null, 2), { encoding: "utf-8" });
   }
 };
 
 // src/lib/integration-manager.ts
-import { homedir as homedir5 } from "os";
-import { join as join5 } from "path";
-import { existsSync as existsSync5, writeFileSync as writeFileSync4, mkdirSync as mkdirSync4 } from "fs";
-import { execSync } from "child_process";
+import { homedir as homedir6 } from "os";
+import { join as join6, delimiter } from "path";
+import { existsSync as existsSync6, writeFileSync as writeFileSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync6, rmSync } from "fs";
+import { execFile } from "child_process";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { getProfile as getProfile4 } from "@hap/core";
-var DEFAULT_DATA_DIR2 = process.env.SUVEREN_DATA_DIR ?? join5(homedir5(), ".suveren");
-var INTEGRATIONS_DIR = process.env.SUVEREN_INTEGRATIONS_DIR ?? join5(DEFAULT_DATA_DIR2, "integrations");
-var INTEGRATIONS_BIN = join5(INTEGRATIONS_DIR, "node_modules", ".bin");
+import { getProfile as getProfile5 } from "@hap/core";
+var DEFAULT_DATA_DIR2 = process.env.SUVEREN_DATA_DIR ?? join6(homedir6(), ".suveren");
+var INTEGRATIONS_DIR = process.env.SUVEREN_INTEGRATIONS_DIR ?? join6(DEFAULT_DATA_DIR2, "integrations");
+var INTEGRATIONS_BIN = join6(INTEGRATIONS_DIR, "node_modules", ".bin");
 function buildPath() {
   const base = process.env.PATH ?? "";
-  return [INTEGRATIONS_BIN, base].join(":");
+  return [INTEGRATIONS_BIN, base].join(delimiter);
 }
 function ensureIntegrationsDir() {
-  if (!existsSync5(INTEGRATIONS_DIR)) {
-    mkdirSync4(INTEGRATIONS_DIR, { recursive: true });
+  if (!existsSync6(INTEGRATIONS_DIR)) {
+    mkdirSync5(INTEGRATIONS_DIR, { recursive: true });
   }
-  const pkgPath = join5(INTEGRATIONS_DIR, "package.json");
-  if (!existsSync5(pkgPath)) {
-    writeFileSync4(pkgPath, JSON.stringify({ name: "suveren-integrations", version: "1.0.0", private: true }, null, 2));
+  const pkgPath = join6(INTEGRATIONS_DIR, "package.json");
+  if (!existsSync6(pkgPath)) {
+    writeFileSync5(pkgPath, JSON.stringify({ name: "suveren-integrations", version: "1.0.0", private: true }, null, 2));
   }
 }
 var RESPAWN_DELAYS = [2e3, 4e3, 6e3];
 var MAX_RESPAWN_ATTEMPTS = 3;
+var CONNECT_TIMEOUT_MS = 3e4;
 var IntegrationManager = class {
   constructor(serviceCredentials2) {
     this.serviceCredentials = serviceCredentials2;
@@ -2057,25 +2588,141 @@ var IntegrationManager = class {
     this.onToolsChanged = cb;
   }
   /**
-   * Install an npm package into the managed integrations directory if not already present.
-   * Called automatically before spawning when config.npmPackage is set.
+   * Is `npmPackage` present AND usable?
+   *
+   * The directory existing is not enough: an install that was interrupted
+   * (timeout, Ctrl+C, antivirus lock) leaves the package directory behind
+   * with no package.json and no bin shim. Treating that as "installed" made
+   * every later start fail instantly on a missing binary, with no way to
+   * self-repair — the user saw "Not running" and a Start button that did
+   * nothing, forever. So we verify the manifest parses and its entry points
+   * exist, and treat anything else as not-installed (and reinstallable).
    */
-  ensureInstalled(npmPackage) {
+  isUsableInstall(npmPackage) {
+    const pkgDir = join6(INTEGRATIONS_DIR, "node_modules", ...npmPackage.split("/"));
+    const pkgJson = join6(pkgDir, "package.json");
+    if (!existsSync6(pkgDir) || !existsSync6(pkgJson)) return false;
+    try {
+      const pkg = JSON.parse(readFileSync6(pkgJson, "utf8"));
+      const defaultBinName = (pkg.name ?? npmPackage).split("/").pop() ?? "";
+      const binMap = typeof pkg.bin === "string" ? { [defaultBinName]: pkg.bin } : pkg.bin ?? {};
+      const binEntries = Object.entries(binMap);
+      for (const [binName, target] of binEntries) {
+        if (!existsSync6(join6(pkgDir, target))) return false;
+        if (!this.binShimExists(binName)) return false;
+      }
+      if (binEntries.length === 0 && pkg.main && !existsSync6(join6(pkgDir, pkg.main))) return false;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Does the node_modules/.bin shim for `binName` exist? On Windows npm writes
+   * `<name>`, `<name>.cmd`, and `<name>.ps1`; the .cmd variant is what actually
+   * runs, so any of them present counts.
+   */
+  binShimExists(binName) {
+    if (!binName) return false;
+    const candidates = process.platform === "win32" ? [binName, `${binName}.cmd`, `${binName}.CMD`, `${binName}.ps1`] : [binName];
+    return candidates.some((c) => existsSync6(join6(INTEGRATIONS_BIN, c)));
+  }
+  /**
+   * Install an npm package into the managed integrations directory if not
+   * already present. Called automatically before spawning when
+   * config.npmPackage is set.
+   *
+   * Asynchronous ON PURPOSE. This used to be execSync, which blocked the MCP
+   * server's event loop for the entire install — the port stayed bound but
+   * nothing was answered, so the control plane's /internal/manifests call
+   * failed and the UI showed "Couldn't load integrations". Measured on clean
+   * CI runners: ~3.6s (Linux), ~5.4s (macOS), ~14s (Windows), and far worse
+   * on machines with real-time antivirus.
+   */
+  async ensureInstalled(npmPackage) {
     ensureIntegrationsDir();
-    const binName = npmPackage.split("/").pop()?.replace(/^@/, "") ?? npmPackage;
-    const installed = existsSync5(join5(INTEGRATIONS_DIR, "node_modules", ...npmPackage.split("/")));
-    if (installed) return;
+    if (this.isUsableInstall(npmPackage)) return;
+    const pkgDir = join6(INTEGRATIONS_DIR, "node_modules", ...npmPackage.split("/"));
+    if (existsSync6(pkgDir)) {
+      console.error(`[IntegrationManager] Removing unusable install of ${npmPackage}`);
+      try {
+        rmSync(pkgDir, { recursive: true, force: true });
+      } catch (err) {
+        console.error(`[IntegrationManager] Could not clean ${pkgDir}:`, err);
+      }
+    }
+    if (!/^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(npmPackage)) {
+      throw new Error(`Refusing to install unsafe package name: ${JSON.stringify(npmPackage)}`);
+    }
     console.error(`[IntegrationManager] Installing ${npmPackage}...`);
+    const startedAt = Date.now();
+    const isWin = process.platform === "win32";
+    await new Promise((resolve3, reject) => {
+      const child = execFile(
+        "npm",
+        ["install", "--no-fund", "--no-audit", npmPackage],
+        {
+          cwd: INTEGRATIONS_DIR,
+          // Windows: a shell so cmd.exe finds npm.cmd (see EINVAL note above).
+          // POSIX: no shell — npm is a normal executable and keeping shell off
+          // means the validated package name is still passed as a bare argv.
+          shell: isWin,
+          // No timeout: a slow install on a machine with antivirus is not an
+          // error, and killing it midway is what created broken installs in
+          // the first place. Progress is visible in the log.
+          maxBuffer: 10 * 1024 * 1024,
+          windowsHide: true
+        },
+        (err, _stdout, stderr) => {
+          if (err) {
+            reject(new Error(`Failed to install ${npmPackage}: ${err.message}${stderr ? ` \u2014 ${stderr.trim()}` : ""}`));
+            return;
+          }
+          resolve3();
+        }
+      );
+      child.on("error", (err) => reject(new Error(`Failed to run npm for ${npmPackage}: ${err.message}`)));
+    });
+    if (!this.isUsableInstall(npmPackage)) {
+      throw new Error(
+        `Installed ${npmPackage} but it is not usable \u2014 package.json or its bin target is missing. Check ${INTEGRATIONS_DIR} for a partial install.`
+      );
+    }
+    console.error(`[IntegrationManager] Installed ${npmPackage} (${((Date.now() - startedAt) / 1e3).toFixed(1)}s)`);
+  }
+  /**
+   * Connect a client to its transport, but never wait indefinitely. Resolves
+   * on a successful handshake; rejects if the transport errors (child crash /
+   * spawn failure) or the handshake exceeds CONNECT_TIMEOUT_MS. On failure the
+   * transport is closed so the child process can't linger.
+   */
+  async connectWithGuard(client, transport, config) {
+    let timer;
+    let settled = false;
+    const guard = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => {
+        if (settled) return;
+        reject(new Error(
+          `Timed out after ${CONNECT_TIMEOUT_MS}ms connecting to ${config.id} (${config.command} ${config.args.join(" ")}) \u2014 the downstream server did not complete the MCP handshake. It may have crashed on startup.`
+        ));
+      }, CONNECT_TIMEOUT_MS);
+      transport.onerror = (err) => {
+        if (settled) return;
+        reject(new Error(`Transport error while connecting to ${config.id}: ${err.message}`));
+      };
+    });
     try {
-      execSync(`npm install --no-fund --no-audit ${npmPackage}`, {
-        cwd: INTEGRATIONS_DIR,
-        stdio: ["pipe", "pipe", "pipe"],
-        timeout: 12e4
-      });
-      console.error(`[IntegrationManager] Installed ${npmPackage}`);
+      await Promise.race([client.connect(transport), guard]);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new Error(`Failed to install ${npmPackage}: ${message}`);
+      try {
+        await transport.close();
+      } catch {
+      }
+      throw err;
+    } finally {
+      settled = true;
+      if (timer) clearTimeout(timer);
+      transport.onerror = void 0;
     }
   }
   /**
@@ -2088,12 +2735,14 @@ var IntegrationManager = class {
       await this.stopIntegration(config.id);
     }
     if (config.npmPackage) {
-      this.ensureInstalled(config.npmPackage);
+      await this.ensureInstalled(config.npmPackage);
     }
     const env = this.resolveEnvKeys(config);
+    const interpolate = (s) => s.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => env[name] ?? process.env[name] ?? "");
+    const args = config.args.map(interpolate);
     const transport = new StdioClientTransport({
       command: config.command,
-      args: config.args,
+      args,
       env: {
         ...process.env,
         PATH: buildPath(),
@@ -2106,10 +2755,10 @@ var IntegrationManager = class {
       { name: "suveren-gateway", version: "0.1.0" },
       { capabilities: {} }
     );
-    await client.connect(transport);
+    await this.connectWithGuard(client, transport, config);
     console.error(`[IntegrationManager] Connected to ${config.id} (${config.command} ${config.args.join(" ")})`);
     const toolsResult = await client.listTools();
-    const profileGating = config.toolGating ?? (config.profile ? getProfile4(config.profile)?.toolGating ?? null : null);
+    const profileGating = config.toolGating ?? (config.profile ? getProfile5(config.profile)?.toolGating ?? null : null);
     const tools = (toolsResult.tools ?? []).map((tool) => {
       const gating = this.resolveToolGating(config.profile, profileGating, tool.name);
       return {
@@ -2188,6 +2837,16 @@ var IntegrationManager = class {
     }
     return tools;
   }
+  /**
+   * RESERVED / NOT YET WIRED (see IntegrationConfig.readAgeDays). The local
+   * read-age window (days) for a running integration, for a deferred feature
+   * that moves the read age off the signed grant. The read path does NOT call
+   * this yet — it still enforces the signed `read_max_age_days` bound.
+   */
+  getReadAgeDays(integrationId) {
+    const days = this.running.get(integrationId)?.config.readAgeDays;
+    return typeof days === "number" && Number.isFinite(days) ? days : null;
+  }
   /**
    * Get status info for all known integrations.
    */
@@ -2279,11 +2938,20 @@ var IntegrationManager = class {
     if (!profileId || !profileGating) return null;
     if (profileGating.overrides && toolName in profileGating.overrides) {
       const override = profileGating.overrides[toolName];
-      if (override === null || override.category === "read") {
+      const ext = override ?? {};
+      if (ext.category === "disabled") {
+        return { profile: profileId, executionMapping: {}, category: "disabled" };
+      }
+      if (override === null || ext.category === "read") {
         return {
           profile: profileId,
           executionMapping: {},
-          category: "read"
+          category: "read",
+          boundField: ext.boundField,
+          requiredValue: ext.requiredValue,
+          read: ext.read,
+          readGovernance: ext.readGovernance,
+          readGovernanceReason: ext.readGovernanceReason
         };
       }
       return {
@@ -2337,28 +3005,28 @@ var IntegrationManager = class {
 };
 
 // src/lib/profile-loader.ts
-import { readFileSync as readFileSync5, existsSync as existsSync6 } from "fs";
-import { join as join6, resolve } from "path";
+import { readFileSync as readFileSync7, existsSync as existsSync7 } from "fs";
+import { join as join7, resolve } from "path";
 import { registerProfile } from "@hap/core";
 function loadProfiles(profilesDir) {
-  const dir = resolve(profilesDir ?? process.env.SUVEREN_PROFILES_DIR ?? join6(import.meta.dirname ?? __dirname, "..", "..", "..", "..", "..", "hap-profiles"));
-  const indexPath = join6(dir, "index.json");
-  if (!existsSync6(indexPath)) {
+  const dir = resolve(profilesDir ?? process.env.SUVEREN_PROFILES_DIR ?? join7(import.meta.dirname ?? __dirname, "..", "..", "..", "..", "..", "hap-profiles"));
+  const indexPath = join7(dir, "index.json");
+  if (!existsSync7(indexPath)) {
     warnNoProfiles(`No index.json at ${indexPath}`);
     return 0;
   }
   let index;
   try {
-    index = JSON.parse(readFileSync5(indexPath, "utf-8"));
+    index = JSON.parse(readFileSync7(indexPath, "utf-8"));
   } catch (err) {
     console.error(`[ProfileLoader] Failed to parse ${indexPath}:`, err);
     return 0;
   }
   let loaded = 0;
   for (const [profileId, relativePath] of Object.entries(index.profiles)) {
-    const profilePath = join6(dir, relativePath);
+    const profilePath = join7(dir, relativePath);
     try {
-      const profile = JSON.parse(readFileSync5(profilePath, "utf-8"));
+      const profile = JSON.parse(readFileSync7(profilePath, "utf-8"));
       registerProfile(profileId, profile);
       const shortName = profileId.split("/").pop()?.replace(/@.*$/, "");
       if (shortName && shortName !== profileId) {
@@ -2391,30 +3059,30 @@ function warnNoProfiles(reason) {
 }
 
 // src/lib/manifest-loader.ts
-import { readFileSync as readFileSync6, existsSync as existsSync7 } from "fs";
-import { join as join7, resolve as resolve2 } from "path";
+import { readFileSync as readFileSync8, existsSync as existsSync8 } from "fs";
+import { join as join8, resolve as resolve2 } from "path";
 var manifests = /* @__PURE__ */ new Map();
 function loadManifests(integrationsDir) {
   const dir = resolve2(
-    integrationsDir ?? process.env.SUVEREN_MANIFESTS_DIR ?? join7(import.meta.dirname ?? __dirname, "..", "..", "..", "..", "content", "integrations")
+    integrationsDir ?? process.env.SUVEREN_MANIFESTS_DIR ?? join8(import.meta.dirname ?? __dirname, "..", "..", "..", "..", "content", "integrations")
   );
-  const indexPath = join7(dir, "index.json");
-  if (!existsSync7(indexPath)) {
+  const indexPath = join8(dir, "index.json");
+  if (!existsSync8(indexPath)) {
     console.error(`[ManifestLoader] No index.json found at ${indexPath}, skipping manifest loading`);
     return 0;
   }
   let index;
   try {
-    index = JSON.parse(readFileSync6(indexPath, "utf-8"));
+    index = JSON.parse(readFileSync8(indexPath, "utf-8"));
   } catch (err) {
     console.error(`[ManifestLoader] Failed to parse ${indexPath}:`, err);
     return 0;
   }
   let loaded = 0;
   for (const [id, relativePath] of Object.entries(index.integrations)) {
-    const manifestPath = join7(dir, relativePath);
+    const manifestPath = join8(dir, relativePath);
     try {
-      const manifest = JSON.parse(readFileSync6(manifestPath, "utf-8"));
+      const manifest = JSON.parse(readFileSync8(manifestPath, "utf-8"));
       manifests.set(id, manifest);
       loaded++;
     } catch (err) {
@@ -2492,8 +3160,10 @@ app.post("/internal/configure", internalOnly, (req, res) => {
   state.spClient.setSessionCookie(sessionCookie);
   console.error("[Suveren MCP] Session cookie configured by control-plane");
   if (vaultKeyHex) {
-    state.gateStore.setVaultKey(Buffer.from(vaultKeyHex, "hex"));
-    console.error("[Suveren MCP] Vault key configured \u2014 gate store encryption active");
+    const key = Buffer.from(vaultKeyHex, "hex");
+    state.gateStore.setVaultKey(key);
+    state.denialLog.setVaultKey(key);
+    console.error("[Suveren MCP] Vault key configured \u2014 gate store + denial log encryption active");
   }
   if (apiKey) {
     state.spClient.setApiKey(apiKey);