@nimbus-sh/worker 0.5.0 → 0.7.0

package/dist/session/init.js

@@ -35,6 +35,7 @@
  */
 import { Shell, createCurlCommand, createNpmCommand, NPM_VERSION, createTopCommand, createWatchCommand, createHelpCommand, rehydrateGlobalPackages, } from '@nimbus-sh/core/substrate/lifo/index.js';
 import { createKillCommand } from '@nimbus-sh/core/substrate/lifo/commands/system/kill.js';
+import { textSink } from '@nimbus-sh/core/_shared/bytes.js';
 import { NimbusWorkspace } from '@nimbus-sh/core/workspace';
 import { CRED_KERNEL, requireVfsCred } from '@nimbus-sh/core/runtime/os-contracts.js';
 import { WebSocketTerminal } from '../facets/ws-terminal.js';
@@ -42,50 +43,41 @@ import { EsbuildService } from '@nimbus-sh/core/runtime/esbuild-service.js';
 import { runFresh } from '../runtime/node-runner.js';
 import { runBunScript, BUN_VERSION } from '../runtime/bun-runner.js';
 import { buildRuntimeHandler, resolveRuntimeScriptPath, } from '@nimbus-sh/core/runtime/runtime-registry.js';
-import { parseViteConfigSource } from '@nimbus-sh/core/runtime/vite-config-parser.js';
-import { startRealVite } from './start-real-vite.js';
-import { findHtmlScriptEntrypoint, rewriteViteBuildHtml } from '../runtime/html-entrypoint.js';
 import { normalizeVfsPath, parentVfsPath, resolveVfsPath, stripLeadingSlashes } from '@nimbus-sh/core/vfs/path.js';
-import { ViteDevServer } from '../facets/vite-dev-server.js';
-import { shouldUseRealVite } from '../facets/cirrus-real.js';
-import { makeLongRunningPortStub, resolveLongRunningPort, expandArgvShellDefaults, } from '@nimbus-sh/core/runtime/long-running-handle.js';
+import { errorText } from '@nimbus-sh/core/_shared/error-text.js';
 import { NimbusWrangler } from '../wrangler/nimbus-wrangler.js';
-import { filterWranglerFlags, detectBundlerBin, checkNodeModulesGuard, detectUnsupportedWranglerConfig, } from './helpers.js';
+import { filterWranglerFlags, detectBundlerBin, checkNodeModulesGuard, detectUnsupportedWranglerConfig, refusedNextSubcommand, NEXT_REFUSAL_MESSAGE, } from './helpers.js';
+import { createViteCommand } from './vite-command.js';
 import { HeredocHandler, LineEditorExtender } from '@nimbus-sh/core/shell/features.js';
 import { registerShellEntrypointCommands } from '@nimbus-sh/core/shell/shell-entrypoints.js';
 import { makeChshCommand } from '@nimbus-sh/core/substrate/lifo/shell/default-shell.js';
 import { installNpmBinFallbackResolver } from '../shell/npm-bin-entrypoints.js';
-import { parseNpmInstallInvocation } from '../npm/install-args.js';
-import { npmLogEnabled } from '../npm/npm-log.js';
-import { materializeNpmBinShims } from '../npm/bin-links.js';
+import { createNpmInstallPort } from './npm-install-port.js';
 import { makeNimbusVerbHandler, createRuntimeCommandHintResolver, } from '../runtime/package-manager.js';
+import { rpcExposeApp, rpcListApps, rpcRemoveApp, rpcRotateLink } from './programmatic.js';
 import { listInstalledRuntimes, rehydrateInstalledRuntimes, registerRunnerFactory, } from '@nimbus-sh/core/runtime/installed-runtimes.js';
 // Runtime factories (clang/python/ruby/bash/wasm) are imported lazily at
 // first-use inside their registered handlers — see the registrations below.
 // Keeping them off the top-level import graph shaves their module-eval cost
 // (zod, embedded socket-kernel/shim sources, wasm loaders) out of the
 // one-time Worker Startup Time paid on every fresh-isolate cold run.
-import { hasSeededProject, SEED_PROJECT_DIR } from '@nimbus-sh/core/vfs/seed-project.js';
+import { hasSeededProject, SEED_PROJECT_DIR, SEED_PROJECT_NAME, SEED_PROJECT_TILDE } from '@nimbus-sh/core/vfs/seed-project.js';
 import { notifyTerminalEvent } from '../runtime/process-logs-api.js';
 import { generation } from '@nimbus-sh/fabric/generation.js';
 import { stripAnsi } from '@nimbus-sh/core/runtime/process-logs.js';
 import { DEFAULT_MOUNT_POINTS, NODE_VERSION, } from '@nimbus-sh/core/constants.js';
-import { ensureSessionStateSchema, loadShellState, stampHydratedAt, countSessionStateKeys, loadKernelMounts, persistKernelMounts, appendScrollback, loadScrollback, } from './state-store.js';
+import { ensureSessionStateSchema, loadShellState, stampHydratedAt, countSessionStateKeys, loadKernelMounts, persistKernelMounts, loadScrollback, } from './state-store.js';
 import { recordRecoveryEvent } from '@nimbus-sh/platform/oom-discriminator.js';
 import { sessionAiEnv } from './ai.js';
 import { routeSessionLoopback } from './loopback.js';
 import { setPhase } from './init-phases.js';
+import { shellTerminalTee } from './ws.js';
 import { VITE_CONFIG_KEY } from './keys.js';
-import { clearPortCapability } from './port-capability.js';
-function resolveNpmPrefix(prefix, cwd) {
-    return prefix.startsWith('/')
-        ? normalizeVfsPath(prefix)
-        : resolveVfsPath(prefix, cwd || '/home/user');
-}
 function quoteShellArgument(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-export async function initSession(self, ws) {
+export async function initSession(self, ws, options = {}) {
+    const replayScrollback = options.resume !== 'wake';
     self.ensureSqliteFs();
     const kernelFs = self.sqliteFs.as(CRED_KERNEL);
     self.ensureFacetManager();
@@ -114,17 +106,7 @@ export async function initSession(self, ws) {
     // facet and the scrollback replay below is wire-phase work.
     // Phase B will tag in once we start building the kernel.
     setPhase(self, 'wire', 'init-session');
-    self.terminal = new WebSocketTerminal(ws, (frame) => {
-        try {
-            appendScrollback(self.ctx, frame, Date.now());
-        }
-        catch (e) {
-            try {
-                console.warn('[B\'.3] appendScrollback failed:', e?.message || e);
-            }
-            catch { }
-        }
-    });
+    self.terminal = new WebSocketTerminal(ws, shellTerminalTee(self));
     // [B'.3] Replay persisted scrollback BEFORE the cold-start UI gate.
     // On rehydrate (hasPersistedState=true) we emit the prior
     // session's terminal contents as a single batched write — the
@@ -138,16 +120,18 @@ export async function initSession(self, ws) {
     // same scrollback both times. The cap eviction keeps total bytes
     // bounded.
     if (persisted.hasPersistedState) {
-        try {
-            const replay = loadScrollback(self.ctx);
-            if (replay.length > 0)
-                self.terminal.write(replay);
-        }
-        catch (e) {
+        if (replayScrollback) {
             try {
-                console.warn('[B\'.3] scrollback replay failed:', e?.message || e);
+                const replay = loadScrollback(self.ctx);
+                if (replay.length > 0)
+                    self.terminal.write(replay);
+            }
+            catch (e) {
+                try {
+                    console.warn('[B\'.3] scrollback replay failed:', e?.message || e);
+                }
+                catch { }
             }
-            catch { }
         }
         // The scrollback stops mid-command when the previous instance was
         // reset under it — the platform kills the isolate without running a
@@ -262,8 +246,8 @@ export async function initSession(self, ws) {
                     stdout: parent.isFdTerminal?.(1) ?? false,
                     stderr: parent.isFdTerminal?.(2) ?? false,
                 },
-                onStdout: (data) => parent.stdout.write(data),
-                onStderr: (data) => parent.stderr.write(data),
+                onStdout: textSink((data) => parent.stdout.write(data)),
+                onStderr: textSink((data) => parent.stderr.write(data)),
                 commandContext: {
                     pid: identity.pid,
                     cred: identity.cred,
@@ -589,6 +573,14 @@ export async function initSession(self, ws) {
             vfs: sqliteFs,
             registry: pkgRegistry,
             getHome: nimbusGetHome,
+            // The application verbs are the session's own (programmatic.ts):
+            // the shell, the SDK and the Agent all reach the same policy.
+            apps: {
+                expose: (target, options) => rpcExposeApp(self, target, options),
+                list: () => rpcListApps(self),
+                rotateLink: (target) => rpcRotateLink(self, target),
+                remove: (target) => rpcRemoveApp(self, target),
+            },
             warmRuntime: async (target, ctx) => {
                 // The runtime name, which is what `nimbus install python` installs
                 // — not the name the user typed. Left as 'python' through the
@@ -813,8 +805,8 @@ export async function initSession(self, ws) {
                         const shellResult = await shell.execute(command, {
                             cwd: ctx.cwd,
                             env: ctx.env,
-                            onStdout: (d) => ctx.stdout.write(d),
-                            onStderr: (d) => ctx.stderr.write(d),
+                            onStdout: textSink((d) => ctx.stdout.write(d)),
+                            onStderr: textSink((d) => ctx.stderr.write(d)),
                         });
                         return shellResult.exitCode;
                     }
@@ -1070,443 +1062,7 @@ export async function initSession(self, ws) {
         }
     });
     // ── vite command: start/stop the dev server ──────────────────────────
-    registry.register('vite', async (ctx) => {
-        const args = ctx.args || [];
-        const cwd = normalizeVfsPath(ctx.cwd || '/home/user');
-        if (args.includes('--help') || args.includes('-h')) {
-            ctx.stdout.write('Usage: vite [command] [options]\n\n');
-            ctx.stdout.write('Commands:\n');
-            ctx.stdout.write('  (default)   Start dev server\n');
-            ctx.stdout.write('  build       Build for production\n');
-            ctx.stdout.write('  preview     Serve the built dist/\n');
-            ctx.stdout.write('  stop        Stop dev server\n\n');
-            ctx.stdout.write('Options:\n');
-            ctx.stdout.write('  --root <dir>  Project root\n');
-            ctx.stdout.write('  --port <n>    Server port\n');
-            return 0;
-        }
-        self.ensureSqliteFs();
-        const viteConfig = {};
-        for (const cfgName of ['vite.config.ts', 'vite.config.js', 'vite.config.mjs']) {
-            const cfgPath = cwd + '/' + cfgName;
-            if (kernelFs.exists(cfgPath)) {
-                try {
-                    let cfgCode = kernelFs.readFileString(cfgPath);
-                    // Transform TS to JS
-                    if (cfgName.endsWith('.ts')) {
-                        if (!self.esbuildService)
-                            self.esbuildService = new EsbuildService(kernelFs);
-                        const t = await self.esbuildService.transform(cfgCode, { loader: 'ts', format: 'esm' });
-                        cfgCode = t.code;
-                    }
-                    Object.assign(viteConfig, parseViteConfigSource(cfgCode));
-                }
-                catch (e) {
-                    ctx.stderr.write(`Warning: could not parse ${cfgName}: ${e?.message}\n`);
-                }
-                break;
-            }
-        }
-        // ── vite build ──
-        if (args[0] === 'build') {
-            if (!self.esbuildService)
-                self.esbuildService = new EsbuildService(kernelFs);
-            const htmlPath = cwd + '/index.html';
-            let entryPoint = cwd + '/src/main.tsx';
-            let origHtml = '';
-            try {
-                origHtml = kernelFs.readFileString(htmlPath);
-                const htmlEntrypoint = await findHtmlScriptEntrypoint(origHtml);
-                if (htmlEntrypoint)
-                    entryPoint = cwd + '/' + stripLeadingSlashes(htmlEntrypoint);
-            }
-            catch {
-                ctx.stderr.write('Warning: no index.html\n');
-            }
-            if (!kernelFs.exists(entryPoint)) {
-                const alts = [cwd + '/src/main.tsx', cwd + '/src/main.ts', cwd + '/src/index.tsx', cwd + '/src/index.ts'];
-                entryPoint = alts.find(p => kernelFs.exists(p)) || entryPoint;
-            }
-            ctx.stdout.write('Building for production...\n');
-            ctx.stdout.write('  Entry: ' + entryPoint + '\n');
-            const t0 = Date.now();
-            try {
-                const outDir = viteConfig.outDir || 'dist';
-                const distDir = cwd + '/' + outDir;
-                // Detect which packages are installed vs need CDN
-                const nmDir = cwd + '/node_modules';
-                const externals = [];
-                const cdnPackages = [];
-                for (const pkg of ['react', 'react-dom', 'react/jsx-runtime', 'react-dom/client']) {
-                    const pkgBase = pkg.split('/')[0];
-                    if (!kernelFs.exists(nmDir + '/' + pkgBase)) {
-                        externals.push(pkg);
-                        if (!cdnPackages.includes(pkgBase))
-                            cdnPackages.push(pkgBase);
-                    }
-                }
-                if (viteConfig.alias)
-                    externals.push(...Object.keys(viteConfig.alias));
-                // Bundle JS
-                const result = await self.esbuildService.build([entryPoint], {
-                    bundle: true, format: 'esm', target: 'es2020', platform: 'browser',
-                    minify: true, outdir: '/' + distDir + '/assets',
-                    external: externals.length > 0 ? externals : undefined,
-                });
-                if (result.errors?.length) {
-                    for (const e of result.errors)
-                        ctx.stderr.write('  error: ' + e.text + '\n');
-                    return 1;
-                }
-                // Generate content hash for filenames
-                let jsContent = '';
-                for (const f of result.outputFiles || []) {
-                    jsContent = f.contents;
-                }
-                const hashNum = jsContent.split('').reduce((h, c) => ((h << 5) - h + c.charCodeAt(0)) | 0, 0);
-                const hash = (hashNum >>> 0).toString(36).padStart(6, '0');
-                // Write JS with hashed filename
-                const jsFilename = 'index-' + hash + '.js';
-                const jsPath = distDir + '/assets/' + jsFilename;
-                kernelFs.mkdir(distDir + '/assets', { recursive: true });
-                kernelFs.writeFile(jsPath, jsContent);
-                ctx.stdout.write('  \x1b[2m' + outDir + '/assets/' + jsFilename + '\x1b[0m  ' + (jsContent.length / 1024).toFixed(2) + ' kB\n');
-                // Collect all CSS files from src/
-                let allCss = '';
-                const collectCss = (dir) => {
-                    try {
-                        for (const e of kernelFs.readdir(dir)) {
-                            const fp = dir + '/' + e.name;
-                            if (e.type === 'directory')
-                                collectCss(fp);
-                            else if (e.name.endsWith('.css')) {
-                                try {
-                                    allCss += kernelFs.readFileString(fp) + '\n';
-                                }
-                                catch { }
-                            }
-                        }
-                    }
-                    catch { }
-                };
-                collectCss(cwd + '/src');
-                const cssFilename = 'index-' + hash + '.css';
-                if (allCss.trim()) {
-                    kernelFs.writeFile(distDir + '/assets/' + cssFilename, allCss);
-                    ctx.stdout.write('  \x1b[2m' + outDir + '/assets/' + cssFilename + '\x1b[0m  ' + (allCss.length / 1024).toFixed(2) + ' kB\n');
-                }
-                // Generate dist/index.html
-                if (origHtml) {
-                    const distHtml = await rewriteViteBuildHtml(origHtml, {
-                        jsFilename,
-                        cssFilename: allCss.trim() ? cssFilename : undefined,
-                        removeImportMap: cdnPackages.length === 0,
-                    });
-                    kernelFs.writeFile(distDir + '/index.html', distHtml);
-                    ctx.stdout.write('  \x1b[2m' + outDir + '/index.html\x1b[0m  ' + (distHtml.length / 1024).toFixed(2) + ' kB\n');
-                    if (cdnPackages.length > 0) {
-                        ctx.stdout.write('  \x1b[33mNote: ' + cdnPackages.join(', ') + ' loaded from CDN (not bundled)\x1b[0m\n');
-                    }
-                }
-                ctx.stdout.write('\n\x1b[32m\u2713 built in ' + ((Date.now() - t0) / 1000).toFixed(2) + 's\x1b[0m\n');
-                return 0;
-            }
-            catch (e) {
-                ctx.stderr.write('Build error: ' + (e?.message || e) + '\n');
-                return 1;
-            }
-        }
-        // ── vite preview ──
-        if (args[0] === 'preview') {
-            ctx.stdout.write('Serving dist/ — open ' + self.viteBasePath + '/\n');
-            const distRoot = cwd + '/' + (viteConfig.outDir || 'dist');
-            if (!kernelFs.exists(distRoot)) {
-                ctx.stderr.write('dist/ not found. Run vite build first.\n');
-                return 1;
-            }
-            // Start vite on the dist directory
-            if (!self.esbuildService)
-                self.esbuildService = new EsbuildService(kernelFs);
-            if (self.viteDevServer?.isRunning)
-                self.viteDevServer.stop();
-            const previewBasePath = self.viteBasePath;
-            // process metadata support: same long-running treatment as the
-            // dev path, just on the dist/ directory.
-            const previewPort = viteConfig.port || 4173; // vite preview default
-            const previewProcEntry = self.processes.spawn('vite preview (' + distRoot + ')', [], distRoot, { longRunning: true });
-            self.viteDevServer = new ViteDevServer({
-                vfs: self.sqliteFs, esbuild: self.esbuildService, root: distRoot,
-                onHmrMessage: () => { },
-                sql: self.ctx.storage.sql,
-                basePath: previewBasePath,
-                env: self.env,
-                ctx: self.ctx,
-                port: previewPort,
-                pid: previewProcEntry.pid,
-                processes: self.processes,
-            });
-            self.viteDevServer.start();
-            try {
-                const previewStub = makeLongRunningPortStub(self.viteDevServer);
-                self.portRegistry.bindFacetStub(previewProcEntry.pid, previewStub);
-                await clearPortCapability(self, previewPort);
-                self.portRegistry.register(previewPort, previewProcEntry.pid);
-                self._viteShimPid = previewProcEntry.pid;
-                self._viteShimPort = previewPort;
-            }
-            catch { }
-            try {
-                await self.ctx.storage.put(VITE_CONFIG_KEY, { root: distRoot, basePath: previewBasePath, port: previewPort });
-            }
-            catch { }
-            ctx.stdout.write('Serving at ' + previewBasePath + '/ \x1b[2m(pid=' + previewProcEntry.pid + ', port=' + previewPort + ')\x1b[0m\n');
-            return 0;
-        }
-        // ── vite stop ──
-        if (args[0] === 'stop') {
-            let stopped = false;
-            if (self.cirrusReal?.isRunning) {
-                self.cirrusReal.stop(self.ctx);
-                self.cirrusReal = null;
-                stopped = true;
-            }
-            if (self.viteDevServer?.isRunning) {
-                self.viteDevServer.stop();
-                self.viteDevServer = null;
-                try {
-                    await self.ctx.storage.delete(VITE_CONFIG_KEY);
-                }
-                catch { }
-                stopped = true;
-            }
-            // Primitive #3 teardown — symmetric with the start path. Always
-            // safe to call: unregisterByPid is idempotent, exit() guards
-            // against re-marking already-terminal entries.
-            if (self._viteShimPid != null) {
-                try {
-                    self.portRegistry.unregisterByPid(self._viteShimPid);
-                }
-                catch { }
-                try {
-                    self.processes.exit(self._viteShimPid, 0);
-                }
-                catch { }
-                notifyTerminalEvent(self.terminal, {
-                    type: 'exit', pid: self._viteShimPid, code: 0, command: 'vite',
-                });
-                self._viteShimPid = null;
-                self._viteShimPort = null;
-            }
-            if (stopped) {
-                ctx.stdout.write('\x1b[33mDev server stopped.\x1b[0m\n');
-            }
-            else {
-                ctx.stdout.write('No dev server running.\n');
-            }
-            return 0;
-        }
-        // ── vite (default: dev server) ──
-        let vfsRoot = cwd;
-        for (let i = 0; i < args.length; i++) {
-            if (args[i] === '--root' && args[i + 1])
-                vfsRoot = resolveVfsPath(args[i + 1], cwd);
-        }
-        if (viteConfig.root && viteConfig.root !== '.') {
-            vfsRoot = resolveVfsPath(viteConfig.root, cwd);
-        }
-        vfsRoot = normalizeVfsPath(vfsRoot);
-        // Argv expansion: package.json scripts commonly write
-        // `--port ${PORT:-3000}`. Resolve it once and feed both Vite
-        // backends so `/api/stats`, `/preview/`, and port tabs agree.
-        const expandedArgs = expandArgvShellDefaults(args, ctx.env || {});
-        const vitePortDefault = 5173;
-        const resolvedPort = resolveLongRunningPort({
-            argv: expandedArgs,
-            env: ctx.env,
-            configPort: viteConfig.port,
-            fallback: vitePortDefault,
-        });
-        // ── Preflight: node_modules guard ────────────────────────────────────
-        // Direct `vite` invocation requires installed deps. Bail loudly BEFORE
-        // spawning a dev server that would just serve broken modules and
-        // confuse the user. --force / --no-install-check bypasses the check.
-        const bypassInstallCheck = expandedArgs.includes('--force') || expandedArgs.includes('--no-install-check');
-        if (!bypassInstallCheck) {
-            const guard = checkNodeModulesGuard(kernelFs, vfsRoot);
-            if (guard.missing) {
-                ctx.stderr.write('\x1b[31m\u2718\x1b[0m \x1b[1mnode_modules/ not found\x1b[0m' +
-                    (guard.depCount > 0 ? ` (${guard.depCount} dependencies declared)` : '') + '\n' +
-                    '  Run \x1b[36mnpm install\x1b[0m in ' + vfsRoot + ' first,\n' +
-                    '  or re-run with \x1b[36m--force\x1b[0m to skip this check.\n');
-                return 1;
-            }
-        }
-        if (self.viteDevServer?.isRunning)
-            self.viteDevServer.stop();
-        // ── Real-vite mode (Phase 0 spike, opt-in) ─────────────────────────
-        // NIMBUS_REAL_VITE=1 or `nimbusDevServer: 'real'` in vite.config.ts
-        // routes the session through a dynamic-worker facet running the
-        // real `vite` npm package. The in-process Cirrus shim is bypassed.
-        //
-        // This is EXPERIMENTAL and gated behind an explicit opt-in. Any
-        // error here falls back to Cirrus by the user re-running without
-        // the env flag — we do not silently fall back (fidelity over
-        // magic).
-        const sessionEnv = (ctx && ctx.env) || {};
-        const useReal = shouldUseRealVite({ env: sessionEnv, viteConfig });
-        if (useReal) {
-            const vitePort = resolvedPort;
-            const previewBasePath = self.viteBasePath;
-            // One boot path, shared with hibernation-restore (start-real-vite.ts):
-            // pre-bundles the user's vite.config, boots the facet, registers the
-            // port, and persists the vite-config so a woken session rebuilds the
-            // same real-vite server. Only the banner below is command-specific.
-            const { cirrusReal, userConfigBundle, cfgPath } = await startRealVite(self, {
-                root: vfsRoot,
-                port: vitePort,
-                basePath: previewBasePath,
-                configDir: cwd,
-                signal: ctx.signal,
-                onConfigError: (msg) => {
-                    ctx.stderr.write('\x1b[33m!\x1b[0m vite.config bundling failed: ' + msg + '\n');
-                    ctx.stderr.write('  Real-vite will run with default config.\n');
-                },
-            });
-            {
-                // ── Boot banner (§4.3 of PHASE2-REAL-VITE-PLAN.md) ──────
-                const snap = cirrusReal.stats.snapshot;
-                ctx.stdout.write('\n\x1b[1;36m  Nimbus: real-vite mode\x1b[0m \x1b[2m(experimental, Phase 1-4)\x1b[0m\n\n');
-                ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Preview:    \x1b[36m' + previewBasePath + '/\x1b[0m\n');
-                ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Vite:       ' + cirrusReal.stats.viteVersion + ' (bundled)\n');
-                ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Root:       ' + vfsRoot + '\n');
-                ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Port:       ' + vitePort + ' \x1b[2m(virtual routing key)\x1b[0m\n');
-                if (snap) {
-                    const kb = (snap.totalBytes / 1024).toFixed(1);
-                    const pkgJson = snap.packageJsonCount;
-                    ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Snapshot:   ' + snap.fileCount + ' files / ' +
-                        kb + ' KB ' +
-                        (pkgJson ? '\x1b[2m(incl. ' + pkgJson + ' package.json, rest lazy)\x1b[0m' : '') + '\n');
-                }
-                if (userConfigBundle) {
-                    ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Config:     ' + cfgPath + ' \x1b[2m(' +
-                        (userConfigBundle.length / 1024).toFixed(0) + ' KB bundled)\x1b[0m\n');
-                }
-                ctx.stdout.write('\n  \x1b[2mWorks:\x1b[0m @vitejs/plugin-react, JSX/TSX transforms, SPA fallback, HMR.\n');
-                ctx.stdout.write('  \x1b[2mPartial:\x1b[0m other plugins (Babel-family generally OK; SWC/Rolldown blocked).\n');
-                ctx.stdout.write('  \x1b[2mBlocked:\x1b[0m vite build (rolldown needs node:wasi). Use cirrus for build.\n');
-                ctx.stdout.write('\n  \x1b[2mRun \x1b[0mvite stop\x1b[2m, or \x1b[0mNIMBUS_REAL_VITE=0 vite\x1b[2m for Cirrus.\x1b[0m\n\n');
-                return 0;
-            }
-        }
-        if (!self.esbuildService)
-            self.esbuildService = new EsbuildService(kernelFs);
-        const previewBasePath = self.viteBasePath;
-        const viteDefine = viteConfig.define;
-        // Vite dev servers are represented as long-running process-table
-        // entries and port-registry handlers, so `ps`, logs, preview routing,
-        // `vite stop`, and `kill <pid>` share the same lifecycle primitives.
-        // Allocate PID FIRST so we can plumb it into ViteDevServer's
-        // process-log wiring at construction time. The PID stays valid
-        // for the life of this dev-server instance; subsequent log lines
-        // emitted by ViteDevServer flow into the pid's stderr ring,
-        // visible in the Process tab.
-        //
-        // Long-running handoff (bin-spawn contract): when invoked from a
-        // wrapper that already allocated a pid (`npm run dev` via
-        // shellExecuteTracked, or the npm-bin resolver), ADOPT that pid instead
-        // of spawning a second one. One pid, one start banner, no false exit —
-        // the wrapper stays `running` in /api/processes with this port.
-        const binSpawn = ctx.__nimbusBinSpawn;
-        const adoptedEntry = binSpawn?.skipSpawn && binSpawn.callerPid != null
-            ? self.processes.get(binSpawn.callerPid)
-            : undefined;
-        const handedOff = adoptedEntry != null;
-        const viteProcEntry = adoptedEntry ?? self.processes.spawn('vite (' + vfsRoot + ')', expandedArgs, vfsRoot, { longRunning: true });
-        if (handedOff)
-            self.processes.setLongRunning(viteProcEntry.pid);
-        self.viteDevServer = new ViteDevServer({
-            vfs: self.sqliteFs,
-            esbuild: self.esbuildService,
-            root: vfsRoot,
-            port: resolvedPort,
-            aliases: viteConfig.alias,
-            define: viteDefine,
-            onHmrMessage: (msg) => {
-                if (self.terminal)
-                    try {
-                        self.terminal.ws.send(JSON.stringify({ type: 'hmr', data: msg }));
-                    }
-                    catch { }
-            },
-            sql: self.ctx.storage.sql,
-            injectBasename: viteConfig.injectBasename,
-            basePath: previewBasePath,
-            env: self.env,
-            ctx: self.ctx,
-            // process diagnostics support: wire dev-server diagnostics into the
-            // supervisor's per-PID log store so the Process tab is no
-            // longer silent after the banner.
-            pid: viteProcEntry.pid,
-            processes: self.processes,
-        });
-        self.viteDevServer.start();
-        try {
-            await self.ctx.storage.put(VITE_CONFIG_KEY, {
-                root: vfsRoot, aliases: viteConfig.alias, define: viteDefine,
-                injectBasename: viteConfig.injectBasename, basePath: previewBasePath,
-                port: resolvedPort,
-            });
-        }
-        catch { }
-        // Register the port and build the long-running stub. The stub
-        // forwards into the in-process viteDevServer through the generic
-        // long-running adapter — same hook every future long-running
-        // facet uses (Express, Bun.serve, http.createServer().listen()).
-        const viteStub = makeLongRunningPortStub(self.viteDevServer);
-        self.portRegistry.bindFacetStub(viteProcEntry.pid, viteStub);
-        await clearPortCapability(self, resolvedPort);
-        self.portRegistry.register(resolvedPort, viteProcEntry.pid);
-        // Track the wiring so `vite stop` and crash-handlers can tear it
-        // down without searching the registry.
-        self._viteShimPid = viteProcEntry.pid;
-        self._viteShimPort = resolvedPort;
-        // Spawn / long-running event for the Process tab UI. Mirrors the
-        // shellExecuteTracked banner so the user sees the same shape no
-        // matter how vite was invoked. Suppressed on handoff — the wrapper
-        // already emitted the single start banner and spawn event for this pid.
-        if (!handedOff) {
-            if (self.terminal) {
-                self.terminal.write(`\x1b[2m[shell started (long-running): pid=${viteProcEntry.pid} cmd="vite ${expandedArgs.join(' ')}"]\x1b[0m\r\n`);
-            }
-            notifyTerminalEvent(self.terminal, {
-                type: 'spawn',
-                pid: viteProcEntry.pid,
-                command: 'vite ' + expandedArgs.join(' '),
-                longRunning: true,
-                attachedTty: false,
-            });
-        }
-        // Banner — reports the resolved port and PID so the user can
-        // verify the multi-target routing.
-        ctx.stdout.write('\n\x1b[1;36m  Nimbus Vite Dev Server\x1b[0m\n\n');
-        ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Preview:    \x1b[36m' + previewBasePath + '/\x1b[0m');
-        if (resolvedPort !== vitePortDefault) {
-            ctx.stdout.write('  \x1b[2m(also: ' + previewBasePath + '/?port=' + resolvedPort + ')\x1b[0m');
-        }
-        ctx.stdout.write('\n');
-        ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Root:       ' + vfsRoot + '\n');
-        ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Port:       ' + resolvedPort + ' \x1b[2m(pid=' + viteProcEntry.pid + ')\x1b[0m\n');
-        ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Transforms: .ts .tsx .jsx (React JSX automatic)\n');
-        if (viteConfig.alias)
-            ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Aliases:    ' + Object.keys(viteConfig.alias).join(', ') + '\n');
-        if (viteDefine)
-            ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Define:     ' + Object.keys(viteDefine).join(', ') + '\n');
-        const twCfg = [vfsRoot + '/tailwind.config.js', vfsRoot + '/tailwind.config.ts'].find(p => kernelFs.exists(p));
-        if (twCfg)
-            ctx.stdout.write('  \x1b[32m\u279C\x1b[0m  Tailwind:   edge-vendored Play CDN \x1b[2m(detected)\x1b[0m\n');
-        ctx.stdout.write('\n  \x1b[2mRun \x1b[0mvite stop\x1b[2m, or \x1b[0mkill ' + viteProcEntry.pid + '\x1b[2m, to stop.\x1b[0m\n\n');
-        return 0;
-    });
+    registry.register('vite', createViteCommand(self));
     // ── nimbus-wrangler / wrangler command: Worker dev server ─────────────
     //
     // `wrangler` is registered as a transparent alias for `nimbus-wrangler`
@@ -1742,8 +1298,8 @@ export async function initSession(self, ws) {
         const result = await shell.execute(cmd, {
             cwd: cmdCtx.cwd,
             env: cmdCtx.env,
-            onStdout: (d) => cmdCtx.stdout.write(d),
-            onStderr: (d) => cmdCtx.stderr.write(d),
+            onStdout: textSink((d) => cmdCtx.stdout.write(d)),
+            onStderr: textSink((d) => cmdCtx.stderr.write(d)),
             stdin,
             terminalStdin: cmdCtx.terminalStdin,
             // `npm run x` runs x on npm's own fds. Handing the nested execution a
@@ -1821,15 +1377,18 @@ export async function initSession(self, ws) {
         });
         // Wrap the caller-supplied streams so every chunk is both displayed
         // AND captured in the ring buffer keyed by this PID.
-        const tee = (stream, target) => (d) => {
-            try {
-                self.processes.appendOutput(pid, stream, String(d));
-            }
-            catch { }
-            try {
-                target.write(d);
-            }
-            catch { }
+        const tee = (stream, target) => {
+            const toTarget = textSink((text) => target.write(text));
+            return (d) => {
+                try {
+                    self.processes.appendOutputBytes(pid, stream, d);
+                }
+                catch { }
+                try {
+                    toTarget(d);
+                }
+                catch { }
+            };
         };
         let exitCode = 1;
         try {
@@ -1872,7 +1431,15 @@ export async function initSession(self, ws) {
         catch (e) {
             // Surface the error in the terminal and the ring buffer.
             const msg = (e && (e.stack || e.message)) || String(e);
-            tee('stderr', cmdCtx.stderr)('shellExecuteTracked error: ' + msg + '\n');
+            const line = 'shellExecuteTracked error: ' + msg + '\n';
+            try {
+                self.processes.appendOutput(pid, 'stderr', line);
+            }
+            catch { }
+            try {
+                cmdCtx.stderr.write(line);
+            }
+            catch { }
             exitCode = 1;
         }
         finally {
@@ -1927,8 +1494,11 @@ export async function initSession(self, ws) {
             catch { }
         },
     });
-    // Register core npm with enhanced `npm run <script>` support
-    const coreNpmCmd = createNpmCommand(registry, shellExecute, kernel);
+    // Register core npm — the install work itself goes through the port,
+    // which owns the NpmInstaller, prefix dirs and bin materialisation.
+    const coreNpmCmd = createNpmCommand(registry, shellExecute, kernel, {
+        installer: createNpmInstallPort(self),
+    });
     registry.register('npm', async (ctx) => {
         const args = ctx.args || [];
         const sub = args[0];
@@ -2012,26 +1582,17 @@ export async function initSession(self, ws) {
                 // (the only thing the module did was hold these strings) and
                 // the file is deleted.
                 //
-                // Next.js dev/start still needs a custom http.Server +
-                // child_process.fork with v8-IPC + webpack/Turbopack, none of
-                // which Nimbus ships. We surface a deterministic message
-                // rather than letting the script hang or emit a confusing
-                // crash. The block remains a one-off symbol-detection
-                // guard, NOT a generic per-framework code path. Any future
-                // similar guard belongs alongside this one — not in its own
-                // src/frameworks/<name>.ts file.
-                if ((scriptName === 'dev' || scriptName === 'start') &&
-                    (pkg.dependencies?.next || pkg.devDependencies?.next) &&
-                    !(scriptArgs.includes('--force') || scriptArgs.includes('--allow-next'))) {
-                    const NEXT_BLOCK_MESSAGE = '\x1b[31m\u2718\x1b[0m \x1b[1mNext.js dev server is not supported in Nimbus.\x1b[0m\n' +
-                        '   Specific blockers:\n' +
-                        "     1. \x1b[2mchild_process.fork\x1b[0m IPC uses v8-serializer (Nimbus ships JSON projection).\n" +
-                        '     2. webpack / Turbopack bundlers are not integrated with the pre-bundle pipeline.\n' +
-                        '     3. Custom \x1b[2mhttp.Server\x1b[0m semantics (keep-alive, raw sockets) are facet-incompatible.\n' +
-                        '\n' +
-                        '   Workaround: deploy with \x1b[36mnext build\x1b[0m + a hosted runtime,\n' +
-                        '   or pass \x1b[36m--allow-next\x1b[0m to bypass at your own risk.\n';
-                    ctx.stderr.write(NEXT_BLOCK_MESSAGE);
+                // Next.js dev/start/build/export all need the same pipeline —
+                // custom http.Server + child_process.fork with v8-IPC +
+                // webpack/Turbopack — none of which Nimbus ships. We surface a
+                // deterministic refusal rather than letting the script hang or
+                // (build) reset the isolate during spawn. The block remains a
+                // one-off symbol-detection guard, NOT a generic per-framework
+                // code path. Any future similar guard belongs alongside this
+                // one — not in its own src/frameworks/<name>.ts file.
+                const refused = refusedNextSubcommand(scriptName, script, pkg, scriptArgs);
+                if (refused) {
+                    ctx.stderr.write(NEXT_REFUSAL_MESSAGE);
                     return 127;
                 }
                 const scriptTrim = script.trim();
@@ -2141,85 +1702,6 @@ export async function initSession(self, ws) {
             catch { }
             return 0;
         }
-        // npm install (no args or with packages) — use NpmInstaller v2 (batched writes)
-        if (sub === 'install' || sub === 'i' || sub === 'add') {
-            const installInvocation = parseNpmInstallInvocation(args.slice(1));
-            const explicitPkgs = installInvocation.packages;
-            const globalPrefix = installInvocation.global
-                ? resolveNpmPrefix(installInvocation.prefix ?? String(ctx.env?.npm_config_prefix || '/usr/local'), ctx.cwd || '/home/user')
-                : null;
-            self.ensureSqliteFs();
-            if (globalPrefix)
-                self.ensureGlobalPrefixDirs(globalPrefix);
-            const installCwd = globalPrefix ? `${globalPrefix}/lib` : cwdKey;
-            // Ensure package.json exists for bare `npm install`
-            if (!globalPrefix && explicitPkgs.length === 0) {
-                const pkgJsonPath = installCwd + '/package.json';
-                if (!kernelFs.exists(pkgJsonPath)) {
-                    ctx.stderr.write('npm ERR! no package.json found\n');
-                    return 1;
-                }
-            }
-            if (globalPrefix && explicitPkgs.length === 0) {
-                ctx.stderr.write('npm ERR! missing package name for global install\n');
-                return 1;
-            }
-            const pkgLabel = explicitPkgs.length > 0
-                ? `${explicitPkgs.length} packages`
-                : 'dependencies from package.json';
-            ctx.stdout.write(`\x1b[36mInstalling ${pkgLabel} (npm v2 — batched writes)...\x1b[0m\n`);
-            await self.ensureNpmInstaller((msg) => {
-                ctx.stdout.write('[npm] ' + msg + '\n');
-            });
-            // `--loglevel` selects npm's own log protocol on stderr, where npm
-            // writes it. Tooling that drives npm parses those lines rather than
-            // our prose — pi's installer advances its progress label off them.
-            const npmLogLevel = installInvocation.loglevel;
-            const npmLog = npmLogLevel === null ? undefined : ((level, line) => {
-                if (npmLogEnabled(npmLogLevel, level))
-                    ctx.stderr.write(line + '\n');
-            });
-            try {
-                const result = await self.npmInstaller.install(installCwd, {
-                    packages: explicitPkgs.length > 0 ? explicitPkgs : undefined,
-                    production: installInvocation.production,
-                    pid: ctx.pid,
-                    npmLog,
-                });
-                if (result.failed?.length > 0) {
-                    ctx.stderr.write('\x1b[31mFailed: ' + result.failed.join(', ') + '\x1b[0m\n');
-                }
-                // [HONEST INSTALL MESSAGE P0a] Yellow + "(N failed, see above)"
-                // when partial. Green only when failed.length === 0.
-                const partial = (result.failed?.length || 0) > 0;
-                const color = partial ? '\x1b[33m' : '\x1b[32m';
-                const suffix = partial ? ` (${result.failed.length} failed, see above)` : '';
-                ctx.stdout.write(`\n${color}added ${result.installed?.length || 0} packages (${result.totalFiles || 0} files) in ${((result.elapsed || 0) / 1000).toFixed(1)}s${suffix}\x1b[0m\n`);
-                if (result.cachedHits > 0) {
-                    ctx.stdout.write(`\x1b[2m  (${result.cachedHits} from cache)\x1b[0m\n`);
-                }
-                if (globalPrefix) {
-                    // Materialize on-PATH bin shims even for partial installs. The
-                    // only writer of shims into ${globalPrefix}/bin used to be gated
-                    // behind zero failures across the whole dependency tree — but a
-                    // global install of a 100+-dep package almost always has at least
-                    // one transitive failure, so /usr/local/bin was ~never created
-                    // and the installed package's bin was unreachable. materialize →
-                    // validateEntry → resolveExistingTarget already skips bins whose
-                    // target file didn't land, so a partial install safely exposes
-                    // exactly the bins that actually installed.
-                    const linked = materializeNpmBinShims(kernelFs, `${installCwd}/node_modules`, `${globalPrefix}/bin`);
-                    if (linked > 0) {
-                        ctx.stdout.write(`\x1b[2m  linked ${linked} bin${linked === 1 ? '' : 's'} into /${globalPrefix}/bin\x1b[0m\n`);
-                    }
-                }
-                return result.failed?.length > 0 ? 1 : 0;
-            }
-            catch (e) {
-                ctx.stderr.write(`\x1b[31mnpm install failed: ${e?.message}\x1b[0m\n`);
-                return 1;
-            }
-        }
         // ── npm create <pkg> / npm init <pkg> → npx create-<pkg> ─────────
         //
         // Per the npm spec, `npm create X args...` and `npm init X args...`
@@ -2638,17 +2120,17 @@ export async function initSession(self, ws) {
         catch { }
         // ── Starter-app hint (only if seed sentinel still exists) ──
         // We check the live VFS, not a static file, so that if the user
-        // deletes ~/.nimbus-seeded (or ~/app) the hint stops appearing on
-        // next login.
+        // deletes ~/.nimbus-seeded (or the project dir) the hint stops
+        // appearing on next login.
         try {
             if (hasSeededProject(self.sqliteFs) && kernelFs.exists(SEED_PROJECT_DIR)) {
-                self.terminal.write('\x1b[2mStarter app ready at \x1b[36m~/app\x1b[0m\x1b[2m — try:\x1b[0m\r\n' +
-                    '  \x1b[36mcd app && npm install && npm run dev\x1b[0m\r\n\r\n');
+                self.terminal.write(`\x1b[2mStarter app ready at \x1b[36m${SEED_PROJECT_TILDE}\x1b[0m\x1b[2m — try:\x1b[0m\r\n` +
+                    `  \x1b[36mcd ${SEED_PROJECT_NAME} && npm install && npm run dev\x1b[0m\r\n\r\n`);
             }
         }
         catch { }
         // ── W11: framework detection MOTD line ──
-        // If ~/app has a recognizable framework, print one informational line.
+        // If the seeded project dir has a recognizable framework, print one informational line.
         // Purely advisory — does not change boot behaviour. Fire-and-forget
         // because initSession is sync; any failure is silently swallowed.
         void (async () => {
@@ -2729,13 +2211,19 @@ export async function initSession(self, ws) {
     // ── Start shell ──
     //
     // Now, and not inside the workspace, because the login files are the
-    // user's and may name any of the commands registered above. Not awaited:
-    // `shell.start()` runs synchronously and the rc files apply as they
-    // finish, which is what the terminal has always done. A user's broken
-    // rc file must not take the socket down with it.
-    workspace.start().catch((e) => {
-        console.warn('[nimbus] shell start failed:', e?.message || e);
+    // user's and may name any of the commands registered above. On a
+    // reconnect it is not awaited: `shell.start()` registers the input
+    // handler synchronously and the rc files apply as they finish, which is
+    // what the terminal has always done. On a wake the caller has the
+    // peer's frame in hand and delivers it the moment this returns, so the
+    // prompt has to be on the terminal first — otherwise the line runs
+    // alongside the rc files and its prompt lands before the shell's own.
+    // Either way a user's broken rc file must not take the socket down.
+    const started = workspace.start().catch((e) => {
+        console.warn('[nimbus] shell start failed:', errorText(e));
     });
+    if (options.resume === 'wake')
+        await started;
     ws.send(JSON.stringify({ type: 'ready' }));
 }
 function installShellExecutionFeatures(shell, terminal) {