@deeeed/metamask-harness 0.17.3 → 0.17.5

package/dist/mm-harness-cli.js

@@ -4,17 +4,10 @@ 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");
@@ -76,16 +69,13 @@ Example:
   },
   {
     name: "actions",
-    summary: "Discover typed single operations and their fields.",
+    summary: "List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).",
     example: "mm-harness actions --adapter mobile",
-    helpText: `mm-harness actions [query] [flags]
+    helpText: `mm-harness actions [flags]
 
-  Discover typed single operations and their field schemas for this checkout.
+  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)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --raw                              Dump raw action registry JSON
@@ -93,9 +83,6 @@ 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
   mm-harness actions --adapter extension --raw`
   },
@@ -152,11 +139,11 @@ Example (real actions; run mm-harness actions for this checkout's full set):
   },
   {
     name: "flows",
-    summary: "Browse reusable parameterized action sequences.",
+    summary: "Browse the reusable flow library (bare = list; `flows promote` publishes a flow up a tier). Resolves across libraries \u2014 personal > team > canonical, highest tier wins.",
     example: "mm-harness flows",
     helpText: `mm-harness flows [flags]
 
-  Browse reusable parameterized action sequences. Flows resolve by precedence
+  Browse the reusable flow library. Flows resolve across libraries by precedence
   (personal > team > canonical); the highest-tier copy wins and shadows lower ones.
   Flow resolution is adapter-global, so there is no --adapter flag here.
 
@@ -169,12 +156,11 @@ Example:
   },
   {
     name: "run",
-    summary: "Execute a complete proof and write its evidence.",
+    summary: "Validate + run a recipe and write evidence (summary/trace/artifacts). --plan validates + prints the plan, touching nothing.",
     example: "mm-harness run recipe.json",
     helpText: `mm-harness run <recipe.json> [flags]
 
-  Validate and execute a complete proof, then write summary, trace, diagnostics,
-  and artifacts. A recipe may use actions directly or call reusable flows.
+  Validate + run a recipe and write evidence (summary / trace / artifacts).
 
   --list                             List everything invocable for the adapter (actions + flows); no <recipe> needed
   --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
@@ -186,29 +172,12 @@ 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.",
@@ -406,7 +375,6 @@ 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
@@ -425,8 +393,8 @@ Example:
   --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
   --window                           (Re)open the read-only tmux tail window for the resolved dev-server port (leaves the process untouched)
   --events <n>                       Compact event count (default 10) (env: RECIPE_LOG_EVENTS)
-  --source <label>                   Log source per adapter \u2014 mobile: metro|app;
-                                     extension: extension|dapp|webpack|watcher|rebuild.
+  --source <label>                   Log source per adapter \u2014 mobile: metro|app (default metro);
+                                     extension: webpack|watcher|rebuild|app (default webpack).
                                      Core is headless (teaching error).
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
@@ -505,7 +473,6 @@ 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
@@ -520,28 +487,21 @@ 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(", ")}]`
-      );
-    }
+const RETIRED = [
+  {
+    name: "live",
+    message: `mm-harness live is retired (exit 2).
+
+Replacement: mm-harness launch --verify (install overlay \u2192 launch \u2192 CDP/bridge poll \u2192 smoke verify).`
+  },
+  {
+    name: "manifest",
+    message: `mm-harness manifest is retired (exit 2).
+
+Replacement: mm-harness actions --raw   (works now \u2014 dumps the raw action registry JSON,
+identical to the old \`manifest --json\`). Manifest validation moved into doctor / run --plan.`
   }
-}
-assertPublicContractMatchesSurface();
+];
 const HELP_GROUPS = [
   {
     title: "DAILY LOOP",
@@ -556,7 +516,7 @@ const HELP_GROUPS = [
   {
     title: "PROVE",
     blurb: "run recipes and inspect readiness",
-    commands: ["run", "last", "doctor", "check", "checklist", "recipe-quality"]
+    commands: ["run", "doctor", "check", "checklist", "recipe-quality"]
   },
   {
     title: "RUNTIME OVERLAY",
@@ -644,7 +604,7 @@ function groupedHelp() {
   lines.push("DEV/PROD \u2014 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 README.md for the workflow and docs/CHEATSHEET.md for examples.");
+  lines.push("See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).");
   return `${lines.join("\n")}
 `;
 }
@@ -656,6 +616,11 @@ async function delegate(argv) {
     return error !== null && typeof error === "object" && "exitCode" in error && typeof error.exitCode === "number" ? error.exitCode : 1;
   }
 }
+function translateActionsRaw(argv) {
+  const rest = argv.slice(1).filter((arg) => arg !== "--raw");
+  const withJson = rest.includes("--json") ? rest : [...rest, "--json"];
+  return ["manifest", ...withJson];
+}
 const pkgVersion = (() => {
   try {
     return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version ?? "unknown";
@@ -673,7 +638,8 @@ for (const command of REAL) {
     if (command.name === "update") {
       process.exit(await handleUpdate(rawArgv.slice(1)));
     }
-    process.exit(await withCommandJournal(command.name, rawArgv, () => delegate(rawArgv)));
+    const argv = command.name === "actions" && rawArgv.includes("--raw") ? translateActionsRaw(rawArgv) : rawArgv;
+    process.exit(await delegate(argv));
   });
 }
 const HIDDEN = [
@@ -695,9 +661,24 @@ program.command("completions").description("Install/print bundled shell tab-comp
   const result = spawnSync("bash", [script, ...rawArgv.slice(1)], { stdio: "inherit" });
   process.exit(result.status ?? 1);
 });
+for (const retired of RETIRED) {
+  program.command(retired.name).description(`${retired.name} is retired (see teaching error)`).allowUnknownOption().helpOption(false).argument("[args...]").action(async () => {
+    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] : void 0;
+      if (adapterVal === "mobile" || adapterVal === "android") {
+        process.exit(await delegate(rawArgv));
+        return;
+      }
+    }
+    console.error(retired.message);
+    process.exit(2);
+  });
+}
 const NUDGE_SKIP = ["update", "completions", "completion-candidates"];
 if (rawArgv.length > 0 && !NUDGE_SKIP.includes(rawArgv[0])) {
-  maybeNudge();
+  setImmediate(() => void maybeNudge());
 }
 function hasPassthroughHelp(argv) {
   const divider = argv.indexOf("--");
@@ -711,66 +692,10 @@ 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"
-]);
-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/paths.js

@@ -47,7 +47,10 @@ function recipeWatchLogCandidates() {
 }
 function resolveLocalProtocolRoot() {
   const candidates = [
+    // Orchestrator-neutral name is primary; FARMSLOT_ROOT stays a back-compat alias
+    // for one release (the installer injects METAMASK_RUNNER_PROTOCOL_ROOT).
     process.env.METAMASK_RUNNER_PROTOCOL_ROOT,
+    process.env.FARMSLOT_ROOT,
     readConfiguredProtocolRoot(),
     findProtocolRoot(runnerDir),
     findProtocolRoot(process.cwd())
@@ -59,7 +62,7 @@ function resolveRequiredLocalProtocolRoot(reason) {
   const root = resolveLocalProtocolRoot();
   if (!root) {
     throw new Error(
-      `${reason} requires a local protocol/runtime checkout. Set METAMASK_RUNNER_PROTOCOL_ROOT or create .farmslot-root for this dev-only path.`
+      `${reason} requires a local protocol/runtime checkout. Set METAMASK_RUNNER_PROTOCOL_ROOT (or the legacy FARMSLOT_ROOT), or create .farmslot-root for this dev-only path.`
     );
   }
   return root;
@@ -149,7 +152,7 @@ async function importProtocolPackage(packageName, localSourceEntry) {
   const root = resolveLocalProtocolRoot();
   if (!root) {
     throw new Error(
-      `${packageName} is not installed. Install @farmslot/* packages normally, or set METAMASK_RUNNER_PROTOCOL_ROOT/use npm run dev:link-farmslot while co-developing protocol packages locally.`
+      `${packageName} is not installed. Install @farmslot/* packages normally, or set FARMSLOT_ROOT/use npm run dev:link-farmslot while co-developing protocol packages locally.`
     );
   }
   return import(pathToFileURL(path.join(root, localSourceEntry)).href);

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: withActionProgress([...core, ...ui, ...lifecycle, ...custom], options.onActionEvent),
+    adapters: [...core, ...ui, ...lifecycle, ...custom],
     logger,
     recording: {
       targetProvider: createMetaMaskRecordingTargetProvider(adapter)
@@ -76,36 +76,6 @@ 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) => ({
@@ -113,11 +83,7 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle) {
     async execute(node, context) {
       const command = node.command ?? node.event ?? node.state;
       const reloadsSource = command === "launch" || command === "foreground" || command === "restart";
-      const source = reloadsSource ? mobileSourceFingerprint(context.projectRoot) : void 0;
-      if (source?.status === "unavailable") {
-        throw new Error(`${source.error.message} Next: ${source.error.userAction}`);
-      }
-      const fingerprint = source?.fingerprint;
+      const fingerprint = reloadsSource ? mobileSourceFingerprint(context.projectRoot) : void 0;
       const result = await entry.execute(node, context);
       if (fingerprint !== void 0 && !recordMobileSourceBaseline(context.projectRoot, fingerprint)) {
         throw new Error(
@@ -150,6 +116,5 @@ export {
   createMetaMaskExtensionRunner,
   createMetaMaskMobileRunner,
   createMetaMaskRunner,
-  isAutomaticHudProgress,
   mobileSourceAwareLifecycleAdapters
 };

package/dist/runtime-context.js

@@ -53,32 +53,6 @@ function readExistingContext(contextPath, repoRoot, runtimeDir, adapter) {
   return { context, existed: true };
 }
 function validExistingContext(context, repoRoot, runtimeDir, adapter) {
-  const allowedFields = /* @__PURE__ */ new Set([
-    "schemaVersion",
-    "repoRoot",
-    "project",
-    "slotId",
-    "machine",
-    "runtimeOwner",
-    "strict",
-    "platform",
-    "runtimeDir",
-    "gitDirty",
-    "simulator",
-    "adbSerial",
-    "distDir",
-    "extensionId",
-    "gitHead",
-    "gitBranch",
-    "gitCommit",
-    "createdAt",
-    "session",
-    "cdpPort",
-    "watcherPort",
-    "metroPort",
-    "devServerPort"
-  ]);
-  if (Object.keys(context).some((field) => !allowedFields.has(field))) return false;
   if (context.schemaVersion !== void 0 && context.schemaVersion !== 1) return false;
   if (context.repoRoot !== void 0 && (typeof context.repoRoot !== "string" || path.resolve(context.repoRoot) !== repoRoot)) return false;
   if (context.platform !== void 0 && context.platform !== adapter) return false;
@@ -108,6 +82,14 @@ function validExistingContext(context, repoRoot, runtimeDir, adapter) {
     const value = context[field];
     if (value !== void 0 && (!Number.isInteger(value) || Number(value) < 1 || Number(value) > 65535)) return false;
   }
+  if (context.runtimeStart !== void 0) {
+    if (!context.runtimeStart || typeof context.runtimeStart !== "object" || Array.isArray(context.runtimeStart)) return false;
+    const runtimeStart = context.runtimeStart;
+    if (runtimeStart.approved !== void 0 && typeof runtimeStart.approved !== "boolean") return false;
+    for (const field of ["command", "readyUrl"]) {
+      if (runtimeStart[field] !== void 0 && (typeof runtimeStart[field] !== "string" || runtimeStart[field].length === 0)) return false;
+    }
+  }
   const forbiddenResources = adapter === "core" ? ["cdpPort", "watcherPort", "metroPort", "devServerPort", "simulator", "adbSerial", "extensionId"] : adapter === "extension" ? ["metroPort", "simulator", "adbSerial"] : ["cdpPort", "extensionId"];
   if (forbiddenResources.some((field) => context[field] !== void 0)) return false;
   return true;

package/docs/ADAPTER-SURFACE.md

@@ -1,26 +1,119 @@
-# Adapter surface
+# The adapter surface — one seam for per-platform behavior
 
-`src/adapters/surface.ts` is the typed seam for Mobile, Extension, and Core.
-Commands ask it for platform behavior instead of re-deriving platform rules.
+`mm-harness` runs against three platforms (mobile | extension | core). The
+danger is that every command re-derives "what does this platform do?" with its
+own `if (adapter === 'mobile') … else if (adapter === 'extension') …` ladder.
+When it does, a platform gets forgotten in one command but not another — the
+class of bug where `doctor` reported a live runtime section for mobile only,
+`stop` refused every non-mobile adapter, and `logs` knew a single extension log
+file instead of all three. Those are *platform-blind* commands.
 
-Each adapter implements:
+The **adapter surface** is the fix: one interface per platform, resolved through
+a registry, that owns the behavior a command would otherwise branch on.
 
-- runtime readiness;
-- slot-owned ports;
-- dev-server lifecycle;
-- log sources;
-- launch/recovery hints;
-- headless capability.
+## The interface
 
-Implementations live in `src/adapters/{mobile,extension,core}/surface.ts`.
-Platform-specific shell and Node operations live under `adapters/<platform>/`.
+`src/adapters/surface.ts` defines `AdapterSurface` and the registry
+`getAdapterSurface(adapter)`. Each platform ships one implementation:
 
-When adding behavior:
+- `src/adapters/mobile/surface.ts`
+- `src/adapters/extension/surface.ts`
+- `src/adapters/core/surface.ts`
 
-1. Extend `AdapterSurface` only when every platform needs the concept.
-2. Implement all three adapters; Core should explicitly report headless/N/A.
-3. Call the surface from the command instead of adding adapter conditionals.
-4. Add a registry-completeness contract and a real affected-platform check.
+```ts
+interface AdapterSurface {
+  readonly adapter: MetaMaskRecipeAdapter;
+  readonly headless: boolean;                       // core runs no app/dev server
+  resolveSlotPorts(target: string): void;           // context > pool > formula (no-op for core)
+  runtimeStatus(target: string): Promise<AdapterRuntimeStatus>; // read-only readiness for doctor
+  devServer: {
+    describe(): string;                             // "Metro" | "webpack watcher" | "no dev server (headless)"
+    stop(target: string): AdapterDevServerStop;     // idempotent, slot-scoped; headless = teach
+  };
+  logSources(target: string): AdapterLogSource[];   // ordered candidate log files (empty for core)
+  hints: { launch: string; relaunch: string };      // platform-phrased Next: hints
+}
+```
 
-Mechanisms unique to one command may remain platform-specific. Shared readiness,
-ports, logs, lifecycle, and recovery language belong on the surface.
+`runtimeStatus` returns a normalized shape so `doctor` renders one line the same
+way for every platform:
+
+```ts
+interface AdapterRuntimeStatus {
+  decision: string;
+  reasonCode?: string;
+  reasons: string[];
+  deps?: string;
+  devServer?: { label: string; status: string };    // absent for headless core
+}
+```
+
+The implementations are thin: they delegate to the readiness/port plumbing that
+already existed (`decideExtensionReadiness`, `mobileRuntimeStatus`, the slot-port
+resolvers and the webpack-watcher stop, all re-homed to
+`src/adapters/slot-ports.ts`). The surface is an organizing seam, not a rewrite.
+
+## The rule
+
+**A command never branches on adapter for behavior the surface owns.**
+
+- Do not write `if (adapter === 'core')` — ask `surface.headless`.
+- Do not write `adapter === 'mobile' ? metroPorts() : extensionPorts()` — call
+  `surface.resolveSlotPorts(target)`.
+- Do not print `adapter === 'mobile' ? 'mm-harness launch ios' : 'mm-harness
+  launch'` — use `surface.hints.launch`.
+
+A new platform behavior is added by **extending the surface** (a new member on
+the interface plus its three implementations), never by adding another branch to
+a command. TypeScript then makes it impossible to ship a platform that forgot the
+new member, because each implementation is annotated `: AdapterSurface`.
+
+What the surface deliberately does **not** own: a command may still branch on
+adapter for a *mechanism* that is genuinely platform-specific and not part of the
+interface — e.g. `fixtures set` uses a shell arm on mobile and the engine path on
+extension. Those branches select a mechanism; they never re-derive readiness,
+ports, log locations, dev-server lifecycle, or Next: phrasing, which are the
+surface's responsibility.
+
+## Migration status
+
+Every command that used to branch on adapter now resolves through the surface:
+
+| command | surface-backed | uses |
+| --- | --- | --- |
+| `doctor` | yes | `resolveSlotPorts` + `runtimeStatus` (mobile/extension/core runtime section) |
+| `launch` | yes | `resolveSlotPorts` |
+| `stop` | yes | `resolveSlotPorts` + `devServer.stop` (+ headless teaching) |
+| `logs` | yes | `logSources` + `hints.launch` + `headless` |
+| `debug` | yes | `headless` + `hints.relaunch` (core teaching); flag semantics stay per-command |
+| `fixtures` | yes | `headless` + `hints` (retry/launch); the set *mechanism* stays per-platform |
+| `run` / `call` | n/a | engine path; core-headless is handled by the heal contract, not the surface |
+| `flows` | no (by design) | recipe-library flows are adapter-global; not a platform-owned behavior |
+| `completion-candidates` | partial | `actions` scope to the detected checkout adapter; `flows` are adapter-global |
+
+`flows` is intentionally not surface-backed: a recipe-library flow can compose
+actions across platforms, so flows are adapter-global by design rather than a
+platform-blind gap. `completion-candidates actions` already resolves the adapter
+from the checkout context (cwd/`--target`); only the adapter-global `flows`
+candidates are unscoped, matching the flows model.
+
+## How this composes with the UX principles
+
+`docs/UX-PRINCIPLES.md` principle 1 (*Context-aware by default* — "output is
+scoped to the platform… help, flag lists, and completion candidates shrink to
+what applies here") states the intent. The adapter surface is its **enforcement
+mechanism**: a command that resolves platform behavior through the surface is
+context-aware by construction, and one that hand-rolls an adapter ladder is the
+exact failure principle 1 warns against. When adding a command or output path,
+satisfy principle 1 by going through the surface.
+
+## Adding a platform behavior — checklist
+
+1. Add the member to `AdapterSurface` in `src/adapters/surface.ts`.
+2. Implement it in all three `src/adapters/*/surface.ts` (TypeScript will not
+   compile until you do).
+3. Have the command call `getAdapterSurface(adapter).<member>` instead of
+   branching.
+4. Cover the closed blind spot with a contract test (see
+   `tests/contract/adapter-surface.test.sh`), and keep the registry-completeness
+   assertion green.