madarx 2.21.0 → 2.22.0

package/lib/agent-routing.js

@@ -23,6 +23,7 @@ import {
   CATEGORY_TO_ROLE,
   KEYWORD_CATEGORY_HINTS,
   isSpecialistTool,
+  neededToolCategoriesForGoal,
   roleForCategory,
 } from './role-capability-map.js';
 
@@ -86,6 +87,34 @@ export function assessCoverage(agentId, neededTools = []) {
   return { covered: missing.length === 0, granted, missing_tools: missing };
 }
 
+/** Catalog tools whose category is in `categories`. Pure. */
+export function toolsForCategories(catalog = [], categories = []) {
+  const cats = new Set(categories);
+  if (!cats.size) return [];
+  return (catalog || []).filter((t) => cats.has(t.category));
+}
+
+/**
+ * Rank existing agents that ALREADY own tools in the needed categories — the
+ * delegate-first answer. An image-gen goal surfaces the agent granted
+ * higgsfield_generate_image, so the main agent reuses it instead of spawning a
+ * tool-less new specialist that completes nothing. Pure (no DB).
+ *
+ * @returns {Array<{id,name,role,owns_tools:string[]}>} sorted by overlap desc
+ */
+export function recommendSpecialists({ agents = [], categories = [], catalog = [] } = {}) {
+  const cats = new Set(categories);
+  if (!cats.size) return [];
+  const toolCat = new Map((catalog || []).map((t) => [t.name, t.category]));
+  const ranked = [];
+  for (const a of agents) {
+    const owns = (a.tools || []).filter((name) => cats.has(toolCat.get(name)));
+    if (owns.length) ranked.push({ id: a.id, name: a.name, role: a.role || null, owns_tools: owns });
+  }
+  ranked.sort((x, y) => y.owns_tools.length - x.owns_tools.length);
+  return ranked;
+}
+
 /**
  * Assemble the grounded registry the main agent reasons over to route a goal.
  * Read-only; no side effects.
@@ -125,6 +154,26 @@ export function buildRoutingContext({ goal = '', project_id = null } = {}) {
   const toolSmith = allAgents.find((a) => a.id === TOOL_SMITH_AGENT_ID && isActiveStatus(a.status));
   const hint = fastPathHint(goal);
 
+  // Capability match: which tool categories this goal needs, which catalog tools
+  // sit in them, and which existing agents already own those tools. This is the
+  // delegate-first answer made explicit so the agent reuses an equipped
+  // specialist instead of spawning a tool-less new one.
+  const neededCategories = neededToolCategoriesForGoal(goal);
+  const recommendedSpecialists = recommendSpecialists({ agents, categories: neededCategories, catalog });
+  const toolsForGoal = toolsForCategories(catalog, neededCategories).map((t) => ({
+    name: t.name,
+    category: t.category,
+    enabled: t.enabled,
+    available: t.available,
+    owners: agents.filter((a) => (a.tools || []).includes(t.name)).map((a) => a.id),
+  }));
+
+  const matchNote = recommendedSpecialists.length
+    ? `CAPABILITY MATCH — recommended_specialists already own the tool(s) this goal needs (see tools_for_goal). PREFER ladder step 1 (delegate) to "${recommendedSpecialists[0].name}" (owns ${recommendedSpecialists[0].owns_tools.join(', ')}); do NOT create a new agent when one already owns the tool. `
+    : toolsForGoal.length
+      ? `CAPABILITY MATCH — no existing agent owns the tool(s) this goal needs (tools_for_goal lists them). create_then_delegate, and when you create_agent you MUST grant it those tools — an agent with no matching tool cannot finish the goal. `
+      : '';
+
   return {
     goal: String(goal || ''),
     agents,
@@ -132,9 +181,13 @@ export function buildRoutingContext({ goal = '', project_id = null } = {}) {
     tools_catalog: catalog,
     tool_smith_available: Boolean(toolSmith),
     fast_path_hint: hint,
+    needed_categories: neededCategories,
+    recommended_specialists: recommendedSpecialists,
+    tools_for_goal: toolsForGoal,
     recommendation_ladder: RECOMMENDATION_LADDER,
     routing_note:
-      'Reason over agents[] (role/mission/skills/tools) vs. what this goal needs. '
+      matchNote
+      + 'Reason over agents[] (role/mission/skills/tools) vs. what this goal needs. '
       + 'Pick a ladder step: delegate an existing fit specialist, create_then_delegate when none fits, '
       + 'build_capability via Tool Smith when a specialist lacks a tool, or direct_fallback for trivial asks. '
       + 'fast_path_hint is only a shortcut for obvious domains — do not treat it as the answer when the goal is broader.',

package/lib/cli-action-flow.js

@@ -0,0 +1,88 @@
+/**
+ * Pure classification of a CLI engine turn's executed madarx-action blocks.
+ *
+ * Why this exists: the CLI engines (claude-code / codex) execute madarx-action
+ * blocks POST-HOC (app/api/orchestrator/stream/route.js::executeCliActions) and
+ * never feed the results back into the subprocess. There is no "turn 2" inside
+ * one CLI invocation.
+ *
+ * route_goal is a PLANNING action: its result (the live roster) must drive a
+ * follow-up DELEGATING action (run_agent / create_agent / request_capability).
+ * A turn that calls ONLY route_goal therefore dead-ends — the model narrates
+ * "I'll delegate once the roster comes back", but the roster never comes back to
+ * it, so no specialist is ever dispatched (no sub-agent run, nothing in the
+ * activity panel). classifyCliTurn() detects that stall so the caller can
+ * re-invoke the CLI once with the route_goal registry injected — the CLI-engine
+ * equivalent of the Anthropic agentic loop's turn 2.
+ */
+
+/** Actions that actually delegate work to a specialist (complete the ladder). */
+export const DELEGATING_TOOLS = new Set([
+  'run_agent',
+  'create_agent',
+  'request_capability',
+]);
+
+/**
+ * Planning/routing tools whose RESULT must drive a follow-up action. On their
+ * own they complete nothing — they only hand back a registry to reason over.
+ */
+export const PLANNING_TOOLS = new Set(['route_goal']);
+
+/**
+ * Classify the actions executed in one CLI turn.
+ *
+ * @param {Array<{tool?: string, result?: any}>} actions - executeCliActions output
+ * @param {{ hasHtml?: boolean }} opts - hasHtml: did the turn emit an HTML artifact
+ * @returns {{ ranDelegatingAction: boolean, ranPlanningAction: boolean,
+ *             onlyPlanning: boolean, needsRouteContinuation: boolean }}
+ */
+export function classifyCliTurn(actions = [], { hasHtml = false } = {}) {
+  const list = Array.isArray(actions) ? actions : [];
+  const ranDelegatingAction = list.some((a) => DELEGATING_TOOLS.has(a?.tool));
+  const ranPlanningAction = list.some((a) => PLANNING_TOOLS.has(a?.tool));
+  // Tightest, safest trigger: fire ONLY when literally nothing but planning
+  // tools ran and no artifact stands as the answer. If route_goal ran alongside
+  // any other action, assume the model already took a terminal step — never
+  // re-prompt over a one-shot delegation or a conversational answer.
+  const onlyPlanning = list.length > 0 && list.every((a) => PLANNING_TOOLS.has(a?.tool));
+  const needsRouteContinuation = onlyPlanning && !hasHtml;
+  return { ranDelegatingAction, ranPlanningAction, onlyPlanning, needsRouteContinuation };
+}
+
+/** Result of the LAST planning action in the turn (the registry to feed back). */
+export function latestPlanningResult(actions = []) {
+  const list = Array.isArray(actions) ? actions : [];
+  for (let i = list.length - 1; i >= 0; i--) {
+    if (PLANNING_TOOLS.has(list[i]?.tool)) return list[i].result;
+  }
+  return null;
+}
+
+/**
+ * Build the re-invocation prompt that injects the route_goal registry back into
+ * the CLI so it can pick a ladder step and emit the real delegating action.
+ */
+export function buildRouteGoalContinuationPrompt(baseUserContent, registry) {
+  let registryJson;
+  try {
+    registryJson = JSON.stringify(registry, null, 2);
+  } catch {
+    registryJson = String(registry);
+  }
+  registryJson = (registryJson || '').slice(0, 8000);
+  return `${baseUserContent}
+
+[SYSTEM] You called route_goal and its result (the live roster) is below. The CLI engine does NOT return tool results to you across turns — this is your ONE chance to act on it. Do NOT call route_goal again and do NOT promise to delegate "once the roster comes back." Reason over this registry now and emit the matching madarx-action block THIS turn:
+- delegate: an existing specialist fits -> run_agent it (pass instruction + expected_output).
+- create_then_delegate: none fits -> create_agent the needed role, then run_agent it.
+- build_capability: a specialist exists but lacks a required tool -> request_capability so Tool Smith builds + grants it, then delegate.
+If and ONLY if the goal is a trivial one-line factual ask, answer directly instead.
+
+CAPABILITY RULES (a goal that needs a tool MUST end with that tool actually running):
+- If recommended_specialists is non-empty, DELEGATE to the top one with run_agent — it already owns the tool this goal needs. Do NOT create a new agent when one already owns the tool.
+- If you must create_agent, you MUST pass the exact tool names from tools_for_goal in its "tools" so the new agent can finish — an agent with no matching tool generates nothing and the goal fails.
+
+route_goal result:
+${registryJson}`;
+}

package/lib/delegation.js

@@ -522,7 +522,11 @@ export function createTask(payload = {}) {
     agent_id: assignee?.id || null,
     details: { event: 'created' },
     event_type: 'task.created',
-    wake_reason: assignee ? 'task_assigned' : null,
+    // suppress_wake: the caller will run this assignee synchronously (chat
+    // delegation) and must NOT also queue an async heartbeat agent-task, or the
+    // sub-agent would run twice. The task row is still created + assigned for
+    // tracking; only the auto-dispatch is skipped.
+    wake_reason: (assignee && !payload.suppress_wake) ? 'task_assigned' : null,
   });
   if (assignee) {
     recordTaskMutation(task, {
@@ -547,6 +551,68 @@ export function createTask(payload = {}) {
   return task;
 }
 
+/**
+ * Periodic safety net: drive assigned tasks toward completion. Idempotent — only
+ * acts on a task when it has NO active run and NO already-queued agent-task wake,
+ * so repeated sweeps never double-dispatch or spam. Run by the recurring
+ * `task_sweep` heartbeat job (lib/heartbeat-worker.js).
+ *
+ * Acts on three classes of assigned, non-terminal task:
+ *  - todo never dispatched      → wake the assignee (task_assigned)
+ *  - in_progress stale, no run  → re-wake the assignee to resume (task_blockers_resolved)
+ *  - overdue (due_at passed)    → re-wake the assignee to finish (task_blockers_resolved)
+ *
+ * @param {{ now?: number, staleMinutes?: number }} opts
+ * @returns {{ assigned_woken: string[], rewoken: string[], overdue_woken: string[], scanned: number }}
+ */
+export function sweepTasks({ now = Date.now(), staleMinutes = 30 } = {}) {
+  const db = getDb();
+  const nowIsoStr = new Date(now).toISOString();
+  const staleCutoff = new Date(now - staleMinutes * 60 * 1000).toISOString();
+  const out = { assigned_woken: [], rewoken: [], overdue_woken: [], scanned: 0 };
+
+  // A task already has work in flight when it has an active run OR a queued/leased
+  // agent-task heartbeat referencing it. The LIKE match is safe because task ids
+  // are unique opaque tokens (`task_...`) that never collide as substrings.
+  const hasQueuedWake = db.prepare(
+    "SELECT 1 FROM heartbeat_tasks WHERE type = 'agent-task' AND status IN ('queued','leased','running') AND payload LIKE ? LIMIT 1",
+  );
+  const inFlight = (taskId) => Boolean(getTaskActiveRun(taskId)) || Boolean(hasQueuedWake.get(`%"task_id":"${taskId}"%`));
+
+  const wake = (taskId, reason, bucket) => {
+    if (inFlight(taskId)) return;
+    const task = getTask(taskId);
+    if (!task || !task.assignee_agent_id || isTerminalTaskStatus(task.status)) return;
+    if (queueTaskWake({ task, reason, triggerSource: 'task-sweep' })) out[bucket].push(taskId);
+  };
+
+  // 1. Assigned but never dispatched (e.g. created via the UI, or a wake that was
+  //    never enqueued). status 'todo' with an assignee and nothing in flight.
+  const todoAssigned = db.prepare(
+    "SELECT id FROM tasks WHERE status = 'todo' AND assignee_agent_id IS NOT NULL",
+  ).all();
+  out.scanned += todoAssigned.length;
+  for (const t of todoAssigned) wake(t.id, 'task_assigned', 'assigned_woken');
+
+  // 2. Stuck in_progress: claimed long ago, no active run — the worker crashed,
+  //    the chat turn died, or the agent never reported back. Re-wake to resume.
+  const stuck = db.prepare(
+    "SELECT id FROM tasks WHERE status = 'in_progress' AND assignee_agent_id IS NOT NULL AND updated_at < ?",
+  ).all(staleCutoff);
+  out.scanned += stuck.length;
+  for (const t of stuck) wake(t.id, 'task_blockers_resolved', 'rewoken');
+
+  // 3. Overdue: a deadline passed and the task is not finished. Re-wake the
+  //    assignee to push it to completion.
+  const overdue = db.prepare(
+    "SELECT id FROM tasks WHERE due_at IS NOT NULL AND due_at < ? AND status NOT IN ('done','cancelled')",
+  ).all(nowIsoStr);
+  out.scanned += overdue.length;
+  for (const t of overdue) wake(t.id, 'task_blockers_resolved', 'overdue_woken');
+
+  return out;
+}
+
 export function updateTask(id, patch = {}) {
   const db = getDb();
   const current = getTask(id);
@@ -1053,6 +1119,33 @@ export function getTaskLastRun(taskId) {
   `).get(taskId));
 }
 
+/**
+ * Every persisted agent run currently in an active status, with the agent name.
+ * Backs GET /api/agents/active-runs so the activity panels can seed "what's
+ * running now" on mount/reconnect instead of depending on catching the live
+ * agent_run_start SSE event (which a late or reconnected EventSource can miss).
+ */
+export function listActiveAgentRuns({ limit = 50 } = {}) {
+  const rows = getDb().prepare(`
+    SELECT r.id, r.agent_id, r.status, r.trigger_source, r.started_at, r.created_at, r.task_id,
+           a.name AS agent_name
+    FROM agent_runs r
+    LEFT JOIN agents a ON a.id = r.agent_id
+    WHERE r.status IN ('queued', 'running', 'waiting_approval')
+    ORDER BY r.created_at DESC
+    LIMIT ?
+  `).all(limit);
+  return rows.map((r) => ({
+    run_id: r.id,
+    agent_id: r.agent_id,
+    agent_name: r.agent_name || r.agent_id,
+    status: r.status,
+    triggered_by: r.trigger_source || null,
+    started_at: r.started_at || r.created_at || null,
+    task_id: r.task_id || null,
+  }));
+}
+
 export function getTaskLastFailure(taskId) {
   return rowToAgentRun(getDb().prepare(`
     SELECT * FROM agent_runs

package/lib/heartbeat-worker.js

@@ -63,6 +63,19 @@ async function executeTask(task) {
     });
     return { ok: true, behind: check.behind, latest: check.latest, applied };
   }
+  if (type === 'task_sweep') {
+    const { sweepTasks } = await import('./delegation.js');
+    const result = sweepTasks();
+    // Recurring: re-schedule the next sweep. Frequent enough to keep the queue
+    // moving, light enough to be cheap (idempotent, read-mostly).
+    createHeartbeatTask({
+      type: 'task_sweep',
+      payload: { type: 'task_sweep' },
+      max_attempts: 99,
+      run_after: new Date(Date.now() + 2 * 60 * 1000).toISOString(),
+    });
+    return { ok: true, ...result };
+  }
   if (type === 'competitor-report') return competitorReport({ triggered_by: 'heartbeat-worker' });
   if (type === 'marketing-plan') return marketingPlan({ triggered_by: 'heartbeat-worker' });
   if (type === 'heartbeat') return heartbeatTick({ triggered_by: 'heartbeat-worker' });

package/lib/orchestrator-tools.js

@@ -19,6 +19,7 @@ import {
   deleteArtifact,
   moveArtifact,
   listAgents,
+  listAgentToolPermissions,
   setAgentWhatsAppNotify,
   findArtifacts,
   getArtifact,
@@ -42,10 +43,11 @@ import { executeRegistryTool, getEnabledToolSchemas, listMarketplaceTools, setTo
 import { listMarketplaceItems } from './marketplace.js';
 import { buildRoutingContext } from './agent-routing.js';
 import { isSpecialistTool } from './role-capability-map.js';
-import { createTask, listTasks } from './delegation.js';
+import { createTask, listTasks, getTask, updateTask } from './delegation.js';
 import { runSingleReport } from './mines/diligence.js';
 import { getBridgeHealth, sendWhatsAppDocument, sendWhatsAppMessage } from './whatsapp.js';
 import { listProjects } from './projects.js';
+import { diskListFolders, diskListFiles, diskReadFile } from './tools/adapters/disk.js';
 import {
   createSpace,
   deleteSpace,
@@ -662,6 +664,72 @@ export const CORE_TOOLS = [
       properties: {},
     },
   },
+  {
+    name: 'list_agents',
+    description:
+      'List the existing sub-agents (your workforce) and WHAT EACH CAN DO — id, name, role, status, the tools each is granted, and how many open tasks it already has. Call this BEFORE creating a new agent: if an existing agent already owns the tool the goal needs, delegate to it with run_agent instead of spawning a duplicate. This is the cheap roster read; route_goal is the fuller capability match for a specific goal.',
+    input_schema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'list_projects',
+    description:
+      'List the owner\'s projects (the workspaces shown at /projects/<slug>). Returns each project\'s id, slug, name, and status. Use this to resolve which project the owner means before reading its Disk with disk_list_files / disk_list_folders.',
+    input_schema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'disk_list_folders',
+    description:
+      'List the FOLDERS inside a project\'s Disk — the owner\'s "project folder" / "my files" shown at /projects/<slug>. This is the owner\'s content, NOT the madarX source code. Use this (never file_read/directory_list/Bash on the source tree) when the owner asks to check their project, folder, or files.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        project_id: {
+          type: 'string',
+          description: 'Project id or slug (e.g. "ai-agents"). Omit to use the active project. If unsure, call list_projects first.',
+        },
+      },
+    },
+  },
+  {
+    name: 'disk_list_files',
+    description:
+      'List the FILES in a project\'s Disk (the owner\'s "project folder" at /projects/<slug>). Returns file id, name, kind, size, and local_only flag. This is the owner\'s uploaded/produced content — NOT madarX source code. Read a file\'s contents with disk_read_file using the returned id.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        project_id: {
+          type: 'string',
+          description: 'Project id or slug (e.g. "ai-agents"). Omit to use the active project. If unsure, call list_projects first.',
+        },
+        folder_id: {
+          type: 'string',
+          description: 'Optional folder id (from disk_list_folders) to list only that folder. Omit to list all files in the project.',
+        },
+      },
+    },
+  },
+  {
+    name: 'disk_read_file',
+    description:
+      'Read the contents of a single Disk file by id (get ids from disk_list_files). Returns the file body. local_only files are redacted for cloud engines by design.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        file_id: { type: 'string', description: 'The Disk file id, from disk_list_files.' },
+        project_id: {
+          type: 'string',
+          description: 'Optional project id or slug to scope the read to (cross-project reads are refused). Omit to use the active project.',
+        },
+      },
+      required: ['file_id'],
+    },
+  },
   {
     name: 'create_artifact',
     description:
@@ -1358,9 +1426,51 @@ async function dispatchTool(toolName, input = {}, context = {}) {
       return summarizeStateForTool(full);
     }
 
+    case 'list_agents': {
+      // Roster + capabilities + current load, so the main agent reuses an
+      // equipped agent instead of creating a duplicate. Excludes the Tool Smith
+      // (it builds capabilities, it isn't a delegation target).
+      const roster = listAgents()
+        .filter((a) => a.id !== 'tool-smith-agent' && a.status !== 'terminated')
+        .map((a) => {
+          let tools = [];
+          try {
+            tools = listAgentToolPermissions(a.id)
+              .filter((p) => p.mode !== 'disabled')
+              .map((p) => p.tool_name);
+          } catch { /* legacy agent with no permission rows */ }
+          let openTasks = 0;
+          try {
+            openTasks = listTasks({ assignee_agent_id: a.id }).filter(
+              (t) => t.status !== 'done' && t.status !== 'cancelled',
+            ).length;
+          } catch { /* tasks table not ready */ }
+          return {
+            id: a.id,
+            name: a.name,
+            role: a.role || a.type || null,
+            status: a.status || null,
+            engine: a.engine || null,
+            mission: a.mission || null,
+            tools,
+            open_tasks: openTasks,
+          };
+        });
+      return { ok: true, agents: roster, agent_count: roster.length };
+    }
+
     case 'list_projects':
       return { ok: true, projects: listProjects({ status: 'all' }) };
 
+    case 'disk_list_folders':
+      return diskListFolders(input, context);
+
+    case 'disk_list_files':
+      return diskListFiles(input, context);
+
+    case 'disk_read_file':
+      return diskReadFile(input, context);
+
     case 'create_artifact': {
       const allowedKinds = new Set(['markdown', 'text']);
       const kind = allowedKinds.has(input.kind) ? input.kind : 'markdown';
@@ -1644,13 +1754,50 @@ async function runAgentOnDemand(input, context = {}) {
         meta: { agent_id: agent.id, wake_reason, has_instruction: Boolean(instruction), has_expected_output: Boolean(expected_output) },
       });
     }
-    const run = await runAgentTick(agent.id, { triggered_by: 'main_agent', wake_reason, instruction, expected_output, pending_approvals });
+    // Task-backed delegation: every chat-initiated delegation is a tracked task
+    // on the /tasks board, so the owner can follow it and the sweep cron can
+    // ensure it completes. We create the task with suppress_wake and run it
+    // SYNCHRONOUSLY here (passing task_id) — runAgentTick persists the agent_run
+    // (running→terminal), moves the task in_progress→in_review, and emits the
+    // live events the activity panels seed from. Best-effort: a tasks-table hiccup
+    // must never block the delegation itself.
+    let task = null;
+    try {
+      const title = (instruction || wake_reason || `Run ${agent.name}`).slice(0, 140);
+      task = createTask({
+        title,
+        description: instruction || null,
+        assignee_agent_id: agent.id,
+        status: 'todo',
+        priority: 'medium',
+        created_by_user_id: context.user_id || null,
+        project_id: context.project_id || null,
+        acceptance_criteria: expected_output || null,
+        suppress_wake: true,
+      });
+    } catch { task = null; }
+
+    const run = await runAgentTick(agent.id, { triggered_by: 'main_agent', task_id: task?.id || null, wake_reason, instruction, expected_output, pending_approvals });
     if (!run) return { ok: false, error: `runAgentTick returned null for ${agent.id}` };
+
+    // Auto-complete the happy path: runAgentTick advances a successful run's task
+    // to in_review. With the deliverable on canvas and no approval pending, mark
+    // it done. Blocked/failed tasks stay open for the sweep + main-agent verify.
+    if (task && !run.pending_approval) {
+      try {
+        const cur = getTask(task.id);
+        if (cur && cur.status === 'in_review') {
+          updateTask(task.id, { status: 'done', actor_type: 'agent', actor_id: agent.id });
+        }
+      } catch { /* leave for the task sweep / main-agent verification */ }
+    }
+
     return {
       ok: true,
       agent_id: agent.id,
       agent_name: agent.name,
       run_id: run.id,
+      task_id: task?.id || null,
       status: run.pending_approval ? 'awaiting_approval' : (run.status || 'complete'),
       title: run.artifact_title || run.title,
       preview: (run.preview || '').slice(0, 600),

package/lib/role-capability-map.js

@@ -66,6 +66,11 @@ export const KEYWORD_CATEGORY_HINTS = [
   [/\b(calendar|schedule a (meeting|call)|book (a )?(meeting|slot|30 ?min)|invite .* to)\b/i, 'calendar'],
   [/\b(deploy|vercel|production build|ship the site)\b/i, 'vercel'],
   [/\b(supabase|database row|insert into|update the table|sql)\b/i, 'supabase'],
+  // Visual / image generation — routes to whoever owns the media tools
+  // (higgsfield_generate_image / _video / product_photoshoot). Without this, an
+  // "create an ad image" goal had no hint and the agent spawned a bare,
+  // tool-less specialist that could not generate anything.
+  [/\b(image|images|photo|photograph|photoshoot|picture|visual|visuals|render|rendering|artwork|illustration|graphic|poster|advert|advertisement|\bad\b|\bads\b|banner|logo|thumbnail|mockup|still[\s-]?life|moodboard|generate (an?|the) (image|picture|visual|ad)|text[\s-]?to[\s-]?image)\b/i, 'media'],
 ];
 
 /**
@@ -87,3 +92,20 @@ export function isSpecialistTool(tool) {
 export function roleForCategory(category) {
   return CATEGORY_TO_ROLE[category] || null;
 }
+
+/**
+ * ALL tool categories a goal plausibly needs (deduped), not just the first hit.
+ * Used by buildRoutingContext to surface which existing specialists already own
+ * the matching tools, so the main agent delegates to an equipped agent instead
+ * of spawning a tool-less one. A goal with no keyword match returns [] and the
+ * routing falls back to pure LLM reasoning over the registry — unchanged.
+ */
+export function neededToolCategoriesForGoal(goal) {
+  const text = String(goal || '');
+  if (!text.trim()) return [];
+  const cats = [];
+  for (const [re, category] of KEYWORD_CATEGORY_HINTS) {
+    if (re.test(text) && !cats.includes(category)) cats.push(category);
+  }
+  return cats;
+}

package/lib/seeds.js

@@ -89,6 +89,31 @@ function seedUpdateCheckTask(db) {
   `).run(id, 'update_check', payload, runAfter, now, now);
 }
 
+/**
+ * Ensure a queued recurring task_sweep heartbeat task exists (idempotent). The
+ * worker re-schedules the next sweep +2m after each run, so this seed only fires
+ * on a fresh install. The sweep drives assigned tasks toward completion:
+ * dispatches never-woken tasks, re-wakes stuck/overdue ones. See
+ * lib/delegation.js::sweepTasks.
+ */
+function seedTaskSweepTask(db) {
+  const existing = db.prepare(
+    "SELECT id FROM heartbeat_tasks WHERE type = 'task_sweep' AND status IN ('queued','leased','running') LIMIT 1"
+  ).get();
+  if (existing) return;
+
+  const id = `hbtask-sweep-${Date.now().toString(36)}`;
+  const payload = JSON.stringify({ type: 'task_sweep' });
+  const now = new Date().toISOString();
+  // First sweep: 2 min after install.
+  const runAfter = new Date(Date.now() + 2 * 60 * 1000).toISOString();
+  db.prepare(`
+    INSERT INTO heartbeat_tasks
+      (id, agent_id, schedule_id, type, status, priority, payload, attempts, max_attempts, run_after, created_at, updated_at)
+    VALUES (?, NULL, NULL, ?, 'queued', 0, ?, 0, 99, ?, ?, ?)
+  `).run(id, 'task_sweep', payload, runAfter, now, now);
+}
+
 /**
  * Seed a default email allowlist entry for the email_send tool.
  *
@@ -448,6 +473,14 @@ export function seedDefaults(db) {
     // Ignore — heartbeat_tasks table may not be ready yet during schema bootstrap.
   }
 
+  // Infrastructure: ensure the recurring task-sweep is queued (idempotent). Keeps
+  // assigned tasks moving toward completion (dispatch/​re-wake stuck/overdue).
+  try {
+    seedTaskSweepTask(db);
+  } catch {
+    // Ignore — heartbeat_tasks table may not be ready yet during schema bootstrap.
+  }
+
   // Email allowlist: seed install user's domain from git config on first install.
   try {
     seedDefaultEmailAllowlist(db);