@happier-dev/stack 0.2.1-preview.1775586714.26562 → 0.2.11

package/node_modules/@happier-dev/cli-common/dist/providers/install.js

@@ -1,9 +1,12 @@
 import { spawnSync } from 'node:child_process';
-import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from 'node:fs';
-import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
-import { delimiter, dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmod, copyFile, mkdir, readFile, readdir, rename, rm, stat, symlink, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { basename, delimiter, dirname, join, relative } from 'node:path';
 import { getProviderCliRuntimeSpec } from '@happier-dev/agents';
 import { fetchGitHubLatestRelease } from '@happier-dev/release-runtime';
+import { withWorkspaceBundleLock } from '../../workspaceBundleLock.mjs';
 import { commandExistsOnPath, resolveWindowsCommandInvocation } from '../process/index.js';
 import { createManagedToolScratchDir } from './createManagedToolScratchDir.js';
 import { downloadGitHubReleaseAsset } from './downloadGitHubReleaseAsset.js';
@@ -11,7 +14,138 @@ import { extractGitHubReleaseAsset } from './extractGitHubReleaseAsset.js';
 import { ensureManagedJavaScriptRuntimeCommand, readExplicitJavaScriptRuntimeCommand, resolveJavaScriptRuntimePathEntries, } from './managedJavaScriptRuntime.js';
 import { buildManagedPnpmEnvironment, ensureManagedPnpmCommand, readRawPnpmOverride } from './managedPnpm.js';
 import { resolveHappyHomeDirFromEnvironment } from './resolveHappyHomeDir.js';
-import { resolveProviderCliCommand, resolveProviderCliManagedCommandPath } from './resolution.js';
+import { resolveProviderCliCommand, resolveProviderCliManagedCommandRelativePath, } from './resolution.js';
+const MANAGED_RETIRED_INSTALL_DIRECTORY_PATTERN = /^previous-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MANAGED_VERSIONED_RELEASE_DIRECTORY_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function managedInstallPathExists(path) {
+    return await stat(path)
+        .then(() => true)
+        .catch(() => false);
+}
+async function cleanupRetiredManagedInstallDirectories(params) {
+    const entries = await readdir(params.installRoot, { withFileTypes: true }).catch((error) => {
+        appendInstallLogBestEffort(params.logPath, `# retired release cleanup scan deferred: ${String(error)}`);
+        return [];
+    });
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !MANAGED_RETIRED_INSTALL_DIRECTORY_PATTERN.test(entry.name))
+            continue;
+        const retiredPath = join(params.installRoot, entry.name);
+        try {
+            await params.removePath(retiredPath, { recursive: true, force: true });
+        }
+        catch (error) {
+            appendInstallLogBestEffort(params.logPath, `# retired release cleanup deferred: ${String(error)}`);
+        }
+    }
+}
+async function cleanupRetiredManagedVersionedReleases(params) {
+    const entries = await readdir(params.releasesDir, { withFileTypes: true }).catch((error) => {
+        appendInstallLogBestEffort(params.logPath, `# retired managed release cleanup scan deferred: ${String(error)}`);
+        return [];
+    });
+    const activeReleaseName = basename(params.activeReleaseDir);
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === activeReleaseName || !MANAGED_VERSIONED_RELEASE_DIRECTORY_PATTERN.test(entry.name))
+            continue;
+        const retiredPath = join(params.releasesDir, entry.name);
+        try {
+            await params.removePath(retiredPath, { recursive: true, force: true });
+        }
+        catch (error) {
+            appendInstallLogBestEffort(params.logPath, `# retired managed release cleanup deferred: ${String(error)}`);
+        }
+    }
+}
+async function promoteVersionedManagedInstallCandidate(params) {
+    const releasesDir = join(params.installRoot, '.releases');
+    const activePath = join(params.installRoot, 'active');
+    const releaseName = randomUUID();
+    const activeReleaseDir = join(releasesDir, releaseName);
+    const pendingActivePath = join(params.installRoot, `.active-${releaseName}`);
+    await mkdir(releasesDir, { recursive: true });
+    await params.renamePath(params.candidateDir, activeReleaseDir);
+    try {
+        // POSIX can atomically replace this symlink, so every new launch resolves a complete release.
+        await symlink(relative(params.installRoot, activeReleaseDir), pendingActivePath);
+        await params.renamePath(pendingActivePath, activePath);
+    }
+    catch (error) {
+        await params.removePath(pendingActivePath, { force: true });
+        await params.removePath(activeReleaseDir, { recursive: true, force: true });
+        throw error;
+    }
+    await cleanupRetiredManagedVersionedReleases({
+        releasesDir,
+        activeReleaseDir,
+        logPath: params.logPath,
+        removePath: params.removePath,
+    });
+}
+async function promoteManagedInstallCandidate(params) {
+    const currentDir = join(params.installRoot, 'current');
+    const previousDir = join(params.installRoot, `previous-${randomUUID()}`);
+    const activePath = join(params.installRoot, 'active');
+    const removePath = params.deps.removeManagedInstallPath ?? rm;
+    const renamePath = params.deps.renameManagedInstallPath ?? rename;
+    await mkdir(params.installRoot, { recursive: true });
+    let waitReported = false;
+    await withWorkspaceBundleLock(async () => {
+        if (params.activateVersionedRelease
+            && process.platform !== 'win32'
+            && (await managedInstallPathExists(currentDir) || await managedInstallPathExists(activePath))) {
+            await promoteVersionedManagedInstallCandidate({
+                installRoot: params.installRoot,
+                candidateDir: params.candidateDir,
+                logPath: params.logPath,
+                removePath,
+                renamePath,
+            });
+            return;
+        }
+        let previousReleaseMoved = false;
+        try {
+            await renamePath(currentDir, previousDir);
+            previousReleaseMoved = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        try {
+            await renamePath(params.candidateDir, currentDir);
+        }
+        catch (promotionError) {
+            await removePath(currentDir, { recursive: true, force: true });
+            if (previousReleaseMoved) {
+                try {
+                    await renamePath(previousDir, currentDir);
+                }
+                catch (restoreError) {
+                    throw new Error(`Managed provider promotion failed and the previous release could not be restored: ${String(restoreError)}`, { cause: promotionError });
+                }
+            }
+            await removePath(params.candidateDir, { recursive: true, force: true });
+            throw promotionError;
+        }
+        await cleanupRetiredManagedInstallDirectories({
+            installRoot: params.installRoot,
+            logPath: params.logPath,
+            removePath,
+        });
+    }, {
+        lockPath: join(params.installRoot, '.lock', 'install.lock'),
+        timeoutMs: 60_000,
+        staleAfterMs: 60_000,
+        errorLabel: 'managed provider install lock',
+        onWait: ({ waitedMs }) => {
+            if (waitReported)
+                return;
+            waitReported = true;
+            appendInstallLogBestEffort(params.logPath, `# waiting for managed provider install lock after ${waitedMs}ms`);
+        },
+    });
+}
 export function resolvePlatformFromNodePlatform(nodePlatform) {
     if (nodePlatform === 'darwin')
         return 'darwin';
@@ -102,11 +236,12 @@ function writeLogHeader(logPath, plan) {
         // best-effort
     }
 }
-function appendCommandLog(logPath, cmd, args, stdout, stderr, status) {
+function appendCommandLog(logPath, cmd, args, stdout, stderr, status, signal) {
     appendFileSync(logPath, [
         '',
         `## ${cmd} ${args.join(' ')}`.trim(),
         `# exit: ${status ?? 'null'}`,
+        `# signal: ${signal ?? 'null'}`,
         '',
         '### stdout',
         stdout || '',
@@ -116,9 +251,33 @@ function appendCommandLog(logPath, cmd, args, stdout, stderr, status) {
         '',
     ].join('\n'), 'utf8');
 }
+function resolveVendorRecipeFailureMessage(params) {
+    const stderr = params.stderr.trim();
+    if (params.status === 137 || params.signal === 'SIGKILL') {
+        return [
+            `Vendor install was killed while running ${params.cmd}; this often means the machine ran out of memory.`,
+            'Please increase available memory or swap and retry.',
+            stderr ? `Installer output: ${stderr}` : null,
+        ].filter(Boolean).join(' ');
+    }
+    return stderr || `Command failed (${params.status ?? 'unknown'}): ${params.cmd}`;
+}
 function appendLogLine(logPath, line) {
     appendFileSync(logPath, `${line}\n`, 'utf8');
 }
+function appendInstallLogBestEffort(logPath, line) {
+    try {
+        appendLogLine(logPath, line);
+    }
+    catch (logError) {
+        try {
+            console.warn(`[provider-install] ${line} (install log unavailable: ${String(logError)})`);
+        }
+        catch {
+            // Reporting must never replace the install outcome.
+        }
+    }
+}
 function resolveProviderToolInstallDir(providerId, env) {
     return join(resolveHappyHomeDirFromEnvironment(env), 'tools', 'providers', providerId);
 }
@@ -162,20 +321,27 @@ function resolveVendorInstallTimeoutMs(env) {
         return 180_000;
     return Math.min(parsed, 900_000);
 }
-function resolveStagedManagedProviderCommandPath(providerId, stage, env) {
-    const currentPath = resolveProviderCliManagedCommandPath(providerId, {
-        happyHomeDir: resolveHappyHomeDirFromEnvironment(env),
-        processEnv: env,
-    });
-    const currentSegment = join('current', 'bin');
-    const targetSegment = join(stage, 'bin');
-    if (!currentPath.includes(currentSegment)) {
-        throw new Error(`Managed provider path missing ${currentSegment}: ${currentPath}`);
-    }
-    return currentPath.replace(currentSegment, targetSegment);
+function resolveManagedProviderCommandPathInInstallDir(providerId, installDir, env) {
+    return join(installDir, resolveProviderCliManagedCommandRelativePath(providerId));
 }
-function resolveStagedManagedProviderWorkspaceDir(providerId, stage, env) {
-    return join(dirname(resolveStagedManagedProviderCommandPath(providerId, stage, env)), '..', 'workspace');
+function buildManagedPackageInstallEnvironment(env, workspaceDir) {
+    const childEnv = buildManagedPnpmEnvironment(env);
+    delete childEnv.INIT_CWD;
+    delete childEnv.npm_command;
+    delete childEnv.npm_config_user_agent;
+    delete childEnv.npm_execpath;
+    delete childEnv.npm_lifecycle_event;
+    delete childEnv.npm_lifecycle_script;
+    delete childEnv.npm_node_execpath;
+    delete childEnv.npm_package_json;
+    delete childEnv.npm_package_manager;
+    for (const key of Object.keys(childEnv)) {
+        if (key.startsWith('npm_package_') || key.startsWith('YARN_')) {
+            delete childEnv[key];
+        }
+    }
+    childEnv.PWD = workspaceDir;
+    return childEnv;
 }
 async function writeManagedPackageLauncher(params) {
     await mkdir(dirname(params.outputPath), { recursive: true });
@@ -184,12 +350,189 @@ async function writeManagedPackageLauncher(params) {
         ? `${runtimePathEntries.join(process.platform === 'win32' ? ';' : ':')}${process.platform === 'win32' ? ';' : ':'}`
         : '';
     if (process.platform === 'win32') {
-        await writeFile(params.outputPath, `@echo off\r\nset "PATH=${pathPrefix}%PATH%"\r\n"${params.pnpmCommand}" --dir "${params.workspaceDir}" exec "${params.binaryName}" %*\r\n`, 'utf8');
+        const binaryPath = join(params.workspaceDir, 'node_modules', '.bin', `${params.binaryName}.cmd`);
+        await writeFile(params.outputPath, `@echo off\r\nset "PATH=${pathPrefix}%PATH%"\r\n"${binaryPath}" %*\r\nexit /b %ERRORLEVEL%\r\n`, 'utf8');
         return;
     }
-    await writeFile(params.outputPath, `#!/bin/sh\nPATH="${pathPrefix}$PATH"\nexport PATH\nexec "${params.pnpmCommand}" --dir "${params.workspaceDir}" exec "${params.binaryName}" "$@"\n`, 'utf8');
+    const binaryPath = join(params.workspaceDir, 'node_modules', '.bin', params.binaryName);
+    await writeFile(params.outputPath, `#!/bin/sh\nPATH="${pathPrefix}$PATH"\nexport PATH\nexec "${binaryPath}" "$@"\n`, 'utf8');
     await chmod(params.outputPath, 0o755);
 }
+function resolveOpenCodePlatformName(platform) {
+    return platform === 'win32' ? 'windows' : platform;
+}
+function resolveOpenCodeArchName(arch) {
+    if (arch === 'x64' || arch === 'arm64' || arch === 'arm')
+        return arch;
+    return arch;
+}
+function hasOpenCodeLinuxMuslRuntime() {
+    if (process.platform !== 'linux')
+        return false;
+    try {
+        return existsSync('/etc/alpine-release');
+    }
+    catch {
+        // Ignore filesystem probes that are blocked by the host.
+    }
+    try {
+        const result = spawnSync('ldd', ['--version'], { encoding: 'utf8' });
+        return `${result.stdout || ''}${result.stderr || ''}`.toLowerCase().includes('musl');
+    }
+    catch {
+        return false;
+    }
+}
+function supportsOpenCodeAvx2(params) {
+    if (params.arch !== 'x64')
+        return false;
+    if (params.platform === 'linux') {
+        try {
+            const cpuinfo = readFileSync('/proc/cpuinfo', 'utf8');
+            return /(^|\s)avx2(\s|$)/i.test(cpuinfo);
+        }
+        catch {
+            return false;
+        }
+    }
+    if (params.platform === 'darwin') {
+        try {
+            const result = params.spawn('sysctl', ['-n', 'hw.optional.avx2_0'], {
+                encoding: 'utf8',
+                env: params.env,
+                timeout: 1500,
+            });
+            if (result.status !== 0)
+                return false;
+            return String(result.stdout ?? '').trim() === '1';
+        }
+        catch {
+            return false;
+        }
+    }
+    if (params.platform === 'win32') {
+        const command = '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)';
+        for (const executable of ['powershell.exe', 'pwsh.exe', 'pwsh', 'powershell']) {
+            try {
+                const result = params.spawn(executable, ['-NoProfile', '-NonInteractive', '-Command', command], {
+                    encoding: 'utf8',
+                    env: params.env,
+                    timeout: 3000,
+                    windowsHide: true,
+                });
+                if (result.status !== 0)
+                    continue;
+                const output = String(result.stdout ?? '').trim().toLowerCase();
+                if (output === 'true' || output === '1')
+                    return true;
+                if (output === 'false' || output === '0')
+                    return false;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return false;
+}
+function resolveOpenCodePlatformPackageCandidates(params) {
+    const platform = resolveOpenCodePlatformName(params.platform);
+    const arch = resolveOpenCodeArchName(params.arch);
+    const base = `opencode-${platform}-${arch}`;
+    const baseline = arch === 'x64' && !supportsOpenCodeAvx2(params);
+    if (platform === 'linux') {
+        if (hasOpenCodeLinuxMuslRuntime()) {
+            if (arch === 'x64') {
+                return baseline
+                    ? [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+                    : [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`];
+            }
+            return [`${base}-musl`, base];
+        }
+        if (arch === 'x64') {
+            return baseline
+                ? [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+                : [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`];
+        }
+        return [base, `${base}-musl`];
+    }
+    if (arch === 'x64')
+        return baseline ? [`${base}-baseline`, base] : [base, `${base}-baseline`];
+    return [base];
+}
+function readOptionalDependencyNames(packageJson) {
+    if (!packageJson || typeof packageJson !== 'object' || Array.isArray(packageJson))
+        return new Set();
+    const optionalDependencies = packageJson.optionalDependencies;
+    if (!optionalDependencies || typeof optionalDependencies !== 'object' || Array.isArray(optionalDependencies)) {
+        return new Set();
+    }
+    return new Set(Object.keys(optionalDependencies));
+}
+async function resolvePnpmPackageJsonPaths(params) {
+    const pnpmDir = join(params.workspaceDir, 'node_modules', '.pnpm');
+    const encodedName = params.packageName.replace('/', '+');
+    const prefix = `${encodedName}@`;
+    try {
+        const entries = await readdir(pnpmDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith(prefix))
+            .map((entry) => join(pnpmDir, entry.name, 'node_modules', params.packageName, 'package.json'));
+    }
+    catch {
+        return [];
+    }
+}
+async function resolvePackageJsonPaths(params) {
+    const paths = [];
+    const requireFromOpenCode = createRequire(params.packageJsonPath);
+    const requireFromWorkspace = createRequire(join(params.workspaceDir, 'package.json'));
+    for (const requireFrom of [requireFromOpenCode, requireFromWorkspace]) {
+        try {
+            paths.push(requireFrom.resolve(`${params.packageName}/package.json`));
+        }
+        catch {
+            // Fall back to package-manager-specific layouts below.
+        }
+    }
+    paths.push(...await resolvePnpmPackageJsonPaths({
+        workspaceDir: params.workspaceDir,
+        packageName: params.packageName,
+    }));
+    return [...new Set(paths)];
+}
+async function materializeOpenCodeManagedPackageBinary(params) {
+    const packageDir = join(params.workspaceDir, 'node_modules', 'opencode-ai');
+    const packageJsonPath = join(packageDir, 'package.json');
+    const rawPackageJson = await readFile(packageJsonPath, 'utf8');
+    const optionalDependencyNames = readOptionalDependencyNames(JSON.parse(rawPackageJson));
+    const sourceBinary = params.platform === 'win32' ? 'opencode.exe' : 'opencode';
+    const targetBinary = join(packageDir, 'bin', 'opencode.exe');
+    const candidates = resolveOpenCodePlatformPackageCandidates({
+        platform: params.platform,
+        arch: process.arch,
+        env: params.env,
+        spawn: params.spawnSync,
+    }).filter((packageName) => optionalDependencyNames.has(packageName));
+    for (const packageName of candidates) {
+        for (const platformPackageJsonPath of await resolvePackageJsonPaths({
+            workspaceDir: params.workspaceDir,
+            packageName,
+            packageJsonPath,
+        })) {
+            try {
+                const sourceBinaryPath = join(dirname(platformPackageJsonPath), 'bin', sourceBinary);
+                await copyFile(sourceBinaryPath, targetBinary);
+                await chmod(targetBinary, 0o755);
+                return { packageName };
+            }
+            catch {
+                // Try the next installed location for this platform package.
+            }
+        }
+    }
+    throw new Error(`OpenCode managed install did not include a usable platform binary package for ${params.platform}/${process.arch}.`);
+}
 async function installManagedPackageProviderCli(params) {
     const pnpmCommand = await (params.deps.ensureManagedPnpmCommand ?? ensureManagedPnpmCommand)(params.env);
     if (!pnpmCommand) {
@@ -208,47 +551,67 @@ async function installManagedPackageProviderCli(params) {
         throw new Error('Managed JavaScript runtime is unavailable');
     }
     const installRoot = resolveManagedProviderInstallDir(params.providerId, params.env);
-    const nextDir = join(installRoot, 'next');
-    const workspaceDir = join(nextDir, 'workspace');
-    const launcherPath = resolveStagedManagedProviderCommandPath(params.providerId, 'next', params.env);
-    const launcherWorkspaceDir = resolveStagedManagedProviderWorkspaceDir(params.providerId, 'current', params.env);
-    const runtimePathEntries = resolveJavaScriptRuntimePathEntries({
-        processEnv: params.env,
-        runtimeCommand: jsRuntimeCommand,
-    });
-    await rm(nextDir, { recursive: true, force: true });
-    await mkdir(workspaceDir, { recursive: true });
-    await writeFile(join(workspaceDir, 'package.json'), JSON.stringify({ name: `happier-provider-${params.providerId}`, private: true, version: '0.0.0' }, null, 2), 'utf8');
-    const childEnv = buildManagedPnpmEnvironment(params.env);
-    if (runtimePathEntries.length > 0) {
-        childEnv.PATH = [...runtimePathEntries, String(childEnv.PATH ?? params.env.PATH ?? '')]
-            .filter((value) => value.length > 0)
-            .join(delimiter);
-    }
-    const addArgs = ['--dir', workspaceDir, 'add', params.managedInstall.packageName];
-    const spawn = params.deps.spawnSync ?? spawnSync;
-    const result = spawn(pnpmCommand, addArgs, {
-        encoding: 'utf8',
-        env: childEnv,
-        windowsHide: true,
-    });
-    appendCommandLog(params.logPath, pnpmCommand, addArgs, String(result.stdout ?? ''), String(result.stderr ?? ''), result.status ?? null);
-    if (result.error) {
-        throw result.error;
-    }
-    if ((result.status ?? 1) !== 0) {
-        throw new Error(String(result.stderr ?? '').trim() || `pnpm add failed (${result.status ?? 'unknown'})`);
-    }
-    await writeManagedPackageLauncher({
-        outputPath: launcherPath,
-        pnpmCommand,
-        workspaceDir: launcherWorkspaceDir,
-        binaryName: params.managedInstall.binaryName,
-        runtimePathEntries,
+    const scratchDir = await createManagedToolScratchDir({
+        installDir: installRoot,
+        prefix: params.providerId,
     });
-    await rm(join(installRoot, 'current'), { recursive: true, force: true });
-    await mkdir(installRoot, { recursive: true });
-    await rename(nextDir, join(installRoot, 'current'));
+    try {
+        const candidateDir = join(scratchDir, 'candidate');
+        const workspaceDir = join(candidateDir, 'workspace');
+        const launcherPath = resolveManagedProviderCommandPathInInstallDir(params.providerId, candidateDir, params.env);
+        const launcherWorkspaceDir = join(installRoot, 'current', 'workspace');
+        const runtimePathEntries = resolveJavaScriptRuntimePathEntries({
+            processEnv: params.env,
+            runtimeCommand: jsRuntimeCommand,
+        });
+        await mkdir(workspaceDir, { recursive: true });
+        await writeFile(join(workspaceDir, 'package.json'), JSON.stringify({ name: `happier-provider-${params.providerId}`, private: true, version: '0.0.0' }, null, 2), 'utf8');
+        const childEnv = buildManagedPackageInstallEnvironment(params.env, workspaceDir);
+        if (runtimePathEntries.length > 0) {
+            childEnv.PATH = [...runtimePathEntries, String(childEnv.PATH ?? params.env.PATH ?? '')]
+                .filter((value) => value.length > 0)
+                .join(delimiter);
+        }
+        const addArgs = ['--dir', workspaceDir, 'add', params.managedInstall.packageName, '--ignore-scripts'];
+        const spawn = params.deps.spawnSync ?? spawnSync;
+        const result = spawn(pnpmCommand, addArgs, {
+            cwd: workspaceDir,
+            encoding: 'utf8',
+            env: childEnv,
+            windowsHide: true,
+        });
+        appendCommandLog(params.logPath, pnpmCommand, addArgs, String(result.stdout ?? ''), String(result.stderr ?? ''), result.status ?? null, result.signal ?? null);
+        if (result.error) {
+            throw result.error;
+        }
+        if ((result.status ?? 1) !== 0) {
+            throw new Error(String(result.stderr ?? '').trim() || `pnpm add failed (${result.status ?? 'unknown'})`);
+        }
+        if (params.managedInstall.packageBinarySetup?.kind === 'opencode_platform_binary') {
+            const materialized = await materializeOpenCodeManagedPackageBinary({
+                workspaceDir,
+                platform: params.platform,
+                env: childEnv,
+                spawnSync: spawn,
+            });
+            appendLogLine(params.logPath, `# opencode platform package: ${materialized.packageName}`);
+        }
+        await writeManagedPackageLauncher({
+            outputPath: launcherPath,
+            workspaceDir: launcherWorkspaceDir,
+            binaryName: params.managedInstall.binaryName,
+            runtimePathEntries,
+        });
+        await promoteManagedInstallCandidate({
+            installRoot,
+            candidateDir,
+            logPath: params.logPath,
+            deps: params.deps,
+        });
+    }
+    finally {
+        await rm(scratchDir, { recursive: true, force: true });
+    }
 }
 async function resolveManagedBinaryAsset(params) {
     const release = await (params.deps.fetchGitHubLatestRelease ?? fetchGitHubLatestRelease)({
@@ -256,12 +619,94 @@ async function resolveManagedBinaryAsset(params) {
         userAgent: 'happier-cli',
         githubToken: params.env.GITHUB_TOKEN,
     });
-    if (params.providerId === 'codex') {
-        const { resolveCodexReleaseAsset } = await import('./codexRelease.js');
-        const asset = resolveCodexReleaseAsset(release);
-        return { name: asset.name, url: asset.url, digest: asset.digest };
+    const assets = normalizeGitHubReleaseAssets(release);
+    const declaredAssetName = params.managedInstall.assetNameByPlatform
+        ? params.managedInstall.assetNameByPlatform[params.platform][resolveManagedAssetArch(process.arch)]
+        : null;
+    const selected = (declaredAssetName
+        ? [declaredAssetName]
+        : preferredGitHubReleaseAssetNames({
+            binaryName: params.managedInstall.binaryName,
+            platform: params.platform,
+            arch: process.arch,
+        }))
+        .map((name) => assets.find((asset) => asset.name === name))
+        .find(Boolean);
+    if (!selected) {
+        throw new Error(`No ${params.managedInstall.binaryName} release asset found for ${params.platform}/${process.arch}`);
     }
-    throw new Error(`Unsupported managed github release provider: ${params.providerId}`);
+    if (!selected.digest)
+        throw new Error(`${selected.name} release asset is missing a required digest`);
+    return { name: selected.name, url: selected.browser_download_url, digest: selected.digest };
+}
+function normalizeGitHubReleaseAssets(release) {
+    const rawAssets = release && typeof release === 'object'
+        ? release.assets
+        : null;
+    if (!Array.isArray(rawAssets))
+        return [];
+    const assets = [];
+    for (const entry of rawAssets) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const name = typeof entry.name === 'string'
+            ? entry.name.trim()
+            : '';
+        const url = typeof entry.browser_download_url === 'string'
+            ? entry.browser_download_url.trim()
+            : '';
+        const digest = typeof entry.digest === 'string'
+            ? entry.digest.trim()
+            : null;
+        if (name && url)
+            assets.push({ name, browser_download_url: url, digest });
+    }
+    return assets;
+}
+function resolveManagedAssetArch(arch) {
+    if (arch === 'arm64' || arch === 'x64')
+        return arch;
+    throw new Error(`Unsupported managed GitHub release architecture: ${arch}`);
+}
+function preferredGitHubReleaseAssetNames(params) {
+    const { binaryName, platform, arch } = params;
+    if (platform === 'darwin' && arch === 'arm64') {
+        return [
+            `${binaryName}-darwin-arm64`, `${binaryName}-darwin-arm64.tar.gz`, `${binaryName}-darwin-arm64.tar.xz`,
+            `${binaryName}-darwin-arm64.zip`, `${binaryName}-aarch64-apple-darwin.tar.gz`,
+            `${binaryName}-aarch64-apple-darwin.tar.xz`, `${binaryName}-aarch64-apple-darwin.zip`,
+        ];
+    }
+    if (platform === 'darwin' && arch === 'x64') {
+        return [
+            `${binaryName}-darwin-x64`, `${binaryName}-darwin-x64.tar.gz`, `${binaryName}-darwin-x64.tar.xz`,
+            `${binaryName}-darwin-x64.zip`, `${binaryName}-x86_64-apple-darwin.tar.gz`,
+            `${binaryName}-x86_64-apple-darwin.tar.xz`, `${binaryName}-x86_64-apple-darwin.zip`,
+        ];
+    }
+    if (platform === 'linux' && arch === 'arm64') {
+        return [
+            `${binaryName}-linux-arm64`, `${binaryName}-linux-arm64.tar.gz`, `${binaryName}-linux-arm64.tar.xz`,
+            `${binaryName}-linux-arm64.zip`, `${binaryName}-aarch64-unknown-linux-musl.tar.gz`,
+            `${binaryName}-aarch64-unknown-linux-musl.tar.xz`, `${binaryName}-aarch64-unknown-linux-gnu.tar.gz`,
+            `${binaryName}-aarch64-unknown-linux-gnu.tar.xz`,
+        ];
+    }
+    if (platform === 'linux' && arch === 'x64') {
+        return [
+            `${binaryName}-linux-x64`, `${binaryName}-linux-x64.tar.gz`, `${binaryName}-linux-x64.tar.xz`,
+            `${binaryName}-linux-x64.zip`, `${binaryName}-x86_64-unknown-linux-musl.tar.gz`,
+            `${binaryName}-x86_64-unknown-linux-musl.tar.xz`, `${binaryName}-x86_64-unknown-linux-gnu.tar.gz`,
+            `${binaryName}-x86_64-unknown-linux-gnu.tar.xz`,
+        ];
+    }
+    if (platform === 'win32' && arch === 'arm64') {
+        return [`${binaryName}-windows-arm64.exe`, `${binaryName}-windows-arm64.zip`, `${binaryName}-aarch64-pc-windows-msvc.exe.zip`];
+    }
+    if (platform === 'win32' && arch === 'x64') {
+        return [`${binaryName}-windows-x64.exe`, `${binaryName}-windows-x64.zip`, `${binaryName}-x86_64-pc-windows-msvc.exe.zip`];
+    }
+    throw new Error(`Unsupported managed GitHub release platform: ${platform}/${arch}`);
 }
 async function installManagedBinaryProviderCli(params) {
     const installRoot = resolveManagedProviderInstallDir(params.providerId, params.env);
@@ -273,26 +718,47 @@ async function installManagedBinaryProviderCli(params) {
     try {
         const archivePath = join(scratchDir, asset.name);
         const extractDir = join(scratchDir, 'extract');
-        const nextDir = join(installRoot, 'next');
-        const nextBinPath = resolveStagedManagedProviderCommandPath(params.providerId, 'next', params.env);
+        const candidateDir = join(scratchDir, 'candidate');
+        const candidateBinPath = resolveManagedProviderCommandPathInInstallDir(params.providerId, candidateDir, params.env);
+        const archiveEntries = params.managedInstall.archiveEntriesByPlatform?.[params.platform];
+        if (params.managedInstall.archiveEntriesByPlatform && archiveEntries?.length === 0) {
+            throw new Error(`Provider ${params.providerId} has no declared runtime archive entries for ${params.platform}`);
+        }
         await (params.deps.downloadGitHubReleaseAsset ?? downloadGitHubReleaseAsset)({
             url: asset.url,
             destinationPath: archivePath,
             digest: asset.digest,
             userAgent: 'happier-cli',
         });
-        await rm(nextDir, { recursive: true, force: true });
-        await mkdir(dirname(nextBinPath), { recursive: true });
+        await mkdir(dirname(candidateBinPath), { recursive: true });
         await (params.deps.extractGitHubReleaseAsset ?? extractGitHubReleaseAsset)({
             archivePath,
             archiveName: asset.name,
             extractDir,
-            outputPath: nextBinPath,
+            outputPath: candidateBinPath,
+            outputDir: candidateDir,
+            archiveEntries,
+            archiveExtractionLimits: params.managedInstall.archiveExtractionLimits,
         });
+        for (const entry of archiveEntries ?? []) {
+            const installedPath = join(candidateDir, ...entry.destinationPath.split('/'));
+            const installedStat = await stat(installedPath).catch((error) => {
+                if (error.code === 'ENOENT')
+                    return null;
+                throw error;
+            });
+            if (!installedStat?.isFile()) {
+                throw new Error(`[github-release] required archive member was not staged: ${entry.archivePath}`);
+            }
+        }
         appendLogLine(params.logPath, `# asset: ${asset.name}`);
-        await rm(join(installRoot, 'current'), { recursive: true, force: true });
-        await mkdir(installRoot, { recursive: true });
-        await rename(nextDir, join(installRoot, 'current'));
+        await promoteManagedInstallCandidate({
+            installRoot,
+            candidateDir,
+            logPath: params.logPath,
+            deps: params.deps,
+            activateVersionedRelease: params.platform !== 'win32',
+        });
     }
     finally {
         await rm(scratchDir, { recursive: true, force: true });
@@ -368,7 +834,7 @@ export async function installProviderCli(params) {
                     windowsVerbatimArguments: invocation.windowsVerbatimArguments,
                 });
                 if (res.error) {
-                    appendCommandLog(logPath, c.cmd, c.args, '', res.error.message, res.status ?? null);
+                    appendCommandLog(logPath, c.cmd, c.args, '', res.error.message, res.status ?? null, res.signal ?? null);
                     if (res.error.code === 'ETIMEDOUT') {
                         appendLogLine(logPath, `# vendor recipe timed out after ${timeoutMs}ms`);
                         return {
@@ -382,18 +848,23 @@ export async function installProviderCli(params) {
                     return { ok: false, errorCode: 'command-exec-failed', errorMessage: res.error.message, plan, logPath };
                 }
                 const status = typeof res.status === 'number' ? res.status : null;
-                appendCommandLog(logPath, c.cmd, c.args, String(res.stdout ?? ''), String(res.stderr ?? ''), status);
+                const signal = res.signal ?? null;
+                appendCommandLog(logPath, c.cmd, c.args, String(res.stdout ?? ''), String(res.stderr ?? ''), status, signal);
                 if (status !== 0) {
                     const resolvedAfterFailure = resolveProviderCliCommand(params.providerId, { processEnv: childEnv });
                     if (resolvedAfterFailure) {
                         appendLogLine(logPath, `# vendor recipe exited ${status ?? 'unknown'} but ${params.providerId} became available at ${resolvedAfterFailure.command}`);
                         return { ok: true, plan, alreadyInstalled: false, logPath };
                     }
-                    const stderr = String(res.stderr ?? '').trim();
                     return {
                         ok: false,
                         errorCode: 'command-failed',
-                        errorMessage: stderr || `Command failed (${status ?? 'unknown'}): ${c.cmd}`,
+                        errorMessage: resolveVendorRecipeFailureMessage({
+                            cmd: c.cmd,
+                            status,
+                            signal,
+                            stderr: String(res.stderr ?? ''),
+                        }),
                         plan,
                         logPath,
                     };
@@ -405,6 +876,7 @@ export async function installProviderCli(params) {
             await installManagedPackageProviderCli({
                 providerId: params.providerId,
                 managedInstall: plan.managedInstall,
+                platform: params.platform,
                 env,
                 logPath,
                 deps,
@@ -415,6 +887,7 @@ export async function installProviderCli(params) {
             await installManagedBinaryProviderCli({
                 providerId: params.providerId,
                 managedInstall: plan.managedInstall,
+                platform: params.platform,
                 env,
                 logPath,
                 deps,
@@ -434,7 +907,7 @@ export async function installProviderCli(params) {
         const code = message.startsWith('Managed pnpm is unavailable') || message.startsWith('Managed JavaScript runtime is unavailable')
             ? 'managed-runtime-unavailable'
             : 'command-failed';
-        appendLogLine(logPath, message);
+        appendInstallLogBestEffort(logPath, message);
         return { ok: false, errorCode: code, errorMessage: message, plan, logPath };
     }
     finally {