@byok-sdk/server 0.1.0

package/dist/hub.d.ts

@@ -0,0 +1,861 @@
+import type { WebSocket } from 'ws';
+import { type Envelope, type RuntimeId, type RuntimeInfo, type TaskState } from '@byok-sdk/protocol';
+import type { DeviceRegistry } from './auth';
+import { RateLimiter } from './rate-limiter';
+import type { TaskStore } from './task-store';
+import type { ByokServerEvent, DispatchInput, HubStats, MachineInfo, TaskHandle, TaskSnapshot } from './types';
+/**
+ * The connection hub: tracks each device's live transport (WS or long-poll —
+ * never both at once, see {@link takeOverAsLongPoll}), routes `dispatch()`'d
+ * tasks to a device, and processes inbound task.* envelopes from daemons.
+ *
+ * Routing (M1): every `task.*` envelope carries a *required* envelope
+ * `task_id` — the sole routing key, both directions. No payload duplicates
+ * it, and none of the handlers below need to guard against a missing one
+ * (the wire schema already rejects such an envelope before it reaches here).
+ *
+ * Inbound gate ({@link handleInbound}): the single choke point both
+ * transports (`ws-server.ts`'s WS message handler, `http.ts`'s
+ * `POST /byok/messages`) call instead of reaching into per-type handlers
+ * directly. Runs, in order: (1) type-allow — only `DAEMON_TO_SERVER_TYPES`
+ * may pass, a server -> daemon type arriving inbound is rejected (P2); (2)
+ * ownership (N2) — an envelope for a task already owned by a *different*
+ * device is dropped and logged, never force-failed (force-failing on an
+ * authz mismatch would let an attacker who merely guesses a `taskId` kill
+ * the real owner's task); (3) dedup (N3) — an envelope `id` already seen
+ * from this device is a no-op, making the at-least-once wire (§9)
+ * effectively at-most-once server-side; (4) dispatch to the per-type
+ * handler. Because ownership is enforced once, centrally, here, the
+ * handlers below no longer carry their own device-mismatch checks.
+ *
+ * Outbound delivery (M1, §1.2/§9): every server -> daemon envelope
+ * (`conn.ack`, `task.offer/approve/reject/cancel/steer`) gets a fresh
+ * per-device monotonic `seq` and is retained in a capped ring buffer
+ * ({@link OUTBOX_RING_CAPACITY} entries) so it can be redelivered — in `seq`
+ * order, skipping anything whose task has since reached a terminal state —
+ * on reconnect (`redeliverAfterReconnect`) or long-poll
+ * (`pollEvents`/`collectRelevant`). `conn.ack` has no task association, so
+ * it's retained (for seq-counting purposes only) but never redelivered.
+ * Exception (N1/F4): `task.cancel`/`task.reject` are exempt from the
+ * terminal-task skip (`OutboxEntry.redeliverThroughTerminal`) because both
+ * move their own task to a terminal state before being queued — without the
+ * exemption they could never qualify for redelivery even when the original
+ * send never reached the daemon.
+ *
+ * State-machine (M1): `task.claim` only claims (`Offered -> Claimed`); it no
+ * longer implies `Running`. The daemon reports `Claimed -> Running`
+ * explicitly via `task.started` once its runtime session actually starts
+ * (§3.1). `task.decline` reports a pre-claim fail-closed rejection
+ * (`Offered -> Failed`, §3.2). `task.cancelled` is dual-purpose: an
+ * idempotent ack when the server already cancelled the task itself, or the
+ * authoritative trigger when the daemon observed the cancellation first
+ * (§3.3). Per §9, `task.complete`/`task.fail`/`task.cancelled` arriving for
+ * an already-terminal task are silently dropped as stale/duplicate — not a
+ * warning; this is what naturally resolves the M0 gatekeeper's cancel-race
+ * `console.warn` finding (a late `task.fail`/`task.cancelled` racing a
+ * server-initiated cancel is exactly this case).
+ *
+ * Task lease (M2): a periodic sweep (started in the constructor) reaps a
+ * `Claimed`/`Running`/`AwaitApproval` task to
+ * `Failed(retryable: true, reason: 'lease-expired')` once its owning device
+ * has been dark (disconnected, or long-poll-silent) AND the task itself has
+ * had no inbound activity for `taskLeaseMs` — see the "task-lease reaper"
+ * section further down for the full design, including why this does not
+ * reintroduce the disconnect-alone-fails-the-task bug M1 removed above.
+ */
+/**
+ * M4 Phase 3: thrown by {@link ConnectionHub.approveTask}/{@link
+ * ConnectionHub.rejectTask} for a `taskId` this hub has no record of at all
+ * — mirrors `task-store.ts`'s `IllegalTaskTransitionError` (typed error
+ * class + `instanceof` dispatch is this codebase's own established idiom for
+ * mapping a domain error to the right status code). Distinguished from
+ * {@link TaskNotAwaitingApprovalError} so a caller CAN tell the two failure
+ * modes apart (e.g. 404 vs. 409) instead of only ever seeing a single
+ * generic `Error`. There is no bearer-authed HTTP route for this on
+ * `http.ts`'s own app (see that file's own closing comment for why) — the
+ * supported entry point is calling `approveTask`/`rejectTask` directly, or
+ * via `TaskHandle.approve()`/`reject()` (thin wrappers over the same two
+ * methods); an embedder builds its own operator-facing surface on top of
+ * that, exactly like `examples/basic/server.ts`'s own
+ * `/api/tasks/:taskId/approve`/`reject` routes do.
+ */
+export declare class UnknownTaskError extends Error {
+    readonly taskId: string;
+    constructor(taskId: string);
+}
+/**
+ * Thrown by {@link ConnectionHub.approveTask}/{@link ConnectionHub.rejectTask}
+ * when the task exists but isn't currently `AwaitApproval` — see {@link
+ * UnknownTaskError}'s own doc comment for why this is a distinct class.
+ * `verb` keeps the exact pre-existing message wording per call site
+ * ("cannot approve ..." vs. "cannot reject ...") byte-for-byte unchanged —
+ * this message is user-visible today (e.g. `examples/basic`'s own
+ * `/api/tasks/:taskId/approve` surfaces `err.message` straight to the
+ * caller), so only the error's TYPE changes here, not its text.
+ */
+export declare class TaskNotAwaitingApprovalError extends Error {
+    readonly taskId: string;
+    readonly state: TaskState;
+    constructor(taskId: string, state: TaskState, verb: 'approve' | 'reject');
+}
+/**
+ * M5 (approval targeting): thrown by {@link ConnectionHub.approveTask}/
+ * {@link ConnectionHub.rejectTask} when an operator-supplied
+ * `opts.approvalId` is provided but does NOT match this hub's own
+ * last-recorded {@link TaskSnapshot.pendingApprovalId} for `taskId` — i.e.
+ * the caller is targeting a SPECIFIC approval that this server's record
+ * shows has already been superseded by a newer one (see `onAwaitApproval`'s
+ * own doc comment for how that happens). Distinct from
+ * {@link TaskNotAwaitingApprovalError} (the task isn't `AwaitApproval` at
+ * all right now — checked FIRST, so it still wins when both would apply):
+ * this error means the task genuinely IS awaiting approval, just not the one
+ * the caller thinks it is. Thrown before any state change and before any
+ * wire message is sent — a stale-id call has zero side effects, same as any
+ * other validation failure in this file.
+ */
+export declare class StaleApprovalError extends Error {
+    readonly taskId: string;
+    readonly requestedApprovalId: string;
+    readonly currentApprovalId: string | undefined;
+    constructor(taskId: string, requestedApprovalId: string, currentApprovalId: string | undefined);
+}
+/**
+ * S0 (GAP-002): why {@link ConnectionHub.steerTask} refused. Stable strings —
+ * a caller (an embedder's operator UI, an HTTP surface mapping this to a
+ * status code) switches on these rather than matching error text.
+ *
+ * - `task_terminal` — the task already reached `Complete`/`Failed`/
+ *   `Cancelled`. Checked FIRST, so a terminal task that is also (obviously)
+ *   not `Running` reports the more specific truth, and a steer racing a
+ *   terminal transition always resolves terminal-first.
+ * - `task_not_running` — the task exists and is live, but is `Offered`/
+ *   `Claimed`/`AwaitApproval`; there is no running turn to steer yet.
+ * - `steer_unsupported_runtime` — the runtime that CLAIMED this task cannot
+ *   be steered, per the claim-time capability snapshot
+ *   (`TaskSnapshot.claimedRuntimeCapabilities`, sourced from the claiming
+ *   adapter's own `task.claim.capabilities`). Fail-closed: a MISSING snapshot
+ *   rejects under this same code, because "unknown" is not "supported" (see
+ *   {@link SteerRejectedError}'s own doc comment).
+ */
+export type SteerRejectionCode = 'steer_unsupported_runtime' | 'task_not_running' | 'task_terminal';
+/**
+ * S0 (GAP-002): thrown by {@link ConnectionHub.steerTask} instead of the
+ * pre-S0 generic `Error`, so a caller can tell WHY a steer was refused
+ * without matching on message text — same typed-error idiom as
+ * {@link UnknownTaskError}/{@link TaskNotAwaitingApprovalError}/
+ * {@link StaleApprovalError} above.
+ *
+ * The gap this closes: pre-S0 `steerTask` sent `task.steer` to ANY `Running`
+ * task, but only pi's adapter implements steering — Claude's and Codex's
+ * throw on receipt (`claude-adapter.ts`, `codex-adapter.ts`), which stalls
+ * the client's redelivery cursor at that seq and loops forever. So the
+ * decision has to be made server-side, from per-runtime truth, BEFORE an
+ * envelope exists.
+ *
+ * Fail-closed on unknown, deliberately: `steer_unsupported_runtime` covers
+ * both "the claiming adapter reported `steer: false`" and "this server has no
+ * capability snapshot for this task at all" (a pre-D-4 daemon whose claim
+ * carried no `capabilities`, a task record predating S0). Refusing an unknown
+ * is a recoverable operator-visible error; guessing "supported" reintroduces
+ * the exact permanent cursor stall this gate exists to prevent.
+ *
+ * Thrown before any state change and before any wire message is built — a
+ * rejected steer has zero side effects, same as every other validation
+ * failure in this file.
+ *
+ * SINGLE SOURCE, deliberately: the gate reads the claim payload and NOTHING
+ * from the connection layer — not {@link getDeviceCapabilities} (the
+ * CONNECTION-level `conn.hello` flag list) and not `ConnectionState.runtimes`.
+ * Two reasons, either sufficient. First, scope: connection-level data is
+ * discovery describing a daemon BUILD, not the per-runtime, per-task,
+ * claim-time truth this gate needs — conflating the two is the original bug.
+ * Second, reach: `conn.hello` is transport-shaped. A long-poll-only daemon
+ * never sends one (sole sender: `ws-transport.ts:192`, `packages/client`), so
+ * a connection-sourced snapshot is permanently `undefined` for an entire
+ * transport and a fail-closed gate reading it disables steer across that whole
+ * deployment surface — a regression, not a safety property. The claim, by
+ * contrast, is the message that establishes the task↔runtime binding on every
+ * transport, so the gate's input now shares a lifecycle with the thing it
+ * judges. Adding a connection-level fallback here would restore both defects
+ * at once and is what this design exists to forbid.
+ */
+export declare class SteerRejectedError extends Error {
+    readonly taskId: string;
+    readonly code: SteerRejectionCode;
+    /** The task's state at the moment the steer was refused. */
+    readonly state: TaskState;
+    /** `TaskSnapshot.claimedRuntime` — `undefined` when nothing was ever recorded (which is itself a reason `steer_unsupported_runtime` can fire). */
+    readonly runtime: RuntimeId | undefined;
+    constructor(taskId: string, code: SteerRejectionCode, 
+    /** The task's state at the moment the steer was refused. */
+    state: TaskState, 
+    /** `TaskSnapshot.claimedRuntime` — `undefined` when nothing was ever recorded (which is itself a reason `steer_unsupported_runtime` can fire). */
+    runtime: RuntimeId | undefined);
+}
+export declare class ConnectionHub {
+    private readonly taskStore;
+    private readonly devices;
+    /** See {@link CreateByokServerOptions.taskLeaseMs} — already defaulted by `createByokServer` before reaching here. */
+    private readonly taskLeaseMs;
+    /**
+     * M4 Phase 4 (part A): per-device inbound-envelope token bucket — see
+     * {@link CreateByokServerOptions.rateLimit} (already defaulted by
+     * `createByokServer` before reaching here) and {@link handleInbound}'s
+     * own doc comment for where it's enforced. Defaults to a fresh
+     * default-configured `RateLimiter` so every existing direct-construction
+     * call site (this hub is constructed directly by several tests) keeps
+     * working unchanged.
+     */
+    private readonly rateLimiter;
+    private readonly connections;
+    private readonly outboxes;
+    /** Idempotency window per device (N3) — recent inbound envelope ids, capped at {@link DEDUP_RING_CAPACITY}. */
+    private readonly dedupRings;
+    private readonly longPollWaiters;
+    private readonly runtimes;
+    private readonly serverEvents;
+    /**
+     * Per-task last-inbound-activity timestamp (epoch ms) — the task-lease
+     * reaper's condition (c), see the "task-lease reaper" section below. Reset
+     * on every accepted inbound `task.*` envelope ({@link recordTaskActivity},
+     * called from {@link dispatchToHandler}); cleared once the task reaches a
+     * terminal state ({@link onStateChange}), so this map only ever holds
+     * entries for currently non-terminal claimed tasks.
+     */
+    private readonly taskActivity;
+    /** The task-lease reaper's own periodic sweep timer — see the constructor and `sweepLeases` below. */
+    private readonly leaseReaperTimer;
+    /** {@link ConnectionHub.stats}'s `uptimeMs` origin — this hub's own construction instant. */
+    private readonly startedAtMs;
+    /** {@link ConnectionHub.stats}'s `envelopesIn` — every {@link handleInbound} call, every outcome. */
+    private envelopesInCount;
+    /** {@link ConnectionHub.stats}'s `envelopesOut` — every envelope built via the single outbound choke point, {@link sendToDevice}. */
+    private envelopesOutCount;
+    /** {@link ConnectionHub.stats}'s `dedupDrops` (N3). */
+    private dedupDropCount;
+    /** {@link ConnectionHub.stats}'s `rateLimitEvents` — see {@link handleRateLimited}. */
+    private rateLimitEventCount;
+    /**
+     * M4 Phase 4 (gatekeeper LOW advisory): devices that have already had a
+     * `device.rate_limited` embedder event emitted for their CURRENT
+     * over-budget episode — see {@link handleRateLimited}'s own doc comment.
+     * Coalescing state only; {@link rateLimitEventCount} still counts every
+     * single hit regardless of what this suppresses.
+     */
+    private readonly rateLimitEventEmittedFor;
+    constructor(taskStore: TaskStore, devices: DeviceRegistry, 
+    /** See {@link CreateByokServerOptions.taskLeaseMs} — already defaulted by `createByokServer` before reaching here. */
+    taskLeaseMs: number, 
+    /**
+     * M4 Phase 4 (part A): per-device inbound-envelope token bucket — see
+     * {@link CreateByokServerOptions.rateLimit} (already defaulted by
+     * `createByokServer` before reaching here) and {@link handleInbound}'s
+     * own doc comment for where it's enforced. Defaults to a fresh
+     * default-configured `RateLimiter` so every existing direct-construction
+     * call site (this hub is constructed directly by several tests) keeps
+     * working unchanged.
+     */
+    rateLimiter?: RateLimiter);
+    /**
+     * Stop the task-lease reaper's sweep timer — called by `ByokServer.stop()`
+     * (`index.ts`) on shutdown. Idempotent: clearing an already-cleared
+     * interval is a safe no-op.
+     */
+    stopLeaseReaper(): void;
+    /** The top-level `events` feed returned by `createByokServer` — see {@link ByokServerEvent}. */
+    subscribeServerEvents(): AsyncIterable<ByokServerEvent>;
+    /**
+     * A daemon completed the WS handshake (`conn.hello`). Does not itself send
+     * `conn.ack` or redeliver — see {@link sendConnAck}/{@link redeliverAfterReconnect}.
+     *
+     * `capabilities` (M5, hello-capability plumbing): the daemon's own
+     * `conn.hello.capabilities` — previously silently ignored end to end (a
+     * verified gap: `ws-server.ts` forwarded only `runtimes`). Optional so
+     * every pre-M5 direct-construction call site (several tests construct a
+     * `ConnectionHub` and call this directly) keeps working unchanged; a
+     * connection this hub never learns capabilities for simply reads back
+     * `undefined` from {@link getDeviceCapabilities}.
+     */
+    registerConnection(deviceId: string, ws: WebSocket, runtimes: RuntimeInfo[] | undefined, capabilities?: readonly string[]): void;
+    sendConnAck(deviceId: string, capabilities: string[]): void;
+    /**
+     * Reconnection procedure step 3 (§9): redeliver, in `seq` order, every
+     * retained envelope with `seq > cursor` that still belongs to a
+     * non-terminal task. Called after `conn.ack` (step 2), per the spec.
+     */
+    redeliverAfterReconnect(deviceId: string, cursor: number): void;
+    /**
+     * A device's WS socket closed. `ws` identifies *which* socket closed: if
+     * it's no longer the one this device's connection state points at (a
+     * newer WS reconnected, or long-poll took over — "last transport wins"),
+     * this close is for a stale/superseded socket and the device isn't
+     * actually gone, so the bookkeeping below is skipped entirely.
+     *
+     * M1 note: the M0 server force-failed/cancelled every in-flight task for a
+     * device the instant it disconnected, on the stated premise that "a task
+     * still in flight for a device that just disconnected can't be resumed, so
+     * it's terminated" — true only in the absence of a redelivery cursor. M1
+     * adds exactly that (§9): a task's in-flight state is retained
+     * independently of any one connection, specifically so it can survive a
+     * disconnect and resume via redelivery once the device reconnects. Failing
+     * tasks here would make that feature unreachable in practice (nothing
+     * would ever still be non-terminal by the time a reconnect happened), so
+     * this now only updates connection bookkeeping and leaves task state
+     * alone. A task left in-flight by a device that never reconnects stays
+     * that way until the SaaS embedder explicitly cancels it — no
+     * disconnect-timeout is specified by the protocol, so none is invented
+     * here (see the M1-2 report's contract-gap notes).
+     */
+    handleDisconnect(deviceId: string, ws: WebSocket): void;
+    /**
+     * Resolve immediately if there are already-relevant events past `cursor`;
+     * otherwise hold for up to `holdMs` and resolve with an empty result if
+     * nothing arrives. A device may be connected via WS or long-poll, not
+     * both simultaneously — a poll here supersedes (closes) any live WS for
+     * this device ("last one wins", documented at the type level on
+     * {@link ConnectionState}).
+     */
+    pollEvents(deviceId: string, cursor: number, holdMs: number): Promise<{
+        events: Envelope[];
+        cursor: number;
+    }>;
+    /** Make long-poll this device's active transport, closing any live WS ("last one wins", §8). */
+    private takeOverAsLongPoll;
+    /** Resolve (settle) any long-poll request currently held open for `deviceId`, if one exists. */
+    private settleLongPollWaiter;
+    /**
+     * Single inbound choke point for every daemon -> server envelope (N2/N3/
+     * P2) — called by both the WS path (`ws-server.ts`) and the long-poll send
+     * path (`POST /byok/messages`, `http.ts`) in place of reaching into
+     * per-type handlers directly. Runs a fixed gate, in order:
+     *
+     * 0. **rate limit (M4 Phase 4, part A)** — one token debited from this
+     *    device's bucket ({@link rateLimiter}) for EVERY inbound envelope,
+     *    before anything else runs (including the type-allow check below) —
+     *    a flood of garbage-typed envelopes must cost the same budget as a
+     *    flood of well-formed ones. Checked first specifically so an
+     *    over-budget device is turned away as cheaply as possible, before any
+     *    taskStore lookup or dedup bookkeeping. See {@link handleRateLimited}
+     *    for what happens on exceed (never a silent drop).
+     * 1. **type-allow (P2)** — only {@link DAEMON_TO_SERVER_TYPES} may pass; a
+     *    server -> daemon type (or anything unrecognized, e.g. a stale/future
+     *    `conn.hello` outside the handshake) arriving inbound is rejected
+     *    before it's dispatched or counted accepted.
+     * 2. **ownership (N2)** — an envelope for a task already owned by a
+     *    *different* device is dropped (logged), never force-failed:
+     *    force-failing on an authz mismatch would let an attacker who merely
+     *    guesses a `taskId` kill the real owner's task (a DoS). A task with no
+     *    owner yet, or that doesn't exist at all, is not rejected here — the
+     *    per-type handler's own no-op-on-missing-record behavior covers the
+     *    latter.
+     * 3. **dedup (N3)** — an envelope `id` already seen from this device is a
+     *    no-op: the wire is at-least-once (§9), this makes server-side
+     *    processing at-most-once. Check-and-record is synchronous (Node is
+     *    single-threaded), so it's atomic with respect to any other envelope
+     *    for this device.
+     * 4. **dispatch** — handed to the existing per-type `on*` handler.
+     *
+     * Returns which outcome applied. A duplicate still counts as `accepted` on
+     * the `POST /byok/messages` wire (§8.2) — an idempotent replay is a
+     * wire-level success even though no handler ran a second time; only
+     * `rejected`/`rate_limited` (gate steps 0-2) are excluded from that count.
+     */
+    handleInbound(deviceId: string, envelope: Envelope): 'accepted' | 'duplicate' | 'rejected' | 'rate_limited';
+    /**
+     * M4 Phase 4 (part A): `deviceId` just exceeded its inbound-envelope rate
+     * limit. Never a silent drop: counts the occurrence
+     * ({@link rateLimitEventCount}, surfaced via {@link stats} — every single
+     * hit, unconditionally) and, the FIRST time in this over-budget episode
+     * only, emits an embedder-facing `device.rate_limited`
+     * {@link ByokServerEvent} — see that variant's own doc comment (`types.ts`)
+     * for the full per-transport enforcement shape.
+     *
+     * Gatekeeper LOW advisory (event amplification): a single flood can make
+     * `handleInbound` call this many times in a row — e.g. several WS frames
+     * already in flight before the close below actually lands, or a
+     * long-poll device retrying its `POST /byok/messages` before its bucket
+     * has refilled. Without coalescing, an embedder subscribed to
+     * `events.subscribe()` would see one `device.rate_limited` per hit, which
+     * is noisy for what is really ONE ongoing episode of one device
+     * flooding. `rateLimitEventEmittedFor` suppresses the repeats: this
+     * method only pushes the event the first time it sees a given `deviceId`
+     * since `handleInbound`'s own success path last cleared it (i.e. since
+     * this device was last confirmed back under budget) — the COUNTER above
+     * is entirely unaffected by this and still increments on every call,
+     * unconditionally.
+     *
+     * This method only handles the WS half of the enforcement shape (closing
+     * the live connection, if any, so the client's existing backoff+reconnect
+     * takes over — mirrors `takeOverAsLongPoll`'s own `ws.close`, the only
+     * other place this hub closes a device's socket directly); a long-poll
+     * device has no live `ws` to close here at all (`conn.ws` is `undefined`
+     * while long-polling — see {@link ConnectionState}), so `http.ts`'s
+     * `/byok/messages` handler maps this same `'rate_limited'` `handleInbound`
+     * outcome to an HTTP 429 for that transport instead.
+     */
+    private handleRateLimited;
+    /**
+     * Idempotency check-and-record (N3): `true` (duplicate) if `id` was
+     * already seen for `deviceId`; otherwise records it and returns `false`.
+     * Bounded to {@link DEDUP_RING_CAPACITY} ids per device — a ring, not an
+     * unbounded set — evicting the oldest once full.
+     */
+    private checkAndRecordDuplicate;
+    /**
+     * Route one already-gated envelope (see {@link handleInbound}) to its
+     * per-type handler. Type-allow/ownership/dedup have already run by the
+     * time this executes, so the handlers below no longer need their own
+     * device-mismatch checks — that authz decision now lives solely in
+     * `handleInbound` (N2).
+     *
+     * Also the task-lease reaper's activity checkpoint
+     * ({@link recordTaskActivity}): every envelope for a task that currently
+     * *exists and is non-terminal* counts as proof of life for `taskId`'s
+     * lease, regardless of what its per-type handler below ends up doing with
+     * it (including a no-op/stale drop) — see the "task-lease reaper" section
+     * further down for why. Deliberately gated on the record's existence and
+     * non-terminal state *here*, before dispatch: `taskActivity` must never
+     * gain an entry for a taskId that doesn't exist (a nonexistent/garbage id
+     * an authenticated-but-malicious daemon could send indefinitely — an
+     * unbounded-growth vector, since `taskId`s aren't deduped the way envelope
+     * `id`s are) or for one that's already terminal (a stale/late message for
+     * a finished task — `onStateChange` deletes the entry on the *real*
+     * terminal transition, but a stale message arriving *after* that would
+     * otherwise silently recreate it, since every per-type handler's own
+     * terminal/unknown-task guard runs — and early-returns — only *after*
+     * this would already have recorded activity).
+     */
+    private dispatchToHandler;
+    /** Reset the task-lease reaper's per-task clock (condition (c) in the "task-lease reaper" section below). */
+    private recordTaskActivity;
+    /**
+     * Ownership (record.deviceId matching the connection's authenticated
+     * deviceId) is enforced centrally by {@link handleInbound} (N2) before this
+     * runs; only the idempotent-claim CAS and the first-claim device patch
+     * happen here.
+     *
+     * M5 (claimed runtime, docs/protocol.md §3.1): `payload.runtime` — the
+     * ACTUAL adapter the daemon selected (`TaskRunner.pickAdapter`,
+     * `packages/client`'s `task-runner.ts`) — is recorded into
+     * `TaskSnapshot.claimedRuntime` alongside the device patch, distinct from
+     * the pre-existing `TaskSnapshot.runtime` (the merely REQUESTED runtime,
+     * untouched here and set only once, at `dispatch()` time). Only ever
+     * written on the FIRST real claim: the idempotent-CAS early return above
+     * fires before this for a retried claim from a device that already owns
+     * the task, so a redelivered/retried `task.claim` can never overwrite an
+     * already-recorded `claimedRuntime` — including with a stale or absent
+     * value from an out-of-order retry.
+     *
+     * S0/D-4 (claim-time capability snapshot): `payload.capabilities` — the
+     * claiming adapter's OWN self-report, carried on this same `task.claim`
+     * (docs/protocol.md §2.4) — supplies
+     * `TaskSnapshot.claimedRuntimeCapabilities`, written in the same patch and
+     * therefore under the same write-exactly-once property as `claimedRuntime`.
+     *
+     * Taken from the payload and from nowhere else. This hub deliberately does
+     * NOT consult connection state (`conn.hello.runtimes[]`) for it — see
+     * {@link SteerRejectedError} for why that source is structurally wrong for a
+     * control decision, and that field's own doc comment (`types.ts`) for why
+     * this is snapshotted rather than read live at steer time. A claim that
+     * carries no `capabilities` (a pre-D-4 daemon) records `undefined`, which
+     * the gate reads as "unknown" and refuses.
+     */
+    private onClaim;
+    /**
+     * `Claimed -> Running` (§3.1) — a daemon actually starting the runtime
+     * session, distinct from merely claiming. Ownership is already enforced
+     * by {@link handleInbound} (N2) before this runs.
+     */
+    private onStarted;
+    /**
+     * `Offered -> Failed` (§3.2) — a fail-closed pre-claim rejection. Only
+     * ever legal from `Offered`; anything else is stale. Ownership is already
+     * enforced by {@link handleInbound} (N2) before this runs.
+     */
+    private onDecline;
+    private onProgress;
+    private onArtifact;
+    private onAwaitApproval;
+    private onComplete;
+    private onFail;
+    /**
+     * Dual-purpose on receipt (§3.3): if the server already moved this task to
+     * `Cancelled` on its own action (the common case — `cancelTask()` is
+     * authoritative immediately, §4), this is a late idempotent ack — silent,
+     * not a warning (this is the other half of the M0 gatekeeper finding this
+     * change resolves). Otherwise it's the authoritative trigger for a
+     * cancellation the daemon observed that the server didn't initiate.
+     * Ownership is already enforced by {@link handleInbound} (N2) before this
+     * runs.
+     */
+    private onCancelled;
+    /**
+     * M4 (additive-minor, `task.approval_resolved`): the EXPLICIT counterpart
+     * to {@link resumeIfImplicitlyApproved} — a daemon that resolved a pending
+     * approval entirely LOCALLY now reports it immediately, instead of the
+     * server only finding out after the fact once evidence (a later
+     * `task.progress`/`task.artifact`/`task.complete`) proves it.
+     *
+     * Relationship to the implicit path (both stay, permanently — this is not
+     * a replacement): {@link resumeIfImplicitlyApproved} remains completely
+     * untouched as the fallback for (a) an old daemon that predates this
+     * message, and (b) a daemon connected to an old server that never
+     * advertised the `approval_resolved` capability flag (`version.ts`) at
+     * handshake time — in either case the daemon never sends this message at
+     * all (see `packages/client`'s `task-runner.ts`), and the server keeps
+     * inferring the resolution from evidence exactly as it did before this
+     * message existed. When THIS message does arrive first, it already moves
+     * the record out of `AwaitApproval` (see below) — so by the time any
+     * following `task.progress`/etc. reaches `onProgress`/`onArtifact`/
+     * `onComplete`, `resumeIfImplicitlyApproved`'s own `record.state !==
+     * 'AwaitApproval'` guard is already true and it no-ops, never firing its
+     * own `task.approval_resolved_implicit` event a second time for the same
+     * resolution. The two mechanisms race harmlessly: whichever one the
+     * server processes first is the one that actually performs the
+     * transition; the other is naturally inert once it runs.
+     *
+     * Three outcomes, mirroring this file's existing per-type idempotency
+     * conventions:
+     *   - `AwaitApproval` (the expected case): legal transition to `Running`
+     *     (an existing `TASK_TRANSITIONS` edge, the same one `approveTask`
+     *     itself uses) plus a `task.approval_resolved` {@link ByokServerEvent}
+     *     carrying `approvalId`/`decision`/`resolvedBy` for an embedder to
+     *     observe.
+     *   - Already `Running` (evidence — or the implicit path — already beat
+     *     this message to it): idempotent no-op, silent, mirroring
+     *     `onStarted`'s own already-running guard.
+     *   - Terminal, or a state that was never `AwaitApproval` in the first
+     *     place (`Offered`/`Claimed` — a genuinely out-of-sequence report):
+     *     stale no-op with a `console.warn`, matching this file's existing
+     *     stale-message convention (`forceFailOrDrop`, `handleInbound`'s
+     *     ownership-mismatch drop) — never force-failed, since a late/
+     *     redelivered report about a task that has already moved on is not
+     *     evidence of anything currently wrong with it.
+     *
+     * This is also the residual-race resolution the accompanying protocol/docs
+     * update documents: a SaaS decision (`approveTask`/`rejectTask`) already in
+     * flight when the local resolution happens can still land on the server
+     * FIRST and move the record to a terminal state before this message
+     * arrives — in that case this message hits the terminal branch above and
+     * is a stale no-op, exactly like any other late message for an
+     * already-terminal task. The window for that crossing is now
+     * network-latency-sized (how long this message takes to arrive), not
+     * "until the next progress message" the way the pre-existing implicit-only
+     * inference left it.
+     */
+    private onApprovalResolved;
+    /**
+     * M5 (approval targeting): single low-level wrapper around
+     * `TaskStore.transition` that every ACTUAL state-changing write in this
+     * file goes through — {@link applyOrFail}'s legal-transition branch,
+     * {@link forceFailOrDrop}, and {@link resumeIfImplicitlyApproved} (the one
+     * caller that transitions WITHOUT going through `applyOrFail` at all).
+     * Two responsibilities, folded in here once rather than duplicated at
+     * each call site:
+     *
+     *   1. Clears `pendingApprovalId` whenever `record` is LEAVING
+     *      `AwaitApproval` (`record.state === 'AwaitApproval' && to !==
+     *      'AwaitApproval'`) — the id this hub last recorded for a task's
+     *      pending approval ({@link onAwaitApproval}) is meaningless the
+     *      instant that task is no longer awaiting it. Clearing it here,
+     *      centrally, is what guarantees a FUTURE `AwaitApproval` cycle for
+     *      the SAME task always starts from a clean slate instead of silently
+     *      inheriting a stale id from a previous cycle (which would make a
+     *      stale-approval check against the NEW cycle's real pending id
+     *      spuriously pass just because a leftover value happened to still be
+     *      sitting in the record).
+     *   2. Calls {@link onStateChange} — every call site already did this
+     *      immediately after its own `transition` call; folding it in here
+     *      removes the duplication and the chance of a future call site
+     *      forgetting it.
+     */
+    private transitionTask;
+    /**
+     * Apply `taskId`'s state -> `target`. If that's illegal per
+     * `TASK_TRANSITIONS`, fall back to `Failed` (if reachable from the current
+     * state); this is the "illegal transition = error + task.fail path" rule.
+     */
+    private applyOrFail;
+    /**
+     * M4 Phase 3 hardening (orchestrator-directed fix for the server-state-
+     * machine trace finding): a task can be resolved entirely OUT-OF-BAND, on
+     * the daemon side only (M4 Phase 3's local `approvals.resolve`
+     * control-socket path, `packages/client`) — the server never sees a wire
+     * `task.approve`/`task.reject` for it, so its own record sits in
+     * `AwaitApproval` even though the daemon already resumed and moved on.
+     *
+     * The daemon is the execution authority in this security model (the SaaS
+     * only ever *proposes* — see docs/spec.md); the daemon sending ANY further
+     * task.* traffic for a task the server still thinks is `AwaitApproval` is
+     * itself sufficient proof the approval was resolved locally, one way or
+     * another. Rather than force-failing/dropping that traffic (the pre-fix
+     * behavior — `onProgress`/`onArtifact`'s own `!== 'Running'` guard,
+     * `onComplete`'s illegal-transition fallback), this applies the exact same
+     * `AwaitApproval -> Running` edge `approveTask` already uses (a
+     * pre-existing legal `TASK_TRANSITIONS` edge, not a new one) through the
+     * normal transition path — `taskStore.transition` + `onStateChange`, same
+     * as `applyOrFail`'s own legal-transition branch — so every existing
+     * consumer of task state (§, `TaskHandle.events()`, the lease reaper's
+     * `taskActivity`) observes it exactly as it would a real wire
+     * `task.approve`. Then emits `task.approval_resolved_implicit` (a
+     * `ByokServerEvent`, NOT a wire message — see that type's own doc comment)
+     * so an embedder can distinguish this from an operator-driven approval.
+     *
+     * M4 (additive-minor, superseding this method's own former "deferred"
+     * framing): a first-class `task.approval_resolved` WIRE notification now
+     * exists (`onApprovalResolved`, below) — a daemon that supports it, talking
+     * to a server that advertised the `approval_resolved` capability flag
+     * (`version.ts`), reports a local resolution explicitly and immediately
+     * instead of leaving the server to infer it here. This method is
+     * UNTOUCHED and remains the permanent fallback for the N/N-1 cases where
+     * that explicit report never arrives (an old daemon, or an old server this
+     * daemon is talking to) — see `onApprovalResolved`'s own doc comment for
+     * the full relationship between the two paths, including why they can
+     * never both fire for the same resolution.
+     *
+     * No-op (returns `record` unchanged) for any state other than
+     * `AwaitApproval` — every other guard (terminal, pre-claim, already-
+     * Running) keeps exactly its current behavior. `onFail`/`onCancelled`
+     * never call this: `Failed`/`Cancelled` are already direct, legal edges
+     * from `AwaitApproval`, so they never hit the illegal-transition path this
+     * exists to avoid in the first place.
+     */
+    private resumeIfImplicitlyApproved;
+    /**
+     * A daemon message didn't fit the task's current state (e.g. progress
+     * while AwaitApproval). Force the task to `Failed` if that's reachable;
+     * otherwise it's already terminal (or `Offered`, which has no Failed edge)
+     * and there's nothing safe to do but log + drop.
+     */
+    private forceFailOrDrop;
+    private onStateChange;
+    /**
+     * Task lease: a backstop for a device that goes dark mid-task and never
+     * comes back — distinct from, and layered on top of, M1's redelivery
+     * (docs/protocol.md §9), which already handles "device reconnects within
+     * the window, nothing lost." Decision (user+design): reuse the existing
+     * `Failed` terminal state and its `retryable` flag —
+     * `Failed(retryable: true, reason: 'lease-expired')` — exactly like any
+     * other `task.fail`. The embedder is expected to treat this exactly like
+     * any other retryable failure: re-dispatch as a brand-new task.
+     *
+     * Implemented as a periodic sweep (see the constructor), not a per-task
+     * timer, so a device that goes dark *after* being idle-but-connected for a
+     * while is still caught on a later tick without needing extra bookkeeping
+     * at disconnect time. `sweepLeases` reaps a task only when ALL of the
+     * following hold, checked fresh on every tick (never cached):
+     *
+     *   (a) the task is in a non-terminal *claimed* state — `Claimed`,
+     *       `Running`, or `AwaitApproval` ({@link isClaimedState}). `Offered`
+     *       is excluded: it has no owning device yet, so there's nothing to
+     *       be "dark".
+     *   (b) the owning device is dark right now ({@link deviceDarkSince}
+     *       returns a timestamp rather than `undefined`) — disconnected
+     *       outright, or (long-poll only) hasn't been seen since before the
+     *       lease window. A live WS connection is never dark from the
+     *       reaper's point of view: `heartbeat.ts` already independently
+     *       proves liveness at the transport level and flips
+     *       `connected: false` via `handleDisconnect` once it stops getting
+     *       pongs — the reaper just reads that flag rather than re-deriving
+     *       it. `deviceDarkSince` also returns *when* darkness started
+     *       ({@link ConnectionState.darkSince}, set the instant
+     *       `handleDisconnect` flips the connection dark) — that instant
+     *       feeds condition (c), below.
+     *   (c) a full `taskLeaseMs` has elapsed since the *later* of: the task's
+     *       own last inbound-activity timestamp ({@link taskActivity}, reset
+     *       in {@link dispatchToHandler} on every accepted envelope for a
+     *       known, non-terminal task — claim, started, progress, artifact,
+     *       await_approval, anything), and (b)'s dark-since instant. Taking
+     *       the *later* of the two — not the activity timestamp alone — is
+     *       what makes a device going dark start a fresh, full countdown
+     *       instead of reusing whatever (possibly already-stale) activity
+     *       timestamp the task happened to have: a task can be legitimately
+     *       idle *while connected* for longer than `taskLeaseMs` (a long turn
+     *       with no progress events, or just a quiet stretch) without being
+     *       touched — see (b) — but the instant such a task's device
+     *       disconnects, that stale activity timestamp must NOT immediately
+     *       satisfy (c) on its own, or the task would get reaped within one
+     *       sweep tick of disconnect instead of waiting the full window. That
+     *       was a real bug (a disconnect-after-long-idle reap effectively
+     *       indistinguishable from the M0 disconnect-alone-fails-the-task
+     *       behavior M1 removed, below); anchoring (c) to
+     *       `max(lastActivity, darkSince)` fixes it — idle time that elapsed
+     *       *before* the device went dark no longer counts toward the lease,
+     *       only silence *after* dark-start does.
+     *
+     * (b) and (c) are deliberately independent clocks, not one merged check.
+     * The property this most exists to protect: a *connected*, momentarily
+     * idle device mid-turn must never be reaped, no matter how long
+     * `taskLeaseMs` is — condition (b) alone blocks that regardless of (c).
+     * This is also what keeps this from reintroducing the M0 bug M1
+     * deliberately removed (see `handleDisconnect`'s own doc comment above) —
+     * M0 force-failed a task the instant its device disconnected; M1
+     * correctly stopped doing that so a task could survive a disconnect and
+     * resume via redelivery. This reaper does not revert that: disconnect
+     * ALONE still does nothing here either — (c) still has to independently
+     * hold, and per the `max(...)` above it only will once a full
+     * `taskLeaseMs` has genuinely elapsed *since the device went dark*, no
+     * matter how stale the task's own activity timestamp already was at that
+     * moment.
+     *
+     * Interaction with redelivery (§9): redelivery is what handles "the
+     * device came back within the window" — nothing to reap, normal traffic
+     * resumes. This reaper is what handles "it never came back." Idempotent
+     * claim (`onClaim`'s CAS) still protects server-side bookkeeping if a
+     * device wakes up *after* its task was already reaped and retries a stale
+     * claim/progress/etc. for it: every per-type handler's existing
+     * stale/terminal-task guard (§9) drops it as a no-op, same as any other
+     * late message for an already-terminal task — no new guard was needed for
+     * that here.
+     *
+     * Accepted residual (by design, not a bug): idempotent claim protects
+     * *server-side* state, not the device's own local side effects. A dark
+     * device that wakes up after its task has already been reaped may still
+     * be mid-way through running real local work (file writes, shell
+     * commands, whatever the runtime adapter was doing) for a task the server
+     * has since moved on from — and that the embedder may have already
+     * re-dispatched elsewhere. There is no way to remotely guarantee a
+     * truly-dark device stops running; the mitigation is entirely
+     * `taskLeaseMs` being set far larger than any realistic task duration, so
+     * this can only happen to a device that was genuinely gone for a very
+     * long time, not a normal slow turn.
+     */
+    private sweepLeases;
+    /**
+     * Condition (b) above: `undefined` while `deviceId`'s connection counts as
+     * alive (never reapable, no matter how stale (c) is); otherwise the
+     * epoch-ms instant it began counting as "dark" for lease purposes.
+     * `sweepLeases` combines this with (c)'s own last-activity instant via
+     * `max(...)` so the full `taskLeaseMs` silence window is always measured
+     * from whichever of the two happened later.
+     */
+    private deviceDarkSince;
+    /** Reap one lease-expired task through the exact same TaskStore/canTransition path — and terminal-event emission — as any other `task.fail` (see {@link applyOrFail}). */
+    private reapTask;
+    dispatch(input: DispatchInput): Promise<TaskHandle>;
+    private buildTaskHandle;
+    /** Idempotent: cancelling an already-terminal task is a no-op, not an error. */
+    private cancelTask;
+    /**
+     * M4 Phase 3: made public (was private through M3) so an embedder can call
+     * it directly from its own operator-facing surface — there is no
+     * bearer-authed HTTP route for this on `http.ts`'s own app (see
+     * `UnknownTaskError`'s own doc comment for why, and
+     * `examples/basic/server.ts`'s `/api/tasks/:taskId/approve` for the
+     * intended shape of that embedder-built surface). See this file's own
+     * `UnknownTaskError`/`TaskNotAwaitingApprovalError` doc comments for why
+     * the two failure modes are now distinct typed errors rather than a
+     * single generic `Error`. Every thrown message's TEXT is byte-for-byte
+     * unchanged from M2/M3 — only the error's type changed (this is still also
+     * reachable via `TaskHandle.approve()`, unaffected).
+     */
+    /**
+     * M5 (approval targeting, docs/protocol.md §5.3): `opts.approvalId`
+     * targets a SPECIFIC pending approval rather than "whichever one is
+     * currently pending" (the pre-M5 default, unchanged when `opts` is
+     * omitted). Validated FIRST, before any state change or wire send: if
+     * `opts.approvalId` is supplied and this hub has a recorded
+     * `pendingApprovalId` for `taskId` that DIFFERS, throws
+     * {@link StaleApprovalError} — no transition, no `task.approve` sent. If
+     * this hub never recorded a `pendingApprovalId` (a legacy daemon that
+     * never reported one), the call proceeds untargeted exactly as before.
+     * The outgoing `task.approve` carries `approvalId`: the caller-supplied
+     * one if given, else this hub's own recorded one, else omitted entirely
+     * (legacy wire shape) — so the daemon can apply its own exact-match check
+     * whenever this server has an id to offer at all.
+     */
+    approveTask(taskId: string, opts?: {
+        approvalId?: string;
+    }): Promise<void>;
+    /**
+     * M4 Phase 3: made public — see {@link ConnectionHub.approveTask}'s own
+     * doc comment for the full rationale (identical reasoning applies here).
+     * M5: same `opts.approvalId` targeting semantics as `approveTask` above —
+     * see that method's own doc comment.
+     */
+    rejectTask(taskId: string, reason?: string, opts?: {
+        approvalId?: string;
+    }): Promise<void>;
+    /**
+     * S0 (GAP-002): a task-level gate, evaluated in full before any envelope is
+     * built — see {@link SteerRejectedError} for the gap this closes and why an
+     * unknown capability must refuse rather than proceed. Order matters:
+     *
+     *   1. unknown task — unchanged pre-S0 `Error` (this is not a steer-policy
+     *      decision, and `TaskHandle.steer` can only be reached with a taskId
+     *      this hub minted, so it's a programming error, not an operator one);
+     *   2. terminal (`Complete`/`Failed`/`Cancelled`) -> `task_terminal`,
+     *      checked BEFORE the `Running` check so a steer racing a terminal
+     *      transition always resolves terminal-first;
+     *   3. not `Running` (`Offered`/`Claimed`/`AwaitApproval`) ->
+     *      `task_not_running`;
+     *   4. the claim-time snapshot does not positively say `steer: true` ->
+     *      `steer_unsupported_runtime`, including when there is no snapshot at
+     *      all (fail-closed);
+     *   5. only then, the pre-existing device-liveness check and the send.
+     *
+     * Step 4 reads `TaskSnapshot.claimedRuntimeCapabilities` — the per-runtime,
+     * per-task value frozen at claim time from the claiming adapter's own
+     * `task.claim.capabilities` — and reads NO connection state whatsoever:
+     * not {@link getDeviceCapabilities}, not `ConnectionState.runtimes`, and
+     * with no fallback to either when the snapshot is absent. See
+     * {@link SteerRejectedError} for why a connection-sourced input is wrong
+     * both in scope (describes a daemon build, not this task's runtime) and in
+     * reach (absent entirely on long-poll-only daemons).
+     */
+    private steerTask;
+    private pickFirstConnectedDevice;
+    /**
+     * Build a server -> daemon envelope with a fresh per-device `seq`, retain
+     * it in that device's outbox ring buffer, and deliver it now if a live
+     * transport is available (WS send, or wake a pending long-poll).
+     *
+     * `opts`'s type mirrors `createEnvelope`'s own per-type conditional
+     * requiredness (finding F1) minus `seq` (computed fresh right here on
+     * every call, never caller-supplied) — so every one of this method's 6
+     * callers below must supply `taskId` for the 5 types that need it
+     * (everything except `conn.ack`), same as calling `createEnvelope`
+     * directly would require.
+     */
+    private sendToDevice;
+    private deliverToDevice;
+    /**
+     * Retained envelopes for `deviceId` with `seq > cursor` that still belong
+     * to a non-terminal task — OR are explicitly exempted from that filter
+     * (`redeliverThroughTerminal`, N1/F4: `task.cancel`/`task.reject`) — in
+     * `seq` order. The `seq > cursor` bound is what naturally stops an
+     * exempted entry from redelivering forever: once the daemon acks it (its
+     * reported cursor advances past that `seq`), it no longer qualifies here
+     * on any future reconnect/poll.
+     */
+    private collectRelevant;
+    private isTaskTerminal;
+    /** The highest `seq` assigned to `deviceId` so far — the redelivery cursor to hand back on a poll/reconnect. */
+    private currentCursor;
+    private getOrCreateOutbox;
+    listMachines(): MachineInfo[];
+    /**
+     * M5 (approval targeting, hello-capability plumbing): the capability flags
+     * `deviceId`'s CURRENT connection advertised in its `conn.hello` —
+     * `undefined` if this hub has no connection state for the device at all,
+     * or one that never had capabilities recorded (a pre-M5 daemon, or a
+     * device this hub only ever saw over long-poll with no prior WS hello —
+     * see `ConnectionState.capabilities`'s own doc comment). Read fresh from
+     * live connection state, mirroring `listMachines()`'s own convention; an
+     * embedder can use this to distinguish a targeting-capable device from a
+     * legacy one for its own observability/UI purposes (see `version.ts`'s
+     * `approval-targeting` flag doc comment for why this is informational
+     * only, never a correctness gate).
+     */
+    getDeviceCapabilities(deviceId: string): readonly string[] | undefined;
+    getTask(taskId: string): TaskSnapshot | undefined;
+    listTasks(): TaskSnapshot[];
+    /**
+     * A plain, serializable snapshot of this hub's current state, derived from
+     * existing structures (`connections`, `taskStore`) plus the small counters
+     * this file already maintains for exactly this purpose — no new
+     * bookkeeping structures beyond those counters. See {@link HubStats}
+     * (`types.ts`) for the full field-by-field contract.
+     */
+    stats(): HubStats;
+}