@deeeed/metamask-harness 0.16.0 → 0.17.0

package/dist/harness.js

@@ -50,6 +50,12 @@ function failureHint(adapter, action) {
   const helper = adapter === "mobile" ? "mm-harness launch ios   # or launch android" : "mm-harness launch";
   return `Read the error above for the specific cause. To (re)start the runtime, run: ${helper}`;
 }
+function successNext(adapter, action, target) {
+  const base = `--adapter ${adapter} --target ${shellQuote(target)}`;
+  if (action === "install") return `mm-harness verify ${base}`;
+  if (action === "cleanup") return `mm-harness install ${base}`;
+  return `mm-harness status --target ${shellQuote(target)} --json`;
+}
 function hasArg(args, needle) {
   return args.some((arg) => arg === needle || arg.startsWith(`${needle}=`));
 }
@@ -347,7 +353,8 @@ async function handleMobileLive(target, forwardArgs, json, autoDetected) {
       )
     );
   } else if (exitCode === 0) {
-    console.error(`\u2713 live mobile passed (${elapsed}s)`);
+    console.error(`\u2713 live mobile passed (${elapsed}s)
+  Next: ${successNext("mobile", "live", target)}`);
   } else {
     console.error(
       `\u2717 live mobile failed (exit ${exitCode}, ${elapsed}s)
@@ -492,7 +499,8 @@ async function handleHarness(argv) {
       )
     );
   } else if (exitCode === 0) {
-    console.error(`\u2713 ${harnessAction} ${adapter} passed (${seconds}s)`);
+    console.error(`\u2713 ${harnessAction} ${adapter} passed (${seconds}s)
+  Next: ${successNext(adapter, harnessAction, target)}`);
   } else {
     console.error(`\u2717 ${harnessAction} ${adapter} failed (exit ${exitCode}, ${seconds}s)
   ${failureHint(adapter, harnessAction)}`);
@@ -522,8 +530,10 @@ async function handleRunwayInstall(adapter, target, forward, json) {
     resolveOnly: hasArg(forward, "--resolve-only"),
     rerunCommand
   });
+  const next = result.status === "pass" && adapter === "mobile" && result.resolveOnly !== true ? `mm-harness launch ${String(result.platform ?? "ios")} --adapter mobile --target ${shellQuote(target)}` : void 0;
+  const output = next ? { ...result, next } : result;
   if (json) {
-    console.log(JSON.stringify(result, null, 2));
+    console.log(JSON.stringify(output, null, 2));
   } else if (result.status === "pass") {
     const cache = typeof result.cache === "object" && result.cache ? result.cache : void 0;
     const simulator = typeof result.simulator === "object" && result.simulator ? result.simulator : void 0;
@@ -534,6 +544,7 @@ async function handleRunwayInstall(adapter, target, forward, json) {
       const action = result.skipped ? "already provisioned" : "installed Runway app";
       console.error(`\u2713 ${action} for ${adapter} ${result.platform ?? ""} simulator=${simulator?.name ?? "unknown"} cache=${cache?.status ?? "skip"}`);
     }
+    if (next) console.error(`  Next: ${next}`);
   } else {
     console.error(`\u2717 mm-harness install --runway: ${result.error?.message ?? "runway install failed"}
   Next: ${result.error?.userAction ?? rerunCommand}`);
@@ -578,7 +589,8 @@ function harnessSummary(action, adapter, target, status, exitCode, autoDetected,
     // Error contract: every --json failure carries a stable machine code + human
     // message (CLI-SPEC.md §5.1). userAction is included when present so callers
     // can surface the reachable escape without parsing the human message.
-    ...status === "fail" && error ? { error } : {}
+    ...status === "fail" && error ? { error } : {},
+    ...status === "pass" && adapter ? { next: successNext(adapter, action, target) } : {}
   });
 }
 export {

package/dist/json-stream.js

@@ -0,0 +1,57 @@
+class JsonStreamWriter {
+  enabled;
+  command;
+  completed = false;
+  writeLine;
+  constructor(command, enabled, output = process.stdout) {
+    this.command = command;
+    this.enabled = enabled;
+    const write = output.write.bind(output);
+    this.writeLine = (line) => {
+      write(`${line}
+`);
+    };
+  }
+  isolateStdout() {
+    if (!this.enabled) return () => void 0;
+    const original = process.stdout.write;
+    const redirect = ((chunk, encoding, callback) => process.stderr.write(chunk, encoding, callback));
+    process.stdout.write = redirect;
+    return () => {
+      if (process.stdout.write === redirect) process.stdout.write = original;
+    };
+  }
+  emit(event, fields = {}) {
+    if (!this.enabled || this.completed) return;
+    this.writeLine(JSON.stringify({
+      schemaVersion: 1,
+      command: this.command,
+      event,
+      ...fields,
+      ts: (/* @__PURE__ */ new Date()).toISOString()
+    }));
+  }
+  phase(phase, fields = {}) {
+    this.emit("phase", { phase, ...fields });
+  }
+  node(nodeId, action, status) {
+    this.emit("node", { nodeId, action, status });
+  }
+  mutation(mutation) {
+    this.emit("mutation", { mutation });
+  }
+  recovery(code) {
+    this.emit("recovery", { code });
+  }
+  error(error) {
+    this.emit("error", { error });
+  }
+  complete(status, exitCode, fields = {}) {
+    if (!this.enabled || this.completed) return;
+    this.emit("complete", { status, exitCode, ...fields });
+    this.completed = true;
+  }
+}
+export {
+  JsonStreamWriter
+};

package/dist/mm-harness-cli.js

@@ -4,10 +4,17 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { color } from "./cli-color.js";
+import { withCommandJournal } from "./command-journal.js";
+import { JsonStreamWriter } from "./json-stream.js";
 import { handleUpdate, maybeNudge } from "./commands/update.js";
 import { handleCallHelp } from "./commands/call.js";
 import { getAdapterSurface } from "./adapters/surface.js";
 import { detectAdapter } from "./harness.js";
+import {
+  PUBLIC_COMMAND_CONTRACTS,
+  publicCommandNames,
+  validatePublicInvocation
+} from "./command-contract.js";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 globalThis.__MM_HARNESS_WRAPPER__ = true;
 const { main: recipeMain } = await import("./cli.js");
@@ -71,10 +78,11 @@ Example:
     name: "actions",
     summary: "List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).",
     example: "mm-harness actions --adapter mobile",
-    helpText: `mm-harness actions [flags]
+    helpText: `mm-harness actions [query] [flags]
 
   List the action vocabulary + field schemas for the checkout adapter.
 
+  query                              Search names, categories, fields, and descriptions (typo-tolerant)
   --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)
@@ -85,6 +93,7 @@ Example:
 
 Example:
   mm-harness actions --adapter mobile
+  mm-harness actions positions --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
@@ -176,12 +185,29 @@ Example:
   --library <name=path>              Add/override a recipe-library source (repeatable)
   --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
   --json                             Machine-readable output
+  --json-stream                      Line-flushed JSONL progress + terminal event
   --record-video=full-run            Record a video of the run
 
 Example:
   mm-harness run recipe.json --plan --adapter mobile
   mm-harness run recipe.json --adapter extension --artifacts-dir ./out`
   },
+  {
+    name: "last",
+    summary: "Show the last significant command, verdict, timestamps, and evidence paths for this checkout.",
+    example: "mm-harness last --json",
+    helpText: `mm-harness last [flags]
+
+  Read the atomic per-checkout resumability journal. Discovery commands do not
+  replace it, and an interrupted process remains recorded as verdict=running.
+
+  --target <path>                    Checkout path (default: cwd)
+  --runtime-dir <dir>                Runtime dir containing last-command.json
+  --json                             Machine-readable envelope
+
+Example:
+  mm-harness last --json`
+  },
   {
     name: "doctor",
     summary: "Readiness check for a checkout \u2014 no app launch. --fix repairs the overlay/runtime without launching.",
@@ -379,6 +405,7 @@ Example:
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable summary (recovered[] / mutations[] / phase)
+  --json-stream                      Line-flushed JSONL progress + terminal event
 
 Example:
   mm-harness launch ios
@@ -477,6 +504,7 @@ Example:
   --cdp-port <port>                  finalize: CDP port of the running extension
   --extension-dir <path>             finalize: loaded extension dist (e.g. dist/chrome)
   --extension-id-file <path>         finalize: optional file to read/write the resolved extension id
+  --action-manifest <path>           Extension set: override the wallet action manifest
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --device <udid|serial|name>        Mobile only: target this device for sync/set
@@ -491,6 +519,28 @@ Example:
   mm-harness fixtures finalize --fixture wallet-fixture.json --state fixture-state.json --cdp-port 6661 --extension-dir dist/chrome`
   }
 ];
+const PUBLIC_COMMAND_EXAMPLES = Object.fromEntries(
+  REAL.map((command) => [command.name, command.example])
+);
+function assertPublicContractMatchesSurface() {
+  const registered = REAL.map((command) => command.name).sort();
+  const contracted = publicCommandNames().sort();
+  if (registered.join("\n") !== contracted.join("\n")) {
+    throw new Error(
+      `public command contract drift: registered=[${registered.join(", ")}], contracted=[${contracted.join(", ")}]`
+    );
+  }
+  for (const command of REAL) {
+    const registeredAliases = [...command.aliases ?? []].sort();
+    const contractedAliases = [...PUBLIC_COMMAND_CONTRACTS[command.name]?.aliases ?? []].sort();
+    if (registeredAliases.join("\n") !== contractedAliases.join("\n")) {
+      throw new Error(
+        `public command alias contract drift for ${command.name}: registered=[${registeredAliases.join(", ")}], contracted=[${contractedAliases.join(", ")}]`
+      );
+    }
+  }
+}
+assertPublicContractMatchesSurface();
 const RETIRED = [
   {
     name: "live",
@@ -520,7 +570,7 @@ const HELP_GROUPS = [
   {
     title: "PROVE",
     blurb: "run recipes and inspect readiness",
-    commands: ["run", "doctor", "check", "checklist", "recipe-quality"]
+    commands: ["run", "last", "doctor", "check", "checklist", "recipe-quality"]
   },
   {
     title: "RUNTIME OVERLAY",
@@ -643,7 +693,7 @@ for (const command of REAL) {
       process.exit(await handleUpdate(rawArgv.slice(1)));
     }
     const argv = command.name === "actions" && rawArgv.includes("--raw") ? translateActionsRaw(rawArgv) : rawArgv;
-    process.exit(await delegate(argv));
+    process.exit(await withCommandJournal(command.name, rawArgv, () => delegate(argv)));
   });
 }
 const HIDDEN = [
@@ -696,10 +746,67 @@ function isCallActionHelp(argv) {
   const scope = divider === -1 ? argv : argv.slice(0, divider);
   return scope.includes("--help") || scope.includes("-h");
 }
+function jsonRequestedBeforePassthrough(argv) {
+  const divider = argv.indexOf("--");
+  const scope = divider === -1 ? argv : argv.slice(0, divider);
+  return scope.some((argument) => argument === "--json" || argument.startsWith("--json="));
+}
+function jsonStreamRequestedBeforePassthrough(argv) {
+  const divider = argv.indexOf("--");
+  const scope = divider === -1 ? argv : argv.slice(0, divider);
+  return scope.includes("--json-stream");
+}
+function emitUsageError(error, json, jsonStream) {
+  if (jsonStream) {
+    const stream = new JsonStreamWriter(error.command, true);
+    stream.error({ code: error.code, message: error.message, userAction: error.userAction });
+    stream.complete("fail", 2);
+  } else if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: error.command,
+          status: "fail",
+          error: {
+            code: error.code,
+            message: error.message,
+            userAction: error.userAction
+          },
+          exitCode: 2
+        },
+        null,
+        2
+      )}
+`
+    );
+  } else {
+    const scope = error.command === "mm-harness" ? "" : ` ${error.command}`;
+    process.stderr.write(`\u2717 mm-harness${scope}: ${error.message}
+  Next: ${error.userAction}
+`);
+  }
+  process.exit(2);
+}
 if (rawArgv.length === 0) {
   process.stdout.write(groupedHelp());
   process.exit(0);
 }
+const preflightBypass = /* @__PURE__ */ new Set([
+  ...HIDDEN,
+  "completions",
+  ...RETIRED.map((command) => command.name)
+]);
+if (!preflightBypass.has(rawArgv[0] ?? "")) {
+  const usageError = validatePublicInvocation(rawArgv, PUBLIC_COMMAND_EXAMPLES);
+  if (usageError) {
+    emitUsageError(
+      usageError,
+      jsonRequestedBeforePassthrough(rawArgv),
+      jsonStreamRequestedBeforePassthrough(rawArgv)
+    );
+  }
+}
 if (hasPassthroughHelp(rawArgv)) {
   process.exit(await delegate(rawArgv));
 }

package/dist/runner.js

@@ -58,7 +58,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
   const logger = options.quietStdout ? new console.Console(process.stderr) : console;
   return createRecipeRunner({
     actionManifest,
-    adapters: [...core, ...ui, ...lifecycle, ...custom],
+    adapters: withActionProgress([...core, ...ui, ...lifecycle, ...custom], options.onActionEvent),
     logger,
     recording: {
       targetProvider: createMetaMaskRecordingTargetProvider(adapter)
@@ -76,6 +76,36 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     }
   });
 }
+function withActionProgress(adapters, onActionEvent) {
+  if (!onActionEvent) return adapters;
+  return adapters.map((entry) => ({
+    ...entry,
+    async execute(node, context) {
+      const event = { nodeId: context.nodeId, action: entry.action };
+      const reportProgress = !isAutomaticHudProgress(entry.action, node, context.nodeId);
+      if (reportProgress) onActionEvent({ ...event, status: "running" });
+      try {
+        const result = await entry.execute(node, context);
+        if (reportProgress) {
+          onActionEvent({ ...event, status: result.status === "fail" ? "failed" : "passed" });
+        }
+        return result;
+      } catch (error) {
+        if (reportProgress) onActionEvent({ ...event, status: "failed" });
+        throw error;
+      }
+    }
+  }));
+}
+function isAutomaticHudProgress(action, node, nodeId) {
+  if (action !== "app.hud" || node === null || typeof node !== "object" || Array.isArray(node)) {
+    return false;
+  }
+  const payload = node;
+  if (typeof payload.action_name === "string") return true;
+  const progress = payload.progress;
+  return nodeId === "recipe-complete" && progress !== null && typeof progress === "object" && !Array.isArray(progress) && progress.complete === true;
+}
 function mobileSourceAwareLifecycleAdapters(adapter, lifecycle) {
   if (adapter !== "mobile") return lifecycle;
   return lifecycle.map((entry) => ({
@@ -120,5 +150,6 @@ export {
   createMetaMaskExtensionRunner,
   createMetaMaskMobileRunner,
   createMetaMaskRunner,
+  isAutomaticHudProgress,
   mobileSourceAwareLifecycleAdapters
 };

package/docs/CLI-ERGONOMICS-AUDIT.md

@@ -0,0 +1,32 @@
+<!-- Generated by scripts/generate-cli-ergonomics-audit.mjs. Do not edit by hand. -->
+# CLI ergonomics audit
+
+This matrix tracks the public command surface. “Covered” means the shared preflight contract and
+`tests/contract/cli-teaching-errors.test.sh` exercise the behavior without dispatching runtime work.
+Runtime recovery is claimed only where command-specific failures return a stable `userAction`.
+Success hints are intentionally limited to lifecycle transitions with one truthful next command;
+discovery, read-only, and terminal evidence commands do not invent one. ID prefix support is N/A
+unless a command displays a shortened ID that another command accepts.
+
+| Command | Bad flag | First feedback | `--json` recovery | Success next step | Displayed ID prefix |
+|---|---|---|---|---|---|
+| `status` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | structured `next` | N/A: command displays no shortened ID |
+| `checklist` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage errors covered; no runtime recovery claim | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `actions` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `stop` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | launch `next` when the adapter has one unambiguous launch | N/A: command displays no shortened ID |
+| `call` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `flows` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage errors covered; no runtime recovery claim | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `run` | covered: `CLI_UNKNOWN_OPTION` | TTY intent before slow work; machine output clean | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `last` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `doctor` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `check` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `recipe-quality` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `provision` | covered: `CLI_UNKNOWN_OPTION` | TTY intent before slow work; machine output clean | usage + runtime `error.code/message/userAction` | launch `next` after install | N/A: command displays no shortened ID |
+| `install` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | verify `next` | N/A: command displays no shortened ID |
+| `verify` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | status `next` | N/A: command displays no shortened ID |
+| `cleanup` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | install `next` | N/A: command displays no shortened ID |
+| `launch` | covered: `CLI_UNKNOWN_OPTION` | TTY intent before slow work; machine output clean | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `logs` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `debug` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage errors covered; no runtime recovery claim | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `update` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `fixtures` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |

package/docs/CLI-ERGONOMICS-HUMAN-QA.md

@@ -0,0 +1,104 @@
+# CLI ergonomics human QA
+
+Use this short pass after installing a release candidate. Automated contracts remain the release gate; this checklist confirms the experience in a real shell and checkout.
+
+## Setup
+
+```bash
+export TARGET=/absolute/path/to/a/metamask-checkout
+export ADAPTER=extension # extension, mobile, or core
+mm-harness --version
+mm-harness doctor --adapter "$ADAPTER" --target "$TARGET" --json | jq .status
+```
+
+Expected: the intended version is printed and `doctor` returns parseable JSON. Resolve required doctor failures before continuing.
+
+## 1. Teaching errors
+
+```bash
+out="$(mm-harness actions --categoriez --adapter "$ADAPTER" --json 2>/dev/null || true)"
+jq '.error | {code, message, userAction}' <<<"$out"
+```
+
+Expected: `code` is stable, the message names the bad flag and valid options, and `userAction` suggests the closest valid invocation.
+
+## 2. In-tool discovery
+
+```bash
+mm-harness actions --adapter "$ADAPTER" --categories
+mm-harness actions status --adapter "$ADAPTER"
+mm-harness actions --action app.status --adapter "$ADAPTER" --json | jq '{actions, relatedActions}'
+```
+
+Expected: category output is compact, fuzzy search is bounded, and action detail includes related actions when available. A missing example action should produce a teaching error, not silent output.
+
+## 3. Machine-output cleanliness and recovery
+
+```bash
+out="$(mm-harness call definitely.not.an.action --adapter "$ADAPTER" --target "$TARGET" --json 2>/dev/null || true)"
+jq '{status, error}' <<<"$out"
+```
+
+Expected: stdout is one parseable JSON document with `error.code`, `error.message`, and `error.userAction`; it contains no spinner, banner, or human-only glyph.
+
+## 4. Immediate human feedback
+
+Run the platform-appropriate launch in an interactive terminal:
+
+```bash
+# Extension
+mm-harness launch --adapter extension --target "$TARGET"
+
+# Mobile: choose the intended platform
+mm-harness launch ios --target "$TARGET"
+# mm-harness launch android --target "$TARGET"
+```
+
+Expected: intent/progress appears immediately, long work continues to report progress, and the app becomes ready. Redirected or `--json` stdout stays decoration-free.
+
+## 5. Lifecycle next step
+
+For Extension:
+
+```bash
+mm-harness stop --adapter extension --target "$TARGET" --json | jq '{status, next}'
+```
+
+Expected: `next` is a target-scoped launch command. Mobile `stop` intentionally omits `next` because Metro does not identify whether iOS or Android should be relaunched.
+
+## 6. Resume after interruption
+
+```bash
+mm-harness last --target "$TARGET" --json | jq '.last | {command, args, verdict, evidencePaths, startedAt, finishedAt}'
+```
+
+Expected: the last operation can be reconstructed without rerunning it, including its arguments, verdict, evidence paths, and timestamps.
+
+## 7. Recipe proof smoke
+
+```bash
+mm-harness run --list --adapter "$ADAPTER" --json | jq '{actions: .actions[0:5], flows: .flows[0:5]}'
+export RECIPE=replace-with-a-safe-recipe-name-or-path
+export ARTIFACTS_DIR="$(mktemp -d)"
+mm-harness run "$RECIPE" --plan --adapter "$ADAPTER" --target "$TARGET" --json | jq '{status, plan}'
+mm-harness run "$RECIPE" --adapter "$ADAPTER" --target "$TARGET" --artifacts-dir "$ARTIFACTS_DIR"
+```
+
+Expected: the plan validates before execution; the final result identifies evidence paths and `mm-harness last --json` records the run.
+
+Optional JSONL check:
+
+```bash
+mm-harness run "$RECIPE" --adapter "$ADAPTER" --target "$TARGET" --artifacts-dir "$ARTIFACTS_DIR-stream" --json-stream | jq -c .
+```
+
+Expected: complete JSON objects arrive line by line while the run is active.
+
+## Cleanup
+
+```bash
+[ "$ADAPTER" = core ] || mm-harness stop --adapter "$ADAPTER" --target "$TARGET"
+mm-harness status --target "$TARGET" --json | jq .
+```
+
+Record the harness version, checkout SHA, adapter/platform, failed command, exit code, and JSON envelope for any discrepancy.

package/docs/CLI-SPEC.md

@@ -379,7 +379,7 @@ Installs the cached Runway iOS dev client onto a prepared mobile slot. It does n
 > recipe) validate fully; the execute path relies on the engine's own manifest
 > validation. Tagged in code (`runner/src/cli.ts` `validateRecipeAdapterAware`).
 
-**Phase state-machine:** `resolve → install → healthcheck → recover → validate → launch → execute` (phase reported in `--json` as `phase`; `--json-stream` emits one event per phase transition).
+**Execution phases:** `resolve → validate → install → healthcheck → execute`, with `recover` emitted only when bounded recovery actually runs. `--json-stream` emits each transition as it occurs.
 
 **Auto-ensure overlay:** `run` checks for the runtime overlay before executing (phase: `install`). If missing: installs it inline with a one-line notice, then proceeds. **First-install overlay notice:** on the very first install for this checkout, prints `installed mm-harness overlay v<version> → <path>` to stderr in human mode; in `--json` it appears solely as `mutations[]`. Use `--heal=off` to disable all auto-install and healing.
 
@@ -389,6 +389,14 @@ Installs the cached Runway iOS dev client onto a prepared mobile slot. It does n
 **Outputs:** `summary.json`, `trace.json`, `artifact-manifest.json`, screenshots/logs under `--artifacts-dir`.
 **Maps-to:** A:`run` (ROUTES-NOW); C/D:`run` (ABSORB-LATER — supply the auto adapter+artifacts defaults the typed CLI lacks).
 
+## `last` (resumability inspect verb)
+
+**Synopsis:** `mm-harness last [--target <checkout>] [--runtime-dir <dir>] [--json]`
+
+Reads `last-command.json`, the atomic per-checkout journal written before and after significant runtime/proof commands. The record contains redacted args, `running|pass|fail` verdict, exit code, explicit evidence/output paths, and start/finish timestamps. A process killed between writes remains `running`, allowing an agent to inspect rather than repeat side effects. Read-only discovery commands do not replace the record, and `last` never journals itself.
+
+The file is mode `0600`; password, credential, auth, mnemonic, private-key, seed/SRP, secret, and token values are redacted before the first write. `--json` returns `{ command:"last", target, journalPath, status, exitCode, last }`. Missing or invalid state returns `LAST_NOT_FOUND` with an exact `userAction`.
+
 ## `doctor` (ROUTES-NOW → PROVE inspect verb)
 
 Readiness check for a checkout without launching the app. Doctor is the single place to understand the full slot context — **no hunting for files**. It also absorbs the retired `manifest` verb's validation function: the readiness checks include manifest well-formedness (schema valid, no unknown action references) and report the manifest path + protocol version in the explain-my-setup section. It includes three grounded sub-sections:
@@ -561,9 +569,9 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
 
 ### `actions` (ROUTES-NOW → DISCOVER verb)
 
-**Synopsis:** `mm-harness actions --adapter <p> [--json] [--categories | --category <name> | --action <name>]`
+**Synopsis:** `mm-harness actions [query] --adapter <p> [--json] [--categories | --category <name> | --action <name>]`
 
-**PRIMARY (agent):** `mm-harness actions --adapter mobile --categories --json`, then one `--category` or `--action` query.
+**PRIMARY (agent):** search from the task vocabulary, for example `mm-harness actions positions --adapter mobile --json`, then request one full `--action` schema. Use `--categories` only when the task does not provide a useful search term.
 
 **`--json` output shape** (grounded — `actions --adapter core --json` confirmed):
 ```json
@@ -581,7 +589,7 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
   ]
 }
 ```
-`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.
+`kind` is `"official"` (engine built-ins) or `"custom"` (MetaMask adapter actions). `category` uses manifest metadata when present, then stable generic groups for protocol primitives and durable action namespaces (`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,...>`.
 
@@ -595,7 +603,7 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
 | `--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 keyword search across descriptions or fields. Flow discovery remains separate.
+The optional positional `query` searches names, categories, fields, and descriptions with typo tolerance. A single `--action` detail also returns up to five compact `relatedActions` names. Flow discovery remains separate.
 **Exit:** 0 / non-zero on engine error.
 **Maps-to:** A:`actions` (ROUTES-NOW); C/D:`actions` (ABSORB-LATER).
 
@@ -901,6 +909,36 @@ Every failure in `--json` mode produces an `error` field at the top level:
 | `retryable` | boolean | `true` = same command may succeed on retry; `false` = agent must change inputs or escalate |
 | `userAction` | string \| null | Exact next command or manual step |
 
+Successful lifecycle transitions may add a top-level `next` command when exactly
+one follow-up is correct (for example install → verify or stop → relaunch).
+Discovery, read-only, and terminal evidence commands intentionally omit it rather
+than inventing guidance. Agents must therefore treat `next` as optional.
+
+Public command-grammar failures happen before runtime dispatch and always exit 2.
+Their machine envelope is deliberately smaller and stable: agents branch on
+`error.code`, never on prose.
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "actions",
+  "status": "fail",
+  "error": {
+    "code": "CLI_UNKNOWN_OPTION",
+    "message": "unknown option '--categoriez'. Valid options for mm-harness actions: ...",
+    "userAction": "Did you mean '--categories' instead of '--categoriez'? Try: mm-harness actions --adapter mobile"
+  },
+  "exitCode": 2
+}
+```
+
+Stable grammar codes are `CLI_UNKNOWN_COMMAND`, `CLI_UNKNOWN_OPTION`,
+`CLI_MISSING_OPTION_VALUE`, `CLI_INVALID_OPTION_VALUE`,
+`CLI_MISSING_POSITIONAL`, `CLI_INVALID_POSITIONAL`,
+`CLI_EXCESS_POSITIONAL`, and `CLI_UNEXPECTED_PASSTHROUGH`. Every public
+command is tracked in `docs/CLI-ERGONOMICS-AUDIT.md`; private adapter leaves keep
+their own grammar behind explicit `--` passthrough.
+
 ## §5.2 Stable recovery codes (`recovered[]`)
 
 `recovered[]` in `--json` output lists what was healed. These are stable enum values — not prose, safe to match in agent code:
@@ -941,18 +979,20 @@ Every `--json` response includes `mutations[]` listing all side effects the comm
 
 ## §5.4 Phase state-machine
 
-Every `--json` response includes a `phase` field reflecting the last completed phase. `--json-stream` emits one event per transition. Agents can detect exactly where a failure occurred.
+Summary `--json` responses retain their command-specific `phase` field. `--json-stream` emits transitions as they occur, so an agent can distinguish active work from a stalled command.
 
 **`run` phases:**
 ```
-resolve → install → healthcheck → recover → validate → launch → execute
+resolve → validate → install → healthcheck → execute
 ```
 
 **`launch` phases:**
 ```
-resolve → install → healthcheck → recover → launch → verify
+resolve → install → healthcheck → launch → verify
 ```
 
+`recover` is conditional and appears immediately before a bounded recovery attempt; `verify` appears only for `launch --verify`.
+
 | Phase | What happens |
 |---|---|
 | `resolve` | Recipe/target/adapter resolved; library sources loaded |
@@ -966,20 +1006,20 @@ resolve → install → healthcheck → recover → launch → verify
 
 ## §5.5 JSONL event stream (`--json-stream`)
 
-`--json-stream` emits one JSON object per line on stdout as the command progresses. Parseable with `jq -R 'fromjson?'`. Schema is versioned via `schemaVersion`.
+`run` and `launch` accept `--json-stream`. Each progress event is written as one complete JSON object plus a newline, so a piped reader can parse it before the command finishes. Schema is versioned via `schemaVersion`; every event also carries `command` and `ts`.
+
+Stream mode owns stdout: existing human or subprocess output is routed to stderr. If both `--json` and `--json-stream` are supplied, stream mode wins. The existing summary `--json` bytes are unchanged when stream mode is absent.
 
 ```jsonl
-{"schemaVersion":1,"event":"phase","phase":"resolve","ts":"2026-07-02T10:00:00.000Z"}
-{"schemaVersion":1,"event":"phase","phase":"install","ts":"2026-07-02T10:00:00.100Z"}
-{"schemaVersion":1,"event":"mutation","mutation":{"type":"file","path":"/...","action":"created"},"ts":"..."}
-{"schemaVersion":1,"event":"phase","phase":"validate","ts":"..."}
-{"schemaVersion":1,"event":"phase","phase":"execute","ts":"..."}
-{"schemaVersion":1,"event":"node","index":0,"action":"metamask.wallet.unlock","status":"running","ts":"..."}
-{"schemaVersion":1,"event":"node","index":0,"action":"metamask.wallet.unlock","status":"passed","ts":"..."}
-{"schemaVersion":1,"event":"complete","status":"pass","exitCode":0,"recovered":[],"mutations":[...],"ts":"..."}
+{"schemaVersion":1,"command":"run","event":"phase","phase":"resolve","ts":"2026-07-02T10:00:00.000Z"}
+{"schemaVersion":1,"command":"run","event":"phase","phase":"validate","ts":"2026-07-02T10:00:00.100Z"}
+{"schemaVersion":1,"command":"run","event":"phase","phase":"execute","ts":"..."}
+{"schemaVersion":1,"command":"run","event":"node","nodeId":"unlock","action":"metamask.wallet.unlock","status":"running","ts":"..."}
+{"schemaVersion":1,"command":"run","event":"node","nodeId":"unlock","action":"metamask.wallet.unlock","status":"passed","ts":"..."}
+{"schemaVersion":1,"command":"run","event":"complete","status":"pass","exitCode":0,"reportPath":"/.../report.md","artifactManifestPath":"/.../artifact-manifest.json","recovered":[],"mutations":[],"ts":"..."}
 ```
 
-Event types: `phase` · `node` · `mutation` · `recovery` · `error` · `complete`. The terminal `complete` event always appears (even on failure) so agents have a clean sentinel.
+Event types: `phase` · `node` · `mutation` · `recovery` · `error` · `complete`. Node events use stable recipe `nodeId` values rather than an inferred numeric order. Exactly one terminal `complete` event is last on normal success or handled failure, giving agents a clean sentinel and compact evidence paths without repeating the full run result.
 
 ## §5.6 Exit code taxonomy