@houwert/conductor 0.27.2 → 0.29.0

package/dist/commands/run-flow.js

@@ -4,15 +4,58 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
+exports.aggregateRuns = aggregateRuns;
 exports.runFlow = runFlow;
 exports.HELP = `  run-flow <file> [--device <id>]     Run a Maestro YAML flow file
     --env KEY=VALUE                   Inject env var (repeatable; overrides flow env block)
-    --benchmark                       Print elapsed time for each command and total flow time`;
+    --benchmark                       Print elapsed time for each command and total flow time
+    --repeat <n>                      With --benchmark, run the flow n times and report p50/p90/σ
+    --json                            With --benchmark --repeat, emit the aggregate as JSON`;
 const path_1 = __importDefault(require("path"));
 const runner_js_1 = require("../runner.js");
 const flow_runner_js_1 = require("../drivers/flow-runner.js");
 const output_js_1 = require("../output.js");
-async function runFlow(file, opts = {}, sessionName = 'default', env = {}, benchmark = false) {
+const stats_js_1 = require("../stats.js");
+/**
+ * Aggregate per-run timings by command label. Keyed on label rather than
+ * position so a flow whose branches differ between runs still lines up.
+ */
+function aggregateRuns(runs) {
+    const byLabel = new Map();
+    for (const run of runs) {
+        for (const entry of run.entries) {
+            const slot = byLabel.get(entry.label) ?? { times: [], failures: 0 };
+            slot.times.push(entry.ms);
+            if (!entry.ok)
+                slot.failures++;
+            byLabel.set(entry.label, slot);
+        }
+    }
+    return {
+        runs: runs.length,
+        total: (0, stats_js_1.describe)(runs.map((r) => r.totalMs)),
+        commands: [...byLabel.entries()]
+            .map(([label, v]) => ({
+            label,
+            runs: v.times.length,
+            failures: v.failures,
+            ...(0, stats_js_1.describe)(v.times),
+        }))
+            .sort((a, b) => (b.p50Ms ?? 0) - (a.p50Ms ?? 0)),
+    };
+}
+function printAggregate(agg) {
+    console.log(`\nBenchmark over ${agg.runs} run(s)`);
+    console.log(`  total  p50 ${(0, stats_js_1.fmt)(agg.total.p50Ms)}  p90 ${(0, stats_js_1.fmt)(agg.total.p90Ms)}  ` +
+        `σ ${(0, stats_js_1.fmt)(agg.total.stddevMs)}  min ${(0, stats_js_1.fmt)(agg.total.minMs)}  max ${(0, stats_js_1.fmt)(agg.total.maxMs)}`);
+    console.log(`\n  ${'p50'.padStart(9)} ${'p90'.padStart(9)} ${'σ'.padStart(8)}  n  command`);
+    for (const c of agg.commands) {
+        console.log(`  ${(0, stats_js_1.fmt)(c.p50Ms).padStart(9)} ${(0, stats_js_1.fmt)(c.p90Ms).padStart(9)} ` +
+            `${(0, stats_js_1.fmt)(c.stddevMs).padStart(8)}  ${c.runs}  ${c.label}` +
+            (c.failures > 0 ? `  (${c.failures} failed)` : ''));
+    }
+}
+async function runFlow(file, opts = {}, sessionName = 'default', env = {}, benchmark = false, repeat = 1) {
     if (!file) {
         (0, output_js_1.printError)('run-flow requires <file>', opts);
         return 1;
@@ -21,8 +64,31 @@ async function runFlow(file, opts = {}, sessionName = 'default', env = {}, bench
     try {
         const driver = await (0, runner_js_1.getDriver)(sessionName);
         const flow = await (0, flow_runner_js_1.parseFlowFile)(resolvedFile, env);
-        await (0, flow_runner_js_1.executeFlow)(flow, driver, { cwd: path_1.default.dirname(resolvedFile), env, benchmark });
-        (0, output_js_1.printSuccess)(`run-flow "${file}" — done`, opts);
+        if (repeat <= 1) {
+            await (0, flow_runner_js_1.executeFlow)(flow, driver, { cwd: path_1.default.dirname(resolvedFile), env, benchmark });
+            (0, output_js_1.printSuccess)(`run-flow "${file}" — done`, opts);
+            return 0;
+        }
+        const runs = [];
+        for (let i = 0; i < repeat; i++) {
+            const entries = [];
+            console.log(`\n── run ${i + 1}/${repeat} ─────────────────────────────`);
+            const started = performance.now();
+            await (0, flow_runner_js_1.executeFlow)(flow, driver, {
+                cwd: path_1.default.dirname(resolvedFile),
+                env,
+                benchmark,
+                benchmarkSink: (e) => entries.push(e),
+            });
+            runs.push({ totalMs: (0, stats_js_1.round)(performance.now() - started), entries });
+        }
+        const agg = aggregateRuns(runs);
+        if (opts.json)
+            (0, output_js_1.printData)({ status: 'ok', benchmark: agg }, opts);
+        else {
+            printAggregate(agg);
+            (0, output_js_1.printSuccess)(`run-flow "${file}" — ${repeat} runs done`, opts);
+        }
         return 0;
     }
     catch (err) {

package/dist/drivers/bootstrap.js

@@ -246,6 +246,11 @@ function findPackageRoot() {
 }
 const DRIVERS_CACHE_ROOT = path_1.default.join(os_1.default.homedir(), '.conductor', 'drivers');
 const DRIVERS_DOWNLOAD_BASE = 'https://github.com/DouweBos/conductor/releases/download';
+// Must match the tag `.github/workflows/release.yml` pushes — the two are only
+// ever in sync because a release builds this file and cuts its tag from one
+// commit. Releases up to v0.27.2 predate the prefix and keep their `v<version>`
+// tags, which is fine — each published version only ever fetches its own tag.
+const DRIVERS_TAG_PREFIX = 'cli-v';
 const DRIVERS_LOCK_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes (download can be slow)
 const DRIVERS_LOCK_POLL_MS = 500;
 let _driversDirPromise = null;
@@ -331,7 +336,7 @@ async function ensureDriversCache(pkgRoot) {
         fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
         fs_1.default.mkdirSync(tmpDir, { recursive: true });
         const tarball = path_1.default.join(tmpDir, 'drivers.tar.gz');
-        const url = `${DRIVERS_DOWNLOAD_BASE}/v${version}/drivers.tar.gz`;
+        const url = `${DRIVERS_DOWNLOAD_BASE}/${DRIVERS_TAG_PREFIX}${version}/drivers.tar.gz`;
         (0, verbose_js_1.log)(`Downloading conductor drivers v${version} from ${url}...`);
         try {
             await downloadToFile(url, tarball);

package/dist/drivers/flow-runner.js

@@ -29,6 +29,23 @@ const utils_js_1 = require("../utils.js");
 function fmtMs(ms) {
     return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
 }
+// tvOS remote key names (uppercased, as flow pressKey normalises them) → IOSDriver
+// button values. Without this a flow's `pressKey: "Remote Dpad Up"` would fall
+// through to the software-keyboard path and silently do nothing — tvOS has no
+// keyboard. Mirrors TVOS_REMOTE_BUTTONS in commands/press-key.ts.
+const TVOS_FLOW_BUTTONS = {
+    'REMOTE DPAD UP': 'up',
+    'REMOTE DPAD DOWN': 'down',
+    'REMOTE DPAD LEFT': 'left',
+    'REMOTE DPAD RIGHT': 'right',
+    'REMOTE DPAD CENTER': 'select',
+    'REMOTE MENU': 'menu',
+    'REMOTE MEDIA PLAY PAUSE': 'playPause',
+    ENTER: 'select',
+    RETURN: 'select',
+    ESCAPE: 'menu',
+    BACK: 'menu',
+};
 // vega (Amazon Fire TV) remote key names → VegaDriver button values, for flow pressKey.
 const VEGA_FLOW_BUTTONS = {
     BACK: 'back',
@@ -375,6 +392,7 @@ async function executeFlow(flow, driver, opts = {}) {
         output: opts.output ?? {},
         depth: opts.depth ?? 0,
         benchmark: opts.benchmark,
+        benchmarkSink: opts.benchmarkSink,
     };
     const flowStart = opts.benchmark ? perf_hooks_1.performance.now() : 0;
     if (flow.onFlowStart?.length) {
@@ -498,9 +516,11 @@ async function executeCommand(cmd, driver, opts) {
     else {
         process.stdout.write(`${indent}→ ${label} ... `);
     }
-    const t0 = opts.benchmark ? perf_hooks_1.performance.now() : 0;
+    const timing = opts.benchmark || opts.benchmarkSink;
+    const t0 = timing ? perf_hooks_1.performance.now() : 0;
     try {
         await executeCommandBody(key, resolvedVal, driver, opts);
+        opts.benchmarkSink?.({ label, depth: opts.depth, ms: perf_hooks_1.performance.now() - t0, ok: true });
         const elapsed = opts.benchmark ? `  (${fmtMs(perf_hooks_1.performance.now() - t0)})` : '';
         if (!isCompound) {
             console.log(`ok${elapsed}`);
@@ -511,6 +531,7 @@ async function executeCommand(cmd, driver, opts) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
+        opts.benchmarkSink?.({ label, depth: opts.depth, ms: perf_hooks_1.performance.now() - t0, ok: false });
         const elapsed = opts.benchmark ? `  (${fmtMs(perf_hooks_1.performance.now() - t0)})` : '';
         if (optional) {
             // For compound commands the sub-command already printed its warning/failure
@@ -1055,13 +1076,20 @@ async function executeCommandBody(key, val, driver, opts) {
         case 'pressKey': {
             const keyName = val.toUpperCase();
             if (driver instanceof ios_js_1.IOSDriver) {
+                const tvosButton = driver.platform === 'tvos' ? TVOS_FLOW_BUTTONS[keyName] : undefined;
                 // Home and Lock are hardware buttons on iOS, not software keys
-                if (keyName === 'HOME') {
+                if (tvosButton) {
+                    await driver.pressButton(tvosButton);
+                }
+                else if (keyName === 'HOME') {
                     await driver.pressButton('home');
                 }
                 else if (keyName === 'LOCK' || keyName === 'POWER') {
                     await driver.pressButton('lock');
                 }
+                else if (driver.platform === 'tvos') {
+                    throw new Error(`pressKey: key "${val}" is not supported on tvOS`);
+                }
                 else {
                     await driver.pressKey(mapIosKey(keyName));
                 }
@@ -1249,6 +1277,7 @@ async function executeCommandBody(key, val, driver, opts) {
                     output: opts.output,
                     depth: childDepth,
                     benchmark: opts.benchmark,
+                    benchmarkSink: opts.benchmarkSink,
                 });
             }
             else {
@@ -1269,6 +1298,7 @@ async function executeCommandBody(key, val, driver, opts) {
                         output: opts.output,
                         depth: childDepth,
                         benchmark: opts.benchmark,
+                        benchmarkSink: opts.benchmarkSink,
                     });
                 }
             }

package/dist/drivers/metro-cdp.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MetroCdpClient = void 0;
 exports.selectDebuggerUrl = selectDebuggerUrl;
 exports.resolveDebuggerUrl = resolveDebuggerUrl;
+exports.resolveMetroPort = resolveMetroPort;
 exports.cdpCall = cdpCall;
 /**
  * One-shot CDP client to Metro's debugger endpoint.
@@ -62,14 +63,38 @@ function selectDebuggerUrl(targets, opts, displayName) {
  * Throws with a clear message if Metro is unreachable or no target matches.
  */
 async function resolveDebuggerUrl(opts) {
-    const port = opts.port ?? 8081;
+    const port = await resolveMetroPort(opts);
     const host = opts.host ?? 'localhost';
-    const targets = await (0, metro_js_1.fetchTargets)(port, host);
+    let targets;
+    try {
+        targets = await (0, metro_js_1.fetchTargets)(port, host);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Cannot reach Metro on ${host}:${port} — ${detail}.\n` +
+            `Pass --port <n> if Metro listens elsewhere (a project may set RCT_METRO_PORT); ` +
+            `\`conductor workspace info\` reports the port it can see.`);
+    }
     let displayName;
     if (opts.deviceId && opts.platform) {
         displayName = (await (0, metro_discovery_js_1.getDeviceDisplayName)(opts.platform, opts.deviceId)) ?? undefined;
     }
-    return selectDebuggerUrl(targets, opts, displayName);
+    return selectDebuggerUrl(targets, { ...opts, port }, displayName);
+}
+/**
+ * Metro's port for this device: the explicit --port, else whatever the device is
+ * actually connected to, else 8081. Auto-discovery matters because a project
+ * that sets RCT_METRO_PORT otherwise fails with an opaque connection error.
+ */
+async function resolveMetroPort(opts) {
+    if (opts.port !== undefined)
+        return opts.port;
+    if (opts.deviceId && opts.platform) {
+        const discovered = await (0, metro_discovery_js_1.discoverMetroPortForDevice)(opts.platform, opts.deviceId).catch(() => null);
+        if (discovered)
+            return discovered;
+    }
+    return 8081;
 }
 /**
  * Open a short-lived CDP socket, send a single method, return the result.

package/dist/index.js

@@ -42,6 +42,8 @@ const debug_js_1 = require("./commands/debug.js");
 const network_js_1 = require("./commands/network.js");
 const flow_record_js_1 = require("./commands/flow-record.js");
 const profile_js_1 = require("./commands/profile.js");
+const profile_frames_js_1 = require("./commands/profile-frames.js");
+const profile_js_js_1 = require("./commands/profile-js.js");
 const crashes_js_1 = require("./commands/crashes.js");
 const flow_recorder_js_1 = require("./drivers/flow-recorder.js");
 const foreground_app_js_1 = require("./commands/foreground-app.js");
@@ -223,6 +225,10 @@ async function main() {
             'force',
             'yes',
             'update',
+            'measure',
+            'report',
+            'timeline',
+            'baselines',
         ],
         string: [
             'device',
@@ -254,6 +260,9 @@ async function main() {
             'source',
             'level',
             'save',
+            'save-baseline',
+            'sequence',
+            'settle',
             'diff',
             'vs',
             'top',
@@ -655,6 +664,15 @@ async function main() {
             exitCode = await (0, press_key_js_1.pressKey)(key, opts, sessionName, {
                 longPress: argv['long-press'],
                 duration: durationArg !== undefined ? Number(durationArg) : undefined,
+                measure: argv['measure'],
+                repeat: argv['repeat'] !== undefined ? Number(argv['repeat']) : undefined,
+                timeoutMs: argv['timeout'] !== undefined ? Number(argv['timeout']) : undefined,
+                pollIntervalMs: argv['poll-interval'] !== undefined ? Number(argv['poll-interval']) : undefined,
+                settleMs: argv['settle'] !== undefined ? Number(argv['settle']) : undefined,
+                sequence: typeof argv['sequence'] === 'string'
+                    ? argv['sequence'].split(',')
+                    : undefined,
+                appId: argv['app'],
             });
             break;
         }
@@ -901,7 +919,7 @@ async function main() {
             const rawEnv = argv['env'];
             const envPairs = Array.isArray(rawEnv) ? rawEnv : rawEnv ? [rawEnv] : [];
             const flowEnv = Object.fromEntries(envPairs.map((e) => e.split('=', 2)));
-            exitCode = await (0, run_flow_js_1.runFlow)(file, opts, sessionName, flowEnv, argv['benchmark']);
+            exitCode = await (0, run_flow_js_1.runFlow)(file, opts, sessionName, flowEnv, argv['benchmark'], argv['repeat'] !== undefined ? Number(argv['repeat']) : 1);
             break;
         }
         case 'run-flow-inline': {
@@ -942,7 +960,8 @@ async function main() {
             const release = argv['release'];
             const releaseId = typeof argv['release'] === 'string' ? argv['release'] : rest[0];
             const action = acquire ? 'acquire' : release || releaseId ? 'release' : 'list';
-            exitCode = await (0, device_pool_js_1.devicePool)(action, releaseId, opts);
+            const owner = argv['owner'] ? Number(argv['owner']) : undefined;
+            exitCode = await (0, device_pool_js_1.devicePool)(action, releaseId, opts, argv['device'], owner);
             break;
         }
         case 'run-sequence': {
@@ -979,12 +998,15 @@ async function main() {
             const sub = (rest[0] ?? '').toLowerCase();
             const port = argv['port'] !== undefined ? Number(argv['port']) : undefined;
             const targetIndex = argv['target'] !== undefined ? Number(argv['target']) : undefined;
+            const top = argv['top'] !== undefined ? Number(argv['top']) : undefined;
             if (sub === 'cpu') {
                 const durationSec = argv['duration'] !== undefined ? Number(argv['duration']) : 10;
                 exitCode = await (0, profile_js_1.profileCpu)(opts, sessionName, {
                     durationSec,
                     out: argv['out'],
                     appId: rest[1],
+                    report: argv['report'],
+                    top,
                 });
             }
             else if (sub === 'memory') {
@@ -996,14 +1018,67 @@ async function main() {
                     appId: rest[1],
                 });
             }
+            else if (sub === 'frames') {
+                const sub2 = (rest[1] ?? '').toLowerCase();
+                if (sub2 === 'reset') {
+                    exitCode = await (0, profile_frames_js_1.profileFramesReset)(opts, sessionName, rest[2]);
+                }
+                else if (sub2 === 'report') {
+                    exitCode = await (0, profile_frames_js_1.profileFramesReport)(opts, sessionName, {
+                        appId: rest[2],
+                        trackSec: argv['track'] !== undefined ? Number(argv['track']) : undefined,
+                        intervalMs: argv['interval'] !== undefined ? Number(argv['interval']) : undefined,
+                        top,
+                        saveBaseline: argv['save-baseline'],
+                        diff: argv['diff'],
+                        listBaselines: argv['baselines'],
+                    });
+                }
+                else {
+                    console.error('Usage: conductor profile frames <reset|report> [<appId>]');
+                    exitCode = 1;
+                }
+            }
+            else if (sub === 'js') {
+                const sub2 = (rest[1] ?? '').toLowerCase();
+                const jsOpts = {
+                    port,
+                    targetIndex,
+                    out: argv['out'],
+                    top,
+                    durationSec: argv['duration'] !== undefined ? Number(argv['duration']) : undefined,
+                };
+                if (sub2 === 'record') {
+                    exitCode = await (0, profile_js_js_1.profileJsRecord)(opts, sessionName, jsOpts);
+                }
+                else if (sub2 === 'start') {
+                    exitCode = await (0, profile_js_js_1.profileJsStart)(opts, sessionName, jsOpts);
+                }
+                else if (sub2 === 'stop') {
+                    exitCode = await (0, profile_js_js_1.profileJsStop)(opts, sessionName, jsOpts);
+                }
+                else if (sub2 === '_hold') {
+                    exitCode = await (0, profile_js_js_1.profileJsHold)(sessionName, jsOpts);
+                }
+                else {
+                    console.error('Usage: conductor profile js <record|start|stop>');
+                    exitCode = 1;
+                }
+            }
             else if (sub === 'react') {
                 const sub2 = (rest[1] ?? '').toLowerCase();
-                const top = argv['top'] !== undefined ? Number(argv['top']) : 20;
+                const reactOpts = {
+                    port,
+                    targetIndex,
+                    maxCommits: argv['max-commits'] !== undefined ? Number(argv['max-commits']) : undefined,
+                    maxComponents: argv['max-components'] !== undefined ? Number(argv['max-components']) : undefined,
+                    timeline: argv['timeline'],
+                };
                 if (sub2 === 'start') {
-                    exitCode = await (0, profile_js_1.profileReactStart)(opts, sessionName, { port, targetIndex });
+                    exitCode = await (0, profile_js_1.profileReactStart)(opts, sessionName, reactOpts);
                 }
                 else if (sub2 === 'stop') {
-                    exitCode = await (0, profile_js_1.profileReactStop)(opts, sessionName, { port, targetIndex }, top);
+                    exitCode = await (0, profile_js_1.profileReactStop)(opts, sessionName, reactOpts, top ?? 20);
                 }
                 else {
                     console.error('Usage: conductor profile react <start|stop>');
@@ -1011,7 +1086,7 @@ async function main() {
                 }
             }
             else {
-                console.error('Usage: conductor profile <cpu|memory|react> [args]');
+                console.error('Usage: conductor profile <cpu|memory|frames|js|react> [args]');
                 exitCode = 1;
             }
             break;

package/dist/stats.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Percentile / dispersion helpers shared by the profiling commands.
+ *
+ * Percentiles use nearest-rank on a sorted copy so a p99 over a handful of
+ * samples still names a real observation rather than an interpolated one that
+ * never happened.
+ *
+ * With no samples every figure is `null`, never 0. A missing measurement that
+ * reads as `0ms` is a missing measurement that reads as a *perfect* one, and a
+ * consumer has to remember to check `count` to avoid believing it. `null`
+ * propagates through arithmetic and comparison loudly enough to notice.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_DISTRIBUTION = void 0;
+exports.hasSamples = hasSamples;
+exports.percentile = percentile;
+exports.round = round;
+exports.roundOrNull = roundOrNull;
+exports.describe = describe;
+exports.fmt = fmt;
+exports.EMPTY_DISTRIBUTION = {
+    count: 0,
+    minMs: null,
+    maxMs: null,
+    meanMs: null,
+    stddevMs: null,
+    p50Ms: null,
+    p90Ms: null,
+    p95Ms: null,
+    p99Ms: null,
+};
+function hasSamples(d) {
+    return d !== undefined && d.count > 0;
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return null;
+    const rank = Math.ceil((p / 100) * sorted.length);
+    return sorted[Math.min(sorted.length - 1, Math.max(0, rank - 1))];
+}
+function round(n, digits = 2) {
+    const f = 10 ** digits;
+    return Math.round(n * f) / f;
+}
+/** `round` that passes `null` through, for optional measurements. */
+function roundOrNull(n, digits = 2) {
+    return n === null ? null : round(n, digits);
+}
+function describe(values) {
+    if (values.length === 0)
+        return { ...exports.EMPTY_DISTRIBUTION };
+    const sorted = [...values].sort((a, b) => a - b);
+    const mean = sorted.reduce((a, b) => a + b, 0) / sorted.length;
+    const variance = sorted.reduce((acc, v) => acc + (v - mean) ** 2, 0) / sorted.length;
+    return {
+        count: sorted.length,
+        minMs: round(sorted[0]),
+        maxMs: round(sorted[sorted.length - 1]),
+        meanMs: round(mean),
+        stddevMs: round(Math.sqrt(variance)),
+        p50Ms: roundOrNull(percentile(sorted, 50)),
+        p90Ms: roundOrNull(percentile(sorted, 90)),
+        p95Ms: roundOrNull(percentile(sorted, 95)),
+        p99Ms: roundOrNull(percentile(sorted, 99)),
+    };
+}
+/** Format a possibly-absent measurement for text output. */
+function fmt(v, unit = 'ms') {
+    return v === null || v === undefined ? 'n/a' : `${v}${unit}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.27.2",
+  "version": "0.29.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {

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

@@ -14,7 +14,7 @@ existing Maestro flows run unchanged. Use flows for repeatable journeys; use
 
 | Command | Purpose |
 |---|---|
-| `conductor run-flow <file> [--env K=V] [--benchmark]` | Run a Maestro YAML flow file |
+| `conductor run-flow <file> [--env K=V] [--benchmark] [--repeat <n>]` | Run a Maestro YAML flow file. `--benchmark --repeat <n>` reports per-command p50/p90/stddev across runs |
 | `conductor run-flow-inline '<yaml>' [--benchmark]` | Run inline YAML from the command line |
 | `conductor run-sequence [--file path.json]` | Run a JSON sequence of conductor commands serially; reads stdin if no `--file` |
 | `conductor run-parallel --flows-dir <path>` | Shard a directory of flows across all booted devices |

package/skills/conductor-device-interact/SKILL.md

@@ -41,7 +41,7 @@ conductor assert-visible "Dashboard"
 | `conductor copy-text-from <element>` | Print an element's text (and copy to the iOS clipboard) |
 | `conductor input-text <text>` | Type into the focused field |
 | `conductor erase-text [n]` | Erase n characters (default 50) |
-| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega. `--long-press` / `--duration <seconds>` holds it |
+| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega. `--long-press` / `--duration <seconds>` holds it; `--measure` times the response (see `conductor-profiler`) |
 | `conductor hide-keyboard` | Dismiss the on-screen keyboard |
 | `conductor back` | Press back |
 | `conductor scroll [--direction down\|up\|left\|right]` | Scroll |

package/skills/conductor-device-setup/SKILL.md

@@ -14,7 +14,7 @@ nothing is booted yet.
 conductor workspace info     # detected project type, bundle IDs, devices, Metro port — best first call
 conductor list-devices       # booted + available devices
 conductor foreground-app     # bundle id of the app currently in front
-conductor list-apps          # installed app ids / package names
+conductor list-apps          # installed app ids / package names (--json adds appNames on iOS/tvOS)
 ```
 
 ## Devices
@@ -100,11 +100,28 @@ Parallel agents each get their own `--session <name>` so they don't collide.
 | `conductor daemon-status`              | Show daemon status                                                                                   |
 | `conductor daemon-stop [--all]`        | Stop this session's daemon (`--all` = every session)                                                 |
 | `conductor device-pool --list`         | List devices + pool status                                                                           |
-| `conductor device-pool --acquire`      | Claim a free device (prints id)                                                                      |
+| `conductor device-pool --acquire`      | Claim a free device (prints id); `--device <id>` claims that one, `--owner <pid>` holds the claim     |
 | `conductor device-pool --release <id>` | Release a device back to the pool                                                                    |
 
 Don't leave a daemon running when you're done — `daemon-stop` it.
 
+### Reserving a device
+
+Claim a device before driving it when other agents share the machine, so nobody
+taps through your test half-way. A claim belongs to a **process**: conductor
+frees any claim whose owner has exited, and the CLI exits immediately, so
+`--acquire` on its own reserves nothing. Pass the PID that should hold it:
+
+```bash
+conductor device-pool --acquire --device <id> --owner $$ --json   # claim it
+conductor device-pool --list --json                               # who holds what
+conductor device-pool --release <id>                              # give it back
+```
+
+Acquiring a device someone else holds fails rather than stealing it. Always
+release when you're done — a crash releases it for you, an abandoned shell
+doesn't.
+
 ## Tips
 
 - `--device <id>` / `--device-name <name>` targets a device; `--platform` scopes by platform.