@dotdrelle/wiki-manager 0.15.85 → 0.15.91

package/src/orchestrator/dispatcher.js

@@ -2,12 +2,24 @@ import { normalizeActivity, parseJsonText } from '../core/activity.js';
 import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { callMcpTool, formatMcpToolResult } from '../core/mcp.js';
 import { loadWorkspaceProfile } from '../core/profile.js';
+import { containerReachableUrl } from '../core/wikiSetup.js';
 import { mapRuntimeEvent } from '../core/runtimeEventAdapter.js';
 import { emitRuntimeLog, pollActivitiesOnce } from '../runtime/supervisor.js';
 import { APPROVAL_DEFAULT_CLASS, approvalCovered } from './approvalPolicy.js';
 import { isSuccessful, isTerminal } from './taskStatuses.js';
 
 
+// Distinguishes "the manager process is shutting down" from a genuine task
+// cancellation (/run cancel, /stop, /control cancel) on the SAME shared
+// AbortController + signal (server.js's context.currentAbortController) —
+// the dispatcher otherwise cannot tell the two apart, and calling agent_cancel
+// on a shutdown-abort was cancelling a still-healthy job the very recovery
+// mechanism (recoveryManager.js's idempotency requeue) exists to reattach to
+// on the next boot. A shutdown must still abort the poll loop — the `finally`
+// block's lock release has to run before the process exits — it must just not
+// tell the agent to give up on real work.
+export const RUNTIME_SHUTDOWN_ABORT_REASON = 'runtime_shutdown';
+
 export function createDispatcher({
   session = null,
   callTool = callMcpTool,
@@ -66,7 +78,7 @@ export async function execute(task, assignment, {
       session.mcp,
       serverName,
       executeTool,
-      executeRequest(task, session, runId),
+      executeRequest(task, session, runId, assignment),
       signal,
     ));
     if (accepted?.accepted === false || accepted?.ok === false) {
@@ -155,7 +167,7 @@ export async function execute(task, assignment, {
       }
     }
   } catch (error) {
-    if (isAbortError(error) && jobId) {
+    if (isAbortError(error) && jobId && error.reason !== RUNTIME_SHUTDOWN_ABORT_REASON) {
       await callTool(session.mcp, serverName, cancelTool, { jobId }, null).catch(() => null);
     }
     throw error;
@@ -407,7 +419,20 @@ function dispatchExternalRuntimeActivity(session, task, assignment, runtimeRunId
   }));
 }
 
-function executeRequest(task, session, runId) {
+function executeRequest(task, session, runId, assignment) {
+  // The assignment's `capability` field is the capability ID (a string) for
+  // MCP agents; the OBJECT with the inputSchema lives on the registry agent's
+  // description. Resolve it properly — reading inputSchema off the string is
+  // what silently disabled the configPath injection below.
+  const capabilityId = task?.requiredCapability;
+  const capabilityObject = (assignment?.capability && typeof assignment.capability === 'object'
+    ? assignment.capability
+    : null)
+    ?? assignment?.agent?.description?.capabilities?.find(
+      (capability) => String(capability?.id ?? '') === String(capabilityId ?? ''),
+    )
+    ?? null;
+  const schemaProperties = capabilityObject?.inputSchema?.properties ?? {};
   return {
     taskId: String(task.id ?? task.step),
     ...(runId ? { runId: String(runId) } : {}),
@@ -428,6 +453,17 @@ function executeRequest(task, session, runId) {
       // first E2E ingest plan dispatched by the deep agent's
       // planExpansionRequest failed exactly that way, 19 tasks in one batch.
       ...(task.requiresApproval === true ? { confirm: true } : {}),
+      // The ACTIVE profile must reach the job: a task planned without an
+      // explicit configPath (the common case) otherwise runs on the workspace
+      // default .wikirc, so /config use <profile> changes the runtime's own
+      // LLM but silently not the production job's. The dispatcher is the one
+      // place every executor sees — inject the session's current profile when
+      // the capability declares the field and the task did not set one.
+      ...(task.arguments?.configPath === undefined
+        && 'configPath' in schemaProperties
+        && session?.wikirc?.fileName
+        ? { configPath: session.wikirc.fileName }
+        : {}),
     },
     constraints: {
       requireApprovalForMutations: task.requiresApproval === true,
@@ -448,7 +484,7 @@ function workspaceRequest(session) {
 function activeProfileModel(session) {
   const llm = session?.wikircConfig?.llm ?? {};
   const model = {
-    ...(llm.baseUrl ? { baseUrl: String(llm.baseUrl) } : {}),
+    ...(llm.baseUrl ? { baseUrl: containerReachableUrl(String(llm.baseUrl)).url } : {}),
     ...(llm.model ? { model: String(llm.model) } : {}),
     ...(llm.apiKey ? { apiKey: String(llm.apiKey) } : {}),
   };
@@ -521,7 +557,7 @@ export function activeProfileMcp(session) {
       };
       blocks.push({
         name: 'wiki',
-        url: String(wiki.url),
+        url: containerReachableUrl(String(wiki.url)).url,
         ...(Object.keys(headers).length > 0 ? { headers } : {}),
         tools,
       });
@@ -542,7 +578,7 @@ export function activeProfileMcp(session) {
     if (tools.length === 0) continue;
     blocks.push({
       name,
-      url: String(entry.url),
+      url: containerReachableUrl(String(entry.url)).url,
       ...(entry.headers && typeof entry.headers === 'object' ? { headers: entry.headers } : {}),
       tools,
     });
@@ -739,24 +775,25 @@ function taskLogPayload(event, task, assignment, {
 function delay(ms, signal) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
-      reject(abortError());
+      reject(abortError(signal));
       return;
     }
     const timer = setTimeout(resolve, Math.max(0, Number(ms) || 0));
     signal?.addEventListener('abort', () => {
       clearTimeout(timer);
-      reject(abortError());
+      reject(abortError(signal));
     }, { once: true });
   });
 }
 
 function throwIfAborted(signal) {
-  if (signal?.aborted) throw abortError();
+  if (signal?.aborted) throw abortError(signal);
 }
 
-function abortError() {
+function abortError(signal) {
   const error = new Error('Runtime run cancelled.');
   error.name = 'AbortError';
+  error.reason = signal?.reason;
   return error;
 }
 

package/src/orchestrator/dispatcher.test.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { activeProfileMcp, createDispatcher, normalizeTaskError } from './dispatcher.js';
+import { activeProfileMcp, createDispatcher, normalizeTaskError, RUNTIME_SHUTDOWN_ABORT_REASON } from './dispatcher.js';
 
 test('activeProfileMcp forwards only the read-only wiki tools to the external runtime', () => {
   const session = {
@@ -91,6 +91,29 @@ test('activeProfileMcp tolerates namespaced tool names', () => {
   assert.deepEqual(activeProfileMcp(session)[0].tools, ['wiki__wiki_read_page']);
 });
 
+test('activeProfileMcp rewrites loopback URLs for the container the runtime runs in', () => {
+  const session = {
+    mcp: {
+      wiki: {
+        url: 'http://127.0.0.1:3201/mcp', status: 'connected',
+        tools: [{ name: 'wiki_read_page' }],
+      },
+      exa: {
+        url: 'http://localhost:9999/mcp/', status: 'connected', external: true,
+        tools: [{ name: 'web_search_exa' }],
+      },
+      hosted: {
+        url: 'https://mcp.exa.ai/mcp', status: 'connected', external: true,
+        tools: [{ name: 'web_search_exa' }],
+      },
+    },
+  };
+  const pool = activeProfileMcp(session);
+  assert.equal(pool.find((block) => block.name === 'wiki').url, 'http://host.docker.internal:3201/mcp');
+  assert.equal(pool.find((block) => block.name === 'exa').url, 'http://host.docker.internal:9999/mcp');
+  assert.equal(pool.find((block) => block.name === 'hosted').url, 'https://mcp.exa.ai/mcp');
+});
+
 test('dispatcher returns a retryable logical failure when agent_execute reports workspace_busy', async () => {
   const session = {
     workspace: 'test',
@@ -203,6 +226,72 @@ test('dispatcher completes when an executor-only agent reports succeeded', async
   assert.equal(result.jobId, 'job-connectors');
 });
 
+test('dispatcher cancels the agent job when genuinely aborted mid-poll', async () => {
+  const session = {
+    workspace: 'test',
+    mcp: { production: { status: 'connected', tools: [{ name: 'agent_execute' }, { name: 'agent_status' }, { name: 'agent_cancel' }] } },
+    activities: {},
+  };
+  const calledTools = [];
+  const dispatcher = createDispatcher({
+    session,
+    pollIntervalMs: 5,
+    callTool: async (_mcp, _server, tool) => {
+      calledTools.push(tool);
+      if (tool === 'agent_execute') return { accepted: true, jobId: 'job-1', status: 'queued' };
+      if (tool === 'agent_cancel') return { ok: true };
+      // agent_status: never terminal, forces the poll loop to keep waiting
+      // until the abort fires.
+      return { jobId: 'job-1', status: 'running' };
+    },
+  });
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), 10);
+
+  await assert.rejects(
+    dispatcher.execute(
+      { id: 'analyze-doc', label: 'Analyze doc', requiredCapability: 'knowledge.update', operation: 'ingest_plan', arguments: {} },
+      { serverName: 'production', agentInstanceId: 'production-main' },
+      { attempt: { attemptId: 'analyze-doc:attempt-1', locks: [], release() {} }, signal: controller.signal },
+    ),
+  );
+  assert.ok(calledTools.includes('agent_cancel'), 'a genuine cancel/abort must still cancel the agent job');
+});
+
+test('dispatcher does NOT cancel the agent job when the manager is only shutting down', async () => {
+  // The exact scenario that caused a real incident: restarting the runtime
+  // mid-ingest orphaned in-flight sources because this path cancelled their
+  // still-healthy jobs instead of leaving them for recoveryManager.js's
+  // idempotency requeue to reattach to on the next boot.
+  const session = {
+    workspace: 'test',
+    mcp: { production: { status: 'connected', tools: [{ name: 'agent_execute' }, { name: 'agent_status' }, { name: 'agent_cancel' }] } },
+    activities: {},
+  };
+  const calledTools = [];
+  const dispatcher = createDispatcher({
+    session,
+    pollIntervalMs: 5,
+    callTool: async (_mcp, _server, tool) => {
+      calledTools.push(tool);
+      if (tool === 'agent_execute') return { accepted: true, jobId: 'job-2', status: 'queued' };
+      if (tool === 'agent_cancel') return { ok: true };
+      return { jobId: 'job-2', status: 'running' };
+    },
+  });
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(RUNTIME_SHUTDOWN_ABORT_REASON), 10);
+
+  await assert.rejects(
+    dispatcher.execute(
+      { id: 'analyze-doc', label: 'Analyze doc', requiredCapability: 'knowledge.update', operation: 'ingest_plan', arguments: {} },
+      { serverName: 'production', agentInstanceId: 'production-main' },
+      { attempt: { attemptId: 'analyze-doc:attempt-1', locks: [], release() {} }, signal: controller.signal },
+    ),
+  );
+  assert.ok(!calledTools.includes('agent_cancel'), 'a shutdown-reason abort must leave the still-healthy agent job running');
+});
+
 test('dispatcher normalizes a bare string error reported on a terminal agent_status', async () => {
   const session = {
     workspace: 'test',

package/src/orchestrator/providers/dispatcherExternalRuntime.test.js

@@ -298,7 +298,7 @@ test('dispatcher sends the active profile model with the run', async () => {
   assert.equal(requests[0].language, 'fr', 'the workspace language travels with the run');
   assert.deepEqual(requests[0].mcp, [{
     name: 'wiki',
-    url: 'http://localhost:3335/mcp/',
+    url: 'http://host.docker.internal:3335/mcp',
     headers: { Authorization: 'Bearer wiki-token' },
     tools: ['wiki_search_context', 'wiki_read_page'],
   }], 'the wiki MCP travels per run, read tools only — write tools never leave');
@@ -378,7 +378,7 @@ test('dispatcher sends the active profile model with the run', async () => {
   );
 
   assert.equal(received[0].model.model, 'openai/gpt-test');
-  assert.equal(received[0].model.baseUrl, 'http://127.0.0.1:9/v1');
+  assert.equal(received[0].model.baseUrl, 'http://host.docker.internal:9/v1');
   assert.equal(received[0].model.apiKey, 'k');
   assert.equal(received[0].model.temperature, 0.2);
 });

package/src/orchestrator/providers/runtimeProviders.test.js

@@ -157,8 +157,10 @@ test('resolveRuntimeProviders maps enabled entries and skips unknown types', ()
 test('loadAgentRuntimesConfig reads both array and object forms', () => {
   const dir = mkdtempSync(join(tmpdir(), 'agent-runtimes-'));
   try {
+    // env: {} — the machine's manager .env (GATEWAY_ENABLED) must not leak
+    // into this parse-shape test through the implied-gateway path.
     writeFileSync(join(dir, 'agent-runtimes.json'), JSON.stringify({ runtimes: [{ id: 'a', type: 'fake' }] }));
-    assert.deepEqual(loadAgentRuntimesConfig({ stateDir: dir }), [{ id: 'a', type: 'fake' }]);
+    assert.deepEqual(loadAgentRuntimesConfig({ stateDir: dir, env: {} }), [{ id: 'a', type: 'fake' }]);
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }

package/src/orchestrator/resultAggregator.js

@@ -1,3 +1,5 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { validateContract } from '../contracts/schemas.js';
 import { parseJsonText } from '../core/activity.js';
 import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
@@ -63,6 +65,26 @@ export async function accept(result, {
     taskId,
     payload,
   })));
+  // A worktree proposal is a review item, not a log line: persist it into the
+  // workspace review queue (.wiki/agent-proposals/) where the served review
+  // surface reads it, and announce it — a proposal nobody is told about is a
+  // proposal nobody merges, and a merge is the approval.
+  const worktreePersisted = persistWorktreeProposal(session, result, { runId, taskId, ok, status });
+  if (worktreePersisted.error) {
+    persistDispatch(store, dispatchAgentEvent(session, createAgentEvent('runtime_log', {
+      origin: 'result_aggregator',
+      runId,
+      taskId,
+      payload: { message: `agent-proposal: could not persist the worktree proposal for ${taskId}: ${worktreePersisted.error}` },
+    })));
+  } else if (worktreePersisted.path) {
+    persistDispatch(store, dispatchAgentEvent(session, createAgentEvent('runtime_log', {
+      origin: 'result_aggregator',
+      runId,
+      taskId,
+      payload: { message: `agent-proposal: ${taskId} is waiting for review — ${worktreePersisted.path}` },
+    })));
+  }
   persistDispatch(store, dispatchAgentEvent(session, createAgentEvent('plan_step_updated', {
     origin: 'result_aggregator',
     runId,
@@ -227,6 +249,51 @@ function persistDispatch(store, event) {
   store?.persistEvent?.(event);
 }
 
+/**
+ * Worktree proposals (agent.curate): the external runtime's run result carries
+ * `worktreeProposal` — the confined branch's changed files, their new content
+ * and the unified diff. The manager writes it into the workspace review queue
+ * (`.wiki/agent-proposals/<id>.json`, gitignored state) where the served
+ * review surface reads it; the MERGE happens there, through the engine's own
+ * write machinery — this function only records, it never touches wiki content.
+ */
+function persistWorktreeProposal(session, result, { runId, taskId }) {
+  const proposal = result?.result?.worktreeProposal ?? result?.worktreeProposal;
+  if (!proposal || typeof proposal !== 'object') return { path: null };
+  const changes = Array.isArray(proposal.changes) ? proposal.changes : [];
+  if (changes.length === 0) return { path: null };
+  const workspacePath = session?.workspacePath;
+  if (!workspacePath || typeof workspacePath !== 'string') {
+    return { error: 'no workspace path on the session — the proposal stays in the run result only' };
+  }
+  const record = {
+    id: String(taskId),
+    runId: String(runId ?? ''),
+    workspace: String(proposal.workspace ?? session.workspace ?? ''),
+    branch: String(proposal.branch ?? ''),
+    worktreePath: String(proposal.worktreePath ?? ''),
+    worktreeRelativePath: String(proposal.worktreeRelativePath ?? ''),
+    createdAt: new Date().toISOString(),
+    justification: String(proposal.justification ?? ''),
+    ...(Array.isArray(proposal.objections) && proposal.objections.length > 0
+      ? { objections: proposal.objections }
+      : {}),
+    changedFiles: Array.isArray(proposal.changedFiles) ? proposal.changedFiles : [],
+    changes,
+    diff: String(proposal.diff ?? ''),
+  };
+  try {
+    const safeId = String(taskId).replace(/[^a-zA-Z0-9._-]/g, '_');
+    const dir = join(workspacePath, '.wiki', 'agent-proposals');
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${safeId}.json`);
+    writeFileSync(path, JSON.stringify(record, null, 2));
+    return { path };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 function agentPlanRequest(request, session) {
   return {
     capability: request.capability,

package/src/runtime/server.js

@@ -8,6 +8,7 @@ import { runtimeTokenFromEnv } from './auth.js';
 import { controlMessage } from './controlMessages.js';
 import { tasksAwaitingApproval } from '../orchestrator/dependencyResolver.js';
 import { approvalClassForTask } from '../orchestrator/approvalPolicy.js';
+import { RUNTIME_SHUTDOWN_ABORT_REASON } from '../orchestrator/dispatcher.js';
 import { matchSkillInvocation } from '../core/skillInvocation.js';
 import { reconcileControlQueue } from './controlDrain.js';
 import { cancelControlChain, cancelQueuedControlItem } from './controlCancellation.js';
@@ -413,7 +414,7 @@ export function startRuntimeServer({
         // Read-only chat turns intentionally remain available while an agent
         // run is active. Other interactive turns still become control
         // messages so they cannot start a competing agent decision.
-        const readOnlyChat = String(body.mode ?? '').toLowerCase() === 'chat';
+        let readOnlyChat = String(body.mode ?? '').toLowerCase() === 'chat';
         // An explicit /skill invocation has deterministic meaning. Keep the
         // conversational /turn boundary, but do not ask the LLM to rediscover
         // the skill from prose: it could choose a direct mutation instead and
@@ -433,14 +434,25 @@ export function startRuntimeServer({
           return;
         }
         if (context.running && !readOnlyChat) {
-          const result = await handleControlMessage(context, store, input, {
-            intent: body.intent,
-            startNextControlRequest,
-            cancel,
-            approve,
+          // Agent-mode message while a run is active. Classify once: control
+          // verbs and new tasks go to the control lane, plain conversation is
+          // ANSWERED read-only (like a chat turn) instead of parking the
+          // reader in a choice menu — the chat must stay usable during runs.
+          const classification = await classifyControlMessage(input, controlStatus(context, store), {
+            llm: context?.session?.llm,
+            session: context?.session,
           });
-          sendJson(response, result.statusCode, result.body);
-          return;
+          if (classification.kind !== 'converse') {
+            const result = await handleControlMessage(context, store, input, {
+              intent: body.intent,
+              startNextControlRequest,
+              cancel,
+              approve,
+            });
+            sendJson(response, result.statusCode, result.body);
+            return;
+          }
+          readOnlyChat = true;
         }
         if (typeof turn !== 'function') {
           sendJson(response, 501, { error: 'Runtime interactive turns are unavailable.' });
@@ -454,21 +466,27 @@ export function startRuntimeServer({
           // after this request was accepted. Reclassify against the fresh
           // state instead of starting another interactive decision in parallel.
           if (context.running && !readOnlyChat) {
-            const result = await handleControlMessage(context, store, input, {
-              intent: body.intent,
-              startNextControlRequest,
-              cancel,
-              approve,
+            const classification = await classifyControlMessage(input, controlStatus(context, store), {
+              llm: context?.session?.llm,
+              session: context?.session,
             });
-            publish(createAgentEvent('assistant_message', {
-              origin: 'runtime_turn',
-              turnId,
-              workspace: context.workspace ?? null,
-              payload: { content: result.body?.explanation ?? 'Runtime control request processed.' },
-            }));
-            return result.body;
+            if (classification.kind !== 'converse') {
+              const result = await handleControlMessage(context, store, input, {
+                intent: body.intent,
+                startNextControlRequest,
+                cancel,
+                approve,
+              });
+              publish(createAgentEvent('assistant_message', {
+                origin: 'runtime_turn',
+                turnId,
+                workspace: context.workspace ?? null,
+                payload: { content: result.body?.explanation ?? 'Runtime control request processed.' },
+              }));
+              return result.body;
+            }
           }
-          return turn(context, { ...body, input }, {
+          return turn(context, { ...body, input, mode: readOnlyChat ? 'chat' : body.mode }, {
             signal: controller.signal,
             turnId,
           });
@@ -560,7 +578,13 @@ export function startRuntimeServer({
         const workspace = workspaceFromUrl(url);
         const context = await resolveContext({ workspace });
         if (context?.running && context.currentAbortController) {
-          context.currentAbortController.abort();
+          // Reason-tagged: the poll loop still has to unwind so its `finally`
+          // releases locks before the process exits, but this is the manager
+          // going away, not a user cancellation — the dispatcher must not
+          // read it as "give up on the agent job too". recoveryManager.js's
+          // idempotency requeue exists precisely to reattach to that job on
+          // the next boot; cancelling it here defeats that on every restart.
+          context.currentAbortController.abort(RUNTIME_SHUTDOWN_ABORT_REASON);
           await cancel?.(context);
         }
         sendJson(response, 202, { shutdown: true });
@@ -1484,16 +1508,20 @@ async function classifyControlMessage(input, status, { forcedIntent = null, llm
       const kind = String(reply ?? '').trim().toLowerCase();
       if (kind.startsWith('action')) return { kind: 'enqueue_run', confidence: 0.85, reason: 'llm_classified_action' };
       if (kind.startsWith('conversation')) return { kind: 'converse', confidence: 0.85, reason: 'llm_classified_conversation' };
-      emitRuntimeLog(session, `control-classify: LLM returned an unrecognized reply, falling back to the choice menu — ${JSON.stringify(kind).slice(0, 200)}`);
+      emitRuntimeLog(session, `control-classify: LLM returned an unrecognized reply, answering as read-only conversation — ${JSON.stringify(kind).slice(0, 200)}`);
     } catch (err) {
       // A degradation must announce itself: silently falling through here
       // hides the difference between "no LLM configured" (expected) and "the
       // configured LLM is failing every call" (a real problem) — both would
       // otherwise look identical from the Shell or serve UI.
-      emitRuntimeLog(session, `control-classify: LLM call failed, falling back to the choice menu — ${err instanceof Error ? err.message : String(err)}`);
+      emitRuntimeLog(session, `control-classify: LLM call failed, answering as read-only conversation — ${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  return { kind: 'ambiguous', confidence: 0.45, reason: 'action_vs_conversation_unclear' };
+  // A choice menu IS the block the reader complains about: while a run is
+  // active, every unanswered message turned into a menu. Falling back to
+  // read-only conversation keeps the chat usable — a wrong converse only
+  // answers as chat, it can never mutate or queue anything.
+  return { kind: 'converse', confidence: 0.3, reason: 'fallback_to_readonly_conversation' };
 }
 
 function isAuthorized(request, token) {

package/src/shell/repl.js

@@ -437,31 +437,71 @@ export function sanitizeOpenWikiPages(values) {
 }
 
 
+// Tolerant [src: path] matcher, mirroring llm-wiki's own
+// src/utils/markdown.ts#extractSourceCitations (chained "[src: a.md ; src:
+// b.md]" included) without importing across the repo boundary for one regex.
+const SOURCE_CITATION_PATTERN = /\[\s*src\s*:\s*([^\]]+?)\s*\]/gi;
+
+function extractSourceCitationPaths(content) {
+  return [...content.matchAll(SOURCE_CITATION_PATTERN)].flatMap((match) =>
+    (match[1] ?? '')
+      .split(';')
+      .map((part) => part.trim().replace(/^src\s*:\s*/i, ''))
+      .filter(Boolean),
+  );
+}
+
+async function readWorkspaceFile(session, relPath, maxCharsPerDoc) {
+  try {
+    const absPath = path.resolve(session.workspacePath, relPath);
+    const rel = path.relative(session.workspacePath, absPath);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) return { path: relPath, content: null };
+    const raw = await readFile(absPath, 'utf8');
+    const content = raw.length > maxCharsPerDoc
+      ? `${raw.slice(0, maxCharsPerDoc).trimEnd()}\n[truncated]`
+      : raw;
+    return { path: relPath, content };
+  } catch {
+    return { path: relPath, content: null };
+  }
+}
+
 // Read the selected documents' content so chat can summarize them directly,
 // without depending on the model choosing to call a read tool (and without the
 // tool being offered at all). Paths are already sanitized to wiki/ or
 // raw/untracked/ .md files; the path.relative check is defence in depth. A doc
 // that cannot be read yields { content: null } so the caller can note it.
-export async function readSelectedPageDocuments(session, pages, { maxCharsPerDoc = 16000 } = {}) {
+//
+// A wiki page is a digest, not the evidence: it names its real sources inline
+// as [src: ...] citations. Reading only the digest is exactly the shortcut
+// that produced an answer covering one facet of a source ingest had split
+// into several concept leaves — the model reused the one digest already in
+// hand instead of going back to the source, even though it was told to.
+// Rather than hope a differently-prompted model chooses to call a read tool
+// for that source, follow each selected page's own citations one level deep
+// and attach them the same deterministic way, up to maxCitedDocs.
+export async function readSelectedPageDocuments(session, pages, { maxCharsPerDoc = 16000, maxCitedDocs = 5 } = {}) {
   if (!Array.isArray(pages) || pages.length === 0 || !session?.workspacePath) return [];
   const docs = [];
+  const seen = new Set();
   for (const relPath of pages) {
-    try {
-      const absPath = path.resolve(session.workspacePath, relPath);
-      const rel = path.relative(session.workspacePath, absPath);
-      if (rel.startsWith('..') || path.isAbsolute(rel)) {
-        docs.push({ path: relPath, content: null });
-        continue;
-      }
-      const raw = await readFile(absPath, 'utf8');
-      const content = raw.length > maxCharsPerDoc
-        ? `${raw.slice(0, maxCharsPerDoc).trimEnd()}\n[truncated]`
-        : raw;
-      docs.push({ path: relPath, content });
-    } catch {
-      docs.push({ path: relPath, content: null });
+    docs.push(await readWorkspaceFile(session, relPath, maxCharsPerDoc));
+    seen.add(relPath);
+  }
+
+  const citedBy = new Map();
+  for (const doc of docs) {
+    if (typeof doc.content !== 'string') continue;
+    for (const citation of extractSourceCitationPaths(doc.content)) {
+      if (seen.has(citation) || citedBy.has(citation)) continue;
+      citedBy.set(citation, doc.path);
     }
   }
+  for (const [citation, citingPath] of [...citedBy.entries()].slice(0, maxCitedDocs)) {
+    const doc = await readWorkspaceFile(session, citation, maxCharsPerDoc);
+    docs.push({ ...doc, citedBy: citingPath });
+    seen.add(citation);
+  }
   return docs;
 }
 
@@ -473,7 +513,12 @@ export function buildAttachedDocMessages(docs) {
   const readable = (docs ?? []).filter((doc) => typeof doc?.content === 'string' && doc.content.trim());
   if (readable.length === 0) return [];
   const body = readable
-    .map((doc) => `--- BEGIN ATTACHED DOCUMENT ${doc.path} ---\n${doc.content}\n--- END ATTACHED DOCUMENT ${doc.path} ---`)
+    .map((doc) => {
+      const label = doc.citedBy
+        ? `${doc.path} (cited source of ${doc.citedBy} — the real evidence, not a digest)`
+        : doc.path;
+      return `--- BEGIN ATTACHED DOCUMENT ${label} ---\n${doc.content}\n--- END ATTACHED DOCUMENT ${label} ---`;
+    })
     .join('\n\n');
   return [{
     role: 'user',