@flowriki/agent 0.1.0-beta.64 → 0.1.0-beta.66

package/dist/{chunk-RI63WNGU.js → chunk-YD7F7JMA.js}

@@ -16,10 +16,12 @@ import os3 from "os";
 import path3 from "path";
 import { execFile as execFile2 } from "child_process";
 import fs4 from "fs";
-import os4 from "os";
 import path4 from "path";
+import fs5 from "fs";
+import os4 from "os";
+import path5 from "path";
 
-// ../test-model/dist/chunk-I5COYCQ5.js
+// ../test-model/dist/chunk-6JIZJVPN.js
 import { z as z2 } from "zod";
 import { z } from "zod";
 var PLATFORMS = ["web", "android", "ios"];
@@ -69,7 +71,10 @@ var CloudAccountSchema = z.object({
   provider: z.enum(CLOUD_PROVIDERS),
   username: z.string().trim().min(1).max(200),
   /** Sauce Labs data centre: "us-west-1", "eu-central-1", "us-east-4". */
-  region: z.string().trim().max(40).optional(),
+  /** A Sauce Labs region — a word like us-west-1, never an address: it is
+   *  spelled into the host the farm's key is sent to. Anything else is
+   *  dropped, and the default region used. */
+  region: z.string().trim().max(40).optional().transform((v) => v && /^[a-z]{2}-[a-z]+-\d$/.test(v) ? v : void 0),
   keyRef: z.string().regex(/^[a-z][a-z0-9_]*$/)
 }).strict();
 var DeviceChoiceSchema = z.discriminatedUnion("kind", [
@@ -629,19 +634,19 @@ var CHECK_TARGET_FIELDS = [
 var unset = (value) => value === void 0 || value === null || value === "" || Array.isArray(value) && value.length === 0;
 function mirrorCheckTargets(steps) {
   return steps.map((step) => {
-    const held = step;
-    if (held["type"] !== "assert") return step;
-    const proposals = held["proposals"];
+    const held2 = step;
+    if (held2["type"] !== "assert") return step;
+    const proposals = held2["proposals"];
     if (!Array.isArray(proposals)) return step;
     const first = proposals[0];
     const target = first?.["target"];
     if (!target) return step;
     const fill = {};
     for (const field of CHECK_TARGET_FIELDS) {
-      if (!unset(held[field]) || unset(target[field])) continue;
+      if (!unset(held2[field]) || unset(target[field])) continue;
       fill[field] = target[field];
     }
-    return Object.keys(fill).length === 0 ? step : { ...held, ...fill };
+    return Object.keys(fill).length === 0 ? step : { ...held2, ...fill };
   });
 }
 
@@ -660,6 +665,9 @@ import { z as z11 } from "zod";
 import { z as z12 } from "zod";
 import { z as z13 } from "zod";
 import { z as z14 } from "zod";
+import { z as z15 } from "zod";
+import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 var EngineSchema = z3.enum(["chromium", "firefox", "webkit", "android", "ios"]);
 var CapabilitySchema = z3.object({
   id: z3.string(),
@@ -1446,11 +1454,52 @@ var HttpHelperSchema = z5.object({
     pattern: z5.string().max(500).default("")
   }).strict().default({})
 }).strict();
+var CommandLineSchema = z5.object({
+  program: z5.string().trim().min(1).max(500),
+  args: z5.array(z5.string().max(2e3)).max(50).default([])
+}).strict();
+var EnvName = z5.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "an environment variable name is letters, digits and _");
+var CommandHelperSchema = z5.object({
+  kind: z5.literal("command"),
+  /** What runs everywhere, unless a system has its own below. */
+  run: CommandLineSchema,
+  /** The same job on another system — a different program, or a .cmd on
+   *  Windows. A tester's computer uses its own when there is one. */
+  perSystem: z5.object({
+    macos: CommandLineSchema.optional(),
+    windows: CommandLineSchema.optional(),
+    linux: CommandLineSchema.optional()
+  }).strict().default({}),
+  /** Where it runs: a folder inside the project's checkout, or empty for the
+   *  project's folder (the agent's own folder when there is no checkout). */
+  folder: z5.string().max(500).default(""),
+  /** Plain environment variables, in the repository. */
+  env: z5.record(EnvName, z5.string().max(2e3)).default({}),
+  /** Environment variable → vault reference: how a token reaches the command
+   *  without ever being on its command line. */
+  secretEnv: z5.record(EnvName, SecretRef).default({}),
+  /** `run` waits for it to finish; `background` starts it, waits until it is
+   *  ready, and stops it when the test ends — a mock server, a simulator. */
+  mode: z5.enum(["run", "background"]).default("run"),
+  /** Background: the output line that says it is ready. Empty waits a
+   *  couple of seconds instead. */
+  readyPattern: z5.string().max(500).default(""),
+  timeoutSeconds: z5.number().int().min(1).max(600).default(60),
+  /** Refused unless it ends with this exit code. */
+  expectExit: z5.number().int().min(0).max(255).default(0),
+  extract: z5.object({
+    take: z5.enum(["output", "pattern", "json", "nothing"]).default("output"),
+    pattern: z5.string().max(500).default(""),
+    /** For json: a dot path — `device.id`. */
+    path: z5.string().max(300).default("")
+  }).strict().default({})
+}).strict();
 var HelperConfigSchema = z5.discriminatedUnion("kind", [
   MailboxHelperSchema,
   TotpHelperSchema,
   SmsHelperSchema,
-  HttpHelperSchema
+  HttpHelperSchema,
+  CommandHelperSchema
 ]);
 var HelperSchema = z5.object({
   schemaVersion: z5.literal(HELPER_SCHEMA_VERSION),
@@ -1467,7 +1516,9 @@ var HelperSchema = z5.object({
   const patterns = [
     helper.config.kind === "mailbox" && helper.config.extract.take === "code" ? helper.config.extract.pattern : "",
     helper.config.kind === "sms" ? helper.config.extract.pattern : "",
-    helper.config.kind === "http" && helper.config.extract.take === "pattern" ? helper.config.extract.pattern : ""
+    helper.config.kind === "http" && helper.config.extract.take === "pattern" ? helper.config.extract.pattern : "",
+    helper.config.kind === "command" && helper.config.extract.take === "pattern" ? helper.config.extract.pattern : "",
+    helper.config.kind === "command" ? helper.config.readyPattern : ""
   ];
   for (const pattern of patterns) {
     if (pattern && !PatternSchema.safeParse(pattern).success) {
@@ -1475,6 +1526,12 @@ var HelperSchema = z5.object({
     }
   }
 });
+function commandFor(config, system) {
+  return config.perSystem[system] ?? config.run;
+}
+function commandSystemOf(platform) {
+  return platform === "win32" ? "windows" : platform === "darwin" ? "macos" : "linux";
+}
 var DeliveredHelperSchema = z5.object({
   id: z5.string().min(1),
   name: z5.string(),
@@ -1832,7 +1889,7 @@ function decodeEntities(text) {
 var nameKey = (name) => decodeEntities(name).toLowerCase().replace(/&/g, " and ").replace(/[^\p{L}\p{N}]+/gu, " ").trim();
 var PLATFORM_PART = "(web|android|ios)";
 var LEARNED_PATH = new RegExp(`^(explore\\/${PLATFORM_PART}\\.md|memory\\/sessions\\/[a-z0-9][a-z0-9-]{0,120}\\.md)$`);
-var isLearnedPath = (path8) => LEARNED_PATH.test(path8);
+var isLearnedPath = (path9) => LEARNED_PATH.test(path9);
 var LearnedSchema = z11.object({
   id: z11.string().regex(/^lrn_[a-z0-9_-]+$/),
   projectId: z11.string().min(1),
@@ -1873,6 +1930,29 @@ var WhatToDoSchema = z13.object({
   skipped: z13.array(z13.string().min(1).max(80)).max(100),
   updatedAt: z13.string()
 }).strict();
+var BLOCKER_KINDS = ["app-bug", "needs-person", "unclear-step", "not-found", "stuck"];
+var CaseStandingSchema = z14.discriminatedUnion("state", [
+  z14.object({
+    state: z14.literal("blocked"),
+    kind: z14.enum(BLOCKER_KINDS),
+    /** The business step it stopped at, counted from 1 — when it was one. */
+    line: z14.number().int().positive().max(500).optional(),
+    lineText: z14.string().max(500).optional(),
+    detail: z14.string().min(1).max(1500),
+    /** What would unblock it, said for a person. */
+    needs: z14.string().max(600).optional(),
+    platform: z14.enum(["web", "android", "ios"]).optional(),
+    by: z14.string().max(200),
+    at: z14.string()
+  }).strict(),
+  z14.object({
+    state: z14.literal("manual"),
+    /** Why it is run by hand, when somebody said. */
+    reason: z14.string().max(600).optional(),
+    by: z14.string().max(200),
+    at: z14.string()
+  }).strict()
+]);
 var CaseRegistrySchema = z14.object({
   id: z14.string().regex(/^creg_/),
   projectId: z14.string().min(1),
@@ -1880,11 +1960,83 @@ var CaseRegistrySchema = z14.object({
   cases: z14.record(z14.string(), z14.number().int().positive()),
   features: z14.record(z14.string(), z14.number().int().positive()),
   reviews: z14.record(z14.string(), z14.object({ hash: z14.string(), by: z14.string().max(200), at: z14.string() }).strict()),
+  /** Blocked and manual cases, by case id. Absent on a project with none. */
+  standing: z14.record(z14.string(), CaseStandingSchema).optional(),
   updatedAt: z14.string()
 }).strict();
+var BranchChoiceSchema = z15.object({
+  id: z15.string().regex(/^bch_/),
+  projectId: z15.string().min(1),
+  userId: z15.string().min(1),
+  /** The branch (a change id), or null for the published version. */
+  changeId: z15.string().min(1).max(100).nullable(),
+  at: z15.string()
+}).strict();
+var TokensSchema = z16.object({
+  /** Read fresh — the request, minus what came from the cache. */
+  input: z16.number().int().nonnegative(),
+  output: z16.number().int().nonnegative(),
+  /** Read from the prompt cache: a tenth of the price of fresh input. */
+  cacheRead: z16.number().int().nonnegative(),
+  /** Written to the prompt cache, so later turns can read it cheaply. */
+  cacheWrite: z16.number().int().nonnegative()
+}).strict();
+var USAGE_STAGES = ["write", "automate", "setup", "knowledge", "reply"];
+var USAGE_KINDS = ["automate", "reautomate", "heal", "update", "write", "explore", "chat"];
+function usageKindOf(shown) {
+  const s = shown.trim();
+  if (/^Heal\b/i.test(s)) return "heal";
+  if (/^Re-automate\b/i.test(s)) return "reautomate";
+  if (/^Automate\b/i.test(s)) return "automate";
+  if (/business steps of .* (just )?changed/i.test(s) || /^Update\b/i.test(s)) return "update";
+  if (/^Explore\b|\bexplore (the|this) (app|site|website)\b/i.test(s)) return "explore";
+  if (/^(Write|Import)\b.*test cases?/i.test(s)) return "write";
+  return "chat";
+}
+var UsagePartSchema = TokensSchema.extend({
+  stage: z16.enum(USAGE_STAGES),
+  /** The tool the turn called; null for a turn that called none. */
+  tool: z16.string().max(80).nullable(),
+  /** The test case the work was for, when one was being worked on. */
+  caseName: z16.string().max(300).nullable(),
+  folder: z16.string().max(300).nullable(),
+  /** Its id — TC-12 — when the assistant named it by id. */
+  caseKey: z16.string().max(40).nullable(),
+  /** The flow being recorded, when one was. */
+  flow: z16.string().max(300).nullable(),
+  /** How many turns are in this line. */
+  turns: z16.number().int().nonnegative()
+}).strict();
+var UsageRecordSchema = z16.object({
+  id: z16.string().regex(/^use_/),
+  projectId: z16.string().min(1),
+  userId: z16.string().min(1),
+  jobId: z16.string().min(1),
+  kind: z16.enum(USAGE_KINDS),
+  /** The start of what was asked, so a list of jobs reads as one. */
+  asked: z16.string().max(200),
+  platform: z16.enum(["web", "android", "ios"]).nullable(),
+  startedAt: z16.string(),
+  finishedAt: z16.string().nullable(),
+  status: z16.enum(["running", "done", "failed", "stopped"]),
+  /** Every turn added up, from the turns as they happened. */
+  totals: TokensSchema,
+  turns: z16.number().int().nonnegative(),
+  /** What the model said the whole job cost, in US dollars — at API prices;
+   *  on a Claude plan it is what the same work would cost there. */
+  costUsd: z16.number().nonnegative().nullable(),
+  durationMs: z16.number().int().nonnegative().nullable(),
+  parts: z16.array(UsagePartSchema).max(600)
+}).strict();
+var StepRenameSchema = z17.object({
+  occurrenceId: z17.string().min(1).max(200),
+  stepId: z17.string().min(1).max(200),
+  from: z17.string().min(1).max(500),
+  to: z17.string().trim().min(1).max(200)
+}).strict();
 
 // ../engine-appium/dist/index.js
-import path5 from "path";
+import path6 from "path";
 
 // ../core/dist/index.js
 function proposeAssertions(before, after) {
@@ -2217,9 +2369,9 @@ var STEP_PRESENTATION = {
 };
 
 // ../engine-appium/dist/index.js
-import path6 from "path";
-import fs5 from "fs";
 import path7 from "path";
+import fs6 from "fs";
+import path8 from "path";
 import { spawn as spawn3 } from "child_process";
 var WebDriverError = class extends Error {
   constructor(message, error, status) {
@@ -2231,10 +2383,10 @@ var WebDriverError = class extends Error {
   status;
 };
 var ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecc";
-async function call(endpoint, method, path8, body, timeoutMs = 12e4) {
+async function call(endpoint, method, path9, body, timeoutMs = 12e4) {
   const headers = { "content-type": "application/json; charset=utf-8" };
   if (endpoint.username) headers["authorization"] = `Basic ${Buffer.from(`${endpoint.username}:${endpoint.password ?? ""}`).toString("base64")}`;
-  const res = await fetch(`${endpoint.url.replace(/\/+$/, "")}${path8}`, {
+  const res = await fetch(`${endpoint.url.replace(/\/+$/, "")}${path9}`, {
     method,
     headers,
     ...method === "POST" ? { body: JSON.stringify(body ?? {}) } : {},
@@ -2273,11 +2425,11 @@ var WebDriverSession = class _WebDriverSession {
     return new _WebDriverSession(endpoint, value.sessionId, value.capabilities ?? {});
   }
   /** Any other command — Appium's own extensions live under /appium/. */
-  raw(method, path8, body, timeoutMs) {
-    return this.req(method, path8, body, timeoutMs);
+  raw(method, path9, body, timeoutMs) {
+    return this.req(method, path9, body, timeoutMs);
   }
-  req(method, path8, body, timeoutMs) {
-    return call(this.endpoint, method, `/session/${this.id}${path8}`, body, timeoutMs);
+  req(method, path9, body, timeoutMs) {
+    return call(this.endpoint, method, `/session/${this.id}${path9}`, body, timeoutMs);
   }
   source() {
     return this.req("GET", "/source");
@@ -2380,8 +2532,8 @@ function appiumPath() {
 }
 function javaMajor(home) {
   try {
-    const release = fs.readFileSync(path.join(home, "release"), "utf8");
-    const v = /JAVA_VERSION="(\d+)(?:\.(\d+))?/.exec(release);
+    const release2 = fs.readFileSync(path.join(home, "release"), "utf8");
+    const v = /JAVA_VERSION="(\d+)(?:\.(\d+))?/.exec(release2);
     if (!v) return 0;
     return v[1] === "1" ? Number(v[2] ?? 0) : Number(v[1]);
   } catch {
@@ -3304,6 +3456,88 @@ async function checkMobileAssertion(session, a, timeoutMs = 3e3) {
   }
   throw last;
 }
+var held = /* @__PURE__ */ new Map();
+var lockDir = () => path4.join(process.env["FLOWRIKI_HOME"] || AGENT_HOME, "locks");
+var fileFor = (udid) => path4.join(lockDir(), `device-${udid.replace(/[^A-Za-z0-9._-]/g, "_")}.lock`);
+var alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+};
+var DeviceInUse = class extends Error {
+  constructor(device, pid) {
+    super(`${device} is being used by another Flowriki job on this computer \u2014 wait for it to finish, or stop it first`);
+    this.device = device;
+    this.pid = pid;
+    this.name = "DeviceInUse";
+  }
+  device;
+  pid;
+};
+function lockDevice(udid, name = udid) {
+  const file = fileFor(udid);
+  const mine = held.get(file);
+  if (mine) {
+    held.set(file, mine + 1);
+    return once(() => release(file));
+  }
+  fs4.mkdirSync(lockDir(), { recursive: true, mode: 448 });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs4.openSync(file, "wx", 384);
+      fs4.writeSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
+      fs4.closeSync(fd);
+      held.set(file, 1);
+      return once(() => release(file));
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      let owner = 0;
+      try {
+        owner = Number(JSON.parse(fs4.readFileSync(file, "utf8")).pid) || 0;
+      } catch {
+      }
+      if (owner && owner !== process.pid && alive(owner)) throw new DeviceInUse(name, owner);
+      try {
+        fs4.unlinkSync(file);
+      } catch {
+      }
+    }
+  }
+  throw new DeviceInUse(name, 0);
+}
+function release(file) {
+  const count = held.get(file) ?? 0;
+  if (count > 1) {
+    held.set(file, count - 1);
+    return;
+  }
+  held.delete(file);
+  try {
+    const owner = Number(JSON.parse(fs4.readFileSync(file, "utf8")).pid);
+    if (owner === process.pid) fs4.unlinkSync(file);
+  } catch {
+  }
+}
+function once(fn) {
+  let done = false;
+  return () => {
+    if (!done) {
+      done = true;
+      fn();
+    }
+  };
+}
+process.once("exit", () => {
+  for (const file of held.keys()) {
+    try {
+      fs4.unlinkSync(file);
+    } catch {
+    }
+  }
+});
 var uploaded = /* @__PURE__ */ new Map();
 var OPEN = /* @__PURE__ */ new Map();
 var openSessionOn = (platform) => OPEN.get(platform) ?? null;
@@ -3321,6 +3555,8 @@ var MobileSession = class _MobileSession {
   deviceName;
   cloud;
   cached = null;
+  /** Lets go of this phone for other Flowriki processes — see device-lock. */
+  releaseDevice = null;
   static async open(target, opts = {}) {
     const app = appOf(target);
     const say = opts.onProgress ?? (() => {
@@ -3342,11 +3578,11 @@ var MobileSession = class _MobileSession {
         }
       }
       say(`Opening ${choice2.device} on ${CLOUD_PROVIDER_NAME[choice2.provider]}\u2026`);
-      const { endpoint: endpoint2, capabilities: capabilities2 } = cloudCapabilities(target, account, key, appRef);
-      const driver2 = await WebDriverSession.create(endpoint2, capabilities2).catch((e) => {
+      const { endpoint, capabilities } = cloudCapabilities(target, account, key, appRef);
+      const driver = await WebDriverSession.create(endpoint, capabilities).catch((e) => {
         throw new Error(`${CLOUD_PROVIDER_NAME[choice2.provider]} could not open ${choice2.device}: ${e.message}`);
       });
-      const cloudSession = new _MobileSession(driver2, target.platform, app.id, choice2.device, true);
+      const cloudSession = new _MobileSession(driver, target.platform, app.id, choice2.device, true);
       OPEN.set(target.platform, cloudSession);
       await cloudSession.settle(2e4);
       return cloudSession;
@@ -3358,23 +3594,30 @@ var MobileSession = class _MobileSession {
     if (known.platform !== target.platform) throw new Error(`${known.name} is ${known.platform === "ios" ? "an iOS" : "an Android"} device; this flow runs on ${target.platform === "ios" ? "iOS" : "Android"}.`);
     if (known.state !== "ready") say(`Starting ${known.name}\u2026`);
     const udid = await bootDevice(known);
-    const endpoint = await appiumServer();
-    const buildFile = app.build ? await localBuild(app.build) : null;
-    say(`Opening the app on ${known.name}\u2026`);
-    const ports = target.platform === "android" ? { system: await freePort(), mjpeg: await freePort() } : { wda: await freePort(), mjpeg: await freePort() };
-    const activity = target.platform === "android" && !app.activity && !buildFile ? await launchActivityOf(udid, app.id) : null;
-    const capabilities = await localCapabilities(target, udid, { buildFile, ports, ...activity ? { activity } : {} });
-    const driver = await WebDriverSession.create(endpoint, capabilities).catch((e) => {
-      const tail = appiumLog().filter((l) => /error/i.test(l)).slice(-2).join(" ");
-      throw new Error(explainStartFailure(e.message, target.platform) + (tail ? ` (${tail.slice(0, 300)})` : ""));
-    });
-    const session = new _MobileSession(driver, target.platform, app.id, known.name, false);
-    OPEN.set(target.platform, session);
-    await session.terminateApp().catch(() => {
-    });
-    await session.launchApp().catch(() => {
-    });
-    return session;
+    const releaseDevice = lockDevice(udid, known.name);
+    try {
+      const endpoint = await appiumServer();
+      const buildFile = app.build ? await localBuild(app.build) : null;
+      say(`Opening the app on ${known.name}\u2026`);
+      const ports = target.platform === "android" ? { system: await freePort(), mjpeg: await freePort() } : { wda: await freePort(), mjpeg: await freePort() };
+      const activity = target.platform === "android" && !app.activity && !buildFile ? await launchActivityOf(udid, app.id) : null;
+      const capabilities = await localCapabilities(target, udid, { buildFile, ports, ...activity ? { activity } : {} });
+      const driver = await WebDriverSession.create(endpoint, capabilities).catch((e) => {
+        const tail = appiumLog().filter((l) => /error/i.test(l)).slice(-2).join(" ");
+        throw new Error(explainStartFailure(e.message, target.platform) + (tail ? ` (${tail.slice(0, 300)})` : ""));
+      });
+      const session = new _MobileSession(driver, target.platform, app.id, known.name, false);
+      session.releaseDevice = releaseDevice;
+      OPEN.set(target.platform, session);
+      await session.terminateApp().catch(() => {
+      });
+      await session.launchApp().catch(() => {
+      });
+      return session;
+    } catch (error) {
+      releaseDevice();
+      throw error;
+    }
   }
   // ── Reading ────────────────────────────────────────────────────────────
   async screen() {
@@ -3405,8 +3648,8 @@ var MobileSession = class _MobileSession {
   async screenshot(file) {
     const png = Buffer.from(await this.driver.screenshot(), "base64");
     if (file) {
-      fs4.mkdirSync(path4.dirname(file), { recursive: true });
-      fs4.writeFileSync(file, png);
+      fs5.mkdirSync(path5.dirname(file), { recursive: true });
+      fs5.writeFileSync(file, png);
     }
     return png;
   }
@@ -3607,14 +3850,19 @@ var MobileSession = class _MobileSession {
     const b64 = await this.driver.raw("POST", "/appium/stop_recording_screen", { options: {} }, 12e4).catch(() => "");
     if (!file || !b64) return null;
     const bytes = Buffer.from(b64, "base64");
-    fs4.mkdirSync(path4.dirname(file), { recursive: true });
-    fs4.writeFileSync(file, bytes);
-    return { relPath: path4.basename(file), bytes: bytes.length };
+    fs5.mkdirSync(path5.dirname(file), { recursive: true });
+    fs5.writeFileSync(file, bytes);
+    return { relPath: path5.basename(file), bytes: bytes.length };
   }
   async close() {
     if (OPEN.get(this.platform) === this) OPEN.delete(this.platform);
-    if (this.recording) await this.stopVideo(null);
-    await this.driver.close();
+    try {
+      if (this.recording) await this.stopVideo(null);
+      await this.driver.close();
+    } finally {
+      this.releaseDevice?.();
+      this.releaseDevice = null;
+    }
   }
 };
 async function launchActivityOf(udid, appPackage) {
@@ -3630,18 +3878,18 @@ async function launchActivityOf(udid, appPackage) {
 }
 async function shrink(png, maxPx) {
   if (process.platform !== "darwin") return png;
-  const dir = fs4.mkdtempSync(path4.join(os4.tmpdir(), "flowriki-shot-"));
-  const file = path4.join(dir, "s.png");
+  const dir = fs5.mkdtempSync(path5.join(os4.tmpdir(), "flowriki-shot-"));
+  const file = path5.join(dir, "s.png");
   try {
-    fs4.writeFileSync(file, png);
+    fs5.writeFileSync(file, png);
     await new Promise((resolve, reject) => {
       execFile2("/usr/bin/sips", ["-Z", String(maxPx), file], { timeout: 5e3 }, (error) => error ? reject(error) : resolve());
     });
-    return fs4.readFileSync(file);
+    return fs5.readFileSync(file);
   } catch {
     return png;
   } finally {
-    fs4.rmSync(dir, { recursive: true, force: true });
+    fs5.rmSync(dir, { recursive: true, force: true });
   }
 }
 var ANDROID_KEYS = {
@@ -3901,7 +4149,7 @@ async function runMobileSteps(session, steps, opts) {
       if (opts.evidenceDir && (shots === "always" || shots === "on-failure" && result.status === "failed")) {
         const file = `step-${String((opts.stepOffset ?? 0) + results.length + 1).padStart(2, "0")}.png`;
         try {
-          await session.screenshot(path5.join(opts.evidenceDir, file));
+          await session.screenshot(path6.join(opts.evidenceDir, file));
           result.evidence = { screenshot: file, url: await session.currentScreenName(), title: session.deviceName };
         } catch {
         }
@@ -3925,7 +4173,7 @@ var typesSecrets = (steps) => steps.some((s) => s.secret || Boolean(s.secretRef)
 var filmsThis = (policy, steps, evidenceDir) => Boolean(evidenceDir) && Boolean(policy) && policy.mode !== "off" && (policy.allowUnmasked === true || !typesSecrets(steps));
 async function finishVideo(session, policy, evidenceDir, passed, name = "phone") {
   const keep = Boolean(evidenceDir) && (policy?.mode === "always" || policy?.mode === "on-failure" && !passed);
-  const saved = await session.stopVideo(keep ? path6.join(evidenceDir, `video-${name}.mp4`) : null).catch(() => null);
+  const saved = await session.stopVideo(keep ? path7.join(evidenceDir, `video-${name}.mp4`) : null).catch(() => null);
   return saved ? [{ kind: "video", relPath: saved.relPath, bytes: saved.bytes }] : [];
 }
 async function chooseDevice(platform, mobile, asked, where) {
@@ -4054,20 +4302,20 @@ function stream(file, args, env, cwd, say) {
     child.stdout.on("data", each);
     child.stderr.on("data", each);
     child.on("error", reject);
-    child.on("close", (code) => code === 0 ? resolve() : reject(new Error(`${path7.basename(file)} ${args.join(" ")} failed (${code})`)));
+    child.on("close", (code) => code === 0 ? resolve() : reject(new Error(`${path8.basename(file)} ${args.join(" ")} failed (${code})`)));
   });
 }
 async function mobileSetup(say = console.log) {
   const npm = onPath("npm");
   if (!npm) throw new Error("npm was not found \u2014 install Node.js 20 or newer.");
-  fs5.mkdirSync(path7.join(APPIUM_DIR, "home"), { recursive: true });
-  if (!fs5.existsSync(path7.join(APPIUM_DIR, "package.json"))) {
-    fs5.writeFileSync(path7.join(APPIUM_DIR, "package.json"), JSON.stringify({ name: "flowriki-appium", private: true }, null, 2));
+  fs6.mkdirSync(path8.join(APPIUM_DIR, "home"), { recursive: true });
+  if (!fs6.existsSync(path8.join(APPIUM_DIR, "package.json"))) {
+    fs6.writeFileSync(path8.join(APPIUM_DIR, "package.json"), JSON.stringify({ name: "flowriki-appium", private: true }, null, 2));
   }
-  const env = { ...await toolEnv(), APPIUM_HOME: path7.join(APPIUM_DIR, "home") };
+  const env = { ...await toolEnv(), APPIUM_HOME: path8.join(APPIUM_DIR, "home") };
   say("Installing Appium\u2026");
   await stream(npm, ["install", "--no-audit", "--no-fund", "appium@2"], env, APPIUM_DIR, say);
-  const bin = path7.join(APPIUM_DIR, "node_modules", ".bin", process.platform === "win32" ? "appium.cmd" : "appium");
+  const bin = path8.join(APPIUM_DIR, "node_modules", ".bin", process.platform === "win32" ? "appium.cmd" : "appium");
   const have = await installedDrivers();
   const wanted = ["uiautomator2", ...process.platform === "darwin" ? ["xcuitest"] : []];
   for (const driver of wanted) {
@@ -4253,6 +4501,8 @@ export {
   sameIdentity,
   PrerequisiteProblem,
   expandForRun,
+  commandFor,
+  commandSystemOf,
   DeliveredHelperSchema,
   exploreSummary,
   CODEBASE_TAG_NAME,
@@ -4261,6 +4511,7 @@ export {
   WEB_CLOUD_BROWSER_NAME,
   webCloudOf,
   nameKey,
+  usageKindOf,
   proposeAssertions,
   hasObservableChange,
   normalizeStartUrl,
@@ -4307,6 +4558,8 @@ export {
   CheckError,
   textOf,
   checkMobileAssertion,
+  DeviceInUse,
+  lockDevice,
   openSessionOn,
   MobileSession,
   shrink,