@agentdeck/bridge 1.0.22 → 1.0.24

package/dist/daemon-takeover.d.ts

@@ -43,6 +43,9 @@ export interface TakeoverDeps {
     shutdown: (port: number) => Promise<void>;
     waitForExit: (port: number, timeoutMs: number) => Promise<boolean>;
     waitForBindable: (port: number, timeoutMs: number) => Promise<boolean>;
+    /** Best-effort derived APME projection capture before the Swift listener
+     *  disappears. Never blocks takeover on failure. */
+    captureActivity?: (port: number, token: unknown) => Promise<boolean>;
 }
 export type TakeoverOutcome = 
 /** Nothing in the way (or it yielded) — go bind. */

package/dist/daemon-takeover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemon-takeover.d.ts","sourceRoot":"","sources":["../src/daemon-takeover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAGxE,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,kBAAkB,CAAC;IACnE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,2DAA2D;IAC3D,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACxC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE;AAED,MAAM,MAAM,eAAe;AACzB,oDAAoD;AAClD,SAAS;AACX,2DAA2D;GACzD,iBAAiB;AACnB,0EAA0E;GACxE,QAAQ,CAAC;AAEb;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAC3C,SAAS,GAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,kBAAuC,GACrF,OAAO,CAET;AASD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,EACnF,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,eAAe,CAAC,CAmG1B"}
+{"version":3,"file":"daemon-takeover.d.ts","sourceRoot":"","sources":["../src/daemon-takeover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAGxE,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,kBAAkB,CAAC;IACnE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,2DAA2D;IAC3D,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACxC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE;wDACoD;IACpD,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE;AAED,MAAM,MAAM,eAAe;AACzB,oDAAoD;AAClD,SAAS;AACX,2DAA2D;GACzD,iBAAiB;AACnB,0EAA0E;GACxE,QAAQ,CAAC;AAEb;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAC3C,SAAS,GAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,kBAAuC,GACrF,OAAO,CAET;AASD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,EACnF,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,eAAe,CAAC,CAwG1B"}

package/dist/daemon-takeover.js

@@ -81,6 +81,11 @@ export async function negotiateIncumbentDaemon(args, deps) {
         log(`Daemon already running on port ${port}. Use 'agentdeck daemon stop' first.`);
         return 'already-running';
     }
+    if (deps.captureActivity) {
+        const captured = await deps.captureActivity(port, incumbent.pairingToken);
+        if (captured)
+            log(`Merged the app daemon's activity history into the CLI dashboard cache.`);
+    }
     // Reverse two-tier upgrade path: the macOS app may already own the canonical
     // port with its in-process Swift daemon (Tier 1 — limited: no ADB devices,
     // no subscription usage, …). A plain "already running → exit" would strand

package/dist/daemon-takeover.js.map

@@ -1 +1 @@
-{"version":3,"file":"daemon-takeover.js","sourceRoot":"","sources":["../src/daemon-takeover.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"daemon-takeover.js","sourceRoot":"","sources":["../src/daemon-takeover.ts"],"names":[],"mappings":"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"}

package/dist/daemon.js

@@ -17,7 +17,7 @@ const program = new Command();
 program
     .name('agentdeck')
     .description('AgentDeck daemon (legacy entry point — use `agentdeck daemon` instead)')
-    .version('1.0.22');
+    .version('1.0.24');
 program
     .command('start', { isDefault: true })
     .description('Start monitoring daemon')

package/dist/esp32-flash-lease.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The serial-suspend lease: "nobody but the flasher may open a serial port
+ * until <when>".
+ *
+ * WHY IT IS A FILE AND NOT A VARIABLE. The recorded failure this exists to fix
+ * was not the daemon we asked to stand down — it was the daemon that came back.
+ * An in-process pause dies with the process; a respawn (LaunchAgent, a user
+ * re-running `daemon start`, the app relaunching) opens every port again and
+ * DTR-resets the board mid-write. A lease on disk survives that, because the
+ * respawned daemon reads it before its first poll.
+ *
+ * WHY EXPIRY IS ENFORCED ON READ, NEVER BY A TIMER. Same rule the pairing
+ * window follows. A timer on a laptop that sleeps fires late, and a late timer
+ * extends the suspension past what was promised — the daemon stays deaf to
+ * every board for as long as the machine was asleep. Reading the clock at the
+ * point of use cannot do that, and it also self-heals when the CLI is killed
+ * mid-flash: nothing has to run to end the lease, it simply stops being true.
+ *
+ * HONEST GAP: the sandboxed Swift daemon cannot read `~/.agentdeck`, so a lease
+ * written here does not stop it. That is why the CLI also runs an `lsof`
+ * pre-check and refuses to start when a non-AgentDeck process holds the port,
+ * and why it verifies after writing rather than trusting the suspension.
+ */
+export interface FlashLease {
+    /** epoch ms after which the lease means nothing */
+    until: number;
+    /** who asked, for a human reading the file or the log */
+    reason: string;
+    /** pid of the requester, informational only — never a liveness test */
+    pid?: number;
+    board?: string;
+}
+/** Clamp, so a caller cannot suspend the daemon's device layer indefinitely. */
+export declare const LEASE_MIN_SECONDS = 1;
+export declare const LEASE_MAX_SECONDS = 900;
+export declare function leaseFile(): string;
+export declare function clampLeaseSeconds(seconds: unknown): number;
+/**
+ * The lease, or null. Expiry is applied HERE — the only place that reads it —
+ * so no caller can observe an expired lease as active.
+ */
+export declare function readLease(now?: number, file?: string): FlashLease | null;
+export declare function serialSuspended(now?: number): boolean;
+export declare function writeLease(lease: FlashLease, file?: string): FlashLease;
+/** Idempotent: resuming when nothing is suspended is a success, not an error. */
+export declare function clearLease(file?: string): void;
+//# sourceMappingURL=esp32-flash-lease.d.ts.map

package/dist/esp32-flash-lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esp32-flash-lease.d.ts","sourceRoot":"","sources":["../src/esp32-flash-lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAI1D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,SAAa,EAAE,IAAI,SAAc,GAAG,UAAU,GAAG,IAAI,CAajF;AAED,wBAAgB,eAAe,CAAC,GAAG,SAAa,GAAG,OAAO,CAEzD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,SAAc,GAAG,UAAU,CAS5E;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,SAAc,GAAG,IAAI,CAMnD"}

package/dist/esp32-flash-lease.js

@@ -0,0 +1,84 @@
+/**
+ * The serial-suspend lease: "nobody but the flasher may open a serial port
+ * until <when>".
+ *
+ * WHY IT IS A FILE AND NOT A VARIABLE. The recorded failure this exists to fix
+ * was not the daemon we asked to stand down — it was the daemon that came back.
+ * An in-process pause dies with the process; a respawn (LaunchAgent, a user
+ * re-running `daemon start`, the app relaunching) opens every port again and
+ * DTR-resets the board mid-write. A lease on disk survives that, because the
+ * respawned daemon reads it before its first poll.
+ *
+ * WHY EXPIRY IS ENFORCED ON READ, NEVER BY A TIMER. Same rule the pairing
+ * window follows. A timer on a laptop that sleeps fires late, and a late timer
+ * extends the suspension past what was promised — the daemon stays deaf to
+ * every board for as long as the machine was asleep. Reading the clock at the
+ * point of use cannot do that, and it also self-heals when the CLI is killed
+ * mid-flash: nothing has to run to end the lease, it simply stops being true.
+ *
+ * HONEST GAP: the sandboxed Swift daemon cannot read `~/.agentdeck`, so a lease
+ * written here does not stop it. That is why the CLI also runs an `lsof`
+ * pre-check and refuses to start when a non-AgentDeck process holds the port,
+ * and why it verifies after writing rather than trusting the suspension.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { getDataDir } from './session-registry.js';
+import { debug } from './logger.js';
+/** Clamp, so a caller cannot suspend the daemon's device layer indefinitely. */
+export const LEASE_MIN_SECONDS = 1;
+export const LEASE_MAX_SECONDS = 900;
+export function leaseFile() {
+    return join(getDataDir(), 'esp32-flash-lease.json');
+}
+export function clampLeaseSeconds(seconds) {
+    const n = Number(seconds);
+    if (!Number.isFinite(n))
+        return LEASE_MIN_SECONDS;
+    return Math.max(LEASE_MIN_SECONDS, Math.min(LEASE_MAX_SECONDS, Math.floor(n)));
+}
+/**
+ * The lease, or null. Expiry is applied HERE — the only place that reads it —
+ * so no caller can observe an expired lease as active.
+ */
+export function readLease(now = Date.now(), file = leaseFile()) {
+    try {
+        if (!existsSync(file))
+            return null;
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        const until = Number(raw.until);
+        if (!Number.isFinite(until) || until <= now)
+            return null;
+        return { until, reason: String(raw.reason ?? 'unknown'), pid: raw.pid, board: raw.board };
+    }
+    catch {
+        // A corrupt lease means "no lease". Failing open is correct: the cost is a
+        // reset board during a flash that is probably not running; failing closed
+        // would leave every device permanently unreachable behind a bad file.
+        return null;
+    }
+}
+export function serialSuspended(now = Date.now()) {
+    return readLease(now) !== null;
+}
+export function writeLease(lease, file = leaseFile()) {
+    mkdirSync(dirname(file), { recursive: true });
+    // tmp+rename, like every other file this daemon owns: a torn lease read as
+    // corrupt is a lease that silently is not protecting the write in flight.
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(lease, null, 2)}\n`);
+    renameSync(tmp, file);
+    debug('ESP32', `flash lease until ${new Date(lease.until).toISOString()} (${lease.reason})`);
+    return lease;
+}
+/** Idempotent: resuming when nothing is suspended is a success, not an error. */
+export function clearLease(file = leaseFile()) {
+    try {
+        if (existsSync(file))
+            unlinkSync(file);
+    }
+    catch {
+        // Best effort. An unremovable lease still expires on its own clock.
+    }
+}
+//# sourceMappingURL=esp32-flash-lease.js.map

package/dist/esp32-flash-lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esp32-flash-lease.js","sourceRoot":"","sources":["../src/esp32-flash-lease.ts"],"names":[],"mappings":"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"}

package/dist/esp32-flash-transport.d.ts

@@ -0,0 +1,90 @@
+/**
+ * A Web Serial-shaped port over `serialport`, so the CLI can drive esptool-js.
+ *
+ * WHY A SHIM AND NOT AN EXTENSION OF `esp32-serial.ts`. That module opens a raw
+ * fd and configures the line with `stty`, which can set baud and framing but
+ * **cannot touch DTR or RTS** — those need `ioctl(TIOCMSET)`. DTR/RTS *are* the
+ * ROM download-mode entry sequence, so there is no path from the existing
+ * serial code to a flasher. `serialport`'s `set({dtr, rts})` is the missing
+ * primitive, and once you have it, esptool-js needs only six members of a Web
+ * Serial port — open/close/readable/writable/setSignals/getInfo — which is what
+ * this class is.
+ *
+ * This exact adapter was what made the Phase 0 hardware spike possible: the
+ * browser's `requestPort()` opens a native chooser no automation can drive, so
+ * seven boards were measured headlessly through this code path before a byte
+ * was ever written. It is not scaffolding that got reused; it is the thing that
+ * was validated.
+ *
+ * `serialport` is an OPTIONAL dependency (native module, same class as
+ * `node-pty` / `better-sqlite3` / `@resvg/resvg-js`), so every entry point here
+ * has to survive its absence with an actionable message rather than a
+ * MODULE_NOT_FOUND stack.
+ */
+/** Loaded lazily so importing this module never fails on a machine without it. */
+type SerialPortCtor = typeof import('serialport').SerialPort;
+export declare function loadSerialPort(): Promise<SerialPortCtor | null>;
+/** @internal test seam — lets the absent-module path run without uninstalling anything. */
+export declare function __setSerialPortForTests(ctor: SerialPortCtor | null | undefined): void;
+export interface PortCandidate {
+    path: string;
+    usbVendorId?: number;
+    usbProductId?: number;
+    manufacturer?: string;
+}
+export declare function listCandidatePorts(): Promise<PortCandidate[]>;
+interface OpenOpts {
+    baudRate: number;
+    dataBits?: number;
+    stopBits?: number;
+    parity?: string;
+    bufferSize?: number;
+    flowControl?: string;
+}
+/**
+ * The six members esptool-js touches, and nothing else. Structurally compatible
+ * with `SerialPort` from the Web Serial types; cast at the call site.
+ */
+export declare class NodeWebSerialPort {
+    private readonly path;
+    private readonly info;
+    private readonly ctor?;
+    private port?;
+    private webReadable?;
+    private webWritable?;
+    constructor(path: string, info?: {
+        usbVendorId?: number;
+        usbProductId?: number;
+    }, ctor?: SerialPortCtor | undefined);
+    getInfo(): {
+        usbVendorId?: number;
+        usbProductId?: number;
+    };
+    get readable(): ReadableStream<Uint8Array> | null;
+    get writable(): WritableStream<Uint8Array> | null;
+    open(opts: OpenOpts): Promise<void>;
+    /**
+     * ALWAYS WRITE BOTH LINES. This is the single most expensive thing the spike
+     * learned.
+     *
+     * Web Serial lets a caller move one signal and leave the other alone;
+     * `serialport`'s `set()` applies its OWN defaults to whatever you omit, so a
+     * single-signal call silently moves the other line too. esptool-js's
+     * `Transport.setRTS()` re-sends DTR immediately after RTS (a usbser.sys
+     * work-around), so the clobber lands on every reset strobe and the board
+     * never enters the ROM bootloader. The symptom is only ever "failed to
+     * connect" — nothing points at the adapter. Every strategy failed on the
+     * first probe run for exactly this reason.
+     *
+     * So the two lines are held here and both are written every time.
+     */
+    private dtr;
+    private rts;
+    setSignals(signals: {
+        dataTerminalReady?: boolean;
+        requestToSend?: boolean;
+    }): Promise<void>;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=esp32-flash-transport.d.ts.map

package/dist/esp32-flash-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esp32-flash-transport.d.ts","sourceRoot":"","sources":["../src/esp32-flash-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,kFAAkF;AAClF,KAAK,cAAc,GAAG,cAAc,YAAY,EAAE,UAAU,CAAC;AAI7D,wBAAsB,cAAc,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CASrE;AAED,2FAA2F;AAC3F,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAErF;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAYD,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAYnE;AAED,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,iBAAiB;IAM1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;IAPxB,OAAO,CAAC,IAAI,CAAC,CAA+B;IAC5C,OAAO,CAAC,WAAW,CAAC,CAA6B;IACjD,OAAO,CAAC,WAAW,CAAC,CAA6B;gBAG9B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO,EAC1D,IAAI,CAAC,EAAE,cAAc,YAAA;IAGxC,OAAO,IAAI;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAI1D,IAAI,QAAQ,IAAI,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAEhD;IAED,IAAI,QAAQ,IAAI,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAEhD;IAEK,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BzC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,GAAG,CAAS;IAEd,UAAU,CAAC,OAAO,EAAE;QAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAW7B"}

package/dist/esp32-flash-transport.js

@@ -0,0 +1,157 @@
+/**
+ * A Web Serial-shaped port over `serialport`, so the CLI can drive esptool-js.
+ *
+ * WHY A SHIM AND NOT AN EXTENSION OF `esp32-serial.ts`. That module opens a raw
+ * fd and configures the line with `stty`, which can set baud and framing but
+ * **cannot touch DTR or RTS** — those need `ioctl(TIOCMSET)`. DTR/RTS *are* the
+ * ROM download-mode entry sequence, so there is no path from the existing
+ * serial code to a flasher. `serialport`'s `set({dtr, rts})` is the missing
+ * primitive, and once you have it, esptool-js needs only six members of a Web
+ * Serial port — open/close/readable/writable/setSignals/getInfo — which is what
+ * this class is.
+ *
+ * This exact adapter was what made the Phase 0 hardware spike possible: the
+ * browser's `requestPort()` opens a native chooser no automation can drive, so
+ * seven boards were measured headlessly through this code path before a byte
+ * was ever written. It is not scaffolding that got reused; it is the thing that
+ * was validated.
+ *
+ * `serialport` is an OPTIONAL dependency (native module, same class as
+ * `node-pty` / `better-sqlite3` / `@resvg/resvg-js`), so every entry point here
+ * has to survive its absence with an actionable message rather than a
+ * MODULE_NOT_FOUND stack.
+ */
+import { Readable, Writable } from 'node:stream';
+let cached;
+export async function loadSerialPort() {
+    if (cached !== undefined)
+        return cached;
+    try {
+        const mod = await import('serialport');
+        cached = mod.SerialPort;
+    }
+    catch {
+        cached = null;
+    }
+    return cached;
+}
+/** @internal test seam — lets the absent-module path run without uninstalling anything. */
+export function __setSerialPortForTests(ctor) {
+    cached = ctor;
+}
+/**
+ * macOS exposes each USB serial device twice: `/dev/tty.*` blocks on open until
+ * DCD asserts, `/dev/cu.*` does not. Only the callout node is usable here.
+ */
+const toCallout = (p) => p.replace('/dev/tty.', '/dev/cu.');
+/** Same predicate the serial bridge uses, so both agree on what is a candidate. */
+const CANDIDATE = /usbserial|wchusbserial|usbmodem|ttyUSB|ttyACM/;
+const EXCLUDE = /Bluetooth|WLAN|debug/i;
+export async function listCandidatePorts() {
+    const SerialPort = await loadSerialPort();
+    if (!SerialPort)
+        return [];
+    const list = await SerialPort.list();
+    return list
+        .filter((p) => CANDIDATE.test(p.path) && !EXCLUDE.test(p.path))
+        .map((p) => ({
+        path: toCallout(p.path),
+        usbVendorId: p.vendorId ? Number.parseInt(p.vendorId, 16) : undefined,
+        usbProductId: p.productId ? Number.parseInt(p.productId, 16) : undefined,
+        manufacturer: p.manufacturer,
+    }));
+}
+/**
+ * The six members esptool-js touches, and nothing else. Structurally compatible
+ * with `SerialPort` from the Web Serial types; cast at the call site.
+ */
+export class NodeWebSerialPort {
+    path;
+    info;
+    ctor;
+    port;
+    webReadable;
+    webWritable;
+    constructor(path, info = {}, ctor) {
+        this.path = path;
+        this.info = info;
+        this.ctor = ctor;
+    }
+    getInfo() {
+        return this.info;
+    }
+    get readable() {
+        return this.webReadable ?? null;
+    }
+    get writable() {
+        return this.webWritable ?? null;
+    }
+    async open(opts) {
+        const SerialPort = this.ctor ?? (await loadSerialPort());
+        if (!SerialPort)
+            throw new Error('serialport is not installed');
+        // A fresh handle per open: Transport.connect() re-opens at a new baud, and
+        // reusing the streams across a close would hand back a locked reader.
+        await this.close();
+        await new Promise((resolve, reject) => {
+            this.port = new SerialPort({
+                path: this.path,
+                baudRate: opts.baudRate,
+                dataBits: (opts.dataBits ?? 8),
+                stopBits: (opts.stopBits ?? 1),
+                parity: (opts.parity ?? 'none'),
+                autoOpen: false,
+                // Do NOT let the driver assert DTR/RTS on open. esptool drives the
+                // reset sequence itself, and an implicit strobe here resets the board
+                // at a moment the chosen strategy is not expecting.
+                hupcl: false,
+            }, (err) => { if (err)
+                reject(err); });
+            this.port.open((err) => (err ? reject(err) : resolve()));
+        });
+        this.webReadable = Readable.toWeb(this.port);
+        this.webWritable = Writable.toWeb(this.port);
+    }
+    /* --------------------------------------------------------------- signals */
+    /**
+     * ALWAYS WRITE BOTH LINES. This is the single most expensive thing the spike
+     * learned.
+     *
+     * Web Serial lets a caller move one signal and leave the other alone;
+     * `serialport`'s `set()` applies its OWN defaults to whatever you omit, so a
+     * single-signal call silently moves the other line too. esptool-js's
+     * `Transport.setRTS()` re-sends DTR immediately after RTS (a usbser.sys
+     * work-around), so the clobber lands on every reset strobe and the board
+     * never enters the ROM bootloader. The symptom is only ever "failed to
+     * connect" — nothing points at the adapter. Every strategy failed on the
+     * first probe run for exactly this reason.
+     *
+     * So the two lines are held here and both are written every time.
+     */
+    dtr = false;
+    rts = false;
+    async setSignals(signals) {
+        const p = this.port;
+        if (!p?.isOpen)
+            return;
+        if (signals.dataTerminalReady !== undefined)
+            this.dtr = signals.dataTerminalReady;
+        if (signals.requestToSend !== undefined)
+            this.rts = signals.requestToSend;
+        await new Promise((resolve, reject) => p.set({ dtr: this.dtr, rts: this.rts }, (e) => (e ? reject(e) : resolve())));
+    }
+    async close() {
+        const p = this.port;
+        this.webReadable = undefined;
+        this.webWritable = undefined;
+        this.port = undefined;
+        if (!p)
+            return;
+        await new Promise((resolve) => {
+            if (!p.isOpen)
+                return resolve();
+            p.close(() => resolve());
+        });
+    }
+}
+//# sourceMappingURL=esp32-flash-transport.js.map

package/dist/esp32-flash-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esp32-flash-transport.js","sourceRoot":"","sources":["../src/esp32-flash-transport.ts"],"names":[],"mappings":"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"}

package/dist/esp32-flash.d.ts

@@ -0,0 +1,171 @@
+/**
+ * `agentdeck esp32 flash <board>` — the reliable half of the firmware install
+ * story. (The browser flasher at /flash/ is the reachable half.)
+ *
+ * WHAT IT WRITES. One `agentdeck-<board>-merged.bin` at offset 0x0, on every
+ * chip. `esptool merge-bin --target-offset 0x0` has already put each board's
+ * bootloader where its ROM looks for it — classic ESP32 at 0x1000 inside the
+ * image, P4 at 0x2000, S3/C6 at 0x0 — so nothing downstream branches on chip
+ * family. The old release notes told users to write the app alone at 0x10000,
+ * which cannot bring a board up: `boot_app0.bin` was never published, so a
+ * stale otadata boots the previous slot.
+ *
+ * WHAT IT WILL NOT WRITE. The preflight in `@agentdeck/shared` is shared
+ * verbatim with the browser, and there is no `--force`. Writing an S3 image to
+ * a classic ESP32, or a 16MB-header image to an 8MB part, is how these boards
+ * get bricked — and the recovery tool for a bricked board is this one.
+ */
+import { type Esp32BoardSpec, type Esp32PreflightVerdict } from '@agentdeck/shared';
+export declare const GITHUB_REPO = "puritysb/AgentDeck";
+export declare function resolveFlashBoard(target: string): Esp32BoardSpec;
+export interface ManifestArtifact {
+    file: string;
+    size: number;
+    sha256: string;
+    offset: string;
+}
+export interface ManifestBoardEntry {
+    id: string;
+    chipFamily: string;
+    flashSize: string;
+    flashMode: string;
+    flashFreq: string;
+    uploadBaud: number;
+    merged?: ManifestArtifact;
+}
+export interface ReleaseManifest {
+    schema: number;
+    release: string;
+    firmwareVersion: string;
+    boards: ManifestBoardEntry[];
+}
+/**
+ * Every published `esp32-v*` tag, newest first.
+ *
+ * PAGED, because a single page is a silent cap. `per_page` maxes at 100 and
+ * this repo cuts ~6 tags a round across its channels, so once ~100 releases
+ * accumulate after the newest esp32 cut, one page stops containing it — and the
+ * damage is not "no answer" but a WRONG one: the existence check would report a
+ * genuinely published version as unpublished and quietly fall back to an older
+ * release. Stops at the first page that yields no esp32 tag once some are
+ * already known, so the common case is still one request.
+ */
+export declare function listFirmwareTags(maxPages?: number): Promise<string[]>;
+/** Newest `esp32-v*` tag, or undefined when the repo has none. */
+export declare function latestFirmwareTag(): Promise<string | undefined>;
+/**
+ * Which release a bare `agentdeck esp32 flash <board>` takes firmware from.
+ *
+ * TWO RULES, IN THIS ORDER, AND NEITHER WORKS ALONE. The checkout's
+ * `FIRMWARE_VERSION` names the release this source tree belongs to — but it is
+ * bumped BEFORE the tag is pushed, so during that window it names a release
+ * that does not exist yet. Taking it unconditionally is how the first command
+ * in the docs came to fail from every checkout the moment the version was
+ * bumped (and the 404 it produced was indistinguishable from "this release has
+ * no manifest", so it also misdiagnosed itself).
+ *
+ * Deliberately the same shape as `resolveTag` in
+ * `scripts/fetch-flash-firmware.mjs`. That one runs in CI with `gh`; this one
+ * runs on a user's machine with `fetch`. Same rules, same reported `source`.
+ */
+export declare function pickFirmwareTag(configVersion: string | undefined, published: readonly string[]): {
+    tag: string;
+    source: 'config' | 'latest';
+};
+export declare function firmwareVersionFromCheckout(configH: string): string | undefined;
+export declare function firmwareCacheDir(tag: string): string;
+export interface ResolveFirmwareOptions {
+    tag?: string;
+    /** an explicit .bin — skips the download entirely, mirroring esp32-ota's -f */
+    firmwarePath?: string;
+    /** fail instead of reaching the network */
+    offline?: boolean;
+    /** the repo checkout's esp32/src/config.h, when running from a checkout */
+    checkoutConfigH?: string;
+    log?: (msg: string) => void;
+}
+export interface ResolvedFirmware {
+    tag: string;
+    image: Buffer;
+    /** the manifest entry, when one was used; absent for --firmware */
+    entry?: ManifestBoardEntry;
+    source: 'file' | 'cache' | 'download';
+    path?: string;
+}
+/**
+ * Get the merged image for a board, verifying its sha256 EVERY time — on a
+ * fresh download and on every cache hit. The cache key proves which release a
+ * file came from, never that its bits are still intact, and a bit-rotted cached
+ * image is a bricked board.
+ */
+export declare function resolveFirmware(board: Esp32BoardSpec, opts?: ResolveFirmwareOptions): Promise<ResolvedFirmware>;
+export interface PortHolder {
+    command: string;
+    pid: number;
+}
+/**
+ * Three answers, not two — because this is the ONLY guard against the holder
+ * the lease provably cannot reach (the sandboxed Swift daemon cannot read
+ * `~/.agentdeck`).
+ *
+ * `lsof` exits non-zero when nothing holds the file, so a failed run really is
+ * the common "free" case. But it ALSO exits non-zero when it is not installed
+ * (a minimal Linux container), when the 5s timeout fires, and on EPERM — and
+ * collapsing those into `[]` launders "I could not look" into "nobody is
+ * holding it", which is the exact trap `esp32FlashIdIsUsable` exists to avoid
+ * on the flash-size axis, inverted to the permissive direction.
+ */
+export type PortHolderScan = {
+    known: true;
+    holders: PortHolder[];
+} | {
+    known: false;
+    reason: string;
+};
+export declare function parseLsofHolders(stdout: string): PortHolder[];
+export declare function scanPortHolders(port: string): Promise<PortHolderScan>;
+/** Back-compat convenience: holders, or none when they could not be observed. */
+export declare function whoHoldsPort(port: string): Promise<PortHolder[]>;
+export declare function classifyHolders(holders: PortHolder[]): {
+    ours: PortHolder[];
+    foreign: PortHolder[];
+};
+export interface FlashProgress {
+    onPhase?: (phase: string) => void;
+    onProgress?: (written: number, total: number) => void;
+    log?: (msg: string) => void;
+}
+export interface FlashOutcome {
+    chip: string;
+    mac: string;
+    flashSize?: string;
+    verdict: Esp32PreflightVerdict;
+    bytes: number;
+    elapsedMs: number;
+}
+/**
+ * Connect, identify, refuse-or-write, verify by MD5. Mirrors the browser's
+ * `flash.ts` step for step; the two share `esp32PreflightVerdict` so they can
+ * never disagree about which board may be written.
+ */
+export declare function flashBoard(board: Esp32BoardSpec, portPath: string, image: Buffer, geometry: Pick<ManifestBoardEntry, 'flashMode' | 'flashFreq' | 'flashSize'> & Partial<Pick<ManifestBoardEntry, 'chipFamily'>>, opts?: {
+    eraseAll?: boolean;
+    baud?: number;
+    imageIsFromManifest?: boolean;
+}, cb?: FlashProgress): Promise<FlashOutcome>;
+export interface DeviceIdentity {
+    board?: string;
+    version?: string;
+    buildHash?: string;
+}
+/**
+ * Reopen the port at 115200 and wait for the firmware's `device_info`.
+ *
+ * `ulanzi_tc001` MUST SKIP THIS. Its CH340 TX is broken in hardware, so it
+ * never answers any serial probe — running this on a TC001 reports a perfectly
+ * good flash as a failure. The exception is named in the SSOT's notes, in
+ * docs/esp32.md, and in the browser flasher's done-state copy.
+ */
+export declare const SERIAL_PROBE_UNAVAILABLE: Set<string>;
+export declare function readDeviceIdentity(portPath: string, timeoutMs?: number): Promise<DeviceIdentity | null>;
+//# sourceMappingURL=esp32-flash.d.ts.map

package/dist/esp32-flash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esp32-flash.d.ts","sourceRoot":"","sources":["../src/esp32-flash.ts"],"names":[],"mappings":"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"}