@flowriki/agent 0.1.0-beta.45 → 0.1.0-beta.47

package/dist/cli.js

@@ -1,29 +1,50 @@
 #!/usr/bin/env node
 import {
+  AGENT_LATEST_URL,
   AGENT_VERSION,
+  CLOUD_PROVIDERS,
+  CLOUD_PROVIDER_NAME,
+  MobileLane,
   RecordedStepSchema,
+  agentUpdateFor,
   authenticationResolver,
   checkAssertion,
+  checkMobileAssertion,
   closeRunSession,
   connect,
   connectionFor,
+  dataDir,
   disconnect,
   doctor,
   executeStep,
   fieldNames,
   helperRunner,
+  isMobile,
+  listDevices,
+  locate,
   mirrorCheckTargets,
+  mobileDoctor,
+  mobileOf,
+  mobileSetup,
+  openMobileSession,
   openRunSession,
   parseGherkin,
+  performMobileStep,
+  platformsOf,
   prepareBrowsers,
   replayCase,
   replayFlow,
+  replayMobileCase,
   resolveCheckouts,
   resolveService,
+  runMobileSteps,
   runtimeValue,
+  screenLines,
   start,
-  status
-} from "./chunk-JJB45ZTL.js";
+  status,
+  stepRefusedOn,
+  targetFor
+} from "./chunk-AMXSHZYE.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -119,8 +140,8 @@ var ServiceClient = class {
   get origin() {
     return this.connection.service;
   }
-  async call(path, init = {}) {
-    const res = await this.fetcher(`${this.connection.service}${path}`, {
+  async call(path2, init = {}) {
+    const res = await this.fetcher(`${this.connection.service}${path2}`, {
       ...init,
       headers: {
         "x-flowriki-device": this.connection.deviceId,
@@ -154,10 +175,12 @@ var ServiceClient = class {
   catalog(projectId) {
     return this.call(`/api/agent/catalog?projectId=${encodeURIComponent(projectId)}`);
   }
-  prepare(projectId, steps, signIn) {
+  /** `cloud` asks for that device farm's access key too, for a flow written
+   *  on one of its phones. */
+  prepare(projectId, steps, signIn, extra = {}) {
     return this.call(`/api/agent/prepare?projectId=${encodeURIComponent(projectId)}`, {
       method: "POST",
-      body: JSON.stringify({ steps, ...signIn ? { signIn } : {} })
+      body: JSON.stringify({ steps, ...signIn ? { signIn } : {}, ...extra.cloud ? { cloud: extra.cloud } : {} })
     });
   }
   /** This person's open branches that Claude wrote on this project. */
@@ -260,9 +283,9 @@ var ServiceClient = class {
   }
   // ── Manual cycles and bugs: the dashboard's own routes, behind this
   // machine's credential, so the assistant can do what a person can. ──────
-  scoped(path, projectId, extra = {}) {
+  scoped(path2, projectId, extra = {}) {
     const query = new URLSearchParams({ projectId, ...extra });
-    return `/api/agent${path}?${query}`;
+    return `/api/agent${path2}?${query}`;
   }
   cycles(projectId) {
     return this.call(this.scoped("/cycles", projectId));
@@ -301,8 +324,8 @@ var ServiceClient = class {
   knowledgePages(projectId) {
     return this.call(this.scoped("/knowledge", projectId));
   }
-  knowledgePage(projectId, path) {
-    return this.call(this.scoped("/knowledge/page", projectId, { path }));
+  knowledgePage(projectId, path2) {
+    return this.call(this.scoped("/knowledge/page", projectId, { path: path2 }));
   }
   writeKnowledge(projectId, body) {
     return this.call(`/api/agent/knowledge?projectId=${encodeURIComponent(projectId)}`, { method: "POST", body: JSON.stringify(body) });
@@ -361,7 +384,31 @@ var STEP_TIMEOUT_MS = 1e4;
 var SECRET_WORDS = /password|passwd|pass[-_\s]?code|pwd|secret|otp|one[-_\s]?time[-_\s]?(code|pass)|security[-_\s]?(code|answer)|cvv|cvc|\bpin\b/i;
 var TYPED = "typed_";
 var withoutTyped = (steps) => steps.map((st) => st.secretRef?.startsWith(TYPED) ? (({ secretRef: _, ...rest }) => rest)(st) : st);
-var ACTIONS = ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward"];
+var ACTIONS = [
+  "click",
+  "dblclick",
+  "rightclick",
+  "hover",
+  "fill",
+  "select",
+  "check",
+  "press",
+  "navigate",
+  "back",
+  "forward",
+  // On a phone: a tap is a click, and these have no web equivalent.
+  "tap",
+  "longPress",
+  "swipe",
+  "scroll",
+  "hideKeyboard",
+  "launchApp",
+  "terminateApp",
+  "resetApp",
+  "background",
+  "rotate",
+  "permission"
+];
 var isAction = (value) => ACTIONS.includes(String(value));
 var LANDMARKS = /* @__PURE__ */ new Set(["main", "navigation", "banner", "contentinfo", "complementary", "search", "form", "dialog", "alertdialog", "region", "group", "list", "table", "menu", "toolbar", "tablist"]);
 function scopeOf(within) {
@@ -404,6 +451,24 @@ function numberDuplicates(tree) {
     return `${l}  [nth ${at} of ${total} with this name]`;
   }).join("\n");
 }
+function deviceFrom(said, platform, devices, mobile) {
+  const want = said?.trim();
+  if (!want) return mobile?.devices[platform];
+  const lower = want.toLowerCase();
+  const mine = devices.filter((d) => d.platform === platform);
+  const local = mine.find((d) => d.id.toLowerCase() === lower || d.name.toLowerCase() === lower) ?? mine.find((d) => d.name.toLowerCase().includes(lower));
+  if (local) return { kind: "local", id: local.id, name: local.name };
+  const farm = /^([^:]+):\s*(.+?)(?:\s+(\d+(?:\.\d+)*))?$/.exec(want);
+  const provider = farm && CLOUD_PROVIDERS.find((p) => p === farm[1].trim().toLowerCase().replace(/\s+/g, "") || CLOUD_PROVIDER_NAME[p].toLowerCase() === farm[1].trim().toLowerCase());
+  if (farm && provider) {
+    if (!mobile?.cloud.some((c) => c.provider === provider)) throw new Error(`${CLOUD_PROVIDER_NAME[provider]} is not connected to this project \u2014 add it in Settings \u2192 Mobile`);
+    return { kind: "cloud", provider, device: farm[2].trim(), ...farm[3] ? { osVersion: farm[3] } : {} };
+  }
+  throw new Error(`no ${platform === "ios" ? "iOS" : "Android"} device called "${want}" \u2014 connected: ${mine.map((d) => d.name).join(", ") || "none"}`);
+}
+async function devicesSummary() {
+  return listDevices().catch(() => []);
+}
 function describeRows(rows) {
   return rows.map((r) => [
     `Row ${r.row}: "${r.flow}" (${r.browser})`,
@@ -431,6 +496,26 @@ function describe(step) {
       return `check ${step.proposals.map((p) => `${p.kind}${p.op && p.op !== "equals" ? ` ${p.op}` : ""} "${String(p.value)}"${p.target?.name ? ` on ${p.target.role} "${p.target.name}"` : ""}`).join(", ")}`;
     case "useHelper":
       return `use helper ${step.name || step.helper?.helperId} \u2192 {{${step.helper?.saveAs}}}${step.helper?.then === "open" ? ", then open it" : ""}`;
+    case "swipe":
+      return `swipe ${step.value}${target ? ` on ${target}` : ""}`;
+    case "scroll":
+      return target ? `scroll to ${target}` : `scroll ${step.value}`;
+    case "longPress":
+      return `long-press ${target}${where}`;
+    case "hideKeyboard":
+      return "hide the keyboard";
+    case "launchApp":
+      return "open the app";
+    case "terminateApp":
+      return "close the app";
+    case "resetApp":
+      return "clear the app's data and open it";
+    case "background":
+      return `send the app to the background for ${step.value || 3}s`;
+    case "rotate":
+      return `rotate to ${step.value}`;
+    case "permission":
+      return `${step.value === "deny" ? "deny" : "allow"} the permission prompt`;
     default:
       return `${step.type} ${target}${where}`;
   }
@@ -444,6 +529,8 @@ var AuthoringSession = class {
   opts;
   run = null;
   page = null;
+  /** The phone, when the flow being written runs on one. */
+  mobile = null;
   values = /* @__PURE__ */ new Map();
   resolvers = null;
   lastTree = null;
@@ -465,7 +552,11 @@ var AuthoringSession = class {
     return out;
   }
   get open() {
-    return this.run !== null;
+    return this.run !== null || this.mobile !== null;
+  }
+  requireMobile() {
+    if (!this.mobile || !this.draft) throw new Error("no flow is being written \u2014 call start_flow first");
+    return { mobile: this.mobile, draft: this.draft };
   }
   requireOpen() {
     if (!this.run || !this.page || !this.draft) throw new Error("no flow is being written \u2014 call start_flow first");
@@ -476,7 +567,12 @@ var AuthoringSession = class {
    *  helper or sign-in appears, never kept beyond this process. */
   async prepare(extra = []) {
     const draft = this.draft;
-    const prepared = await this.service.prepare(draft.projectId, withoutTyped([...draft.preparation ?? [], ...draft.steps, ...extra]), draft.signIn ?? null);
+    const prepared = await this.service.prepare(
+      draft.projectId,
+      withoutTyped([...draft.preparation ?? [], ...draft.steps, ...extra]),
+      draft.signIn ?? null,
+      draft.device?.kind === "cloud" ? { cloud: draft.device.provider } : {}
+    );
     const runHelper = helperRunner(prepared.helpers, prepared.secrets);
     this.resolvers = {
       resolveAuth: authenticationResolver(prepared.authentications),
@@ -498,6 +594,7 @@ var AuthoringSession = class {
     this.values = /* @__PURE__ */ new Map();
     this.typed = /* @__PURE__ */ new Map();
     this.lastTree = null;
+    if (isMobile(input.platform)) return this.startMobile(input.platform, catalog);
     const base = this.baseUrl();
     this.run = await openRunSession({ steps: [], headless: this.opts.headless ?? false });
     this.page = this.run.page;
@@ -560,17 +657,7 @@ var AuthoringSession = class {
    * the page is new, the page itself, capped. read_page is always the whole
    * thing. */
   async view(full) {
-    const { page, draft } = this.requireOpen();
-    await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
-    const tree = numberDuplicates(labelTree(
-      await page.locator("body").ariaSnapshot({ timeout: 8e3 }).catch((e) => `(could not read the page: ${e.message})`),
-      await fieldNames(page)
-    ));
-    const title = await page.title().catch(() => "");
-    const head = `Page: ${page.url()}${title ? ` \u2014 "${title}"` : ""}
-Steps so far: ${draft.steps.length}
-
-`;
+    const { tree, head } = this.mobile ? await this.mobileTree() : await this.webTree();
     const before = this.lastTree;
     this.lastTree = tree;
     const cap = (t, max) => t.length > max ? `${t.slice(0, max)}
@@ -595,8 +682,24 @@ ${removed.join("\n")}` : "",
       "(changes since the last step \u2014 read_page shows the whole page)"
     ].filter(Boolean).join("\n");
   }
+  async webTree() {
+    const { page, draft } = this.requireOpen();
+    await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
+    const tree = numberDuplicates(labelTree(
+      await page.locator("body").ariaSnapshot({ timeout: 8e3 }).catch((e) => `(could not read the page: ${e.message})`),
+      await fieldNames(page)
+    ));
+    const title = await page.title().catch(() => "");
+    return { tree, head: `Page: ${page.url()}${title ? ` \u2014 "${title}"` : ""}
+Steps so far: ${draft.steps.length}
+
+` };
+  }
   /** Do one thing on the page, and keep it as a step if it worked. */
   async act(input) {
+    if (this.mobile) return this.mobileAct(input);
+    const refused = stepRefusedOn(input.action === "tap" ? "click" : input.action, "web");
+    if (refused) throw new Error(refused);
     const { page, draft, run } = this.requireOpen();
     const navigating = input.action === "navigate" || input.action === "back" || input.action === "forward";
     if (!navigating && input.action !== "press" && !(input.role && input.name)) {
@@ -650,6 +753,7 @@ ${await this.view(false)}`;
   }
   /** Check something about the page now, and keep the check if it holds. */
   async check(input) {
+    if (this.mobile) return this.mobileCheck(input);
     const { page, draft } = this.requireOpen();
     if ((input.kind === "heading" || input.kind === "message" || input.kind === "screen") && input.op && input.op !== "equals" && !input.role) {
       throw new Error(`a ${input.kind} check without role and name matches the whole ${input.kind} \u2014 give its full text with op equals, or name the element (role + name) and use kind "text" with op ${input.op}`);
@@ -685,6 +789,7 @@ ${await this.view(false)}`;
   /** Get a value from outside the page — an email code, a 2FA code, a text,
    *  an API reply — and keep the step that gets it. */
   async useHelper(input) {
+    if (this.mobile) return this.mobileHelper(input);
     const { page, draft, run } = this.requireOpen();
     const helper = this.catalog?.helpers.find((h) => h.id === input.helperId || h.name.toLowerCase() === input.helperId.toLowerCase());
     if (!helper) throw new Error(`no helper "${input.helperId}" \u2014 project_catalog lists them; one can be made on the Helpers screen`);
@@ -736,7 +841,8 @@ ${draft.steps.map((s, i) => `${i + 1}. ${describe(s)}`).join("\n")}`;
   /** Drop a step from the draft. The browser is not wound back — replay to
    *  see the flow as it now stands. */
   remove(number) {
-    const { draft } = this.requireOpen();
+    const draft = this.draft;
+    if (!draft || !this.open) throw new Error("no flow is being written \u2014 call start_flow first");
     if (!Number.isInteger(number) || number < 1 || number > draft.steps.length) throw new Error(`there is no step ${number}`);
     const [gone] = draft.steps.splice(number - 1, 1);
     return `Removed step ${number} (${describe(gone)}). The browser was not undone \u2014 replay_flow shows the flow as it now stands.
@@ -746,6 +852,7 @@ ${this.list()}`;
   /** Run the whole draft from the start, in a browser of its own, the way a
    *  run will — the proof the steps work together, not just one at a time. */
   async replay() {
+    if (this.mobile) return this.mobileReplay();
     const { draft } = this.requireOpen();
     if (draft.steps.length === 0) throw new Error("there are no steps to replay yet");
     const resolvers = await this.prepare();
@@ -761,7 +868,8 @@ ${lines.join("\n")}`;
   }
   /** Save the draft as a flow on a new branch, for a person to review. */
   async save(title, where = {}) {
-    const { draft } = this.requireOpen();
+    const draft = this.draft;
+    if (!draft || !this.open) throw new Error("no flow is being written \u2014 call start_flow first");
     if (draft.steps.length === 0) throw new Error("there are no steps to save yet");
     if (!draft.steps.some((s) => s.type === "assert" || s.proposals.length > 0)) {
       throw new Error("the flow checks nothing \u2014 add at least one check (add_check) that proves it worked, then save");
@@ -777,6 +885,7 @@ ${lines.join("\n")}`;
       name: draft.name,
       ...draft.featureId ? { featureId: draft.featureId } : { featureName: draft.featureName },
       startPath: draft.startPath,
+      ...isMobile(draft.platform) ? { platform: draft.platform } : {},
       steps: withoutTyped(checksOff),
       ...draft.signIn ? { signIn: draft.signIn } : {},
       ...draft.after?.length ? { prerequisites: draft.after.map((a) => ({ flowId: a.flowId })) } : {}
@@ -810,8 +919,26 @@ ${describeRows(built.rows)}`;
     const prepared = await this.service.prepare(projectId, steps, null);
     const runHelper = helperRunner(prepared.helpers, prepared.secrets);
     const base = catalog.baseUrl;
-    if (!base) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
-    const outcome = await replayCase({
+    const phoneRows = testCase.occurrences.filter((o) => isMobile(o.platform));
+    if (!base && phoneRows.length < testCase.occurrences.length) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
+    const laneOptions = {
+      mobile: catalog.mobile ?? mobileOf(null),
+      resolveSecret: (ref) => prepared.secrets[ref],
+      resolveAuth: authenticationResolver(prepared.authentications),
+      ...runHelper ? { runHelper } : {}
+    };
+    const lane = phoneRows.length ? new MobileLane(laneOptions) : null;
+    const opened = /* @__PURE__ */ new Set();
+    const outcome = phoneRows.length === testCase.occurrences.length ? await replayMobileCase({ ...laneOptions, occurrences: testCase.occurrences, ...testCase.defaultActorId ? { defaultActorId: testCase.defaultActorId } : {} }) : await replayCase({
+      ...lane ? {
+        runElsewhere: (occurrence, ctx) => {
+          if (!isMobile(occurrence.platform)) return null;
+          const key = occurrence.actorId ?? testCase.defaultActorId ?? "default";
+          const first = !opened.has(key);
+          opened.add(key);
+          return lane.run(occurrence, { deviceKey: key, first, ...ctx });
+        }
+      } : {},
       occurrences: testCase.occurrences,
       ...testCase.actors ? { actors: testCase.actors } : {},
       ...testCase.defaultActorId ? { defaultActorId: testCase.defaultActorId } : {},
@@ -820,7 +947,7 @@ ${describeRows(built.rows)}`;
       resolveAuth: authenticationResolver(prepared.authentications),
       resolveSecret: (ref) => prepared.secrets[ref],
       ...runHelper ? { runHelper } : {}
-    });
+    }).finally(() => lane?.close());
     const lines = outcome.occurrences.map((o, i) => {
       const failed = o.steps.find((st) => st.status === "failed");
       const why = o.status === "failed" ? `: ${failed ? `step "${failed.name || failed.type}" \u2014 ${(failed.detail ?? "").split("\n")[0]}` : (o.error ?? "").split("\n")[0]}` : "";
@@ -840,11 +967,196 @@ Review and publish it here: ${review}`;
   }
   async close() {
     const run = this.run;
+    const mobile = this.mobile;
     this.run = null;
     this.page = null;
+    this.mobile = null;
     this.resolvers = null;
+    if (mobile) await mobile.close().catch(() => void 0);
     if (run) await closeRunSession(run, { passed: true }).catch(() => void 0);
   }
+  // ── On a phone ────────────────────────────────────────────────────────
+  /** Open the project's app on the chosen phone, signed in and brought to
+   *  where the flow starts, as on the web. */
+  async startMobile(platform, catalog) {
+    const draft = this.draft;
+    const mobile = catalog.mobile;
+    if (!mobile) throw new Error("this project has no phone apps set up \u2014 turn on Android or iOS in Settings \u2192 Mobile");
+    const resolvers = draft.signIn || draft.device?.kind === "cloud" ? await this.prepare() : null;
+    this.mobile = await openMobileSession({
+      platform,
+      mobile,
+      ...draft.device ? { device: draft.device } : {},
+      ...resolvers ? { resolveSecret: resolvers.resolveSecret } : {}
+    });
+    const opening = [
+      ...draft.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: draft.signIn, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
+      ...draft.preparation ?? []
+    ];
+    if (/^[a-z][\w+.-]*:\/\//i.test(draft.startPath)) await this.mobile.openLink(draft.startPath);
+    if (opening.length) {
+      const ready = await this.prepare(draft.preparation ?? []);
+      const done = await runMobileSteps(this.mobile, opening, { values: this.values, ...ready });
+      if (done.status !== "passed") throw new Error(`The app could not be brought to where this flow starts: ${done.error}`);
+    }
+    return this.snapshot();
+  }
+  async mobileTree() {
+    const { mobile, draft } = this.requireMobile();
+    mobile.changed();
+    let screen = await mobile.screen();
+    if (screen.nodes.length === 0) screen = await mobile.settle(8e3);
+    const where = await mobile.currentScreenName();
+    const tree = numberDuplicates(screenLines(screen)) || "(nothing on the screen can be read \u2014 the app may still be loading, or draws without accessibility labels)";
+    return { tree, head: `Screen: ${screen.app || mobile.appId} on ${mobile.deviceName}${where ? ` \u2014 ${where}` : ""}
+Steps so far: ${draft.steps.length}
+
+` };
+  }
+  mobileResolvers() {
+    return {
+      values: this.values,
+      ...this.resolvers ?? {},
+      resolveSecret: (ref) => this.typed.get(ref) ?? this.resolvers?.resolveSecret(ref)
+    };
+  }
+  async mobileAct(input) {
+    const { mobile, draft } = this.requireMobile();
+    const type = input.action === "tap" ? "click" : input.action;
+    const refused = stepRefusedOn(type, mobile.platform);
+    if (refused) throw new Error(refused);
+    const needsElement = ["click", "longPress", "fill", "select", "check"].includes(type);
+    if (needsElement && !(input.role && (input.name || input.nth !== void 0))) {
+      throw new Error(`${input.action} needs the element's role and name, exactly as read_page shows them`);
+    }
+    if ((type === "fill" || type === "select" || type === "navigate") && input.value === void 0) throw new Error(`${input.action} needs a value`);
+    let target = { role: "", name: "" };
+    let password = false;
+    if (input.role) {
+      const asked = { role: input.role, name: input.name ?? "", ...scopeOf(input.within), ...input.nth !== void 0 ? { nth: input.nth } : {} };
+      try {
+        const found = await locate(mobile, asked, STEP_TIMEOUT_MS, { scroll: type !== "swipe" });
+        target = { ...targetFor(found.screen, found.node), ...asked };
+        password = found.node.password;
+      } catch (error) {
+        const said = error.message.split("\n")[0] ?? "";
+        const several = /elements match/.test(said) ? "\nSeveral elements share this role and name. Pass nth (0 = the first, in the order read_page lists them) to say which one." : "";
+        throw new Error(`That did not work, and was not kept: ${said}${several}
+
+${await this.view(false)}`);
+      }
+    }
+    const secret = type === "fill" && (input.secret ?? (password || SECRET_WORDS.test(input.name ?? "")));
+    const id = `s${draft.steps.length + 1}_${Date.now().toString(36)}`;
+    if (secret) this.typed.set(`${TYPED}${id}`, input.value ?? "");
+    const value = secret ? "" : type === "check" ? input.value === "false" ? "false" : "true" : type === "swipe" || type === "scroll" && !input.role ? (input.value || "up").toLowerCase() : input.value ?? "";
+    const step = RecordedStepSchema.parse({
+      id,
+      type,
+      ...target,
+      value,
+      secret,
+      ...secret ? { secretRef: `${TYPED}${id}` } : {},
+      legacySelector: "",
+      proposals: []
+    });
+    try {
+      await performMobileStep(mobile, step, this.mobileResolvers());
+    } catch (error) {
+      if (secret) this.typed.delete(`${TYPED}${id}`);
+      throw new Error(`That did not work, and was not kept: ${error.message.split("\n")[0]}
+
+${await this.view(false)}`);
+    }
+    await new Promise((r) => setTimeout(r, 600));
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}.
+
+${await this.view(false)}`;
+  }
+  async mobileCheck(input) {
+    const { mobile, draft } = this.requireMobile();
+    if (input.kind === "url" || input.kind === "title") throw new Error(`a phone app has no ${input.kind === "url" ? "address" : "page title"} \u2014 check text on the screen (message), a heading's text, or an element`);
+    const assertion = RecordedStepSchema.shape.proposals.element.parse({
+      kind: input.kind,
+      value: input.value,
+      enabled: true,
+      ...input.op && input.op !== "equals" ? { op: input.op } : {},
+      ...input.role ? { target: { role: input.role, name: input.name ?? "", ...scopeOf(input.within), ...input.nth !== void 0 ? { nth: input.nth } : {} } } : {}
+    });
+    const filled = (text2) => text2.replace(/\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g, (_, name) => runtimeValue(this.values, name));
+    const expected = Array.isArray(assertion.value) ? assertion.value.map(filled) : filled(assertion.value);
+    try {
+      await checkMobileAssertion(mobile, { ...assertion, value: expected }, 5e3);
+    } catch (error) {
+      throw new Error(`That is not true of the screen right now, so it was not kept: ${error.message.split("\n")[0]}`);
+    }
+    const step = RecordedStepSchema.parse(mirrorCheckTargets([{
+      id: `c${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "assert",
+      role: "",
+      name: "",
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [assertion]
+    }])[0]);
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}.`;
+  }
+  async mobileHelper(input) {
+    const { mobile, draft } = this.requireMobile();
+    const helper = this.catalog?.helpers.find((h) => h.id === input.helperId || h.name.toLowerCase() === input.helperId.toLowerCase());
+    if (!helper) throw new Error(`no helper "${input.helperId}" \u2014 project_catalog lists them; one can be made on the Helpers screen`);
+    const missing = helper.inputs.filter((name) => !(input.inputs ?? {})[name]);
+    if (missing.length) throw new Error(`${helper.name} needs ${missing.map((n) => `{{${n}}}`).join(", ")} in inputs`);
+    const step = RecordedStepSchema.parse({
+      id: `h${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "useHelper",
+      role: "",
+      name: helper.name,
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [],
+      helper: { helperId: helper.id, inputs: input.inputs ?? {}, saveAs: input.saveAs || (helper.kind === "mailbox" ? "code" : "value"), then: input.then ?? "remember" }
+    });
+    await this.prepare([step]);
+    let got;
+    try {
+      got = await performMobileStep(mobile, step, this.mobileResolvers());
+    } catch (error) {
+      throw new Error(`The helper did not get a value, and the step was not kept: ${error.message}`);
+    }
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}. It got "${got?.value ?? ""}" (${got?.detail ?? ""}). Use {{${step.helper.saveAs}}} as the value of a later step.` + (step.helper.then === "open" ? `
+
+${await this.view(false)}` : "");
+  }
+  /** The whole flow again from the app's start, on the same phone — a phone
+   *  holds one session at a time, so the app is closed and opened rather than
+   *  a second device started. */
+  async mobileReplay() {
+    const { mobile, draft } = this.requireMobile();
+    if (draft.steps.length === 0) throw new Error("there are no steps to replay yet");
+    const resolvers = await this.prepare();
+    const steps = [
+      ...draft.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: draft.signIn, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
+      ...draft.preparation ?? [],
+      ...draft.steps
+    ];
+    await mobile.terminateApp().catch(() => void 0);
+    await mobile.launchApp();
+    await mobile.settle();
+    if (/^[a-z][\w+.-]*:\/\//i.test(draft.startPath)) await mobile.openLink(draft.startPath);
+    const outcome = await runMobileSteps(mobile, steps, { values: /* @__PURE__ */ new Map(), ...resolvers, resolveSecret: (ref) => this.typed.get(ref) ?? resolvers.resolveSecret(ref) });
+    this.lastTree = null;
+    const lines = outcome.results.map((s) => `${s.status === "passed" ? "\u2713" : s.status === "failed" ? "\u2717" : "\xB7"} ${s.name || s.type}${s.status === "failed" && s.detail ? ` \u2014 ${s.detail}` : ""}`);
+    return `${outcome.status === "passed" ? "The whole flow passed from the app's start." : `The flow ${outcome.status}${outcome.error ? `: ${outcome.error}` : ""}.`}
+${lines.join("\n")}`;
+  }
   /** Let a click's consequences land before the page is read again. */
   async settle() {
     const page = this.page;
@@ -935,6 +1247,26 @@ converted once. Use the project's existing feature names (project_catalog)
 when a case belongs in one, rather than a new look-alike. Rows that are not test cases (titles,
 notes, empty) are left out. Say in note what you could not convert.
 
+PHONE APPS (Android, iOS): a project can test its Android and iOS apps as well
+as, or instead of, a website \u2014 project_catalog says which, names the app, and
+lists the phones connected to this computer. start_flow with platform
+"android" or "ios" opens the app on a phone (device: a name from the catalog,
+"BrowserStack: Samsung Galaxy S23", or nothing for whatever is connected).
+read_page then reads the SCREEN as roles and names, just like a page, and act
+and add_check work the same way. On a phone: tap (= click) a button, fill a
+textbox, swipe up/down/left/right (value; on an element, or the screen), scroll
+to an element (role + name) or by direction, longPress, back (Android only),
+hideKeyboard, permission (value "allow" or "deny") for a system prompt, and
+launchApp / terminateApp / resetApp / background (value: seconds) / rotate
+(value: portrait or landscape). navigate opens a deep link. Never tap by
+position \u2014 use the role and name; [id=\u2026] on a line is the app's own id for it,
+and is used automatically. A phone app has no URL or page title: check a
+message (text on the screen), an element's text, or that something is visible.
+The app keeps its data between runs unless the project says otherwise, so a
+sign-in step is skipped when the app is already signed in. A test case can
+mix rows on a phone with rows in a browser (a customer orders in the app, an
+admin approves on the website).
+
 HOW TO WORK:
 1. Call project_catalog. Reuse what exists \u2014 published, and on Claude's working
    branch \u2014 rather than writing it again.
@@ -1063,9 +1395,23 @@ It is now the project these tools work on. Open it: ${service.origin}/projects/$
       run: async (args) => {
         const projectId = await projectFor(args["projectId"]);
         const c = await catalogOf(projectId, true);
-        const flowsBy = (featureId) => c.flows.filter((f) => f.featureId === featureId).map((f) => `    - ${f.name} (${f.steps} steps)`).join("\n");
+        const flowsBy = (featureId) => c.flows.filter((f) => f.featureId === featureId).map((f) => `    - ${f.name} (${f.steps} steps${isMobile(f.platform) ? `, ${f.platform}` : ""})`).join("\n");
+        const platforms = platformsOf(c);
+        const phones = platforms.android || platforms.ios ? await devicesSummary() : [];
+        const phoneLines = ["android", "ios"].filter((p) => platforms[p]).map((p) => {
+          const app = p === "android" ? c.mobile?.android?.appPackage : c.mobile?.ios?.bundleId;
+          const here = phones.filter((d) => d.platform === p);
+          const farms = (c.mobile?.cloud ?? []).map((f) => CLOUD_PROVIDER_NAME[f.provider]);
+          const chosen = c.mobile?.devices[p];
+          return `${p === "android" ? "Android" : "iOS"} app: ${app ?? "(not set up \u2014 Settings \u2192 Mobile)"}
+  Phones on this computer: ${here.length ? here.map((d) => `${d.name}${d.state === "ready" ? "" : ` (${d.state})`}`).join(", ") : "none"}` + (farms.length ? `
+  Cloud device farms: ${farms.join(", ")}` : "") + (chosen ? `
+  Runs go to: ${chosen.kind === "local" ? chosen.name || chosen.id : `${CLOUD_PROVIDER_NAME[chosen.provider]}: ${chosen.device}`}` : "");
+        });
         return text([
-          `Project ${projectId}. Base URL: ${c.baseUrl || "(not set)"}`,
+          `Project ${projectId}. Tests: ${[platforms.web && "web", platforms.android && "Android app", platforms.ios && "iOS app"].filter(Boolean).join(", ")}.`,
+          platforms.web ? `Base URL: ${c.baseUrl || "(not set)"}` : "",
+          ...phoneLines,
           c.environments.length ? `Environments: ${c.environments.map((e) => `${e.name} ${e.baseUrl}`).join(", ")}` : "",
           `
 Features:${c.features.length ? "" : " none yet"}`,
@@ -1095,13 +1441,15 @@ Helpers:${c.helpers.length ? "" : " none \u2014 create_helper makes one"}`,
     {
       name: "start_flow",
       title: "Start writing a flow",
-      description: "Open a browser on this computer at the project's app and start a new flow. Returns the page. Closes any flow that was being written.",
+      description: "Open a browser on this computer at the project's app \u2014 or, with platform android or ios, the project's phone app on a phone \u2014 and start a new flow. Returns the page or screen. Closes any flow that was being written.",
       inputSchema: {
         type: "object",
         properties: {
           name: { type: "string", description: `The flow's name: the user journey, e.g. "Sign up and verify email".` },
           feature: { type: "string", description: "The feature it belongs to: an existing feature's id or name, or a new name." },
-          startPath: { type: "string", description: 'Where it starts, relative to the base URL. Default "/".' },
+          startPath: { type: "string", description: `Where it starts, relative to the base URL. Default "/". On a phone: a deep link to open, or leave out for the app's first screen.` },
+          platform: { type: "string", enum: ["web", "android", "ios"], description: "Where the flow runs. Default: web, or the project's only platform." },
+          device: { type: "string", description: `Phones only: a phone from project_catalog by name, or a cloud farm's as "BrowserStack: Samsung Galaxy S23". Default: the project's choice, then whatever is connected.` },
           after: {
             type: "array",
             items: { type: "string" },
@@ -1131,16 +1479,23 @@ Helpers:${c.helpers.length ? "" : " none \u2014 create_helper makes one"}`,
         }
         const asked = Array.isArray(args["after"]) ? args["after"].map(String).filter(Boolean) : [];
         const plan = asked.length ? await service.flowsAfter(projectId, asked) : null;
+        const platforms = platformsOf(catalog);
+        const enabled = ["web", "android", "ios"].filter((p) => platforms[p]);
+        const platform = str(args["platform"]) ?? (enabled.length === 1 ? enabled[0] : enabled.includes("web") ? "web" : void 0);
+        if (!platform) throw new Error(`this project tests ${enabled.join(" and ")} \u2014 say which with platform`);
+        if (!platforms[platform]) throw new Error(`this project does not test ${platform === "web" ? "a website" : `an ${platform === "ios" ? "iOS" : "Android"} app`} \u2014 turn it on in Settings first`);
+        const device = isMobile(platform) ? deviceFrom(str(args["device"]), platform, await devicesSummary(), catalog.mobile) : void 0;
         const page = await session.start({
           projectId,
+          ...isMobile(platform) ? { platform, ...device ? { device } : {} } : {},
           ...plan ? { after: plan.prerequisites, preparation: plan.steps } : {},
           name: str(args["name"]) ?? "Untitled flow",
           ...feature ? { featureId: feature.id } : { featureName: featureAsked },
-          startPath: str(args["startPath"]) || "/",
+          startPath: str(args["startPath"]) || (isMobile(platform) ? "" : "/"),
           ...signIn?.profileId ? { signIn: { profileId: signIn.profileId, ...signIn.accountId ? { accountId: signIn.accountId } : {} } } : {}
         }, catalog);
         const after = plan?.prerequisites.length ? ` It starts after ${plan.prerequisites.map((p) => `"${p.name}"`).join(" \u2192 ")}, which ran first.` : "";
-        return text(`Started "${str(args["name"])}"${feature ? ` in ${feature.name}` : ` in a new feature, ${featureAsked}`}.${after} The browser is open.
+        return text(`Started "${str(args["name"])}"${feature ? ` in ${feature.name}` : ` in a new feature, ${featureAsked}`}.${after} ${isMobile(platform) ? "The app is open on the phone." : "The browser is open."}
 
 ${page}`);
       }
@@ -1148,7 +1503,7 @@ ${page}`);
     {
       name: "read_page",
       title: "Read the page",
-      description: "The current page as its accessibility tree: each element's role and name, which is exactly what act and add_check refer to.",
+      description: "The current page \u2014 or phone screen \u2014 as its accessibility tree: each element's role and name, which is exactly what act and add_check refer to.",
       inputSchema: { type: "object", properties: {}, additionalProperties: false },
       annotations: { readOnlyHint: true },
       run: async () => text(await session.snapshot())
@@ -1156,11 +1511,11 @@ ${page}`);
     {
       name: "act",
       title: "Do one thing on the page",
-      description: `Perform one step and keep it in the flow if it worked. Returns the page afterwards. click/dblclick/rightclick/hover: role + name. fill: role + name + value (may use {{values}} from helpers). select: role + name + the option's label as value. check: role + name, value "true" or "false". press: a key such as "Enter" as value, optionally role + name of where. navigate: a path such as "/settings" or a full URL as value. back/forward: nothing.`,
+      description: `Perform one step and keep it in the flow if it worked. Returns the page afterwards. click/dblclick/rightclick/hover: role + name. fill: role + name + value (may use {{values}} from helpers). select: role + name + the option's label as value. check: role + name, value "true" or "false". press: a key such as "Enter" as value, optionally role + name of where. navigate: a path such as "/settings" or a full URL as value (on a phone, a deep link). back/forward: nothing. PHONE ONLY: tap (role + name), longPress (role + name), swipe (value up/down/left/right, optionally on role + name), scroll (to role + name, or value up/down), hideKeyboard, permission (value allow/deny), launchApp, terminateApp, resetApp, background (value: seconds), rotate (value portrait/landscape).`,
       inputSchema: {
         type: "object",
         properties: {
-          action: { type: "string", enum: ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward"] },
+          action: { type: "string", enum: ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward", "tap", "longPress", "swipe", "scroll", "hideKeyboard", "permission", "launchApp", "terminateApp", "resetApp", "background", "rotate"] },
           role: { type: "string", description: "The element's role as read_page shows it, e.g. button, link, textbox, checkbox, combobox." },
           name: { type: "string", description: "The element's accessible name, exactly as read_page shows it." },
           within: { type: "string", description: "When the name is not unique: the name of the region, dialog, form or navigation that holds it." },
@@ -1172,7 +1527,7 @@ ${page}`);
         additionalProperties: false
       },
       run: async (args) => {
-        if (!isAction(args["action"])) throw new Error("action must be one of click, dblclick, rightclick, hover, fill, select, check, press, navigate, back, forward");
+        if (!isAction(args["action"])) throw new Error("action must be one of click, dblclick, rightclick, hover, fill, select, check, press, navigate, back, forward \u2014 or on a phone tap, longPress, swipe, scroll, hideKeyboard, permission, launchApp, terminateApp, resetApp, background, rotate");
         return text(await session.act({
           action: args["action"],
           ...str(args["role"]) ? { role: str(args["role"]) } : {},
@@ -1187,7 +1542,7 @@ ${page}`);
     {
       name: "add_check",
       title: "Add a check",
-      description: "Assert something about the page as it is now, and keep it in the flow if it holds. Page checks need only kind + value: heading, url (a path), title, message. Element checks also need role + name: text, value, visible, hidden, checked, count. op: equals (default), contains or matches.",
+      description: "Assert something about the page (or phone screen) as it is now, and keep it in the flow if it holds. Page checks need only kind + value: heading, url (a path), title, message (text shown anywhere \u2014 on a phone, the way to check a screen). Element checks also need role + name: text, value, visible, hidden, checked, count. op: equals (default), contains or matches.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1651,7 +2006,7 @@ Use it with start_flow signIn {"profileId": "\u2026", "accountId": "${made.accou
       run: async (args) => {
         const projectId = await projectFor(args["projectId"]);
         const { pages } = await service.knowledgePages(projectId);
-        const read = async (path) => pages.some((p) => p.path === path) ? (await service.knowledgePage(projectId, path)).content : null;
+        const read = async (path2) => pages.some((p) => p.path === path2) ? (await service.knowledgePage(projectId, path2)).content : null;
         const [product, glossary, decisions] = await Promise.all(["product.md", "glossary.md", "memory/decisions.md"].map(read));
         const codebases = pages.filter((p) => p.path.startsWith("codebase/"));
         const headers = await Promise.all(codebases.map(async (p) => `- ${p.path}: ${(await read(p.path))?.split("\n").filter((l) => l.trim()).slice(0, 3).join(" \xB7 ") ?? ""}`));
@@ -1721,7 +2076,7 @@ ${pages.filter((p) => !shown.has(p.path)).map((p) => `- ${p.path}`).join("\n") |
     {
       name: "close_browser",
       title: "Close the browser",
-      description: "Close the browser and drop the flow being written, unsaved.",
+      description: "Close the browser \u2014 or the app on the phone \u2014 and drop the flow being written, unsaved.",
       inputSchema: { type: "object", properties: {}, additionalProperties: false },
       annotations: { destructiveHint: true },
       run: async () => {
@@ -1745,6 +2100,212 @@ ${pages.filter((p) => !shown.has(p.path)).map((p) => `- ${p.path}`).join("\n") |
   }));
 }
 
+// src/mcp/upgrade.ts
+import { spawn } from "child_process";
+import readline2 from "readline";
+var PRIVATE = "flowriki-upgrade";
+var startWithNpx = (version) => spawn(process.platform === "win32" ? "npx.cmd" : "npx", ["-y", `@flowriki/agent@${version}`, "mcp"], {
+  env: { ...process.env, FLOWRIKI_MCP_CHILD: "1" },
+  stdio: ["pipe", "pipe", "inherit"]
+});
+var toolShape = (tools) => JSON.stringify(tools.map((t) => [t.name, t.description ?? "", t.inputSchema ?? null]).sort());
+function serveWithUpgrades(tools, info, opts) {
+  const input = opts.input ?? process.stdin;
+  const output = opts.output ?? process.stdout;
+  const log = opts.log ?? ((line) => process.stderr.write(`flowriki: ${line}
+`));
+  const send = (m) => output.write(`${JSON.stringify(m)}
+`);
+  if (!opts.output) {
+    console.log = console.info = console.warn = console.debug = (...args) => {
+      process.stderr.write(`${args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")}
+`);
+    };
+  }
+  let initialize = null;
+  let localCalls = 0;
+  let ready = null;
+  let active = null;
+  let preparing = false;
+  let notice = null;
+  const forwarded = /* @__PURE__ */ new Set();
+  let timer = null;
+  const withNotice = (answer) => {
+    if (!notice || !answer.result || typeof answer.result !== "object") return answer;
+    const result = answer.result;
+    if (!Array.isArray(result.content)) return answer;
+    const text2 = notice;
+    notice = null;
+    return { ...answer, result: { ...result, content: [{ type: "text", text: text2 }, ...result.content] } };
+  };
+  const prepare = async (version) => {
+    if (preparing || ready || active || !initialize) return;
+    preparing = true;
+    let child = null;
+    try {
+      child = (opts.start ?? startWithNpx)(version);
+      const c = child;
+      const lines2 = readline2.createInterface({ input: c.stdout, crlfDelay: Infinity });
+      const waiting = /* @__PURE__ */ new Map();
+      const exited = new Promise((_, reject) => c.once("exit", (code) => reject(new Error(`it stopped while starting (exit ${code})`))));
+      exited.catch(() => void 0);
+      c.once("error", (e) => waiting.forEach((resolve) => resolve({ jsonrpc: "2.0", error: { message: e.message } })));
+      lines2.on("line", (line) => {
+        let m;
+        try {
+          m = JSON.parse(line);
+        } catch {
+          return;
+        }
+        if (typeof m.id === "string" && m.id.startsWith(PRIVATE)) {
+          waiting.get(m.id)?.(m);
+          waiting.delete(m.id);
+          return;
+        }
+        if (active?.child !== c) return;
+        if (m.id !== void 0 && m.id !== null) forwarded.delete(m.id);
+        send(m.id !== void 0 && m.id !== null && "result" in m ? withNotice(m) : m);
+      });
+      const ask = (method, params, id) => new Promise((resolve, reject) => {
+        waiting.set(id, resolve);
+        c.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, ...params ? { params } : {} })}
+`);
+        setTimeout(() => reject(new Error("it did not answer in time")), opts.readyWithinMs ?? 18e4).unref();
+      });
+      const hello = await Promise.race([ask("initialize", initialize.params, `${PRIVATE}-init`), exited]);
+      if (hello.error) throw new Error(JSON.stringify(hello.error));
+      c.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}
+`);
+      const listed = await Promise.race([ask("tools/list", void 0, `${PRIVATE}-tools`), exited]);
+      const theirs = listed.result?.tools ?? [];
+      ready = { child: c, version, lines: lines2, toolsChanged: toolShape(theirs) !== toolShape(tools) };
+      c.once("exit", () => {
+        if (ready?.child === c) ready = null;
+        if (active?.child === c) {
+          active = null;
+          for (const id of forwarded) send({ jsonrpc: "2.0", id, error: { code: -32603, message: "the updated Flowriki stopped \u2014 ask again" } });
+          forwarded.clear();
+          notice = `The updated Flowriki (${version}) stopped, so this connection carries on with ${opts.current}.`;
+          log(`updated server ${version} exited; back on ${opts.current}`);
+        }
+      });
+      log(`${version} is ready to take over from ${opts.current}`);
+    } catch (error) {
+      child?.kill();
+      log(`could not start ${version}: ${error.message}`);
+      notice ??= `Flowriki ${version} is out (this connection runs ${opts.current}) and could not switch over by itself: ${error.message}. Reconnect Flowriki in Claude to start the new version.`;
+    } finally {
+      preparing = false;
+    }
+  };
+  const maybeSwitch = async (incomingTool) => {
+    if (!ready || active || localCalls > 0) return false;
+    if (!opts.idle() && incomingTool !== "start_flow") return false;
+    const next = ready;
+    ready = null;
+    await opts.handOff().catch(() => void 0);
+    active = next;
+    if (timer) clearInterval(timer);
+    notice = `Flowriki updated itself from ${opts.current} to ${next.version} \u2014 the new version is answering now.` + (next.toolsChanged ? " It brings new or changed tools; if Claude does not offer them yet, reconnect Flowriki in Claude (in Claude Code: /mcp, then Reconnect)." : "");
+    send({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+    log(`switched to ${next.version}`);
+    return true;
+  };
+  const look = async () => {
+    if (active || ready || preparing) return;
+    const version = await opts.check().catch(() => null);
+    if (version) {
+      await prepare(version);
+      await maybeSwitch();
+    }
+  };
+  setTimeout(() => void look(), opts.firstCheckMs ?? 15e3).unref();
+  timer = setInterval(() => void look(), opts.everyMs ?? 30 * 6e4);
+  timer.unref();
+  const lines = readline2.createInterface({ input, crlfDelay: Infinity });
+  const pending = /* @__PURE__ */ new Set();
+  lines.on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+      return;
+    }
+    if (message.method === "initialize") initialize = message;
+    const task = (async () => {
+      const tool = message.method === "tools/call" ? String(message.params?.["name"] ?? "") : void 0;
+      if (!active && tool) await maybeSwitch(tool);
+      if (active) {
+        if (message.id !== void 0 && message.id !== null) forwarded.add(message.id);
+        active.child.stdin.write(`${line}
+`);
+        return;
+      }
+      if (tool) localCalls++;
+      try {
+        const answer = await handle(message, tools, info);
+        if (answer) send(tool ? withNotice(answer) : answer);
+        if (message.method === "notifications/initialized") send({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+      } finally {
+        if (tool) localCalls--;
+      }
+      if (tool && ready) await maybeSwitch();
+    })();
+    pending.add(task);
+    void task.finally(() => pending.delete(task));
+  });
+  return new Promise((resolve) => lines.on("close", () => {
+    void Promise.allSettled([...pending]).then(() => {
+      if (timer) clearInterval(timer);
+      const child = active?.child ?? ready?.child;
+      if (!child) return resolve();
+      child.stdin?.end();
+      const done = () => resolve();
+      child.once("exit", done);
+      setTimeout(() => {
+        child.kill();
+        done();
+      }, 5e3).unref();
+    });
+  }));
+}
+
+// src/updates.ts
+import fs from "fs";
+import path from "path";
+var CACHE_MS = 30 * 60 * 1e3;
+async function latestPublished(opts = {}) {
+  const file = path.join(dataDir(), "latest-agent.json");
+  if (!opts.fresh) {
+    try {
+      const kept = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (kept.version && kept.at && Date.now() - kept.at < CACHE_MS) return kept.version;
+    } catch {
+    }
+  }
+  try {
+    const res = await fetch(AGENT_LATEST_URL, { signal: AbortSignal.timeout(5e3), headers: { accept: "application/json" } });
+    if (!res.ok) return null;
+    const version = (await res.json()).version ?? null;
+    if (version) {
+      try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ version, at: Date.now() }));
+      } catch {
+      }
+    }
+    return version;
+  } catch {
+    return null;
+  }
+}
+async function updateFor(running) {
+  const latest = await latestPublished();
+  return agentUpdateFor(running, latest) ? latest : null;
+}
+
 // src/mcp/index.ts
 async function runMcp(opts) {
   let service;
@@ -1768,7 +2329,20 @@ async function runMcp(opts) {
   };
   process.on("SIGINT", () => void closing());
   process.on("SIGTERM", () => void closing());
-  await serve(tools, { name: "flowriki", version: opts.version, instructions: INSTRUCTIONS });
+  const info = { name: "flowriki", version: opts.version, instructions: INSTRUCTIONS };
+  if (process.env["FLOWRIKI_MCP_CHILD"] === "1" || process.env["FLOWRIKI_NO_UPDATE"] === "1" || !/^\d+\.\d+\.\d+/.test(opts.version)) {
+    await serve(tools, info);
+  } else {
+    await serveWithUpgrades(tools, info, {
+      current: opts.version,
+      check: () => updateFor(opts.version),
+      idle: () => !session?.open,
+      handOff: async () => {
+        await session?.close();
+        if (session) session.draft = null;
+      }
+    });
+  }
   await session?.close();
   return 0;
 }
@@ -1792,6 +2366,10 @@ ${bold("USAGE")}
   flowriki-agent doctor             diagnose setup problems
   flowriki-agent prepare            download the browser recording needs
   flowriki-agent disconnect         forget this computer's credential
+  flowriki-agent mobile setup       install what testing Android and iOS apps
+                                    needs (Appium and its drivers)
+  flowriki-agent mobile doctor      is this computer ready to test phones
+  flowriki-agent mobile devices     the phones, emulators and simulators here
   flowriki-agent mcp                Flowriki as tools for Claude \u2014 started by
                                     Claude Code or Claude Desktop, not by you:
                                     claude mcp add flowriki -- flowriki-agent mcp
@@ -1914,6 +2492,17 @@ Run \`flowriki-agent --help\`.`);
         console.log(dim(`  project  ${project.name}  (${project.root})`));
       }
       console.log(dim("\n  Running in the foreground. Ctrl-C to stop.\n"));
+      let told = null;
+      const tellIfBehind = async () => {
+        const newer = await updateFor(AGENT_VERSION).catch(() => null);
+        if (!newer || newer === told) return;
+        told = newer;
+        console.log(yellow(`  ! Flowriki agent ${newer} is out \u2014 this is ${AGENT_VERSION}.`));
+        console.log(dim(`    Update: npm install -g @flowriki/agent@latest   then stop (Ctrl-C) and start again
+`));
+      };
+      void tellIfBehind();
+      setInterval(() => void tellIfBehind(), 6 * 60 * 6e4).unref();
       let stopping = false;
       const shutdown = async (signal) => {
         if (stopping) return;
@@ -1987,6 +2576,42 @@ Run \`flowriki-agent --help\`.`);
       }
       return 0;
     }
+    case "mobile": {
+      const sub = positionals[1] ?? "doctor";
+      const report = (found) => {
+        for (const [title, lines] of [["Appium", found.appium], ["Android", found.android], ["iOS", found.ios]]) {
+          console.log(bold(title));
+          for (const line of lines) {
+            console.log(`  ${line.ok ? green("\u2713") : line.optional ? yellow("\u2013") : red("\u2717")} ${line.item.padEnd(15)} ${line.ok ? dim(line.detail) : line.detail}`);
+            if (!line.ok && line.fix) console.log(`    ${yellow("\u2192")} ${line.fix}`);
+          }
+        }
+        console.log(`
+  Android ${found.androidReady ? green("ready") : yellow("not ready")}   iOS ${found.iosReady ? green("ready") : yellow("not ready")}`);
+        return found.androidReady || found.iosReady ? 0 : 1;
+      };
+      if (sub === "setup") return report(await mobileSetup((line) => console.log(dim(`  ${line}`))));
+      if (sub === "doctor") {
+        const found = await mobileDoctor();
+        if (values.json) {
+          console.log(JSON.stringify(found, null, 2));
+          return found.androidReady || found.iosReady ? 0 : 1;
+        }
+        return report(found);
+      }
+      if (sub === "devices") {
+        const found = await listDevices();
+        if (values.json) {
+          console.log(JSON.stringify(found, null, 2));
+          return 0;
+        }
+        if (!found.length) console.log(yellow("  No phones, emulators or simulators found."));
+        for (const d of found) console.log(`  ${d.state === "ready" ? green("\u25CF") : dim("\u25CB")} ${d.name.padEnd(28)} ${dim(`${d.platform === "ios" ? "iOS" : "Android"} ${d.osVersion} \xB7 ${d.kind}${d.state === "ready" ? "" : ` \xB7 ${d.state}`}`)}`);
+        return 0;
+      }
+      console.error(`unknown: mobile ${sub} \u2014 use setup, doctor or devices`);
+      return 2;
+    }
     case "projects": {
       const { projects: found, skipped } = resolveCheckouts(projects.length ? projects : [process.cwd()]);
       for (const p of found) console.log(`  ${p.name}  ${dim(p.root)}`);