@dotdrelle/wiki-manager 0.12.8 → 0.12.10

package/.env.example

@@ -23,33 +23,28 @@ WORKSPACES_ROOT=/path/to/workspaces
 #
 #   "cme":       { "headers": { "Authorization": "Bearer <CME_MCP_AUTH_TOKEN>" } }
 #   "documents": { "headers": { "Authorization": "Bearer <DOCUMENTS_MCP_AUTH_TOKEN>" } }
-#   "mailer":    { "headers": { "Authorization": "Bearer <MAILER_MCP_AUTH_TOKEN>" } }
 #
 # Leave empty to disable authentication on that agent (not recommended in production).
 
 CME_MCP_AUTH_TOKEN=
 DOCUMENTS_MCP_AUTH_TOKEN=
-MAILER_MCP_AUTH_TOKEN=
 
 # ── Mailer (MailerSend) ────────────────────────────────────────────────────────
 
-MAILERSEND_API_KEY=
-MAILERSEND_FROM_EMAIL=no-reply@example.com
-MAILERSEND_FROM_NAME=Donna
 
 # ── Documents LLM OCR / Mermaid (optional) ─────────────────────────────────────
 
 # All image OCR is delegated to an OpenAI-compatible vision LLM. The default
-# base URL is OpenAI; set DOCUMENT_LLM_API_KEY or OPENAI_API_KEY.
-# DOCUMENT_LLM_BASE_URL=https://api.openai.com/v1
-# DOCUMENT_LLM_MODEL=gpt-5.4-mini
+# Default target is the Albert API (etalab); set DOCUMENT_LLM_API_KEY.
+# DOCUMENT_LLM_BASE_URL=https://albert.api.etalab.gouv.fr/v1
+# DOCUMENT_LLM_MODEL=LightOnOCR-2-1B
 # DOCUMENT_LLM_API_KEY=
 # DOCUMENT_LLM_TIMEOUT_SECONDS=120
 
 # ── Optional external MCP providers ────────────────────────────────────────────
-
-# Used by mcp.endpoints.json when the Exa MCP endpoint is enabled.
-EXA_MCP_API_KEY=
+# Doctrine: every variable an external MCP endpoint needs (API key, token…)
+# lives HERE and is referenced from mcp.endpoints.json as ${VAR_NAME}.
+# Add your own entries when you declare additional endpoints.
 
 # ── MCP retry policy (optional) ────────────────────────────────────────────────
 
@@ -75,4 +70,3 @@ EXA_MCP_API_KEY=
 
 # CME_MCP_PORT=3336
 # DOCUMENTS_MCP_PORT=3337
-# MAILER_MCP_PORT=3335

package/README.md

@@ -48,6 +48,7 @@ Use a local installation when the manager should be pinned in a project's
 
 ```bash
 npm install @dotdrelle/wiki-manager
+npm approve-scripts bun  # only when npm reports that Bun's postinstall is pending
 npx wiki-manager
 npx wiki-workspace --help
 ```
@@ -55,7 +56,9 @@ npx wiki-workspace --help
 `npm install` does not add `wiki-manager` or `wiki-workspace` to the shell's
 global `PATH`. Run local executables with `npx` (or `npm exec wiki-manager` and
 `npm exec wiki-workspace`). Bun is installed automatically as a package runtime;
-you do not need to add `~/.bun/bin` to `PATH`.
+you do not need to add `~/.bun/bin` to `PATH`. Recent npm versions may require
+the explicit `npm approve-scripts bun` security approval shown above before the
+first launch.
 
 ### Global installation
 
@@ -69,7 +72,12 @@ wiki-workspace --help
 ```
 
 The global installation also installs the required Bun runtime. A separately
-installed Bun remains supported, but is not required.
+installed Bun remains supported, but is not required. If npm blocks Bun's
+installation script, reinstall with:
+
+```bash
+npm install --global --allow-scripts=bun @dotdrelle/wiki-manager
+```
 
 In both modes, launch the commands from the directory that should hold the
 manager state (`workspaces/`, `.env`, and `mcp.endpoints.json`).
@@ -117,7 +125,7 @@ cp .env.example .env
 ```
 
 **3 — Start the shared agents.**
-Start the common toolbox once (Confluence export `cme`, `documents`, `mailer`).
+Start the common toolbox once (Confluence export `cme`, `documents`).
 They run in the background and serve every workspace.
 
 ```bash
@@ -215,7 +223,7 @@ Start the common toolbox once and for all (Confluence, documents, e-mail,
 production). These agents run in the background and serve **all your projects**:
 
 ```bash
-wiki-workspace agents up        # start cme, documents, mailer…
+wiki-workspace agents up        # start cme, documents…
 wiki-workspace agents status    # check they respond
 ```
 
@@ -360,7 +368,7 @@ of you in the browser (create → configure → start the agents → open).
 | [`agent-cme`](https://github.com/dotdrelle/agent-cme) | Global Confluence to Markdown MCP exporter; workspace injected automatically by Donna |
 | [`agent-wiki-production`](https://github.com/dotdrelle/agent-wiki-production) | Workspace-scoped production jobs: ingest, build, export, polish, pipeline |
 | [`agent-wiki-documents`](https://github.com/dotdrelle/agent-wiki-documents) | Document conversion MCP: PDF/Office/HTML/images → Markdown (OCR-capable) |
-| [`agent-mailer-api`](https://github.com/dotdrelle/agent-mailer-api) | Optional external mailer MCP endpoint |
+| [`agent-mailer-api`](https://github.com/dotdrelle/agent-mailer-api) | Optional external mailer MCP endpoint (user-side override, not in the default stack) |
 
 ## Workspace Model
 
@@ -406,7 +414,7 @@ keys** (`apiKey` + `baseUrl` that *reach a model*).
 
 | File | Owner | Scope | Holds |
 | --- | --- | --- | --- |
-| `.env` | manager | global | shared secrets: agent MCP tokens, MailerSend, OCR LLM, port overrides |
+| `.env` | manager | global | shared secrets: agent MCP tokens, OCR LLM, port overrides, variables for any user-declared external MCP |
 | `mcp.endpoints.json` | manager | global | where each external agent lives + which `Bearer`/header to send |
 | `workspaces/<name>/.env` | manager | per workspace | ports, workspace path, the wiki's own MCP tokens |
 | `workspaces/<name>/.wikirc.yaml` (+ `.wikirc.yaml.<profile>`) | workspace | per workspace | LLM & vector keys (provider/model/apiKey/baseUrl/retrieval) |
@@ -454,7 +462,7 @@ cp .env.example .env
 
 The `.env` file is loaded automatically by both `wiki-manager` (Node/Bun process)
 and `wiki-workspace` (Docker Compose). It sets `WORKSPACES_ROOT`, per-agent auth
-tokens, mailer credentials, and optional port overrides.
+tokens and optional port overrides; credentials of optional connectors you enable via the user override.
 
 ### External MCP endpoints
 
@@ -530,16 +538,40 @@ than tracking its own state.
 
 ### Starting external agents
 
-Start CME, documents, and mailer once for all workspaces:
+Start CME and documents once for all workspaces:
 
 ```bash
 wiki-workspace agents up
 ```
 
-This uses the packaged `agents.docker-compose.yml`. `WORKSPACES_ROOT` is resolved
+This uses the packaged `agents.docker-compose.yml` (it lives inside the npm
+package — never edit it, updates overwrite it). On first run, `agents up`
+generates the missing agent auth tokens into your manager `.env` and seeds
+`mcp.endpoints.json` from the packaged example. `WORKSPACES_ROOT` is resolved
 automatically from the manager workspaces directory. Agent state is stored under
 `./.agents-data/` unless `AGENTS_DATA_DIR` is set.
 
+#### Optional agents and user overrides
+
+Anything beyond the default stack (for example the MailerSend agent) is an
+external connector operated at the user's charge — built and published, but
+not part of the delivery. To enable one, create a file named
+`agents.docker-compose.override.yml` **next to your `.env`**:
+
+```bash
+cp "$(npm root -g)/@dotdrelle/wiki-manager/agents.docker-compose.mailer.example.yml" \
+   agents.docker-compose.override.yml
+```
+
+`agents up` includes it automatically when present (standard Docker Compose
+merge: new services are added, same-name keys override the defaults — you can
+also use it to pin a port or a variable of a default agent). The file is
+yours: wiki-manager never generates or overwrites it. Complete the setup by
+adding the connector's variables to your `.env` and its endpoint block to
+your `mcp.endpoints.json` — every variable an external MCP endpoint needs
+lives in the `.env` and is referenced as `${VAR_NAME}` from
+`mcp.endpoints.json`. Detailed steps are in the example file header.
+
 Workspace-native MCP servers (`llm-wiki`, `production`) stay configured through
 each workspace `.env`. External agents are workspace-agnostic: the active
 `/use <workspace>` is injected automatically on every CME and documents tool

package/agents.docker-compose.mailer.example.yml

@@ -0,0 +1,36 @@
+# agents.docker-compose.mailer.example.yml — optional MailerSend agent
+#
+# The mailer agent is NOT part of the default delivery: it is an external
+# MCP connector operated at the user's charge. To enable it:
+#
+#   1. Copy this file NEXT TO YOUR .env (the directory where you run
+#      wiki-manager) under the name:  agents.docker-compose.override.yml
+#      That file is yours — wiki-manager never generates or overwrites it,
+#      and `wiki-workspace agents up` includes it automatically when present.
+#   2. Add to your .env:
+#        MAILER_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
+#        MAILERSEND_API_KEY=...
+#        MAILERSEND_FROM_EMAIL=...
+#   3. Declare the endpoint in your mcp.endpoints.json:
+#        "mailer": {
+#          "url": "http://host.docker.internal:${MAILER_MCP_PORT:-3335}/mcp/",
+#          "headers": { "Authorization": "Bearer ${MAILER_MCP_AUTH_TOKEN}" }
+#        }
+#
+services:
+  mailer:
+    image: dotdrelle/agent-mailer-api:latest
+    user: "${UID:-1000}:${GID:-1000}"
+    ports:
+      - "${MAILER_MCP_PORT:-3335}:8080"
+    environment:
+      - MAILERSEND_API_KEY=${MAILERSEND_API_KEY:-}
+      - MAILERSEND_FROM_EMAIL=${MAILERSEND_FROM_EMAIL:-no-reply@example.com}
+      - MAILERSEND_FROM_NAME=${MAILERSEND_FROM_NAME:-Mailer Agent}
+      - MAILERSEND_USER_AGENT=${MAILERSEND_USER_AGENT:-curl/8.7.1}
+      - MAILERSEND_VERIFY_SSL=${MAILERSEND_VERIFY_SSL:-true}
+      - MAILERSEND_CA_CERT=${MAILERSEND_CA_CERT:-}
+      - MAILER_REQUIRE_CONFIRMATION=${MAILER_REQUIRE_CONFIRMATION:-true}
+      - MAILER_DRY_RUN=${MAILER_DRY_RUN:-false}
+      - MCP_AUTH_TOKEN=${MAILER_MCP_AUTH_TOKEN:-}
+    restart: unless-stopped

package/agents.docker-compose.yml

@@ -1,6 +1,6 @@
 # agents.docker-compose.yml — external agent stack
 #
-# Starts cme, documents, and mailer as workspace-agnostic global services.
+# Starts cme and documents as workspace-agnostic global services.
 # All workspace paths are resolved at tool-call time via the `workspace` param.
 #
 # Required:
@@ -10,18 +10,12 @@
 #   AGENTS_DATA_DIR        — persistent state for stateful agents (default: ./.agents-data)
 #   CME_MCP_PORT           — 3336
 #   DOCUMENTS_MCP_PORT     — 3337
-#   MAILER_MCP_PORT        — 3335
 #   CME_MCP_AUTH_TOKEN     — bearer token for cme agent (empty = no auth)
 #   DOCUMENTS_MCP_AUTH_TOKEN — bearer token for documents agent (empty = no auth)
-#   DOCUMENT_LLM_BASE_URL  — https://api.openai.com/v1
-#   DOCUMENT_LLM_MODEL     — gpt-5.4-mini
+#   DOCUMENT_LLM_BASE_URL  — https://albert.api.etalab.gouv.fr/v1
+#   DOCUMENT_LLM_MODEL     — LightOnOCR-2-1B
 #   DOCUMENT_LLM_API_KEY   — OpenAI/OpenAI-compatible API key for document OCR
 #   DOCUMENT_LLM_TIMEOUT_SECONDS — 120
-#   MAILER_MCP_AUTH_TOKEN  — bearer token for mailer agent (empty = no auth)
-#   MAILERSEND_API_KEY
-#   MAILERSEND_FROM_EMAIL
-#   MAILERSEND_FROM_NAME
-#   MAILERSEND_CA_CERT    — optional CA bundle path inside the container
 #
 # Set these variables in a .env file at the directory where you run wiki-workspace,
 # or export them in your shell before running wiki-workspace agents up.
@@ -83,22 +77,3 @@ services:
       #- ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
     restart: unless-stopped
 
-  mailer:
-    image: dotdrelle/agent-mailer-api:latest
-    user: "${UID:-1000}:${GID:-1000}"
-    ports:
-      - "${MAILER_MCP_PORT:-3335}:8080"
-    environment:
-      - MAILERSEND_API_KEY=${MAILERSEND_API_KEY:-}
-      - MAILERSEND_FROM_EMAIL=${MAILERSEND_FROM_EMAIL:-no-reply@example.com}
-      - MAILERSEND_FROM_NAME=${MAILERSEND_FROM_NAME:-Mailer Agent}
-      - MAILERSEND_USER_AGENT=${MAILERSEND_USER_AGENT:-curl/8.7.1}
-      - MAILERSEND_VERIFY_SSL=${MAILERSEND_VERIFY_SSL:-true}
-      - MAILERSEND_CA_CERT=${MAILERSEND_CA_CERT:-}
-      - MAILER_REQUIRE_CONFIRMATION=${MAILER_REQUIRE_CONFIRMATION:-true}
-      - MAILER_DRY_RUN=${MAILER_DRY_RUN:-false}
-      - MCP_AUTH_TOKEN=${MAILER_MCP_AUTH_TOKEN:-}
-    # Optional: mount a CA bundle and set MAILERSEND_CA_CERT to its container path.
-    # volumes:
-    #   - ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
-    restart: unless-stopped

package/bin/wiki-manager

@@ -71,6 +71,13 @@ if [[ -z "$BUN_BIN" ]]; then
     'Reinstall @dotdrelle/wiki-manager or install Bun from https://bun.sh/docs/installation.' >&2
   exit 127
 fi
+if ! "$BUN_BIN" --version >/dev/null 2>&1; then
+  printf '%s\n' \
+    'The bundled Bun runtime is installed but not initialized.' \
+    'Local install:  npm approve-scripts bun' \
+    'Global install: npm install -g --allow-scripts=bun @dotdrelle/wiki-manager' >&2
+  exit 126
+fi
 
 if [[ ${#ARGS[@]} -eq 0 ]]; then
   exec "$BUN_BIN" "$BIN_DIR/wiki-manager.js"

package/docker-compose.yml

@@ -51,10 +51,8 @@ services:
       - PRODUCTION_MCP_PORT
       - CME_MCP_PORT
       - DOCUMENTS_MCP_PORT
-      - MAILER_MCP_PORT
       - CME_MCP_AUTH_TOKEN
       - DOCUMENTS_MCP_AUTH_TOKEN
-      - MAILER_MCP_AUTH_TOKEN
       - WORKSPACE_NAME
       - DOCUMENT_INPUT_DIR=/documents/input
       - DOCUMENT_UPLOADS_DIR=/documents/uploads

package/mcp.endpoints.example.json

@@ -24,12 +24,6 @@
       "headers": {
         "Authorization": "Bearer ${DOCUMENTS_MCP_AUTH_TOKEN}"
       }
-    },
-    "mailer": {
-      "url": "http://host.docker.internal:${MAILER_MCP_PORT:-3335}/mcp/",
-      "headers": {
-        "Authorization": "Bearer ${MAILER_MCP_AUTH_TOKEN}"
-      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.12.8",
+  "version": "0.12.10",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -27,6 +27,7 @@
     "wiki-workspace",
     "docker-compose.yml",
     "agents.docker-compose.yml",
+    "agents.docker-compose.mailer.example.yml",
     "mcp.endpoints.example.json",
     ".env.example",
     "tsconfig.json",

package/src/cli/wiki-manager.js

@@ -677,6 +677,9 @@ async function runRuntime(argv, agent) {
     port,
     store,
     getContext: getWorkspaceContext,
+    listActiveRuns: () => [...contexts.values()]
+      .filter((context) => context?.running)
+      .map((context) => ({ workspace: context.workspace ?? null, runId: context.currentRunId ?? null })),
     run: executeRun,
     cancel: (context) => emitRuntimeLog(context.session, 'runtime: cancel requested'),
     resume: ({ workspace }) => recoverRuntime({ workspace, manual: true }),
@@ -801,12 +804,18 @@ export async function runCli(argv) {
     let runtime = null;
     try {
       const { ensureRuntime } = await import('../runtime/lifecycle.js');
-      runtime = await ensureRuntime();
+      // If the manager files were just scaffolded, a pre-existing runtime
+      // predates them: restart it so its sessions load the new endpoints.
+      runtime = await ensureRuntime({ forceRestart: scaffolded.length > 0 });
     } catch (err) {
       runtime = unavailableRuntime(err);
       console.error(`Runtime unavailable: ${runtime.error}`);
     }
     await runOpenTuiShell({ agent, packageJson, runtime });
+    if (runtime?.url) {
+      const { shutdownOwnedRuntime } = await import('../runtime/lifecycle.js');
+      await shutdownOwnedRuntime(runtime, { log: (message) => console.log(`[wiki-manager] ${message}`) });
+    }
     return;
   }
 
@@ -821,4 +830,8 @@ export async function runCli(argv) {
     }
   }
   await runShell({ agent, packageJson, runtime });
+  if (runtime?.url) {
+    const { shutdownOwnedRuntime } = await import('../runtime/lifecycle.js');
+    await shutdownOwnedRuntime(runtime, { log: (message) => console.log(`[wiki-manager] ${message}`) });
+  }
 }

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.12.8",
-  "commit": "eefd59f"
+  "version": "0.12.10",
+  "commit": "e256e16"
 }

package/src/core/dockerCompose.test.js

@@ -22,5 +22,7 @@ test('agent compose services run as the host uid and gid', async () => {
   const agentsCompose = YAML.parse(agentsRaw);
   assert.equal(agentsCompose.services.cme.user, '${UID:-1000}:${GID:-1000}');
   assert.equal(agentsCompose.services.documents.user, '${UID:-1000}:${GID:-1000}');
-  assert.equal(agentsCompose.services.mailer.user, '${UID:-1000}:${GID:-1000}');
+  // MailerSend was an external-connector experiment — removed from the
+  // default stack (the agent repo still exists for ad-hoc use).
+  assert.equal(agentsCompose.services.mailer, undefined);
 });

package/src/core/env.js

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, readFileSync } from 'node:fs';
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -38,8 +38,8 @@ const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..')
 // mcp.endpoints.json nor .env, so the external agents (cme, mailer,
 // documents) silently never connect — /status shows no agents and Donna has
 // no CME tools to configure anything with. Copy the packaged examples so a
-// fresh directory works out of the box with the default agent ports; the
-// user only has to fill in tokens/keys.
+// fresh directory works out of the box with the default agent ports. Optional
+// credentials can be added later for the external services the user enables.
 export function ensureManagerScaffold({ log = () => {} } = {}) {
   const created = [];
   const endpointsFile = managerMcpEndpointsFile();
@@ -51,11 +51,18 @@ export function ensureManagerScaffold({ log = () => {} } = {}) {
   const envFile = managerEnvFile();
   const envExample = join(packageRoot, '.env.example');
   if (!existsSync(envFile) && existsSync(envExample)) {
-    copyFileSync(envExample, envFile);
+    // Substitute the documentation placeholders with real paths: a copied
+    // WORKSPACES_ROOT=/path/to/workspaces silently broke agents compose
+    // mounts until manually edited.
+    const workspacesRoot = join(managerStateDir(), 'workspaces');
+    const content = readFileSync(envExample, 'utf8')
+      .replace(/^WORKSPACES_ROOT=.*$/m, `WORKSPACES_ROOT=${workspacesRoot}`)
+      .replace(/^# WIKI_WORKSPACES_DIR=.*$/m, `WIKI_WORKSPACES_DIR=${workspacesRoot}`);
+    writeFileSync(envFile, content);
     created.push('.env');
   }
   if (created.length > 0) {
-    log(`scaffold: created ${created.join(' and ')} in ${managerStateDir()} from packaged example(s) — fill in tokens/keys (WIKI_WORKSPACES_DIR, *_MCP_AUTH_TOKEN…) before starting agents.`);
+    log(`configuration initialized successfully in ${managerStateDir()} — created ${created.join(' and ')} from packaged defaults. Optional credentials can be added later for external services.`);
   }
   return created;
 }

package/src/core/mcp.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
-const WIKI_MANAGER_VERSION = '0.12.8';
+const WIKI_MANAGER_VERSION = '0.12.10';
 
 function envValue(key) {
   const filePath = managerEnvFile();

package/src/core/wikiSetup.js

@@ -3,6 +3,7 @@ import { readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 import { patchWikircProfile } from './wikirc.js';
+import { managerEnvFile, managerMcpEndpointsFile } from './env.js';
 import { createWorkspace, findWorkspace, isValidWorkspaceName, listWorkspaces, managerRoot, workspacesDir } from './workspaces.js';
 
 const execFileAsync = promisify(execFile);
@@ -39,6 +40,13 @@ export async function startAgents(options = {}) {
       env: {
         ...process.env,
         WIKI_WORKSPACES_DIR: workspacesDir(),
+        // cwd is the npm package root (the script and compose files live
+        // there), so the manager files MUST be pinned explicitly: without
+        // these, wiki-workspace resolved .env and mcp.endpoints.json against
+        // $PWD and generated agent tokens into the PACKAGE directory — the
+        // user's .env stayed empty on a fresh install.
+        WIKI_MANAGER_ENV_FILE: managerEnvFile(),
+        WIKI_MANAGER_ENDPOINTS_FILE: managerMcpEndpointsFile(),
       },
       timeout: options.timeout ?? 180_000,
       maxBuffer: options.maxBuffer ?? 1024 * 1024 * 8,

package/src/runtime/lifecycle.js

@@ -39,6 +39,7 @@ export async function ensureRuntime({
   stateDir = process.env.WIKI_MANAGER_STATE_DIR ?? defaultRuntimeStateDir(),
   url = process.env.WIKI_MANAGER_RUNTIME_URL ?? `http://127.0.0.1:${port}`,
   timeoutMs = 5000,
+  forceRestart = false,
 } = {}) {
   const auth = resolveRuntimeAuthToken({ host, stateDir });
   if (auth.token) process.env.WIKI_MANAGER_RUNTIME_TOKEN = auth.token;
@@ -46,7 +47,11 @@ export async function ensureRuntime({
   if (existing) {
     const expectedCacertPath = activeCacertPath();
     const actualCacertPath = existing.cacertPath ? resolve(existing.cacertPath) : null;
-    if (actualCacertPath === expectedCacertPath) {
+    // forceRestart: the caller knows the manager configuration just changed
+    // (e.g. mcp.endpoints.json scaffolded on first run) — a runtime started
+    // BEFORE that only knows the old endpoints and would keep answering
+    // without the agents until manually restarted.
+    if (!forceRestart && actualCacertPath === expectedCacertPath) {
       return { url, started: false, health: existing, token: auth.token, tokenPath: auth.tokenPath };
     }
     await postRuntimeShutdown({ url, token: auth.token });
@@ -99,3 +104,28 @@ export async function runtimeHealthOrNull(url = runtimeUrlFromEnv(), token = run
     return null;
   }
 }
+
+// Contract with the user: the shell OWNS the runtime it started — leaving it
+// alive after exit produced zombie runtimes running yesterday's code and
+// yesterday's endpoints. Nuance preserved: if a run is active anywhere, the
+// runtime is left alive so the run survives the shell (that promise stays).
+export async function shutdownOwnedRuntime(runtime, { log = () => {} } = {}) {
+  if (!runtime?.url || !runtime?.started) return { action: 'kept', reason: 'not_owned' };
+  try {
+    const health = await runtimeHealthOrNull(runtime.url, runtime.token);
+    if (!health) return { action: 'kept', reason: 'unreachable' };
+    const activeRuns = Array.isArray(health.activeRuns) ? health.activeRuns : [];
+    if (activeRuns.length > 0) {
+      const labels = activeRuns
+        .map((run) => [run.workspace, run.runId ? String(run.runId).slice(0, 8) : null].filter(Boolean).join('/'))
+        .join(', ');
+      log(`runtime laissé actif : run en cours (${labels}) — il survivra à ce shell ; relance wiki-manager pour le retrouver.`);
+      return { action: 'kept', reason: 'run_active', activeRuns };
+    }
+    await postRuntimeShutdown({ url: runtime.url, token: runtime.token });
+    log('runtime arrêté (démarré par ce shell, aucun run en cours).');
+    return { action: 'shutdown' };
+  } catch (err) {
+    return { action: 'error', reason: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/runtime/server.js

@@ -20,6 +20,7 @@ export function startRuntimeServer({
   approve,
   configProfiles,
   useConfigProfile,
+  listActiveRuns = null,
   exitOnShutdown = process.env.WIKI_MANAGER_RUNTIME_CHILD === '1',
 } = {}) {
   const clients = new Set();
@@ -52,10 +53,14 @@ export function startRuntimeServer({
       if (request.method === 'GET' && url.pathname === '/health') {
         const workspace = workspaceFromUrl(url);
         const context = workspace ? await resolveContext({ workspace }) : null;
+        // activeRuns spans ALL workspace contexts: the shell uses it at exit
+        // to decide whether shutting down its own runtime would kill work.
+        const activeRuns = typeof listActiveRuns === 'function' ? listActiveRuns() : [];
         sendJson(response, 200, {
           ok: true,
           status: context?.running ? 'running' : 'idle',
           workspace: context?.workspace ?? workspace ?? null,
+          activeRuns,
           dbPath: store.dbPath,
           cacertPath: activeCacertPath(),
           nodeExtraCaCerts: process.env.NODE_EXTRA_CA_CERTS ?? null,

package/src/runtime/server.test.js

@@ -1396,3 +1396,31 @@ test('runtime server answers control messages posted to /run during an active ru
     await handle.close();
   }
 });
+
+test('runtime health reports active runs across workspaces', async (t) => {
+  let handle;
+  try {
+    handle = await startRuntimeServer({
+      host: '127.0.0.1',
+      port: 0,
+      store: { dbPath: ':memory:', getState: () => ({ status: 'idle' }), listEvents: () => [] },
+      session: {},
+      // The shell reads this at exit: shutting down its own runtime must not
+      // kill a run that is supposed to survive the shell.
+      listActiveRuns: () => [{ workspace: 'juno', runId: 'run-1234abcd' }],
+    });
+  } catch (err) {
+    if (err?.code === 'EPERM') {
+      t.skip('network listen is not permitted in this sandbox');
+      return;
+    }
+    throw err;
+  }
+
+  try {
+    const health = await (await fetch(`http://127.0.0.1:${handle.port}/health`)).json();
+    assert.deepEqual(health.activeRuns, [{ workspace: 'juno', runId: 'run-1234abcd' }]);
+  } finally {
+    await handle.close();
+  }
+});

package/src/shell/tui.tsx

@@ -393,10 +393,13 @@ export async function runOpenTuiShell({
   packageJson: Record<string, unknown>;
   runtime?: any;
 }) {
-  await render(() => <App agent={agent} packageJson={packageJson} runtime={runtime} />, {
-    exitOnCtrlC: false,
-    useMouse: true,
-    targetFps: 30,
+  await new Promise<void>((resolve, reject) => {
+    render(() => <App agent={agent} packageJson={packageJson} runtime={runtime} />, {
+      exitOnCtrlC: false,
+      useMouse: true,
+      targetFps: 30,
+      onDestroy: resolve,
+    }).catch(reject);
   });
   return {};
 }

package/wiki-workspace

@@ -86,7 +86,7 @@ Commands:
   up <workspace> [--open]           Start workspace stack: wiki + production
   list                              List configured workspaces
 
-  agents up [--pull]                Start all external agents (cme, documents, mailer)
+  agents up [--pull]                Start all external agents (cme, documents)
   agents down                       Stop all external agents
   agents logs [args...]             Follow external agent logs
   agents pull                       Pull latest external agent images
@@ -215,9 +215,15 @@ agents_compose() {
     local cacert_args=()
     WORKSPACES_ROOT="$workspaces_root" AGENTS_DATA_DIR="$agents_data_dir" \
       read_lines_into_array cacert_args cacert_compose_args "$agents_compose_file" "agents.cacert.compose.yml"
+    # User-owned override: optional external agents (e.g. mailer) live in a
+    # file the user maintains NEXT TO the .env — never generated, never
+    # overwritten by package updates.
+    local override_args=()
+    local user_override="$MANAGER_STATE_DIR/agents.docker-compose.override.yml"
+    [[ -f "$user_override" ]] && override_args+=(-f "$user_override")
     WORKSPACES_ROOT="$workspaces_root" AGENTS_DATA_DIR="$agents_data_dir" \
       docker compose --project-directory "$DEFAULT_MANAGER_DIR" \
-        ${compose_env_args[@]+"${compose_env_args[@]}"} -f "$agents_compose_file" ${cacert_args[@]+"${cacert_args[@]}"} -p wiki-agents "$@"
+        ${compose_env_args[@]+"${compose_env_args[@]}"} -f "$agents_compose_file" ${override_args[@]+"${override_args[@]}"} ${cacert_args[@]+"${cacert_args[@]}"} -p wiki-agents "$@"
   }
 
   case "$subcommand" in
@@ -245,8 +251,9 @@ agents_compose() {
       printf 'Workspaces root: %s\n' "$workspaces_root"
       printf 'Agents data:     %s\n' "$agents_data_dir"
       [[ -z "$CACERT_PATH" ]] || printf 'CA cert:         %s -> /wiki-manager-ca.pem\n' "$CACERT_PATH"
-      printf 'Agents: cme=:%s  documents=:%s  mailer=:%s\n' \
-        "${CME_MCP_PORT:-3336}" "${DOCUMENTS_MCP_PORT:-3337}" "${MAILER_MCP_PORT:-3335}"
+      printf 'Agents: cme=:%s  documents=:%s\n' \
+        "${CME_MCP_PORT:-3336}" "${DOCUMENTS_MCP_PORT:-3337}"
+      [[ ! -f "$MANAGER_STATE_DIR/agents.docker-compose.override.yml" ]] || printf 'User override: agents.docker-compose.override.yml included\n'
       ;;
     down)
       [[ $# -eq 0 ]] || die "agents down does not take arguments"
@@ -389,12 +396,12 @@ ensure_runtime_node() {
 }
 
 ensure_agent_tokens() {
-  # The external agents (cme, documents, mailer) authenticate with tokens
+  # The external agents (cme, documents) authenticate with tokens
   # from the manager .env — generate any missing one, exactly like the
   # workspace and runtime tokens are generated. Leaving them empty made a
   # fresh install start agents nobody could talk to.
   local key token
-  for key in CME_MCP_AUTH_TOKEN DOCUMENTS_MCP_AUTH_TOKEN MAILER_MCP_AUTH_TOKEN; do
+  for key in CME_MCP_AUTH_TOKEN DOCUMENTS_MCP_AUTH_TOKEN; do
     token="$(env_value "$MANAGER_ENV_FILE" "$key" "")"
     if [[ -z "$token" ]]; then
       token="$(generate_token)"