@byok-sdk/client 0.1.0

package/dist/daemon/create-daemon.d.ts

@@ -0,0 +1,364 @@
+import type { RuntimeId } from '@byok-sdk/protocol';
+import type { PermissionPolicy } from '@byok-sdk/protocol';
+import type { RuntimeAdapter, GitWorkspaceConfig } from '../types';
+import type { BackoffOptions, LivenessOptions } from './ws-transport';
+import { type OperationalHealthSnapshot } from './operational-health';
+import { type DaemonEventListener, type DaemonTaskInfo, type Unsubscribe } from './observer';
+import { GitWorkspaceManager } from './git-workspace';
+import { GitWorkspaceStore } from './git-workspace-store';
+import { type DeviceRecord } from './store';
+import { type LocalTaskJournal } from './journal/journal';
+import { type JournalOpenFaultSeam } from './journal/sqlite-support';
+import { LocalStoragePressureEngine, type LocalStoragePolicyInput } from './journal/storage-policy';
+import type { ProgressBatcherOptions } from './progress-batcher';
+/**
+ * Optional white-label product display info — purely opaque passthrough
+ * (never interpreted, validated, or rendered by the daemon itself). Carried
+ * through to `DaemonStatus.branding` (see `status()` below) so a downstream
+ * CLI or audit log can render/stamp product identity without the daemon
+ * needing to know anything about presentation. Deliberately a small,
+ * open-ish shape rather than an exhaustive theming schema — add fields here
+ * only as concrete consumers (CLI UX, audit log) need them.
+ */
+export interface DaemonBranding {
+    /** Product/company name for banners, prompts, audit log entries, etc. */
+    displayName?: string;
+    /** Support/help URL surfaced alongside branding. */
+    supportUrl?: string;
+    /** Brand accent color (any CSS-color-like string — hex, name, etc.); not parsed or validated here. */
+    accent?: string;
+}
+/**
+ * S3b (L-002): opt-in durable local journal for hosted deployments
+ * (architecture §12.7.2).
+ *
+ * Explicit and off by default, because it changes what an ack MEANS. With no
+ * journal configured (the self-hosted default this SDK has always shipped),
+ * the daemon's redelivery cursor advances on handler success exactly as
+ * before. With one configured, every inbound envelope is committed and fsynced
+ * to `<storeDir>/daemon.db` BEFORE the handler resolves — and since
+ * `ConnectionManager` only advances the cursor once the handler resolves
+ * (`connection-manager.ts`), acking before committing stops being something
+ * this daemon can express, rather than something it is careful not to do.
+ *
+ * Turning this on when the runtime has no working `node:sqlite` is a typed
+ * construction failure, not a downgrade to a file journal — see
+ * `JournalUnavailableError`. That refusal is the point (§12.7.2): a journal
+ * that does not fsync loses tasks only under power-cut timings, so it passes
+ * every test anyone will ever run against it.
+ */
+export interface HostedJournalConfig {
+    /**
+     * The backend. Only `sqlite` today, and spelled out rather than implied by
+     * the section's presence so adding a second one later is an additive change
+     * to a closed set instead of a re-interpretation of an existing config.
+     */
+    mode: 'sqlite';
+    /**
+     * The tenant every journal row on this device is scoped to (§12.7.2's
+     * minimum fact set opens with tenant/product/device). Required: a hosted
+     * daemon that cannot say which tenant its durable evidence belongs to has
+     * evidence nobody can act on.
+     */
+    tenantId: string;
+    /** Bound on waiting for the journal's write lock, ms. Defaults to the journal's own bound. */
+    busyTimeoutMs?: number;
+    /** Per-record byte bound. Defaults to the journal's own bound; oversized records are refused, never truncated. */
+    maxRecordBytes?: number;
+    /**
+     * S3b (L-003): opt-in local storage policy — §12.7.2.1's watermarks,
+     * classified GC, and bounded WAL compaction. See `LocalStoragePolicyInput`
+     * (`journal/storage-policy.ts`); `maxStoreBytes` and `minFreeBytes` are the
+     * only two a host must supply.
+     *
+     * Optional WITHIN hosted journal mode, and off by default there too: a
+     * journal without a policy is a daemon that records durably and never
+     * declines, which is exactly the right behaviour on a host that manages its
+     * own disk. Setting it is what turns local storage into an admission-control
+     * input — hard pressure declines new offers (retryably) while terminal
+     * flush, delete, export and recovery keep running, and `emergency` refuses
+     * to ack at all rather than acking a row it cannot durably record.
+     */
+    storagePolicy?: LocalStoragePolicyInput;
+}
+export interface DaemonConfig {
+    productName: string;
+    productId: string;
+    serverUrl: string;
+    deviceName?: string;
+    workspaceRoot: string;
+    /** Disabled by default. Enables local-only Git checkpoint repositories. */
+    gitWorkspace?: GitWorkspaceConfig;
+    /** Disabled by default. Enables the durable local task journal — see {@link HostedJournalConfig}. */
+    hostedJournal?: HostedJournalConfig;
+    /**
+     * Restricts which runtimes this daemon will ever use — enforced in two
+     * places that must stay consistent: `createDaemon` (this file) builds its
+     * bundled adapter set FROM this list (unset = all three bundled adapters
+     * — pi, claude, codex; set = exactly the listed runtime ids, unknown ids
+     * ignored — see `buildDefaultAdapters`), and `TaskRunner.pickAdapter`
+     * (`task-runner.ts`) separately fail-closed-rejects any `task.offer`
+     * naming a runtime outside this list regardless of which adapters were
+     * constructed. `createDaemonWithAdapters` callers supply their own
+     * `adapters` array directly, so for them this field is enforcement-only,
+     * unchanged from M1/M2.
+     */
+    runtimeAllowlist?: string[];
+    /**
+     * M5 batch-3 (workstream 1): explicit auto-select priority order for
+     * `TaskRunner.pickAdapter`'s no-explicit-runtime branch (`task-runner.ts`)
+     * — tried in listed order; the first candidate that is both PRESENT
+     * (`adapter.detect()`) and CAPABLE (declares the offer's
+     * `PermissionPolicy.mode` in its own `capabilities().permissionModes` —
+     * see `adapterSupportsMode`) wins. Unset defaults to
+     * `DEFAULT_RUNTIME_PREFERENCE` (`task-runner.ts`): `['claude', 'codex',
+     * 'pi']` — pi LAST, deliberately.
+     *
+     * Product decision: pi is this SDK's FALLBACK runtime, not its default.
+     * Before this field existed, the auto-select path had no notion of
+     * priority at all — it simply walked `deps.adapters` in whatever order
+     * `buildDefaultAdapters`/the embedder constructed them, which for
+     * `createDaemon`'s bundled set meant `ALL_RUNTIME_IDS`'s construction
+     * order (`['pi', 'claude', 'codex']`) doubled as the de-facto selection
+     * priority — silently making pi the default winner whenever it was
+     * present, for no better reason than being listed first in an array never
+     * meant to encode a priority. This field makes the real priority an
+     * explicit, independently-configurable decision instead of an accident of
+     * construction order — see `ALL_RUNTIME_IDS`'s own doc comment below for
+     * the construction-vs-selection-order split this introduces.
+     *
+     * Only affects the auto-select (no `task.offer.runtime`) path — an offer
+     * naming an explicit runtime is unaffected (unchanged semantics: that
+     * exact adapter is used, or the offer is declined; never a fallback
+     * substitution). Independent of `runtimeAllowlist` above (which restricts
+     * WHICH runtimes are eligible at all): this only orders the attempt
+     * sequence among whatever that allowlist, if set, already let through.
+     */
+    runtimePreference?: RuntimeId[];
+    /**
+     * The device operator's configured policy CEILING — every `task.offer`'s
+     * own policy is merged against this and fail-closed-rejected if it asks
+     * for more latitude than this allows (`daemon/policy.ts`'s
+     * `computeEffectivePolicy`).
+     *
+     * M5 batch-3 (workstream 1): `workspaceRoot` set on THIS ceiling is still
+     * merged into the effective policy handed to an adapter as
+     * `ctx.policy.workspaceRoot` (`computeEffectivePolicy` is unchanged) — but
+     * no bundled adapter (pi/claude/codex) actually reads or enforces it;
+     * every adapter derives its real confinement from `ctx.workspaceDir` (the
+     * daemon-created per-task directory) instead — see docs/security.md's
+     * "Workspace confinement is a convention, not a sandbox" section. Setting
+     * it here is therefore silently inert rather than actively dangerous by
+     * itself (an OFFER independently asking for its OWN `workspaceRoot` is a
+     * separate, fail-closed-declined case — see `TaskRunner.handleOffer` —
+     * precisely because THAT looks like a live security control when it
+     * isn't). `start()` below logs a loud, one-time `console.warn` whenever
+     * this ceiling sets `workspaceRoot`, so an operator who configured it
+     * expecting real enforcement finds out immediately instead of trusting a
+     * control nothing honors.
+     */
+    permissionDefaults?: PermissionPolicy;
+    storeDir?: string;
+    /** Optional white-label branding — see `DaemonBranding`. Carried through verbatim to `status().branding`. */
+    branding?: DaemonBranding;
+    /**
+     * M5: per-device, per-runtime escape hatch into the environment allowlist
+     * `task-runner.ts` builds each task's spawn environment from
+     * (`daemon/environment.ts`'s `buildRuntimeEnv`) — keyed by runtime id
+     * (`'pi' | 'claude' | 'codex'`, though not typed that narrowly here since
+     * an id with no matching adapter is simply never looked up). `allow`
+     * entries are exact variable names or `*`-suffixed prefixes, merged in
+     * alongside that runtime adapter's own declared
+     * `environmentRequirements()` — this can never override the hard
+     * `BYOK_*` deny (see `environment.ts`'s own doc comment).
+     */
+    runtimeEnvironment?: Record<string, {
+        allow?: string[];
+    }>;
+    /**
+     * M5: explicit escape hatch for `url.ts`'s `assertServerUrlAllowed` — see
+     * that function's own doc comment for the full allow/deny rule. Default
+     * (unset/`false`): a `serverUrl` using plaintext `ws:`/`http:` is only
+     * accepted when its host is loopback (`localhost`/`*.localhost`,
+     * `127.0.0.0/8`, `::1`); anything else over plaintext throws a typed
+     * `InsecureServerUrlError` from `pair()`/`start()` below, BEFORE any
+     * network call is attempted, rather than silently sending the pairing
+     * code / device credentials to a remote host in the clear. Set this
+     * `true` only when you have deliberately decided to accept that risk
+     * (e.g. a trusted private network with no TLS terminator in front of the
+     * server) — doing so also logs a loud `console.warn` (see
+     * `checkServerUrl`, this file) every time it actually changes the
+     * outcome. Never overrides an unsupported scheme (anything other than
+     * `http:`/`https:`/`ws:`/`wss:`), which is refused unconditionally.
+     */
+    dangerouslyAllowInsecureRemote?: boolean;
+    /**
+     * M5 batch-3 (workstream 2): caps accumulated (approximate,
+     * serialized-event-length) agent-event output bytes this daemon will
+     * tolerate for a single task before tearing it down as a resource-limit
+     * violation (`task.fail`, `retryable: false`, reason prefixed
+     * `resource limit exceeded: maxTaskOutputBytes` — see
+     * `MAX_OUTPUT_BYTES_EXCEEDED_REASON_PREFIX`, `task-runner.ts`) — see
+     * `TaskRunner.pump`'s own doc comment for exactly what's counted and what
+     * isn't. Default {@link DEFAULT_MAX_TASK_OUTPUT_BYTES} (64 MiB) when
+     * unset.
+     *
+     * `0` or a negative number is a config validation error, thrown
+     * synchronously from `createDaemonWithAdapters`/`createDaemon` — NOT a
+     * supported way to disable the cap. Pass `Number.POSITIVE_INFINITY`
+     * explicitly instead to opt out of enforcement altogether.
+     */
+    maxTaskOutputBytes?: number;
+    /**
+     * M5 batch-3 (workstream 2): deadline bound on the graceful-shutdown
+     * sequence's own wait for `TaskRunner.shutdownActiveTasks` to finish
+     * interrupting/failing every active task before this daemon proceeds to
+     * actually stop regardless — see `runShutdownSequence`'s own doc comment
+     * for the full sequence this bounds, and for why every graceful-shutdown
+     * path (`stop()`, `unpair()`, the control socket's `shutdown` RPC) now
+     * shares it. Default 10s (`SHUTDOWN_TASK_TEARDOWN_DEADLINE_MS`) — the same
+     * bound the control-socket shutdown path already used before this field
+     * existed.
+     */
+    shutdownGraceMs?: number;
+}
+export interface DaemonStatus {
+    paired: boolean;
+    connected: boolean;
+    /** True once the connection has fallen back to long-poll (protocol §8) — transport info only (finding F6): long-poll is a full transport, so work still proceeds normally while this holds; outbound envelopes POST to /byok/messages instead of going out over WS. */
+    degraded: boolean;
+    /** True once the server has revoked this device (401 on challenge/token, protocol §6.3). The only recourse is calling `pair()` again — the daemon does not keep retrying on its own. */
+    revoked: boolean;
+    deviceId?: string;
+    activeTaskCount: number;
+    /** Passthrough of `DaemonConfig.branding` — `undefined` when the product configured none. See `DaemonBranding`. */
+    branding?: DaemonBranding;
+    /** Local lifecycle/retry budget, separate from transport fallback state. */
+    operationalHealth: OperationalHealthSnapshot;
+}
+export interface Daemon {
+    pair(pairingCode: string): Promise<DeviceRecord>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    status(): DaemonStatus;
+    /**
+     * M3-2a: local observability — subscribe to live `DaemonEvent`s (task
+     * feed, connection/pairing state changes, runtime-detection results) as
+     * they happen on THIS daemon, no SaaS-side polling required. Returns an
+     * unsubscribe function; a listener that throws is caught and logged, never
+     * propagated (see `observer.ts`). Purely additive: emitting these never
+     * changes `status()` or any existing wire/task behavior.
+     */
+    subscribe(listener: DaemonEventListener): Unsubscribe;
+    /** M3-2a: current locally-known tasks and their derived state/summary (for a `tasks` CLI subcommand) — reflects only what this daemon has observed since it started; see `observer.ts`'s `DaemonObserver.tasks`. */
+    tasks(): DaemonTaskInfo[];
+    /**
+     * M3-2a: clears this device's persisted identity/credentials and
+     * disconnects — the next `start()` throws until `pair()` is called again.
+     * Safe to call at any point in the daemon's lifecycle (never paired,
+     * paired-but-not-started, or running).
+     */
+    unpair(): Promise<void>;
+    /**
+     * M3-2a: locally resolve a task currently paused on `needs_approval` —
+     * drives the exact same code path a server-sent `task.approve` does
+     * (`TaskRunner.handleApprove`), invoked directly instead of over the wire.
+     * Honest-but-currently-unexercised: none of the three bundled adapters
+     * (pi/claude/codex) ever actually pauses for approval — each one's
+     * `resolveApproval` throws unconditionally (see `toRuntimeInfoCapabilities`'s
+     * doc comment below) — so calling this against a task on this daemon today
+     * always fails that task with a clear reason instead of resuming it,
+     * exactly as an honest, doing-nothing-magic implementation should. Ready
+     * for the day a runtime adapter implements real interactive approval, with
+     * no further changes needed here. A no-op (resolves immediately) for a
+     * `taskId` this daemon doesn't currently have active.
+     */
+    approve(taskId: string): Promise<void>;
+    /** M3-2a: same as {@link approve} but rejects — see that method's doc comment. */
+    reject(taskId: string, reason?: string): Promise<void>;
+}
+/** Internal seam so tests can substitute stub adapters / faster backoff+batch+liveness+long-poll timing. `createDaemonWithAdapters` (which takes this) is also the real entry point for products supplying a hand-built adapter set `createDaemon` can't construct on its own — e.g. custom adapter options, or an adapter that REPLACES a bundled runtime's implementation under the same id. Honest limit: an adapter id outside `pi`/`claude`/`codex` cannot pass wire validation today — `RuntimeIdSchema` (`@byok-sdk/protocol`) is a closed `z.enum(['pi', 'claude', 'codex'])`, and `isRuntimeId` filtering below (see `detectRuntimes`) drops any detected adapter outside that set before it ever reaches a wire-visible field. A genuinely fourth/namespaced runtime id is a future protocol change, not something this seam enables today. */
+export interface DaemonOverrides {
+    backoff?: BackoffOptions;
+    batch?: ProgressBatcherOptions;
+    liveness?: LivenessOptions;
+    /** M4 Phase 3: overrides `TaskRunner`'s default out-of-band approval wait (`DEFAULT_APPROVAL_TIMEOUT_MS`, 10 minutes) before an unanswered `requestApproval` force-resolves as a fail-closed rejection. */
+    approvalTimeoutMs?: number;
+    /** Finding F5: overrides for the control-socket shutdown path's own bounded waits — see `TaskRunner.shutdownTask`'s and `ConnectionManager.stop`'s own doc comments. Both default to 5s; neither affects an ordinary (non-shutdown-RPC) `daemon.stop()` call. */
+    shutdown?: {
+        /** Bound on how long `shutdownTask` waits for a single task's own `session.interrupt()` before giving up on it specifically and reporting `task.fail` anyway. Default `DEFAULT_SHUTDOWN_INTERRUPT_TIMEOUT_MS`. */
+        taskInterruptTimeoutMs?: number;
+        /** Bound on how long the control-socket shutdown path waits for the outbox to actually drain before closing the connection. Default `DEFAULT_SHUTDOWN_OUTBOX_DRAIN_TIMEOUT_MS`. */
+        outboxDrainTimeoutMs?: number;
+    };
+    longPoll?: {
+        /** Consecutive never-acked WS connect failures before falling back to long-poll. Default 3. */
+        wsFailureThreshold?: number;
+        /** While long-polling, how often to retry establishing WS. Default 5 minutes. */
+        wsRetryIntervalMs?: number;
+        /** Backoff between failed long-poll HTTP attempts. Default 2s. */
+        retryDelayMs?: number;
+        /** Minimum delay before the next long-poll request after an empty (no-events) response — avoids busy-looping against a server that responds instantly. Default 250ms. */
+        idleDelayMs?: number;
+    };
+    /**
+     * Test/product injection seam for the local Git workspace boundary. The
+     * supplied manager/store are used only when `config.gitWorkspace` is enabled;
+     * an absent Git config therefore cannot accidentally activate either object.
+     */
+    gitWorkspace?: {
+        manager?: GitWorkspaceManager;
+        store?: GitWorkspaceStore;
+    };
+    /**
+     * S3b: injection seam for the durable local journal, mirroring
+     * `gitWorkspace` above — used only when `config.hostedJournal` is set, so an
+     * absent journal config cannot accidentally activate a supplied object. Also
+     * the host-injected-implementation path §12.7.2 allows: a backend other than
+     * `SqliteLocalTaskJournal` is acceptable if it meets the same durability
+     * contract (a resolved `appendEnvelope` means fsynced), and unacceptable
+     * otherwise — this seam does not verify that, the host asserting it does.
+     *
+     * A journal supplied here is NOT closed by `stop()`; whoever injected it
+     * owns its lifetime.
+     */
+    hostedJournal?: {
+        journal?: LocalTaskJournal;
+        /** Test-only post-open SQLite initialization fault seam. */
+        openFaults?: JournalOpenFaultSeam;
+        /**
+         * S3b (L-003): injection seam for the storage pressure engine, same rule
+         * as `journal` above — used only when `config.hostedJournal` is set, and
+         * NOT started or stopped by this daemon. Whoever injects one owns its
+         * cadence, which is what lets the disk-pressure matrix drive `tick()` by
+         * hand with fake usage/free providers and no timer at all.
+         *
+         * An injected engine still answers both questions the daemon asks it
+         * (admission under hard pressure, ack-critical refusal under emergency)
+         * and still backs the `storage` section of the control-socket status.
+         */
+        pressureEngine?: LocalStoragePressureEngine;
+    };
+}
+export declare function createDaemonWithAdapters(config: DaemonConfig, adapters: RuntimeAdapter[], overrides?: DaemonOverrides): Daemon;
+/**
+ * Public white-label entry point (M0-M3): the "5-line launcher" — a product
+ * only needs a `DaemonConfig`, no hand-built adapter list. The bundled
+ * adapter set is built from `config.runtimeAllowlist` (see
+ * `buildDefaultAdapters` and that field's own doc comment for the exact
+ * unset-vs-set contract); with no `runtimeAllowlist` configured, the default
+ * is ALL THREE bundled adapters (pi, claude, codex), not pi alone: M0/M1
+ * hard-wired pi-only unconditionally, which meant any product wanting
+ * claude/codex had to drop to `createDaemonWithAdapters` and hand-build
+ * adapters just to get a runtime that was already built into this SDK.
+ * `detectRuntimes` only ever advertises what's actually present on the
+ * device (protocol §10 gap #4), so constructing an adapter for a runtime the
+ * device doesn't have costs one quick failed `--version` probe at `start()`
+ * and is otherwise invisible — there's no reason to withhold it by default.
+ * Products that DO want to restrict to a subset set `runtimeAllowlist`
+ * (also independently enforced at task-pick time — see
+ * `TaskRunnerDeps.runtimeAllowlist` / `TaskRunner.pickAdapter`); products
+ * needing something this can't build (custom adapter options, a fourth
+ * in-house runtime, test stubs) use `createDaemonWithAdapters` directly.
+ */
+export declare function createDaemon(config: DaemonConfig): Daemon;

package/dist/daemon/cursor-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Persists the highest processed server->daemon envelope `seq` per
+ * (server, device) pair (protocol §9, at-least-once redelivery), so a
+ * restarted daemon can send an accurate `conn.hello.cursor` and the server
+ * can skip re-delivering envelopes it already knows were handled. Keyed by a
+ * hash of `serverUrl` + `deviceId` together (not just `serverUrl`) so
+ * filenames stay filesystem-safe regardless of scheme/port/path.
+ *
+ * Finding F5 (stale cursor across re-pair): `POST /byok/pair` always mints a
+ * brand new `deviceId` (see `packages/server/src/http.ts`), including on a
+ * re-pair against the same `serverUrl` (e.g. recovering from revocation,
+ * protocol §6.3). A cursor keyed by `serverUrl` alone would hand the fresh
+ * device's very first connection a stale, unrelated cursor value left over
+ * from whatever device previously used this URL — the new device's own
+ * server-side outbox starts its `seq` counter back at 1, so that stale
+ * cursor would make the server's redelivery filter (`seq > cursor`) throw
+ * away every legitimate envelope sent to it. Keying by the pair means a new
+ * deviceId always starts with a genuinely fresh (absent) cursor entry;
+ * `clear()` additionally lets `create-daemon.ts`'s `pair()` proactively wipe
+ * the previous device's entry for this `serverUrl` as a hygiene measure.
+ */
+export declare class CursorStore {
+    private readonly storeDir;
+    constructor(storeDir: string);
+    private fileFor;
+    load(serverUrl: string, deviceId: string): Promise<number | undefined>;
+    save(serverUrl: string, deviceId: string, cursor: number): Promise<void>;
+    /** Remove any persisted cursor for (serverUrl, deviceId) — a no-op if none exists. Called from `pair()` (finding F5) so a device that's about to be replaced never leaves a cursor a future, unrelated device could somehow inherit. */
+    clear(serverUrl: string, deviceId: string): Promise<void>;
+}

package/dist/daemon/daemon-owner.d.ts

@@ -0,0 +1,24 @@
+export declare const DAEMON_OWNER_FILENAME = "daemon-owner.json";
+interface OwnerRecord {
+    version: 2;
+    pid: number;
+    nonce: string;
+    role: 'daemon' | 'doctor';
+    acquiredAt: string;
+    processStartedAt: string;
+    livenessPort: number;
+}
+export interface DaemonOwnerLease {
+    release(): Promise<void>;
+}
+export declare class DaemonOwnerActiveError extends Error {
+    readonly role: OwnerRecord['role'] | 'unknown';
+    constructor(role: OwnerRecord['role'] | 'unknown');
+}
+/**
+ * Cross-process, fail-closed ownership for store mutations that must never
+ * race a daemon. A separate exclusive reclaim file serializes stale-owner recovery so two
+ * starters cannot accidentally rename each other's newly-acquired lease.
+ */
+export declare function acquireDaemonOwner(storeDir: string, role: OwnerRecord['role'], clock?: () => Date): Promise<DaemonOwnerLease>;
+export {};

package/dist/daemon/deterministic-jitter.d.ts

@@ -0,0 +1,20 @@
+export type JitterDomain = 'reconnect' | 'upload' | 'maintenance';
+export interface DeterministicJitterInput {
+    seed: string;
+    domain: JitterDomain;
+    sequence: number;
+    baseMs: number;
+    ratio?: number;
+}
+/**
+ * Stable, domain-separated fleet jitter. The same identity/domain/sequence
+ * always produces the same integer delay, while a different domain cannot
+ * accidentally reuse the same hash stream. There is deliberately no random
+ * fallback: callers must have loaded the device identity before constructing
+ * an automatic retry loop.
+ */
+export declare function deterministicJitterMs(input: DeterministicJitterInput): number;
+export interface FleetJitter {
+    delay(domain: JitterDomain, sequence: number, baseMs: number): number;
+}
+export declare function createFleetJitter(productId: string, deviceId: string): FleetJitter;

package/dist/daemon/device-keys.d.ts

@@ -0,0 +1,45 @@
+import { type KeyObject } from 'node:crypto';
+/**
+ * Device identity keypair (protocol §6): Ed25519, generated once on first
+ * pair and reused across re-pairs (§6.3 — "a fresh device keypair is not
+ * required" when re-pairing after revocation). The private key never
+ * leaves this device; only the public key ever goes over the wire
+ * (`PairRequest.devicePublicKey`).
+ *
+ * Encoding choice: an OKP (Ed25519) key's JWK `x` member is defined by
+ * RFC 8037 as the raw 32-byte public key, base64url-encoded with no
+ * padding — exactly "Ed25519 public key, base64url-encoded" per
+ * docs/protocol.md §6.1, and avoids shipping an ASN.1/SPKI wrapper the
+ * server would otherwise have to strip. Signatures are the raw 64-byte
+ * Ed25519 signature (`crypto.sign(null, data, privateKey)` — Ed25519 needs
+ * no digest algorithm), also base64url-encoded.
+ */
+export interface DeviceKeyPair {
+    publicKeyBase64Url: string;
+    privateKey: KeyObject;
+}
+export declare function generateDeviceKeyPair(): DeviceKeyPair;
+/** PKCS8 PEM — the on-disk storage form (0600 file under storeDir). OS keychain integration is deferred (tracked as a future roadmap item, not promised for any specific milestone). */
+export declare function exportPrivateKeyPem(privateKey: KeyObject): string;
+export declare function importPrivateKeyPem(pem: string): KeyObject;
+/**
+ * S1 (GAP-004): the domain-separation prefix this device signs along with a
+ * challenge nonce, byte-identical to the server's own
+ * `NONCE_SIGNING_DOMAIN` (`packages/server/src/auth.ts`). The device key is a
+ * long-lived identity key that later planes will also sign structured
+ * messages with; tagging the domain is what stops a signature made for one of
+ * those from being replayable as a token-renewal credential.
+ *
+ * Not shared through a package: the two ends agree on a wire constant, and
+ * inventing a dependency between server and client to hold one string literal
+ * would couple them far harder than the literal does.
+ */
+export declare const NONCE_SIGNING_DOMAIN = "byok-nonce-v1\n";
+/**
+ * Sign a challenge nonce with the device private key: the signed message is
+ * {@link NONCE_SIGNING_DOMAIN} followed by `nonce` (UTF-8), and the result is
+ * the raw 64-byte Ed25519 signature, base64url-encoded (protocol §6.2). A
+ * server on the domain-separated contract rejects the undomained form, so
+ * there is no variant of this that omits the prefix.
+ */
+export declare function signNonce(privateKey: KeyObject, nonce: string): string;

package/dist/daemon/device-proof-signer.d.ts

@@ -0,0 +1,41 @@
+import { type DeviceProofEnvelopeV1 } from '@byok-sdk/core';
+import type { DeviceStore } from './store';
+export interface DeviceProofRequest {
+    readonly method: string;
+    /** Exact origin-relative path, including the query string when present. */
+    readonly path: string;
+    readonly operation: string;
+    readonly resource: string;
+    readonly requestId: string;
+    readonly body: Uint8Array;
+    readonly issuedAt?: string;
+    readonly expiresAt?: string;
+    readonly nonce?: string;
+}
+/** Local signing seam consumed by the truth client. It never exposes key bytes. */
+export interface DeviceProofSigner {
+    sign(request: DeviceProofRequest): Promise<DeviceProofEnvelopeV1>;
+}
+export interface StoredDeviceProofSignerOptions {
+    readonly store: Pick<DeviceStore, 'load'>;
+    /** Explicit host configuration. Pairing/bearer state is never mined for tenant identity. */
+    readonly tenantId: string;
+    readonly productId: string;
+    readonly keyId: string;
+    readonly keyEpoch: number;
+    readonly clock?: () => Date;
+}
+/**
+ * Signs request-bound S6 proofs with the paired device identity key.
+ *
+ * The store is read for every signature rather than cached: clearing the paired
+ * record immediately removes local signing authority. Canonicalization is
+ * imported from `@byok-sdk/core`, the one frozen byte authority; this module only
+ * supplies the Node Ed25519 operation.
+ */
+export declare class StoredDeviceProofSigner implements DeviceProofSigner {
+    #private;
+    private readonly options;
+    constructor(options: StoredDeviceProofSignerOptions);
+    sign(request: DeviceProofRequest): Promise<DeviceProofEnvelopeV1>;
+}

package/dist/daemon/environment.d.ts

@@ -0,0 +1,96 @@
+/**
+ * M5: per-runtime environment allowlist for spawned agent child processes.
+ *
+ * Before this module existed, `task-runner.ts` built every task's
+ * `TaskContext.env` as `process.env` verbatim — the daemon's OWN full
+ * environment, unfiltered, handed to whichever runtime CLI (`pi`/`claude`/
+ * `codex`) `pickAdapter` selected. Any credential-shaped variable sitting in
+ * the daemon's own environment for a completely unrelated reason (an
+ * `AWS_SECRET_ACCESS_KEY`, `DATABASE_URL`, `GITHUB_TOKEN` set for the
+ * daemon's OWN deployment, nothing to do with any coding-agent runtime) was
+ * therefore inherited by every single spawned agent process — a
+ * credential-leak gap, not a deliberate design choice.
+ *
+ * {@link buildRuntimeEnv} replaces that blanket passthrough with an explicit
+ * allowlist, built fresh per task from three layers:
+ *
+ * 1. A small, always-included platform baseline ({@link BASE_PLATFORM_ALLOWLIST}
+ *    / {@link WINDOWS_BASE_ALLOWLIST}) — the bare minimum any CLI needs to
+ *    resolve its own binaries/libraries, find a home/temp directory, and
+ *    behave sanely in a non-interactive shell.
+ * 2. Whatever ADDITIONAL names the *specific* runtime adapter about to be
+ *    spawned declares it actually needs
+ *    (`RuntimeAdapter.environmentRequirements()` — see `../types.ts`). An
+ *    adapter that declares nothing at all (doesn't implement the optional
+ *    method) gets the platform baseline ONLY — fail-closed by construction,
+ *    not by an extra check here.
+ * 3. A per-device, per-runtime operator override (`DaemonConfig
+ *    .runtimeEnvironment` — see `create-daemon.ts`) — a local escape hatch
+ *    for a product/operator that knows it needs one more variable forwarded
+ *    to one specific runtime on this one device.
+ *
+ * One hard, unconditional deny always wins over all three layers above,
+ * including the operator's own override: `BYOK_*`, this SDK's own
+ * control-plane variables, must never reach a spawned agent process — see
+ * {@link HARD_DENY_PATTERNS}.
+ *
+ * Every name in every list may be an exact match or a `*`-suffixed prefix
+ * (e.g. `'LC_*'` matches `LC_ALL`, `LC_CTYPE`, ...).
+ */
+/**
+ * What one runtime adapter declares it needs beyond the always-included
+ * platform baseline. Returned from the optional
+ * `RuntimeAdapter.environmentRequirements()` method (`../types.ts`).
+ */
+export interface RuntimeEnvironmentRequirements {
+    /**
+     * Extra non-secret, config-discovery-shaped variable names this runtime's
+     * own CLI reads (e.g. a `<RUNTIME>_CONFIG_DIR`-style override) — anything
+     * that isn't itself a credential. Optional: most adapters need nothing
+     * beyond the platform baseline.
+     */
+    baseNames?: readonly string[];
+    /**
+     * Credential/auth variable names this runtime's own CLI reads to
+     * authenticate (e.g. a provider API key). Kept as its own field (distinct
+     * from `baseNames`) so a product's own security review can reason about
+     * "what credential-shaped names does this runtime get" as a single,
+     * explicit list per adapter — see e.g. the pi adapter's
+     * `KNOWN_PROVIDER_ENV_VARS`.
+     */
+    credentialNames?: readonly string[];
+}
+/** Inputs to {@link buildRuntimeEnv}. */
+export interface BuildRuntimeEnvOptions {
+    /**
+     * The daemon's own ambient environment (normally `process.env`). Never
+     * mutated — every returned variable is copied into a fresh object.
+     */
+    ambient: NodeJS.ProcessEnv;
+    /**
+     * The selected runtime adapter's own declared requirements —
+     * `undefined` (no `environmentRequirements()` implementation on that
+     * adapter) means "platform baseline only," fail-closed.
+     */
+    requirements?: RuntimeEnvironmentRequirements;
+    /**
+     * This device's own operator-configured escape hatch for this one runtime
+     * (`DaemonConfig.runtimeEnvironment?.[adapterId]?.allow`) — merged in like
+     * any other allowlist entry, still subject to the hard deny below.
+     */
+    locallyAllowedNames?: readonly string[];
+    /**
+     * Test seam: which platform's extra base vars to include
+     * ({@link WINDOWS_BASE_ALLOWLIST} vs none) — defaults to `process.platform`
+     * so callers never have to think about it, while still letting a test
+     * exercise the win32 branch deterministically on any host OS.
+     */
+    platform?: NodeJS.Platform;
+}
+/**
+ * Build the environment one specific runtime's spawned child process should
+ * actually receive — a fresh object, never `options.ambient` itself and
+ * never mutated in place. See this module's own doc comment for the full
+ * allow/deny model.
+ */
+export declare function buildRuntimeEnv(options: BuildRuntimeEnvOptions): Record<string, string>;