@amodalai/amodal 0.3.48 → 0.3.50

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @amodalai/amodal
 
+## 0.3.50
+
+### Patch Changes
+
+- Updated dependencies [1a0732b]
+- Updated dependencies [1a0732b]
+- Updated dependencies [1a0732b]
+- Updated dependencies [1a0732b]
+- Updated dependencies [1a0732b]
+- Updated dependencies [1a0732b]
+- Updated dependencies [1a0732b]
+- Updated dependencies [1a0732b]
+- Updated dependencies [1a0732b]
+- Updated dependencies [1a0732b]
+- Updated dependencies [1a0732b]
+  - @amodalai/types@0.3.50
+  - @amodalai/runtime@0.3.50
+  - @amodalai/studio@0.3.50
+  - @amodalai/core@0.3.50
+  - @amodalai/db@0.3.50
+  - @amodalai/runtime-app@0.3.50
+
+## 0.3.49
+
+### Patch Changes
+
+- Updated dependencies [fadad93]
+  - @amodalai/runtime@0.3.49
+  - @amodalai/types@0.3.49
+  - @amodalai/core@0.3.49
+  - @amodalai/runtime-app@0.3.49
+  - @amodalai/db@0.3.49
+  - @amodalai/studio@0.3.49
+
 ## 0.3.48
 
 ### Patch Changes

package/dist/src/commands/dev.d.ts

@@ -7,8 +7,6 @@ import type { CommandModule } from 'yargs';
 export interface DevOptions {
     cwd?: string;
     port?: number;
-    studioPort?: number;
-    adminPort?: number;
     host?: string;
     resume?: string;
     verbose?: number;
@@ -18,6 +16,34 @@ export interface DevOptions {
     /** Disable admin agent subprocess. */
     noAdmin?: boolean;
 }
+/**
+ * Pipe a child process's stdout/stderr to the parent's stderr, prefixed
+ * with a label. Lines are buffered per-stream to avoid interleaved output
+ * from concurrent subprocesses.
+ */
+/**
+ * Predicate for pipeWithLabel's quiet mode. Exported for unit tests so a
+ * format change in the runtime logger can't silently break dev observability.
+ *
+ * Passes warnings/errors and the Phase 4 intent-routing telemetry through
+ * (the latter is exactly what makes intent vs LLM ratios visible in dev).
+ */
+export declare function passesQuietFilter(line: string): boolean;
+/**
+ * Best-effort pretty-printer for routing telemetry. The runtime emits
+ * `[INFO] route_intent {…json…}` style lines (for production aggregators);
+ * in the dev terminal that's mostly visual noise. This rewrites the few
+ * route/intent lifecycle events into one-liner status lines so a human
+ * scanning their terminal can answer "is intent routing working?" at a
+ * glance. Falls back to the original line when parsing fails so we never
+ * eat a line that the user might need.
+ *
+ * Returns:
+ *   - a string (possibly the same as input) — print it verbatim
+ *   - null — suppress the line entirely (e.g. dropping intent_matched
+ *     once route_intent has already been printed for the same turn)
+ */
+export declare function formatLineForDev(line: string): string | null;
 /**
  * Starts a local development server for the repo with hot reload enabled,
  * and optionally spawns Studio and admin agent as subprocesses.

package/dist/src/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/commands/dev.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,OAAO,CAAC;AAwEzC,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAkRD;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAoPpE;AAED,eAAO,MAAM,UAAU,EAAE,aA2ExB,CAAC"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/commands/dev.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,OAAO,CAAC;AA0EzC,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAYD;;;;GAIG;AACH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA8E5D;AAuQD;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAgYpE;AAED,eAAO,MAAM,UAAU,EAAE,aA8DxB,CAAC"}

package/dist/src/commands/dev.js

@@ -3,14 +3,14 @@
  * Copyright 2025 Amodal Labs, Inc.
  * SPDX-License-Identifier: MIT
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createLocalServer, initLogLevel, interceptConsole, log } from '@amodalai/runtime';
 import { ensureAdminAgent, getAdminAgentConfig, getAdminAgentVersion, checkRegistryVersion } from '@amodalai/core';
-import { findRepoRoot } from '../shared/repo-discovery.js';
+import { findRepoRootOrCwd } from '../shared/repo-discovery.js';
 import { createServer } from 'node:net';
 import { runConnectionPreflight, printPreflightTable } from '../shared/connection-preflight.js';
 import { resolveEnv } from '../shared/env-resolution.js';
@@ -19,6 +19,8 @@ import { getDb, ensureSchema, closeDb } from '@amodalai/db';
 // Constants
 // ---------------------------------------------------------------------------
 const DEFAULT_RUNTIME_PORT = 3847;
+const DEFAULT_STUDIO_PORT = 3848;
+const DEFAULT_ADMIN_PORT = 3849;
 // ---------------------------------------------------------------------------
 // Port checking
 // ---------------------------------------------------------------------------
@@ -66,9 +68,122 @@ function resolveStudioDir() {
  * with a label. Lines are buffered per-stream to avoid interleaved output
  * from concurrent subprocesses.
  */
+/**
+ * Predicate for pipeWithLabel's quiet mode. Exported for unit tests so a
+ * format change in the runtime logger can't silently break dev observability.
+ *
+ * Passes warnings/errors and the Phase 4 intent-routing telemetry through
+ * (the latter is exactly what makes intent vs LLM ratios visible in dev).
+ */
+export function passesQuietFilter(line) {
+    return (line.includes('[WARN]') ||
+        line.includes('[ERROR]') ||
+        line.includes('Error') ||
+        line.includes('intent_') ||
+        line.includes('agent_loop_start') ||
+        line.includes('route_intent') ||
+        line.includes('route_llm'));
+}
+/**
+ * Best-effort pretty-printer for routing telemetry. The runtime emits
+ * `[INFO] route_intent {…json…}` style lines (for production aggregators);
+ * in the dev terminal that's mostly visual noise. This rewrites the few
+ * route/intent lifecycle events into one-liner status lines so a human
+ * scanning their terminal can answer "is intent routing working?" at a
+ * glance. Falls back to the original line when parsing fails so we never
+ * eat a line that the user might need.
+ *
+ * Returns:
+ *   - a string (possibly the same as input) — print it verbatim
+ *   - null — suppress the line entirely (e.g. dropping intent_matched
+ *     once route_intent has already been printed for the same turn)
+ */
+export function formatLineForDev(line) {
+    // Only touch our recognized events. Match `[LEVEL] event_name {json}` form.
+    const m = /^\[(INFO|WARN|ERROR)\] ([a-z_]+) (\{.*\})\s*$/.exec(line);
+    if (!m)
+        return line;
+    const [, , event, jsonStr] = m;
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonStr);
+    }
+    catch {
+        return line;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return line;
+    }
+    const data = Object.fromEntries(Object.entries(parsed));
+    const str = (k) => typeof data[k] === 'string' ? (data[k]) : '';
+    const num = (k) => typeof data[k] === 'number' ? (data[k]) : 0;
+    switch (event) {
+        case 'route_intent': {
+            const preview = str('userMessagePreview');
+            return `→ INTENT  ${str('intentId').padEnd(22)} "${preview}"`;
+        }
+        case 'route_llm': {
+            const reason = str('reason');
+            const detail = str('intentId') || str('userMessagePreview');
+            return `→ LLM     ${reason.padEnd(22)} ${detail ? `"${detail}"` : ''}`.trimEnd();
+        }
+        case 'intent_completed': {
+            const toolCount = num('toolCount');
+            const ms = num('durationMs');
+            return `  ✓ ${str('intentId')} done (${String(toolCount)} tools, ${String(ms)}ms)`;
+        }
+        case 'intent_fell_through': {
+            const ms = num('durationMs');
+            return `  ↓ ${str('intentId')} fell through to LLM (${String(ms)}ms)`;
+        }
+        case 'intent_errored': {
+            return `  ✗ ${str('intentId')} ERRORED: ${str('error')}`;
+        }
+        case 'intent_blocked_by_confirmation': {
+            return `  ✗ ${str('intentId')} blocked: ${str('toolName')} requires confirmation`;
+        }
+        case 'intent_returned_null_after_committing': {
+            return `  ⚠ ${str('intentId')} returned null after ${String(num('toolCallsStarted'))} tool calls — treating as completion`;
+        }
+        case 'intent_matched':
+        case 'agent_loop_start': {
+            // Both are redundant in dev: intent_matched duplicates the
+            // route_intent line that fires a millisecond earlier, and
+            // agent_loop_start always follows a route_llm line (manager.ts
+            // emits route_llm immediately before invoking the LLM). Drop
+            // them to keep the dev terminal scannable; production
+            // aggregators still get them on stderr from the runtime
+            // process directly (this formatter only runs in pipeWithLabel).
+            return null;
+        }
+        case 'tool_log': {
+            // Tools call ctx.log(...) for noteworthy progress (e.g.
+            // install_template emits "Cloned whodatdev/template-X into
+            // agent repo (N connection packages installed)"). When fired
+            // during an intent run the callId starts with `intent_`, so
+            // these lines pass the quiet filter — but as raw JSON they
+            // bury the useful message inside callId/session noise. Strip
+            // to a clean nested bullet.
+            const msg = str('message');
+            if (!msg)
+                return null;
+            return `    · ${msg}`;
+        }
+        default:
+            return line;
+    }
+}
 function pipeWithLabel(child, label, opts) {
     const prefix = `[${label}] `;
     const quiet = opts?.quiet ?? false;
+    const writeLine = (line) => {
+        if (quiet && !passesQuietFilter(line))
+            return;
+        const pretty = formatLineForDev(line);
+        if (pretty === null)
+            return;
+        process.stderr.write(`${prefix}${pretty}\n`);
+    };
     for (const stream of [child.stdout, child.stderr]) {
         if (!stream)
             continue;
@@ -78,17 +193,12 @@ function pipeWithLabel(child, label, opts) {
             buffer += chunk;
             const lines = buffer.split('\n');
             buffer = lines.pop() ?? '';
-            for (const line of lines) {
-                if (quiet && !line.includes('[WARN]') && !line.includes('[ERROR]') && !line.includes('Error'))
-                    continue;
-                process.stderr.write(`${prefix}${line}\n`);
-            }
+            for (const line of lines)
+                writeLine(line);
         });
         stream.on('end', () => {
             if (buffer.length > 0) {
-                if (!quiet || buffer.includes('[WARN]') || buffer.includes('[ERROR]') || buffer.includes('Error')) {
-                    process.stderr.write(`${prefix}${buffer}\n`);
-                }
+                writeLine(buffer);
                 buffer = '';
             }
         });
@@ -136,7 +246,6 @@ function spawnStudio(opts) {
         HOSTNAME: '0.0.0.0',
         ...(opts.agentId ? { AGENT_ID: opts.agentId } : {}),
         ...(opts.adminAgentUrl ? { ADMIN_AGENT_URL: opts.adminAgentUrl } : {}),
-        ...(opts.basePath ? { BASE_PATH: opts.basePath } : {}),
     };
     // Pre-built server (npm install): dist-server/studio-server.js
     // Source mode (monorepo dev): src/server/studio-server.ts via tsx
@@ -244,6 +353,9 @@ async function spawnAdminAgent(opts) {
         AMODAL_NO_STUDIO: '1',
         REPO_PATH: opts.repoPath,
     };
+    if (opts.studioUrl) {
+        env['STUDIO_URL'] = opts.studioUrl;
+    }
     const child = spawn(process.execPath, [cliEntrypoint, 'dev', '--port', String(opts.port)], {
         cwd: adminAgentPath,
         env,
@@ -274,25 +386,13 @@ async function spawnAdminAgent(opts) {
 export async function runDev(options = {}) {
     initLogLevel({ verbosity: options.verbose ?? 0, quiet: options.quiet ?? false });
     interceptConsole();
-    let repoPath;
-    try {
-        repoPath = findRepoRoot(options.cwd);
-    }
-    catch {
-        process.stderr.write(`
-  No amodal.json found.
-
-  Create a new agent:
-
-    amodal init        Initialize this directory
-    amodal dev         Start the dev server
-
-  Or if your agent is in another directory:
-
-    cd /path/to/agent && amodal dev
-
-`);
-        process.exit(1);
+    // Empty directories are allowed: the create flow in Studio scaffolds
+    // amodal.json from a chosen template (or admin-agent conversation), so
+    // the user can `amodal dev` before they have a project at all. We just
+    // skip the runtime in that case — it can't loadRepo without a manifest.
+    const { root: repoPath, hasManifest } = findRepoRootOrCwd(options.cwd);
+    if (!hasManifest) {
+        log.info('dev_create_flow_mode', { repoPath });
     }
     // -------------------------------------------------------------------------
     // Require DATABASE_URL
@@ -319,7 +419,18 @@ Or add it to your agent's .env file:
     }
     // Make DATABASE_URL available to child processes (runtime, Studio)
     process.env['DATABASE_URL'] = databaseUrl;
-    // Read agent name from amodal.json for AGENT_ID
+    // Resolve AGENT_ID — must be set BEFORE spawning subprocesses so
+    // Studio, runtime, and admin-agent all key `setup_state` rows by
+    // the same id. Three sources, in priority order:
+    //   1. amodal.json#name when the file exists (post-setup repos)
+    //   2. The repo dir basename (pre-setup repos — what the user calls
+    //      their working directory; stable across the setup flow)
+    //   3. 'default' as a last-ditch fallback
+    // Without this, the admin-agent process would compute its own id
+    // from its own bundle (name: "admin") and Studio's `getAgentId()`
+    // would fall back to "default", leaving `commit_setup` marking a
+    // different row than Studio reads — IndexPage would loop the user
+    // back to /setup even after a successful commit.
     const amodalJsonPath = path.join(repoPath, 'amodal.json');
     let agentId;
     if (existsSync(amodalJsonPath)) {
@@ -332,7 +443,6 @@ Or add it to your agent's .env file:
             const nameValue = parsed !== undefined ? parsed['name'] : undefined;
             if (typeof nameValue === 'string') {
                 agentId = nameValue;
-                process.env['AGENT_ID'] = agentId;
             }
         }
         catch (err) {
@@ -342,6 +452,14 @@ Or add it to your agent's .env file:
             });
         }
     }
+    if (!agentId) {
+        // Pre-setup fallback. `path.basename(repoPath)` gives "test-empty"
+        // or whatever the user named their working dir — stable enough
+        // for setup_state coordination, and the agent name will switch
+        // to amodal.json#name on the next CLI invocation post-commit.
+        agentId = path.basename(repoPath) || 'default';
+    }
+    process.env['AGENT_ID'] = agentId;
     // -------------------------------------------------------------------------
     // Run schema migrations
     // -------------------------------------------------------------------------
@@ -363,15 +481,17 @@ Or add it to your agent's .env file:
     // Port allocation
     // -------------------------------------------------------------------------
     const runtimePort = options.port ?? DEFAULT_RUNTIME_PORT;
-    const studioPort = options.studioPort ?? runtimePort + 1;
-    const adminPort = options.adminPort ?? runtimePort + 2;
-    await assertPortFree(runtimePort);
+    const studioPort = DEFAULT_STUDIO_PORT;
+    const adminPort = DEFAULT_ADMIN_PORT;
+    if (hasManifest) {
+        await assertPortFree(runtimePort);
+    }
     if (!options.noStudio)
         await assertPortFree(studioPort);
     if (!options.noAdmin)
         await assertPortFree(adminPort);
     log.debug('ports_allocated', {
-        runtime: runtimePort,
+        runtime: hasManifest ? runtimePort : null,
         studio: options.noStudio ? null : studioPort,
         admin: options.noAdmin ? null : adminPort,
     });
@@ -408,44 +528,63 @@ Or add it to your agent's .env file:
         }
     }
     // -------------------------------------------------------------------------
-    // Start the runtime server
+    // Start the runtime server (skipped when there's no amodal.json — the
+    // runtime can't loadRepo on an empty directory; the create flow in Studio
+    // takes the user from an empty repo to a configured one, after which they
+    // ctrl+C and re-run `amodal dev` to pick up the runtime).
     // -------------------------------------------------------------------------
-    log.debug('starting_dev_server', { repoPath });
+    log.debug('starting_dev_server', { repoPath, hasManifest });
     try {
-        let staticAppDir;
-        // Use pre-built static assets for the SPA.
-        // Vite dev middleware is only used inside the monorepo with `pnpm dev`.
-        const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-        const candidates = [
-            // esbuild bundle: bundle/app/
-            path.resolve(scriptDir, 'app'),
-        ];
-        // Resolve @amodalai/runtime-app via Node module resolution (works regardless of install layout)
-        const require = createRequire(import.meta.url);
-        const runtimeAppPkg = require.resolve('@amodalai/runtime-app/package.json');
-        candidates.push(path.join(path.dirname(runtimeAppPkg), 'dist'));
-        for (const dir of candidates) {
-            if (existsSync(path.join(dir, 'index.html'))) {
-                log.debug('serving_prebuilt_app', { path: staticAppDir });
-                staticAppDir = dir;
-                break;
+        let server = null;
+        /**
+         * Boot the runtime server. Factored out so the empty-repo
+         * branch (Phase E.9) can call it lazily when amodal.json lands.
+         */
+        const bootRuntime = async () => {
+            let staticAppDir;
+            // Use pre-built static assets for the SPA.
+            // Vite dev middleware is only used inside the monorepo with `pnpm dev`.
+            const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+            const candidates = [
+                // esbuild bundle: bundle/app/
+                path.resolve(scriptDir, 'app'),
+            ];
+            // Resolve @amodalai/runtime-app via Node module resolution (works regardless of install layout)
+            const require = createRequire(import.meta.url);
+            const runtimeAppPkg = require.resolve('@amodalai/runtime-app/package.json');
+            candidates.push(path.join(path.dirname(runtimeAppPkg), 'dist'));
+            for (const dir of candidates) {
+                if (existsSync(path.join(dir, 'index.html'))) {
+                    log.debug('serving_prebuilt_app', { path: staticAppDir });
+                    staticAppDir = dir;
+                    break;
+                }
             }
+            const created = await createLocalServer({
+                repoPath,
+                port: runtimePort,
+                host,
+                hotReload: true,
+                corsOrigin: '*',
+                staticAppDir,
+                resumeSessionId: options.resume,
+                studioUrl: studioUrl ?? undefined,
+                adminAgentUrl: adminAgentUrl ?? undefined,
+            });
+            await created.start();
+            return created;
+        };
+        if (hasManifest) {
+            server = await bootRuntime();
         }
-        const server = await createLocalServer({
-            repoPath,
-            port: runtimePort,
-            host,
-            hotReload: true,
-            corsOrigin: '*',
-            staticAppDir,
-            resumeSessionId: options.resume,
-            studioUrl: studioUrl ?? undefined,
-            adminAgentUrl: adminAgentUrl ?? undefined,
-        });
-        await server.start();
         // Print clean startup summary
         process.stderr.write('\n');
-        process.stderr.write(`  Runtime:     http://localhost:${String(runtimePort)}\n`);
+        if (server) {
+            process.stderr.write(`  Runtime:     http://localhost:${String(runtimePort)}\n`);
+        }
+        else {
+            process.stderr.write('  Runtime:     waiting for amodal.json (auto-boots when Studio finishes setup)\n');
+        }
         if (studioUrl) {
             process.stderr.write(`  Studio:      ${studioUrl}\n`);
         }
@@ -455,25 +594,130 @@ Or add it to your agent's .env file:
         const redactedUrl = databaseUrl.replace(/\/\/([^:]+):([^@]+)@/, '//$1:***@');
         process.stderr.write(`  Database:    ${redactedUrl}\n`);
         process.stderr.write('\n');
-        // Preflight connection check (non-blocking)
-        const preflight = await runConnectionPreflight(repoPath);
-        if (preflight.results.length > 0) {
-            process.stderr.write('\n');
-            printPreflightTable(preflight.results);
-            if (preflight.hasFailures) {
-                process.stderr.write('\n  WARNING: Some connections failed. The agent may not work correctly.\n');
+        // Preflight connection check (non-blocking) — only meaningful when
+        // there's a manifest to load connections from.
+        if (hasManifest) {
+            const preflight = await runConnectionPreflight(repoPath);
+            if (preflight.results.length > 0) {
+                process.stderr.write('\n');
+                printPreflightTable(preflight.results);
+                if (preflight.hasFailures) {
+                    process.stderr.write('\n  WARNING: Some connections failed. The agent may not work correctly.\n');
+                }
+                process.stderr.write('\n');
             }
-            process.stderr.write('\n');
         }
+        // -------------------------------------------------------------------
+        // Phase E.9 — runtime auto-(re)spawn on amodal.json change.
+        //
+        // Two flows watched by the same poller:
+        //
+        //   1. AUTO-BOOT — runtime didn't start at CLI launch (no manifest
+        //      yet). Once amodal.json lands (commit_setup, the user-button
+        //      commit-setup endpoint, or init-repo's skip-onboarding
+        //      write), boot the runtime in place. Studio's runtime URL
+        //      probe picks it up on the next tick.
+        //
+        //   2. AUTO-RESTART — runtime is already up but amodal.json has
+        //      been rewritten since the last spawn. Happens after a
+        //      Restart-Setup → re-commit, or when the user edits
+        //      amodal.json by hand (adding a connection package, etc.).
+        //      Without a restart, the running runtime keeps the stale
+        //      bundle in memory and the new packages/config never load.
+        //
+        // 500ms debounce after detecting a change — lets the writer
+        // (commit_setup's atomic rename, init-repo's full write) settle
+        // before loadRepo tries to read.
+        // -------------------------------------------------------------------
+        const RUNTIME_WATCH_INTERVAL_MS = 2_000;
+        let runtimeWatcher = null;
+        let lastManifestMtime = null;
+        const stopRuntimeWatch = () => {
+            if (runtimeWatcher !== null) {
+                clearTimeout(runtimeWatcher);
+                runtimeWatcher = null;
+            }
+        };
+        const manifestPath = path.join(repoPath, 'amodal.json');
+        /**
+         * Read the manifest's last-modified timestamp without throwing.
+         * Returns null when the file is missing.
+         */
+        const manifestMtime = () => {
+            try {
+                if (!existsSync(manifestPath))
+                    return null;
+                return statSync(manifestPath).mtimeMs;
+            }
+            catch {
+                return null;
+            }
+        };
+        // Seed lastManifestMtime if the runtime was booted at startup so
+        // we don't immediately self-restart on the first poll.
+        if (server)
+            lastManifestMtime = manifestMtime();
+        const watchForRuntime = () => {
+            const mtime = manifestMtime();
+            const exists = mtime !== null;
+            // Auto-boot path: no runtime yet, manifest just appeared.
+            if (!server && exists) {
+                runtimeWatcher = setTimeout(() => {
+                    (async () => {
+                        try {
+                            process.stderr.write('\n[dev] amodal.json appeared — booting runtime...\n');
+                            server = await bootRuntime();
+                            lastManifestMtime = manifestMtime();
+                            process.stderr.write(`  Runtime:     http://localhost:${String(runtimePort)}\n\n`);
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            process.stderr.write(`[dev] Runtime auto-boot failed: ${msg}\n`);
+                            process.stderr.write('       Try ctrl+C and re-running `amodal dev`.\n');
+                        }
+                    })().catch(() => undefined);
+                }, 500);
+                return;
+            }
+            // Auto-restart path: runtime is up, manifest was rewritten.
+            if (server && exists && lastManifestMtime !== null && mtime > lastManifestMtime) {
+                const previousServer = server;
+                // Clear server immediately so a second mtime change while
+                // we're restarting doesn't re-enter this branch.
+                server = null;
+                runtimeWatcher = setTimeout(() => {
+                    (async () => {
+                        try {
+                            process.stderr.write('\n[dev] amodal.json changed — restarting runtime...\n');
+                            await previousServer.stop();
+                            server = await bootRuntime();
+                            lastManifestMtime = manifestMtime();
+                            process.stderr.write(`  Runtime:     http://localhost:${String(runtimePort)} (restarted)\n\n`);
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            process.stderr.write(`[dev] Runtime restart failed: ${msg}\n`);
+                            process.stderr.write('       Try ctrl+C and re-running `amodal dev`.\n');
+                        }
+                    })().catch(() => undefined);
+                }, 500);
+                return;
+            }
+            runtimeWatcher = setTimeout(watchForRuntime, RUNTIME_WATCH_INTERVAL_MS);
+        };
+        runtimeWatcher = setTimeout(watchForRuntime, RUNTIME_WATCH_INTERVAL_MS);
         // Graceful shutdown
         const shutdown = async (signal) => {
             process.stderr.write(`\n[dev] Received ${signal}, shutting down...\n`);
+            stopRuntimeWatch();
             // Kill subprocesses first
             if (managedProcesses.length > 0) {
                 log.debug('subprocess_shutdown', { count: managedProcesses.length });
                 await killAll(managedProcesses);
             }
-            await server.stop();
+            if (server) {
+                await server.stop();
+            }
             process.exit(0);
         };
         process.on('SIGTERM', () => void shutdown('SIGTERM'));
@@ -517,14 +761,6 @@ export const devCommand = {
             describe: 'Only show errors',
             default: false,
         },
-        'studio-port': {
-            type: 'number',
-            describe: 'Port for Studio (defaults to port + 1)',
-        },
-        'admin-port': {
-            type: 'number',
-            describe: 'Port for admin agent (defaults to port + 2)',
-        },
         'no-studio': {
             type: 'boolean',
             describe: 'Do not spawn Studio subprocess',
@@ -548,15 +784,11 @@ export const devCommand = {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
         const quiet = argv['quiet'];
         // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-        const studioPort = argv['studio-port'];
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-        const adminPort = argv['admin-port'];
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
         const noStudio = argv['no-studio'] || process.env['AMODAL_NO_STUDIO'] === '1';
         // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
         const noAdmin = argv['no-admin'] || process.env['AMODAL_NO_ADMIN'] === '1';
         try {
-            await runDev({ port, studioPort, adminPort, host, resume, verbose, quiet, noStudio, noAdmin });
+            await runDev({ port, host, resume, verbose, quiet, noStudio, noAdmin });
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);