@nimbus-sh/worker 0.1.4 → 0.1.6

package/dist/runtime/os-contracts.d.ts

@@ -0,0 +1,128 @@
+import type { VfsEvent } from '../vfs/events.js';
+export type RuntimeFileType = 'file' | 'directory' | 'symlink';
+export interface RuntimeVfsStat {
+    type: RuntimeFileType;
+    size: number;
+    ctime: number;
+    mtime: number;
+    mode: number;
+    revision: number;
+}
+export interface RuntimeVfsDirEntry {
+    name: string;
+    type: RuntimeFileType;
+}
+export interface RuntimeOpenFlags {
+    read?: boolean;
+    write?: boolean;
+    append?: boolean;
+    create?: boolean;
+    truncate?: boolean;
+    followSymlinks?: boolean;
+    expectedRevision?: number;
+}
+export interface RuntimeFileHandle {
+    id: number;
+    path: string;
+    flags: Required<Omit<RuntimeOpenFlags, 'expectedRevision'>> & {
+        expectedRevision?: number;
+    };
+    position: number;
+    baseRevision: number;
+    closed: boolean;
+}
+export interface RuntimeFsBridge {
+    stat(path: string, options?: {
+        followSymlinks?: boolean;
+    }): Promise<RuntimeVfsStat | null>;
+    readFile(path: string, options?: {
+        followSymlinks?: boolean;
+    }): Promise<Uint8Array | null>;
+    writeFile(path: string, bytes: string | Uint8Array, options?: {
+        createParents?: boolean;
+        expectedRevision?: number;
+    }): Promise<void>;
+    open(path: string, flags: RuntimeOpenFlags): Promise<RuntimeFileHandle>;
+    read(handleId: number, offset: number | null, length: number): Promise<Uint8Array>;
+    write(handleId: number, offset: number | null, bytes: Uint8Array): Promise<number>;
+    close(handleId: number): Promise<void>;
+    readdir(path: string, options?: {
+        followSymlinks?: boolean;
+    }): Promise<RuntimeVfsDirEntry[]>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<void>;
+    unlink(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    readlink(path: string): Promise<string | null>;
+    symlink(target: string, path: string): Promise<void>;
+    fsync(handleId?: number): Promise<void>;
+    revision(path?: string): Promise<number>;
+    subscribe?(path: string, listener: (event: VfsEvent) => void): () => void;
+}
+export interface RuntimeProcessBridge {
+    spawn(command: string, args: string[], options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        tty?: RuntimeTtyOptions;
+    }): Promise<{
+        pid: number;
+    }>;
+    writeStdin(pid: number, bytes: string | Uint8Array): Promise<void>;
+    endStdin(pid: number): Promise<void>;
+    kill(pid: number, signal?: string): Promise<void>;
+    wait(pid: number, timeoutMs?: number): Promise<{
+        exitCode: number | null;
+    }>;
+}
+export interface RuntimeTtyOptions {
+    stdinIsTTY?: boolean;
+    stdoutIsTTY?: boolean;
+    stderrIsTTY?: boolean;
+    columns?: number;
+    rows?: number;
+    raw?: boolean;
+}
+export interface RuntimePortBridge {
+    register(port: number, processId: number, handler: (request: Request) => Promise<Response>): Promise<void>;
+    unregister(port: number, processId?: number): Promise<void>;
+    list(): Promise<Array<{
+        port: number;
+        processId: number;
+        registeredAt: number;
+    }>>;
+}
+export type RuntimePackageAbi = 'javascript' | 'wasm32-wasi-nimbus' | 'pyodide' | 'ruby-wasm' | 'native-unsupported';
+export interface RuntimeCommandProvider {
+    runtimeName: string;
+    version: string;
+    abi: RuntimePackageAbi;
+    commands: string[];
+    packageManagers?: string[];
+    libraries?: string[];
+}
+export type RuntimeDiagnosticEvent = {
+    type: 'fs-cache';
+    hit: boolean;
+    path: string;
+    bytes?: number;
+    revision?: number;
+} | {
+    type: 'fs-flush';
+    path?: string;
+    bytes: number;
+    durationMs: number;
+} | {
+    type: 'fs-invalidation';
+    path: string;
+    revision: number;
+    lagMs?: number;
+} | {
+    type: 'unsupported-abi';
+    packageName?: string;
+    abi: string;
+    message: string;
+};
+//# sourceMappingURL=os-contracts.d.ts.map

package/dist/runtime/os-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"os-contracts.d.ts","sourceRoot":"","sources":["../../src/runtime/os-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,eAAe,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC,GAAG;QAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC3F,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC3F,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,CAAC,EAAE;QAC5D,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACxE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACnF,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnF,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC7F,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/C,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,SAAS,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC3E;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,GAAG,CAAC,EAAE,iBAAiB,CAAC;KACzB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7B,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3G,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CACnF;AAED,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ,oBAAoB,GACpB,SAAS,GACT,WAAW,GACX,oBAAoB,CAAC;AAEzB,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,iBAAiB,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/runtime/os-contracts.js

@@ -0,0 +1 @@
+export {};

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,123 @@ export function registerRunnerFactory(key, factory) {
 export function getRegisteredRunners() {
     return Object.keys(runnerFactories);
 }
+const RUNTIME_NAME_ALIASES = {
+    python3: 'python',
+    pip: 'python',
+    pip3: 'python',
+    ruby3: 'ruby',
+    gem: 'ruby',
+    bundle: 'ruby',
+    bundler: 'ruby',
+    'wasm-ld': 'clang',
+};
+function runtimeEntrypoints(manifest) {
+    const out = [...manifest.entrypoints];
+    const seen = new Set(out.map((ep) => ep.binName));
+    const add = (binName, runner, kind) => {
+        if (seen.has(binName))
+            return;
+        out.push({ binName, runner, kind, args: [] });
+        seen.add(binName);
+    };
+    if (manifest.name === 'python') {
+        add('pip', 'python-runner', 'pip');
+        add('pip3', 'python-runner', 'pip');
+    }
+    if (manifest.name === 'ruby') {
+        add('gem', 'ruby-runner', 'gem');
+        add('bundle', 'ruby-runner', 'bundle');
+        add('bundler', 'ruby-runner', 'bundle');
+    }
+    return out;
+}
+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 (runtimeEntrypoints(manifest).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 runtimeEntrypoints(manifest))
+                    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) {
@@ -83,7 +200,7 @@ export function listInstalledManifests(vfs, homeDir) {
 export function rehydrateInstalledRuntimes(vfs, registry, homeDir) {
     const bins = [];
     for (const { root, manifest } of listInstalledManifests(vfs, homeDir)) {
-        for (const ep of manifest.entrypoints) {
+        for (const ep of runtimeEntrypoints(manifest)) {
             const factory = runnerFactories[ep.runner];
             if (!factory)
                 continue; // runner not registered yet — skip
@@ -99,7 +216,7 @@ export function listInstalledRuntimes(vfs, homeDir) {
         name: manifest.name,
         version: manifest.version,
         root,
-        bins: manifest.entrypoints.map((e) => e.binName),
+        bins: runtimeEntrypoints(manifest).map((e) => e.binName),
         sizeBytes: manifest.files.reduce((a, f) => a + f.size, 0),
         license: manifest.license,
     }));
@@ -151,13 +268,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 +301,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 +311,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 +335,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.
@@ -300,7 +431,7 @@ async function runInstall(args, ctx, deps) {
     });
     await Promise.all(workers);
     // Register entrypoints.
-    for (const ep of manifest.entrypoints) {
+    for (const ep of runtimeEntrypoints(manifest)) {
         const factory = runnerFactories[ep.runner];
         if (!factory) {
             ctx.stderr.write(`[${name}] warning: runner '${ep.runner}' not registered; bin '${ep.binName}' will not be invokable\n`);
@@ -310,8 +441,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();
@@ -323,7 +470,7 @@ async function runList(ctx, deps) {
     ctx.stdout.write(`installed runtimes (${installed.length}):\n`);
     for (const { root, manifest } of installed) {
         const totalBytes = manifest.files.reduce((a, f) => a + f.size, 0);
-        const bins = manifest.entrypoints.map((e) => e.binName).join(', ');
+        const bins = runtimeEntrypoints(manifest).map((e) => e.binName).join(', ');
         ctx.stdout.write(`  ${manifest.name}@${manifest.version}  ${(totalBytes / 1024 / 1024).toFixed(1)} MiB  bins=[${bins}]  ${root}\n`);
     }
     return 0;
@@ -374,7 +521,7 @@ async function runUninstall(args, ctx, deps) {
     }
     for (const m of matches) {
         // Unregister bins.
-        for (const ep of m.manifest.entrypoints) {
+        for (const ep of runtimeEntrypoints(m.manifest)) {
             // We don't have a guaranteed `unregister`; bins shadowing is OK
             // because boot-rehydration only re-registers what's still on disk.
             if (typeof deps.registry.unregister === 'function') {

package/dist/runtime/port-registry.d.ts

@@ -38,6 +38,9 @@ export interface PortEntry {
 }
 export declare class PortRegistry {
     private ports;
+    private facetStubsByPid;
+    /** Remember the routeable facet stub for a running process. */
+    bindFacetStub(pid: number, facetStub: any): void;
     /** Register a facet as listening on a port. */
     register(port: number, pid: number, facetStub: any): void;
     /** Unregister a port. */
@@ -46,6 +49,8 @@ export declare class PortRegistry {
     unregisterByPid(pid: number): number;
     /** Look up a port entry. */
     get(port: number): PortEntry | undefined;
+    /** Attach a routeable facet stub to ports previously reserved by a PID. */
+    attachFacetStubByPid(pid: number, facetStub: any): number[];
     /** Check if a port is registered. */
     has(port: number): boolean;
     /** Get all registered ports. */

package/dist/runtime/port-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"port-registry.d.ts","sourceRoot":"","sources":["../../src/runtime/port-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,SAAS,EAAE,GAAG,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAgC;IAE7C,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI;IAIzD,yBAAyB;IACzB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,oDAAoD;IACpD,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAWpC,4BAA4B;IAC5B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIxC,qCAAqC;IACrC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,gCAAgC;IAChC,MAAM,IAAI,SAAS,EAAE;IAIrB;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA8F9F,IAAI,KAAK;;;;;;MAKR;CACF"}
+{"version":3,"file":"port-registry.d.ts","sourceRoot":"","sources":["../../src/runtime/port-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,SAAS,EAAE,GAAG,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,eAAe,CAA0B;IAEjD,+DAA+D;IAC/D,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI;IAMhD,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI;IAKzD,yBAAyB;IACzB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,oDAAoD;IACpD,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAYpC,4BAA4B;IAC5B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIxC,2EAA2E;IAC3E,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,MAAM,EAAE;IAU3D,qCAAqC;IACrC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,gCAAgC;IAChC,MAAM,IAAI,SAAS,EAAE;IAIrB;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA8F9F,IAAI,KAAK;;;;;;MAKR;CACF"}

package/dist/runtime/port-registry.js

@@ -27,9 +27,18 @@
  */
 export class PortRegistry {
     ports = new Map();
+    facetStubsByPid = new Map();
+    /** Remember the routeable facet stub for a running process. */
+    bindFacetStub(pid, facetStub) {
+        if (!facetStub)
+            return;
+        this.facetStubsByPid.set(pid, facetStub);
+        this.attachFacetStubByPid(pid, facetStub);
+    }
     /** Register a facet as listening on a port. */
     register(port, pid, facetStub) {
-        this.ports.set(port, { port, pid, facetStub, registeredAt: Date.now() });
+        const routeableStub = facetStub || this.facetStubsByPid.get(pid) || null;
+        this.ports.set(port, { port, pid, facetStub: routeableStub, registeredAt: Date.now() });
     }
     /** Unregister a port. */
     unregister(port) {
@@ -44,12 +53,24 @@ export class PortRegistry {
                 count++;
             }
         }
+        this.facetStubsByPid.delete(pid);
         return count;
     }
     /** Look up a port entry. */
     get(port) {
         return this.ports.get(port);
     }
+    /** Attach a routeable facet stub to ports previously reserved by a PID. */
+    attachFacetStubByPid(pid, facetStub) {
+        const ports = [];
+        for (const entry of this.ports.values()) {
+            if (entry.pid !== pid || entry.facetStub)
+                continue;
+            entry.facetStub = facetStub;
+            ports.push(entry.port);
+        }
+        return ports;
+    }
     /** Check if a port is registered. */
     has(port) {
         return this.ports.has(port);

package/dist/runtime/pyodide-runtime-assets.d.ts

@@ -0,0 +1,19 @@
+import type { RuntimeManifest } from './runtime-catalog.js';
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+export interface PyodideRuntimeAssetPaths {
+    asmWasmVfs: string | null;
+    asmJsVfs: string | null;
+    stdlibVfs: string | null;
+    lockfileVfs: string | null;
+    manifest: RuntimeManifest;
+    vfs: SqliteVFS;
+}
+export interface PyodideRuntimeFiles {
+    asmWasmBytes: Uint8Array;
+    asmJsSrc: string;
+    stdlibB64: string;
+    lockfileText: string;
+}
+export declare function readPyodideRuntimeFiles(args: PyodideRuntimeAssetPaths): PyodideRuntimeFiles;
+export declare function uint8ToBase64(u8: Uint8Array): string;
+//# sourceMappingURL=pyodide-runtime-assets.d.ts.map

package/dist/runtime/pyodide-runtime-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pyodide-runtime-assets.d.ts","sourceRoot":"","sources":["../../src/runtime/pyodide-runtime-assets.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAWtD,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,UAAU,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,GAAG,mBAAmB,CAoB3F;AA6BD,wBAAgB,aAAa,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAUpD"}

package/dist/runtime/pyodide-runtime-assets.js

@@ -0,0 +1,44 @@
+import pyodideWorkerdAdapter from '../../runtime-contracts/pyodide-workerd-adapter.json';
+const WORKERD_ADAPTER = pyodideWorkerdAdapter;
+export function readPyodideRuntimeFiles(args) {
+    if (!args.asmWasmVfs || !args.asmJsVfs || !args.stdlibVfs) {
+        throw new Error('installed Pyodide manifest is missing required files');
+    }
+    const asmWasmBytes = args.vfs.readFile(args.asmWasmVfs);
+    const asmJsSrc = new TextDecoder('utf-8').decode(args.vfs.readFile(args.asmJsVfs));
+    const stdlibBytes = args.vfs.readFile(args.stdlibVfs);
+    const lockfileText = args.lockfileVfs && args.vfs.exists(args.lockfileVfs)
+        ? new TextDecoder('utf-8').decode(args.vfs.readFile(args.lockfileVfs))
+        : '{"packages":{}}';
+    assertPyodideWorkerdAdapter(args.manifest, asmJsSrc);
+    return {
+        asmWasmBytes,
+        asmJsSrc,
+        stdlibB64: uint8ToBase64(stdlibBytes),
+        lockfileText,
+    };
+}
+function assertPyodideWorkerdAdapter(manifest, asmJsSrc) {
+    const metadata = (manifest.runtime_artifacts || []).find((entry) => entry.path === WORKERD_ADAPTER.artifactPath && entry.kind === 'workerd-adapter');
+    if (!metadata) {
+        throw new Error(`pyodide.asm.js is missing Nimbus workerd adapter metadata (${WORKERD_ADAPTER.id}); ` +
+            `sync the python runtime and reinstall it with 'nimbus install python --reinstall'`);
+    }
+    if (metadata.id !== WORKERD_ADAPTER.id) {
+        throw new Error(`pyodide.asm.js adapter mismatch: installed ${metadata.id}, expected ${WORKERD_ADAPTER.id}`);
+    }
+    if (manifest.version !== WORKERD_ADAPTER.pyodideVersion) {
+        throw new Error(`Pyodide version mismatch: installed ${manifest.version}, expected ${WORKERD_ADAPTER.pyodideVersion}`);
+    }
+    if (!asmJsSrc.startsWith(WORKERD_ADAPTER.sentinel)) {
+        throw new Error(`pyodide.asm.js does not contain the Nimbus workerd adapter sentinel (${WORKERD_ADAPTER.id})`);
+    }
+}
+export function uint8ToBase64(u8) {
+    const chunk = 0x8000;
+    let s = '';
+    for (let i = 0; i < u8.length; i += chunk) {
+        s += String.fromCharCode.apply(null, Array.from(u8.subarray(i, Math.min(i + chunk, u8.length))));
+    }
+    return btoa(s);
+}

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

@@ -29,6 +29,7 @@
 import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
 import type { FacetManager } from '../facets/manager.js';
 import type { WebSocketTerminal } from '../facets/ws-terminal.js';
+import type { RuntimeManifest } from './runtime-catalog.js';
 /** Inputs needed to bootstrap a Pyodide REPL session. */
 export interface PythonReplDeps {
     facetMgr: FacetManager;
@@ -36,6 +37,7 @@ export interface PythonReplDeps {
     terminal: WebSocketTerminal;
     /** Per-user-VFS install dir, e.g. 'home/user/.nimbus/runtimes/python/0.29.4'. */
     installRoot: string;
+    manifest: RuntimeManifest;
     /**
      * REPL-R7-1 (2026-05-12): optional lifo-sh Shell reference.
      *
@@ -62,4 +64,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' | 'manifest'>): 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;AAElE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAK5D,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,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,EAAE,GAAG,CAAC;CACb;AA8fD;;;;;;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,GAAG,UAAU,CAAC,GAC1E,OAAO,CAAC,IAAI,CAAC,CAIf"}