vibeview 0.32.0 → 0.33.0

package/dist/{chunk-ZZK7YQSP.js → chunk-4D2E2PE4.js}

@@ -377,9 +377,19 @@ var ApiClient = class {
   /** Report presence on a session and read it back in one call. A Roku dev
    *  loop has no tunnel and no browser, so this is what tells the backend
    *  someone is still using the session between device commands. Same
-   *  response shape as `getSession`. */
-  async touchSession(sessionId) {
-    return this.requestRaw("POST", `/sessions/${sessionId}/presence`);
+   *  response shape as `getSession`.
+   *
+   *  `lease: true` also renews the caller's hold on the session: a dev loop
+   *  (`vibeview dev`, `--detach`, MCP `dev_start`) renews it every
+   *  `AGENT_LEASE_RENEW_MS`, and once renewals stop — the process was killed,
+   *  crashed, or the computer went to sleep — the backend ends the session
+   *  about a minute later instead of after the org idle timeout. */
+  async touchSession(sessionId, opts = {}) {
+    return this.requestRaw(
+      "POST",
+      `/sessions/${sessionId}/presence`,
+      opts.lease ? { lease: true } : void 0
+    );
   }
   async stopSession(sessionId) {
     await this.requestRaw("DELETE", `/sessions/${sessionId}`);

package/dist/{chunk-T6H5XTBX.js → chunk-D3OZPFJ3.js}

@@ -13,7 +13,7 @@ import {
   resolveArtifact,
   resolveAuth,
   uploadAppBuild
-} from "./chunk-ZZK7YQSP.js";
+} from "./chunk-4D2E2PE4.js";
 
 // src/lib/dev-config.ts
 import { readFileSync, renameSync, rmSync, writeFileSync } from "fs";
@@ -360,6 +360,30 @@ function checkDevBuild(app, buildId, platform, opts = {}) {
   }
   return build;
 }
+function debugBuildsNewestFirst(app) {
+  const time = (b) => b.uploaded_at ? Date.parse(b.uploaded_at) || 0 : 0;
+  return app.builds.filter((b) => canUseMetro(b) === true).sort((a, b) => time(b) - time(a) || b.id - a.id);
+}
+function pickDevBuild(app, localVersion) {
+  const builds = debugBuildsNewestFirst(app);
+  if (builds.length === 0) return null;
+  const newest = builds[0];
+  if (!localVersion || newest.version === localVersion) return { build: newest, reason: null };
+  const match = builds.find((b) => b.version === localVersion);
+  if (!match) return { build: newest, reason: null };
+  return {
+    build: match,
+    reason: `the newest debug build (${newest.id}) is version ${newest.version ?? "unknown"}, this project is version ${localVersion}`
+  };
+}
+function buildLabel(b) {
+  const parts = [];
+  if (b.version) parts.push(`version ${b.version}${b.build_number ? ` (${b.build_number})` : ""}`);
+  parts.push(b.kind ?? buildKind(b));
+  if (b.uploaded_at) parts.push(`uploaded ${formatUtcTimestamp(b.uploaded_at)}`);
+  if (b.note) parts.push(JSON.stringify(b.note.length > 60 ? `${b.note.slice(0, 57)}...` : b.note));
+  return `${b.id} (${parts.join(", ")})`;
+}
 
 // src/commands/list-builds.ts
 import chalk from "chalk";
@@ -604,16 +628,6 @@ function describeLocalChanges(before, after) {
   return changes;
 }
 
-// src/commands/build.ts
-import { spawn as spawn2 } from "child_process";
-import { createInterface } from "readline";
-import { select as select2 } from "@inquirer/prompts";
-import chalk3 from "chalk";
-
-// src/lib/dev-setup.ts
-import chalk2 from "chalk";
-import { input, select } from "@inquirer/prompts";
-
 // src/lib/project-detect.ts
 import { existsSync as existsSync2, readFileSync as readFileSync4, readdirSync, statSync } from "fs";
 import { join as join4 } from "path";
@@ -791,8 +805,72 @@ function productionDefaultsFor(cwd, platform) {
   }
   return {};
 }
+function uniqueMatch(text, re) {
+  const found = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(re)) {
+    const v = m[1].trim().replace(/^"|"$/g, "");
+    if (v && !v.includes("$")) found.add(v);
+  }
+  return found.size === 1 ? [...found][0] : null;
+}
+function readText(path) {
+  try {
+    return readFileSync4(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function pbxprojText(cwd) {
+  try {
+    const proj = readdirSync(join4(cwd, "ios")).find((f) => f.endsWith(".xcodeproj"));
+    return proj ? readText(join4(cwd, "ios", proj, "project.pbxproj")) : null;
+  } catch {
+    return null;
+  }
+}
+function localAppIdentity(cwd, platform) {
+  const rn = readJson(cwd, "node_modules/react-native/package.json");
+  const reactNative = typeof rn?.version === "string" ? rn.version : null;
+  const android = platform === "android" || platform === "androidtv";
+  const ios = platform === "ios" || platform === "tvos";
+  let version = null;
+  let bundleId = null;
+  const dynamic = existsSync2(join4(cwd, "app.config.js")) || existsSync2(join4(cwd, "app.config.ts"));
+  const raw = dynamic ? null : readJson(cwd, "app.config.json") ?? readJson(cwd, "app.json");
+  const expo = raw ? "expo" in raw ? raw.expo : raw : null;
+  if (expo && typeof expo === "object") {
+    const cfg = expo;
+    if (typeof cfg.version === "string") version = cfg.version;
+    const section = android ? cfg.android : ios ? cfg.ios : null;
+    const id = android ? section?.package : section?.bundleIdentifier;
+    if (typeof id === "string") bundleId = id;
+  }
+  if (android && (!version || !bundleId)) {
+    const gradle = readText(join4(cwd, "android", "app", "build.gradle")) ?? readText(join4(cwd, "android", "app", "build.gradle.kts"));
+    if (gradle) {
+      version ??= uniqueMatch(gradle, /versionName\s*=?\s*["']([^"']+)["']/g);
+      bundleId ??= uniqueMatch(gradle, /applicationId\s*=?\s*["']([^"']+)["']/g);
+    }
+  }
+  if (ios && (!version || !bundleId)) {
+    const pbx = pbxprojText(cwd);
+    if (pbx) {
+      version ??= uniqueMatch(pbx, /MARKETING_VERSION = ([^;]+);/g);
+      bundleId ??= uniqueMatch(pbx, /PRODUCT_BUNDLE_IDENTIFIER = ([^;]+);/g);
+    }
+  }
+  return { reactNative, version, bundleId };
+}
+
+// src/commands/build.ts
+import { spawn as spawn2 } from "child_process";
+import { createInterface } from "readline";
+import { select as select2 } from "@inquirer/prompts";
+import chalk3 from "chalk";
 
 // src/lib/dev-setup.ts
+import chalk2 from "chalk";
+import { input, select } from "@inquirer/prompts";
 function platformChoices(cwd) {
   const choices = [
     { value: "ios", name: "iOS simulator" },
@@ -2359,6 +2437,12 @@ function parseWatchSeconds(flag) {
   }
   return seconds;
 }
+var AGENT_LEASE_RENEW_MS = 15e3;
+var AGENT_LEASE_TTL_MS = 6e4;
+function leaseLapsedReason(gapMs) {
+  if (gapMs <= AGENT_LEASE_TTL_MS) return void 0;
+  return `the session ended because this computer did not check in with VibeView for ${Math.round(gapMs / 1e3)}s (asleep, offline, or the process was paused) \u2014 start a new session to continue`;
+}
 function queuedLine(position, reasonMessage) {
   const where = position ? ` (position ${position})` : "";
   const why = reasonMessage ?? "Every device is busy.";
@@ -2379,9 +2463,14 @@ async function startDevSession(cfg, onEvent = () => {
   let stopping = false;
   let tunnel = null;
   let queueEntryId = null;
+  let lastLeaseAt = Date.now();
+  let leaseTimer = null;
   const stopSession = async (code) => {
     if (stopping) return;
     stopping = true;
+    if (leaseTimer) clearInterval(leaseTimer);
+    leaseTimer = null;
+    const reason = code !== 0 ? leaseLapsedReason(Date.now() - lastLeaseAt) : void 0;
     tunnel?.stop();
     if (queueEntryId !== null) {
       await api.cancelQueueEntry(queueEntryId).catch(() => {
@@ -2390,8 +2479,27 @@ async function startDevSession(cfg, onEvent = () => {
     }
     await api.stopSession(sessionId).catch(() => {
     });
-    onEvent({ event: "session_ended", session_id: sessionId, code });
+    onEvent({ event: "session_ended", session_id: sessionId, code, ...reason ? { reason } : {} });
   };
+  const renewLease = async () => {
+    if (stopping) return;
+    let info;
+    try {
+      info = await api.touchSession(sessionId, { lease: true });
+    } catch {
+      return;
+    }
+    if (stopping) return;
+    if (info.status === "stopped" || info.status === "failed") {
+      void stopSession(1);
+      return;
+    }
+    lastLeaseAt = Date.now();
+  };
+  void renewLease();
+  leaseTimer = setInterval(() => void renewLease(), AGENT_LEASE_RENEW_MS);
+  leaseTimer.unref?.();
+  cfg.onCreated?.({ sessionId, stop: () => stopSession(1) });
   try {
     const started = await api.startSession(sessionId);
     if (started.status === "queued") {
@@ -2406,6 +2514,7 @@ async function startDevSession(cfg, onEvent = () => {
       });
       await pollWhileQueued(api, sessionId, QUEUE_WAIT_MS);
       queueEntryId = null;
+      cfg.onDequeued?.();
     }
     const pageUrl = `${cfg.webUrl || cfg.baseUrl}/sandbox/${sessionId}`;
     const reportedWarnings = /* @__PURE__ */ new Set();
@@ -2458,7 +2567,14 @@ async function startDevSession(cfg, onEvent = () => {
       reportedWarnings.add(w);
       onEvent({ event: "warning", message: w });
     }
-    return { sessionId, pageUrl, stop: () => stopSession(0), reportedWarnings, session: active };
+    return {
+      sessionId,
+      pageUrl,
+      stop: () => stopSession(0),
+      reportedWarnings,
+      session: active,
+      lapsedReason: () => leaseLapsedReason(Date.now() - lastLeaseAt)
+    };
   } catch (err) {
     await stopSession(1);
     throw err;
@@ -3102,7 +3218,7 @@ async function runDevInProcess(opts) {
             chalk4.dim("  Putting the channel on the Roku \u2014 the link appears once it is up.")
           );
         } else if (evt.event === "session_ended" && !stopping && handle) {
-          console.error(chalk4.red("tunnel closed by server \u2014 session ended"));
+          console.error(chalk4.red(evt.reason ?? "session ended by the server"));
           stopping = true;
           endedEmitted = true;
           emit(opts.json, evt);
@@ -3217,8 +3333,14 @@ async function runDevInProcess(opts) {
             }
             const verdict = sessionLivenessVerdict(info);
             if (verdict.end && !stopping) {
-              console.error(chalk4.red(verdict.message));
-              emit(opts.json, { event: "session_ended", session_id: sessionId, code: 1 });
+              const reason = handle?.lapsedReason?.();
+              console.error(chalk4.red(reason ?? verdict.message));
+              emit(opts.json, {
+                event: "session_ended",
+                session_id: sessionId,
+                code: 1,
+                ...reason ? { reason } : {}
+              });
               endedEmitted = true;
               await stopSession(1);
               return;
@@ -3664,7 +3786,7 @@ var AGENT_COMMANDS = [
     // iOS system alerts only.
     verb: "alert",
     tool: "alert",
-    summary: "Inspect or respond to a visible iOS system alert (get, accept, or dismiss).",
+    summary: "Inspect or respond to a visible system alert on iOS or Apple TV (get, accept, or dismiss). `get` returns the message and the button labels.",
     mutating: true,
     params: [
       {
@@ -3747,7 +3869,7 @@ var AGENT_COMMANDS = [
     // tools.py open_url: { url: string }.
     verb: "open-url",
     tool: "open_url",
-    summary: "Open a deep link or URL in the app under test. The link goes to that app only; one it has no screen for fails rather than opening a browser.",
+    summary: "Open a deep link in the app under test. The link goes to that app only, never a browser: on Android a link the app has no screen for fails; on iOS only the app's own URL scheme (e.g. myapp://settings) is accepted, and a web or system link is refused.",
     mutating: true,
     params: [
       {
@@ -3759,6 +3881,16 @@ var AGENT_COMMANDS = [
       }
     ]
   },
+  {
+    // relaunch_app: {} — terminate the session's app and launch it again the
+    // way the session launched it (same launch params); its data is kept.
+    // Refused on embed sessions (their watchdog owns launching) and on Roku.
+    verb: "relaunch-app",
+    tool: "relaunch_app",
+    summary: "Close the app under test and start it again: a cold start that keeps the app's data, e.g. to check that something persists. Its log keeps streaming across the restart. Not available on Roku or embed sessions.",
+    mutating: true,
+    params: []
+  },
   {
     // set_posture: { posture: 'closed' | 'partial' | 'open' } OR { angle: 0..180 }
     // — exactly one (buildToolCall enforces it CLI-side, agent_control.py's
@@ -3805,6 +3937,33 @@ var AGENT_COMMANDS = [
       }
     ]
   },
+  {
+    // set_location: { latitude: -90..90, longitude: -180..180 } — both
+    // required (agent_control.py validate_tool_args refuses anything else).
+    // The same control as the dashboard's Set location. Flags rather than
+    // positionals: a western/southern coordinate starts with `-`, which a
+    // positional would read as an option.
+    verb: "set-location",
+    tool: "set_location",
+    summary: "Set the device's simulated GPS location, for location-based flows. Phones, tablets and foldables (iOS and Android); not available on TV devices.",
+    mutating: true,
+    params: [
+      {
+        name: "latitude",
+        cli: "--lat",
+        type: "number",
+        required: true,
+        description: "Latitude in decimal degrees, -90 to 90."
+      },
+      {
+        name: "longitude",
+        cli: "--lon",
+        type: "number",
+        required: true,
+        description: "Longitude in decimal degrees, -180 to 180 (west is negative)."
+      }
+    ]
+  },
   {
     // tools.py wait: { seconds?: number } (default: 2). Note the wire arg is
     // "seconds", NOT "ms" — tool_dispatch.py reads args.get("seconds", 2)
@@ -3949,6 +4108,14 @@ function resultLines(result) {
     const state = deviceStateLine(r);
     if (state) lines.push(state);
   }
+  if (Array.isArray(r.buttons) && r.buttons.length > 0) {
+    const labels = r.buttons.filter((b) => typeof b === "string");
+    if (labels.length > 0)
+      lines.push(`buttons: ${labels.map((b) => JSON.stringify(b)).join(", ")}`);
+  }
+  if (r.action === "location_set" && typeof r.latitude === "number" && typeof r.longitude === "number") {
+    lines.push(`location: ${r.latitude}, ${r.longitude}`);
+  }
   if (typeof r.note === "string" && r.note) lines.push(chalk6.dim(r.note));
   if (typeof r.message === "string" && r.message) lines.push(r.message);
   if (typeof r.warning === "string" && r.warning) lines.push(r.warning);
@@ -3959,8 +4126,8 @@ function deviceStateLine(r) {
   if (r.action === "rotated") {
     if (typeof r.device_orientation === "string") {
       let o = `device held ${r.device_orientation}`;
-      if (typeof r.screen_orientation === "string" && r.screen_orientation !== r.device_orientation) {
-        o += ` (picture on the lit screen: ${r.screen_orientation})`;
+      if (typeof r.screen_orientation === "string" && !r.device_orientation.startsWith(r.screen_orientation)) {
+        o += typeof r.posture === "string" ? ` (picture on the lit screen: ${r.screen_orientation})` : ` (screen stayed ${r.screen_orientation})`;
       }
       parts.push(o);
     }
@@ -4196,7 +4363,9 @@ async function runAgentVerb(cmd, positionals, opts) {
     }
     writeFileSync6(outPath, imageBytes);
     if (opts.json) {
-      console.log(JSON.stringify(envelope));
+      console.log(
+        JSON.stringify({ ...envelope, result: { written_to: outPath, bytes: imageBytes.length } })
+      );
     } else {
       process.stderr.write(renderEnvelope(envelope) + "\n");
       console.log(outPath);
@@ -4222,7 +4391,11 @@ export {
   loadDevConfig,
   resolveMetro,
   parseBuildId,
+  buildKind,
   checkDevBuild,
+  debugBuildsNewestFirst,
+  pickDevBuild,
+  buildLabel,
   buildRows,
   formatBuildRowsHuman,
   listBuilds,
@@ -4234,6 +4407,7 @@ export {
   checkMetro,
   loadLocalDevConfig,
   effectiveDevConfig,
+  localAppIdentity,
   buildCommand,
   formatDuration,
   BUILD_TERMINAL_STATUSES,
@@ -4243,7 +4417,6 @@ export {
   printOutcomeLine,
   createRokuPush,
   startDevSession,
-  ROKU_LIVENESS_INTERVAL_MS,
   PLATFORM_DEVICE,
   dev,
   formatDevicesHuman,

package/dist/cli.js

@@ -24,7 +24,7 @@ import {
   readDevStateFile,
   readMetroState,
   runAgentVerb
-} from "./chunk-T6H5XTBX.js";
+} from "./chunk-D3OZPFJ3.js";
 import {
   ApiClient,
   ApiStatusError,
@@ -45,7 +45,7 @@ import {
   resolveAuth,
   saveConfig,
   uploadApp
-} from "./chunk-ZZK7YQSP.js";
+} from "./chunk-4D2E2PE4.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -4079,7 +4079,7 @@ program.command("dev-reload").description(
 program.command("mcp").description(
   "Run an MCP stdio server exposing the agent verbs (tap, swipe, type, ...) plus dev_start/dev_stop/dev_reload as tools"
 ).option("--token <token>", "API token (or set VIBEVIEW_API_TOKEN)").action(async (opts) => {
-  const { runMcpServer } = await import("./server-FJSBWEHZ.js");
+  const { runMcpServer } = await import("./server-GHCQHKYX.js");
   await runMcpServer({ ...opts, version: pkg.version });
 });
 program.command("agent-setup").description(

package/dist/{server-FJSBWEHZ.js → server-GHCQHKYX.js}

@@ -4,12 +4,14 @@ import {
   DEV_PLATFORMS,
   PLATFORM_DEVICE,
   PLATFORM_NEEDS_METRO,
-  ROKU_LIVENESS_INTERVAL_MS,
+  buildKind,
+  buildLabel,
   buildRows,
   buildToolCall,
   checkDevBuild,
   checkMetro,
   createRokuPush,
+  debugBuildsNewestFirst,
   decodeScreenshotResult,
   effectiveDevConfig,
   filterDeviceModels,
@@ -18,18 +20,20 @@ import {
   isDevPlatform,
   loadDevConfig,
   loadLocalDevConfig,
+  localAppIdentity,
   parseBuildId,
+  pickDevBuild,
   platformWithArticle,
   readDevState,
   renderEnvelope,
   resolveMetro,
   startDevSession
-} from "./chunk-T6H5XTBX.js";
+} from "./chunk-D3OZPFJ3.js";
 import {
   ApiClient,
   NotFoundError,
   resolveAuth
-} from "./chunk-ZZK7YQSP.js";
+} from "./chunk-4D2E2PE4.js";
 
 // src/mcp/server.ts
 import { writeFileSync } from "fs";
@@ -45,14 +49,25 @@ function isMcpDevPlatform(p) {
   return isDevPlatform(p) && MCP_DEV_PLATFORMS.includes(p);
 }
 var MCP_PARAM_DESCRIPTIONS = {
-  wait: { seconds: "How long to wait, in seconds. Default: 2." }
+  wait: { seconds: "How long to wait, in seconds. Default: 2." },
+  screenshot: {
+    out: "File path to write the PNG to on the machine running this server (default: a temp file)."
+  }
 };
 function paramToProperty(cmd, param) {
   return {
     type: param.type,
-    description: MCP_PARAM_DESCRIPTIONS[cmd.verb]?.[param.name] ?? param.description
+    description: MCP_PARAM_DESCRIPTIONS[cmd.verb]?.[param.name] ?? mcpText(cmd, param.description)
   };
 }
+function mcpText(cmd, text) {
+  let out = text.replace(/`?(?:vibeview )?list-devices --models`?/g, "list_device_models").replace(/`vibeview ([a-z-]+)`/g, (_, verb) => toolNameFor(verb));
+  for (const param of cmd.params) {
+    if (param.cli === "positional") continue;
+    out = out.replace(new RegExp(`${param.cli}(?![a-z-])`, "g"), param.name);
+  }
+  return out;
+}
 function toolNameFor(verb) {
   return verb.replace(/-/g, "_");
 }
@@ -66,12 +81,12 @@ function toolDefFromCommand(cmd) {
   if (cmd.verb === "screenshot") {
     properties.inline = {
       type: "boolean",
-      description: "Return the image itself so you can see it, not just the file path. Set this to true whenever you need to judge how the screen LOOKS, or whenever you cannot open files on the machine running this server \u2014 otherwise the screenshot is only written to disk and you never see it. It costs a lot of context, so skip it when you only need to confirm an action happened (the response already tells you what changed)."
+      description: "Return the image itself so you can see it, not just the file path. Set this to true whenever you need to judge how the screen LOOKS, or whenever you cannot open files on the machine running this server \u2014 otherwise the screenshot is only written to disk and you never see it. It costs context, so skip it when you only need to confirm an action happened (the response already tells you what changed). The image has the same size as the screenshot (a JPEG when the PNG is large), so a point read off it is the coordinate tap and drag take."
     };
   }
   return {
     name: toolNameFor(cmd.verb),
-    description: cmd.summary,
+    description: mcpText(cmd, cmd.summary),
     mutating: cmd.mutating,
     properties,
     required
@@ -205,8 +220,15 @@ function errorResult(message) {
   return { content: [{ type: "text", text: forMcp(message) }], isError: true };
 }
 function forMcp(message) {
-  let text = message.replace(/`vibeview list-devices --models`/g, "list_device_models").replace(/`vibeview list-builds <app>`/g, "list_builds").replace(/`vibeview list-builds ([^`\s]+)`/g, 'list_builds (app "$1")').replace(/`vibeview list-apps`/g, "list_apps").replace(/\blist-apps\b/g, "list_apps").replace(/`vibeview upload-app`/g, "upload_app").replace(/`vibeview dev` needs/g, "dev_start needs");
+  let text = message.replace(/`vibeview list-devices --models`/g, "list_device_models").replace(/`vibeview list-builds <app>`/g, "list_builds").replace(/`vibeview list-builds ([^`\s]+)`/g, 'list_builds with app "$1"').replace(
+    /use `vibeview dev --standalone --build (\d+)`/g,
+    "call dev_start with standalone: true and build_id: $1"
+  ).replace(
+    /Set VIBEVIEW_API_TOKEN \(or --token\) to a full-access token for this command\./g,
+    "Start this MCP server with a full-access token (VIBEVIEW_API_TOKEN or --token)."
+  ).replace(/`vibeview list-apps`/g, "list_apps").replace(/\blist-apps\b/g, "list_apps").replace(/`vibeview upload-app`/g, "upload_app").replace(/`vibeview dev` needs/g, "dev_start needs");
   if (/No debug build|is not a debug build/.test(text) && !/standalone: true/.test(text)) {
+    text = `${text.replace(/\s+$/, "")}${/[.!?]$/.test(text.trim()) ? "" : "."}`;
     text += " To run a release build as it is, with no Metro, call dev_start with standalone: true.";
   }
   return text;
@@ -244,9 +266,9 @@ async function explainInactive(sessionId, deps) {
 function findCommand(toolName) {
   return AGENT_COMMANDS.find((c) => toolNameFor(c.verb) === toolName);
 }
-async function handleToolCall(toolName, args, deps) {
+async function handleToolCall(toolName, args, deps, extra = {}) {
   if (toolName === "dev_start") {
-    return handleDevStart(args, deps);
+    return handleDevStart(args, deps, extra);
   }
   if (toolName === "dev_stop") {
     return handleDevStop(deps);
@@ -287,6 +309,9 @@ async function handleToolCall(toolName, args, deps) {
     const positionals = positionalsFor(cmd, rest);
     const opts = optsFor(cmd, rest);
     call = buildToolCall(cmd, positionals, opts);
+    if (cmd.verb === "screenshot" && args.inline === true) {
+      call = { ...call, args: { ...call.args, preview: true } };
+    }
   } catch (err) {
     return errorResult(`error: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -307,9 +332,10 @@ async function handleToolCall(toolName, args, deps) {
   return textResult(renderEnvelope(envelope), envelope, !envelope.ok);
 }
 function screenshotToolResult(envelope, args) {
+  const { image, preview } = splitScreenshotResult(envelope.result);
   let imageBytes;
   try {
-    imageBytes = decodeScreenshotResult(envelope.result);
+    imageBytes = decodeScreenshotResult(image);
   } catch (err) {
     return errorResult(`error: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -325,15 +351,54 @@ function screenshotToolResult(envelope, args) {
     ...envelope,
     result: { written_to: outPath, bytes: imageBytes.length }
   };
-  const content = [
-    { type: "text", text: `${renderEnvelope(sanitized)}
-screenshot written to ${outPath}` }
-  ];
+  const lines = [`${renderEnvelope(sanitized)}
+screenshot written to ${outPath}`];
+  let inlineBlock = null;
   if (args.inline === true) {
-    content.push({ type: "image", data: imageBytes.toString("base64"), mimeType: "image/png" });
+    if (preview) {
+      inlineBlock = { type: "image", data: preview.data, mimeType: preview.mimeType };
+      lines.push(
+        `inline image: ${preview.mimeType === "image/jpeg" ? "JPEG" : "PNG"} ${preview.width}x${preview.height}, ${kb(preview.bytes)} \u2014 the same size as the saved PNG, so a point read off it is the coordinate tap and drag take`
+      );
+    } else if (imageBytes.length <= INLINE_PNG_MAX_BYTES) {
+      inlineBlock = { type: "image", data: imageBytes.toString("base64"), mimeType: "image/png" };
+    } else {
+      lines.push(
+        `inline image left out: the PNG is ${kb(imageBytes.length)}, too large to send inline \u2014 open the file instead`
+      );
+    }
   }
+  const content = [{ type: "text", text: lines.join("\n") }];
+  if (inlineBlock) content.push(inlineBlock);
   return { content, structuredContent: sanitized };
 }
+var INLINE_PNG_MAX_BYTES = 15e5;
+function kb(bytes) {
+  return bytes >= 1e6 ? `${(bytes / 1e6).toFixed(1)} MB` : `${Math.round(bytes / 1e3)} KB`;
+}
+function splitScreenshotResult(result) {
+  if (!result || typeof result !== "object" || !("image" in result)) {
+    return { image: result, preview: null };
+  }
+  const r = result;
+  const p = r.preview;
+  const url = typeof p?.data_url === "string" ? p.data_url : "";
+  const comma = url.indexOf(",");
+  if (!p || comma < 0 || typeof p.mime_type !== "string" || typeof p.width !== "number" || typeof p.height !== "number") {
+    return { image: r.image, preview: null };
+  }
+  const data = url.slice(comma + 1);
+  return {
+    image: r.image,
+    preview: {
+      data,
+      mimeType: p.mime_type,
+      width: p.width,
+      height: p.height,
+      bytes: typeof p.bytes === "number" ? p.bytes : Math.floor(data.length * 3 / 4)
+    }
+  };
+}
 function positionalsFor(cmd, args) {
   return cmd.params.filter((p) => p.cli === "positional").map((p) => args[p.name] === void 0 ? void 0 : String(args[p.name])).filter((v) => v !== void 0);
 }
@@ -348,7 +413,7 @@ function optsFor(cmd, args) {
   }
   return opts;
 }
-async function handleDevStart(args, deps) {
+async function handleDevStart(args, deps, extra = {}) {
   const platform = args.platform;
   if (!isMcpDevPlatform(platform)) {
     return errorResult(
@@ -373,7 +438,8 @@ async function handleDevStart(args, deps) {
       metroPort: typeof args.metro_port === "number" ? args.metro_port : void 0,
       model: typeof args.model === "string" && args.model.trim() ? args.model : void 0,
       ...buildId !== void 0 ? { buildId } : {},
-      ...standalone ? { standalone } : {}
+      ...standalone ? { standalone } : {},
+      ...extra.progress ? { onProgress: extra.progress } : {}
     });
     const warnings = result.warnings ?? [];
     const payload = {
@@ -381,17 +447,56 @@ async function handleDevStart(args, deps) {
       page_url: result.pageUrl,
       standalone,
       device: result.device ?? null,
+      build: result.build ?? null,
+      build_reason: result.buildReason ?? null,
+      other_debug_builds: result.otherBuilds ?? [],
+      project: result.project ?? null,
+      queued_seconds: result.queuedSeconds ?? null,
       warnings
     };
     const lines = [`${standalone ? "session" : "dev session"} started: ${payload.session_id}`];
     const device = result.device ? deviceLine(result.device) : null;
     if (device) lines.push(device);
+    lines.push(...buildLines(result, standalone));
+    if (typeof result.queuedSeconds === "number") {
+      lines.push(`waited ${Math.round(result.queuedSeconds)} s in the queue for a device`);
+    }
     lines.push(payload.page_url, ...warnings.map((w) => `warning: ${w}`));
     return textResult(lines.join("\n"), payload);
   } catch (err) {
     return errorResult(`error: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
+function buildLines(result, standalone) {
+  const lines = [];
+  if (result.build) {
+    lines.push(`build: ${buildLabel(result.build)}`);
+  }
+  if (result.buildReason) lines.push(`picked that build because ${result.buildReason}`);
+  const others = result.otherBuilds ?? [];
+  if (others.length > 0) {
+    lines.push(
+      `other debug builds: ${others.map((b) => buildLabel(b)).join("; ")} \u2014 pass build_id to run one`
+    );
+  }
+  const rn = result.project?.reactNative;
+  if (!standalone && rn) {
+    lines.push(
+      `this project: react-native ${rn}. If the app shows "React Native version mismatch", the build was made with another React Native: run a build made from this project (build_id, see list_builds).`
+    );
+  }
+  return lines;
+}
+function startedBuild(b) {
+  return {
+    id: b.id,
+    version: b.version ?? null,
+    build_number: b.build_number ?? null,
+    kind: buildKind(b),
+    uploaded_at: b.uploaded_at ?? null,
+    note: b.note ?? null
+  };
+}
 function deviceLine(d) {
   const name = d.model || d.name;
   if (!name) return null;
@@ -542,7 +647,7 @@ async function handleUploadApp(args, deps) {
   }
   const name = typeof args.name === "string" && args.name ? args.name : void 0;
   const upload = deps.uploadApp ?? (async (f, n) => {
-    const { uploadAppBuild } = await import("./upload-app-2LVG4LMB.js");
+    const { uploadAppBuild } = await import("./upload-app-AKD73742.js");
     const { result: result2 } = await uploadAppBuild(f, { ...deps.auth, name: n });
     return result2;
   });
@@ -575,16 +680,69 @@ async function handleUploadApp(args, deps) {
   ];
   return textResult(lines.join("\n"), payload);
 }
+var START_PROGRESS_INTERVAL_MS = 1e4;
+function startProgress(report) {
+  const started = Date.now();
+  let queuedAt = null;
+  let dequeuedAt = null;
+  let phase = "starting the device";
+  let timer = null;
+  const say = (message) => {
+    try {
+      report?.(message);
+    } catch {
+    }
+  };
+  if (report) {
+    timer = setInterval(() => {
+      const since = Math.round(
+        (Date.now() - (queuedAt !== null && dequeuedAt === null ? queuedAt : started)) / 1e3
+      );
+      say(`${phase} (${since} s so far)`);
+    }, START_PROGRESS_INTERVAL_MS);
+    timer.unref?.();
+  }
+  return {
+    event(evt) {
+      if (evt.event === "queued") {
+        queuedAt = Date.now();
+        const where = evt.position ? ` at position ${evt.position}` : "";
+        phase = `waiting in the queue for a device${where}`;
+        say(
+          `${evt.message ?? "Every device of this kind is busy."} Waiting in the queue${where}; dev_start returns once a device is free.`
+        );
+      } else if (evt.event === "tunnel_connected") {
+        phase = "connected to Metro; waiting for the app to be installed";
+        say("connected to Metro; the device is starting and the app is being installed");
+      } else if (evt.event === "installing") {
+        phase = "installing the app";
+        say("the device is up; installing the app");
+      }
+    },
+    dequeued() {
+      dequeuedAt = Date.now();
+      phase = "got a device; starting it";
+      if (queuedAt !== null)
+        say(
+          `got a device after ${Math.round((dequeuedAt - queuedAt) / 1e3)} s in the queue; starting it`
+        );
+    },
+    queuedSeconds() {
+      if (queuedAt === null) return null;
+      return ((dequeuedAt ?? Date.now()) - queuedAt) / 1e3;
+    },
+    done() {
+      if (timer) clearInterval(timer);
+      timer = null;
+    }
+  };
+}
 function createDevSessionController(auth, webUrl) {
   let handle = null;
   let platform = null;
   let ended = null;
-  let presence = null;
   let reloading = null;
-  const stopPresence = () => {
-    if (presence) clearInterval(presence);
-    presence = null;
-  };
+  let pending = null;
   const readRokuBuild = () => {
     try {
       return loadDevConfig(process.cwd())?.platforms?.roku?.build ?? null;
@@ -597,10 +755,9 @@ function createDevSessionController(auth, webUrl) {
   const markEnded = (e) => {
     if (!handle || handle.sessionId !== e.sessionId) return;
     const dead = handle;
-    stopPresence();
     handle = null;
     platform = null;
-    ended = e;
+    ended = { ...e, reason: e.reason ?? dead.lapsedReason?.() ?? null };
     void dead.stop().catch(() => {
     });
   };
@@ -662,71 +819,116 @@ function createDevSessionController(auth, webUrl) {
           );
         }
       }
-      if (cfg.buildId !== void 0) {
-        checkDevBuild(app, cfg.buildId, cfg.platform, { standalone });
+      let buildId = cfg.buildId;
+      if (buildId !== void 0) {
+        checkDevBuild(app, buildId, cfg.platform, { standalone });
+      }
+      const project = usesMetro ? localAppIdentity(process.cwd(), cfg.platform) : null;
+      let buildReason = null;
+      if (buildId === void 0 && usesMetro) {
+        const picked = pickDevBuild(app, project?.version ?? null);
+        if (picked?.reason) {
+          buildId = picked.build.id;
+          buildReason = picked.reason;
+        }
       }
       const isTv = PLATFORM_DEVICE[cfg.platform].tv;
       const warnings = [];
+      if (project?.bundleId && app.package_name && project.bundleId !== app.package_name) {
+        warnings.push(
+          `this project's ${isTv || cfg.platform.startsWith("android") ? "package name" : "bundle id"} is ${project.bundleId}, but app ${app.public_id} is ${app.package_name} \u2014 check that dev_start runs the app this project builds (list_apps)`
+        );
+      }
+      const progress = startProgress(cfg.onProgress);
       let started = null;
-      started = await startDevSession(
-        {
-          token: auth.token,
-          baseUrl: auth.baseUrl,
-          webUrl,
-          platform: cfg.platform,
-          appId,
-          deviceCategory: isTv ? "tv" : entry?.deviceCategory ?? "phone",
-          // A named model decides the category itself (startDevSession).
-          model: cfg.model,
-          buildId: cfg.buildId,
-          ...standalone ? { standalone } : {},
-          metroPort,
-          open: false
-        },
-        (evt) => {
-          if (evt.event === "warning") warnings.push(evt.message);
-          if (evt.event === "session_ended" && evt.code !== 0 && started) {
-            const id = evt.session_id;
-            void api().getSession(id).then(
-              (info) => ({ status: info.status, reason: info.failure_reason ?? null }),
-              () => ({ status: "stopped", reason: null })
-            ).then(({ status, reason }) => markEnded({ sessionId: id, status, reason }));
+      try {
+        started = await startDevSession(
+          {
+            token: auth.token,
+            baseUrl: auth.baseUrl,
+            webUrl,
+            platform: cfg.platform,
+            appId,
+            deviceCategory: isTv ? "tv" : entry?.deviceCategory ?? "phone",
+            // A named model decides the category itself (startDevSession).
+            model: cfg.model,
+            buildId,
+            ...standalone ? { standalone } : {},
+            metroPort,
+            open: false,
+            onCreated: (created) => {
+              pending = created;
+            },
+            onDequeued: () => progress.dequeued()
+          },
+          (evt) => {
+            progress.event(evt);
+            if (evt.event === "warning") warnings.push(evt.message);
+            if (evt.event === "session_ended" && evt.code !== 0 && started) {
+              const id = evt.session_id;
+              void api().getSession(id).then(
+                (info) => ({ status: info.status, reason: info.failure_reason ?? null }),
+                () => ({ status: "stopped", reason: null })
+              ).then(({ status, reason }) => markEnded({ sessionId: id, status, reason }));
+            }
           }
-        }
-      );
+        );
+      } finally {
+        progress.done();
+        pending = null;
+      }
       handle = started;
       platform = cfg.platform;
       ended = null;
-      if (!usesMetro) {
-        const client = api();
-        const sessionId = handle.sessionId;
-        presence = setInterval(() => {
-          client.touchSession(sessionId).then(
-            (info) => {
-              if (info && isEndedStatus(info.status)) {
-                markEnded({ sessionId, status: info.status, reason: info.failure_reason ?? null });
-              }
-            },
-            () => {
-            }
-          );
-        }, ROKU_LIVENESS_INTERVAL_MS);
-        presence.unref?.();
-      }
+      const installedId = handle.session?.app_build_id ?? buildId ?? null;
+      const installed = app.builds.find((b) => b.id === installedId);
+      const others = usesMetro ? debugBuildsNewestFirst(app).filter((b) => b.id !== installedId) : [];
       return {
         sessionId: handle.sessionId,
         pageUrl: handle.pageUrl,
         device: startedDevice(handle.session),
+        build: installed ? startedBuild(installed) : typeof installedId === "number" ? {
+          id: installedId,
+          version: handle.session?.app_version ?? null,
+          build_number: handle.session?.app_build_number ?? null,
+          kind: "unknown",
+          uploaded_at: null,
+          note: null
+        } : null,
+        buildReason,
+        otherBuilds: others.slice(0, 3).map(startedBuild),
+        project,
+        queuedSeconds: progress.queuedSeconds(),
         warnings
       };
     },
     async stop() {
-      stopPresence();
       await handle?.stop();
       handle = null;
       platform = null;
       ended = null;
     },
+    async shutdown() {
+      const stopped = [];
+      const held = handle;
+      const starting = pending;
+      handle = null;
+      platform = null;
+      pending = null;
+      await Promise.all([
+        held ? held.stop().then(
+          () => void stopped.push(held.sessionId),
+          () => {
+          }
+        ) : null,
+        starting ? starting.stop().then(
+          () => void stopped.push(starting.sessionId),
+          () => {
+          }
+        ) : null
+      ]);
+      return stopped;
+    },
     current() {
       return handle ? { sessionId: handle.sessionId, pageUrl: handle.pageUrl } : null;
     },
@@ -803,6 +1005,7 @@ var MCP_INSTRUCTIONS = [
   "VibeView runs your app on a cloud iOS simulator, Android emulator, Apple TV, Android TV or Roku (beta) device you control with these tools.",
   "Loop: dev_start (platform, app from list_apps; add standalone: true for a release or CI build that needs no Metro) -> ui_tree -> act with refs (tap @e5, type, swipe, press) and read the change each action reports -> dev_stop when done.",
   "Foldables: pick one by model in dev_start (list_device_models marks them foldable, with free/busy counts), then set_posture and rotate.",
+  "set_location sets the simulated GPS position (phones and tablets) for location-based flows.",
   "screenshot writes a PNG and returns its path; pass inline: true to see the image. logs reads the app output after a crash or blank screen.",
   "A session stopped elsewhere is reported as ended; call dev_start again for a new one."
 ].join("\n");
@@ -841,30 +1044,89 @@ async function createMcpServer(opts) {
         inputSchema: zodShape(def),
         annotations: { readOnlyHint: !def.mutating }
       },
-      async (args) => {
-        const result = await handleToolCall(def.name, args ?? {}, deps);
+      async (args, extra) => {
+        const result = await handleToolCall(def.name, args ?? {}, deps, {
+          progress: progressReporter(extra)
+        });
         return result;
       }
     );
   }
-  return server;
+  return { server, devSession };
+}
+function progressReporter(extra) {
+  const token = extra?._meta?.progressToken;
+  const send = extra?.sendNotification;
+  if (token === void 0 || !send) return void 0;
+  let step = 0;
+  return (message) => {
+    step += 1;
+    void send({
+      method: "notifications/progress",
+      params: { progressToken: token, progress: step, message }
+    }).catch(() => {
+    });
+  };
+}
+var SHUTDOWN_TIMEOUT_MS = 5e3;
+function createShutdown(devSession, opts = {}) {
+  const exit = opts.exit ?? ((code) => process.exit(code));
+  const log = opts.log ?? ((line) => console.error(line));
+  const timeoutMs = opts.timeoutMs ?? SHUTDOWN_TIMEOUT_MS;
+  let running = null;
+  return (reason) => {
+    running ??= (async () => {
+      let timer;
+      const timedOut = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("timeout"), timeoutMs);
+      });
+      const outcome = await Promise.race([
+        devSession.shutdown().catch(() => []),
+        timedOut
+      ]);
+      clearTimeout(timer);
+      if (outcome === "timeout") {
+        log(
+          `vibeview mcp: ${reason}; could not confirm the session stopped within ${timeoutMs / 1e3} s`
+        );
+      } else if (outcome.length > 0) {
+        log(`vibeview mcp: ${reason}; stopped session ${outcome.join(", ")}`);
+      }
+      exit(0);
+    })();
+    return running;
+  };
 }
 async function runMcpServer(opts) {
   chalk.level = 0;
-  const [server, { StdioServerTransport }] = await Promise.all([
+  const [{ server, devSession }, { StdioServerTransport }] = await Promise.all([
     createMcpServer(opts),
     import("@modelcontextprotocol/sdk/server/stdio.js")
   ]);
   const transport = new StdioServerTransport();
+  const shutdown = createShutdown(devSession);
+  process.stdin.once("end", () => void shutdown("the client closed the connection"));
+  process.stdin.once("close", () => void shutdown("the client closed the connection"));
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.once(signal, () => void shutdown(`received ${signal}`));
+  }
+  server.server.onclose = () => void shutdown("the connection closed");
   await server.connect(transport);
 }
 export {
   MCP_INSTRUCTIONS,
+  SHUTDOWN_TIMEOUT_MS,
+  START_PROGRESS_INTERVAL_MS,
+  buildLines,
   buildToolDefinitions,
   createDevSessionController,
+  createShutdown,
   deviceLine,
   forMcp,
   handleToolCall,
+  mcpText,
+  progressReporter,
   runMcpServer,
+  startProgress,
   startedDevice
 };

package/dist/{upload-app-2LVG4LMB.js → upload-app-AKD73742.js}

@@ -3,7 +3,7 @@ import {
   describeBuild,
   uploadApp,
   uploadAppBuild
-} from "./chunk-ZZK7YQSP.js";
+} from "./chunk-4D2E2PE4.js";
 export {
   describeBuild,
   uploadApp,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeview",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "VibeView CLI -- run your app on cloud iOS simulators, Android emulators, Apple TV, Android TV and Roku (beta) devices: a React Native dev loop, device control for you or your coding agent (CLI or MCP), and tests from CI",
   "mcpName": "io.github.vibeview/vibeview",
   "type": "module",

package/skills/vibeview-agent/SKILL.md

@@ -115,7 +115,9 @@ appear unexplained in their `git status`.
   vibeview screenshot --out ./check.png --session <id>   # then open it
   ```
   Over MCP, `screenshot` only writes the file and returns its path unless
-  you pass `inline: true`, which returns the image itself. If you cannot
+  you pass `inline: true`, which returns the image itself (under 1 MB — a
+  JPEG when the PNG is large — at the same size, so its pixels are still tap
+  coordinates). If you cannot
   open files on the machine running the server, `inline: true` is the only
   way you will ever see the screen. It costs a lot of context, so use it
   when appearance matters — not to confirm a tap landed, which the
@@ -161,6 +163,9 @@ appear unexplained in their `git status`.
   ```
   On Apple TV this also covers the "Open in …?" prompt a deep link raises;
   the button is answered with the remote.
+- Use `set-location --lat 51.5074 --lon -0.1278` to place the device before
+  a location-based flow (maps, store finders, region-gated screens); the app
+  reads it like a GPS fix. Not on TV.
 - Use `open-url` to jump straight to a deep link instead of navigating by
   hand:
   ```bash
@@ -190,10 +195,11 @@ appear unexplained in their `git status`.
   angle can keep the inner screen lit on the way down), or the new
   orientation. The posture names come from each device's own angle ranges,
   so trust the reported `posture` over the angle you asked for: the Duo
-  reads 120-169 as `partial`, 170 up as `open`, and 1-119 by direction of
-  travel; an Android foldable uses its own ranges (the Pixel 9 Pro Fold: below
-  30 `closed`, 30-149 `partial`, 150 up `open`) and its inner screen whenever
-  it is not closed. An Android foldable rotates like a phone. Folding
+  reads 0 as `closed` and 170 up as `open`; in between it depends on how the
+  hinge got there (moved in one go it switches at about 85 degrees, moved in
+  small steps it keeps the screen it had); an Android foldable uses its own
+  ranges (the Pixel 9 Pro Fold: 0-30 `closed`, 31-149 `partial`, 150 up
+  `open`) and its inner screen whenever it is not closed. An Android foldable rotates like a phone. Folding
   switches screens of different sizes and rotating turns the picture, so run
   `ui-tree` afterwards — old refs are stale. On other phones and tablets
   `rotate` toggles portrait/landscape (only 90 is accepted); TV devices don't
@@ -266,9 +272,11 @@ human-readable text.
 | `type` | `<text>` | Type text into the currently focused input field. On a phone or tablet a line break presses Enter and submits the field (`$'query\n'`), like `press enter`. |
 | `clear-text` | — | Clear the text in the currently focused input field. |
 | `press` | `<button>` | Press a device button or perform a system gesture (home, back, d-pad, etc). |
-| `open-url` | `<url>` | Open a deep link or URL in the app under test. The link goes to that app only; a link it has no screen for fails (no browser). |
+| `open-url` | `<url>` | Open a deep link in the app under test, never a browser. Android: a link the app has no screen for fails. iOS/Apple TV: only the app's own URL scheme (`myapp://...`); a web or system link is refused. |
+| `relaunch-app` | — | Close the app and start it again (cold start, data kept) — for "does it persist after a restart" checks. The app log keeps streaming. Not on Roku or embed sessions. |
 | `set-posture` | `<closed\|partial\|open>` or `--angle <0-180>` | Fold or unfold a foldable device (form factor `foldable`: the iPhone Duo, Android foldables) to a preset or an exact hinge angle — exactly one. Reports posture, angle and lit screen. Errors on a device without a hinge. |
 | `rotate` | `[--degrees <90\|180\|270>]` | Rotate the device and report the new orientation. Phones/tablets and Android foldables toggle portrait/landscape (90 only); the iPhone Duo turns a quarter clockwise by default. Not on TV. |
+| `set-location` | `--lat <n> --lon <n>` | Set the device's simulated GPS position (decimal degrees; west and south are negative) for location-based flows. Phones, tablets and foldables; not on TV. |
 | `wait` | `[--ms <n>]` | Wait for a specified number of seconds before continuing (default: 2s). |
 | `find` | `<text>` `[--below <text>] [--above <text>] [--near <text>]` | Find an element by text with optional spatial constraints. |
 | `tap-focused` | `<ref>` | TV: move focus to an element and press SELECT in one step. |
@@ -279,7 +287,7 @@ Dev-loop lifecycle commands (not registry verbs, but needed for every run):
 | Command | Purpose |
 |---------|---------|
 | `dev --detach --json` | Start a device + Metro-tunnel session in the background, emitting `session_ready`/`warning`/`error` JSON events on stdout. Add `--model "<name>"` to pick an exact device model. |
-| `dev --build <id>` | Run that uploaded build instead of the app's newest debug build (combine with `--app`, `--platform`, `--model`, `--detach --json`). Only a debug build (kind `debug` in `list-builds`) is accepted; a release build or one with an embedded JS bundle is refused. Not on Roku. |
+| `dev --build <id>` | Run that uploaded build instead of the app's newest debug build (combine with `--app`, `--platform`, `--model`, `--detach --json`). Only a debug build (kind `debug` in `list-builds`) is accepted, including a debug build with its JS bundle embedded; a release build is refused (run it with `--standalone`). Not on Roku. |
 | `list-builds <app>` | List an app's uploaded builds, newest first: id, version (build number), platform, kind (`debug`/`release`/`unknown`), upload time, note. `--json` prints an array. |
 | `list-devices --models` | List the device models you can start (the names `--model` takes); foldables are marked `foldable`. |
 | `dev-status` | Check on the current project's detached dev session. |
@@ -304,11 +312,12 @@ steps the CLI does with plain shell commands:
 |----------|------|---------|
 | `upload_app` | `file` (required path), `name` | Upload a build (zipped iOS/tvOS simulator `.app`, Android/Android TV `.apk`, Roku channel `.zip`). The MCP equivalent of `vibeview upload-app`, so step 1 of the loop needs no shell. Returns the `app_id` to pass to `dev_start`. |
 | `list_apps` | `platform` | List the org's apps (app id, name, platform, bundle id). The MCP equivalent of `vibeview list-apps` — use it to find an app someone else uploaded. |
-| `dev_start` | `platform` (required: `ios`/`android`/`tvos`/`androidtv`/`roku`), `app`, `metro_port`, `model`, `build_id`, `standalone` | Start a session held open by the MCP server. The MCP equivalent of `vibeview dev --detach`; `model` picks an exact device model (e.g. `"iPhone Duo"`); `build_id` runs that build instead of the newest debug one (see `list_builds`). `standalone: true` runs any build as it is with no Metro — a release, CI or cloud build (without `build_id`: the newest release build). An app for another platform is refused before a device is taken. Returns `page_url` — relay it to the developer immediately, same as step 5 of the loop — and the device it got (model, OS, category; posture and lit screen on a foldable). |
+| `dev_start` | `platform` (required: `ios`/`android`/`tvos`/`androidtv`/`roku`), `app`, `metro_port`, `model`, `build_id`, `standalone` | Start a session held open by the MCP server. The MCP equivalent of `vibeview dev --detach`; `model` picks an exact device model (e.g. `"iPhone Duo"`); `build_id` runs that build instead of the newest debug one (see `list_builds`). `standalone: true` runs any build as it is with no Metro — a release, CI or cloud build (without `build_id`: the newest release build). An app for another platform is refused before a device is taken. Returns `page_url` — relay it to the developer immediately, same as step 5 of the loop — the device it got (model, OS, category; posture and lit screen on a foldable), and the build it installed (id, version, upload time) with the app's other debug builds. A red "React Native version mismatch" screen means that build was made with another React Native than the project: pick one made from this project with `build_id`. While every device is busy it waits in the queue, sending progress. |
 | `list_device_models` | `device_type` | List the device models you can start (model, OS, platform, category, `foldable` marker, and how many are free/busy). The MCP equivalent of `vibeview list-devices --models`. |
 | `list_builds` | `app` (required) | List an app's uploaded builds with their kind (`debug`/`release`/`unknown`). The MCP equivalent of `vibeview list-builds`. |
 | `dev_stop` | — | Stop the session `dev_start` started. The MCP equivalent of `vibeview dev-stop`. Says "no dev session was running" when there was none. |
 | `stop_session` | `session_id` (required) | Stop any session by id. The MCP equivalent of `vibeview stop <session-id>`. Says so when the session had already ended. |
+| `dev_reload` | — | Roku only: re-package, upload and restart the channel in the held session (or this project's `vibeview dev --detach` session). The MCP equivalent of `vibeview dev-reload`. |
 
 If the held session ends elsewhere (dashboard, idle timeout, failure), the
 next tool call answers "session … has ended (…) — call dev_start"; the
@@ -319,5 +328,6 @@ call.** Once it succeeds, any tool called without an explicit `session_id`
 targets that session instead of whatever `vibeview dev --detach` state exists
 in the project directory. Only one such session can be held at a time
 (`dev_start` fails if one is already running), and it stays live — billing
-streaming minutes — until `dev_stop` or the MCP connection ends. Always call
-`dev_stop` when you finish verifying.
+streaming minutes — until `dev_stop` or the MCP connection ends (the server
+stops it when the client quits or closes the connection; a killed server
+can't). Always call `dev_stop` when you finish verifying.