@deeeed/metamask-harness 0.2.0

package/orchestration/lib/cli-home.mjs

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+/**
+ * cli-home.mjs — recipe CLI home screen and ports output.
+ */
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import {
+  color,
+  colorKv,
+  colorStatusWord,
+} from './cli-color.mjs';
+
+const OUT = process.stdout;
+
+function readJson(file) {
+  if (!file || !fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function httpProbe(url, timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    const req = http.get(url, { timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, body }));
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, body: '' }); });
+    req.on('error', () => resolve({ ok: false, body: '' }));
+  });
+}
+
+function watcherPhase(logPath) {
+  if (!logPath || !fs.existsSync(logPath)) return 'stopped';
+  const text = fs.readFileSync(logPath, 'utf8');
+  if (/Module build failed|^ERROR in /m.test(text)) return 'failed';
+  if (/compiled successfully|MetaMask .* compiled|Bundle end:/m.test(text)) return 'ready';
+  if (/webpack.Progress|Building|Compiling|yarn start/m.test(text)) return 'compiling';
+  return 'unknown';
+}
+
+function metroPhase(logPath) {
+  if (!logPath || !fs.existsSync(logPath)) return 'stopped';
+  const text = fs.readFileSync(logPath, 'utf8');
+  if (/Bundl(ed|ing)|Finished/m.test(text)) {
+    const match = text.match(/(iOS|Android).*?([0-9]+(?:\.[0-9]+)?)%/);
+    if (match && Number(match[2]) < 100) return 'bundling';
+    return 'ready';
+  }
+  return 'starting';
+}
+
+function mobileBridgeSnapshot(runtimeStatus) {
+  const raw = runtimeStatus?.bridge?.status;
+  const targets = Array.isArray(raw) ? raw : raw ? [raw] : [];
+  const ready = targets.find((item) => item && typeof item === 'object' && item.route);
+  if (!ready) return { route: null, account: null, deviceName: null };
+  return {
+    route: ready.route?.name || null,
+    account: ready.account?.name || ready.account?.address || null,
+    deviceName: ready.deviceName || null,
+  };
+}
+
+function watcherPhaseLabel(phase) {
+  switch (phase) {
+    case 'ready': return 'ready';
+    case 'compiling': return 'compiling';
+    case 'failed': return 'failed';
+    case 'stopped': return 'stopped';
+    default: return phase || 'unknown';
+  }
+}
+
+function metroPhaseLabel(phase) {
+  switch (phase) {
+    case 'running':
+    case 'ready': return 'ready';
+    case 'bundling': return 'bundling';
+    case 'starting': return 'starting';
+    case 'down': return 'down';
+    default: return phase || 'unknown';
+  }
+}
+
+function nextActions(adapter, state) {
+  const actions = [];
+  if (state.harnessStale) {
+    actions.push({ command: 'recipe sync', reason: 'refresh harness scripts + fixture context' });
+  }
+  if (adapter === 'extension') {
+    if (state.ready) {
+      actions.push({ command: 'recipe refresh', reason: 'fast incremental update when watcher is active' });
+      actions.push({ command: 'recipe debug', reason: 'open Chrome DevTools' });
+      actions.push({ command: 'recipe logs', reason: 'compact last build events (recipe logs --full for raw tail)' });
+    } else if (state.watcher === 'ready' && state.decision === 'build') {
+      actions.push({ command: 'recipe refresh', reason: 'watcher is up; wait for dist to catch up' });
+      actions.push({ command: 'recipe rebuild', reason: 'heavy clean rebuild if refresh stalls' });
+    } else if (state.watcher === 'compiling') {
+      actions.push({ command: 'recipe logs', reason: 'compact webpack progress' });
+      actions.push({ command: 'recipe status', reason: 're-check readiness' });
+    } else {
+      actions.push({ command: 'recipe up', reason: 'decide and run the minimum path to ready' });
+      actions.push({ command: 'recipe rebuild', reason: 'clean webpack + browser launch (2-8 min)' });
+      actions.push({ command: 'recipe watch', reason: 'start watcher only' });
+    }
+    if (!state.fixturePresent) actions.unshift({ command: 'recipe sync', reason: 'install fixture + harness context' });
+  } else {
+    if (state.ready) {
+      actions.push({ command: 'recipe debug', reason: 'open React Native DevTools' });
+      actions.push({ command: 'recipe logs', reason: 'compact Metro events (recipe logs --full for raw tail)' });
+    } else if (state.metro === 'ready' && !state.bridgeReady) {
+      actions.push({ command: 'recipe up', reason: 'launch dev client and wait for bridge' });
+      actions.push({ command: 'recipe logs', reason: 'compact bundle progress' });
+    } else {
+      actions.push({ command: 'recipe up', reason: 'start Metro + launch dev client as needed' });
+      actions.push({ command: 'recipe ios', reason: 'launch iOS dev client' });
+      actions.push({ command: 'recipe android', reason: 'launch Android dev client' });
+    }
+    if (!state.fixturePresent) actions.unshift({ command: 'recipe sync', reason: 'install fixture + harness context' });
+  }
+  return actions.slice(0, 5);
+}
+
+function renderHuman(payload) {
+  const lines = [];
+  const head = payload.adapter === 'extension' ? 'Extension recipe' : 'Mobile recipe';
+  lines.push(`${color('bold', head, { stream: OUT })} ${color('dim', '|', { stream: OUT })} ${color('path', payload.root, { stream: OUT })}`);
+  lines.push(`${colorKv('slot', payload.slotId || '?', 'info', { stream: OUT })}  ${colorKv('runtime', payload.runtimeDir, 'path', { stream: OUT })}`);
+  if (payload.harnessStale) {
+    lines.push(color('warn', 'harness: stale - run: recipe sync', { stream: OUT }));
+  }
+  if (payload.adapter === 'extension') {
+    lines.push(
+      `${colorKv('cdp', String(payload.ports.cdp ?? '?'), 'info', { stream: OUT })}  ${colorKv('watcher-port', String(payload.ports.watcher ?? '?'), 'info', { stream: OUT })}`,
+    );
+    lines.push([
+      `${color('label', 'browser:', { stream: OUT })} ${colorStatusWord(payload.browser, { stream: OUT })}`,
+      `${color('label', 'webpack:', { stream: OUT })} ${colorStatusWord(watcherPhaseLabel(payload.watcher), { stream: OUT })}`,
+      `${color('label', 'ready:', { stream: OUT })} ${colorStatusWord(payload.ready ? 'yes' : 'no', { stream: OUT })}`,
+      payload.reason ? color('comment', ` (${payload.reason})`, { stream: OUT }) : '',
+    ].join('  '));
+    lines.push(`${color('label', 'fixture:', { stream: OUT })} ${colorStatusWord(payload.fixturePresent ? 'present' : 'missing', { stream: OUT })}`);
+  } else {
+    const bridgeBits = [];
+    if (payload.appRoute) bridgeBits.push(`route=${payload.appRoute}`);
+    if (payload.appAccount) bridgeBits.push(`account=${payload.appAccount}`);
+    const bridgeDetail = bridgeBits.length > 0 ? color('comment', ` (${bridgeBits.join(', ')})`, { stream: OUT }) : '';
+    lines.push(
+      `${colorKv('metro-port', String(payload.ports.watcher ?? '?'), 'info', { stream: OUT })}  ${colorKv('device', payload.device || payload.appDevice || '?', 'info', { stream: OUT })}  ${color('label', 'metro:', { stream: OUT })} ${colorStatusWord(metroPhaseLabel(payload.metro), { stream: OUT })}  ${color('label', 'bridge:', { stream: OUT })} ${colorStatusWord(payload.bridge, { stream: OUT })}${bridgeDetail}`,
+    );
+    lines.push([
+      `${color('label', 'fixture:', { stream: OUT })} ${colorStatusWord(payload.fixturePresent ? 'present' : 'missing', { stream: OUT })}`,
+      `${color('label', 'ready:', { stream: OUT })} ${colorStatusWord(payload.ready ? 'yes' : 'no', { stream: OUT })}`,
+      payload.reason ? color('comment', ` (${payload.reason})`, { stream: OUT }) : '',
+    ].join('  '));
+  }
+  if (payload.decision) {
+    lines.push(`${colorKv('decision', payload.decision, 'ok', { stream: OUT })}${payload.reasonCode ? color('comment', ` - ${payload.reasonCode}`, { stream: OUT }) : ''}`);
+  }
+  if (payload.tmux) {
+    lines.push(`${colorKv('tmux', payload.tmux, 'accent', { stream: OUT })}${color('comment', ' (webpack window may still stream full logs)', { stream: OUT })}`);
+  }
+  lines.push('');
+  lines.push(color('label', 'next:', { stream: OUT }));
+  for (const item of payload.nextActions) {
+    lines.push(`  ${color('cmd', item.command, { stream: OUT })}  ${color('comment', `# ${item.reason}`, { stream: OUT })}`);
+  }
+  lines.push('');
+  lines.push(color('comment', 'speed:  fast -> watch -> refresh   slow -> rebuild   inspect -> status | logs | logs --full | debug', { stream: OUT }));
+  return `${lines.join('\n')}\n`;
+}
+
+function renderPorts(payload) {
+  const lines = [
+    colorKv('slot', payload.slotId || '?', 'info', { stream: OUT }),
+    `${colorKv('cdp', String(payload.ports.cdp ?? '?'), 'info', { stream: OUT })}  ${colorKv('watcher', String(payload.ports.watcher ?? '?'), 'info', { stream: OUT })}`,
+    `${colorKv('runtime', payload.runtimeDir, 'path', { stream: OUT })}  ${colorKv('harness', payload.harnessDir, 'path', { stream: OUT })}`,
+  ];
+  if (payload.tmux) lines.push(colorKv('tmux', payload.tmux, 'accent', { stream: OUT }));
+  return `${lines.join('\n')}\n`;
+}
+
+async function buildHome({ adapter, target, runtimeDir, ports, runtimeStatus, decision, harnessStale = false }) {
+  const runtimeAbs = path.join(target, runtimeDir);
+  const context = readJson(path.join(runtimeAbs, 'agentic-runtime.json'))
+    || readJson(path.join(runtimeAbs, 'recipe-runtime.json'))
+    || {};
+  const slotId = context.slotId || null;
+  const fixturePresent = Boolean(
+    runtimeStatus?.fixture?.present
+    || fs.existsSync(path.join(runtimeAbs, 'wallet-fixture.json')),
+  );
+
+  let browser = 'down';
+  let watcher = 'stopped';
+  let metro = 'stopped';
+  let bridge = 'down';
+  let bridgeReady = false;
+  let device = process.env.IOS_SIMULATOR || process.env.ANDROID_DEVICE || process.env.ADB_SERIAL || null;
+  let tmux = null;
+
+  if (adapter === 'extension') {
+    const cdp = ports.cdp;
+    if (cdp) {
+      const probe = await httpProbe(`http://127.0.0.1:${cdp}/json/version`);
+      browser = probe.ok ? 'up' : 'down';
+    }
+    const logPath = path.join(runtimeAbs, 'webpack.log');
+    watcher = watcherPhase(logPath);
+    const slot = (path.basename(target).match(/-(\d+)$/) || [])[1];
+    if (slot) tmux = `mme-${slot}:webpack-${ports.watcher || '?'}`;
+  } else {
+    const port = ports.watcher;
+    if (port) {
+      const status = await httpProbe(`http://127.0.0.1:${port}/status`);
+      metro = status.ok && status.body.includes('packager-status:running') ? 'running' : 'down';
+      if (metro === 'running') metro = metroPhase(path.join(runtimeAbs, 'metro.log'));
+    }
+    bridgeReady = Boolean(runtimeStatus?.bridge?.ready);
+    bridge = bridgeReady ? 'ready' : (runtimeStatus?.debugTarget?.present ? 'waiting' : 'down');
+  }
+
+  const ready = Boolean(runtimeStatus?.ready);
+  const decisionValue = decision?.decision || runtimeStatus?.decision?.decision || null;
+  const reasonCode = decision?.reasonCode || runtimeStatus?.decision?.reasonCode || runtimeStatus?.reason || null;
+  const bridgeSnap = adapter === 'mobile' ? mobileBridgeSnapshot(runtimeStatus) : null;
+
+  const payload = {
+    schemaVersion: 1,
+    kind: 'home',
+    adapter,
+    root: target,
+    runtimeDir,
+    slotId,
+    ports,
+    fixturePresent,
+    harnessStale,
+    ready,
+    reason: runtimeStatus?.reason || null,
+    appRoute: bridgeSnap?.route || null,
+    appAccount: bridgeSnap?.account || null,
+    appDevice: bridgeSnap?.deviceName || null,
+    decision: decisionValue,
+    reasonCode,
+    browser: adapter === 'extension' ? browser : undefined,
+    watcher: adapter === 'extension' ? watcher : undefined,
+    metro: adapter === 'mobile' ? metro : undefined,
+    bridge: adapter === 'mobile' ? bridge : undefined,
+    bridgeReady: adapter === 'mobile' ? bridgeReady : undefined,
+    device: adapter === 'mobile' ? device : undefined,
+    tmux: adapter === 'extension' ? tmux : undefined,
+    runtimeStatus,
+    nextActions: [],
+  };
+  payload.nextActions = nextActions(adapter, {
+    ready,
+    watcher,
+    metro,
+    bridgeReady,
+    fixturePresent,
+    harnessStale,
+    decision: decisionValue,
+  });
+  return payload;
+}
+
+function buildPorts({ adapter, target, runtimeDir, ports, slotId }) {
+  return {
+    schemaVersion: 1,
+    kind: 'ports',
+    adapter,
+    root: target,
+    runtimeDir,
+    slotId: slotId || null,
+    ports,
+    tmux: adapter === 'extension' && ports.watcher
+      ? `mme-${(path.basename(target).match(/-(\d+)$/) || ['', ''])[1]}:webpack-${ports.watcher}`
+      : null,
+    harnessDir: process.env.RECIPE_HARNESS_ROOT || 'temp/recipe/harness',
+  };
+}
+
+async function main() {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      adapter: { type: 'string' },
+      target: { type: 'string' },
+      'runtime-dir': { type: 'string' },
+      'cdp-port': { type: 'string' },
+      'watcher-port': { type: 'string' },
+      'slot-id': { type: 'string' },
+      mode: { type: 'string', default: 'home' },
+      'runtime-status-file': { type: 'string' },
+      'decision-file': { type: 'string' },
+      'harness-stale': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  });
+
+  if (!values.adapter || !values.target) {
+    console.error('cli-home.mjs requires --adapter and --target');
+    process.exit(2);
+  }
+
+  const ports = {
+    cdp: values['cdp-port'] ? Number(values['cdp-port']) : null,
+    watcher: values['watcher-port'] ? Number(values['watcher-port']) : null,
+  };
+  const runtimeStatus = readJson(values['runtime-status-file']);
+  const decision = readJson(values['decision-file']);
+
+  const payload = values.mode === 'ports'
+    ? buildPorts({
+      adapter: values.adapter,
+      target: values.target,
+      runtimeDir: values['runtime-dir'] || 'temp/recipe/runtime',
+      ports,
+      slotId: values['slot-id'],
+    })
+    : await buildHome({
+      adapter: values.adapter,
+      target: values.target,
+      runtimeDir: values['runtime-dir'] || 'temp/recipe/runtime',
+      ports,
+      runtimeStatus,
+      decision,
+      harnessStale: values['harness-stale'],
+    });
+
+  if (values.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
+  if (payload.kind === 'ports') {
+    process.stdout.write(renderPorts(payload));
+    return;
+  }
+
+  process.stdout.write(renderHuman(payload));
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/orchestration/lib/cli-ux.sh

@@ -0,0 +1,252 @@
+# cli-ux.sh — shared recipe CLI UX helpers for mm-harness porcelain wrappers.
+# Sourced, not executed.
+
+recipe_color_enabled() {
+  [ -n "${NO_COLOR:-}" ] && [ "${NO_COLOR:-}" != "0" ] && return 1
+  [ "${RECIPE_NO_COLOR:-}" = "1" ] && return 1
+  [ "${RECIPE_COLOR:-}" = "1" ] || [ "${FORCE_COLOR:-}" = "1" ] || [ -t 2 ]
+}
+
+recipe_color() {
+  local style="$1" text="$2"
+  if ! recipe_color_enabled; then
+    printf '%s' "$text"
+    return 0
+  fi
+  case "$style" in
+    bold) printf '\033[1m%s\033[0m' "$text" ;;
+    dim|comment|path) printf '\033[2m%s\033[0m' "$text" ;;
+    label) printf '\033[1;36m%s\033[0m' "$text" ;;
+    cmd) printf '\033[1m%s\033[0m' "$text" ;;
+    ok) printf '\033[1;32m%s\033[0m' "$text" ;;
+    warn) printf '\033[1;33m%s\033[0m' "$text" ;;
+    err) printf '\033[1;31m%s\033[0m' "$text" ;;
+    *) printf '%s' "$text" ;;
+  esac
+}
+
+recipe_progress_script() {
+  printf '%s' "${RECIPE_PROGRESS_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/progress.mjs}"
+}
+
+recipe_home_script() {
+  printf '%s' "${RECIPE_HOME_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/cli-home.mjs}"
+}
+
+recipe_log_tui_script() {
+  printf '%s' "${RECIPE_LOG_TUI_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/log-tui.mjs}"
+}
+
+recipe_version_script() {
+  printf '%s' "${RECIPE_VERSION_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/cli-version.mjs}"
+}
+
+recipe_log_ui_mode() {
+  printf '%s' "${RECIPE_LOG_UI:-compact}"
+}
+
+recipe_log_events_limit() {
+  printf '%s' "${RECIPE_LOG_EVENTS:-10}"
+}
+
+recipe_watch_build_log() {
+  local log_path="$1" label="${2:-build}" success_pattern="${3:-}"
+  local args=(
+    watch --log "$log_path"
+    --events "$(recipe_log_events_limit)"
+    --mode "$(recipe_log_ui_mode)"
+    --label "$label"
+  )
+  [ -n "$success_pattern" ] && args+=(--success-pattern "$success_pattern")
+  node "$(recipe_log_tui_script)" "${args[@]}"
+}
+
+recipe_watch_rebuild_log() {
+  local log_path="$1"
+  recipe_watch_build_log "$log_path" "runtime rebuild" \
+    'PASS runtime-launch|Extension harness verify pass|runtime rebuild complete'
+}
+
+recipe_instant_hint() {
+  local message="$1"
+  [ "${RECIPE_PROGRESS_JSON:-}" = "1" ] && return 0
+  [ -t 2 ] || return 0
+  local prefix="${RECIPE_CLI_PREFIX:-recipe}"
+  printf '%s: %s\n' \
+    "$(recipe_color label "$prefix")" \
+    "$(recipe_color dim "$message")" >&2
+}
+
+recipe_progress() {
+  local verb="$1" phase="$2" message="$3" elapsed="${4:-}"
+  local args=(emit --verb "$verb" --phase "$phase" --message "$message")
+  [ -n "$elapsed" ] && args+=(--elapsed-ms "$elapsed")
+  [ "${RECIPE_PROGRESS_JSON:-}" = "1" ] && args+=(--json)
+  node "$(recipe_progress_script)" "${args[@]}" || true
+}
+
+recipe_done() {
+  local verb="$1" status="$2" message="$3" elapsed="${4:-}"
+  local args=(done --verb "$verb" --status "$status" --message "$message")
+  [ -n "$elapsed" ] && args+=(--elapsed-ms "$elapsed")
+  [ "${RECIPE_PROGRESS_JSON:-}" = "1" ] && args+=(--json)
+  node "$(recipe_progress_script)" "${args[@]}" || true
+}
+
+recipe_failure_playbook() {
+  local verb="$1" reason="$2"
+  shift 2
+  local log_path="" artifact="" prefix="${RECIPE_CLI_PREFIX:-recipe}"
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --log) log_path="$2"; shift 2 ;;
+      --artifact) artifact="$2"; shift 2 ;;
+      --prefix) prefix="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  printf '%s: %s %s - %s\n' \
+    "$(recipe_color label "$prefix")" \
+    "$(recipe_color cmd "$verb")" \
+    "$(recipe_color err failed)" \
+    "$(recipe_color warn "$reason")" >&2
+  printf '%s\n' "$(recipe_color label next:)" >&2
+  case "$verb" in
+    rebuild|up|watch)
+      printf '  %s\n' "$(recipe_color cmd "$prefix logs")" >&2
+      printf '  %s\n' "$(recipe_color cmd "$prefix logs --full")" >&2
+      printf '  %s\n' "$(recipe_color cmd "$prefix doctor")" >&2
+      printf '  %s\n' "$(recipe_color cmd "$prefix sync")" >&2
+      ;;
+    refresh)
+      printf '  %s\n' "$(recipe_color cmd "$prefix watch")" >&2
+      printf '  %s\n' "$(recipe_color cmd "$prefix logs")" >&2
+      printf '  %s\n' "$(recipe_color cmd "$prefix rebuild")" >&2
+      ;;
+    metro|ios|android|setup-wallet)
+      printf '  %s\n' "$(recipe_color cmd "$prefix logs")" >&2
+      printf '  %s\n' "$(recipe_color cmd "$prefix logs --full")" >&2
+      printf '  %s\n' "$(recipe_color cmd "$prefix up")" >&2
+      ;;
+    *)
+      printf '  %s\n' "$(recipe_color cmd "$prefix status")" >&2
+      printf '  %s\n' "$(recipe_color cmd "$prefix logs")" >&2
+      ;;
+  esac
+  [ -n "$log_path" ] && printf '%s\n' "$(recipe_color path "log: $log_path")" >&2
+  [ -n "$artifact" ] && printf '%s\n' "$(recipe_color path "artifact: $artifact")" >&2
+}
+
+recipe_check_harness_stale() {
+  local adapter="$1" root="$2" harness_root="$3" runner_root="$4"
+  local manifest="" sha=""
+  case "$adapter" in
+    extension) manifest="$root/$harness_root/extension/manifest.json" ;;
+    mobile) manifest="$root/$harness_root/mobile/manifest.json" ;;
+    *) return 0 ;;
+  esac
+  [ -f "$manifest" ] || return 0
+  sha="${manifest%/*}/installed-scripts.sha256"
+  node "$(recipe_version_script)" check \
+    --runner-root "$runner_root" \
+    --manifest "$manifest" \
+    ${sha:+--installed-sha "$sha"} \
+    --json 2>/dev/null | grep -q '"stale"[[:space:]]*:[[:space:]]*true'
+}
+
+recipe_warn_harness_stale() {
+  local adapter="$1" root="$2" harness_root="$3" runner_root="$4"
+  local prefix="${RECIPE_CLI_PREFIX:-recipe}"
+  if recipe_check_harness_stale "$adapter" "$root" "$harness_root" "$runner_root"; then
+    printf '%s: %s - run: %s\n' \
+      "$(recipe_color label "$prefix")" \
+      "$(recipe_color warn 'harness scripts are stale')" \
+      "$(recipe_color cmd "$prefix sync")" >&2
+    return 1
+  fi
+  return 0
+}
+
+recipe_infer_farmslot_root() {
+  if [ -n "${FARMSLOT_ROOT:-}" ] && [ -d "${FARMSLOT_ROOT}" ]; then
+    printf '%s' "${FARMSLOT_ROOT}"
+    return 0
+  fi
+  local candidate=""
+  for candidate in "$HOME/dev/farmslot" "$HOME/farmslot"; do
+    [ -d "$candidate/scripts" ] || continue
+    printf '%s' "$candidate"
+    return 0
+  done
+  return 1
+}
+
+recipe_try_farmslot_fixture_sync() {
+  local slot_id="$1"
+  local farmslot_root=""
+  [ -n "$slot_id" ] || return 1
+  farmslot_root="$(recipe_infer_farmslot_root || true)"
+  [ -n "$farmslot_root" ] || return 1
+  [ -f "$farmslot_root/scripts/sync-fixtures.sh" ] || return 1
+  bash "$farmslot_root/scripts/sync-fixtures.sh" --slot "$slot_id"
+}
+
+recipe_sync_wallet_fixture() {
+  local root="$1" runtime_dir="$2" cdp_port="${3:-}" seed_script="${4:-}" farmslot_slot="${5:-}"
+  local canonical="$root/$runtime_dir/wallet-fixture.json"
+  local candidate resolved prefix="${RECIPE_CLI_PREFIX:-recipe}"
+
+  mkdir -p "$root/$runtime_dir"
+  if [ -f "$canonical" ]; then
+    return 0
+  fi
+
+  if [ -n "${RECIPE_WALLET_FIXTURE:-}" ] && [ -f "${RECIPE_WALLET_FIXTURE}" ]; then
+    cp "${RECIPE_WALLET_FIXTURE}" "$canonical"
+    chmod 600 "$canonical" 2>/dev/null || true
+    printf '%s: fixture: linked %s/wallet-fixture.json from RECIPE_WALLET_FIXTURE\n' "$prefix" "$runtime_dir" >&2
+    return 0
+  fi
+
+  if [ -n "$seed_script" ] && [ -f "$seed_script" ]; then
+    resolved="$(cd "$root" && bash "$seed_script" resolve --target "$root" ${cdp_port:+--cdp-port "$cdp_port"} 2>/dev/null || true)"
+    if [ -n "$resolved" ] && [ -f "$resolved" ] && [ "$resolved" != "$canonical" ]; then
+      cp "$resolved" "$canonical"
+      chmod 600 "$canonical" 2>/dev/null || true
+      printf '%s: fixture: copied to %s/wallet-fixture.json\n' "$prefix" "$runtime_dir" >&2
+      return 0
+    fi
+  fi
+
+  for candidate in \
+    "$root/temp/runtime/wallet-fixture.json" \
+    ${cdp_port:+"$root/temp/.recipe-validation-${cdp_port}/wallet-fixture.json"} \
+    "$root/temp/.agent-validation/wallet-fixture.json"
+  do
+    [ -f "$candidate" ] || continue
+    cp "$candidate" "$canonical"
+    chmod 600 "$canonical" 2>/dev/null || true
+    printf '%s: fixture: copied to %s/wallet-fixture.json\n' "$prefix" "$runtime_dir" >&2
+    return 0
+  done
+
+  if [ -n "$farmslot_slot" ]; then
+    printf '%s: fixture: trying farmslot sync-fixtures --slot %s\n' "$prefix" "$farmslot_slot" >&2
+    if recipe_try_farmslot_fixture_sync "$farmslot_slot"; then
+      [ -f "$canonical" ] && return 0
+    fi
+  fi
+
+  return 1
+}
+
+recipe_speed_ladder() {
+  cat >&2 <<'EOF'
+Speed ladder:
+  FAST (seconds):  recipe watch -> recipe refresh
+  SLOW (minutes):  recipe rebuild
+  INSPECT:         recipe status | recipe ports | recipe logs | recipe logs --full | recipe debug
+  PROOF:           recipe run <recipe.json>
+  SYNC CONTEXT:    recipe sync
+EOF
+}