@dzhechkov/cloudru-hub 0.1.12 → 0.1.14

package/src/credentials.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const UUID = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i;
+
+const ZONES = Object.freeze({
+  'ru.AZ-1': '7c99a597-8516-494f-a2c7-d7377048681e',
+  'ru.AZ-2': '479a4ab3-3ff3-4972-95c5-7610bac5c0bb',
+  'ru.AZ-3': '2c63c482-2532-4bba-8c9b-70ea330507bf',
+});
+
+function credentialsPath(env = process.env) {
+  return env.CLOUDRU_HUB_CREDENTIALS || path.join(os.homedir(), '.config', 'cloudru-hub', 'credentials.json');
+}
+
+function readCredentials(env = process.env) {
+  const file = credentialsPath(env);
+  const st = fs.lstatSync(file);
+  if (!st.isFile() || st.isSymbolicLink()) throw new Error('credentials must be a regular file');
+  if ((st.mode & 0o077) !== 0) throw new Error('credentials permissions must be 0600');
+  if (typeof process.getuid === 'function' && st.uid !== process.getuid()) throw new Error('credentials owner differs from MCP process');
+  if (st.size > 65536) throw new Error('credentials file is too large');
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch { throw new Error('credentials file is not valid JSON'); }
+  if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') throw new Error('credentials JSON must be an object');
+  for (const key of ['key_id', 'secret', 'project_id']) {
+    if (typeof parsed[key] !== 'string' || !parsed[key].trim()) throw new Error(`credentials ${key} is required`);
+    if (/[\r\n\0]/.test(parsed[key])) throw new Error(`credentials ${key} contains a control character`);
+  }
+  if (parsed.agreement_id !== undefined &&
+      (typeof parsed.agreement_id !== 'string' || !parsed.agreement_id.trim() || /[\r\n\0]/.test(parsed.agreement_id))) {
+    throw new Error('credentials agreement_id must be a non-empty string without control characters');
+  }
+  if (!UUID.test(parsed.project_id)) throw new Error('credentials project_id must be a UUID');
+  const region = parsed.region || 'ru.AZ-2';
+  const zone = ZONES[region] || region;
+  if (!UUID.test(zone)) throw new Error('credentials region must be a known zone or UUID');
+  return {
+    path: file,
+    projectId: parsed.project_id,
+    env: {
+      CLOUDRU_KEY_ID: parsed.key_id,
+      CLOUDRU_SECRET: parsed.secret,
+      CLOUDRU_PROJECT_ID: parsed.project_id,
+      CLOUDRU_REGION: zone,
+      ...(parsed.agreement_id === undefined ? {} : { CLOUDRU_AGREEMENT_ID: parsed.agreement_id.trim() }),
+    },
+  };
+}
+
+function readOptionalCredentials(env = process.env) {
+  // An explicit path must fail loudly when unreadable. Without one, retain
+  // environment-only billing setups that have no default credential file.
+  if (!env.CLOUDRU_HUB_CREDENTIALS && !fs.existsSync(credentialsPath(env))) return null;
+  return readCredentials(env);
+}
+
+module.exports = { credentialsPath, readCredentials, readOptionalCredentials, ZONES, UUID };

package/src/deploy-approval.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { readCredentials, UUID } = require('./credentials');
+
+const PLAN_ID = /^plan-[0-9a-f]{12}$/;
+
+function stateRoot(env = process.env) { return env.CLOUDRU_VM_HOME || os.homedir(); }
+function approvalRoot(env = process.env) { return env.CLOUDRU_HUB_APPROVALS || path.join(os.homedir(), '.config', 'cloudru-hub', 'approvals'); }
+function planPath(id, env = process.env) {
+  if (!PLAN_ID.test(id)) throw new Error('invalid plan_id');
+  return path.join(stateRoot(env), '.cloudru-vm', 'plans', `${id}.json`);
+}
+function readPlan(id, env = process.env, now = Date.now()) {
+  const file = planPath(id, env);
+  const st = fs.lstatSync(file);
+  if (!st.isFile() || st.isSymbolicLink() || st.size > 65536) throw new Error('plan file is not a bounded regular file');
+  const raw = fs.readFileSync(file);
+  const plan = JSON.parse(raw);
+  if (plan.plan_id !== id || !UUID.test(plan.project_id || '')) throw new Error('plan identity or project is invalid');
+  const expires = Date.parse(plan.expires_at);
+  if (!Number.isFinite(expires) || expires <= now) throw new Error('plan expired');
+  const price = plan.cost && plan.cost.total_monthly_rub;
+  if (!plan.cost || plan.cost.currency !== 'RUB' || !Number.isFinite(price) || price < 0) throw new Error('plan cost is not a finite RUB estimate');
+  if (typeof plan.vm?.name !== 'string' || !plan.vm.name) throw new Error('plan VM name is invalid');
+  if (!plan.static_site && (typeof plan.ssh?.login !== 'string' || !plan.ssh.login)) throw new Error('plan SSH login is invalid');
+  if (plan.static_site) {
+    const site = plan.static_site;
+    if (!/^[0-9a-f]{64}$/.test(site.sha256 || '') || !Number.isSafeInteger(site.size_bytes) || site.size_bytes < 1 || site.size_bytes > 20 * 1024 ||
+        typeof site.source_base64 !== 'string' || site.source_base64.length > 28 * 1024 ||
+        !Array.isArray(site.files) || site.files.length < 1 || site.files.length > 32 ||
+        !Array.isArray(plan.ports) || plan.ports.length !== 1 || plan.ports[0] !== 80 || plan.network?.floating_ip !== true ||
+        typeof plan.network?.attach_fip_id !== 'string' || !UUID.test(plan.network.attach_fip_id)) {
+      throw new Error('static-site plan artifact or network scope is invalid');
+    }
+  }
+  return { plan, hash: crypto.createHash('sha256').update(raw).digest('hex'), price, expires };
+}
+function approvalPath(id, env = process.env) { return path.join(approvalRoot(env), `${id}.json`); }
+function ensurePrivateDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const st = fs.lstatSync(dir);
+  if (!st.isDirectory() || st.isSymbolicLink() || (st.mode & 0o077) !== 0) throw new Error('approval directory must be private (0700)');
+}
+function readPrivateJson(file) {
+  const st = fs.lstatSync(file);
+  if (!st.isFile() || st.isSymbolicLink() || (st.mode & 0o077) !== 0 || st.size > 65536 ||
+      (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 issueApproval(id, maxMonthlyRub, env = process.env, now = Date.now(), reviewedSiteSha256 = '') {
+  const { plan, hash, price, expires } = readPlan(id, env, now);
+  if (plan.static_site && reviewedSiteSha256 !== plan.static_site.sha256) {
+    throw new Error('static-site approval requires --site-sha256 matching the reviewed artifact');
+  }
+  const credentials = readCredentials(env);
+  if (credentials.projectId !== plan.project_id) throw new Error('plan project differs from credentials project');
+  if (!Number.isFinite(maxMonthlyRub) || maxMonthlyRub < price) throw new Error('monthly cost exceeds operator cap');
+  const root = approvalRoot(env);
+  ensurePrivateDir(root);
+  const record = {
+    planId: id,
+    planHash: hash,
+    projectId: plan.project_id,
+    vmName: plan.vm.name,
+    sshUser: plan.ssh?.login || '',
+    siteMode: !!plan.static_site,
+    maxMonthlyRub,
+    issuedAt: now,
+    expiresAt: Math.min(expires, now + 10 * 60_000),
+  };
+  fs.writeFileSync(approvalPath(id, env), JSON.stringify(record) + '\n', { flag: 'wx', mode: 0o600 });
+  return { planId: id, projectId: record.projectId, vmName: record.vmName, estimatedMonthlyRub: price, maxMonthlyRub, expiresAt: record.expiresAt,
+    ...(plan.static_site ? { staticSite: { source: plan.static_site.source, sha256: plan.static_site.sha256, sizeBytes: plan.static_site.size_bytes,
+      files: plan.static_site.files.map((file) => ({ path: file.path, sha256: file.sha256, sizeBytes: file.size_bytes })),
+      ingress: 'dedicated security group: TCP 80 from 0.0.0.0/0', estimateScope: 'compute and disk only; public IP charges excluded' } } : {}) };
+}
+
+function consumeApproval(id, env = process.env, now = Date.now()) {
+  const { plan, hash, price } = readPlan(id, env, now);
+  const credentials = readCredentials(env);
+  const file = approvalPath(id, env);
+  const a = readPrivateJson(file);
+  if (a.planId !== id || a.planHash !== hash || a.projectId !== plan.project_id || a.projectId !== credentials.projectId || a.siteMode !== !!plan.static_site ||
+      a.vmName !== plan.vm.name || !Number.isFinite(a.maxMonthlyRub) || price > a.maxMonthlyRub ||
+      !Number.isFinite(a.expiresAt) || a.expiresAt <= now) throw new Error('approval does not match current plan, project, cost or time');
+  const spent = path.join(approvalRoot(env), `${id}.used-${crypto.randomBytes(8).toString('hex')}.json`);
+  fs.renameSync(file, spent); // one caller consumes the pending path; a replay cannot.
+  return a;
+}
+
+function recordDeployedVM(approval, result, env = process.env, now = Date.now()) {
+  const vmId = result && result.vm_id;
+  if (!UUID.test(vmId || '') || result.status !== 'running') throw new Error('deploy did not return a running VM UUID');
+  const root = approvalRoot(env);
+  ensurePrivateDir(root);
+  const session = { planId: approval.planId, projectId: approval.projectId, vmId, sshUser: approval.sshUser, expiresAt: now + 2 * 60 * 60_000 };
+  fs.writeFileSync(path.join(root, `${approval.planId}.session.json`), JSON.stringify(session) + '\n', { flag: 'wx', mode: 0o600 });
+  return session;
+}
+
+function approvedVM(requestedId, env = process.env, now = Date.now()) {
+  const root = approvalRoot(env);
+  if (!fs.existsSync(root)) throw new Error('no approved deployment session');
+  ensurePrivateDir(root);
+  const sessions = fs.readdirSync(root).filter((name) => /^plan-[0-9a-f]{12}\.session\.json$/.test(name));
+  const credentials = readCredentials(env);
+  if (requestedId && !UUID.test(requestedId)) throw new Error('vm_exec requires an approved VM UUID');
+  const live = sessions.map((name) => readPrivateJson(path.join(root, name)))
+    .filter((s) => s.expiresAt > now && s.projectId === credentials.projectId && UUID.test(s.vmId || ''));
+  const matching = requestedId ? live.filter((s) => s.vmId === requestedId) : live;
+  if (matching.length !== 1) throw new Error('vm_exec requires exactly one matching active approved VM session');
+  return matching[0];
+}
+
+module.exports = { stateRoot, approvalRoot, planPath, readPlan, issueApproval, consumeApproval, recordDeployedVM, approvedVM };

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,
 };