madarx 2.12.0 → 2.13.0

package/lib/cli/banner.js

@@ -12,16 +12,22 @@
 
 // ── palette ────────────────────────────────────────────────────────────────
 const PALETTE = {
-  mars:   [0xc2, 0x45, 0x2a], // brand primary
+  mars:   [0xc2, 0x45, 0x2a], // brand primary / THE accent
   marsHi: [0xde, 0x6a, 0x53], // lighter mars (top of gradient)
   marsLo: [0x7c, 0x2b, 0x19], // dark mars (bottom of gradient)
   gold:   [0xd4, 0xb7, 0x7f],
   sand:   [0xf6, 0xf3, 0xed],
   ink:    [0x68, 0x70, 0x7b], // "muted" — used for secondary text
   green:  [0x4c, 0xae, 0x6a],
+  // ── Sovereign-Mono palette (brand-guidelines v1.3) — used by the splash ──
+  onyx:     [0x0F, 0x0F, 0x11], // ground / black letter fill
+  platinum: [0xE8, 0xE8, 0xE5], // mark / wordmark / "done" ✓
+  bone:     [0xDC, 0xDC, 0xD8], // body labels
+  graphite: [0x4A, 0x4A, 0x4D], // rules, borders, pending ·
+  muted:    [0x8A, 0x82, 0x78], // datelines, subtitle, secondary
 };
 
-function colorEnabled() {
+export function colorEnabled() {
   if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0') return true;
   if (process.env.NO_COLOR) return false;
   return Boolean(process.stdout && process.stdout.isTTY);
@@ -29,32 +35,49 @@ function colorEnabled() {
 
 const ON = colorEnabled();
 
-function fg([r, g, b], s) {
+export function fg([r, g, b], s) {
   if (!ON) return s;
   return `\x1b[38;2;${r};${g};${b}m${s}\x1b[0m`;
 }
-function bold(s) { return ON ? `\x1b[1m${s}\x1b[0m` : s; }
-function dim(s) { return ON ? `\x1b[2m${s}\x1b[0m` : s; }
+export function bold(s) { return ON ? `\x1b[1m${s}\x1b[0m` : s; }
+export function dim(s) { return ON ? `\x1b[2m${s}\x1b[0m` : s; }
 
-// ── wordmark ─────────────────────────────────────────────────────────────────
-// 5-row block alphabet, just the glyphs we need for "MADARX".
-const GLYPHS = {
-  M: ['█   █', '██ ██', '█ █ █', '█   █', '█   █'],
-  A: [' ███ ', '█   █', '█████', '█   █', '█   █'],
-  D: ['████ ', '█   █', '█   █', '█   █', '████ '],
-  R: ['████ ', '█   █', '████ ', '█  █ ', '█   █'],
-  X: ['█   █', ' █ █ ', '  █  ', ' █ █ ', '█   █'],
-};
+/** Visible (printable) length of a string, ignoring ANSI escape sequences. */
+export function visibleLength(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s).replace(/\x1b\[[0-9;]*m/g, '').length;
+}
 
-const ROW_TINT = [PALETTE.marsHi, PALETTE.mars, PALETTE.mars, PALETTE.marsLo, PALETTE.marsLo];
+// ── wordmark ─────────────────────────────────────────────────────────────────
+// Embedded figlet "Standard" font art for "madar" + "X", captured offline so the
+// banner stays dependency-free (no figlet at runtime). "madar" renders in Sand,
+// the "X" in Mars — the single brand accent (the X is a permanent constant, so
+// it never counts against the one-Mars-per-surface rule).
+const FIG_MADAR = [
+  '                      _            ',
+  '  _ __ ___   __ _  __| | __ _ _ __ ',
+  " | '_ ` _ \\ / _` |/ _` |/ _` | '__|",
+  ' | | | | | | (_| | (_| | (_| | |   ',
+  ' |_| |_| |_|\\__,_|\\__,_|\\__,_|_|   ',
+  '                                   ',
+];
+const FIG_X = [
+  ' __  __',
+  ' \\ \\/ /',
+  '  \\  / ',
+  '  /  \\ ',
+  ' /_/\\_\\',
+  '       ',
+];
 
-/** The MADARX wordmark as a colored, multi-line string. */
-function wordmark() {
-  const word = 'MADARX'.split('');
+/** The "madarX" wordmark as a colored, multi-line string. */
+export function wordmark() {
+  const rows = Math.max(FIG_MADAR.length, FIG_X.length);
   const lines = [];
-  for (let row = 0; row < 5; row++) {
-    const segs = word.map((ch) => GLYPHS[ch][row]).join('  ');
-    lines.push(fg(ROW_TINT[row], segs));
+  for (let i = 0; i < rows; i++) {
+    const l = FIG_MADAR[i] ?? '';
+    const r = FIG_X[i] ?? '';
+    lines.push(fg(PALETTE.platinum, l) + fg(PALETTE.mars, r));
   }
   return lines.join('\n');
 }
@@ -145,4 +168,160 @@ export function renderHeader(title = 'setup', version) {
   return out.join('\n');
 }
 
+// ── hero banner (Hermes-style: 3D wordmark + orbit mark + grouped catalog) ────
+
+/**
+ * Hero wordmark — identical to the install splash: the lowercase Standard
+ * "madar" (FIG_MADAR, Platinum) beside the Standard "X" (FIG_X, Mars).
+ * Returns an array of lines so the hero can indent/compose them.
+ */
+function heroWordmark() {
+  return wordmark().split('\n');
+}
+
+// Orbit mark — "madar" (مدار) is Arabic for orbit. Graphite ring, Mars core + bead.
+const ORBIT = [
+  '   ╭───────╮ ● ',
+  ' ╭─╯       ╰─╮ ',
+  '│     ╲ ╱     │',
+  '│      ╳      │',
+  '│     ╱ ╲     │',
+  ' ╰─╮       ╭─╯ ',
+  '   ╰───────╯   ',
+];
+function orbitMark() {
+  return ORBIT.map((line) => {
+    let out = '';
+    for (const ch of line) {
+      if (ch === ' ') out += ' ';
+      else if (ch === '╳' || ch === '╲' || ch === '╱' || ch === '●') out += fg(PALETTE.mars, ch);
+      else out += fg(PALETTE.graphite, ch);
+    }
+    return out;
+  });
+}
+
+/** Truncate raw (uncolored) text to a visible width with an ellipsis. */
+function clip(s, width) {
+  if (s.length <= width) return s;
+  return s.slice(0, Math.max(0, width - 1)) + '…';
+}
+
+/**
+ * Hermes-style hero banner: a big 3D MADARX wordmark, a titled rule, then a
+ * two-column body — orbit mark + runtime meta on the left, a grouped capability
+ * catalog (tools by category, then skills) on the right.
+ *
+ * Dependency-free and DB-free: all inputs are passed in by the caller (the CLI
+ * supervisor), so importing this never opens the database.
+ *
+ * @param {object} info
+ * @param {string}  info.version
+ * @param {string} [info.home]      data home path
+ * @param {string} [info.url]       dashboard URL
+ * @param {string} [info.engine]    default sub-agent engine
+ * @param {string} [info.commit]    short git hash (optional)
+ * @param {string} [info.session]   session id (optional)
+ * @param {Array<{category:string,count:number,names:string[]}>} [info.toolCats]
+ * @param {number} [info.toolCount]
+ * @param {Array<{category:string,count:number,names:string[]}>} [info.skillGroups]
+ * @param {number} [info.skillCount]
+ * @param {boolean}[info.behind]
+ * @param {string} [info.latest]
+ * @returns {string}
+ */
+export function renderHeroBanner(info = {}) {
+  const {
+    version = '0.0.0', home, url,
+    commit, session, toolCats = [], toolCount, skillGroups = [], skillCount,
+    behind = false, latest,
+  } = info;
+
+  const cols = (process.stdout && process.stdout.columns) || 84;
+  const out = [''];
+
+  // 1) 3D wordmark.
+  for (const l of heroWordmark()) out.push('  ' + l);
+  out.push('');
+
+  // 2) Titled rule: ── madarX OS v… · date · commit ─────────
+  const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, '.');
+  const title = `${bold(fg(PALETTE.platinum, 'madar'))}${bold(fg(PALETTE.mars, 'X'))}${bold(fg(PALETTE.platinum, ' OS'))}`
+    + ` ${fg(PALETTE.mars, 'v' + version)}`
+    + fg(PALETTE.muted, `  ·  ${stamp}${commit ? '  ·  ' + commit : ''}`);
+  const titleVis = visibleLength(title);
+  const railLen = Math.max(3, cols - 4 - titleVis - 3);
+  out.push('  ' + fg(PALETTE.graphite, '── ') + title + ' ' + fg(PALETTE.graphite, '─'.repeat(railLen)));
+  out.push('');
+
+  // 3) Two columns. Left: orbit mark + meta. Right: catalog.
+  const left = orbitMark();
+  const leftMeta = [
+    '',
+    home ? '  ' + fg(PALETTE.muted, home.replace(process.env.HOME || '~', '~')) : '',
+    url ? '  ' + fg(PALETTE.muted, url) : '',
+    session ? '  ' + fg(PALETTE.muted, 'session ' + session) : '',
+  ].filter(Boolean);
+  const leftAll = [...left, ...leftMeta];
+  // Left column width = its widest line (orbit block or the longer meta lines
+  // like the dashboard URL / session id), so the right column never collides
+  // with the address/session under the logo.
+  const LW = Math.max(...leftAll.map(visibleLength));
+  const GAP = 6; // breathing room between the two columns
+
+  const right = [];
+  const rw = Math.max(28, cols - LW - GAP - 2);
+  // One "label: a, b, c…" row, clipped to the right column.
+  const groupLine = (label, names) => {
+    const body = clip(names.join(', '), rw - label.length - 2);
+    return `${fg(PALETTE.bone, label + ':')} ${fg(PALETTE.muted, body)}`;
+  };
+
+  right.push(fg(PALETTE.mars, bold('Available Tools')) + fg(PALETTE.muted, toolCount ? `  ${toolCount}` : ''));
+  // Feature the toolsets a business agent actually reaches for, in priority
+  // order — not raw count. Domain/installable packs (mines, travel,
+  // cli_generator, vercel, …) stay in the registry but fold into "more toolsets".
+  const FEATURED_TOOL_CATEGORIES = [
+    'web', 'email', 'calendar', 'local_machine', 'browser',
+    'supabase', 'workflow', 'authoring', 'github', 'voice',
+  ];
+  // Friendly display labels for the slugs that read like internals.
+  const TOOL_LABELS = {
+    local_machine: 'files', web: 'web', email: 'email', calendar: 'calendar',
+    browser: 'browser', supabase: 'data', workflow: 'automations',
+    authoring: 'build-tools', github: 'github', voice: 'voice',
+  };
+  const byName = new Map(toolCats.map((c) => [c.category, c]));
+  const featured = FEATURED_TOOL_CATEGORIES.map((n) => byName.get(n)).filter(Boolean);
+  const shownCats = featured.slice(0, 8);
+  for (const c of shownCats) right.push(groupLine(TOOL_LABELS[c.category] || c.category, c.names));
+  const moreCats = toolCats.length - shownCats.length;
+  if (moreCats > 0) right.push(fg(PALETTE.muted, `(and ${moreCats} more toolsets…)`));
+
+  right.push('');
+  right.push(fg(PALETTE.mars, bold('Available Skills')) + fg(PALETTE.muted, skillCount ? `  ${skillCount}` : ''));
+  // Business-default skills, grouped by category (research, comms, …).
+  for (const g of skillGroups) right.push(groupLine(g.category, g.names));
+
+  // Zip columns.
+  const rows = Math.max(leftAll.length, right.length);
+  for (let i = 0; i < rows; i++) {
+    const l = leftAll[i] ?? '';
+    const r = right[i] ?? '';
+    const pad = ' '.repeat(Math.max(0, LW - visibleLength(l)));
+    out.push('  ' + (l || '') + pad + ' '.repeat(GAP) + r);
+  }
+
+  // 4) Update status footer + dateline.
+  out.push('');
+  if (behind && latest) {
+    out.push('  ' + fg(PALETTE.mars, '▲') + '  ' + fg(PALETTE.bone, `v${latest} available`) + fg(PALETTE.muted, '  — run ') + fg(PALETTE.mars, 'madarx update'));
+  } else {
+    out.push('  ' + fg(PALETTE.muted, '●  up to date'));
+  }
+  out.push('  ' + fg(PALETTE.muted, `${stamp}  ·  Designed in UAE  ·  v${version}`));
+  out.push('');
+  return out.join('\n');
+}
+
 export const _palette = PALETTE;

package/lib/cli/run.js

@@ -17,7 +17,8 @@ import fs from 'node:fs';
 import { spawn } from 'node:child_process';
 import { applyHomeEnv } from './home.js';
 import { PKG_ROOT } from './dispatch.js';
-import { renderBanner } from './banner.js';
+import { renderBanner, renderHeroBanner } from './banner.js';
+import { readyPanel } from './splash.js';
 import { readUpdateCheck } from '../update-check.js';
 import { loadProjectEnv } from '../load-env.js';
 
@@ -157,25 +158,39 @@ export async function run({ flags = {} } = {}) {
     // Catalog counts: best-effort dynamic import so a count never blocks or
     // breaks boot. These modules build static catalogs at eval time and do NOT
     // open the database, so the supervisor stays DB-free.
-    let tools, skills;
+    let toolCats = [];
+    let toolCount;
+    let skillGroups = [];
+    let skillCount;
     try {
-      const [{ MARKETPLACE_TOOL_COUNT }, seeds] = await Promise.all([
+      const [{ MARKETPLACE_TOOL_COUNT, listToolCategories }, seeds] = await Promise.all([
         import('../tools/registry.js'),
         import('../marketplace-seeds.js'),
       ]);
-      tools = MARKETPLACE_TOOL_COUNT;
-      skills = (seeds.PHASE1_SKILL_SLUGS?.length || 0) + (seeds.OPEN_DESIGN_SKILL_SLUGS?.length || 0);
-    } catch { /* counts are optional */ }
+      toolCount = MARKETPLACE_TOOL_COUNT;
+      toolCats = listToolCategories();
+      // Showcase the business-default skill pack (research, comms, documents,
+      // data, web) grouped by category — what most teams need out of the box.
+      skillGroups = seeds.listDefaultSkillGroups ? seeds.listDefaultSkillGroups() : [];
+      skillCount = (seeds.DEFAULT_SKILL_SLUGS || []).length;
+    } catch { /* catalog is optional — banner still renders without it */ }
     const version = pkgVersion() || '0.0.0';
-    console.log(renderBanner({
+    const hero = process.env.MADARX_BANNER_LEGACY !== '1';
+    const render = hero ? renderHeroBanner : renderBanner;
+    console.log(render({
       version,
       home: layout.home,
       url: BASE_URL,
-      engine: process.env.MADARX_DEFAULT_ENGINE || 'claude-code (default)',
+      engine: process.env.MADARX_DEFAULT_ENGINE || 'claude-code',
+      commit: process.env.MADARX_COMMIT || undefined,
       latest: ledger?.latest || null,
       behind: Boolean(ledger?.latest && ledger.latest !== version && ledger?.behind),
-      tools,
-      skills,
+      toolCats,
+      toolCount,
+      skillGroups,
+      skillCount,
+      // legacy renderBanner still understands these:
+      tools: toolCount,
     }));
   } else {
     log(`data home: ${layout.home}`);
@@ -213,7 +228,14 @@ export async function run({ flags = {} } = {}) {
     // Health gate + browser open run alongside; never block shutdown on them.
     waitForHealth().then((ok) => {
       if (stopping) return;
-      if (ok) { log(`ready → ${BASE_URL}`); openBrowser(BASE_URL, flags); }
+      if (ok) {
+        if (!flags.quiet && process.env.MADARX_NO_BANNER !== '1') {
+          console.log('\n' + readyPanel({ version: pkgVersion() || undefined, url: BASE_URL }) + '\n');
+        } else {
+          log(`ready → ${BASE_URL}`);
+        }
+        openBrowser(BASE_URL, flags);
+      }
       else warn(`web tier did not answer on ${BASE_URL} within the timeout — it may still be starting.`);
     });
   });

package/lib/cli/splash.js

@@ -0,0 +1,120 @@
+/**
+ * Branded boot/install splash for the madarX OS CLI.
+ *
+ * Zero dependencies — node builtins + the ANSI primitives in ./banner.js only —
+ * so it is safe to import from the CLI supervisor (lib/cli/run.js) and from the
+ * postinstall script (scripts/postinstall-splash.mjs) without pulling in the
+ * runtime or opening the database.
+ *
+ * Look is the brand-guidelines v1.3 "Sovereign-Mono" splash (see preview.svg):
+ * the whole step list prints upfront — pending in Graphite, the active step
+ * carries the single live Mars spinner, settled steps resolve to a neutral
+ * Platinum ✓ (never green, so Mars never repeats on a settled surface). Closes
+ * on a Muted dateline. Degrades to a plain auditable record off-TTY.
+ */
+
+import { _palette as P, fg, bold, dim, wordmark, colorEnabled, visibleLength } from './banner.js';
+
+const ON = colorEnabled();
+const isTTY = ON && Boolean(process.stdout && process.stdout.isTTY);
+
+// Monospace-safe braille spinner — reads as motion without noise.
+const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const GLYPH = {
+  done: fg(P.platinum, '✓'),
+  fail: fg(P.mars, '✗'),
+  pending: fg(P.graphite, '·'),
+  bead: fg(P.mars, '●'),
+};
+
+// ── cursor hygiene: hide during animation, always restore ─────────────────────
+let cursorHidden = false;
+function hideCursor() { if (isTTY && !cursorHidden) { process.stdout.write('\x1b[?25l'); cursorHidden = true; } }
+function showCursor() { if (cursorHidden) { process.stdout.write('\x1b[?25h'); cursorHidden = false; } }
+process.on('exit', showCursor);
+process.on('SIGINT', () => { showCursor(); process.exit(130); });
+
+// A step line at a given state. `state`: 'pending' | 'active' | 'done' | 'fail'.
+function lineFor(label, state, frame) {
+  if (state === 'pending') return `  ${GLYPH.pending} ${fg(P.graphite, label)}`;
+  if (state === 'active') return `  ${fg(P.mars, frame)} ${fg(P.bone, label)}`;
+  if (state === 'fail') return `  ${GLYPH.fail} ${fg(P.bone, label)}`;
+  return `  ${GLYPH.done} ${fg(P.bone, label)}`;
+}
+
+/**
+ * Run a list of boot steps, rendered the way preview.svg shows them: the whole
+ * list appears at once (pending/Graphite), then each step lights its Mars
+ * spinner while its real work runs and resolves to a Platinum ✓.
+ *
+ * @param {Array<{label: string, work: () => Promise<any>}>} steps
+ */
+export async function bootSequence(steps) {
+  if (!isTTY) {
+    // CI / piped / NO_COLOR: no animation, just the record an auditor would want.
+    for (const s of steps) {
+      try { await s.work(); process.stdout.write(lineFor(s.label, 'done') + '\n'); }
+      catch { process.stdout.write(lineFor(s.label, 'fail') + '\n'); }
+    }
+    return;
+  }
+
+  const n = steps.length;
+  hideCursor();
+  try {
+    // Paint the full list pending, then park the cursor below it.
+    for (const s of steps) process.stdout.write(lineFor(s.label, 'pending') + '\n');
+
+    // Redraw line `i` (0 = top) in place: jump up, clear, write, jump back down.
+    const redraw = (i, text) => {
+      const up = n - i;
+      process.stdout.write(`\x1b[${up}A\r\x1b[2K${text}\r\x1b[${up}B`);
+    };
+
+    for (let i = 0; i < n; i++) {
+      const s = steps[i];
+      let spinning = true, f = 0;
+      const anim = (async () => {
+        while (spinning) { redraw(i, lineFor(s.label, 'active', SPINNER[f++ % SPINNER.length])); await sleep(80); }
+      })();
+      try { await s.work(); spinning = false; await anim; redraw(i, lineFor(s.label, 'done')); }
+      catch { spinning = false; await anim; redraw(i, lineFor(s.label, 'fail')); }
+    }
+  } finally {
+    showCursor();
+  }
+}
+
+/** The dateline rule: a Muted mono `date · place · version` stamp. */
+export function dateline(version, place = 'Designed in UAE') {
+  const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, '.');
+  const v = version ? `  ·  v${version}` : '';
+  return fg(P.muted, `${stamp}  ·  ${place}${v}`);
+}
+
+// ── optional framed panel (used by `madarx run` ready-state, not the splash) ──
+
+/** A framed panel. Graphite border; a single Mars bead leads the headline. */
+export function readyBox(lines) {
+  const pad = 2;
+  const inner = Math.max(...lines.map(visibleLength)) + pad * 2;
+  const top = fg(P.graphite, '╭' + '─'.repeat(inner) + '╮');
+  const bot = fg(P.graphite, '╰' + '─'.repeat(inner) + '╯');
+  const bar = fg(P.graphite, '│');
+  const body = lines.map((l) => {
+    const gap = inner - visibleLength(l) - pad * 2;
+    return `${bar}${' '.repeat(pad)}${l}${' '.repeat(pad + gap)}${bar}`;
+  });
+  return ['  ' + top, ...body.map((b) => '  ' + b), '  ' + bot].join('\n');
+}
+
+/** Standard "ready" panel for a booted instance (the `madarx run` close). */
+export function readyPanel({ version, url } = {}) {
+  const head = `${GLYPH.bead} ${bold(fg(P.platinum, 'madarX is ready'))}`;
+  const hint = `${fg(P.muted, 'run')} ${fg(P.mars, 'madarx')} ${fg(P.muted, '→ dashboard on')} ${fg(P.bone, url || 'http://127.0.0.1:8787')}`;
+  return [readyBox([head, hint]), '  ' + dateline(version)].join('\n');
+}
+
+export { GLYPH, isTTY as splashIsTTY };

package/lib/engine-capabilities.js

@@ -0,0 +1,92 @@
+// Engine capability model — which engines can actually run tools, and whether a
+// given agent's job depends on that.
+//
+// Two tiers:
+//   - GOVERNED tool loop: dispatches madarX registry tools through
+//     executeRegistryTool (gates, allowlists, audit). Today ONLY `anthropic`
+//     (generateTickOutput in lib/agent-runner.js).
+//   - REAL tool execution of SOME kind: the CLI agents (`claude-code`, `codex`)
+//     run their own native tool runtimes (WebSearch/WebFetch/Write/etc.) in a
+//     subprocess, so they do real work even though it isn't the governed madarX
+//     toolset.
+//
+// Engines with NEITHER (`ollama`, `hermes`) run a single-shot text completion
+// with NO tool dispatch at all. A Hermes/Nous-template instruct model "satisfies"
+// a tool task by role-playing the whole loop — emitting `<tool_call>` and an
+// invented `<tool_response>` in plain text. Saving that as a deliverable ships
+// fiction as a real result. This module is the single source of truth for the
+// capability check so the runner can fail loudly instead.
+
+import { normalizeAgentEngine } from './agent-engines.js';
+import { getEnabledToolSchemasForAgent } from './tools/registry.js';
+
+// Engines that run the GOVERNED madarX tool loop end-to-end.
+const GOVERNED_TOOL_LOOP_ENGINES = new Set(['anthropic']);
+
+// Engines that execute tools for real in SOME form (governed loop OR a native
+// CLI tool runtime). Engines NOT in this set produce single-shot text only and
+// will fabricate a tool transcript when asked to use tools.
+const TOOL_EXECUTING_ENGINES = new Set(['anthropic', 'claude-code', 'codex']);
+
+/**
+ * True when the engine runs the governed madarX tool loop (dispatches registry
+ * tools through executeRegistryTool with gates/allowlists/audit).
+ */
+export function engineHasGovernedToolLoop(engine) {
+  return GOVERNED_TOOL_LOOP_ENGINES.has(normalizeAgentEngine(engine));
+}
+
+/**
+ * True when the engine can execute tools for real (governed loop or native CLI
+ * runtime). `ollama` / `hermes` return false — they only complete text.
+ */
+export function engineCanExecuteTools(engine) {
+  return TOOL_EXECUTING_ENGINES.has(normalizeAgentEngine(engine));
+}
+
+/**
+ * True when the agent has at least one enabled madarX tool — i.e. its work
+ * depends on tools actually running. An agent with zero enabled tools is a
+ * pure-reasoning/summarize job and runs fine single-shot on any engine.
+ */
+export function agentNeedsTools(agent) {
+  if (!agent?.id) return false;
+  try {
+    return getEnabledToolSchemasForAgent(agent.id).length > 0;
+  } catch {
+    // If we can't determine the toolset, do NOT over-block — treat as no tools.
+    return false;
+  }
+}
+
+/**
+ * Assert that `agent` can actually run its job on its selected engine. Throws a
+ * tagged error (`code = 'engine_cannot_run_tools'`) when the agent needs tools
+ * but the engine cannot execute any (`ollama` / `hermes`). The caller records
+ * this as a FAILED run with the remediation message rather than saving a
+ * fabricated transcript as a "complete" deliverable.
+ *
+ * CLI engines (`claude-code` / `codex`) pass this check — they run real tool
+ * runtimes — and rely on the fabricated-transcript detector (Layer B) as the
+ * backstop on the rare turn they role-play instead of dispatching.
+ *
+ * @returns {{ needsTools: boolean, engineCanExecuteTools: boolean }}
+ */
+export function assertRunnable(agent) {
+  const engine = normalizeAgentEngine(agent?.engine);
+  const canExecute = engineCanExecuteTools(engine);
+  const needsTools = agentNeedsTools(agent);
+
+  if (!needsTools || canExecute) {
+    return { needsTools, engineCanExecuteTools: canExecute };
+  }
+
+  const e = new Error(
+    `This agent has live tools enabled but its engine (${engine}) cannot run tools — it only completes text, ` +
+    `so it would fabricate a tool transcript instead of doing real work. The run was stopped. ` +
+    `Fix: switch this agent's engine to "Anthropic API" (governed tools) or "Claude Code" in its Details view.`
+  );
+  e.code = 'engine_cannot_run_tools';
+  e.engine = engine;
+  throw e;
+}

package/lib/fabricated-tool-output.js

@@ -0,0 +1,77 @@
+// Detector for FABRICATED tool-call transcripts.
+//
+// Some engines (Hermes/Nous-template instruct models on Ollama, and even the
+// Claude Code CLI when asked to "run an agent") role-play an entire tool loop in
+// PLAIN TEXT instead of dispatching real tools — emitting `<tool_call>` and a
+// hallucinated `<tool_response>` with invented results. Nothing actually runs.
+// If that text is saved verbatim as a deliverable or delivered as a chat answer,
+// the user gets fiction presented as a real result.
+//
+// This module spots that pattern so callers can refuse to deliver/persist it.
+//
+// CRITICAL false-positive guard: a GENUINE report may legitimately *quote*
+// `<tool_call>` inside a fenced code block (e.g. a bug write-up about this very
+// problem). We must only flag the markers when they appear as BARE text — i.e.
+// the model is emitting them as its own turn — never when they sit inside a
+// ``` ``` ``` fence or inline `code` span. We strip fenced/inline code first and
+// only scan what remains.
+
+// Remove fenced code blocks (``` ... ``` and ~~~ ... ~~~) and inline `code`
+// spans so quoted tool syntax inside documentation is NOT mistaken for a real
+// (fabricated) emission.
+function stripCodeContext(text) {
+  return String(text || '')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/~~~[\s\S]*?~~~/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ');
+}
+
+// Bare `<tool_call>` / `<tool_response>` XML tags (Hermes/Nous chat template).
+const BARE_TOOL_TAG_RE = /<\s*tool_(call|response)\s*>/i;
+
+// A bare JSON function-call blob the model wrote as text, e.g.
+//   {"name": "web-search", "parameters": { ... }}
+//   {"name": "web_fetch", "arguments": { ... }}
+// Hyphenated tool names are an especially strong tell — the real registry uses
+// underscores, so a hyphenated `"name"` call is almost certainly invented.
+const BARE_JSON_CALL_RE = /\{\s*"name"\s*:\s*"[a-z0-9._-]+"\s*,\s*"(parameters|arguments)"\s*:/i;
+
+// A fabricated tool RESULT echoed as text — the model inventing what a tool
+// "returned". Pairs with the call markers above to raise confidence.
+const BARE_TOOL_RESULT_RE = /"(snippet|tool_response)"\s*:/i;
+
+/**
+ * True when `text` looks like a model that role-played a tool loop in plain text
+ * (fabricated calls + invented results) rather than dispatching real tools.
+ *
+ * Conservative by design: requires a bare (non-code-fenced) call marker. Quoting
+ * tool syntax inside ``` fences ``` or `inline code` does NOT trip it.
+ */
+export function looksFabricatedToolTranscript(text) {
+  const bare = stripCodeContext(text);
+  if (!bare.trim()) return false;
+  // Primary tell: the Hermes `<tool_call>`/`<tool_response>` XML template.
+  if (BARE_TOOL_TAG_RE.test(bare)) return true;
+  // Secondary tell: a bare JSON function-call blob. Require a corroborating
+  // signal (a second call OR a fabricated result echo) so a single inline JSON
+  // object in prose can't false-positive.
+  if (BARE_JSON_CALL_RE.test(bare)) {
+    const callCount = (bare.match(/\{\s*"name"\s*:\s*"[a-z0-9._-]+"\s*,\s*"(parameters|arguments)"\s*:/gi) || []).length;
+    if (callCount >= 2) return true;
+    if (BARE_TOOL_RESULT_RE.test(bare)) return true;
+  }
+  return false;
+}
+
+/**
+ * Remove fabricated tool-call / tool-response blocks from text, leaving any
+ * genuine prose. Used when we want to salvage a clean message rather than reject
+ * the whole turn. Best-effort — primarily strips the bare XML template.
+ */
+export function stripFabricatedToolBlocks(text) {
+  return String(text || '')
+    // <tool_call> ... </tool_call> (with or without closing tag before EOF)
+    .replace(/<\s*tool_call\s*>[\s\S]*?(<\s*\/\s*tool_call\s*>|$)/gi, '')
+    .replace(/<\s*tool_response\s*>[\s\S]*?(<\s*\/\s*tool_response\s*>|$)/gi, '')
+    .trim();
+}