@beeos-ai/device-agent 0.4.0

package/dist/fleet/adapters/state/port-allocator.js

@@ -0,0 +1,173 @@
+/**
+ * Adapter — sticky port allocator backed by `~/.beeos/fleet.json`.
+ *
+ * Sticky semantics: once a serial is mapped to a port, that mapping is kept
+ * indefinitely so users can bookmark / paste the URL. The allocator only
+ * forgets a mapping if the persisted port collides with another listener at
+ * acquire time — then we probe the next free port within the configured
+ * range.
+ *
+ * Range: configurable, defaults to `[7900, 7999]` (matches the historical
+ * device-mcp-server default of 7900). 100 slots × per-laptop scale is plenty
+ * even for power users running 30 devices.
+ */
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+const DEFAULT_BASE = 7900;
+const DEFAULT_RANGE = 100;
+const FALLBACK_PORT = 7900;
+export class StickyPortAllocator {
+    filePath;
+    basePort;
+    rangeSize;
+    probe;
+    map = new Map();
+    writeQueue = Promise.resolve();
+    started = false;
+    constructor(opts = {}) {
+        this.filePath = opts.filePath ?? defaultFleetStatePath();
+        this.basePort = opts.basePort ?? DEFAULT_BASE;
+        this.rangeSize = opts.rangeSize ?? DEFAULT_RANGE;
+        this.probe = opts.probe ?? defaultProbe;
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        await this.load();
+    }
+    async stop() {
+        this.started = false;
+        await this.writeQueue;
+    }
+    async acquire(serial) {
+        if (!this.started)
+            await this.start();
+        const sticky = this.map.get(serial);
+        const hint = sticky ?? this.hintFor(serial);
+        const port = await this.findAvailable(serial, hint);
+        if (this.map.get(serial) !== port) {
+            this.map.set(serial, port);
+            this.flush();
+        }
+        return port;
+    }
+    async release(serial) {
+        // Sticky — we keep the mapping. This is a no-op by design but exposed
+        // for symmetry. Tests may call `forget` (below) for full reset.
+        void serial;
+        return;
+    }
+    /** Test/maintenance helper: drop the persisted mapping for a serial. */
+    forget(serial) {
+        if (this.map.delete(serial))
+            this.flush();
+    }
+    snapshot() {
+        return new Map(this.map);
+    }
+    // ── Internals ────────────────────────────────────────────────────────────
+    hintFor(serial) {
+        // Stable hash → base + (h % range). Avoids "everyone gets 7900" stampede.
+        let h = 2166136261; // FNV-1a
+        for (let i = 0; i < serial.length; i++) {
+            h ^= serial.charCodeAt(i);
+            h = Math.imul(h, 16777619);
+        }
+        return this.basePort + (Math.abs(h) % this.rangeSize);
+    }
+    async findAvailable(serial, hint) {
+        // Probe `hint` first (so sticky mappings re-acquire the same port), then
+        // walk the rest of the range. We don't take ports outside the configured
+        // range — easier to firewall.
+        const candidates = [];
+        if (hint >= this.basePort && hint < this.basePort + this.rangeSize) {
+            candidates.push(hint);
+        }
+        for (let i = 0; i < this.rangeSize; i++) {
+            const p = this.basePort + i;
+            if (!candidates.includes(p))
+                candidates.push(p);
+        }
+        // Skip ports already assigned to OTHER serials (in-memory). The current
+        // serial's own existing mapping is allowed (sticky re-acquire).
+        const occupiedByOthers = new Set();
+        for (const [s, p] of this.map) {
+            if (s !== serial)
+                occupiedByOthers.add(p);
+        }
+        for (const port of candidates) {
+            if (occupiedByOthers.has(port))
+                continue;
+            const free = await this.probe(port);
+            if (free)
+                return port;
+        }
+        return FALLBACK_PORT;
+    }
+    async load() {
+        let raw;
+        try {
+            raw = await fs.promises.readFile(this.filePath, "utf8");
+        }
+        catch {
+            return;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || parsed.v !== 1 || !parsed.ports)
+                return;
+            for (const [serial, port] of Object.entries(parsed.ports)) {
+                if (typeof port === "number" && port >= 1024 && port < 65536) {
+                    this.map.set(serial, port);
+                }
+            }
+        }
+        catch {
+            /* corrupt — start clean */
+        }
+    }
+    flush() {
+        const snap = {
+            v: 1,
+            ports: Object.fromEntries(this.map.entries()),
+        };
+        const dir = path.dirname(this.filePath);
+        const data = JSON.stringify(snap, null, 2);
+        this.writeQueue = this.writeQueue.then(async () => {
+            try {
+                await fs.promises.mkdir(dir, { recursive: true });
+                await fs.promises.writeFile(this.filePath, data, "utf8");
+            }
+            catch {
+                /* best-effort */
+            }
+        });
+    }
+}
+// ── Pure helpers (exported for tests) ────────────────────────────────────────
+export function defaultFleetStatePath() {
+    const override = process.env.BEEOS_HOME;
+    const base = override && override.length > 0
+        ? override
+        : path.join(os.homedir(), ".beeos");
+    return path.join(base, "fleet.json");
+}
+async function defaultProbe(port) {
+    return await new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.once("error", () => resolve(false));
+        srv.once("listening", () => {
+            srv.close(() => resolve(true));
+        });
+        try {
+            srv.listen(port, "127.0.0.1");
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+//# sourceMappingURL=port-allocator.js.map

package/dist/fleet/adapters/state/port-allocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-allocator.js","sourceRoot":"","sources":["../../../../src/fleet/adapters/state/port-allocator.ts"],"names":[],"mappings":"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"}

package/dist/fleet/domain/device.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Fleet domain — `Device` entity and lifecycle state.
+ *
+ * A `Device` represents one ADB-connected target (real phone, ReDroid container,
+ * remote `host:port`) under fleet supervision. Each device transitions through
+ * the FSM defined in `./fsm.ts` driven by ADB / process / config / timer events.
+ *
+ * The FSM has 9 named states; see the lifecycle diagram in
+ * `agents/device-agent/CHANGELOG.md` (or the v4 plan) for the full picture.
+ *
+ * Layered decay (HEALTHY → GRACE → DEGRADED → GONE):
+ *   - GRACE keeps mcp + daemon alive for a short window so USB jitter is
+ *     transparent to the user.
+ *   - DEGRADED tears down mcp (which is tightly coupled to ADB pipes) but
+ *     retains the daemon so the BeeOS session and Centrifugo subscription
+ *     survive transient outages.
+ *   - GONE is reached only after a long absence; the daemon is finally killed
+ *     and the user-side session is paused.
+ *
+ * Tunables (`grace_ms`, `keep_ms`) come from env vars or per-device entries in
+ * `~/.beeos/devices.json`; see {@link DeviceBinding}.
+ */
+/** All FSM states a device can occupy. */
+export type FleetState = "adb_offline" | "adb_unauthorized" | "awaiting_bind" | "spawning" | "healthy" | "grace" | "degraded" | "gone" | "crashed";
+/**
+ * Whether a state owns child processes (mcp/daemon) at all. Useful for the
+ * supervisor to decide whether `kill_*` effects are no-ops.
+ */
+export declare function stateExpectsMcp(s: FleetState): boolean;
+export declare function stateExpectsDaemon(s: FleetState): boolean;
+/**
+ * Per-device binding loaded from `~/.beeos/devices.json` (the file owned by
+ * `web/packages/cli` `attach` / `detach`). Fleet treats the file as read-only;
+ * `beeos device attach` is the writer. `instance_id === null` means the user
+ * started attach but didn't complete the platform bind step — fleet must NOT
+ * spawn anything for those entries (treat as `awaiting_bind`).
+ */
+/**
+ * Canonical backend names used by `device-mcp-server` (and forwarded as
+ * `--backend <name>` by the fleet's process manager). Pre-self-hosted
+ * `devices.json` files don't carry this field; the supervisor treats
+ * `undefined` as `adb` for back-compat with v0.1 ADB-only attaches.
+ *
+ * Aliases (`android`/`mac`/`win`/`desktop-{linux,windows,macos}`) are
+ * accepted on read and normalized to the canonical short name in
+ * `toBinding`. See plan §3.4.
+ */
+export type FleetBackend = "adb" | "macos" | "linux" | "windows" | "desktop" | "mock-desktop";
+export interface DeviceBinding {
+    serial: string;
+    name: string;
+    instanceId: string | null;
+    keyFile: string;
+    /** Persisted http_port from `web/packages/cli`. Fleet honours it for the daemon's HTTP debug port (sticky). */
+    httpPort?: number;
+    /**
+     * Video backend selection inherited from `devices.json#video_mode`. Drives
+     * whether the supervisor co-spawns `scrcpy-bridge` alongside mcp + daemon.
+     *
+     *   - `"scrcpy"` — Android/ADB device (default for ADB serials)
+     *   - `"vnc"`    — desktop/macOS/Linux device with a VNC server (vnc-bridge
+     *                  is OS-service-managed, not fleet-managed)
+     *   - `"none"`   — explicit opt-out (e.g. CI)
+     *   - `undefined` — fleet treats as "no scrcpy" to stay backwards
+     *                   compatible with older devices.json entries
+     */
+    videoMode?: "scrcpy" | "vnc" | "none";
+    /**
+     * `device-mcp-server --backend <name>` selection. Drives which capability
+     * set the spawned MCP server exposes. `undefined` is interpreted as `adb`
+     * by the fleet for back-compat (the v0.1 attach flow only ever bound ADB
+     * devices). See {@link FleetBackend}.
+     */
+    backend?: FleetBackend;
+    /** Optional per-device override of `FLEET_ADB_GRACE_MS` (HEALTHY → DEGRADED). */
+    graceMs?: number;
+    /** Optional per-device override of `FLEET_DAEMON_KEEP_MS` (DEGRADED → GONE). */
+    keepMs?: number;
+}
+/**
+ * In-memory FSM record for a single device. The supervisor mutates this via
+ * the pure `step()` function in `./fsm.ts`. PIDs and timer handles live
+ * outside the FSM (the supervisor manages them) so the FSM stays pure /
+ * snapshottable.
+ */
+export interface DeviceRecord {
+    serial: string;
+    name: string;
+    state: FleetState;
+    binding: DeviceBinding | null;
+    /** Monotonic ms timestamp when `state` was last entered. */
+    enteredAt: number;
+    /** Increments on each unexpected child-process exit while ADB was online. */
+    restartCount: number;
+    /** Allocated mcp-server port (sticky across restarts). `0` means unallocated. */
+    mcpPort: number;
+}
+/** Convenient initial value for a freshly-discovered ADB device. */
+export declare function newDeviceRecord(args: {
+    serial: string;
+    name?: string;
+    binding?: DeviceBinding | null;
+    state?: FleetState;
+    now: number;
+}): DeviceRecord;
+/** Liveness summary for the optional scrcpy-bridge sibling. */
+export interface ScrcpyStatus {
+    /**
+     * Whether the device's binding requested scrcpy at all (i.e. `videoMode
+     * === "scrcpy"`). When `false`, all other fields are meaningless and the
+     * supervisor does not co-spawn scrcpy-bridge.
+     */
+    enabled: boolean;
+    /** True iff the supervisor currently observes the scrcpy-bridge child as alive. */
+    running: boolean;
+    pid: number | null;
+    /** Last error/reason recorded for scrcpy-bridge (binary missing, startup_failed, …). */
+    lastError: string | null;
+}
+/** A snapshot exported through the HTTP `/fleet/devices` endpoint. */
+export interface DeviceSnapshot {
+    serial: string;
+    name: string;
+    instanceId: string | null;
+    state: FleetState;
+    mcpUrl: string | null;
+    mcpPid: number | null;
+    daemonPid: number | null;
+    /**
+     * scrcpy-bridge sibling status. Always present (even when scrcpy is
+     * disabled for the device) so that consumers can render a stable shape.
+     */
+    scrcpy: ScrcpyStatus;
+    enteredAt: number;
+    /** ms since the FSM entered the current state, computed at read time. */
+    sinceMs: number;
+    restartCount: number;
+}

package/dist/fleet/domain/device.js

@@ -0,0 +1,49 @@
+/**
+ * Fleet domain — `Device` entity and lifecycle state.
+ *
+ * A `Device` represents one ADB-connected target (real phone, ReDroid container,
+ * remote `host:port`) under fleet supervision. Each device transitions through
+ * the FSM defined in `./fsm.ts` driven by ADB / process / config / timer events.
+ *
+ * The FSM has 9 named states; see the lifecycle diagram in
+ * `agents/device-agent/CHANGELOG.md` (or the v4 plan) for the full picture.
+ *
+ * Layered decay (HEALTHY → GRACE → DEGRADED → GONE):
+ *   - GRACE keeps mcp + daemon alive for a short window so USB jitter is
+ *     transparent to the user.
+ *   - DEGRADED tears down mcp (which is tightly coupled to ADB pipes) but
+ *     retains the daemon so the BeeOS session and Centrifugo subscription
+ *     survive transient outages.
+ *   - GONE is reached only after a long absence; the daemon is finally killed
+ *     and the user-side session is paused.
+ *
+ * Tunables (`grace_ms`, `keep_ms`) come from env vars or per-device entries in
+ * `~/.beeos/devices.json`; see {@link DeviceBinding}.
+ */
+/**
+ * Whether a state owns child processes (mcp/daemon) at all. Useful for the
+ * supervisor to decide whether `kill_*` effects are no-ops.
+ */
+export function stateExpectsMcp(s) {
+    return s === "healthy" || s === "grace" || s === "spawning" || s === "crashed";
+}
+export function stateExpectsDaemon(s) {
+    return (s === "healthy" ||
+        s === "grace" ||
+        s === "degraded" ||
+        s === "spawning" ||
+        s === "crashed");
+}
+/** Convenient initial value for a freshly-discovered ADB device. */
+export function newDeviceRecord(args) {
+    return {
+        serial: args.serial,
+        name: args.name ?? args.binding?.name ?? args.serial,
+        state: args.state ?? "adb_offline",
+        binding: args.binding ?? null,
+        enteredAt: args.now,
+        restartCount: 0,
+        mcpPort: 0,
+    };
+}
+//# sourceMappingURL=device.js.map

package/dist/fleet/domain/device.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../../../src/fleet/domain/device.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAcH;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,CAAa;IAC3C,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,SAAS,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,CAAa;IAC9C,OAAO,CACL,CAAC,KAAK,SAAS;QACf,CAAC,KAAK,OAAO;QACb,CAAC,KAAK,UAAU;QAChB,CAAC,KAAK,UAAU;QAChB,CAAC,KAAK,SAAS,CAChB,CAAC;AACJ,CAAC;AA8ED,oEAAoE;AACpE,MAAM,UAAU,eAAe,CAAC,IAM/B;IACC,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC,MAAM;QACpD,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,aAAa;QAClC,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI;QAC7B,SAAS,EAAE,IAAI,CAAC,GAAG;QACnB,YAAY,EAAE,CAAC;QACf,OAAO,EAAE,CAAC;KACX,CAAC;AACJ,CAAC"}

package/dist/fleet/domain/events.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Fleet domain — event types fed into the FSM (`./fsm.ts`).
+ *
+ * Events are produced by adapters:
+ *  - `LocalAdbSource` / `RemoteAdbSource` → `AdbEvent` (online / offline / unauthorized)
+ *  - `BeeosCliStore` watcher              → `BindingEvent`
+ *  - `ProcessManager`                     → `ProcessEvent` (spawn ack, exit, health)
+ *  - In-process timers                    → `TimerEvent` (grace expiry, keep expiry, restart backoff)
+ *
+ * The FSM is purely a `(state, event) => { next, effects }` reducer; effects
+ * are descriptions (e.g. `{ kind: "spawn_mcp", serial }`) that the supervisor
+ * translates into real `child_process.spawn` calls and timer handles.
+ */
+export interface AdbOnlineEvent {
+    kind: "adb_online";
+    serial: string;
+}
+export interface AdbOfflineEvent {
+    kind: "adb_offline";
+    serial: string;
+}
+export interface AdbUnauthorizedEvent {
+    kind: "adb_unauthorized";
+    serial: string;
+}
+export type AdbEvent = AdbOnlineEvent | AdbOfflineEvent | AdbUnauthorizedEvent;
+export interface BindingAddedEvent {
+    kind: "binding_added";
+    serial: string;
+}
+export interface BindingChangedEvent {
+    kind: "binding_changed";
+    serial: string;
+}
+export interface BindingRemovedEvent {
+    kind: "binding_removed";
+    serial: string;
+}
+export type BindingEvent = BindingAddedEvent | BindingChangedEvent | BindingRemovedEvent;
+export interface McpStartedEvent {
+    kind: "mcp_started";
+    serial: string;
+    pid: number;
+    port: number;
+}
+export interface McpExitedEvent {
+    kind: "mcp_exited";
+    serial: string;
+    /** Process exit code (null when killed by signal). */
+    code: number | null;
+    /** UNIX signal name when killed by signal (`SIGTERM`, `SIGKILL`, …). */
+    signal: NodeJS.Signals | null;
+    /** True if fleet asked for the kill (so the FSM should not penalise restartCount). */
+    expected: boolean;
+}
+export interface DaemonStartedEvent {
+    kind: "daemon_started";
+    serial: string;
+    pid: number;
+}
+export interface DaemonExitedEvent {
+    kind: "daemon_exited";
+    serial: string;
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    expected: boolean;
+}
+/**
+ * `scrcpy-bridge` is an OPTIONAL sibling we co-supervise alongside
+ * mcp + daemon when `video_mode === "scrcpy"`. The pure FSM ignores
+ * these events (scrcpy lifecycle does not gate `healthy`); the
+ * supervisor uses them solely for the `/fleet/devices` snapshot.
+ */
+export interface ScrcpyStartedEvent {
+    kind: "scrcpy_started";
+    serial: string;
+    pid: number;
+}
+export interface ScrcpyExitedEvent {
+    kind: "scrcpy_exited";
+    serial: string;
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    expected: boolean;
+    /** Optional human-readable reason (binary missing, spawn failure, …). */
+    reason?: string;
+}
+export type ProcessEvent = McpStartedEvent | McpExitedEvent | DaemonStartedEvent | DaemonExitedEvent | ScrcpyStartedEvent | ScrcpyExitedEvent;
+export interface GraceExpiredEvent {
+    kind: "grace_expired";
+    serial: string;
+}
+export interface KeepExpiredEvent {
+    kind: "keep_expired";
+    serial: string;
+}
+export interface BackoffElapsedEvent {
+    kind: "backoff_elapsed";
+    serial: string;
+}
+export type TimerEvent = GraceExpiredEvent | KeepExpiredEvent | BackoffElapsedEvent;
+export type FleetEvent = AdbEvent | BindingEvent | ProcessEvent | TimerEvent;

package/dist/fleet/domain/events.js

@@ -0,0 +1,15 @@
+/**
+ * Fleet domain — event types fed into the FSM (`./fsm.ts`).
+ *
+ * Events are produced by adapters:
+ *  - `LocalAdbSource` / `RemoteAdbSource` → `AdbEvent` (online / offline / unauthorized)
+ *  - `BeeosCliStore` watcher              → `BindingEvent`
+ *  - `ProcessManager`                     → `ProcessEvent` (spawn ack, exit, health)
+ *  - In-process timers                    → `TimerEvent` (grace expiry, keep expiry, restart backoff)
+ *
+ * The FSM is purely a `(state, event) => { next, effects }` reducer; effects
+ * are descriptions (e.g. `{ kind: "spawn_mcp", serial }`) that the supervisor
+ * translates into real `child_process.spawn` calls and timer handles.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/fleet/domain/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/fleet/domain/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/fleet/domain/fsm.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Fleet domain — pure FSM reducer.
+ *
+ * Single entry point: `step(record, event, ctx) => { record', effects }`.
+ *
+ * Effects are *intent descriptors* the supervisor (`fleet/supervisor.ts`)
+ * translates into actual side effects (process spawn, timer, log line). This
+ * keeps the FSM trivially testable — the M1 unit suite covers the entire
+ * lifecycle without any IO.
+ *
+ * Lifecycle (see also v4 plan):
+ *   adb_offline ─► (adb_online + bound)        ─► spawning ─► healthy
+ *                  (adb_online + unbound)      ─► awaiting_bind
+ *                  (adb_online + unauthorized) ─► adb_unauthorized
+ *   healthy     ─► (adb_offline)               ─► grace
+ *   grace       ─► (adb_online same serial)    ─► healthy            (USB jitter, transparent)
+ *                  (grace_expired)             ─► degraded           (kill mcp only, daemon survives)
+ *   degraded    ─► (adb_online same serial)    ─► spawning           (respawn mcp, daemon self-heals)
+ *                  (keep_expired)              ─► gone               (kill daemon, session paused)
+ *   gone        ─► (adb_online)                ─► spawning
+ *   healthy     ─► (mcp_exited unexpected)     ─► spawning           (mcp_only_restart)
+ *                  (daemon_exited unexpected)  ─► spawning           (daemon_only_restart)
+ *                  (both crashed back-to-back) ─► crashed → spawning
+ *
+ * The reducer never reads outside its inputs (`record`, `event`, `ctx`) — pure.
+ */
+import type { DeviceRecord } from "./device.js";
+import type { FleetEvent } from "./events.js";
+export interface SpawnMcpEffect {
+    kind: "spawn_mcp";
+    serial: string;
+}
+export interface KillMcpEffect {
+    kind: "kill_mcp";
+    serial: string;
+    /** When true, supervisor records the kill as fleet-initiated → expected exit. */
+    expected: true;
+}
+export interface SpawnDaemonEffect {
+    kind: "spawn_daemon";
+    serial: string;
+}
+export interface KillDaemonEffect {
+    kind: "kill_daemon";
+    serial: string;
+    expected: true;
+}
+export interface StartGraceTimerEffect {
+    kind: "start_grace_timer";
+    serial: string;
+}
+export interface CancelGraceTimerEffect {
+    kind: "cancel_grace_timer";
+    serial: string;
+}
+export interface StartKeepTimerEffect {
+    kind: "start_keep_timer";
+    serial: string;
+}
+export interface CancelKeepTimerEffect {
+    kind: "cancel_keep_timer";
+    serial: string;
+}
+export interface StartBackoffTimerEffect {
+    kind: "start_backoff_timer";
+    serial: string;
+    /** How many failed restarts have already happened. */
+    attempt: number;
+}
+export interface CancelBackoffTimerEffect {
+    kind: "cancel_backoff_timer";
+    serial: string;
+}
+export interface AllocatePortEffect {
+    kind: "allocate_port";
+    serial: string;
+}
+export interface ReleasePortEffect {
+    kind: "release_port";
+    serial: string;
+}
+export interface LogEffect {
+    kind: "log";
+    level: "debug" | "info" | "warn" | "error";
+    serial: string;
+    msg: string;
+    data?: Record<string, unknown>;
+}
+export type FleetEffect = SpawnMcpEffect | KillMcpEffect | SpawnDaemonEffect | KillDaemonEffect | StartGraceTimerEffect | CancelGraceTimerEffect | StartKeepTimerEffect | CancelKeepTimerEffect | StartBackoffTimerEffect | CancelBackoffTimerEffect | AllocatePortEffect | ReleasePortEffect | LogEffect;
+export interface StepContext {
+    /** Monotonic ms (used to set `enteredAt` on transitions). */
+    now: number;
+}
+export interface StepResult {
+    record: DeviceRecord;
+    effects: FleetEffect[];
+}
+/**
+ * Pure FSM reducer.
+ *
+ * Apply `event` to `record` and return the next `record` plus the effects the
+ * supervisor must enact. Events that the current state does not care about
+ * are no-ops (empty effects, identical record).
+ *
+ * Important: the supervisor MUST update `record.binding` before calling
+ * `step()` for binding events, because some transitions consult
+ * `record.binding.instanceId` to decide between `spawning` and
+ * `awaiting_bind`.
+ */
+export declare function step(record: DeviceRecord, event: FleetEvent, ctx: StepContext): StepResult;
+/**
+ * Internal helper for the supervisor: when both children have been observed
+ * alive (mcp_started + daemon_started), the supervisor calls this to flip the
+ * record from `spawning` → `healthy`. Centralised here so the transition
+ * lives next to the rest of the state machine.
+ */
+export declare function markHealthy(record: DeviceRecord, ctx: StepContext): StepResult;
+/**
+ * Backoff schedule used by the supervisor when arming the
+ * `start_backoff_timer` effect.  Exponential with cap.
+ */
+export declare function backoffMs(attempt: number): number;