@dzhechkov/cloudru-hub 0.1.12 → 0.1.13

package/src/install.js

@@ -1,12 +1,12 @@
 'use strict';
-// Per-target installer — ADR-005 tiering (tier derived from flow requirements R1–R5,
-// live-probe discipline) + ADR-004 brake emission (permission ask/deny + PreToolUse veto).
+// Per-target installer — Claude settings plus guarded MCP registrations for other hosts.
 //
 // Tier map (ADR-005 Decision, applied verbatim):
 //   claude-code  FULL candidate — full install path (this module emits it)
-//   codex        FULL candidate #2 — plan printed, NOT auto-applied (delivery requires an
-//                EXECUTED veto probe; project hooks.json is a measured silent no-op)
-//   openclaude / opencode / cursor / windsurf / copilot
+//   codex / opencode / pi — project-scoped, pinned read-only MCP proxy;
+//                host activation still needs a live probe
+//   hermes       guarded MCP entry in $HERMES_HOME/config.yaml (complex YAML refused)
+//   openclaude / cursor / windsurf / copilot
 //                DEGRADED-until-proven — installer REFUSES (no live probe delivered yet)
 //   agents-md / gemini
 //                POINTER-ONLY — ≤2048-char pointer + no-veto warning, never a fake install
@@ -16,18 +16,25 @@
 // (ADR-004/ADR-005: "наличие файла хука — не evidence"; layout ≠ registration).
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const { isDeepStrictEqual } = require('util');
 const { spawnSync } = require('child_process');
-const { permissionRules } = require('./classification');
+const YAML = require('yaml');
+const { permissionRules, loadClassification } = require('./classification');
+const { resolveEngine } = require('./resolve');
+const { selectedToolNames } = require('./toolsets');
 
 const HOOK_TEMPLATE = path.join(__dirname, '..', 'templates', '.claude', 'hooks', 'cloudru-ssh-guard.cjs');
 const POINTER_TEMPLATE = path.join(__dirname, '..', 'data', 'pointer-section.md');
 
 const TIERS = {
   'claude-code': 'full',
-  codex: 'plan-only',
+  codex: 'safe-mcp',
+  hermes: 'safe-mcp',
+  opencode: 'safe-mcp',
+  pi: 'safe-mcp',
   openclaude: 'degraded',
-  opencode: 'degraded',
   cursor: 'degraded',
   windsurf: 'degraded',
   copilot: 'degraded',
@@ -37,7 +44,6 @@ const TIERS = {
 
 const DEGRADED_REASONS = {
   openclaude: 'all three legs exist upstream (.mcp.json, PreToolUse deny, .openclaude/skills) but NOTHING has been probed live — degraded-until-proven (ADR-005).',
-  opencode: 'MCP + veto plugins are documented, zero live runs; R4 (tool budget deferral) unverified (ADR-005).',
   cursor: 'veto hooks documented only; R3 broken by the .mdc adapter, R4 truncation history (~40 tools) unresolved (ADR-005).',
   windsurf: 'R4 FAILS as-is: Cascade budget 100 tools < 144 — needs the engine tool-profile before any delivery (ADR-005).',
   copilot: 'only Copilot CLI is a candidate; the coding agent fails R2 by construction ("will not ask for your approval" + hook timeout fail-open) (ADR-005).',
@@ -118,6 +124,221 @@ function writeJson(file, obj) {
   fs.writeFileSync(file, JSON.stringify(obj, null, 2) + '\n');
 }
 
+const SAFE_SERVER = 'cloudru_hub';
+const longRunningProfile = (toolsets) => toolsets === 'vm-deploy' || toolsets === 'k8s-deploy';
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function safeCommand(toolsets) {
+  return { command: process.execPath, args: [path.join(__dirname, '..', 'bin', 'cloudru-hub.js'), 'mcp-safe', '--toolsets', toolsets] };
+}
+
+function installClaudeK8s(projectDir, opts = {}) {
+  if (opts.npx) return { code: 2, lines: ['cloudru-hub install: k8s-deploy requires the local guarded launcher; npx package publication is not assumed.'] };
+  const file = path.join(projectDir, '.mcp.json');
+  const settingsFile = path.join(projectDir, '.claude', 'settings.json');
+  if ((fs.existsSync(file) && !readJson(file)) || (fs.existsSync(settingsFile) && !readJson(settingsFile))) {
+    return { code: 2, lines: ['cloudru-hub install: existing Claude JSON is invalid; refusing to replace it.'] };
+  }
+  const mcp = readJson(file) || {};
+  if (!record(mcp)) return { code: 2, lines: ['cloudru-hub install: Claude MCP JSON root must be an object.'] };
+  if (mcp.mcpServers && !record(mcp.mcpServers)) {
+    return { code: 2, lines: ['cloudru-hub install: existing Claude MCP server map is invalid.'] };
+  }
+  const servers = mcp.mcpServers || {};
+  if (servers['cloudru-vm'] || servers.cloudru_vm) return { code: 2, lines: ['cloudru-hub install: raw Cloud.ru MCP server is present; remove it from this isolated project before enabling k8s-deploy.'] };
+  const cmd = safeCommand('k8s-deploy');
+  const desired = { command: cmd.command, args: cmd.args };
+  if (servers[SAFE_SERVER] && !isDeepStrictEqual(servers[SAFE_SERVER], desired)) {
+    return { code: 2, lines: ['cloudru-hub install: existing cloudru_hub server differs from the guarded k8s-deploy command.'] };
+  }
+  const settings = readJson(settingsFile) || {};
+  if (!record(settings)) return { code: 2, lines: ['cloudru-hub install: Claude settings JSON root must be an object.'] };
+  if (settings.enabledMcpjsonServers && !Array.isArray(settings.enabledMcpjsonServers)) {
+    return { code: 2, lines: ['cloudru-hub install: existing Claude enabled server list is invalid.'] };
+  }
+  if (settings.enabledMcpjsonServers?.some((name) => name === 'cloudru-vm' || name === 'cloudru_vm')) {
+    return { code: 2, lines: ['cloudru-hub install: raw Cloud.ru MCP server is enabled in Claude settings; use an isolated project.'] };
+  }
+  mcp.mcpServers = { ...servers, [SAFE_SERVER]: desired };
+  writeJson(file, mcp);
+  writeJson(settingsFile, { ...settings, enabledMcpjsonServers: unionSorted(settings.enabledMcpjsonServers, [SAFE_SERVER]) });
+  return { code: 0, lines: [`cloudru-hub install: guarded k8s-deploy server written to ${file}.`,
+    '  Claude Code activation and actual agent calls remain unverified until inference access returns.'] };
+}
+
+function installJsonMcp(target, projectDir, toolsets) {
+  const opencode = target === 'opencode';
+  const file = path.join(projectDir, opencode ? 'opencode.json' : '.pi/mcp.json');
+  if (opencode && fs.existsSync(path.join(projectDir, 'opencode.jsonc'))) {
+    return { code: 2, lines: ['cloudru-hub install: REFUSED — opencode.jsonc exists; merge the safe server manually to avoid competing project configs.'] };
+  }
+  let config = {};
+  if (fs.existsSync(file)) {
+    try { config = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch { return { code: 2, lines: [`cloudru-hub install: REFUSED — ${file} is not strict JSON; no changes written.`] }; }
+  }
+  if (!config || Array.isArray(config) || typeof config !== 'object') return { code: 2, lines: ['cloudru-hub install: REFUSED — config root is not an object.'] };
+  const parent = opencode ? config.mcp : config.mcpServers;
+  if (parent != null && (Array.isArray(parent) || typeof parent !== 'object')) return { code: 2, lines: ['cloudru-hub install: REFUSED — MCP config is not an object.'] };
+  const servers = parent || {};
+  if (servers['cloudru-vm'] || servers.cloudru_vm) return { code: 2, lines: ['cloudru-hub install: REFUSED — a raw cloudru-vm server already exists; remove it before enabling the safe server.'] };
+  const cmd = safeCommand(toolsets);
+  const entry = opencode
+    ? { type: 'local', command: [cmd.command, ...cmd.args], enabled: true, ...(longRunningProfile(toolsets) ? { timeout: 1_200_000 } : {}) }
+    : { ...cmd, enabled: true, ...(longRunningProfile(toolsets) ? { timeout: 1200 } : {}), description: toolsets === 'vm-deploy' ? 'Pinned Cloud.ru VM deployment with local plan approval' : toolsets === 'k8s-deploy' ? 'Pinned Cloud.ru Kubernetes deployment with exact-manifest approval' : 'Pinned Cloud.ru MCP tools with cloud mutations blocked' };
+  if (servers[SAFE_SERVER] && JSON.stringify(servers[SAFE_SERVER]) !== JSON.stringify(entry)) {
+    return { code: 2, lines: [`cloudru-hub install: REFUSED — ${SAFE_SERVER} already has a different configuration.`] };
+  }
+  servers[SAFE_SERVER] = entry;
+  if (opencode) config.mcp = servers;
+  else config.mcpServers = servers;
+  writeJson(file, config);
+  return { code: 0, lines: [`cloudru-hub install: wrote ${file} with ${SAFE_SERVER} → mcp-safe.`, '  Activation requires a trusted project and a host-side connection probe; no live host claim made.'] };
+}
+
+function installCodex(projectDir, toolsets) {
+  const file = path.join(projectDir, '.codex', 'config.toml');
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const cmd = safeCommand(toolsets);
+  const tools = selectedToolNames(toolsets);
+  const inheritedEnv = longRunningProfile(toolsets)
+    ? ['CLOUDRU_VM_BIN', 'CLOUDRU_HUB_CREDENTIALS', 'CLOUDRU_VM_HOME', 'CLOUDRU_HUB_APPROVALS']
+    : ['CLOUDRU_VM_BIN'];
+  if (tools.some((name) => name.startsWith('billing_'))) {
+    for (const name of ['CLOUDRU_HUB_CREDENTIALS', 'CLOUDRU_AGREEMENT_ID', 'CLOUDRU_KEY_ID', 'CLOUDRU_SECRET', 'CLOUDRU_PROJECT_ID', 'CLOUDRU_REGION']) {
+      if (!inheritedEnv.includes(name)) inheritedEnv.push(name);
+    }
+  }
+  const entry = `# cloudru-hub safe BEGIN\n[mcp_servers.${SAFE_SERVER}]\ncommand = ${JSON.stringify(cmd.command)}\nargs = ${JSON.stringify(cmd.args)}\nenv_vars = ${JSON.stringify(inheritedEnv)}\nrequired = true\nenabled_tools = ${JSON.stringify(tools)}\ndefault_tools_approval_mode = ${JSON.stringify(longRunningProfile(toolsets) ? 'auto' : 'prompt')}\n${longRunningProfile(toolsets) ? 'tool_timeout_sec = 1200\n' : ''}# cloudru-hub safe END\n`;
+  // TOML has quoted/dotted keys and inline tables. A regex that checks only a
+  // bare section name can leave a raw server enabled alongside this one. The
+  // zero-dependency installer therefore owns its exact block and refuses any
+  // other MCP declaration for manual review rather than guessing its meaning.
+  const remainder = existing.includes(entry) ? existing.replace(entry, '') : existing;
+  if (/mcp_servers|^\s*(?:\[\s*["']|["'][^"']+["']\s*=)|\\u[0-9a-f]{4}/im.test(remainder)) {
+    return { code: 2, lines: ['cloudru-hub install: REFUSED — existing MCP/TOML syntax needs manual review before adding a safe server.'] };
+  }
+  if (remainder !== existing) return { code: 0, lines: [`cloudru-hub install: ${file} already contains the safe server.`] };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, existing.trimEnd() + '\n' + entry);
+  return { code: 0, lines: [`cloudru-hub install: wrote ${file} with ${tools.length} classified tools and mcp-safe.`, '  Codex loads project config only in a trusted project; run a live host probe before claiming activation.'] };
+}
+
+function hermesBlock(toolsets, enginePath, indent = '  ') {
+  const cmd = safeCommand(toolsets);
+  const include = selectedToolNames(toolsets);
+  return [
+    `${indent}# cloudru-hub safe BEGIN`,
+    `${indent}${SAFE_SERVER}:`,
+    `${indent}${indent}command: ${JSON.stringify(cmd.command)}`,
+    `${indent}${indent}args: ${JSON.stringify(cmd.args)}`,
+    `${indent}${indent}env:`,
+    `${indent}${indent}${indent}CLOUDRU_VM_BIN: ${JSON.stringify(enginePath)}`,
+    `${indent}${indent}enabled: true`,
+    `${indent}${indent}timeout: ${longRunningProfile(toolsets) ? 1200 : 120}`,
+    `${indent}${indent}tools:`,
+    `${indent}${indent}${indent}include: [${include.map((name) => JSON.stringify(name)).join(', ')}]`,
+    `${indent}# cloudru-hub safe END`,
+  ].join('\n') + '\n';
+}
+
+function installHermes(toolsets, opts = {}) {
+  const home = path.resolve(opts.hermesHome || process.env.HERMES_HOME || path.join(os.homedir(), '.hermes'));
+  const file = path.join(home, 'config.yaml');
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const refuse = (reason) => ({ code: 2, lines: [`cloudru-hub install: REFUSED — ${reason}; ${file} was not changed.`] });
+  let original;
+  let before;
+  try {
+    original = YAML.parseDocument(existing, { uniqueKeys: true });
+    if (original.errors.length || (original.contents && (!YAML.isMap(original.contents) || original.contents.flow))) {
+      return refuse('existing YAML is invalid or not a block mapping');
+    }
+    before = original.toJS() || {};
+    if (before.mcp_servers != null && (Array.isArray(before.mcp_servers) || typeof before.mcp_servers !== 'object')) {
+      return refuse('mcp_servers is not a mapping');
+    }
+  } catch { return refuse('existing YAML could not be parsed'); }
+  if (/\t|^---\s*$|^\.\.\.\s*$/m.test(existing)) return refuse('complex YAML needs manual review');
+  const sections = [...existing.matchAll(/^mcp_servers:\s*(?:#.*)?$/gm)];
+  if (sections.length > 1) return refuse('duplicate mcp_servers sections');
+  if (!sections.length && /^mcp_servers\s*:/m.test(existing)) return refuse('mcp_servers is not a plain top-level mapping');
+  if (!sections.length && /(?:^|\n)\s*["']?mcp_servers["']?\s*:/m.test(existing)) return refuse('complex mcp_servers syntax needs manual review');
+  // YAML duplicate keys may be accepted with last-value-wins semantics. A
+  // quoted second mcp_servers key could hide the server we just inserted.
+  if ((existing.match(/mcp_servers/g) || []).length !== sections.length || /\\[uxU][0-9a-f]+/i.test(existing)) {
+    return refuse('duplicate or escaped YAML keys need manual review');
+  }
+
+  let indent = '  ';
+  let insertAt = existing.length;
+  let blockText = '';
+  if (sections.length) {
+    const section = sections[0];
+    const contentStart = section.index + section[0].length + (existing[section.index + section[0].length] === '\n' ? 1 : 0);
+    const next = /^\S[^\n]*$/gm;
+    next.lastIndex = contentStart;
+    const match = next.exec(existing);
+    insertAt = match ? match.index : existing.length;
+    blockText = existing.slice(contentStart, insertAt);
+    const indents = [...blockText.matchAll(/^([ ]+)(\S.*)$/gm)]
+      .filter((m) => !m[2].startsWith('#')).map((m) => m[1].length);
+    if (indents.length) {
+      const min = Math.min(...indents);
+      indent = ' '.repeat(min);
+      if (min > 8) return refuse('unusual mcp_servers indentation');
+    }
+  } else if (/\b(?:cloudru[-_]vm|cloudru_hub)\b/i.test(existing)) {
+    return refuse('Cloud.ru configuration is already mentioned');
+  }
+
+  // Hermes deliberately strips non-baseline environment variables before
+  // starting MCP servers. Resolve the engine now and pass only its path in
+  // the server-specific env; the proxy hashes the file again at runtime.
+  const engine = opts.resolvedEngine || resolveEngine();
+  if (engine.error || !engine.verified || !engine.path || engine.sha256 !== loadClassification().engineSha256) {
+    return refuse('a locally available, hash-verified Cloud.ru engine is required for Hermes');
+  }
+  const enginePath = path.resolve(engine.path);
+  const block = hermesBlock(toolsets, enginePath, indent);
+  if (/\b(?:cloudru[-_]vm|cloudru_hub)\b/i.test(existing.replace(block, ''))) {
+    return refuse('a Cloud.ru server is already mentioned outside this exact safe block');
+  }
+  if (blockText.includes('# cloudru-hub safe BEGIN')) {
+    const remainder = blockText.replace(block, '');
+    if (remainder !== blockText && !/\b(?:cloudru[-_]vm|cloudru_hub)\b|[&*]|<<\s*:/i.test(remainder)) {
+      return { code: 0, lines: [`cloudru-hub install: ${file} already contains the safe server.`] };
+    }
+    return refuse('existing cloudru-hub block differs from the requested toolset');
+  }
+  if (/\b(?:cloudru[-_]vm|cloudru_hub)\b|[&*]|<<\s*:/i.test(blockText)) return refuse('Cloud.ru server or YAML aliases already occur in mcp_servers');
+  const updated = sections.length
+    ? existing.slice(0, insertAt) + (insertAt && existing[insertAt - 1] !== '\n' ? '\n' : '') + block + existing.slice(insertAt)
+    : existing.trimEnd() + (existing.trim() ? '\n\n' : '') + 'mcp_servers:\n' + block;
+  try {
+    const candidate = YAML.parseDocument(updated, { uniqueKeys: true });
+    if (candidate.errors.length) return refuse('generated YAML failed syntax validation');
+    const cmd = safeCommand(toolsets);
+    const expected = {
+      ...before,
+      mcp_servers: {
+        ...(before.mcp_servers || {}),
+        [SAFE_SERVER]: { command: cmd.command, args: cmd.args, env: { CLOUDRU_VM_BIN: enginePath }, enabled: true, timeout: longRunningProfile(toolsets) ? 1200 : 120, tools: { include: selectedToolNames(toolsets) } },
+      },
+    };
+    if (!isDeepStrictEqual(candidate.toJS(), expected)) return refuse('generated YAML would change other configuration');
+  } catch { return refuse('generated YAML could not be validated'); }
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+  const tmp = path.join(home, `.config.yaml.cloudru-hub-${process.pid}.tmp`);
+  try {
+    fs.writeFileSync(tmp, updated, { flag: 'wx', mode: fs.existsSync(file) ? fs.statSync(file).mode & 0o777 : 0o600 });
+    fs.renameSync(tmp, file);
+  } finally {
+    if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+  }
+  return { code: 0, lines: [`cloudru-hub install: wrote ${file} with ${selectedToolNames(toolsets).length} classified tools and mcp-safe.`, '  Restart Hermes and inspect loaded MCP tools before claiming activation.'] };
+}
+
 /**
  * Execute the emitted brake against the ADR-004 acid fixtures and REQUIRE the veto.
  * Returns {ok, results:[{fixture, expected, got}]}. An installer that skips this and
@@ -141,16 +362,23 @@ function probeBrake(hookPath) {
   return { ok, results };
 }
 
-/**
- * Install into a project dir for a target. Pure I/O orchestration; returns
- * {code, lines:[...]} — code 0 success, 2 refused (degraded), 3 plan-only, 1 failure.
- */
+/** Install files or print guarded setup instructions; code 0 emitted, 2 refused, 3 manual setup. */
 function install(target, projectDir, opts = {}) {
   const lines = [];
   const tier = TIERS[target];
   if (!tier) {
     return { code: 1, lines: [`cloudru-hub install: unknown target "${target}" (known: ${Object.keys(TIERS).join(', ')})`] };
   }
+  const toolsets = opts.toolsets || 'inventory';
+  if (target === 'claude-code' && toolsets === 'k8s-deploy') {
+    try { selectedToolNames(toolsets); }
+    catch (error) { return { code: 1, lines: [`cloudru-hub install: ${error.message}`] }; }
+    return installClaudeK8s(projectDir, opts);
+  }
+  if (['codex', 'opencode', 'pi', 'hermes'].includes(target)) {
+    try { selectedToolNames(toolsets); }
+    catch (error) { return { code: 1, lines: [`cloudru-hub install: ${error.message}`] }; }
+  }
 
   if (tier === 'degraded') {
     return {
@@ -178,20 +406,10 @@ function install(target, projectDir, opts = {}) {
     };
   }
 
-  if (tier === 'plan-only') {
-    // codex: strongest non-Claude-Code target, but hooks are user-global-only and a
-    // non-executed veto is indistinguishable from an absent one (measured, codex.md §3).
-    return {
-      code: 3,
-      lines: [
-        'cloudru-hub install: target "codex" — plan printed, NOT auto-applied (ADR-005: delivery requires an EXECUTED veto probe).',
-        '  1. codex mcp add cloudru-vm -- cloudru-hub mcp        # registers the stdio server in ~/.codex/config.toml',
-        `  2. Merge into ~/.codex/hooks.json (user-global ONLY — project hooks.json is a measured silent no-op):`,
-        `     {"hooks":{"preToolUse":[{"command":"node ${HOOK_TEMPLATE}"}]}}`,
-        '  3. MANDATORY probe: in a codex session run `sshpass -p x ssh user1@1.2.3.4` and CONFIRM the block message.',
-        '     A hook file on disk is NOT evidence (health-advisor 1.2.0 lesson: layout ≠ registration).',
-      ],
-    };
+  if (tier === 'safe-mcp') {
+    if (target === 'codex') return installCodex(projectDir, toolsets);
+    if (target === 'hermes') return installHermes(toolsets, opts);
+    return installJsonMcp(target, projectDir, toolsets);
   }
 
   // ── claude-code FULL path ──
@@ -248,5 +466,6 @@ module.exports = {
   mergeHookEvents,
   claudeSettingsFragment,
   probeBrake,
+  installClaudeK8s,
   install,
 };

package/src/k8s-approval.js

@@ -0,0 +1,208 @@
+'use strict';
+
+// An opt-in, exact-manifest approval for an existing Kubernetes cluster.
+// The model never supplies the manifest, cluster, namespace or confirmation
+// forwarded to the engine. The local operator reviews the file and its digest.
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { isDeepStrictEqual } = require('util');
+const YAML = require('yaml');
+const { readCredentials, UUID } = require('./credentials');
+const { approvalRoot } = require('./deploy-approval');
+
+const APPROVAL_ID = /^k8s-[0-9a-f]{12}$/;
+const DNS_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+const MAX_MANIFEST = 64 * 1024;
+const PILOT_IMAGE = 'docker.io/library/busybox@sha256:66a6306db78bf2dbf3487f293aa8d6990d8e506fdffab9cc43fe422becf886e4';
+const isRecord = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+const sha256 = (raw) => crypto.createHash('sha256').update(raw).digest('hex');
+function keys(value, allowed, label) {
+  if (!isRecord(value) || Object.keys(value).some((key) => !allowed.includes(key))) {
+    throw new Error(`${label} contains unsupported fields`);
+  }
+}
+function exact(value, expected, label) {
+  if (!isDeepStrictEqual(value, expected)) throw new Error(`${label} differs from the bounded Snake profile`);
+}
+function quantity(value, max, suffix = '') {
+  if (typeof value !== 'string' || !new RegExp(`^[1-9][0-9]{0,4}${suffix}$`).test(value)) return false;
+  return Number.parseInt(value, 10) <= max;
+}
+
+function privateDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const st = fs.lstatSync(dir);
+  if (!st.isDirectory() || st.isSymbolicLink() || (st.mode & 0o077) !== 0 ||
+      (typeof process.getuid === 'function' && st.uid !== process.getuid())) {
+    throw new Error('approval directory must be private and owned');
+  }
+}
+
+function privateJson(file) {
+  const st = fs.lstatSync(file);
+  if (!st.isFile() || st.isSymbolicLink() || (st.mode & 0o077) !== 0 || st.size > MAX_MANIFEST + 8192 ||
+      (typeof process.getuid === 'function' && st.uid !== process.getuid())) {
+    throw new Error('approval file must be private, owned and bounded');
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function validateManifest(raw, namespace) {
+  if (typeof raw !== 'string' || Buffer.byteLength(raw) < 1 || Buffer.byteLength(raw) > MAX_MANIFEST) {
+    throw new Error('manifest must be non-empty and at most 64 KiB');
+  }
+  if (typeof namespace !== 'string' || !DNS_NAME.test(namespace) || namespace.length > 63) throw new Error('invalid namespace');
+  const docs = YAML.parseAllDocuments(raw, { uniqueKeys: true, maxAliasCount: 0 });
+  if (docs.length !== 3 || docs.some((d) => d.errors.length)) throw new Error('manifest must contain exactly three valid YAML documents');
+  const resources = docs.map((d) => d.toJS({ maxAliasCount: 0 }));
+  const byKind = new Map();
+  for (const r of resources) {
+    if (!isRecord(r) || !isRecord(r.metadata) || typeof r.metadata.name !== 'string' || !DNS_NAME.test(r.metadata.name) ||
+        r.metadata.namespace !== namespace || !['ConfigMap', 'Deployment', 'Service'].includes(r.kind) || byKind.has(r.kind)) {
+      throw new Error('manifest requires one namespaced ConfigMap, Deployment and Service with valid unique names');
+    }
+    if (r.apiVersion !== (r.kind === 'Deployment' ? 'apps/v1' : 'v1')) throw new Error('unexpected Kubernetes apiVersion');
+    keys(r.metadata, ['name', 'namespace'], 'metadata');
+    byKind.set(r.kind, r);
+  }
+  if (byKind.size !== 3) throw new Error('manifest requires ConfigMap, Deployment and Service');
+  const config = byKind.get('ConfigMap');
+  const deploy = byKind.get('Deployment');
+  const service = byKind.get('Service');
+  const app = deploy.metadata.name;
+  keys(config, ['apiVersion', 'kind', 'metadata', 'data'], 'ConfigMap');
+  keys(deploy, ['apiVersion', 'kind', 'metadata', 'spec'], 'Deployment');
+  keys(service, ['apiVersion', 'kind', 'metadata', 'spec'], 'Service');
+  if (config.metadata.name !== `${app}-html` || service.metadata.name !== app ||
+      !isRecord(config.data) || typeof config.data['index.html'] !== 'string' ||
+      Buffer.byteLength(config.data['index.html']) < 1 || Buffer.byteLength(config.data['index.html']) > 20 * 1024 ||
+      Object.keys(config.data).length !== 1 || config.binaryData !== undefined) {
+    throw new Error('ConfigMap must contain only bounded index.html for this app');
+  }
+  const spec = deploy.spec;
+  const pod = spec?.template?.spec;
+  const container = Array.isArray(pod?.containers) && pod.containers.length === 1 ? pod.containers[0] : null;
+  const image = container?.image;
+  keys(spec, ['replicas', 'selector', 'template'], 'Deployment spec');
+  keys(spec.selector, ['matchLabels'], 'Deployment selector');
+  keys(spec.template, ['metadata', 'spec'], 'pod template');
+  keys(spec.template.metadata, ['labels'], 'pod metadata');
+  keys(pod, ['automountServiceAccountToken', 'securityContext', 'containers', 'volumes'], 'pod spec');
+  if (container) keys(container, ['name', 'image', 'command', 'args', 'ports', 'readinessProbe', 'resources', 'securityContext', 'volumeMounts'], 'container');
+  keys(service.spec, ['type', 'selector', 'ports'], 'Service spec');
+  exact(spec.selector.matchLabels, { app }, 'Deployment selector');
+  exact(spec.template.metadata.labels, { app }, 'pod labels');
+  exact(service.spec.selector, { app }, 'Service selector');
+  exact(pod.securityContext, { runAsNonRoot: true }, 'pod securityContext');
+  if (container) {
+    exact(container.ports, [{ containerPort: 8080 }], 'container ports');
+    exact(container.securityContext, { allowPrivilegeEscalation: false, readOnlyRootFilesystem: true,
+      runAsUser: 10001, runAsGroup: 10001, capabilities: { drop: ['ALL'] } }, 'container securityContext');
+    exact(container.command, ['httpd'], 'container command');
+    exact(container.args, ['-f', '-p', '8080', '-h', '/www'], 'container args');
+    exact(container.readinessProbe, { httpGet: { path: '/', port: 8080 } }, 'readiness probe');
+  }
+  if (spec?.replicas !== 1 || spec?.selector?.matchLabels?.app !== app ||
+      spec?.template?.metadata?.labels?.app !== app || !isRecord(pod) ||
+      pod.hostNetwork || pod.hostPID || pod.hostIPC || pod.serviceAccountName ||
+      pod.automountServiceAccountToken !== false || pod.initContainers !== undefined ||
+      !container || container.name !== app || image !== PILOT_IMAGE ||
+      container.securityContext?.privileged === true || container.securityContext?.allowPrivilegeEscalation !== false ||
+      pod.securityContext?.runAsNonRoot !== true ||
+      container.readinessProbe?.httpGet?.path !== '/' || container.readinessProbe?.httpGet?.port !== 8080 ||
+      !isRecord(container.resources?.requests) || !isRecord(container.resources?.limits) ||
+      !container.resources.requests.cpu || !container.resources.requests.memory ||
+      !quantity(container.resources.requests.cpu, 500, 'm') || !quantity(container.resources.limits.cpu, 1000, 'm') ||
+      !quantity(container.resources.requests.memory, 512, 'Mi') || !quantity(container.resources.limits.memory, 1024, 'Mi') ||
+      Object.keys(container.resources.requests).length !== 2 || Object.keys(container.resources.limits).length !== 2 ||
+      Number.parseInt(container.resources.requests.cpu, 10) > Number.parseInt(container.resources.limits.cpu, 10) ||
+      Number.parseInt(container.resources.requests.memory, 10) > Number.parseInt(container.resources.limits.memory, 10) ||
+      !Array.isArray(pod.volumes) || pod.volumes.length !== 1 || pod.volumes[0]?.configMap?.name !== config.metadata.name ||
+      !Array.isArray(container.volumeMounts) || container.volumeMounts.length !== 1 ||
+      container.volumeMounts[0]?.name !== pod.volumes[0]?.name || !container.volumeMounts[0]?.readOnly ||
+      container.volumeMounts[0]?.mountPath !== '/www') {
+    throw new Error('Deployment must be a bounded non-root single-replica pod with pinned image, probes and resources');
+  }
+  exact(pod.volumes[0], { name: 'html', configMap: { name: config.metadata.name } }, 'pod volume');
+  exact(container.volumeMounts[0], { name: 'html', mountPath: '/www', readOnly: true }, 'volume mount');
+  exact(service.spec.ports, [{ port: 80, targetPort: 8080 }], 'Service ports');
+  if (service.spec?.type !== 'ClusterIP' || service.spec?.selector?.app !== app ||
+      !Array.isArray(service.spec?.ports) || service.spec.ports.length !== 1 ||
+      service.spec.ports[0]?.port !== 80 || service.spec.ports[0]?.targetPort !== 8080 ||
+      service.spec.externalIPs !== undefined || service.spec.loadBalancerIP !== undefined ||
+      service.spec.loadBalancerClass !== undefined) {
+    throw new Error('Service must be ClusterIP port 80 to pod port 8080 without external IPs');
+  }
+  return { app, resources: resources.map((r) => ({ kind: r.kind, name: r.metadata.name })), image };
+}
+
+function approvalFile(id, env = process.env) {
+  if (!APPROVAL_ID.test(id)) throw new Error('invalid Kubernetes approval ID');
+  return path.join(approvalRoot(env), `${id}.json`);
+}
+
+function issueK8sApproval(clusterId, namespace, manifestFile, reviewedSha256, env = process.env, now = Date.now()) {
+  if (!UUID.test(clusterId || '')) throw new Error('cluster_id must be a UUID');
+  if (!DIGEST.test(reviewedSha256 || '')) throw new Error('reviewed manifest SHA-256 is required');
+  const st = fs.lstatSync(manifestFile);
+  if (!st.isFile() || st.isSymbolicLink() || st.size < 1 || st.size > MAX_MANIFEST) {
+    throw new Error('manifest source must be a bounded regular file');
+  }
+  const manifest = fs.readFileSync(manifestFile, 'utf8');
+  const details = validateManifest(manifest, namespace);
+  const digest = sha256(manifest);
+  if (digest !== reviewedSha256) throw new Error('manifest digest differs from reviewed SHA-256');
+  const credentials = readCredentials(env);
+  const root = approvalRoot(env);
+  privateDir(root);
+  const id = `k8s-${crypto.randomBytes(6).toString('hex')}`;
+  const record = { id, projectId: credentials.projectId, clusterId, namespace, manifest, digest,
+    app: details.app, issuedAt: now, expiresAt: now + 10 * 60_000 };
+  fs.writeFileSync(approvalFile(id, env), JSON.stringify(record) + '\n', { flag: 'wx', mode: 0o600 });
+  return { approvalId: id, projectId: record.projectId, clusterId, namespace, manifestSha256: digest,
+    resources: details.resources, image: details.image, expiresAt: record.expiresAt,
+    estimateScope: 'existing cluster only; no cluster, worker, NAT or public load balancer is created' };
+}
+
+function consumeK8sApproval(id, env = process.env, now = Date.now()) {
+  const file = approvalFile(id, env);
+  const a = privateJson(file);
+  const credentials = readCredentials(env);
+  if (a.id !== id || a.projectId !== credentials.projectId || !UUID.test(a.clusterId || '') ||
+      !Number.isFinite(a.expiresAt) || a.expiresAt <= now || !DIGEST.test(a.digest || '') ||
+      sha256(a.manifest) !== a.digest || validateManifest(a.manifest, a.namespace).app !== a.app) {
+    throw new Error('Kubernetes approval does not match manifest, project or time');
+  }
+  const spent = path.join(approvalRoot(env), `${id}.used-${crypto.randomBytes(8).toString('hex')}.json`);
+  fs.renameSync(file, spent);
+  const session = { id, projectId: a.projectId, clusterId: a.clusterId, namespace: a.namespace,
+    app: a.app, expiresAt: now + 2 * 60 * 60_000 };
+  fs.writeFileSync(path.join(approvalRoot(env), `${id}.session.json`), JSON.stringify(session) + '\n', { flag: 'wx', mode: 0o600 });
+  return { clusterId: a.clusterId, namespace: a.namespace, manifest: a.manifest, app: a.app };
+}
+
+function k8sSession(id, env = process.env, now = Date.now()) {
+  if (!APPROVAL_ID.test(id)) throw new Error('invalid Kubernetes approval ID');
+  const s = privateJson(path.join(approvalRoot(env), `${id}.session.json`));
+  if (s.id !== id || s.projectId !== readCredentials(env).projectId || !UUID.test(s.clusterId || '') ||
+      typeof s.namespace !== 'string' || !DNS_NAME.test(s.namespace) ||
+      typeof s.app !== 'string' || !DNS_NAME.test(s.app) || !Number.isFinite(s.expiresAt) || s.expiresAt <= now) {
+    throw new Error('Kubernetes verification session is expired or mismatched');
+  }
+  return s;
+}
+
+function verificationArgs(session, query) {
+  const prefix = `-n ${session.namespace}`;
+  switch (query) {
+    case 'pods': return `${prefix} get pods -l app=${session.app} -o json`;
+    case 'deployment': return `${prefix} get deployment ${session.app} -o json`;
+    case 'service': return `${prefix} get service ${session.app} -o json`;
+    case 'rollout': return `${prefix} rollout status deployment/${session.app} --timeout=90s`;
+    default: throw new Error('query must be pods, deployment, service or rollout');
+  }
+}
+
+module.exports = { PILOT_IMAGE, validateManifest, issueK8sApproval, consumeK8sApproval, k8sSession, verificationArgs };

package/src/probe-child.js

@@ -0,0 +1,38 @@
+'use strict';
+// One-shot live tools/list probe. MCP servers may stay alive after stdin EOF;
+// terminate the child after the first matching response instead of waiting for exit.
+const { spawn } = require('child_process');
+
+const bin = process.argv[2];
+const child = spawn(bin, ['mcp'], { stdio: ['pipe', 'pipe', 'ignore'] });
+let buffer = '';
+let done = false;
+const fail = (message) => {
+  if (done) return;
+  done = true;
+  process.stderr.write(message + '\n');
+  child.kill();
+  process.exitCode = 1;
+};
+child.on('error', (error) => fail(error.message));
+child.on('exit', (code) => { if (!done) fail(`engine exited before tools/list: ${code}`); });
+child.stdout.setEncoding('utf8');
+child.stdout.on('data', (chunk) => {
+  if (done) return;
+  buffer += chunk;
+  if (Buffer.byteLength(buffer) > 16 * 1024 * 1024) { fail('tools/list response too large'); return; }
+  let end;
+  while ((end = buffer.indexOf('\n')) >= 0) {
+    const line = buffer.slice(0, end).trim();
+    buffer = buffer.slice(end + 1);
+    if (!line) continue;
+    let message;
+    try { message = JSON.parse(line); } catch { fail('engine emitted invalid JSON'); return; }
+    if (message.id !== 1) continue;
+    done = true;
+    process.stdout.write(JSON.stringify(message) + '\n');
+    child.kill();
+    return;
+  }
+});
+child.stdin.end(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }) + '\n');