@deeeed/metamask-harness 0.2.0 → 0.3.1

package/{runner/src → src}/harness.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from './paths.ts';
 import type { MetaMaskRecipeAdapter } from './types.ts';
+import { prepareMobile } from './adapters/mobile/prepare.ts';
 
 // The `harness` command moves the recipe-harness skill's runner-locate + dispatch
 // bash (resolve-runner-source.sh + recipe-harness.sh dispatch_adapter_action)
@@ -155,6 +156,12 @@ function parseHarnessArgs(args: string[]): ParsedHarnessArgs {
 // Mirror of scripts/lib/cli-common.sh detect_adapter for the auto-detect path.
 // Exported so `doctor` shares the exact same detect-from-target logic as the
 // overlay commands (verify/install/cleanup) — one auto-detect story, no drift.
+// Both escapes from a failed repo-type detection: where to run it (checkout/target)
+// and how to force it (adapter). A single source so every detect-failure teaches
+// the same reachable next step.
+export const ADAPTER_DETECT_NEXT =
+  'cd into a MetaMask checkout or pass --target <path>, or force it with --adapter <mobile|extension|core>';
+
 export function detectAdapter(target: string): MetaMaskRecipeAdapter | undefined {
   let remote = '';
   try {
@@ -277,11 +284,14 @@ function resolveEntry(base: string, candidates: string[], mode: 'exec' | 'file')
 
 // Content of an installed overlay's runner source pointer, if present. Command
 // substitution in the skill stripped trailing newlines, so trim here too.
+// Validates the path exists so stale stamps (e.g. from a renamed package dir)
+// fall back to the current runnerDir rather than producing ENOENT at cleanup.
 function installedRunnerSource(target: string, adapter: MetaMaskRecipeAdapter): string | undefined {
   const pointer = path.join(recipeHarnessPath(target, adapter), 'runner', '.runner-source');
   if (!fs.existsSync(pointer)) return undefined;
   const value = fs.readFileSync(pointer, 'utf8').trim();
-  return value || undefined;
+  if (!value || !fs.existsSync(value)) return undefined;
+  return value;
 }
 
 function isExecutable(file: string): boolean {
@@ -299,15 +309,15 @@ interface HarnessDispatch {
 }
 
 const INJECT_CANDIDATES: Record<MetaMaskRecipeAdapter, { entry: string; fallback: string }> = {
-  mobile: { entry: 'orchestration/mobile/inject.sh', fallback: 'scripts/inject-mobile-harness.sh' },
-  extension: { entry: 'orchestration/extension/inject.mjs', fallback: 'scripts/inject-extension-harness.mjs' },
-  core: { entry: 'orchestration/core/inject.sh', fallback: 'scripts/inject-core-harness.sh' },
+  mobile: { entry: 'adapters/mobile/inject.sh', fallback: 'scripts/inject-mobile-harness.sh' },
+  extension: { entry: 'adapters/extension/inject.mjs', fallback: 'scripts/inject-extension-harness.mjs' },
+  core: { entry: 'adapters/core/inject.sh', fallback: 'scripts/inject-core-harness.sh' },
 };
 
 const CLEANUP_CANDIDATES: Record<MetaMaskRecipeAdapter, { entry: string; fallback: string }> = {
-  mobile: { entry: 'orchestration/mobile/cleanup.sh', fallback: 'scripts/cleanup-mobile-harness.sh' },
-  extension: { entry: 'orchestration/extension/cleanup.mjs', fallback: 'scripts/cleanup-extension-harness.mjs' },
-  core: { entry: 'orchestration/core/cleanup.sh', fallback: 'scripts/cleanup-core-harness.sh' },
+  mobile: { entry: 'adapters/mobile/cleanup.sh', fallback: 'scripts/cleanup-mobile-harness.sh' },
+  extension: { entry: 'adapters/extension/cleanup.mjs', fallback: 'scripts/cleanup-extension-harness.mjs' },
+  core: { entry: 'adapters/core/cleanup.sh', fallback: 'scripts/cleanup-core-harness.sh' },
 };
 
 // Resolve the exact command + fixed prefix args to exec, mirroring
@@ -337,7 +347,7 @@ function resolveHarnessDispatch(
   }
 
   if (adapter === 'core' && action === 'verify') {
-    const delegate = path.join(recipeHarnessPath(target, 'core'), 'runner', 'bin', 'metamask-recipe');
+    const delegate = path.join(recipeHarnessPath(target, 'core'), 'runner', 'bin', 'mm-harness');
     if (!isExecutable(delegate)) {
       return {
         error:
@@ -351,19 +361,98 @@ function resolveHarnessDispatch(
   }
 
   // mobile/extension live|verify: prefer the installed helper, else the runner's
-  // own orchestration/runner/scripts helper (first executable candidate wins).
+  // own adapters/scripts helper (first executable candidate wins).
   const installedScript = path.join(recipeHarnessPath(target, adapter), 'scripts', `${action}.sh`);
   if (isExecutable(installedScript)) {
     return { command: installedScript, prefixArgs: [] };
   }
   const command = resolveEntry(
     runnerDir,
-    [`orchestration/${adapter}/${action}.sh`, `runner/${adapter}/${action}.sh`, `scripts/${adapter}/${action}.sh`],
+    [`adapters/${adapter}/${action}.sh`, `scripts/${adapter}/${action}.sh`],
     'exec',
   );
   return { command, prefixArgs: [] };
 }
 
+// Mobile live: prepare device in-process then run the verify leaf.
+// Replaces the retired live.sh → launch.sh → mm-harness-mobile-prepare chain.
+// Control flows down only: TS calls prepareMobile(), then spawns verify.sh.
+async function handleMobileLive(
+  target: string,
+  forwardArgs: string[],
+  json: boolean,
+  autoDetected: boolean,
+): Promise<number> {
+  const platform = argValue(forwardArgs, '--platform') ?? 'ios';
+  const watcherPortStr = argValue(forwardArgs, '--watcher-port') ?? process.env.WATCHER_PORT;
+  const watcherPort = watcherPortStr ? parseInt(watcherPortStr, 10) : undefined;
+  const start = Date.now();
+
+  if (!json) {
+    const detected = autoDetected ? ', auto-detected' : '';
+    console.error(`→ live (mobile${detected}) — target: ${target}`);
+  }
+
+  const prepResult = await prepareMobile(target, { platform, json, watcherPort });
+  if (prepResult.status !== 0) {
+    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+    if (json) {
+      console.log(
+        harnessSummary('live', 'mobile', target, 'fail', prepResult.status, autoDetected, {
+          code: 'MOBILE_PREPARE_FAILED',
+          message: `mobile prepare failed (exit ${prepResult.status})`,
+          userAction: failureHint('mobile', 'live'),
+        }),
+      );
+    } else {
+      console.error(
+        `✗ live mobile failed (exit ${prepResult.status}, ${elapsed}s)\n  ${failureHint('mobile', 'live')}`,
+      );
+    }
+    return prepResult.status;
+  }
+
+  // Verify leaf: --no-auto-start because launch already started the app.
+  const installedVerify = path.join(recipeHarnessPath(target, 'mobile'), 'scripts', 'verify.sh');
+  const verifySh = isExecutable(installedVerify)
+    ? installedVerify
+    : resolveEntry(runnerDir, ['adapters/mobile/verify.sh', 'scripts/mobile/verify.sh'], 'exec');
+
+  const verifyArgs = hasArg(forwardArgs, '--no-auto-start')
+    ? [...forwardArgs]
+    : ['--no-auto-start', ...forwardArgs];
+
+  const result = spawnSync(verifySh, verifyArgs, {
+    stdio: json ? ['inherit', 2, 'inherit'] : 'inherit',
+    env: process.env,
+  });
+  const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+  const exitCode = result.status ?? 1;
+
+  if (json) {
+    console.log(
+      harnessSummary(
+        'live',
+        'mobile',
+        target,
+        exitCode === 0 ? 'pass' : 'fail',
+        exitCode,
+        autoDetected,
+        exitCode === 0
+          ? undefined
+          : { code: 'MOBILE_VERIFY_FAILED', message: `mobile live verify failed (exit ${exitCode})`, userAction: failureHint('mobile', 'live') },
+      ),
+    );
+  } else if (exitCode === 0) {
+    console.error(`✓ live mobile passed (${elapsed}s)`);
+  } else {
+    console.error(
+      `✗ live mobile failed (exit ${exitCode}, ${elapsed}s)\n  ${failureHint('mobile', 'live')}`,
+    );
+  }
+  return exitCode;
+}
+
 export async function handleHarness(argv: string[]): Promise<number> {
   const action = argv[0];
   if (!action || action === '-h' || action === '--help') {
@@ -388,15 +477,15 @@ export async function handleHarness(argv: string[]): Promise<number> {
       // parsedAdapter is string|undefined here; not yet validated as a real
       // adapter, so pass undefined rather than forwarding a garbage string.
       const detectError = adapter
-        ? { code: 'UNSUPPORTED_PLATFORM', message: `unsupported platform: ${adapter}` }
-        : { code: 'ADAPTER_DETECTION_FAILED', message: `could not detect the MetaMask repo type for ${target}` };
+        ? { code: 'UNSUPPORTED_PLATFORM', message: `unsupported platform: ${adapter}`, userAction: 'pass --adapter <mobile|extension|core> to specify a supported adapter' }
+        : { code: 'ADAPTER_DETECTION_FAILED', message: `could not detect the MetaMask repo type for ${target}`, userAction: ADAPTER_DETECT_NEXT };
       console.log(harnessSummary(harnessAction, undefined, target, 'fail', 2, false, detectError));
     } else {
       harnessUsage();
       console.error(
         adapter
           ? `\n✗ unsupported platform: ${adapter}`
-          : `\n✗ could not detect the MetaMask repo type for ${target}\n  Next: pass --platform mobile|extension|core`,
+          : `\n✗ could not detect the MetaMask repo type for ${target}\n  Next: ${ADAPTER_DETECT_NEXT}`,
       );
     }
     return 2;
@@ -407,6 +496,7 @@ export async function handleHarness(argv: string[]): Promise<number> {
         harnessSummary(harnessAction, adapter, target, 'fail', 2, parsedAdapter === undefined, {
           code: 'UNSUPPORTED_ACTION',
           message: `${harnessAction} is not supported for ${adapter} (core supports install, verify, cleanup).`,
+          userAction: 'run mm-harness doctor to see which actions are supported for this adapter',
         }),
       );
     } else {
@@ -425,6 +515,11 @@ export async function handleHarness(argv: string[]): Promise<number> {
     forwardArgs = applyExtensionRuntimeEnv(target, harnessAction, forwardArgs);
   }
 
+  // Mobile live is orchestrated in-process (prepareMobile → verify.sh leaf).
+  if (adapter === 'mobile' && harnessAction === 'live') {
+    return handleMobileLive(target, forwardArgs, json, autoDetected);
+  }
+
   const dispatch = resolveHarnessDispatch(adapter, harnessAction, target);
   if ('error' in dispatch) {
     if (json) {
@@ -432,6 +527,9 @@ export async function handleHarness(argv: string[]): Promise<number> {
         harnessSummary(harnessAction, adapter, target, 'fail', 1, autoDetected, {
           code: 'DISPATCH_UNAVAILABLE',
           message: dispatch.error,
+          // The dispatch error embeds "Next: <hint>" — extract it so --json consumers
+          // get a clean programmatic escape without parsing the human message.
+          userAction: dispatch.error.split('\nNext: ')[1] ?? 'run mm-harness install to complete setup, then retry',
         }),
       );
     } else {
@@ -460,6 +558,7 @@ export async function handleHarness(argv: string[]): Promise<number> {
         harnessSummary(harnessAction, adapter, target, 'fail', 1, autoDetected, {
           code: 'HARNESS_SPAWN_FAILED',
           message: `${harnessAction} ${adapter} could not start: ${result.error.message}`,
+          userAction: failureHint(adapter, harnessAction),
         }),
       );
     } else {
@@ -480,7 +579,7 @@ export async function handleHarness(argv: string[]): Promise<number> {
         autoDetected,
         exitCode === 0
           ? undefined
-          : { code: 'HARNESS_FAILED', message: `${harnessAction} ${adapter} failed (exit ${exitCode})` },
+          : { code: 'HARNESS_FAILED', message: `${harnessAction} ${adapter} failed (exit ${exitCode})`, userAction: failureHint(adapter, harnessAction) },
       ),
     );
   } else if (exitCode === 0) {
@@ -491,6 +590,9 @@ export async function handleHarness(argv: string[]): Promise<number> {
   return exitCode;
 }
 
+// userAction is required whenever an error object is present so every --json
+// failure carries a machine-readable escape path — parallel to the `usageOut`
+// enforcement on the CLI layer. Omitting userAction is a compile-time error.
 function harnessSummary(
   action: HarnessAction,
   adapter: MetaMaskRecipeAdapter | undefined,
@@ -498,7 +600,7 @@ function harnessSummary(
   status: 'pass' | 'fail',
   exitCode: number,
   autoDetected: boolean,
-  error?: { code: string; message: string },
+  error?: { code: string; message: string; userAction: string },
 ): string {
   return JSON.stringify({
     schemaVersion: 1,
@@ -510,7 +612,8 @@ function harnessSummary(
     status,
     exitCode,
     // Error contract: every --json failure carries a stable machine code + human
-    // message (CLI-SPEC.md §5.1).
+    // 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 } : {}),
   });
 }

package/{runner/src → src}/heal-bounds.ts

@@ -7,6 +7,7 @@
 
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import path from 'node:path';
 
 import { handleHarness } from './harness.ts';
 import { recipeHarnessPath, recipeRuntimePath } from './paths.ts';
@@ -54,6 +55,24 @@ function overlayPresent(target: string, adapter: MetaMaskRecipeAdapter): boolean
   }
 }
 
+// Validates that the installed overlay's runner-source stamp points to an existing
+// runner directory whose binary is still present. Two failure modes are detected:
+//   1. Stale stamp — runner dir moved or renamed since install (dir absent).
+//   2. Stale exec target — runner dir exists but its bin/mm-harness was removed
+//      (e.g. the package was unlinked/purged inside an otherwise-live dir).
+// Either way the delegate binary will fail to exec; treat the overlay as absent
+// so auto-ensure re-installs it from the current runner.
+function overlayDelegateValid(target: string, adapter: MetaMaskRecipeAdapter): boolean {
+  if (adapter === 'core') return true;
+  const pointer = path.join(recipeHarnessPath(target, adapter), 'runner', '.runner-source');
+  if (!fs.existsSync(pointer)) return true; // no stamp = running from local runner, valid
+  const runnerPath = fs.readFileSync(pointer, 'utf8').trim();
+  if (!Boolean(runnerPath) || !fs.existsSync(runnerPath)) return false;
+  // Runner dir is present; verify the binary inside still exists — the directory
+  // can survive a package removal while the binary inside is deleted.
+  return fs.existsSync(path.join(runnerPath, 'bin', 'mm-harness'));
+}
+
 // Auto-ensure the runtime overlay (install phase). Missing + heal != off →
 // install inline, emit a first-install notice to stderr, and record the mutation.
 // heal === off disables auto-install (repro-preserving); we proceed and let the
@@ -67,7 +86,7 @@ export async function ensureOverlay(
 ): Promise<{ ok: boolean; error?: string }> {
   // core is headless — the engine path used by run/call needs no launch overlay.
   if (adapter === 'core') return { ok: true };
-  if (overlayPresent(target, adapter)) return { ok: true };
+  if (overlayPresent(target, adapter) && overlayDelegateValid(target, adapter)) return { ok: true };
   if (heal === 'off') return { ok: true };
 
   const installBin = process.env.MM_HARNESS_INSTALL_BIN;

package/src/index.ts

@@ -0,0 +1,15 @@
+// Keep the package entrypoint narrow: runner factory, manifest, doctor, and the
+// path/import helpers that library actions are allowed to consume (R9 — no
+// deep-importing src internals past this file).
+export { createDoctorReport } from './doctor.ts';
+export { loadActionManifest, validateManifest } from './manifest.ts';
+export { createMetaMaskExtensionRunner, createMetaMaskMobileRunner, createMetaMaskRunner } from './runner.ts';
+export type { CreateMetaMaskRunnerOptions, MetaMaskDoctorReport, MetaMaskRecipeAdapter } from './types.ts';
+export {
+  extensionIdPath,
+  importRecipeHarnessRuntimeBrowserExtension,
+  importRecipeHarnessRuntimeCdp,
+  recipeHarnessPath,
+  walletFixturePath,
+} from './paths.ts';
+export { captureActiveRecipeRecordingSnapshot } from './run-recording.ts';

package/{runner/src → src}/live-adapter-contract.ts

@@ -223,7 +223,7 @@ export async function runLiveAdapterScript({ platform, action, node, context }:
   const script = await resolveLiveAdapter(platform, action);
   if (!script) return null;
 
-  const tempDir = await mkdtemp(path.join(os.tmpdir(), 'metamask-recipe-live-adapter-'));
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), 'mm-harness-live-adapter-'));
   const inputPath = path.join(tempDir, 'input.json');
   const outputPath = path.join(tempDir, 'output.json');
   const input = {

package/{runner/src → src}/mm-harness-cli.ts

@@ -12,8 +12,10 @@ import { fileURLToPath } from 'node:url';
 
 import { Command } from 'commander';
 
-// runner root (…/runner) → its parent is the package root that holds scripts/.
-const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+import { handleUpdate, maybeNudge } from './commands/update.ts';
+
+// …/src → its parent is the package root that holds scripts/.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
 // Signal cli.ts NOT to auto-run its own dispatch when we import it below: we
 // reuse its `main` in-process. Must be set BEFORE the dynamic import runs the
@@ -245,6 +247,26 @@ Example:
   mm-harness debug
   mm-harness debug --worker`,
   },
+  {
+    name: 'update',
+    summary: 'Update the installed mm-harness to the published latest (--check reports only; --json = {current, latest, updateAvailable}).',
+    example: 'mm-harness update',
+    helpText: `mm-harness update [flags]
+
+  Update the globally-installed mm-harness to the npm registry's latest.
+  Bare form upgrades (npm i -g @deeeed/metamask-harness@latest) and prints old → new;
+  already-current exits 0.
+
+  --check                            Report only — exit 0 up-to-date / exit 1 update available (no install)
+  --json                             Machine-readable { current, latest, updateAvailable }
+
+  A passive once-a-day nudge also prints one stderr line when a newer version exists.
+  Silence it with MM_HARNESS_NO_UPDATE_CHECK=1 (auto-off in CI).
+
+Example:
+  mm-harness update
+  mm-harness update --check --json`,
+  },
   {
     name: 'fixtures',
     summary: 'Manage the canonical wallet fixture (wallet DATA only) — sync files / set the wallet.',
@@ -340,6 +362,11 @@ const HELP_GROUPS: HelpGroup[] = [
     blurb: 'install/verify/clean the per-checkout overlay (the everyday commands auto-ensure it)',
     commands: ['install', 'verify', 'cleanup'],
   },
+  {
+    title: 'MAINTAIN',
+    blurb: 'keep the installed harness current with the npm registry',
+    commands: ['update'],
+  },
 ];
 
 function commandMeta(name: string): { summary: string; example: string; planned: boolean } {
@@ -371,6 +398,9 @@ function groupedHelp(): string {
   lines.push('SETUP — tab-completion (zsh + bash), sourced from the bundled scripts:');
   lines.push('  mm-harness completions install   # print the lines to add to ~/.zshrc / ~/.bashrc');
   lines.push('');
+  lines.push('DEV/PROD — the global npm install is prod; set MM_HARNESS_BIN to a dev checkout to override:');
+  lines.push('  MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness   # unset = the installed/global bin');
+  lines.push('');
   lines.push('See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).');
   return `${lines.join('\n')}\n`;
 }
@@ -430,6 +460,11 @@ for (const command of REAL) {
         process.stdout.write(`${command.helpText}\n`);
         process.exit(0);
       }
+      // `update` is self-contained registry tooling (no engine, no overlay), so it
+      // runs directly rather than through the dispatch in cli.ts.
+      if (command.name === 'update') {
+        process.exit(await handleUpdate(rawArgv.slice(1)));
+      }
       const argv = command.name === 'actions' && rawArgv.includes('--raw') ? translateActionsRaw(rawArgv) : rawArgv;
       process.exit(await delegate(argv));
     });
@@ -474,12 +509,38 @@ for (const retired of RETIRED) {
     .allowUnknownOption()
     .helpOption(false)
     .argument('[args...]')
-    .action(() => {
+    .action(async () => {
+      // `live --adapter mobile` (or android) is handled in-process via handleMobileLive.
+      // All other `live` invocations still teach the replacement.
+      if (retired.name === 'live') {
+        const adapterIdx = rawArgv.indexOf('--adapter');
+        const aliasIdx = rawArgv.indexOf('-a');
+        const adapterVal =
+          adapterIdx !== -1
+            ? rawArgv[adapterIdx + 1]
+            : aliasIdx !== -1
+              ? rawArgv[aliasIdx + 1]
+              : undefined;
+        if (adapterVal === 'mobile' || adapterVal === 'android') {
+          process.exit(await delegate(rawArgv));
+          return;
+        }
+      }
       console.error(retired.message);
       process.exit(2);
     });
 }
 
+// Passive update nudge: one throttled stderr line if a newer version is published.
+// Skipped for update itself (redundant) and for shell/completion tooling (whose
+// stdout is consumed by the shell). stderr-only keeps every --json stdout clean.
+const NUDGE_SKIP: readonly string[] = ['update', 'completions', 'completion-candidates'];
+if (rawArgv.length > 0 && !NUDGE_SKIP.includes(rawArgv[0])) {
+  // Fully deferred: no nudge code runs before parseAsync starts. The exit hook
+  // registered inside maybeNudge prints the line after command output.
+  setImmediate(() => void maybeNudge());
+}
+
 if (rawArgv.length === 0) {
   process.stdout.write(groupedHelp());
   process.exit(0);

package/{runner/src → src}/paths.ts

@@ -11,7 +11,7 @@ import type {
   MetaMaskRecipeAdapter,
 } from './types.ts';
 
-export const runnerDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+export const runnerDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const pathDefaults = readPathDefaults();
 export const DEFAULT_RECIPE_RUNTIME_DIR = pathDefaults.recipeRuntimeDir;
 export const DEFAULT_RECIPE_HARNESS_ROOT = pathDefaults.recipeHarnessRoot;
@@ -26,7 +26,7 @@ export function recipeHarnessRoot() {
 
 
 function readPathDefaults(): { recipeRuntimeDir: string; recipeHarnessRoot: string } {
-  const defaultsPath = path.join(runnerDir, 'orchestration/lib/path-defaults.json');
+  const defaultsPath = path.join(runnerDir, 'adapters/shared/path-defaults.json');
   const parsed = JSON.parse(fs.readFileSync(defaultsPath, 'utf8')) as Partial<{ recipeRuntimeDir: string; recipeHarnessRoot: string }>;
   return {
     recipeRuntimeDir: validateRelativeRecipePath('recipeRuntimeDir', parsed.recipeRuntimeDir || ''),

package/{orchestration/lib/progress.mjs → src/progress.ts}

@@ -1,20 +1,29 @@
-#!/usr/bin/env node
 /**
- * progress.mjs — structured progress events for long recipe CLI operations.
+ * progress.ts — structured progress events for long recipe CLI operations.
  *
  * Human mode: short lines on stderr.
  * Machine mode: JSONL on stderr when --json or RECIPE_PROGRESS_JSON=1.
  */
+import path from 'node:path';
 import { parseArgs } from 'node:util';
-import { color } from './cli-color.mjs';
+import { color } from './cli-color.ts';
 
-function shouldEmitJson(explicit) {
+function shouldEmitJson(explicit: boolean): boolean {
   if (explicit) return true;
   const env = process.env.RECIPE_PROGRESS_JSON;
   return env === '1' || env === 'true';
 }
 
-export function emitProgress(event, { json = false } = {}) {
+interface ProgressEvent {
+  command?: string;
+  phase?: string;
+  message?: string;
+  status?: string;
+  elapsedMs?: number;
+  [key: string]: unknown;
+}
+
+export function emitProgress(event: ProgressEvent, { json = false }: { json?: boolean } = {}): void {
   const payload = {
     schemaVersion: 1,
     type: 'progress',
@@ -30,28 +39,28 @@ export function emitProgress(event, { json = false } = {}) {
   if (payload.phase === 'done') {
     const statusStyle = payload.status === 'pass' ? 'ok' : 'err';
     const statusWord = payload.status === 'pass' ? 'done' : 'failed';
-    const verb = payload.verb ? color('cmd', `${payload.verb}`, { stream }) : '';
+    const cmd = payload.command ? color('cmd', `${payload.command}`, { stream }) : '';
     const elapsed = Number.isFinite(payload.elapsedMs)
-      ? color('comment', ` (${Math.round(payload.elapsedMs / 1000)}s)`, { stream })
+      ? color('comment', ` (${Math.round((payload.elapsedMs as number) / 1000)}s)`, { stream })
       : '';
-    process.stderr.write(`${prefix}: ${verb} ${color(statusStyle, statusWord, { stream })} ${payload.message || ''}${elapsed}\n`);
+    process.stderr.write(`${prefix}: ${cmd} ${color(statusStyle, statusWord, { stream })} ${payload.message || ''}${elapsed}\n`);
     return;
   }
-  const verb = payload.verb ? `${color('cmd', payload.verb, { stream })}: ` : '';
+  const cmd = payload.command ? `${color('cmd', payload.command, { stream })}: ` : '';
   const phase = payload.phase ? `${color('accent', `[${payload.phase}]`, { stream })} ` : '';
   const elapsed = Number.isFinite(payload.elapsedMs)
-    ? color('comment', ` (${Math.round(payload.elapsedMs / 1000)}s)`, { stream })
+    ? color('comment', ` (${Math.round((payload.elapsedMs as number) / 1000)}s)`, { stream })
     : '';
-  process.stderr.write(`${prefix}: ${verb}${phase}${payload.message || ''}${elapsed}\n`);
+  process.stderr.write(`${prefix}: ${cmd}${phase}${payload.message || ''}${elapsed}\n`);
 }
 
-function usage() {
+function usage(): void {
   console.error(`Usage:
-  progress.mjs emit --verb <name> --phase <id> --message <text> [--elapsed-ms <n>] [--json]
-  progress.mjs done --verb <name> --status pass|fail --message <text> [--elapsed-ms <n>] [--json]`);
+  progress emit --command <name> --phase <id> --message <text> [--elapsed-ms <n>] [--json]
+  progress done --command <name> --status pass|fail --message <text> [--elapsed-ms <n>] [--json]`);
 }
 
-async function main() {
+async function main(): Promise<void> {
   const [command, ...rest] = process.argv.slice(2);
   if (!command || command === '--help' || command === '-h') {
     usage();
@@ -61,7 +70,7 @@ async function main() {
   const { values } = parseArgs({
     args: rest,
     options: {
-      verb: { type: 'string' },
+      command: { type: 'string' },
       phase: { type: 'string' },
       message: { type: 'string' },
       status: { type: 'string' },
@@ -76,7 +85,7 @@ async function main() {
 
   if (command === 'emit') {
     emitProgress({
-      verb: values.verb || 'recipe',
+      command: values.command || 'recipe',
       phase: values.phase || 'working',
       message: values.message || '',
       elapsedMs: Number.isFinite(elapsedMs) ? elapsedMs : undefined,
@@ -86,7 +95,7 @@ async function main() {
 
   if (command === 'done') {
     emitProgress({
-      verb: values.verb || 'recipe',
+      command: values.command || 'recipe',
       phase: 'done',
       status: values.status || 'pass',
       message: values.message || '',
@@ -99,9 +108,10 @@ async function main() {
   process.exit(2);
 }
 
-if (import.meta.url === new URL(process.argv[1], 'file:').href) {
-  main().catch((error) => {
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename ?? '');
+if (isMain) {
+  main().catch((error: unknown) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
   });
-}
+}

package/docs/extension-runtime-commands.md

@@ -1,60 +0,0 @@
-# Extension runtime lifecycle (internal notes)
-
-Internal implementation notes for the MetaMask Extension runtime lifecycle — the
-self-healing path that gets a checkout from "installed" to "a live, verified
-extension under CDP control". These are **not** a public command surface: the
-probes below are internal functions, composed for you by the daily-loop commands
-(`launch --verify`) and the readiness commands (`doctor --fix`, `verify`). The
-public surface is defined in [CLI-SPEC.md](CLI-SPEC.md); this file explains what
-happens underneath.
-
-The runner is the source of truth for Extension harness injection, readiness
-decisions, extension-id resolution, and live CDP health checks.
-
-## Public entry points
-
-- **`install`** writes the Extension runtime overlay under the configured harness
-  root. CI/agents run it explicitly; the daily-loop commands auto-ensure it.
-- **`verify`** confirms the overlay is present and healthy — a live CDP health
-  probe when a runtime is reachable, no launch.
-- **`launch --verify`** installs the overlay if missing, launches/attaches the
-  extension, and polls CDP until the runtime is ready.
-- **`doctor` / `doctor --fix`** report readiness and (with `--fix`) run the
-  healing steps below WITHOUT starting the app.
-
-## Internal lifecycle stages
-
-The healing path composes these internal functions in order. Each is idempotent
-and reports the cheapest next action, so the composed path converges rather than
-rebuilding from scratch.
-
-### Extension-id resolution
-
-Resolves the deterministic unpacked extension id from
-`dist/chrome/manifest.json`, and can verify it against a live CDP target. Every
-later stage keys off this id, so it runs first.
-
-### Readiness decision
-
-Inspects the checkout + live browser and returns the cheapest next action:
-`install`, `build`, `relaunch`, or `ready`, plus the concrete `actions[]` to
-execute. The healing path branches on this decision instead of always launching.
-
-### Runtime launch
-
-Launches Chrome with the installed harness helper, seeds the wallet fixture, and
-runs live smoke verification. Two tiers: reuse the existing dist (quick relaunch),
-or the clean-build path — clear the webpack cache, start the harness-owned
-watcher, wait for a clean compile, then launch and verify.
-
-### Convergence
-
-Converges the live browser to exactly one healthy `home.html` tab (closing
-strays, reopening if needed) and confirms it with the health probe. This is the
-step that makes "launch" deterministic across a messy pre-existing browser state.
-
-### Health probe
-
-Read-only liveness probe for the running extension over CDP. Used both as the
-final gate of the convergence step and standalone by `verify` to answer "is the
-runtime healthy right now?" without mutating anything.