@beeos-ai/device-agent 0.4.0

package/dist/inbound/cli/fleet-command.js

@@ -0,0 +1,792 @@
+/**
+ * inbound/cli/fleet-command — `device-agent fleet …` subcommand family.
+ *
+ * The fleet supervisor process is a single long-running daemon that:
+ *
+ *   - Listens to ADB events (`adb track-devices`)
+ *   - Watches `~/.beeos/devices.json` for binding changes
+ *   - For every BOUND device, spawns and supervises:
+ *       device-mcp-server  (local AI tooling)
+ *       device-agent       (BeeOS cloud control daemon, Ed25519 → Agent Gateway)
+ *   - Exposes a tiny HTTP status server on `127.0.0.1:7950` for the
+ *     other CLI subcommands (`status`, `devices`, `restart`, `reload`).
+ *
+ * The CLI splits into two halves:
+ *
+ *   server side: `start [--no-daemon]` → builds the `FleetSupervisor` and
+ *                serves `/fleet/*` over HTTP.
+ *   client side: `status | devices | restart | reload` → opens an HTTP
+ *                connection to the running fleet on `:7950`.
+ *
+ * All client-side commands fail fast with an actionable hint when the
+ * fleet isn't running. There is intentionally NO auto-spawn: the user is
+ * expected to start the fleet via `fleet start` (foreground) or `fleet
+ * enable` (launchd / systemd, M5 in a follow-up plan).
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import { BeeosCliStore, defaultDevicesPath, } from "../../fleet/adapters/state/beeos-cli-store.js";
+import { StickyPortAllocator, defaultFleetStatePath } from "../../fleet/adapters/state/port-allocator.js";
+import { LocalAdbSource } from "../../fleet/adapters/sources/local-adb.js";
+import { NodeProcessManager } from "../../fleet/adapters/process/node-process-manager.js";
+import { SystemClock } from "../../fleet/ports/clock.js";
+import { FleetSupervisor } from "../../fleet/supervisor.js";
+import { StatusServer } from "../../fleet/http/status-server.js";
+import { FleetStatusClient, FleetClientError } from "../../fleet/http/status-client.js";
+import { buildFleetServiceSpec, deriveFleetSpawnEnv, FLEET_LABEL, fleetPlistPath, installFleetLaunchd, migrateFromAttach, uninstallFleetLaunchd, } from "../../fleet/installer/index.js";
+import { getLogger } from "../../logger/index.js";
+export async function fleetCommand(argv, io = {}) {
+    const stdout = io.stdout ?? process.stdout;
+    const stderr = io.stderr ?? process.stderr;
+    const sub = argv[0];
+    if (!sub || sub === "-h" || sub === "--help" || sub === "help") {
+        printUsage(stdout);
+        return sub ? 0 : 2;
+    }
+    switch (sub) {
+        case "start":
+            return startCommand(argv.slice(1), { stdout, stderr });
+        case "status":
+            return statusCommand({ stdout, stderr });
+        case "devices":
+            return devicesCommand(argv.slice(1), { stdout, stderr });
+        case "restart":
+            return restartCommand(argv.slice(1), { stdout, stderr });
+        case "reload":
+            return reloadCommand({ stdout, stderr });
+        case "stop":
+            return stopCommand({ stdout, stderr });
+        case "enable":
+            return enableCommand(argv.slice(1), { stdout, stderr });
+        case "disable":
+            return disableCommand({ stdout, stderr });
+        case "migrate-from-attach":
+            return migrateCommand({ stdout, stderr });
+        case "logs":
+            return logsCommand(argv.slice(1), { stdout, stderr });
+        default:
+            stderr.write(`device-agent fleet: unknown subcommand '${sub}'\n`);
+            printUsage(stderr);
+            return 2;
+    }
+}
+function parseStartArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`Missing value for ${a}`);
+            return v;
+        };
+        switch (a) {
+            case "-h":
+            case "--help":
+                out.help = true;
+                break;
+            case "--no-daemon":
+                out.noDaemon = true;
+                break;
+            case "--agent-gateway-url":
+                out.agentGatewayUrl = next();
+                break;
+            case "--grace-ms":
+                out.graceMs = Number(next());
+                break;
+            case "--keep-ms":
+                out.keepMs = Number(next());
+                break;
+            case "--port":
+                out.port = Number(next());
+                break;
+            default:
+                if (a.startsWith("--")) {
+                    throw new Error(`device-agent fleet start: unknown flag ${a}`);
+                }
+        }
+    }
+    return out;
+}
+async function startCommand(argv, io) {
+    let flags;
+    try {
+        flags = parseStartArgs(argv);
+    }
+    catch (e) {
+        io.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    if (flags.help) {
+        io.stdout.write(`device-agent fleet start — run the supervisor in the foreground
+
+Usage:
+  device-agent fleet start [options]
+
+Options:
+  --no-daemon              (reserved) skip OS service detach (current default)
+  --agent-gateway-url URL  Default Agent Gateway URL injected into spawned daemons
+  --grace-ms <n>           HEALTHY → DEGRADED window in ms (default 5000, env FLEET_ADB_GRACE_MS)
+  --keep-ms <n>            DEGRADED → GONE window in ms (default 300000, env FLEET_DAEMON_KEEP_MS)
+  --port <n>               Status HTTP port on loopback (default 7950, env FLEET_STATUS_PORT)
+  -h, --help               Show this help
+`);
+        return 0;
+    }
+    const log = getLogger().child({ component: "fleet" });
+    const supervisorLogger = {
+        debug: (msg, data) => log.debug({ ...data }, msg),
+        info: (msg, data) => log.info({ ...data }, msg),
+        warn: (msg, data) => log.warn({ ...data }, msg),
+        error: (msg, data) => log.error({ ...data }, msg),
+    };
+    const registry = new BeeosCliStore({ filePath: defaultDevicesPath() });
+    const allocator = new StickyPortAllocator({ filePath: defaultFleetStatePath() });
+    // NOTE: every adapter inside `fleet/` defines its OWN logger shape
+    // — `(msg: string, data?: Record<string, unknown>)`. Pino's runtime
+    // calling convention is the OPPOSITE: `(obj, msg)`. Passing the
+    // raw pino logger therefore swallows every structured field
+    // (observed in M11 dogfooding: `child error` arrived without
+    // `serial` / `error`). The wrapper above (`supervisorLogger`)
+    // bridges the two conventions, so every adapter must use it
+    // — not the bare `log`.
+    const source = new LocalAdbSource({ logger: supervisorLogger });
+    const processManager = new NodeProcessManager({ logger: supervisorLogger });
+    const clock = new SystemClock();
+    const supervisor = new FleetSupervisor({
+        source,
+        registry,
+        allocator,
+        processManager,
+        clock,
+        graceMs: flags.graceMs,
+        keepMs: flags.keepMs,
+        logger: supervisorLogger,
+        defaultAgentGatewayUrl: flags.agentGatewayUrl ?? process.env.AGENT_GATEWAY_URL ?? undefined,
+    });
+    let stopping = false;
+    const shutdown = async (signal) => {
+        if (stopping)
+            return 0;
+        stopping = true;
+        log.info({ signal }, "fleet shutdown initiated");
+        try {
+            await status.stop();
+            await supervisor.stop();
+            log.info("fleet shutdown complete");
+            return 0;
+        }
+        catch (e) {
+            log.error({ err: String(e) }, "fleet shutdown failed");
+            return 1;
+        }
+    };
+    const status = new StatusServer({
+        supervisor,
+        port: flags.port ?? Number(process.env.FLEET_STATUS_PORT ?? 7950),
+        logger: supervisorLogger,
+        onShutdown: () => {
+            // POST /fleet/shutdown — defer to the same path as SIGTERM so we
+            // exit with the same lifecycle order regardless of whether the
+            // signal came from launchd, the user, or the CLI's `fleet stop`.
+            void shutdown("HTTP /fleet/shutdown").then((c) => process.exit(c));
+        },
+    });
+    process.once("SIGINT", () => {
+        void shutdown("SIGINT").then((c) => process.exit(c));
+    });
+    process.once("SIGTERM", () => {
+        void shutdown("SIGTERM").then((c) => process.exit(c));
+    });
+    try {
+        await supervisor.start();
+        await status.start();
+        log.info({
+            host: status.address.host,
+            port: status.address.port,
+            beeosHome: defaultDevicesPath(),
+            host_os: os.platform(),
+        }, "fleet supervisor running");
+    }
+    catch (e) {
+        log.error({ err: String(e) }, "fleet supervisor failed to start");
+        await status.stop().catch(() => { });
+        await supervisor.stop().catch(() => { });
+        return 1;
+    }
+    await new Promise((resolve) => {
+        process.once("beforeExit", () => resolve());
+    });
+    return 0;
+}
+// ── client-side commands ────────────────────────────────────────────────────
+async function statusCommand(io) {
+    const client = new FleetStatusClient();
+    const alive = await client.healthz();
+    if (!alive) {
+        io.stdout.write("fleet: NOT RUNNING\n");
+        io.stdout.write("hint: start it with `device-agent fleet start`\n");
+        return 1;
+    }
+    try {
+        const devices = await client.listDevices();
+        io.stdout.write(`fleet: RUNNING (${devices.length} device${devices.length === 1 ? "" : "s"})\n`);
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof FleetClientError) {
+            io.stderr.write(`${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}
+function parseDevicesArgs(argv) {
+    const out = {};
+    for (const a of argv) {
+        if (a === "--json")
+            out.json = true;
+        else if (a === "-h" || a === "--help")
+            out.help = true;
+        else if (a.startsWith("--"))
+            throw new Error(`fleet devices: unknown flag ${a}`);
+    }
+    return out;
+}
+async function devicesCommand(argv, io) {
+    let flags;
+    try {
+        flags = parseDevicesArgs(argv);
+    }
+    catch (e) {
+        io.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    if (flags.help) {
+        io.stdout.write(`device-agent fleet devices — list managed devices
+
+Usage:
+  device-agent fleet devices [--json]
+`);
+        return 0;
+    }
+    const client = new FleetStatusClient();
+    let devices;
+    try {
+        devices = await client.listDevices();
+    }
+    catch (e) {
+        if (e instanceof FleetClientError) {
+            io.stderr.write(`${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+    if (flags.json) {
+        io.stdout.write(`${JSON.stringify(devices, null, 2)}\n`);
+        return 0;
+    }
+    if (devices.length === 0) {
+        io.stdout.write("(no devices discovered)\n");
+        return 0;
+    }
+    const rows = [
+        ["SERIAL", "NAME", "STATE", "INSTANCE", "MCP", "DAEMON", "SCRCPY", "AGE"],
+    ];
+    for (const d of devices) {
+        rows.push([
+            d.serial,
+            d.name,
+            d.state.toUpperCase(),
+            d.instanceId ?? "—",
+            d.mcpUrl
+                ? `${d.mcpUrl}${d.mcpPid ? ` pid:${d.mcpPid}` : ""}`
+                : "—",
+            d.daemonPid ? `pid:${d.daemonPid}` : "—",
+            formatScrcpy(d.scrcpy),
+            formatAge(d.sinceMs),
+        ]);
+    }
+    io.stdout.write(formatTable(rows));
+    return 0;
+}
+async function restartCommand(argv, io) {
+    const target = argv[0];
+    if (!target || target === "-h" || target === "--help") {
+        io.stdout.write(`device-agent fleet restart — restart a device's mcp + daemon pair
+
+Usage:
+  device-agent fleet restart <serial-or-name>
+`);
+        return target ? 0 : 2;
+    }
+    const client = new FleetStatusClient();
+    // Resolve name → serial first if needed.
+    let serial = target;
+    try {
+        const devices = await client.listDevices();
+        const match = devices.find((d) => d.serial === target || d.name === target);
+        if (!match) {
+            io.stderr.write(`fleet: no device matches '${target}'.\n`);
+            io.stderr.write("hint: run `device-agent fleet devices` to see available serials.\n");
+            return 1;
+        }
+        serial = match.serial;
+    }
+    catch (e) {
+        if (e instanceof FleetClientError) {
+            io.stderr.write(`${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+    try {
+        const ok = await client.restartDevice(serial);
+        if (!ok) {
+            io.stderr.write(`fleet: serial '${serial}' is unknown to the supervisor.\n`);
+            return 1;
+        }
+        io.stdout.write(`fleet: restart accepted for ${serial}\n`);
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof FleetClientError) {
+            io.stderr.write(`${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}
+async function reloadCommand(io) {
+    const client = new FleetStatusClient();
+    try {
+        await client.reload();
+        io.stdout.write("fleet: reload accepted\n");
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof FleetClientError) {
+            io.stderr.write(`${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}
+function parseEnableArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`Missing value for ${a}`);
+            return v;
+        };
+        switch (a) {
+            case "-h":
+            case "--help":
+                out.help = true;
+                break;
+            case "--cli-entry":
+                out.cliEntry = next();
+                break;
+            case "--agent-gateway-url":
+                out.agentGatewayUrl = next();
+                break;
+            case "--grace-ms":
+                out.graceMs = Number(next());
+                break;
+            case "--keep-ms":
+                out.keepMs = Number(next());
+                break;
+            case "--port":
+                out.port = Number(next());
+                break;
+            default:
+                if (a.startsWith("--")) {
+                    throw new Error(`device-agent fleet enable: unknown flag ${a}`);
+                }
+        }
+    }
+    return out;
+}
+async function enableCommand(argv, io) {
+    let flags;
+    try {
+        flags = parseEnableArgs(argv);
+    }
+    catch (e) {
+        io.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    if (flags.help) {
+        io.stdout.write(`device-agent fleet enable — register the fleet supervisor as an OS service
+
+Usage:
+  device-agent fleet enable [options]
+
+Options:
+  --cli-entry PATH         Absolute path to the device-agent CLI entry. Defaults
+                           to the entry that's running this command.
+  --agent-gateway-url URL  Agent Gateway URL injected into spawned daemons.
+                           Defaults to the AGENT_GATEWAY_URL env var.
+  --grace-ms <n>           HEALTHY → DEGRADED window (env FLEET_ADB_GRACE_MS).
+  --keep-ms <n>            DEGRADED → GONE window (env FLEET_DAEMON_KEEP_MS).
+  --port <n>               Override status server port (env FLEET_STATUS_PORT).
+
+Currently macOS-only. Linux (systemd --user) and Windows (Task Scheduler)
+support is tracked separately.
+`);
+        return 0;
+    }
+    if (process.platform !== "darwin") {
+        io.stderr.write(`device-agent fleet enable: not yet supported on ${process.platform}.\n` +
+            "Run `device-agent fleet start` manually instead.\n");
+        return 2;
+    }
+    const cliEntry = flags.cliEntry ?? resolveCliEntryGuess();
+    if (!cliEntry) {
+        io.stderr.write("fleet enable: could not detect device-agent CLI entry path. " +
+            "Re-run with `--cli-entry /absolute/path/to/cli.js`.\n");
+        return 2;
+    }
+    if (!path.isAbsolute(cliEntry)) {
+        io.stderr.write(`fleet enable: --cli-entry must be absolute: ${cliEntry}\n`);
+        return 2;
+    }
+    if (!(await fileExists(cliEntry))) {
+        io.stderr.write(`fleet enable: --cli-entry not found: ${cliEntry}\n`);
+        return 2;
+    }
+    // Build the operator-level overrides (CLI flags + explicit env). The
+    // derivation step seeds defaults (PATH, BEEOS_DEVICE_*_BIN,
+    // AGENT_GATEWAY_URL/BRIDGE_URL from ~/.beeos/config.toml) which the
+    // overrides win over.
+    const overrides = {};
+    const explicitAgw = flags.agentGatewayUrl ?? process.env.AGENT_GATEWAY_URL;
+    if (explicitAgw)
+        overrides.AGENT_GATEWAY_URL = explicitAgw;
+    if (flags.graceMs !== undefined && Number.isFinite(flags.graceMs)) {
+        overrides.FLEET_ADB_GRACE_MS = String(flags.graceMs);
+    }
+    if (flags.keepMs !== undefined && Number.isFinite(flags.keepMs)) {
+        overrides.FLEET_DAEMON_KEEP_MS = String(flags.keepMs);
+    }
+    if (flags.port !== undefined && Number.isFinite(flags.port)) {
+        overrides.FLEET_STATUS_PORT = String(flags.port);
+    }
+    const { env, warnings: envWarnings } = await deriveFleetSpawnEnv({
+        cliEntry,
+        overrides,
+    });
+    const spec = buildFleetServiceSpec({ cliEntry, env });
+    let result;
+    try {
+        result = await installFleetLaunchd(spec);
+    }
+    catch (e) {
+        io.stderr.write(`fleet enable: install failed: ${e.message}\n`);
+        return 1;
+    }
+    io.stdout.write(`fleet enabled (label=${spec.label})\n`);
+    io.stdout.write(`  plist: ${result.plistPath}\n`);
+    io.stdout.write(`  log:   ${spec.logFile}\n`);
+    io.stdout.write(`  bootstrap: ${result.bootstrapped ? "ok" : "skipped (see warnings)"}\n`);
+    // Visibility into discovered binaries / config so operators can spot
+    // a misconfigured AGENT_GATEWAY_URL or missing scrcpy-bridge BEFORE
+    // children start crashing. Logged in dependency order so a missing
+    // PATH (rare) shows up first.
+    if (env.PATH)
+        io.stdout.write(`  PATH:   captured\n`);
+    if (env.AGENT_GATEWAY_URL) {
+        io.stdout.write(`  agent-gateway-url: ${env.AGENT_GATEWAY_URL}\n`);
+    }
+    else {
+        io.stdout.write(`  agent-gateway-url: <unset>  (set --agent-gateway-url or platform.agent_gateway_url in ~/.beeos/config.toml)\n`);
+    }
+    if (env.BEEOS_DEVICE_AGENT_BIN) {
+        io.stdout.write(`  device-agent: ${env.BEEOS_DEVICE_AGENT_BIN}\n`);
+    }
+    if (env.BEEOS_DEVICE_MCP_BIN) {
+        io.stdout.write(`  device-mcp:   ${env.BEEOS_DEVICE_MCP_BIN}\n`);
+    }
+    if (env.BEEOS_SCRCPY_BRIDGE_BIN) {
+        io.stdout.write(`  scrcpy-bridge: ${env.BEEOS_SCRCPY_BRIDGE_BIN}\n`);
+    }
+    for (const w of envWarnings) {
+        io.stdout.write(`  warning: ${w}\n`);
+    }
+    for (const w of result.warnings) {
+        io.stdout.write(`  warning: ${w}\n`);
+    }
+    io.stdout.write("Verify: launchctl print gui/$(id -u)/" + spec.label + "  # or `device-agent fleet status`\n");
+    return 0;
+}
+async function disableCommand(io) {
+    if (process.platform !== "darwin") {
+        io.stderr.write(`device-agent fleet disable: not yet supported on ${process.platform}.\n`);
+        return 2;
+    }
+    let result;
+    try {
+        result = await uninstallFleetLaunchd(FLEET_LABEL);
+    }
+    catch (e) {
+        io.stderr.write(`fleet disable failed: ${e.message}\n`);
+        return 1;
+    }
+    if (!result.removed) {
+        io.stdout.write(`fleet: nothing installed (${result.plistPath} not found)\n`);
+    }
+    else {
+        io.stdout.write(`fleet disabled — removed ${result.plistPath}\n`);
+    }
+    for (const w of result.warnings) {
+        io.stdout.write(`  warning: ${w}\n`);
+    }
+    return 0;
+}
+async function migrateCommand(io) {
+    if (process.platform !== "darwin") {
+        io.stderr.write(`device-agent fleet migrate-from-attach: not yet supported on ${process.platform}.\n`);
+        return 2;
+    }
+    let result;
+    try {
+        result = await migrateFromAttach();
+    }
+    catch (e) {
+        io.stderr.write(`fleet migrate failed: ${e.message}\n`);
+        return 1;
+    }
+    const a = result.removedDeviceAgents.length;
+    const b = result.removedScrcpyBridges.length;
+    if (a === 0 && b === 0) {
+        io.stdout.write("fleet: no legacy per-device launchd entries found\n");
+    }
+    else {
+        io.stdout.write(`Removed ${a} device-agent + ${b} scrcpy-bridge launchd entries; fleet now exclusive\n`);
+        for (const label of result.removedDeviceAgents) {
+            io.stdout.write(`  - ${label}\n`);
+        }
+        for (const label of result.removedScrcpyBridges) {
+            io.stdout.write(`  - ${label}\n`);
+        }
+    }
+    for (const w of result.warnings) {
+        io.stdout.write(`  warning: ${w}\n`);
+    }
+    return 0;
+}
+async function stopCommand(io) {
+    // Prefer the in-band shutdown route — it lets a fleet started in the
+    // foreground (e.g. via `goreman` or `pnpm dev`) exit cleanly without
+    // launchctl. Fall back to launchctl stop only when the HTTP route is
+    // unreachable AND we're on macOS.
+    const client = new FleetStatusClient();
+    if (await client.healthz()) {
+        try {
+            const accepted = await client.shutdown();
+            if (accepted) {
+                io.stdout.write("fleet: shutdown requested via HTTP\n");
+                return 0;
+            }
+            io.stdout.write("fleet: HTTP shutdown not supported by this supervisor build; falling back to launchctl\n");
+        }
+        catch (e) {
+            if (!(e instanceof FleetClientError))
+                throw e;
+            io.stderr.write(`fleet: HTTP shutdown failed: ${e.message}\n`);
+        }
+    }
+    if (process.platform !== "darwin") {
+        io.stderr.write("fleet stop: HTTP unreachable and launchctl fallback only available on macOS.\n");
+        return 1;
+    }
+    try {
+        const { execFile } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execFileP = promisify(execFile);
+        await execFileP("launchctl", ["stop", FLEET_LABEL]);
+        io.stdout.write("fleet: launchctl stop issued\n");
+        return 0;
+    }
+    catch (e) {
+        io.stderr.write(`fleet stop: launchctl fallback failed: ${e.message}\n`);
+        return 1;
+    }
+}
+function parseLogsArgs(argv) {
+    const out = {};
+    for (const a of argv) {
+        if (a === "-f" || a === "--follow")
+            out.follow = true;
+        else if (a === "-h" || a === "--help")
+            out.help = true;
+        else if (a.startsWith("--"))
+            throw new Error(`fleet logs: unknown flag ${a}`);
+        else if (!out.serial)
+            out.serial = a;
+    }
+    return out;
+}
+async function logsCommand(argv, io) {
+    let flags;
+    try {
+        flags = parseLogsArgs(argv);
+    }
+    catch (e) {
+        io.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    if (flags.help) {
+        io.stdout.write(`device-agent fleet logs — tail the fleet supervisor log
+
+Usage:
+  device-agent fleet logs [-f] [serial]
+
+Options:
+  -f, --follow   Follow new lines (like \`tail -f\`)
+  serial         Filter to lines containing this serial (substring match)
+`);
+        return 0;
+    }
+    const logFile = path.join(beeosHome(), "logs", "device-fleet.log");
+    if (!(await fileExists(logFile))) {
+        io.stderr.write(`fleet logs: ${logFile} does not exist yet — has the fleet been started?\n` +
+            "  hint: `device-agent fleet enable` (launchd) or `device-agent fleet start` (foreground)\n");
+        return 1;
+    }
+    const grep = flags.serial;
+    // Use `tail` for follow + grep — far simpler than reimplementing
+    // streaming + filter in Node and matches what an operator would type
+    // by hand. This is intentionally a thin convenience wrapper.
+    const { spawn } = await import("node:child_process");
+    const tailArgs = flags.follow ? ["-n", "200", "-f", logFile] : ["-n", "1000", logFile];
+    const tail = spawn("tail", tailArgs, { stdio: ["ignore", "pipe", "inherit"] });
+    return await new Promise((resolve) => {
+        if (!tail.stdout) {
+            io.stderr.write("fleet logs: failed to capture tail stdout\n");
+            resolve(1);
+            return;
+        }
+        let buf = "";
+        tail.stdout.setEncoding("utf8");
+        tail.stdout.on("data", (chunk) => {
+            buf += chunk;
+            const lines = buf.split("\n");
+            buf = lines.pop() ?? "";
+            for (const line of lines) {
+                if (grep && !line.includes(grep))
+                    continue;
+                io.stdout.write(`${line}\n`);
+            }
+        });
+        tail.on("close", (code) => {
+            if (buf) {
+                if (!grep || buf.includes(grep))
+                    io.stdout.write(buf);
+            }
+            resolve(code ?? 0);
+        });
+        tail.on("error", (err) => {
+            io.stderr.write(`fleet logs: tail spawn failed: ${err.message}\n`);
+            resolve(1);
+        });
+        // Forward Ctrl-C cleanly when running in --follow.
+        process.once("SIGINT", () => {
+            tail.kill("SIGINT");
+        });
+    });
+}
+// ── helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Best-effort detection of the device-agent CLI entry — what the current
+ * process is running. Used as the default `--cli-entry` for `fleet
+ * enable` so users don't have to type a path. Returns null when running
+ * via REPL / unit test where the entry isn't a stable file.
+ */
+function resolveCliEntryGuess() {
+    // Node populates argv[1] with the script path when launched via
+    // `node /path/to/script.js …`. Anything else (e.g. REPL, --eval) is
+    // not a reliable path we can hand to launchd.
+    const script = process.argv[1];
+    if (!script || !path.isAbsolute(script))
+        return null;
+    return script;
+}
+/** Resolve the BeeOS home dir (override-aware). */
+function beeosHome() {
+    const override = process.env.BEEOS_HOME;
+    if (override && override.length > 0)
+        return override;
+    return path.join(os.homedir(), ".beeos");
+}
+async function fileExists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Avoid unused-warning for fleetPlistPath (will be used by tests/docs).
+void fleetPlistPath;
+function printUsage(out) {
+    out.write(`device-agent fleet — multi-device supervisor
+
+Usage:
+  device-agent fleet start [options]            Run the supervisor (foreground)
+  device-agent fleet enable [--cli-entry PATH]  Register OS service (macOS launchd)
+  device-agent fleet disable                    Stop + unregister OS service
+  device-agent fleet migrate-from-attach        Remove legacy per-device launchd entries
+  device-agent fleet stop                       Graceful shutdown of running supervisor
+  device-agent fleet logs [-f] [serial]         Tail fleet log (filtered by serial)
+  device-agent fleet status                     Print supervisor liveness
+  device-agent fleet devices [--json]           List managed devices
+  device-agent fleet restart <serial-or-name>   Restart one device's mcp + daemon
+  device-agent fleet reload                     Re-read ~/.beeos/devices.json
+
+Environment:
+  FLEET_STATUS_PORT     HTTP status server port (default 7950)
+  FLEET_ADB_GRACE_MS    HEALTHY → DEGRADED window (default 5000)
+  FLEET_DAEMON_KEEP_MS  DEGRADED → GONE window (default 300000)
+  AGENT_GATEWAY_URL     Default Agent Gateway URL for spawned daemons
+  BEEOS_HOME            Override ~/.beeos location
+`);
+}
+function formatTable(rows) {
+    if (rows.length === 0)
+        return "";
+    const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => (r[i] ?? "").length)));
+    const lines = [];
+    for (const r of rows) {
+        lines.push(r
+            .map((cell, i) => (cell ?? "").padEnd(widths[i]))
+            .join("  ")
+            .trimEnd());
+    }
+    return `${lines.join("\n")}\n`;
+}
+function formatScrcpy(status) {
+    if (!status.enabled)
+        return "—";
+    if (status.running)
+        return status.pid ? `pid:${status.pid}` : "running";
+    return status.lastError ? `err:${status.lastError}` : "off";
+}
+function formatAge(ms) {
+    if (ms < 1_000)
+        return `${ms}ms`;
+    const s = Math.floor(ms / 1_000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m${s % 60}s`;
+    const h = Math.floor(m / 60);
+    return `${h}h${m % 60}m`;
+}
+//# sourceMappingURL=fleet-command.js.map