@byok-sdk/server 0.11.0 → 0.13.0

package/dist/hub.d.ts

@@ -1,931 +0,0 @@
-import type { WebSocket } from 'ws';
-import { type Envelope, type AgentMessagePublishPayload, type AgentMessageServerContext, type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionReadback, type RuntimeId, type RuntimeInfo, type TaskState, type ToolsetId } from '@byok-sdk/protocol';
-import type { DeviceRegistry } from './auth';
-import { RateLimiter } from './rate-limiter';
-import type { TaskStore } from './task-store';
-import type { ByokServerEvent, AgentContentReadRequest, AgentHomeProjectionRequest, AgentEgressReceipt, DispatchInput, FreshAgentEgressDispatchInput, 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`
- * plus the authenticated long-poll `conn.hello` snapshot 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`, either task offer, `task.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, lifecycle: the authenticated `conn.hello` snapshot on either
- * transport describes the device build, while the claim establishes the
- * exact task↔runtime binding. Only the latter shares a lifecycle with the
- * thing this gate judges. Adding a connection-level fallback here would
- * restore the scope defect 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 type AgentHomeProjectionCompletionErrorCode = 'not_found' | 'conflict' | 'invalid';
-export declare class AgentHomeProjectionCompletionError extends Error {
-    readonly code: AgentHomeProjectionCompletionErrorCode;
-    constructor(code: AgentHomeProjectionCompletionErrorCode, message: string);
-}
-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 agentMessage?;
-    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;
-    /** First-write-wins reliable facts; the reference composition's bounded in-memory readback. */
-    private readonly agentEgressReceipts;
-    private readonly agentMessageRequirements;
-    private readonly agentMessageReceipts;
-    private readonly agentMessageTaskPayloads;
-    /** Accepted requests are the authority that later receipts/transfers must echo exactly. */
-    private readonly agentContentReadRequests;
-    /** Content-free explicit-read audit facts keyed by exact authenticated device/request identity. */
-    private readonly agentContentReceipts;
-    /** Immutable requested projection facts, keyed by authenticated device/request. */
-    private readonly agentHomeProjectionRequests;
-    /** First terminal completion for each exact projection request. */
-    private readonly agentHomeProjectionCompletions;
-    /**
-     * 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, agentMessage?: {
-        consume(input: {
-            readonly deviceId: string;
-            readonly taskId: string;
-            readonly context: AgentMessageServerContext;
-            readonly payload: AgentMessagePublishPayload;
-        }): {
-            readonly outcome: 'accepted' | 'held' | 'refused';
-            readonly reasonCode?: string;
-        };
-    } | undefined);
-    /**
-     * 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[], configuredToolsets?: readonly ToolsetId[], clientVersion?: 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;
-    /**
-     * Drop every piece of hub state keyed by `deviceId` — called when the
-     * device's registration is DELETED (§6.3 revocation, composed in
-     * `index.ts`). Presence, its undelivered outbox, its inbound-dedup ring,
-     * any held long-poll, and its rate-limit episode suppression only ever
-     * existed to serve a row the directory can no longer name; leaving them
-     * would keep a deleted device visible as live state and would let a
-     * re-paired device inherit the dead one's dedup window and seq cursor.
-     *
-     * What the device DID is not revocation's business and is untouched here:
-     * task records (`taskStore`), egress and content receipts, and projection
-     * facts are history, not credentials.
-     *
-     * A live socket is closed rather than left attached — a still-open WS whose
-     * next envelope would re-create the presence entry we just deleted is a
-     * half-applied revocation. The close is detached first so `handleDisconnect`
-     * sees no connection state and skips its disconnect bookkeeping: the device
-     * is not going dark, it is gone.
-     */
-    forgetDevice(deviceId: string): 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 arriving inbound is rejected before it's
-     *    dispatched or counted accepted. `conn.hello` is the one non-task
-     *    exception, and is accepted only from the bearer-authenticated
-     *    long-poll route with an exact device/product/protocol match.
-     * 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, authenticatedProductId?: string): 'accepted' | 'duplicate' | 'rejected' | 'rate_limited';
-    /**
-     * Store before acking. Replays must agree on every identity/cursor/hash
-     * field and receive the original receipt id; a same event id with changed
-     * facts is rejected rather than treated as an update.
-     */
-    private handleAgentEgressReliable;
-    private handleAgentMessagePublish;
-    private sendAgentMessageDisposition;
-    private handleAgentContentReceipt;
-    private sendAgentEgressAck;
-    private sendAgentContentReceiptAck;
-    private agentEgressReceiptKey;
-    /** Record the authenticated long-poll equivalent of the WS opening frame. */
-    private registerLongPollHello;
-    /**
-     * 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>;
-    dispatchFreshAgentEgress(input: FreshAgentEgressDispatchInput): Promise<TaskHandle>;
-    private dispatchInternal;
-    /** Capability-gated control-plane read request; no request enters the outbox on omission. */
-    requestAgentContentRead(input: AgentContentReadRequest): Promise<void>;
-    /** Task-free exact-device projection; no task record, runtime or session is created. */
-    enqueueAgentHomeProjection(input: AgentHomeProjectionRequest): Promise<AgentHomeProjectionReadback>;
-    readAgentHomeProjection(deviceId: string, requestId: string): AgentHomeProjectionReadback | undefined;
-    completeAgentHomeProjection(deviceId: string, input: AgentHomeProjectionCompletionRequest): AgentHomeProjectionReadback;
-    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
-     * in scope (it describes a daemon build, not this task's runtime).
-     */
-    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;
-    private hasDeviceCapabilities;
-    getAgentEgressReceipt(deviceId: string, eventId: string): AgentEgressReceipt | 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;
-}