@dotdrelle/wiki-manager 0.15.28 → 0.15.32

package/src/core/startupCheck.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { promisify } from 'node:util';
 import { activeCacertPath, cacertEnv } from './cacert.js';
 import { COMPOSE_SERVICES, parseComposePsJson, serviceStates } from './compose.js';
+import { resolveAgentsComposeContext } from './agentsCompose.js';
 import { buildMcpStatus, discoverMcpTools } from './mcp.js';
 import { listWikircProfiles, loadWikircProfile, summarizeWikircConfig } from './wikirc.js';
 import { listWorkspaces, managerRoot, workspacesDir } from './workspaces.js';
@@ -79,22 +80,27 @@ export async function checkInternetConnectivity({
   }
 }
 
-async function checkAgents({ exec = execFileAsync } = {}) {
-  const composeFile = join(managerRoot(), 'agents.docker-compose.yml');
-  if (!existsSync(composeFile)) return null;
+export async function checkAgents({ exec = execFileAsync, context = resolveAgentsComposeContext() } = {}) {
+  if (!context.exists) return null;
   try {
-    const { stdout } = await exec('docker', [
-      'compose',
-      '--project-directory',
-      managerRoot(),
-      '-f',
-      composeFile,
-      '-p',
-      'wiki-agents',
-      'ps',
-      '--format',
-      'json',
-    ], {
+    // `config --services` is Compose's authoritative view after profiles,
+    // overrides and interpolation. Unlike `ps`, it also includes services that
+    // have never created a container, including ordinary (non-profiled)
+    // services and services contributed by the user override.
+    const { stdout: configuredStdout } = await exec(
+      'docker',
+      [...context.args, 'config', '--services'],
+      {
+        cwd: managerRoot(),
+        env: {
+          ...process.env,
+          WIKI_WORKSPACES_DIR: workspacesDir(),
+        },
+        timeout: 30_000,
+        maxBuffer: 1024 * 1024,
+      },
+    );
+    const { stdout } = await exec('docker', [...context.args, 'ps', '--all', '--format', 'json'], {
       cwd: managerRoot(),
       env: {
         ...process.env,
@@ -104,16 +110,38 @@ async function checkAgents({ exec = execFileAsync } = {}) {
       timeout: 5000,
       maxBuffer: 1024 * 1024,
     });
-    const entries = parseComposePsJson(stdout);
-    if (entries.length === 0) return null;
-    const downServices = entries
-      .filter((entry) => {
-        const state = String(entry.State ?? entry.state ?? entry.Status ?? entry.status ?? '').toLowerCase();
-        return !(state.includes('running') || state.includes('up'));
-      })
-      .map((entry) => entry.Service ?? entry.service ?? entry.Name ?? entry.name)
+    const expectedServices = String(configuredStdout ?? '')
+      .split(/\r?\n/)
+      .map((service) => service.trim())
       .filter(Boolean);
-    return downServices.length > 0 ? { kind: 'agents', context: { downServices } } : null;
+    const entries = parseComposePsJson(stdout);
+    const running = new Set();
+    const downServices = [];
+    for (const entry of entries) {
+      const name = entry.Service ?? entry.service ?? entry.Name ?? entry.name;
+      if (!name) continue;
+      const state = String(entry.State ?? entry.state ?? entry.Status ?? entry.status ?? '').toLowerCase();
+      if (state.includes('running') || state.includes('up')) running.add(name);
+      else downServices.push(name);
+    }
+    // A service whose profile the operator enabled but which `ps` does not list
+    // at all is missing, not opted out — reporting only the listed-but-stopped
+    // ones turned "connectors never started" into a silent success.
+    const missingServices = expectedServices.filter(
+      (service) => !running.has(service) && !downServices.includes(service),
+    );
+    if (entries.length === 0 && missingServices.length === 0) return null;
+    if (downServices.length === 0 && missingServices.length === 0) return null;
+    return {
+      kind: 'agents',
+      context: {
+        ...(downServices.length > 0 ? { downServices } : {}),
+        ...(missingServices.length > 0 ? { missingServices } : {}),
+        expectedServices,
+        requestedProfileServices: context.expectedProfileServices,
+        profiles: context.profiles,
+      },
+    };
   } catch (err) {
     if (err?.code === 'ENOENT') {
       return { kind: 'agents', context: { dockerMissing: true } };
@@ -349,16 +377,25 @@ export async function runChecks({
   if (!docker.ok) gaps.push({ kind: 'agents', context: docker.context ?? { dockerUnavailable: true } });
   if (!internet.ok) gaps.push({ kind: 'network', context: internet.context ?? {} });
   if (agents) gaps.push(agents);
+  const missingRequested = (agents?.context?.missingServices ?? []).filter(
+    (service) => (agents?.context?.requestedProfileServices ?? []).includes(service),
+  );
   onCheck({
     kind: 'agents',
     ok: docker.ok && !agents,
     skipped: !docker.ok,
     pending: !docker.ok || Boolean(agents),
+    // A service behind a profile the operator explicitly enabled is not merely
+    // "not started yet": they asked for it. Reporters use this to stay silent
+    // about ordinary boot latency while still surfacing this one.
+    requested: missingRequested.length > 0,
     detail: !docker.ok
       ? 'Waiting for Docker'
-      : agents?.context?.downServices?.length
-        ? `To start: ${agents.context.downServices.join(', ')}`
-        : 'Running',
+      : missingRequested.length > 0
+        ? `Enabled but not running: ${missingRequested.join(', ')}`
+        : agents?.context?.downServices?.length
+          ? `To start: ${agents.context.downServices.join(', ')}`
+          : 'Running',
     context: { ...(agents?.context ?? {}), command: 'wiki-workspace agents up' },
   });
   const workspaceGap = checkWorkspace(workspaces);

package/src/core/startupCheck.test.js

@@ -4,7 +4,7 @@ import { mkdtemp } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
-import { checkInternetConnectivity, checkMcpConnections, runChecks, runPreflightChecks, withRuntimePreflight } from './startupCheck.js';
+import { checkAgents, checkInternetConnectivity, checkMcpConnections, runChecks, runPreflightChecks, withRuntimePreflight } from './startupCheck.js';
 
 async function withWorkspace(wikircLines, fn) {
   const root = await mkdtemp(join(tmpdir(), 'wiki-manager-startup-check-'));
@@ -34,6 +34,54 @@ function hasGap(gaps, kind) {
   return gaps.some((gap) => gap.kind === kind);
 }
 
+test('checkAgents reports an enabled profile whose container never appeared', async () => {
+  // `docker compose ps` lists nothing for a service that was never created, so
+  // filtering only on "listed but stopped" reported success while connectors
+  // was absent. An enabled profile is a promise, not an opt-out.
+  const context = {
+    exists: true,
+    args: ['compose', '-p', 'wiki-agents', '--profile', 'connectors'],
+    profiles: ['connectors'],
+    expectedProfileServices: ['connectors'],
+  };
+  const running = JSON.stringify([{ Service: 'cme', State: 'running' }]);
+  const execWithPs = (ps) => async (_command, args) => ({
+    stdout: args.includes('config') ? 'cme\nconnectors\n' : ps,
+  });
+
+  const gap = await checkAgents({ context, exec: execWithPs(running) });
+  assert.equal(gap.kind, 'agents');
+  assert.deepEqual(gap.context.missingServices, ['connectors']);
+  assert.deepEqual(gap.context.profiles, ['connectors']);
+
+  const started = JSON.stringify([
+    { Service: 'cme', State: 'running' },
+    { Service: 'connectors', State: 'running' },
+  ]);
+  assert.equal(await checkAgents({ context, exec: execWithPs(started) }), null);
+});
+
+test('checkAgents ignores a profile the operator did not enable', async () => {
+  const context = { exists: true, args: [], profiles: [], expectedProfileServices: [] };
+  const stdout = JSON.stringify([{ Service: 'cme', State: 'running' }]);
+  const exec = async (_command, args) => ({
+    stdout: args.includes('config') ? 'cme\n' : stdout,
+  });
+  assert.equal(await checkAgents({ context, exec }), null);
+});
+
+test('checkAgents reports an ordinary agent that never created a container', async () => {
+  const context = { exists: true, args: [], profiles: [], expectedProfileServices: [] };
+  const exec = async (_command, args) => ({
+    stdout: args.includes('config')
+      ? 'cme\ndocuments\n'
+      : JSON.stringify([{ Service: 'cme', State: 'running' }]),
+  });
+  const gap = await checkAgents({ context, exec });
+  assert.deepEqual(gap.context.missingServices, ['documents']);
+  assert.deepEqual(gap.context.expectedServices, ['cme', 'documents']);
+});
+
 test('runChecks treats default LLM config without baseUrl as incomplete', async () => {
   await withWorkspace([
     'llm:',

package/src/core/wikiSetup.js

@@ -6,15 +6,12 @@ import { promisify } from 'node:util';
 import YAML from 'yaml';
 import { checkMissingDockerImages } from './dockerImages.js';
 import { patchWikircProfile } from './wikirc.js';
-import { managerEnvFile, managerMcpEndpointsFile, readEnvFile, resolveAgentsDataDir } from './env.js';
+import { resolveAgentsComposeContext } from './agentsCompose.js';
+import { managerEnvFile, managerMcpEndpointsFile, resolveAgentsDataDir } from './env.js';
 import { createWorkspace, findWorkspace, isValidWorkspaceName, listWorkspaces, managerRoot, workspacesDir } from './workspaces.js';
 
 const execFileAsync = promisify(execFile);
 
-function enabled(value) {
-  return /^(?:1|true|yes|on)$/i.test(String(value ?? '').trim());
-}
-
 export function configuredAgentImages(config, activeProfiles = new Set()) {
   return Object.values(config.services ?? {})
     .filter((service) => {
@@ -25,21 +22,12 @@ export function configuredAgentImages(config, activeProfiles = new Set()) {
     .filter(Boolean);
 }
 
-async function missingAgentImages() {
-  let managerEnv = {};
-  try {
-    managerEnv = readEnvFile(managerEnvFile());
-  } catch {
-    // A missing manager .env is valid during first-run setup.
-  }
-  const activeProfiles = new Set();
-  if (enabled(managerEnv.CONNECTORS_ENABLED ?? process.env.CONNECTORS_ENABLED)) {
-    activeProfiles.add('connectors');
-  }
-  const composeFiles = [
-    join(managerRoot(), 'agents.docker-compose.yml'),
-    join(dirname(managerEnvFile()), 'agents.docker-compose.override.yml'),
-  ].filter(existsSync);
+async function missingAgentImages(context = resolveAgentsComposeContext()) {
+  // Same resolution as the preflight and as `wiki-workspace agents up`: an
+  // image behind a profile the operator did not enable must not be reported
+  // missing, and one behind a profile they DID enable must be.
+  const activeProfiles = new Set(context.profiles);
+  const composeFiles = context.composeFiles.filter(existsSync);
   const images = [...new Set(composeFiles.flatMap((filePath) => {
     try {
       const config = YAML.parse(readFileSync(filePath, 'utf8')) ?? {};
@@ -77,13 +65,22 @@ function wrapDockerError(err) {
 }
 
 export async function startAgents(options = {}) {
+  const composeContext = options.composeContext ?? resolveAgentsComposeContext();
   try {
-    const absentImages = await missingAgentImages();
+    const absentImages = options.imagesCheck
+      ? await options.imagesCheck(composeContext)
+      : await missingAgentImages(composeContext);
     if (absentImages.length > 0) options.onImagesMissing?.(absentImages);
-    const { stdout, stderr } = await execFileAsync(join(managerRoot(), 'wiki-workspace'), ['agents', 'up'], {
+    const exec = options.exec ?? execFileAsync;
+    const { stdout, stderr } = await exec(join(managerRoot(), 'wiki-workspace'), ['agents', 'up'], {
       cwd: managerRoot(),
       env: {
         ...process.env,
+        // Compose gives variables already exported by its parent process
+        // precedence over --env-file, including an empty value loaded at boot.
+        // Re-apply the manager's resolved policy here so a token/secret written
+        // later to .env is not shadowed by stale process.env state.
+        ...composeContext.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
@@ -102,15 +99,53 @@ export async function startAgents(options = {}) {
       timeout: options.timeout ?? 180_000,
       maxBuffer: options.maxBuffer ?? 1024 * 1024 * 8,
     });
+    // `wiki-workspace agents up` also (re)writes mcp.endpoints.json, so the
+    // endpoints must be re-read here — the caller's in-memory session still
+    // holds the file as it was BEFORE the connectors entry was added, and the
+    // freshly started agent would stay unreachable until the next restart.
+    const verification = await verifyAgentsStarted({
+      context: composeContext,
+      agentsCheck: options.agentsCheck,
+    });
+    if (!verification.ok) throw agentsStartFailure(verification);
     return {
       output: [stdout, stderr].filter(Boolean).join('\n').trim(),
       missingImages: absentImages,
+      profiles: composeContext.profiles,
     };
   } catch (err) {
     throw wrapDockerError(err);
   }
 }
 
+// A start that leaves an enabled service down is a failure. Reporting success
+// and letting the operator discover it through a silent preflight line is what
+// made CONNECTORS_ENABLED=true look like it had been ignored.
+async function verifyAgentsStarted({ context, agentsCheck }) {
+  const check = agentsCheck ?? (await import('./startupCheck.js')).checkAgents;
+  const gap = await check({ context });
+  if (!gap) return { ok: true, profiles: context.profiles };
+  const down = gap.context?.downServices ?? [];
+  const missing = gap.context?.missingServices ?? [];
+  if (down.length === 0 && missing.length === 0) return { ok: true, profiles: context.profiles };
+  return { ok: false, downServices: down, missingServices: missing, profiles: context.profiles };
+}
+
+function agentsStartFailure({ downServices = [], missingServices = [], profiles = [] }) {
+  const parts = [
+    missingServices.length > 0 ? `never started: ${missingServices.join(', ')}` : '',
+    downServices.length > 0 ? `not running: ${downServices.join(', ')}` : '',
+  ].filter(Boolean);
+  const error = new Error(
+    `Agents started, but the expected services are not up (${parts.join('; ')}).`
+    + (profiles.length > 0 ? ` Active profiles: ${profiles.join(', ')}.` : ''),
+  );
+  error.name = 'AgentsNotRunningError';
+  error.downServices = downServices;
+  error.missingServices = missingServices;
+  return error;
+}
+
 export async function stopAgents(options = {}) {
   try {
     const { stdout, stderr } = await execFileAsync(join(managerRoot(), 'wiki-workspace'), ['agents', 'down'], {

package/src/core/wikiSetup.test.js

@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { startAgents } from './wikiSetup.js';
+
+const CONTEXT = {
+  exists: true,
+  args: [],
+  profiles: ['connectors'],
+  expectedProfileServices: ['connectors'],
+  composeFiles: [],
+};
+
+function startOptions(overrides = {}) {
+  return {
+    composeContext: CONTEXT,
+    imagesCheck: async () => [],
+    exec: async () => ({ stdout: 'started', stderr: '' }),
+    ...overrides,
+  };
+}
+
+test('starting the agents succeeds when every enabled service is running', async () => {
+  const result = await startAgents(startOptions({ agentsCheck: async () => null }));
+  assert.equal(result.output, 'started');
+  assert.deepEqual(result.profiles, ['connectors']);
+});
+
+test('an enabled connector that never started makes the start fail, not succeed', async () => {
+  // The script exits 0 whether or not the profiled container came up, so
+  // trusting its exit code alone reported success while connectors was absent
+  // — the operator only found out much later, through a silent preflight line.
+  await assert.rejects(
+    startAgents(startOptions({
+      agentsCheck: async () => ({ kind: 'agents', context: { missingServices: ['connectors'], profiles: ['connectors'] } }),
+    })),
+    (err) => {
+      assert.equal(err.name, 'AgentsNotRunningError');
+      assert.deepEqual(err.missingServices, ['connectors']);
+      assert.match(err.message, /never started: connectors/);
+      assert.match(err.message, /Active profiles: connectors\./);
+      return true;
+    },
+  );
+});
+
+test('a listed but stopped service also fails the start', async () => {
+  await assert.rejects(
+    startAgents(startOptions({
+      agentsCheck: async () => ({ kind: 'agents', context: { downServices: ['cme'] } }),
+    })),
+    (err) => {
+      assert.equal(err.name, 'AgentsNotRunningError');
+      assert.deepEqual(err.downServices, ['cme']);
+      assert.match(err.message, /not running: cme/);
+      return true;
+    },
+  );
+});
+
+test('the verification runs against the same compose context as the start', async () => {
+  let seen = null;
+  await startAgents(startOptions({
+    agentsCheck: async ({ context }) => { seen = context; return null; },
+  }));
+  assert.equal(seen, CONTEXT);
+});
+
+test('the manager .env values override stale blank process values for agents up', async () => {
+  let childEnv = null;
+  const context = {
+    ...CONTEXT,
+    env: {
+      ...process.env,
+      GOOGLE_OAUTH_CLIENT_SECRET: 'fresh-secret',
+    },
+  };
+  await startAgents(startOptions({
+    composeContext: context,
+    agentsCheck: async () => null,
+    exec: async (_file, _args, options) => {
+      childEnv = options.env;
+      return { stdout: 'started', stderr: '' };
+    },
+  }));
+  assert.equal(childEnv.GOOGLE_OAUTH_CLIENT_SECRET, 'fresh-secret');
+});

package/src/core/wikiWorkspace.test.js

@@ -28,6 +28,15 @@ test('wiki-workspace checks runtime pid command before killing', async () => {
   assert.match(script, /kill "\$\(cat "\$pid_file"\)"/);
 });
 
+test('project refresh shuts down runtime and removes only compose-owned images', async () => {
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+
+  assert.match(script, /if \[\[ \$# -eq 1 && "\$1" == "refresh" \]\]; then\n    refresh_project/);
+  assert.match(script, /compose_for_workspace "\$workspace" down --rmi all --remove-orphans/);
+  assert.match(script, /_agents_dc down --rmi all --remove-orphans/);
+  assert.doesNotMatch(script, /docker (?:image )?prune/);
+});
+
 test('wiki-workspace regenerates CA compose overrides instead of retaining removed services', async () => {
   const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
 
@@ -57,6 +66,13 @@ test('wiki-workspace provisions connector secrets and persistent state', async (
   assert.match(script, /delete config\.chatAccess\.servers\.connectors/);
 });
 
+test('local connector builds require both public Desktop OAuth values', async () => {
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+
+  assert.match(script, /for build_key in WIKILLM_GOOGLE_OAUTH_CLIENT_ID WIKILLM_GOOGLE_OAUTH_CLIENT_SECRET/);
+  assert.match(script, /require_connectors_build_credentials/);
+});
+
 test('workspace creation keeps mutable manager files outside the installed package', async () => {
   const source = await readFile(new URL('./workspaces.js', import.meta.url), 'utf8');
 

package/src/orchestrator/agentRegistry.js

@@ -41,13 +41,20 @@ async function discoverServerAgent(session, serverName, endpoint = {}, { callToo
     return legacyAgent(serverName, endpoint, { health: UNAVAILABLE, lastSeenAt });
   }
 
-  const toolName = findAgentDescribeTool(serverName, endpoint.tools ?? []);
-  if (!toolName) {
+  const tool = findAgentDescribeTool(serverName, endpoint.tools ?? []);
+  if (!tool) {
     return legacyAgent(serverName, endpoint, { health: AVAILABLE, lastSeenAt });
   }
+  const toolName = tool.name;
 
   try {
-    const result = await callTool(session.mcp, serverName, toolName, {}, signal);
+    const result = await callTool(
+      session.mcp,
+      serverName,
+      toolName,
+      describeArguments(tool, session?.workspace),
+      signal,
+    );
     const description = assertContract('agentDescription', parseToolJsonResult(result));
     return {
       serverName,
@@ -108,13 +115,34 @@ function dispatchRegistryEvent(session, type, payload) {
 }
 
 function findAgentDescribeTool(serverName, tools) {
-  const names = tools.map((tool) => String(tool.name ?? '')).filter(Boolean);
-  return names.find((name) => name === 'agent_describe')
-    ?? names.find((name) => name === `${serverName}__agent_describe`)
-    ?? names.find((name) => name.endsWith('__agent_describe'))
+  const named = tools.filter((tool) => String(tool?.name ?? ''));
+  const byName = (predicate) => named.find((tool) => predicate(String(tool.name)));
+  return byName((name) => name === 'agent_describe')
+    ?? byName((name) => name === `${serverName}__agent_describe`)
+    ?? byName((name) => name.endsWith('__agent_describe'))
     ?? null;
 }
 
+// Parts of a contract are workspace-scoped — typically the closed vocabulary of
+// an argument (the sources declared in THIS workspace). Published as a bare
+// string, such a field is unverifiable and a planner fills it with any noun
+// from the objective, so it is worth telling the agent which workspace we are
+// asking about.
+//
+// But the orchestrator must not assume an agent accepts an argument it never
+// declared: an agent whose agent_describe schema is `additionalProperties:
+// false` REJECTS the call, drops out of the registry, and its capabilities
+// silently vanish — the objective then resolves to whatever agent is left.
+// Send the workspace only to agents whose own schema says they can take it.
+function describeArguments(tool, workspace) {
+  if (!workspace) return {};
+  const schema = tool?.inputSchema;
+  if (!schema || typeof schema !== 'object') return {};
+  const declaresWorkspace = Object.hasOwn(schema.properties ?? {}, 'workspace');
+  const acceptsExtra = schema.additionalProperties !== false;
+  return declaresWorkspace || acceptsExtra ? { workspace: String(workspace) } : {};
+}
+
 function parseToolJsonResult(result) {
   if (result && typeof result === 'object' && !Array.isArray(result) && !Array.isArray(result.content)) {
     return result;

package/src/orchestrator/agentRegistry.test.js

@@ -112,3 +112,76 @@ test('agentRegistry marks unavailable boot agents and emits health changes on re
   assert.equal(events[1].payload.health, 'available');
   assert.equal(registry.snapshot()[0].health, 'available');
 });
+
+test('discovery sends the workspace only to agents whose schema declares it', async () => {
+  const seen = {};
+  const registry = createAgentRegistry({
+    callTool: async (_mcp, server, _tool, args) => {
+      seen[server] = args;
+      return { content: [{ type: 'text', text: JSON.stringify(description()) }] };
+    },
+  });
+
+  await registry.discover({
+    workspace: 'acpi',
+    mcp: {
+      // Declares workspace: gets it, and can scope its vocabulary.
+      cme: {
+        status: 'connected',
+        tools: [{
+          name: 'agent_describe',
+          inputSchema: { type: 'object', properties: { workspace: { type: 'string' } }, additionalProperties: false },
+        }],
+      },
+      // Strict schema without workspace: sending it would be REJECTED, the
+      // agent would drop out of the registry, and its capabilities would
+      // silently vanish from objective resolution.
+      production: {
+        status: 'connected',
+        tools: [{
+          name: 'agent_describe',
+          inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        }],
+      },
+      // Open schema: tolerant, so the workspace is worth sending.
+      connectors: {
+        status: 'connected',
+        tools: [{ name: 'agent_describe', inputSchema: { type: 'object', properties: {} } }],
+      },
+      // No schema published at all: assume nothing.
+      legacyish: {
+        status: 'connected',
+        tools: [{ name: 'agent_describe' }],
+      },
+    },
+  });
+
+  assert.deepEqual(seen.cme, { workspace: 'acpi' });
+  assert.deepEqual(seen.production, {});
+  assert.deepEqual(seen.connectors, { workspace: 'acpi' });
+  assert.deepEqual(seen.legacyish, {});
+});
+
+test('discovery sends no workspace argument when no workspace is active', async () => {
+  const seen = [];
+  const registry = createAgentRegistry({
+    callTool: async (_mcp, _server, _tool, args) => {
+      seen.push(args);
+      return { content: [{ type: 'text', text: JSON.stringify(description()) }] };
+    },
+  });
+
+  await registry.discover({
+    mcp: {
+      cme: {
+        status: 'connected',
+        tools: [{
+          name: 'agent_describe',
+          inputSchema: { type: 'object', properties: { workspace: { type: 'string' } } },
+        }],
+      },
+    },
+  });
+
+  assert.deepEqual(seen, [{}]);
+});

package/src/orchestrator/dispatcher.js

@@ -243,10 +243,15 @@ export function normalizeTaskError(rawError, { fallbackCode = null, fallbackMess
       retryable: transientError(fallbackCode),
     };
   }
+  // The agent gave a real reason. `fallbackMessage` describes only WHERE the
+  // failure was observed ("agent_execute rejected task"), so letting it win
+  // here replaced the one actionable sentence we have with a generic one —
+  // and Donna, left with nothing to explain, invented a cause. The fallback
+  // is a last resort, never an override.
   const code = String(rawError);
   return {
     code,
-    message: String(fallbackMessage ?? code),
+    message: code,
     retryable: transientError(code),
   };
 }

package/src/orchestrator/dispatcher.test.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { createDispatcher } from './dispatcher.js';
+import { createDispatcher, normalizeTaskError } from './dispatcher.js';
 
 test('dispatcher returns a retryable logical failure when agent_execute reports workspace_busy', async () => {
   const session = {
@@ -159,3 +159,26 @@ test('dispatcher keeps a null error when a terminal status reports none', async
   assert.equal(result.ok, true);
   assert.equal(result.error, null);
 });
+
+test('normalizeTaskError keeps the agent reason as the message, never the fallback', () => {
+  // Regression: the fallback describes only WHERE the failure was seen
+  // ("agent_execute rejected task"). Letting it win discarded the one
+  // actionable sentence — and left Donna to invent a cause.
+  const error = normalizeTaskError("Error: source 'acpi' not found", {
+    fallbackCode: 'execution_rejected',
+    fallbackMessage: 'agent_execute rejected task',
+  });
+
+  assert.equal(error.code, "Error: source 'acpi' not found");
+  assert.equal(error.message, "Error: source 'acpi' not found");
+});
+
+test('normalizeTaskError falls back only when the agent reports no reason at all', () => {
+  const error = normalizeTaskError('', {
+    fallbackCode: 'execution_rejected',
+    fallbackMessage: 'agent_execute rejected task',
+  });
+
+  assert.equal(error.code, 'execution_rejected');
+  assert.equal(error.message, 'agent_execute rejected task');
+});

package/src/orchestrator/objectiveResolver.js

@@ -1,3 +1,18 @@
+// Distinguishes "nothing here can do that" from a genuine resolution failure:
+// the first is a normal answer Donna gives the user, the second is a defect.
+export class ObjectiveNotOrchestrableError extends Error {
+  constructor(objective, candidates = [], reason = '') {
+    const available = candidates.map((item) => item.id).join(', ') || 'none';
+    super(
+      `No connected agent can do that.${reason ? ` ${String(reason).trim()}` : ''}`
+      + ` Available capabilities: ${available}.`,
+    );
+    this.name = 'ObjectiveNotOrchestrableError';
+    this.objective = String(objective ?? '');
+    this.candidates = candidates.map((item) => item.id);
+  }
+}
+
 export async function resolveObjective(objective, session) {
   const candidates = capabilityCandidates(session);
   if (candidates.length === 0) throw new Error('No orchestrable capability is currently available.');
@@ -10,6 +25,12 @@ export async function resolveObjective(objective, session) {
     system: [
       'You resolve one user objective against a closed capability registry.',
       'Select exactly one listed capability and one of its supported operations.',
+      // Without an explicit way out, the model has to pick SOMETHING: an
+      // objective no listed capability covers ("authorize Gmail") came back as
+      // workspace.diagnose/doctor and launched an unrelated job. Declining is
+      // a valid answer and the caller turns it into a plain reply.
+      'If no listed capability can achieve the objective, do not pick the closest one:',
+      'return {"capability":null,"reason":"<short reason>"}.',
       'Never invent identifiers. Return JSON only: {"capability":"...","operation":"..."}.',
     ].join('\n'),
     tools: [],
@@ -20,6 +41,9 @@ export async function resolveObjective(objective, session) {
     signal: session?._abortSignal,
   });
   const selection = parseJson(result?.content);
+  if (selection?.capability === null) {
+    throw new ObjectiveNotOrchestrableError(objective, candidates, selection?.reason);
+  }
   const capability = String(selection?.capability ?? '');
   const operation = String(selection?.operation ?? '');
   const candidate = candidates.find((item) => item.id === capability);