@houwert/conductor 0.29.2 → 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,6 +4,9 @@ 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;
@@ -37,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
@@ -105,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.
@@ -182,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;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.29.2",
+  "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)