@g9tm/app-pilot-cli 0.0.0-stage → 0.1.0

package/bin/g9pilot.mjs

@@ -0,0 +1,1594 @@
+#!/usr/bin/env node
+// g9pilot — the G9AppPilot controller CLI (pilot/AiGuides/04).
+//
+//   g9pilot hello                      [--url http://127.0.0.1:8799]
+//   g9pilot call <command> [json]      signed; prints the answer
+//   g9pilot trace [list|<id>] [--out <dir>] [--crash --serial <adb serial> | --simulator <udid>] | trace --file <trace.json>
+//                                      a failure trace from the device's black box (default the newest): prints what
+//                                      most likely went wrong and writes trace.json + index.html (a static viewer) to --out;
+//                                      --crash adds the OS's crash log (an app that died cannot report it itself)
+//   g9pilot os <what> … --serial <adb serial> | --simulator <udid>   the device around the app (the stage scope's OS half):
+//     os crashlogs [--package <id>] [--lines 400]        the OS crash buffer (logcat -b crash; the simulator's reports)
+//     os permission grant|revoke <permission> --package <id>   pm grant / simctl privacy (android.permission.CAMERA, camera…)
+//     os location <lat> <lon>                           a fake position (emulator geo fix; simulator location set)
+//     os net offline|online                             the whole device network (airplane mode): native traffic too
+//     os dialog allow|deny                              answers the system permission dialog on screen (Android)
+//     os video <seconds> --out <dir>                    records the screen (Android: pieces under screenrecord's 180 s
+//                                                       limit, each pulled; simulator: simctl io recordVideo, SIGINT)
+//     os doze on|off|step                               Android Doze (deviceidle force-idle / unforce + battery reset)
+//     os standby <active|working_set|frequent|rare|restricted> --package <id>   Android App Standby bucket
+//     os appearance dark|light                          the system theme (cmd uimode night / simctl ui appearance)
+//     os fontscale <1.3 | extra-large …>                the system text size (settings font_scale / simctl content_size)
+//     os notify <payload.json> --package <id>           a push to the app (simulator: simctl push; Android: refused —
+//                                                       `cmd notification post` posts as the shell, not the app)
+//   g9pilot status --brief             one line per configured device: app, version, page ready, keys (for a Skill)
+//   g9pilot events [--since N] [--kinds a,b]   follow the event stream
+//   g9pilot proxy --listen 8799 --target http://127.0.0.1:18799
+//                                      a local signing proxy: an unchanged runner talks to --listen, every request
+//                                      reaches the device signed (the key never leaves this process)
+//   g9pilot keys new --kid <id>        a fresh ES256 pair: the public key is printed, the private key goes ONLY to
+//                                      --out <file> (or nowhere: you store it yourself from the printed instructions)
+//   g9pilot keys public                the public key of the configured private key
+//   g9pilot conformance [--json]       the protocol-2 conformance suite against --url (exit 1 on any failure)
+//   g9pilot savepoint save|load|list|delete [<name>] [--serial emulator-5554] [--forward 8797]
+//                                      level 0 of a savepoint: the WHOLE Android emulator (app, data, OS) as a snapshot
+//                                      (`adb emu avd snapshot`); load takes seconds and the app comes back as it was
+//   g9pilot savepoint save|load|list <name> --level app --package <id> [--serial <any device>] [--dir <folder>]
+//                                      level 1: the APP's data (files, databases, preferences) of a debuggable build,
+//                                      to a tar on this machine and back (`run-as`); the app is stopped first.
+//                                      Every level-1 save: [--server <database / environment> --server-commit <sha>] →
+//                                      <name>.meta.json beside the tar (the server the app's data belongs to)
+//   g9pilot savepoint save|load|list|delete <name> --simulator <udid>
+//                                      level 0 on the iOS simulator: the whole device (simctl clone; a load copies the
+//                                      clone's data back with APFS clones, so the device keeps its UDID); on the Mac
+//   g9pilot savepoint save|load|list <name> --level app --simulator <udid> --package <bundle id> [--dir <folder>]
+//                                      the same on the iOS simulator: Documents + Library of the data container
+//                                      (not Caches, SplashBoard, tmp); run on the Mac
+//   g9pilot savepoint save|load|list <name> --level app --via bridge --package <id> [--device <iPhone udid> |
+//                                      --simulator <udid> | --serial <s>]   the APP packs it at its next launch (before
+//                                      it opens its data) and one file moves: the iPhone path (devicectl copies files only)
+//   g9pilot tokens gen | approve [--snapshot <file>] [--dry-run]
+//                                      design tokens (DTCG files in g9pilot.json "tokens") → the app's generated module;
+//                                      the device's design.snapshot written back into the files (no commit)
+//   g9pilot catalog shoot --serial <s> | --simulator <udid> [--approve-new] [--only A,B] [--variant catalog]
+//                                      the app's component catalog (catalog.list / catalog.show) in every studio mode,
+//                                      each state against its reference <component>.<state> (variant <variant>-m<mode>)
+//   g9pilot visual check <name> --serial <adb serial> | --simulator <udid> | --file <png> [--variant android-light-fa]
+//                                      the screen against its approved reference (lossless OS capture, masks for a clock
+//                                      or a live map; g9pilot.json "visual"): exit 0 match, 1 differs (a .diff.png beside
+//                                      it), 2 no reference yet or another size
+//   g9pilot visual approve <name> | visual list   the last capture becomes the reference (no commit) | what exists
+//   g9pilot studio [--port 47901]      the local studio: the device's screen beside its tokens, live edits, approve
+//   g9pilot mcp                        an MCP server on stdio for agents (packages/mcp): twelve tools over this bridge;
+//                                      `claude mcp add app-pilot -- g9pilot mcp --config <g9pilot.json>`
+//   g9pilot session send <summary.json>   a session summary (format g9/pilot-session) to the hub of g9pilot.json "hub";
+//                                      proxy, mcp, studio and relay send theirs themselves when a session ends (10 minutes
+//                                      without a command, G9PILOT_SESSION_IDLE_MS, or the process's end) — command names and
+//                                      counts only, never an argument
+//   g9pilot relay [--name <name>]       the devices in g9pilot.json "devices" offered to the hub's studio page: the hub
+//                                      adapter's long poll; each request is run here, signed here, studio commands only
+//                                      (design tokens, a screenshot, the app's identity)
+//   g9pilot approvals list [--status approved] | apply <DA-…> [--dry-run]
+//                                      the design approvals made on the hub's studio page: apply writes one into the token
+//                                      files here (g9pilot.json "tokens") and regenerates them, then reports «applied»;
+//                                      never a commit
+//   g9pilot studio --emit <dir> [--header Name=value]   the studio page as a hub serves it (studio.fa.html,
+//                                      studio.en.html, assets/studio.js); --header = what the hub wants on a write
+//   g9pilot host --listen 47900 [--bind 0.0.0.0]   (g9pilot.json "reserve": {hold, release, idleMinutes} books a shared
+//                                      device on first use and frees it when idle; a refused booking is HTTP 423)
+//                                      a relay for the devices attached to THIS machine (adb serials, g9pilot.json
+//                                      "hostDevices" such as a booted simulator): /devices lists them, /d/<name>/…
+//                                      reaches one, signed requests pass unchanged (no key here). A token
+//                                      (G9PILOT_HOST_TOKEN, or --token-env) guards it; off the loopback it is required.
+//   --host <name> --device <name>      any command above, through a relay named in g9pilot.json "hosts"
+//   g9pilot dev [--cmd "npm run dev"] [--cwd app] [--port 3000] [--bundle main.lynx.bundle] [--serial <adb serial>]
+//               [--watch-flows [tag:@smoke | <flow id>]]   after each rebuild: the page ready again, settled, then the
+//                                      runner (g9pilot.json "runner") replays them; one ✓/✗ line per change
+//                                      live development: starts the dev server, waits for the bundle, `adb reverse`s the
+//                                      port to every Android device (or --serial), then sends the signed dev.server so the
+//                                      app loads from it (HMR, state kept). Ctrl+C puts the app back on its own bundle.
+//                                      The dev server is told its port in G9PILOT_DEV_PORT.
+//
+// Configuration: g9pilot.json in the working directory (or --config), all optional:
+//   { "url": "http://127.0.0.1:8799", "kid": "owner-…", "key": { "env": "G9PILOT_KEY", "file": "…",
+//     "windows": "<Credential Manager target>", "macos": { "service": "…", "account": "…" } },
+//     "hosts": { "<name>": { "url": "http://…:47900", "tokenEnv": "G9PILOT_HOST_TOKEN" } },
+//     "hostDevices": [{ "name": "…", "url": "http://127.0.0.1:8796" }], "devicePort": 8799 }
+// The private key is read from env/file/OS store and is never printed.
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { runConformance } from '@g9tm/app-pilot-client/conformance';
+import { explainTrace, generateKeyPair, PilotClient, publicKeyOf, loadHub, readSummary, runRelay, sessionRecorder, signRequest, tallyCalls, traceViewerHtml } from '@g9tm/app-pilot-client';
+import { loadPrivateKey } from '@g9tm/app-pilot-client/keys';
+import { studioHtml, studioScript, studioServer, tokenSets, tokensApprove, tokensGen } from '../src/design.mjs';
+import { approveVisual, captureOsPng, checkVisual, listVisual, visualSettings } from '../src/visual.mjs';
+
+const argv = process.argv.slice(2);
+const flags = {};
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a.startsWith('--')) {
+    const k = a.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) flags[k] = true;
+    else flags[k] = argv[++i];
+  } else positional.push(a);
+}
+
+const configPath = flags.config ?? path.join(process.cwd(), 'g9pilot.json');
+const config = fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, 'utf8')) : {};
+const kid = flags.kid ?? config.kid;
+
+/** `--host <name> --device <name>`: the relay's URL for that device, and the relay's token header (never signed). */
+function viaHost() {
+  if (!flags.host) return { base: null, headers: {} };
+  const host = config.hosts?.[String(flags.host)];
+  if (!host?.url) fail(`No host "${flags.host}" in g9pilot.json "hosts".`);
+  if (!flags.device) fail('--host needs --device <name> (g9pilot host lists them at /devices).');
+  const token = process.env[host.tokenEnv ?? 'G9PILOT_HOST_TOKEN'];
+  return { base: `${String(host.url).replace(/\/+$/, '')}/d/${encodeURIComponent(String(flags.device))}`, headers: token ? { 'x-g9p-host-token': token } : {} };
+}
+const relay = viaHost();
+const url = String(relay.base ?? flags.url ?? (flags.port ? `http://127.0.0.1:${flags.port}` : (config.url ?? 'http://127.0.0.1:8799')));
+const clientFor = (opts = {}) => new PilotClient({ base: url, kid, extraHeaders: relay.headers, ...opts });
+/** A session record for a long-running command; its device is the g9pilot.json device of that address, else the address. */
+let hubLoad = null;
+/** The hub of g9pilot.json "hub" (its adapter, loaded once), or null. */
+const hub = () => (hubLoad ??= loadHub(config, path.dirname(path.resolve(configPath))));
+const recorder = (tool, address) => sessionRecorder({ tool, kid, device: (config.devices ?? []).find((d) => d.url === address)?.name ?? address, hub: config.hub ? hub() : null, enabled: Boolean(config.hub) });
+
+function key({ required = true } = {}) {
+  const found = loadPrivateKey(config.key ?? {});
+  if (!found && required) {
+    fail('No private key: set G9PILOT_KEY, or name a file / Credential Manager target / keychain item in g9pilot.json "key".');
+  }
+  return found;
+}
+
+function fail(message, code = 2) {
+  process.stderr.write(`g9pilot: ${message}\n`);
+  process.exit(code);
+}
+
+const print = (v) => process.stdout.write(`${typeof v === 'string' ? v : JSON.stringify(v, null, 2)}\n`);
+
+async function main() {
+  const [cmd, ...rest] = positional;
+  switch (cmd) {
+    case 'hello': {
+      print(await clientFor().hello());
+      return;
+    }
+    case 'call': {
+      const [command, argsJson] = rest;
+      if (!command) fail('call needs a command: g9pilot call qa.ping');
+      const k = key({ required: !flags.unsigned });
+      const client = clientFor({ privateKey: k?.key, leaseId: flags.lease ?? null });
+      const answer = await client.call(command, argsJson ? JSON.parse(argsJson) : {}, { timeoutMs: Number(flags.timeout ?? 30_000) });
+      print(answer);
+      process.exitCode = answer?.ok ? 0 : 1;
+      return;
+    }
+    case 'trace': {
+      // A trace already on disk (a runner's failure bundle, <report>/failures/<flow>.trace.json): explained and viewed
+      // without a device.
+      if (flags.file) {
+        const trace = JSON.parse(fs.readFileSync(String(flags.file), 'utf8'));
+        const out = path.resolve(String(flags.out ?? path.join(path.dirname(String(flags.file)), `${path.basename(String(flags.file), '.json')}-viewer`)));
+        fs.mkdirSync(out, { recursive: true });
+        fs.writeFileSync(path.join(out, 'index.html'), traceViewerHtml(trace));
+        print({ ...explainTrace(trace), written: out });
+        return;
+      }
+      const client = clientFor({ privateKey: key({ required: !flags.unsigned })?.key });
+      const [which] = rest;
+      if (which === 'list') {
+        const answer = await client.call('trace.list');
+        print(answer.ok ? answer.result.traces : answer);
+        process.exitCode = answer.ok ? 0 : 1;
+        return;
+      }
+      const answer = await client.call('trace.get', which ? { id: which } : {});
+      if (!answer.ok) {
+        print(answer);
+        process.exitCode = 1;
+        return;
+      }
+      const trace = answer.result;
+      if (flags.crash) trace.sections = { ...(trace.sections ?? {}), osCrashLog: crashLog({ lines: 200 }) };
+      const e = explainTrace(trace);
+      const out = path.resolve(String(flags.out ?? `pilot-trace-${trace.id}`));
+      fs.mkdirSync(out, { recursive: true });
+      fs.writeFileSync(path.join(out, 'trace.json'), JSON.stringify(trace, null, 2));
+      fs.writeFileSync(path.join(out, 'index.html'), traceViewerHtml(trace));
+      print({ ...e, written: out });
+      return;
+    }
+    case 'os':
+      return osCommand(rest);
+    case 'status': {
+      const targets = config.devices ?? [{ name: 'default', url }];
+      const lines = [];
+      for (const t of targets) {
+        try {
+          const h = await new PilotClient({ base: t.url }).hello({ timeoutMs: 3000 });
+          lines.push(`${t.name}: ${h.app} ${h.versionName} (${h.environment}, ${h.platform ?? '?'}) page ${h.jsReady ? 'ready' : 'NOT ready'}, protocol ${h.protocol ?? 1}, keys ${JSON.stringify(h.kids ?? [])}, signatures ${h.signatureRequired ? 'required' : 'optional'}${h.devtool ? ', devtool' : ''}`);
+        } catch (e) {
+          lines.push(`${t.name}: no bridge at ${t.url} (${e.message})`);
+        }
+      }
+      const k = key({ required: false });
+      lines.push(`key: ${k ? `${kid ?? '(kid from the hello)'} from ${k.source}` : 'none configured'}`);
+      print(flags.brief ? lines.join('\n') : { devices: lines });
+      return;
+    }
+    case 'events': {
+      const k = key();
+      const client = clientFor({ privateKey: k.key });
+      const kinds = flags.kinds ? new Set(String(flags.kinds).split(',')) : null;
+      client.events({
+        since: Number(flags.since ?? 0),
+        onEvent: (e) => {
+          if (!kinds || kinds.has(e.kind)) print(JSON.stringify(e));
+        },
+        onError: (e) => process.stderr.write(`events: ${e.message}\n`),
+      });
+      return;
+    }
+    case 'session': {
+      const [sub, file] = rest;
+      if (sub !== 'send' || !file) fail('session send <summary.json>');
+      print(await (await hubOrFail()).sendSession(readSummary(String(file))));
+      return;
+    }
+    case 'relay':
+      return relayCommand();
+    case 'approvals':
+      return approvals(rest);
+    case 'proxy':
+      return proxy();
+    case 'host':
+      return host();
+    case 'dev':
+      return dev();
+    case 'mcp':
+      return mcp();
+    case 'savepoint':
+      return savepoint(rest);
+    case 'tokens': {
+      const sets = tokenSets(config, path.dirname(path.resolve(configPath)));
+      const [sub] = rest;
+      if (sub === 'gen') {
+        const written = tokensGen(sets);
+        print(written.length ? `generated ${written.join(', ')}` : 'the generated modules are up to date');
+        return;
+      }
+      if (sub === 'approve') {
+        let snapshot;
+        if (flags.snapshot) snapshot = JSON.parse(fs.readFileSync(String(flags.snapshot), 'utf8'));
+        else {
+          const client = clientFor({ privateKey: key({ required: !flags.unsigned })?.key });
+          const answer = await client.call('design.snapshot');
+          if (!answer.ok) fail(`design.snapshot: ${answer.error?.message ?? JSON.stringify(answer.error)}`);
+          snapshot = answer.result;
+        }
+        print(tokensApprove(sets, snapshot, { dryRun: flags['dry-run'] === true, ...approveFollowUps() }));
+        return;
+      }
+      fail('tokens gen | tokens approve [--snapshot <file>] [--dry-run]');
+      return;
+    }
+    case 'catalog': {
+      // The app's live component catalog against its references (plan v2 P1-19): for each studio mode (g9pilot.json
+      // studio.modes; none = as it is), each component and state the app lists (catalog.list) is shown alone
+      // (catalog.show), the OS picture taken (lossless, --serial / --simulator) and compared with its reference
+      // `<component>.<state>` in the variant `<--variant or catalog>-m<mode>`. A new one or a changed one is LISTED;
+      // `--approve-new` takes the first pictures as the references (a baseline: look at them first).
+      if (rest[0] !== 'shoot') fail('catalog shoot [--serial <s> | --simulator <udid>] [--approve-new] [--only Component[,…]]');
+      const settings0 = visualSettings(config, path.dirname(path.resolve(configPath)), flags);
+      const client = clientFor({ privateKey: key({ required: !flags.unsigned })?.key });
+      const call = async (command, args = {}) => {
+        const r = await client.call(command, args, { timeoutMs: 30_000 });
+        if (!r?.ok) throw new Error(`${command}: ${r?.error ?? 'no answer'}`);
+        return r.result;
+      };
+      const list = (await call('catalog.list')).components;
+      const only = flags.only ? String(flags.only).split(',') : null;
+      const modes = config.studio?.modes?.length ? config.studio.modes : [{ name: 'as it is', commands: [] }];
+      const rows = [];
+      try {
+        for (const [mi, mode] of modes.entries()) {
+          for (const cmd of mode.commands ?? []) await call(cmd.command, cmd.args ?? {});
+          const settings = { ...settings0, variant: `${flags.variant ?? 'catalog'}-m${mi}` };
+          for (const entry of list) {
+            if (only && !only.includes(entry.id)) continue;
+            for (const state of entry.states) {
+              await call('catalog.show', { component: entry.id, state });
+              await call('ui.waitIdle', {}).catch(() => null);
+              await new Promise((r) => setTimeout(r, 350));
+              const png = captureOsPng({ serial: flags.serial, simulator: flags.simulator, adb: String(flags.adb ?? process.env.ADB ?? 'adb') });
+              const name = `${entry.id}.${state}`;
+              let r = checkVisual(settings, name, png);
+              if (r.verdict === 'new' && flags['approve-new']) {
+                approveVisual(settings, name);
+                r = { ...r, verdict: 'new → reference' };
+              }
+              rows.push({ mode: mode.name, name, verdict: r.verdict, ...(r.ratio !== undefined ? { ratio: r.ratio } : {}), ...(r.diffImage ? { diff: r.diffImage } : {}) });
+            }
+          }
+        }
+      } finally {
+        await call('catalog.show', {}).catch(() => null);
+        await call('dev.close', {}).catch(() => null);
+      }
+      const count = (v) => rows.filter((x) => x.verdict.startsWith(v)).length;
+      print(JSON.stringify({ shots: rows.length, match: count('match'), differs: count('differs'), new: count('new'), size: count('size'), rows: rows.filter((x) => x.verdict !== 'match') }, null, 2));
+      process.exitCode = count('differs') || count('size') ? 1 : 0;
+      return;
+    }
+    case 'visual': {
+      const settings = visualSettings(config, path.dirname(path.resolve(configPath)), flags);
+      const [sub, name] = rest;
+      if (sub === 'list') {
+        const rows = listVisual(settings);
+        print(rows.length ? rows.map((r) => `${r.variant}/${r.name}${r.pending ? '  (a capture waits for approval)' : ''}`).join(String.fromCharCode(10)) : `no references under ${settings.dir}`);
+        return;
+      }
+      if (!name) fail('visual check <name> [--serial s | --simulator udid | --file shot.png] | visual approve <name> | visual list');
+      if (sub === 'approve') {
+        print(`approved: ${approveVisual(settings, String(name))}`);
+        return;
+      }
+      if (sub !== 'check') fail(`visual ${sub}: check, approve or list`);
+      const png = flags.file ? fs.readFileSync(String(flags.file)) : captureOsPng({ serial: flags.serial, simulator: flags.simulator, adb: String(flags.adb ?? process.env.ADB ?? 'adb') });
+      const r = checkVisual(settings, String(name), png);
+      print(JSON.stringify(r, null, 2));
+      if (r.verdict === 'differs') process.exitCode = 1;
+      else if (r.verdict !== 'match') process.exitCode = 2;
+      return;
+    }
+    case 'studio': {
+      // The same page for a hub's studio (one UI, two transports): its files, written where the hub serves them.
+      if (flags.emit) {
+        const dir = path.resolve(String(flags.emit));
+        fs.mkdirSync(path.join(dir, 'assets'), { recursive: true });
+        for (const lang of ['fa', 'en']) fs.writeFileSync(path.join(dir, `studio.${lang}.html`), studioHtml(lang === 'fa' ? 'استودیوی طراحی' : 'Design studio', { mode: 'hub', lang, scriptUrl: '/assets/studio.js', headers: Object.fromEntries([].concat(flags.header ?? []).map((h) => String(h).split('=')).filter(([k, v]) => k && v)) }));
+        fs.writeFileSync(path.join(dir, 'assets', 'studio.js'), studioScript());
+        print(`wrote studio.fa.html, studio.en.html, assets/studio.js under ${dir}`);
+        return;
+      }
+      const sets = tokenSets(config, path.dirname(path.resolve(configPath)));
+      const client = clientFor({ privateKey: key({ required: !flags.unsigned })?.key });
+      tallyCalls(client, recorder('studio', url));
+      const port = Number(flags.port ?? 47901);
+      // Several devices at once (plan v2 P1-17): --devices all | a,b (names in g9pilot.json "devices"), each its own
+      // client; a token change goes to all. `studio.modes`: the states each grid shot is taken in. A reference overlay
+      // is `g9pilot visual`: the device entry's `serial` / `simulator` gives the OS picture to compare.
+      const listed = config.devices ?? [];
+      const chosen = flags.devices ? (flags.devices === 'all' ? listed : listed.filter((d) => String(flags.devices).split(',').includes(d.name))) : [];
+      const pk = key({ required: !flags.unsigned })?.key;
+      const devices = chosen.map((d) => {
+        const c = new PilotClient({ base: String(d.url).replace(/\/+$/, ''), kid, privateKey: pk });
+        return { name: d.name, entry: d, call: (command, args) => c.call(command, args, { timeoutMs: 20_000 }) };
+      });
+      const settings = config.visual ? visualSettings(config, path.dirname(path.resolve(configPath)), flags) : null;
+      const reference = settings
+        ? (name, refName) => {
+            const d = devices.find((x) => x.name === name)?.entry ?? {};
+            const png = captureOsPng({ serial: d.serial ?? flags.serial, simulator: d.simulator ?? flags.simulator, adb: String(flags.adb ?? process.env.ADB ?? 'adb') });
+            const r = checkVisual(settings, refName, png);
+            const diffFile = r.diffImage && fs.existsSync(r.diffImage) ? r.diffImage : null;
+            return { verdict: r.verdict, ratio: r.ratio ?? null, diff: diffFile ? fs.readFileSync(diffFile).toString('base64') : null };
+          }
+        : null;
+      studioServer({ port, call: (command, args) => client.call(command, args, { timeoutMs: 20_000 }), devices: devices.length ? devices : null, modes: config.studio?.modes ?? [], reference, approve: (snapshot, o) => tokensApprove(sets, snapshot, { ...o, ...approveFollowUps() }) });
+      print(`G9AppPilot Studio: http://127.0.0.1:${port}  (${devices.length ? devices.map((d) => d.name).join(', ') : `device ${url}`}; ${(config.studio?.modes ?? []).length} mode(s); Ctrl+C ends it)`);
+      return;
+    }
+    case 'conformance': {
+      const k = key({ required: false });
+      const report = await runConformance({ base: url, privateKey: k?.key, kid, fetchImpl: (u, o = {}) => fetch(u, { ...o, headers: { ...relay.headers, ...(o.headers ?? {}) } }) });
+      if (flags.json) print(report);
+      else {
+        for (const c of report.checks) print(`${c.skipped ? 'SKIP' : c.ok ? 'PASS' : 'FAIL'} ${c.name}${c.detail ? `  (${c.detail})` : ''}`);
+        print(`${report.app}: ${report.passed} passed, ${report.failed} failed, ${report.skipped} skipped`);
+      }
+      process.exitCode = report.failed ? 1 : 0;
+      return;
+    }
+    case 'keys': {
+      const [sub] = rest;
+      if (sub === 'new') {
+        if (!flags.kid) fail('keys new --kid <id>');
+        const pair = generateKeyPair();
+        if (flags.out) fs.writeFileSync(String(flags.out), pair.privateKey, { mode: 0o600 });
+        print({ kid: flags.kid, publicKey: pair.publicKey, privateKey: flags.out ? `written to ${flags.out}` : 'NOT kept — pass --out <file> to keep it' });
+        return;
+      }
+      if (sub === 'public') {
+        print(publicKeyOf(key().key));
+        return;
+      }
+      fail('keys new --kid <id> [--out file] | keys public');
+      return;
+    }
+    default:
+      fail('commands: hello, call <command> [json], status [--brief], events, proxy --listen <port> --target <url>, host --listen <port>, dev, conformance, keys new|public', cmd ? 2 : 0);
+  }
+}
+
+/** The hub of g9pilot.json "hub", or the reason there is none (session send, relay and approvals need it). */
+async function hubOrFail() {
+  const h = await hub();
+  if (!h) fail('g9pilot.json has no "hub" (an adapter: "hub": {"adapter": "<path or package>", …its options}).');
+  if (h.error) fail(h.error);
+  return h;
+}
+
+/** `g9pilot relay`: this machine's devices for the hub's studio page, until Ctrl+C. */
+async function relayCommand() {
+  const h = await hubOrFail();
+  const k = key();
+  const targets = config.devices?.length ? config.devices : [{ name: 'default', url }];
+  const devices = [];
+  for (const t of targets) {
+    const client = new PilotClient({ base: t.url, privateKey: k.key, kid, extraHeaders: relay.headers });
+    let hello = null;
+    try {
+      const h = await client.hello({ timeoutMs: 3000 });
+      hello = { app: h.app, appVersion: h.versionName, platform: h.platform ?? null };
+    } catch {
+      continue; // a device that does not answer is not offered
+    }
+    devices.push({ name: t.name, hello, call: (command, args) => client.call(command, args, { timeoutMs: 20_000 }) });
+  }
+  if (!devices.length) fail(`none of the devices in g9pilot.json answers (${targets.map((t) => t.url).join(', ')})`);
+  const tally = recorder('relay', devices[0].name);
+  const stop = new AbortController();
+  process.once('SIGINT', () => stop.abort());
+  process.stderr.write(`g9pilot relay: ${devices.map((d) => `${d.name} (${d.hello.app} ${d.hello.appVersion})`).join(', ')} → ${h.url} (key ${k.source}; Ctrl+C ends it)\n`);
+  await runRelay({ poll: h.relayPoll, name: String(flags.name ?? os.hostname()), devices, signal: stop.signal, onRequest: (_d, command, ok) => tally.record(command, { ok }), log: (l) => process.stderr.write(`${l}\n`) });
+}
+
+/** `g9pilot approvals list | apply <id>`: the hub's design approvals into this checkout's token files (never a commit). */
+async function approvals([sub, id]) {
+  const h = await hubOrFail();
+  if (sub === 'list') {
+    const r = await h.approvals.list({ status: String(flags.status ?? 'approved'), branch: flags.branch ? String(flags.branch) : '' });
+    print(r.approvals.length ? r.approvals.map((a) => `${a.id}  ${a.status}  ${a.branch ?? '—'}  ${a.app ?? ''} ${a.appVersion ?? ''}  by ${a.by}  ${a.changes.map((c) => `${c.id}: ${c.from} → ${c.to}`).join('; ')}`).join('\n') : 'no design approval in that state');
+    return;
+  }
+  // A person committed what an apply wrote (the /pilot-approve skill asks first): the approval says so, with the commit.
+  if (sub === 'committed' && id) {
+    await h.approvals.setStatus({ id, status: 'committed', ...(flags.commit ? { commit: String(flags.commit) } : {}) });
+    print(`${id}: committed${flags.commit ? ` (${flags.commit})` : ''}`);
+    return;
+  }
+  if (sub !== 'apply' || !id) fail('approvals list [--status approved|applied|committed|rejected] [--branch b] | approvals apply <DA-…> [--dry-run] | approvals committed <DA-…> [--commit <sha>]');
+  const a = await h.approvals.get(id);
+  if (a.status !== 'approved' && !flags.again) fail(`${id} is ${a.status}, not approved (--again to apply it once more)`);
+  if (a.branch && h.branch && a.branch !== h.branch) process.stderr.write(`g9pilot: ${id} was approved on ${a.branch}; this checkout is on ${h.branch}\n`);
+  const sets = tokenSets(config, path.dirname(path.resolve(configPath)));
+  const result = tokensApprove(sets, { changes: a.changes }, { dryRun: flags['dry-run'] === true, ...approveFollowUps() });
+  print(result);
+  if (flags['dry-run']) return;
+  await h.approvals.setStatus({ id, status: 'applied', files: result.files, tokens: result.changed.length, modules: result.generated.length });
+  print(`${id}: applied (the files changed; nothing is committed)`);
+}
+
+/** A signing proxy: the unchanged runner (protocol 1, unsigned) talks to --listen; the device gets signed requests. */
+function proxy() {
+  const listen = Number(flags.listen ?? 8799);
+  const target = String(flags.target ?? 'http://127.0.0.1:18799').replace(/\/+$/, '');
+  const k = key();
+  const client = new PilotClient({ base: target, privateKey: k.key, kid });
+  const tally = recorder('proxy', target);
+  const server = http.createServer(async (req, res) => {
+    const t0 = Date.now();
+    const chunks = [];
+    for await (const c of req) chunks.push(c);
+    const body = Buffer.concat(chunks).toString('utf8');
+    const reqPath = (req.url ?? '/').split('?')[0];
+    try {
+      let headers = {};
+      const open = req.method === 'GET' && (reqPath === '/' || reqPath === '/qa' || reqPath === '/pilot');
+      if (!open) {
+        const hello = client.helloCache ?? (await client.hello());
+        headers = signRequest({ privateKey: k.key, kid: kid ?? hello.kids?.[0], appId: hello.app, method: req.method, path: reqPath, body, now: Date.now() + Math.round(client.offsetMs) });
+      }
+      const send = (h) =>
+        fetch(`${target}${req.url}`, {
+          method: req.method,
+          headers: { 'content-type': req.headers['content-type'] ?? 'application/json', ...(req.headers['last-event-id'] ? { 'last-event-id': req.headers['last-event-id'] } : {}), ...h },
+          body: req.method === 'GET' ? undefined : body,
+        });
+      let upstream = await send(headers);
+      // The device clock moved (a restored emulator snapshot, a phone that slept): correct from the time it reports and
+      // send once more, as the client does — a proxy that did not left every request of the session refused.
+      if (!open && upstream.status === 401) {
+        const refused = await upstream.clone().json().catch(() => null);
+        if (refused?.code === 'CLOCK_SKEW' && typeof refused.deviceTime === 'number') {
+          client.offsetMs = refused.deviceTime - Date.now();
+          const hello = client.helloCache ?? (await client.hello());
+          const again = signRequest({ privateKey: k.key, kid: kid ?? hello.kids?.[0], appId: hello.app, method: req.method, path: reqPath, body, now: Date.now() + Math.round(client.offsetMs) });
+          upstream = await send(again);
+        }
+      }
+      if (open) {
+        // The hello says what a client behind the proxy needs: no token and no signature of its own (the proxy signs —
+        // a client that read `signatureRequired` used to look for a key it does not need, and failed without one).
+        const hello = await upstream.json();
+        client.helloCache = hello;
+        if (typeof hello.deviceTime === 'number') client.offsetMs = hello.deviceTime - Date.now();
+        res.writeHead(upstream.status, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ...hello, tokenRequired: false, signatureRequired: false, signedBy: 'g9pilot proxy' }));
+        return;
+      }
+      // The session's record: a command's name and how it ended (never its arguments or its answer).
+      const command = req.method === 'POST' && (reqPath === '/qa' || reqPath === '/pilot') ? (() => { try { return JSON.parse(body).command; } catch { return null; } })() : null;
+      const verdict = command || upstream.status === 401 ? upstream.clone().json().catch(() => null) : null;
+      res.writeHead(upstream.status, { 'content-type': upstream.headers.get('content-type') ?? 'application/json' });
+      if (upstream.body) for await (const chunk of upstream.body) res.write(chunk);
+      res.end();
+      const answer = await verdict;
+      if (upstream.status === 401) tally.refused(answer?.code ?? 'REFUSED');
+      else if (command) { tally.hello(client.helloCache); tally.record(command, { ok: upstream.ok && answer?.ok !== false, ms: Date.now() - t0 }); }
+      if (upstream.status === 401) client.helloCache = null; // a key or clock change: read the hello again next time
+    } catch (e) {
+      res.writeHead(502, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: `g9pilot proxy: the device at ${target} did not answer (${e.message})`, code: 'PROXY_UPSTREAM', category: 'automation' }));
+    }
+  });
+  server.listen(listen, '127.0.0.1', () => process.stderr.write(`g9pilot proxy: 127.0.0.1:${listen} → ${target} (key ${k.source})\n`));
+}
+
+/**
+ * The relay for the devices attached to this machine. It holds no key: a signed request passes through unchanged (the
+ * signature covers the device's path, `/qa`, which is what the device receives). Android devices are reached through
+ * `adb forward` (a local port per serial, made on first use); a booted simulator shares this machine's loopback, so it is
+ * named in "hostDevices" with its URL. Server-Sent Events stream through.
+ */
+function host() {
+  const listen = Number(flags.listen ?? 47900);
+  const bind = String(flags.bind ?? '127.0.0.1');
+  const token = process.env[String(flags['token-env'] ?? 'G9PILOT_HOST_TOKEN')] ?? '';
+  const loopback = bind === '127.0.0.1' || bind === '::1' || bind === 'localhost';
+  if (!loopback && token.length < 16) fail(`host: binding ${bind} needs a token of at least 16 characters (G9PILOT_HOST_TOKEN or --token-env).`);
+  const devicePort = Number(flags['device-port'] ?? config.devicePort ?? 8799);
+  const adb = String(flags.adb ?? process.env.ADB ?? 'adb');
+  const forwards = new Map();
+  let nextPort = Number(flags['forward-base'] ?? listen + 10);
+
+  const adbSerials = () => {
+    try {
+      return execFileSync(adb, ['devices'], { encoding: 'utf8', timeout: 10_000 })
+        .split('\n')
+        .slice(1)
+        .map((l) => l.trim().split(/\s+/))
+        .filter((p) => p[1] === 'device')
+        .map((p) => p[0]);
+    } catch {
+      return [];
+    }
+  };
+  const fixed = () => config.hostDevices ?? [];
+  const devices = () => [...adbSerials().map((serial) => ({ name: serial, kind: 'android' })), ...fixed().map((d) => ({ name: d.name, kind: d.kind ?? 'url' }))];
+  const urlFor = (name) => {
+    const f = fixed().find((d) => d.name === name);
+    if (f) return String(f.url).replace(/\/+$/, '');
+    if (!adbSerials().includes(name)) return null;
+    let port = forwards.get(name);
+    if (!port) {
+      port = nextPort++;
+      execFileSync(adb, ['-s', name, 'forward', `tcp:${port}`, `tcp:${devicePort}`], { timeout: 10_000 });
+      forwards.set(name, port);
+    }
+    return `http://127.0.0.1:${port}`;
+  };
+  const deny = (res, status, code, error) => {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ ok: false, error, code, category: 'auth' }));
+  };
+  // A shared device is reserved before it is handed out (plan v2 P1-14): g9pilot.json "reserve": {hold: [cmd…],
+  // release: [cmd…], idleMinutes, resources?} with {device} {resource} {minutes} {id} filled in — whoever runs the lab names its own booking
+  // (this tool knows none). The id the hold prints (`"id":"…"` or the last word) is what release gets; a refused hold
+  // answers 423 with the booking tool's own words; idle devices (and all of them when the host stops) are released.
+  const reserve = config.reserve?.hold ? config.reserve : null;
+  const holds = new Map();
+  const idleMs = Number(reserve?.idleMinutes ?? 15) * 60_000;
+  const runReserve = (cmd, vars) => {
+    const [file, ...args] = cmd.map((x) => String(x).replace(/\{(\w+)\}/g, (_, k) => String(vars[k] ?? '')));
+    try {
+      return { ok: true, out: execFileSync(file === 'node' ? process.execPath : file, args, { encoding: 'utf8', timeout: 60_000 }) };
+    } catch (e) {
+      return { ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`.trim() || e.message };
+    }
+  };
+  const hold = (name) => {
+    if (!reserve) return null;
+    const known = holds.get(name);
+    if (known) {
+      known.lastUse = Date.now();
+      return null;
+    }
+    // {resource}: what the booking calls this device — reserve.resources[name], the fixed device's own `resource`,
+    // reserve.resources['*'], else its name.
+    const resource = reserve.resources?.[name] ?? fixed().find((d) => d.name === name)?.resource ?? (config.devices ?? []).find((d) => d.name === name)?.resource ?? reserve.resources?.['*'] ?? name;
+    const r = runReserve(reserve.hold, { device: name, resource, minutes: Math.ceil(idleMs / 60_000) + 5 });
+    if (!r.ok) return `The device ${name} could not be reserved: ${r.out.slice(-300)}`;
+    const id = /"id"\s*:\s*\\?"([^"\\]+)/.exec(r.out)?.[1] ?? r.out.trim().split(/\s+/).pop();
+    holds.set(name, { id, lastUse: Date.now() });
+    process.stderr.write(`g9pilot host: ${name} reserved (${id})\n`);
+    return null;
+  };
+  const release = (name) => {
+    const h = holds.get(name);
+    if (!h) return;
+    holds.delete(name);
+    if (reserve.release) runReserve(reserve.release, { device: name, id: h.id });
+    process.stderr.write(`g9pilot host: ${name} released (${h.id})\n`);
+  };
+  if (reserve) {
+    setInterval(() => {
+      for (const [name, h] of holds) if (Date.now() - h.lastUse > idleMs) release(name);
+    }, Math.min(30_000, idleMs)).unref();
+    const stop = () => {
+      for (const name of [...holds.keys()]) release(name);
+      process.exit(0);
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+  }
+
+  const server = http.createServer(async (req, res) => {
+    if (token && req.headers['x-g9p-host-token'] !== token) return deny(res, 401, 'HOST_TOKEN', 'This relay needs its token (x-g9p-host-token).');
+    const [pathOnly, query = ''] = (req.url ?? '/').split('?');
+    if (pathOnly === '/devices') {
+      const list = [];
+      for (const d of devices()) {
+        let hello = null;
+        try {
+          const u = urlFor(d.name);
+          hello = u ? await (await fetch(`${u}/qa`, { signal: AbortSignal.timeout(2500) })).json() : null;
+        } catch {
+          hello = null;
+        }
+        list.push({ ...d, bridge: hello ? { app: hello.app, protocol: hello.protocol, jsReady: hello.jsReady, signatureRequired: hello.signatureRequired } : null });
+      }
+      res.writeHead(200, { 'content-type': 'application/json' });
+      return res.end(JSON.stringify({ ok: true, devices: list }));
+    }
+    const m = pathOnly.match(/^\/d\/([^/]+)(\/.*)$/);
+    if (!m) return deny(res, 404, 'NOT_FOUND', 'Paths: /devices, /d/<device>/qa, /d/<device>/pilot, /d/<device>/pilot/events.');
+    const name = decodeURIComponent(m[1]);
+    let target;
+    try {
+      target = urlFor(name);
+    } catch (e) {
+      return deny(res, 502, 'HOST_FORWARD', `adb forward for ${name} failed: ${e.message}`);
+    }
+    if (!target) return deny(res, 404, 'NO_DEVICE', `No device "${name}" on this host.`);
+    const refused = hold(name);
+    if (refused) return deny(res, 423, 'DEVICE_RESERVED', refused);
+    const chunks = [];
+    for await (const c of req) chunks.push(c);
+    const headers = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+      if ((k.startsWith('x-g9p-') && k !== 'x-g9p-host-token') || k === 'content-type' || k === 'accept' || k === 'last-event-id') headers[k] = v;
+    }
+    const ctrl = new AbortController();
+    res.on('close', () => ctrl.abort());
+    try {
+      const upstream = await fetch(`${target}${m[2]}${query ? `?${query}` : ''}`, {
+        method: req.method,
+        headers,
+        body: req.method === 'GET' || req.method === 'HEAD' ? undefined : Buffer.concat(chunks),
+        signal: ctrl.signal,
+      });
+      res.writeHead(upstream.status, { 'content-type': upstream.headers.get('content-type') ?? 'application/json', 'cache-control': 'no-cache' });
+      if (upstream.body) for await (const chunk of upstream.body) res.write(chunk);
+      res.end();
+    } catch (e) {
+      if (!ctrl.signal.aborted) deny(res, 502, 'HOST_UPSTREAM', `The device ${name} did not answer (${e.message}).`);
+    }
+  });
+  server.listen(listen, bind, () => process.stderr.write(`g9pilot host: ${bind}:${listen}${token ? ' (token required)' : ''}; devices: ${devices().map((d) => d.name).join(', ') || 'none yet'}\n`));
+}
+
+/**
+ * Live development. The page's dev server runs on THIS machine; each device reaches it on its own loopback (`adb reverse`
+ * on Android, the Mac's loopback for a simulator), so the bundle's HMR client, which connects back to the URL it was
+ * built with, finds it too. The bridge command `dev.server` (admin: it changes what code runs) points the app at it.
+ */
+async function dev() {
+  const port = Number(flags.port ?? config.dev?.port ?? 3000);
+  const bundle = String(flags.bundle ?? config.dev?.bundle ?? 'main.lynx.bundle');
+  const cwd = path.resolve(String(flags.cwd ?? config.dev?.cwd ?? '.'));
+  const command = String(flags.cmd ?? config.dev?.cmd ?? 'npm run dev');
+  const bundleUrl = `http://127.0.0.1:${port}/${bundle}`;
+  const k = key();
+  const client = clientFor({ privateKey: k.key });
+  const log = (line) => process.stderr.write(`g9pilot dev: ${line}\n`);
+
+  const { spawn } = await import('node:child_process');
+  const server = spawn(command, { cwd, shell: true, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, G9PILOT_DEV_PORT: String(port) } });
+  const relayOut = (stream, out) => stream.on('data', (d) => out.write(String(d).replace(/^/gm, '  │ ')));
+  relayOut(server.stdout, process.stdout);
+  relayOut(server.stderr, process.stderr);
+  // --watch-flows [target] (plan v2 P1-14): after every rebuild the dev server reports (its own «built / compiled /
+  // ready» line, `dev.rebuilt` in g9pilot.json to name another), the app takes the hot update, settles, and the runner
+  // replays the flows (default `tag:@smoke`) — a change that breaks a basic path says so within seconds of the save.
+  const watchTarget = flags['watch-flows'] ? (flags['watch-flows'] === true ? 'tag:@smoke' : String(flags['watch-flows'])) : null;
+  if (watchTarget) {
+    const runner = config.runner?.path ? config.runner : null;
+    if (!runner) fail('--watch-flows needs a runner (g9pilot.json "runner": {path, args}).');
+    const rebuilt = new RegExp(config.dev?.rebuilt ?? '(built|compiled|rebuilt|ready) in [\\d.]+ ?m?s', 'i');
+    let timer = null;
+    let running = false;
+    let again = false;
+    let first = true;
+    const replay = async () => {
+      if (running) {
+        again = true;
+        return;
+      }
+      running = true;
+      const t0 = Date.now();
+      // A change the hot update cannot take reloads the whole page: wait for the page to declare itself again (the
+      // hello's jsReady), then for it to settle — the first try ran the flow into «the page has not called ready()».
+      for (const until = Date.now() + 45_000; Date.now() < until; ) {
+        const hello = await fetch(`${url}/qa`, { signal: AbortSignal.timeout(2000) }).then((r) => r.json()).catch(() => null);
+        if (hello?.jsReady) break;
+        await new Promise((r) => setTimeout(r, 500));
+      }
+      await clientFor({ privateKey: key().key }).call('ui.waitIdle', {}, { timeoutMs: 20_000 }).catch(() => null);
+      const { spawn: spawnRun } = await import('node:child_process');
+      // Each replay's report in its own temporary folder — never the runner's default beside the project.
+      const reportDir = fs.mkdtempSync(path.join((await import('node:os')).tmpdir(), 'g9pilot-watch-'));
+      const child = spawnRun(process.execPath, [runner.path, 'run', watchTarget, ...(runner.args ?? []), '--quiet', '--report', reportDir], { stdio: ['ignore', 'pipe', 'pipe'] });
+      let out = '';
+      child.stdout.on('data', (d) => (out += d));
+      child.stderr.on('data', (d) => (out += d));
+      child.on('close', (code) => {
+        const summary = out.trim().split(/\r?\n/).filter(Boolean).slice(-2).join(' · ');
+        process.stderr.write(`g9pilot dev: ${code === 0 ? '✓' : '✗'} ${watchTarget} after the change — ${summary} (${Math.round((Date.now() - t0) / 100) / 10} s)\n`);
+        running = false;
+        if (again) {
+          again = false;
+          void replay();
+        }
+      });
+    };
+    const onLine = (d) => {
+      if (!rebuilt.test(String(d))) return;
+      if (first) {
+        first = false; // the first build is the one the app loads at start, not a change
+        return;
+      }
+      clearTimeout(timer);
+      timer = setTimeout(() => void replay(), Number(config.dev?.settleMs ?? 2500));
+    };
+    server.stdout.on('data', onLine);
+    server.stderr.on('data', onLine);
+  }
+  server.on('exit', (code) => {
+    log(`the dev server stopped (${code})`);
+    process.exit(code ?? 1);
+  });
+
+  const deadline = Date.now() + Number(flags.timeout ?? 180_000);
+  for (;;) {
+    const ok = await fetch(bundleUrl, { method: 'HEAD', signal: AbortSignal.timeout(2000) })
+      .then((r) => r.ok)
+      .catch(() => false);
+    if (ok) break;
+    if (Date.now() > deadline) {
+      server.kill();
+      fail(`the dev server did not serve ${bundleUrl} in time`);
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  log(`serving ${bundleUrl}`);
+
+  const adb = String(flags.adb ?? process.env.ADB ?? 'adb');
+  let serials = flags.serial ? [String(flags.serial)] : [];
+  if (!serials.length) {
+    try {
+      serials = execFileSync(adb, ['devices'], { encoding: 'utf8', timeout: 10_000 })
+        .split('\n')
+        .slice(1)
+        .map((l) => l.trim().split(/\s+/))
+        .filter((p) => p[1] === 'device')
+        .map((p) => p[0]);
+    } catch {
+      serials = [];
+    }
+  }
+  for (const serial of serials) {
+    try {
+      execFileSync(adb, ['-s', serial, 'reverse', `tcp:${port}`, `tcp:${port}`], { timeout: 10_000 });
+      log(`${serial}: adb reverse tcp:${port}`);
+    } catch (e) {
+      log(`${serial}: adb reverse failed (${e.message})`);
+    }
+  }
+  // A reverse port can vanish mid-session (another tool restarts the adb server: 2026-11-05 the app then failed «Fetch
+  // template resource failed … no bundle»). Put it back whenever it is gone, every 5 s, quietly.
+  const keepReverse = setInterval(() => {
+    for (const serial of serials) {
+      try {
+        const list = execFileSync(adb, ['-s', serial, 'reverse', '--list'], { encoding: 'utf8', timeout: 5_000 });
+        if (!list.includes(`tcp:${port}`)) {
+          execFileSync(adb, ['-s', serial, 'reverse', `tcp:${port}`, `tcp:${port}`], { timeout: 5_000 });
+          log(`${serial}: adb reverse tcp:${port} was gone — set again`);
+        }
+      } catch {
+        // the device went away; the next round tries again
+      }
+    }
+  }, 5_000);
+  keepReverse.unref?.();
+
+  const point = async (url) => {
+    const answer = await client.call('dev.server', { url }, { timeoutMs: 20_000 });
+    if (!answer?.ok) log(`dev.server: ${answer?.code ?? ''} ${answer?.error ?? JSON.stringify(answer)}`);
+    return answer;
+  };
+  const answer = await point(bundleUrl);
+  if (answer?.ok) log(`the app loads ${bundleUrl}: save a file and it changes in place${watchTarget ? `, then ${watchTarget} replays` : ''} (Ctrl+C ends).`);
+
+  let ending = false;
+  const end = async () => {
+    if (ending) return;
+    ending = true;
+    if (!flags.keep) {
+      await point(null).catch(() => undefined);
+      log('the app is back on its own bundle');
+    }
+    server.kill();
+    process.exit(0);
+  };
+  process.on('SIGINT', end);
+  process.on('SIGTERM', end);
+}
+
+/**
+ * Level 0 of a savepoint: an Android emulator's own snapshot (the app, its data, the OS, the clock), through the emulator
+ * console (`adb emu avd snapshot …`). A real phone or a simulator has no such thing: level 1 (the app's data) is for them.
+ */
+function savepoint([sub, name]) {
+  const adb = String(flags.adb ?? process.env.ADB ?? 'adb');
+  const serial = String(flags.serial ?? 'emulator-5554');
+  if (flags.level === 'app' && (flags.via === 'bridge' || flags.device)) return bridgeAppSavepoint(sub, name);
+  if (flags.level === 'app' && flags.simulator) return simulatorAppSavepoint(String(flags.simulator), sub, name);
+  if (flags.simulator) return simulatorSavepoint(String(flags.simulator), sub, name);
+  if (flags.level === 'app') return appSavepoint(adb, serial, sub, name);
+  if (!serial.startsWith('emulator-')) fail(`savepoint: ${serial} is not an emulator — level 0 exists only on an Android emulator.`);
+  const emu = (args, timeout = 180_000) => execFileSync(adb, ['-s', serial, 'emu', 'avd', 'snapshot', ...args], { encoding: 'utf8', timeout }).trim();
+  const named = () => {
+    if (!name || !/^[A-Za-z0-9._-]{1,64}$/.test(name)) fail('savepoint needs a name: letters, digits, . _ - (at most 64).');
+    return name;
+  };
+  const started = Date.now();
+  const report = (what, out) => {
+    const failed = /KO|error|fail/i.test(out);
+    print({ ok: !failed, what, name: name ?? null, serial, ms: Date.now() - started, ...(flags.clockNote ? { clock: flags.clockNote } : {}), ...(flags.gpuNote ? { note: flags.gpuNote } : {}), emulator: out.split(/\r?\n/).filter((l) => l && l !== 'OK').slice(0, 6) });
+    process.exitCode = failed ? 1 : 0;
+  };
+  switch (sub) {
+    case 'save':
+      return report('saved', emu(['save', named()]));
+    case 'load': {
+      const out = emu(['load', named()]);
+      // The emulator drops off adb while it swaps its state, and the forwards with it (measured: «device offline», the
+      // bridge unreachable until a new forward): wait for it, then make them again (--forward 8797[,8798]).
+      try {
+        execFileSync(adb, ['-s', serial, 'wait-for-device'], { timeout: 60_000 });
+      } catch {
+        // reported by the caller's next command
+      }
+      // The snapshot brings its own clock back (measured: 191 s behind after a 3-minute-old snapshot). Asked to sync from
+      // the network, else set with su (an image that has it); a Play image has neither — then the offset is reported, and
+      // the bridge's clients correct for it (CLOCK_SKEW → deviceTime). A token the server issued may still look old.
+      let clock = 'unknown';
+      try {
+        const now = Math.floor(Date.now() / 1000);
+        execFileSync(adb, ['-s', serial, 'shell', `cmd network_time_update_service force_refresh >/dev/null 2>&1; su 0 toybox date -u @${now} >/dev/null 2>&1; true`], { timeout: 20_000 });
+        const after = Number(execFileSync(adb, ['-s', serial, 'shell', 'date +%s'], { encoding: 'utf8', timeout: 10_000 }).trim());
+        const behind = Math.round(Date.now() / 1000 - after);
+        clock = Math.abs(behind) <= 5 ? 'in step with this machine' : `${behind} s behind this machine (no network time and no su on this image; clients correct for it)`;
+      } catch {
+        clock = 'unknown';
+      }
+      flags.clockNote = clock;
+      for (const port of String(flags.forward ?? '').split(',').filter(Boolean)) {
+        try {
+          execFileSync(adb, ['-s', serial, 'forward', `tcp:${port}`, `tcp:${port}`], { timeout: 15_000 });
+        } catch {
+          // ditto
+        }
+      }
+      flags.gpuNote = 'A restored snapshot does not always bring the GPU back: on a host-GPU emulator a GL-heavy app (a map) has taken the emulator down at its next draw. Use --level app for such an app: it is also about twice as fast (measured 19 s / 11 s against 43 s / 25 s on a 3 GB emulator).';
+      return report('loaded', out);
+    }
+    case 'delete':
+      return report('deleted', emu(['delete', named()]));
+    case 'list':
+      return report('list', emu(['list'], 30_000));
+    default:
+      fail('savepoint save|load|list|delete <name> [--serial emulator-5554]');
+  }
+}
+
+/**
+ * Level 1 of a savepoint: the app's own data folder (`run-as`, so a debuggable build), streamed to
+ * `<dir>/<package>/<name>.tar` on this machine and back. The app is stopped before either, so no database is copied
+ * half-written; after a load it starts from that data. Works on a real phone as on an emulator.
+ */
+/**
+ * Beside a level-1 savepoint `<name>.tar`: `<name>.meta.json` — when, what, from where, and the SERVER its data belongs
+ * to (plan v2 P1-11: `--server <database or environment>` and `--server-commit <sha>`, given by whoever knows them — a
+ * runner, a test hub, a person). An app's data names rows a server holds: loaded against another server it may mean
+ * nothing, so the pair is written down. Returns the metadata.
+ */
+function writeSavepointMeta(file, meta) {
+  const full = {
+    format: 'g9pilot/savepoint-meta',
+    at: new Date().toISOString(),
+    ...meta,
+    server: flags.server || flags['server-commit'] ? { name: flags.server ? String(flags.server) : null, commit: flags['server-commit'] ? String(flags['server-commit']) : null } : null,
+  };
+  fs.writeFileSync(file.replace(/\.tar$/, '.meta.json'), JSON.stringify(full, null, 2));
+  return full;
+}
+
+/** The entry names of a tar (ustar headers, 512-byte blocks): enough to prove what a savepoint holds. */
+export function tarEntries(buf) {
+  const names = [];
+  let at = 0;
+  while (at + 512 <= buf.length) {
+    const header = buf.subarray(at, at + 512);
+    if (header.every((b) => b === 0)) break;
+    const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/s, '');
+    const prefix = header.subarray(345, 500).toString('utf8').replace(/\0.*$/s, '');
+    const size = parseInt(header.subarray(124, 136).toString('utf8').replace(/\0.*$/s, '').trim() || '0', 8);
+    const type = String.fromCharCode(header[156] || 48);
+    if (type !== 'L' && type !== 'x' && type !== 'g') names.push(prefix ? `${prefix}/${name}` : name);
+    at += 512 + Math.ceil(size / 512) * 512;
+  }
+  return names;
+}
+
+async function appSavepoint(adb, serial, sub, name) {
+  const pkg = flags.package;
+  if (!pkg || !/^[A-Za-z][\w]*(\.[A-Za-z][\w]*)+$/.test(String(pkg))) fail('--level app needs --package <application id>.');
+  const dir = path.resolve(String(flags.dir ?? path.join(process.env.HOME ?? process.env.USERPROFILE ?? '.', '.g9pilot', 'savepoints')), String(pkg));
+  fs.mkdirSync(dir, { recursive: true });
+  if (sub === 'list') {
+    print({ ok: true, dir, savepoints: fs.readdirSync(dir).filter((f) => f.endsWith('.tar')).map((f) => ({ name: f.slice(0, -4), bytes: fs.statSync(path.join(dir, f)).size })) });
+    return;
+  }
+  if (!name || !/^[A-Za-z0-9._-]{1,64}$/.test(name)) fail('savepoint needs a name: letters, digits, . _ - (at most 64).');
+  const file = path.join(dir, `${name}.tar`);
+  const { spawnSync } = await import('node:child_process');
+  const started = Date.now();
+  spawnSync(adb, ['-s', serial, 'shell', 'am', 'force-stop', pkg], { timeout: 20_000 });
+  // Only what the app owns and needs again: not its caches (any path with «cache» in it), not the code cache. A cache
+  // folder may also be out of run-as's reach (SELinux; measured on API 36: `d?????????`), and toybox tar STOPS at the
+  // first unreadable entry — the first savepoint lost shared_prefs (the session) that way and still said «saved».
+  const parts = 'files databases shared_prefs no_backup';
+  const keep = `$(ls -d ${parts} 2>/dev/null)`;
+  if (sub === 'save') {
+    const r = spawnSync(adb, ['-s', serial, 'exec-out', `run-as ${pkg} sh -c 'cd /data/data/${pkg} && tar -cf - --exclude="*cache*" ${keep}'`], { maxBuffer: 2 * 1024 ** 3, timeout: 10 * 60_000 });
+    if (r.status !== 0 || !r.stdout?.length) fail(`savepoint save: run-as failed (${String(r.stderr || '').trim().slice(0, 200) || 'no data'}) — a debuggable build is needed.`);
+    // Proof, not hope: the tar holds every entry the device has (the same selection).
+    const listed = spawnSync(adb, ['-s', serial, 'shell', `run-as ${pkg} sh -c 'cd /data/data/${pkg} && find ${keep} ! -path "*cache*" 2>/dev/null | wc -l'`], { encoding: 'utf8', timeout: 60_000 });
+    const onDevice = Number(String(listed.stdout).trim());
+    const inTar = tarEntries(r.stdout);
+    if (Number.isFinite(onDevice) && inTar.length < onDevice) {
+      fail(`savepoint save: the tar holds ${inTar.length} of ${onDevice} entries — the device refused part of the app's data (last in the tar: ${inTar.at(-1) ?? 'none'}). Nothing was saved.`);
+    }
+    fs.writeFileSync(file, r.stdout);
+    const meta = writeSavepointMeta(file, { level: 'app', name, package: pkg, serial, entries: inTar.length, bytes: r.stdout.length });
+    print({ ok: true, what: 'saved', level: 'app', name, package: pkg, serial, file, bytes: r.stdout.length, entries: inTar.length, server: meta.server, ms: Date.now() - started });
+    return;
+  }
+  if (sub === 'load') {
+    if (!fs.existsSync(file)) fail(`No savepoint ${name} for ${pkg} in ${dir}.`);
+    const clear = `run-as ${pkg} sh -c 'cd /data/data/${pkg} && rm -rf ${parts}'`;
+    spawnSync(adb, ['-s', serial, 'shell', clear], { timeout: 60_000 });
+    const tar = fs.readFileSync(file);
+    const r = spawnSync(adb, ['-s', serial, 'exec-in', `run-as ${pkg} sh -c 'cd /data/data/${pkg} && tar -xf -'`], { input: tar, timeout: 10 * 60_000 });
+    if (r.status !== 0) fail(`savepoint load: ${String(r.stderr || '').trim().slice(0, 200)}`);
+    const expected = tarEntries(tar).length;
+    const listed = spawnSync(adb, ['-s', serial, 'shell', `run-as ${pkg} sh -c 'cd /data/data/${pkg} && find ${keep} ! -path "*cache*" 2>/dev/null | wc -l'`], { encoding: 'utf8', timeout: 60_000 });
+    const onDevice = Number(String(listed.stdout).trim());
+    if (Number.isFinite(onDevice) && onDevice < expected) fail(`savepoint load: ${onDevice} of ${expected} entries arrived on the device — load it again.`);
+    print({ ok: true, what: 'loaded', level: 'app', name, package: pkg, serial, bytes: fs.statSync(file).size, ms: Date.now() - started, next: 'start the app' });
+    return;
+  }
+  fail('savepoint save|load|list <name> --level app --package <id>');
+}
+
+/**
+ * Level 0 on the iOS simulator (plan v2 P1-10, research R5): the WHOLE device — every app, its data, the keychain, the
+ * settings. Save = shut down + `simctl clone` (APFS copy-on-write: seconds, little disk). simctl cannot restore INTO a
+ * device and a clone has its own UDID, so load = shut down + the clone's `data` folder copied back over the original's
+ * with APFS clones (`cp -c`) + boot: the device keeps its UDID, which the lab and every flow name. Run on the Mac.
+ */
+async function simulatorSavepoint(udid, sub, name) {
+  const { spawnSync } = await import('node:child_process');
+  const os = await import('node:os');
+  const devices = path.join(os.homedir(), 'Library', 'Developer', 'CoreSimulator', 'Devices');
+  const prefix = `g9pilot-sp:${udid.slice(0, 8)}:`;
+  const all = () => JSON.parse(run('xcrun', ['simctl', 'list', 'devices', '--json'])).devices;
+  const clones = () => Object.values(all()).flat().filter((d) => String(d.name).startsWith(prefix)).map((d) => ({ name: d.name.slice(prefix.length), udid: d.udid }));
+  const state = () => Object.values(all()).flat().find((d) => d.udid === udid)?.state ?? null;
+  if (!state()) fail(`No simulator ${udid}.`);
+  if (sub === 'list') return print({ ok: true, level: 0, simulator: udid, savepoints: clones() });
+  if (!name || !/^[A-Za-z0-9._-]{1,48}$/.test(name)) fail('savepoint needs a name: letters, digits, . _ - (at most 48).');
+  const started = Date.now();
+  const shutdown = () => {
+    if (state() !== 'Shutdown') spawnSync('xcrun', ['simctl', 'shutdown', udid], { timeout: 120_000 });
+  };
+  const boot = () => {
+    spawnSync('xcrun', ['simctl', 'boot', udid], { timeout: 120_000 });
+    spawnSync('xcrun', ['simctl', 'bootstatus', udid, '-b'], { timeout: 300_000 });
+  };
+  const existing = clones().find((c) => c.name === name);
+  if (sub === 'save') {
+    const wasBooted = state() === 'Booted';
+    shutdown();
+    const t0 = Date.now();
+    if (existing) spawnSync('xcrun', ['simctl', 'delete', existing.udid], { timeout: 120_000 });
+    const r = spawnSync('xcrun', ['simctl', 'clone', udid, `${prefix}${name}`], { encoding: 'utf8', timeout: 600_000 });
+    if (r.status !== 0) fail(`simctl clone: ${String(r.stderr).trim().slice(0, 300)}`);
+    const cloneMs = Date.now() - t0;
+    if (wasBooted) boot();
+    return print({ ok: true, what: 'saved', level: 0, simulator: udid, name, clone: String(r.stdout).trim(), cloneMs, ms: Date.now() - started, rebooted: wasBooted });
+  }
+  if (sub === 'load') {
+    if (!existing) fail(`No level-0 savepoint ${name} of ${udid} (g9pilot savepoint list --simulator ${udid}).`);
+    shutdown();
+    const t0 = Date.now();
+    const dst = path.join(devices, udid, 'data');
+    const src = path.join(devices, existing.udid, 'data');
+    if (!fs.existsSync(src)) fail(`The clone's data folder is missing: ${src}`);
+    // Beside the original, never over it: the swap happens only after a good copy (the first try removed the original
+    // first and a refused file left the lab simulator with a partial copy — 2026-11-04). Some of the simulator's own
+    // caches cannot be copied by a user (Library/Caches/locationd: «Operation not permitted»); they rebuild themselves,
+    // so a refusal there is accepted — anywhere else the load stops and the device stays as it was.
+    const fresh = `${dst}.g9new`;
+    const old = `${dst}.g9old`;
+    fs.rmSync(fresh, { recursive: true, force: true });
+    const r = spawnSync('cp', ['-cRp', src, fresh], { encoding: 'utf8', timeout: 600_000, maxBuffer: 64 * 1024 * 1024 });
+    const refused = String(r.stderr ?? '').split('\n').filter(Boolean);
+    const serious = refused.filter((l) => !/\/data\/Library\/Caches\//.test(l));
+    if (!fs.existsSync(fresh) || serious.length) {
+      fs.rmSync(fresh, { recursive: true, force: true });
+      fail(`cp -c refused ${serious.length} file(s) outside the caches; the device is unchanged: ${serious.slice(0, 3).join(' | ').slice(0, 400)}`);
+    }
+    fs.rmSync(old, { recursive: true, force: true });
+    fs.renameSync(dst, old);
+    fs.renameSync(fresh, dst);
+    fs.rmSync(old, { recursive: true, force: true });
+    const copyMs = Date.now() - t0;
+    const t1 = Date.now();
+    boot();
+    return print({ ok: true, what: 'loaded', level: 0, simulator: udid, name, copyMs, cachesSkipped: refused.length, bootMs: Date.now() - t1, ms: Date.now() - started, next: 'start the app' });
+  }
+  if (sub === 'delete') {
+    if (!existing) fail(`No level-0 savepoint ${name} of ${udid}.`);
+    spawnSync('xcrun', ['simctl', 'delete', existing.udid], { timeout: 120_000 });
+    return print({ ok: true, what: 'deleted', level: 0, simulator: udid, name });
+  }
+  fail('savepoint save|load|list|delete <name> --simulator <udid>');
+}
+
+/**
+ * Level 1 on the iOS simulator (plan v2 P1-08, research R5): the app's data container (`simctl get_app_container … data`)
+ * is a folder of this Mac, so it is a tar of Documents and Library — not Library/Caches, not the launch snapshots
+ * (SplashBoard), not tmp — to `<dir>/<bundle id>/<name>.tar` and back. The app is terminated first; after a load it
+ * starts from that data. The Keychain is not in the container: a session kept there stays as it is on this simulator.
+ */
+async function simulatorAppSavepoint(udid, sub, name) {
+  const bundle = flags.package ?? flags.bundle;
+  if (!bundle || !/^[A-Za-z][\w-]*(\.[A-Za-z][\w-]*)+$/.test(String(bundle))) fail('--level app --simulator <udid> needs --package <bundle id>.');
+  const dir = path.resolve(String(flags.dir ?? path.join(process.env.HOME ?? process.env.USERPROFILE ?? '.', '.g9pilot', 'savepoints')), String(bundle));
+  fs.mkdirSync(dir, { recursive: true });
+  if (sub === 'list') {
+    print({ ok: true, dir, savepoints: fs.readdirSync(dir).filter((f) => f.endsWith('.tar')).map((f) => ({ name: f.slice(0, -4), bytes: fs.statSync(path.join(dir, f)).size })) });
+    return;
+  }
+  if (!name || !/^[A-Za-z0-9._-]{1,64}$/.test(name)) fail('savepoint needs a name: letters, digits, . _ - (at most 64).');
+  const file = path.join(dir, `${name}.tar`);
+  const { spawnSync } = await import('node:child_process');
+  const started = Date.now();
+  const container = run('xcrun', ['simctl', 'get_app_container', udid, String(bundle), 'data']).trim();
+  if (!container || !fs.existsSync(container)) fail(`savepoint: ${bundle} is not installed on simulator ${udid}.`);
+  spawnSync('xcrun', ['simctl', 'terminate', udid, String(bundle)], { timeout: 20_000 });
+  const SKIP = ['Library/Caches', 'Library/SplashBoard', 'Library/Saved Application State'];
+  const skipped = (rel) => SKIP.some((x) => rel === x || rel.startsWith(`${x}/`));
+  // Every entry (folders too) the savepoint should hold — the proof both ways, as on Android.
+  const entries = () => {
+    const out = [];
+    const walk = (rel) => {
+      for (const e of fs.readdirSync(path.join(container, rel), { withFileTypes: true })) {
+        const r = `${rel}/${e.name}`;
+        if (skipped(r)) continue;
+        out.push(r);
+        if (e.isDirectory()) walk(r);
+      }
+    };
+    for (const top of ['Documents', 'Library']) {
+      if (!fs.existsSync(path.join(container, top))) continue;
+      out.push(top);
+      walk(top);
+    }
+    return out;
+  };
+  // Preferences live in cfprefsd: flush its copy into the file before the tar, and hand the file back to it after a
+  // load (a replaced plist alone can be overwritten by the cached domain).
+  const prefs = path.join(container, 'Library', 'Preferences', `${bundle}.plist`);
+  if (sub === 'save') {
+    // The app's domain is keyed by its file in the container (a bare bundle id is another domain outside it).
+    const flushed = path.join(container, 'tmp', `g9pilot-prefs-${process.pid}.plist`);
+    fs.mkdirSync(path.dirname(flushed), { recursive: true });
+    const ex = spawnSync('xcrun', ['simctl', 'spawn', udid, 'defaults', 'export', prefs.replace(/\.plist$/, ''), flushed], { timeout: 30_000 });
+    if (ex.status === 0 && fs.existsSync(flushed)) fs.copyFileSync(flushed, prefs);
+    fs.rmSync(flushed, { force: true });
+    const want = entries();
+    const r = spawnSync('tar', ['-cf', '-', '-C', container, ...SKIP.flatMap((x) => ['--exclude', x]), ...want.filter((x) => !x.includes('/'))], { maxBuffer: 2 * 1024 ** 3, timeout: 10 * 60_000, env: { ...process.env, COPYFILE_DISABLE: '1' } }); // no AppleDouble ._ files
+    if (r.status !== 0 || !r.stdout?.length) fail(`savepoint save: tar failed (${String(r.stderr || '').trim().slice(0, 200)})`);
+    const inTar = tarEntries(r.stdout);
+    if (inTar.length < want.length) fail(`savepoint save: the tar holds ${inTar.length} of ${want.length} entries. Nothing was saved.`);
+    fs.writeFileSync(file, r.stdout);
+    const meta = writeSavepointMeta(file, { level: 'app', name, package: bundle, simulator: udid, entries: inTar.length, bytes: r.stdout.length });
+    print({ ok: true, what: 'saved', level: 'app', name, package: bundle, simulator: udid, file, bytes: r.stdout.length, entries: inTar.length, server: meta.server, ms: Date.now() - started });
+    return;
+  }
+  if (sub === 'load') {
+    if (!fs.existsSync(file)) fail(`No savepoint ${name} for ${bundle} in ${dir}.`);
+    // Out with what the app has now (but the skipped caches), in with the savepoint.
+    for (const top of ['Documents', 'Library']) {
+      const at = path.join(container, top);
+      if (!fs.existsSync(at)) continue;
+      for (const e of fs.readdirSync(at)) if (!skipped(`${top}/${e}`)) fs.rmSync(path.join(at, e), { recursive: true, force: true });
+    }
+    const tar = fs.readFileSync(file);
+    const r = spawnSync('tar', ['-xf', '-', '-C', container], { input: tar, timeout: 10 * 60_000 });
+    if (r.status !== 0) fail(`savepoint load: ${String(r.stderr || '').trim().slice(0, 200)}`);
+    const expected = tarEntries(tar).length;
+    const now = entries().length;
+    if (now < expected) fail(`savepoint load: ${now} of ${expected} entries arrived — load it again.`);
+    if (fs.existsSync(prefs)) spawnSync('xcrun', ['simctl', 'spawn', udid, 'defaults', 'import', prefs.replace(/\.plist$/, ''), prefs], { timeout: 30_000 });
+    else spawnSync('xcrun', ['simctl', 'spawn', udid, 'defaults', 'delete', prefs.replace(/\.plist$/, '')], { timeout: 30_000 });
+    print({ ok: true, what: 'loaded', level: 'app', name, package: bundle, simulator: udid, bytes: tar.length, entries: expected, ms: Date.now() - started, next: 'start the app' });
+    return;
+  }
+  fail('savepoint save|load|list <name> --level app --simulator <udid> --package <bundle id>');
+}
+
+/**
+ * Level 1 packed BY THE APP (`--via bridge`, and always for an iPhone: `--device <udid>`): the bridge does the tar at
+ * the app's next launch, before the app opens its data (PilotState.kt / G9PilotState.m), and this side moves ONE file
+ * by the device's own channel — devicectl on an iPhone (it copies files, not folders), the container folder on the
+ * simulator, run-as on Android. `state.cmd` carries a nonce that comes back in `state.done`.
+ */
+async function bridgeAppSavepoint(sub, name) {
+  const id = String(flags.package ?? flags.bundle ?? '');
+  if (!/^[A-Za-z][\w-]*(\.[A-Za-z][\w-]*)+$/.test(id)) fail('--level app --via bridge needs --package <application / bundle id>.');
+  const dir = path.resolve(String(flags.dir ?? path.join(process.env.HOME ?? process.env.USERPROFILE ?? '.', '.g9pilot', 'savepoints')), id);
+  fs.mkdirSync(dir, { recursive: true });
+  if (sub === 'list') {
+    print({ ok: true, dir, savepoints: fs.readdirSync(dir).filter((f) => f.endsWith('.tar')).map((f) => ({ name: f.slice(0, -4), bytes: fs.statSync(path.join(dir, f)).size })) });
+    return;
+  }
+  if (!name || !/^[A-Za-z0-9._-]{1,64}$/.test(name)) fail('savepoint needs a name: letters, digits, . _ - (at most 64).');
+  const file = path.join(dir, `${name}.tar`);
+  const { spawnSync } = await import('node:child_process');
+  const os = await import('node:os');
+  const ch = bridgeChannel(id, spawnSync, os);
+  const started = Date.now();
+  const nonce = Math.random().toString(36).slice(2, 12);
+  const waitDone = (what) => {
+    for (const until = Date.now() + Number(flags.timeout ?? 120_000); Date.now() < until; ) {
+      const raw = ch.get('state.done');
+      if (raw) {
+        try {
+          const d = JSON.parse(raw.toString('utf8'));
+          if (d.nonce === nonce && d.what === what) return d;
+        } catch {
+          // being written
+        }
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1_000);
+    }
+    fail(`savepoint ${what}: the app did not answer in time (a debug build whose G9AppPilot packs savepoints at launch — PilotState / G9PilotState — and calls applyPendingState or install at launch?)`);
+  };
+  if (sub === 'save') {
+    ch.put('state.cmd', Buffer.from(`export ${nonce}\n`));
+    ch.relaunch();
+    const done = waitDone('export');
+    if (!done.ok) fail(`savepoint save: ${done.error}`);
+    const tar = ch.get('state.tar');
+    if (!tar?.length) fail('savepoint save: state.tar could not be copied off the device.');
+    const entries = tarEntries(tar).length;
+    if (entries !== done.entries) fail(`savepoint save: the copy holds ${entries} of the ${done.entries} entries the app packed. Nothing was saved.`);
+    fs.writeFileSync(file, tar);
+    const meta = writeSavepointMeta(file, { level: 'app', via: 'bridge', channel: ch.kind, name, package: id, entries, bytes: tar.length });
+    print({ ok: true, what: 'saved', level: 'app', via: 'bridge', channel: ch.kind, name, package: id, file, bytes: tar.length, entries, server: meta.server, packMs: done.ms, ms: Date.now() - started });
+    return;
+  }
+  if (sub === 'load') {
+    if (!fs.existsSync(file)) fail(`No savepoint ${name} for ${id} in ${dir}.`);
+    const tar = fs.readFileSync(file);
+    ch.put('state-in.tar', tar);
+    ch.put('state.cmd', Buffer.from(`import ${nonce}\n`));
+    ch.relaunch();
+    const done = waitDone('import');
+    if (!done.ok) fail(`savepoint load: ${done.error}`);
+    const expected = tarEntries(tar).length;
+    if (done.entries !== expected) fail(`savepoint load: the app applied ${done.entries} of ${expected} entries — load it again.`);
+    print({ ok: true, what: 'loaded', level: 'app', via: 'bridge', channel: ch.kind, name, package: id, bytes: tar.length, entries: expected, applyMs: done.ms, ms: Date.now() - started, note: 'the app is running from that data now' });
+    return;
+  }
+  fail('savepoint save|load|list <name> --level app --via bridge --package <id> [--device <udid> | --simulator <udid> | --serial <s>]');
+}
+
+/** One file in and out of the bridge's work folder, and a relaunch, by the device's own channel. */
+function bridgeChannel(id, spawnSync, os) {
+  if (flags.device) {
+    const udid = String(flags.device);
+    const remote = (f) => `tmp/g9pilot/${f}`;
+    const ctl = (args, timeout = 120_000) => spawnSync('xcrun', ['devicectl', ...args], { timeout, encoding: 'utf8' });
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'g9pilot-'));
+    const where = ['--device', udid, '--domain-type', 'appDataContainer', '--domain-identifier', id, '--user', 'mobile'];
+    return {
+      kind: 'devicectl',
+      put(f, bytes) {
+        const local = path.join(scratch, f);
+        fs.writeFileSync(local, bytes);
+        const r = ctl(['device', 'copy', 'to', ...where, '--source', local, '--destination', remote(f)], 15 * 60_000);
+        if (r.status !== 0) fail(`devicectl copy to: ${String(r.stderr || r.stdout).trim().slice(-300)}`);
+      },
+      get(f) {
+        const local = path.join(scratch, `in-${f}`);
+        fs.rmSync(local, { force: true });
+        const r = ctl(['device', 'copy', 'from', ...where, '--source', remote(f), '--destination', local], 15 * 60_000);
+        return r.status === 0 && fs.existsSync(local) ? fs.readFileSync(local) : null;
+      },
+      relaunch() {
+        const r = ctl(['device', 'process', 'launch', '--device', udid, '--terminate-existing', id]);
+        if (r.status !== 0) fail(`devicectl launch: ${String(r.stderr || r.stdout).trim().slice(-300)}`);
+      },
+    };
+  }
+  if (flags.simulator) {
+    const udid = String(flags.simulator);
+    const container = run('xcrun', ['simctl', 'get_app_container', udid, id, 'data']).trim();
+    const work = path.join(container, 'tmp', 'g9pilot');
+    fs.mkdirSync(work, { recursive: true });
+    return {
+      kind: 'simulator',
+      put: (f, bytes) => fs.writeFileSync(path.join(work, f), bytes),
+      get: (f) => (fs.existsSync(path.join(work, f)) ? fs.readFileSync(path.join(work, f)) : null),
+      relaunch() {
+        spawnSync('xcrun', ['simctl', 'terminate', udid, id], { timeout: 20_000 });
+        const r = spawnSync('xcrun', ['simctl', 'launch', udid, id], { timeout: 60_000, encoding: 'utf8' });
+        if (r.status !== 0) fail(`simctl launch: ${String(r.stderr).trim().slice(-300)}`);
+      },
+    };
+  }
+  const adb = String(flags.adb ?? process.env.ADB ?? 'adb');
+  const serial = String(flags.serial ?? 'emulator-5554');
+  const work = `/data/data/${id}/cache/g9pilot`;
+  return {
+    kind: 'run-as',
+    put(f, bytes) {
+      const r = spawnSync(adb, ['-s', serial, 'exec-in', `run-as ${id} sh -c 'mkdir -p ${work} && cat > ${work}/${f}'`], { input: bytes, timeout: 10 * 60_000 });
+      if (r.status !== 0) fail(`run-as write: ${String(r.error?.message ?? r.stderr).trim().slice(0, 200)} — a debuggable build is needed.`);
+    },
+    get(f) {
+      const r = spawnSync(adb, ['-s', serial, 'exec-out', `run-as ${id} sh -c 'cat ${work}/${f} 2>/dev/null'`], { maxBuffer: 2 * 1024 ** 3, timeout: 10 * 60_000 });
+      return r.status === 0 && r.stdout?.length ? r.stdout : null;
+    },
+    relaunch() {
+      spawnSync(adb, ['-s', serial, 'shell', 'am', 'force-stop', id], { timeout: 20_000 });
+      spawnSync(adb, ['-s', serial, 'shell', 'monkey', '-p', id, '-c', 'android.intent.category.LAUNCHER', '1'], { timeout: 30_000 });
+    },
+  };
+}
+
+// ---- the OS around the app (g9pilot os …) ----------------------------------------------------------------------------
+
+function deviceTarget() {
+  if (flags.simulator) return { kind: 'simulator', udid: String(flags.simulator) };
+  return { kind: 'android', adb: String(flags.adb ?? process.env.ADB ?? 'adb'), serial: String(flags.serial ?? 'emulator-5554') };
+}
+
+const run = (file, args, opts = {}) => execFileSync(file, args, { encoding: 'utf8', timeout: 30_000, maxBuffer: 64 * 1024 * 1024, ...opts });
+const adbOf = (t) => (args, opts) => run(t.adb, ['-s', t.serial, ...args], opts);
+
+/** The OS's crash records for the app (or all), newest last. */
+function crashLog({ lines = Number(flags.lines ?? 400), pkg = flags.package } = {}) {
+  const t = deviceTarget();
+  if (t.kind === 'android') {
+    const out = adbOf(t)(['logcat', '-b', 'crash', '-d', '-v', 'time']);
+    const all = out.split(/\r?\n/).filter(Boolean);
+    const mine = pkg ? all.filter((l, i) => l.includes(String(pkg)) || (i > 0 && /^\S+ \S+ [EF]\/AndroidRuntime/.test(l))) : all;
+    return { source: 'logcat -b crash', count: mine.length, lines: mine.slice(-lines) };
+  }
+  if (process.platform !== 'darwin') fail('os crashlogs --simulator runs on the Mac that hosts the simulator (or through `--host`).');
+  const dir = path.join(process.env.HOME ?? '', 'Library', 'Logs', 'DiagnosticReports');
+  const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => /\.(ips|crash)$/.test(f) && (!pkg || f.toLowerCase().includes(String(pkg).split('.').pop().toLowerCase()))) : [];
+  files.sort((a, b) => fs.statSync(path.join(dir, a)).mtimeMs - fs.statSync(path.join(dir, b)).mtimeMs);
+  const newest = files.slice(-3).map((f) => ({ file: f, head: fs.readFileSync(path.join(dir, f), 'utf8').split('\n').slice(0, lines).join('\n') }));
+  return { source: dir, count: files.length, reports: newest };
+}
+
+/** Answers the system permission dialog by its buttons' ids (the permission controller's own), with a real tap. */
+function answerDialog(t, allow) {
+  const adb = adbOf(t);
+  adb(['shell', 'uiautomator', 'dump', '/sdcard/g9pilot-ui.xml']);
+  const xml = adb(['exec-out', 'cat', '/sdcard/g9pilot-ui.xml']);
+  const ids = allow
+    ? ['permission_allow_foreground_only_button', 'permission_allow_button', 'permission_allow_one_time_button', 'permission_allow_always_button']
+    : ['permission_deny_button', 'permission_deny_and_dont_ask_again_button'];
+  for (const id of ids) {
+    const m = new RegExp(`resource-id="[^"]*:id/${id}"[^>]*bounds="\\[(\\d+),(\\d+)\\]\\[(\\d+),(\\d+)\\]"`).exec(xml);
+    if (!m) continue;
+    const [x, y] = [Math.round((+m[1] + +m[3]) / 2), Math.round((+m[2] + +m[4]) / 2)];
+    adb(['shell', 'input', 'tap', String(x), String(y)]);
+    return { answered: allow ? 'allow' : 'deny', button: id, at: { x, y } };
+  }
+  return { answered: null, note: 'No system permission dialog is on screen.' };
+}
+
+/** One OS action; returns its result or throws (the CLI prints it, MCP's pilot_stage `os.*` returns it). */
+export function osAction(what, a = {}) {
+  const t = deviceTarget();
+  const sim = t.kind === 'simulator';
+  const simctl = (x) => run('xcrun', ['simctl', ...x]);
+  const bad = (m) => {
+    throw new Error(m);
+  };
+  switch (what) {
+    case 'crashlogs':
+      return crashLog({ lines: Number(a.lines ?? flags.lines ?? 400), pkg: a.package ?? flags.package });
+    case 'permission': {
+      const { verb, permission } = a;
+      const pkg = a.package ?? flags.package;
+      if (!['grant', 'revoke'].includes(verb) || !permission || !pkg) bad('os permission grant|revoke <permission> --package <id>');
+      if (sim) simctl(['privacy', t.udid, verb, permission, String(pkg)]);
+      else adbOf(t)(['shell', 'pm', verb, String(pkg), permission]);
+      return { [verb === 'grant' ? 'granted' : 'revoked']: permission, package: pkg, ...(verb === 'revoke' && !sim ? { note: 'Android stops an app whose runtime permission is revoked' } : {}) };
+    }
+    case 'location': {
+      const lat = Number(a.lat);
+      const lon = Number(a.lon);
+      if (!Number.isFinite(lat) || !Number.isFinite(lon) || Math.abs(lat) > 90 || Math.abs(lon) > 180) bad('os location <lat> <lon> (degrees)');
+      if (sim) simctl(['location', t.udid, 'set', `${lat},${lon}`]);
+      else if (t.serial.startsWith('emulator-')) adbOf(t)(['emu', 'geo', 'fix', String(lon), String(lat)]);
+      else bad('A real Android phone takes a fake position only from a mock-location app; use an emulator.');
+      return { location: { lat, lon } };
+    }
+    case 'net': {
+      const { state } = a;
+      if (!['offline', 'online'].includes(state)) bad('os net offline|online');
+      if (sim) bad('The simulator shares the Mac’s network; shape the page’s requests with net.shape instead.');
+      adbOf(t)(['shell', 'cmd', 'connectivity', 'airplane-mode', state === 'offline' ? 'enable' : 'disable']);
+      return { network: state, note: 'the whole device: the sync hub and map tiles too (net.shape shapes only the page’s fetch)' };
+    }
+    case 'dialog': {
+      const { answer } = a;
+      if (!['allow', 'deny'].includes(answer)) bad('os dialog allow|deny');
+      if (sim) bad('The simulator’s dialogs: grant first with `os permission grant` (simctl privacy).');
+      return answerDialog(t, answer === 'allow');
+    }
+    case 'video': {
+      const seconds = Math.max(1, Math.min(3600, Math.round(Number(a.seconds ?? 30))));
+      const out = String(a.out ?? flags.out ?? '.');
+      fs.mkdirSync(out, { recursive: true });
+      if (sim) return recordSimulatorVideo(t.udid, seconds, out);
+      return recordAndroidVideo(t, seconds, out);
+    }
+    case 'doze': {
+      const { state } = a;
+      if (sim) bad('Doze is Android only; iOS has no equivalent a test can switch.');
+      const adb = adbOf(t);
+      if (state === 'on') {
+        adb(['shell', 'dumpsys', 'battery', 'unplug']);
+        adb(['shell', 'dumpsys', 'deviceidle', 'enable', 'all']);
+        adb(['shell', 'dumpsys', 'deviceidle', 'force-idle']);
+      } else if (state === 'off') {
+        adb(['shell', 'dumpsys', 'deviceidle', 'unforce']);
+        adb(['shell', 'dumpsys', 'battery', 'reset']);
+      } else if (state === 'step') {
+        adb(['shell', 'dumpsys', 'deviceidle', 'step']);
+      } else bad('os doze on|off|step');
+      const mState = /mState=(\w+)/.exec(adb(['shell', 'dumpsys', 'deviceidle']))?.[1] ?? null;
+      return { doze: state, mState, ...(state === 'on' ? { undo: 'os doze off (it also resets the battery state)' } : {}) };
+    }
+    case 'standby': {
+      const { bucket } = a;
+      const pkg = a.package ?? flags.package;
+      if (sim) bad('App Standby buckets are Android only.');
+      if (!['active', 'working_set', 'frequent', 'rare', 'restricted'].includes(bucket) || !pkg) bad('os standby active|working_set|frequent|rare|restricted --package <id>');
+      adbOf(t)(['shell', 'am', 'set-standby-bucket', String(pkg), bucket]);
+      return { package: pkg, bucket: String(adbOf(t)(['shell', 'am', 'get-standby-bucket', String(pkg)])).trim() };
+    }
+    case 'appearance': {
+      const { mode } = a;
+      if (!['dark', 'light'].includes(mode)) bad('os appearance dark|light');
+      if (sim) simctl(['ui', t.udid, 'appearance', mode]);
+      else adbOf(t)(['shell', 'cmd', 'uimode', 'night', mode === 'dark' ? 'yes' : 'no']);
+      return { appearance: mode };
+    }
+    case 'fontscale': {
+      const { value } = a;
+      const SIZES = ['extra-small', 'small', 'medium', 'large', 'extra-large', 'extra-extra-large', 'extra-extra-extra-large', 'accessibility-medium', 'accessibility-large', 'accessibility-extra-large', 'accessibility-extra-extra-large', 'accessibility-extra-extra-extra-large'];
+      const n = Number(value);
+      if (sim) {
+        // iOS takes a category; a number is mapped (1 = large, the default).
+        const category = SIZES.includes(value) ? value : Number.isFinite(n) ? (n <= 0.85 ? 'small' : n <= 1 ? 'large' : n <= 1.15 ? 'extra-large' : n <= 1.3 ? 'extra-extra-large' : 'extra-extra-extra-large') : null;
+        if (!category) bad(`os fontscale <number | ${SIZES.join(' | ')}>`);
+        simctl(['ui', t.udid, 'content_size', category]);
+        return { contentSize: category };
+      }
+      if (!Number.isFinite(n) || n < 0.5 || n > 2) bad('os fontscale <0.5 … 2> on Android (1 = normal)');
+      adbOf(t)(['shell', 'settings', 'put', 'system', 'font_scale', String(n)]);
+      return { fontScale: n, undo: 'os fontscale 1' };
+    }
+    case 'notify': {
+      const file = a.payload;
+      const pkg = a.package ?? flags.package;
+      if (!sim) bad('Android: `cmd notification post` posts as the shell, not as the app — a test of the app\'s own notification needs an app command that posts one locally.');
+      if (!file || !fs.existsSync(String(file)) || !pkg) bad('os notify <payload.json> --package <bundle id> (an APNs payload: {"aps": {"alert": …}})');
+      simctl(['push', t.udid, String(pkg), String(file)]);
+      return { pushed: String(file), package: pkg };
+    }
+    default:
+      return bad('os crashlogs | permission | location | net | dialog | video | doze | standby | appearance | fontscale | notify — see the header of g9pilot.mjs');
+  }
+}
+
+/**
+ * Android screen video in pieces: screenrecord stops at 180 s (its own limit), so a longer recording is consecutive
+ * pieces of at most 175 s, each pulled to `out` (not joined — the list says the order). Research R4.
+ */
+function recordAndroidVideo(t, seconds, out) {
+  const adb = adbOf(t);
+  const pieces = [];
+  let left = seconds;
+  for (let i = 0; left > 0; i++) {
+    const length = Math.min(175, left);
+    const remote = `/sdcard/g9pilot-video-${i}.mp4`;
+    adb(['shell', 'screenrecord', '--time-limit', String(length), remote], { timeout: (length + 30) * 1000 });
+    const local = path.join(out, `video-${String(i).padStart(2, '0')}.mp4`);
+    run(t.adb, ['-s', t.serial, 'pull', remote, local], { timeout: 120_000 });
+    adb(['shell', 'rm', '-f', remote]);
+    pieces.push(local);
+    left -= length;
+  }
+  return { video: pieces, seconds, note: pieces.length > 1 ? 'consecutive pieces (screenrecord stops at 180 s), in order' : undefined };
+}
+
+/** The simulator's screen: simctl io recordVideo until SIGINT. */
+function recordSimulatorVideo(udid, seconds, out) {
+  const file = path.join(out, 'video.mp4');
+  const child = spawn('xcrun', ['simctl', 'io', udid, 'recordVideo', '--codec=h264', '--force', file], { stdio: 'ignore' });
+  const until = Date.now() + seconds * 1000;
+  while (Date.now() < until) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
+  child.kill('SIGINT');
+  return { video: [file], seconds, note: 'written when simctl finishes (a second or two after SIGINT)' };
+}
+
+function osCommand([what, ...args]) {
+  const named =
+    {
+      permission: { verb: args[0], permission: args[1] },
+      location: { lat: args[0], lon: args[1] },
+      net: { state: args[0] },
+      dialog: { answer: args[0] },
+      video: { seconds: args[0] },
+      doze: { state: args[0] },
+      standby: { bucket: args[0] },
+      appearance: { mode: args[0] },
+      fontscale: { value: args[0] },
+      notify: { payload: args[0] },
+    }[what] ?? {};
+  try {
+    print({ ok: true, ...osAction(what, named) });
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * What an approval does after writing (plan v2 P1-18): g9pilot.json `tokens.afterApprove` (each [cmd, …args], from the
+ * token root) and `tokens.references` — reference names re-checked on this device (`g9pilot visual`, the OS picture of
+ * --serial / --simulator); a changed one is listed for a person, never approved.
+ */
+function approveFollowUps() {
+  const after = Array.isArray(config.tokens?.afterApprove) ? config.tokens.afterApprove : [];
+  const names = Array.isArray(config.tokens?.references) ? config.tokens.references : [];
+  const check = names.length && config.visual
+    ? () => {
+        const settings = visualSettings(config, path.dirname(path.resolve(configPath)), flags);
+        let png;
+        try {
+          png = captureOsPng({ serial: flags.serial, simulator: flags.simulator, adb: String(flags.adb ?? process.env.ADB ?? 'adb') });
+        } catch (e) {
+          return [{ name: '*', verdict: 'no picture', note: e.message }];
+        }
+        return names.map((name) => {
+          const r = checkVisual(settings, String(name), png);
+          return { name, verdict: r.verdict, ...(r.verdict === 'differs' ? { next: `look at ${r.diffImage}, then g9pilot visual approve ${name}` } : {}) };
+        });
+      }
+    : null;
+  return { after, check };
+}
+
+/** The MCP server (packages/mcp) over this bridge, on stdio. Logs go to stderr: stdout is the protocol. */
+async function mcp() {
+  const { createTools, serve } = await import('@g9tm/app-pilot-mcp');
+  const k = key({ required: false });
+  const client = clientFor({ privateKey: k?.key });
+  tallyCalls(client, recorder('mcp', url));
+  const runner = config.runner?.path ? config.runner : null;
+  const runFlow = runner
+    ? async (spec, file, { onStep = null, signal = null } = {}) => {
+        // Not spawnSync: the MCP server keeps answering (tasks/get, other tools) while a flow runs; each «· step n/m»
+        // line of the runner's --progress is one progress notification; a cancelled task kills the run.
+        const os = await import('node:os');
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'g9pilot-flow-'));
+        const flowFile = file ?? path.join(dir, `${spec.id ?? 'inline'}.flow.json`);
+        if (!file) fs.writeFileSync(flowFile, JSON.stringify(spec, null, 2));
+        const report = path.join(dir, 'report');
+        const r = await new Promise((resolve) => {
+          const child = spawn(process.execPath, [runner.path, 'run', flowFile, ...(runner.args ?? []), '--progress', '--report', report], { stdio: ['ignore', 'pipe', 'pipe'] });
+          let stdout = '';
+          let stderr = '';
+          let pending = '';
+          const timer = setTimeout(() => child.kill(), 30 * 60_000);
+          const onAbort = () => child.kill();
+          signal?.addEventListener('abort', onAbort, { once: true });
+          child.stdout.on('data', (d) => {
+            stdout += d;
+            pending += d;
+            const lines = pending.split(/\r?\n/);
+            pending = lines.pop() ?? '';
+            for (const line of lines) {
+              const m = /· step (\d+)\/(\d+) \(([^)]*)\)/.exec(line);
+              if (m) onStep?.(Number(m[1]), `step ${m[1]}/${m[2]} (${m[3]})`);
+            }
+          });
+          child.stderr.on('data', (d) => (stderr += d));
+          child.on('close', (status) => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolve({ status: signal?.aborted ? 130 : status, stdout, stderr });
+          });
+        });
+        let verdict = null;
+        try {
+          verdict = JSON.parse(fs.readFileSync(path.join(report, 'run.json'), 'utf8')).flows?.[0]?.verdict ?? null;
+        } catch {
+          verdict = null;
+        }
+        return { ok: r.status === 0, verdict, report, error: r.status === 0 ? null : String(r.stderr || r.stdout).slice(-600) };
+      }
+    : null;
+  const tools = createTools({ client, devices: config.devices ?? [], confirmWrites: config.mcp?.confirmWrites !== false, runFlow, osAction });
+  serve({ tools });
+  process.stderr.write(`g9pilot mcp: ${tools.length} tools over ${url}${k ? ` (key ${k.source})` : ' (no key: an unsigned bridge only)'}
+`);
+}
+
+main().catch((e) => fail(e.stack ?? String(e), 1));