@monster-orange/den 0.4.17 → 0.4.19

package/skills/install-den/SKILL.md

@@ -1,25 +1,28 @@
 ---
 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.
+description: Install Den, Monster Orange's local dev orchestrator, and hand the person over to Den's own agent, 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.
+You are installing Den on this person's machine. Den runs their repos locally and shows them in a browser. Your job
+is short: install it, name it, start it, and hand over the link. **Den's own agent takes it from there.** It adds
+their repos and starts their services, with the person allowing each change in the browser.
+
+You do three things only. You don't add repos or create workspaces: those are Den's own agent's job. 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.
+- **Never edit the person's repos.** Don't touch them at all.
+- **Send nothing off this machine.** No uploads, no telemetry. The only download is Den from npm.
+- **Sudo is the person's job.** Never run `sudo` yourself.
+- **Never open the setup link yourself**, and never fetch it. It signs in one browser, once. Give it to the person.
 - Every step below is safe to re-run. If you are unsure whether a step ran, run it again.
 
-## 1. Check the prerequisites
+## 1. Install Den, after checking Node and git
 
 Run these and read the results. Don't install anything without saying so first.
 
@@ -27,88 +30,45 @@ Run these and read the results. Don't install anything without saying so first.
    (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":
+## 2. Pick the folder and the name
 
-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`.
+Ask both together, each with a default, so the person can just say "yes":
 
-Below, `<dir>` is the Den folder, `<repo>` the repo path, and `<name>` the name.
+1. **What should we call your Den?** Default: `den`. Lowercase letters, numbers and dashes. This also becomes its
+   command, so `acme` gives you `./bin/acme`.
+2. **Where should it live?** Default: `~/<name>`. It must be a new or empty folder.
 
-## 3. Create the Den
+Below, `<name>` is the name and `<dir>` the folder.
 
 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`).
+person (`ask`).
 
-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.
+1. `npx @monster-orange/den@latest create <name> <dir> --yes --json`. It answers `{ok, dir, cli, existed, port}`. If the
+   folder already holds this Den, it answers `ok` with `existed: true` and changes nothing. When another Den already
+   uses the usual port, it picks the next free one and says so (`portPicked`).
 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`, Den couldn't tell how the repo starts, and it wrote nothing. Ask the person **one**
-   question: the `ask` text, with any `choices` numbered (there may be none). 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.
+## 3. Start the web server and hand over the link
+
+1. `./bin/<name> web up --no-open --json`. It answers `{ok, url, port}`.
+2. `./bin/<name> web claim-link --json`. It answers `{url, expiresAt}`: a one-time setup link that signs the
+   person's browser in, so they can allow Den's agent's changes. It lasts 30 minutes and works once.
+3. Hand over, in a few short sentences:
+   - **Open** the `url` from `claim-link`, in your browser on this machine. "Den's own agent takes it from there."
+   - **Your Den** lives in `<dir>`, and its command is `./bin/<name>`.
+   - If the link has expired, run `./bin/<name> web claim-link` yourself for a new one.
+
+That's all. Don't go on to add repos.
 
 ## 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.
+2. If it has `ask`, the person has to decide or act. 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
+4. 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/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);