@houwert/conductor 0.29.1 → 0.29.3

package/dist/commands/profile-frames.js

@@ -647,8 +647,10 @@ async function profileFramesReport(opts, sessionName, frameOpts) {
         if (frameOpts.trackSec !== undefined && repeat === 1) {
             notes.push({
                 code: 'single-window',
-                message: 'One window carries no run-to-run variance, so a later --diff cannot tell a real ' +
-                    'change from noise. Capture a baseline with --repeat 5 to record its own spread.',
+                message: 'One window carries no run-to-run variance, so nothing here can be called a change. ' +
+                    'Measured on a Fire TV Stick, five identical captures of the same screen ranged ' +
+                    '37.8-72.9% janky and 6.2-13.0ms issueDraw p50 — wide enough to invent a regression ' +
+                    'or hide one. Treat --repeat 5 as the default on TV, not an option.',
             });
         }
         const report = {

package/dist/commands/profile.js

@@ -4,9 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REACT_PROFILER_STOP = exports.REACT_PROFILER_READ = exports.REACT_PROFILER_INSTALL = exports.HELP = void 0;
+exports.isUnsymbolised = isUnsymbolised;
+exports.rollupByDso = rollupByDso;
+exports.unsymbolisedPercent = unsymbolisedPercent;
 exports.parseSimpleperfReport = parseSimpleperfReport;
 exports.profileCpu = profileCpu;
 exports.heapGrowth = heapGrowth;
+exports.inferCollections = inferCollections;
 exports.profileMemory = profileMemory;
 exports.profileReactStart = profileReactStart;
 exports.profileReactStop = profileReactStop;
@@ -36,9 +40,80 @@ const output_js_1 = require("../output.js");
 const bootstrap_js_1 = require("../drivers/bootstrap.js");
 const sdk_js_1 = require("../android/sdk.js");
 const runner_js_1 = require("../runner.js");
+const device_js_1 = require("../android/device.js");
 const memory_js_1 = require("./memory.js");
 const metro_cdp_js_1 = require("../drivers/metro-cdp.js");
 const profile_gc_js_1 = require("./profile-gc.js");
+/** simpleperf renders an unresolved address as `libfoo.so[+1a62f8]`. */
+function isUnsymbolised(symbol) {
+    return /\[\+[0-9a-fx]+\]\s*$/i.test(symbol);
+}
+function shortDso(dso) {
+    return dso.includes('/') ? dso.slice(dso.lastIndexOf('/') + 1) : dso;
+}
+/**
+ * Sum a flat symbol table by library.
+ *
+ * A stripped app library shows up as a dozen `libfoo.so[+offset]` rows that a
+ * reader cannot tell apart from a dozen unrelated hotspots. Rolled up, one
+ * library dominating is immediately visible — which is the actual finding when
+ * a profile has no single hot symbol.
+ */
+function rollupByDso(entries) {
+    const byDso = new Map();
+    for (const e of entries) {
+        const key = shortDso(e.dso);
+        const slot = byDso.get(key) ?? { percent: 0, symbols: 0, unsym: 0 };
+        slot.percent += e.percent;
+        slot.symbols++;
+        if (isUnsymbolised(e.symbol))
+            slot.unsym++;
+        byDso.set(key, slot);
+    }
+    return [...byDso.entries()]
+        .map(([dso, v]) => ({
+        dso,
+        percent: Math.round(v.percent * 100) / 100,
+        symbols: v.symbols,
+        unsymbolised: v.unsym === v.symbols,
+    }))
+        .sort((a, b) => b.percent - a.percent);
+}
+/** Share of the sampled overhead that resolved to no function name. */
+function unsymbolisedPercent(entries) {
+    const total = entries.reduce((a, e) => a + e.percent, 0);
+    if (total <= 0)
+        return 0;
+    const unsym = entries.filter((e) => isUnsymbolised(e.symbol)).reduce((a, e) => a + e.percent, 0);
+    return Math.round((unsym / total) * 10000) / 100;
+}
+/**
+ * Turn a simpleperf failure into something actionable.
+ *
+ * simpleperf needs the target to be `android:debuggable` or to declare
+ * `<profileable android:shell="true"/>`. A stock release APK is neither, and
+ * the resulting error says only `exited with 1`.
+ */
+async function explainSimpleperfFailure(deviceId, appId, stderr) {
+    // Drop simpleperf's PMU probing chatter; it is present on every run.
+    const meaningful = stderr
+        .split(/\r?\n/)
+        .filter((l) => l.trim() && !/cannot read event type|Failed to read event type/i.test(l))
+        .slice(-4)
+        .join('\n');
+    if (appId) {
+        const pkg = await (0, device_js_1.adbShell)(deviceId, ['dumpsys', 'package', appId]);
+        if (pkg.success && /^\s*flags=\[/m.test(pkg.stdout) && !/\bDEBUGGABLE\b/.test(pkg.stdout)) {
+            return (`simpleperf cannot profile ${appId}: the installed APK is neither debuggable nor ` +
+                `profileable.\nsimpleperf needs android:debuggable, or ` +
+                `\`<profileable android:shell="true"/>\` inside <application> — the latter is a ` +
+                `one-line manifest change that keeps the build a release build and is the right fix ` +
+                `for a perf build.\n` +
+                (meaningful ? `simpleperf said:\n${meaningful}` : ''));
+        }
+    }
+    return `simpleperf record failed.\n${meaningful || '(no diagnostic output)'}`;
+}
 /**
  * Parse `simpleperf report --sort dso,symbol`. The header row is located by its
  * `Overhead` column rather than by line number, since simpleperf prefixes the
@@ -104,11 +179,13 @@ async function recordAndroidCpu(deviceId, appId, durationSec, out, report) {
     else {
         recordArgs.push('-a');
     }
-    await new Promise((resolve, reject) => {
-        const proc = (0, child_process_1.spawn)(adb, recordArgs, { stdio: 'inherit', env });
-        proc.on('close', (code) => code === 0 ? resolve() : reject(new Error(`simpleperf record exited with ${code}`)));
-        proc.on('error', reject);
-    });
+    // Capture rather than inherit: simpleperf prints a wall of `cannot read event
+    // type` lines while probing PMU support, and those are not the error. Letting
+    // them through buries whatever actually went wrong.
+    const rec = await (0, runner_js_1.spawnCommand)(adb, recordArgs, { env });
+    if (!rec.success) {
+        throw new Error(await explainSimpleperfFailure(deviceId, appId, rec.stderr));
+    }
     // Symbolize on-device before pulling: /system/bin/simpleperf resolves against
     // the libraries actually loaded there, which a host-side report cannot do
     // without a matching symfs.
@@ -181,17 +258,41 @@ async function profileCpu(opts, sessionName, profileOpts) {
             (0, output_js_1.printError)(`profile cpu is not supported on platform ${platform ?? '(unknown)'}`, opts);
             return 1;
         }
+        const byDso = entries ? rollupByDso(entries) : undefined;
+        const unsymPercent = entries ? unsymbolisedPercent(entries) : undefined;
         if (opts.json) {
-            (0, output_js_1.printData)({ out, durationSec: profileOpts.durationSec, platform, symbols: entries }, opts);
+            (0, output_js_1.printData)({
+                out,
+                durationSec: profileOpts.durationSec,
+                platform,
+                symbols: entries,
+                byDso,
+                unsymbolisedPercent: unsymPercent,
+            }, opts);
         }
         else {
             (0, output_js_1.printSuccess)(`profile cpu — recorded ${profileOpts.durationSec}s → ${out}`, opts);
+            if (byDso && byDso.length > 0) {
+                // Lead with the rollup: a flat profile has no hot symbol, and the real
+                // finding is usually which library the samples are spread across.
+                console.log(`\n  by library`);
+                for (const d of byDso.slice(0, 10)) {
+                    console.log(`  ${`${d.percent}%`.padStart(9)}  ${d.dso}  (${d.symbols} symbol${d.symbols === 1 ? '' : 's'}` +
+                        `${d.unsymbolised ? ', unsymbolised' : ''})`);
+                }
+            }
             if (entries) {
-                console.log(`  ${'overhead'.padStart(9)}  symbol`);
+                console.log(`\n  ${'overhead'.padStart(9)}  symbol`);
                 for (const e of entries) {
                     console.log(`  ${`${e.percent}%`.padStart(9)}  ${e.symbol}  [${e.dso}]`);
                 }
             }
+            if (unsymPercent !== undefined && unsymPercent > 10) {
+                console.log(`\n  note: ${unsymPercent}% of sampled overhead resolved to a raw address rather ` +
+                    `than a function — those libraries are stripped. Read the by-library rollup above ` +
+                    `instead of the symbol table; a dozen \`lib.so[+offset]\` rows are one library, ` +
+                    `not a dozen findings.`);
+            }
         }
         return 0;
     }
@@ -228,6 +329,37 @@ function heapGrowth(samples) {
 function mb(bytes) {
     return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
 }
+/**
+ * Infer collections from the heap series rather than from logcat.
+ *
+ * A heap that shrinks between two samples was collected between them — there is
+ * no other mechanism. This matters because ART's GC logging is not reliably on:
+ * measured on a Fire TV Stick (Fire OS, API 30), a window in which the Java heap
+ * fell 11.8MB produced no `art:I` lines at all. Absence of logged collections is
+ * therefore not absence of collection, and the deltas are the sounder signal.
+ */
+function inferCollections(samples, series = 'javaHeapBytes') {
+    const values = [];
+    for (const s of samples) {
+        const app = s.data?.app;
+        const v = app?.[series];
+        if (typeof v === 'number')
+            values.push(v);
+    }
+    if (values.length < 2)
+        return undefined;
+    let collections = 0;
+    let reclaimedBytes = 0;
+    for (let i = 1; i < values.length; i++) {
+        const drop = values[i - 1] - values[i];
+        // Ignore sampling jitter; only count drops worth a collection.
+        if (drop > 256 * 1024) {
+            collections++;
+            reclaimedBytes += drop;
+        }
+    }
+    return { collections, reclaimedBytes, series };
+}
 async function profileMemory(opts, sessionName, profileOpts) {
     const samples = [];
     const platform = await (0, bootstrap_js_1.detectPlatform)(sessionName).catch(() => undefined);
@@ -257,6 +389,7 @@ async function profileMemory(opts, sessionName, profileOpts) {
         }
     });
     const growth = heapGrowth(parsed);
+    const inferredGc = isAndroid ? inferCollections(parsed) : undefined;
     let gc;
     if (isAndroid) {
         const events = await (0, profile_gc_js_1.collectGcSince)(sessionName, gcSince);
@@ -264,7 +397,7 @@ async function profileMemory(opts, sessionName, profileOpts) {
             gc = (0, profile_gc_js_1.summariseGc)(events);
     }
     if (opts.json) {
-        (0, output_js_1.printData)({ samples: parsed, durationMs: Date.now() - start, growth, gc }, opts);
+        (0, output_js_1.printData)({ samples: parsed, durationMs: Date.now() - start, growth, gc, inferredGc }, opts);
     }
     else {
         console.log(`profile memory — ${samples.length} samples over ${profileOpts.trackSec}s`);
@@ -293,8 +426,20 @@ async function profileMemory(opts, sessionName, profileOpts) {
             }
         }
         else if (isAndroid) {
-            console.log('\n  GC: no ART collections logged in the window. ART only logs collections it ' +
-                'considers noteworthy, so a quiet window here is a real signal.');
+            console.log('\n  GC: no ART collections logged in the window.');
+            if (inferredGc && inferredGc.collections > 0) {
+                console.log(`    But ${inferredGc.series} fell ${inferredGc.collections} time(s), reclaiming ` +
+                    `${mb(inferredGc.reclaimedBytes)} — so collections did run and were not logged. ` +
+                    `ART's logging is off or filtered on this build; trust the heap deltas, not logcat.`);
+            }
+            else {
+                console.log('    Absence of logged collections is not absence of collection — ART logging is ' +
+                    'off or filtered on some builds. The heap deltas above are the sounder signal.');
+            }
+        }
+        if (inferredGc && inferredGc.collections > 0 && gc) {
+            console.log(`    (heap deltas independently imply ${inferredGc.collections} collection(s), ` +
+                `${mb(inferredGc.reclaimedBytes)} reclaimed)`);
         }
     }
     return 0;

package/dist/drivers/log-sources/metro.js

@@ -131,7 +131,9 @@ async function discoverTarget(port, host, targetIndex) {
     const data = await fetchTargets(port, host);
     const withWs = data.filter((t) => t.webSocketDebuggerUrl);
     if (withWs.length === 0) {
-        throw new Error('Metro returned no debugger targets. Is the app running on a device/simulator?');
+        throw new Error('Metro is reachable but has no debugger targets. Most often the app is a release ' +
+            'build — release Hermes ships without the inspector and never connects to Metro. ' +
+            'Otherwise, check the app is running and pointed at this Metro instance.');
     }
     if (targetIndex !== undefined) {
         if (targetIndex < 0 || targetIndex >= withWs.length) {

package/dist/drivers/metro-cdp.js

@@ -33,7 +33,17 @@ function selectDebuggerUrl(targets, opts, displayName) {
     const host = opts.host ?? 'localhost';
     const withWs = targets.filter((t) => t.webSocketDebuggerUrl);
     if (withWs.length === 0) {
-        throw new Error(`Metro on ${host}:${port} returned no debugger targets. Is an app running on a device/simulator?`);
+        // Metro is reachable but nothing registered. The usual cause is not a
+        // missing app — it is a release build: release Hermes ships without the
+        // inspector and never connects to Metro at all, so asking "is the app
+        // running?" sends people to check something that is already true.
+        throw new Error(`Metro on ${host}:${port} is reachable but has no debugger targets.\n` +
+            `Most often the app is a release build — release Hermes ships without the ` +
+            `inspector and never connects to Metro, so no amount of relaunching will help. ` +
+            `Use a debug or profiling build for anything that attaches over Metro ` +
+            `(\`profile js\`, \`profile react\`, \`debug\`, \`network\`).\n` +
+            `Otherwise: check the app is running and foreground, and that it is pointed at ` +
+            `this Metro instance rather than another one.`);
     }
     if (opts.targetIndex !== undefined) {
         if (opts.targetIndex < 0 || opts.targetIndex >= withWs.length) {

package/package.json

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

package/skills/conductor-profiler/SKILL.md

@@ -18,9 +18,14 @@ Measure a running app's performance and inspect crashes.
 | "Which component re-renders on every input?" | `profile react start` → interact → `profile react stop` |
 | "Memory grows / it stutters periodically" | `profile memory --track 30` |
 
-`profile frames`, `profile cpu` and `profile memory` work on **release builds**
-and on real hardware. `profile js` and `profile react` attach over Metro, so
-they need a dev/profiling build.
+Only `profile frames` and `profile memory` work on a **stock release build**.
+`profile cpu` needs `android:debuggable` or `<profileable android:shell="true"/>`
+in the manifest; `profile js` and `profile react` attach over Metro, and release
+Hermes ships without the inspector so there is no target to attach to.
+
+On TV, run `profile frames --track` with `--repeat 5`. Identical captures of one
+screen have been measured spanning 37.8-72.9% janky — a single window can invent
+a regression or hide one, and cannot support a `--diff`.
 
 ## Frame timing & jank (Android, incl. Fire TV / Android TV)