@dotdrelle/wiki-manager 0.15.32 → 0.15.35

package/src/shell/repl.js

@@ -9,12 +9,13 @@ import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 import { buildAgentSystemPrompt, formatLlmUnavailableMessage, isOrchestrationBypassTool } from '../agent/graph.js';
 import { handleSlashCommand, rawCommandAgentPrompt } from '../commands/slash.js';
-import { serviceDescription, serviceNames as composeServiceNames } from '../core/compose.js';
+import { serviceChoices as composeServiceChoices, serviceDescription } from '../core/compose.js';
 import { extractActivity, parseJsonText, sessionActivities } from '../core/activity.js';
 import { syncActivitiesToPlan } from '../core/plan.js';
 import { buildLlmTools, callMcpTool, formatMcpToolResult, parseToolCallName, resolveToolCallName } from '../core/mcp.js';
 import { runBoundedToolLoop } from '../core/toolLoop.js';
 import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { togglableAgentNames } from '../core/agentsCompose.js';
 import { listSkills } from '../core/skills.js';
 import { listWikircProfiles } from '../core/wikirc.js';
 import { listWorkspaces } from '../core/workspaces.js';
@@ -78,7 +79,7 @@ const COMMAND_COMPLETION_DESCRIPTIONS = {
   '/stop': 'Stop one service or the workspace service set.',
   '/logs': 'Show recent logs for a service.',
   '/mcp': 'Inspect or call workspace MCP servers.',
-  '/connector': 'List connectors or authorize one — /connector auth <connector>.',
+  '/connector': 'List connectors, or authorize one with all its rights — /connector auth google.',
   '/wiki': 'Run llm-wiki commands for the active workspace.',
   '/skills': 'List workspace skills.',
   '/upload': 'Upload a document — /upload <path>',
@@ -256,8 +257,19 @@ function wikircProfileNames(session) {
     : [];
 }
 
-function serviceNames() {
-  return composeServiceNames();
+function serviceChoices() {
+  return composeServiceChoices();
+}
+
+/**
+ * Agents proposés un par un, en plus du raccourci `agents`.
+ *
+ * Seulement ceux derrière un drapeau de profil. Lister tous les agents avait
+ * rallongé la liste de quatre entrées, dont `mailer` qui n'existe même pas tant
+ * que l'opérateur ne l'a pas décommenté dans son override.
+ */
+function togglableAgents() {
+  return togglableAgentNames();
 }
 
 function skillNames(session) {
@@ -282,6 +294,11 @@ function completionValuesFor(parts, inputBuffer, session) {
   if (command === '/mcp' && parts[1] === 'call' && tokenIndex === 3) return mcpToolNames(session, parts[2]);
   if (command === '/connector' && tokenIndex === 1) return ['auth', 'list'];
   if (command === '/connector' && previousToken === 'auth') return ['google'];
+  // Pas de complétion des droits après le connecteur. `/connector auth google`
+  // demande déjà tout ce que l'agent sait faire, en une autorisation : proposer
+  // une liste laissait croire qu'il fallait choisir, et transformait une
+  // commande à taper d'un trait en menu à trois entrées. Les droits restent
+  // saisissables un par un pour restreindre, et le libellé de /connector le dit.
   if (command === '/upload' && tokenIndex === 1) return ['convert'];
   if (command === '/upload' && parts[1] === 'convert' && tokenIndex === 2) return ['pending'];
   if (command === '/uploads' && tokenIndex === 1) return ['clean', 'list'];
@@ -301,9 +318,11 @@ function completionValuesFor(parts, inputBuffer, session) {
   if (command === '/wiki' && tokenIndex === 1) return ['run'];
   if (command === '/skills' && tokenIndex === 1) return ['edit', 'list', 'run', 'show'];
   if (command === '/skills' && ['edit', 'run', 'show'].includes(previousToken ?? '')) return skillNames(session);
-  if (command === '/start' && tokenIndex === 1) return ['all', 'agents', 'services', ...serviceNames()];
-  if (command === '/stop' && tokenIndex === 1) return ['agents', ...serviceNames()];
-  if (command === '/logs' && tokenIndex === 1) return serviceNames();
+  // Vocabulaire de l'opérateur uniquement : `serviceChoices()` écarte les noms
+  // Compose bruts que les alias désignent déjà. Ils restent tapables.
+  if (command === '/start' && tokenIndex === 1) return ['all', 'agents', 'services', ...serviceChoices(), ...togglableAgents()];
+  if (command === '/stop' && tokenIndex === 1) return ['all', 'agents', 'services', ...serviceChoices(), ...togglableAgents()];
+  if (command === '/logs' && tokenIndex === 1) return ['all', ...serviceChoices()];
   return [];
 }
 
@@ -533,12 +552,19 @@ export function completionDescription(value, parts) {
   if (subcommand) return subcommand;
   if (command === '/use') return 'Load this workspace.';
   if (command === '/start') {
-    if (value === 'all') return 'Start the workspace services AND the external agents.';
-    if (value === 'agents' || value === 'agent') return 'Start the external agents only.';
-    if (value === 'services') return 'Start the workspace services only.';
+    if (value === 'all') return 'Everything: workspace services AND external agents.';
+    if (value === 'agents' || value === 'agent') return 'External agents only (CME, documents, connectors…).';
+    if (value === 'services') return 'Workspace services only, without the external agents.';
+    if (togglableAgents().includes(value)) return `Start only the ${value} agent, leaving the other agents as they are.`;
     return serviceDescription(value) ?? 'Start this Docker Compose service.';
   }
-  if (command === '/stop') return serviceDescription(value) ?? 'Stop this Docker Compose service.';
+  if (command === '/stop') {
+    if (value === 'all') return 'Everything: workspace services AND external agents.';
+    if (value === 'agents' || value === 'agent') return 'External agents only.';
+    if (value === 'services') return 'Workspace services only.';
+    if (togglableAgents().includes(value)) return `Stop only the ${value} agent, leaving the other agents running.`;
+    return serviceDescription(value) ?? 'Stop this Docker Compose service.';
+  }
   if (command === '/logs') return serviceDescription(value) ?? 'Show logs for this Docker Compose service.';
   if (command === '/workspace') {
     if (parts[1] === 'delete' && value === '--confirm') return 'Confirm workspace deletion.';

package/src/shell/setupWizardDiscovery.test.js

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const source = readFileSync(
+  fileURLToPath(new URL('./SetupWizard.tsx', import.meta.url)),
+  'utf8',
+);
+
+test('model discovery never blocks a wizard step', () => {
+  // La régression d'origine : `await discoverModels()` sur l'étape clé API
+  // gelait l'écran pendant tout le délai réseau, sans rien afficher.
+  assert.doesNotMatch(source, /await\s+(start|discover)\w*[Dd]iscover\w*\(/);
+  assert.doesNotMatch(source, /await\s+fetch(Models|GatewayCatalog)\(/);
+  assert.match(source, /startDiscovery\(\{ \.\.\.llm\(\), apiKey: value \}\);\s*\n\s*return navigate\('llm-model'\)/);
+});
+
+test('a late answer cannot overwrite a newer discovery', () => {
+  assert.match(source, /discoveryRun \+= 1;/);
+  assert.match(source, /if \(run !== discoveryRun\) return;/);
+});
+
+test('the gateway flat list is shown before the typed catalog', () => {
+  assert.match(source, /onPartial:/);
+  assert.match(source, /Refining chat\/embedding\/rerank types/);
+});
+
+test('the discovery panel reports state, endpoint and transport', () => {
+  for (const fragment of [
+    'Reading the model catalog',
+    'Model catalog unavailable',
+    'Cause: ',
+    'Transport: ',
+    'transportSummary()',
+    'model(s) available',
+  ]) {
+    assert.ok(source.includes(fragment), `discovery panel must show: ${fragment}`);
+  }
+});
+
+test('the wizard fills the terminal instead of a fixed narrow box', () => {
+  const width = source.match(/const dialogWidth = \(\) => ([^;]+);/);
+  const height = source.match(/const dialogHeight = \(\) => ([^;]+);/);
+  assert.ok(width && height);
+  assert.match(width[1], /Math\.min\(1\d\d,/);
+  assert.match(height[1], /Math\.min\([34]\d,/);
+});

package/src/shell/setupWizardPlaceholders.test.js

@@ -22,11 +22,22 @@ test('the wizard treats scaffolded config values as unset', { skip: !existsSync(
   // Cross-repo guard: if the scaffold ever ships a different fake endpoint or
   // secret, the wizard would prefill it as a real answer and a skipped step
   // would write it to the operator's config.
+  // `embeddingModel` et `rerankerModel` ont ete ajoutes ici apres coup : ils
+  // etaient les seuls champs du scaffold a porter une valeur d'apparence reelle
+  // (`BAAI/bge-m3`), que le wizard preremplissait donc comme une reponse
+  // choisie — et qui filtrait le catalogue sur zero resultat des que le serveur
+  // nommait le meme modele autrement.
   const placeholders = [
-    ...scaffold.matchAll(/^\s*(baseUrl|apiKey|model):\s*(\S+)\s*$/gm),
+    ...scaffold.matchAll(/^\s*(baseUrl|apiKey|model|embeddingModel|rerankerModel):\s*(\S+)\s*$/gm),
   ].map(([, key, value]) => [key, value]);
 
-  assert.ok(placeholders.length >= 4, 'expected the scaffold to declare endpoints and secrets');
+  assert.ok(placeholders.length >= 6, 'expected the scaffold to declare endpoints, secrets and models');
+  for (const key of ['embeddingModel', 'rerankerModel']) {
+    assert.ok(
+      placeholders.some(([name]) => name === key),
+      `the scaffold must declare ${key} so this guard covers it`,
+    );
+  }
   for (const [key, value] of placeholders) {
     assert.match(value, regex, `scaffolded ${key}=${value} must be recognised as a placeholder`);
   }
@@ -41,6 +52,8 @@ test('preloading a profile filters placeholders out of every prefilled field', (
     'model: configuredValue(config.llm.model)',
     'baseUrl: configuredValue(config.retrieval.vector.baseUrl)',
     'apiKey: configuredValue(config.retrieval.vector.apiKey)',
+    'embeddingModel: configuredValue(config.retrieval.vector.embeddingModel)',
+    'rerankerModel: configuredValue(config.retrieval.vector.rerankerModel)',
   ]) {
     assert.ok(source.includes(field), `preloadWikirc must filter ${field}`);
   }
@@ -48,7 +61,7 @@ test('preloading a profile filters placeholders out of every prefilled field', (
   // With the vector URL filtered to null, this is what makes the embeddings
   // step offer the base URL the operator just typed.
   assert.match(source, /const baseUrl = vector\(\)\.baseUrl \|\| llm\(\)\.baseUrl;/);
-  assert.match(source, /baseUrl: old\.baseUrl \|\| llm\(\)\.baseUrl \|\| defaultBaseUrl\(llm\(\)\.provider\)/);
+  assert.match(source, /baseUrl: old\.baseUrl \|\| llm\(\)\.baseUrl \|\| defaultBaseUrl\(llm\(\)\.provider, llm\(\)\.engine\)/);
 });
 
 test('a real configuration is never mistaken for a placeholder', () => {

package/src/shell/setupWizardSuggestions.test.js

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readFileSync } from 'node:fs';
+
+const source = readFileSync(new URL('./SetupWizard.tsx', import.meta.url), 'utf8');
+
+test('the model steps feed the discovered catalog into the filter', () => {
+  // Trois étapes doivent porter des suggestions : modèle LLM, embeddings,
+  // reranker. Sans elles, le filtre n'a rien a filtrer.
+  const occurrences = source.match(/\.\.\.suggestionField\(/g) ?? [];
+  assert.equal(occurrences.length, 3);
+  assert.match(source, /suggestions: discovered/);
+});
+
+test('no model is preselected when a catalog was discovered', () => {
+  // Preremplir avec le premier modele decouvert filtrait la liste sur
+  // lui-meme : neuf entrees sur dix devenaient invisibles.
+  assert.match(source, /prefill: usable \?\? \(discovered\.length === 0 \? example : ''\)/);
+  assert.doesNotMatch(source, /prefill: [^\n]*discovered\[0\]/);
+});
+
+test('a configured model absent from the catalog is not prefilled', () => {
+  // Le `BAAI/bge-m3` du scaffold face a un serveur qui nomme le meme modele
+  // `bge-m3` : preremplir filtrait la liste sur zero resultat, et l'ecran
+  // affichait « No match » devant dix modeles disponibles.
+  assert.match(source, /discovered\.length === 0 \|\| discovered\.includes\(configured\)/);
+  assert.match(source, /is not in this catalog — pick one below/);
+});
+
+test('the list is navigable with the arrows and confirmed in two steps', () => {
+  assert.match(source, /keyName === 'down' \|\| keyName === 'up'/);
+  assert.match(source, /if \(hovered && \(isEnter \|\| keyName === 'tab'\)\)/);
+  // Le premier Enter depose la valeur, il ne valide pas l'etape.
+  assert.match(source, /setInput\(hovered\);\s*\n\s*setHighlight\(-1\);\s*\n\s*return;/);
+});
+
+test('the typed value always wins over the suggestion list', () => {
+  // Garde-fou : la liste ne doit jamais devenir un select. Si ce message
+  // disparait, c'est que la saisie libre a ete perdue.
+  assert.match(source, /the typed value wins/);
+  assert.match(source, /the typed value is used as-is/);
+});
+
+test('suggestions are filtered by the current input, not shown raw', () => {
+  assert.match(source, /all\.filter\(\(item\) => item\.toLowerCase\(\)\.includes\(needle\)\)/);
+  // Fenetre glissante : la liste defile au lieu de s'arreter aux premieres
+  // entrees, sinon un catalogue de 200 modeles reste inatteignable.
+  assert.match(source, /matches\.slice\(offset, offset \+ SUGGESTION_ROWS\)/);
+});
+
+test('the language typed by the operator is the one displayed back', () => {
+  // Sans ce setLanguage, le recapitulatif affichait la langue lue dans le
+  // scaffold a la creation du workspace, pas celle qui vient d'etre saisie.
+  assert.match(
+    source,
+    /writeLanguageConfig\([^)]*\);\s*(\n\s*\/\/[^\n]*)*\n\s*setLanguage\(lang\);/,
+  );
+});

package/src/shell/wrapText.js

@@ -0,0 +1,57 @@
+/**
+ * Découpe un texte en lignes tenant dans la largeur d'une boîte TUI.
+ *
+ * Le wizard rendait chaque libellé, note ou erreur dans un `<text height={1}>` :
+ * au delà de la largeur du dialogue le texte était coupé net, sans ellipse ni
+ * indice. Les phrases les plus utiles — la note d'une étape, la cause d'une
+ * erreur de connexion — sont les plus longues, donc les plus tronquées.
+ *
+ * Le module est volontairement en JavaScript pur, hors du composant : c'est ce
+ * qui le rend testable sans transpiler du JSX.
+ *
+ * @param {string} text texte à découper ; les `\n` explicites sont respectés.
+ * @param {number} width largeur utile en colonnes.
+ * @param {number} maxLines nombre de lignes maximum ; la dernière est
+ *   marquée d'une ellipse quand il reste du texte, pour que la troncature
+ *   restante soit au moins visible.
+ * @returns {string[]}
+ */
+export function wrapText(text, width, maxLines = 6) {
+  const safeWidth = Math.max(8, Math.floor(width) || 8);
+  const lines = [];
+  for (const paragraph of String(text ?? '').split('\n')) {
+    if (paragraph.trim() === '') {
+      lines.push('');
+      continue;
+    }
+    let current = '';
+    for (const word of paragraph.split(/\s+/).filter(Boolean)) {
+      // Un mot plus long que la boîte — une URL, un chemin, un nom de modèle
+      // qualifié — est coupé plutôt que de déborder : mieux vaut le lire en
+      // deux morceaux que pas du tout.
+      if (word.length > safeWidth) {
+        if (current) {
+          lines.push(current);
+          current = '';
+        }
+        for (let i = 0; i < word.length; i += safeWidth) {
+          lines.push(word.slice(i, i + safeWidth));
+        }
+        current = lines.pop() ?? '';
+        continue;
+      }
+      if (!current) current = word;
+      else if (current.length + 1 + word.length <= safeWidth) current += ` ${word}`;
+      else {
+        lines.push(current);
+        current = word;
+      }
+    }
+    if (current) lines.push(current);
+  }
+  if (lines.length <= maxLines) return lines;
+  const kept = lines.slice(0, maxLines);
+  const last = kept[maxLines - 1] ?? '';
+  kept[maxLines - 1] = `${last.slice(0, Math.max(1, safeWidth - 1))}…`;
+  return kept;
+}

package/src/shell/wrapText.test.js

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { wrapText } from './wrapText.js';
+
+test('wraps on word boundaries within the given width', () => {
+  const lines = wrapText('Required: an agentic model with tool calling support.', 20);
+  assert.ok(lines.length > 1);
+  for (const line of lines) assert.ok(line.length <= 20, `too wide: ${line}`);
+  assert.equal(lines.join(' '), 'Required: an agentic model with tool calling support.');
+});
+
+test('keeps explicit line breaks', () => {
+  assert.deepEqual(wrapText('one\ntwo', 40), ['one', 'two']);
+});
+
+test('splits a word longer than the box instead of letting it overflow', () => {
+  const lines = wrapText('https://gateway.internal.example.com/v1/models', 16);
+  for (const line of lines) assert.ok(line.length <= 16, `too wide: ${line}`);
+  assert.equal(lines.join(''), 'https://gateway.internal.example.com/v1/models');
+});
+
+test('marks the truncation instead of cutting silently', () => {
+  const lines = wrapText('a b c d e f g h i j k l m n o p', 4, 2);
+  assert.equal(lines.length, 2);
+  assert.ok(lines[1].endsWith('…'));
+});
+
+test('a short text is returned untouched', () => {
+  assert.deepEqual(wrapText('API key', 40), ['API key']);
+});
+
+test('the wizard renders every prose field through wrapText', () => {
+  const source = readFileSync(
+    fileURLToPath(new URL('./SetupWizard.tsx', import.meta.url)),
+    'utf8',
+  );
+  // Garde-fou : un `<text height={1}>` autour d'un libellé, d'une note ou
+  // d'une erreur réintroduirait la troncature silencieuse.
+  for (const call of [
+    'wrapText((step() as any).message ?? (step() as any).label, textWidth(), 5)',
+    'wrapText((step() as any).note, textWidth(), 4)',
+    'wrapText(message(), textWidth(), 5)',
+  ]) {
+    assert.ok(source.includes(call), `missing wrapped render: ${call}`);
+  }
+});

package/wiki-workspace

@@ -262,30 +262,10 @@ agents_compose() {
   local compose_env_args=()
   [[ -f "$MANAGER_ENV_FILE" ]] && compose_env_args+=(--env-file "$MANAGER_ENV_FILE")
 
-  # Local-iteration build only: the packaged connectors service carries a
-  # `build:` block pointing at the sibling agent-connectors repo, whose OAuth
-  # credentials live in a gitignored .env.build.local. Compose resolves the
-  # value-less build args from *this* process environment, not from
-  # --env-file, so the variables must be exported here or the image ships with
-  # empty WIKILLM_GOOGLE_OAUTH_* and every Google connector stays unusable.
-  local connectors_build_env="$ROOT_DIR/../agent-external/agent-connectors/.env.build.local"
-  if [[ -f "$connectors_build_env" ]]; then
-    local build_key build_value
-    while IFS='=' read -r build_key build_value; do
-      case "$build_key" in
-        WIKILLM_GOOGLE_OAUTH_CLIENT_ID|WIKILLM_GOOGLE_OAUTH_CLIENT_SECRET) ;;
-        *) continue ;;
-      esac
-      [[ -n "${!build_key:-}" ]] || export "$build_key=$build_value"
-    done < <(grep -v '^[[:space:]]*#' "$connectors_build_env" || true)
-  fi
-
-  require_connectors_build_credentials() {
-    local build_key
-    for build_key in WIKILLM_GOOGLE_OAUTH_CLIENT_ID WIKILLM_GOOGLE_OAUTH_CLIENT_SECRET; do
-      [[ -n "${!build_key:-}" ]] || die "cannot build connectors: $build_key is missing from $connectors_build_env"
-    done
-  }
+  # Ce script ne construit aucune image. L'application OAuth Google est cuite
+  # dans l'image publiée par build-and-push.sh ; pour en utiliser une autre,
+  # l'opérateur pose GOOGLE_OAUTH_CLIENT_ID / _SECRET dans le .env du manager,
+  # que Compose transmet au conteneur et qui l'emporte sur la valeur embarquée.
 
   _agents_dc() {
     local cacert_args=()
@@ -312,12 +292,11 @@ agents_compose() {
         do_pull=true
         shift
       fi
-      [[ $# -eq 0 ]] || die "agents up accepts only --pull"
+      # Services nommés : démarrer `connectors` seul une fois le profil actif,
+      # sans relancer toute la pile. Sans argument, tout monte comme avant.
+      local only_services=("$@")
       ensure_agent_tokens
       ensure_endpoints_file
-      if connectors_enabled && [[ -f "$ROOT_DIR/../agent-external/agent-connectors/Dockerfile" ]]; then
-        require_connectors_build_credentials
-      fi
       # The .env may have just been created above — recompute the env-file
       # flag so freshly generated tokens reach the containers on first run.
       compose_env_args=()
@@ -330,6 +309,7 @@ agents_compose() {
       if [[ -n "$CACERT_PATH" ]]; then
         up_args+=(--force-recreate)
       fi
+      up_args+=(${only_services[@]+"${only_services[@]}"})
       _agents_dc "${up_args[@]}"
       printf 'Workspaces root: %s\n' "$workspaces_root"
       printf 'Agents data:     %s\n' "$agents_data_dir"
@@ -341,8 +321,15 @@ agents_compose() {
       [[ ! -f "$MANAGER_COMPOSE_DIR/agents.docker-compose.override.yml" ]] || printf 'User override: %s\n' "$MANAGER_COMPOSE_DIR/agents.docker-compose.override.yml"
       ;;
     down)
-      [[ $# -eq 0 ]] || die "agents down does not take arguments"
-      _agents_dc down
+      # `down` sans argument démonte la pile ; avec des services nommés, Compose
+      # n'accepte que `stop` + `rm` — `down <service>` supprime le réseau commun
+      # et couperait les autres agents.
+      if [[ $# -eq 0 ]]; then
+        _agents_dc down
+      else
+        _agents_dc stop "$@"
+        _agents_dc rm -f "$@"
+      fi
       ;;
     purge)
       [[ $# -eq 0 ]] || die "agents purge does not take arguments"
@@ -634,12 +621,65 @@ runtime_pid_command() {
   ps -p "$pid" -o command= 2>/dev/null || ps -p "$pid" -o args= 2>/dev/null || true
 }
 
+runtime_command_looks_like_runtime() {
+  local command="$1"
+  [[ "$command" == *"/bin/wiki-manager.js runtime"* || "$command" == *" bin/wiki-manager.js runtime"* ]]
+}
+
 runtime_pid_matches() {
   local pid command
   pid="$(cat "$(runtime_pid_file)" 2>/dev/null || true)"
   [[ "$pid" =~ ^[0-9]+$ ]] || return 1
   command="$(runtime_pid_command "$pid")"
-  [[ "$command" == *"/bin/wiki-manager.js runtime"* || "$command" == *" bin/wiki-manager.js runtime"* ]]
+  runtime_command_looks_like_runtime "$command"
+}
+
+# Pids qui écoutent sur le port du runtime, quel que soit leur parent.
+#
+# Un runtime démarré par une session de shell précédente survit à la mort de
+# cette session : il ne répond plus à notre jeton (401, donc « injoignable »)
+# et son fichier pid a disparu avec l'ancien répertoire d'état. Sans ce repli,
+# `runtime down` répond « not running » pendant que le port reste occupé, et il
+# ne reste que le `kill` manuel — inacceptable pour qui utilise l'application.
+runtime_port_pids() {
+  local port="$1"
+  if command -v lsof >/dev/null 2>&1; then
+    lsof -nP -iTCP:"$port" -sTCP:LISTEN -t 2>/dev/null | sort -u
+  elif command -v ss >/dev/null 2>&1; then
+    ss -lptnH "sport = :${port}" 2>/dev/null |
+      grep -o 'pid=[0-9]*' | cut -d= -f2 | sort -u
+  fi
+}
+
+# Arrête les runtimes orphelins tenant le port. Ne tue QUE des processus dont
+# la ligne de commande est celle d'un `wiki-manager runtime` : un port occupé
+# par autre chose est signalé, jamais tué.
+runtime_kill_orphans() {
+  local port="$1"
+  local pid command stopped=0 waited
+  while read -r pid; do
+    [[ "$pid" =~ ^[0-9]+$ ]] || continue
+    [[ "$pid" == "$$" ]] && continue
+    command="$(runtime_pid_command "$pid")"
+    if ! runtime_command_looks_like_runtime "$command"; then
+      printf 'port %s is held by pid %s, which is not a wiki-manager runtime — leaving it alone\n' "$port" "$pid" >&2
+      printf 'command: %s\n' "$command" >&2
+      continue
+    fi
+    printf 'Stopping orphan agent-runtime (pid %s)\n' "$pid"
+    kill "$pid" 2>/dev/null || true
+    waited=0
+    while kill -0 "$pid" 2>/dev/null && (( waited < 50 )); do
+      sleep 0.1
+      (( waited++ )) || true
+    done
+    if kill -0 "$pid" 2>/dev/null; then
+      printf 'pid %s did not stop, sending SIGKILL\n' "$pid" >&2
+      kill -9 "$pid" 2>/dev/null || true
+    fi
+    stopped=1
+  done < <(runtime_port_pids "$port")
+  (( stopped == 1 ))
 }
 
 runtime_port() {
@@ -704,6 +744,14 @@ runtime_command() {
       if runtime_pid_running; then
         printf 'Waiting for agent-runtime process (pid %s)...\n' "$(cat "$pid_file")"
       else
+        # Le port peut être tenu par un runtime d'une session précédente, qui
+        # répond 401 à notre jeton : la sonde de santé le croit absent, et le
+        # démarrage se solderait par un EADDRINUSE incompréhensible. On le
+        # remplace, puisque `runtime up` veut précisément un runtime ici.
+        if [[ -n "$(runtime_port_pids "$port")" ]]; then
+          printf 'Port %s is already held by an unreachable agent-runtime.\n' "$port"
+          runtime_kill_orphans "$port" || true
+        fi
         WIKI_WORKSPACES_DIR="$WORKSPACES_DIR" \
         WIKI_MANAGER_ENV_FILE="$MANAGER_ENV_FILE" \
         WIKI_MANAGER_STATE_DIR="$MANAGER_RUNTIME_DIR" \
@@ -730,12 +778,24 @@ runtime_command() {
           sleep 0.1
           (( wait_count++ )) || true
         done
+        # Un arrêt propre refusé laissait le port occupé sans le dire.
+        if runtime_health_check; then
+          printf 'agent-runtime ignored the shutdown request; stopping the process\n' >&2
+          runtime_kill_orphans "$port" || true
+        fi
         rm -f "$pid_file"
         printf 'agent-runtime stopped\n'
         return
       fi
       if ! runtime_pid_running; then
-        printf 'agent-runtime is not running from %s\n' "$pid_file"
+        # Ni sain, ni référencé par un pid : reste le port. C'est le cas d'un
+        # orphelin, qu'on ne peut pas demander à l'utilisateur de tuer.
+        if runtime_kill_orphans "$port"; then
+          rm -f "$pid_file"
+          printf 'agent-runtime stopped\n'
+          return
+        fi
+        printf 'agent-runtime is not running (no healthy endpoint, no pid in %s, nothing listening on port %s)\n' "$pid_file" "$port"
         rm -f "$pid_file"
         return
       fi
@@ -757,6 +817,16 @@ runtime_command() {
         printf 'agent-runtime process running (pid %s), health check failed\n' "$(cat "$pid_file")"
         exit 1
       else
+        local orphan_pids
+        orphan_pids="$(runtime_port_pids "$port")"
+        if [[ -n "$orphan_pids" ]]; then
+          # Le symptôme perçu comme « ça ne démarre pas » : quelqu'un tient le
+          # port et répond 401 à notre jeton, donc les sondes le voient absent.
+          printf 'agent-runtime is not reachable with this token, but pid(s) %s hold port %s\n' \
+            "$(printf '%s' "$orphan_pids" | tr '\n' ' ')" "$port"
+          printf 'run `%s runtime down` to stop it\n' "$(basename "$0")"
+          exit 1
+        fi
         printf 'agent-runtime is not running\n'
         exit 1
       fi
@@ -792,6 +862,19 @@ refresh_project() {
 
   printf 'Removing external-agent stack and images...\n'
   agents_compose purge
+
+  # `refresh` promet un état propre : le vérifier plutôt que l'affirmer. Un
+  # port encore tenu ici signifie qu'il l'est par un processus étranger, que
+  # `runtime down` refuse de tuer à raison — mais le taire ferait échouer le
+  # prochain démarrage sans que personne ne fasse le lien.
+  local leftover
+  leftover="$(runtime_port_pids "$(runtime_port)")"
+  if [[ -n "$leftover" ]]; then
+    printf 'Refresh incomplete: port %s is still held by pid(s) %s.\n' \
+      "$(runtime_port)" "$(printf '%s' "$leftover" | tr '\n' ' ')" >&2
+    printf 'It is not a wiki-manager runtime, so it was left running. Free the port, or set WIKI_MANAGER_RUNTIME_PORT to another one.\n' >&2
+    return 1
+  fi
   printf 'Refresh complete. Persistent workspace and agent data were preserved.\n'
 }
 
@@ -1074,6 +1157,7 @@ cacert_compose_args() {
 run_wiki() {
   local workspace="$1"
   shift
+  need_workspace_env "$workspace"
   local ws_path
   ws_path="$(normalize_path "$(workspace_value "$workspace" WIKI_WORKSPACE_PATH)")"
   ensure_workspace_dirs "$ws_path"