@houwert/conductor 0.27.1 → 0.28.0

package/README.md

@@ -110,10 +110,25 @@ conductor/
 ├── packages/
 │   ├── cli/              # TypeScript CLI (@houwert/conductor)
 │   ├── android-driver/   # Kotlin/Gradle instrumentation driver
-│   └── ios-driver/       # Swift/Xcode XCTest driver
+│   ├── ios-driver/       # Swift/Xcode XCTest driver
+│   └── studio-ui/        # Design system for Conductor Studio
+├── apps/
+│   └── studio/           # Conductor Studio — the desktop app
 └── Makefile
 ```
 
+## 🖥️ Conductor Studio
+
+There's also a desktop app: **Conductor Studio**, a Maestro test workbench built
+on this CLI — flow editor with autocomplete, live device stream with element
+picking, an agentic test writer, and test case management. It lives in
+[`apps/studio`](apps/studio); see its
+[README](apps/studio/README.md) for what it does and how to run it.
+
+```bash
+pnpm dev:studio
+```
+
 ## 🛠️ Development
 
 ```bash

package/dist/commands/cases.js

@@ -0,0 +1,260 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.storeDir = storeDir;
+exports.loadCases = loadCases;
+exports.casesList = casesList;
+exports.parseJunit = parseJunit;
+exports.casesReport = casesReport;
+exports.casesResult = casesResult;
+exports.HELP = `  cases list                          List the repo's test cases and their coverage
+  cases report --junit <file>         File a JUnit report as test-case results
+  cases result <id> --verdict <v>     Record one case result (passed/failed/blocked/skipped)`;
+const promises_1 = require("node:fs/promises");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const output_js_1 = require("../output.js");
+/**
+ * Test cases from the CLI, so CI can file results without Studio running.
+ *
+ * Cases and their results live under `~/.conductor/studio/cases/<project>/`,
+ * outside the repo under test — testing a project never adds files to it. The
+ * project is identified by its path, the same way Studio scopes its own store,
+ * so both see the same cases for the same checkout.
+ */
+const RESULTS = 'results.jsonl';
+/** Legacy in-repo location, still read so an older checkout keeps working. */
+const IN_REPO_CASES = 'test-cases';
+function studioRoot() {
+    // __CONDUCTOR_STUDIO_DIR keeps tests (and CI sandboxes) out of the real home.
+    return process.env.__CONDUCTOR_STUDIO_DIR ?? node_path_1.default.join((0, node_os_1.homedir)(), '.conductor', 'studio');
+}
+function slug(text) {
+    return (text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 48) || 'project');
+}
+function hash(text) {
+    let h = 0;
+    for (let i = 0; i < text.length; i++)
+        h = (h * 31 + text.charCodeAt(i)) | 0;
+    return Math.abs(h).toString(36);
+}
+/** `<basename>-<hash of path>`, matching Studio's own project scoping. */
+function storeDir(root) {
+    const resolved = node_path_1.default.resolve(root);
+    return node_path_1.default.join(studioRoot(), 'cases', `${slug(node_path_1.default.basename(resolved))}-${hash(resolved)}`);
+}
+/** Where cases are read from: the store, falling back to a legacy in-repo dir. */
+function casesDir(root) {
+    const store = storeDir(root);
+    if ((0, node_fs_1.existsSync)(store))
+        return store;
+    const legacy = node_path_1.default.join(root, IN_REPO_CASES);
+    return (0, node_fs_1.existsSync)(legacy) ? legacy : store;
+}
+/** Minimal YAML reader for the case fields we need — no dependency for one shape. */
+function readCase(text) {
+    const lines = text.split(/\r?\n/);
+    const scalar = (key) => {
+        const hit = lines.find((l) => l.startsWith(`${key}:`));
+        return hit
+            ?.slice(key.length + 1)
+            .trim()
+            .replace(/^['"]|['"]$/g, '');
+    };
+    const id = scalar('id');
+    const title = scalar('title');
+    if (!id || !title)
+        return null;
+    // `flows:` is a nested block: read indented `column: path` until the indent ends.
+    const flows = {};
+    const start = lines.findIndex((l) => /^flows:\s*$/.test(l));
+    if (start >= 0) {
+        for (const line of lines.slice(start + 1)) {
+            if (!line.trim())
+                continue;
+            if (!/^\s/.test(line))
+                break;
+            const entry = /^\s+([\w-]+):\s*(.+)$/.exec(line);
+            if (entry)
+                flows[entry[1]] = entry[2].trim().replace(/^['"]|['"]$/g, '');
+        }
+    }
+    return {
+        id,
+        title,
+        flow: scalar('flow'),
+        flows: Object.keys(flows).length ? flows : undefined,
+    };
+}
+async function loadCases(root) {
+    const dir = casesDir(root);
+    if (!(0, node_fs_1.existsSync)(dir))
+        return [];
+    const cases = [];
+    for (const file of (await (0, promises_1.readdir)(dir)).filter((f) => /\.ya?ml$/i.test(f))) {
+        const parsed = readCase(await (0, promises_1.readFile)(node_path_1.default.join(dir, file), 'utf8'));
+        if (parsed)
+            cases.push(parsed);
+    }
+    return cases.sort((a, b) => a.id.localeCompare(b.id));
+}
+function flowsOf(c) {
+    const entries = Object.entries(c.flows ?? {}).map(([column, flow]) => ({ column, flow }));
+    if (c.flow)
+        entries.push({ flow: c.flow });
+    return entries;
+}
+let seq = 0;
+async function append(root, results) {
+    const file = node_path_1.default.join(storeDir(root), RESULTS);
+    await (0, promises_1.mkdir)(node_path_1.default.dirname(file), { recursive: true });
+    await (0, promises_1.appendFile)(file, results.map((r) => JSON.stringify(r)).join('\n') + '\n', 'utf8');
+}
+function result(fields) {
+    seq += 1;
+    return { id: `res-${Date.now()}-${seq}`, at: Date.now(), ...fields };
+}
+async function casesList(root, opts = {}) {
+    const cases = await loadCases(root);
+    if (!cases.length) {
+        (0, output_js_1.printError)(`No test cases found under ${casesDir(root)}.`, opts);
+        return 1;
+    }
+    if (opts.json) {
+        (0, output_js_1.printData)({
+            status: 'ok',
+            total: cases.length,
+            automated: cases.filter((c) => flowsOf(c).length).length,
+            cases: cases.map((c) => ({ id: c.id, title: c.title, flows: flowsOf(c) })),
+        }, opts);
+    }
+    else {
+        console.log(`${cases.length} cases, ${cases.filter((c) => flowsOf(c).length).length} with a flow`);
+        for (const c of cases) {
+            console.log(`  ${c.id.padEnd(10)} ${c.title}${flowsOf(c).length ? '' : '   (no flow)'}`);
+        }
+    }
+    return 0;
+}
+/** `<testcase name="…" classname="…">` plus its failure/skipped child, if any. */
+function parseJunit(xml) {
+    const out = [];
+    const re = /<testcase\b([^>]*?)(\/>|>([\s\S]*?)<\/testcase>)/g;
+    let match;
+    while ((match = re.exec(xml))) {
+        const attrs = match[1];
+        const body = match[3] ?? '';
+        const name = /\bname="([^"]*)"/.exec(attrs)?.[1] ?? '';
+        const classname = /\bclassname="([^"]*)"/.exec(attrs)?.[1] ?? '';
+        out.push({
+            name: [classname, name].filter(Boolean).join(' '),
+            failed: /<(failure|error)\b/.test(body),
+            skipped: /<skipped\b/.test(body),
+        });
+    }
+    return out;
+}
+/** Whole-word id match, so DT-9 doesn't claim a test named for DT-97. */
+function mentionsId(entry, id) {
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(^|[^A-Za-z0-9])${escaped}([^A-Za-z0-9]|$)`, 'i').test(entry);
+}
+/** A report entry belongs to a flow when it names the file or its basename. */
+function matchesFlow(entry, flow) {
+    const name = entry.toLowerCase();
+    const base = (flow.split('/').pop() ?? flow).toLowerCase();
+    return (name.includes(flow.toLowerCase()) ||
+        name.includes(base) ||
+        name.includes(base.replace(/\.[^.]+$/, '')));
+}
+async function casesReport(root, junitPath, opts = {}) {
+    if (!junitPath) {
+        (0, output_js_1.printError)('Usage: conductor cases report --junit <file.xml>', opts);
+        return 1;
+    }
+    if (!(0, node_fs_1.existsSync)(junitPath)) {
+        (0, output_js_1.printError)(`No such JUnit file: ${junitPath}`, opts);
+        return 1;
+    }
+    const entries = parseJunit(await (0, promises_1.readFile)(junitPath, 'utf8'));
+    const cases = await loadCases(root);
+    const records = [];
+    const unmatched = [];
+    for (const entry of entries) {
+        // Prefer the flow: it says which platform column ran. An id in the test
+        // name only identifies the case, so it files one case-level result.
+        const byFlow = [];
+        for (const c of cases) {
+            for (const { column, flow } of flowsOf(c)) {
+                if (matchesFlow(entry.name, flow))
+                    byFlow.push({ c, column, flow });
+            }
+        }
+        const targets = byFlow.length
+            ? byFlow
+            : cases
+                .filter((c) => mentionsId(entry.name, c.id))
+                .map((c) => ({ c, column: undefined, flow: undefined }));
+        if (!targets.length) {
+            unmatched.push(entry.name);
+            continue;
+        }
+        for (const target of targets) {
+            records.push(result({
+                caseId: target.c.id,
+                column: target.column,
+                flow: target.flow,
+                verdict: entry.skipped ? 'skipped' : entry.failed ? 'failed' : 'passed',
+                source: 'ci',
+                note: entry.name,
+                build: opts.build,
+                environment: opts.environment,
+            }));
+        }
+    }
+    if (records.length)
+        await append(root, records);
+    if (opts.json) {
+        (0, output_js_1.printData)({ status: 'ok', reported: records.length, tests: entries.length, unmatched }, opts);
+    }
+    else {
+        console.log(`Filed ${records.length} results from ${entries.length} tests` +
+            (unmatched.length ? `; ${unmatched.length} matched no case` : ''));
+    }
+    return 0;
+}
+async function casesResult(root, caseId, verdict, opts = {}) {
+    if (!caseId || !verdict) {
+        (0, output_js_1.printError)('Usage: conductor cases result <case-id> --verdict passed|failed|blocked|skipped', opts);
+        return 1;
+    }
+    const known = await loadCases(root);
+    if (known.length && !known.some((c) => c.id === caseId)) {
+        (0, output_js_1.printError)(`No case "${caseId}" under ${casesDir(root)}.`, opts);
+        return 1;
+    }
+    await append(root, [
+        result({
+            caseId,
+            verdict,
+            column: opts.column,
+            source: 'ci',
+            note: opts.note,
+            build: opts.build,
+            environment: opts.environment,
+        }),
+    ]);
+    if (opts.json)
+        (0, output_js_1.printData)({ status: 'ok', caseId, verdict }, opts);
+    else
+        console.log(`Recorded ${caseId}: ${verdict}`);
+    return 0;
+}

package/dist/commands/device-pool.js

@@ -7,6 +7,10 @@ exports._testDeviceOverride = exports.HELP = void 0;
 exports.devicePool = devicePool;
 exports.HELP = `  device-pool --list                  List all devices and pool status
   device-pool --acquire               Claim a free device (prints device ID)
+    --device <id>                     Claim this specific device instead of any free one
+    --owner <pid>                     Hold the claim for this process (default: this CLI's
+                                      own PID, which exits immediately — pass a long-lived
+                                      PID to keep the device reserved)
   device-pool --release <id>          Release a device back to the pool`;
 /**
  * device-pool: Manage a pool of available devices for concurrent multi-agent use.
@@ -115,7 +119,11 @@ function pruneStaleAcquisitions(state) {
     }
 }
 // ── Commands ──────────────────────────────────────────────────────────────────
-async function devicePool(action, releaseId, opts = {}) {
+async function devicePool(action, releaseId, opts = {}, 
+/** Claim this device specifically, rather than any free one. */
+wantedDevice, 
+/** Process that owns the claim; it is released when that process goes away. */
+ownerPid) {
     if (action === 'list') {
         const allDevices = await discoverAllDevices();
         const pool = await withLock(() => {
@@ -152,6 +160,9 @@ async function devicePool(action, releaseId, opts = {}) {
             (0, output_js_1.printError)('No devices available', opts);
             return 1;
         }
+        // A claim lives as long as its owner process. This CLI exits immediately, so
+        // a caller that wants to keep a device reserved passes its own long-lived PID.
+        const owner = String(ownerPid ?? process.pid);
         const result = await withLock(() => {
             const state = readPool();
             pruneStaleAcquisitions(state);
@@ -161,17 +172,25 @@ async function devicePool(action, releaseId, opts = {}) {
                     state.devices.push({ deviceId: id });
                 }
             }
-            // Find a free device
-            const free = state.devices.find((e) => allDevices.includes(e.deviceId) && !e.acquiredBy);
+            // Asking for a device by name is idempotent: re-claiming one you already
+            // hold succeeds, because an owner running two things against one device
+            // isn't a conflict. Asking for *any* free device is the opposite request
+            // — "give me one nobody is on" — so a device you already hold doesn't
+            // count as free, or two parallel runs would land on the same screen.
+            const free = wantedDevice
+                ? state.devices.find((e) => e.deviceId === wantedDevice && (!e.acquiredBy || e.acquiredBy === owner))
+                : state.devices.find((e) => allDevices.includes(e.deviceId) && !e.acquiredBy);
             if (!free)
                 return null;
-            free.acquiredBy = String(process.pid);
+            free.acquiredBy = owner;
             free.acquiredAt = Date.now();
             writePool(state);
             return free.deviceId;
         });
         if (!result) {
-            (0, output_js_1.printError)('No free devices available in pool', opts);
+            (0, output_js_1.printError)(wantedDevice
+                ? `Device ${wantedDevice} is already in use by another agent`
+                : 'No free devices available in pool', opts);
             return 1;
         }
         if (opts.json) {

package/dist/commands/list-apps.js

@@ -23,6 +23,8 @@ async function listApps(opts = {}, sessionName = 'default') {
     }
     const platform = await (0, bootstrap_js_1.detectPlatform)(deviceId);
     let appIds;
+    // Display names, where the platform gives them up cheaply (iOS/tvOS only).
+    const appNames = {};
     if (platform === 'web') {
         (0, output_js_1.printError)('list-apps is not supported on web. Use foreground-app to get the current URL.', opts);
         return 1;
@@ -43,6 +45,11 @@ async function listApps(opts = {}, sessionName = 'default') {
         try {
             const parsed = JSON.parse(result.stdout);
             appIds = Object.keys(parsed).sort();
+            for (const id of appIds) {
+                const name = parsed[id]?.CFBundleDisplayName ?? parsed[id]?.CFBundleName;
+                if (typeof name === 'string' && name)
+                    appNames[id] = name;
+            }
         }
         catch {
             (0, output_js_1.printError)('Failed to parse app list from simctl', opts);
@@ -62,7 +69,7 @@ async function listApps(opts = {}, sessionName = 'default') {
             .sort();
     }
     if (opts.json) {
-        (0, output_js_1.printData)({ status: 'ok', apps: appIds }, opts);
+        (0, output_js_1.printData)({ status: 'ok', apps: appIds, ...(Object.keys(appNames).length ? { appNames } : {}) }, opts);
     }
     else {
         for (const id of appIds)

package/dist/commands/list-devices.js

@@ -21,8 +21,25 @@ const cdp_discovery_js_1 = require("../drivers/cdp-discovery.js");
 // Module-scoped because the discover function returns Device[]; bolting an
 // extra return field onto the public type would ripple beyond this fix.
 let listAvdsError;
+/**
+ * Android TV identifies itself through `ro.build.characteristics` (or the
+ * leanback feature). One cheap getprop per device beats guessing from a model
+ * name like `sdk_google_atv_x86` or `AFTKA`.
+ */
+async function annotateAndroidFormFactors(devices, ids) {
+    await Promise.all(ids.map(async (id) => {
+        const device = devices.find((d) => d.id === id);
+        if (!device)
+            return;
+        const res = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', id, 'shell', 'getprop', 'ro.build.characteristics'], { env: (0, sdk_js_1.androidSpawnEnv)() });
+        if (!res.success)
+            return;
+        device.formFactor = /\btv\b/i.test(res.stdout) ? 'tv' : 'handset';
+    }));
+}
 async function discoverBootedDevices() {
     const devices = [];
+    const androidIds = [];
     // Try adb devices (Android)
     const adb = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['devices', '-l'], {
         env: (0, sdk_js_1.androidSpawnEnv)(),
@@ -40,9 +57,11 @@ async function discoverBootedDevices() {
                 const modelMatch = trimmed.match(/model:(\S+)/);
                 const name = modelMatch ? modelMatch[1].replace(/_/g, ' ') : id;
                 devices.push({ id, name, platform: 'android', status });
+                androidIds.push(id);
             }
         }
     }
+    await annotateAndroidFormFactors(devices, androidIds);
     // Try xcrun simctl list (iOS simulators)
     const xcrun = await (0, runner_js_1.spawnCommand)('xcrun', ['simctl', 'list', 'devices', 'booted', '--json']);
     if (xcrun.success) {
@@ -143,7 +162,17 @@ async function discoverAvailableDevices() {
         for (const line of emu.stdout.split('\n')) {
             const name = line.trim();
             if (name) {
-                devices.push({ id: name, name, platform: 'android', status: 'available' });
+                // A shut-down AVD can't be probed, so fall back to its name: the AVD
+                // wizard calls TV images "Television"/"Android TV" or `_atv_`.
+                devices.push({
+                    id: name,
+                    name,
+                    platform: 'android',
+                    status: 'available',
+                    formFactor: /(^|[_\s-])(tv|television|atv|leanback)([_\s-]|$)/i.test(name)
+                        ? 'tv'
+                        : 'handset',
+                });
             }
         }
     }

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',
@@ -1055,13 +1072,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));
                 }

package/dist/index.js

@@ -61,6 +61,7 @@ const start_device_js_1 = require("./commands/start-device.js");
 const stop_device_js_1 = require("./commands/stop-device.js");
 const delete_device_js_1 = require("./commands/delete-device.js");
 const logs_js_1 = require("./commands/logs.js");
+const cases_js_1 = require("./commands/cases.js");
 const memory_js_1 = require("./commands/memory.js");
 const metro_js_1 = require("./commands/metro.js");
 const clipboard_js_1 = require("./commands/clipboard.js");
@@ -88,6 +89,7 @@ const COMMAND_HELP = {
     'list-devices': list_devices_js_1.HELP,
     'foreground-app': foreground_app_js_1.HELP,
     'list-apps': list_apps_js_1.HELP,
+    cases: cases_js_1.HELP,
     'copy-app': copy_app_js_1.HELP,
     'download-app': download_app_js_1.HELP,
     'install-app': install_app_js_1.HELP,
@@ -292,6 +294,13 @@ async function main() {
             'speed',
             'threshold',
             'reference',
+            'project',
+            'junit',
+            'verdict',
+            'note',
+            'column',
+            'build',
+            'environment',
         ],
         alias: { h: 'help', v: 'verbose', V: 'version', o: 'output', y: 'yes' },
     });
@@ -869,6 +878,35 @@ async function main() {
                 interval: argv['interval'] !== undefined ? Number(argv['interval']) : undefined,
             });
             break;
+        case 'cases': {
+            // Repo-scoped, not device-scoped: cases and their results are files.
+            const root = argv['project'] ?? process.cwd();
+            const sub = rest[0] ?? 'list';
+            if (sub === 'list') {
+                exitCode = await (0, cases_js_1.casesList)(root, opts);
+            }
+            else if (sub === 'report') {
+                exitCode = await (0, cases_js_1.casesReport)(root, argv['junit'] ?? '', {
+                    ...opts,
+                    build: argv['build'],
+                    environment: argv['environment'],
+                });
+            }
+            else if (sub === 'result') {
+                exitCode = await (0, cases_js_1.casesResult)(root, rest[1] ?? '', argv['verdict'] ?? 'passed', {
+                    ...opts,
+                    note: argv['note'],
+                    column: argv['column'],
+                    build: argv['build'],
+                    environment: argv['environment'],
+                });
+            }
+            else {
+                console.error(`Unknown cases subcommand "${sub}". Use list, report or result.`);
+                exitCode = 1;
+            }
+            break;
+        }
         case 'logs':
             exitCode = await (0, logs_js_1.logs)(opts, sessionName, {
                 source: argv['source'],
@@ -942,7 +980,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': {

package/package.json

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

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
@@ -74,7 +74,7 @@ screen recording, clipboard, `clear-state`/`uninstall-app`.
 | Command                                               | Purpose                                                                |
 | ----------------------------------------------------- | ---------------------------------------------------------------------- |
 | `conductor install-app <path>`                        | Install .app / .ipa / .apk                                             |
-| `conductor launch-app <appId>`                        | Launch app (saved to session); `--no-stop-app`, `--argument key=value`, `--inject` |
+| `conductor launch-app <appId>`                        | Launch app (saved to session); `--no-stop-app`, `--argument key=value`, `--inject` (enables the `native-*` in-process instrument — see `conductor-native`) |
 | `conductor stop-app [<appId>]`                        | Stop app                                                               |
 | `conductor uninstall-app <appId>`                     | Uninstall app                                                          |
 | `conductor copy-app <bundleId> --from <id> --to <id>` | Copy an installed app between iOS simulators                           |
@@ -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.

package/skills/conductor-inspect/SKILL.md

@@ -29,48 +29,13 @@ conductor capture-ui --output /tmp/screen.json
 conductor tap-on @e5
 ```
 
-## Native in-process inspection (iOS/tvOS simulator)
+## Native internals (colors, fonts, layers, live-edit)
 
 The commands above observe the app **externally** (accessibility snapshots), so
-they can't see real component colors, fonts, or the view-controller stack. When
-you need that native detail, launch the app with an injected in-process library
-and use the `native-*` commands. Requires `launch-app <appId> --inject` first
-(iOS/tvOS simulator only).
-
-| Command | Purpose |
-|---|---|
-| `conductor native-ping` | Verify the injected in-process control library is alive |
-| `conductor native-inspect` | Real UIView/CALayer tree: resolved colors (`#RRGGBBAA`), fonts, text (incl. React Native Fabric), corner radius, borders, shadows, gradients, and each node's `absFrame` |
-| `conductor native-nav` | Navigation state: `UINavigationController` stacks, tab selection, presented controllers, titles |
-| `conductor native-screenshot --output <p.png>` | In-process PNG of the key window |
-| `conductor native-image <x,y,w,h> --output <p.png>` | Extract a component as a PNG — pass a node's `absFrame` from `native-inspect` |
-| `conductor native-snapshot <id> --output <p.png>` | Isolated PNG of one view's own content (transparent) — per-layer texture for a 3D explosion; `--with-subviews` composites the subtree |
-| `conductor native-console [--since <n>]` / `native-network [--since <n>]` | App stdout/stderr + captured HTTP; poll with the returned `cursor` |
-| `conductor native-heap --pattern <s> \| --class <name> \| --read <addr> [--key <keyPath>]` | Live-object browser (find classes/instances, read a property off an address) |
-| `conductor native-appearance <light\|dark\|system> \| --direction <ltr\|rtl> \| --anim-speed <n>` | Force appearance / RTL / freeze animations app-wide |
-| `conductor native-eval '<swift>'` | Compile & run arbitrary Swift inside the app (full UIKit / ObjC-runtime access); `--mode full` for a whole function body. e.g. `native-eval 'UIScreen.main.bounds'` |
-| `conductor native-raw <path>` | Escape hatch — GET any in-process endpoint (e.g. `'/get?id=..&keyPath=layer.cornerRadius'`, `'/class?id=..'`, `'/responders?id=..'`, `'/swiftui'`, `'/defaults'`, `'/focus'`, `'/snapshots?scale=0.5'`). Full list in `packages/ios-inproc/README.md`. |
-| `conductor native-view <id>` | Full property detail for one view (class chain, transform, layer, gestures, text/font) |
-| `conductor native-set <id> <key> <value>` | **Live-edit** a property: alpha, hidden, backgroundColor, tintColor, cornerRadius, borderWidth, borderColor, frame, text, textColor. `text`/`textColor` work on RN Fabric text views too |
-| `conductor native-props <id>` | React Native Fabric props: typed `ViewProps` + the raw JS prop bag (Fabric host views only) |
-
-> **Editing RN Fabric text/props:** the native plane can't set text on `RCTParagraphComponentView` (no native setter) and `native-props` returns `rawProps: null` on Fabric. Edit through React instead with `conductor native-rn-set --react-tag <n> --path children --value '"…"'` (and read raw JSX props with `native-rn-props --react-tag <n>`). `reactTag` comes from this tree's `rn.reactTag`. See the conductor-metro-debugger skill. Dev builds only.
-| `conductor native-constraints <id>` | Auto Layout constraints affecting a view + ambiguity |
-| `conductor native-hittest <x,y>` | Topmost view at a point + ancestor chain (select-by-point) |
-| `conductor native-highlight <id>` | Flash a highlight over the view on the device |
-| `conductor native-find [--class <name>] [--text <s>]` | Search views by class and/or text |
-
-Every `native-inspect` node has a stable `id` (for this launch). The Reveal-style loop:
-inspect → pick an `id` → `native-view` for detail → `native-set` to edit live → see it
-on the device. IDs are pointer-based and reset each launch, so re-inspect after relaunch.
-
-```bash
-conductor launch-app com.example.app --inject
-conductor native-inspect                              # tree with ids, colors, fonts, absFrame
-conductor native-view 0x10280d0c0                     # full detail for a view
-conductor native-set 0x10280d0c0 backgroundColor '#FF3B30FF'   # live-edit, visible on device
-conductor native-image 816,286,288,288 --output /tmp/avatar.png
-```
+they can't see real component colors, fonts, or the view-controller stack. For
+that native detail — or to live-edit a running app's view properties, force
+appearance/RTL, or run Swift in-process — use the **`conductor-native`** skill
+(`launch-app --inject` + the `native-*` commands; iOS/tvOS simulator, dev builds).
 
 ## Assertions
 

package/skills/conductor-metro-debugger/SKILL.md

@@ -21,7 +21,8 @@ Playwright web.
 | `conductor native-rn-set --react-tag <n> --path <dot.path> --value <json>` | Live-edit an RN component's props via React DevTools `overrideProps` (text via `--path children`, color via `--path style.color`). Dev builds only |
 | `conductor native-rn-props --react-tag <n>` | Raw JSX props (`memoizedProps`) of an RN fiber by reactTag — the JS-side truth for Fabric where native `/props` `rawProps` is null |
 
-`--react-tag` comes from `native-inspect`'s `rn.reactTag`. `--value` is JSON (a bare
+`--react-tag` comes from `native-inspect`'s `rn.reactTag` (see `conductor-native`
+for the native-plane instrument). `--value` is JSON (a bare
 string works for text). `--path` is a dot path into props: `children`, `style.color`,
 `style.fontSize`, `accessibilityLabel`. `style.color` works whether the component's
 `style` is an object or a composed array. These drive React itself over Metro CDP, so

package/skills/conductor-native/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: conductor-native
+description: Inspect and live-edit a running app's native internals with the conductor CLI's in-process instrument (iOS/tvOS simulator, requires launch-app --inject). Use when you need real native view details the accessibility tree can't show — resolved colors/fonts/layers, the UIViewController/navigation stack, Auto Layout constraints, live-object heap — or to tweak the running app in place: set a view's properties (color, text, frame), force dark/RTL/animation state, or run arbitrary Swift inside the process.
+---
+
+# Conductor — native in-process inspection & live editing
+
+The external commands in `conductor-inspect` observe the app through the
+**accessibility tree**, so they can't see real component colors, fonts, layers,
+or the view-controller stack. When you need that native detail — or want to
+tweak the running app in place — launch with an injected in-process library and
+use the `native-*` commands.
+
+Requires `launch-app <appId> --inject` first. **iOS/tvOS simulator, dev builds
+only.** IDs are pointer-based and reset each launch, so re-inspect after relaunch.
+
+## Inspect the native plane
+
+| Command | Purpose |
+|---|---|
+| `conductor native-ping` | Verify the injected in-process control library is alive |
+| `conductor native-inspect` | Real UIView/CALayer tree: resolved colors (`#RRGGBBAA`), fonts, text (incl. React Native Fabric), corner radius, borders, shadows, gradients, and each node's `absFrame` |
+| `conductor native-nav` | Navigation state: `UINavigationController` stacks, tab selection, presented controllers, titles |
+| `conductor native-view <id>` | Full property detail for one view (class chain, transform, layer, gestures, text/font) |
+| `conductor native-props <id>` | React Native Fabric props: typed `ViewProps` + the raw JS prop bag (Fabric host views only) |
+| `conductor native-constraints <id>` | Auto Layout constraints affecting a view + ambiguity |
+| `conductor native-hittest <x,y>` | Topmost view at a point + ancestor chain (select-by-point) |
+| `conductor native-find [--class <name>] [--text <s>]` | Search views by class and/or text |
+| `conductor native-heap --pattern <s> \| --class <name> \| --read <addr> [--key <keyPath>]` | Live-object browser (find classes/instances, read a property off an address) |
+| `conductor native-console [--since <n>]` / `native-network [--since <n>]` | App stdout/stderr + captured HTTP; poll with the returned `cursor` |
+| `conductor native-screenshot --output <p.png>` | In-process PNG of the key window |
+| `conductor native-image <x,y,w,h> --output <p.png>` | Extract a component as a PNG — pass a node's `absFrame` from `native-inspect` |
+| `conductor native-snapshot <id> --output <p.png>` | Isolated PNG of one view's own content (transparent); `--with-subviews` composites the subtree |
+| `conductor native-raw <path>` | Escape hatch — GET any in-process endpoint (e.g. `'/get?id=..&keyPath=layer.cornerRadius'`, `'/class?id=..'`, `'/responders?id=..'`, `'/swiftui'`, `'/defaults'`, `'/focus'`, `'/snapshots?scale=0.5'`). Full list in `packages/ios-inproc/README.md`. |
+
+## Live-edit the running app
+
+| Command | Purpose |
+|---|---|
+| `conductor native-set <id> <key> <value>` | **Live-edit** a property: alpha, hidden, backgroundColor, tintColor, cornerRadius, borderWidth, borderColor, frame, text, textColor. `text`/`textColor` work on RN Fabric text views too |
+| `conductor native-highlight <id>` | Flash a highlight over the view on the device |
+| `conductor native-appearance <light\|dark\|system> \| --direction <ltr\|rtl> \| --anim-speed <n>` | Force appearance / RTL / freeze animations app-wide |
+| `conductor native-eval '<swift>'` | Compile & run arbitrary Swift inside the app (full UIKit / ObjC-runtime access); `--mode full` for a whole function body. e.g. `native-eval 'UIScreen.main.bounds'` |
+
+> **Editing RN Fabric text/props:** the native plane can't set text on `RCTParagraphComponentView` (no native setter) and `native-props` returns `rawProps: null` on Fabric. Edit through React instead with `conductor native-rn-set --react-tag <n> --path children --value '"…"'` (and read raw JSX props with `native-rn-props --react-tag <n>`). `reactTag` comes from this tree's `rn.reactTag`. See the `conductor-metro-debugger` skill. Dev builds only.
+
+## The Reveal-style loop
+
+Every `native-inspect` node has a stable `id` (for this launch): inspect →
+pick an `id` → `native-view` for detail → `native-set` to edit live → see it on
+the device. Re-inspect after relaunch (IDs reset).
+
+```bash
+conductor launch-app com.example.app --inject
+conductor native-inspect                              # tree with ids, colors, fonts, absFrame
+conductor native-view 0x10280d0c0                     # full detail for a view
+conductor native-set 0x10280d0c0 backgroundColor '#FF3B30FF'   # live-edit, visible on device
+conductor native-image 816,286,288,288 --output /tmp/avatar.png
+```
+
+## Related
+
+- `conductor-inspect` — external observation (a11y snapshots, screenshots, `@eN` refs) + assertions.
+- `conductor-metro-debugger` — the React/JS plane: `native-rn-set` / `native-rn-props`, `debug evaluate`, component tree, logs, network.

package/skills/conductor-test-cases/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: conductor-test-cases
+description: Read a repo's test cases and file execution results from the command line, including turning a JUnit report from a CI run into per-case results. Use when reporting automated test outcomes back to the test-case matrix, checking which cases have no flow behind them, or recording a case verdict from a script.
+---
+
+# Conductor — test cases
+
+A **test case** is the human-readable spec — id, title, business rule, steps,
+tags — kept as a YAML file under `~/.conductor/studio/cases/<project>/`, keyed
+by the project's path. Executions are appended to `results.jsonl` beside them.
+Neither is written into the repo under test: the Maestro flow a case names is
+the implementation, and that is what belongs in git.
+
+Both are plain files — read them, diff them, sync them however you like. Set
+`__CONDUCTOR_STUDIO_DIR` to relocate the store (CI sandboxes, tests). Cases an
+older version wrote to `test-cases/` in the repo are still read.
+
+| Command | Purpose |
+|---|---|
+| `conductor cases list [--project <dir>]` | List every case and the flow behind it |
+| `conductor cases report --junit <file.xml>` | File a JUnit report as per-case results |
+| `conductor cases result <case-id> --verdict <v>` | Record one result by hand |
+
+`--project <dir>` points at the repo root; it defaults to the working directory.
+These commands touch files only — no device, no session.
+
+## Report a CI run
+
+```bash
+conductor cases report --junit maestro-report.xml \
+  --build 2026.17.0 --environment staging
+```
+
+Each `<testcase>` binds to a case by the **flow** it names (`vod-playback.tv.yaml`
+→ the case whose `flows.tv` is that file, recording against the `tv` column) or,
+failing that, by a **case id** appearing in the test name as a whole word
+(`DT-97 search returns results` → case `DT-97`, recorded case-wide). Entries that
+match nothing are reported as unmatched rather than silently dropped.
+
+Add it as the last step of an e2e job, after the report is written:
+
+```yaml
+- run: conductor cases report --junit report.xml --build ${{ github.sha }}
+```
+
+## Record a single result
+
+```bash
+conductor cases result DT-1 --verdict failed --column tv \
+  --note "Subtitles never appear after seek" --build 2026.17.0
+```
+
+`--verdict` is `passed`, `failed`, `blocked` or `skipped`. `--column` scopes the
+result to one platform of a case that has a flow per platform; omit it for a
+case-wide verdict.
+
+## Find work
+
+```bash
+conductor cases list --json | jq '.cases[] | select(.flows | length == 0) | .id'
+```
+
+Cases with no flow are the unautomated ones — the backlog. Write the flow with
+`conductor-create-flow`, then add its path to the case's `flow:` (or `flows:`,
+keyed by platform) so the matrix picks it up.