@happier-dev/stack 0.2.1-preview.1775586714.26562 → 0.2.12-preview.1

package/scripts/utils/tui/dev_target_panes.test.mjs

@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  createDevTargetPaneSpecs,
+  routeDevTargetLogPaneId,
+} from './dev_target_panes.mjs';
+
+test('dev target panes add one Mutagen owner and one pane per configured remote worker', () => {
+  assert.deepEqual(
+    createDevTargetPaneSpecs([{ name: 'linux' }, { name: 'windows' }]),
+    [
+      { id: 'mutagen', title: 'mutagen sync', visible: true, kind: 'log' },
+      { id: 'remote-linux', title: 'remote linux', visible: true, kind: 'log' },
+      { id: 'remote-windows', title: 'remote windows', visible: true, kind: 'log' },
+    ],
+  );
+});
+
+test('dev target log routing recognizes only canonical owner prefixes', () => {
+  assert.equal(routeDevTargetLogPaneId('mutagen', new Set(['linux', 'windows'])), 'mutagen');
+  assert.equal(routeDevTargetLogPaneId('remote:linux', new Set(['linux', 'windows'])), 'remote-linux');
+  assert.equal(routeDevTargetLogPaneId('remote:windows', new Set(['linux', 'windows'])), 'remote-windows');
+  assert.equal(routeDevTargetLogPaneId('remote:unknown', new Set(['linux', 'windows'])), null);
+  assert.equal(routeDevTargetLogPaneId('daemon', new Set(['linux', 'windows'])), null);
+});

package/scripts/utils/tui/rescue_priority.mjs

@@ -0,0 +1,37 @@
+import { spawn } from 'node:child_process';
+
+const RESCUE_CONTROL_NICE = -5;
+
+async function runPrivilegedRenice({ pid, nice }) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn('sudo', ['renice', '-n', String(nice), '-p', String(pid)], {
+      stdio: 'inherit',
+      shell: false,
+    });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (code === 0) {
+        resolve({ ok: true });
+        return;
+      }
+      reject(new Error(
+        `Could not enable TUI rescue priority (sudo renice exited code=${code ?? 'null'}, signal=${signal ?? 'null'})`,
+      ));
+    });
+  });
+}
+
+export async function enableTuiRescuePriority(
+  { pid = process.pid, platform = process.platform } = {},
+  { runPrivilegedReniceImpl = runPrivilegedRenice } = {},
+) {
+  if (platform !== 'darwin' && platform !== 'linux') {
+    throw new Error(`TUI rescue priority is not supported on ${platform}`);
+  }
+  const normalizedPid = Number(pid);
+  if (!Number.isFinite(normalizedPid) || normalizedPid <= 1) {
+    throw new Error(`TUI rescue priority requires a valid process id (received ${pid})`);
+  }
+  await runPrivilegedReniceImpl({ pid: normalizedPid, nice: RESCUE_CONTROL_NICE });
+  return { nice: RESCUE_CONTROL_NICE, platform };
+}

package/scripts/utils/tui/rescue_priority.test.mjs

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { enableTuiRescuePriority } from './rescue_priority.mjs';
+
+test('enableTuiRescuePriority elevates only the current control process', async () => {
+  const calls = [];
+  const result = await enableTuiRescuePriority({ pid: 123, platform: 'darwin' }, {
+    runPrivilegedReniceImpl: async (input) => {
+      calls.push(input);
+      return { ok: true };
+    },
+  });
+
+  assert.deepEqual(calls, [{ pid: 123, nice: -5 }]);
+  assert.deepEqual(result, { nice: -5, platform: 'darwin' });
+});
+
+test('enableTuiRescuePriority rejects unsupported platforms instead of silently degrading', async () => {
+  await assert.rejects(
+    enableTuiRescuePriority({ pid: 123, platform: 'win32' }),
+    /not supported on win32/i,
+  );
+});

package/scripts/utils/tui/restart_operation.mjs

@@ -0,0 +1,151 @@
+import { normalizeStackRuntimeOwnerStartedAt } from '../stack/runtime_owner_incarnation.mjs';
+
+function isActiveChild(child) {
+  return Boolean(child && child.exitCode == null && child.signalCode == null);
+}
+
+function normalizeRuntimeOwnerIncarnation(runtimeOwner) {
+  const ownerPid = Number(runtimeOwner?.ownerPid);
+  const startedAt = normalizeStackRuntimeOwnerStartedAt(runtimeOwner?.startedAt);
+  if (!Number.isInteger(ownerPid) || ownerPid <= 1 || !startedAt) return null;
+  return { ownerPid, startedAt };
+}
+
+function isSameRuntimeOwnerIncarnation(left, right) {
+  return Boolean(left && right && left.ownerPid === right.ownerPid && left.startedAt === right.startedAt);
+}
+
+export function createTuiRuntimeOwnershipTracker({ runtimeOwnerBeforeSpawn = null } = {}) {
+  const baseline = normalizeRuntimeOwnerIncarnation(runtimeOwnerBeforeSpawn);
+  let expectedOwner = null;
+
+  return {
+    observe({ runtimeOwner = null, childActive = false, replacementAdmitted = false } = {}) {
+      const observed = normalizeRuntimeOwnerIncarnation(runtimeOwner);
+      if (!observed) return false;
+      if (replacementAdmitted) {
+        expectedOwner = observed;
+        return true;
+      }
+      if (!expectedOwner && childActive && !isSameRuntimeOwnerIncarnation(observed, baseline)) {
+        expectedOwner = observed;
+        return true;
+      }
+      return false;
+    },
+    getExpectedOwner() {
+      return expectedOwner ? { ...expectedOwner } : null;
+    },
+  };
+}
+
+function uniqueActiveChildren(children) {
+  const seen = new Set();
+  const active = [];
+  for (const child of children) {
+    if (!isActiveChild(child)) continue;
+    const key = Number.isFinite(Number(child?.pid)) ? `pid:${Number(child.pid)}` : child;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    active.push(child);
+  }
+  return active;
+}
+
+export function beginTuiRestartOperation({
+  currentOperation = null,
+  previousChild = null,
+  previousRuntimeOwner = null,
+  restartArgs = [],
+  spawnChild,
+  trackChild = () => {},
+  log = () => {},
+  refresh = () => {},
+} = {}) {
+  if (currentOperation?.pending) {
+    log('restart: canonical replacement is already in progress');
+    return { started: false, reason: 'in_progress', operation: currentOperation };
+  }
+
+  const incumbentRuntimeOwner = normalizeRuntimeOwnerIncarnation(previousRuntimeOwner);
+  if (!incumbentRuntimeOwner && isActiveChild(previousChild)) {
+    log('restart: current runtime owner evidence is unavailable; wait for the stack summary to refresh');
+    refresh();
+    return { started: false, reason: 'missing_runtime_owner', operation: null };
+  }
+
+  let replacementChild;
+  try {
+    replacementChild = spawnChild(restartArgs);
+  } catch (error) {
+    trackChild(previousChild);
+    log(`restart: replacement launch failed; previous runtime preserved (${error instanceof Error ? error.message : String(error)})`);
+    refresh();
+    return { started: false, reason: 'spawn_failed', operation: null, error };
+  }
+
+  let pending = true;
+  let settled = false;
+  const operation = {
+    get pending() {
+      return pending;
+    },
+    getActiveChildren() {
+      return uniqueActiveChildren([previousChild, replacementChild]);
+    },
+    observeRuntimeOwner(runtimeOwner) {
+      if (settled) return false;
+      const observed = normalizeRuntimeOwnerIncarnation(runtimeOwner);
+      if (!observed || isSameRuntimeOwnerIncarnation(observed, incumbentRuntimeOwner)) return false;
+      settle({
+        preservePrevious: false,
+        message: `restart: canonical owner admitted the replacement (ownerPid=${observed.ownerPid}, startedAt=${observed.startedAt})`,
+      });
+      return true;
+    },
+  };
+
+  const settle = ({ preservePrevious, message }) => {
+    if (settled) return;
+    settled = true;
+    pending = false;
+    trackChild(preservePrevious ? previousChild : replacementChild);
+    log(message);
+    refresh();
+  };
+
+  replacementChild.once('error', (error) => {
+    const previousStillActive = isActiveChild(previousChild);
+    settle({
+      preservePrevious: previousStillActive,
+      message: previousStillActive
+        ? `restart: replacement launch failed; previous runtime preserved (${error instanceof Error ? error.message : String(error)})`
+        : `restart: replacement launch failed (${error instanceof Error ? error.message : String(error)})`,
+    });
+  });
+  replacementChild.once('exit', (code, signal) => {
+    const previousStillActive = isActiveChild(previousChild);
+    settle({
+      preservePrevious: previousStillActive,
+      message: previousStillActive
+        ? `restart: canonical replacement exited before admission; previous runtime preserved (code=${code}, sig=${signal ?? 'null'})`
+        : `restart: replacement exited (code=${code}, sig=${signal ?? 'null'})`,
+    });
+  });
+
+  if (isActiveChild(previousChild)) {
+    previousChild.once('exit', () => {
+      if (settled) return;
+      trackChild(replacementChild);
+      log('restart: previous wrapper exited; waiting for canonical runtime owner admission');
+      refresh();
+    });
+  }
+
+  return { started: true, reason: 'started', operation, replacementChild };
+}
+
+export function resolveTuiShutdownChildren({ trackedChild = null, restartOperation = null } = {}) {
+  const operationChildren = restartOperation?.getActiveChildren?.() ?? [];
+  return uniqueActiveChildren([...operationChildren, trackedChild]);
+}

package/scripts/utils/tui/stack_scope_env.mjs

@@ -1,10 +1,15 @@
-import { applyStackActiveServerScopeEnv } from '../auth/stable_scope_id.mjs';
+import {
+  applyStackActiveServerScopeEnv,
+  applyStackDaemonLifecycleScopeEnv,
+} from '../auth/stable_scope_id.mjs';
 
 export function applyTuiStackAuthScopeEnv({ env, stackName }) {
   const base = env && typeof env === 'object' ? env : {};
   const name = String(stackName ?? '').trim() || (base.HAPPIER_STACK_STACK ?? '').toString().trim() || 'main';
   // Make credential/daemon state lookups stable per stack, even if the user's shell exported
   // a different HAPPIER_ACTIVE_SERVER_ID (common when main stack is running).
-  return applyStackActiveServerScopeEnv({ env: base, stackName: name });
+  return applyStackDaemonLifecycleScopeEnv({
+    env: applyStackActiveServerScopeEnv({ env: base, stackName: name }),
+    stackName: name,
+  });
 }
-

package/scripts/utils/tui/stack_scope_env.test.mjs

@@ -5,10 +5,15 @@ import { applyTuiStackAuthScopeEnv } from './stack_scope_env.mjs';
 
 test('applyTuiStackAuthScopeEnv overrides HAPPIER_ACTIVE_SERVER_ID per stack', () => {
   const env = applyTuiStackAuthScopeEnv({
-    env: { HAPPIER_ACTIVE_SERVER_ID: 'main', HAPPIER_STACK_CLI_IDENTITY: 'default' },
+    env: {
+      HAPPIER_ACTIVE_SERVER_ID: 'main',
+      HAPPIER_DAEMON_LIFECYCLE_SCOPE_ID: 'stack_other__id_default',
+      HAPPIER_STACK_CLI_IDENTITY: 'default',
+    },
     stackName: 'repo-dev-a1cc5e0671',
   });
   assert.equal(env.HAPPIER_ACTIVE_SERVER_ID, 'stack_repo-dev-a1cc5e0671__id_default');
+  assert.equal(env.HAPPIER_DAEMON_LIFECYCLE_SCOPE_ID, 'stack_repo-dev-a1cc5e0671__id_default');
 });
 
 test('applyTuiStackAuthScopeEnv deletes HAPPIER_ACTIVE_SERVER_ID when stable scope is disabled', () => {
@@ -17,5 +22,5 @@ test('applyTuiStackAuthScopeEnv deletes HAPPIER_ACTIVE_SERVER_ID when stable sco
     stackName: 'repo-dev-a1cc5e0671',
   });
   assert.equal(env.HAPPIER_ACTIVE_SERVER_ID, undefined);
+  assert.equal(env.HAPPIER_DAEMON_LIFECYCLE_SCOPE_ID, undefined);
 });
-

package/scripts/utils/tui/stdin_handoff.mjs

@@ -24,6 +24,11 @@ function safeResume(stdin) {
   }
 }
 
+export function ensureTuiStdinMode(stdin) {
+  safeSetRawMode(stdin, true);
+  safeResume(stdin);
+}
+
 /**
  * When we spawn a child with stdio: 'inherit', the child and the TUI compete for the same stdin FD.
  * If the TUI keeps reading, it will consume keystrokes before the child sees them.
@@ -46,8 +51,7 @@ export function detachTuiStdinForChild({ stdin, onData }) {
 
   return {
     restoreForTui() {
-      safeSetRawMode(stdin, true);
-      safeResume(stdin);
+      ensureTuiStdinMode(stdin);
       if (hadListener) {
         try {
           stdin.on('data', onData);
@@ -59,43 +63,12 @@ export function detachTuiStdinForChild({ stdin, onData }) {
   };
 }
 
-export async function waitForEnter({ stdin, timeoutMs = 120_000 } = {}) {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    // eslint-disable-next-line no-await-in-loop
-    const chunk = await new Promise((resolve) => {
-      const onData = (d) => {
-        cleanup();
-        resolve(d);
-      };
-      const onEnd = () => {
-        cleanup();
-        resolve(null);
-      };
-      const cleanup = () => {
-        try {
-          stdin?.off?.('data', onData);
-        } catch {
-          // ignore
-        }
-        try {
-          stdin?.off?.('end', onEnd);
-        } catch {
-          // ignore
-        }
-      };
-
-      try {
-        stdin?.on?.('data', onData);
-        stdin?.on?.('end', onEnd);
-      } catch {
-        resolve(null);
-      }
-    });
-
-    const s = chunk == null ? '' : String(chunk);
-    if (s.includes('\n') || s.includes('\r')) return true;
+export async function runWithTuiStdinHandoff({ stdin, onData, run }) {
+  if (typeof run !== 'function') throw new Error('runWithTuiStdinHandoff: run is required');
+  const handoff = detachTuiStdinForChild({ stdin, onData });
+  try {
+    return await run();
+  } finally {
+    handoff.restoreForTui();
   }
-  return false;
 }
-

package/scripts/utils/tui/stdin_handoff.test.mjs

@@ -2,7 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { EventEmitter } from 'node:events';
 
-import { detachTuiStdinForChild } from './stdin_handoff.mjs';
+import { detachTuiStdinForChild, ensureTuiStdinMode, runWithTuiStdinHandoff } from './stdin_handoff.mjs';
 
 test('detachTuiStdinForChild pauses stdin and detaches TUI data handler, then restores it', () => {
   const stdin = new EventEmitter();
@@ -27,3 +27,38 @@ test('detachTuiStdinForChild pauses stdin and detaches TUI data handler, then re
   assert.deepEqual(calls, ['pause', 'raw:false', 'raw:true', 'resume']);
 });
 
+test('ensureTuiStdinMode reasserts raw input ownership', () => {
+  const calls = [];
+  const stdin = {
+    setRawMode: (value) => calls.push(`raw:${String(Boolean(value))}`),
+    resume: () => calls.push('resume'),
+  };
+
+  ensureTuiStdinMode(stdin);
+
+  assert.deepEqual(calls, ['raw:true', 'resume']);
+});
+
+test('runWithTuiStdinHandoff restores raw input when the child action rejects', async () => {
+  const stdin = new EventEmitter();
+  const calls = [];
+  stdin.pause = () => calls.push('pause');
+  stdin.resume = () => calls.push('resume');
+  stdin.setRawMode = (value) => calls.push(`raw:${String(Boolean(value))}`);
+  const onData = () => {};
+  stdin.on('data', onData);
+
+  await assert.rejects(
+    runWithTuiStdinHandoff({
+      stdin,
+      onData,
+      run: async () => {
+        throw new Error('auth spawn failed');
+      },
+    }),
+    /auth spawn failed/,
+  );
+
+  assert.equal(stdin.listenerCount('data'), 1);
+  assert.deepEqual(calls, ['pause', 'raw:false', 'raw:true', 'resume']);
+});

package/scripts/utils/tui/tauri_mode.mjs

@@ -1,21 +1,69 @@
 import { isTuiStartLikeForwardedArgs } from './args.mjs';
 import { buildTauriRuntimeEnv } from '../dev/tauri_dev.mjs';
 import { join } from 'node:path';
-import { getRepoDir } from '../paths/paths.mjs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { getRepoDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { readStackRuntimeStateFile } from '../stack/runtime_state.mjs';
+import { assertRestartHasNoControlOnlyArgs } from '../stack/restart_args.mjs';
+import { looksLikeExpoMetro } from '../expo/expo.mjs';
+
+function ensureTuiWatchArg(args) {
+  if (!isTuiDevForwardedArgs(args) || args.includes('--watch') || args.includes('--no-watch')) {
+    return args;
+  }
+  return [...args, '--watch'];
+}
+
+function ensureTuiMobileArg(args) {
+  if (
+    !isTuiDevForwardedArgs(args)
+    || args.includes('--mobile')
+    || args.includes('--with-mobile')
+    || args.includes('--no-mobile')
+  ) {
+    return args;
+  }
+  return [...args, '--mobile'];
+}
+
+function isTuiDevForwardedArgs(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  if (!args.length) return false;
+
+  const first = String(args[0] ?? '').trim();
+  if (first === 'dev') return true;
+
+  const stackIdx = args.indexOf('stack');
+  if (stackIdx < 0) return false;
+  return String(args[stackIdx + 1] ?? '').trim() === 'dev';
+}
 
 export function buildTuiChildArgs({ forwardedArgs, withTauri } = {}) {
   const args = Array.isArray(forwardedArgs) ? forwardedArgs.map((arg) => String(arg ?? '')).filter(Boolean) : [];
+  const childArgs = ensureTuiMobileArg(ensureTuiWatchArg(args.length > 0 ? args : ['dev']));
   if (!withTauri) {
-    return args.length > 0 ? args : ['dev'];
+    return childArgs;
   }
 
-  const childArgs = args.length > 0 ? args : ['dev'];
   if (childArgs.includes('--no-browser')) {
     return childArgs;
   }
   return [...childArgs, '--no-browser'];
 }
 
+export function buildTuiRestartChildArgs({ childArgs, stackName = '' } = {}) {
+  const args = Array.isArray(childArgs) ? childArgs.map((arg) => String(arg ?? '')).filter(Boolean) : [];
+  assertRestartHasNoControlOnlyArgs(args);
+  const withoutRestart = args.filter((arg) => arg !== '--restart');
+  const resolvedStackName = String(stackName ?? '').trim();
+  const command = String(withoutRestart[0] ?? '').trim();
+  const canonicalArgs =
+    resolvedStackName && (command === 'dev' || command === 'start')
+      ? ['stack', command, resolvedStackName, ...withoutRestart.slice(1)]
+      : withoutRestart;
+  return [...canonicalArgs, '--restart'];
+}
+
 export function shouldStartTauriPane(forwardedArgs) {
   if (!isTuiStartLikeForwardedArgs(forwardedArgs)) {
     return false;
@@ -43,19 +91,143 @@ export function resolveTauriPaneInvocation({ rootDir, env = process.env } = {})
   };
 }
 
-export function buildTauriPaneEnv({ env = process.env, resolveUserHomeDir } = {}) {
-  return {
+export function buildTauriPaneEnv({ env = process.env, resolveUserHomeDir, forceExpoClearCache = false } = {}) {
+  const nextEnv = {
     ...buildTauriRuntimeEnv({ env, resolveUserHomeDir }),
     HAPPIER_STACK_TUI: '1',
     COREPACK_ENABLE_AUTO_PIN: '0',
     COREPACK_ENABLE_STRICT: '0',
   };
+  if (forceExpoClearCache && !String(nextEnv.HAPPIER_STACK_EXPO_CLEAR_CACHE ?? '').trim()) {
+    nextEnv.HAPPIER_STACK_EXPO_CLEAR_CACHE = '1';
+  }
+  return nextEnv;
 }
 
-export function resolveTauriPaneSpawnConfig({ rootDir, env = process.env, resolveUserHomeDir } = {}) {
+export function resolveTauriPaneLaunchEnv({
+  env = process.env,
+  resolveUserHomeDir,
+  expoPort = null,
+  skipExpoWait = false,
+} = {}) {
   const tauriEnv = buildTauriPaneEnv({ env, resolveUserHomeDir });
+  const resolvedExpoPort = Number(expoPort);
+  if (Number.isFinite(resolvedExpoPort) && resolvedExpoPort > 0) {
+    tauriEnv.HAPPIER_STACK_EXPO_DEV_PORT = String(Math.floor(resolvedExpoPort));
+  }
+  if (skipExpoWait) {
+    tauriEnv.HAPPIER_STACK_TAURI_WAIT_FOR_EXPO = '0';
+  }
+  return tauriEnv;
+}
+
+export function resolveTauriPaneSpawnConfig({
+  rootDir,
+  env = process.env,
+  resolveUserHomeDir,
+  expoPort = null,
+  skipExpoWait = false,
+} = {}) {
+  const tauriEnv = resolveTauriPaneLaunchEnv({
+    env,
+    resolveUserHomeDir,
+    expoPort,
+    skipExpoWait,
+  });
   return {
     invocation: resolveTauriPaneInvocation({ rootDir, env: tauriEnv }),
     env: tauriEnv,
   };
 }
+
+function resolveTauriPaneExpoWaitTimeoutMs(env = process.env) {
+  const raw = String(
+    env?.HAPPIER_STACK_TUI_TAURI_EXPO_WAIT_TIMEOUT_MS
+      ?? env?.HAPPIER_STACK_EXPO_METRO_WAIT_TIMEOUT_MS
+      ?? ''
+  ).trim();
+  if (!raw) {
+    return null;
+  }
+  const timeoutMs = Number(raw);
+  return Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.floor(timeoutMs) : null;
+}
+
+function resolveTauriPaneExpoWaitIntervalMs(env = process.env) {
+  const raw = String(
+    env?.HAPPIER_STACK_TUI_TAURI_EXPO_WAIT_INTERVAL_MS
+      ?? env?.HAPPIER_STACK_EXPO_METRO_WAIT_INTERVAL_MS
+      ?? ''
+  ).trim();
+  const intervalMs = Number(raw);
+  return Number.isFinite(intervalMs) && intervalMs > 0 ? Math.floor(intervalMs) : 500;
+}
+
+export function resolveRuntimeExpoPort(runtimeState) {
+  const expo = runtimeState && typeof runtimeState === 'object' ? runtimeState.expo : null;
+  const port = Number(expo?.port ?? expo?.webPort ?? expo?.mobilePort);
+  return Number.isFinite(port) && port > 0 ? Math.floor(port) : null;
+}
+
+export async function waitForTauriPaneExpoReady(
+  {
+    stackName,
+    env = process.env,
+    runtimeStatePath = '',
+    timeoutMs = null,
+    intervalMs = null,
+    isCancelled = () => false,
+  } = {},
+  {
+    readRuntimeStateImpl = readStackRuntimeStateFile,
+    looksLikeExpoMetroImpl = looksLikeExpoMetro,
+    delayImpl = delay,
+    nowMsImpl = () => Date.now(),
+  } = {},
+) {
+  const resolvedStackName = String(stackName ?? env?.HAPPIER_STACK_STACK ?? '').trim();
+  const resolvedRuntimeStatePath =
+    String(runtimeStatePath ?? '').trim()
+    || (resolvedStackName ? join(resolveStackEnvPath(resolvedStackName, env).baseDir, 'stack.runtime.json') : '');
+  if (!resolvedRuntimeStatePath) {
+    return { ok: false, reason: 'missing_runtime_state', port: null };
+  }
+
+  const resolvedTimeoutMs =
+    Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0
+      ? Number(timeoutMs)
+      : resolveTauriPaneExpoWaitTimeoutMs(env);
+  const resolvedIntervalMs =
+    Number.isFinite(Number(intervalMs)) && Number(intervalMs) > 0
+      ? Number(intervalMs)
+      : resolveTauriPaneExpoWaitIntervalMs(env);
+
+  const startMs = nowMsImpl();
+  let runtimeStateProbes = 0;
+  let metroProbes = 0;
+  const hasTimeout = Number.isFinite(resolvedTimeoutMs) && resolvedTimeoutMs > 0;
+
+  while (!hasTimeout || nowMsImpl() - startMs <= resolvedTimeoutMs) {
+    if (isCancelled()) {
+      return { ok: false, reason: 'cancelled', port: null, runtimeStateProbes, metroProbes };
+    }
+
+    // eslint-disable-next-line no-await-in-loop
+    const runtimeState = await readRuntimeStateImpl(resolvedRuntimeStatePath);
+    runtimeStateProbes += 1;
+    const port = resolveRuntimeExpoPort(runtimeState);
+    if (Number.isFinite(port) && port > 0) {
+      // eslint-disable-next-line no-await-in-loop
+      const metroReady = await looksLikeExpoMetroImpl({ port });
+      metroProbes += 1;
+      if (metroReady) {
+        return { ok: true, reason: 'ready', port, runtimeStateProbes, metroProbes };
+      }
+    }
+
+    // eslint-disable-next-line no-await-in-loop
+    await delayImpl(resolvedIntervalMs);
+  }
+
+  return { ok: false, reason: 'timeout', port: null, runtimeStateProbes, metroProbes };
+}