@nimbus-sh/worker 0.1.3 → 0.1.5

package/README.md

@@ -67,7 +67,7 @@ export default createNimbusHandler({
 ```
 
 `wrangler.jsonc` (use `@nimbus-sh/config` to generate, or adapt
-`apps/dogfood/wrangler.jsonc`):
+`apps/hosted-demo/wrangler.jsonc`):
 
 ```jsonc
 {
@@ -246,7 +246,7 @@ export default createNimbusHandler({
 
 ## Required bindings
 
-Every binding is load-bearing — see `apps/dogfood/wrangler.jsonc` or
+Every binding is load-bearing — see `apps/hosted-demo/wrangler.jsonc` or
 `@nimbus-sh/config` for the canonical set:
 
 - `NIMBUS_SESSION` (Durable Object) — per-session SQLite state

package/dist/index.js

@@ -64,8 +64,8 @@ export function getCtxExports() {
     return _getCtxExports();
 }
 // Worker default export — a `createNimbusHandler()` instance running in
-// auto auth mode. The live demo and dogfood embedder are bit-identical
+// auto auth mode. The live demo and hosted-demo embedder are bit-identical
 // from here on; the only difference is `NIMBUS_LEGACY_PUBLIC=1` env var
-// (set on the live demo, unset for the dogfood) flipping auth.mode to
+// (set on the live demo, unset for the hosted-demo) flipping auth.mode to
 // 'legacy' inside the auto-resolver.
 export default createNimbusHandler();

package/dist/loaders/loader-pool.d.ts

@@ -50,6 +50,13 @@ export interface NimbusLoaderPoolOptions {
      * that don't need DO callbacks (e.g. a pure CPU compute pool).
      */
     omitSupervisor?: boolean;
+    /**
+     * Loader cache scope. Defaults to `session`, which bakes the owning DO id
+     * into the loader key so stateful facets cannot leak bindings or globals
+     * across sessions. Use `global` only for stateless compute modules that do
+     * not receive a Supervisor binding and do not retain user state.
+     */
+    cacheScope?: 'session' | 'global';
     /**
      * Override the `doId` baked into the auto-injected SUPERVISOR binding.
      * Default: `ctx.id.toString()` (the DO that constructs the pool).

package/dist/loaders/loader-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader-pool.d.ts","sourceRoot":"","sources":["../../src/loaders/loader-pool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loader-pool.d.ts","sourceRoot":"","sources":["../../src/loaders/loader-pool.ts"],"names":[],"mappings":"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"}

package/dist/loaders/loader-pool.js

@@ -109,7 +109,9 @@ export class NimbusLoaderPool {
         // Include preamble in the cache-bucket key so changes to bundled helpers
         // invalidate warm slots. Empty preamble → '0' suffix (stable).
         this.preambleHash = this.preamble ? hashSource(this.preamble) : '0';
-        this.doIdShort = ctx.id.toString().slice(0, 12);
+        this.doIdShort = opts?.cacheScope === 'global'
+            ? 'global'
+            : ctx.id.toString().slice(0, 12);
         // Materialise the wasm-modules table. Sanitise each name into a
         // valid JS identifier for the static import binding; key collisions
         // (e.g. 'esbuild.wasm' and 'esbuild_wasm' both sanitise to

package/dist/router/index.d.ts

@@ -29,7 +29,7 @@
  *   - Hooks let embedders observe lifecycle without forking the DO. They
  *     run alongside, never block (errors are caught + logged).
  *   - The default `createNimbusHandler()` (zero args) is the
- *     "ship-Nimbus-as-is" case — exactly what `apps/dogfood/` does.
+ *     "ship-Nimbus-as-is" case — exactly what `apps/hosted-demo/` does.
  */
 import { type NimbusSdkRouterConfig } from './remote-api.js';
 export type { NimbusConfig as NimbusSdkConfig, NimbusRemoteApiConfig, NimbusRuntimePolicy, NimbusSandboxProfile, NimbusSdkRouterConfig, } from './remote-api.js';

package/dist/router/index.js

@@ -29,7 +29,7 @@
  *   - Hooks let embedders observe lifecycle without forking the DO. They
  *     run alongside, never block (errors are caught + logged).
  *   - The default `createNimbusHandler()` (zero args) is the
- *     "ship-Nimbus-as-is" case — exactly what `apps/dogfood/` does.
+ *     "ship-Nimbus-as-is" case — exactly what `apps/hosted-demo/` does.
  */
 import { generateSessionId, isValidSessionId, } from '../_shared/session-id.js';
 import { parseSessionRoute, forwardToSession, renderInvalidSessionHtml, SESSION_ROUTE_PREFIX, LEGACY_PUBLIC_DO_SEGMENT, } from '../_shared/session-router.js';

package/dist/runtime/clang-runner.d.ts

@@ -19,8 +19,8 @@
  *              tiny .o = ~20 MiB.
  *
  * Sysroot subset extraction happens supervisor-side via a small ustar
- * parser. The full 9.3 MiB sysroot.tar is parsed once per compile;
- * only the files matching the role's prefix-allowlist are forwarded.
+ * parser. The full sysroot.tar is parsed once when the clang runtime
+ * warms for a session; compile/link calls reuse the filtered subsets.
  *
  * Dispatch stays direct: no sleeps, no caller-side retries, and no
  * catch-and-continue around loader failures.

package/dist/runtime/clang-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clang-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/clang-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;CAChB,GAAG,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAC7F,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,CAqShC;AAqZD,eAAO,MAAM,qBAAqB,imXA4UjC,CAAC"}
+{"version":3,"file":"clang-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/clang-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;CAChB,GAAG,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAC7F,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,CAyShC;AAgcD,eAAO,MAAM,qBAAqB,imXA4UjC,CAAC"}

package/dist/runtime/clang-runner.js

@@ -19,8 +19,8 @@
  *              tiny .o = ~20 MiB.
  *
  * Sysroot subset extraction happens supervisor-side via a small ustar
- * parser. The full 9.3 MiB sysroot.tar is parsed once per compile;
- * only the files matching the role's prefix-allowlist are forwarded.
+ * parser. The full sysroot.tar is parsed once when the clang runtime
+ * warms for a session; compile/link calls reuse the filtered subsets.
  *
  * Dispatch stays direct: no sleeps, no caller-side retries, and no
  * catch-and-continue around loader failures.
@@ -37,6 +37,7 @@ export function makeClangRunnerFactory(deps) {
         const lldVfsPath = findFile('bin/wasm-ld');
         const memfsVfsPath = findFile('share/clang/memfs.wasm');
         const sysrootVfsPath = findFile('share/clang/sysroot.tar');
+        let runtimePromise = null;
         return async function clangBinHandler(ctx) {
             const argv = ctx.args || [];
             const cwd = ctx.cwd || '/home/user';
@@ -66,8 +67,6 @@ export function makeClangRunnerFactory(deps) {
                 ctx.stderr.write(`${binName}: clang/wasm-ld missing from install\n`);
                 return 127;
             }
-            const memfsBytes = vfs.readFile(memfsVfsPath);
-            const sysrootBytes = vfs.readFile(sysrootVfsPath);
             // Parse argv: find input .c + output path.
             const parsed = parseUserArgv(argv);
             if (parsed.error) {
@@ -80,8 +79,6 @@ export function makeClangRunnerFactory(deps) {
                 ctx.stderr.write(`${binName}: direct wasm-ld invocation not yet wired (v1.2)\n`);
                 return 2;
             }
-            // Parse sysroot.tar ONCE on supervisor side.
-            const sysroot = parseUstar(sysrootBytes);
             // Validate all user-supplied source inputs exist in the user's
             // session VFS. Collect their bytes for memfs population.
             const userSourceFiles = {};
@@ -110,6 +107,24 @@ export function makeClangRunnerFactory(deps) {
                 ctx.stderr.write(`${binName}: no compilable / linkable inputs\n`);
                 return 1;
             }
+            let runtime;
+            try {
+                if (!runtimePromise) {
+                    runtimePromise = createClangFacetRuntime(facetMgr, {
+                        clangVfsPath,
+                        lldVfsPath,
+                        memfsVfsPath,
+                        sysrootVfsPath,
+                        vfs,
+                    });
+                }
+                runtime = await runtimePromise;
+            }
+            catch (e) {
+                runtimePromise = null;
+                ctx.stderr.write(`${binName}: clang runtime warm-up failed: ${e?.message || e}\n`);
+                return 1;
+            }
             // Walk the user's cwd to gather headers (.h/.hpp/.hxx/.inc/...)
             // and any sibling headers users typically expect to be visible
             // to #include "..." resolution. Real clang/gcc auto-search the
@@ -122,10 +137,8 @@ export function makeClangRunnerFactory(deps) {
             // are vastly under the cap.
             const userIncludeBundle = collectIncludeBundle(vfs, cwd.replace(/^\/+/, ''));
             // ── COMPILE PHASE ────────────────────────────────────────────
-            // Ship: clang.wasm + memfs.wasm + C-include subset of sysroot
-            // + user's source files + user's header bundle.
-            const compileSysroot = filterSysrootForCompile(sysroot);
-            const clangBytes = vfs.readFile(clangVfsPath);
+            // Reuse the warm clang/memfs pool and ship only the C-include
+            // subset plus user source/header files for this invocation.
             // Build -I flag list. We pass each user -I path verbatim AND add
             // an implicit '.' (cwd) for quote-form lookup. wasm-clang's -cc1
             // mode does NOT add cwd to the quote search list by default
@@ -170,12 +183,9 @@ export function makeClangRunnerFactory(deps) {
                 // so sibling sources stay out of memfs (smaller payload, no
                 // surface for unintended cross-TU textual inclusion via -I.).
                 const oneSourceFile = { [src]: userSourceFiles[src] };
-                const compileResult = await dispatchClangFacet(facetMgr, {
-                    primaryName: 'clang',
-                    primaryBytes: clangBytes,
-                    memfsBytes,
+                const compileResult = await dispatchClangFacet(runtime.compile, {
                     sysrootFiles: {
-                        ...compileSysroot,
+                        ...runtime.compile.sysrootFiles,
                         ...oneSourceFile,
                         // User's headers from cwd tree (so quote-form #include
                         // resolves; this is the primary clang-include-fix payload).
@@ -235,9 +245,8 @@ export function makeClangRunnerFactory(deps) {
                 preBuiltBytesMap[lp] = userSourceFiles[lp];
             }
             // ── LINK PHASE ───────────────────────────────────────────────
-            // Ship: lld.wasm + memfs.wasm + lib subset of sysroot + .o's.
-            const linkSysroot = filterSysrootForLink(sysroot);
-            const lldBytes = vfs.readFile(lldVfsPath);
+            // Reuse the warm wasm-ld/memfs pool and ship only the link
+            // sysroot subset plus object/archive inputs for this invocation.
             const stackSize = 1024 * 1024;
             // User-supplied -L paths and -l libraries flow through. The user
             // -L paths point at user-VFS dirs; we currently don't ship user
@@ -270,11 +279,8 @@ export function makeClangRunnerFactory(deps) {
                 '-lclang_rt.builtins-wasm32',
                 '-o', parsed.outputPath,
             ];
-            const linkResult = await dispatchClangFacet(facetMgr, {
-                primaryName: 'wasm-ld',
-                primaryBytes: lldBytes,
-                memfsBytes,
-                sysrootFiles: { ...linkSysroot, ...objBytesMap, ...preBuiltBytesMap },
+            const linkResult = await dispatchClangFacet(runtime.link, {
+                sysrootFiles: { ...runtime.link.sysrootFiles, ...objBytesMap, ...preBuiltBytesMap },
                 argv: linkArgv,
                 outputPaths: [parsed.outputPath],
             });
@@ -600,23 +606,45 @@ function filterSysrootForLink(all) {
     }
     return out;
 }
-async function dispatchClangFacet(facetMgr, args) {
+async function createClangFacetRuntime(facetMgr, args) {
+    if (!args.clangVfsPath || !args.lldVfsPath || !args.memfsVfsPath || !args.sysrootVfsPath) {
+        throw new Error('installed clang manifest is missing required files');
+    }
     const toAB = (u8) => u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength);
+    const memfsBytes = args.vfs.readFile(args.memfsVfsPath);
+    const clangBytes = args.vfs.readFile(args.clangVfsPath);
+    const lldBytes = args.vfs.readFile(args.lldVfsPath);
+    const sysroot = parseUstar(args.vfs.readFile(args.sysrootVfsPath));
+    const { NimbusLoaderPool } = await import('../loaders/loader-pool.js');
+    const env = facetMgr.env;
+    const ctx = facetMgr.ctx;
+    const makeTarget = (primaryName, primaryBytes, sysrootFiles) => ({
+        primaryName,
+        sysrootFiles,
+        pool: new NimbusLoaderPool(env, ctx, {
+            tag: `clang-runner-${primaryName}`,
+            concurrency: 1,
+            omitSupervisor: true,
+            cacheScope: 'global',
+            preamble: CLANG_RUNNER_PREAMBLE,
+            wasmModules: {
+                'memfs.wasm': toAB(memfsBytes),
+                'primary.wasm': toAB(primaryBytes),
+            },
+        }),
+    });
+    return {
+        compile: makeTarget('clang', clangBytes, filterSysrootForCompile(sysroot)),
+        link: makeTarget('wasm-ld', lldBytes, filterSysrootForLink(sysroot)),
+    };
+}
+async function dispatchClangFacet(target, args) {
     // Encode sysroot files as base64 for context ferrying. We do this on
     // the supervisor to keep the facet preamble small and CPU-light.
     const filesB64 = {};
     for (const [path, bytes] of Object.entries(args.sysrootFiles)) {
         filesB64[path] = uint8ToBase64(bytes);
     }
-    const { NimbusLoaderPool } = await import('../loaders/loader-pool.js');
-    const env = facetMgr.env;
-    const ctx = facetMgr.ctx;
-    const pool = new NimbusLoaderPool(env, ctx, {
-        tag: `clang-runner-${args.primaryName}`,
-        concurrency: 1,
-        omitSupervisor: true,
-        preamble: CLANG_RUNNER_PREAMBLE,
-    });
     const facetFn = async function clangFacetCall(inArgs) {
         const wasmTable = globalThis.__NIMBUS_WASM || {};
         const memfsMod = wasmTable['memfs.wasm'];
@@ -646,16 +674,12 @@ async function dispatchClangFacet(facetMgr, args) {
         });
     };
     try {
-        const result = await pool.submit(facetFn, {
-            primaryName: args.primaryName,
+        const result = await target.pool.submit(facetFn, {
+            primaryName: target.primaryName,
             argv: args.argv,
             filesB64,
             outputPaths: args.outputPaths,
         }, {
-            wasmModules: {
-                'memfs.wasm': toAB(args.memfsBytes),
-                'primary.wasm': toAB(args.primaryBytes),
-            },
             timeoutMs: 300_000,
         });
         // Decode outputFiles from base64 → Uint8Array.

package/dist/runtime/package-manager.d.ts

@@ -27,12 +27,31 @@
  */
 import { type RuntimeCatalogEnv, type RuntimeManifest } from './runtime-catalog.js';
 import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+/** Minimal shell ctx shape we depend on (matches existing handlers). */
+export interface ShellCtx {
+    args: string[];
+    env: Record<string, string>;
+    cwd: string;
+    stdout: {
+        write(s: string): void;
+    };
+    stderr: {
+        write(s: string): void;
+    };
+}
 /** Minimal shell-registry shape we depend on. */
 export interface MinShellRegistry {
     register(name: string, handler: (ctx: any) => Promise<number>): void;
     unregister?(name: string): void;
     resolve?(name: string): any;
 }
+export interface RuntimeWarmTarget {
+    name: string;
+    version: string;
+    root: string;
+    manifest: RuntimeManifest;
+}
+export type RuntimeWarmHook = (target: RuntimeWarmTarget, ctx: ShellCtx) => Promise<void>;
 /** Runner-factory contract. Each registered runner produces a shell-
  *  command handler given the manifest + the installed root dir. The
  *  package manager invokes the factory at install-time + at boot-time
@@ -54,6 +73,17 @@ export interface RuntimeSummary {
     sizeBytes: number;
     license: string;
 }
+export interface RuntimeInstallTarget {
+    runtimeName: string;
+    versionOverride: string | null;
+    requestedName: string;
+}
+export interface RuntimeCommandHint {
+    command: string;
+    runtimeName: string;
+    installSpec: string;
+}
+export declare function createRuntimeCommandHintResolver(env: RuntimeCatalogEnv): (command: string) => Promise<RuntimeCommandHint | null>;
 /** Compute the per-user install root for (name, version). Uses
  *  `process.env.HOME` if present; falls back to `/home/user`. */
 export declare function installRoot(homeDir: string, name: string, version: string): string;
@@ -109,5 +139,6 @@ export declare function makeNimbusVerbHandler(deps: {
     /** Returns `process.env.HOME` for the session. Computed by the
      *  caller (init.ts) from the shell env. */
     getHome(): string;
+    warmRuntime?: RuntimeWarmHook;
 }): (ctx: any) => Promise<number>;
 //# sourceMappingURL=package-manager.d.ts.map

package/dist/runtime/package-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-manager.d.ts","sourceRoot":"","sources":["../../src/runtime/package-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"package-manager.d.ts","sourceRoot":"","sources":["../../src/runtime/package-manager.ts"],"names":[],"mappings":"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"}

package/dist/runtime/package-manager.js

@@ -34,6 +34,98 @@ export function registerRunnerFactory(key, factory) {
 export function getRegisteredRunners() {
     return Object.keys(runnerFactories);
 }
+const RUNTIME_NAME_ALIASES = {
+    python3: 'python',
+    ruby3: 'ruby',
+    'wasm-ld': 'clang',
+};
+function splitRuntimeSpec(spec) {
+    const atIdx = spec.indexOf('@');
+    return {
+        name: atIdx >= 0 ? spec.slice(0, atIdx) : spec,
+        versionOverride: atIdx >= 0 ? spec.slice(atIdx + 1) : null,
+    };
+}
+async function resolveRuntimeInstallTarget(env, catalog, spec) {
+    const parsed = splitRuntimeSpec(spec);
+    const aliased = RUNTIME_NAME_ALIASES[parsed.name] ?? parsed.name;
+    if (catalog.runtimes[aliased]) {
+        return {
+            runtimeName: aliased,
+            versionOverride: parsed.versionOverride,
+            requestedName: parsed.name,
+        };
+    }
+    for (const [runtimeName, entry] of Object.entries(catalog.runtimes)) {
+        const version = entry.default;
+        const versionEntry = entry.versions[version];
+        if (!versionEntry)
+            continue;
+        try {
+            const manifest = await fetchManifest(env, versionEntry.manifest);
+            if (manifest.entrypoints.some((ep) => ep.binName === parsed.name)) {
+                return {
+                    runtimeName,
+                    versionOverride: parsed.versionOverride,
+                    requestedName: parsed.name,
+                };
+            }
+        }
+        catch {
+            // A bad manifest should not prevent canonical catalog names from
+            // resolving; it only suppresses bin-name aliasing for that runtime.
+        }
+    }
+    return null;
+}
+export function createRuntimeCommandHintResolver(env) {
+    let hintsPromise = null;
+    const loadHints = async () => {
+        const catalog = await fetchCatalog(env);
+        const hints = new Map();
+        const add = (command, runtimeName) => {
+            if (!command || command.includes('/'))
+                return;
+            if (!hints.has(command)) {
+                hints.set(command, { command, runtimeName, installSpec: command });
+            }
+        };
+        for (const runtimeName of Object.keys(catalog.runtimes)) {
+            add(runtimeName, runtimeName);
+        }
+        for (const [alias, runtimeName] of Object.entries(RUNTIME_NAME_ALIASES)) {
+            if (catalog.runtimes[runtimeName])
+                add(alias, runtimeName);
+        }
+        for (const [runtimeName, entry] of Object.entries(catalog.runtimes)) {
+            const versionEntry = entry.versions[entry.default];
+            if (!versionEntry)
+                continue;
+            try {
+                const manifest = await fetchManifest(env, versionEntry.manifest);
+                for (const ep of manifest.entrypoints)
+                    add(ep.binName, runtimeName);
+            }
+            catch {
+                // Hints are best-effort UX. Install itself still surfaces the
+                // manifest/catalog error through the normal package-manager path.
+            }
+        }
+        return hints;
+    };
+    return async (command) => {
+        if (!command || command.includes('/'))
+            return null;
+        if (!hintsPromise) {
+            hintsPromise = loadHints().catch((e) => {
+                hintsPromise = null;
+                throw e;
+            });
+        }
+        const hints = await hintsPromise;
+        return hints.get(command) ?? null;
+    };
+}
 /** Compute the per-user install root for (name, version). Uses
  *  `process.env.HOME` if present; falls back to `/home/user`. */
 export function installRoot(homeDir, name, version) {
@@ -151,13 +243,13 @@ export async function ensureRuntimesProgrammatic(deps, specs, opts = {}) {
  * `nimbus uninstall …`. Registered under the name `nimbus`.
  */
 export function makeNimbusVerbHandler(deps) {
-    const { env, vfs, registry, getHome } = deps;
+    const { env, vfs, registry, getHome, warmRuntime } = deps;
     return async function nimbus(ctx) {
         const argv = ctx.args || [];
         const verb = argv[0];
         const rest = argv.slice(1);
         if (verb === 'install') {
-            return runInstall(rest, ctx, { env, vfs, registry, getHome });
+            return runInstall(rest, ctx, { env, vfs, registry, getHome, warmRuntime });
         }
         if (verb === 'uninstall') {
             return runUninstall(rest, ctx, { vfs, registry, getHome });
@@ -184,11 +276,7 @@ async function runInstall(args, ctx, deps) {
         ctx.stderr.write('usage: nimbus install <name>[@<version>]\n');
         return 2;
     }
-    // Parse `<name>` or `<name>@<version>`.
     const spec = positional[0];
-    const atIdx = spec.indexOf('@');
-    const name = atIdx >= 0 ? spec.slice(0, atIdx) : spec;
-    const versionOverride = atIdx >= 0 ? spec.slice(atIdx + 1) : null;
     // Fetch catalog.
     let catalog;
     try {
@@ -198,13 +286,16 @@ async function runInstall(args, ctx, deps) {
         ctx.stderr.write(`nimbus install: ${e?.message || e}\n`);
         return 1;
     }
-    const runtimeEntry = catalog.runtimes[name];
-    if (!runtimeEntry) {
-        ctx.stderr.write(`nimbus install: '${name}' is not in catalog\n`);
+    const target = await resolveRuntimeInstallTarget(deps.env, catalog, spec);
+    if (!target) {
+        const parsed = splitRuntimeSpec(spec);
+        ctx.stderr.write(`nimbus install: '${parsed.name}' is not in catalog\n`);
         ctx.stderr.write(`nimbus install: try 'nimbus install --available' to see installable runtimes\n`);
         return 1;
     }
-    const version = versionOverride || runtimeEntry.default;
+    const name = target.runtimeName;
+    const runtimeEntry = catalog.runtimes[name];
+    const version = target.versionOverride || runtimeEntry.default;
     const versionEntry = runtimeEntry.versions[version];
     if (!versionEntry) {
         ctx.stderr.write(`nimbus install: '${name}@${version}' not in catalog\n`);
@@ -219,6 +310,21 @@ async function runInstall(args, ctx, deps) {
         ctx.stdout.write(`[${name}] already installed at ${root} (use --reinstall to refetch)\n`);
         // Still re-register bins in case the registry lost them — idempotent.
         rehydrateInstalledRuntimes(deps.vfs, deps.registry, home);
+        let manifest = null;
+        try {
+            manifest = JSON.parse(deps.vfs.readFileString(`${root}/manifest.json`));
+        }
+        catch {
+            manifest = null;
+        }
+        if (manifest) {
+            await warmRuntimeIfConfigured(ctx, deps, {
+                name,
+                version,
+                root,
+                manifest,
+            });
+        }
         return 0;
     }
     // Fetch manifest from R2.
@@ -310,8 +416,24 @@ async function runInstall(args, ctx, deps) {
         deps.registry.register(ep.binName, handler);
     }
     ctx.stdout.write(`[${name}] installed at ${root} (${(totalBytes / 1024 / 1024).toFixed(1)} MiB)\n`);
+    await warmRuntimeIfConfigured(ctx, deps, {
+        name,
+        version,
+        root,
+        manifest,
+    });
     return 0;
 }
+async function warmRuntimeIfConfigured(ctx, deps, target) {
+    if (!deps.warmRuntime)
+        return;
+    try {
+        await deps.warmRuntime(target, ctx);
+    }
+    catch (e) {
+        ctx.stderr.write(`[${target.name}] warning: runtime warm-up failed: ${e?.message || e}\n`);
+    }
+}
 // ── --list ───────────────────────────────────────────────────────────
 async function runList(ctx, deps) {
     const home = deps.getHome();

package/dist/runtime/python-repl.d.ts

@@ -62,4 +62,5 @@ export interface PythonReplDeps {
  * runs `python` with no args.
  */
 export declare function runPythonRepl(deps: PythonReplDeps): Promise<number>;
+export declare function warmPythonRepl(deps: Pick<PythonReplDeps, 'facetMgr' | 'vfs' | 'installRoot'>): Promise<void>;
 //# sourceMappingURL=python-repl.d.ts.map

package/dist/runtime/python-repl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"python-repl.d.ts","sourceRoot":"","sources":["../../src/runtime/python-repl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAKlE,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;IACf,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,EAAE,GAAG,CAAC;CACb;AAwhBD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAOzE"}
+{"version":3,"file":"python-repl.d.ts","sourceRoot":"","sources":["../../src/runtime/python-repl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAKlE,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;IACf,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,EAAE,GAAG,CAAC;CACb;AAuhBD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAOzE;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,KAAK,GAAG,aAAa,CAAC,GAC7D,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/runtime/python-repl.js

@@ -153,14 +153,13 @@ class PythonReplAdapter {
             concurrency: 1,
             omitSupervisor: true,
             preamble,
+            wasmModules: {
+                'pyodide.asm.wasm': toAB(wasmBytes),
+            },
         });
-        // Stash the wasm bytes for first submit's wasmModules.
-        this.__wasmBytesAB = toAB(wasmBytes);
     }
     async submitFacetFn(args) {
-        const wasmModules = { 'pyodide.asm.wasm': this.__wasmBytesAB };
         return await this.pool.submit(replStepFacetFn, args, {
-            wasmModules,
             timeoutMs: 60_000,
         });
     }
@@ -560,3 +559,8 @@ export async function runPythonRepl(deps) {
     const session = new ReplSession(adapter, deps.terminal, deps.shell);
     return await session.run();
 }
+export async function warmPythonRepl(deps) {
+    const adapter = new PythonReplAdapter(deps);
+    await adapter.push('');
+    await adapter.close();
+}

package/dist/runtime/python-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"python-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/python-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;CAChB,GAAG,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAC7F,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,CA2HhC;AAkPD;;;;;;GAMG;AAKH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAyFhF"}
+{"version":3,"file":"python-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/python-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;CAChB,GAAG,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAC7F,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,CAuIhC;AA6ND;;;;;;GAMG;AAKH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAyFhF"}