@deeeed/metamask-harness 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.22.0 - 2026-07-26
+
+### Added
+
+- Added `execution-template` as the thin public boundary for shared checklist discovery and materialization.
+
+### Fixed
+
+- `ui.navigate page=home` recognizes both the current bottom navigation and the selected legacy Tokens tab.
+- Extension readiness recovers deterministically from transient target-list failures.
+- Team-library calls retain their source provenance.
+
 ## 0.21.0 - 2026-07-24
 
 ### Changed

package/dist/adapters/extension/ensure-ready.js

@@ -36,9 +36,11 @@ async function openHome(port, extensionId) {
   try {
     let res = await fetch(endpoint, { method: "PUT", signal: AbortSignal.timeout(8e3) });
     if (res.status === 404 || res.status === 405) res = await fetch(endpoint, { signal: AbortSignal.timeout(8e3) });
-    return res.ok;
+    if (!res.ok) return null;
+    const value = await res.json();
+    return value && typeof value === "object" ? value : {};
   } catch {
-    return false;
+    return null;
   }
 }
 function homePages(targets, extensionId) {
@@ -94,7 +96,7 @@ async function ensureExtensionReady(target, options) {
         continue;
       }
       action = "opened";
-      opened = await openHome(cdpPort, extensionId) || opened;
+      opened = Boolean(await openHome(cdpPort, extensionId)) || opened;
       await sleep(1500);
     } else {
       action = "pruned";
@@ -149,20 +151,47 @@ async function ensureExtensionReady(target, options) {
   if (action === "pruned" && (health.status !== "PASS" || after !== 1)) {
     const listing = await jsonList(cdpPort);
     if (listing.ok) {
-      action = "reopened";
-      for (const h of homePages(listing.targets, extensionId)) {
-        await closeTab(cdpPort, String(h.id));
-        closed += 1;
-      }
-      await sleep(500);
-      opened = await openHome(cdpPort, extensionId) || opened;
+      const existingHomeIds = new Set(
+        homePages(listing.targets, extensionId).map((home) => String(home.id))
+      );
+      const replacement = await openHome(cdpPort, extensionId);
+      opened = Boolean(replacement) || opened;
       await sleep(1500);
-      const relisted = await jsonList(cdpPort);
-      if (!relisted.ok) {
-        return base({ extensionId, opened, action, homeTabs: { before, closed, after }, reasonCode: "cdp-unreachable" });
+      const replacementListing = await jsonList(cdpPort);
+      if (!replacementListing.ok) {
+        return base({
+          extensionId,
+          opened,
+          action,
+          homeTabs: { before, closed, after },
+          reasonCode: "cdp-unreachable"
+        });
+      }
+      const replacementHomes = homePages(replacementListing.targets, extensionId);
+      const replacementId = replacement?.id && replacementHomes.some((home) => home.id === replacement.id) ? String(replacement.id) : replacementHomes.find((home) => !existingHomeIds.has(String(home.id)))?.id;
+      if (replacementId) {
+        action = "reopened";
+        for (const home of replacementHomes) {
+          if (String(home.id) === replacementId) continue;
+          await closeTab(cdpPort, String(home.id));
+          closed += 1;
+        }
+        await sleep(500);
+        const relisted = await jsonList(cdpPort);
+        if (!relisted.ok) {
+          return base({
+            extensionId,
+            opened,
+            action,
+            homeTabs: { before, closed, after },
+            reasonCode: "cdp-unreachable"
+          });
+        }
+        after = homePages(relisted.targets, extensionId).length;
+        health = await checkHealth();
+      } else {
+        after = replacementHomes.length;
       }
-      after = homePages(relisted.targets, extensionId).length;
-      health = await checkHealth();
     }
   }
   let slotTitle;

package/dist/cli-commands.js

@@ -18,6 +18,7 @@ const SPEC = {
     { name: "actions", desc: "List runnable recipe actions", flags: ["--json", "--categories", "--category", "--action", "--library"] },
     { 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: "execution-template", desc: "Discover and materialize shared agent checklists", args: ["list", "materialize", "lint", "new"], flags: ["--dir", "--domain-dir", "--project-worker", "--project-name", "--package-templates", "--package-id", "--flow", "--run-mode", "--platform", "--domain", "--id", "--provenance", "--include-shadowed", "--no-include-shadowed", "--title", "--force", "--json"] },
     { name: "recipe-quality", desc: "Build the recipe-quality artifact from compact JSON", args: ["build"], flags: ["--input", "--output", "--json"] },
     { name: "interactive", aliases: ["menu"], desc: "Interactive command menu" },
     { name: "prepare", desc: "Install harness (+ optional validate)", flags: ["--target", "--runtime-dir", "--json"] },

package/dist/cli.js

@@ -20,6 +20,7 @@ import { handleRecipeQuality } from "./commands/recipe-quality.js";
 import { handleStatus } from "./commands/status.js";
 import { handleCheck } from "./commands/check.js";
 import { handleChecklist } from "./commands/checklist.js";
+import { handleExecutionTemplate } from "./commands/execution-template.js";
 import { handleLast } from "./commands/last.js";
 import { parseArgs, targetPath } from "./commands/parse-args.js";
 const COMMANDS = {
@@ -121,6 +122,7 @@ async function main(argv) {
   if (command === "recipe-quality") return handleRecipeQuality(argv.slice(1));
   if (command === "check") return handleCheck(argv.slice(1));
   if (command === "checklist") return handleChecklist(argv.slice(1));
+  if (command === "execution-template") return handleExecutionTemplate(argv.slice(1));
   if (command === "last") return handleLast(parseArgs(argv.slice(1), command));
   const handler = COMMANDS[command];
   if (!handler) throw new Error(`Unknown command: ${command}`);

package/dist/command-contract.js

@@ -88,6 +88,32 @@ const PUBLIC_COMMAND_CONTRACTS = {
     ],
     minimumPositionals: 2
   },
+  "execution-template": {
+    usage: "mm-harness execution-template <list|materialize|lint|new> [target] [options]",
+    options: options(HELP, JSON, {
+      "--dir": value(),
+      "--domain-dir": value(),
+      "--project-worker": value(),
+      "--project-name": value(),
+      "--package-templates": value(),
+      "--package-id": value(),
+      "--flow": value(),
+      "--run-mode": value(["autonomous", "interactive", "validation"]),
+      "--platform": value(),
+      "--domain": value(),
+      "--id": value(),
+      "--provenance": value(),
+      "--include-shadowed": bool(),
+      "--no-include-shadowed": bool(),
+      "--title": value(),
+      "--force": bool()
+    }),
+    positionals: [
+      { label: "action", choices: ["list", "materialize", "lint", "new"] }
+    ],
+    minimumPositionals: 1,
+    variadic: { label: "target", validate: (value2) => value2.length > 0 }
+  },
   actions: {
     options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
       "--action": value(),
@@ -360,6 +386,37 @@ function validatePublicInvocation(argv, examples = {}) {
       );
     }
   }
+  if (name === "execution-template") {
+    const action = positionals[0];
+    const validAction = ["list", "materialize", "lint", "new"].includes(action ?? "");
+    const targetCount = Math.max(0, positionals.length - 1);
+    if (validAction && action === "list" && targetCount > 0) {
+      return usageFailure(
+        "CLI_EXCESS_POSITIONAL",
+        name,
+        `execution-template list does not accept positional '${positionals[1]}'.`,
+        contract,
+        examples
+      );
+    }
+    if (validAction && (action === "materialize" || action === "lint" || action === "new") && targetCount === 0) {
+      return missingPositionalFailure(
+        name,
+        `execution-template ${action} requires <target>.`,
+        contract,
+        examples
+      );
+    }
+    if (validAction && targetCount > 1) {
+      return usageFailure(
+        "CLI_EXCESS_POSITIONAL",
+        name,
+        `unexpected positional '${positionals[2]}'; execution-template ${action} accepts one <target>.`,
+        contract,
+        examples
+      );
+    }
+  }
   if (contract.leadingPositionals && !contract.requiredUnless?.some((option) => seenOptions.has(option)) && tokens.slice(0, contract.leadingPositionals).some((argument) => !argument || argument.startsWith("-"))) {
     const missing = contract.positionals?.[0]?.label ?? "argument";
     return missingPositionalFailure(name, `${name} requires <${missing}> first.`, contract, examples);

package/dist/commands/execution-template.js

@@ -0,0 +1,28 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+const require2 = createRequire(import.meta.url);
+async function handleExecutionTemplate(argv) {
+  let entrypoint;
+  try {
+    entrypoint = require2.resolve(
+      "@farmslot/agent-runtime/scripts/execution-template-cli.mjs"
+    );
+  } catch (error) {
+    console.error(
+      `mm-harness execution-template: installed @farmslot/agent-runtime does not expose the catalog command: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return 1;
+  }
+  const result = spawnSync(process.execPath, [entrypoint, ...argv], {
+    env: process.env,
+    stdio: "inherit"
+  });
+  if (result.error) {
+    console.error(`mm-harness execution-template: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+export {
+  handleExecutionTemplate
+};

package/dist/commands/run-engine.js

@@ -21,6 +21,7 @@ import {
 import { captureHelperSupportsRecordSessionSnapshots } from "../recording-target.js";
 import { startRecipeRecording, stopRecipeRecording } from "../run-recording.js";
 import { validateMetaMaskActionInputs } from "../metamask-action-validation.js";
+import { gitLibraryProvenance } from "../library-provenance.js";
 import {
   beginRunDiagnostics,
   finishRunDiagnostics
@@ -655,14 +656,22 @@ async function resolveMetaMaskLibrarySources(libraryEntry, recipePath) {
   if (!sources.some((source) => path.resolve(source.root) === canonicalRoot)) {
     sources.push({ name: "metamask", root: canonicalRoot });
   }
-  return sources.map((source) => ({
-    ...source,
-    provenance: source.provenance ?? {
-      kind: source.name === "metamask" ? "bundled" : "library",
-      trust: source.name === "metamask" ? "trusted" : "unknown",
-      name: source.name ?? path.basename(source.root)
-    }
-  }));
+  return Promise.all(
+    sources.map(async (source) => {
+      const isBundled = source.name === "metamask";
+      const detected = isBundled ? {} : await gitLibraryProvenance(source.root);
+      return {
+        ...source,
+        provenance: {
+          kind: isBundled ? "bundled" : "library",
+          trust: isBundled ? "trusted" : "unknown",
+          name: source.name ?? path.basename(source.root),
+          ...detected,
+          ...source.provenance
+        }
+      };
+    })
+  );
 }
 function synthesizeOneNodeRecipe(action, args) {
   return {

package/dist/library-provenance.js

@@ -0,0 +1,33 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+async function gitLibraryProvenance(root) {
+  try {
+    const { stdout: tracked } = await execFileAsync("git", ["-C", root, "ls-files", "--", "."], {
+      encoding: "utf8",
+      timeout: 5e3
+    });
+    if (!tracked.trim()) return {};
+    const [{ stdout: revision }, { stdout: status }] = await Promise.all([
+      execFileAsync("git", ["-C", root, "rev-parse", "HEAD"], {
+        encoding: "utf8",
+        timeout: 5e3
+      }),
+      execFileAsync(
+        "git",
+        ["-C", root, "status", "--porcelain=v1", "--untracked-files=normal", "--", "."],
+        {
+          encoding: "utf8",
+          timeout: 5e3
+        }
+      )
+    ]);
+    const trimmedRevision = revision.trim();
+    return trimmedRevision ? { revision: trimmedRevision, dirty: status.trim().length > 0 } : {};
+  } catch {
+    return {};
+  }
+}
+export {
+  gitLibraryProvenance
+};

package/dist/mm-harness-cli.js

@@ -77,6 +77,40 @@ Example:
   mm-harness checklist mark temp/tasks/recipe-cook/<task> complete --mark-last
   mm-harness checklist closeout temp/tasks/recipe-cook/<task> --share`
   },
+  {
+    name: "execution-template",
+    summary: "Discover, validate, and materialize shared agent checklists.",
+    example: "mm-harness execution-template list --package-templates <path> --json",
+    helpText: `mm-harness execution-template <list|materialize|lint|new> [options]
+
+  Shared Markdown checklist catalog used by direct and orchestrated workflows.
+  Sources use the flow-tree shape <root>/<flow>/<variant>.md.
+
+  list        List compatible templates and portable source provenance.
+  materialize Select one template, copy its immutable snapshot, and optionally
+              write a provenance record.
+  lint        Validate one template file or flow-tree directory.
+  new         Create a minimal starter template.
+
+Common source/filter options:
+  --dir <path>                       Custom flow-tree source (repeatable)
+  --domain-dir <domain=path>         Domain-scoped team source (repeatable)
+  --package-templates <path>         Canonical package flow-tree root
+  --package-id <id>                  Source label for the package root
+  --project-worker <path>            Project template directory
+  --project-name <name>              Source label for project templates
+  --flow <flow>                      Exact flow
+  --platform <platform>              Exact platform
+  --run-mode <mode>                  autonomous|interactive|validation
+  --domain <domain>                  Exact domain
+  --id <id>                          Exact template id
+  --json                             Machine-readable output
+
+Materialize:
+  mm-harness execution-template materialize <output> --flow fix-bug \\
+    --platform mobile --run-mode autonomous --id fix-bug/autonomous.mobile \\
+    --package-templates <path> --provenance <path> --json`
+  },
   {
     name: "actions",
     summary: "Discover typed single operations and their fields.",
@@ -552,7 +586,7 @@ const HELP_GROUPS = [
   {
     title: "DISCOVER",
     blurb: "discover atomic actions and reusable recipes (--json is the agent-primary form)",
-    commands: ["actions", "call"]
+    commands: ["actions", "call", "execution-template"]
   },
   {
     title: "PROVE",

package/library/actions/extension/ui/navigate.mjs

@@ -69,12 +69,17 @@ async function activateSemanticControl(page, selector) {
 export async function openHome(page, timeoutMs) {
   const home = dataTestId('bottom-nav-home');
   const selectedHome = `${home}[aria-current="page"]`;
+  const legacyHome = dataTestId('account-overview__asset-tab');
+  const selectedLegacyHome = `${legacyHome}[aria-selected="true"]`;
   const deadline = Date.now() + timeoutMs;
   const steps = [];
   let pendingActivation;
 
   while (Date.now() < deadline) {
-    if (await hasVisibleSelector(page, selectedHome)) {
+    if (
+      (await hasVisibleSelector(page, selectedHome)) ||
+      (await hasVisibleSelector(page, selectedLegacyHome))
+    ) {
       return { method: 'visible-ui', href: await currentHref(page), steps };
     }
     const href = await currentHref(page);
@@ -83,12 +88,17 @@ export async function openHome(page, timeoutMs) {
       await pauseForUi(page);
       continue;
     }
-    if (await hasVisibleSelector(page, home)) {
-      if (pendingActivation?.selector !== home) pendingActivation = undefined;
+    const homeControl = (await hasVisibleSelector(page, home))
+      ? home
+      : (await hasVisibleSelector(page, legacyHome))
+        ? legacyHome
+        : undefined;
+    if (homeControl) {
+      if (pendingActivation?.selector !== homeControl) pendingActivation = undefined;
       if (!pendingActivation) {
-        await activateSemanticControl(page, home);
-        steps.push(home);
-        pendingActivation = { selector: home, href };
+        await activateSemanticControl(page, homeControl);
+        steps.push(homeControl);
+        pendingActivation = { selector: homeControl, href };
       }
       await pauseForUi(page);
       continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -19,9 +19,9 @@
     "check:syntax": "find . -name '*.mjs' -print0 | xargs -0 -n1 node --check"
   },
   "dependencies": {
-    "@farmslot/agent-runtime": "^0.3.1",
+    "@farmslot/agent-runtime": "^0.4.0",
     "@farmslot/handoff": "^0.3.1",
-    "@farmslot/protocol": "^0.12.0",
+    "@farmslot/protocol": "^0.13.0",
     "@farmslot/recipe-harness": "^0.10.0",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",

package/scripts/completions.sh

@@ -29,7 +29,7 @@ _mmh_bin() {
   return 1
 }
 
-_mmh_commands="launch stop logs debug fixtures actions call run doctor check checklist recipe-quality install verify cleanup completions"
+_mmh_commands="launch stop logs debug fixtures actions call run doctor check checklist execution-template recipe-quality install verify cleanup completions"
 
 # Per-command flags (static, from the mm-harness surface).
 _mmh_flags_for() {
@@ -40,6 +40,7 @@ _mmh_flags_for() {
     debug)    printf '%s' "--worker --dev-menu --adapter --target --json" ;;
     fixtures) printf '%s' "--from --dev --force --fixture --adapter --target --json" ;;
     checklist) printf '%s' "" ;;
+    execution-template) printf '%s' "--dir --domain-dir --project-worker --project-name --package-templates --package-id --flow --run-mode --platform --domain --id --provenance --include-shadowed --no-include-shadowed --title --force --json" ;;
     actions)  printf '%s' "--adapter --action --kind --raw --action-manifest --target --json" ;;
     call)     printf '%s' "--list --arg --adapter --target --artifacts-dir --action-manifest --heal --json" ;;
     run)      printf '%s' "--list --describe --plan --adapter --artifacts-dir --target --library --cdp-port --heal --record-video --json" ;;