@dotdrelle/wiki-manager 0.12.11 → 0.14.0

package/src/core/agentEvents.test.js

@@ -440,3 +440,29 @@ test('empty assistant_message finalize is a no-op without a streaming entry', ()
   dispatchAgentEvent(session, createAgentEvent('assistant_message', { origin: 'llm', payload: { content: '' } }));
   assert.equal(session.agentProjection.conversation.length, 1);
 });
+
+test('run_error cancels pending plan steps and active activities (no ghosts at relaunch)', () => {
+  const session = {};
+  dispatchAgentEvent(session, createAgentEvent('plan_set', {
+    origin: 'runtime',
+    payload: { steps: [
+      { id: 'a', description: 'Ingest a.md', status: 'pending', requiredCapability: 'knowledge.update', operation: 'ingest_plan' },
+      { id: 'b', description: 'Ingest b.md', status: 'done' },
+    ] },
+  }));
+  dispatchAgentEvent(session, createAgentEvent('activity_upserted', {
+    origin: 'runtime_poll',
+    payload: { activity: { key: 'production:j1', id: 'j1', label: 'Ingest', status: 'running', terminal: false } },
+  }));
+  dispatchAgentEvent(session, createAgentEvent('run_error', {
+    origin: 'runtime',
+    payload: { message: 'Plan is stalled: no_ready_plan_task' },
+  }));
+
+  const plan = session.agentProjection.plan;
+  assert.equal(plan.find((step) => step.id === 'a').status, 'cancelled');
+  assert.equal(plan.find((step) => step.id === 'b').status, 'done', 'completed work stays done');
+  const activity = session.agentProjection.activities.find((item) => item.id === 'j1');
+  assert.equal(activity.status, 'cancelled');
+  assert.equal(activity.terminal, true);
+});

package/src/core/agentLoop.js

@@ -1,7 +1,7 @@
 import { buildAgentSystemPrompt, formatLlmUnavailableMessage } from '../agent/graph.js';
 import { createAgentEvent, dispatchAgentEvent } from './agentEvents.js';
 import { activitySnapshot, newNonTerminalActivities } from './activity.js';
-import { extractHeadlessPlan, formatCompletedActivities, formatPlanStatus } from './plan.js';
+import { formatCompletedActivities, formatPlanStatus } from './plan.js';
 import { formatReadyTaskPrompt, nextReadyPlanTask, readyPlanTasks, sanitizePlanForExecution } from './planPatch.js';
 
 export function abortError(message = 'Agent run cancelled.') {
@@ -70,9 +70,13 @@ export async function runAgenticLoop(agent, session, initialInput, {
   onMaxTurns = null,
   abortMessage = 'Agent run cancelled.',
   parallelHandoff = false,
+  initialMessages = [],
 } = {}) {
   if (!waitForActivities) throw new Error('runAgenticLoop requires waitForActivities.');
-  const conversationHistory = [];
+  // Seeded with the chat that led to this run: a run that starts amnesiac
+  // receives an orphan sentence ("lance l'ingestion") and the model invents
+  // the missing context — the root of most "Donna répond sans savoir".
+  const conversationHistory = [...initialMessages];
   let currentInput = initialInput;
 
   for (let turn = 1; turn <= maxTurns; turn += 1) {
@@ -95,21 +99,16 @@ export async function runAgenticLoop(agent, session, initialInput, {
       { role: 'assistant', content: response },
     );
 
-    if (turn === 1) {
-      if (session.headlessPlan === null) {
-        const extractedPlan = extractHeadlessPlan(response);
-        if (extractedPlan) {
-          dispatchAgentEvent(session, createAgentEvent('plan_set', {
-            origin: planOrigin,
-            runId,
-            payload: { steps: extractedPlan },
-          }));
-          onPlanExtracted?.({ steps: session.headlessPlan ?? extractedPlan, fallback: true });
-        }
-      } else {
-        onPlanAlreadySet?.({ steps: session.headlessPlan });
-      }
+    if (turn === 1 && session.headlessPlan !== null) {
+      onPlanAlreadySet?.({ steps: session.headlessPlan });
     }
+    // NOTE: the deprecated text-plan extraction is gone. It converted any
+    // numbered list in a chatty LLM answer into an executable plan — the
+    // model's own questions ("Souhaitez-vous que je vous guide ?") became
+    // pending tasks, each step re-invoked the LLM, which produced another
+    // list… an infinite work-inventing loop. Plans now come ONLY from
+    // explicit channels: wiki__plan_set, _activity.plan.steps, or an
+    // integrated agent_plan fragment. Prose stays prose.
     sanitizeSessionPlan(session, { runId });
 
     const newPending = newNonTerminalActivities(snapshot, session);

package/src/core/agentLoop.test.js

@@ -129,23 +129,25 @@ test('runAgenticLoop can finish from terminal activity facts without another LLM
   assert.match(result.summary, /output: deliverables\/result\.md/);
 });
 
-test('runAgenticLoop extracts a fallback numbered plan from first response', async () => {
+test('runAgenticLoop never turns a chatty numbered answer into a plan', async () => {
+  // Regression guard for the removed text-plan extraction: the model's own
+  // numbered prose ("1. … 2. … Souhaitez-vous… ?") used to become pending
+  // tasks and re-invoke the LLM in an infinite work-inventing loop. A chatty
+  // answer with no declared plan and no activity is simply a COMPLETE reply.
   const session = {
     activities: {},
     headlessPlan: null,
   };
   const result = await runAgenticLoop({
     async invoke() {
-      return { response: '1. Collect sources\n2. Build page' };
+      return { response: '1. Collect sources\n2. Build page\nSouhaitez-vous que je vous guide ?' };
     },
   }, session, 'Plan task', {
-    maxTurns: 1,
+    maxTurns: 3,
     timeoutMs: 1000,
     waitForActivities: async () => assert.fail('No activities should be waited for.'),
   });
 
-  assert.equal(result.ok, false);
-  assert.equal(result.maxTurns, true);
-  assert.equal(session.headlessPlan.length, 2);
-  assert.equal(session.headlessPlan[0].description, 'Collect sources');
+  assert.equal(result.ok, true, 'the run completes with the reply instead of inventing steps');
+  assert.equal(session.headlessPlan, null);
 });

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.12.11",
-  "commit": "d8eae0b"
+  "version": "0.14.0",
+  "commit": "fb0b915"
 }

package/src/core/mcp.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
-const WIKI_MANAGER_VERSION = '0.12.11';
+const WIKI_MANAGER_VERSION = '0.14.0';
 
 function envValue(key) {
   const filePath = managerEnvFile();
@@ -305,8 +305,7 @@ export function formatMcpToolResult(result) {
 const DEFAULT_TOOL_RESULT_MAX_CHARS = 16000;
 
 function toolResultMaxChars() {
-  const parsed = Number(process.env.WIKI_MANAGER_TOOL_RESULT_MAX_CHARS);
-  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : DEFAULT_TOOL_RESULT_MAX_CHARS;
+  return DEFAULT_TOOL_RESULT_MAX_CHARS;
 }
 
 // Bound what a tool result injects into the LLM context and the conversation
@@ -480,15 +479,22 @@ export function formatMcpToolSummary(mcpStatus) {
   return lines.length > 0 ? lines.join('\n') : 'No connected MCP tools discovered.';
 }
 
-export function formatMcpToolsForAgent(mcpStatus) {
+export function formatMcpToolsForAgent(mcpStatus, { include } = {}) {
   const sections = [];
   for (const [name, value] of Object.entries(mcpStatus ?? {})) {
     if (value.status !== 'connected') continue;
-    const tools = value.tools ?? [];
-    if (tools.length === 0) {
+    const allTools = value.tools ?? [];
+    if (allTools.length === 0) {
       sections.push(`${name}: connected, tools not discovered yet`);
       continue;
     }
+    // Optional filter: callers (e.g. the interactive prompt) advertise only
+    // the tools Donna is actually allowed to call, so a capable model is not
+    // tempted to invoke a mutating provider tool directly instead of delegating.
+    const tools = typeof include === 'function'
+      ? allTools.filter((tool) => include(`${name}__${tool.name}`, tool, name))
+      : allTools;
+    if (tools.length === 0) continue;
     // Always advertise the qualified call name (server__tool): showing bare
     // tool names here is what teaches the model to emit unqualified calls.
     sections.push(`${name}: ${tools.map((tool) => `${name}__${tool.name}`).join(', ')}`);
@@ -503,6 +509,7 @@ export function buildLlmTools(mcpStatus) {
     for (const tool of value.tools ?? []) {
       tools.push({
         type: 'function',
+        readOnly: tool.annotations?.readOnlyHint === true,
         function: {
           name: `${serverName}__${tool.name}`,
           description: clarifyToolDescription(serverName, tool.name, tool.description),

package/src/core/mcp.test.js

@@ -529,15 +529,3 @@ test('truncateToolResult keeps short results intact and bounds long ones head+ta
   assert.match(bounded, /caractères tronqués/);
 });
 
-test('truncateToolResult honours WIKI_MANAGER_TOOL_RESULT_MAX_CHARS', () => {
-  const previous = process.env.WIKI_MANAGER_TOOL_RESULT_MAX_CHARS;
-  process.env.WIKI_MANAGER_TOOL_RESULT_MAX_CHARS = '500';
-  try {
-    const bounded = truncateToolResult('y'.repeat(5000));
-    assert.ok(bounded.length < 700);
-    assert.match(bounded, /caractères tronqués/);
-  } finally {
-    if (previous === undefined) delete process.env.WIKI_MANAGER_TOOL_RESULT_MAX_CHARS;
-    else process.env.WIKI_MANAGER_TOOL_RESULT_MAX_CHARS = previous;
-  }
-});

package/src/core/skills.js

@@ -69,32 +69,6 @@ function readWorkspaceManifest(workspacePath) {
   }
 }
 
-function readWorkspaceManifestSkill(workspacePath, loadedManifest = null) {
-  const loaded = loadedManifest ?? readWorkspaceManifest(workspacePath);
-  if (!loaded) return null;
-  const { manifest, manifestPath } = loaded;
-  const name = String(manifest.name || basename(workspacePath)).trim();
-  if (!SKILL_NAME_RE.test(name)) return null;
-  const entrypoints = manifest.entrypoints && typeof manifest.entrypoints === 'object'
-    ? manifest.entrypoints
-    : {};
-  const claude = safeRelativeEntry(entrypoints.claude, 'CLAUDE.md');
-  const body = readOptionalText(join(workspacePath, claude));
-  return {
-    name,
-    title: String(manifest.title || name).trim(),
-    description: String(manifest.description || '').trim(),
-    params: [],
-    body,
-    scope: 'workspace',
-    path: manifestPath,
-    manifest,
-    entrypoints,
-    version: manifest.version ? String(manifest.version) : null,
-    language: manifest.language ? String(manifest.language) : null,
-  };
-}
-
 function workspaceUiSkillDir(loadedManifest = null) {
   if (!loadedManifest) return DEFAULT_UI_SKILL_DIR;
   const { manifest } = loadedManifest;
@@ -119,8 +93,6 @@ export function listSkills(session = {}) {
   const skills = [];
   if (session.workspacePath) {
     const loadedManifest = readWorkspaceManifest(session.workspacePath);
-    const manifestSkill = readWorkspaceManifestSkill(session.workspacePath, loadedManifest);
-    if (manifestSkill) skills.push(manifestSkill);
     skills.push(...collectDirectorySkills(join(session.workspacePath, workspaceUiSkillDir(loadedManifest)), 'workspace'));
   }
 

package/src/orchestrator/capabilityRegistry.js

@@ -45,6 +45,20 @@ export function createCapabilityRegistry({ agents = [], compatibleContractVersio
   };
 }
 
+// Discovery and registry construction are asynchronous and are not always
+// completed in the same order. Consumers must nevertheless validate against
+// the live discovered agents instead of treating a temporarily absent cached
+// registry as an empty registry.
+export function capabilityRegistryForSession(session) {
+  const agents = session?.agentRegistry?.snapshot?.()
+    ?? session?.agentRegistrySnapshot
+    ?? session?.agents
+    ?? [];
+  if (agents.length > 0) return createCapabilityRegistry({ agents });
+  if (session?.capabilityRegistry?.providersFor) return session.capabilityRegistry;
+  return createCapabilityRegistry();
+}
+
 function isProviderAgent(agent, compatible) {
   if (!agent || agent.legacy || agent.orchestrable === false) return false;
   if (!compatible.has(String(agent.description?.contractVersion ?? ''))) return false;

package/src/orchestrator/capabilityRegistry.test.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { createCapabilityRegistry } from './capabilityRegistry.js';
+import { capabilityRegistryForSession, createCapabilityRegistry } from './capabilityRegistry.js';
 
 function agent(agentInstanceId, capabilityId, { contractVersion = '1', health = 'available', version = '1' } = {}) {
   return {
@@ -23,6 +23,17 @@ function agent(agentInstanceId, capabilityId, { contractVersion = '1', health =
   };
 }
 
+test('capabilityRegistryForSession rebuilds the registry from live discovery when the cache is absent', () => {
+  const discoveredAgent = agent('production-main', 'knowledge.update');
+  const registry = capabilityRegistryForSession({
+    capabilityRegistry: createCapabilityRegistry(),
+    agentRegistry: { snapshot: () => [discoveredAgent] },
+    agentRegistrySnapshot: [],
+  });
+
+  assert.equal(registry.providersFor('knowledge.update').length, 1);
+});
+
 test('capabilityRegistry indexes two agents for the same capability', () => {
   const registry = createCapabilityRegistry({
     agents: [

package/src/orchestrator/dependencyResolver.js

@@ -15,7 +15,16 @@ export function readyTasks(dag, {
   const done = new Set(tasks.filter((task) => DONE_STATUSES.has(statusOf(task))).map(taskId));
   const active = new Set([...activeTaskIds].map(String));
   return tasks
-    .filter((task) => statusOf(task) === 'pending')
+    .filter((task) => {
+      const status = statusOf(task);
+      return status === 'pending'
+        || ((status === 'waiting_approval' || status === 'pending_approval')
+          && approvalCovered(task, approvals, {
+            runId: task?.runId ?? dag?.runId ?? null,
+            workspaceId: dag?.workspace ?? null,
+            planRevision: dag?.planRevision ?? null,
+          }));
+    })
     .filter((task) => !active.has(taskId(task)))
     .filter((task) => dependenciesDone(task, done))
     .filter((task) => groupBarrierSatisfied(task, tasks))

package/src/orchestrator/dispatcher.js

@@ -8,7 +8,7 @@ const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'c
 export function createDispatcher({
   session = null,
   callTool = callMcpTool,
-  pollIntervalMs = 250,
+  pollIntervalMs = 2500,
 } = {}) {
   return {
     execute(task, assignment, options = {}) {
@@ -30,7 +30,7 @@ export async function execute(task, assignment, {
   attempt = null,
   timeoutMs = null,
   pollBusy = new Set(),
-  pollIntervalMs = 250,
+  pollIntervalMs = 2500,
 } = {}) {
   if (!session) throw new Error('dispatcher.execute requires session.');
   if (!assignment?.serverName) throw new Error(`No MCP server found for agent ${assignment?.agentInstanceId ?? '(unknown)'}.`);
@@ -57,7 +57,7 @@ export async function execute(task, assignment, {
       signal,
     ));
     if (accepted?.accepted === false || accepted?.ok === false) {
-      throw new Error(String(accepted.error ?? 'agent_execute rejected task'));
+      return rejectedTaskResult(task, assignment, accepted, attempt);
     }
     jobId = String(accepted.jobId ?? '');
     if (!jobId) throw new Error('agent_execute did not return jobId.');
@@ -218,6 +218,37 @@ function taskResultFromStatus(task, assignment, jobId, statusPayload, attempt =
   };
 }
 
+function rejectedTaskResult(task, assignment, payload, attempt = null) {
+  const rawError = payload?.error;
+  const error = rawError && typeof rawError === 'object'
+    ? { ...rawError }
+    : {
+        code: String(rawError ?? 'execution_rejected'),
+        message: String(payload?.message ?? rawError ?? 'agent_execute rejected task'),
+        retryable: transientError(rawError ?? payload?.message),
+      };
+  return {
+    ok: false,
+    taskId: String(task.id ?? task.step),
+    attemptId: attempt?.attemptId ?? null,
+    jobId: payload?.activeJobId ?? null,
+    agentInstanceId: assignment.agentInstanceId,
+    status: 'failed',
+    outputRefs: [],
+    metrics: {},
+    error: {
+      code: String(error.code ?? 'execution_rejected'),
+      message: String(error.message ?? error.code ?? 'agent_execute rejected task'),
+      retryable: error.retryable === true || transientError(error.code) || transientError(error.message),
+    },
+    rawStatus: payload,
+  };
+}
+
+function transientError(value) {
+  return /(?:429|timeout|temporar|throttl|rate.?limit|quota|busy|unavailable)/i.test(String(value ?? ''));
+}
+
 function toolNameFor(session, serverName, baseName) {
   const tools = session.mcp?.[serverName]?.tools ?? [];
   const names = tools.map((tool) => String(tool.name ?? '')).filter(Boolean);

package/src/orchestrator/dispatcher.test.js

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createDispatcher } from './dispatcher.js';
+
+test('dispatcher returns a retryable logical failure when agent_execute reports workspace_busy', async () => {
+  const session = {
+    workspace: 'test',
+    mcp: {
+      production: {
+        tools: [
+          { name: 'agent_execute' },
+          { name: 'agent_status' },
+          { name: 'agent_cancel' },
+        ],
+      },
+    },
+  };
+  const dispatcher = createDispatcher({
+    session,
+    callTool: async () => ({ accepted: false, error: 'workspace_busy', activeJobId: 'job-old' }),
+  });
+
+  const result = await dispatcher.execute(
+    { id: 'ingest-a', requiredCapability: 'knowledge.update', operation: 'ingest_plan', arguments: {} },
+    { serverName: 'production', agentInstanceId: 'production-main' },
+    { attempt: { attemptId: 'ingest-a:attempt-1', locks: [], release() {} } },
+  );
+
+  assert.equal(result.ok, false);
+  assert.equal(result.taskId, 'ingest-a');
+  assert.equal(result.attemptId, 'ingest-a:attempt-1');
+  assert.equal(result.error.code, 'workspace_busy');
+  assert.equal(result.error.retryable, true);
+});

package/src/orchestrator/objectiveResolver.js

@@ -0,0 +1,79 @@
+export async function resolveObjective(objective, session) {
+  const candidates = capabilityCandidates(session);
+  if (candidates.length === 0) throw new Error('No orchestrable capability is currently available.');
+  const llm = session?.llm;
+  if (!llm?.completeWithTools) throw new Error('Objective resolution requires the configured workspace LLM.');
+
+  const result = await llm.completeWithTools({
+    system: [
+      'You resolve one user objective against a closed capability registry.',
+      'Select exactly one listed capability and one of its supported operations.',
+      'Never invent identifiers. Return JSON only: {"capability":"...","operation":"..."}.',
+    ].join('\n'),
+    tools: [],
+    messages: [{
+      role: 'user',
+      content: `Objective:\n${String(objective)}\n\nRegistry:\n${JSON.stringify(candidates, null, 2)}`,
+    }],
+    signal: session?._abortSignal,
+  });
+  const selection = parseJson(result?.content);
+  const capability = String(selection?.capability ?? '');
+  const operation = String(selection?.operation ?? '');
+  const candidate = candidates.find((item) => item.id === capability);
+  if (!candidate) throw new Error(`Objective resolver selected unknown capability "${capability}".`);
+  if (!candidate.operations.includes(operation)) {
+    throw new Error(`Objective resolver selected unsupported operation "${operation}" for ${capability}.`);
+  }
+  const providers = providersFor(session, capability)
+    .filter((provider) => !operation || (provider.capability?.supportedOperations ?? []).includes(operation))
+    .sort((a, b) => String(a.agentInstanceId).localeCompare(String(b.agentInstanceId)));
+  if (providers.length === 0) throw new Error(`No healthy agent provides ${capability}/${operation}.`);
+  return { capability, operation, provider: providers[0], candidates };
+}
+
+export function capabilityCandidates(session) {
+  const snapshot = registrySnapshot(session);
+  const byId = new Map();
+  for (const [versionedId, providers] of Object.entries(snapshot)) {
+    const id = versionedId.includes('@') ? versionedId.slice(0, versionedId.lastIndexOf('@')) : versionedId;
+    const operations = [...new Set((providers ?? []).flatMap((provider) => provider?.capability?.supportedOperations ?? []))].sort();
+    const description = (providers ?? []).map((provider) => provider?.capability?.description).find(Boolean) ?? '';
+    byId.set(id, { id, description, operations });
+  }
+  return [...byId.values()].filter((item) => item.operations.length > 0).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function providersFor(session, capability) {
+  if (session?.capabilityRegistry?.providersFor) return session.capabilityRegistry.providersFor(capability) ?? [];
+  return Object.entries(registrySnapshot(session))
+    .filter(([key]) => key === capability || key.startsWith(`${capability}@`))
+    .flatMap(([, providers]) => providers ?? []);
+}
+
+function registrySnapshot(session) {
+  const registry = session?.capabilityRegistry;
+  if (registry?.snapshot) return registry.snapshot();
+  if (registry && typeof registry === 'object') return registry;
+  const agents = session?.agentRegistry?.snapshot?.() ?? session?.agentRegistrySnapshot ?? [];
+  const snapshot = {};
+  for (const agent of agents) {
+    for (const capability of agent?.description?.capabilities ?? []) {
+      const key = `${capability.id}@${capability.version ?? '1'}`;
+      (snapshot[key] ??= []).push({
+        agentInstanceId: agent.agentInstanceId,
+        serverName: agent.serverName,
+        capability,
+        description: agent.description,
+        health: agent.health,
+      });
+    }
+  }
+  return snapshot;
+}
+
+function parseJson(content) {
+  const text = String(content ?? '').trim();
+  const fenced = text.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  return JSON.parse(fenced ? fenced[1] : text);
+}

package/src/orchestrator/objectiveResolver.test.js

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { capabilityCandidates, resolveObjective } from './objectiveResolver.js';
+
+function sessionWithSelection(selection) {
+  const provider = {
+    agentInstanceId: 'production-1',
+    serverName: 'production',
+    capability: {
+      id: 'knowledge.update',
+      version: '1',
+      description: 'Update knowledge from pending sources.',
+      supportedOperations: ['ingest'],
+    },
+  };
+  return {
+    capabilityRegistry: {
+      snapshot: () => ({ 'knowledge.update@1': [provider] }),
+      providersFor: () => [provider],
+    },
+    llm: {
+      completeWithTools: async () => ({ content: JSON.stringify(selection) }),
+    },
+  };
+}
+
+test('capabilityCandidates exposes only the closed live registry', () => {
+  assert.deepEqual(capabilityCandidates(sessionWithSelection({})), [{
+    id: 'knowledge.update',
+    description: 'Update knowledge from pending sources.',
+    operations: ['ingest'],
+  }]);
+});
+
+test('resolveObjective selects and validates one real provider', async () => {
+  const result = await resolveObjective('Ingère tous les fichiers en attente', sessionWithSelection({
+    capability: 'knowledge.update',
+    operation: 'ingest',
+  }));
+  assert.equal(result.capability, 'knowledge.update');
+  assert.equal(result.operation, 'ingest');
+  assert.equal(result.provider.agentInstanceId, 'production-1');
+});
+
+test('resolveObjective rejects invented capability and operation', async () => {
+  await assert.rejects(
+    resolveObjective('Ingère tout', sessionWithSelection({ capability: 'ingest', operation: 'ingest_all_pending' })),
+    /unknown capability "ingest"/,
+  );
+});

package/src/orchestrator/scheduler.js

@@ -9,6 +9,30 @@ export function resolveSchedulerConcurrency(value = process.env.WIKI_MANAGER_SCH
     : DEFAULT_SCHEDULER_CONCURRENCY;
 }
 
+export function resolvePlanConcurrency({ plan = [], agents = [], configured = null } = {}) {
+  const capabilities = new Set(plan.map((task) => task?.requiredCapability).filter(Boolean).map(String));
+  const assignedAgents = new Set(plan.map((task) => task?.agentInstanceId).filter(Boolean).map(String));
+  const relevantAgents = agents.filter((agent) => {
+    const id = String(agent?.agentInstanceId ?? agent?.description?.agentInstanceId ?? '');
+    if (id && assignedAgents.has(id)) return true;
+    return (agent?.description?.capabilities ?? []).some((capability) => capabilities.has(String(capability?.id ?? '')));
+  });
+  const values = [
+    positiveInteger(configured),
+    ...plan.flatMap(concurrencyValues),
+    ...relevantAgents.flatMap(concurrencyValues),
+  ].filter(Boolean);
+  return values.length > 0 ? Math.max(1, Math.min(...values)) : DEFAULT_SCHEDULER_CONCURRENCY;
+}
+
+export function resolveCapabilityConcurrency(agent = null, ...constraints) {
+  const values = [
+    ...concurrencyValues(agent),
+    ...constraints.map(positiveInteger),
+  ].filter(Boolean);
+  return values.length > 0 ? Math.max(1, Math.min(...values)) : DEFAULT_SCHEDULER_CONCURRENCY;
+}
+
 export function effectiveConcurrency(group = null, agent = null, donna = null, provider = null) {
   const limits = [
     ...concurrencyValues(donna),

package/src/orchestrator/scheduler.test.js

@@ -6,7 +6,12 @@ import test from 'node:test';
 import { createBudgetManager } from './budgetManager.js';
 import { readyTasks } from './dependencyResolver.js';
 import { createLockManager } from './lockManager.js';
-import { effectiveConcurrency, startReadyTasks } from './scheduler.js';
+import {
+  effectiveConcurrency,
+  resolveCapabilityConcurrency,
+  resolvePlanConcurrency,
+  startReadyTasks,
+} from './scheduler.js';
 
 test('dependencyResolver holds a barrier task until its dependsOnGroup is done', () => {
   const plan = [
@@ -30,6 +35,31 @@ test('dependencyResolver orders ready tasks by priority before step', () => {
   assert.deepEqual(readyTasks(plan).map((item) => item.id), ['high', 'low', 'none']);
 });
 
+test('dependencyResolver releases a waiting task when a run grant covers it', () => {
+  const plan = {
+    runId: 'run-1',
+    workspace: 'test4',
+    planRevision: 1,
+    tasks: [task('ingest', {
+      status: 'waiting_approval',
+      requiresApproval: true,
+      approvalClass: 'mutation',
+    })],
+  };
+
+  assert.deepEqual(readyTasks(plan), []);
+  assert.deepEqual(readyTasks(plan, {
+    approvals: [{
+      status: 'approved',
+      scope: 'run',
+      runId: 'run-1',
+      workspaceId: 'test4',
+      planRevision: 1,
+      approvalClasses: ['mutation'],
+    }],
+  }).map((item) => item.id), ['ingest']);
+});
+
 test('dependencyResolver skips tasks whose locks are not free and keeps other ready work moving', () => {
   const lockManager = createLockManager();
   const held = lockManager.acquire(['deliverable:a.md']);
@@ -76,6 +106,40 @@ test('scheduler.effectiveConcurrency returns the minimum effective concurrency',
   assert.equal(effectiveConcurrency(group, agent, donna, provider), 2);
 });
 
+test('scheduler uses the relevant agent declaration instead of hard-capping plans at three', () => {
+  const plan = [{ id: 'task-1', requiredCapability: 'ingest' }];
+  const agents = [{
+    description: {
+      capabilities: [{ id: 'ingest' }],
+      limits: { recommendedConcurrency: 10, maxConcurrency: 12 },
+    },
+  }];
+
+  assert.equal(resolvePlanConcurrency({ plan, agents }), 10);
+  assert.equal(resolvePlanConcurrency({ plan, agents, configured: 3 }), 3);
+  assert.equal(resolvePlanConcurrency({ plan, agents, configured: 20 }), 10);
+});
+
+test('scheduler ignores unrelated agents and falls back to three without declarations', () => {
+  const plan = [{ id: 'task-1', requiredCapability: 'ingest' }];
+  const agents = [{
+    description: {
+      capabilities: [{ id: 'production' }],
+      limits: { recommendedConcurrency: 1 },
+    },
+  }];
+
+  assert.equal(resolvePlanConcurrency({ plan, agents }), 3);
+});
+
+test('capability constraints can lower but never raise an agent declaration', () => {
+  const agent = { description: { limits: { recommendedConcurrency: 6, maxConcurrency: 10 } } };
+
+  assert.equal(resolveCapabilityConcurrency(agent), 6);
+  assert.equal(resolveCapabilityConcurrency(agent, 2), 2);
+  assert.equal(resolveCapabilityConcurrency(agent, 20), 6);
+});
+
 test('startReadyTasks starts only ready tasks and respects lock starvation', () => {
   const active = new Map();
   const lockManager = createLockManager();