@agentdeck/bridge 1.0.3 → 1.0.5

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { writeFileSync, unlinkSync, existsSync, realpathSync } from 'fs';
 import { homedir } from 'os';
 import { dirname, join } from 'path';
@@ -8,12 +8,42 @@ import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { request } from 'http';
 import { BRIDGE_WS_PORT } from './types.js';
+import { SESSION_WEIGHT_MIN, SESSION_WEIGHT_MAX } from '@agentdeck/shared';
+import { ensureBleRuntime, getBleRuntimeStatus } from './python-ble-runtime.js';
 import { TASK_NAME, installWindowsTask, taskExists, runWindowsTask, endWindowsTask, deleteWindowsTask, } from './windows-service.js';
+import { deriveRemoteAttachOpts } from './session-registry.js';
+import { SERVICE_NAME, hasSystemctl, unitExists, installUnit, startUnit, disableUnit, getUnitPath, getDataDir, } from './linux-service.js';
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
+/**
+ * Pre-PTY warning for a host hint given without the opt-in switch. Must run in
+ * the CLI action handler BEFORE the bridge starts: once the PTY takes the
+ * terminal, `log()` output is swallowed and the user would never see it.
+ */
+function warnIfDaemonHostIgnored(opts) {
+    if (deriveRemoteAttachOpts(opts).ignoredHostHint) {
+        console.error('[agentdeck] --daemon-host / AGENTDECK_DAEMON_HOST is set but ignored: remote attach requires --remote-daemon (or AGENTDECK_REMOTE_DAEMON=1). Session stays local-only.');
+    }
+}
 function log(msg) {
     process.stderr.write(msg + '\n');
 }
+/**
+ * Parse a `--weight <n>` value into an integer sort override. Rejects
+ * non-integers so a typo (`--weight foo`) fails loudly instead of silently
+ * collapsing to 0, and rejects values outside the documented cross-platform
+ * range (shared SESSION_WEIGHT_MIN/MAX) — the wire value must fit every
+ * consumer's integer type (Kotlin `Int` in particular), and comparators on
+ * fixed-width platforms must never see values that could overflow. Lower
+ * sorts first (see shared sortSessions).
+ */
+function parseWeight(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < SESSION_WEIGHT_MIN || n > SESSION_WEIGHT_MAX) {
+        throw new InvalidArgumentError(`weight must be an integer between ${SESSION_WEIGHT_MIN} and ${SESSION_WEIGHT_MAX} (e.g. --weight 1, --weight -5)`);
+    }
+    return n;
+}
 function formatBytes(value) {
     const bytes = typeof value === 'number' && Number.isFinite(value) ? value : 0;
     if (bytes >= 1024 * 1024)
@@ -135,19 +165,30 @@ async function isDaemonPort(port) {
         return false;
     }
 }
-function resolveTimeboxSyncPaths() {
-    const distPath = dirname(fileURLToPath(import.meta.url));
-    const projectRoot = join(distPath, '..', '..');
-    const timeboxDir = join(projectRoot, 'bridge', 'src', 'timebox');
-    return {
-        python: join(projectRoot, '.venv', 'bin', 'python'),
-        bleScript: join(timeboxDir, 'sync_ble.py'),
-        scanScript: join(timeboxDir, 'scan_ble.py'),
-    };
-}
 function projectRootPath() {
     return join(dirname(fileURLToPath(import.meta.url)), '..', '..');
 }
+async function runBlePython(python, args, captureStdout = false) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(python, args, captureStdout ? { stdio: ['ignore', 'pipe', 'inherit'], windowsHide: true } : { stdio: 'inherit', windowsHide: true });
+        let stdout = '';
+        child.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.once('error', reject);
+        child.once('close', (code) => resolve({ code, stdout }));
+    });
+}
+function prepareBleRuntime() {
+    try {
+        return ensureBleRuntime({ log });
+    }
+    catch (err) {
+        log(`BLE support unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+        return null;
+    }
+}
 const ESP32_OTA_BOARDS = [
     { board: 'inkdeck', env: 'inkdeck', aliases: [] },
     { board: 'ulanzi_tc001', env: 'led8x32', aliases: ['led8x32'] },
@@ -192,6 +233,117 @@ function platformioBin() {
         return '/opt/homebrew/bin/pio';
     return 'pio';
 }
+// ===== Env-var default CLI args =====
+//
+// Two layers of environment-variable defaults, so a shell profile can set
+// repeated flags once:
+//   AGENTDECK_COMMANDER_ARGS   → args for the `agentdeck` (commander) layer,
+//                                spliced into argv after the session subcommand.
+//   AGENTDECK_<AGENT>_ARGS     → args appended to the spawned agent command,
+//                                weaving into an explicit `-c` when present.
+// See docs and cli.test.ts for behavior.
+/** Session subcommands the global env-args var applies to. */
+const SESSION_COMMANDS = ['claude', 'codex', 'opencode', 'monitor'];
+/** Env var holding extra args for the spawned agent command, per agent type. */
+const AGENT_ARGS_ENV = {
+    'claude-code': 'AGENTDECK_CLAUDE_ARGS',
+    'codex-cli': 'AGENTDECK_CODEX_ARGS',
+    opencode: 'AGENTDECK_OPENCODE_ARGS',
+};
+/**
+ * Split an env-provided arg string into tokens, honoring single/double quotes
+ * so values like `--flag "a b"` survive. No shell expansion (no $VAR,
+ * globbing, or escapes beyond quote grouping) — this only groups whitespace.
+ * Cross-platform: pure JS, never invokes a shell.
+ */
+export function tokenizeArgString(s) {
+    if (!s)
+        return [];
+    const tokens = [];
+    // Match: double-quoted run | single-quoted run | bare non-space run.
+    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let cur = '';
+    let curActive = false;
+    let lastIndex = 0;
+    let m;
+    while ((m = re.exec(s)) !== null) {
+        // A gap of whitespace between matches ends the current token.
+        if (curActive && m.index > lastIndex) {
+            tokens.push(cur);
+            cur = '';
+            curActive = false;
+        }
+        cur += m[1] ?? m[2] ?? m[3] ?? '';
+        curActive = true;
+        lastIndex = re.lastIndex;
+    }
+    if (curActive)
+        tokens.push(cur);
+    return tokens;
+}
+/** Per-invocation escape hatch: disables BOTH env-default layers when typed. */
+const NO_ENV_ARGS_FLAG = '--no-env-args';
+/**
+ * If argv's subcommand is a session command and AGENTDECK_COMMANDER_ARGS is set,
+ * splice its tokens in immediately after the subcommand name. Env tokens land
+ * before any user-typed tokens, giving last-write override for SCALAR options
+ * (retype `--weight`/`--daemon-host` to win); boolean flags have no inverse
+ * spelling, so the per-invocation override is the typed `--no-env-args` hatch,
+ * which skips the splice entirely (and, parsed by commander, turns the
+ * per-agent append off in the session actions too).
+ * Returns a new argv; no-op (returns input) when unset or not a session command.
+ */
+export function applyGlobalEnvArgs(argv, env = process.env) {
+    // The hatch itself is stripped from the env tokens: an env-smuggled
+    // --no-env-args would otherwise splice normally and then parse to
+    // envArgs=false, silently disabling only the per-agent layer — an
+    // undocumented half-state. The env var cannot turn the hatch on or off;
+    // only a typed flag can.
+    const extra = tokenizeArgString(env.AGENTDECK_COMMANDER_ARGS)
+        .filter((tok) => tok !== NO_ENV_ARGS_FLAG);
+    if (extra.length === 0)
+        return argv;
+    // The CLI has a fixed top-level command position: argv[0]=node,
+    // argv[1]=script, argv[2]=subcommand. Keying the decision to argv[2] (not a
+    // token scan) keeps non-session commands a true no-op even when a
+    // positional VALUE equals a session command name (`agentdeck speak b claude`).
+    const sub = argv[2];
+    if (sub === undefined || !SESSION_COMMANDS.includes(sub))
+        return argv;
+    // Typed escape hatch — checked on the RAW argv before splicing, because
+    // post-parse is too late (env tokens would already have parsed into opts).
+    // Exact-token match: a flag VALUE lexically equal to --no-env-args would
+    // false-positive, but producing that requires a deliberately pathological
+    // invocation (`-c --no-env-args`), and the argv[2] gate above bounds the
+    // scan to session commands.
+    if (argv.slice(3).includes(NO_ENV_ARGS_FLAG))
+        return argv;
+    const next = argv.slice();
+    next.splice(3, 0, ...extra);
+    return next;
+}
+/**
+ * Append the per-agent env var to the resolved `-c` command string. Raw append
+ * (single space + trim) — the PTY shell re-parses the whole string at spawn, so
+ * this rides the same platform shell path (cmd.exe / POSIX) that already handles
+ * a user's `-c`. No-op (returns `command`) when the var is unset/empty.
+ */
+export function weaveAgentCommand(agentType, command, env = process.env) {
+    const extra = (env[AGENT_ARGS_ENV[agentType]] ?? '').trim();
+    if (!extra)
+        return command;
+    return `${command} ${extra}`.trim();
+}
+/**
+ * The session actions' one-call selection for the spawned agent command:
+ * weave the per-agent env args unless the user typed `--no-env-args`
+ * (commander parses it as `opts.envArgs === false`; the hatch covers BOTH
+ * env layers, and the commander-layer half is handled pre-parse in
+ * `applyGlobalEnvArgs`).
+ */
+export function resolveAgentCommand(agentType, command, envArgsEnabled, env = process.env) {
+    return envArgsEnabled ? weaveAgentCommand(agentType, command, env) : command;
+}
 // ===== Program =====
 const program = new Command();
 program
@@ -211,16 +363,24 @@ program
     .option('--no-adb', 'Disable ADB reverse setup')
     .option('--no-postit', 'Disable terminal tab title updates')
     .option('--wake-word', 'Enable wake word voice assistant ("오픈클로")')
+    .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
+    .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
+    .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnIfDaemonHostIgnored(opts);
     const { startSession } = await import('./index.js');
     await startSession({
         agentType: 'claude-code',
         port: parseInt(opts.port, 10),
-        command: opts.command,
+        command: resolveAgentCommand('claude-code', opts.command, opts.envArgs !== false),
         debug: opts.debug,
         noUpdateCheck: opts.updateCheck === false,
         postit: opts.postit !== false,
         wakeWord: !!opts.wakeWord,
+        remoteDaemon: !!opts.remoteDaemon,
+        daemonHost: opts.daemonHost,
+        weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
             mdns: false, // daemon-only — session bridges never advertise mDNS
             adb: opts.adb !== false ? 'auto' : false,
@@ -240,7 +400,12 @@ program
     .option('--no-adb', 'Disable ADB reverse setup')
     .option('--no-postit', 'Disable terminal tab title updates')
     .option('--no-codex-hooks', 'Skip ~/.codex/config.toml hook install')
+    .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
+    .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
+    .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnIfDaemonHostIgnored(opts);
     // Install Codex lifecycle hooks before starting the session so the
     // first prompt's UserPromptSubmit / Stop events reach the daemon.
     // Idempotent: re-running with the same daemon port is a no-op.
@@ -269,9 +434,12 @@ program
     await startSession({
         agentType: 'codex-cli',
         port: parseInt(opts.port, 10),
-        command: opts.command,
+        command: resolveAgentCommand('codex-cli', opts.command, opts.envArgs !== false),
         debug: opts.debug,
         postit: opts.postit !== false,
+        remoteDaemon: !!opts.remoteDaemon,
+        daemonHost: opts.daemonHost,
+        weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
             mdns: false, // daemon-only
             adb: opts.adb !== false ? 'auto' : false,
@@ -291,7 +459,12 @@ program
     .option('--no-adb', 'Disable ADB reverse setup')
     .option('--no-postit', 'Disable terminal tab title updates')
     .option('--no-opencode-hooks', 'Skip OpenCode observer plugin install')
+    .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
+    .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
+    .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnIfDaemonHostIgnored(opts);
     // Install the OpenCode observer plugin so standalone `opencode` runs
     // (outside this managed session) also reach the daemon timeline. The
     // plugin self-disables inside managed PTYs via AGENTDECK_PORT, so this
@@ -319,9 +492,12 @@ program
     await startSession({
         agentType: 'opencode',
         port: parseInt(opts.port, 10),
-        command: opts.command,
+        command: resolveAgentCommand('opencode', opts.command, opts.envArgs !== false),
         debug: opts.debug,
         postit: opts.postit !== false,
+        remoteDaemon: !!opts.remoteDaemon,
+        daemonHost: opts.daemonHost,
+        weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
             mdns: false,
             adb: opts.adb !== false ? 'auto' : false,
@@ -337,7 +513,13 @@ program
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-d, --debug', 'Enable debug logging')
     .option('--local', 'Disable all device modules')
+    .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
+    .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    // Commander-layer half only: monitor spawns no agent command to weave into.
+    .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS for this invocation')
+    .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnIfDaemonHostIgnored(opts);
     const { startSession } = await import('./index.js');
     const port = parseInt(opts.port, 10);
     log(`\nMonitor mode: hook server on port ${port}`);
@@ -346,6 +528,9 @@ program
         agentType: 'monitor',
         port,
         debug: opts.debug,
+        remoteDaemon: !!opts.remoteDaemon,
+        daemonHost: opts.daemonHost,
+        weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : undefined,
     });
 });
@@ -453,6 +638,7 @@ daemon
         const child = spawn(process.execPath, args, {
             detached: true,
             stdio: ['ignore', out, err],
+            windowsHide: true,
         });
         child.unref();
         log(`Daemon started (PID ${child.pid})`);
@@ -490,6 +676,7 @@ daemon
     const child = spawn(process.execPath, args, {
         detached: true,
         stdio: 'ignore',
+        windowsHide: true,
     });
     child.unref();
     log(`Daemon restarted (PID ${child.pid})`);
@@ -522,7 +709,7 @@ daemon
 });
 daemon
     .command('install')
-    .description('Install daemon auto-start (LaunchAgent on macOS, Scheduled Task on Windows)')
+    .description('Install daemon auto-start (LaunchAgent on macOS, Scheduled Task on Windows, systemd --user unit on Linux)')
     .action(async () => {
     if (process.platform === 'win32') {
         try {
@@ -576,6 +763,62 @@ daemon
         catch { /* hooks package not built yet — task install still succeeds */ }
         process.exit(0);
     }
+    if (process.platform === 'linux') {
+        if (!hasSystemctl()) {
+            log('systemd --user is not available on this host.');
+            log('Run the daemon manually with: agentdeck daemon start');
+            log('(or add your own autostart entry).');
+        }
+        else {
+            try {
+                installUnit();
+                startUnit();
+                log(`systemd user unit '${SERVICE_NAME}' installed and started.`);
+                log(`Unit file: ${getUnitPath()}`);
+                if (process.env.AGENTDECK_DATA_DIR) {
+                    log(`Data dir: ${getDataDir()} (AGENTDECK_DATA_DIR persisted into the unit — re-run 'agentdeck daemon install' to change it)`);
+                }
+                else {
+                    log(`Data dir: ${getDataDir()}`);
+                }
+                log('For boot-without-login on a headless host, run once: loginctl enable-linger $USER');
+            }
+            catch (e) {
+                const detail = e.stderr?.toString().trim() || e.message;
+                log('Failed to install the systemd user unit.');
+                if (detail)
+                    log(detail);
+                log('You can still run the daemon manually with: agentdeck daemon start');
+                process.exit(1);
+            }
+        }
+        // Install Codex + OpenCode hooks for parity with the macOS/Windows paths.
+        try {
+            const { installCodexHooksIfNeeded } = await import('@agentdeck/hooks');
+            const result = installCodexHooksIfNeeded();
+            if (result.installed) {
+                log('Codex lifecycle hooks installed in ~/.codex/config.toml');
+                if (result.warning)
+                    log(`Codex hooks degraded: ${result.warning}`);
+            }
+            else if (result.reason) {
+                log(`Codex hooks skipped: ${result.reason}`);
+            }
+        }
+        catch { /* hooks package not built yet — install still succeeds */ }
+        try {
+            const { installOpenCodeHooksIfNeeded, opencodePluginPath } = await import('@agentdeck/hooks');
+            const result = installOpenCodeHooksIfNeeded();
+            if (result.installed) {
+                log(`OpenCode observer plugin installed at ${opencodePluginPath()}`);
+            }
+            else if (result.reason) {
+                log(`OpenCode observer plugin skipped: ${result.reason}`);
+            }
+        }
+        catch { /* hooks package not built yet — install still succeeds */ }
+        process.exit(0);
+    }
     if (process.platform !== 'darwin') {
         log('LaunchAgent is macOS-only');
         process.exit(1);
@@ -618,7 +861,7 @@ daemon
 });
 daemon
     .command('uninstall')
-    .description('Remove daemon auto-start (LaunchAgent on macOS, Scheduled Task on Windows)')
+    .description('Remove daemon auto-start (LaunchAgent on macOS, Scheduled Task on Windows, systemd --user unit on Linux)')
     .action(async () => {
     if (process.platform === 'win32') {
         if (!taskExists()) {
@@ -644,6 +887,17 @@ daemon
         }
         process.exit(0);
     }
+    if (process.platform === 'linux') {
+        if (!unitExists()) {
+            log(`systemd user unit '${SERVICE_NAME}' is not installed.`);
+            process.exit(0);
+        }
+        // Graceful daemon shutdown first, then disable + remove the unit.
+        await stopDaemon(BRIDGE_WS_PORT);
+        disableUnit();
+        log(`systemd user unit '${SERVICE_NAME}' removed.`);
+        process.exit(0);
+    }
     if (!existsSync(PLIST_PATH)) {
         log('LaunchAgent not installed');
         return;
@@ -949,6 +1203,7 @@ program
     .option('-e, --env <env>', 'PlatformIO environment for default firmware path')
     .option('-f, --firmware <path>', 'Firmware .bin path')
     .option('--build', 'Build the PlatformIO environment before upload')
+    .option('--stage', 'Stage for pull OTA: the board installs it on its next feed pull (no live WS needed)')
     .action(async (target, opts) => {
     const { readDaemonInfo, findDaemonPort } = await import('./session-registry.js');
     const info = readDaemonInfo();
@@ -962,12 +1217,25 @@ program
         execFileSync(pio, ['run', '-e', env], {
             cwd: join(projectRootPath(), 'esp32'),
             stdio: 'inherit',
+            windowsHide: true,
         });
     }
     // Send the canonical board string, not the raw alias — the daemon matches
     // `target` against device_info.board, so `ttgo` must become `ttgo_t_display`.
     const daemonTarget = resolveEsp32OtaDaemonTarget(target);
     const firmwarePath = resolveEsp32FirmwarePath(target, opts.env, opts.firmware);
+    if (opts.stage) {
+        // Pull-OTA staging: for wake-sync-sleep boards (XTeink X3/X4) that never
+        // hold a live WS. The daemon adverts the build on the board's feed pulls;
+        // the board downloads + flashes itself on its next wake.
+        const { statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, { target: daemonTarget, firmwarePath, stage: true }, 30_000);
+        if (statusCode < 200 || statusCode >= 300 || body.ok === false) {
+            throw new Error(String(body.error ?? `HTTP ${statusCode}`));
+        }
+        log(`Staged for ${body.board}: ${formatBytes(body.bytes)} md5=${body.md5}`);
+        log('The board installs it on its next feed pull (battery cadence: typically within 15-60 min).');
+        return;
+    }
     log(`Uploading ${firmwarePath} to ${daemonTarget} via daemon :${port}...`);
     let { statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, { target: daemonTarget, firmwarePath }, 15 * 60_000);
     if (body.ok === false && String(body.error ?? '').startsWith('firmware_unreadable')) {
@@ -1149,35 +1417,55 @@ task
     .action(async (opts) => {
     await postTaskClose({ signal: 'manual', outcome: 'abandoned', sessionId: opts.session });
 });
+// ===== Optional Python BLE runtime =====
+const ble = program.command('ble').description('Prepare optional Python support for BLE display devices');
+ble
+    .command('setup')
+    .description('Create the private BLE environment and install its Python dependencies')
+    .action(() => {
+    const runtime = prepareBleRuntime();
+    if (runtime)
+        log(`BLE support ready (${runtime.python}).`);
+});
+ble
+    .command('status')
+    .description('Show whether optional BLE support is ready')
+    .action(() => {
+    const status = getBleRuntimeStatus();
+    if (status.ready) {
+        log(`BLE support ready (${status.python}).`);
+        return;
+    }
+    log(`BLE support is not ready: ${status.reason}. Run \`agentdeck ble setup\`.`);
+    process.exitCode = 1;
+});
 // ===== iDotMatrix commands =====
 const idotmatrix = program.command('idotmatrix').description('Manage iDotMatrix BLE pixel display devices');
 idotmatrix
     .command('scan')
     .description('Discover iDotMatrix devices via BLE')
     .action(async () => {
-    const { dirname } = await import('path');
-    const { fileURLToPath } = await import('url');
-    const { spawn } = await import('child_process');
-    const distPath = dirname(fileURLToPath(import.meta.url));
-    const projectRoot = join(distPath, '..', '..');
-    const venvPython = join(projectRoot, '.venv', 'bin', 'python');
-    const scanScript = join(projectRoot, 'bridge', 'src', 'idotmatrix', 'scan.py');
+    const runtime = prepareBleRuntime();
+    if (!runtime)
+        return;
     log('Scanning for BLE devices (5 seconds)...');
-    const py = spawn(venvPython, [scanScript]);
-    let stdoutData = '';
-    py.stdout.on('data', (data) => {
-        stdoutData += data.toString();
-    });
-    py.on('close', (code) => {
+    try {
+        // Panels are identified by advertised service UUID first and known name
+        // families second; settings.json `idotmatrixNamePrefixes` widens the
+        // latter for a rebranded panel that hides its service.
+        const { loadIDotMatrixNamePrefixes } = await import('./idotmatrix/idotmatrix-settings.js');
+        const { code, stdout } = await runBlePython(runtime.python, [runtime.paths.scripts.idotmatrixScan, ...loadIDotMatrixNamePrefixes()], true);
         if (code !== 0) {
             log('Failed to run scan script.');
-            process.exit(1);
+            process.exitCode = 1;
+            return;
         }
         try {
-            const devices = JSON.parse(stdoutData.trim());
+            const devices = JSON.parse(stdout.trim());
             if (devices.error) {
                 log(`Scan error: ${devices.error}`);
-                process.exit(1);
+                process.exitCode = 1;
+                return;
             }
             if (!Array.isArray(devices) || devices.length === 0) {
                 log('No BLE devices found.');
@@ -1189,10 +1477,15 @@ idotmatrix
                 log(`${prefix}${d.name} (${d.address})`);
             }
         }
-        catch (e) {
-            log(`Failed to parse scan output: ${stdoutData}`);
+        catch {
+            log(`Failed to parse scan output: ${stdout}`);
+            process.exitCode = 1;
         }
-    });
+    }
+    catch (err) {
+        log(`Failed to start BLE scan: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+    }
 });
 idotmatrix
     .command('add <address>')
@@ -1243,9 +1536,6 @@ idotmatrix
     .option('-a, --address <address>', 'BLE Address (defaults to first configured device)')
     .action(async (valueStr, opts) => {
     const { loadIDotMatrixDevices } = await import('./idotmatrix/idotmatrix-settings.js');
-    const { dirname } = await import('path');
-    const { fileURLToPath } = await import('url');
-    const { spawn } = await import('child_process');
     const value = parseInt(valueStr, 10);
     if (isNaN(value) || value < 5 || value > 100) {
         log('Brightness value must be between 5 and 100.');
@@ -1260,22 +1550,30 @@ idotmatrix
         }
         targetAddress = devices[0].address;
     }
-    const distPath = dirname(fileURLToPath(import.meta.url));
-    const projectRoot = join(distPath, '..', '..');
-    const venvPython = join(projectRoot, '.venv', 'bin', 'python');
-    const brightnessScript = join(projectRoot, 'bridge', 'src', 'idotmatrix', 'brightness.py');
+    const runtime = prepareBleRuntime();
+    if (!runtime)
+        return;
     log(`Setting brightness of ${targetAddress} to ${value}%...`);
-    const py = spawn(venvPython, [brightnessScript, '-a', targetAddress, '-b', String(value)], {
-        stdio: 'inherit'
-    });
-    py.on('close', (code) => {
+    try {
+        const { code } = await runBlePython(runtime.python, [
+            runtime.paths.scripts.idotmatrixBrightness,
+            '-a',
+            targetAddress,
+            '-b',
+            String(value),
+        ]);
         if (code === 0) {
             log('Brightness updated successfully.');
         }
         else {
             log(`Failed to update brightness, process exited with code ${code}`);
+            process.exitCode = code ?? 1;
         }
-    });
+    }
+    catch (err) {
+        log(`Failed to start brightness command: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+    }
 });
 idotmatrix
     .command('sync [address]')
@@ -1286,9 +1584,6 @@ idotmatrix
     .action(async (addressOpt, opts) => {
     const { loadIDotMatrixDevices } = await import('./idotmatrix/idotmatrix-settings.js');
     const { readDaemonInfo, findDaemonPort } = await import('./session-registry.js');
-    const { dirname } = await import('path');
-    const { fileURLToPath } = await import('url');
-    const { spawn } = await import('child_process');
     let targetAddress = addressOpt;
     let defaultBrightness = 100;
     const devices = loadIDotMatrixDevices();
@@ -1314,17 +1609,30 @@ idotmatrix
         ? parseInt(opts.port, 10)
         : (info?.httpPort ?? info?.port ?? findDaemonPort() ?? BRIDGE_WS_PORT);
     const url = `http://127.0.0.1:${port}`;
-    const distPath = dirname(fileURLToPath(import.meta.url));
-    const projectRoot = join(distPath, '..', '..');
-    const venvPython = join(projectRoot, '.venv', 'bin', 'python');
-    const syncScript = join(projectRoot, 'bridge', 'src', 'idotmatrix', 'sync.py');
+    const runtime = prepareBleRuntime();
+    if (!runtime)
+        return;
     log(`Starting BLE sync client linking to bridge at ${url} (brightness ${brightness}%, boost ${boost}x)...`);
-    const py = spawn(venvPython, [syncScript, '-a', targetAddress, '-u', url, '-b', String(brightness), '--boost', String(boost)], {
-        stdio: 'inherit'
-    });
-    py.on('close', (code) => {
+    try {
+        const { code } = await runBlePython(runtime.python, [
+            runtime.paths.scripts.idotmatrixSync,
+            '-a',
+            targetAddress,
+            '-u',
+            url,
+            '-b',
+            String(brightness),
+            '--boost',
+            String(boost),
+        ]);
         log(`Sync process exited with code ${code}`);
-    });
+        if (code !== 0)
+            process.exitCode = code ?? 1;
+    }
+    catch (err) {
+        log(`Failed to start BLE sync: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+    }
 });
 // ===== Divoom Timebox Mini Light commands =====
 const timebox = program.command('timebox').description('Manage Divoom Timebox Mini devices (Bluetooth LE)');
@@ -1332,22 +1640,22 @@ timebox
     .command('scan')
     .description('Discover BLE TimeBox-mini-light peripherals')
     .action(async () => {
-    const paths = resolveTimeboxSyncPaths();
+    const runtime = prepareBleRuntime();
+    if (!runtime)
+        return;
     log('Scanning for BLE devices (5 seconds)...');
-    const py = spawn(paths.python, [paths.scanScript]);
-    let stdoutData = '';
-    py.stdout.on('data', (data) => {
-        stdoutData += data.toString();
-    });
-    py.on('close', (code) => {
+    try {
+        const { code, stdout } = await runBlePython(runtime.python, [runtime.paths.scripts.timeboxScan], true);
         if (code !== 0) {
-            log('BLE scan failed (is bleak installed in .venv?).');
+            log('BLE scan failed.');
+            process.exitCode = 1;
             return;
         }
         try {
-            const devices = JSON.parse(stdoutData.trim());
+            const devices = JSON.parse(stdout.trim());
             if (devices.error) {
                 log(`BLE scan error: ${devices.error}`);
+                process.exitCode = 1;
                 return;
             }
             if (!Array.isArray(devices) || devices.length === 0) {
@@ -1363,9 +1671,14 @@ timebox
             log('\nAdd the starred BLE device with: agentdeck timebox add <address>');
         }
         catch {
-            log(`Failed to parse BLE scan output: ${stdoutData}`);
+            log(`Failed to parse BLE scan output: ${stdout}`);
+            process.exitCode = 1;
         }
-    });
+    }
+    catch (err) {
+        log(`Failed to start BLE scan: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+    }
 });
 timebox
     .command('add <address>')
@@ -1442,11 +1755,22 @@ async function runTimeboxSync(targetOpt, opts, once) {
         ? parseInt(opts.bridgePort, 10)
         : (info?.httpPort ?? info?.port ?? findDaemonPort() ?? BRIDGE_WS_PORT);
     const url = `http://127.0.0.1:${bridgePort}`;
-    const paths = resolveTimeboxSyncPaths();
-    const args = [paths.bleScript, '--address', id, '--url', url, '--brightness', String(brightness), ...(once ? ['--once'] : [])];
+    const runtime = prepareBleRuntime();
+    if (!runtime)
+        return;
+    const args = [
+        runtime.paths.scripts.timeboxSync,
+        '--address',
+        id,
+        '--url',
+        url,
+        '--brightness',
+        String(brightness),
+        ...(once ? ['--once'] : []),
+    ];
     log(`${once ? 'Sending one Timebox frame' : 'Starting Timebox sync'} via BLE ${id} from ${url} (brightness ${brightness}%)...`);
-    const py = spawn(paths.python, args, { stdio: 'inherit' });
-    py.on('close', (code) => {
+    try {
+        const { code } = await runBlePython(runtime.python, args);
         if (once) {
             if (code === 0) {
                 log('Timebox test frame sent.');
@@ -1458,8 +1782,14 @@ async function runTimeboxSync(targetOpt, opts, once) {
         }
         else {
             log(`Timebox sync process exited with code ${code}`);
+            if (code !== 0)
+                process.exitCode = code ?? 1;
         }
-    });
+    }
+    catch (err) {
+        log(`Failed to start Timebox BLE command: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+    }
 }
 timebox
     .command('test [target]')
@@ -2259,7 +2589,7 @@ export async function runCli(argv = process.argv) {
         await showDefaultStatusOrHelp();
         return;
     }
-    program.parse(argv);
+    program.parse(applyGlobalEnvArgs(argv));
 }
 export { program };
 if (isMainModule()) {