@byok-sdk/client 0.1.0

package/dist/daemon/approvals.d.ts

@@ -0,0 +1,87 @@
+/**
+ * M4 Phase 2: minimal pending-approval registry backing the control
+ * socket's `approvals.list`/`approvals.resolve` methods.
+ *
+ * Nothing PRODUCES an approval yet in Phase 2 — every one of the three
+ * bundled runtime adapters (pi/claude/codex) still has no interactive
+ * `needs_approval` path (see `create-daemon.ts`'s `toRuntimeInfoCapabilities`
+ * doc comment) — so `list()` always returns `[]` and `resolve()` always
+ * throws {@link ApprovalNotFoundError} against a real daemon today. This
+ * class exists now so Phase 3 (the claude permission-prompt path) only has
+ * to call `register()` from wherever it detects a prompt; the control-socket
+ * plumbing (`control-server.ts`'s method registry, the CLI's `approve`/
+ * `reject` commands) is already wired end-to-end against this same registry.
+ */
+export type ApprovalDecision = 'approve' | 'reject';
+/**
+ * M4 (additive-minor, `task.approval_resolved`): distinguishes a resolution
+ * that arrived over the wire (a server-sent `task.approve`/`task.reject`,
+ * relayed here via `TaskContext.approvalChannel.resolve` — `task-runner.ts`'s
+ * `handleOffer`) from one this device decided on its own (the local
+ * `approvals.resolve` control-socket RPC, a fail-closed `requestApproval`
+ * timeout, or a fail-closed finish/eviction rejection). `TaskRunner` uses
+ * this to decide whether to report `task.approval_resolved` back to the
+ * server: a wire-triggered resolution is something the server already knows
+ * about (it sent the decision itself) and must never be echoed back;
+ * everything else is new information only the device has, and — capability
+ * permitting — gets reported. `'local'` is the default (see `resolve()`
+ * below) precisely because it's the common case: every call site in this
+ * module and `task-runner.ts` except the one wire-relay closure is local by
+ * construction.
+ */
+export type ApprovalOrigin = 'wire' | 'local';
+/** What `approvals.list` returns per pending approval — deliberately small; a runtime-specific payload (e.g. the exact tool call awaiting approval) is Phase 3's concern, not this registry's. */
+export interface PendingApproval {
+    approvalId: string;
+    taskId: string;
+    summary?: string;
+    createdAt: string;
+}
+export declare class ApprovalNotFoundError extends Error {
+    constructor(approvalId: string);
+}
+/** Cap on simultaneously pending approvals — generous for any plausible concurrent-approval workload, and existing purely as a defensive bound (mirrors `task-runner.ts`'s `MAX_TRACKED_TASK_IDS`/`observer.ts`'s `MAX_TRACKED_TASKS`), not a real-world limit this is expected to ever approach. */
+export declare const MAX_PENDING_APPROVALS = 200;
+type ResolveCallback = (decision: ApprovalDecision, reason: string | undefined, origin: ApprovalOrigin) => void;
+/**
+ * `register()`/`resolve()` are the producer/consumer halves of one pending
+ * approval: a future runtime adapter integration calls `register()` when it
+ * pauses a task awaiting a decision and gets called back via `onResolve`
+ * once `resolve()` is invoked (locally, or — Phase 2's actual wiring — via
+ * the control socket's `approvals.resolve` RPC). `list()` is a pure read
+ * for `approvals.list`.
+ */
+export declare class ApprovalRegistry {
+    private readonly pending;
+    /**
+     * Registers a new pending approval, evicting the OLDEST entry first if
+     * already at {@link MAX_PENDING_APPROVALS} — bounded, not unbounded
+     * growth, for a long-lived daemon. The evicted entry's own `onResolve` is
+     * called (as a reject, with a reason naming the eviction) rather than
+     * simply dropped: whatever registered it (a future Phase 3 producer,
+     * e.g. a paused runtime session awaiting a decision) is very likely
+     * still waiting on that callback firing at all — silently stranding it
+     * would leave that producer hanging forever instead of unblocking it
+     * with a clear, if unwelcome, outcome.
+     */
+    register(approval: PendingApproval, onResolve: ResolveCallback): void;
+    list(): PendingApproval[];
+    /**
+     * Throws {@link ApprovalNotFoundError} for an unknown/already-resolved id —
+     * never silently no-ops, since a caller (the control socket's
+     * `approvals.resolve`) needs to distinguish "resolved" from "nothing to
+     * resolve".
+     *
+     * `origin` defaults to `'local'` (see {@link ApprovalOrigin}'s own doc
+     * comment for why that's the correct default, not just a convenient one):
+     * every existing caller of this method — the control socket's
+     * `approvals.resolve` RPC (`create-daemon.ts`), `TaskRunner`'s
+     * `requestApproval` timeout and `finish()` fail-closed cleanup
+     * (`task-runner.ts`) — resolves a decision this device made on its own.
+     * The one exception, a server-sent wire `task.approve`/`task.reject`
+     * relayed through `TaskContext.approvalChannel.resolve`
+     * (`task-runner.ts`'s `handleOffer`), passes `'wire'` explicitly.
+     */
+    resolve(approvalId: string, decision: ApprovalDecision, reason?: string, origin?: ApprovalOrigin): void;
+}
+export {};

package/dist/daemon/auth-manager.d.ts

@@ -0,0 +1,52 @@
+import { DeviceStore, type DeviceRecord } from './store';
+/**
+ * Thrown when the server has revoked this device: a 401 on `/byok/challenge`
+ * or `/byok/token` (protocol §6.3). The only recourse is a fresh
+ * `/byok/pair` — callers must surface a clear "re-pair needed" state and
+ * must NOT retry the renewal in a loop.
+ */
+export declare class DeviceRevokedError extends Error {
+    constructor(message?: string);
+}
+export interface AuthManagerOptions {
+    serverUrl: string;
+    store: DeviceStore;
+    deviceName?: string;
+    /** Called once revocation is detected, so a caller (ConnectionManager) can stop retrying and surface the state instead of looping. */
+    onRevoked?: () => void;
+}
+/**
+ * Owns device pairing and the access token lifecycle (protocol §6):
+ * generates/reuses the device Ed25519 keypair, pairs, and renews the access
+ * token both proactively (before expiry) and reactively (on a 401 from any
+ * caller). This is the single source of truth for "the current valid JWT"
+ * that WS connects, blob HTTP calls, and the long-poll fallback all use.
+ */
+export declare class AuthManager {
+    private readonly opts;
+    private record;
+    private renewing;
+    private proactiveTimer;
+    private revoked;
+    private stopped;
+    private pairing;
+    private credentialMutationTail;
+    constructor(opts: AuthManagerOptions);
+    get deviceId(): string | undefined;
+    isRevoked(): boolean;
+    /** Load a previously-paired device record from disk, if any (idempotent — a second call is a no-op once loaded). */
+    loadExisting(): Promise<DeviceRecord | undefined>;
+    /** `POST /byok/pair` (v2): generates a device keypair on first pair, reuses it on any subsequent (e.g. post-revocation) re-pair. */
+    pair(pairingCode: string): Promise<DeviceRecord>;
+    /** The current, non-expired access token — renews first if it's expired or close to it. Throws {@link DeviceRevokedError} if the device has been revoked. */
+    getValidAccessToken(): Promise<string>;
+    /** Force a renewal regardless of the cached token's remaining lifetime — the reactive path, used after a caller sees a 401. */
+    handleUnauthorized(): Promise<string>;
+    stop(): Promise<void>;
+    private renew;
+    private doRenew;
+    /** Always throws — `never` return type lets call sites use `if (x === 401) this.markRevoked();` without an explicit `return`/`throw` of their own. */
+    private markRevoked;
+    private scheduleProactiveRenewal;
+    private runCredentialMutation;
+}

package/dist/daemon/blob-client.d.ts

@@ -0,0 +1,22 @@
+import type { BlobRef } from '@byok-sdk/protocol';
+import type { AuthManager } from './auth-manager';
+/** Seam `TaskRunner` depends on, so tests can substitute a fake without spinning up real HTTP endpoints. */
+export interface BlobResolver {
+    resolveInstruction(blobRef: BlobRef): Promise<string>;
+    uploadArtifact(content: string | Uint8Array, contentType: string): Promise<BlobRef>;
+}
+/**
+ * HTTP-side blob transfer (protocol §7): resolving an instruction `blobRef`
+ * into its actual content, and uploading an artifact too large to inline.
+ * Both require a valid bearer token, handled via `authedFetch`.
+ */
+export declare class BlobClient implements BlobResolver {
+    #private;
+    private readonly serverUrl;
+    private readonly auth;
+    constructor(serverUrl: string, auth: AuthManager);
+    /** `blobRef` -> `GET /byok/blobs/:id/url` -> fetch the presigned download URL -> text content. Always resolves fresh rather than trusting any inlined `BlobRef.url`, per docs/protocol.md §7. */
+    resolveInstruction(blobRef: BlobRef): Promise<string>;
+    /** `POST /byok/blobs` (declares size/contentType/contentHash) -> PUT the bytes to the presigned upload URL -> a `BlobRef` for `task.artifact.blobRef`. */
+    uploadArtifact(content: string | Uint8Array, contentType: string): Promise<BlobRef>;
+}

package/dist/daemon/connection-manager.d.ts

@@ -0,0 +1,502 @@
+import { type CapabilityFlag, type Envelope, type RuntimeInfo } from '@byok-sdk/protocol';
+import { AuthManager } from './auth-manager';
+import type { CursorStore } from './cursor-store';
+import { type FleetJitter } from './deterministic-jitter';
+import { type BackoffOptions, type ConnectionState, type LivenessOptions } from './ws-transport';
+export type { ConnectionState } from './ws-transport';
+export interface ConnectionManagerOptions {
+    serverUrl: string;
+    deviceId: string;
+    productId: string;
+    capabilities: CapabilityFlag[];
+    runtimes: RuntimeInfo[];
+    auth: AuthManager;
+    cursorStore: CursorStore;
+    /**
+     * May return a promise; `ConnectionManager` awaits it before considering
+     * this envelope "processed" (findings F2/F3 — see `deliver`/`process`
+     * below). A handler that throws/rejects is caught here, not propagated.
+     */
+    onEnvelope: (envelope: Envelope) => void | Promise<void>;
+    onStateChange?: (state: ConnectionState) => void;
+    backoff?: BackoffOptions;
+    liveness?: LivenessOptions;
+    /** Consecutive never-acked WS connect failures before falling back to long-poll (protocol §8). Default 3. */
+    wsFailureThreshold?: number;
+    /** While long-polling, how often to retry establishing WS (protocol §8, "e.g. every 5 min"). Default 5 minutes. */
+    wsRetryIntervalMs?: number;
+    /** Backoff between failed long-poll HTTP attempts. Default 2s. */
+    longPollRetryDelayMs?: number;
+    /** Minimum delay before the next long-poll request after an empty (no-events) response. Default 250ms. */
+    longPollIdleDelayMs?: number;
+    fleetJitter?: FleetJitter;
+    onOperationalOutcome?: (outcome: 'success' | 'failure', source: 'reconnect' | 'upload') => void;
+}
+/**
+ * Owns the daemon's one logical connection to the server, which may be
+ * backed by either transport the wire protocol defines: WS (the normal
+ * path) or long-poll (protocol §8's fallback for environments where an
+ * outbound WSS connection isn't viable). Both funnel every received
+ * envelope through the same cursor-dedupe/persistence logic (protocol §9),
+ * so redelivery is safe regardless of which transport happens to deliver a
+ * given envelope — including during the brief overlap window when handing
+ * off between them.
+ *
+ * `send()` (Design B, finding N4) pushes onto a single shared outbox this
+ * class owns and drains through whichever transport is currently active —
+ * WS raw-sends while acked, `POST /byok/messages` while long-polling
+ * (finding F6, long-poll is a full transport, not receive-only; see
+ * docs/protocol.md §8) — so a transport switch mid-flight never strands a
+ * queued envelope. See `drainOutbox`.
+ */
+export declare class ConnectionManager {
+    private readonly opts;
+    private readonly fleetJitter;
+    private readonly ws;
+    private readonly longPoll;
+    private mode;
+    private consecutiveFailures;
+    private wsRetryTimer;
+    private wsProbeSequence;
+    private uploadRetryAttempt;
+    private cursor;
+    /**
+     * Finding F3 (at-most-once redelivery): the lowest `task.*` envelope `seq`
+     * whose handler failed and hasn't yet been successfully reprocessed. While
+     * set, the cursor is frozen at its pre-failure value even if later
+     * envelopes succeed — advancing past a still-unresolved failure would
+     * mean a future reconnect's redelivery skips it forever (it's <= the
+     * persisted cursor), which is exactly the bug this fixes. Cleared once an
+     * envelope carrying this exact seq is reprocessed (via redelivery after a
+     * reconnect) and succeeds; everything from there back up to the new
+     * cursor gets safely re-attempted too, relying on the idempotency
+     * guarantees in docs/protocol.md §9.
+     */
+    private stalledAtSeq;
+    /**
+     * Design A (Wave 2, F3-on-long-poll): the second, in-memory watermark
+     * alongside the durable `cursor`. `cursor` only ever advances AFTER a
+     * `task.*` handler's side effects resolve successfully, and is persisted
+     * (see `advanceCursor`) — that semantics is unchanged. `deliveredSeq`
+     * advances eagerly, the instant a `task.*` envelope is admitted past
+     * dedup (see `deliver`/`noteDelivered`), independent of whether its
+     * handler has even started, let alone succeeded. It exists so a
+     * long-poll re-query (`LongPollClient`'s `getCursor`) doesn't re-pull an
+     * envelope that's already been delivered once and is still in flight —
+     * `handleOffer` is NOT idempotent and must never be re-pulled while a
+     * first attempt is still running. On WS this same field is written the
+     * same way, but since a live WS connection only ever pushes a given `seq`
+     * once, it never has an observable effect there beyond mirroring
+     * `cursor` (see `dedupWatermark`'s doc comment for why redelivery
+     * correctness doesn't depend on resetting it anywhere).
+     */
+    private deliveredSeq;
+    /** Finding F3: serializes `onEnvelope` calls into a per-connection FIFO — one envelope's handler always fully settles before the next one starts. */
+    private processingChain;
+    /**
+     * Design B (finding N4): the ONE outbound queue both transports drain
+     * from — holds `Envelope` OBJECTS, never re-encoded/rebuilt strings, so a
+     * resend after a failed send attempt is byte-identical to the original
+     * (same `id`), which is what lets the server's per-(deviceId,id) dedup
+     * (Wave 1) recognize it as a safe no-op retry rather than a second
+     * application (protocol §9). A transport switch (long-poll <-> WS) never
+     * touches this queue — see `drainOutbox` — so nothing queued while one
+     * transport was active is ever stranded when the other takes over.
+     */
+    private readonly outbox;
+    /**
+     * Finding F5(b): how many envelopes `drainOutbox`'s long-poll branch has
+     * currently spliced OUT of `this.outbox` for an in-flight (not yet
+     * confirmed delivered) `postBatch` call — 0 the rest of the time. See
+     * `outboxLength`'s own doc comment for why this needs to be tracked
+     * separately from `this.outbox.length` at all.
+     */
+    private inFlightBatchSize;
+    private draining;
+    private stopped;
+    private revoked;
+    private settledWaiters;
+    private pendingCursorSave;
+    /**
+     * Finding P2 (Fix 2b): seqs currently admitted into `processingChain` but
+     * not yet settled — added in `deliver()` the moment a `task.*` envelope is
+     * accepted past the ordinary watermark check, removed in `process()`'s
+     * `finally` once that specific attempt resolves (success OR failure).
+     * While stalled, `dedupWatermark()` deliberately stays frozen below
+     * already-delivered seqs (see its own doc comment) so the failed seq's own
+     * redelivery can get through — but that same frozen watermark also means
+     * every OTHER seq above it rides along on every re-poll too. Without this,
+     * a seq already mid-flight (e.g. a `task.offer` whose `adapter.start()`
+     * hasn't resolved yet) would be re-enqueued into `processingChain` on
+     * every such re-poll, piling up duplicate copies that — once the first
+     * finally resolves and the chain unwinds through them — run its handler
+     * again; for `task.offer` specifically, a second adapter session
+     * orphaning the first (`TaskRunner`'s own `this.tasks.has` guard, finding
+     * P2c, is the second, independent layer against exactly that).
+     */
+    private readonly inFlightSeqs;
+    /**
+     * Finding P2 (Fix 2b): seqs whose handler has already resolved
+     * successfully at least once this session, tracked only while a stall is
+     * in effect — cleared the moment `stalledAtSeq` itself clears (see
+     * `process()`), since once unstalled the ordinary watermark check via
+     * `deliveredSeq` already covers everything delivered so far, making this
+     * redundant. Needed because the stall-gap-prevention rule in `process()`
+     * deliberately does NOT advance `cursor` past a seq above the
+     * still-unresolved `stalledAtSeq`, even once that seq's own handler
+     * succeeds — so `dedupWatermark()` alone can't distinguish "already
+     * succeeded, don't re-run" from "never yet attempted" for anything in
+     * that gap.
+     */
+    private readonly processedSeqs;
+    /**
+     * Finding P3: the pending `drainOutbox` long-poll retry backoff, if any —
+     * cancellable so `enterRevoked()` can unblock it immediately instead of
+     * waiting out the rest of the delay before the loop notices `revoked` and
+     * exits. See `drainRetryDelay`.
+     */
+    private cancelPendingDrainRetry;
+    /**
+     * The capabilities the CURRENTLY connected server advertised in its
+     * `conn.ack` — untyped `string[]` (forward-compat: a server may advertise
+     * a flag this build doesn't recognize yet), populated by {@link onAcked}
+     * and read by {@link getServerCapabilities}. Empty until the very first
+     * successful handshake.
+     *
+     * Finding R2 (cross-model re-review — was P1): strictly PER-CONNECTION,
+     * not per-daemon-lifetime. Cleared to `[]` the instant the acked WS
+     * connection ends for ANY reason — an ordinary disconnect (`onWsOutcome`'s
+     * `acked` branch), `stop()`, or a transport switch to long-poll
+     * (`enterLongPoll`) — and only ever repopulated by a FRESH `conn.ack`.
+     * The previous version of this doc comment claimed long-poll mode simply
+     * "stays at whatever the last real WS `conn.ack` said" — that was the bug:
+     * a daemon that once learned e.g. `approval_resolved` from an earlier WS
+     * session kept believing it applied to whatever it's connected to NOW,
+     * even after a disconnect/degrade where nothing has actually confirmed
+     * that's still true (a reconnect could land on a DIFFERENT server behind a
+     * load balancer; long-poll fallback itself never performs an equivalent
+     * handshake at all). Concretely, `TaskRunner.sendApprovalResolved` gates
+     * `task.approval_resolved` on this list — sending it to a server that
+     * doesn't actually understand it over the long-poll path would get a
+     * batch-level 400 from `MessagesSendRequestSchema` (protocol §8.2), which
+     * `drainOutbox`'s retry-the-same-batch-forever loop then head-of-line
+     * blocks EVERY envelope queued behind it on, permanently. Clearing this
+     * eagerly means that gate reliably fails closed (falls back to the
+     * pre-existing implicit-resume inference, unconditionally — see
+     * `sendApprovalResolved`'s own doc comment) the moment the connection that
+     * advertised the capability is no longer the one actually in use.
+     */
+    private serverCapabilities;
+    constructor(opts: ConnectionManagerOptions);
+    start(): Promise<void>;
+    /**
+     * Design B (finding N4): push onto the single shared outbox and try to
+     * drain it now. Never routes directly to either transport itself — see
+     * `drainOutbox`.
+     */
+    send(envelope: Envelope): void;
+    /**
+     * Design B (finding N4): drain the shared outbox through whichever
+     * transport is currently active, re-checking `this.mode` fresh on every
+     * iteration so a transport switch mid-drain is picked up immediately
+     * rather than fighting a stale decision made before the switch.
+     *
+     * WS: a synchronous, one-at-a-time `sendNow` per envelope while open+
+     * acked; stops (without dropping anything — the remainder stays queued)
+     * the moment it isn't, and is re-invoked once `onAcked` fires.
+     *
+     * Long-poll: POSTs the outbox in chunks of at most
+     * `MAX_MESSAGES_PER_BATCH` (finding P1) — the server hard-caps a single
+     * `/byok/messages` batch there (`MessagesSendRequestSchema`, protocol
+     * §8.2) and 400s the WHOLE request if it's exceeded, which — before this
+     * fix — meant more than that queued during an outage produced an oversize
+     * batch that the server would reject forever, since the client re-queued
+     * and retried the identical (still oversize) batch unchanged. Each chunk
+     * is one `LongPollClient.postBatch` call; on success the loop continues
+     * (more may still be queued, or the next chunk still needs sending), on
+     * failure that SAME chunk is unshifted back (order-preserving, same
+     * Envelope objects/ids — never rebuilt, so a retry is exactly the resend
+     * Wave 1's server-side dedup expects) and retried after a short backoff,
+     * re-reading `this.mode` each time so a WS recovery that happens
+     * mid-retry is honored on the very next loop iteration instead of only
+     * after this attempt's backoff chain gives up.
+     *
+     * Re-entrancy is guarded by `draining`: a call arriving while a drain is
+     * already in progress just returns — the in-progress loop's own
+     * `while (this.outbox.length > 0)` check will pick up anything newly
+     * pushed (or left over after a mode switch) on its very next iteration.
+     */
+    private drainOutbox;
+    /**
+     * Finding P3: backoff delay for `drainOutbox`'s long-poll retry loop.
+     * Unlike a plain `setTimeout`-based wait, this is (a) cancellable —
+     * `enterRevoked()` calls `cancelPendingDrainRetry()` to unblock an
+     * in-flight wait immediately instead of leaving `drainOutbox` parked here
+     * for up to the rest of the delay before it next checks `this.revoked` —
+     * and (b) unref'd, so the timer never keeps the Node process alive by
+     * itself while nothing else (a live long-poll GET, an open WS connection)
+     * legitimately is.
+     */
+    private drainRetryDelay;
+    isTransportDegraded(): boolean;
+    /**
+     * The capabilities the CURRENTLY connected server advertised in its
+     * `conn.ack` — e.g. lets a caller gate a daemon->server message on whether
+     * THIS server understands it before sending (see `task-runner.ts`'s
+     * `sendApprovalResolved`, gated on `approval_resolved`). Empty before the
+     * first handshake completes, AND (finding R2) once again empty after any
+     * disconnect/degrade — see `serverCapabilities`'s own doc comment for why
+     * this is strictly per-connection rather than "sticky" across one.
+     */
+    getServerCapabilities(): readonly string[];
+    isConnected(): boolean;
+    isRevoked(): boolean;
+    /**
+     * Resolves once the connection has settled — either a working, acked WS
+     * connection, or the long-poll fallback taking over (protocol §8). This
+     * lets `daemon.start()` return promptly even when WS is unavailable from
+     * the very first attempt, rather than hanging until a WS `conn.ack` that
+     * may never come.
+     *
+     * Rejects with {@link DeviceRevokedError} — instead of hanging until
+     * `timeoutMs` — if the device turns out to be revoked while settling (or
+     * already was): a cold `daemon.start()` against an already-revoked device
+     * must fail fast, not surface a generic timeout (protocol §6.3).
+     */
+    waitForAck(timeoutMs?: number): Promise<void>;
+    /**
+     * Stops both transports and waits for every in-flight envelope handler
+     * (the F3 FIFO chain) and the most recent cursor write to actually land on
+     * disk — otherwise a `stop()` racing a just-processed envelope's
+     * persistence could lose that cursor advance, or leave a handler running
+     * unobserved after the daemon reports itself stopped.
+     *
+     * Finding F5(b) (cross-model adversarial review): `drainTimeoutMs`, when
+     * passed, bounds how long this waits for the shared outbox (`this.outbox`
+     * — Design B) to actually finish draining BEFORE flipping `this.stopped`
+     * and closing the transports. Before this fix, `stop()` set `stopped`
+     * synchronously and never waited for `drainOutbox` at all: an envelope
+     * `send()` had just pushed moments earlier (e.g. `TaskRunner.shutdownTask`'s
+     * own `task.fail`, sent right before `create-daemon.ts`'s
+     * `performControlShutdown` calls this) could still be sitting UNSENT in
+     * `this.outbox` — mid long-poll retry backoff, or simply not yet picked up
+     * by the fire-and-forget `drainOutbox()` `send()` kicked off — and this
+     * method would happily proceed to `stopped = true` / `ws.close()` regardless,
+     * after which NOTHING ever drains it again: silently lost, even though
+     * `TaskRunner` believed it had been sent. `drainTimeoutMs` omitted (the
+     * default) preserves the EXACT prior behavior for every other existing
+     * caller (an ordinary `daemon.stop()`/`unpair()`) — only the control-socket
+     * shutdown path opts into the bounded wait (see `create-daemon.ts`'s
+     * `performControlShutdown`). This can never claim delivery that didn't
+     * happen: on a timeout, whatever's still queued stays exactly where it is
+     * (readable via {@link outboxLength} immediately after this resolves) —
+     * it does NOT force-flush or pretend success.
+     */
+    stop(drainTimeoutMs?: number): Promise<void>;
+    /**
+     * Finding F5(b): how many envelopes are neither confirmed delivered NOR
+     * safely re-queued — meant to be read right after a bounded {@link stop}
+     * call returns, to know honestly whether the drain actually finished (0)
+     * or timed out with something still stuck (>0). See `create-daemon.ts`'s
+     * `performControlShutdown`, which surfaces this on the `shutdown-complete`
+     * audit event rather than silently claiming everything was delivered.
+     *
+     * Deliberately `this.outbox.length + this.inFlightBatchSize`, NOT just
+     * `this.outbox.length` alone: `drainOutbox`'s long-poll branch SPLICES a
+     * batch out of `this.outbox` before awaiting `postBatch` (so a concurrent
+     * `send()` sees an accurate, non-double-counted queue) — while that POST
+     * is in flight (or, this finding's whole point, genuinely STALLED and
+     * never resolving), those envelopes have already left `this.outbox` but
+     * are not delivered either. Reading `this.outbox.length` alone at exactly
+     * that moment would undercount to 0 — silently implying full delivery
+     * for the one case (a hung POST) this finding exists to catch honestly.
+     */
+    outboxLength(): number;
+    /**
+     * Finding F5(b): polls {@link outboxLength} (not `this.outbox.length`
+     * alone — see that method's own doc comment for why a spliced-out,
+     * in-flight batch would otherwise be invisible here) rather than hooking
+     * a single `drainOutbox()` promise directly — a drain in progress can
+     * itself loop through multiple retry/backoff cycles (`drainRetryDelay`)
+     * while the server is unreachable, and a fresh, INDEPENDENT
+     * `drainOutbox()` call can also be triggered concurrently (`send()`, a
+     * mode switch's own `void this.drainOutbox()`) — polling the one thing
+     * that actually matters (is anything still undelivered) can never go
+     * stale the way capturing one specific in-flight promise reference
+     * could. Kicks off one more `drainOutbox()` attempt itself first
+     * (harmless no-op if one is already running — see its own re-entrancy
+     * guard) in case nothing is currently actively retrying (e.g. WS just
+     * dropped and long-poll hasn't taken over yet), so this bounded wait
+     * isn't just passively hoping something else happens to be making
+     * progress.
+     */
+    private waitForOutboxDrained;
+    /**
+     * Findings F2 + F3. Two rules, both pinned in docs/protocol.md §1.2/§9:
+     *
+     * - F2 (redelivery dead on reconnect): cursor accounting covers ONLY
+     *   `task.*` envelopes. `conn.ack` carries a `seq` too (required by the
+     *   schema for schema uniformity across every server->daemon type), but a
+     *   reconnecting server sends it BEFORE replaying the backlog and always
+     *   assigns it the next (i.e. highest-so-far) per-device seq — advancing
+     *   the cursor for it would make every backlog envelope's (necessarily
+     *   lower) seq look already-delivered and drop it. `conn.*` envelopes
+     *   never advance the cursor.
+     * - F3 (at-most-once): the old code persisted the cursor advance BEFORE
+     *   `onEnvelope` even ran (fire-and-forget) — a handler that then failed
+     *   left a redelivery-proof envelope permanently marked processed. Inbound
+     *   envelopes are now serialized through `processingChain` (one handler
+     *   fully settles before the next starts) and the cursor only advances
+     *   AFTER the handler resolves successfully; a rejection leaves the
+     *   cursor where it was (see `stalledAtSeq`), so a future reconnect's
+     *   redelivery re-attempts it — safe because every server->daemon type is
+     *   documented idempotent (protocol §9).
+     */
+    private deliver;
+    /**
+     * Design A: the watermark `deliver()` dedupes inbound `task.*` envelopes
+     * against, and the same value `LongPollClient` queries the next
+     * `GET /byok/events` cursor with (see the constructor). Normally this is
+     * `deliveredSeq` — which is always >= `cursor` (every envelope that
+     * reaches `advanceCursor` already passed through `noteDelivered` first,
+     * see `deliver`) — so this is the literal `max(cursor, deliveredSeq)` the
+     * design calls for, just expressed via that invariant rather than an
+     * explicit `Math.max`.
+     *
+     * While `stalledAtSeq` is set, this collapses to the durable `cursor`
+     * alone, deliberately ignoring however far `deliveredSeq` had already run
+     * ahead before the failure was known: that's what lets the stalled
+     * envelope's own redelivery (and everything after it, right up to a
+     * fresh success) get past this same dedup check instead of being
+     * self-deduped by the client's own earlier eager tracking of envelopes
+     * whose outcome wasn't known yet. No separate "reset deliveredSeq on
+     * reconnect" step is needed for this to be correct — collapsing to
+     * `cursor` exactly while stalled already produces the right answer on
+     * every redelivery path (long-poll re-query AND a WS reconnect's
+     * backlog replay alike), and NOT resetting it unconditionally on every
+     * reconnect is what lets `deliveredSeq` keep doing its job of not
+     * re-pulling/re-dispatching something already in flight across a
+     * reconnect that happens to land while a handler is still running.
+     */
+    private dedupWatermark;
+    /** Design A: eagerly advance the in-memory delivery watermark — called for every `task.*` envelope `deliver()` admits past dedup, regardless of transport or of whether its handler has even started yet. */
+    private noteDelivered;
+    private process;
+    /**
+     * M4 Phase 4 (version-negotiation drill fix): `LongPollClient` calls this
+     * for a batch entry it could not parse into a known `Envelope` at all (an
+     * unrecognized message type — mirrors `ws-transport.ts`'s identical
+     * per-frame tolerance, see `long-poll-transport.ts`'s own doc comment on
+     * `parseLooseEventsPollResponse`) but which still carried a numeric,
+     * task-class envelope-level `seq` (the caller only invokes this for a
+     * `task.`-prefixed type — see `long-poll-transport.ts`'s own
+     * `extractSkippableSeq`; `conn.*`-shaped or type-less entries never reach
+     * here at all, mirroring F2's "conn.* is never cursor-tracked" rule).
+     * There is no real `Envelope` to hand to a handler — a genuinely
+     * unrecognized type has nothing this build could ever act on.
+     *
+     * GATEKEEPER-CAUGHT REGRESSION (fixed here): this used to call
+     * `advanceCursor(seq)` DIRECTLY, synchronously, the instant a skip was
+     * detected in `LongPollClient.loop()`'s per-entry for-loop. That is NOT
+     * "instantaneous and race-free" the way the previous version of this
+     * comment claimed — the hazard was never the skip racing against itself,
+     * it was the skip racing AHEAD of an EARLIER real envelope in the SAME
+     * batch that is still in flight on `processingChain` (`deliver()`, above,
+     * only ever CHAINS `process()` onto that promise chain — it never awaits
+     * it before returning). Concretely, batch `[real seq1, unknown seq2]`:
+     * `deliver(seq1)` chains `process(seq1)` but returns immediately without
+     * running it; the for-loop then reaches `seq2` and (pre-fix) called
+     * `advanceCursor(2)` synchronously, BEFORE `process(seq1)` had even
+     * started, let alone failed. If `seq1`'s handler then failed,
+     * `stalledAtSeq` became 1 — but the durable cursor was already 2, so
+     * `dedupWatermark()` returned 2, and every future redelivery of seq1 was
+     * dedup-dropped as "already past the cursor" forever: permanent envelope
+     * loss, exactly the F3 bug class the whole `stalledAtSeq`/frozen-watermark
+     * mechanism exists to prevent.
+     *
+     * Fix: the cursor-advancing half is now CHAINED onto `processingChain`
+     * too, exactly like `process()`'s own post-handler bookkeeping — so it
+     * only ever runs once every earlier envelope already queued ahead of it
+     * has fully settled (success or failure), and can observe `stalledAtSeq`'s
+     * REAL, up-to-date value rather than whatever it happened to be at the
+     * instant the skip was first noticed. The guard mirrors `process()`'s own
+     * success-path guard exactly: never advance past a still-unresolved
+     * earlier failure, unless (degenerate, cannot really happen for a skip)
+     * this exact seq IS the stalled one.
+     *
+     * `noteDelivered` (the eager, in-memory watermark) stays UNCHAINED —
+     * called immediately, unconditionally, regardless of `stalledAtSeq` —
+     * matching `deliver()`'s own eager, unconditional call for a real
+     * envelope: its only job is "don't re-pull something already handed off,"
+     * independent of outcome, and that property does not depend on FIFO
+     * ordering the way the DURABLE cursor does.
+     *
+     * Deliberately NO top-level `dedupWatermark() <= seq` early-return before
+     * queuing the chained callback (an earlier draft of this fix had one, and
+     * it was itself subtly wrong): `deliveredSeq` can already reflect a seq
+     * from the FIRST time it was ever seen, while the DURABLE cursor is still
+     * behind it because a stall intervened before that seq's chained
+     * advancement ran — a pre-check keyed on `deliveredSeq` would then
+     * wrongly treat a LATER redelivery of the same seq (arriving once the
+     * stall has since cleared) as "already accounted for" and never queue
+     * another attempt, permanently stranding the cursor one seq short. Always
+     * queuing is safe and cheap: `advanceCursor`'s own `seq <= this.cursor`
+     * guard already makes a genuinely-redundant call a no-op, so there is no
+     * correctness reason to short-circuit earlier, only a (here, unnecessary)
+     * micro-optimization one.
+     */
+    private noteSkippedSeq;
+    /**
+     * Finding R1 (cross-model re-review — was NOT-CLOSED against F1):
+     * `LongPollClient` calls this for a batch entry whose `type` it
+     * recognized but whose payload failed schema validation
+     * ({@link EnvelopeValidationError}) — a genuine delivery failure at that
+     * seq, unlike `noteSkippedSeq`'s forward-compat case. Deliberately mirrors
+     * `process()`'s own catch block (`if (tracked && this.stalledAtSeq ===
+     * undefined) this.stalledAtSeq = envelope.seq;`) as closely as possible:
+     * the SAME "only the lowest unresolved failure holds the stall" rule, the
+     * SAME resulting freeze of `dedupWatermark()` at the durable cursor
+     * (protocol §9 keeps this seq alive), and — because it's the SAME
+     * `stalledAtSeq` field `process()`'s own post-success guard already
+     * checks — anything ELSE delivered after this seq (same batch or a later
+     * one) is automatically held back from advancing the cursor too, with
+     * zero changes needed to `process()` itself.
+     *
+     * Chained onto `processingChain` for exactly the reason `noteSkippedSeq`
+     * documents for its own identical chaining (see that method's sibling
+     * doc comment on `LongPollClient`, "GATEKEEPER-CAUGHT REGRESSION"): an
+     * EARLIER real envelope in the SAME batch may still be in flight on that
+     * FIFO chain when this is called (`deliver()` only ever chains
+     * `process()` onto it, never awaits before returning) — mutating
+     * `stalledAtSeq` synchronously here could race ahead of that still-
+     * unresolved earlier envelope. Chaining instead guarantees this only
+     * takes effect once every earlier-queued envelope has already settled,
+     * and reads `stalledAtSeq`'s real, up-to-date value rather than whatever
+     * it happened to be the instant the failure was first noticed.
+     *
+     * No `noteDelivered` call here (contrast `noteSkippedSeq`, which does
+     * call it): a validation-failed entry never becomes a real `Envelope` and
+     * never reaches `deliver()`, so it was never "delivered" in the eager
+     * in-memory-watermark sense that field tracks — there is nothing for it
+     * to eagerly mark. Once a corrected redelivery of this exact seq DOES
+     * arrive as a real envelope, it flows through the ordinary `deliver()`
+     * path (which calls `noteDelivered` itself) and, on success, clears the
+     * stall via `process()`'s own existing logic — no special-casing needed.
+     */
+    private noteValidationFailure;
+    private advanceCursor;
+    /**
+     * Fires the moment a connection attempt reaches `conn.ack` — independent
+     * of whether/when it later closes. This is the ONLY place that can
+     * reliably detect "WS is back up" while long-polling: a healthy
+     * connection stays open indefinitely, so it never reaches `onWsOutcome`
+     * (which is close-only) at all.
+     */
+    private onAcked;
+    private onWsOutcome;
+    private notifySettled;
+    private enterLongPoll;
+    private exitLongPoll;
+    private scheduleWsProbe;
+    private enterRevoked;
+}