@swmansion/argent 0.19.0 → 0.19.1-next.0

package/dist/cli-cmds.mjs

@@ -9547,7 +9547,11 @@ filename (minus .yaml) names the run's report and artifacts, so it must
 contain only letters, numbers, "_", or "-" \u2014 the same charset a name must
 match. A flow that begins with a \`launch\` step runs its app from scratch; any
 other flow (a fragment) runs against the device's current state \u2014 handy while
-authoring one.
+authoring one. Exception: a fragment whose first step \`run:\`s a chromium e2e
+flow boots that flow's app before step 1 \u2014 when that launch is unambiguously
+chromium (a lone \`{ chromium: ... }\` target, or --platform chromium); a
+multi-platform launch auto-detects a device instead. Pass --device to attach to
+a running instance.
 
 A directory run prints only failing steps plus a final flow summary;
 --recursive walks subdirectories too (dot-directories and node_modules are
@@ -9674,7 +9678,7 @@ function renderUnderStepLine(s, n2, text2) {
 function renderSummary(report, opts = {}) {
   const warnings = report.steps.filter((s) => s.warning).length;
   const warningsNote = warnings ? `, ${warnings} warning${warnings === 1 ? "" : "s"}` : "";
-  const where = opts.withDevice && report.device ? ` on ${report.device}` : "";
+  const where = opts.withDevice && report.device ? ` (started on ${report.device})` : "";
   const nothingCounted = report.ok && report.passed + report.failed + report.errored + report.skipped === 0;
   const note = nothingCounted ? " (no test steps)" : "";
   return `${report.ok ? "PASS" : "FAIL"}${where} \u2014 ${report.passed} passed, ${report.failed} failed, ${report.errored} errored, ${report.skipped} skipped${warningsNote}${note}`;

package/dist/tool-server.cjs

@@ -792,6 +792,12 @@ function getFailureSignal(error52) {
 function getFailureSignalOrFallback(error52, fallback = FALLBACK_SIGNAL) {
   return getFailureSignal(error52) ?? fallback;
 }
+function wrapFailure(error52, fallback, message) {
+  const cause = error52 instanceof Error ? error52 : new Error(String(error52));
+  return new FailureError(message ?? cause.message, getFailureSignalOrFallback(cause, fallback), {
+    cause
+  });
+}
 function subprocessFailureMetadata(error52, failure_command) {
   const metadata = { failure_command };
   const err = error52;
@@ -124390,6 +124396,7 @@ function electronGuiChildEnv(overrides = {}) {
 
 // ../tool-server/src/tools/devices/boot-electron.ts
 var DEFAULT_READY_TIMEOUT_MS = 3e4;
+var BOOT_CONFIRM_WINDOW_MS = 300;
 async function pickFreePort() {
   return new Promise((resolve10, reject) => {
     const srv = net5.createServer();
@@ -124488,11 +124495,22 @@ function sanitizeExtraArgs(extra) {
     return true;
   });
 }
+function signalGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch (err) {
+    return err.code !== "ESRCH";
+  }
+}
 function killChildEscalating(child) {
   try {
     child.kill("SIGTERM");
   } catch {
   }
+  if (child.pid !== void 0 && (child.exitCode !== null || child.signalCode !== null)) {
+    signalGroup(child.pid, "SIGTERM");
+  }
   setTimeout(() => {
     if (child.exitCode === null && child.signalCode === null) {
       try {
@@ -124500,6 +124518,9 @@ function killChildEscalating(child) {
       } catch {
       }
     }
+    if (child.pid !== void 0 && signalGroup(child.pid, 0)) {
+      signalGroup(child.pid, "SIGKILL");
+    }
   }, 2e3).unref();
 }
 var liveChildren = /* @__PURE__ */ new Map();
@@ -124512,21 +124533,33 @@ function killChromiumByPort(port, pid) {
   }
   if (pid !== void 0) killChromiumByPidFallback(pid);
 }
+var EXIT_WAIT_TIMEOUT_MS = 5e3;
+var EXIT_POLL_MS = 50;
+async function killChromiumByPortAndWait(port, pid, timeoutMs = EXIT_WAIT_TIMEOUT_MS) {
+  const child = liveChildren.get(port);
+  const alive = child && child.exitCode === null && child.signalCode === null;
+  const exited = alive ? new Promise((resolve10) => child.once("exit", () => resolve10())) : null;
+  killChromiumByPort(port, pid);
+  if (exited) return Promise.race([exited, sleepUnref(timeoutMs)]);
+  if (!child && pid !== void 0) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (!signalGroup(pid, 0)) return;
+      await sleepUnref(EXIT_POLL_MS);
+    }
+  }
+}
+function sleepUnref(ms) {
+  return new Promise((resolve10) => {
+    setTimeout(resolve10, ms).unref();
+  });
+}
 function killChromiumByPidFallback(pid) {
-  if (signalPid(pid, "SIGTERM") === "gone") return;
+  if (!signalGroup(pid, "SIGTERM")) return;
   setTimeout(() => {
-    if (signalPid(pid, 0) === "gone") return;
-    signalPid(pid, "SIGKILL");
+    if (signalGroup(pid, 0)) signalGroup(pid, "SIGKILL");
   }, 2e3).unref();
 }
-function signalPid(pid, signal) {
-  try {
-    process.kill(pid, signal);
-    return "sent";
-  } catch (err) {
-    return err.code === "ESRCH" ? "gone" : "sent";
-  }
-}
 var ANTI_THROTTLING_ARGS = [
   "--disable-background-timer-throttling",
   "--disable-backgrounding-occluded-windows",
@@ -124642,6 +124675,7 @@ async function bootElectronApp(options) {
       earlyExit,
       spawnError
     ]);
+    await Promise.race([earlyExit, sleepUnref(BOOT_CONFIRM_WINDOW_MS)]);
   } catch (err) {
     detachBootListeners();
     killChildEscalating(child);
@@ -148287,7 +148321,7 @@ var zodSchema60 = external_exports.object({
     "Absolute path to the project root directory (the directory that contains or should contain `.argent/flows/`). The flow file is created at `<project_root>/.argent/flows/<name>.yaml`."
   ),
   executionPrerequisite: external_exports.string().optional().describe(
-    'Fragments only: the app/device state assumed on entry (e.g. "Settings app open on General page"). For a self-contained e2e flow, omit this and record a `restart-app` as the first step instead \u2014 it is captured as the flow\'s `launch` step.'
+    'Fragments only: the app/device state assumed on entry (e.g. "Settings app open on General page"). For a self-contained e2e flow, omit this and record a `restart-app` as the first step instead \u2014 it is captured as the flow\'s `launch` step. restart-app has no chromium support, so a chromium flow records as a fragment; add the `launch: { chromium: <app path> }` line to the YAML afterward, deleting the executionPrerequisite line if you passed one \u2014 a flow that starts with a launch must not declare it.'
   )
 });
 var fileInputs2 = [
@@ -149058,7 +149092,7 @@ function createFlowAddStepTool(registry2) {
       completedMsg: ({ params }) => `Added ${params.command} step to recorded flow`,
       failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to add ${params.command} step to recorded flow: ${failureSignal2.error_code}`
     },
-    description: `Execute a tool call and record it as a step in the active flow. Use when recording a flow with flow-start-recording and you want to run and capture each action. A coordinate \`gesture-tap\` is recorded as a portable \`tap: { selector }\` step when the tapped element has stable text/identifier (otherwise coordinates are kept with a warning); a \`restart-app\` is recorded as a \`launch\` step (record one FIRST to make the flow a self-contained e2e flow). Returns { message, toolResult, flowFile } on success. If it fails an error is returned and nothing is recorded.
+    description: `Execute a tool call and record it as a step in the active flow. Use when recording a flow with flow-start-recording and you want to run and capture each action. A coordinate \`gesture-tap\` is recorded as a portable \`tap: { selector }\` step when the tapped element has stable text/identifier (otherwise coordinates are kept with a warning); a \`restart-app\` is recorded as a \`launch\` step (record one FIRST to make the flow a self-contained e2e flow; restart-app has no chromium support, so a chromium flow records as a fragment \u2014 add the \`launch: { chromium: <app path> }\` line to the YAML afterward, deleting the executionPrerequisite line if one was recorded: a flow that starts with a launch must not declare it). Returns { message, toolResult, flowFile } on success. If it fails an error is returned and nothing is recorded.
 If a step was recorded by mistake, edit the .yaml file directly to remove it.`,
     zodSchema: zodSchema61,
     services: () => ({}),
@@ -151967,6 +152001,15 @@ async function runSnapshot(env, opts) {
   const key = `${snapshotKey}.png`;
   const dir = baselineDir(opts.flowsDir, opts.flowName);
   const baselinePath = path34.join(dir, key);
+  const priorApp = opts.seenKeys.get(snapshotKey);
+  if (priorApp !== void 0 && priorApp !== opts.appIdentity) {
+    return {
+      status: "fail",
+      reason: `snapshot "${opts.name}" was already captured in this run from a different app (${priorApp}) \u2014 both captures would share the baseline ${key}, nothing was compared. Give per-app snapshots distinct names`,
+      snapshotKey
+    };
+  }
+  opts.seenKeys.set(snapshotKey, opts.appIdentity);
   let currentPath = shot.image.hostPath;
   let cropDir;
   let keepCropped = false;
@@ -152262,34 +152305,7 @@ async function treeSourceGate(registry2, device, bundleId, signal) {
 async function runLaunch(state3, app) {
   const env = deviceEnv(state3);
   const { registry: registry2, device, signal } = env;
-  if (device.platform === "chromium") {
-    if (state3.chromiumLaunched) {
-      return {
-        ok: false,
-        reason: `chromium launches only the top-level flow's app, once per run \u2014 a nested launch can't boot its own instance and would run against the already-launched app. Nested chromium e2e flows aren't supported: run this flow at the top level, or drop its launch step to make it a fragment.`
-      };
-    }
-    state3.chromiumLaunched = true;
-    if (state3.chromiumBooted) {
-      if (!await sleepOrAbort(POST_LAUNCH_SETTLE_MS, signal)) return ABORTED_OUTCOME;
-      return { ok: true };
-    }
-    if (!appIdForPlatform(app, "chromium")) {
-      return { ok: false, reason: `no chromium app declared \u2014 add a chromium launch entry` };
-    }
-    try {
-      const ref = chromiumCdpRef(device);
-      const api = await registry2.resolveService(ref.urn, ref.options);
-      await api.refreshViewport();
-    } catch (err) {
-      return {
-        ok: false,
-        reason: `could not attach to chromium instance "${device.id}": ${errMsg2(err)}`
-      };
-    }
-    if (!await sleepOrAbort(POST_LAUNCH_SETTLE_MS, signal)) return ABORTED_OUTCOME;
-    return { ok: true };
-  }
+  if (device.platform === "chromium") return runChromiumLaunch(state3, app);
   const bundleId = appIdForPlatform(app, device.platform);
   if (!bundleId) {
     return {
@@ -152309,6 +152325,137 @@ async function runLaunch(state3, app) {
   if (gate) return { ok: false, reason: gate };
   return { ok: true };
 }
+async function runChromiumLaunch(state3, app) {
+  const { registry: registry2, device, signal } = deviceEnv(state3);
+  if (state3.chromiumLaunched) return bootChromiumForLaunch(state3, app);
+  state3.chromiumLaunched = true;
+  const spec = chromiumLaunchSpec(app);
+  if (!spec) return { ok: false, reason: noChromiumAppReason(device) };
+  const owned = ownedInstance(state3);
+  if (owned) {
+    const declared = await resolveAppPath(spec.path, state3.flowsDir);
+    if (declared !== owned.appPath) {
+      return {
+        ok: false,
+        reason: `launch declares "${declared}" but the instance booted for this run is "${owned.appPath}" \u2014 the flow file changed after the run started`
+      };
+    }
+    if (!await sleepOrAbort(POST_LAUNCH_SETTLE_MS, signal)) return ABORTED_OUTCOME;
+    return { ok: true, reason: `booted chromium instance ${device.id}` };
+  }
+  try {
+    const ref = chromiumCdpRef(device);
+    const api = await registry2.resolveService(ref.urn, ref.options);
+    await api.refreshViewport();
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `could not attach to chromium instance "${device.id}": ${errMsg2(err)}`
+    };
+  }
+  state3.attachedAppPath = await resolveAppPath(spec.path, state3.flowsDir);
+  for (const [key, appId] of state3.snapshotApps) {
+    if (appId === `attached:${device.id}`) state3.snapshotApps.set(key, state3.attachedAppPath);
+  }
+  if (!await sleepOrAbort(POST_LAUNCH_SETTLE_MS, signal)) return ABORTED_OUTCOME;
+  return { ok: true };
+}
+async function bootChromiumForLaunch(state3, app) {
+  const { registry: registry2, device, signal } = deviceEnv(state3);
+  const spec = chromiumLaunchSpec(app);
+  if (!spec) return { ok: false, reason: noChromiumAppReason(device) };
+  const appPath = await resolveAppPath(spec.path, state3.flowsDir);
+  const prevId = device.id;
+  const retiring = state3.owned.findIndex((o) => o.appPath === appPath);
+  let retiredId;
+  if (retiring !== -1) {
+    const [prev] = state3.owned.splice(retiring, 1);
+    retiredId = prev.deviceId;
+    await teardownBootedChromium(registry2, prev);
+  }
+  let booted;
+  try {
+    booted = await bootChromiumForFlow(spec, state3.flowsDir, state3.viaUpload);
+  } catch (err) {
+    return { ok: false, reason: await chromiumBootFailureReason(state3, err) };
+  }
+  state3.owned.push(booted);
+  state3.device = resolveDevice(booted.deviceId);
+  await frontChromiumPage(registry2, state3.device);
+  if (!await sleepOrAbort(POST_LAUNCH_SETTLE_MS, signal)) return ABORTED_OUTCOME;
+  const move = retiredId === prevId ? `retired ${prevId} (same app relaunched)` : `run moved off ${prevId}`;
+  const alsoRetired = retiredId !== void 0 && retiredId !== prevId ? `, retired ${retiredId} (same app relaunched)` : "";
+  return {
+    ok: true,
+    reason: `booted chromium instance ${booted.deviceId} \u2014 ${move}${alsoRetired}`
+  };
+}
+var LOCK_SUSPECT_PROBE_TIMEOUT_MS = 800;
+function singleInstanceLockSignal(err) {
+  const signal = getFailureSignal(err);
+  if (signal?.error_code !== FAILURE_CODES.CHROMIUM_ELECTRON_EXITED_BEFORE_READY || signal.failure_exit_code !== 0) {
+    return null;
+  }
+  return signal;
+}
+var NO_LOCK_SUSPECTS = Object.freeze({ attached: null, owned: [] });
+function singleInstanceLockHint(suspects) {
+  const clauses = [];
+  if (suspects.attached) {
+    clauses.push(
+      `${suspects.attached} is running and this run does not own it; if it is this same app, it holds that lock.`
+    );
+  }
+  if (suspects.owned.length > 0) {
+    const owned = suspects.owned.map((o) => `${o.deviceId} (${o.appPath})`).join(", ");
+    clauses.push(
+      `This run booted ${owned}, alive until run end \u2014 an app path that shares an Electron \`name\` with this one shares its lock. That holder is the runner's own, so closing it is not on offer and a rerun fails identically; launch them in separate runs, or give this launch its own \`--user-data-dir\` in \`args\`.`
+    );
+  }
+  if (clauses.length === 0)
+    clauses.push(`If a copy of this app is already running, close it and rerun.`);
+  return `A clean exit before CDP comes up is the signature of a single-instance lock \u2014 an already-running copy of the app quits the new one at startup. ${clauses.join(" ")}`;
+}
+async function chromiumBootFailureReason(state3, err) {
+  const base = `could not boot the chromium app: ${errMsg2(err)}`;
+  if (!singleInstanceLockSignal(err)) return base;
+  return `${base} ${singleInstanceLockHint(await liveLockSuspects(state3))}`;
+}
+async function liveLockSuspects(state3) {
+  const [attached, owned] = await Promise.all([
+    liveAttachedInstance(state3),
+    liveOwnedInstances(state3)
+  ]);
+  return { attached, owned };
+}
+async function liveAttachedInstance(state3) {
+  const id = state3.attachedDeviceId;
+  if (id === void 0) return null;
+  const port = parseChromiumCdpPort(id);
+  if (port === null) return null;
+  return await answersCdp(port) ? id : null;
+}
+async function liveOwnedInstances(state3) {
+  const alive = await Promise.all(state3.owned.map((o) => answersCdp(o.port)));
+  return state3.owned.filter((_, i) => alive[i]);
+}
+async function answersCdp(port) {
+  try {
+    await ensureCdpReachable(port, AbortSignal.timeout(LOCK_SUSPECT_PROBE_TIMEOUT_MS));
+    return true;
+  } catch {
+    return false;
+  }
+}
+function ownedInstance(state3) {
+  return state3.owned.find((o) => o.deviceId === state3.device?.id);
+}
+function snapshotAppIdentity(state3) {
+  return ownedInstance(state3)?.appPath ?? state3.attachedAppPath ?? `attached:${deviceEnv(state3).device.id}`;
+}
+function noChromiumAppReason(device) {
+  return `no chromium app declared \u2014 the run is on ${device.id}; add a \`chromium:\` entry to this launch`;
+}
 function deviceEnv(state3) {
   if (!state3.device) {
     throw new Error("internal: a step that acts on a device ran in a flow resolved as device-free");
@@ -152385,11 +152532,22 @@ checked once with the short assert grace \u2014 for one-sided divergences like i
 marks; a skipped block reports distinctly and failures inside an entered block are real failures.
 A flow that begins with a \`launch\` step is a self-contained e2e flow; one that doesn't runs against the
 device's current state. Device id is injected by the runner (flows store none) \u2014 pass \`device\` or
-\`platform\` to pick one, else the single booted device is used. For a Chromium e2e flow the \`launch\`
-step's chromium value is an Electron app path ({ chromium: <path> | { path, args } }); the runner boots a
-fresh instance from it (on the tool-server host) and tears it down when the run ends, unless an explicit
-\`device\` pins an already-running instance. Every step hard-stops the flow on failure;
-later steps are reported as skipped. Returns a structured report ({ ok, passed, failed, skipped, errored, steps }).
+\`platform\` to pick one, else the single booted device is used. On Chromium a \`launch\` step's value is an
+Electron app path ({ chromium: <path> | { path, args } }) the runner boots (on the tool-server host) rather
+than an installed app id it relaunches. With no explicit \`device\`, a run whose leading launch is
+unambiguously chromium (\`platform: chromium\`, or a lone \`{ chromium: \u2026 }\` target) boots that app and
+starts there \u2014 following a leading \`run:\`, so a fragment that composes a chromium e2e flow boots too;
+otherwise the first launch attaches to an already-running instance and never kills it. Every later
+launch \u2014 a nested e2e flow's own, or a mid-flow relaunch \u2014 boots a fresh instance the run moves onto;
+an instance the run already owns for that same app is killed first (its exit awaited) so the
+replacement can't lose the race against its single-instance lock. Instances the runner still owns at
+run end are torn down then. A launch declaring no id for the run's platform is an error, not a cue to
+switch platforms. Every step hard-stops the flow on failure; later steps are reported as skipped.
+Returns a structured report ({ flow, device, executionPrerequisite, ok, aborted?, passed, failed,
+skipped, errored, steps }) \u2014 \`device\` is the device the run STARTED on; when launches moved it onto
+runner-booted instances, each names its instance in that step's reason and marks the move \u2014 \`run moved
+off <id>\`, or \`retired <id> (same app relaunched)\` when the instance it left was the one killed \u2014
+a relaunch that retired an older owned instance names both.
 
 If a fragment has an execution prerequisite and prerequisiteAcknowledged is not set to true, the tool
 returns a notice with the prerequisite instead of running.`,
@@ -152409,6 +152567,22 @@ returns a notice with the prerequisite instead of running.`,
       const flowsDir = path35.dirname(canonicalPath);
       const flow = parseFlow(await fs49.readFile(canonicalPath, "utf8"));
       if (viaUpload) assertUploadSelfContained(flow);
+      const rootEntry = { canonical: canonicalPath, display: flowName };
+      if (flow.executionPrerequisite && !pinnedToChromium(params.device)) {
+        const leading = await leadingLaunch(flow, [rootEntry]);
+        if (leading) {
+          const pinRemedy = chromiumPinnable(leading.app, params.platform) ? ` Or pin the run to a chromium instance you have already brought to that state (--device chromium-cdp-<port>), where the leading launch only attaches.` : "";
+          throw new FailureError(
+            `A flow whose leading run: chain reaches a launch step must not declare executionPrerequisite \u2014 it launches its own app and controls its start state. Drop the leading launch in "${leading.flow}" to make it a fragment, or drop executionPrerequisite from "${flowName}".${pinRemedy}`,
+            {
+              error_code: FAILURE_CODES.FLOW_E2E_HAS_PREREQUISITE,
+              failure_stage: "flow_run_validate",
+              failure_area: "tool_server",
+              error_kind: "validation"
+            }
+          );
+        }
+      }
       if (flow.executionPrerequisite && !params.prerequisiteAcknowledged) {
         return {
           flow: flowName,
@@ -152416,7 +152590,15 @@ returns a notice with the prerequisite instead of running.`,
           executionPrerequisite: flow.executionPrerequisite
         };
       }
-      const resolved = await resolveRunDevice(registry2, ctx, flow, params, flowsDir, viaUpload);
+      const resolved = await resolveRunDevice(
+        registry2,
+        ctx,
+        flow,
+        params,
+        flowsDir,
+        rootEntry,
+        viaUpload
+      );
       const device = resolved.device;
       const statusBarPinned = device !== null && await pinStatusBar(device);
       if (device?.platform === "chromium") await frontChromiumPage(registry2, device);
@@ -152426,25 +152608,30 @@ returns a notice with the prerequisite instead of running.`,
         device,
         signal,
         flowsDir,
+        viaUpload,
         baselineKey: baselineKeyFor(canonicalPath, flowName),
         updateBaselines: Boolean(params.updateBaselines),
         reports: [],
         stopped: false,
         pinned: statusBarPinned,
-        chromiumBooted: resolved.booted !== null,
+        owned: resolved.booted ? [resolved.booted] : [],
         chromiumLaunched: false,
+        snapshotApps: /* @__PURE__ */ new Map(),
+        ...!resolved.booted && device?.platform === "chromium" ? { attachedDeviceId: device.id } : {},
         ...ctx?.emitProgress ? { onStepReport: ctx.emitProgress } : {}
       };
       let aborted2;
       try {
         await execSteps(state3, flow.steps, {
-          runStack: [{ canonical: canonicalPath, display: flowName }],
+          runStack: [rootEntry],
           depth: 0
         });
       } finally {
         aborted2 = state3.signal?.aborted === true;
         if (state3.pinned && device) await restoreStatusBar(device);
-        if (resolved.booted) await teardownBootedChromium(registry2, resolved.booted);
+        for (let i = state3.owned.length - 1; i >= 0; i--) {
+          await teardownBootedChromium(registry2, state3.owned[i]);
+        }
       }
       return summarize(
         flowName,
@@ -152456,11 +152643,17 @@ returns a notice with the prerequisite instead of running.`,
     }
   };
 }
-async function resolveRunDevice(registry2, ctx, flow, params, flowDir, viaUpload) {
+async function resolveRunDevice(registry2, ctx, flow, params, flowDir, rootEntry, viaUpload) {
   if (!params.device) {
-    const spec = chromiumBootSpec(flow, params.platform);
+    const leading = await leadingLaunch(flow, [rootEntry]);
+    const spec = leading && chromiumBootSpec(leading.app, params.platform);
     if (spec) {
-      const booted = await bootChromiumForFlow(spec, flowDir, viaUpload);
+      let booted;
+      try {
+        booted = await bootChromiumForFlow(spec, flowDir, viaUpload);
+      } catch (err) {
+        throw hoistedBootFailure(err);
+      }
       return { device: resolveDevice(booted.deviceId), booted };
     }
     if (!flowRequiresDevice(registry2, flow.steps)) {
@@ -152473,12 +152666,54 @@ async function resolveRunDevice(registry2, ctx, flow, params, flowDir, viaUpload
   });
   return { device, booted: null };
 }
-function chromiumBootSpec(flow, platform) {
-  if (!isE2eFlow(flow)) return null;
-  const first = flow.steps.find((s) => s.kind !== "echo");
-  if (!first || first.kind !== "launch") return null;
-  if (launchTargetPlatform(first.app, platform) !== "chromium") return null;
-  return chromiumLaunchSpec(first.app);
+function hoistedBootFailure(err) {
+  const signal = singleInstanceLockSignal(err);
+  if (!signal) return err;
+  return wrapFailure(err, signal, `${errMsg2(err)} ${singleInstanceLockHint(NO_LOCK_SUSPECTS)}`);
+}
+function pinnedToChromium(device) {
+  return device !== void 0 && resolveDevice(device).platform === "chromium";
+}
+function chromiumPinnable(app, platform) {
+  if (typeof app === "string") return platform === "chromium";
+  return chromiumLaunchSpec(app) !== null;
+}
+var NO_EXECUTABLE_STEP = "no-executable-step";
+async function leadingLaunch(flow, stack) {
+  const found = await scanLeadingLaunch(flow, stack);
+  return found === NO_EXECUTABLE_STEP ? null : found;
+}
+async function scanLeadingLaunch(flow, stack) {
+  const top = stack[stack.length - 1];
+  for (const step of flow.steps) {
+    if (step.kind === "echo") continue;
+    if (step.kind === "launch") return { app: step.app, flow: top.display };
+    if (step.kind !== "run") return null;
+    const spelled = path35.dirname(top.canonical) + path35.sep + step.flow;
+    let nested;
+    let canonical;
+    try {
+      canonical = await canonicalFlowPath(spelled);
+      if (stack.some((entry) => entry.canonical === canonical)) return null;
+      if (stack.length >= MAX_RUN_DEPTH) return null;
+      const supplied = path35.posix.basename(step.flow);
+      const spelling = await classifyOnDiskSpelling(path35.dirname(spelled), supplied);
+      if (spelling.state === "case_folded") return null;
+      nested = parseFlow(await fs49.readFile(canonical, "utf8"));
+    } catch {
+      return null;
+    }
+    const inner = await scanLeadingLaunch(nested, [
+      ...stack,
+      { canonical, display: runDisplayFor(step.flow, stack[0].display) }
+    ]);
+    if (inner !== NO_EXECUTABLE_STEP) return inner;
+  }
+  return NO_EXECUTABLE_STEP;
+}
+function chromiumBootSpec(app, platform) {
+  if (launchTargetPlatform(app, platform) !== "chromium") return null;
+  return chromiumLaunchSpec(app);
 }
 function launchTargetPlatform(launch, platform) {
   if (platform) return platform;
@@ -152488,6 +152723,14 @@ function launchTargetPlatform(launch, platform) {
   }
   return null;
 }
+async function resolveAppPath(specPath, flowDir) {
+  const lexical = path35.resolve(flowDir, specPath);
+  try {
+    return await fs49.realpath(lexical);
+  } catch {
+    return lexical;
+  }
+}
 async function bootChromiumForFlow(spec, flowDir, viaUpload) {
   if (viaUpload && !path35.isAbsolute(spec.path)) {
     throw new FailureError(
@@ -152500,9 +152743,9 @@ async function bootChromiumForFlow(spec, flowDir, viaUpload) {
       }
     );
   }
-  const appPath = path35.isAbsolute(spec.path) ? spec.path : path35.resolve(flowDir, spec.path);
+  const appPath = await resolveAppPath(spec.path, flowDir);
   const res = await bootElectronApp({ appPath, extraArgs: spec.args });
-  return { deviceId: res.id, port: res.port, pid: res.pid };
+  return { deviceId: res.id, port: res.port, pid: res.pid, appPath: res.appPath };
 }
 async function teardownBootedChromium(registry2, booted) {
   const urn = `${CHROMIUM_CDP_NAMESPACE}:${booted.deviceId}`;
@@ -152511,8 +152754,11 @@ async function teardownBootedChromium(registry2, booted) {
     if (entry && isLiveServiceState(entry.state)) await registry2.disposeService(urn);
   } catch {
   }
-  killChromiumByPort(booted.port, booted.pid);
-  untrackChromiumPort(booted.port);
+  try {
+    await killChromiumByPortAndWait(booted.port, booted.pid);
+    untrackChromiumPort(booted.port);
+  } catch {
+  }
 }
 async function frontChromiumPage(registry2, device) {
   try {
@@ -152614,8 +152860,11 @@ function scopeFlow(scope) {
   return scope.runStack[scope.runStack.length - 1].display;
 }
 function runDisplayName(target, scope) {
+  return runDisplayFor(target, scope.runStack[0].display);
+}
+function runDisplayFor(target, rootDisplay) {
   const stem = runTargetName(target);
-  if (stem !== scope.runStack[0].display) return stem;
+  if (stem !== rootDisplay) return stem;
   const spelled = target.slice(0, -".yaml".length);
   return spelled === stem ? `./${stem}` : spelled;
 }
@@ -152879,7 +153128,9 @@ async function execLeafStep(state3, step, index, scope) {
           name: step.name,
           maxMismatch: step.maxMismatch ?? DEFAULT_MAX_MISMATCH,
           updateBaselines: state3.updateBaselines,
-          cropOn: step.cropOn
+          cropOn: step.cropOn,
+          appIdentity: snapshotAppIdentity(state3),
+          seenKeys: state3.snapshotApps
         });
         return {
           ...base,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.19.0",
+  "version": "0.19.1-next.0",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",

package/skills/argent-create-flow/SKILL.md

@@ -11,10 +11,10 @@ Flows store **no device id**: the runner binds a device (the single booted one,
 
 **Two flow types**
 
-- **e2e** — begins with a `launch:` step, which starts that app from scratch (terminate + relaunch), so the flow controls its own start state. No `executionPrerequisite`. May `run:` other flows, and (on iOS/Android) may itself be a `run:` target — when nested, its `launch` runs inline, restarting the app for that sub-scenario. **Chromium is the exception:** the runner boots one Electron app per run (the top-level flow's), so a nested chromium e2e flow's `launch` can't boot its own instance and fails the run — keep chromium e2e flows top-level. Record one by adding a `restart-app` of the app under test as the **first** step — it is captured as the `launch` step.
-- **fragment** — doesn't begin with a launch; runs against the device's current state. May declare an `executionPrerequisite` (a documented entry-state contract). Invoked from other flows via a `run:` step, or directly by you at any time.
+- **e2e** — begins with a `launch:` step, which starts that app from scratch (terminate + relaunch), so the flow controls its own start state. No `executionPrerequisite`. May `run:` other flows, and may itself be a `run:` target — when nested, its `launch` runs inline, restarting the app for that sub-scenario. **On Chromium a launch is a process, not a relaunch:** the "device" is the booted app (its id is the CDP port). The runner needs a device before step 1, so it boots for the launch the run _begins_ with, following a leading `run:` — a fragment whose first step composes a chromium e2e flow boots that flow's app (pass `--platform chromium` when the launch names several platforms, or the target is ambiguous and auto-detection is used instead). That first launch then just settles the instance it was booted for; every _later_ launch — a nested e2e flow's own, or a mid-flow `launch:` of the same app — boots its own instance and the run moves onto it for the remaining steps, replacing the one the runner already owns for that app. Every instance the runner boots is torn down at run end; one you pinned with `--device` is attached to, never killed — so relaunching _that_ app mid-flow fails if it holds a single-instance lock. A launch that names no id for the run's platform is an error — a `chromium:` entry does not make a flow runnable on iOS, and the run never switches platforms mid-flight. Record one by adding a `restart-app` of the app under test as the **first** step — it is captured as the `launch` step. Not on Chromium, though: `restart-app` has no chromium support and only successful calls are recorded, so a recorded chromium flow is always a fragment — write the `launch: { chromium: <app path> }` line into the YAML yourself afterward, and delete any `executionPrerequisite` the recording declared: with its own launch the flow controls its start state, and a launch-first flow must not carry one.
+- **fragment** — doesn't begin with a launch; runs against the device's current state. May declare an `executionPrerequisite` (a documented entry-state contract). Invoked from other flows via a `run:` step, or directly by you at any time. One exception to "current state": a fragment whose **first** step `run:`s a chromium e2e flow takes on that flow's launch — the runner boots that app before step 1 (see the e2e bullet; pass `--device` to attach to a running instance instead).
 
-Both run via `argent flow run <flow|flow.yaml>` — a fragment simply runs against whatever is on screen (its prerequisite is printed as a reminder). A bare name is read from `.argent/flows/<name>.yaml`; anything ending in `.yaml` is a path. Only e2e flows are meaningful CI/suite entries, since only they give a deterministic verdict from a clean start.
+Both run via `argent flow run <flow|flow.yaml>` — a fragment simply runs against whatever is on screen (its prerequisite is printed as a reminder), except the chromium leading-`run:` case above, which boots. A bare name is read from `.argent/flows/<name>.yaml`; anything ending in `.yaml` is a path. Only e2e flows are meaningful CI/suite entries, since only they give a deterministic verdict from a clean start.
 
 ### Step directives
 
@@ -118,7 +118,7 @@ Since a `tv-remote` path is positional (like a coordinate tap), gate each naviga
 
 ### Standalone runner
 
-`argent flow run <flow|flow.yaml|dir> [--device <id>] [--platform ios|android|chromium|vega] [--update-baselines] [--output <dir>] [-r|--recursive] [--json]` runs a flow with no LLM in the loop and exits non-zero on any failure — suitable for CI (e2e flows; a fragment runs against the current device state, useful while authoring). The argument is either a saved flow's name, read from `.argent/flows/<name>.yaml` under the current directory, or a `.yaml` file path (relative to the current directory, or absolute) for a flow kept anywhere else. The two never collide: a name carries no separator and no extension, so an argument ending in `.yaml` is always a path and never falls back to the flows directory. Either way the filename (minus `.yaml`) names the run's report and artifacts, so it must contain only letters, numbers, `_`, or `-`. A directory path runs every flow in it sequentially, printing only failing steps plus a final `passed/failed/skipped` flow summary (`--json` prints one aggregate object); `-r`/`--recursive` walks subdirectories too, skipping dot-directories and `node_modules`. An invalid flow file fails alone and the batch continues; an infra error stops the batch, counting the remaining flows skipped. Only a path reaches a directory — a name always resolves to one `.yaml` file. `argent flow list` prints runnable paths for flows saved under `.argent/flows/` — a nested one is addressable by its path only.
+`argent flow run <flow|flow.yaml|dir> [--device <id>] [--platform ios|android|chromium|vega] [--update-baselines] [--output <dir>] [-r|--recursive] [--json]` runs a flow with no LLM in the loop and exits non-zero on any failure — suitable for CI (e2e flows; a fragment runs against the current device state, useful while authoring — unless its first step `run:`s a chromium e2e flow, which boots that app). The argument is either a saved flow's name, read from `.argent/flows/<name>.yaml` under the current directory, or a `.yaml` file path (relative to the current directory, or absolute) for a flow kept anywhere else. The two never collide: a name carries no separator and no extension, so an argument ending in `.yaml` is always a path and never falls back to the flows directory. Either way the filename (minus `.yaml`) names the run's report and artifacts, so it must contain only letters, numbers, `_`, or `-`. A directory path runs every flow in it sequentially, printing only failing steps plus a final `passed/failed/skipped` flow summary (`--json` prints one aggregate object); `-r`/`--recursive` walks subdirectories too, skipping dot-directories and `node_modules`. An invalid flow file fails alone and the batch continues; an infra error stops the batch, counting the remaining flows skipped. Only a path reaches a directory — a name always resolves to one `.yaml` file. `argent flow list` prints runnable paths for flows saved under `.argent/flows/` — a nested one is addressable by its path only.
 
 The standalone command uses only the auto-started local tool server. It is unavailable while `ARGENT_TOOLS_URL` or `argent link` routing is active; unset `ARGENT_TOOLS_URL` or run `argent unlink` first. This restriction applies only to the CLI: an agent may continue calling `flow-execute` with `name` and `project_root`, including through a remote tool server — but a remote call uploads the one YAML into a temp directory on the server, and both `run:` targets (whose referenced files stay behind on the client) and `__baselines__/` resolve beside that copy, so only a self-contained flow replays remotely (see _Replaying_).
 
@@ -159,7 +159,7 @@ Record an `await-ui-element` step to **gate** the next step on a screen transiti
 
 ## Recording
 
-1. **Start, then launch as the first step (e2e) or set the stage yourself (fragment).** Call `flow-start-recording` with a descriptive name and the absolute `project_root`. For an **e2e** flow, record a `restart-app` of the app under test as the **first** step — it runs live (resetting the device for the rest of the recording) and is captured as the flow's `launch` step. For a **fragment**, bring the device to the entry state _before_ recording and pass an `executionPrerequisite` describing it (e.g. "App on the login screen") to `flow-start-recording` instead.
+1. **Start, then launch as the first step (e2e) or set the stage yourself (fragment).** Call `flow-start-recording` with a descriptive name and the absolute `project_root`. For an **e2e** flow, record a `restart-app` of the app under test as the **first** step — it runs live (resetting the device for the rest of the recording) and is captured as the flow's `launch` step (`restart-app` has no chromium support, so on Chromium record the flow as a fragment against the running app and add the `launch:` line to the YAML afterward, deleting the `executionPrerequisite` line if you passed one — a launch-first flow must not declare it). For a **fragment**, bring the device to the entry state _before_ recording and pass an `executionPrerequisite` describing it (e.g. "App on the login screen") to `flow-start-recording` instead.
 2. **Build step-by-step**: for each action, call `flow-add-step` with the tool name and args. The tool runs immediately — check the result before moving on, and gate each navigation with an `await-ui-element` step.
 3. **Add labels**: use `flow-add-echo` between steps — echo the expected state, not just the action (see _Making flows resilient_).
 4. **Finish**: call `flow-finish-recording`. It returns the file path where the flow was saved and a summary of all steps.