@deeeed/metamask-harness 0.15.2 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.16.0 - 2026-07-14
+
+### Added
+
+- Mobile and Extension recipe runs now write bounded, redacted, non-blocking side findings to `diagnostics.json`: Mobile combines its in-app issue buffer with run-scoped log bytes, while Extension owns a CDP console subscription for the run. Core remains N/A because it is headless.
+- `actions --categories` now lists compact category counts, and `actions --category <name>` returns a bounded action/schema view so agents can discover capabilities without loading the complete adapter catalog.
+
 ## 0.15.2 - 2026-07-13
 
 ### Fixed

package/README.md

@@ -50,6 +50,13 @@ mm-harness launch ios                    # mobile: ios | android; extension: jus
 mm-harness run recipe.json --adapter mobile --artifacts-dir /tmp/recipe-artifacts --json
 ```
 
+Mobile and Extension runs also write `diagnostics.json` from application events
+emitted during that run. Mobile combines its bounded in-app issue buffer with
+run-scoped log bytes; Extension owns a CDP console subscription for the run.
+These redacted warnings/errors are non-blocking side findings: they help spot
+adjacent bugs without claiming the recipe or current change caused them. Core
+is headless, so this is N/A there.
+
 Outputs: `summary.json`, `trace.json`, screenshots, logs, and an artifact
 manifest.
 
@@ -69,7 +76,8 @@ windows, wallet state, health, ports, parallel).
 
 ```bash
 # Capabilities (compose recipes from the vocabulary + flow library)
-mm-harness actions --adapter mobile --json      # the action vocabulary
+mm-harness actions --adapter mobile --categories --json # compact discovery
+mm-harness actions --adapter mobile --category ui --json # bounded vocabulary
 mm-harness actions --adapter mobile --raw       # raw action-manifest dump
 mm-harness call unlock --adapter extension      # run one action via the real engine path
 mm-harness flows --json                         # reusable library flows, with provenance

package/dist/cli-commands.js

@@ -15,7 +15,7 @@ const SPEC = {
     { name: "logs", aliases: ["tail"], desc: "Compact build events or full log", flags: ["--full", "-f", "--window", "--events", "--source", "--json"] },
     { name: "debug", aliases: ["devtools", "inspect"], desc: "Open DevTools UI", flags: ["--json", "--no-open"] },
     { name: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/generate)", args: ["sync", "set", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--device", "--json"] },
-    { name: "actions", desc: "List runnable recipe actions", flags: ["--json"] },
+    { name: "actions", desc: "List runnable recipe actions", flags: ["--json", "--categories", "--category", "--action"] },
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--print-ready", "--cdp-port", "--device"] },
     { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run perps.smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },
     { name: "recipe-quality", desc: "Build the recipe-quality artifact from compact JSON", args: ["build"], flags: ["--input", "--output", "--json"] },

package/dist/commands/call.js

@@ -174,6 +174,8 @@ async function handleCall(argv) {
             summaryPath: result.summaryPath,
             tracePath: result.tracePath,
             artifactManifestPath: result.artifactManifestPath,
+            ...result.diagnosticsPath ? { diagnosticsPath: result.diagnosticsPath } : {},
+            ...result.sideFindings ? { sideFindings: result.sideFindings } : {},
             ...callOutput !== void 0 ? { output: callOutput } : {},
             recovered: state.recovered,
             mutations: state.mutations,
@@ -187,12 +189,15 @@ async function handleCall(argv) {
       const rendered = callOutput !== void 0 ? `
 Result:
 ${formatCallOutput(callOutput)}` : "";
+      const sideFindingTotal = result.sideFindings?.counts.total ?? 0;
       const out = (style, text) => color(style, text, { stream: process.stdout });
+      const sideFindings = sideFindingTotal > 0 ? `${out("label", "Side findings:")} REVIEW ${sideFindingTotal} distinct application warning/error event(s); see ${out("path", result.diagnosticsPath ?? "diagnostics.json")} (non-blocking)
+` : "";
       console.log(
         `${out("label", "call")} ${out("cmd", resolvedAction)}: ${out(result.status === "pass" ? "ok" : "err", result.status)}${rendered ? `
 ${out("label", "Result:")}
 ${formatCallOutput(callOutput)}` : ""}
-${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}`
+` + sideFindings + `${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}`
       );
     }
     return result.status === "pass" ? EXIT.ok : EXIT.runtime;

package/dist/commands/manifest.js

@@ -22,13 +22,42 @@ async function handleActions({ options }) {
   await validateManifest(manifest);
   const json = optionFlag(options, "json");
   const action = optionString(options, "action");
+  const category = optionString(options, "category")?.toLowerCase();
+  const categoriesOnly = optionFlag(options, "categories");
   const all = describeManifestActions(manifest);
-  const actions = action ? fuzzyResolveActions(all, action) : all;
+  const categories = summarizeActionCategories(all);
+  if (categoriesOnly && (action || category)) {
+    const message = "--categories cannot be combined with --action or --category.";
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, error: { code: "ACTION_FILTER_CONFLICT", message } }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness actions: ${message}`);
+    }
+    return EXIT.usage;
+  }
+  if (categoriesOnly) {
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, categories }, null, 2));
+    else for (const entry of categories) console.log(`${entry.name} (${entry.count})`);
+    return EXIT.ok;
+  }
+  const categoryActions = category ? all.filter((entry) => entry.category === category) : all;
+  if (category && categoryActions.length === 0) {
+    const message = `no action category matches "${category}" for the ${adapter} adapter.`;
+    const userAction = `mm-harness actions --adapter ${adapter} --categories`;
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, category, availableCategories: categories, error: { code: "ACTION_CATEGORY_UNKNOWN", message, userAction } }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness actions: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.usage;
+  }
+  const actions = action ? fuzzyResolveActions(categoryActions, action) : categoryActions;
   if (action && actions.length === 0) {
     const message = `no action matches "${action}" for the ${adapter} adapter.`;
     const userAction = `mm-harness actions --adapter ${adapter}   # list the vocabulary`;
     if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, action, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));
+      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, action, category, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));
     } else {
       console.error(`\u2717 mm-harness actions: ${message}
   Next: ${userAction}`);
@@ -36,7 +65,7 @@ async function handleActions({ options }) {
     return EXIT.usage;
   }
   if (json) {
-    console.log(JSON.stringify({ adapter, actions }, null, 2));
+    console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, category, actions }, null, 2));
   } else {
     for (const entry of actions) {
       const fields = entry.fields.length ? ` fields=${entry.fields.join(",")}` : "";
@@ -53,6 +82,11 @@ function fuzzyResolveActions(entries, query) {
   if (exactSegment.length > 0) return exactSegment;
   return entries.filter((e) => finalSegment(e.name).includes(query));
 }
+function summarizeActionCategories(actions) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const action of actions) counts.set(action.category, (counts.get(action.category) ?? 0) + 1);
+  return [...counts.entries()].map(([name, count]) => ({ name, count })).sort((left, right) => left.name.localeCompare(right.name));
+}
 function describeManifestActions(manifest) {
   const manifestRecord = isRecord(manifest) ? manifest : {};
   const metadata = isRecord(manifestRecord.action_metadata) ? manifestRecord.action_metadata : {};
@@ -80,15 +114,22 @@ function describeManifestAction(name, kind, metadata) {
   return {
     name,
     kind,
+    category: actionCategory(name),
     description: typeof record.description === "string" ? record.description : "",
     fields: properties,
     schema,
     examples: record.examples
   };
 }
+function actionCategory(name) {
+  const segments = name.split(".");
+  if (segments[0] === "metamask" && segments.length > 2) return segments[1] ?? "metamask";
+  return segments[0] || "other";
+}
 export {
   describeManifestActions,
   fuzzyResolveActions,
   handleActions,
-  handleManifest
+  handleManifest,
+  summarizeActionCategories
 };

package/dist/commands/parse-args.js

@@ -25,6 +25,7 @@ function parseArgs(argv, command) {
     "plan",
     "list",
     "raw",
+    "categories",
     "fix",
     "force",
     "resolveOnly",

package/dist/commands/run-engine.js

@@ -20,6 +20,11 @@ import {
 import { captureHelperSupportsRecordSessionSnapshots } from "../recording-target.js";
 import { listRecipeFiles } from "../recipe-files.js";
 import { startRecipeRecording, stopRecipeRecording } from "../run-recording.js";
+import {
+  beginRunDiagnostics,
+  finishRunDiagnostics,
+  stopRunDiagnostics
+} from "../run-diagnostics.js";
 import { EXIT } from "./shared.js";
 import {
   actionManifestPathOption,
@@ -49,6 +54,7 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
   try {
     await prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions);
     const absoluteArtifactsDir = path.resolve(artifactsDir);
+    const diagnosticBaseline = await beginRunDiagnostics(adapter, projectRoot);
     const recordVideo = runtimeOptions.recordVideo ?? false;
     const useFramedExtensionRecording = adapter === "extension" && recordVideo === "full-run" && captureHelperSupportsRecordSessionSnapshots(projectRoot);
     const recording = useFramedExtensionRecording ? await startRecipeRecording(adapter, projectRoot, absoluteArtifactsDir, {
@@ -80,8 +86,9 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
         }
       }
       await stopRecipeRecording(recording, result);
-      return result;
+      return finishRunDiagnostics(diagnosticBaseline, result);
     } finally {
+      stopRunDiagnostics(diagnosticBaseline);
       await stopRecipeRecording(recording);
     }
   } finally {

package/dist/commands/run-report.js

@@ -25,10 +25,19 @@ function renderRunReport(summary, entries) {
     "",
     `Status: ${String(summary.status ?? "unknown")}`,
     `Duration: ${formatDuration(Number(summary.durationMs ?? 0))}`,
-    `Nodes: ${Number(summary.passed ?? 0)}/${Number(summary.total ?? entries.length)} passed`,
-    "",
-    "## Steps"
+    `Nodes: ${Number(summary.passed ?? 0)}/${Number(summary.total ?? entries.length)} passed`
   ];
+  const sideFindings = isRecord(summary.sideFindings) ? summary.sideFindings : void 0;
+  const sideFindingCounts = sideFindings && isRecord(sideFindings.counts) ? sideFindings.counts : void 0;
+  const sideFindingTotal = Number(sideFindingCounts?.total ?? 0);
+  if (sideFindingTotal > 0) {
+    lines.push(
+      "",
+      "## Side findings",
+      `- REVIEW ${sideFindingTotal} distinct application warning/error event(s); see diagnostics.json (non-blocking)`
+    );
+  }
+  lines.push("", "## Steps");
   for (const entry of entries) {
     if (!isRecord(entry)) continue;
     const mark = entry.ok === false ? "FAIL" : "PASS";

package/dist/mm-harness-cli.js

@@ -76,6 +76,8 @@ Example:
   List the action vocabulary + field schemas for the checkout adapter.
 
   --action <name>                    Describe one action; fuzzy-resolves like call (short or full name)
+  --categories                       List compact action categories and counts
+  --category <name>                  List only one category (for example ui, wallet, or perps)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --raw                              Dump raw action registry JSON
@@ -83,6 +85,8 @@ Example:
 
 Example:
   mm-harness actions --adapter mobile
+  mm-harness actions --adapter mobile --categories --json
+  mm-harness actions --adapter mobile --category ui --json
   mm-harness actions --adapter mobile --action assert_orders
   mm-harness actions --adapter extension --raw`
   },

package/dist/run-diagnostics.js

@@ -0,0 +1,271 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+import { getAdapterSurface } from "./adapters/surface.js";
+import { runnerDir } from "./paths.js";
+const MAX_CAPTURE_BYTES = 512 * 1024;
+const MAX_FINDINGS = 20;
+const MAX_PREVIEW_CHARS = 320;
+async function beginRunDiagnostics(adapter, projectRoot) {
+  const source = getAdapterSurface(adapter).appLogSource(projectRoot);
+  if (!source) return null;
+  const mobileIssueBuffer = adapter === "mobile" && armMobileIssueBuffer(projectRoot) ? { projectRoot } : void 0;
+  const extensionConsoleCapture = adapter === "extension" ? await startExtensionConsoleCapture(source, projectRoot) : void 0;
+  const stat = safeStat(source.path);
+  return {
+    source,
+    offset: stat?.size ?? 0,
+    ...stat ? { inode: stat.ino } : {},
+    ...mobileIssueBuffer ? { mobileIssueBuffer } : {},
+    ...extensionConsoleCapture ? { extensionConsoleCapture } : {}
+  };
+}
+function finishRunDiagnostics(baseline, result) {
+  if (!baseline) return result;
+  try {
+    stopRunDiagnostics(baseline);
+    const bufferedIssues = baseline.mobileIssueBuffer ? collectMobileIssueBuffer(baseline.mobileIssueBuffer.projectRoot) : void 0;
+    const diagnostics = collectRunDiagnostics(baseline, bufferedIssues);
+    const artifactsDir = path.dirname(result.summaryPath);
+    const diagnosticsPath = path.join(artifactsDir, "diagnostics.json");
+    fs.writeFileSync(diagnosticsPath, `${JSON.stringify(diagnostics, null, 2)}
+`);
+    indexDiagnosticArtifact(result.artifactManifestPath);
+    indexDiagnosticSummary(result.summaryPath, diagnostics);
+    return {
+      ...result,
+      diagnosticsPath,
+      sideFindings: {
+        status: diagnostics.status,
+        note: diagnostics.note,
+        counts: diagnostics.counts
+      }
+    };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    console.warn(`WARN: run diagnostics were unavailable: ${detail}`);
+    return {
+      ...result,
+      sideFindings: {
+        status: "unavailable",
+        note: "Run diagnostics could not be collected; the recipe result is unchanged.",
+        counts: { total: 0, warning: 0, error: 0, exception: 0 }
+      }
+    };
+  }
+}
+function stopRunDiagnostics(baseline) {
+  const capture = baseline?.extensionConsoleCapture;
+  if (!capture || capture.exitCode !== null || capture.signalCode !== null) return;
+  capture.kill("SIGTERM");
+}
+function collectRunDiagnostics(baseline, bufferedIssues) {
+  const stat = safeStat(baseline.source.path);
+  const source = {
+    label: baseline.source.label,
+    path: baseline.source.path,
+    startOffset: baseline.offset,
+    endOffset: stat?.size ?? baseline.offset,
+    bytesRead: 0,
+    truncated: false,
+    inAppBuffer: bufferedIssues === void 0 ? "n/a" : bufferedIssues === null ? "unavailable" : "collected"
+  };
+  let text = "";
+  if (stat) {
+    const sameFile = baseline.inode === void 0 || baseline.inode === stat.ino;
+    const startOffset = sameFile && stat.size >= baseline.offset ? baseline.offset : 0;
+    const available = Math.max(0, stat.size - startOffset);
+    const bytesToRead = Math.min(available, MAX_CAPTURE_BYTES);
+    source.startOffset = startOffset;
+    source.endOffset = stat.size;
+    source.bytesRead = bytesToRead;
+    source.truncated = available > MAX_CAPTURE_BYTES;
+    if (bytesToRead > 0) text = readSlice(baseline.source.path, startOffset, bytesToRead);
+  }
+  const allFindings = dedupeFindings(
+    [
+      ...text.split(/\r?\n/u).map(classifyLine).filter((finding) => finding !== null),
+      ...(bufferedIssues ?? []).map(classifyBufferedIssue).filter((finding) => finding !== null)
+    ]
+  );
+  const findings = allFindings.slice(0, MAX_FINDINGS);
+  const counts = countFindings(allFindings);
+  const status = counts.total > 0 ? "review" : stat || bufferedIssues !== void 0 && bufferedIssues !== null ? "clean" : "unavailable";
+  const note = counts.total > 0 ? `Observed ${counts.total} distinct application warning/error event(s) during the recipe run; relation to the task is not determined.` : status === "clean" ? "No application warnings or errors were emitted during the recipe run." : "Application diagnostics were unavailable for this run.";
+  return {
+    schemaVersion: 1,
+    scope: "recipe-run-application",
+    status,
+    nonBlocking: true,
+    note,
+    source,
+    counts,
+    findings
+  };
+}
+function classifyLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  let level = null;
+  if (/\bEXCEPTION\s{2,}|\b(?:Uncaught|UnhandledPromiseRejection|FATAL EXCEPTION)\b/iu.test(trimmed)) {
+    level = "exception";
+  } else if (/^(?:ERROR\s{2,}|\[error\]\s*)/iu.test(trimmed) || /\]\s+ERROR\s{2,}/u.test(trimmed)) {
+    level = "error";
+  } else if (/^(?:WARN(?:ING)?\s{2,}|\[warn(?:ing)?\]\s*)/iu.test(trimmed) || /\]\s+WARN(?:ING)?\s{2,}/u.test(trimmed)) {
+    level = "warning";
+  }
+  if (!level) return null;
+  return makeFinding(level, trimmed);
+}
+function classifyBufferedIssue(value) {
+  if (!isRecord(value) || typeof value.text !== "string") return null;
+  const rawLevel = String(value.level ?? "").toLowerCase();
+  const level = rawLevel === "warn" || rawLevel === "warning" ? "warning" : rawLevel === "error" ? "error" : rawLevel === "exception" ? "exception" : null;
+  return level ? makeFinding(level, value.text) : null;
+}
+function makeFinding(level, text) {
+  const preview = redactPreview(text.trim());
+  const identity = preview.replace(/\b\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?\b/gu, "[TIME]").replace(/\[(?:sw|page:[^\]]+|console:[^\]]+)\]/gu, "[APP]").replace(/^(?:(?:WARN(?:ING)?|ERROR|EXCEPTION|\[TIME\]|\[APP\])\s*)+/u, "");
+  return {
+    level,
+    fingerprint: createHash("sha256").update(`${level}|${identity}`).digest("hex").slice(0, 12),
+    preview
+  };
+}
+function armMobileIssueBuffer(projectRoot) {
+  const armed = runMobileIssueCommand(projectRoot, "issues-arm");
+  if (!armed) return false;
+  return runMobileIssueCommand(projectRoot, "issues-collect") !== null;
+}
+function collectMobileIssueBuffer(projectRoot) {
+  const result = runMobileIssueCommand(projectRoot, "issues-collect");
+  return isRecord(result) && Array.isArray(result.entries) ? result.entries : null;
+}
+function runMobileIssueCommand(projectRoot, command) {
+  const bridge = path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
+  const result = spawnSync(process.execPath, [bridge, command], {
+    cwd: projectRoot,
+    env: { ...process.env, APP_ROOT: projectRoot, CDP_TIMEOUT: "5000" },
+    encoding: "utf8",
+    timeout: 1e4
+  });
+  if (result.status !== 0) return null;
+  try {
+    return JSON.parse(result.stdout.trim());
+  } catch {
+    return null;
+  }
+}
+async function startExtensionConsoleCapture(source, projectRoot) {
+  const cdpPort = process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  if (!cdpPort) return void 0;
+  fs.mkdirSync(path.dirname(source.path), { recursive: true });
+  const before = safeStat(source.path)?.size ?? 0;
+  const script = path.join(runnerDir, "adapters", "extension", "console-tail.mjs");
+  const child = spawn(process.execPath, [script, "--cdp-port", cdpPort, "--log", source.path], {
+    cwd: projectRoot,
+    stdio: "ignore"
+  });
+  const attached = await waitForExtensionAttachment(source.path, before, child, 3e3);
+  if (attached) {
+    await delay(50);
+    return child;
+  }
+  if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+  return void 0;
+}
+async function waitForExtensionAttachment(logPath, offset, child, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && child.exitCode === null && child.signalCode === null) {
+    const stat = safeStat(logPath);
+    if (stat && stat.size > offset) {
+      const appended = readSlice(logPath, offset, Math.min(stat.size - offset, 64 * 1024));
+      if (appended.includes("[attached]")) return true;
+    }
+    await delay(50);
+  }
+  return false;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function redactPreview(value) {
+  return value.replace(/\b(Bearer)\s+\S+/giu, "$1 [REDACTED]").replace(/\b(password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/giu, "$1=[REDACTED]").replace(/\b(?:0x)?[a-f0-9]{64,}\b/giu, "[REDACTED_HEX]").replace(/(https?:\/\/[^\s?]+)\?\S+/giu, "$1?[REDACTED_QUERY]").slice(0, MAX_PREVIEW_CHARS);
+}
+function dedupeFindings(findings) {
+  const byFingerprint = /* @__PURE__ */ new Map();
+  for (const finding of findings) {
+    const existing = byFingerprint.get(finding.fingerprint);
+    if (existing) existing.count += 1;
+    else byFingerprint.set(finding.fingerprint, { ...finding, count: 1 });
+  }
+  return [...byFingerprint.values()];
+}
+function countFindings(findings) {
+  const counts = { total: findings.length, warning: 0, error: 0, exception: 0 };
+  for (const finding of findings) counts[finding.level] += 1;
+  return counts;
+}
+function readSlice(filePath, offset, length) {
+  const fd = fs.openSync(filePath, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    const bytesRead = fs.readSync(fd, buffer, 0, length, offset);
+    return buffer.subarray(0, bytesRead).toString("utf8");
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function safeStat(filePath) {
+  try {
+    return fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+}
+function indexDiagnosticArtifact(manifestPath) {
+  const manifest = readJsonRecord(manifestPath);
+  if (!manifest) return;
+  const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+  manifest.artifacts = [
+    ...artifacts.filter((artifact) => !isRecord(artifact) || artifact.path !== "diagnostics.json"),
+    {
+      path: "diagnostics.json",
+      type: "json",
+      label: "Run-scoped application diagnostics",
+      category: "diagnostic"
+    }
+  ];
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+}
+function indexDiagnosticSummary(summaryPath, diagnostics) {
+  const summary = readJsonRecord(summaryPath);
+  if (!summary) return;
+  summary.sideFindings = {
+    status: diagnostics.status,
+    nonBlocking: true,
+    counts: diagnostics.counts,
+    diagnosticsPath: "diagnostics.json"
+  };
+  fs.writeFileSync(summaryPath, `${JSON.stringify(summary, null, 2)}
+`);
+}
+function readJsonRecord(filePath) {
+  try {
+    const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return isRecord(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export {
+  beginRunDiagnostics,
+  collectRunDiagnostics,
+  finishRunDiagnostics,
+  stopRunDiagnostics
+};

package/docs/CLI-SPEC.md

@@ -366,6 +366,8 @@ Installs the cached Runway iOS dev client onto a prepared mobile slot. It does n
 
 **Validates first (adapter-aware):** Before touching any device, `run` validates the recipe: action existence in the adapter's manifest, platform support for each action, and fixture preconditions. Validation errors exit 5 with a structured error list. `--plan` stops here — prints the plan and exits, no device touched. Without `--plan`, validation failures are fatal before any execution begins.
 
+**Run-scoped diagnostics:** Mobile combines its bounded in-app issue buffer with application-log bytes appended while the recipe executes; Extension owns a CDP console subscription for the run. The bounded, redacted result is written to `diagnostics.json`, indexed as a diagnostic artifact, and summarized as non-blocking `sideFindings`; it never changes recipe pass/fail and does not claim causality. Core is headless, so this is N/A.
+
 > **Wave-2 status:** adapter-aware validation (`validateRecipeDocument` +
 > `validateRecipeWithManifest`, shared helper `validateRecipeAdapterAware`) is
 > wired for **`run --plan`** and **`call`** at the pinned deps (`@farmslot/protocol`
@@ -559,9 +561,9 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
 
 ### `actions` (ROUTES-NOW → DISCOVER verb)
 
-**Synopsis:** `mm-harness actions --adapter <p> [--json] [--action <name>] [--kind official|custom]`
+**Synopsis:** `mm-harness actions --adapter <p> [--json] [--categories | --category <name> | --action <name>]`
 
-**PRIMARY (agent):** `mm-harness actions --adapter mobile --json`
+**PRIMARY (agent):** `mm-harness actions --adapter mobile --categories --json`, then one `--category` or `--action` query.
 
 **`--json` output shape** (grounded — `actions --adapter core --json` confirmed):
 ```json
@@ -571,6 +573,7 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
     {
       "name": "metamask.perps.read_positions",
       "kind": "custom",
+      "category": "perps",
       "description": "Read live Perps positions...",
       "fields": ["account", "action", "market", "markets", "mode", "selector", "side", "symbol", "symbols", "timeout_ms"],
       "examples": [{ "node": { "action": "metamask.perps.read_positions", "account": "...", "symbol": "BTC" } }]
@@ -578,7 +581,7 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
   ]
 }
 ```
-`kind` is `"official"` (engine built-ins) or `"custom"` (MetaMask adapter actions). `fields` lists every accepted parameter name. `examples[].node` is a copy-pasteable recipe node.
+`kind` is `"official"` (engine built-ins) or `"custom"` (MetaMask adapter actions). `category` is derived from the durable action namespace (`ui.*` → `ui`, `metamask.perps.*` → `perps`). `fields` lists every accepted parameter name. `examples[].node` is a copy-pasteable recipe node.
 
 **Human form:** `mm-harness actions --adapter mobile` — one line per action: `<name> (<kind>) <description>  fields=<f1,f2,...>`.
 
@@ -586,12 +589,13 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
 |---|---|---|---|---|---|
 | `--adapter <p>` | mobile\|extension\|core | auto-detect | `RECIPE_HARNESS_PLATFORM` | both | Target adapter · [DEFAULT-GAP] required today |
 | `--action <name>` | string | all | — | agent | Filter to one action; full schema + all examples |
-| `--kind <k>` | official\|custom | all | — | agent | Filter by action kind |
+| `--categories` | bool | false | — | agent | Return only sorted category names and action counts |
+| `--category <name>` | string | all | — | agent | Return actions from one namespace-derived category |
 | `--action-manifest <path>` | path | bundled | — | agent | Override manifest |
 | `--raw` | bool | false | — | agent | Dump the underlying action manifest JSON (protocol version, registry version, all entries in raw registry format — same output as `manifest --json` today; replaces the retired `manifest` verb) |
 | `--json` | bool | false | — | **agent PRIMARY** | Full schema + fields + examples per action |
 
-**[DISCOVERY-GAP]:** No `--action <name>` single-action filter today (all or nothing). No `--kind` filter. No keyword search across descriptions or fields.
+**[DISCOVERY-GAP]:** No keyword search across descriptions or fields. Flow discovery remains separate.
 **Exit:** 0 / non-zero on engine error.
 **Maps-to:** A:`actions` (ROUTES-NOW); C/D:`actions` (ABSORB-LATER).
 

package/docs/MENTAL-MODEL.md

@@ -189,14 +189,14 @@ The composition loop: `actions --json` → `call <action>` (try one via real eng
 | | |
 |---|---|
 | **Human form** | `mm-harness actions --adapter mobile` · `mm-harness call unlock` · `mm-harness flows` |
-| **Agent PRIMARY** | `mm-harness actions --adapter mobile --json` → `{ adapter, actions: [{ name, kind, description, fields, examples }] }` |
+| **Agent PRIMARY** | `mm-harness actions --adapter mobile --categories --json`, then `--category <name>` or one focused `--action <name>` schema |
 | | `mm-harness call metamask.perps.read_positions --arg symbol=BTC --adapter core --json` → `{ action, resolvedAction, args, trace, evidence, recovered, mutations, exitCode, schemaVersion }` (same shape as `run --json`, one-node subset) |
 | | `mm-harness flows --json` → `{ sources, flows: [{ ref, source, file, description?, requiredParams?, shadows?, lastVerified? }] }` |
 | **Plan before run** | `mm-harness run recipe.json --plan --json` → `{ plan[], validation: { status, findings }, schemaVersion }` (adapter-aware; exit 5 on errors) |
 
 | Today (real) | → mm-harness | Status |
 |---|---|---|
-| `metamask-recipe actions --adapter …` | `mm-harness actions --adapter …` | ROUTES-NOW · [DEFAULT-GAP] `--adapter` required · [DISCOVERY-GAP] no `--action <name>` filter, no `--kind` filter, no keyword search |
+| `metamask-recipe actions --adapter …` | `mm-harness actions --adapter …` | ROUTES-NOW · auto-detects in a checkout · bounded category/action views shipped · [DISCOVERY-GAP] no keyword search |
 | `metamask-recipe flows list\|promote` | `mm-harness flows [\|promote]` | ROUTES-NOW · `flows` = browse the reusable flow library (compose, don't rewrite); `promote` publishes a proven flow up a tier · bare `flows` = list · [DISCOVERY-GAP] no keyword filter, no per-flow body fetch, no platform filter |
 | `mm-recipe`/`mme-recipe` `actions`/`doctor` (auto adapter) | same `mm-harness` verbs | ABSORB-LATER — porcelain supplies missing adapter default |
 | hook layer `run-action app.unlock` | `mm-harness call unlock` (fuzzy: `unlock` → `metamask.wallet.unlock`) — **one-node recipe via real engine path** | REAL (wave 2) · ambiguous → exit 2 listing candidates |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"