@bongos/core 1.18.0 → 1.18.18

package/modules/dev-box/app/src/preload.js

@@ -0,0 +1,29 @@
+// devbox-app/src/preload.js — the renderer's ONLY door into the main process.
+// Sandboxed + contextIsolated; every capability is a named verb (no raw URLs,
+// no arbitrary IPC) so a compromised renderer can do nothing the panel UI
+// couldn't already do.
+
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('otb', {
+  getState: () => ipcRenderer.invoke('state:get'),
+  signIn: () => ipcRenderer.invoke('auth:signIn'),
+  cancelPairing: () => ipcRenderer.invoke('auth:cancelPairing'),
+  signOut: () => ipcRenderer.invoke('auth:signOut'),
+  boxOn: () => ipcRenderer.invoke('box:on'),
+  boxOff: () => ipcRenderer.invoke('box:off'),
+  claimable: () => ipcRenderer.invoke('tasks:claimable'),
+  pickTask: (taskId) => ipcRenderer.invoke('tasks:pick', taskId),
+  openTerminal: () => ipcRenderer.invoke('open:terminal'),
+  openHall: () => ipcRenderer.invoke('open:hall'),
+  openPairPage: () => ipcRenderer.invoke('open:pairPage'),
+  openUpdate: () => ipcRenderer.invoke('open:update'),
+  copy: (what) => ipcRenderer.invoke('copy', what),
+  installSettings: () => ipcRenderer.invoke('settings:install'),
+  retryHostKeys: () => ipcRenderer.invoke('hostkeys:retry'),
+  retryKey: () => ipcRenderer.invoke('key:retry'),
+  hide: () => ipcRenderer.invoke('panel:hide'),
+  onState: (cb) => {
+    ipcRenderer.on('state', (_e, payload) => cb(payload));
+  },
+});

package/modules/dev-box/app/src/session-store.js

@@ -0,0 +1,58 @@
+// devbox-app/src/session-store.js — the app shares the GDS CLI's session file.
+//
+// ~/.config/<instance>/gds-session.json is the same file scripts/gds/cli-lib.js and
+// paste-token.js read/write: { token, builder, api_base, ... }. Sharing it is
+// a deliberate UX decision (ADR 0045): pairing the app also signs in every
+// /builder-* skill on this machine, and a builder who already ran
+// /builder-setup opens the app already signed in. Writes are merge-preserving
+// (unknown fields like gemini_api_key survive, mirroring paste-token.js) and
+// 0600 like the CLI's.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const brand = require('./brand');
+
+// The instance's CLI config dir (branding configDir) — so the app shares the
+// exact session file the /builder-* CLI uses on this machine.
+const DIR = path.join(os.homedir(), '.config', brand.CONFIG_DIR);
+const FILE = path.join(DIR, 'gds-session.json');
+// Read-side legacy name only (pre-GDS rename) — never written.
+const FILE_LEGACY = path.join(DIR, 'pms-session.json');
+
+function read() {
+  for (const f of [FILE, FILE_LEGACY]) {
+    try {
+      const data = JSON.parse(fs.readFileSync(f, 'utf8'));
+      if (data && typeof data.token === 'string' && data.token) return data;
+    } catch { /* missing or unparsable → keep looking */ }
+  }
+  return null;
+}
+
+function write({ token, builder, apiBase }) {
+  const existing = read() || {};
+  const next = {
+    ...existing,
+    token,
+    builder: builder ?? existing.builder ?? null,
+    api_base: apiBase ?? existing.api_base ?? null,
+  };
+  fs.mkdirSync(DIR, { recursive: true });
+  fs.writeFileSync(FILE, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  // Re-assert the mode for pre-existing files (chmod is a no-op on Windows,
+  // where the home-dir ACL is the protection — same posture as the CLI).
+  try { fs.chmodSync(FILE, 0o600); } catch { /* best-effort */ }
+  return next;
+}
+
+// Sign-out: drop ONLY our credential fields; preserve everything else
+// (gemini_api_key etc.) so the app never destroys CLI-adjacent config.
+function clear() {
+  const existing = read();
+  if (!existing) return;
+  const { token: _t, builder: _b, ...rest } = existing;
+  fs.writeFileSync(FILE, `${JSON.stringify(rest, null, 2)}\n`, { mode: 0o600 });
+}
+
+module.exports = { read, write, clear, FILE };

package/modules/dev-box/app/src/ssh-setup.js

@@ -0,0 +1,569 @@
+// devbox-app/src/ssh-setup.js — everything connect.sh could not do reliably,
+// done natively (#904, ADR 0045). Three jobs, each fixing a failure proven in
+// the 2026-06-10 onboarding session exports:
+//
+//   1. ensureKey()         — ~/.ssh/otb_builder ed25519 keypair with REAL 600
+//                            perms (git-bash left 644 world-readable keys) and
+//                            a proper Windows ACL, registered via the API.
+//   2. refreshKnownHosts() — ssh-keyscan the box hostname into
+//                            ~/.ssh/known_hosts, REPLACING stale lines. Claude
+//                            Desktop's embedded ssh2 reads only known_hosts —
+//                            never ~/.ssh/config — and every re-provision mints
+//                            new host keys, so stale entries hard-fail the
+//                            connect (the known project bug).
+//   3. installManagedSettings() — write the Claude Desktop managed-settings
+//                            file to the SYSTEM path with a native elevation
+//                            prompt (osascript admin / UAC). The agent-driven
+//                            flow could never finish this step: Claude
+//                            Desktop's own classifier blocks an agent touching
+//                            permission machinery; a native app the human
+//                            launched can simply ask the OS.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFile } = require('node:child_process');
+
+const SSH_DIR = path.join(os.homedir(), '.ssh');
+const KEY_PATH = path.join(SSH_DIR, 'otb_builder');
+const KNOWN_HOSTS = path.join(SSH_DIR, 'known_hosts');
+
+const IS_MAC = process.platform === 'darwin';
+const IS_WIN = process.platform === 'win32';
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: 30_000, windowsHide: true, ...opts }, (err, stdout, stderr) => {
+      if (err) { err.stdout = stdout; err.stderr = stderr; return reject(err); }
+      resolve({ stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+
+// Resolve an OpenSSH client tool to an absolute path. A GUI-launched Electron
+// process on Windows can carry a leaner PATH than a terminal, and the
+// Parallels hardware test (#909) showed a bare 'ssh-keyscan' failing silently
+// while C:\Windows\System32\OpenSSH\ssh-keyscan.exe existed. Order: the
+// canonical Windows install, then Git-for-Windows' bundled copy, then PATH.
+function resolveSshTool(name) {
+  if (IS_WIN) {
+    const candidates = [
+      path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'OpenSSH', `${name}.exe`),
+      'C:\\Program Files\\Git\\usr\\bin\\' + `${name}.exe`,
+    ];
+    for (const c of candidates) {
+      try { if (fs.existsSync(c)) return c; } catch { /* keep looking */ }
+    }
+  }
+  return name; // POSIX or fall through to PATH resolution
+}
+
+// --- 1. SSH key ------------------------------------------------------------
+
+// PURE (unit-tested): the SHA256 fingerprint `ssh-keygen -l` prints — 'SHA256:' +
+// base64(sha256(decoded key blob)) with '=' padding stripped. Byte-identical to the
+// server's own box-onboard.sshFingerprintSha256, so a local fingerprint can be
+// compared straight against a row from GET /box/ssh-key. Deliberately node:crypto
+// and NOT a shell-out: box-connect-lib's ssh-keygen-based localKeyFingerprint
+// returns null whenever the tool is missing from a GUI process's leaner PATH, and
+// "no fingerprint" is exactly what used to make the caller give up.
+function sshFingerprintSha256(base64Body) {
+  const blob = Buffer.from(String(base64Body || ''), 'base64');
+  const digest = crypto.createHash('sha256').update(blob).digest('base64').replace(/=+$/, '');
+  return `SHA256:${digest}`;
+}
+
+// PURE: fingerprint of a `<type> <base64> [comment]` public-key line, or null when
+// the line isn't a key. The comment is excluded — that is why re-registering the
+// same key under a different label de-dupes to one server row.
+function publicKeyFingerprint(pubLine) {
+  const parts = String(pubLine || '').trim().split(/\s+/);
+  if (parts.length < 2 || !parts[1]) return null;
+  return sshFingerprintSha256(parts[1]);
+}
+
+const REGISTER_ATTEMPTS = 3;
+
+// Normalize whatever listKeys() hands back (the route body `{ keys: [...] }`, or a
+// bare array) into a fingerprint list.
+function listedFingerprints(listed) {
+  const rows = Array.isArray(listed) ? listed : (listed && Array.isArray(listed.keys) ? listed.keys : null);
+  if (!rows) return null;
+  return rows.map((k) => (k && k.fingerprint) || '').filter(Boolean);
+}
+
+// Register the public key, retry on failure, then VERIFY against the server's own
+// key list. The old path was a single un-retried POST whose rejection was logged and
+// dropped: a flaky network or a 500 at sign-in left the builder with no key in the
+// box's authorized_keys and nothing ever tried again — every later connect refused,
+// with the panel showing no hint why. Registering is not proof; being in the list is.
+//
+// FULLY INJECTED (registerKey/listKeys/sleep) so it is unit-testable with no network,
+// no fs and no Electron. NEVER throws — callers get a reason they can surface.
+// Reasons: registered_verified | verify_failed | register_failed | list_failed.
+async function registerKeyWithVerify({
+  publicKey,
+  label,
+  registerKey,
+  listKeys,
+  sleep: sleepFn = sleep,
+  attempts = REGISTER_ATTEMPTS,
+  log = () => {},
+} = {}) {
+  const fingerprint = publicKeyFingerprint(publicKey);
+  let registered = false;
+  let used = 0;
+  let detail = '';
+  for (let i = 1; i <= attempts; i += 1) {
+    used = i;
+    try {
+      await registerKey(publicKey, label);
+      registered = true;
+      break;
+    } catch (e) {
+      detail = String((e && e.message) || e).slice(0, 160);
+      log(`ssh key registration attempt ${i}/${attempts} failed: ${detail}`);
+      // 1s / 2s / 4s — a wake-from-sleep network or a restarting server settles
+      // well inside that, and the whole budget is under 10s.
+      if (i < attempts) await sleepFn(1000 * 2 ** (i - 1));
+    }
+  }
+  let listed;
+  try {
+    listed = await listKeys();
+  } catch (e) {
+    return {
+      ok: false,
+      fingerprint,
+      verified: false,
+      attempts: used,
+      reason: 'list_failed',
+      detail: String((e && e.message) || e).slice(0, 160),
+    };
+  }
+  const fingerprints = listedFingerprints(listed);
+  // A key already on the server counts as verified even if every POST failed — the
+  // POST is the means, presence in authorized_keys is the end.
+  const verified = Boolean(fingerprint) && Array.isArray(fingerprints) && fingerprints.includes(fingerprint);
+  if (verified) return { ok: true, fingerprint, verified: true, attempts: used, reason: 'registered_verified' };
+  return {
+    ok: false,
+    fingerprint,
+    verified: false,
+    attempts: used,
+    reason: registered ? 'verify_failed' : 'register_failed',
+    detail,
+  };
+}
+
+async function ensureKey({ registerKey, listKeys, sleep: sleepFn = sleep, log = () => {} }) {
+  fs.mkdirSync(SSH_DIR, { recursive: true, mode: 0o700 });
+  if (!fs.existsSync(KEY_PATH)) {
+    log('generating ed25519 keypair');
+    await run(resolveSshTool('ssh-keygen'), ['-t', 'ed25519', '-N', '', '-C', 'otb-devbox-app', '-f', KEY_PATH]);
+  }
+  // Permissions: real chmod on POSIX; on Windows scope the ACL to the current
+  // user (ssh.exe refuses world-readable keys the same way OpenSSH does, and
+  // a git-bash chmod is cosmetic there).
+  if (IS_WIN) {
+    const user = process.env.USERNAME || os.userInfo().username;
+    try {
+      await run('icacls', [KEY_PATH, '/inheritance:r', '/grant:r', `${user}:F`]);
+    } catch (e) { log(`icacls failed (non-fatal): ${e.message}`); }
+  } else {
+    fs.chmodSync(KEY_PATH, 0o600);
+  }
+  const publicKey = fs.readFileSync(`${KEY_PATH}.pub`, 'utf8').trim();
+  // Upsert by fingerprint server-side — safe to repeat on every sign-in — then
+  // verify it actually landed. `registration` never throws; the caller surfaces it.
+  const registration = await registerKeyWithVerify({
+    publicKey,
+    label: `devbox-app ${os.hostname()}`.slice(0, 80),
+    registerKey,
+    listKeys,
+    sleep: sleepFn,
+    log,
+  });
+  return { keyPath: KEY_PATH, publicKey, registration };
+}
+
+// --- 2. known_hosts --------------------------------------------------------
+
+// PURE (unit-tested): does this known_hosts line name `hostname`? Field 1 is either
+// a plain `host` / `host,ip` list, or — when the client runs with HashKnownHosts on
+// (Debian/Ubuntu ship it ON by default) — the opaque `|1|<b64 salt>|<b64 hash>` form,
+// where hash = HMAC-SHA1(keyed by the salt) over the hostname. Matching only the
+// plain form is why stale lines ACCUMULATED instead of being replaced: a hashed
+// entry never matched, so a re-pin appended a second line for the same host and the
+// client kept verifying against the first, stale one ("Host denied").
+function knownHostsLineMatchesHost(line, hostname) {
+  if (!hostname) return false;
+  const t = String(line || '').trim();
+  if (!t || t.startsWith('#')) return false;
+  const field = t.split(/\s+/)[0] || '';
+  if (!field.startsWith('|1|')) return field.split(',').includes(hostname);
+  const [, , salt, hash] = field.split('|');
+  if (!salt || !hash) return false;
+  try {
+    return crypto.createHmac('sha1', Buffer.from(salt, 'base64')).update(hostname).digest('base64') === hash;
+  } catch {
+    return false; // unparseable salt → leave the line alone rather than guess
+  }
+}
+
+// Pure helper (unit-tested): replace every line for `hostname` with the
+// freshly scanned ones. Handles plain, `host,ip` and hashed entries alike.
+function mergeKnownHosts(existingText, hostname, scannedLines) {
+  const keep = String(existingText || '')
+    .split('\n')
+    .filter((line) => !knownHostsLineMatchesHost(line, hostname));
+  const fresh = scannedLines
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
+  const out = [...keep, ...fresh].join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+  return `${out}\n`;
+}
+
+// Every ssh-keyscan we might be able to use, best first. The Parallels
+// hardware run (#910) showed why a CHAIN is required: Windows' bundled
+// OpenSSH was too old to negotiate Ubuntu 24.04 sshd's KEX
+// ("unsupported KEX method sntrup761x25519-sha512…"), while Git for
+// Windows' bundled copy is modern and succeeds.
+function keyscanCandidates() {
+  const out = [];
+  if (IS_WIN) {
+    for (const c of [
+      path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'OpenSSH', 'ssh-keyscan.exe'),
+      'C:\\Program Files\\Git\\usr\\bin\\ssh-keyscan.exe',
+    ]) {
+      try { if (fs.existsSync(c)) out.push(c); } catch { /* skip */ }
+    }
+  }
+  out.push('ssh-keyscan'); // PATH fallback, and the POSIX path
+  return out;
+}
+
+const HOST_KEY_TYPES = ['ed25519', 'ecdsa', 'rsa'];
+
+// Claude Desktop's embedded ssh2 negotiates ed25519 first and hard-fails when
+// the type it picked is absent from known_hosts — so a scan without an
+// ed25519 line is NOT a usable pin, no matter how many other keys it got
+// (#925: rsa-only pin → "Host denied" behind a green check).
+const REQUIRED_KEY_ALGO = 'ssh-ed25519';
+const SCAN_ATTEMPTS_PER_TYPE = 3;
+
+function scanComplete(lines) {
+  return lines.some((l) => (l.trim().split(/\s+/)[1] || '') === REQUIRED_KEY_ALGO);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => { setTimeout(resolve, ms).unref?.(); });
+}
+
+// Scan one host with one tool. Per-type sequential connections (a single
+// multi-type scan opens parallel connections and sshd's MaxStartups drops
+// some — observed as "Connection closed by remote host"), each type retried
+// when its probe comes back empty (the same drops hit single probes too),
+// and stdout is harvested EVEN when the tool exits non-zero: a non-empty
+// partial scan still carries usable keys.
+async function scanWithTool(tool, hostname) {
+  const lines = [];
+  let lastErr = '';
+  for (const type of HOST_KEY_TYPES) {
+    for (let attempt = 1; attempt <= SCAN_ATTEMPTS_PER_TYPE; attempt += 1) {
+      let stdout = '';
+      try {
+        ({ stdout } = await run(tool, ['-T', '8', '-t', type, hostname]));
+      } catch (e) {
+        if (e.code === 'ENOENT') throw e; // tool itself missing — try the next one
+        stdout = String(e.stdout || '');
+        lastErr = String(e.stderr || e.message).split('\n').find((l) => l.trim()) || lastErr;
+      }
+      const got = stdout.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+      if (got.length > 0) { lines.push(...got); break; }
+      if (attempt < SCAN_ATTEMPTS_PER_TYPE) await sleep(1000 * attempt);
+    }
+  }
+  return { lines, lastErr };
+}
+
+function writeKnownHosts(hostname, lines) {
+  fs.mkdirSync(SSH_DIR, { recursive: true, mode: 0o700 });
+  const existing = fs.existsSync(KNOWN_HOSTS) ? fs.readFileSync(KNOWN_HOSTS, 'utf8') : '';
+  fs.writeFileSync(KNOWN_HOSTS, mergeKnownHosts(existing, hostname, lines));
+}
+
+async function refreshKnownHosts(hostname, { log = () => {} } = {}) {
+  if (!hostname) return { ok: false, reason: 'no_hostname' };
+  let lastErr = '';
+  let sawTool = false;
+  let partial = null; // best incomplete scan — written as a fallback, never latched as ok
+  for (const tool of keyscanCandidates()) {
+    let scan;
+    try {
+      scan = await scanWithTool(tool, hostname);
+    } catch (e) {
+      if (e.code === 'ENOENT') continue; // candidate not present — next
+      scan = { lines: [], lastErr: String(e.message) };
+    }
+    sawTool = true;
+    if (scanComplete(scan.lines)) {
+      writeKnownHosts(hostname, scan.lines);
+      log(`known_hosts refreshed for ${hostname} (${scan.lines.length} keys via ${tool})`);
+      return { ok: true, keys: scan.lines.length, tool };
+    }
+    if (scan.lines.length > 0 && (!partial || scan.lines.length > partial.lines.length)) {
+      partial = { lines: scan.lines, tool };
+    }
+    lastErr = scan.lastErr || lastErr;
+    log(`ssh-keyscan (${tool}) incomplete for ${hostname} (${scan.lines.length} keys, no ${REQUIRED_KEY_ALGO}): ${lastErr.slice(0, 160)}`);
+  }
+  if (!sawTool) return { ok: false, reason: 'tool_missing', detail: 'no ssh-keyscan found' };
+  if (partial) {
+    // Fresher-than-stale: keep what we scanned (plain OpenSSH can use it),
+    // but report failure so the caller retries and the panel never shows the
+    // green check without the key Desktop verifies (#925).
+    writeKnownHosts(hostname, partial.lines);
+    log(`known_hosts partially refreshed for ${hostname} (${partial.lines.length} keys via ${partial.tool}, missing ${REQUIRED_KEY_ALGO})`);
+    return { ok: false, reason: 'partial_scan', keys: partial.lines.length, detail: `missing ${REQUIRED_KEY_ALGO}` };
+  }
+  return { ok: false, reason: 'scan_failed', detail: lastErr.slice(0, 160) };
+}
+
+// --- 2b. AUTHORITATIVE host keys (task 1187 / idea 235) --------------------
+// The box reports its own PUBLIC host keys to the GDS; GET /box/me serves them
+// (box.host_keys, newline-joined `<keytype> <base64>`). Pinning from THOSE beats
+// ssh-keyscan: no TOFU window, no KEX-negotiation flakiness (#910), no partial
+// scan (#925) — the key is known for certain. main.js prefers this and falls back
+// to refreshKnownHosts (keyscan) only when the box hasn't reported yet.
+
+// PURE (unit-tested): build known_hosts lines from the reported keys by prefixing
+// the hostname to each `<keytype> <base64>` pair. Requires an ed25519 line — the
+// algo Desktop verifies (#925). Returns { ok, lines } or { ok:false, reason }.
+function hostKeyLinesFor(hostname, hostKeysText) {
+  if (!hostname) return { ok: false, reason: 'no_hostname' };
+  const pairs = String(hostKeysText || '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
+  if (pairs.length === 0) return { ok: false, reason: 'no_reported_keys' };
+  const lines = pairs.map((p) => `${hostname} ${p}`);
+  if (!scanComplete(lines)) return { ok: false, reason: 'no_ed25519' };
+  return { ok: true, lines };
+}
+
+// PURE (unit-tested): are the GDS-reported host keys older than the droplet that is
+// running now? A rebuild mints fresh host keys and the row keeps the OLD ones until
+// the new box re-reports (~10 min) — pinning in that window is the "Host denied
+// (verification failed)" lockout. Missing either timestamp is also "can't prove
+// fresh". Callers fall back to a live keyscan rather than pin a dead identity.
+//
+// Mirrors modules/dev-box/boxes.hostKeysAreStale (this app takes ZERO requires into
+// the repo — modules/dev-box/CLAUDE.md); tests/devbox_key_register.mjs pins the two
+// to the same fixtures so they cannot drift apart.
+function reportedKeysAreStale({ hostKeysAt, activeSince } = {}) {
+  const toMs = (x) => {
+    if (x == null) return null;
+    const t = x instanceof Date ? x.getTime() : new Date(x).getTime();
+    return Number.isFinite(t) ? t : null;
+  };
+  const reported = toMs(hostKeysAt);
+  const activated = toMs(activeSince);
+  if (reported == null || activated == null) return true;
+  return reported < activated;
+}
+
+// Pin known_hosts from the GDS-reported keys, using the SAME replace-by-host merge
+// as the keyscan path. Same return shape as refreshKnownHosts so main.js treats
+// them interchangeably.
+function refreshKnownHostsFromKeys(hostname, hostKeysText, { log = () => {} } = {}) {
+  const built = hostKeyLinesFor(hostname, hostKeysText);
+  if (!built.ok) return built;
+  writeKnownHosts(hostname, built.lines);
+  log(`known_hosts pinned for ${hostname} from GDS-reported keys (${built.lines.length})`);
+  return { ok: true, keys: built.lines.length, source: 'api' };
+}
+
+// --- 2c. VERIFY the on-disk pin (self-heal, idea 264) ----------------------
+// The app used to pin once per activation and then trust an in-memory ok flag
+// forever. A box rebuild (fresh host keys) or a hand `ssh-keygen -R` silently
+// invalidates the pinned line, leaving the panel showing "pinned ✓" while Claude
+// Desktop's ssh2 hard-fails with "Host denied (verification failed)". These two
+// helpers let main.js re-check the actual file each poll and re-pin on a miss.
+
+// PURE (unit-tested): is the box's CURRENT ed25519 identity pinned in this
+// known_hosts text? ed25519 is the algo Claude Desktop verifies first (#925), so
+// it is the load-bearing line. With `expectedLines` (GDS-authoritative, from
+// hostKeyLinesFor) require the EXACT ed25519 key for `hostname` — that catches a
+// stale key left by a rebuild. Without them, fall back to "an ed25519 line for
+// `hostname` exists at all" — that catches a missing / `ssh-keygen -R`'d pin.
+function knownHostsHasKey(existingText, hostname, expectedLines = []) {
+  if (!hostname) return false;
+  const pinned = new Set();
+  for (const raw of String(existingText || '').split('\n')) {
+    const t = raw.trim();
+    if (!t || t.startsWith('#')) continue;
+    const parts = t.split(/\s+/);
+    if (!(parts[0] || '').split(',').includes(hostname)) continue;
+    if ((parts[1] || '') !== REQUIRED_KEY_ALGO) continue;
+    pinned.add(parts[2] || '');
+  }
+  if (pinned.size === 0) return false; // no ed25519 pin for this host at all
+  const wantEd = (Array.isArray(expectedLines) ? expectedLines : [])
+    .map((l) => String(l).trim().split(/\s+/))
+    .find((p) => (p[1] || '') === REQUIRED_KEY_ALGO);
+  // Authoritative key known → require an exact match (a stale rebuild key fails);
+  // otherwise the presence of any ed25519 pin is the strongest check available.
+  return wantEd ? pinned.has(wantEd[2] || '') : true;
+}
+
+// Thin IO wrapper: read the real known_hosts and report whether the box's current
+// identity is pinned. main.js calls this to decide self-heal, instead of trusting
+// a latched flag. Same { ok, reason? } shape as the refresh helpers.
+function verifyKnownHosts(hostname, hostKeysText) {
+  if (!hostname) return { ok: false, reason: 'no_hostname' };
+  const built = hostKeyLinesFor(hostname, hostKeysText);
+  let existing = '';
+  try {
+    if (fs.existsSync(KNOWN_HOSTS)) existing = fs.readFileSync(KNOWN_HOSTS, 'utf8');
+  } catch { /* unreadable → treat as not-pinned; caller re-pins */ }
+  const ok = knownHostsHasKey(existing, hostname, built.ok ? built.lines : []);
+  return ok ? { ok: true } : { ok: false, reason: 'not_pinned' };
+}
+
+// --- 3. Claude Desktop managed settings ------------------------------------
+
+// The PER-USER Claude settings file — what the Desktop app's environment
+// picker actually reads sshConfigs from (same file its "Add SSH host" UI
+// writes; verified against the official docs in #910 after the managed-file
+// route left the picker empty on Windows). Writing here needs NO elevation.
+const CLAUDE_USER_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
+
+// Merge the server-issued sshConfigs into ~/.claude/settings.json, keyed by
+// entry id (replace ours, preserve everything else in the file). Pure-ish
+// core exported for tests via mergeUserSshConfigs.
+function mergeUserSshConfigs(existingJsonText, sshConfigs) {
+  let settings = {};
+  try {
+    const parsed = JSON.parse(existingJsonText);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) settings = parsed;
+  } catch { /* corrupt/missing → start clean but NEVER throw */ }
+  const ours = new Set(sshConfigs.map((c) => c.id));
+  const kept = Array.isArray(settings.sshConfigs)
+    ? settings.sshConfigs.filter((c) => !c || !ours.has(c.id))
+    : [];
+  return { ...settings, sshConfigs: [...kept, ...sshConfigs] };
+}
+
+function installUserSshConfig(serverSettings, { log = () => {} } = {}) {
+  const sshConfigs = serverSettings && Array.isArray(serverSettings.sshConfigs)
+    ? serverSettings.sshConfigs : [];
+  if (sshConfigs.length === 0) return { ok: false, reason: 'no_ssh_configs' };
+  const existing = fs.existsSync(CLAUDE_USER_SETTINGS)
+    ? fs.readFileSync(CLAUDE_USER_SETTINGS, 'utf8') : '';
+  const next = mergeUserSshConfigs(existing, sshConfigs);
+  const nextText = `${JSON.stringify(next, null, 2)}\n`;
+  if (existing.trim() === nextText.trim()) {
+    return { ok: true, unchanged: true };
+  }
+  fs.mkdirSync(path.dirname(CLAUDE_USER_SETTINGS), { recursive: true });
+  fs.writeFileSync(CLAUDE_USER_SETTINGS, nextText);
+  log(`user settings: sshConfigs written to ${CLAUDE_USER_SETTINGS} (${sshConfigs.map((c) => c.name).join(', ')})`);
+  return { ok: true };
+}
+
+// System-level managed settings — now only the OPTIONAL hardening layer
+// (sshHostAllowlist); the picker entry itself comes from the user settings
+// above. The docs name Program Files on Windows while older Desktop builds
+// referenced ProgramData — installManagedSettings writes BOTH in the one
+// elevation, and settingsUpToDate checks the documented one.
+function managedSettingsPath() {
+  if (IS_MAC) return '/Library/Application Support/ClaudeCode/managed-settings.json';
+  if (IS_WIN) return 'C:\\Program Files\\ClaudeCode\\managed-settings.json';
+  return null; // Linux is not a managed-settings target
+}
+
+function managedSettingsPathsAll() {
+  if (IS_MAC) return [managedSettingsPath()];
+  if (IS_WIN) return [managedSettingsPath(), 'C:\\ProgramData\\ClaudeCode\\managed-settings.json'];
+  return [];
+}
+
+function settingsUpToDate(targetPath, content) {
+  try {
+    const current = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+    return JSON.stringify(current) === JSON.stringify(JSON.parse(content));
+  } catch { return false; }
+}
+
+// Write `content` to the system path via a native elevation prompt.
+// Returns { ok } | { ok: false, reason: 'cancelled' | 'unsupported' | 'failed' }.
+async function installManagedSettings(content, { log = () => {} } = {}) {
+  // Dev/test hook (README): never pop an elevation dialog in stub runs / CI.
+  if (process.env.OTB_DEVBOX_NO_ELEVATE === '1') return { ok: false, reason: 'skipped' };
+  const target = managedSettingsPath();
+  if (!target) return { ok: false, reason: 'unsupported' };
+  if (settingsUpToDate(target, content)) {
+    log('managed settings already current — no elevation needed');
+    return { ok: true, unchanged: true };
+  }
+  const tmp = path.join(os.tmpdir(), `otb-managed-settings-${process.pid}.json`);
+  fs.writeFileSync(tmp, content, { mode: 0o644 });
+  try {
+    if (IS_MAC) {
+      const dir = path.dirname(target);
+      // Single quoted shell line inside osascript; paths are fixed constants
+      // (no user input). The OS shows its own admin-password dialog.
+      const shell = `mkdir -p '${dir}' && cp '${tmp}' '${target}' && chmod 644 '${target}'`;
+      const script = `do shell script "${shell.replace(/[\\"]/g, '\\$&')}" with administrator privileges with prompt "OTB Dev Box installs the Claude Desktop connection file."`;
+      await run('osascript', ['-e', script], { timeout: 120_000 });
+    } else {
+      // UAC prompt via Start-Process -Verb RunAs; -Wait so we can re-check.
+      // One elevation writes EVERY candidate path (Program Files per current
+      // docs + ProgramData for older Desktop builds).
+      const inner = managedSettingsPathsAll()
+        .map((t) => `New-Item -ItemType Directory -Force -Path '${path.dirname(t)}' | Out-Null; Copy-Item -Force '${tmp}' '${t}'`)
+        .join('; ');
+      const outer = `Start-Process -FilePath powershell -Verb RunAs -Wait -WindowStyle Hidden -ArgumentList '-NoProfile','-NonInteractive','-Command',"${inner.replace(/"/g, '\\"')}"`;
+      await run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', outer], { timeout: 120_000 });
+    }
+  } catch (e) {
+    const msg = String((e && (e.stderr || e.message)) || '');
+    const cancelled = /canceled|cancelled|-128|was cancelled by the user|Operation did not complete/i.test(msg);
+    log(`managed-settings install ${cancelled ? 'cancelled' : 'failed'}: ${msg.slice(0, 200)}`);
+    return { ok: false, reason: cancelled ? 'cancelled' : 'failed' };
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* gone is fine */ }
+  }
+  const ok = settingsUpToDate(target, content);
+  log(`managed settings install ${ok ? 'verified' : 'NOT verified'} at ${target}`);
+  return ok ? { ok: true } : { ok: false, reason: 'failed' };
+}
+
+module.exports = {
+  ensureKey,
+  registerKeyWithVerify,
+  sshFingerprintSha256,
+  publicKeyFingerprint,
+  knownHostsLineMatchesHost,
+  refreshKnownHosts,
+  refreshKnownHostsFromKeys,
+  hostKeyLinesFor,
+  reportedKeysAreStale,
+  knownHostsHasKey,
+  verifyKnownHosts,
+  resolveSshTool,
+  keyscanCandidates,
+  scanWithTool,
+  scanComplete,
+  installUserSshConfig,
+  mergeUserSshConfigs,
+  CLAUDE_USER_SETTINGS,
+  installManagedSettings,
+  managedSettingsPath,
+  settingsUpToDate,
+  mergeKnownHosts,
+  KEY_PATH,
+  KNOWN_HOSTS,
+};