@monster-orange/den 0.4.18 → 0.4.19

package/src/shared/agents/den-claude.ts

@@ -48,10 +48,13 @@
 import { randomUUID } from "crypto";
 import * as fs from "fs";
 import * as path from "path";
-import { configuredRuntimeBin } from "../den-config.js";
+import { MCP_ACTIONS, configuredRuntimeBin } from "../den-config.js";
 import { rolePrompt } from "./personas.js";
 import { GUARDRAILS_DIR, guardrailHooks, hookCommands } from "./guardrails.js";
 import { DEFAULT_ROTATE } from "./rotation.js";
+import { idsInNames } from "./handback.js";
+import { isServerScope } from "./server-agent.js";
+import { product } from "../product.js";
 import {
   LaunchError,
   mcpConfigJson,
@@ -140,6 +143,25 @@ export const DEN_CLAUDE_PERMISSIONS: RuntimePermissions = {
   commandRules: COMMAND_RULES,
 };
 
+/**
+ * ON-6, the server agent: Den's own MCP server's tools as Claude Code
+ * permission rules (https://code.claude.com/docs/en/iam, MCP rules:
+ * `mcp__<server>` matches every tool of that server, `mcp__<server>__*`
+ * the same with a wildcard). `ask` keeps the org's immediate actions
+ * (mcp.actions: they run at once, with no browser Allow) asking in the
+ * terminal: Claude Code checks ask before allow. `server` is the name in
+ * the --mcp-config file.
+ */
+export function denToolRules(server: string): {
+  allow: string[];
+  ask: string[];
+} {
+  return {
+    allow: [`mcp__${server}`, `mcp__${server}__*`],
+    ask: MCP_ACTIONS.map((a) => `mcp__${server}__${a}`),
+  };
+}
+
 /** A command prefix's allow rules (permissions.ts checked it). */
 export function allowRules(commands: readonly string[]): string[] {
   return commands.flatMap((c) =>
@@ -336,13 +358,24 @@ function common(input: LaunchInput): {
   const hooks = input.persona.guardrails?.hooks
     ? guardrailHooks(
         GUARDRAILS_DIR,
-        hookCommands(GUARDRAILS_DIR, process.execPath, {
-          files: input.filesDir,
-          after: input.rotateAfter ?? DEFAULT_ROTATE.afterCompactions,
-        }),
+        hookCommands(
+          GUARDRAILS_DIR,
+          process.execPath,
+          {
+            files: input.filesDir,
+            after: input.rotateAfter ?? DEFAULT_ROTATE.afterCompactions,
+          },
+          // A Den named "den-t2" says "Den T2": a name, not an ID.
+          idsInNames([product().title, input.workspace.name]),
+          // ON-6: the server agent talks with the person; it hands nothing
+          // back, so its messages get the plain-writing check only.
+          !isServerScope(input.workspace.name),
+        ),
       )
     : null;
-  const allow = allowRules(input.allow ?? []);
+  const den = input.denToolsAllowed ? denToolRules(input.mcp.name) : null;
+  const allow = [...allowRules(input.allow ?? []), ...(den?.allow ?? [])];
+  const ask = den?.ask ?? [];
   const settings =
     input.stateDir || hooks || allow.length ? settingsPath(input) : null;
   return {
@@ -372,6 +405,7 @@ function common(input: LaunchInput): {
                   ? {
                       permissions: {
                         ...(allow.length ? { allow } : {}),
+                        ...(ask.length ? { ask } : {}),
                         ...(input.stateDir
                           ? {
                               deny: stateDirDenyRules(

package/src/shared/agents/guardrails/stop-hook.ts

@@ -14,6 +14,14 @@
  * (stop_hook_active), it lets the turn end, so it never loops. Any error
  * lets the turn end too.
  *
+ * `--no-handback` (the server agent, ON-6): it talks with the person and
+ * hands no work back, so even a message with the Hand-back heading gets
+ * only the plain-writing check.
+ *
+ * `--known <word>` (repeated): ID-shaped words in the names Den gives
+ * (its title, the workspace), say "T2" in "Den T2". They are names, never
+ * flagged as bare IDs.
+ *
  * Session rotation (den#4): run with `--files <agent files dir> --after
  * <n>`, while a rotation is due (rotation.ts) and handoff.md is missing or
  * fails the handoff check, it blocks once with what to write. Once the
@@ -54,11 +62,23 @@ function rotationBlock(
   });
 }
 
+/** The `--known <word>` values in the hook's arguments. */
+export function knownArgs(argv: readonly string[]): string[] {
+  const out: string[] = [];
+  argv.forEach((a, i) => {
+    if (a === "--known" && argv[i + 1]) out.push(argv[i + 1]);
+  });
+  return out;
+}
+
 /** The hook's stdout for one Stop input ("" lets the turn end). */
 export function stopDecision(
   input: unknown,
   rotation?: RotationHookArgs | null,
+  knownNames: readonly string[] = [],
+  handbackCheck: boolean = true,
 ): string {
+  const known = new Set(knownNames);
   if (!input || typeof input !== "object") return "";
   const i = input as {
     stop_hook_active?: unknown;
@@ -74,10 +94,10 @@ export function stopDecision(
   if (typeof msg !== "string") return "";
   // A hand-back is checked whole. Any other final message is what the
   // person reads too, so it gets the plain-writing check: no bare IDs.
-  const handback = looksLikeHandback(msg);
+  const handback = handbackCheck && looksLikeHandback(msg);
   const problems = handback
-    ? checkHandback(msg).problems
-    : bareIds(msg).map(
+    ? checkHandback(msg, known).problems
+    : bareIds(msg, new Set(), known).map(
         (id) =>
           `"${id}" is not explained. Say what it is, e.g. "${id} (what it is)".`,
       );
@@ -98,7 +118,13 @@ async function main(): Promise<void> {
   for await (const chunk of process.stdin) text += String(chunk);
   let out = "";
   try {
-    out = stopDecision(JSON.parse(text), parseHookArgs(process.argv.slice(2)));
+    const argv = process.argv.slice(2);
+    out = stopDecision(
+      JSON.parse(text),
+      parseHookArgs(argv),
+      knownArgs(argv),
+      !argv.includes("--no-handback"),
+    );
   } catch {
     out = "";
   }

package/src/shared/agents/guardrails.ts

@@ -50,9 +50,34 @@ export const GUARDRAILS_DIR = enginePath(
   "guardrails",
 );
 
-/** The shared persona instructions, as Den ships them. */
-export function sharedInstructions(dir: string = GUARDRAILS_DIR): string {
-  return fs.readFileSync(path.join(dir, "instructions.md"), "utf-8").trim();
+/** What the server agent reads in place of "Handing work back" (ON-6). */
+export const NO_HANDBACK_SECTION = `### Talking with the person
+
+You talk with the person as you go; there is no work to hand back, so don't
+write a hand-back. End each turn with a plain sentence or one question.
+Every message you end a turn with is read by a person: explain each ID in it.`;
+
+/**
+ * The shared persona instructions, as Den ships them. `handback: false`
+ * (the server agent, ON-6) swaps the "Handing work back" section, a build
+ * agent's template (URL, Branch, yes/no decisions), for NO_HANDBACK_SECTION.
+ */
+export function sharedInstructions(
+  dir: string = GUARDRAILS_DIR,
+  opts: { handback?: boolean } = {},
+): string {
+  const text = fs
+    .readFileSync(path.join(dir, "instructions.md"), "utf-8")
+    .trim();
+  if (opts.handback !== false) return text;
+  const at = text.indexOf("### Handing work back");
+  if (at < 0) return text;
+  const next = text.indexOf("\n### ", at + 1);
+  return (
+    text.slice(0, at) +
+    NO_HANDBACK_SECTION +
+    (next < 0 ? "" : `\n${text.slice(next)}`)
+  ).trim();
 }
 
 /** One argument for a POSIX shell, single-quoted when it needs it. */
@@ -88,6 +113,10 @@ export function hookCommands(
   dir: string = GUARDRAILS_DIR,
   node: string = process.execPath,
   rotation?: RotationArgs,
+  /** ID-shaped words in Den's own names, for the Stop hook (stop-hook.ts). */
+  known: readonly string[] = [],
+  /** false: the Stop hook never runs the hand-back check (the server agent). */
+  handback: boolean = true,
 ): HookCommands {
   const more = (c: EngineCommand): EngineCommand =>
     rotation
@@ -108,7 +137,14 @@ export function hookCommands(
       args: [path.join(dir, "pretooluse.mjs")],
     }),
     stop: commandLine(
-      more(scriptEntrypoint("src/shared/agents/guardrails/stop-hook.ts")),
+      ((c: EngineCommand): EngineCommand => ({
+        command: c.command,
+        args: [
+          ...c.args,
+          ...known.flatMap((k) => ["--known", k]),
+          ...(handback ? [] : ["--no-handback"]),
+        ],
+      }))(more(scriptEntrypoint("src/shared/agents/guardrails/stop-hook.ts"))),
     ),
     rotation: commandLine(
       more(scriptEntrypoint("src/shared/agents/guardrails/rotation-hook.ts")),

package/src/shared/agents/handback.ts

@@ -151,10 +151,25 @@ export function isGlossed(line: string, start: number, end: number): boolean {
   return false;
 }
 
-/** Bare IDs in the text, in order, each once. */
+/**
+ * The ID-shaped words in names Den itself gives (the product's title, the
+ * workspace): a Den named "den-t2" is "Den T2", and its agent says so.
+ * They are names, not IDs to explain.
+ */
+export function idsInNames(names: readonly (string | undefined)[]): string[] {
+  const out = new Set<string>();
+  for (const n of names)
+    for (const re of ID_PATTERNS)
+      for (const m of String(n ?? "").matchAll(new RegExp(re.source, "g")))
+        out.add(m[0]);
+  return [...out];
+}
+
+/** Bare IDs in the text, in order, each once. `known` are names, never bare. */
 export function bareIds(
   text: string,
   skipLines: Set<number> = new Set(),
+  known: ReadonlySet<string> = new Set(),
 ): string[] {
   const glossed = new Set<string>();
   const bare: string[] = [];
@@ -172,7 +187,7 @@ export function bareIds(
         hits.push({ id: m[0], start: m.index!, end: m.index! + m[0].length });
     hits.sort((a, b) => a.start - b.start);
     for (const h of hits) {
-      if (glossed.has(h.id)) continue;
+      if (glossed.has(h.id) || known.has(h.id)) continue;
       if (isGlossed(line, h.start, h.end)) glossed.add(h.id);
       else if (!bare.includes(h.id)) bare.push(h.id);
     }
@@ -208,7 +223,10 @@ function decisionProblems(items: string[]): string[] {
 }
 
 /** Check a hand-back. Pure: the text in, the problems out. */
-export function checkHandback(text: string): HandbackResult {
+export function checkHandback(
+  text: string,
+  known: ReadonlySet<string> = new Set(),
+): HandbackResult {
   const lines = String(text ?? "").split(/\r?\n/);
   const { found, literal } = splitParts(lines);
   const problems: string[] = [];
@@ -233,7 +251,7 @@ export function checkHandback(text: string): HandbackResult {
         `"URL:" has no link. Give the full address, with http:// or https://, or say none if this work has no page.`,
       );
   }
-  for (const id of bareIds(lines.join("\n"), literal))
+  for (const id of bareIds(lines.join("\n"), literal, known))
     problems.push(
       `"${id}" is not explained. Say what it is, e.g. "${id} (what it is)".`,
     );

package/src/shared/agents/personas.ts

@@ -42,6 +42,11 @@ import { WORKSPACE_NAME_RE } from "../agent-actor.js";
 import { checkCommands } from "./permissions.js";
 import { DEN_ROLES, REGISTRY_ID_RE } from "./roles.js";
 import { enginePath } from "../engine.js";
+import {
+  SERVER_PACK_DIR,
+  SERVER_PERSONA_ID,
+  isServerScope,
+} from "./server-agent.js";
 import {
   DEFAULT_PACK_GUARDRAILS,
   PACK_GUARDRAILS,
@@ -356,6 +361,23 @@ export function loadPersonas(
   return all;
 }
 
+/**
+ * The server agent's persona (ON-6), from Den's own server pack, with the
+ * default pack's guardrails (the plain-writing rule among them). Only the
+ * server scope loads it, so it is never offered for a workspace.
+ */
+export function serverPersona(): Persona {
+  const p = readPack(SERVER_PACK_DIR, "builtin").find(
+    (x) => x.id === SERVER_PERSONA_ID,
+  );
+  if (!p)
+    throw new Error(`${SERVER_PACK_DIR}: no "${SERVER_PERSONA_ID}" persona`);
+  return {
+    ...p,
+    guardrails: { ...DEFAULT_PACK_GUARDRAILS, ...p.guardrailsSet },
+  };
+}
+
 /**
  * The role prompt as an agent gets it: who and where it is, what to read
  * first, the persona's own prompt, then Den's shared instructions
@@ -368,14 +390,19 @@ export function rolePrompt(
   workspace: string,
   mcpName: string,
 ): string {
-  const lines = [
-    `You are agent ${agentId} in workspace ${workspace}, with the ${persona.id} persona.`,
-    `Act on services, logs and tests only through the ${mcpName} MCP server; it serves this workspace.`,
-  ];
+  const lines = isServerScope(workspace)
+    ? [
+        `You are agent ${agentId}, this Den's own server agent, with the ${persona.id} persona. You belong to no workspace.`,
+        `Act only through the ${mcpName} MCP server; it serves the whole Den, and each write waits for the person's Allow.`,
+      ]
+    : [
+        `You are agent ${agentId} in workspace ${workspace}, with the ${persona.id} persona.`,
+        `Act on services, logs and tests only through the ${mcpName} MCP server; it serves this workspace.`,
+      ];
   if (persona.context.length)
     lines.push(`Read first: ${persona.context.join("; ")}.`);
   const shared = persona.guardrails?.instructions
-    ? `\n\n${sharedInstructions()}`
+    ? `\n\n${sharedInstructions(undefined, { handback: !isServerScope(workspace) })}`
     : "";
   return `${lines.join("\n")}\n\n${persona.prompt}${shared}`;
 }

package/src/shared/agents/runtime.ts

@@ -107,6 +107,14 @@ export interface LaunchInput {
    * role's preset and the extra commands, checked (permissions.ts).
    */
   allow?: string[];
+  /**
+   * ON-6: the server agent's own: Den's MCP tools run without the
+   * runtime's own prompt. Den's reads only read, and its writes are held
+   * for the person's Allow in the browser, so each write asks once there.
+   * The org's immediate actions (mcp.actions) still ask in the terminal.
+   * Nothing outside Den's MCP server is allowed by it.
+   */
+  denToolsAllowed?: boolean;
   /**
    * The new conversation's first prompt (a relaunch from handoff.md).
    * Only a runtime with `firstPrompt: true` is given one.

package/src/shared/agents/server-agent.ts

@@ -0,0 +1,57 @@
+/**
+ * The server agent (ON-6): the Den server's own agent, named after the
+ * distribution ("<Product> agent"). It belongs to no workspace. It runs
+ * under a reserved scope, `den-server`, so it is a normal Den agent
+ * underneath (records, sessions, resume, rotation, hooks) while its MCP
+ * server sees the whole Den. It acts only through Den's MCP actions, and
+ * each write is held for the person's Allow (ON-3).
+ *
+ * No workspace may take the reserved name: `workspace create` and the
+ * MCP's workspace_create refuse it.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { enginePath } from "../engine.js";
+
+/** The reserved scope the server agent's records and session live in. */
+export const SERVER_SCOPE = "den-server";
+
+/** The server agent's id, and its persona's. */
+export const SERVER_AGENT_ID = "server";
+export const SERVER_PERSONA_ID = "server";
+
+/** Den's own pack for it, shipped in the package (src/ ships whole). */
+export const SERVER_PACK_DIR = enginePath(
+  "src",
+  "shared",
+  "agents",
+  "server-pack",
+);
+
+/** Whether `ws` is the server agent's scope (never a workspace). */
+export function isServerScope(ws: unknown): boolean {
+  return ws === SERVER_SCOPE;
+}
+
+/**
+ * The server agent's folder under the state dir: an empty folder it
+ * starts in, so it has no checkout to edit and acts through Den's MCP.
+ * Made when asked for.
+ */
+export function serverAgentDir(stateDir: string): string {
+  const dir = path.join(stateDir, "server-agent");
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+/** Its name: the distribution's, then "agent" ("Acme agent"). */
+export function serverAgentName(title: string): string {
+  return `${title} agent`;
+}
+
+/** The refusal for a workspace that would take the reserved name. */
+export function reservedWorkspaceError(ws: string): string | null {
+  return isServerScope(ws)
+    ? `"${ws}" is reserved for the server agent; pick another workspace name`
+    : null;
+}

package/src/shared/agents/server-pack/server.md

@@ -0,0 +1,45 @@
+---
+name: server
+category: operations
+description: This Den's own agent. Sets it up and looks after it, through Den's MCP actions.
+permission_mode: ask
+resume_on_restart: true
+context: [onboard_status, the doctor's checks]
+---
+
+You are this Den's own agent. You belong to no workspace: your scope is
+the whole Den. You act only through Den's MCP tools. You have no checkout:
+don't edit files or run shell commands to change Den or the person's repos.
+
+Every write (workspace_create, repo_add, service_try) waits for the person
+to Allow it in Den's browser dialog. Until they do, nothing changes, and
+you only read. Say so the first time you ask for one.
+
+## On a fresh Den, set it up
+
+1. Call onboard_status to see what is there.
+2. Ask where their repos are, with the folder above the one Den lives in as
+   the default. Call repos_detect on it and suggest workspaces. A workspace
+   is a set of repos that run together: say so the first time.
+3. Call workspace_create for each workspace the person agrees to. It also
+   makes the workspace active, so its services can start.
+4. For each repo, call manifest_draft, then repo_add. Den brings the repo in
+   unchanged, with a side-car manifest. If Den can't tell how a repo starts,
+   ask the person one question.
+5. Call service_try on one service. If it fails, call doctor and read the
+   service's logs. Fix what you can through Den's tools; otherwise tell the
+   person the one command to run.
+6. Finish with "Here's what's running, and three things to try next.", then
+   the services and their health, then three numbered things to try.
+
+## After setup
+
+The person comes back to you for anything about the server itself: add a
+repo, fix a failing service, change a setting, explain what's running.
+
+## Never
+
+- Never ask for a token, password or secret in chat. Name the command the
+  person runs themselves.
+- Never run sudo. When Den needs the password, it asks in its own prompt.
+- Never edit the person's repos.

package/src/shared/environment-manager/workspaces.ts

@@ -10,6 +10,7 @@
  */
 
 import * as fs from "fs";
+import { reservedWorkspaceError } from "../agents/server-agent.js";
 import * as path from "path";
 import * as yaml from "yaml";
 import type {
@@ -508,6 +509,9 @@ export function setActiveWorkspace(name: string): void {
 }
 
 export function createWorkspace(name: string, config: WorkspaceConfig): void {
+  // ON-6: the server agent's scope is never a workspace.
+  const reserved = reservedWorkspaceError(name);
+  if (reserved) throw new Error(reserved);
   const file = readWorkspacesFile();
   file.workspaces[name] = config;
   writeWorkspacesFile(file);

package/src/ui/cli/agent-ops.ts

@@ -78,6 +78,7 @@ import { envKey } from "../../shared/product.js";
 import { redactSecrets } from "../../shared/redact.js";
 import {
   loadPersonas,
+  serverPersona,
   resolvePackDirs,
   type Persona,
 } from "../../shared/agents/personas.js";
@@ -167,6 +168,11 @@ import {
   type BinSource,
 } from "../../shared/agents/runtime-search.js";
 import { WORKSPACE_NAME_RE } from "../../shared/agent-actor.js";
+import {
+  SERVER_PERSONA_ID,
+  isServerScope,
+  serverAgentDir,
+} from "../../shared/agents/server-agent.js";
 import {
   bindActorSession,
   mintActorToken,
@@ -333,7 +339,7 @@ function defaultMcpServer(cli: string): {
 
 export function resolveAgentsDeps(d: AgentsDeps): AgentsResolved {
   const base = resolveDeps(d);
-  return {
+  return withServerScope({
     ...base,
     agentsConfig: d.agentsConfig ?? (() => readAgentsConfig()),
     distRoot: d.distRoot ?? getDistRoot,
@@ -365,6 +371,26 @@ export function resolveAgentsDeps(d: AgentsDeps): AgentsResolved {
           ? setWorkspaceRuntimeBin(ws, id, bin)
           : setUserRuntimeBin(id, bin)),
     userConfigFile: d.userConfigFile ?? userConfigPath,
+  });
+}
+
+/**
+ * ON-6: the server agent's scope is no workspace, but its agent is a
+ * normal one: it "exists", and its folder is an empty one under the state
+ * dir (serverAgentDir), with no workspace runtime paths.
+ */
+function withServerScope(r: AgentsResolved): AgentsResolved {
+  return {
+    ...r,
+    workspaceExists: (ws) => isServerScope(ws) || r.workspaceExists(ws),
+    workspaceDir: (ws) =>
+      isServerScope(ws) ? serverAgentDir(r.stateDir()) : r.workspaceDir(ws),
+    workspaceFolders: (ws) =>
+      isServerScope(ws)
+        ? { under: [serverAgentDir(r.stateDir())] }
+        : r.workspaceFolders(ws),
+    workspaceRuntimeBin: (ws, id) =>
+      isServerScope(ws) ? undefined : r.workspaceRuntimeBin(ws, id),
   };
 }
 
@@ -685,14 +711,18 @@ function agentsConfig(d: AgentsResolved): ResolvedAgentsConfig {
 function personas(
   d: AgentsResolved,
   cfg: ResolvedAgentsConfig,
+  /** ON-6: the server scope adds Den's own server persona (only there). */
+  ws?: string,
 ): Map<string, Persona> {
   try {
-    return loadPersonas(
+    const all = loadPersonas(
       resolvePackDirs(cfg.personaPacks, d.distRoot()),
       undefined,
       { defaultPack: cfg.defaultPackGuardrails, packs: cfg.packGuardrails },
       localPersonasDir(d.stateDir()),
     );
+    if (isServerScope(ws)) all.set(SERVER_PERSONA_ID, serverPersona());
+    return all;
   } catch (e) {
     throw refused((e as Error).message, [], 422);
   }
@@ -1337,6 +1367,9 @@ function launchInput(
     rotateAfter: after,
     ...(perms.permission ? { permission: perms.permission } : {}),
     ...(perms.allow?.length ? { allow: [...perms.allow] } : {}),
+    // ON-6: the server agent runs Den's own tools without the runtime's
+    // prompt; its writes wait for the person's Allow in the browser.
+    ...(isServerScope(ws) ? { denToolsAllowed: true } : {}),
   };
 }
 
@@ -1573,7 +1606,7 @@ export async function startAgent(
   if (!d.workspaceExists(ws))
     throw usage(`${where}: workspace "${ws}" does not exist`, 404);
   const cfg = agentsConfig(d);
-  const all = personas(d, cfg);
+  const all = personas(d, cfg, ws);
   const persona = all.get(req.persona);
   if (!persona)
     throw usage(
@@ -2108,7 +2141,7 @@ export async function resumeAgent(
     );
   const cfg = agentsConfig(d);
   const grants = resumeGrants(rec, cfg);
-  const persona = personas(d, cfg).get(rec.persona);
+  const persona = personas(d, cfg, rec.workspace).get(rec.persona);
   if (!persona)
     throw refused(`agent ${rec.id}'s persona "${rec.persona}" is gone`);
   const det = await availableOrRefuse(d, rt, rec.workspace);
@@ -2312,7 +2345,7 @@ export async function changePersona(
   const where = "agents persona";
   const rec = agentRecord(d, id, ws);
   const cfg = agentsConfig(d);
-  const all = personas(d, cfg);
+  const all = personas(d, cfg, rec.workspace);
   if (!all.get(req.persona))
     throw usage(
       `${where}: no persona "${req.persona}" (personas: ${[...all.keys()].sort().join(", ")})`,
@@ -2747,7 +2780,9 @@ export async function markInterrupted(
     return found;
   }
   for (const rec of marked) {
-    const p = all.get(rec.persona);
+    const p = isServerScope(rec.workspace)
+      ? serverPersona()
+      : all.get(rec.persona);
     if (!p || !(p.standing || p.resumeOnRestart)) continue;
     if (resumeRefusal(rec)) continue;
     try {

package/src/ui/cli/create.ts

@@ -545,7 +545,7 @@ export async function createResult(
       return {
         ok: false,
         error,
-        fix: `npx ${ENGINE_PACKAGE} create ${args.name} ${path.join(path.dirname(args.dir), `${args.name}-den`)} --yes --json`,
+        fix: `npx ${ENGINE_PACKAGE}@latest create ${args.name} ${path.join(path.dirname(args.dir), `${args.name}-den`)} --yes --json`,
         ask: `${args.dir} already has files that are not a ${args.name} distribution. Which new or empty folder should the distribution go in?`,
       };
     return {
@@ -576,7 +576,7 @@ export async function runCreate(
         JSON.stringify({
           ok: false,
           error: (e as Error).message.split("\n")[0],
-          fix: `npx ${ENGINE_PACKAGE} create <name> [dir] --yes --json`,
+          fix: `npx ${ENGINE_PACKAGE}@latest create <name> [dir] --yes --json`,
         } satisfies CreateJson),
       );
     } else console.error(`create: ${(e as Error).message}`);

package/src/ui/cli/index.ts

@@ -446,7 +446,7 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
       "create <name> [dir] [--title <title>] [--cli <cli>] [--env-prefix <PREFIX>]",
     lines: [
       "Scaffold a new distribution (den.yml, config, bin shim, Makefile) in [dir].",
-      "Also: npx @monster-orange/den create <name>. See docs/distributions.md.",
+      "Also: npx @monster-orange/den@latest create <name>. See docs/distributions.md.",
     ],
   },
   validate: {

package/src/ui/cli/repo-command.ts

@@ -60,6 +60,7 @@ import { ensureManagedServiceClone } from "../../shared/environment-manager/work
 import { getGitHubCoords } from "../../shared/smoke/git-remote.js";
 import {
   detectRunCommands,
+  draftHealthUrl,
   repoNameFrom,
   sidecarManifest,
   type DetectedCommands,
@@ -358,7 +359,13 @@ export function repoAdd(
           error: `cannot name a repo from the folder "${key}"`,
           fix: `${bin} repo add ${a.spec} --name <repo> --json`,
         };
-      const manifest = sidecarManifest(mName, d.commands, a.health);
+      // No --health: the dev server's own port, when its script names one,
+      // so the drafted service has a health check and a Visit link.
+      const manifest = sidecarManifest(
+        mName,
+        d.commands,
+        a.health ?? draftHealthUrl(repoPath, d.commands),
+      );
       const v = validate(manifest);
       const dry = a.dryRun
         ? {