@monster-orange/den 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -4,6 +4,80 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.6] - 2026-11-07
+
+Den in five minutes, set up by your own agent (ON-2, with ON-4's dry run).
+A developer pastes one line into their agent, and every command the agent
+runs answers in JSON, never prompts, and is safe to re-run.
+
+### Added
+
+- **Set up by your agent.** `den --help` and the README print the line to
+  paste: "Set up Den for me by following
+  https://raw.githubusercontent.com/Monster-Orange/den/main/skills/install-den/SKILL.md". The install-den skill it points
+  at ships in the package as `skills/install-den/SKILL.md`: plain Markdown
+  with Claude skill front matter, at most three questions, no secrets in
+  chat, no edits to the person's repos, nothing sent off the machine.
+- **`<cli> repo add <path|git-url>`** adds a repo with no prompts and never
+  writes into it. A git URL is cloned where Den keeps managed clones. A repo
+  with no manifest (or `--sidecar`) gets a side-car manifest in the
+  distribution's `manifests/`, detected from its Makefile `up` target, its
+  compose file or its `package.json` `dev`/`start` scripts (and `test`), and
+  validated before it is written. When detection can't decide, nothing is
+  written and the answer asks, with the choices; a re-run passes
+  `--run "<cmd>"`. `--health <url>` adds a health check. The workspace is
+  `-w`, else the focused one, else a new `default`. The same repo again
+  answers `existed: true`.
+- **`--json` for setup.** `create --yes --json` (a directory that already
+  holds the distribution is `existed: true`), `up --json` (each service's
+  result and health), `doctor --json` and `mcp connect --json`. Stdout is
+  one JSON object, the log goes to stderr, and a failure carries a `fix`
+  the agent can run or an `ask` for the person.
+- **`doctor --json`'s onboarding checks:** Node 22.13 or later, git, Docker
+  (only when a registered repo needs it), the web server and its URL, and
+  Den's MCP through it, each `ok`, `warn` or `fail`. The human `doctor` is
+  unchanged.
+- **`mcp connect --runtime claude|codex|gemini|grok`** names the agent by
+  its runtime. Grok CLI is a new client: Den writes its own
+  `[mcp_servers.<cli>]` table in `~/.grok/config.toml` (or the project's
+  `.grok/config.toml`), as xAI documents. A config file that already has the
+  entry is no longer rewritten.
+- **`create` picks a free web port.** When 7777 is in use on this machine,
+  `create` picks the next free port above it (never 7778, 7791 or 7799),
+  writes it to the new distribution's `config/local/user.yml` and says so,
+  in JSON as `port` and `portPicked`. `--port <n>` sets it outright. The
+  check connects and binds only; it sends nothing to the port's holder.
+  `DEN_WEB_PORT_START` moves the starting port.
+- **`web up --json`** answers `{ ok, url, port }` once the server answers,
+  and `doctor --json`'s web check carries the `port`.
+
+### Changed
+
+- `create` into a directory that already holds the same distribution says
+  so and exits 0, instead of refusing a non-empty directory.
+
+### Fixed
+
+- **An opted-in CLI sends its metrics.** The CLI records each run as it
+  exits, and a send started then never ran. With `metrics.share: true`, the
+  CLI now hands the event to a small detached sender that gives up after 2
+  seconds. The web server sends as before. Not opted in, nothing is sent.
+- **Linked devices read plainly.** A device approved with a code says
+  "approved with a code", not "signed in with approved with a code".
+- **An agent's refusal names the admin password.** It said "the lock",
+  which 0.4.4 removed.
+
+### Metric
+
+- Time from the paste to "service running, MCP connected" (R11): not
+  measured before; ON-4's dry run (create, repo add, up, web up, doctor,
+  mcp connect, each run twice) now records it, about 16 s locally. Target:
+  5 minutes or less.
+
+### Migrations
+
+- None.
+
 ## [0.4.5] - 2026-11-07
 
 Sign in with GitHub as the owner, from your other devices; approve a

package/README.md

@@ -10,10 +10,24 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.5/hero-dark.png">
-  <img src="docs/images/0.4.5/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.6/hero-dark.png">
+  <img src="docs/images/0.4.6/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
 </picture>
 
+## Set up by your agent
+
+Paste this line into your coding agent (Claude Code, Codex, Gemini, Grok, …):
+
+```text
+Set up Den for me by following https://raw.githubusercontent.com/Monster-Orange/den/main/skills/install-den/SKILL.md
+```
+
+The agent follows the [install-den skill](skills/install-den/SKILL.md). It asks you at most three questions,
+creates your Den, adds one of your repos without changing it, starts it, checks it, and connects itself to Den's
+MCP server. Then it tells you what's running and the URL to open. It never asks for a password in chat, never
+edits your repos and sends nothing off your machine. Every step it runs answers in JSON and is safe to re-run:
+see [Set up by your agent](docs/distributions.md#set-up-by-your-agent).
+
 ## What Den is
 
 Den is an opinionated local development framework for solo developers and small teams. You point it at the
@@ -24,7 +38,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.5/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+  <img src="docs/images/0.4.6/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
 </p>
 
 ## How it helps
@@ -54,10 +68,10 @@ yours. Den connects them and turns on good practice from the start.
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.5/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
-  <img src="docs/images/0.4.5/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
-  <img src="docs/images/0.4.5/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
-  <img src="docs/images/0.4.5/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+  <img src="docs/images/0.4.6/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.6/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.6/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.6/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
 </p>
 
 ## Get started

package/docs/distributions.md

@@ -32,8 +32,22 @@ From a Den checkout, `./bin/den create acme ../acme` does the same.
 | `--title <title>`       | `<Name>` Title Case | Brand name shown to people            |
 | `--cli <cli>`           | `<name>`            | The command people type               |
 | `--env-prefix <PREFIX>` | `<NAME>`            | Env-var prefix (`ACME` → `ACME_HOME`) |
+| `--yes`, `-y`           |                     | Never prompt (create never does)      |
+| `--json`                |                     | One JSON object on stdout             |
+| `--port <n>`            | `7777`, else free   | The web UI's port                     |
 
 `create` refuses a directory that is not empty and never overwrites a file.
+A directory that already holds this distribution (its `den.yml` names the
+same product and command) is not an error: `create` says so and writes
+nothing, so it is safe to re-run.
+
+The web UI's port is 7777 unless that port is in use on this machine (another
+Den already running, say). Then `create` picks the next free port above it,
+never a port Den itself reserves (7778, 7791, 7799), writes it to the new
+distribution's `config/local/user.yml` as `web: { port: N }`, and says so.
+`--port <n>` sets it outright. The check only connects and binds; it sends
+nothing to whatever holds the port. `DEN_WEB_PORT_START` moves the starting
+port (tests use it so none touches 7777).
 [`examples/distribution/`](../examples/distribution) is exactly the output of
 `den create acme`; a unit test regenerates it, so the two never drift
 (`npm run example:regen` after changing the scaffolder).
@@ -48,6 +62,85 @@ npm install
 make help
 ```
 
+## Set up by your agent
+
+A developer pastes one line into their agent:
+
+```text
+Set up Den for me by following https://raw.githubusercontent.com/Monster-Orange/den/main/skills/install-den/SKILL.md
+```
+
+That file is the install-den skill, also in the package at
+`skills/install-den/SKILL.md`: plain Markdown any agent can follow, with
+Claude skill front matter. `den --help` prints the line. The skill runs the
+commands below. Each one takes `--json`, never prompts, and is safe to
+re-run. With `--json`, stdout carries exactly one JSON object and the
+command's log goes to stderr. When `ok` is false the object says why
+(`error`) and carries either a command the agent can run (`fix`) or a
+question for the person (`ask`, sometimes with `choices`).
+
+| Step                                                       | Answers                                                                      |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `npx @monster-orange/den create <name> [dir] --yes --json` | `{ ok, dir, cli, existed, files, port, portPicked?, next }`                  |
+| `<cli> repo add <path\|git-url> --json`                    | `{ ok, existed, repo, workspace, mode, path, manifest, services, next }`     |
+| `<cli> up <repo> --json`                                   | `{ ok, workspace, services: [{ address, result, health, detail? }], next }`  |
+| `<cli> web up --no-open --json`                            | `{ ok, url, port, version? }`                                                |
+| `<cli> doctor --json`                                      | `{ ok, checks: [{ id, status, detail, url?, port?, fix?, ask? }] }`          |
+| `<cli> mcp connect --runtime <runtime> --json`             | `{ ok, server, clients: [{ id, ok, said, file?, changed? }], restart, web }` |
+
+### repo add
+
+`<cli> repo add <path|git-url> [--sidecar] [-w <workspace>] [--name <repo>]
+[--run "<cmd>"] [--down "<cmd>"] [--health <url>] [--branch <branch>]
+[--json]` adds a repo to a workspace without writing into the repo.
+
+- A path is the person's own checkout, added dev-managed at that path. A git
+  URL is cloned where Den keeps its managed clones
+  (`.<name>-services/<repo>/<branch>`, the remote's default branch unless
+  `--branch` says otherwise) and added managed. A clone that is already
+  there is used as it is.
+- A repo with its own manifest is used as it is. One without, or with
+  `--sidecar`, gets a side-car: a held manifest at
+  `manifests/<repo>.<name>.yml` ([below](#overriding-a-manifest)), keyed by
+  the repo's `origin` name or folder name. It is checked by the manifest
+  validator before it is written, and an existing one is never overwritten.
+  `--sidecar` on a repo with its own manifest is an error: Den always uses
+  the repo's own file (change it with an override instead).
+- The side-car's commands are detected from the repo's files, in this order:
+  a Makefile with an `up` target (`make up`, plus `down`, `setup` and
+  `restart` when present); otherwise a compose file
+  (`docker compose -f <file> up -d` and `down`) or `package.json`'s `dev`,
+  else `start`, script. One candidate decides. Two, or none, is a question:
+  the answer has `ask` and `choices`, nothing is written, and a re-run names
+  the command with `--run "<cmd>"`. A Makefile `test` target or a
+  `package.json` `test` script becomes the repo's `tests.unit`.
+  `--health <url>` adds an HTTP health check.
+- The workspace is `-w <workspace>` (made and activated if it doesn't exist),
+  else the focused one, else a new `default` workspace.
+- The same repo again answers `ok` with `existed: true`. A different repo
+  under the same name is an error that offers `relocate` or `--name`.
+
+### up, doctor and mcp connect
+
+- `up --json` runs `up` as usual, then reports each service it touched:
+  `result` is `started`, `already-running`, `failed` or `skipped`, and
+  `health` is the service's health after it started (a service with a
+  health check is waited on, up to 30 seconds). A healthy service is
+  `already-running` on a re-run.
+- `doctor --json` lists the onboarding checks first: `node` (22.13 or
+  later), `git`, `docker` (only when a registered repo has a compose file or
+  block, or a docker command), `web` (the web server answers at `url`) and
+  `mcp` (`<cli> mcp --call workspaces` gets an answer through it). Then one
+  `strategy:<kind>` check per row of the [human doctor](#doctor). `ok` is
+  false, and the exit code 1, when any check is `fail`.
+- `mcp connect --runtime <runtime>` names the agent by its runtime: `claude`
+  (the `claude-code` client), `codex`, `gemini` or `grok`. Grok CLI keeps its
+  MCP servers in `~/.grok/config.toml` (or `.grok/config.toml` with
+  `--project`), one `[mcp_servers.<name>]` table each
+  ([xAI's docs](https://docs.x.ai/build/features/mcp-servers)); Den writes
+  only its own table. A config file that already has the entry is left as
+  it is (`changed: false`).
+
 ## Layout
 
 | Path                      | What                                                                                             |
@@ -587,6 +680,10 @@ Acme doctor: strategies
 `session-backend` is never a doctor failure: nothing needs a session until
 one is started (see Sessions).
 
+`<cli> doctor --json` adds the onboarding checks (Node, git, Docker, the web
+server, Den's MCP) and answers with one JSON object: see
+[Set up by your agent](#up-doctor-and-mcp-connect).
+
 ## den.yml: the product profile
 
 Every runtime name derives from `product.name`. Set only what you want to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {
@@ -25,7 +25,8 @@
     "README.md",
     "CHANGELOG.md",
     "docs/",
-    "!docs/images/"
+    "!docs/images/",
+    "skills/"
   ],
   "scripts": {
     "cli": "tsx src/ui/cli/index.ts menu",
@@ -44,7 +45,7 @@
     "gate:org-names": "node scripts/org-name-gate.mjs",
     "docs:shots": "node scripts/doc-shots.mjs",
     "docs:links": "node scripts/docs-links.js",
-    "example:regen": "rm -rf examples/distribution && ./bin/den create acme examples/distribution",
+    "example:regen": "rm -rf examples/distribution && ./bin/den create acme examples/distribution --port 7777",
     "dist-smoke": "bash scripts/dist-smoke.sh"
   },
   "keywords": [

package/skills/install-den/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: install-den
+description: Install and set up Den, Monster Orange's local dev orchestrator, for a developer in five minutes. Use when the person says "set up Den", "install Den", "get me started with Den", or pastes a link to this file.
+---
+
+# Install Den
+
+You are setting up Den on this person's machine. Den runs their repos locally, shows them in a browser, and gives you
+(the agent) an MCP server to work with. Aim to be done in five minutes. Keep your messages short and plain.
+
+## Hard rules
+
+- **Never ask for a token, password or secret in chat.** If a step needs one, tell the person which command to run
+  themselves.
+- **Never edit the person's repos.** Den's files go in the Den folder only. Read the repo; don't write to it.
+- **Send nothing off this machine.** No uploads, no telemetry, no pasting their code anywhere. The only downloads are
+  Den from npm and a repo the person gave you as a git URL.
+- **Sudo is the person's job.** Never run `sudo` yourself. When a Den step needs it, Den asks for the password in its
+  own prompt (in the terminal or the browser), and the person types it there.
+- Every step below is safe to re-run. If you are unsure whether a step ran, run it again.
+
+## 1. Check the prerequisites
+
+Run these and read the results. Don't install anything without saying so first.
+
+1. `node --version`: needs **22.13 or later**. If it's older or missing, say so and suggest their usual installer
+   (for example `brew install node`, or `nvm install 22`).
+2. `npm --version`: needs 9 or later. It comes with Node.
+3. `git --version`: needs to be there.
+4. `docker info`: only matters if the repo runs in containers (it has a `docker-compose.yml` or `compose.yaml`).
+   If Docker is needed and not running, ask them to start it.
+
+If anything is missing, stop here, tell them what and how to fix it, and wait.
+
+## 2. Ask at most three questions
+
+Ask them together, each with a default, so the person can just say "yes":
+
+1. **Where should your Den live?** Default: `~/den`. It must be a new or empty folder.
+2. **Which repo should we start with?** Default: the folder you're in now. A local path or a git URL.
+3. **What should we call your Den?** Default: `den`. Lowercase letters, numbers and dashes. This also becomes the
+   command name, so `acme` gives you `./bin/acme`.
+
+Below, `<dir>` is the Den folder, `<repo>` the repo path, and `<name>` the name.
+
+## 3. Create the Den
+
+Every Den command below takes `--json`. It then prints one JSON object on stdout and its log on stderr. Read `ok`
+first. When `ok` is false, the object says why (`error`) and either a command to run (`fix`) or a question for the
+person (`ask`, sometimes with `choices`).
+
+1. `npx @monster-orange/den create <name> <dir> --yes --json`. It answers `{ok, dir, cli, existed, port, next}`. If
+   the folder already holds this Den, it answers `ok` with `existed: true` and changes nothing. `port` is the browser
+   UI's port. When another Den already uses the usual one on this machine, Den picks the next free port and says so
+   (`portPicked`). Remember the port for the hand-back.
+2. `cd <dir> && npm install`
+3. From here on, the Den command is `./bin/<name>`, run from `<dir>`.
+
+## 4. Add the repo without changing it
+
+1. `./bin/<name> repo add <repo> --json`. `<repo>` can be a path or a git URL. Den clones a URL into its own folder.
+   - If the repo has its own `.<name>.yml`, Den uses it.
+   - If it doesn't, Den works out how the repo starts and writes a side-car manifest into `<dir>/manifests/`. It never
+     writes into the repo. It looks for a Makefile `up` target, then a compose file, then the `dev` or `start` script
+     in `package.json`. `--sidecar` asks for this explicitly, and fails if the repo has its own manifest.
+   - If you can see which port the app listens on, add `--health http://localhost:<port>/`. Den then checks that it
+     answers.
+2. If the answer has `ask` and `choices`, Den couldn't tell how the repo starts, and it wrote nothing. Ask the person
+   **one** question: the `ask` text, with the choices numbered. Then re-run with their answer:
+   `./bin/<name> repo add <repo> --run "<their command>" --json`.
+3. The answer names the repo (`repo`), the workspace it joined (`workspace`) and where its manifest is (`manifest`).
+   A workspace is Den's name for a set of repos that run together. The first one is called `default`.
+
+## 5. Start it and check it
+
+1. `./bin/<name> up <repo> --json`. `<repo>` is the `repo` value from step 4. Each service comes back with a
+   `result` (`started` or `already-running`) and a `health` (`ok`, or `unknown` when it has no health check).
+2. `./bin/<name> web up --no-open --json`. This starts the browser UI, and answers `{ok, url, port}`. The MCP server
+   reads through it.
+3. `./bin/<name> doctor --json`. Each check comes back as `ok`, `warn` or `fail`. The checks are Node, git, Docker
+   (only if a repo needs it), the web server (with its `url` and `port`) and Den's MCP. Fix every `fail` before you hand back.
+
+## 6. Connect yourself to Den's MCP
+
+1. `./bin/<name> mcp connect --runtime <you> --json`. `<you>` is `claude`, `codex`, `gemini` or `grok`. For any other
+   agent, `./bin/<name> mcp config` prints the JSON to add by hand.
+2. `./bin/<name> mcp clients` shows whether you are connected.
+3. If the answer has `restart: true`, you load the new MCP server only when you start again. Tell the person to
+   restart you once.
+
+## 7. Hand back
+
+Tell the person, in a few short sentences. Explain every name you use the first time (for example, "a workspace is a
+set of repos that run together").
+
+- **Open:** the `url` from `web up` or from the doctor's `web` check, for example `http://localhost:<port>`. Never
+  assume a port: use the one Den gave you.
+- **What's running:** each service from `up`, and whether it's healthy.
+- **Your Den:** where it lives (`<dir>`) and its command (`./bin/<name>`).
+- **Decisions, if any:** as numbered yes/no questions, for example "1. Restart me now so I can use Den's tools?"
+- **Three next things we can do together:**
+  1. Add another repo.
+  2. Look at a service's logs, or run its tests.
+  3. Start an agent session on this repo from the browser.
+
+## When something fails
+
+1. Read the JSON. If it has `fix`, run that command, then re-run the step that failed.
+2. If it has `ask`, the person has to decide or act (sudo, a password, starting Docker, signing in). Ask them the
+   question, show any `choices` numbered, and wait.
+3. If there is neither, ask the person **one** clear question, with your best guess as the default.
+4. Never work around a failure by editing their repo, turning off a check, or skipping a step without saying so.
+5. If you're stuck after two tries, stop. Tell them what you ran, what it said, and where Den writes its logs
+   (`~/.<name>/`), so they can get help.

package/src/shared/agent-setup.ts

@@ -0,0 +1,9 @@
+/**
+ * The one line a developer pastes into their agent to have it set Den up
+ * (ON-5): the agent follows the install-den skill published at this URL
+ * (skills/install-den/SKILL.md in the package).
+ */
+export const AGENT_SETUP_URL =
+  "https://raw.githubusercontent.com/Monster-Orange/den/main/skills/install-den/SKILL.md";
+
+export const AGENT_SETUP_LINE = `Set up Den for me by following ${AGENT_SETUP_URL}`;

package/src/shared/constants.ts

@@ -112,3 +112,10 @@ export const SKIP_TEST_DIRS = [
 
 /** Default den web server port. */
 export const DEFAULT_PORT = 7777;
+
+/**
+ * Ports a new distribution's web server never takes when `create` picks
+ * one because DEFAULT_PORT is in use: the edge's and other well-known Den
+ * instances' ports.
+ */
+export const RESERVED_DEN_PORTS: readonly number[] = [7778, 7791, 7799];

package/src/shared/dev-metrics/emit.ts

@@ -31,7 +31,7 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import { execFileSync } from "child_process";
+import { execFileSync, spawn } from "child_process";
 import { createHash, randomUUID } from "crypto";
 import * as yaml from "yaml";
 import { getDistRoot } from "../paths.js";
@@ -241,6 +241,32 @@ export function buildEnvelope(
   return `{}\n${itemHeader}\n${payload}\n`;
 }
 
+/**
+ * Send from a short-lived detached process instead of this one. The CLI
+ * records its run in the `exit` handler, where an async fetch never runs;
+ * a detached sender outlives the CLI and gives up after SHIP_TIMEOUT_MS.
+ * The long-lived server keeps the in-process fetch.
+ */
+let shipDetached = false;
+export function shipFromDetachedSender(): void {
+  shipDetached = true;
+}
+
+const SENDER = `fetch(process.env.DM_URL,{method:"POST",headers:{"Content-Type":"application/x-sentry-envelope","X-Sentry-Auth":process.env.DM_AUTH},body:process.env.DM_BODY,signal:AbortSignal.timeout(${SHIP_TIMEOUT_MS})}).catch(()=>{}).finally(()=>process.exit(0))`;
+
+function sendDetached(url: string, auth: string, body: string): void {
+  try {
+    spawn(process.execPath, ["-e", SENDER], {
+      detached: true,
+      stdio: "ignore",
+      // Only what the sender needs: none of the caller's environment.
+      env: { DM_URL: url, DM_AUTH: auth, DM_BODY: body },
+    }).unref();
+  } catch {
+    /* fail-open: the JSONL line is already buffered */
+  }
+}
+
 function ship(
   record: Record<string, string>,
   epoch: number,
@@ -266,6 +292,7 @@ function ship(
 
   const url = `${parsed.scheme}://${parsed.host}/api/${parsed.projectId}/envelope/`;
   const auth = `Sentry sentry_key=${parsed.key}, sentry_version=7, sentry_client=dev-metrics-${product().cli}/1.0`;
+  if (shipDetached) return sendDetached(url, auth, envelope);
   // Fire-and-forget: never awaited, so the caller never blocks. Bounded by a 2s
   // abort so a hung ingest can't leak a pending request in the long-lived server.
   void fetch(url, {

package/src/shared/port-pick.ts

@@ -0,0 +1,60 @@
+/**
+ * Picking a free localhost port for a new distribution's web server
+ * (`create`, ON-2), so a second Den on one machine doesn't collide with the
+ * first on DEFAULT_PORT.
+ *
+ * "In use" is checked without talking to whoever holds the port: a TCP
+ * connect that is closed as soon as it opens (no byte is sent), then a
+ * bind. Either one finding something there means in use.
+ */
+import * as net from "net";
+import { RESERVED_DEN_PORTS } from "./constants.js";
+
+/** Whether something holds `port` on localhost. Never sends a byte. */
+export function portInUse(port: number, host = "localhost"): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = net.connect({ host, port });
+    const done = (inUse: boolean | null) => {
+      sock.destroy();
+      if (inUse !== null) return resolve(inUse);
+      // Nothing accepted a connection: can we bind it ourselves?
+      const srv = net.createServer();
+      srv.once("error", () => resolve(true));
+      srv.listen({ port, host, exclusive: true }, () =>
+        srv.close(() => resolve(false)),
+      );
+    };
+    sock.setTimeout(1_000);
+    sock.once("connect", () => done(true));
+    // Something there that doesn't complete a handshake: in use.
+    sock.once("timeout", () => done(true));
+    sock.once("error", (e: NodeJS.ErrnoException) =>
+      done(e.code === "ECONNREFUSED" ? null : true),
+    );
+  });
+}
+
+export interface PickPortOptions {
+  /** The port wanted (the default); the search goes up from here. */
+  start: number;
+  /** Never chosen. */
+  reserved?: readonly number[];
+  /** How many ports above `start` to try. */
+  span?: number;
+  inUse?: (port: number) => Promise<boolean>;
+}
+
+/**
+ * `start` when it is free, else the first free port above it that is not
+ * reserved; null when none in the span is free.
+ */
+export async function pickFreePort(o: PickPortOptions): Promise<number | null> {
+  const reserved = o.reserved ?? RESERVED_DEN_PORTS;
+  const inUse = o.inUse ?? ((p: number) => portInUse(p));
+  const span = o.span ?? 100;
+  for (let p = o.start; p <= Math.min(o.start + span, 65535); p++) {
+    if (reserved.includes(p)) continue;
+    if (!(await inUse(p))) return p;
+  }
+  return null;
+}

package/src/ui/cli/create-main.ts

@@ -6,4 +6,4 @@
 import { runCreate } from "./create.js";
 
 const cwd = process.env.DEN_INVOKE_CWD?.trim() || process.cwd();
-process.exit(runCreate(process.argv.slice(2), cwd));
+process.exit(await runCreate(process.argv.slice(2), cwd));