@deeeed/metamask-harness 0.3.9 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.5.0 - 2026-07-05
+
+Minor release: thin Runway provisioning (harness-owned slot provisioning with a shared artifact cache) plus compiled-dist packaging.
+
+### Added
+- **`mm-harness provision runway`** — provisions a mobile slot with exactly: resolve the latest Runway (expo-dev-build) artifact, download it ONCE into a shared machine cache (`~/.cache/metamask-harness/runway/<runId>/`, sha256+size integrity, corrupt entries re-downloaded, never a slot failure), create the simulator if missing, install the dev client on it. Zero yarn/deps/Metro — those stay dispatch-time (lazy, presence-authoritative readiness unchanged). `install --runway` is the overlay-path equivalent (covered by its own contract test). Baseline recorded so doctor reports provisioned-but-deps-pending as a normal state.
+- **Compiled `dist/` for published installs** — the npm tarball ships esbuild-compiled JS; `npm i -g` installs run the dist entry (~0.21s cold vs ~0.37s tsx). Source checkouts without `dist/` keep the tsx dev path; `bin/mm-harness` prefers dist when present. Packaging contract test (pack → global install → dist entry runs).
+
+### Changed
+- Runway provisioning callers (farm installer, mobile-farm `runway` prepare profile) delegate to the harness; the profile no longer runs a deps phase and a contract test enforces that.
+
+## 0.4.0 - 2026-07-04
+
+Minor release: the adapter-surface architecture plus the day's feature wave (0.3.6-0.3.9 shipped fixes as they were validated live; this cut marks the surface additions honestly).
+
+### Added
+- **AdapterSurface** — one per-platform surface behind a common interface (`src/adapters/surface.ts`: resolveSlotPorts, runtimeStatus, devServer, logSources, hints); doctor/launch/stop/logs/debug/fixtures are surface-backed, so no verb hand-rolls platform branching. Contract: `docs/ADAPTER-SURFACE.md` (never-branch rule, add-a-platform checklist, migration table).
+- **Platform-adaptive `stop` on every adapter** — extension: kills this checkout's webpack watcher (pid file + orphan scan, slot-scoped) and closes its tail window; mobile: port-scoped Metro; core: headless teaching error. Idempotent, outcome-stating summaries.
+- **Doctor reports live runtime state on every adapter** — mobile Metro, extension webpack (via the extension readiness decision), core deps-only — one uniform shape, adapter-scoped colored context rows.
+- **`logs` is multi-source per adapter** — sources and the `--source` default come from the adapter's logSources (extension: webpack/watcher/rebuild/app).
+- **Context-aware examples and tier-visible flows** — `call` usage/help examples use the detected adapter's real manifest actions; `flows` prints a precedence legend decoding each source into personal > team > canonical.
+
+### Changed
+- **BREAKING (agent contract)**: `doctor --json` `runtime.metro` (string) is now `runtime.devServer` `{label, status}` and is absent for core.
+
+### Feature wave recap (0.3.6-0.3.9)
+- `mm-harness stop`; live-streamed mobile AND extension launches with upfront intent lines; presence-authoritative readiness (no setup-on-every-launch) with the dev-client running probe; slot-context-first device/port resolution; UTF-8 locale for pod spawns; DEV OVERRIDE banner + SLOT line + colored help; `mmdev-harness` completions; hermetic tmux-stubbed contract suite (now gating CI) + ESLint in `npm run check`; `docs/UX-PRINCIPLES.md` interaction contract.
+
 ## 0.3.9 - 2026-07-04
 
 ### Fixed
@@ -17,7 +45,15 @@
 
 ## Unreleased
 
+### Added
+- Add `mm-harness provision` for thin mobile Runway artifact provisioning with a shared integrity-checked cache and simulator install path.
+- Add `mm-harness provision runway ios --resolve-only` to return Runway run/revision/artifact metadata without touching simulator, cache, download, install, or baseline state.
+- **Dist publish path** — `npm run build` compiles `src/` to `dist/`; `npm pack` / global install runs the compiled CLI entry (`dist/mm-harness-cli.js`) while a source checkout without `dist/` keeps the tsx+src dev path. Contracts: `packaging-dist-install`, `packaging-dev-checkout`.
+
 ### Fixed
+- `mm-harness provision runway ios` now routes through the same Runway provisioning surface as `install --runway`, so overlay dispatch accepts the compatibility command instead of rejecting it as an unsupported harness action.
+- Runway provisioning now accepts farm context flags (`--slot`, `--watcher-port`, `--runtime-dir`), records slot/watcher/runtime-dir baselines correctly, ignores stale provision baselines unless the app is still installed on the simulator, and emits rerunnable `Next:` commands from the actual invocation.
+- Runway iOS artifact extraction now handles the live nested zip layout and app bundle names other than `MetaMask.app` while keeping the cached app directory integrity hash/size contract.
 - **Mobile preflight no longer re-runs `yarn setup` on every launch** — the deps readiness decision escalated an mtime hint to `stale` and ran the FULL `yarn setup` (submodules + inpage bridge + jetify + pods) inside the launch phase on every invocation in orchestrated (farmslot) contexts. `depsCheck` reports `stale` for a no-baseline checkout whenever a manifest is newer than the install markers; the orchestrator's git phase refreshes tracked-file mtimes on every sync while its deps phase leaves `node_modules` untouched, so "manifest newer than markers" is normal and not proof of drift — yet it duplicated the orchestrator's deps work and turned a fast preflight into 15+ minutes (the behavior that also looked like a hang before 0.3.8's streaming). **Presence is now authoritative:** without a recorded baseline an mtime-only `stale` is trusted as `current` (with a one-line stderr warning), so a churned-but-present checkout launches with zero `yarn` in both tiers. Genuine drift is still caught by the recorded-baseline fingerprint. `mm-harness launch` (quick tier / no `--build`) also dropped `preflightMode` before deciding, so the fast contract never took effect; it is threaded through now.
 - **Fast tier never installs; genuine gaps teach the orchestrator** — in the fast tier (quick launch / orchestrated), deps that genuinely need work (absent markers, an absent required package, a fingerprint drift, or Metro unable to resolve a module) return a teaching block naming the orchestrator deps/prepare phase (plus the standalone `yarn setup:expo` / `launch --build` remedies) instead of an implicit setup — deps are the orchestrator's contract. The standalone/full tier still installs.
 - **Deps baseline recorded the instant a setup leaf succeeds** — `prepareMobile` records the deps fingerprint baseline immediately after any successful `yarn-setup`, unconditionally (previously only a later `record: true` re-decide did, gated on the original decision being `install` and on `RECIPE_UP_INSTALL_ATTEMPTED`). Genuine-drift detection is fingerprint-based and self-sustaining after one good install.
@@ -26,11 +62,19 @@
 - **Metro log-tail window no longer leaks into an unrelated tmux session** — running `start-metro` outside a tmux client fell back to `tmux display-message` (the last-attached session, e.g. the user's own) and created its `metro-<port>` window — with a `tail -F` — there, outliving the run. The viewer now opens a window only in a session that belongs to this run (a named slot session that exists, or the current session when actually inside tmux) and otherwise skips it; Metro still runs detached to the log. Extracted to `adapters/mobile/lib/tmux-viewer.sh` so the rule is unit-tested; contract tests stub tmux hermetically so no suite run can create a real window.
 
 ### Added
-- **`mm-harness stop`** — stop the port-scoped Metro dev server this mobile checkout owns and close its log-tail window (idempotent; extension/core are slot-managed and get a teaching error). Slot-context-aware port resolution.
+- **Adapter surface — one seam for per-platform behavior** — `src/adapters/surface.ts` defines `AdapterSurface` + a `getAdapterSurface(adapter)` registry that owns the behavior commands used to hand-roll with `if (adapter === …)` ladders (slot-port resolution, read-only runtime status, dev-server describe/stop, log sources, and platform-phrased Next: hints), with thin `mobile`/`extension`/`core` implementations that delegate to the existing readiness/port plumbing (re-homed to `src/adapters/slot-ports.ts`). `doctor`, `launch`, `stop`, `logs`, `debug`, and `fixtures` now resolve platform behavior through the surface instead of branching. This closes the platform-blind class of bug (a platform handled in one command but forgotten in another). Documented in `docs/ADAPTER-SURFACE.md`; enforces `docs/UX-PRINCIPLES.md` principle 1.
+- **`doctor` reports a runtime section for every adapter** — the live runtime readiness line (decision + reasons, deps currency, dev server) now renders for extension (webpack watcher via `decideExtensionReadiness`) and core (deps-presence-only), not just mobile; the render is one uniform shape sourced from the surface.
+- **`mm-harness stop` is adaptive per platform** — mobile stops its port-scoped Metro and closes the log-tail window; extension stops the checkout's webpack watcher (pid file + orphan ps-scan, slot-scoped) and closes its tail window; core teaches the headless path. All idempotent (nothing-to-stop is success), with a uniform summary and `--json` envelope.
+- **`logs` resolves dev-server log sources through the surface** — extension now recognizes the webpack, watcher, and rebuild logs (ordered), not only `webpack.log`; each platform's "nothing running" teaches its own launch hint. `--source` default and valid set come from the adapter's own log sources (extension defaults to `webpack`, not `metro`), and core teaches with platform-neutral wording (no Metro vocabulary). `--source <label>` now prefers that dev-server log.
+- **`call` with no action gives a context-aware example** — the usage error shows the DETECTED adapter and a REAL action from its manifest (a wallet action where one exists, else the universal `command`) plus the scoped `mm-harness actions --adapter <detected>` discovery hint. The static `call --help` example now uses real actions (`ensure_unlocked` / `command`) and points at `mm-harness actions`, instead of a hardcoded `call unlock --adapter extension` naming a non-existent `metamask.wallet.unlock`.
+- **`flows` surfaces the resolution tier per source** — `flows` prints a precedence legend mapping each resolved library source to its tier (`personal` / `team` / `canonical`), derived from the actual resolution, so the engine's `source=<name>` per flow is decodable and LOCAL libraries read as first-class; the tier is also named in the recipe-library-unavailable teaching error.
+- **`stop --help` matches the adaptive behavior** — the help text now describes mobile Metro / extension webpack watcher / core headless, instead of the stale "Metro dev server … extension/core: teaching error".
 - **Slot-context device/port detection** — `resolve-farmslot-ports.sh` reads `agentic-runtime.json` (the mapping the orchestrator's prepare wrote into the checkout) first, so device/port resolution survives pool renames that break any naming formula.
 - **CLI help surface** — grouped/colored `mm-harness` help, a `DEV OVERRIDE ACTIVE` banner when `MM_HARNESS_BIN` is set, and a `SLOT` line when the checkout is a prepared slot; `mmdev-harness` completion alias.
 
 ### Changed
+- **`doctor --json` runtime dev-server shape is normalized** — the mobile-only `runtime.metro` string is replaced by a platform-labelled `runtime.devServer: { label, status }` (`metro` for mobile, `webpack` for extension; absent for headless core), so agents read one shape across platforms.
+- **`yarn check` runs ESLint** — flat-config ESLint (typescript-eslint recommended on `src/**/*.ts`, `@eslint/js` recommended on the `.mjs`/`.cjs` library) runs after typecheck and comment-hygiene. Dev-only (not in the published `files`); the baseline is zero-warning by config scoping.
 - **Deps install uses a scoped `setup:expo` variant when native isn't wanted** — `adapters/mobile/yarn-setup.sh` gains `--mode full|expo`. `expo` runs `yarn setup:expo --no-build-ios --no-build-android` (JS deps + prebuild, no native — native builds come from `open-device.sh`, never doubled); the full `yarn setup` runs only for a native build (`launch --build`). This is also the standalone Metro-only remedy taught by the fast-tier deps block.
 - **`mm-harness runtime-decision --adapter mobile` accepts `--preflight-mode`** — surfaces the fast (presence, blocks on a genuine gap) vs full (installs) decision for inspection and callers.
 

package/dist/adapters/core/surface.js

@@ -0,0 +1,53 @@
+import path from "node:path";
+import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
+const coreSurface = {
+  adapter: "core",
+  headless: true,
+  resolveSlotPorts() {
+  },
+  async runtimeStatus(target) {
+    const deps = depsCheck(path.resolve(target));
+    const ready = deps.status === "current";
+    return {
+      decision: ready ? "ready" : "install",
+      reasonCode: ready ? "deps-present" : `deps-${deps.status}`,
+      reasons: [
+        ready ? "Core is headless; dependencies are installed. Run recipes with mm-harness run." : "Core is headless; dependencies are not fully installed."
+      ],
+      deps: deps.status
+    };
+  },
+  runwayProvision: {
+    async run(target, options) {
+      return {
+        schemaVersion: 1,
+        command: "provision",
+        adapter: "core",
+        target: path.resolve(target),
+        status: "fail",
+        exitCode: 2,
+        error: { code: "UNSUPPORTED_ADAPTER", message: "core is headless and has no mobile simulator to provision.", userAction: options.rerunCommand || "mm-harness run <recipe> --adapter core" }
+      };
+    }
+  },
+  devServer: {
+    describe: () => "no dev server (headless)",
+    stop() {
+      return {
+        kind: "headless",
+        message: "core is headless \u2014 no dev server runs for a core checkout",
+        userAction: "use mm-harness verify (readiness) or mm-harness run (execute a recipe)"
+      };
+    }
+  },
+  logSources() {
+    return [];
+  },
+  hints: {
+    launch: "mm-harness run <recipe>   # run recipes against the headless core",
+    relaunch: "mm-harness verify"
+  }
+};
+export {
+  coreSurface
+};

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

@@ -0,0 +1,109 @@
+import path from "node:path";
+import { resolveExtensionId } from "./extension-id.js";
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function jsonList(port) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(5e3) });
+    if (!res.ok) return [];
+    const value = await res.json();
+    return Array.isArray(value) ? value : [];
+  } catch {
+    return [];
+  }
+}
+async function closeTab(port, id) {
+  try {
+    await fetch(`http://127.0.0.1:${port}/json/close/${id}`, { signal: AbortSignal.timeout(4e3) });
+  } catch {
+  }
+}
+async function activateTab(port, id) {
+  try {
+    await fetch(`http://127.0.0.1:${port}/json/activate/${id}`, { signal: AbortSignal.timeout(4e3) });
+  } catch {
+  }
+}
+function isStrayTab(url) {
+  if (typeof url !== "string") return false;
+  return /^chrome:\/\/newtab\/?$/.test(url) || /^chrome:\/\/new-tab-page\b/.test(url) || url === "about:blank";
+}
+async function openHome(port, extensionId) {
+  const endpoint = `http://127.0.0.1:${port}/json/new?${encodeURIComponent(`chrome-extension://${extensionId}/home.html`)}`;
+  try {
+    let res = await fetch(endpoint, { method: "PUT", signal: AbortSignal.timeout(8e3) });
+    if (res.status === 404 || res.status === 405) res = await fetch(endpoint, { signal: AbortSignal.timeout(8e3) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+function homePages(targets, extensionId) {
+  const prefix = `chrome-extension://${extensionId}`;
+  return targets.filter(
+    (t) => t.type === "page" && typeof t.url === "string" && t.url.startsWith(prefix) && t.url.includes("/home.html") && t.id
+  );
+}
+async function ensureExtensionReady(target, options) {
+  const resolved = path.resolve(target);
+  const { cdpPort } = options;
+  const base = (extra) => ({
+    schemaVersion: 1,
+    adapter: "extension",
+    target: resolved,
+    cdpPort,
+    extensionId: null,
+    opened: false,
+    homeTabs: { before: 0, closed: 0, after: 0 },
+    ready: false,
+    reasonCode: "unknown",
+    health: { status: "unknown", findings: [] },
+    ...extra
+  });
+  const { extensionId } = await resolveExtensionId(resolved, { cdpPort });
+  if (!extensionId) return base({ reasonCode: "no-extension-id" });
+  const homes = homePages(await jsonList(cdpPort), extensionId);
+  const before = homes.length;
+  let opened = false;
+  let closed = 0;
+  if (homes.length > 1) {
+    for (const h of homes) {
+      await closeTab(cdpPort, String(h.id));
+      closed += 1;
+    }
+    await sleep(500);
+    opened = await openHome(cdpPort, extensionId);
+    await sleep(1500);
+  } else if (homes.length === 0) {
+    opened = await openHome(cdpPort, extensionId);
+    await sleep(1500);
+  }
+  const converged = await jsonList(cdpPort);
+  const homesNow = homePages(converged, extensionId);
+  if (homesNow.length >= 1) {
+    for (const t of converged) {
+      if (t.type === "page" && t.id && isStrayTab(t.url)) await closeTab(cdpPort, String(t.id));
+    }
+    if (homesNow[0]?.id) await activateTab(cdpPort, String(homesNow[0].id));
+  }
+  const after = homePages(await jsonList(cdpPort), extensionId).length;
+  let health = { status: "unknown", findings: [] };
+  try {
+    const { checkExtensionRuntimeHealth } = await import("./runtime.js");
+    const report = await checkExtensionRuntimeHealth(resolved, cdpPort);
+    health = { status: report.status, findings: report.findings };
+  } catch (error) {
+    health = { status: "FAIL", findings: [error instanceof Error ? error.message : String(error)] };
+  }
+  const ready = health.status === "PASS" && after === 1;
+  return base({
+    extensionId,
+    opened,
+    homeTabs: { before, closed, after },
+    ready,
+    reasonCode: ready ? "ready" : after !== 1 ? "tab-count" : "unhealthy",
+    health
+  });
+}
+export {
+  ensureExtensionReady
+};

package/dist/adapters/extension/extension-id.js

@@ -0,0 +1,62 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const DIST_MANIFEST = "dist/chrome/manifest.json";
+function extensionIdFromKey(keyBase64) {
+  const der = Buffer.from(keyBase64, "base64");
+  const hash = crypto.createHash("sha256").update(der).digest();
+  let id = "";
+  for (let i = 0; i < 16; i += 1) {
+    id += String.fromCharCode(97 + (hash[i] >> 4));
+    id += String.fromCharCode(97 + (hash[i] & 15));
+  }
+  return id;
+}
+function idFromDistManifest(target) {
+  const manifestPath = path.join(target, DIST_MANIFEST);
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    return typeof manifest.key === "string" && manifest.key.length > 0 ? extensionIdFromKey(manifest.key) : null;
+  } catch {
+    return null;
+  }
+}
+async function cdpExtensionIds(cdpPort) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${cdpPort}/json/list`, { signal: AbortSignal.timeout(4e3) });
+    if (!res.ok) return [];
+    const targets = await res.json();
+    const ids = /* @__PURE__ */ new Set();
+    for (const t of targets) {
+      const m = /^chrome-extension:\/\/([^/]+)/u.exec(String(t.url ?? ""));
+      if (m) ids.add(m[1]);
+    }
+    return [...ids];
+  } catch {
+    return [];
+  }
+}
+async function resolveExtensionId(target, options = {}) {
+  const resolved = path.resolve(target);
+  const fromKey = idFromDistManifest(resolved);
+  let cdpIds = null;
+  if (options.cdpPort) cdpIds = await cdpExtensionIds(options.cdpPort);
+  if (fromKey) {
+    return {
+      adapter: "extension",
+      target: resolved,
+      extensionId: fromKey,
+      source: "manifest-key",
+      verified: cdpIds ? cdpIds.includes(fromKey) : null
+    };
+  }
+  if (cdpIds && cdpIds.length === 1) {
+    return { adapter: "extension", target: resolved, extensionId: cdpIds[0], source: "cdp-target", verified: true };
+  }
+  return { adapter: "extension", target: resolved, extensionId: null, source: "none", verified: cdpIds ? false : null };
+}
+export {
+  extensionIdFromKey,
+  resolveExtensionId
+};

package/dist/adapters/extension/runtime-decision.js

@@ -0,0 +1,305 @@
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  depsCheck,
+  INSTALL_MARKERS,
+  recordDepsBaseline
+} from "@farmslot/recipe-harness/runtime/deps-readiness";
+import { recipeHarnessPath, recipeWatchLogCandidates } from "../../paths.js";
+const WEBPACK_DIRECT_INPUTS = ["package.json", "yarn.lock", ".yarnrc.yml", ".tool-versions"];
+const WEBPACK_RECURSIVE_INPUTS = ["development/webpack"];
+const WEBPACK_CACHE_DIR = "node_modules/.cache/webpack";
+const WATCH_LOG_CANDIDATES = recipeWatchLogCandidates();
+function git(target, args) {
+  try {
+    return execFileSync("git", ["-C", target, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function gitRaw(target, args) {
+  try {
+    return execFileSync("git", ["-C", target, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return "";
+  }
+}
+function addFile(hash, target, rel) {
+  const abs = path.join(target, rel);
+  const stat = fs.statSync(abs);
+  hash.update(rel);
+  hash.update(String(stat.size));
+  hash.update(fs.readFileSync(abs));
+}
+function walk(hash, target, relDir) {
+  const absDir = path.join(target, relDir);
+  if (!fs.existsSync(absDir)) return;
+  for (const name of fs.readdirSync(absDir).sort()) {
+    const rel = path.join(relDir, name);
+    const stat = fs.statSync(path.join(target, rel));
+    if (stat.isDirectory()) walk(hash, target, rel);
+    else if (stat.isFile() && /\.(c?m?[jt]sx?|json)$/u.test(rel)) addFile(hash, target, rel);
+  }
+}
+function webpackFingerprint(target) {
+  const hash = crypto.createHash("sha256");
+  for (const rel of WEBPACK_DIRECT_INPUTS) {
+    if (fs.existsSync(path.join(target, rel))) addFile(hash, target, rel);
+  }
+  for (const dir of WEBPACK_RECURSIVE_INPUTS) walk(hash, target, dir);
+  return { gitHead: git(target, ["rev-parse", "HEAD"]) ?? "unknown", fingerprint: hash.digest("hex") };
+}
+function stateDir(target) {
+  return recipeHarnessPath(target, "extension", "decision-state");
+}
+function readBaseline(target, name) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(stateDir(target), name), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeBaseline(target, name, value) {
+  const dir = stateDir(target);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, name), `${JSON.stringify(value, null, 2)}
+`);
+}
+function newestMtime(target, rels) {
+  let newest = 0;
+  for (const rel of rels) {
+    const abs = path.join(target, rel);
+    if (fs.existsSync(abs)) newest = Math.max(newest, fs.statSync(abs).mtimeMs);
+  }
+  return newest;
+}
+function webpackCacheCheck(target) {
+  const cachePresent = fs.existsSync(path.join(target, WEBPACK_CACHE_DIR));
+  if (!cachePresent) return { cachePresent: false, status: "no-cache", hasBaseline: false };
+  const baseline = readBaseline(target, "webpack-cache-state.json");
+  if (!baseline) {
+    const cacheMtime = fs.statSync(path.join(target, WEBPACK_CACHE_DIR)).mtimeMs;
+    const poisoned = newestMtime(target, ["yarn.lock", ...INSTALL_MARKERS]) > cacheMtime;
+    return { cachePresent: true, status: poisoned ? "stale" : "current", hasBaseline: false };
+  }
+  const current = webpackFingerprint(target);
+  const status = baseline.fingerprint === current.fingerprint && baseline.gitHead === current.gitHead ? "current" : "stale";
+  return { cachePresent: true, status, hasBaseline: true };
+}
+function buildLogCheck(target, watchLog) {
+  const candidates = (watchLog ? [path.isAbsolute(watchLog) ? watchLog : path.join(target, watchLog)] : WATCH_LOG_CANDIDATES.map((rel) => path.join(target, rel))).filter((file) => fs.existsSync(file));
+  if (!candidates.length) return { status: "no-watch" };
+  const newestFirst = [...candidates].sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+  const lines = fs.readFileSync(newestFirst[0], "utf8").split("\n");
+  const ERR = /Module build failed|^ERROR in |compiled with [1-9]\d* error/u;
+  const OK = /compiled successfully|compiled with \d+ warning|MetaMask .* compiled|Bundle end: service worker|Bundle end:.*app-init/iu;
+  let lastErr = -1;
+  let lastOk = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (ERR.test(lines[i])) lastErr = i;
+    if (OK.test(lines[i])) lastOk = i;
+  }
+  if (lastErr > lastOk) {
+    const excerpt = lines.slice(lastErr, lastErr + 3).join(" | ").slice(0, 400);
+    const staleCache = /ENOENT/u.test(excerpt) && /node_modules/u.test(excerpt);
+    return { status: "errors", reason: staleCache ? "stale-cache" : "build-error", excerpt };
+  }
+  if (lastOk >= 0) return { status: "ok" };
+  return { status: "building" };
+}
+function uncommittedSource(target) {
+  const dirs = ["ui", "app", "shared", "development"].filter((d) => fs.existsSync(path.join(target, d)));
+  if (!dirs.length) return [];
+  const SRC = /\.(ts|tsx|js|jsx|cjs|mjs|json|scss|css)$/iu;
+  const records = gitRaw(target, ["-c", "core.quotePath=false", "status", "--porcelain", "-z", "--", ...dirs]).split("\0").filter(Boolean);
+  const dirty = [];
+  for (const record of records) {
+    const file = /^.. /u.test(record) ? record.slice(3) : record;
+    if (SRC.test(file)) dirty.push(file);
+  }
+  return dirty;
+}
+function latestFileMtime(target, files) {
+  let latest = 0;
+  for (const file of files) {
+    const absolute = path.join(target, file);
+    if (!fs.existsSync(absolute)) continue;
+    const stat = fs.statSync(absolute);
+    if (stat.isFile()) latest = Math.max(latest, stat.mtimeMs);
+  }
+  return latest;
+}
+function latestDistMtime(target) {
+  const distDir = path.join(target, "dist/chrome");
+  let latest = 0;
+  function walk2(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir)) {
+      const absolute = path.join(dir, entry);
+      const stat = fs.statSync(absolute);
+      if (stat.isDirectory()) walk2(absolute);
+      else if (stat.isFile()) latest = Math.max(latest, stat.mtimeMs);
+    }
+  }
+  walk2(distDir);
+  return latest;
+}
+function distCheck(target) {
+  const manifestPath = path.join(target, "dist/chrome/manifest.json");
+  if (!fs.existsSync(manifestPath)) return { status: "no-build" };
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return { status: "no-build" };
+  }
+  const description = typeof manifest.description === "string" ? manifest.description : "";
+  const match = /from git id:\s*([0-9a-f]{7,40})/iu.exec(description);
+  const head = (git(target, ["rev-parse", "HEAD"]) ?? "").toLowerCase();
+  const headShort = head ? head.slice(0, 8) : void 0;
+  if (!match) return { status: "unknown", head: headShort };
+  const distGitId = match[1].toLowerCase();
+  const distShort = distGitId.slice(0, 8);
+  if (!head) return { status: "unknown", distGitId: distShort };
+  if (!head.startsWith(distGitId)) {
+    return { status: "stale", reason: "commit-mismatch", distGitId: distShort, head: headShort };
+  }
+  const dirty = uncommittedSource(target);
+  if (dirty.length) {
+    const dirtySinceBuild = latestFileMtime(target, dirty) > latestDistMtime(target);
+    if (dirtySinceBuild) {
+      return { status: "stale", reason: "uncommitted-source", distGitId: distShort, head: headShort, modified: dirty.slice(0, 10) };
+    }
+  }
+  return { status: "fresh", distGitId: distShort, head: headShort };
+}
+async function cdpCheck(target, cdpPort) {
+  if (!cdpPort) return { status: "skipped" };
+  try {
+    const { checkExtensionRuntimeHealth } = await import("./runtime.js");
+    const report = await checkExtensionRuntimeHealth(target, cdpPort);
+    return report.status === "PASS" ? { status: "pass" } : { status: "fail", findings: report.findings };
+  } catch (error) {
+    return { status: "fail", findings: [error instanceof Error ? error.message : String(error)] };
+  }
+}
+function recordReadinessBaseline(target) {
+  recordDepsBaseline(target);
+  const cache = webpackFingerprint(target);
+  writeBaseline(target, "webpack-cache-state.json", cache);
+}
+async function decideExtensionReadiness(target, options = {}) {
+  const resolved = path.resolve(target);
+  if (options.record) recordReadinessBaseline(resolved);
+  const deps = depsCheck(resolved);
+  const webpackCache = webpackCacheCheck(resolved);
+  const buildLog = buildLogCheck(resolved, options.watchLog);
+  const dist = distCheck(resolved);
+  const cdp = await cdpCheck(resolved, options.cdpPort);
+  const checks = { deps, webpackCache, buildLog, dist, cdp };
+  const install = [{ id: "yarn-install", argv: ["yarn", "install", "--immutable"], cwd: resolved }];
+  const relaunch = [{ id: "relaunch-browser" }];
+  const cacheStale = buildLog.reason === "stale-cache";
+  const rules = [
+    {
+      when: deps.status === "missing",
+      decision: "install",
+      reasonCode: "deps-missing",
+      reasons: ["Dependencies are not installed (no yarn install-state markers)."],
+      actions: install
+    },
+    {
+      when: deps.status === "stale",
+      decision: "install",
+      reasonCode: "deps-stale",
+      reasons: ["package.json/yarn.lock changed since the recorded install."],
+      actions: install
+    },
+    {
+      when: buildLog.status === "errors",
+      decision: "build",
+      clean: cacheStale,
+      reasonCode: cacheStale ? "webpack-cache-stale" : "build-errors",
+      reasons: [
+        cacheStale ? "Webpack is failing on a poisoned cache (ENOENT on a deduped module)." : "Webpack build has errors; fix the source/build before validating.",
+        ...buildLog.excerpt ? [buildLog.excerpt] : []
+      ],
+      actions: buildAction(resolved, cacheStale)
+    },
+    {
+      when: webpackCache.status === "stale",
+      decision: "build",
+      clean: true,
+      reasonCode: "webpack-cache-stale",
+      reasons: ["Webpack build inputs changed since the cache was recorded; clear cache and rebuild."],
+      actions: buildAction(resolved, true)
+    },
+    {
+      when: dist.status === "no-build",
+      decision: "build",
+      reasonCode: "dist-missing",
+      reasons: ["No dist/chrome build present."],
+      actions: buildAction(resolved, false)
+    },
+    {
+      when: dist.status === "stale",
+      decision: "build",
+      reasonCode: "dist-stale",
+      reasons: [dist.reason === "uncommitted-source" ? `Uncommitted source since the build (${dist.modified?.length ?? 0} file(s)); rebuild.` : `dist git id ${dist.distGitId} != HEAD ${dist.head}; rebuild.`],
+      actions: buildAction(resolved, false)
+    },
+    {
+      when: cdp.status === "pass",
+      decision: "ready",
+      reasonCode: "healthy",
+      reasons: ["Build is fresh and the extension runtime is healthy over CDP."],
+      actions: []
+    },
+    {
+      when: cdp.status === "fail",
+      decision: "relaunch",
+      reasonCode: "runtime-unhealthy",
+      reasons: [
+        "Build is fresh but the live extension is unhealthy; relaunch the browser.",
+        ...cdp.findings?.slice(0, 3) ?? []
+      ],
+      actions: relaunch
+    }
+  ];
+  const fallback = {
+    decision: "relaunch",
+    reasonCode: "cdp-unknown",
+    reasons: ["Build is fresh; browser liveness unverified (pass --cdp-port to confirm `ready`)."],
+    actions: relaunch
+  };
+  const core = rules.find((rule) => rule.when) ?? fallback;
+  return {
+    schemaVersion: 1,
+    adapter: "extension",
+    target: resolved,
+    decision: core.decision,
+    clean: core.clean ?? false,
+    reasonCode: core.reasonCode,
+    reasons: core.reasons,
+    checks,
+    actions: core.actions
+  };
+}
+function buildAction(target, clean) {
+  const actions = [];
+  if (clean) actions.push({ id: "clear-webpack-cache", paths: [WEBPACK_CACHE_DIR] });
+  actions.push({ id: "start-webpack-watch", argv: ["yarn", "start"], cwd: target });
+  return actions;
+}
+export {
+  decideExtensionReadiness,
+  recordReadinessBaseline
+};