@minionry/minion 0.7.36

package/bin/platform-endpoints.js

@@ -0,0 +1,8 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+
+export const PROD_PLATFORM_URL = 'https://api.minionry.com';
+
+export function resolvePlatformUrl() {
+  return process.env.PLATFORM_URL || PROD_PLATFORM_URL;
+}

package/bin/postinstall.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+
+
+import { platform } from 'node:os';
+import { CLI_ROOT, prebuiltPlatformDir } from './pty-locator.js';
+import { nodePtyDirIn, normalizeNodePtyTree } from './pty-provision.js';
+
+try {
+  normalizeNodePtyTree(prebuiltPlatformDir());
+  normalizeNodePtyTree(nodePtyDirIn(CLI_ROOT));
+} catch (_) {
+}
+
+async function loadChromeSandbox() {
+  try {
+    return await import('../dist/server/services/browser/chrome-sandbox.js');
+  } catch {
+    const tsx = await import('tsx/esm/api').catch(() => null);
+    if (tsx?.tsImport) {
+      return tsx.tsImport('../server/services/browser/chrome-sandbox.ts', import.meta.url);
+    }
+    return import('../server/services/browser/chrome-sandbox.js');
+  }
+}
+
+async function fixChromeSandbox() {
+  if (platform() === 'win32') return;
+  if (process.env.MINIONRY_SKIP_SANDBOX_FIX === '1') return;
+
+  let mod;
+  try {
+    mod = await loadChromeSandbox();
+  } catch (_) {
+    return;
+  }
+
+  try {
+    const result = await mod.ensureChromeSandbox({ interactive: false });
+    if (result.state === 'fixed') {
+      console.log('Minionry: configured Electron chrome-sandbox (root:root, mode 4755).');
+    } else if (result.state === 'cannot-fix' && result.manualCommand) {
+      console.log('Minionry: the Electron browser sandbox needs a one-time root fix:');
+      console.log(`  ${result.manualCommand}`);
+    }
+  } catch (_) {
+  }
+}
+
+fixChromeSandbox().catch(() => {});

package/bin/pty-doctor.js

@@ -0,0 +1,326 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { machinePath } from './machine-layout.js';
+import { NATIVE_ABI_KEY, nativeRoot } from './pty-locator.js';
+
+
+const PYTHON_KNOWN_GOOD = { min: 6, max: 13 };
+
+const PYTHON_CANDIDATES = ['python3.13', 'python3.12', 'python3.11', 'python3.10', 'python3.9', 'python3', 'python'];
+
+function which(command) {
+  try {
+    const finder = process.platform === 'win32' ? 'where' : 'which';
+    const out = execFileSync(finder, [command], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return out.split(/\r?\n/)[0].trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function pythonVersion(path) {
+  try {
+    const out = execFileSync(path, ['--version'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    const match = out.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match) return null;
+    return { raw: out.trim(), major: Number(match[1]), minor: Number(match[2]) };
+  } catch {
+    return null;
+  }
+}
+
+function isKnownGood(version) {
+  return version.major === 3 && version.minor >= PYTHON_KNOWN_GOOD.min && version.minor <= PYTHON_KNOWN_GOOD.max;
+}
+
+function probePython() {
+  const path = which('python3') ?? which('python');
+  if (!path) return { path: null, version: null, supported: false, alternative: null };
+
+  const version = pythonVersion(path);
+  if (!version) return { path, version: null, supported: false, alternative: null };
+  if (isKnownGood(version)) return { path, version, supported: true, alternative: null };
+
+  for (const candidate of PYTHON_CANDIDATES) {
+    const candidatePath = which(candidate);
+    if (!candidatePath || candidatePath === path) continue;
+    const candidateVersion = pythonVersion(candidatePath);
+    if (candidateVersion && isKnownGood(candidateVersion)) {
+      return { path, version, supported: false, alternative: { path: candidatePath, version: candidateVersion } };
+    }
+  }
+  return { path, version, supported: false, alternative: null };
+}
+
+function probeCompiler() {
+  if (process.platform === 'win32') {
+    return { cc: which('cl') ?? which('clang'), make: which('nmake') ?? which('msbuild') };
+  }
+  return { cc: which('cc') ?? which('gcc') ?? which('clang'), make: which('make') ?? which('gmake') };
+}
+
+export function probeToolchain() {
+  return {
+    node: { version: process.version, abi: process.versions.modules },
+    abiKey: NATIVE_ABI_KEY,
+    prefix: nativeRoot(),
+    python: probePython(),
+    compiler: probeCompiler(),
+  };
+}
+
+export function toolchainReady(probe) {
+  const missing = [
+    probe.compiler.cc ? null : 'a C/C++ compiler (cc/gcc/clang)',
+    probe.compiler.make ? null : 'make',
+    probe.python.path ? null : 'python3',
+  ].filter(Boolean);
+  return { ready: missing.length === 0, missing };
+}
+
+
+function readOsRelease() {
+  try {
+    const fields = {};
+    for (const line of readFileSync('/etc/os-release', 'utf-8').split('\n')) {
+      const eq = line.indexOf('=');
+      if (eq === -1) continue;
+      fields[line.slice(0, eq).trim()] = line
+        .slice(eq + 1)
+        .trim()
+        .replace(/^"|"$/g, '');
+    }
+    return fields;
+  } catch {
+    return null;
+  }
+}
+
+const LINUX_INSTALLERS = [
+  { match: /\b(debian|ubuntu)\b/, command: 'sudo apt install build-essential python3' },
+  { match: /\b(fedora|rhel|centos|rocky|almalinux)\b/, command: 'sudo dnf install gcc-c++ make python3' },
+  { match: /\b(arch|manjaro)\b/, command: 'sudo pacman -S base-devel python' },
+  { match: /\balpine\b/, command: 'sudo apk add build-base python3' },
+  { match: /\b(opensuse|suse|sles)\b/, command: 'sudo zypper install -t pattern devel_basis && sudo zypper install python3' },
+];
+
+const GENERIC_LINUX_ADVICE = [
+  'Install a C/C++ toolchain and Python 3 with your package manager, e.g.:',
+  '  Debian/Ubuntu: sudo apt install build-essential python3',
+  '  Fedora/RHEL:   sudo dnf install gcc-c++ make python3',
+  '  Arch:          sudo pacman -S base-devel python',
+  '  Alpine:        sudo apk add build-base python3',
+];
+
+export function buildToolsAdvice(osRelease = readOsRelease()) {
+  if (process.platform === 'darwin') return ['Install the Xcode Command Line Tools:  xcode-select --install'];
+  if (process.platform === 'win32') {
+    return ['Install the Visual Studio Build Tools with the "Desktop development with C++" workload, plus Python 3'];
+  }
+  const ids = `${osRelease?.ID ?? ''} ${osRelease?.ID_LIKE ?? ''}`.toLowerCase();
+  const installer = LINUX_INSTALLERS.find((i) => i.match.test(ids));
+  return installer ? [`Install a C/C++ toolchain and Python 3:  ${installer.command}`] : GENERIC_LINUX_ADVICE;
+}
+
+
+function allOutput(ctx) {
+  return ctx.attempts.map((a) => a.output).join('\n');
+}
+
+function loadErrorText(ctx) {
+  return ctx.loadErrors.map((e) => `${e.code}: ${e.message}`).join('\n');
+}
+
+const RULES = [
+  {
+    code: 'PERMISSION',
+    title: 'npm could not write to the install directory.',
+    test: (ctx) => /\bEACCES\b|\bEPERM\b|permission denied/i.test(allOutput(ctx)),
+    remedies: (ctx) => [
+      `Check ownership of ${ctx.probe.prefix} and your npm cache:`,
+      `  sudo chown -R "$(id -u):$(id -g)" ${join(ctx.probe.prefix, '..')} ~/.npm`,
+      'Then re-run: minion install terminal',
+    ],
+  },
+  {
+    code: 'REGISTRY',
+    title: 'The npm registry did not serve node-pty.',
+    test: (ctx) => /\bE404\b|\bETARGET\b|\bE401\b|\bE403\b|404 Not Found|401 Unauthorized/i.test(allOutput(ctx)),
+    remedies: () => [
+      'Your default registry may be a private mirror that does not carry node-pty.',
+      'Check it with: npm config get registry',
+      'A public-registry retry was attempted automatically; if it also failed, the mirror may be proxying npmjs.org incorrectly.',
+    ],
+  },
+  {
+    code: 'NETWORK',
+    title: 'npm could not reach a registry.',
+    test: (ctx) => /\bENOTFOUND\b|\bEAI_AGAIN\b|\bECONNREFUSED\b|\bETIMEDOUT\b|network timeout/i.test(allOutput(ctx)),
+    remedies: () => [
+      'Check connectivity and any proxy settings:',
+      '  npm config get proxy && npm config get https-proxy',
+      'Then re-run: minion install terminal',
+    ],
+  },
+  {
+    code: 'MISSING_TOOLCHAIN',
+    title: 'A C/C++ toolchain is missing, so node-pty cannot be compiled on this machine.',
+    test: (ctx) =>
+      !toolchainReady(ctx.probe).ready ||
+      /(?:^|\s)(?:make|gcc|g\+\+|cc|clang):\s*(?:command\s+)?not found/im.test(allOutput(ctx)),
+    remedies: (ctx) => {
+      const { missing } = toolchainReady(ctx.probe);
+      return [
+        missing.length ? `Not found on PATH: ${missing.join(', ')}.` : 'The build reported a missing compiler.',
+        ...buildToolsAdvice(),
+        'Then re-run: minion install terminal',
+      ];
+    },
+  },
+  {
+    code: 'PYTHON',
+    title: "node-gyp could not use this machine's Python.",
+    test: (ctx) =>
+      /gyp ERR!.*(?:Could not find any Python|find Python|Python is not set)/i.test(allOutput(ctx)) ||
+      /ModuleNotFoundError: No module named ['"]?(?:distutils|imp)/i.test(allOutput(ctx)),
+    remedies: (ctx) => {
+      const { python } = ctx.probe;
+      const lines = [];
+      if (python.version) {
+        lines.push(`Found ${python.path} (${python.version.raw}).`);
+      } else {
+        lines.push('No usable python3 was found on PATH.');
+      }
+      if (!python.supported && python.version) {
+        lines.push(
+          `node-gyp is known to work with Python 3.${PYTHON_KNOWN_GOOD.min}–3.${PYTHON_KNOWN_GOOD.max}; this is ${python.version.major}.${python.version.minor}.`,
+        );
+      }
+      if (python.alternative) {
+        lines.push(`A known-good interpreter is installed: ${python.alternative.path} (${python.alternative.version.raw}).`);
+        lines.push(`Point node-gyp at it: npm config set python ${python.alternative.path}`);
+      } else {
+        lines.push('Install a supported interpreter, e.g. Debian/Ubuntu: sudo apt install python3.12');
+        lines.push('Then: npm config set python "$(which python3.12)"');
+      }
+      lines.push('Then re-run: minion install terminal');
+      return lines;
+    },
+  },
+  {
+    code: 'ABI_MISMATCH',
+    title: 'node-pty is installed but was built for a different Node.js runtime.',
+    test: (ctx) =>
+      /NODE_MODULE_VERSION|was compiled against a different Node\.js version|invalid ELF header|undefined symbol|Module did not self-register/i.test(
+        `${loadErrorText(ctx)}\n${allOutput(ctx)}`,
+      ),
+    remedies: (ctx) => [
+      `This build is keyed to ${ctx.probe.abiKey}, so switching Node versions requires a fresh compile.`,
+      `Remove the cached build and re-provision:  rm -rf ${ctx.probe.prefix}`,
+      'Then re-run: minion install terminal',
+    ],
+  },
+  {
+    code: 'SPAWN_HELPER',
+    title: 'node-pty loaded but its spawn-helper is not executable.',
+    test: (ctx) => /posix_spawnp failed|spawn-helper/i.test(`${loadErrorText(ctx)}\n${allOutput(ctx)}`),
+    remedies: (ctx) => [
+      `chmod +x ${join(ctx.probe.prefix, 'node_modules/node-pty/build/Release/spawn-helper')}`,
+      'Then re-run: minion install terminal',
+    ],
+  },
+  {
+    code: 'COMPILE_FAILED',
+    title: 'node-pty failed to compile.',
+    test: (ctx) => /gyp ERR!|gyp: |fatal error:|: error: |ld: cannot find/i.test(allOutput(ctx)),
+    remedies: (ctx) => {
+      const lines = [];
+      if (!ctx.probe.python.supported && ctx.probe.python.version) {
+        lines.push(
+          `Note: python3 is ${ctx.probe.python.version.raw}, outside node-gyp's known-good window (3.${PYTHON_KNOWN_GOOD.min}–3.${PYTHON_KNOWN_GOOD.max}). That is a likely cause.`,
+        );
+        if (ctx.probe.python.alternative) {
+          lines.push(`Try: npm config set python ${ctx.probe.python.alternative.path}`);
+        }
+      }
+      lines.push('The compiler output above (and in the log below) has the specific error.');
+      return lines;
+    },
+  },
+  {
+    code: 'NOT_INSTALLED',
+    title: 'npm reported success but wrote no node-pty.',
+    test: (ctx) => ctx.attempts.some((a) => a.code === 0),
+    remedies: (ctx) => [
+      `Nothing landed in ${join(ctx.probe.prefix, 'node_modules')}.`,
+      'This usually means npm resolved the request against an existing dependency edge and omitted it.',
+      `Clear the prefix and retry:  rm -rf ${ctx.probe.prefix} && minion install terminal`,
+    ],
+  },
+];
+
+const UNKNOWN = {
+  code: 'UNKNOWN',
+  title: 'node-pty could not be installed, and the output did not identify why.',
+  remedies: () => ['Please report this with the log below.'],
+};
+
+export function classifyPtyFailure(input) {
+  const ctx = {
+    attempts: input.attempts ?? [],
+    loadErrors: input.loadErrors ?? [],
+    probe: input.probe ?? probeToolchain(),
+  };
+
+  const rule = RULES.find((r) => r.test(ctx)) ?? UNKNOWN;
+  return {
+    code: rule.code,
+    title: rule.title,
+    remedies: rule.remedies(ctx),
+    probe: ctx.probe,
+  };
+}
+
+
+function installLogDir() {
+  return machinePath('logs');
+}
+
+export function writeInstallLog(attempts, loadErrors = []) {
+  try {
+    const dir = installLogDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const path = join(dir, `terminal-install-${new Date().toISOString().replace(/[:.]/g, '-')}.log`);
+    const body = [
+      `node ${process.version} (abi ${process.versions.modules}) ${process.platform}-${process.arch}`,
+      `prefix ${nativeRoot()}`,
+      '',
+      ...attempts.map((a) => [`$ npm ${a.args?.join(' ') ?? ''}`, `# attempt: ${a.label} → exit ${a.code}`, a.output].join('\n')),
+      loadErrors.length ? `\n# load errors\n${loadErrors.map((e) => `${e.source}: ${e.code}: ${e.message}`).join('\n')}` : '',
+    ].join('\n');
+    writeFileSync(path, `${body}\n`);
+    return path;
+  } catch {
+    return null;
+  }
+}
+
+export function renderProbe(probe) {
+  const mark = (ok) => (ok ? '✓' : '✗');
+  const { python, compiler } = probe;
+  return [
+    `${mark(true)} node          ${probe.node.version} (abi ${probe.node.abi})`,
+    `${mark(Boolean(compiler.cc))} C compiler    ${compiler.cc ?? 'not found on PATH'}`,
+    `${mark(Boolean(compiler.make))} make          ${compiler.make ?? 'not found on PATH'}`,
+    `${mark(python.supported)} python        ${
+      python.version ? `${python.path} (${python.version.raw})` : (python.path ?? 'not found on PATH')
+    }${!python.supported && python.version ? `  — outside node-gyp's known-good 3.${PYTHON_KNOWN_GOOD.min}–3.${PYTHON_KNOWN_GOOD.max}` : ''}`,
+    ...(python.alternative ? [`  alternative   ${python.alternative.path} (${python.alternative.version.raw})`] : []),
+    `  prefix        ${probe.prefix}`,
+  ];
+}

package/bin/pty-locator.js

@@ -0,0 +1,110 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+
+
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { MACHINE_LAYOUT, machineRoot } from './machine-layout.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const CLI_ROOT = resolve(__dirname, '..');
+
+export const PREBUILT_PACKAGE = '@lydell/node-pty';
+
+export const PREBUILT_PLATFORM_PACKAGE = `${PREBUILT_PACKAGE}-${process.platform}-${process.arch}`;
+
+export const NATIVE_ABI_KEY = `node-${process.versions.modules}-${process.platform}-${process.arch}`;
+
+export function nativeRoot() {
+  return join(machineRoot(), MACHINE_LAYOUT.native, 'node-pty', NATIVE_ABI_KEY);
+}
+
+export function nativeModulesDir() {
+  return join(nativeRoot(), 'node_modules');
+}
+
+
+const cliRequire = () => createRequire(join(CLI_ROOT, 'package.json'));
+
+export function loadSources() {
+  return [
+    {
+      id: 'prebuilt',
+      describe: 'the prebuilt binary bundled with the CLI',
+      resolve: () => cliRequire().resolve(PREBUILT_PACKAGE),
+    },
+    {
+      id: 'bundled',
+      describe: "node-pty compiled in the CLI's own tree",
+      resolve: () => cliRequire().resolve('node-pty'),
+    },
+    {
+      id: 'prefix',
+      describe: 'node-pty compiled by "minion install terminal"',
+      resolve: () => createRequire(join(nativeRoot(), 'package.json')).resolve(join(nativeModulesDir(), 'node-pty')),
+    },
+  ];
+}
+
+export function describeSource(id) {
+  return loadSources().find((s) => s.id === id)?.describe ?? id;
+}
+
+function describeError(error) {
+  const own = typeof error?.code === 'string' ? error.code : null;
+  const cause = typeof error?.cause?.code === 'string' ? error.cause.code : null;
+  return {
+    code: own ?? cause ?? 'UNKNOWN',
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+function loadSource(source) {
+  try {
+    const resolved = source.resolve();
+    const req = createRequire(resolved);
+    delete req.cache[resolved];
+    const mod = req(resolved);
+    if (typeof mod?.spawn !== 'function') {
+      throw Object.assign(new Error('node-pty loaded but exports no spawn() — the native binding did not attach'), {
+        code: 'ERR_INVALID_MODULE',
+      });
+    }
+    return { ok: true, module: mod, source: source.id, path: resolved };
+  } catch (error) {
+    return { ok: false, error: { source: source.id, ...describeError(error) } };
+  }
+}
+
+export function loadNodePty() {
+  const errors = [];
+  for (const source of loadSources()) {
+    const result = loadSource(source);
+    if (result.ok) return result;
+    errors.push(result.error);
+  }
+  return { ok: false, errors };
+}
+
+export function loadNodePtySource(id) {
+  const source = loadSources().find((s) => s.id === id);
+  if (!source) {
+    return { ok: false, errors: [{ source: id, code: 'UNKNOWN_SOURCE', message: `no node-pty source "${id}"` }] };
+  }
+  const result = loadSource(source);
+  return result.ok ? result : { ok: false, errors: [result.error] };
+}
+
+export function isNodePtyLoadable() {
+  return loadNodePty().ok;
+}
+
+export function prebuiltPlatformDir() {
+  try {
+    return dirname(cliRequire().resolve(`${PREBUILT_PLATFORM_PACKAGE}/package.json`));
+  } catch {
+    return null;
+  }
+}

package/bin/pty-provision.js

@@ -0,0 +1,186 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+
+
+import { spawn } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CLI_ROOT, loadNodePtySource, NATIVE_ABI_KEY, nativeRoot } from './pty-locator.js';
+
+const DEFAULT_PTY_SPEC = '^1.1.0';
+
+export function nodePtySpec() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(CLI_ROOT, 'package.json'), 'utf-8'));
+    return (
+      pkg.devDependencies?.['node-pty'] ||
+      pkg.dependencies?.['node-pty'] ||
+      pkg.optionalDependencies?.['node-pty'] ||
+      DEFAULT_PTY_SPEC
+    );
+  } catch {
+    return DEFAULT_PTY_SPEC;
+  }
+}
+
+export function ensureNativeRoot() {
+  const root = nativeRoot();
+  mkdirSync(root, { recursive: true });
+
+  const manifest = join(root, 'package.json');
+  if (!existsSync(manifest)) {
+    writeFileSync(
+      manifest,
+      `${JSON.stringify(
+        {
+          name: 'minionry-native-node-pty',
+          version: '1.0.0',
+          private: true,
+          description: `node-pty compiled for ${NATIVE_ABI_KEY}. Managed by "minion install terminal" — safe to delete.`,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  }
+  return root;
+}
+
+export function nodePtyDirIn(root) {
+  return join(root, 'node_modules', 'node-pty');
+}
+
+export function normalizeNodePtyTree(dir) {
+  if (!dir || !existsSync(dir)) return;
+
+  const prebuilds = join(dir, 'prebuilds');
+  const keep = `${process.platform}-${process.arch}`;
+  pruneForeignPrebuilds(prebuilds, keep);
+
+  if (process.platform === 'win32') return;
+  for (const helper of [
+    join(prebuilds, keep, 'spawn-helper'),
+    join(dir, 'build', 'Release', 'spawn-helper'),
+    join(dir, 'spawn-helper'),
+  ]) {
+    restoreExecBit(helper);
+  }
+}
+
+function pruneForeignPrebuilds(prebuilds, keep) {
+  let entries = [];
+  try {
+    entries = readdirSync(prebuilds);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry === keep) continue;
+    try {
+      rmSync(join(prebuilds, entry), { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
+
+function restoreExecBit(path) {
+  if (!existsSync(path)) return;
+  try {
+    chmodSync(path, 0o755);
+  } catch {
+  }
+}
+
+export function provisionEnv(env = process.env) {
+  const clean = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key.startsWith('npm_') || key === 'INIT_CWD' || key === 'NODE_ENV') continue;
+    clean[key] = value;
+  }
+  clean.npm_config_update_notifier = 'false';
+  return clean;
+}
+
+const PUBLIC_REGISTRY = 'https://registry.npmjs.org';
+
+const REGISTRY_FAILURE = /E404|ETARGET|E401|E403|ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ERR_INVALID_URL|404 Not Found/i;
+
+export function planAttempts(spec, probe) {
+  const base = [
+    'install',
+    `node-pty@${spec}`,
+    '--prefix',
+    nativeRoot(),
+    '--no-audit',
+    '--no-fund',
+    '--no-package-lock',
+    '--omit=dev',
+    '--foreground-scripts',
+    '--loglevel=error',
+  ];
+
+  const attempts = [];
+
+  if (probe?.python?.supported === false && probe?.python?.alternative) {
+    attempts.push({
+      label: `using ${probe.python.alternative.path}`,
+      args: [...base, `--python=${probe.python.alternative.path}`],
+    });
+  }
+
+  attempts.push({ label: 'default registry', args: base });
+  attempts.push({
+    label: 'public npm registry',
+    args: [...base, `--registry=${PUBLIC_REGISTRY}`],
+    onlyIf: (previous) => previous.some((a) => REGISTRY_FAILURE.test(a.output)),
+  });
+
+  return attempts;
+}
+
+function runNpm(args, cwd) {
+  return new Promise((resolveRun) => {
+    const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    let output = '';
+
+    const child = spawn(npmCmd, args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: provisionEnv(),
+    });
+
+    child.stdout?.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    child.stderr?.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    child.on('error', (err) => resolveRun({ code: -1, output: `${output}\n${err.message}` }));
+    child.on('exit', (code) => resolveRun({ code: code ?? -1, output }));
+  });
+}
+
+export async function provisionNodePty(options = {}) {
+  const spec = options.spec ?? nodePtySpec();
+  const root = ensureNativeRoot();
+  const attempts = [];
+
+  const stale = nodePtyDirIn(root);
+  if (existsSync(stale) && !loadNodePtySource('prefix').ok) {
+    rmSync(stale, { recursive: true, force: true });
+  }
+
+  for (const attempt of planAttempts(spec, options.probe)) {
+    if (attempt.onlyIf && !attempt.onlyIf(attempts)) continue;
+
+    options.onProgress?.(attempt.label);
+    const { code, output } = await runNpm(attempt.args, root);
+    attempts.push({ label: attempt.label, args: attempt.args, code, output });
+
+    normalizeNodePtyTree(nodePtyDirIn(root));
+    const loaded = loadNodePtySource('prefix');
+    if (loaded.ok) return { ok: true, source: loaded.source, path: loaded.path, attempts };
+  }
+
+  return { ok: false, attempts };
+}