@dotdrelle/wiki-manager 0.14.9 → 0.14.10

package/.env.example

@@ -16,6 +16,18 @@ WORKSPACES_ROOT=/path/to/workspaces
 # Defaults to .agents-data/ next to wiki-workspace.
 # AGENTS_DATA_DIR=/path/to/.agents-data
 
+# ── VPN / outbound HTTP proxy (optional) ──────────────────────────────────────
+#
+# Node fetch does not use HTTP_PROXY / HTTPS_PROXY unless environment proxy
+# support is enabled. This matters for the manager runtime's own LLM calls
+# (including runtime.delegate objective resolution) behind a corporate VPN.
+# Keep these lines commented when no proxy is required.
+# NODE_USE_ENV_PROXY=1
+# HTTPS_PROXY=http://proxy.example:11011
+# HTTP_PROXY=http://proxy.example:11011
+# Always bypass the proxy for the local runtime, local MCPs, and Docker host.
+# NO_PROXY=localhost,127.0.0.1,host.docker.internal
+
 # ── Agent auth tokens ──────────────────────────────────────────────────────────
 #
 # Each agent has its own bearer token. Set the matching Authorization header

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.14.9",
+  "version": "0.14.10",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -11,7 +11,7 @@
   },
   "scripts": {
     "start": "bun ./bin/wiki-manager.js",
-    "test": "node --test src/agent/graph.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/buildInfo.test.js src/core/agentEvents.test.js src/core/runtimeLog.test.js src/activity/activityAggregator.test.js src/graph/runGraphProjector.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/toolLoop.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/orchestrator/agentRegistry.test.js src/orchestrator/capabilityRegistry.test.js src/orchestrator/capabilityResolver.test.js src/orchestrator/planValidator.test.js src/orchestrator/planIntegrator.test.js src/orchestrator/scheduler.test.js src/orchestrator/attemptManager.test.js src/orchestrator/resultAggregator.test.js src/orchestrator/approvalPolicy.test.js src/commands/slash.test.js src/shell/repl.test.js src/runtime/store.test.js src/runtime/controlMessages.test.js src/runtime/recoveryManager.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/runner.test.js src/runtime/runner.e2e.test.js src/runtime/donna-contract.test.js src/runtime/auth.test.js",
+    "test": "node --test src/agent/graph.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/buildInfo.test.js src/core/agentEvents.test.js src/core/runtimeLog.test.js src/activity/activityAggregator.test.js src/graph/runGraphProjector.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/toolLoop.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/cacert.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/orchestrator/agentRegistry.test.js src/orchestrator/capabilityRegistry.test.js src/orchestrator/capabilityResolver.test.js src/orchestrator/planValidator.test.js src/orchestrator/planIntegrator.test.js src/orchestrator/scheduler.test.js src/orchestrator/attemptManager.test.js src/orchestrator/resultAggregator.test.js src/orchestrator/approvalPolicy.test.js src/commands/slash.test.js src/shell/repl.test.js src/runtime/store.test.js src/runtime/controlMessages.test.js src/runtime/recoveryManager.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/runner.test.js src/runtime/runner.e2e.test.js src/runtime/donna-contract.test.js src/runtime/auth.test.js",
     "check-versions": "node scripts/check-versions.js",
     "prepack": "node scripts/check-versions.js",
     "prepublishOnly": "node scripts/check-versions.js",

package/src/cli/wiki-manager.js

@@ -31,6 +31,22 @@ function valueAfter(argv, flag) {
   return argv[index + 1];
 }
 
+function errorDiagnostic(err) {
+  const parts = [];
+  let current = err;
+  const seen = new Set();
+  while (current && !seen.has(current) && parts.length < 4) {
+    seen.add(current);
+    const name = current?.name && current.name !== 'Error' ? String(current.name) : '';
+    const code = current?.code ? String(current.code) : '';
+    const message = current instanceof Error ? current.message : String(current);
+    const detail = [name, code, message].filter(Boolean).join(' ');
+    if (detail && !parts.includes(detail)) parts.push(detail);
+    current = current?.cause;
+  }
+  return parts.join(' <- ') || 'unknown error';
+}
+
 function unavailableRuntime(err) {
   const reason = err instanceof Error ? err.message : String(err);
   return { url: null, error: reason };
@@ -787,27 +803,42 @@ async function runRuntime(argv, agent) {
     const { resolveObjective } = await import('../orchestrator/objectiveResolver.js');
     const { validateFragment } = await import('../orchestrator/planValidator.js');
     const session = context.session;
-    const selection = await resolveObjective(objective, session);
+    let selection;
+    try {
+      selection = await resolveObjective(objective, session);
+    } catch (err) {
+      throw new Error(`Delegation failed during objective_resolution: ${errorDiagnostic(err)}`, { cause: err });
+    }
     const provider = selection.provider;
-    const fragment = parseJsonText(formatMcpToolResult(await callMcpTool(
-      session.mcp,
-      provider.serverName,
-      'agent_plan',
-      {
-        capability: selection.capability,
-        operation: selection.operation,
-        objective,
-        workspace: { revision: String(Date.now()) },
-        constraints: {
-          maxConcurrency: resolveCapabilityConcurrency(
-            provider,
-            undefined,
-            process.env.WIKI_MANAGER_CAPABILITY_CONCURRENCY,
-          ),
-          requireApprovalForMutations: true,
+    let planResult;
+    try {
+      planResult = await callMcpTool(
+        session.mcp,
+        provider.serverName,
+        'agent_plan',
+        {
+          capability: selection.capability,
+          operation: selection.operation,
+          objective,
+          workspace: { revision: String(Date.now()) },
+          constraints: {
+            maxConcurrency: resolveCapabilityConcurrency(
+              provider,
+              undefined,
+              process.env.WIKI_MANAGER_CAPABILITY_CONCURRENCY,
+            ),
+            requireApprovalForMutations: true,
+          },
         },
-      },
-    )));
+      );
+    } catch (err) {
+      const endpoint = session.mcp?.[provider.serverName]?.url ?? 'unknown endpoint';
+      throw new Error(
+        `Delegation failed during agent_plan: provider=${provider.serverName} endpoint=${endpoint} ${errorDiagnostic(err)}`,
+        { cause: err },
+      );
+    }
+    const fragment = parseJsonText(formatMcpToolResult(planResult));
     if (!Array.isArray(fragment?.tasks) || fragment.tasks.length === 0) {
       throw new Error(fragment?.summary?.initialSynthesis?.[0] ?? `No task was planned for ${selection.capability}/${selection.operation}.`);
     }

package/src/commands/slash.js

@@ -627,7 +627,7 @@ ${helpPair('/mcp tools [mcp]', 'MCP tools', '/mcp call ...', 'Call MCP tool')}
 ${helpPair('/upload <path>', 'Upload document', '/uploads', 'Uploaded docs')}
 ${helpPair('/upload convert pending', 'Convert pending', '/uploads clean', 'Clean uploads')}
 ${helpPair('/wiki', 'Run wiki index', '/wiki run <args>', 'Raw wiki CLI')}
-${helpPair('/chat', 'Chat mode', '/agent', 'Agent mode')}
+${helpPair('/chat', 'Chat mode', '/agent [question]', 'Agent mode / one-shot')}
 ${helpPair('/openui', 'Open web UI in browser', '', '')}
 ${helpPair('/run status', 'Runtime status', '/run kill', 'Kill runtime run(s)')}
 ${helpPair('/run capability <id>', 'Deterministic capability run', '/approve', 'Grant pending approval')}
@@ -678,8 +678,31 @@ function rawCommandResult(command, output) {
   };
 }
 
-export function localizedOperationResult({ operation, target, status = 'succeeded' }) {
-  const facts = JSON.stringify({ operation, target, status });
+// Shared by every deterministic command that can trigger an on-demand
+// `docker pull` (agents up, service start): reports the images as they're
+// found missing and hands back the final list for localizedOperationResult.
+async function collectMissingImages(step, fn) {
+  let missingImages = [];
+  await fn({
+    onImagesMissing: (images) => {
+      missingImages = images;
+      step(`Donna: downloading and installing missing components: ${images.join(', ')}…`);
+    },
+  });
+  return missingImages;
+}
+
+function componentInstallAction(missingImages) {
+  return missingImages.length > 0 ? 'downloaded-and-installed-missing-components' : null;
+}
+
+export function localizedOperationResult({ operation, target, status = 'succeeded', componentAction = null, images = [] }) {
+  const facts = JSON.stringify({
+    operation,
+    target,
+    status,
+    ...(componentAction ? { componentAction, images } : {}),
+  });
   return {
     output: facts,
     rawOutput: true,
@@ -730,10 +753,12 @@ export async function handleSlashCommand(line, context) {
   const runAgentCommand = async (fn, verb) => {
     try {
       step(`Agents: ${verb}ing external agents…`);
-      await fn();
+      const missingImages = await collectMissingImages(step, fn);
       return localizedOperationResult({
         operation: verb,
         target: 'agents',
+        componentAction: componentInstallAction(missingImages),
+        images: missingImages,
       });
     } catch (err) {
       step(formatActivityError('agents', verb, err));
@@ -893,15 +918,17 @@ export async function handleSlashCommand(line, context) {
       // do not remap it to undefined, that bypasses any custom "all" target list and always
       // falls back to the hardcoded COMPOSE_SERVICES constant instead.
       const service = args[1];
-      if (service === 'agents') return runAgentCommand(startAgents, 'start');
+      if (service === 'agents' || service === 'agent') return runAgentCommand(startAgents, 'start');
       try {
         step(`Services: starting ${service ?? 'workspace services'}…`);
-        await startService(context.session, service);
+        const missingImages = await collectMissingImages(step, (opts) => startService(context.session, service, opts));
         step('Services: refreshing MCP runtime…');
         await refreshMcpRuntimeStatus(context.session);
         return localizedOperationResult({
           operation: 'start',
           target: service || 'workspace-services',
+          componentAction: componentInstallAction(missingImages),
+          images: missingImages,
         });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/src/commands/slash.test.js

@@ -15,6 +15,23 @@ test('deterministic operation results ask Donna to localize compact facts withou
   assert.doesNotMatch(result.agentTrigger, /\/start|Docker|compose/);
 });
 
+test('start result tells Donna when missing container components were installed', () => {
+  const result = localizedOperationResult({
+    operation: 'start',
+    target: 'all',
+    componentAction: 'downloaded-and-installed-missing-components',
+    images: ['dotdrelle/llm-wiki:latest'],
+  });
+  assert.deepEqual(JSON.parse(result.output), {
+    operation: 'start',
+    target: 'all',
+    status: 'succeeded',
+    componentAction: 'downloaded-and-installed-missing-components',
+    images: ['dotdrelle/llm-wiki:latest'],
+  });
+  assert.match(result.agentTrigger, /downloaded-and-installed-missing-components/);
+});
+
 test('/workspace delete removes files and clears current session context after confirmation', async () => {
   const root = await mkdtemp(join(tmpdir(), 'wiki-manager-delete-workspace-'));
   const registryRoot = join(root, 'registry');

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.14.9",
-  "commit": "768fb25"
+  "version": "0.14.10",
+  "commit": "79503aa"
 }

package/src/core/cacert.js

@@ -40,18 +40,15 @@ function composeOverrideContent(cacertPath, services) {
     services: serviceEntries,
   };
   return [
-    '# Generated by wiki-manager. Edit freely; delete to regenerate.',
+    '# Generated by wiki-manager. Changes are overwritten on the next compose command.',
     YAML.stringify(doc).trimEnd(),
     '',
   ].join('\n');
 }
 
-let _cacertOverrideCache;
-
 export function ensureCacertComposeOverride(composeFilePath, fileName = 'cacert.compose.yml') {
-  if (_cacertOverrideCache !== undefined) return _cacertOverrideCache;
   const cacertPath = activeCacertPath();
-  if (!cacertPath) return (_cacertOverrideCache = null);
+  if (!cacertPath) return null;
   if (!existsSync(cacertPath)) {
     throw new Error(`--cacert file not found: ${cacertPath}`);
   }
@@ -60,8 +57,14 @@ export function ensureCacertComposeOverride(composeFilePath, fileName = 'cacert.
   const runtimeDir = managerRuntimeDir();
   mkdirSync(runtimeDir, { recursive: true });
   const overridePath = join(runtimeDir, fileName);
-  if (!existsSync(overridePath)) {
-    writeFileSync(overridePath, composeOverrideContent(cacertPath, services), 'utf8');
+  const content = composeOverrideContent(cacertPath, services);
+  // The override is generated state, not user configuration. Always compare
+  // it with the active CLI value: keeping an existing file here left Docker
+  // mounting yesterday's CA after --cacert changed, despite all CA
+  // environment variables looking right.
+  const existing = existsSync(overridePath) ? readFileSync(overridePath, 'utf8') : null;
+  if (existing !== content) {
+    writeFileSync(overridePath, content, 'utf8');
   }
-  return (_cacertOverrideCache = overridePath);
+  return overridePath;
 }

package/src/core/cacert.test.js

@@ -0,0 +1,35 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { ensureCacertComposeOverride } from './cacert.js';
+
+test('cacert compose override follows the active certificate path', () => {
+  const root = mkdtempSync(join(tmpdir(), 'wiki-manager-cacert-'));
+  const compose = join(root, 'compose.yml');
+  const firstCa = join(root, 'first.pem');
+  const secondCa = join(root, 'second.pem');
+  writeFileSync(compose, 'services:\n  serve:\n    image: example\n', 'utf8');
+  writeFileSync(firstCa, 'first', 'utf8');
+  writeFileSync(secondCa, 'second', 'utf8');
+  const previousCa = process.env.WIKI_MANAGER_CACERT_PATH;
+  const previousEnvFile = process.env.WIKI_MANAGER_ENV_FILE;
+  process.env.WIKI_MANAGER_ENV_FILE = join(root, '.env');
+  try {
+    process.env.WIKI_MANAGER_CACERT_PATH = firstCa;
+    const override = ensureCacertComposeOverride(compose, 'test-cacert.compose.yml');
+    assert.match(readFileSync(override, 'utf8'), new RegExp(firstCa.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+
+    process.env.WIKI_MANAGER_CACERT_PATH = secondCa;
+    ensureCacertComposeOverride(compose, 'test-cacert.compose.yml');
+    const updated = readFileSync(override, 'utf8');
+    assert.match(updated, new RegExp(secondCa.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+    assert.doesNotMatch(updated, new RegExp(firstCa.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+  } finally {
+    if (previousCa === undefined) delete process.env.WIKI_MANAGER_CACERT_PATH;
+    else process.env.WIKI_MANAGER_CACERT_PATH = previousCa;
+    if (previousEnvFile === undefined) delete process.env.WIKI_MANAGER_ENV_FILE;
+    else process.env.WIKI_MANAGER_ENV_FILE = previousEnvFile;
+  }
+});

package/src/core/compose.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { promisify } from 'node:util';
 import YAML from 'yaml';
 import { cacertEnv, ensureCacertComposeOverride } from './cacert.js';
+import { checkMissingDockerImages } from './dockerImages.js';
 import { managerEnvFile, readEnvFile, resolveAgentsDataDir } from './env.js';
 import { managerRoot } from './workspaces.js';
 
@@ -281,11 +282,28 @@ export async function serviceStates(session) {
   return states;
 }
 
-export async function startService(session, service) {
+export async function missingServiceImages(service) {
   const aliases = serviceAliases();
   const targets = service ? (aliases[service] ?? [service]) : COMPOSE_SERVICES;
-  const output = await runCompose(session, ['up', '-d', ...targets], { timeout: 180_000 });
-  return [`Started: ${targets.join(', ')}`, output].filter(Boolean).join('\n');
+  const config = readComposeConfig();
+  const images = targets.map((target) => config.services?.[target]?.image).filter(Boolean);
+  return checkMissingDockerImages(images);
+}
+
+export async function startService(session, service, options = {}) {
+  const aliases = serviceAliases();
+  const targets = service ? (aliases[service] ?? [service]) : COMPOSE_SERVICES;
+  const absentImages = await missingServiceImages(service);
+  if (absentImages.length > 0) options.onImagesMissing?.(absentImages);
+  const output = await runCompose(session, ['up', '-d', ...targets], {
+    timeout: 180_000,
+    onOutput: options.onOutput,
+  });
+  return {
+    output: [`Started: ${targets.join(', ')}`, output].filter(Boolean).join('\n'),
+    targets,
+    missingImages: absentImages,
+  };
 }
 
 export async function stopService(session, service) {

package/src/core/dockerImages.js

@@ -0,0 +1,22 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export async function checkMissingDockerImages(images) {
+  const unique = [...new Set(images.filter(Boolean))];
+  const checks = await Promise.all(unique.map(async (image) => {
+    try {
+      await execFileAsync('docker', ['image', 'inspect', image], {
+        timeout: 30_000,
+        maxBuffer: 1024 * 1024,
+      });
+      return null;
+    } catch (err) {
+      const detail = [err?.stderr, err?.stdout, err?.message].filter(Boolean).join('\n');
+      if (/no such (?:image|object)/i.test(detail)) return image;
+      throw err;
+    }
+  }));
+  return checks.filter(Boolean);
+}

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.14.9';
+const WIKI_MANAGER_VERSION = '0.14.10';
 
 function envValue(key) {
   const filePath = managerEnvFile();

package/src/core/wikiSetup.js

@@ -1,13 +1,32 @@
 import { execFile } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
 import { readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
+import YAML from 'yaml';
+import { checkMissingDockerImages } from './dockerImages.js';
 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);
 
+async function missingAgentImages() {
+  const composeFiles = [
+    join(managerRoot(), 'agents.docker-compose.yml'),
+    join(dirname(managerEnvFile()), 'agents.docker-compose.override.yml'),
+  ].filter(existsSync);
+  const images = [...new Set(composeFiles.flatMap((filePath) => {
+    try {
+      const config = YAML.parse(readFileSync(filePath, 'utf8')) ?? {};
+      return Object.values(config.services ?? {}).map((service) => service?.image).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }))];
+  return checkMissingDockerImages(images);
+}
+
 function wrapDockerError(err) {
   if (err?.code === 'ENOENT') {
     return new Error('wiki-workspace script not found. Reinstall wiki-manager.');
@@ -35,6 +54,8 @@ function wrapDockerError(err) {
 
 export async function startAgents(options = {}) {
   try {
+    const absentImages = await missingAgentImages();
+    if (absentImages.length > 0) options.onImagesMissing?.(absentImages);
     const { stdout, stderr } = await execFileAsync(join(managerRoot(), 'wiki-workspace'), ['agents', 'up'], {
       cwd: managerRoot(),
       env: {
@@ -51,7 +72,10 @@ export async function startAgents(options = {}) {
       timeout: options.timeout ?? 180_000,
       maxBuffer: options.maxBuffer ?? 1024 * 1024 * 8,
     });
-    return [stdout, stderr].filter(Boolean).join('\n').trim();
+    return {
+      output: [stdout, stderr].filter(Boolean).join('\n').trim(),
+      missingImages: absentImages,
+    };
   } catch (err) {
     throw wrapDockerError(err);
   }

package/src/shell/LeftPane.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @opentui/solid */
 import { For, createEffect, createMemo, createSignal, onCleanup } from 'solid-js';
 import { colorForRenderedLine, helpCommandParts, keyValueParts, renderPlainMarkdown } from './renderer';
+import { httpLinkParts, wrapHttpLinks } from './externalLinks.js';
 
 const LEGACY_DONNA_ROLE = 'do' + 't';
 
@@ -47,7 +48,7 @@ function wrapLine(line: string, width: number) {
   return out;
 }
 
-type Segment = { text: string; color: string; width?: number; bg?: string };
+type Segment = { text: string; color: string; width?: number; bg?: string; url?: string };
 type RenderedLine = {
   segments: Segment[];
   status?: boolean;
@@ -300,6 +301,16 @@ function renderMarkdownLines(lines: Array<{ text: string; isCode: boolean }>, ro
     const rendered = renderPlainMarkdown(text);
     const isCmdDesc = splitCmdDesc(rendered) !== null;
     const fallback = isCmdDesc ? '#FFFFFF' : colorForRenderedLine(rendered, role);
+    if (httpLinkParts(rendered).some((part: { url?: string }) => part.url)) {
+      output.push(...wrapHttpLinks(rendered, columns).map((parts: Array<{ text: string; url?: string }>) => ({
+        segments: parts.map((part) => ({
+          text: part.text || ' ',
+          color: part.url ? '#5DADE2' : fallback,
+          url: part.url,
+        })),
+      })));
+      continue;
+    }
     output.push(...wrapLine(rendered, columns).map((piece, idx) => ({
       segments: idx === 0
         ? segmentsForLine(piece, role, columns)
@@ -489,7 +500,11 @@ export function ConversationView(props: {
           ) : (
             <box height={1} flexDirection="row" overflow="hidden">
               <For each={line.segments}>
-                {(seg: Segment) => <text width={seg.width} fg={seg.color} bg={seg.bg}>{seg.text}</text>}
+                {(seg: Segment) => (
+                  <text width={seg.width} fg={seg.color} bg={seg.bg}>
+                    {seg.url ? <a href={seg.url}>{seg.text}</a> : seg.text}
+                  </text>
+                )}
               </For>
             </box>
           )

package/src/shell/RightPane.tsx

@@ -20,6 +20,7 @@ type LogLineParts = { time: string | null; message: string };
 // wrapped status/error), so fewer, readable entries beat more, truncated ones.
 const ACTIVITY_SLOTS = Array.from({ length: 4 }, (_, index) => index);
 const LOG_SLOTS = Array.from({ length: 24 }, (_, index) => index);
+const PLAN_VIEWPORT_ROWS = 12;
 
 function wrapLine(value: string, width: number) {
   const max = Math.max(8, width);
@@ -131,29 +132,45 @@ function queueSummary(item: QueueItem) {
 }
 
 export function PlanPanel(props: { plan: PlanStep[]; width: number; jobName?: string }) {
-  const lineWidth = () => Math.max(8, props.width - 2);
+  // Keep one column for the native vertical scrollbar when the plan is long.
+  const lineWidth = () => Math.max(8, props.width - 3);
   const firstPending = () => props.plan.find((s) => s.status === 'pending')?.step ?? null;
   const icon = (status: string) =>
     status === 'done' ? '[✓]' : status === 'failed' ? '[✗]' : status === 'running' ? '[…]' : '[ ]';
-  const title = () => props.jobName ? `Plan : ${props.jobName}` : 'Plan';
+  const visualRows = createMemo(() => props.plan.reduce((total, step) =>
+    total + wrapLine(`${icon(step.status)} ${step.step}. ${step.description}`, lineWidth()).slice(0, 2).length, 0));
+  const title = () => {
+    const label = props.jobName ? `Plan : ${props.jobName}` : 'Plan';
+    return visualRows() > PLAN_VIEWPORT_ROWS ? `${label} (${props.plan.length}) · scroll` : label;
+  };
+  const viewportRows = () => Math.min(PLAN_VIEWPORT_ROWS, Math.max(1, visualRows()));
   return (
     <box flexShrink={0} flexDirection="column" padding={1}>
       <text width={lineWidth()} fg="#D6DEE8" content={fit(title(), lineWidth())} />
-      <Index each={props.plan}>
-        {(step) => {
-          // Wrap step descriptions over up to 2 lines instead of truncating —
-          // "Ingest des 39 documents raw/untrac…" hid the actual target.
-          const lines = () => wrapLine(`${icon(step().status)} ${step().step}. ${step().description}`, lineWidth()).slice(0, 2);
-          return (
-            <box flexDirection="column">
-              <text width={lineWidth()} fg={planStepColor(step(), firstPending())} content={lines()[0]} />
-              <Show when={lines()[1]}>
-                <text width={lineWidth()} fg={planStepColor(step(), firstPending())} content={`    ${fit(lines()[1], Math.max(8, lineWidth() - 4))}`} />
-              </Show>
-            </box>
-          );
-        }}
-      </Index>
+      <scrollbox
+        height={viewportRows()}
+        scrollY={true}
+        scrollX={false}
+        stickyStart="top"
+        viewportCulling={true}
+        verticalScrollbarOptions={{ visible: visualRows() > PLAN_VIEWPORT_ROWS }}
+      >
+        <Index each={props.plan}>
+          {(step) => {
+            // Wrap step descriptions over up to 2 lines instead of truncating —
+            // "Ingest des 39 documents raw/untrac…" hid the actual target.
+            const lines = () => wrapLine(`${icon(step().status)} ${step().step}. ${step().description}`, lineWidth()).slice(0, 2);
+            return (
+              <box flexShrink={0} flexDirection="column">
+                <text width={lineWidth()} fg={planStepColor(step(), firstPending())} content={lines()[0]} />
+                <Show when={lines()[1]}>
+                  <text width={lineWidth()} fg={planStepColor(step(), firstPending())} content={`    ${fit(lines()[1], Math.max(8, lineWidth() - 4))}`} />
+                </Show>
+              </box>
+            );
+          }}
+        </Index>
+      </scrollbox>
     </box>
   );
 }

package/src/shell/SetupWizard.tsx

@@ -23,7 +23,7 @@ type Step =
   | { kind: 'menu'; title: string; items: Array<{ label: string; value: string; muted?: boolean }> }
   | { kind: 'confirm'; title: string; message: string; yesLabel: string; noLabel: string }
   | { kind: 'select'; title: string; label: string; options: string[]; note?: string }
-  | { kind: 'text'; title: string; label: string; placeholder?: string; prefill?: string; secret?: boolean }
+  | { kind: 'text'; title: string; label: string; note?: string; placeholder?: string; prefill?: string; secret?: boolean }
   | { kind: 'done' };
 type LogEntry = { icon: string; label: string; detail?: string };
 
@@ -219,21 +219,32 @@ export function SetupWizard(props: {
       };
     }
     if (currentRoute === 'llm-baseurl') {
-      const baseUrl = llm().baseUrl || defaultBaseUrl(llm().provider);
-      return { kind: 'text', title: 'LLM configuration', label: 'Base URL', prefill: baseUrl, placeholder: baseUrl };
+      const example = defaultBaseUrl(llm().provider);
+      return {
+        kind: 'text',
+        title: 'LLM configuration',
+        label: `Base URL${example ? ` (example: ${example})` : ''}`,
+        prefill: llm().baseUrl || '',
+      };
     }
     if (currentRoute === 'llm-apikey') {
       return { kind: 'text', title: 'LLM configuration', label: 'API key (required)', secret: true };
     }
     if (currentRoute === 'llm-model') {
-      const defaultModel = llm().model || fallbackModels(llm().provider)[0] || '';
-      return { kind: 'text', title: 'LLM configuration', label: 'Model', prefill: defaultModel };
+      const example = fallbackModels(llm().provider)[0] || 'provider-agentic-model';
+      return {
+        kind: 'text',
+        title: 'LLM configuration',
+        label: `Model (example: ${example})`,
+        note: 'Required: an agentic model with tool/function calling support.',
+        prefill: llm().model || '',
+      };
     }
     if (currentRoute === 'vector-confirm') {
       return { kind: 'confirm', title: 'Vector search', message: 'Configure vector search?', yesLabel: 'Enable', noLabel: 'Skip' };
     }
     if (currentRoute === 'vector-baseurl') {
-      const baseUrl = vector().baseUrl || llm().baseUrl || defaultBaseUrl(llm().provider);
+      const baseUrl = vector().baseUrl || llm().baseUrl;
       return { kind: 'text', title: 'Vector search', label: 'Embeddings/rerank base URL', prefill: baseUrl, placeholder: baseUrl };
     }
     if (currentRoute === 'vector-apikey') {
@@ -462,7 +473,10 @@ export function SetupWizard(props: {
     if (currentRoute === 'llm-provider') {
       const provider = normalizeProvider(value);
       setLlm((old: any) => {
-        const baseUrl = (old.provider === provider && old.baseUrl) ? old.baseUrl : defaultBaseUrl(provider);
+        const asksForBaseUrl = provider === 'ollama' || provider === 'openai-compatible';
+        const baseUrl = (old.provider === provider && old.baseUrl)
+          ? old.baseUrl
+          : asksForBaseUrl ? '' : defaultBaseUrl(provider);
         return { ...old, provider, baseUrl, ...(provider === 'ollama' && !old.apiKey ? { apiKey: 'ollama' } : {}) };
       });
       if (provider === 'ollama' || provider === 'openai-compatible') return navigate('llm-baseurl');
@@ -560,7 +574,8 @@ export function SetupWizard(props: {
       return;
     }
     if (currentRoute === 'llm-baseurl') {
-      setLlm((old: any) => ({ ...old, baseUrl: value || old.baseUrl || defaultBaseUrl(old.provider) }));
+      if (!value) return setError('Base URL is required.');
+      setLlm((old: any) => ({ ...old, baseUrl: value }));
       if (llm().provider === 'ollama') return navigate('llm-model');
       return navigate('llm-apikey');
     }
@@ -570,7 +585,8 @@ export function SetupWizard(props: {
       return navigate('llm-model');
     }
     if (currentRoute === 'vector-baseurl') {
-      const baseUrl = value || vector().baseUrl || llm().baseUrl || defaultBaseUrl(llm().provider);
+      const baseUrl = value || vector().baseUrl || llm().baseUrl;
+      if (!baseUrl) return setError('Embeddings/rerank base URL is required.');
       setVector((old: any) => ({ ...old, provider: llm().provider, baseUrl }));
       return navigate('vector-apikey');
     }
@@ -750,6 +766,9 @@ export function SetupWizard(props: {
       <Show when={(step() as any).message || (step() as any).label}>
         <text height={1} fg="#D6DEE8">{(step() as any).message ?? (step() as any).label}</text>
       </Show>
+      <Show when={(step() as any).note}>
+        <text height={1} fg="#9CA3AF">{(step() as any).note}</text>
+      </Show>
       <Show when={step().kind === 'text'}>
         <box
           height={5}

package/src/shell/externalLinks.js

@@ -0,0 +1,67 @@
+const HTTP_URL = /https?:\/\/[^\s<>"'`]+/giu;
+const TRAILING_PUNCTUATION = /[.,;:!?]+$/u;
+
+function trimUrlEnd(value) {
+  let url = value.replace(TRAILING_PUNCTUATION, '');
+  while (url.endsWith(')') && (url.match(/\)/g)?.length ?? 0) > (url.match(/\(/g)?.length ?? 0)) {
+    url = url.slice(0, -1);
+  }
+  while (url.endsWith(']') && (url.match(/\]/g)?.length ?? 0) > (url.match(/\[/g)?.length ?? 0)) {
+    url = url.slice(0, -1);
+  }
+  return url;
+}
+
+export function httpLinkParts(value) {
+  const text = String(value ?? '');
+  const parts = [];
+  let cursor = 0;
+  for (const match of text.matchAll(HTTP_URL)) {
+    const start = match.index ?? 0;
+    const candidate = match[0];
+    const url = trimUrlEnd(candidate);
+    if (!url) continue;
+    try {
+      const parsed = new URL(url);
+      if (!parsed.hostname || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) continue;
+    } catch {
+      continue;
+    }
+    if (start > cursor) parts.push({ text: text.slice(cursor, start) });
+    parts.push({ text: url, url });
+    cursor = start + url.length;
+  }
+  if (cursor < text.length) parts.push({ text: text.slice(cursor) });
+  return parts.length > 0 ? parts : [{ text }];
+}
+
+export function wrapHttpLinks(value, width) {
+  const columns = Math.max(12, Number(width) || 12);
+  const rows = [[]];
+  let used = 0;
+  for (const part of httpLinkParts(value)) {
+    if (part.url) {
+      const parsed = new URL(part.url);
+      const label = `[link: ${parsed.hostname}]`;
+      if (used > 0 && used + label.length > columns) {
+        rows.push([]);
+        used = 0;
+      }
+      rows.at(-1).push({ text: label, url: part.url });
+      used += label.length;
+      continue;
+    }
+    let rest = part.text;
+    while (rest.length > 0) {
+      if (used === columns) {
+        rows.push([]);
+        used = 0;
+      }
+      const piece = rest.slice(0, columns - used);
+      rows.at(-1).push({ text: piece });
+      used += piece.length;
+      rest = rest.slice(piece.length);
+    }
+  }
+  return rows;
+}

package/src/shell/repl.js

@@ -82,7 +82,7 @@ const COMMAND_COMPLETION_DESCRIPTIONS = {
   '/uploads': 'List or clean uploaded documents.',
   '/clear': 'Clear the conversation screen.',
   '/chat': 'Switch free text to direct LLM chat without tools.',
-  '/agent': 'Switch free text to the LangGraph agent with tools.',
+  '/agent': 'Switch to agent mode, or run one agent request with /agent <question>.',
   '/openui': 'Open the workspace web UI in the browser.',
   '/run': 'Inspect, cancel, kill runtime runs, or start a capability run.',
   '/approve': 'Approve a pending runtime run or tool.',
@@ -797,8 +797,73 @@ function rememberProductionActivity(session, payload) {
   return true;
 }
 
+const TERMINAL_PLAN_STATUSES = new Set(['done', 'completed', 'succeeded', 'success', 'failed', 'error', 'cancelled', 'canceled']);
+
+function planTaskKey(task, index) {
+  return String(task?.id ?? task?.step ?? `task-${index + 1}`);
+}
+
+function errorDescription(value) {
+  if (!value) return null;
+  if (typeof value === 'string') return value.trim() || null;
+  if (value instanceof Error) return value.message;
+  if (typeof value === 'object') {
+    return errorDescription(value.message ?? value.reason ?? value.detail ?? value.description ?? value.error)
+      ?? (() => { try { return JSON.stringify(value); } catch { return String(value); } })();
+  }
+  return String(value);
+}
+
+function planTaskError(task, state) {
+  const activityKey = task?.activityKey ?? task?._activityKey ?? task?.ownerActivityKey;
+  const activity = (state?.activities ?? []).find((item) =>
+    (activityKey && String(item?.key) === String(activityKey))
+    || (task?.id != null && String(item?.taskId ?? '') === String(task.id)));
+  return errorDescription(
+    task?.error
+      ?? task?.result?.error
+      ?? task?.result?.reason
+      ?? activity?.error
+      ?? activity?.detail
+      ?? (['failed', 'error'].includes(String(state?.status ?? '').toLowerCase()) ? state?.evaluation?.reason : null),
+  );
+}
+
+export function appendRuntimePlanCompletionMessages(session, state) {
+  const plan = Array.isArray(state?.plan) ? state.plan : [];
+  const runId = String(state?.runId ?? 'runtime');
+  const current = new Map(plan.map((task, index) => [planTaskKey(task, index), String(task?.status ?? 'pending').toLowerCase()]));
+  if (session._runtimePlanRunId !== runId || !(session._runtimePlanStatuses instanceof Map)) {
+    session._runtimePlanRunId = runId;
+    session._runtimePlanStatuses = current;
+    return 0;
+  }
+
+  let appended = 0;
+  plan.forEach((task, index) => {
+    const key = planTaskKey(task, index);
+    const status = current.get(key);
+    const previous = session._runtimePlanStatuses.get(key);
+    if (!TERMINAL_PLAN_STATUSES.has(status) || TERMINAL_PLAN_STATUSES.has(previous)) return;
+    const label = String(task?.label ?? task?.description ?? task?.name ?? `Job ${key}`);
+    const failed = status === 'failed' || status === 'error';
+    const cancelled = status === 'cancelled' || status === 'canceled';
+    const error = failed ? planTaskError(task, state) : null;
+    const content = failed
+      ? `✗ Job terminé en erreur : ${label}\nStatus: ${status}${error ? `\nErreur: ${error}` : ''}`
+      : cancelled
+        ? `○ Job terminé : ${label}\nStatus: ${status}`
+        : `✓ Job terminé : ${label}\nStatus: ${status}`;
+    conversationMessages(session).push({ role: 'command', content });
+    appended += 1;
+  });
+  session._runtimePlanStatuses = current;
+  return appended;
+}
+
 export function applyRuntimeStateToShellSession(session, state) {
   if (!state || typeof state !== 'object') return false;
+  appendRuntimePlanCompletionMessages(session, state);
   const displayState = sanitizeRuntimeStateForDisplay(state);
   session.agentProjection = {
     conversation: Array.isArray(displayState.conversation) ? displayState.conversation.map((message) => ({ ...message })) : [],
@@ -872,6 +937,33 @@ export function shouldHandleFreeTextLocally(_line, session, { llmAvailable = Boo
   return { local: true, classification };
 }
 
+// Shared by both the one-shot `/agent <question>` path in runLine and the
+// interactive free-text-to-runtime path below: maps a submitRuntimeRun()
+// outcome to the conversation message(s) it produces and a short log line,
+// so the classification → message mapping isn't duplicated per call site.
+function applyRuntimeOutcome(session, outcome, onLog, {
+  ambiguousFallback = 'Runtime could not classify that message.',
+} = {}) {
+  if (outcome.kind === 'accepted') {
+    onLog('runtime: run accepted');
+  } else if (outcome.kind === 'queued') {
+    conversationMessages(session).push({ role: 'command', content: String(outcome.result?.explanation ?? 'Request added to the queue.') });
+    onLog('runtime: control queued');
+  } else if (outcome.kind === 'observe' || outcome.kind === 'converse' || outcome.kind === 'mutate') {
+    conversationMessages(session).push({ role: 'command', content: String(outcome.result?.explanation ?? 'Runtime control message accepted.') });
+    onLog(`runtime: ${outcome.kind}`);
+  } else if (outcome.kind === 'ambiguous') {
+    conversationMessages(session).push({ role: 'command', content: String(outcome.result?.explanation ?? ambiguousFallback) });
+    onLog('runtime: ambiguous control');
+  } else if (outcome.result?.explanation) {
+    conversationMessages(session).push({ role: 'command', content: String(outcome.result.explanation) });
+    onLog(`runtime: ${outcome.kind}`);
+  } else {
+    conversationMessages(session).push({ role: 'command', content: `Runtime error: ${outcome.message}` });
+    onLog(`runtime error: ${outcome.message}`);
+  }
+}
+
 export async function submitRuntimeRun(line, { runtime, session }) {
   const workspace = session.workspace ?? null;
   try {
@@ -1339,6 +1431,22 @@ export async function runLine(line, { agent, packageJson, session, onUpdate, onS
     return { exit: false };
   }
 
+  const oneShotAgentInput = /^\/agent\s+(.+)$/s.exec(trimmed)?.[1]?.trim();
+  if (oneShotAgentInput) {
+    if (!runtime?.url) {
+      const message = recordRuntimeUnavailableAgentInput(session, oneShotAgentInput, runtime);
+      onStep?.(message ?? 'runtime: disconnected');
+      onUpdate?.();
+      return { exit: false, oneShotAgent: true };
+    }
+    conversationMessages(session).push({ role: 'user', content: oneShotAgentInput });
+    onUpdate?.();
+    const outcome = await submitRuntimeRun(oneShotAgentInput, { runtime, session });
+    applyRuntimeOutcome(session, outcome, (msg) => onStep?.(msg));
+    onUpdate?.();
+    return { exit: false, oneShotAgent: true, runtimeOutcome: outcome };
+  }
+
   if (trimmed.startsWith('/')) {
     onStep?.(`Shell: ${trimmed}`);
     const result = await handleSlashCommand(trimmed, { packageJson, session, onStep, runtime });
@@ -1755,28 +1863,12 @@ async function runTuiShell({ agent, packageJson, session, runtime = null }) {
             }
             conversationMessages(session).push({ role: 'user', content: line });
             const outcome = await submitRuntimeRun(line, { runtime, session });
-            if (outcome.kind === 'accepted') {
-              activityLines = [...activityLines, 'runtime: run accepted'].slice(-LOWER_DETAIL_ROWS);
-            } else if (outcome.kind === 'queued') {
-              // Server-localized acknowledgement (src/runtime/controlMessages.js).
-              conversationMessages(session).push({ role: 'command', content: String(outcome.result?.explanation ?? 'Request added to the queue.') });
-              activityLines = [...activityLines, 'runtime: control queued'].slice(-LOWER_DETAIL_ROWS);
-            } else if (outcome.kind === 'observe' || outcome.kind === 'converse' || outcome.kind === 'mutate') {
-              const explanation = outcome.result?.explanation ?? 'Runtime control message accepted.';
-              conversationMessages(session).push({ role: 'command', content: explanation });
-              activityLines = [...activityLines, `runtime: ${outcome.kind}`].slice(-LOWER_DETAIL_ROWS);
-            } else if (outcome.kind === 'ambiguous') {
-              conversationMessages(session).push({ role: 'command', content: String(outcome.result?.explanation ?? 'Runtime could not classify that message. Use /queue for a future run, or ask/status more explicitly.') });
-              activityLines = [...activityLines, 'runtime: ambiguous control'].slice(-LOWER_DETAIL_ROWS);
-            } else if (outcome.result?.explanation) {
-              // cancel / approve / modify_run and any future control kinds:
-              // always surface the server's localized explanation.
-              conversationMessages(session).push({ role: 'command', content: String(outcome.result.explanation) });
-              activityLines = [...activityLines, `runtime: ${outcome.kind}`].slice(-LOWER_DETAIL_ROWS);
-            } else {
-              conversationMessages(session).push({ role: 'command', content: `Runtime error: ${outcome.message}` });
-              activityLines = [...activityLines, `runtime error: ${outcome.message}`].slice(-LOWER_DETAIL_ROWS);
-            }
+            applyRuntimeOutcome(
+              session,
+              outcome,
+              (msg) => { activityLines = [...activityLines, msg].slice(-LOWER_DETAIL_ROWS); },
+              { ambiguousFallback: 'Runtime could not classify that message. Use /queue for a future run, or ask/status more explicitly.' },
+            );
             syncRuntimeState();
           } else if (!session.chatMode && !line.trim().startsWith('/')) {
             const message = recordRuntimeUnavailableAgentInput(session, line, runtime);

package/src/shell/repl.test.js

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
   applyRuntimeStateToShellSession,
+  appendRuntimePlanCompletionMessages,
   chatReadTools,
   createSession,
   runHeadlessChatTurn,
@@ -17,6 +18,32 @@ import {
   shouldHandleFreeTextLocally,
   submitRuntimeRun,
 } from './repl.js';
+import { httpLinkParts, wrapHttpLinks } from './externalLinks.js';
+
+test('ShellUI turns HTTP URLs into valid links without trailing punctuation', () => {
+  assert.deepEqual(httpLinkParts('Voir https://example.test/docs?q=ok.'), [
+    { text: 'Voir ' },
+    { text: 'https://example.test/docs?q=ok', url: 'https://example.test/docs?q=ok' },
+    { text: '.' },
+  ]);
+});
+
+test('long ShellUI URLs use one short label with the complete link target', () => {
+  const url = 'https://example.test/a/very/long/document';
+  const links = wrapHttpLinks(url, 12).flat().filter((part) => part.url);
+  assert.deepEqual(links, [{ text: '[link: example.test]', url }]);
+});
+
+test('ShellUI never splits a link label at the end of a line', () => {
+  const url = 'https://example.test/a/very/long/document';
+  const rows = wrapHttpLinks(`Voir maintenant ${url}`, 20);
+  assert.equal(rows.length, 2);
+  assert.deepEqual(rows[1], [{ text: '[link: example.test]', url }]);
+});
+
+test('ShellUI leaves malformed URLs as plain text', () => {
+  assert.deepEqual(httpLinkParts('Erreur: https://'), [{ text: 'Erreur: https://' }]);
+});
 
 test('runtime display preserves a failed plan and its diagnostic evidence', () => {
   const state = {
@@ -131,6 +158,47 @@ test('applyRuntimeStateToShellSession clears terminal plan and activities when r
   assert.deepEqual(session.agentProjection.planPatches, []);
 });
 
+test('runtime plan completion is appended once to the ShellUI conversation', () => {
+  const session = createSession();
+  applyRuntimeStateToShellSession(session, {
+    runId: 'run-1',
+    status: 'running',
+    plan: [{ id: 'build', label: 'Build documentation', status: 'running' }],
+  });
+  applyRuntimeStateToShellSession(session, {
+    runId: 'run-1',
+    status: 'running',
+    plan: [{ id: 'build', label: 'Build documentation', status: 'done' }],
+  });
+  applyRuntimeStateToShellSession(session, {
+    runId: 'run-1',
+    status: 'done',
+    plan: [{ id: 'build', label: 'Build documentation', status: 'done' }],
+  });
+
+  assert.deepEqual(conversationMessages(session), [{
+    role: 'command',
+    content: '✓ Job terminé : Build documentation\nStatus: done',
+  }]);
+});
+
+test('runtime plan failure includes its available error description', () => {
+  const session = createSession();
+  appendRuntimePlanCompletionMessages(session, {
+    runId: 'run-2',
+    plan: [{ id: 'ingest', description: 'Ingest pages', status: 'running' }],
+  });
+  appendRuntimePlanCompletionMessages(session, {
+    runId: 'run-2',
+    plan: [{ id: 'ingest', description: 'Ingest pages', status: 'failed', result: { error: { message: 'Index unavailable' } } }],
+  });
+
+  assert.deepEqual(conversationMessages(session), [{
+    role: 'command',
+    content: '✗ Job terminé en erreur : Ingest pages\nStatus: failed\nErreur: Index unavailable',
+  }]);
+});
+
 test('direct chat system prompt forbids unsolicited next steps', async () => {
   const session = createSession();
   let systemPrompt = '';
@@ -223,6 +291,48 @@ test('submitRuntimeRun reports a non-409 error without throwing or calling /cont
   }
 });
 
+test('/agent <question> submits one runtime request and remains in chat mode', async () => {
+  const restore = stubFetch(async (url, init) => {
+    assert.equal(pathOf(url), '/run');
+    assert.equal(JSON.parse(String(init.body)).input, 'lance ingestion');
+    return jsonResponse(202, { accepted: true, runId: 'run-one-shot' });
+  });
+  try {
+    const session = createSession();
+    session.chatMode = true;
+    const result = await runLine('/agent lance ingestion', {
+      agent: null,
+      packageJson: { version: 'test' },
+      session,
+      runtime: { url: 'http://runtime.test' },
+    });
+
+    assert.equal(session.chatMode, true);
+    assert.equal(result.oneShotAgent, true);
+    assert.equal(result.runtimeOutcome.kind, 'accepted');
+    assert.deepEqual(conversationMessages(session), [{ role: 'user', content: 'lance ingestion' }]);
+  } finally {
+    restore();
+  }
+});
+
+test('/agent <question> reports an unavailable runtime without leaving chat mode', async () => {
+  const session = createSession();
+  session.chatMode = true;
+
+  const result = await runLine('/agent lance ingestion', {
+    agent: null,
+    packageJson: { version: 'test' },
+    session,
+    runtime: { error: 'runtime stopped' },
+  });
+
+  assert.equal(session.chatMode, true);
+  assert.equal(result.oneShotAgent, true);
+  assert.deepEqual(conversationMessages(session).map((message) => message.role), ['user', 'command']);
+  assert.match(conversationMessages(session).at(-1).content, /runtime stopped/);
+});
+
 test('runLine does not update workspace profile before Donna handles the request', async () => {
   const workspacePath = mkdtempSync(join(tmpdir(), 'donna-profile-shell-'));
   mkdirSync(join(workspacePath, '.wiki'), { recursive: true });