@passioncode-ai/passioncode 0.1.53 → 0.2.0

package/lib/mcp-probe.js

@@ -0,0 +1,91 @@
+'use strict';
+/**
+ * One proving call against a stdio MCP server, the way a coding agent starts it: the registered
+ * command, arguments and environment; `initialize`, `notifications/initialized`, `tools/list`,
+ * then one read-only tool. The child is the probe's own process and is stopped when the call
+ * returns or the deadline passes. Nothing the server prints is logged; only the outcome is kept.
+ */
+const { spawn } = require('child_process');
+
+const PROTOCOL = '2025-06-18';
+
+function probe({ command, args = [], env = {}, cwd, tool = null, toolArgs = {}, timeoutMs = 20000, version = '0.0.0' }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, { cwd, env: { ...process.env, ...env }, stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (error) {
+      resolve({ ok: false, stage: 'start', reason: error.message });
+      return;
+    }
+    const result = { ok: false, stage: 'start', server: null, tools: null, reason: null };
+    let buffer = '';
+    let done = false;
+    const pending = new Map();
+    let nextId = 1;
+    const finish = (patch) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      Object.assign(result, patch);
+      // Release every pipe (a wrapper that does not exec, whose own child holds them, must not keep
+      // the launcher alive), ask the server to stop, and wait for it — at most 2.5 s, then SIGKILL —
+      // so no probe outlives the command as an orphan.
+      for (const stream of [child.stdin, child.stdout, child.stderr]) { try { stream.destroy(); } catch (_) { /* gone */ } }
+      let settled = false;
+      const settle = () => { if (settled) return; settled = true; clearTimeout(hard); try { child.unref(); } catch (_) { /* gone */ } resolve(result); };
+      const hard = setTimeout(() => { try { child.kill('SIGKILL'); } catch (_) { /* gone */ } settle(); }, 2500);
+      if (child.exitCode !== null || child.signalCode !== null) { settle(); return; }
+      child.once('exit', settle);
+      try { child.kill('SIGTERM'); } catch (_) { settle(); }
+    };
+    const timer = setTimeout(() => finish({ ok: false, reason: `no answer to ${result.stage} within ${Math.round(timeoutMs / 1000)} s` }), timeoutMs);
+    const send = (method, params) => new Promise((ok) => {
+      const id = nextId++;
+      pending.set(id, ok);
+      try { child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`); } catch (error) { finish({ ok: false, reason: error.message }); }
+    });
+    const notify = (method, params) => { try { child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method, ...(params ? { params } : {}) })}\n`); } catch (_) { /* reported by exit */ } };
+    child.on('error', (error) => finish({ ok: false, reason: error.code === 'ENOENT' ? `${command} does not exist` : error.message }));
+    child.on('exit', (code, signal) => finish({ ok: false, reason: `the server exited (${signal || `code ${code}`}) during ${result.stage}` }));
+    child.stderr.on('data', () => { /* servers log on stderr; never echoed */ });
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk.toString('utf8');
+      let nl;
+      while ((nl = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, nl).trim();
+        buffer = buffer.slice(nl + 1);
+        if (!line) continue;
+        let msg;
+        try { msg = JSON.parse(line); } catch (_) { finish({ ok: false, reason: 'the server wrote something that is not JSON-RPC on stdout' }); return; }
+        if (msg.id !== undefined && pending.has(msg.id)) { const ok = pending.get(msg.id); pending.delete(msg.id); ok(msg); }
+      }
+    });
+    (async () => {
+      result.stage = 'initialize';
+      const init = await send('initialize', { protocolVersion: PROTOCOL, capabilities: {}, clientInfo: { name: 'passioncode-doctor', version } });
+      if (init.error || !init.result) { finish({ ok: false, reason: `initialize refused: ${(init.error && init.error.message) || 'no result'}` }); return; }
+      result.server = init.result.serverInfo ? { name: init.result.serverInfo.name, version: init.result.serverInfo.version } : null;
+      notify('notifications/initialized');
+      // tool === false: initialize only (a server whose first real call has an effect).
+      if (tool === false) { finish({ ok: true, stage: 'initialize' }); return; }
+      result.stage = 'tools/list';
+      const list = await send('tools/list', {});
+      if (list.error || !list.result || !Array.isArray(list.result.tools)) { finish({ ok: false, reason: `tools/list failed: ${(list.error && list.error.message) || 'no tools'}` }); return; }
+      result.tools = list.result.tools.length;
+      if (!tool) { finish({ ok: true }); return; }
+      if (!list.result.tools.some((t) => t.name === tool)) { finish({ ok: false, reason: `the server lists no ${tool} tool` }); return; }
+      result.stage = `tools/call ${tool}`;
+      const call = await send('tools/call', { name: tool, arguments: toolArgs });
+      if (call.error) { finish({ ok: false, reason: `${tool} failed: ${call.error.message}` }); return; }
+      if (call.result && call.result.isError) {
+        const text = (call.result.content || []).map((c) => c.text || '').join(' ').slice(0, 200);
+        finish({ ok: false, reason: `${tool} answered with an error${text ? `: ${text}` : ''}` });
+        return;
+      }
+      finish({ ok: true });
+    })().catch((error) => finish({ ok: false, reason: error.message }));
+  });
+}
+
+module.exports = { probe, PROTOCOL };

package/lib/openpgp.js

@@ -0,0 +1,209 @@
+'use strict';
+/**
+ * The one OpenPGP check the launcher needs: a detached v4 Ed25519 signature over SHA256SUMS,
+ * made by the PassionCode.ai release key. Every product release publishes SHA256SUMS and
+ * SHA256SUMS.asc (passioncode-ai/.github release-signing, `release-publish@v1`); the key is
+ * bundled as lib/release-key.asc and pinned here by fingerprint, so no gpg and no keyserver are
+ * involved and a key swapped in the package would not verify either.
+ *
+ * Scope on purpose: v4 packets, public-key algorithm 22 (EdDSA, curve Ed25519), hash SHA-256 or
+ * SHA-512, signature type 0x00 (binary document). Anything else is refused, never guessed.
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const RELEASE_KEY_FINGERPRINT = '63B30DC324BD697487AA31944FAFB8AEC803B6A7';
+const RELEASE_KEY_FILE = path.join(__dirname, 'release-key.asc');
+const ED25519_OID = '2b06010401da470f01';
+const HASHES = { 8: 'sha256', 10: 'sha512' };
+
+function dearmor(text) {
+  const lines = String(text).replace(/\r/g, '').split('\n');
+  const start = lines.findIndex((l) => /^-----BEGIN PGP (SIGNATURE|PUBLIC KEY BLOCK)-----$/.test(l));
+  const end = lines.findIndex((l, i) => i > start && /^-----END PGP /.test(l));
+  if (start < 0 || end < 0) throw new Error('no OpenPGP armour');
+  let i = start + 1;
+  while (i < end && lines[i].trim() !== '') i += 1; // armour headers
+  const body = lines.slice(i + 1, end).filter((l) => !l.startsWith('=')).join('');
+  if (!/^[A-Za-z0-9+/=]+$/.test(body)) throw new Error('damaged OpenPGP armour');
+  return Buffer.from(body, 'base64');
+}
+
+function packets(buf) {
+  const out = [];
+  let i = 0;
+  while (i < buf.length) {
+    const ctb = buf[i];
+    if (!(ctb & 0x80)) throw new Error('not an OpenPGP packet');
+    let tag, len, off;
+    if (ctb & 0x40) {
+      tag = ctb & 0x3f;
+      const o = buf[i + 1];
+      if (o < 192) { len = o; off = i + 2; }
+      else if (o < 224) { len = ((o - 192) << 8) + buf[i + 2] + 192; off = i + 3; }
+      else if (o === 255) { len = buf.readUInt32BE(i + 2); off = i + 6; }
+      else throw new Error('partial-length packets are not supported');
+    } else {
+      tag = (ctb >> 2) & 0x0f;
+      const t = ctb & 3;
+      if (t === 0) { len = buf[i + 1]; off = i + 2; }
+      else if (t === 1) { len = buf.readUInt16BE(i + 1); off = i + 3; }
+      else if (t === 2) { len = buf.readUInt32BE(i + 1); off = i + 5; }
+      else throw new Error('indeterminate-length packets are not supported');
+    }
+    if (off + len > buf.length) throw new Error('truncated OpenPGP packet');
+    out.push({ tag, body: buf.subarray(off, off + len) });
+    i = off + len;
+  }
+  return out;
+}
+
+function mpi(buf, at) {
+  const bits = buf.readUInt16BE(at);
+  const bytes = (bits + 7) >> 3;
+  return { value: buf.subarray(at + 2, at + 2 + bytes), next: at + 2 + bytes };
+}
+
+function subpackets(buf) {
+  const out = [];
+  let i = 0;
+  while (i < buf.length) {
+    let len = buf[i];
+    let off = i + 1;
+    if (len >= 192 && len < 255) { len = ((len - 192) << 8) + buf[i + 1] + 192; off = i + 2; }
+    else if (len === 255) { len = buf.readUInt32BE(i + 1); off = i + 5; }
+    out.push({ type: buf[off] & 0x7f, data: buf.subarray(off + 1, off + len) });
+    i = off + len;
+  }
+  return out;
+}
+
+function parseSignature(body) {
+  if (body[0] !== 4) throw new Error(`signature version ${body[0]} is not supported`);
+  const type = body[1], algo = body[2], hash = body[3];
+  const hashedLen = body.readUInt16BE(4);
+  const hashed = body.subarray(6, 6 + hashedLen);
+  const unhashedLen = body.readUInt16BE(6 + hashedLen);
+  const unhashed = body.subarray(8 + hashedLen, 8 + hashedLen + unhashedLen);
+  let at = 8 + hashedLen + unhashedLen;
+  const left16 = body.subarray(at, at + 2); at += 2;
+  const r = mpi(body, at); const s = mpi(body, r.next);
+  const sub = [...subpackets(hashed), ...subpackets(unhashed)];
+  const fprSub = sub.find((p) => p.type === 33);
+  const created = subpackets(hashed).find((p) => p.type === 2);
+  return {
+    type, algo, hash, left16, r: r.value, s: s.value, hashedSub: subpackets(hashed),
+    signed: body.subarray(0, 6 + hashedLen),
+    issuer: fprSub ? fprSub.data.subarray(1).toString('hex').toUpperCase() : null,
+    createdAt: created ? new Date(created.data.readUInt32BE(0) * 1000) : null,
+  };
+}
+
+function pad32(b) { return b.length >= 32 ? b.subarray(b.length - 32) : Buffer.concat([Buffer.alloc(32 - b.length), b]); }
+
+function sigDigest(sig, data) {
+  const name = HASHES[sig.hash];
+  if (!name) throw new Error(`hash algorithm ${sig.hash} is not supported`);
+  const trailer = Buffer.alloc(6);
+  trailer[0] = 4; trailer[1] = 0xff; trailer.writeUInt32BE(sig.signed.length, 2);
+  return crypto.createHash(name).update(data).update(sig.signed).update(trailer).digest();
+}
+
+function edVerify(rawKey, digest, sig) {
+  const key = crypto.createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: rawKey.toString('base64url') }, format: 'jwk' });
+  return crypto.verify(null, digest, key, Buffer.concat([pad32(sig.r), pad32(sig.s)]));
+}
+
+/** The primary key of an armoured public key block: fingerprint, raw Ed25519 point, expiry. */
+function readPublicKey(armoured) {
+  const list = packets(dearmor(armoured));
+  const pk = list.find((p) => p.tag === 6);
+  if (!pk) throw new Error('no public key packet');
+  const b = pk.body;
+  if (b[0] !== 4 || b[5] !== 22) throw new Error('the release key must be a v4 EdDSA key');
+  const oidLen = b[6];
+  if (b.subarray(7, 7 + oidLen).toString('hex') !== ED25519_OID) throw new Error('the release key must be on Ed25519');
+  const point = mpi(b, 7 + oidLen).value;
+  if (point[0] !== 0x40 || point.length !== 33) throw new Error('unexpected Ed25519 point encoding');
+  const header = Buffer.from([0x99, b.length >> 8, b.length & 0xff]);
+  const fingerprint = crypto.createHash('sha1').update(header).update(b).digest('hex').toUpperCase();
+  const createdAt = new Date(b.readUInt32BE(1) * 1000);
+  const raw = point.subarray(1);
+  // The newest valid self-signature over the user id (types 0x10–0x13) carries the key's expiry.
+  let expiresAt = null;
+  const uidIndex = list.findIndex((p) => p.tag === 13);
+  if (uidIndex >= 0) {
+    const uid = list[uidIndex].body;
+    for (const p of list.slice(uidIndex + 1)) {
+      if (p.tag !== 2) { if (p.tag === 13 || p.tag === 14) break; continue; }
+      const sig = parseSignature(p.body);
+      if (sig.type < 0x10 || sig.type > 0x13 || sig.issuer !== fingerprint) continue;
+      const uidHeader = Buffer.alloc(5); uidHeader[0] = 0xb4; uidHeader.writeUInt32BE(uid.length, 1);
+      const signedData = Buffer.concat([header, b, uidHeader, uid]);
+      if (!edVerify(raw, sigDigest(sig, signedData), sig)) continue;
+      const exp = sig.hashedSub.find((s) => s.type === 9);
+      expiresAt = exp ? new Date(createdAt.getTime() + exp.data.readUInt32BE(0) * 1000) : null;
+    }
+  }
+  return { fingerprint, raw, createdAt, expiresAt };
+}
+
+let bundled = null;
+/**
+ * The trusted release key. PASSIONCODE_RELEASE_KEY (an armoured key file) replaces it for tests,
+ * like the launcher's other PASSIONCODE_* overrides: trusted local configuration, not a sandbox;
+ * setup and doctor name the override in their output whenever it is set.
+ */
+function releaseKey() {
+  if (process.env.PASSIONCODE_RELEASE_KEY) return readPublicKey(fs.readFileSync(process.env.PASSIONCODE_RELEASE_KEY, 'utf8'));
+  if (!bundled) {
+    bundled = readPublicKey(fs.readFileSync(RELEASE_KEY_FILE, 'utf8'));
+    if (bundled.fingerprint !== RELEASE_KEY_FINGERPRINT) throw new Error('the bundled release key does not match its pinned fingerprint');
+  }
+  return bundled;
+}
+
+/**
+ * Verify `data` against an armoured detached signature by the PassionCode.ai release key.
+ * Returns { ok, reason?, fingerprint?, createdAt? }; it never throws on bad input.
+ */
+function verifyDetached(data, armouredSignature, { key, now = new Date() } = {}) {
+  try { key = key || releaseKey(); } catch (error) { return { ok: false, reason: `release key: ${error.message}` }; }
+  let sig;
+  try {
+    const p = packets(dearmor(armouredSignature)).find((x) => x.tag === 2);
+    if (!p) return { ok: false, reason: 'no signature packet in SHA256SUMS.asc' };
+    sig = parseSignature(p.body);
+  } catch (error) {
+    return { ok: false, reason: `unreadable signature: ${error.message}` };
+  }
+  if (sig.type !== 0x00) return { ok: false, reason: `signature type ${sig.type} is not a document signature` };
+  if (sig.algo !== 22) return { ok: false, reason: `signature algorithm ${sig.algo} is not EdDSA` };
+  if (sig.issuer && sig.issuer !== key.fingerprint) {
+    return { ok: false, reason: `signed by ${sig.issuer}, which is not the PassionCode.ai release key ${key.fingerprint}` };
+  }
+  let digest;
+  try { digest = sigDigest(sig, data); } catch (error) { return { ok: false, reason: error.message }; }
+  if (!digest.subarray(0, 2).equals(sig.left16)) return { ok: false, reason: 'the signature does not match SHA256SUMS (digest prefix differs)' };
+  let good = false;
+  try { good = edVerify(key.raw, digest, sig); } catch (_) { good = false; }
+  if (!good) return { ok: false, reason: 'the signature does not match SHA256SUMS' };
+  if (key.expiresAt && sig.createdAt && sig.createdAt > key.expiresAt) return { ok: false, reason: `signed after the release key expired (${key.expiresAt.toISOString()})` };
+  if (sig.createdAt && sig.createdAt.getTime() > now.getTime() + 24 * 3600 * 1000) return { ok: false, reason: 'the signature is dated in the future' };
+  return { ok: true, fingerprint: key.fingerprint, createdAt: sig.createdAt };
+}
+
+/** SHA256SUMS → Map(name → hex). A line that is not `<64 hex>  <name>` is an error, not skipped. */
+function parseSums(text) {
+  const map = new Map();
+  String(text).split('\n').forEach((line, i) => {
+    if (!line.trim()) return;
+    const m = /^([0-9a-f]{64}) [ *](.+)$/.exec(line.trimEnd());
+    if (!m) throw new Error(`SHA256SUMS line ${i + 1} is not "<sha256>  <file>"`);
+    map.set(m[2], m[1]);
+  });
+  return map;
+}
+
+module.exports = { verifyDetached, readPublicKey, releaseKey, parseSums, RELEASE_KEY_FINGERPRINT };

package/lib/release-key.asc

@@ -0,0 +1,10 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mDMEasEA0BYJKwYBBAHaRw8BAQdAzg/il4KR76Liuy7pPkEmveL2sTU8kh3FZn+H
+pfrbJV+0MFBhc3Npb25Db2RlLmFpIHJlbGVhc2VzIDxjb250YWN0QHBhc3Npb25j
+b2RlLmFpPoi1BBMWCgBdFiEEY7MNwyS9aXSHqjGUT6+4rsgDtqcFAmrBANAbFIAA
+AAAABAAObWFudTIsMi41KzEuMTIsMCwzAhsDBQkFo5qABQsJCAcCAiICBhUKCQgL
+AgQWAgMBAh4HAheAAAoJEE+vuK7IA7anM7sBAItPsg0cAR8JcR97aXmgmg+X44cZ
+PhciNxImjH/WhJBjAP9xU0g3+Y/af6sNeoV8PM2w1K1echJaa97VLI38Z/8lCA==
+=5KqR
+-----END PGP PUBLIC KEY BLOCK-----

package/lib/releases.js

@@ -0,0 +1,211 @@
+'use strict';
+/**
+ * Latest releases of the PassionCode.ai apps, and an install that trusts no byte it has not
+ * verified (ADR-0004): SHA256SUMS.asc against the bundled release key, the asset against both its
+ * SHA256SUMS line and GitHub's digest, then the extracted app's Developer ID signature, team,
+ * stapled notarization ticket and Gatekeeper assessment. A failure removes the download.
+ */
+const { spawnSync } = require('child_process');
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const pgp = require('./openpgp');
+const catalog = require('./catalog');
+
+const API = () => (process.env.PASSIONCODE_GITHUB_API || 'https://api.github.com').replace(/\/$/, '');
+const CACHE_TTL_MS = 30 * 60 * 1000;
+
+function run(cmd, args, { timeout = 60000, input } = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', timeout, input });
+  if (r.error && r.error.code === 'ENOENT') return { code: 127, out: '', err: `${cmd} not found` };
+  if (r.error && r.error.code === 'ETIMEDOUT') return { code: 124, out: r.stdout || '', err: `${cmd} timed out after ${Math.round(timeout / 1000)} s` };
+  return { code: r.status === null ? 1 : r.status, out: r.stdout || '', err: r.stderr || '' };
+}
+
+async function getJson(url) {
+  const res = await fetch(url, { headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'passioncode-launcher' }, signal: AbortSignal.timeout(15000) });
+  if (!res.ok) throw new Error(`${url} answered HTTP ${res.status}`);
+  return res.json();
+}
+
+/**
+ * The newest published release of a product: `releases/latest` for stable products, the newest
+ * non-draft release for one that ships prereleases only (Fabric). Cached for 30 minutes in
+ * ~/.passioncode/releases-cache.json, because unauthenticated GitHub allows 60 calls an hour.
+ */
+async function latestRelease(product, { cacheFile = null, now = Date.now() } = {}) {
+  let cache = {};
+  if (cacheFile) { try { cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8')); } catch (_) { cache = {}; } }
+  const hit = cache[product.repo];
+  if (hit && now - Date.parse(hit.at) < CACHE_TTL_MS && hit.release) return hit.release;
+  let raw;
+  if (product.prerelease) {
+    const list = await getJson(`${API()}/repos/${product.repo}/releases?per_page=10`);
+    raw = (Array.isArray(list) ? list : []).find((r) => !r.draft);
+    if (!raw) throw new Error(`${product.repo} has no published release`);
+  } else {
+    raw = await getJson(`${API()}/repos/${product.repo}/releases/latest`);
+  }
+  const release = {
+    tag: raw.tag_name, version: String(raw.tag_name || '').replace(/^v/, ''), prerelease: !!raw.prerelease, url: raw.html_url,
+    assets: (raw.assets || []).map((a) => ({ name: a.name, url: a.browser_download_url, size: a.size, digest: a.digest || null })),
+  };
+  if (!/^\d+\.\d+\.\d+/.test(release.version)) throw new Error(`${product.repo}: unexpected tag ${raw.tag_name}`);
+  if (cacheFile) {
+    cache[product.repo] = { at: new Date(now).toISOString(), release };
+    try { fs.mkdirSync(path.dirname(cacheFile), { recursive: true }); fs.writeFileSync(cacheFile, JSON.stringify(cache, null, 2)); } catch (_) { /* a cache only */ }
+  }
+  return release;
+}
+
+async function download(url, dest) {
+  const res = await fetch(url, { headers: { 'User-Agent': 'passioncode-launcher' }, redirect: 'follow', signal: AbortSignal.timeout(30 * 60 * 1000) });
+  if (!res.ok || !res.body) throw new Error(`download ${url}: HTTP ${res.status}`);
+  const hash = crypto.createHash('sha256');
+  const fd = fs.openSync(dest, 'w');
+  try {
+    for await (const chunk of res.body) { hash.update(chunk); fs.writeSync(fd, chunk); }
+  } finally { fs.closeSync(fd); }
+  return hash.digest('hex');
+}
+
+/** Free bytes on the volume holding `dir` (df -k), or null when it cannot be read. */
+function freeBytes(dir) {
+  const r = run('df', ['-k', dir], { timeout: 10000 });
+  const line = r.out.trim().split('\n').pop() || '';
+  const cols = line.split(/\s+/);
+  const kb = Number(cols[3]);
+  return r.code === 0 && Number.isFinite(kb) ? kb * 1024 : null;
+}
+
+/** Checks of an app bundle on disk: Developer ID signature, the PassionCode.ai team, stapled ticket, Gatekeeper. */
+function verifyApp(appDir, { gatekeeper = true } = {}) {
+  const checks = [];
+  const sig = run('codesign', ['--verify', '--strict', appDir], { timeout: 120000 });
+  checks.push({ check: 'signature', ok: sig.code === 0, detail: sig.code === 0 ? 'codesign --verify --strict: valid' : (sig.err || sig.out).trim().split('\n')[0] });
+  const info = run('codesign', ['-dv', appDir], { timeout: 30000 });
+  const team = /TeamIdentifier=(\S+)/.exec(`${info.err}\n${info.out}`);
+  checks.push({ check: 'team', ok: !!team && team[1] === catalog.TEAM_ID, detail: team ? `team ${team[1]}` : 'no team identifier' });
+  const staple = run('xcrun', ['stapler', 'validate', appDir], { timeout: 60000 });
+  checks.push({ check: 'notarization', ok: staple.code === 0, detail: staple.code === 0 ? 'notarization ticket stapled' : (staple.err || staple.out || 'stapler validate failed').trim().split('\n').pop() });
+  if (gatekeeper) {
+    const gk = run('spctl', ['--assess', '--type', 'execute', '-vv', appDir], { timeout: 120000 });
+    const text = `${gk.err}\n${gk.out}`;
+    checks.push({ check: 'gatekeeper', ok: gk.code === 0 && /source=Notarized Developer ID/.test(text), detail: gk.code === 124 ? gk.err : (/source=([^\n]+)/.exec(text) || [null, text.trim().split('\n')[0] || 'rejected'])[1] });
+  }
+  return { ok: checks.every((c) => c.ok), checks };
+}
+
+/**
+ * Whether anything runs from an app bundle: the app itself or an agent's MCP server that execs
+ * into its Contents/MacOS (pgrep; reads only). pgrep answers 0 (found) or 1 (none); any other
+ * answer — missing, timed out, an error — is "in use", so a doubt never lets a bundle be moved.
+ */
+function isRunning(appDir) {
+  return run('pgrep', ['-f', `${appDir}/Contents/MacOS/`], { timeout: 5000 }).code !== 1;
+}
+
+/** CFBundleShortVersionString of an installed app, or null. */
+function appVersion(appDir) {
+  const r = run('plutil', ['-extract', 'CFBundleShortVersionString', 'raw', '-o', '-', path.join(appDir, 'Contents', 'Info.plist')], { timeout: 10000 });
+  const v = r.out.trim();
+  return r.code === 0 && v ? v : null;
+}
+
+/**
+ * Download, verify and install one absent app into the applications folder. `report(step)` gets
+ * each stage. Throws with the first failed check; the working directory is always removed.
+ */
+async function installApp(product, release, { work, report = () => {}, replace = false, home = os.homedir() }) {
+  const target = catalog.appPath(product);
+  if (fs.existsSync(target) && !replace) throw new Error(`${target} already exists`);
+  if (fs.existsSync(target) && isRunning(target)) throw new Error(`${product.name} is in use (the app, or an agent's MCP server that runs from it); quit it first`);
+  const assetName = product.asset(release.version);
+  const asset = release.assets.find((a) => a.name === assetName);
+  const sums = release.assets.find((a) => a.name === 'SHA256SUMS');
+  const sig = release.assets.find((a) => a.name === 'SHA256SUMS.asc');
+  if (!asset) throw new Error(`${release.tag} has no ${assetName}`);
+  if (!sums || !sig) throw new Error(`${release.tag} publishes no signed SHA256SUMS; nothing unsigned is installed`);
+  fs.rmSync(work, { recursive: true, force: true });
+  fs.mkdirSync(work, { recursive: true });
+  try {
+    const free = freeBytes(work);
+    const need = (asset.size || 0) * 3;
+    if (free !== null && asset.size && free < need) throw new Error(`not enough disk: ${Math.round(free / 1e6)} MB free, about ${Math.round(need / 1e6)} MB needed to download and unpack ${assetName}`);
+    const sumsFile = path.join(work, 'SHA256SUMS');
+    await download(sums.url, sumsFile);
+    await download(sig.url, path.join(work, 'SHA256SUMS.asc'));
+    const verdict = pgp.verifyDetached(fs.readFileSync(sumsFile), fs.readFileSync(path.join(work, 'SHA256SUMS.asc'), 'utf8'));
+    if (!verdict.ok) throw new Error(`SHA256SUMS signature: ${verdict.reason}`);
+    report({ kind: 'verify', detail: `SHA256SUMS of ${release.tag} signed by the PassionCode.ai release key ${pgp.RELEASE_KEY_FINGERPRINT.slice(-16)}` });
+    const listed = pgp.parseSums(fs.readFileSync(sumsFile, 'utf8')).get(assetName);
+    if (!listed) throw new Error(`SHA256SUMS does not list ${assetName}`);
+    const file = path.join(work, assetName);
+    const got = await download(asset.url, file);
+    if (got !== listed) throw new Error(`${assetName}: SHA-256 ${got} is not the signed ${listed}`);
+    if (asset.digest && asset.digest !== `sha256:${got}`) throw new Error(`${assetName}: GitHub's digest ${asset.digest} differs from the download`);
+    report({ kind: 'verify', detail: `${assetName}: SHA-256 matches the signed SHA256SUMS${asset.digest ? ' and GitHub\'s digest' : ''}` });
+    const unpacked = path.join(work, 'unpacked');
+    fs.mkdirSync(unpacked);
+    let mount = null;
+    try {
+      let source;
+      if (assetName.endsWith('.dmg')) {
+        mount = path.join(work, 'mount');
+        fs.mkdirSync(mount);
+        const a = run('hdiutil', ['attach', '-nobrowse', '-readonly', '-noautoopen', '-mountpoint', mount, file], { timeout: 300000 });
+        if (a.code !== 0) { mount = null; throw new Error(`hdiutil attach: ${(a.err || a.out).trim()}`); }
+        source = path.join(mount, product.app);
+      } else {
+        const x = run('ditto', ['-x', '-k', file, unpacked], { timeout: 600000 });
+        if (x.code !== 0) throw new Error(`ditto -x: ${(x.err || x.out).trim()}`);
+        source = path.join(unpacked, product.app);
+      }
+      if (!fs.existsSync(source)) throw new Error(`${assetName} holds no ${product.app}`);
+      const app = verifyApp(source);
+      for (const c of app.checks) report({ kind: 'verify', detail: `${product.app}: ${c.check} — ${c.detail}`, ok: c.ok });
+      if (!app.ok) throw new Error(`${product.app} failed ${app.checks.filter((c) => !c.ok).map((c) => c.check).join(', ')}; nothing was installed`);
+      // Copy beside the target first, so /Applications never holds a half-written bundle; then two
+      // same-volume renames: the old bundle to the person's Trash (never deleted), the new one into place.
+      const staged = `${target}.passioncode-${process.pid}.partial`;
+      // A run killed mid-copy leaves its staged copy; remove those whose process is gone.
+      for (const name of fs.readdirSync(path.dirname(target))) {
+        const m = new RegExp(`^${product.app.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.passioncode-(\\d+)\\.partial$`).exec(name);
+        if (!m) continue;
+        let alive = true;
+        try { process.kill(Number(m[1]), 0); } catch (error) { alive = error.code === 'EPERM'; }
+        if (!alive || Number(m[1]) === process.pid) fs.rmSync(path.join(path.dirname(target), name), { recursive: true, force: true });
+      }
+      const c = run('ditto', [source, staged], { timeout: 600000 });
+      if (c.code !== 0) { fs.rmSync(staged, { recursive: true, force: true }); throw new Error(`copy to ${staged}: ${(c.err || c.out).trim()}`); }
+      let previous = null;
+      try {
+        if (fs.existsSync(target)) {
+          // The download took minutes: check again, right before the bundle moves.
+          if (isRunning(target)) throw new Error(`${product.name} came into use while it downloaded; quit it, then run setup again`);
+          const trash = path.join(home, '.Trash');
+          fs.mkdirSync(trash, { recursive: true });
+          previous = path.join(trash, `${product.app.replace(/\.app$/, '')} ${appVersion(target) || 'old'} ${new Date().toISOString().replace(/[:.]/g, '-')}.app`);
+          fs.renameSync(target, previous);
+          report({ kind: 'trash', detail: `moved the previous ${product.name} to ${previous}` });
+        }
+        try { fs.renameSync(staged, target); } catch (error) {
+          if (previous) {
+            try { fs.renameSync(previous, target); } catch (back) { throw new Error(`${error.message}; and putting the previous app back failed (${back.message}); it is in ${previous}`); }
+          }
+          throw error;
+        }
+      } finally {
+        fs.rmSync(staged, { recursive: true, force: true }); // only the staged copy, never the target
+      }
+      return { path: target, version: release.version, replaced: previous };
+    } finally {
+      if (mount) run('hdiutil', ['detach', mount, '-quiet'], { timeout: 120000 });
+    }
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}
+
+module.exports = { latestRelease, installApp, verifyApp, appVersion, isRunning, freeBytes, run, download, API };