hivehq 2.0.0

package/dist/src/server/preset-launch-support.js

@@ -0,0 +1,98 @@
+import { doesCapturedSessionExist } from './session-capture.js';
+const appendUniqueArgs = (prefix, args) => {
+    const seen = new Set(prefix);
+    return prefix.concat(args.filter((arg) => !seen.has(arg)));
+};
+const unquoteExecutable = (command) => command.trim().replace(/^"(.+)"$/, '$1');
+const isNodeExecutable = (command) => {
+    if (!command)
+        return false;
+    return /(?:^|[\\/])node(?:\.exe)?$/iu.test(unquoteExecutable(command));
+};
+const isCodexNpmEntrypoint = (arg) => {
+    if (!arg)
+        return false;
+    const normalized = arg.replace(/\\/gu, '/');
+    return /(?:^|\/)@openai\/codex\/bin\/codex\.js$/iu.test(normalized);
+};
+const isCodexPreset = (preset) => preset?.id === 'codex' ||
+    preset?.command === 'codex' ||
+    preset?.sessionIdCapture?.source === 'codex_session_jsonl_dir';
+const normalizeCodexNodeEntrypoint = (config, preset) => {
+    if (!isCodexPreset(preset) || !isNodeExecutable(config.command))
+        return config;
+    const args = config.args ?? [];
+    if (!isCodexNpmEntrypoint(args[0]))
+        return config;
+    return {
+        ...config,
+        args: args.slice(1),
+        command: preset?.command ?? 'codex',
+        interactiveCommand: isNodeExecutable(config.interactiveCommand)
+            ? 'codex'
+            : (config.interactiveCommand ?? 'codex'),
+    };
+};
+const getEffectiveCapture = (config, preset) => config.sessionIdCapture ?? preset?.sessionIdCapture ?? null;
+const getEffectiveResumeTemplate = (config, preset) => config.resumeArgsTemplate ?? preset?.resumeArgsTemplate ?? null;
+const withPresetYoloArgs = (config, preset) => {
+    const yoloArgs = preset?.yoloArgsTemplate;
+    if (!yoloArgs?.length)
+        return config;
+    const nextArgs = appendUniqueArgs(yoloArgs, config.args ?? []);
+    if (nextArgs.length === (config.args ?? []).length &&
+        nextArgs.every((arg, index) => arg === (config.args ?? [])[index])) {
+        return config;
+    }
+    return { ...config, args: nextArgs };
+};
+const getPresetYoloArgs = (preset) => preset?.yoloArgsTemplate ?? [];
+const hasResumeArgs = (args) => args.includes('--resume') ||
+    args.includes('-r') ||
+    args.includes('--continue') ||
+    args.includes('-c') ||
+    args.includes('--session') ||
+    args.includes('-s') ||
+    args[0] === 'resume';
+const shouldVerifySessionBeforeResume = (capture) => {
+    // Claude is a cheap project-dir existence check; OpenCode is a direct DB query.
+    // Codex/Gemini require broad session-store scans, so trust the persisted id and
+    // let the CLI fail fast if it is stale.
+    return capture?.source === 'claude_project_jsonl_dir' || capture?.source === 'opencode_session_db';
+};
+const supportsPresetResume = (capture) => capture?.source === 'claude_project_jsonl_dir' ||
+    capture?.source === 'codex_session_jsonl_dir' ||
+    capture?.source === 'gemini_session_json_dir' ||
+    capture?.source === 'opencode_session_db' ||
+    capture?.source === 'stdout_regex';
+export const withPresetResumeArgs = (config, preset, lastSessionId, cwd, discriminator, onInvalidSessionId) => {
+    const launchConfig = normalizeCodexNodeEntrypoint(config, preset);
+    let nextConfig = withPresetYoloArgs(launchConfig, preset);
+    const sessionIdCapture = getEffectiveCapture(nextConfig, preset);
+    if (sessionIdCapture && sessionIdCapture !== nextConfig.sessionIdCapture) {
+        nextConfig = { ...nextConfig, sessionIdCapture };
+    }
+    const resumeArgsTemplate = getEffectiveResumeTemplate(nextConfig, preset);
+    if (!lastSessionId || !resumeArgsTemplate)
+        return nextConfig;
+    if (sessionIdCapture && !supportsPresetResume(sessionIdCapture))
+        return nextConfig;
+    if (cwd &&
+        sessionIdCapture &&
+        shouldVerifySessionBeforeResume(sessionIdCapture) &&
+        !doesCapturedSessionExist(cwd, sessionIdCapture, lastSessionId, discriminator)) {
+        onInvalidSessionId?.(lastSessionId);
+        return nextConfig;
+    }
+    const args = launchConfig.args ?? [];
+    if (hasResumeArgs(args))
+        return nextConfig;
+    const yoloArgs = getPresetYoloArgs(preset);
+    const resumeArgs = resumeArgsTemplate.replace('{session_id}', lastSessionId).trim().split(/\s+/);
+    return {
+        ...nextConfig,
+        args: appendUniqueArgs(yoloArgs, resumeArgs.concat(args)),
+        resumeArgsTemplate,
+        resumedSessionId: lastSessionId,
+    };
+};

package/dist/src/server/pty-output-bus.d.ts

@@ -0,0 +1,8 @@
+type OutputListener = (chunk: string) => void;
+export interface PtyOutputBus {
+    clear: (runId: string) => void;
+    publish: (runId: string, chunk: string) => void;
+    subscribe: (runId: string, listener: OutputListener) => () => void;
+}
+export declare const createPtyOutputBus: () => PtyOutputBus;
+export {};

package/dist/src/server/pty-output-bus.js

@@ -0,0 +1,32 @@
+export const createPtyOutputBus = () => {
+    const listenersByRunId = new Map();
+    const getListeners = (runId) => {
+        let listeners = listenersByRunId.get(runId);
+        if (!listeners) {
+            listeners = new Set();
+            listenersByRunId.set(runId, listeners);
+        }
+        return listeners;
+    };
+    return {
+        clear(runId) {
+            listenersByRunId.delete(runId);
+        },
+        publish(runId, chunk) {
+            const listeners = listenersByRunId.get(runId);
+            if (!listeners)
+                return;
+            for (const listener of listeners)
+                listener(chunk);
+        },
+        subscribe(runId, listener) {
+            const listeners = getListeners(runId);
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0)
+                    listenersByRunId.delete(runId);
+            };
+        },
+    };
+};

package/dist/src/server/recovery-summary.d.ts

@@ -0,0 +1,15 @@
+import type { AgentSummary, WorkspaceSummary } from '../shared/types.js';
+import { type FeatureFlags } from './feature-flags.js';
+import type { RecoveryMessage } from './message-log-store.js';
+export declare const buildRecoverySummary: ({ agent, allTaskMessages, memoryDigest, messages, tasksContent, workers, workspace, flags, }: {
+    agent: AgentSummary;
+    allTaskMessages?: RecoveryMessage[];
+    memoryDigest?: string | null | undefined;
+    messages: RecoveryMessage[];
+    tasksContent: string;
+    workers: AgentSummary[];
+    workspace: WorkspaceSummary;
+    /** Live experimental flags — keep the recovered handover prompt consistent
+     *  with what a fresh startup would inject (workflow + team-sizing rules). */
+    flags?: FeatureFlags;
+}) => string;

package/dist/src/server/recovery-summary.js

@@ -0,0 +1,92 @@
+import { FEATURE_FLAGS_ALL_OFF } from './feature-flags.js';
+import { getHiveTeamRules } from './hive-team-guidance.js';
+import { wrapSystemMessage } from './system-message.js';
+import { TASKS_RELATIVE_PATH } from './tasks-file.js';
+const TASKS_HEAD_LIMIT = 1536;
+const formatUserInputs = (messages) => {
+    const userInputs = messages.filter((message) => message.type === 'user_input');
+    return userInputs.length > 0
+        ? userInputs.slice(-5).map((message) => `- user: ${message.text}`)
+        : ['- (no new user_input in the last hour)'];
+};
+const formatTaskEvents = (messages, agent) => {
+    const taskEvents = messages.filter((message) => {
+        if (agent.role === 'orchestrator') {
+            if (message.type === 'send')
+                return message.from === agent.id;
+            return message.type === 'report' || message.type === 'status';
+        }
+        if (message.type === 'send')
+            return message.to === agent.id || message.from === agent.id;
+        return (message.type === 'report' || message.type === 'status') && message.from === agent.id;
+    });
+    return taskEvents.length > 0
+        ? taskEvents.slice(-8).map((message) => {
+            if (message.type === 'send')
+                return `- send -> ${message.to}: ${message.text}`;
+            if (message.type === 'status')
+                return `- status <- ${message.from}: ${message.text}`;
+            const status = message.status ? ` [${message.status}]` : '';
+            return `- report <- ${message.from}${status}: ${message.text}`;
+        })
+        : ['- (no recent task events)'];
+};
+const getOpenTaskTargets = (agent, workers) => agent.role === 'orchestrator' ? workers : [agent];
+const formatOpenTasks = (messages, agent, workers) => {
+    const targetAgents = getOpenTaskTargets(agent, workers).filter((target) => target.role !== 'orchestrator');
+    const targetIds = new Set(targetAgents.map((target) => target.id));
+    const queues = new Map();
+    for (const message of messages) {
+        if (message.type === 'send' && targetIds.has(message.to)) {
+            const queue = queues.get(message.to) ?? [];
+            queue.push(message);
+            queues.set(message.to, queue);
+            continue;
+        }
+        if (message.type === 'report' && targetIds.has(message.from)) {
+            queues.get(message.from)?.shift();
+        }
+    }
+    const lines = [];
+    for (const target of targetAgents) {
+        const queue = queues.get(target.id) ?? [];
+        for (const task of queue.slice(-8)) {
+            lines.push(`- ${target.name}: ${task.text}`);
+        }
+        if (target.pendingTaskCount > queue.length) {
+            lines.push(`- ${target.name}: ${target.pendingTaskCount - queue.length} pending with no recoverable detail`);
+        }
+    }
+    return lines.length > 0 ? lines : ['- (no open tasks right now)'];
+};
+const formatWorkers = (workers) => {
+    if (workers.length === 0)
+        return ['- (no other workers)'];
+    return workers.map((worker) => `- ${worker.name} (${worker.role}, ${worker.status}, pending_task_count: ${worker.pendingTaskCount})`);
+};
+const getTaskSectionTitle = (agent) => agent.role === 'orchestrator' ? '## Tasks you dispatched' : '## Tasks recently sent to you';
+export const buildRecoverySummary = ({ agent, allTaskMessages, memoryDigest, messages, tasksContent, workers, workspace, flags = FEATURE_FLAGS_ALL_OFF, }) => wrapSystemMessage([
+    `You are ${agent.name} (${agent.role}) in workspace ${workspace.name}.`,
+    'Hive just restarted you and could not recover via native session resume. Here is the handover context.',
+    '',
+    '## Conversation with the user in the last hour',
+    ...formatUserInputs(messages),
+    '',
+    getTaskSectionTitle(agent),
+    ...formatTaskEvents(messages, agent),
+    '',
+    '## Open tasks',
+    ...formatOpenTasks(allTaskMessages ?? messages, agent, workers),
+    '',
+    `## Current ${TASKS_RELATIVE_PATH}`,
+    tasksContent.slice(0, TASKS_HEAD_LIMIT) || '(empty)',
+    '',
+    '## Active workers',
+    ...formatWorkers(workers),
+    '',
+    ...(memoryDigest ? ['## Hive memory digest', memoryDigest, ''] : []),
+    agent.role === 'orchestrator' ? '## Hive worker dispatch rules' : '## Hive worker boundaries',
+    ...getHiveTeamRules(agent, flags),
+    '',
+    'Continue from here. If unsure, ask the user.',
+].join('\n'));

package/dist/src/server/remote-audit-store.d.ts

@@ -0,0 +1,51 @@
+import type { Database } from 'better-sqlite3';
+export type RemoteAuditResult = 'ok' | 'rejected' | 'error';
+export type RemoteAuditAction = 'http' | 'ws_input' | 'ws_open' | 'session_open' | 'session_close' | 'revoke' | 'reject';
+export interface RemoteAuditEvent {
+    /** M1 session device id. Audit/revocation tag only — never a permission branch. */
+    deviceId?: string | null;
+    /** Coarse category (see RemoteAuditAction). */
+    action: RemoteAuditAction;
+    /** Whitelisted path for http/ws actions (`/api/...`, `/ws/...`); omit otherwise. */
+    endpoint?: string | null;
+    /** Affected workspace, when the action is scoped to one. */
+    workspaceId?: string | null;
+    result: RemoteAuditResult;
+    /** Required-in-spirit on a rejection: the concrete reason (off-whitelist, revoked, …). */
+    rejectReason?: string | null;
+    /** WS-input byte count. The full chunk is NEVER stored. */
+    byteCount?: number | null;
+    /** Short truncated preview of WS input. Bounded here, not by the caller. */
+    preview?: string | null;
+}
+export interface RemoteAuditRecord {
+    id: number;
+    deviceId: string | null;
+    ts: number;
+    workspaceId: string | null;
+    action: string;
+    endpoint: string | null;
+    result: string;
+    rejectReason: string | null;
+    byteCount: number | null;
+    preview: string | null;
+}
+export declare const AUDIT_PREVIEW_MAX = 120;
+export declare const createRemoteAuditStore: (db: Database) => {
+    /**
+     * Record an audit event. Returns immediately; the row is written on a
+     * later microtask. This is the ONLY method the tunnel calls on the hot path.
+     */
+    enqueue(event: RemoteAuditEvent, ts?: number): void;
+    /**
+     * Drain the buffer synchronously and await the pending write. Tests await
+     * this to assert rows deterministically; shutdown calls it to avoid losing
+     * the tail of the buffer. Idempotent when there's nothing pending.
+     */
+    flush(): Promise<void>;
+    /** Newest-first audit rows, capped at `limit`. Backs the Settings stream. */
+    list(limit?: number): RemoteAuditRecord[];
+    /** Newest-first rows for one device. Used by the device-detail view. */
+    listForDevice(deviceId: string, limit?: number): RemoteAuditRecord[];
+};
+export type RemoteAuditStore = ReturnType<typeof createRemoteAuditStore>;

package/dist/src/server/remote-audit-store.js

@@ -0,0 +1,108 @@
+// stdin previews are bounded so a paste of a megabyte of secrets can't end up in
+// the audit table. byte_count carries the real size; preview is just enough to
+// recognise the input in the Settings stream.
+export const AUDIT_PREVIEW_MAX = 120;
+const truncatePreview = (preview) => {
+    if (preview === null || preview === undefined)
+        return null;
+    if (preview.length <= AUDIT_PREVIEW_MAX)
+        return preview;
+    return `${preview.slice(0, AUDIT_PREVIEW_MAX)}…`;
+};
+export const createRemoteAuditStore = (db) => {
+    const insert = db.prepare(`INSERT INTO remote_audit
+       (remote_device_id, ts, workspace_id, action, endpoint, result, reject_reason, byte_count, preview)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const listStmt = db.prepare(`SELECT id, remote_device_id, ts, workspace_id, action, endpoint, result, reject_reason, byte_count, preview
+       FROM remote_audit
+      ORDER BY id DESC
+      LIMIT ?`);
+    const listForDeviceStmt = db.prepare(`SELECT id, remote_device_id, ts, workspace_id, action, endpoint, result, reject_reason, byte_count, preview
+       FROM remote_audit
+      WHERE remote_device_id = ?
+      ORDER BY id DESC
+      LIMIT ?`);
+    // Pending events buffered between flushes. enqueue() never touches SQLite
+    // directly — it appends here and arms a single microtask drain, so a burst of
+    // terminal keystrokes coalesces into one transaction instead of N.
+    const pending = [];
+    let flushScheduled = false;
+    let draining = null;
+    const writePending = () => {
+        if (pending.length === 0)
+            return;
+        const batch = pending.splice(0, pending.length);
+        const tx = db.transaction((events) => {
+            for (const e of events) {
+                insert.run(e.deviceId ?? null, e.ts, e.workspaceId ?? null, e.action, e.endpoint ?? null, e.result, e.rejectReason ?? null, typeof e.byteCount === 'number' ? e.byteCount : null, truncatePreview(e.preview));
+            }
+        });
+        tx(batch);
+    };
+    const scheduleFlush = () => {
+        if (flushScheduled)
+            return;
+        flushScheduled = true;
+        draining = new Promise((resolve) => {
+            // queueMicrotask keeps the write off the forwarding call stack while
+            // still landing before the event loop yields to I/O, so audit rows for a
+            // request are durable well before the response round-trips.
+            queueMicrotask(() => {
+                flushScheduled = false;
+                try {
+                    writePending();
+                }
+                catch {
+                    // A failed audit write must not crash the tunnel. Drop the batch and
+                    // keep forwarding; losing an audit row is strictly better than
+                    // dropping a user's terminal input.
+                }
+                resolve();
+            });
+        });
+    };
+    const mapRow = (row) => ({
+        id: row.id,
+        deviceId: row.remote_device_id,
+        ts: row.ts,
+        workspaceId: row.workspace_id,
+        action: row.action,
+        endpoint: row.endpoint,
+        result: row.result,
+        rejectReason: row.reject_reason,
+        byteCount: row.byte_count,
+        preview: row.preview,
+    });
+    return {
+        /**
+         * Record an audit event. Returns immediately; the row is written on a
+         * later microtask. This is the ONLY method the tunnel calls on the hot path.
+         */
+        enqueue(event, ts = Date.now()) {
+            pending.push({ ...event, ts });
+            scheduleFlush();
+        },
+        /**
+         * Drain the buffer synchronously and await the pending write. Tests await
+         * this to assert rows deterministically; shutdown calls it to avoid losing
+         * the tail of the buffer. Idempotent when there's nothing pending.
+         */
+        async flush() {
+            // Settle any already-scheduled drain first, then force-write whatever the
+            // caller enqueued after it was scheduled (or never scheduled at all).
+            if (draining)
+                await draining;
+            writePending();
+        },
+        /** Newest-first audit rows, capped at `limit`. Backs the Settings stream. */
+        list(limit = 100) {
+            writePending();
+            return listStmt.all(limit).map(mapRow);
+        },
+        /** Newest-first rows for one device. Used by the device-detail view. */
+        listForDevice(deviceId, limit = 100) {
+            writePending();
+            return listForDeviceStmt.all(deviceId, limit).map(mapRow);
+        },
+    };
+};

package/dist/src/server/remote-config-keys.d.ts

@@ -0,0 +1,17 @@
+export declare const REMOTE_GATEWAY_URL_KEY = "remote_gateway_url";
+export declare const REMOTE_DAEMON_TOKEN_KEY = "remote_daemon_token";
+export declare const REMOTE_DAEMON_ID_KEY = "remote_daemon_id";
+export declare const REMOTE_ENABLED_KEY = "remote_enabled";
+export declare const DEFAULT_GATEWAY_URL = "https://app.hivehq.dev";
+export interface RemoteAppStateReader {
+    get(key: string): {
+        value: string | null;
+    } | undefined;
+}
+export interface RemoteConfigSource {
+    isEnabled(): boolean;
+    getGatewayUrl(): string | null;
+    getDaemonToken(): string | null;
+    getDaemonId(): string | null;
+}
+export declare const createRemoteConfigSource: (store: RemoteAppStateReader) => RemoteConfigSource;

package/dist/src/server/remote-config-keys.js

@@ -0,0 +1,27 @@
+// Remote-access config lives in the existing app_state KV. These are the
+// canonical key literals — the single source of truth for BOTH sides of the
+// feature: `hive remote login/logout` (src/cli/hive-remote.ts) writes them, and
+// the daemon-side tunnel reads them. The CLI re-exports these so there is one
+// definition, not two that can drift (a rename on only one side would silently
+// stop login from reaching the tunnel).
+//
+// snake_case to match the existing app_state keys (active_workspace_id, …).
+export const REMOTE_GATEWAY_URL_KEY = 'remote_gateway_url';
+export const REMOTE_DAEMON_TOKEN_KEY = 'remote_daemon_token';
+export const REMOTE_DAEMON_ID_KEY = 'remote_daemon_id';
+export const REMOTE_ENABLED_KEY = 'remote_enabled';
+export const DEFAULT_GATEWAY_URL = 'https://app.hivehq.dev';
+// remote_enabled is ON only when it is exactly the string 'true'. Everything
+// else — absent, '', 'false', '1', 'yes' — is OFF. This is invariant 4 (off ==
+// zero behavior change): a truthy check would let a stray value silently arm
+// the outbound tunnel, so the test pins the exact-string semantics.
+const ENABLED_VALUE = 'true';
+export const createRemoteConfigSource = (store) => {
+    const read = (key) => store.get(key)?.value ?? null;
+    return {
+        isEnabled: () => read(REMOTE_ENABLED_KEY) === ENABLED_VALUE,
+        getGatewayUrl: () => read(REMOTE_GATEWAY_URL_KEY),
+        getDaemonToken: () => read(REMOTE_DAEMON_TOKEN_KEY),
+        getDaemonId: () => read(REMOTE_DAEMON_ID_KEY),
+    };
+};

package/dist/src/server/remote-control-constants.d.ts

@@ -0,0 +1,30 @@
+export declare const GW_CONTROL_PREFIX = "\0gw:";
+export declare const RelayCloseCode: {
+    readonly Normal: 1000;
+    readonly ProtocolError: 4400;
+    readonly Unauthorized: 4401;
+    readonly Forbidden: 4403;
+    readonly DaemonOffline: 4404;
+    readonly Replaced: 4409;
+    readonly Revoked: 4410;
+    readonly InternalError: 4500;
+};
+export type RelayCloseCode = (typeof RelayCloseCode)[keyof typeof RelayCloseCode];
+export type GatewayControl = {
+    t: 'peer-online';
+    role: 'daemon' | 'device' | 'pair';
+    jti?: string;
+} | {
+    t: 'peer-offline';
+    role: 'daemon' | 'device' | 'pair';
+} | {
+    t: 'revoked';
+    reason: string;
+} | {
+    t: 'error';
+    code: number;
+    message: string;
+};
+export declare const HB_PING = "hb:ping";
+export declare const HB_PONG = "hb:pong";
+export declare const isAuthFatalCloseCode: (code: number) => boolean;

package/dist/src/server/remote-control-constants.js

@@ -0,0 +1,29 @@
+// Daemon-side re-declaration of the gateway's control-band wire contract.
+//
+// The gateway lives in gateway/src/relay-do.ts — a separate Cloudflare-Workers package that is NOT
+// import-reachable from src/ (importing it would drag in cloudflare:workers). So the daemon mirrors
+// the few values it has to agree on, and tests/unit/remote-control-constants.test.ts pins each one
+// to the literal gateway value so the wire format can never silently drift between the two sides.
+// Control-frame sentinel. The gateway prefixes every control message (peer presence, revocation)
+// with this so it can never be confused with an opaque binary E2E frame. relay-do.ts:29.
+export const GW_CONTROL_PREFIX = '\x00gw:';
+// WebSocket close codes (4xxx app range). relay-do.ts:32-41.
+export const RelayCloseCode = {
+    Normal: 1000,
+    ProtocolError: 4400,
+    Unauthorized: 4401,
+    Forbidden: 4403,
+    DaemonOffline: 4404,
+    Replaced: 4409,
+    Revoked: 4410,
+    InternalError: 4500,
+};
+// Idle keepalive: the daemon SENDS this app-level string and the DO auto-replies HB_PONG WITHOUT
+// waking (setWebSocketAutoResponse, relay-do.ts:144). A protocol-level ws.ping() would wake the DO
+// and burn duration — the heartbeat MUST be this string, never ws.ping().
+export const HB_PING = 'hb:ping';
+export const HB_PONG = 'hb:pong';
+// Only these two close codes are authoritative credential death: the daemon must LATCH (stop
+// retrying until refresh() re-reads config). Every other close — including 4404 DaemonOffline,
+// 4409 Replaced, and the transport 1006 — is transient and backs off + retries.
+export const isAuthFatalCloseCode = (code) => code === RelayCloseCode.Unauthorized || code === RelayCloseCode.Revoked;

package/dist/src/server/remote-device-session.d.ts

@@ -0,0 +1,40 @@
+import type { Direction } from '../shared/remote-crypto.js';
+export interface DeviceSession {
+    deviceId: string;
+    /**
+     * 32-byte directional ROOT keys from M1 deriveDaemonSession. M6.1: these are ROOTS — the bridge
+     * derives the per-connection AEAD keys from them via deriveConnectionKeys + the bilateral connection
+     * salts, and seals/opens ONLY under those connKeys. These bytes are NEVER passed to sealNext/openNext
+     * directly; that is what makes resetting seq to 0 per connection safe (the AEAD key is fresh per
+     * connection even though the root is persisted/reused).
+     */
+    keys: {
+        d2p: Uint8Array;
+        p2d: Uint8Array;
+    };
+}
+export interface DeviceSessionProvider {
+    /**
+     * null => unknown / revoked / no established session. The tunnel resets the stream and audits
+     * 'no_session'; it never bridges a frame for a device it has no key for.
+     */
+    get(deviceId: string): DeviceSession | null;
+    /**
+     * Every established session. Used ONLY to resolve which device a CHANNEL_STREAM_ID Hello came
+     * from: the relay does not tag the source device, so the daemon trial-opens the Hello against
+     * each candidate's p2d key until one authenticates (AEAD makes a wrong key fail cleanly). After
+     * the Hello opens, the daemon binds (deviceId, streamId)->device and never trial-opens that
+     * stream again. deviceId is therefore only ever the result of a successful open (invariant 5).
+     */
+    candidates(): DeviceSession[];
+}
+export declare const DAEMON_OPEN_DIRECTION: Direction;
+export declare const DAEMON_SEAL_DIRECTION: Direction;
+export declare class InMemoryDeviceSessionProvider implements DeviceSessionProvider {
+    private readonly sessions;
+    set(session: DeviceSession): void;
+    /** Models a revoke: the key is gone, so the next frame for this device fails 'no_session'. */
+    remove(deviceId: string): void;
+    get(deviceId: string): DeviceSession | null;
+    candidates(): DeviceSession[];
+}

package/dist/src/server/remote-device-session.js

@@ -0,0 +1,22 @@
+// Daemon directions — the mirror of the device's. Exported so the tunnel, the bridge and the tests
+// all agree on ONE source of truth for which key opens/seals which way.
+//   - the daemon OPENS inbound phone→daemon frames with p2d
+//   - the daemon SEALS outbound daemon→phone frames with d2p
+export const DAEMON_OPEN_DIRECTION = 'p2d';
+export const DAEMON_SEAL_DIRECTION = 'd2p';
+export class InMemoryDeviceSessionProvider {
+    sessions = new Map();
+    set(session) {
+        this.sessions.set(session.deviceId, session);
+    }
+    /** Models a revoke: the key is gone, so the next frame for this device fails 'no_session'. */
+    remove(deviceId) {
+        this.sessions.delete(deviceId);
+    }
+    get(deviceId) {
+        return this.sessions.get(deviceId) ?? null;
+    }
+    candidates() {
+        return [...this.sessions.values()];
+    }
+}

package/dist/src/server/remote-device-store.d.ts

@@ -0,0 +1,36 @@
+import type { Database } from 'better-sqlite3';
+import type { DeviceSession, DeviceSessionProvider } from './remote-device-session.js';
+export interface RemoteDeviceRecord {
+    id: string;
+    name: string;
+    createdAt: number;
+    lastActive: number | null;
+    revokedAt: number | null;
+}
+export interface PersistDeviceInput {
+    id: string;
+    name: string;
+    /** The M3 DeviceSession.keys — a stored secret. */
+    keys: {
+        d2p: Uint8Array;
+        p2d: Uint8Array;
+    };
+    devicePublicKey: Uint8Array;
+}
+export interface RemoteDeviceStore {
+    /** TRUST-ROOT write. ONLY remote-pairing.confirmPairing calls this, ONLY on desktop confirm. */
+    insert(input: PersistDeviceInput, now?: number): RemoteDeviceRecord;
+    /** Provider read path (returns key material). null if absent OR revoked. INTERNAL. */
+    getLiveSession(deviceId: string): DeviceSession | null;
+    /** Active (non-revoked) sessions only — backs DeviceSessionProvider.candidates(). */
+    liveSessions(): DeviceSession[];
+    /** Device-management read path — metadata ONLY, no keys. Newest first. */
+    list(includeRevoked?: boolean): RemoteDeviceRecord[];
+    get(deviceId: string): RemoteDeviceRecord | null;
+    /** Local half of the revocation closed loop. Idempotent; false if unknown / already revoked. */
+    revoke(deviceId: string, now?: number): boolean;
+    /** Best-effort last_active bump. Never resurrects a revoked row. */
+    touchActive(deviceId: string, now?: number): void;
+}
+export declare const createRemoteDeviceStore: (db: Database) => RemoteDeviceStore;
+export declare const createPersistentDeviceSessionProvider: (store: RemoteDeviceStore) => DeviceSessionProvider;