@nylorun/cli 0.2.1-beta → 0.3.0-beta

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @nylorun/cli
 
+## 0.3.0-beta
+
+### Minor Changes
+
+- c49efed: **Breaking (pre-1.0 minor):** CLI reaches the local Runtime only through the installed Runtime's launcher.
+
+  - Dependencies: `@nylorun/agents` and `@nylorun/admin` only (no `@nylorun/runtime`, no `@nylorun/studio`).
+  - `nylorun runtime …` finds `nylorun-runtime` on PATH and checks its launcher and Host protocol; a missing or incompatible Runtime exits 1 with the install command for the recommended version (`package.json` `nylorun.runtime`). Nothing is downloaded. `nylorun doctor runtime` checks the prerequisites.
+  - `nylorun dev` runs the application entry under `tsx watch`; creates Tenants through `@nylorun/admin`.
+  - **Removed:** `nylorun serve`, `nylorun studio`, `--no-studio`, in-process Project runner.
+  - Install as a **devDependency**; production `start` is `node dist/src/main.js`.
+
+- c49efed: **Breaking (pre-1.0 minor):** Replace a single SQLite Runtime per Project or home directory with a **Runtime Host** that serves isolated **Tenants**, selected by `Nylorun-Tenant` and negotiated with `Nylorun-Protocol` (protocol `2`, feature `runtime-tenants`). Vocabulary: Host root + Tenant + Project link.
+
+  - **core:** `PROTOCOL_VERSION = 2`, `HOST_PROTOCOL`, `TENANT_HEADER`, `PROTOCOL_HEADER`, `newTenantId` / `isTenantId`, `checkCompatibility`; health schema gains `hostId` + `protocol` (`service: "nylorun-runtime"`); Tenant/admin wire schemas; Tenant model routes under `/v1/tenant/*`.
+  - **runtime:** Host process + Tenant module; Tenant model routes under `/v1/tenant/*`; `startEphemeralRuntime` for tests/embeds; executors via `PUT /v1/executors`; sandbox prefix `nylorun-<tenant-id>-`.
+  - **agents:** `createClient({ url, key, tenant })`; Transport sends Tenant + protocol headers; `/health` compatibility cache; `IncompatibleRuntimeError` with upgrade remedies.
+  - **cli:** Host root lifecycle (`runtime up|down|status|logs|restart|run`); Project link (`.nylorun/link.json` + `credentials.json`); `tenant` commands; `runtime status --env` exports `NYLORUN_RUNTIME_URL`, `NYLORUN_SERVER_KEY`, `NYLORUN_TENANT`; removed Project/home SQLite selectors.
+  - **studio:** `startStudio({ …, tenant: { id, name } })`; proxy forwards Tenant + protocol headers; UI shows Tenant name/short id.
+
+### Patch Changes
+
+- Pin agents to the tested release.
+- Pin admin to the tested release.
+- Pin runtime to the tested release.
+- Updated dependencies [c49efed]
+- Updated dependencies [c49efed]
+- Updated dependencies [c49efed]
+- Updated dependencies [fd9fd87]
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/agents@0.6.0-beta
+  - @nylorun/admin@0.2.0-beta
+
 ## 0.2.1-beta
 
 ### Patch Changes

package/README.md

@@ -1,61 +1,108 @@
 # @nylorun/cli
 
-The local `nylorun` executable. Requires Node 24+.
+The local `nylorun` executable. Depends on `@nylorun/agents` and `@nylorun/admin`
+only among Nylorun packages — it runs the installed Runtime's **launcher** as a
+process and never imports `@nylorun/runtime`. Vocabulary:
+[runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
+
+Prerequisites, installed by the developer (the CLI never downloads them):
+
+```sh
+node --version                            # 24 or newer
+npm install --global @nylorun/runtime     # provides nylorun-runtime
+nylorun doctor runtime                    # checks both
+```
 
 ```sh
-nylorun up                  # start the local Runtime (alias for "nylorun runtime start")
-nylorun dev                 # watch agents/index.ts, open Studio
-nylorun dev --no-studio
-nylorun serve [entry]       # run the compiled build, default dist/agents/index.js
-nylorun configure
-nylorun studio
-nylorun runtime status
-nylorun down                # stop the Runtime, keeping SQLite and credentials
+nylorun runtime up                 # launcher: start the Host
+nylorun runtime down               # stop the Host; keep Tenants and host.json
+nylorun runtime status             # Host id, address, version, Tenant list
+nylorun runtime status --env       # export lines for the linked Project
+nylorun runtime logs [--follow]    # Host + Tenant logs
+nylorun runtime restart            # restart onto the installed Runtime
+nylorun runtime run                # attached foreground Host
+nylorun dev [entry]                # up → link/create Tenant → tsx watch entry
+nylorun dev --ephemeral            # temporary Host root + one Tenant
+nylorun dev --local-ui             # also start Studio with a local dashboard
+nylorun studio [--local-ui]        # start Studio (launch URL + proxy token)
+nylorun configure                  # replace model credential on the linked Tenant
+nylorun tenant list|delete|status|reset
+nylorun doctor runtime             # prerequisites: Node 24+, installed Runtime
+nylorun doctor sandbox             # sandbox backend via Tenant API
 ```
 
-## The Runtime is a separate, persistent process
+`nylorun serve` remains removed. Production `start` is
+`node dist/src/main.js` with `connectAgents` in the application.
+`--local-ui` cannot be combined with `--no-studio`.
+
+## The launcher
+
+`nylorun runtime …` finds `nylorun-runtime` on PATH, checks that it speaks
+launcher protocol 1 and a compatible Host protocol, and invokes it with
+`--json`. The Host runs on the same Node, from the installed
+`@nylorun/runtime`. When the launcher is missing or incompatible, the command
+exits 1 with the install command for the recommended version
+(`cli/package.json` `nylorun.runtime`). A project devDependency on
+`@nylorun/runtime` also works, because npm scripts put `node_modules/.bin` on
+PATH. See [building a desktop client](../docs/building-a-desktop-client.md)
+for the launcher contract.
+
+`dev` starts (or reuses) the Host via the launcher, creates a Tenant through
+`@nylorun/admin` when the Project has no link, writes format-1 link +
+credentials, and spawns `tsx watch <entry>` with
+`NYLORUN_RUNTIME_URL`, `NYLORUN_TENANT` and `NYLORUN_SERVER_KEY`. The ready
+banner hints `Studio: npm run studio`, or prints the Studio `launchUrl` when
+started with `--local-ui`. Ctrl-C stops the child; the Host stays up.
+`nylorun studio` resolves `@nylorun/studio`, supplies `cacheDir` from the Host
+root (`NYLORUN_HOME` / `~/.nylorun`, never cwd), and prints `launchUrl`.
 
-`nylorun up` starts `@nylorun/runtime/server` in the background and returns the
-terminal. `dev` and `serve` attach to it, registering the project's exported
-agents and connecting scoped executors through `PUT /v1/executors`. They start
-the Runtime themselves when nothing is listening, and they leave it running on
-exit, so a watch restart re-registers agents without losing sessions. Pass
-`--no-autostart` to fail instead, which is what CI should do. `--foreground`
-keeps `runtime start` attached for logs.
+## Host root, Tenants and Project link
 
-## Scope
+The **Host root** is `NYLORUN_HOME` or `~/.nylorun` (resolved absolute once).
+It holds `host.json`, admin credentials and every Tenant; the Runtime itself
+is installed by npm. Isolation is per **Tenant**, not per Project directory.
 
-A project is the default scope: the Runtime's SQLite, credentials, log and pid
-live in `.nylorun/` beside the nearest `package.json`, created on first use and
-added to an existing `.gitignore`. `--global` (and running outside a project)
-uses `~/.nylorun` instead, relocatable with `NYLORUN_HOME`. Both default to
-`127.0.0.1:8787`; `--port` beats `NYLORUN_PORT`, then `PORT`, then the port
-recorded for a running Runtime. `--db` or `NYLORUN_SQLITE_PATH` moves the
-database. `nylorun runtime status --output json` prints the resolved scope for
-scripts, and `nylorun logs [-f]` tails the Runtime's own output.
+A **Project** stores only:
 
-Runtime and executor credentials remain separate. On first `configure`, `dev` or
-`serve`, an interactive terminal saves the model provider credential into the
-Runtime vault; `configure` replaces it while the Runtime is already running.
+- `.nylorun/link.json` — `{ format, hostUrl, hostId, tenantId }`
+- `.nylorun/credentials.json` — application key and principal id (0600); no
+  executor tokens
+- `.nylorun/.gitignore` containing `*`
+
+```sh
+eval "$(npx nylorun runtime status --env)"
+# → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY, NYLORUN_TENANT
+```
+
+Port defaults to `8787` on loopback. On first Host setup, if that port is
+taken, the launcher picks a free loopback port and persists it. Explicit
+`--port` is strict.
 
 ## Exit codes
 
 | Code | Meaning |
 | --- | --- |
 | 0 | Success, including `down` when nothing was running |
-| 1 | Generic failure |
+| 1 | Generic failure / launcher operation failed |
 | 2 | Usage error |
 | 3 | `runtime status` or `logs`: not running |
-| 4 | Port held by another process or another scope |
-| 5 | The running Runtime does not match this CLI |
-| 6 | `--no-autostart` and nothing is listening |
-| 7 | The Runtime did not become healthy |
+| 4 | Port held by another process |
+| 5 | Protocol / feature incompatible with this CLI |
+| 7 | The Host did not become ready |
 | 130 / 143 | SIGINT / SIGTERM |
 
-`dev` loads `agents/index.ts` using project-installed `tsx` and watches changes.
-Studio and `tsx` are optional development dependencies; the CLI is a production
-dependency when the application's `start` script uses it.
+Install the CLI as a **devDependency**. Generated applications keep
+`@nylorun/agents` alone in production dependencies.
+
+## Troubleshooting
+
+| Symptom | What to do |
+| --- | --- |
+| Quarantined Tenant | `nylorun tenant status` shows reason and `repair` |
+| `426` / exit 5 | Upgrade CLI / Runtime pin, or pin a matching older set |
+| Port conflict | Stop the other process or `nylorun runtime up --port <n>` |
+| Logs | `nylorun runtime logs --follow` |
+| Runtime not installed | `npm install --global @nylorun/runtime`; `nylorun doctor runtime` checks |
 
-Reusable provider configuration is imported from `@nylorun/runtime/configuration`;
-interactive prompts and process supervision belong here. Neither runtime nor
-harness depends on this package. See [package architecture](../docs/design/package-architecture.md).
+See [package architecture](../docs/design/package-architecture.md) and
+[MIGRATION.md](../MIGRATION.md#runtime-clients-and-admin-api-breaking-beta).

package/dist/cli.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import "./runtime/baseline.js";

package/dist/cli.js

@@ -1,46 +1,43 @@
 #!/usr/bin/env node
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
+import "./runtime/baseline.js";
 import { createRequire } from "node:module";
-import { ConfigurationCancelled, configureProvider, } from "./model/configure.js";
+import { join } from "node:path";
+import { ConfigurationCancelled, configureProvider, fetchModelCatalog, } from "./model/configure.js";
 import { putHostModel } from "./model/host-model.js";
-import { develop, developmentPreflight } from "./dev.js";
+import { develop, developmentPreflight, startStudio } from "./dev.js";
 import { CliError } from "./errors.js";
-import { loadScopeEnvironment, resolveScope, } from "./scope.js";
-import { cliRuntimeVersion, ensureRuntime, hostStatus, startHost, stopHost, tailLog, warnIncompatible, } from "./runtime-host.js";
-import { localCredentials } from "./project-runner.js";
-const usage = `nylorun <runtime|up|down|logs|dev|serve|configure|studio|doctor>
+import { runtimeCommand, runtimeUsage } from "./runtime/commands.js";
+import { findProjectRoot, requireProjectRoot } from "./project/root.js";
+import { printLinkedEnvExports } from "./project/attach.js";
+import { readLink as readProjectLink } from "./project/link.js";
+import { readCredentials as readProjectCredentials } from "./project/credentials.js";
+import { tenantCommand } from "./tenant/commands.js";
+import { resolveHome } from "./runtime/launcher.js";
+const usage = `nylorun <runtime|up|down|logs|dev|studio|configure|doctor|tenant>
 
-  runtime start [--foreground] [--restart] [--port <n>] [--db <path>] [--global]
-  runtime stop [--global] [--timeout <seconds>]
-  runtime status [--output json] [--global]
-  runtime logs [-f] [-n <lines>] [--global]
-  up                       alias for "runtime start"
-  down                     alias for "runtime stop"
-  logs                     alias for "runtime logs"
+${runtimeUsage}
 
-  dev [--no-studio] [--no-open] [--no-autostart] [--port <n>]
-  serve [entry] [--no-autostart] [--port <n>]
-  configure [--global]
-  studio [--runtime-url <http(s)-url>] [--port <n>] [--no-open]
-  doctor sandbox [--json]  show which sandbox backend this machine offers`;
-/**
- * Flags are parsed before the scope is resolved so --port can win over a PORT in .env, which
- * is only loaded once the project root is known.
- */
+  dev [entry] [--ephemeral] [--local-ui] [--no-studio] [--no-open]
+  studio [--local-ui] [--port <n>] [--no-open]
+  configure
+  doctor runtime [--json]  check the prerequisites: Node 24+ and an installed Runtime
+  doctor sandbox [--json]  show which sandbox backend this Tenant's Host offers
+  tenant current|list [--json]|use <name-or-id>|status [--json]|reset|delete`;
 function parseFlags(args, allowed = {}) {
     const booleans = new Set();
     const values = new Map();
     const rest = [];
-    const scope = {};
-    const booleanNames = new Set(["--global", ...(allowed.booleans ?? [])]);
-    const valueNames = new Set(["--port", "--db", ...(allowed.values ?? [])]);
+    const booleanNames = new Set(allowed.booleans ?? []);
+    const valueNames = new Set(allowed.values ?? []);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg.startsWith("-")) {
             rest.push(arg);
             continue;
         }
+        if (arg === "--global" || arg === "--db") {
+            throw usageError(`${arg} was removed. Use the Runtime Host root (NYLORUN_HOME) and a Project link instead.`);
+        }
         if (booleanNames.has(arg)) {
             if (booleans.has(arg))
                 throw usageError(`${arg} may only be supplied once.`);
@@ -58,198 +55,131 @@ function parseFlags(args, allowed = {}) {
         }
         throw usageError(usage);
     }
-    if (booleans.has("--global"))
-        scope.global = true;
-    if (values.has("--port"))
-        scope.port = parsePort(values.get("--port"));
-    if (values.has("--db"))
-        scope.db = values.get("--db");
-    return { scope, rest, booleans, values };
+    return { rest, booleans, values };
 }
 const usageError = (message) => new CliError(message, 2);
 function parsePort(value) {
-    if (value === undefined)
-        return undefined;
+    if (value === undefined || !/^\d+$/u.test(value))
+        throw usageError(`Invalid --port: ${value ?? "(missing)"}`);
     const port = Number(value);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
-        throw usageError("--port must be an integer between 1 and 65535.");
+        throw usageError(`Invalid --port: ${value}`);
     return port;
 }
-async function serverKeyFor(scope) {
-    return (process.env.NYLORUN_SERVER_KEY ??
-        (await localCredentials(scope.credentialsPath)).serverKey);
-}
-async function startStudio(agentServerUrl, serverKey, open, port) {
-    let entry;
-    try {
-        entry = createRequire(join(process.cwd(), "package.json")).resolve("@nylorun/studio");
+async function resolveLinkedAuth(projectRoot) {
+    const link = await readProjectLink(projectRoot);
+    const credentials = await readProjectCredentials(projectRoot);
+    if (link && credentials) {
+        return {
+            url: link.hostUrl,
+            key: credentials.applicationKey,
+            tenantId: link.tenantId,
+            tenantName: link.tenantId,
+        };
     }
-    catch {
-        throw new Error("Install @nylorun/studio to use the Studio dashboard.");
+    const url = process.env.NYLORUN_RUNTIME_URL?.trim();
+    const key = process.env.NYLORUN_SERVER_KEY?.trim();
+    const tenantId = process.env.NYLORUN_TENANT?.trim();
+    if (url && key && tenantId) {
+        return { url, key, tenantId, tenantName: tenantId };
     }
-    const studio = await import(pathToFileURL(entry).href);
-    return studio.startStudio({
-        runtimeUrl: agentServerUrl,
-        serverKey,
-        open,
-        ...(port === undefined ? {} : { port }),
-    });
-}
-function printStatus(status) {
-    const { scope, runtime } = status;
-    const lines = [
-        ["Scope", `${scope.kind} (${scope.kind === "project" ? scope.root : scope.dataDir})`],
-        ["State", status.state],
-        ["URL", scope.url],
-        ["PID", runtime?.pid ? String(runtime.pid) : status.pid ? String(status.pid) : undefined],
-        ["Runtime", status.version],
-        ["CLI expects", cliRuntimeVersion()],
-        ["Database", scope.sqlitePath],
-        ["Log", scope.logPath],
-        ["Started", runtime?.startedAt],
-    ];
-    const width = Math.max(...lines.map(([label]) => label.length));
-    for (const [label, value] of lines)
-        if (value !== undefined)
-            console.log(`${label.padEnd(width)}  ${value}`);
-}
-async function runtimeCommand(args) {
-    const [verb, ...rest] = args;
-    if (verb === "start") {
-        const flags = parseFlags(rest, { booleans: ["--foreground", "--restart"] });
-        if (flags.rest.length)
-            throw usageError(usage);
-        const scope = resolveScope(flags.scope);
-        loadScopeEnvironment(scope);
-        const before = await hostStatus(scope);
-        if (before.state === "running" && !flags.booleans.has("--restart")) {
-            console.log(`Runtime already running for ${scope.label} at ${scope.url} (pid ${before.runtime?.pid ?? before.pid}).`);
-            warnIncompatible(scope, before);
-            return;
-        }
-        const status = await startHost(scope, {
-            foreground: flags.booleans.has("--foreground"),
-            restart: flags.booleans.has("--restart"),
-        });
-        printStatus(status);
-        console.log(`\n→ npx nylorun dev`);
-        return;
-    }
-    if (verb === "stop") {
-        const flags = parseFlags(rest, { values: ["--timeout"] });
-        if (flags.rest.length)
-            throw usageError(usage);
-        const scope = resolveScope(flags.scope);
-        const seconds = flags.values.has("--timeout")
-            ? Number(flags.values.get("--timeout"))
-            : undefined;
-        if (seconds !== undefined && (!Number.isFinite(seconds) || seconds <= 0))
-            throw usageError("--timeout must be a positive number of seconds.");
-        const result = await stopHost(scope, {
-            ...(seconds === undefined ? {} : { timeoutMs: seconds * 1000 }),
-        });
-        console.log(result === "stopped"
-            ? `Stopped the Runtime for ${scope.label}. SQLite and credentials are kept in ${scope.dataDir}.`
-            : `No Runtime is running for ${scope.label}.`);
-        return;
-    }
-    if (verb === "status") {
-        const flags = parseFlags(rest, { values: ["--output"] });
-        if (flags.rest.length)
-            throw usageError(usage);
-        const output = flags.values.get("--output") ?? "text";
-        if (output !== "text" && output !== "json")
-            throw usageError("--output must be text or json.");
-        const scope = resolveScope(flags.scope);
-        const status = await hostStatus(scope);
-        if (output === "json")
-            console.log(JSON.stringify({
-                scope: scope.kind,
-                root: scope.kind === "project" ? scope.root : scope.dataDir,
-                url: scope.url,
-                state: status.state,
-                pid: status.runtime?.pid ?? status.pid ?? null,
-                runtimeVersion: status.version ?? null,
-                cliVersion: cliRuntimeVersion() ?? null,
-                scopeId: status.scopeId ?? null,
-                sqlitePath: scope.sqlitePath,
-                logPath: scope.logPath,
-                startedAt: status.runtime?.startedAt ?? null,
-            }, null, 2));
-        else
-            printStatus(status);
-        if (status.state !== "running")
-            process.exitCode = status.state === "port-conflict" ? 4 : 3;
-        return;
-    }
-    if (verb === "logs") {
-        const flags = parseFlags(rest, { booleans: ["-f"], values: ["-n"] });
-        if (flags.rest.length)
-            throw usageError(usage);
-        const lines = flags.values.has("-n") ? Number(flags.values.get("-n")) : 200;
-        if (!Number.isInteger(lines) || lines < 1)
-            throw usageError("-n must be a positive integer.");
-        await tailLog(resolveScope(flags.scope), {
-            follow: flags.booleans.has("-f"),
-            lines,
-        });
-        return;
-    }
-    throw usageError(usage);
+    throw new CliError(`No Project link in ${projectRoot}. Run nylorun dev, or set NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY and NYLORUN_TENANT.`, 1);
 }
 async function main() {
     const [rawCommand, ...rawArgs] = process.argv.slice(2);
     if (!rawCommand || rawCommand === "--help" || rawCommand === "-h")
         return void console.log(usage);
     const aliases = {
-        up: "start",
-        down: "stop",
+        up: "up",
+        down: "down",
         logs: "logs",
     };
     const command = rawCommand in aliases ? "runtime" : rawCommand;
     const args = rawCommand in aliases ? [aliases[rawCommand], ...rawArgs] : rawArgs;
-    if (command === "runtime")
-        return await runtimeCommand(args);
+    if (command === "tenant")
+        return await tenantCommand(args);
+    if (command === "runtime") {
+        // F2-7: envHook prints the linked Project's three variables.
+        return await runtimeCommand(args, {
+            envHook: async () => {
+                const root = findProjectRoot() ?? process.cwd();
+                await printLinkedEnvExports(root);
+            },
+        });
+    }
     if (command === "doctor") {
         const [topic, ...options] = args;
-        if (topic !== "sandbox" || options.some((option) => option !== "--json"))
-            throw usageError("Usage: nylorun doctor sandbox [--json]");
-        const { doctorSandbox } = await import("./doctor.js");
-        await doctorSandbox({ json: options.includes("--json") });
+        if ((topic !== "sandbox" && topic !== "runtime") ||
+            options.some((option) => option !== "--json"))
+            throw usageError("Usage: nylorun doctor runtime|sandbox [--json]");
+        const { doctorRuntime, doctorSandbox } = await import("./doctor.js");
+        const json = options.includes("--json");
+        if (topic === "runtime")
+            await doctorRuntime({ json });
+        else
+            await doctorSandbox({ json });
         return;
     }
     if (command === "dev") {
         const flags = parseFlags(args, {
-            booleans: ["--no-studio", "--no-open", "--no-autostart"],
+            booleans: ["--ephemeral", "--local-ui", "--no-studio", "--no-open"],
         });
-        if (flags.rest.length)
+        if (flags.rest.length > 1)
             throw usageError(usage);
-        const scope = resolveScope(flags.scope);
-        loadScopeEnvironment(scope);
-        // The port is re-resolved after .env so a project file can set PORT, while --port wins.
-        const resolved = resolveScope(flags.scope);
-        process.env.PORT = String(resolved.port);
-        developmentPreflight([...flags.booleans]);
-        // The supervisor checks the host before spawning tsx so port conflicts, version skew and
-        // --no-autostart surface with their own exit codes instead of a generic watcher failure.
-        await ensureRuntime(resolved, {
-            autostart: !flags.booleans.has("--no-autostart"),
+        if (flags.booleans.has("--local-ui") && flags.booleans.has("--no-studio"))
+            throw usageError("--local-ui cannot be combined with --no-studio.");
+        requireProjectRoot();
+        developmentPreflight([
+            ...flags.rest,
+            ...[...flags.booleans],
+        ]);
+        process.exitCode = await develop({
+            ...(flags.rest[0] ? { entry: flags.rest[0] } : {}),
+            flags: [...flags.booleans],
         });
-        process.exitCode = await develop([...flags.booleans]);
         return;
     }
     if (command === "serve") {
-        const flags = parseFlags(args, { booleans: ["--no-autostart"] });
-        if (flags.rest.length > 1)
+        throw usageError("nylorun serve was removed. Use nylorun dev [entry] in development, or node dist/src/main.js with NYLORUN_RUNTIME_URL, NYLORUN_TENANT and NYLORUN_SERVER_KEY.");
+    }
+    if (command === "studio") {
+        const flags = parseFlags(args, {
+            booleans: ["--local-ui", "--no-open"],
+            values: ["--port"],
+        });
+        if (flags.rest.length)
             throw usageError(usage);
-        const scope = resolveScope(flags.scope);
-        loadScopeEnvironment(scope);
-        const resolved = resolveScope(flags.scope);
-        // serve runs the project in this process, so runProject's own errors carry their exit
-        // codes out; it validates the agent registry before it touches the host.
-        await (await import("./launcher.js")).serve(flags.rest[0], {
-            autostart: !flags.booleans.has("--no-autostart"),
-            scope: resolved,
+        const projectRoot = findProjectRoot() ?? process.cwd();
+        // Surface missing Studio early with the same Install message as preflight.
+        try {
+            createRequire(join(projectRoot, "package.json")).resolve("@nylorun/studio");
+        }
+        catch {
+            throw new Error("Install @nylorun/studio to use the Studio dashboard.");
+        }
+        const auth = await resolveLinkedAuth(projectRoot);
+        const localUi = flags.booleans.has("--local-ui");
+        // I2: startStudio default is hosted; `--local-ui` forces local + cacheDir.
+        const dashboard = await startStudio({
+            runtimeUrl: auth.url,
+            serverKey: auth.key,
+            tenant: { id: auth.tenantId, name: auth.tenantName },
+            open: !flags.booleans.has("--no-open"),
+            localUi,
+            cacheDir: resolveHome(),
+            projectRoot,
+            ...(flags.values.has("--port")
+                ? { port: parsePort(flags.values.get("--port")) }
+                : {}),
+        });
+        console.log(`Studio        ${dashboard.launchUrl}`);
+        if (!localUi && dashboard.launchUrl.startsWith("https://local.nylorun.studio")) {
+            console.log(`Safari or offline: nylorun studio --local-ui`);
+        }
+        await new Promise((resolve, reject) => {
+            const close = () => void dashboard.close().then(resolve, reject);
+            process.once("SIGINT", close);
+            process.once("SIGTERM", close);
         });
         return;
     }
@@ -257,47 +187,29 @@ async function main() {
         const flags = parseFlags(args);
         if (flags.rest.length)
             throw usageError(usage);
-        const scope = resolveScope(flags.scope);
-        loadScopeEnvironment(scope);
+        const projectRoot = findProjectRoot() ?? process.cwd();
+        const auth = await resolveLinkedAuth(projectRoot);
         const controller = new AbortController();
         const cancel = (signal) => controller.abort(new ConfigurationCancelled(signal));
         process.once("SIGINT", () => cancel("SIGINT"));
         process.once("SIGTERM", () => cancel("SIGTERM"));
-        const serverKey = await serverKeyFor(scope);
-        const health = await fetch(`${scope.url}/health`).catch(() => undefined);
+        const health = await fetch(`${auth.url}/health`).catch(() => undefined);
         if (!health?.ok)
-            throw new CliError(`No Runtime is listening at ${scope.url} for ${scope.label}. Start one with "nylorun up".`, 6);
-        const prompted = await configureProvider({ signal: controller.signal });
-        await putHostModel(scope.url, serverKey, prompted);
+            throw new CliError(`No Runtime Host is listening at ${auth.url}. Start one with "nylorun runtime up".`, 6);
+        const catalog = await fetchModelCatalog({
+            url: auth.url,
+            key: auth.key,
+            tenantId: auth.tenantId,
+        });
+        const prompted = await configureProvider({
+            signal: controller.signal,
+            catalog,
+        });
+        await putHostModel(auth.url, auth.key, prompted, auth.tenantId);
         return;
     }
-    if (command !== "studio")
-        throw usageError(usage);
-    const flags = parseFlags(args, {
-        booleans: ["--no-open"],
-        values: ["--runtime-url", "--studio-port"],
-    });
-    if (flags.rest.length)
-        throw usageError(usage);
-    const scope = resolveScope(flags.scope);
-    const runtimeUrl = flags.values.get("--runtime-url") ?? scope.url;
-    const studioPort = flags.values.has("--studio-port")
-        ? parsePort(flags.values.get("--studio-port"))
-        : flags.scope.port !== undefined && flags.values.has("--runtime-url")
-            ? flags.scope.port
-            : undefined;
-    const dashboard = await startStudio(runtimeUrl, await serverKeyFor(scope), !flags.booleans.has("--no-open"), studioPort);
-    console.log(`Studio on ${dashboard.address}`);
-    await new Promise((resolve, reject) => {
-        const close = () => void dashboard.close().then(resolve, reject);
-        process.once("SIGINT", close);
-        process.once("SIGTERM", close);
-    });
+    throw usageError(usage);
 }
-/**
- * Probing a port that answers but is not a Runtime can leave a pooled connection holding the
- * event loop open, so a finished command exits explicitly once its output has drained.
- */
 async function finish(code) {
     process.exitCode = code;
     for (const stream of [process.stdout, process.stderr])

package/dist/dev-entry.d.ts

@@ -1 +1,5 @@
-export {};
+/**
+ * Legacy watcher entry. `nylorun dev` now runs the Project entry with
+ * `tsx watch` directly (D§12).
+ */
+export declare function legacyDevEntryRemoved(): never;

package/dist/dev-entry.js

@@ -1,6 +1,7 @@
-import { runProject } from "./project-runner.js";
-await runProject("agents/index.ts", {
-    studio: !process.argv.includes("--no-studio"),
-    open: !process.argv.includes("--no-open"),
-    autostart: !process.argv.includes("--no-autostart"),
-});
+/**
+ * Legacy watcher entry. `nylorun dev` now runs the Project entry with
+ * `tsx watch` directly (D§12).
+ */
+export function legacyDevEntryRemoved() {
+    throw new Error("cli/src/dev-entry.ts is no longer used. Point nylorun dev at your Project entry (default src/main.ts).");
+}