madarx 2.19.0 → 2.22.0

package/lib/agent-runner.js

@@ -4,6 +4,7 @@ import { chatWithClaude } from './claude.js';
 import { defaultModelForEngine, normalizeAgentEngine, runAgentEngine } from './agent-engines.js';
 import { currentDateInstruction } from './agent-config.js';
 import { renderDocumentHtml, stripEmoji } from './artifact-format.js';
+import { buildHiggsfieldGalleryHtml } from './higgsfield-media-card.js';
 import { getDb, nowIso } from './db.js';
 import { AGENTS_DIR, REPORTS_DIR, ensureDirs, relToRoot } from './paths.js';
 import { executeRegistryTool, getEnabledToolSchemasForAgent } from './tools/registry.js';
@@ -14,6 +15,7 @@ import { markRunActive, clearRunActive } from './active-runs.js';
 import {
   addTaskComment,
   appendAgentRunEvent,
+  createTask,
   createTaskRun,
   getAgentRun,
   getTask,
@@ -24,6 +26,29 @@ import {
   upsertAgentRuntimeState,
 } from './delegation.js';
 
+const TOOL_SMITH_AGENT_ID = 'tool-smith-agent';
+
+// A specialist sub-agent that cannot finish because a tool/capability is
+// missing emits this fenced block as its FINAL output instead of guessing or
+// fabricating. runAgentTick parses it, files a Tool Smith build task on the
+// agent's behalf (request_capability is orchestrator-only — sub-agents get no
+// new privilege), and ends the run blocked. Keeps the route→build→delegate
+// loop closed from the specialist side.
+const ESCALATE_RE = /```madarx-escalate\s*([\s\S]*?)```/i;
+
+function parseEscalation(output) {
+  const m = ESCALATE_RE.exec(String(output || ''));
+  if (!m) return null;
+  try {
+    const parsed = JSON.parse(m[1].trim());
+    const capability = String(parsed.capability || parsed.capability_description || '').trim();
+    if (!capability) return null;
+    return { capability, reason: String(parsed.reason || '').trim() };
+  } catch {
+    return null;
+  }
+}
+
 function parseJson(value, fallback) {
   if (!value) return fallback;
   try { return JSON.parse(value); } catch { return fallback; }
@@ -226,14 +251,28 @@ function readSkills(agentId) {
   try { return fs.readFileSync(file, 'utf8').trim(); } catch { return ''; }
 }
 
-async function generateTickOutput({ agent, systemPrompt, userMessage, onToolStart, onToolResult, onToolError, acting_on_behalf_of_user_id, heartbeat_task_id }) {
+async function generateTickOutput({ agent, systemPrompt, userMessage, onToolStart, onToolResult, onToolError, acting_on_behalf_of_user_id, heartbeat_task_id, pending_approvals = [] }) {
   if (process.env.MADARX_MOCK_CLAUDE_TICK) {
-    return { output: process.env.MADARX_MOCK_CLAUDE_TICK, toolEvents: [] };
+    return { output: process.env.MADARX_MOCK_CLAUDE_TICK, toolEvents: [], created_approvals: [] };
   }
   const maxTokens = Math.max(256, Math.min(8192, Number(process.env.MAX_TOKENS_PER_TICK || 1024) || 1024));
   const tools = getEnabledToolSchemasForAgent(agent.id);
   const messages = [{ role: 'user', content: userMessage }];
   const toolEvents = [];
+  // Approvals the owner already granted (inline in chat), to inject into the
+  // matching tool call so the gate consumes them instead of re-prompting. One-shot
+  // per (tool_name) — mirrors the main agent's injectPendingApproval.
+  const grants = (Array.isArray(pending_approvals) ? pending_approvals : [])
+    .filter((p) => p && typeof p.approval_id === 'string' && typeof p.tool_name === 'string')
+    .map((p) => ({ approval_id: p.approval_id, tool_name: p.tool_name, used: false }));
+  function injectGrant(toolName, input) {
+    const g = grants.find((x) => !x.used && x.tool_name === toolName);
+    if (!g) return input;
+    g.used = true;
+    return { ...(input || {}), approval_id: g.approval_id };
+  }
+  // Approvals this tick newly created (tool paused awaiting owner authorization).
+  const created_approvals = [];
   let finalText = '';
 
   for (let turn = 0; turn < 4; turn += 1) {
@@ -257,7 +296,7 @@ async function generateTickOutput({ agent, systemPrompt, userMessage, onToolStar
       });
       await onToolStart?.({ toolUse, inputSummary });
       try {
-        const result = await executeRegistryTool(toolUse.name, toolUse.input || {}, {
+        const result = await executeRegistryTool(toolUse.name, injectGrant(toolUse.name, toolUse.input || {}), {
           agent_id: agent.id,
           // Gate 0: thread service-principal identity for RD-1 membership check.
           acting_on_behalf_of_user_id: acting_on_behalf_of_user_id || null,
@@ -265,6 +304,13 @@ async function generateTickOutput({ agent, systemPrompt, userMessage, onToolStar
         });
         event.status = result?.status || 'complete';
         event.result = result;
+        if (result?.status === 'approval_required' && result?.approval_request_id) {
+          created_approvals.push({
+            approval_request_id: result.approval_request_id,
+            tool_name: toolUse.name,
+            summary: result.reason || `Approval required for ${toolUse.name}`,
+          });
+        }
         toolResults.push({
           type: 'tool_result',
           tool_use_id: toolUse.id,
@@ -304,6 +350,7 @@ async function generateTickOutput({ agent, systemPrompt, userMessage, onToolStar
   return {
     output: finalText,
     toolEvents,
+    created_approvals,
     engine: 'anthropic',
     model: agent.model || defaultModelForEngine('anthropic'),
   };
@@ -345,6 +392,10 @@ export async function runAgentTick(agentOrId, {
   // expected_output for THIS run only — never persisted onto the agent row.
   instruction = null,
   expected_output = null,
+  // Owner-granted approvals to inject into matching tool calls this tick, so an
+  // inline-approved sub-agent tool resumes instead of re-prompting. Shape:
+  // [{ approval_id, tool_name }].
+  pending_approvals = [],
   // Service-principal propagation (Task #7 / Gate 0):
   // Identity of the user on whose behalf this tick is running.
   // Passed from heartbeat-worker.js → executeRegistryTool context so Gate 0
@@ -397,7 +448,13 @@ export async function runAgentTick(agentOrId, {
   const systemPrompt = `${baseSystemPrompt.includes('CURRENT_DATE') ? baseSystemPrompt : `${currentDateInstruction()}\n\n${baseSystemPrompt}`}
 
 ${skills ? `<skills>\n${skills}\n</skills>\n` : ''}
-You are running as a scheduled cron tick. Your FINAL message is saved verbatim as the deliverable the owner sees — make it the complete result in clean markdown, not a status summary, progress recap, or "what I did" note. Reproduce the full content in your final message even if a prior version already exists on disk.`;
+You are running as a scheduled cron tick. Your FINAL message is saved verbatim as the deliverable the owner sees — make it the complete result in clean markdown, not a status summary, progress recap, or "what I did" note. Reproduce the full content in your final message even if a prior version already exists on disk.
+
+ESCALATION_PROTOCOL (non-negotiable): if you CANNOT fully achieve the goal because you are missing a tool or capability (a tool you need is not in your toolset, or returns "not permitted"), do NOT guess, fabricate, or deliver a half-answer. Instead make your FINAL message exactly one fenced block:
+\`\`\`madarx-escalate
+{"capability":"<plain-language capability you need, e.g. create pages in Notion>","reason":"<what you were blocked on>"}
+\`\`\`
+madarX will route this to Tool Smith to build the capability and grant it to you, then re-run you. Use this only for a genuine missing capability — not for a transient error you can retry.`;
 
   // Work-unit contract resolved by precedence (see resolveRunContract):
   //   per-call override  →  delegated task  →  agent standing contract  →  default.
@@ -426,7 +483,7 @@ Tools: ${parseJson(agent.tools, []).join(', ') || 'none listed'}
 ${lastMemory.length ? lastMemory.map((entry, index) => `${index + 1}. ${entry}`).join('\n') : 'No prior memory.'}
 </recent_memory>`;
 
-  const { output, toolEvents, engine, model } = (process.env.MADARX_MOCK_AGENT_TICK || process.env.MADARX_MOCK_CLAUDE_TICK)
+  const { output, toolEvents, engine, model, created_approvals = [] } = (process.env.MADARX_MOCK_AGENT_TICK || process.env.MADARX_MOCK_CLAUDE_TICK)
     ? {
         output: process.env.MADARX_MOCK_AGENT_TICK || process.env.MADARX_MOCK_CLAUDE_TICK,
         toolEvents: [],
@@ -440,6 +497,7 @@ ${lastMemory.length ? lastMemory.map((entry, index) => `${index + 1}. ${entry}`)
           userMessage,
           acting_on_behalf_of_user_id,
           heartbeat_task_id,
+          pending_approvals,
           onToolStart: ({ toolUse, inputSummary }) => {
             if (!taskRun) return;
             appendAgentRunEvent(taskRun.id, {
@@ -503,6 +561,79 @@ ${lastMemory.length ? lastMemory.map((entry, index) => `${index + 1}. ${entry}`)
     e.code = 'fabricated_tool_output';
     throw e;
   }
+
+  // Capability escalation: the specialist signalled it is missing a tool. File a
+  // Tool Smith build task on its behalf and end this run blocked — never persist
+  // a half-answer. request_capability stays orchestrator-only; this is the
+  // sub-agent's sanctioned, no-new-privilege path into the same loop.
+  const escalation = parseEscalation(output);
+  if (escalation) {
+    let toolSmithTaskId = null;
+    try {
+      const task = createTask({
+        title: `Build capability: ${escalation.capability.slice(0, 80)}`,
+        description: [
+          `Specialist "${agent.name}" (${agent.id}) is blocked — it needs a capability that does not exist yet:`,
+          `  "${escalation.capability}"`,
+          escalation.reason ? `\nBlocked on: ${escalation.reason}` : '',
+          '',
+          'Author the right path (composite tool / REST connector / skill / propose_tool) and grant it to the requester.',
+          `Grant the result to agent: ${agent.id}.`,
+        ].join('\n'),
+        acceptance_criteria: 'Capability authored and granted to the requesting specialist so its goal can be completed on re-run.',
+        assignee_agent_id: TOOL_SMITH_AGENT_ID,
+        created_by_agent_id: agent.id,
+        priority: 'high',
+        project_id: agent.project_id || null,
+      });
+      toolSmithTaskId = task.id;
+    } catch (err) {
+      if (process.env.MADARX_DEBUG) console.error('[agent-runner] escalation task creation failed:', err?.message || err);
+    }
+    const blockedMsg = `Blocked: missing capability "${escalation.capability}". Routed to Tool Smith${toolSmithTaskId ? ` (task ${toolSmithTaskId})` : ''} to build and grant it; this agent will re-run once available.`;
+    const { recordRun, appendAudit } = await import('./runtime.js');
+    recordRun({
+      kind: 'agent-tick',
+      title: `${agent.name} escalated a missing capability`,
+      agent: agent.name,
+      agent_id: agent.id,
+      status: 'blocked',
+      preview: blockedMsg,
+      output: blockedMsg,
+      triggered_by,
+    });
+    appendAudit({
+      type: 'agent.capability.escalated',
+      summary: `${agent.name} escalated missing capability: ${escalation.capability}`,
+      status: 'blocked',
+      meta: { agent_id: agent.id, tool_smith_task_id: toolSmithTaskId, capability: escalation.capability, triggered_by },
+    });
+    if (taskRun) {
+      try {
+        addTaskComment(task_id, { body: blockedMsg, author_agent_id: agent.id, created_by_run_id: taskRun.id });
+        updateTask(task_id, { status: 'blocked', blocked_reason: blockedMsg, actor_type: 'agent', actor_id: agent.id });
+        markAgentRunFinished(taskRun.id, { status: 'failed', error: blockedMsg });
+      } catch { /* best-effort */ }
+    }
+    publishLiveEvent({
+      type: 'agent_run_complete',
+      agent_id: agent.id,
+      agent_name: agent.name,
+      status: 'blocked',
+      triggered_by,
+      run_id: taskRun?.id || null,
+      task_id,
+    });
+    return {
+      id: taskRun?.id || null,
+      status: 'blocked',
+      escalated: true,
+      tool_smith_task_id: toolSmithTaskId,
+      capability: escalation.capability,
+      preview: blockedMsg,
+    };
+  }
+
   const reportOutput = toolEvents.length
     ? `${output}\n\n## Tool events\n${toolEvents.map(event => `- ${event.name}: ${event.status}`).join('\n')}`
     : output;
@@ -514,9 +645,32 @@ ${lastMemory.length ? lastMemory.map((entry, index) => `${index + 1}. ${entry}`)
   fs.writeFileSync(file, deliverableMd, 'utf8');
   const filePath = relToRoot(file);
 
-  const artifactTitle = `${agent.name} scheduled report`;
+  // If the run generated visual media (Higgsfield image/video tools), make the
+  // artifact SHOW the media directly on the canvas — an embedded gallery with the
+  // markdown report tucked into a collapsible "Design spec" block — instead of a
+  // document that only links to the image URL.
+  const mediaItems = toolEvents
+    .filter((e) => typeof e.name === 'string' && e.name.startsWith('higgsfield_') && e.result?.ok && e.result?.url)
+    .map((e) => ({
+      url: e.result.url,
+      kind: e.name === 'higgsfield_generate_video' ? 'video' : 'image',
+      thumbnail: e.result.thumbnail || null,
+      prompt: e.input?.prompt || '',
+    }));
+
   const cleanMd = stripEmoji(deliverableMd);
-  const renderedHtml = renderDocumentHtml({ title: artifactTitle, markdown: cleanMd });
+  const artifactTitle = mediaItems.length
+    ? `${agent.name} — ${mediaItems[0].kind === 'video' ? 'video' : 'image'}`
+    : `${agent.name} scheduled report`;
+  // Media runs render an embedded gallery (image shown directly on canvas); the
+  // markdown spec is preserved as source_md for download. Both are kind:'document'
+  // so the canvas renders the HTML content in an iframe.
+  const renderedHtml = mediaItems.length
+    ? buildHiggsfieldGalleryHtml(mediaItems, {
+        title: artifactTitle,
+        caption: mediaItems[0].prompt || '',
+      })
+    : renderDocumentHtml({ title: artifactTitle, markdown: cleanMd });
 
   const { recordRun, recordArtifact, appendAudit } = await import('./runtime.js');
   const run = recordRun({
@@ -609,6 +763,37 @@ ${lastMemory.length ? lastMemory.map((entry, index) => `${index + 1}. ${entry}`)
     });
   }
 
+  // If this tick paused on an owner-approval gate, persist enough context on the
+  // approval row to re-dispatch this exact delegation when the owner approves it
+  // inline in chat — and surface the first pending approval to the caller so the
+  // orchestrator can render an inline Approve/Deny card.
+  if (Array.isArray(created_approvals) && created_approvals.length) {
+    const resume = {
+      agent_id: agent.id,
+      agent_name: agent.name,
+      instruction: instruction || null,
+      expected_output: expected_output || null,
+      triggered_by,
+    };
+    for (const ca of created_approvals) {
+      try {
+        const cur = db.prepare('SELECT payload FROM approval_requests WHERE id = ?').get(ca.approval_request_id);
+        const payload = cur?.payload ? parseJson(cur.payload, {}) : {};
+        payload.resume = resume;
+        db.prepare('UPDATE approval_requests SET payload = ? WHERE id = ?')
+          .run(JSON.stringify(payload), ca.approval_request_id);
+      } catch { /* best-effort — resume falls back to main-agent re-delegation */ }
+    }
+    const first = created_approvals[0];
+    run.pending_approval = {
+      approval_id: first.approval_request_id,
+      tool_name: first.tool_name,
+      summary: first.summary,
+      agent_id: agent.id,
+      agent_name: agent.name,
+    };
+  }
+
   return run;
   } catch (err) {
     const message = (err?.message || String(err)).slice(0, 1000);

package/lib/agent-templates.js

@@ -8,6 +8,7 @@ import { PROCESS_AGENT_TEMPLATES } from './process/seeds/agent-templates.js';
 export const AGENT_TEMPLATES = [
   ['project-watcher','Project Watcher','project_watcher','claude-code',['gh_repo_read','gh_issue_list','gh_pr_list','web_fetch','file_read'],['investigate','retro'],'Watches repos, issues, PRs, deploys, and produces weekly project pulses.'],
   ['personal-assistant','Personal Assistant','personal_assistant','anthropic',['gmail_messages_list','gmail_message_read','calendar_events_list','whatsapp_send'],[], 'Reads inbox and calendar context, drafts replies, and keeps the operator organized.'],
+  ['travel-concierge','Travel Concierge','travel_concierge','anthropic',['flight_search','flight_status','hotel_search','hotel_rates','web_search','web_fetch','create_artifact'],[], 'Plans trips end to end — flights, hotels, and itineraries — and returns a booking-ready comparison with real prices, times, and sources. Bookings and purchases stay approval-gated.'],
   ['engineering-lead','Engineering Lead','engineering_lead','claude-code',['gh_repo_read','gh_issue_list','gh_pr_list','terminal_run','file_read','file_write'],['investigate','review','ship','qa'],'Leads implementation, review, QA, and preview deploys with explicit approval gates.'],
   ['marketing-lead','Marketing Lead','marketing_lead','anthropic',['web_search','web_fetch','file_write','create_artifact'],['design-shotgun','impeccable'],'Creates market research, launch copy, positioning, and design briefs.'],
   ['meeting-notes','Meeting Notes Taker','meeting_notes','anthropic',['transcribe_audio','file_write','create_artifact'],[], 'Turns recordings into transcripts, decisions, action items, and follow-ups.'],

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/connection-seeds.js

@@ -523,6 +523,50 @@ const CONNECTION_SEEDS = [
     risk: 'CRM writes (contact/deal upsert) require approval.',
     tags: ['sales', 'crm', 'hubspot', 'oauth'],
   }),
+  {
+    slug: 'higgsfield',
+    title: 'Higgsfield AI',
+    description: 'Generate images and videos via Higgsfield AI. Pair once with your API key/secret to unlock the generation tools.',
+    category: 'integration',
+    author: 'madarx',
+    source_kind: 'builtin',
+    source_url: 'https://cloud.higgsfield.ai/',
+    version: null,
+    risk_summary: 'Generation spends paid Higgsfield credits; both tools stay approval-gated by default.',
+    tags: ['integration', 'media', 'image-generation', 'video-generation', 'higgsfield'],
+    manifest: {
+      service_key: 'higgsfield',
+      setup_kind: 'api_key',
+      benefit: 'Unlock higgsfield_generate_image and higgsfield_generate_video.',
+      credentials: [
+        {
+          name: 'HIGGSFIELD_KEY_ID',
+          label: 'API key ID',
+          type: 'password',
+          placeholder: 'key id',
+          help_url: 'https://cloud.higgsfield.ai/',
+          help_text: 'From your Higgsfield dashboard → API section. Create a key, then copy its ID.',
+          required: true,
+        },
+        {
+          name: 'HIGGSFIELD_KEY_SECRET',
+          label: 'API key secret',
+          type: 'password',
+          placeholder: 'key secret',
+          help_url: 'https://cloud.higgsfield.ai/',
+          help_text: 'The matching secret for the key ID. Stored encrypted in the local vault — never echoed back.',
+          required: true,
+        },
+      ],
+      verify_endpoint: '/api/connections/higgsfield/verify',
+      verify_supported: true,
+      deep_link: null,
+      supports_scopes: ['global', 'project', 'agent'],
+      unlocks_tool_slugs: ['higgsfield_generate_image', 'higgsfield_product_photoshoot', 'higgsfield_generate_video'],
+      engines: [],
+      logo_glyph: 'higgsfield',
+    },
+  },
 ];
 
 function upsertConnection(db, seed) {

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' });