harnery 0.9.0 → 0.11.0

package/dist/core/presence/relay-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-client.d.ts","sourceRoot":"","sources":["../../../src/core/presence/relay-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAwFH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAwBzD;AAED,sEAAsE;AACtE,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqKvE;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAMA"}

package/dist/core/presence/relay-client.js

@@ -0,0 +1,295 @@
+/**
+ * Relay client transport for cross-machine presence (ADR 0016, phase 2c).
+ *
+ * The hooks are short-lived processes, so a live WebSocket needs a home: a
+ * small per-repo-per-machine DAEMON that the hooks lazy-start
+ * (`ensureRelayDaemon`) and that exits itself when the machine goes idle.
+ * The daemon:
+ *
+ *   - derives the room credentials from the repo identity (root-commit SHA +
+ *     origin URL + optional committed `.harnery/presence-salt`)
+ *   - holds the socket open with auto-reconnect + jittered backoff
+ *   - watches `.harnery/active/` and publishes the encrypted presence blob on
+ *     change (debounced), plus a 60s keepalive so peers' staleness math works
+ *   - decrypts received peer frames and writes them to
+ *     `.harnery/presence/remote/<machine>.json`, where `readRemoteMachines`
+ *     merges them with the git-refs floor (freshest source per machine wins)
+ *   - exits after ~5 minutes with no live local sessions (hooks restart it
+ *     when sessions return), and exits if its pid file is superseded
+ *
+ * Everything fails silent; the git-refs transport is always the floor.
+ * Requires a global WebSocket (Bun, Node >= 21, Workers) — on older Nodes the
+ * daemon refuses to start and presence stays on git-refs.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, watch, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { resolveMachineLabel } from "../../lib/machine.js";
+import { presenceRelayUrl } from "../config.js";
+import { buildPresenceBlob } from "./blob.js";
+import { originUrl, rootCommitSha, sanitizeRefComponent } from "./git.js";
+import { computeSenderId, decryptPayload, deriveRoomCredentials, encryptPayload, parseRelayFrame, } from "./relay-protocol.js";
+const KEEPALIVE_MS = 60_000;
+const WATCH_DEBOUNCE_MS = 500;
+const IDLE_EXIT_MS = 5 * 60_000;
+const BACKOFF_MIN_MS = 1_000;
+const BACKOFF_MAX_MS = 60_000;
+function presenceDir(coordRoot) {
+    return join(coordRoot, ".harnery", "presence");
+}
+function remoteCacheDir(coordRoot) {
+    return join(presenceDir(coordRoot), "remote");
+}
+function pidFilePath(coordRoot) {
+    return join(presenceDir(coordRoot), "relay-daemon.json");
+}
+function logFilePath(coordRoot) {
+    return join(presenceDir(coordRoot), "relay-daemon.log");
+}
+function readPidRecord(coordRoot) {
+    try {
+        return JSON.parse(readFileSync(pidFilePath(coordRoot), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The committed rotatable room salt, when the repo minted one. */
+function readRoomSalt(coordRoot) {
+    try {
+        const s = readFileSync(join(coordRoot, ".harnery", "presence-salt"), "utf8").trim();
+        return s || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function atomicWriteJson(path, value) {
+    mkdirSync(join(path, ".."), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(value), "utf8");
+    renameSync(tmp, path);
+}
+/**
+ * Lazy-start the relay daemon for this repo if a relay is configured and no
+ * live daemon already owns the pid file. Called from the hook path — must
+ * return fast and never throw.
+ */
+export function ensureRelayDaemon(coordRoot) {
+    try {
+        const url = presenceRelayUrl(coordRoot);
+        if (!url)
+            return;
+        const rec = readPidRecord(coordRoot);
+        if (rec && rec.url === url && pidAlive(rec.pid))
+            return;
+        // Resolve the harn bin at the package root (works from src/ under Bun and
+        // dist/ under Node — both sit two levels below the root).
+        const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
+        if (!existsSync(harnBin))
+            return;
+        mkdirSync(presenceDir(coordRoot), { recursive: true });
+        const log = openSync(logFilePath(coordRoot), "a");
+        const child = spawn(harnBin, ["presence", "relay-daemon"], {
+            cwd: coordRoot,
+            detached: true,
+            stdio: ["ignore", log, log],
+            env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
+        });
+        child.unref();
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Foreground daemon loop (spawned detached by ensureRelayDaemon). */
+export async function runRelayDaemon(coordRoot) {
+    const url = presenceRelayUrl(coordRoot);
+    if (!url) {
+        console.error("relay-daemon: no relay configured (presence.relay)");
+        return 2;
+    }
+    if (typeof WebSocket === "undefined") {
+        console.error("relay-daemon: no global WebSocket in this runtime (need Bun or Node >= 21)");
+        return 2;
+    }
+    const sha = rootCommitSha(coordRoot);
+    const origin = originUrl(coordRoot);
+    if (!sha || !origin) {
+        console.error("relay-daemon: repo has no commits or no origin remote");
+        return 2;
+    }
+    // Take (or take over) the pid file. A superseded daemon notices and exits.
+    const myRecord = {
+        pid: process.pid,
+        url,
+        started_at: new Date().toISOString(),
+    };
+    atomicWriteJson(pidFilePath(coordRoot), myRecord);
+    const creds = await deriveRoomCredentials({
+        rootCommitSha: sha,
+        originUrl: origin,
+        salt: readRoomSalt(coordRoot),
+    });
+    const machine = sanitizeRefComponent(resolveMachineLabel());
+    const senderId = await computeSenderId(creds, machine);
+    const wsUrl = `${url.replace(/\/+$/, "")}/v1/room/${creds.roomId}`;
+    let ws = null;
+    let backoff = BACKOFF_MIN_MS;
+    let lastBasisHash = "";
+    let lastSentAt = 0;
+    let idleSince = null;
+    let shuttingDown = false;
+    const log = (msg) => {
+        console.log(`[${new Date().toISOString()}] ${msg}`);
+    };
+    const publishNow = async (force = false) => {
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            const { blob, basisHash, json } = buildPresenceBlob(coordRoot);
+            const keepaliveDue = Date.now() - lastSentAt >= KEEPALIVE_MS;
+            if (!force && basisHash === lastBasisHash && !keepaliveDue)
+                return;
+            const enc = await encryptPayload(creds, json);
+            ws.send(JSON.stringify({ t: "pub", sender: senderId, ...enc }));
+            lastBasisHash = basisHash;
+            lastSentAt = Date.now();
+            idleSince = blob.agents.length === 0 ? (idleSince ?? Date.now()) : null;
+        }
+        catch {
+            /* next trigger retries */
+        }
+    };
+    const handleFrame = async (raw) => {
+        const frame = parseRelayFrame(raw);
+        if (frame?.t !== "pub")
+            return;
+        if (frame.sender === senderId)
+            return; // our own warm-join echo
+        const pt = await decryptPayload(creds, frame);
+        if (!pt)
+            return;
+        let blob;
+        try {
+            blob = JSON.parse(pt);
+        }
+        catch {
+            return;
+        }
+        if (blob?.v !== 1 || typeof blob.machine !== "string")
+            return;
+        const m = sanitizeRefComponent(blob.machine);
+        if (m === machine)
+            return;
+        try {
+            atomicWriteJson(join(remoteCacheDir(coordRoot), `${m}.json`), blob);
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+    const connect = () => {
+        if (shuttingDown)
+            return;
+        try {
+            const sock = new WebSocket(wsUrl);
+            ws = sock;
+            sock.onopen = () => {
+                backoff = BACKOFF_MIN_MS;
+                log(`connected room=${creds.roomId.slice(0, 8)}… as ${machine}`);
+                void publishNow(true);
+            };
+            sock.onmessage = (ev) => {
+                void handleFrame(String(ev.data));
+            };
+            const scheduleReconnect = () => {
+                if (shuttingDown)
+                    return;
+                const jitter = Math.random() * backoff * 0.3;
+                const delay = Math.min(BACKOFF_MAX_MS, backoff) + jitter;
+                backoff = Math.min(BACKOFF_MAX_MS, backoff * 2);
+                setTimeout(connect, delay);
+            };
+            sock.onclose = scheduleReconnect;
+            sock.onerror = () => {
+                try {
+                    sock.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            };
+        }
+        catch {
+            setTimeout(connect, backoff);
+            backoff = Math.min(BACKOFF_MAX_MS, backoff * 2);
+        }
+    };
+    connect();
+    // Publish on heartbeat change (debounced).
+    let debounce = null;
+    const activeDir = join(coordRoot, ".harnery", "active");
+    mkdirSync(activeDir, { recursive: true });
+    try {
+        watch(activeDir, () => {
+            if (debounce)
+                clearTimeout(debounce);
+            debounce = setTimeout(() => void publishNow(), WATCH_DEBOUNCE_MS);
+        });
+    }
+    catch {
+        /* keepalive interval still covers publication */
+    }
+    // Keepalive + lifecycle checks.
+    const interval = setInterval(() => {
+        void publishNow();
+        // Superseded by a newer daemon → exit quietly.
+        const rec = readPidRecord(coordRoot);
+        if (!rec || rec.pid !== process.pid) {
+            log("pid file superseded; exiting");
+            shuttingDown = true;
+            clearInterval(interval);
+            try {
+                ws?.close();
+            }
+            catch {
+                /* ignore */
+            }
+            process.exit(0);
+        }
+        // Idle machine (no live sessions for a while) → exit; hooks restart us.
+        if (idleSince && Date.now() - idleSince > IDLE_EXIT_MS) {
+            log("no live sessions; idle exit");
+            shuttingDown = true;
+            clearInterval(interval);
+            try {
+                rmSync(pidFilePath(coordRoot), { force: true });
+                ws?.close();
+            }
+            catch {
+                /* ignore */
+            }
+            process.exit(0);
+        }
+    }, KEEPALIVE_MS);
+    // Never resolves in normal operation; exits happen above.
+    return await new Promise(() => { });
+}
+/** Daemon status for `presence peers`/doctor surfaces. */
+export function relayDaemonStatus(coordRoot) {
+    const rec = readPidRecord(coordRoot);
+    if (rec && pidAlive(rec.pid)) {
+        return { running: true, pid: rec.pid, url: rec.url, started_at: rec.started_at };
+    }
+    return { running: false };
+}

package/dist/core/presence/relay-protocol.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Relay protocol for cross-machine presence (ADR 0016, phase 2): the shared,
+ * host-agnostic logic both relay hosts (the Cloudflare Durable Objects worker
+ * and `harn relay serve`) and the client transport build on.
+ *
+ * Capability-based rooms: the room id and the E2E symmetric key are BOTH
+ * derived client-side via HKDF-SHA256 from (repo root-commit SHA, normalized
+ * origin URL, a rotatable salt). Anyone who can read the repo can derive them;
+ * nobody else can — including the relay operator, who sees only an opaque
+ * room id, opaque sender ids, and AES-GCM ciphertext. Rotating the salt
+ * rotates the room.
+ *
+ * The committed salt is NOT a secret and must never be treated as one: the
+ * derivation needs the root-commit SHA + origin URL too, which only
+ * repo-readers have. Repo access is the trust boundary (same as the git-refs
+ * transport).
+ *
+ * Wire format (JSON text frames over WebSocket):
+ *   client → relay:  { t: "pub", sender, iv, ct }        broadcast + cache
+ *   relay  → client: { t: "pub", sender, iv, ct }        live or warm-join replay
+ *   relay  → client: { t: "hello", peers }               on join (peer count)
+ * The relay never sees plaintext: `ct` is AES-GCM over the presence-blob JSON,
+ * `sender` is an HMAC-derived opaque id, `iv` is the per-message nonce.
+ *
+ * Uses WebCrypto only (globalThis.crypto.subtle) so the same module runs on
+ * Bun, Node ≥ 20, and Cloudflare Workers.
+ */
+/** Default derivation salt when a repo hasn't minted `.harnery/presence-salt`.
+ * Public by design (see module docs); committing a random per-repo salt just
+ * rotates the room away from anything derived before. */
+export declare const DEFAULT_ROOM_SALT = "harnery-presence-salt/v1";
+export interface RoomInputs {
+    /** SHA of the repo's root commit (`git rev-list --max-parents=0 HEAD`,
+     * first line). Stable for the repo's whole life. */
+    rootCommitSha: string;
+    /** The origin remote URL, any format — normalized internally so ssh and
+     * https clones of the same repo land in the same room. */
+    originUrl: string;
+    /** Rotatable room salt (default DEFAULT_ROOM_SALT). */
+    salt?: string;
+}
+export interface RoomCredentials {
+    /** Opaque 32-hex-char room id — the only room identity the relay sees. */
+    roomId: string;
+    /** AES-GCM-256 key for payload E2E encryption. Never leaves the client. */
+    key: CryptoKey;
+    /** Raw bytes for deriving per-machine opaque sender ids. */
+    senderKeyBytes: Uint8Array;
+}
+/**
+ * Normalize a git remote URL so every clone shape of the same repo derives
+ * the same room: `git@github.com:Org/Repo.git`, `ssh://git@github.com/org/repo`,
+ * and `https://github.com/org/repo.git` all → `github.com/org/repo`.
+ */
+export declare function normalizeOriginUrl(raw: string): string;
+/** Derive the room id, E2E key, and sender-id key from the repo identity. */
+export declare function deriveRoomCredentials(inputs: RoomInputs): Promise<RoomCredentials>;
+/** Opaque, stable per-machine sender id: HMAC(senderKey, machineLabel). The
+ * relay caches last-message-per-sender by this without learning the label. */
+export declare function computeSenderId(creds: RoomCredentials, machineLabel: string): Promise<string>;
+/** AES-GCM-encrypt a plaintext payload → { iv, ct } base64 pair. */
+export declare function encryptPayload(creds: RoomCredentials, plaintext: string): Promise<{
+    iv: string;
+    ct: string;
+}>;
+/** Decrypt an { iv, ct } pair. Returns null on any failure (wrong room key,
+ * tampered frame) — callers drop the frame silently. */
+export declare function decryptPayload(creds: RoomCredentials, frame: {
+    iv: string;
+    ct: string;
+}): Promise<string | null>;
+/** Client → relay and relay → client publication frame. */
+export interface PubFrame {
+    t: "pub";
+    /** Opaque sender id (computeSenderId). The relay keys its warm-join cache on this. */
+    sender: string;
+    iv: string;
+    ct: string;
+}
+/** Relay → client greeting on join. */
+export interface HelloFrame {
+    t: "hello";
+    /** Live sockets in the room at join time (including the joiner). */
+    peers: number;
+}
+export type RelayFrame = PubFrame | HelloFrame;
+/** Hard cap a relay enforces per text frame (ciphertext of a ~2KB blob is far
+ * smaller; anything bigger is abuse or a bug). */
+export declare const MAX_FRAME_BYTES: number;
+/** Parse + shape-validate an incoming relay frame. Null on anything off. */
+export declare function parseRelayFrame(raw: string): RelayFrame | null;
+/** Room ids are 32 lowercase hex chars; relays reject anything else. */
+export declare function isValidRoomId(roomId: string): boolean;
+//# sourceMappingURL=relay-protocol.d.ts.map

package/dist/core/presence/relay-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-protocol.d.ts","sourceRoot":"","sources":["../../../src/core/presence/relay-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH;;yDAEyD;AACzD,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,UAAU;IACzB;wDACoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB;8DAC0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,GAAG,EAAE,SAAS,CAAC;IACf,4DAA4D;IAC5D,cAAc,EAAE,UAAU,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiBtD;AAyBD,6EAA6E;AAC7E,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAgBxF;AAED;8EAC8E;AAC9E,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAeD,oEAAoE;AACpE,wBAAsB,cAAc,CAClC,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAQrC;AAED;wDACwD;AACxD,wBAAsB,cAAc,CAClC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxB;AAID,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,KAAK,CAAC;IACT,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,OAAO,CAAC;IACX,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE/C;kDACkD;AAClD,eAAO,MAAM,eAAe,QAAY,CAAC;AAEzC,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA6B9D;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/core/presence/relay-protocol.js

@@ -0,0 +1,169 @@
+/**
+ * Relay protocol for cross-machine presence (ADR 0016, phase 2): the shared,
+ * host-agnostic logic both relay hosts (the Cloudflare Durable Objects worker
+ * and `harn relay serve`) and the client transport build on.
+ *
+ * Capability-based rooms: the room id and the E2E symmetric key are BOTH
+ * derived client-side via HKDF-SHA256 from (repo root-commit SHA, normalized
+ * origin URL, a rotatable salt). Anyone who can read the repo can derive them;
+ * nobody else can — including the relay operator, who sees only an opaque
+ * room id, opaque sender ids, and AES-GCM ciphertext. Rotating the salt
+ * rotates the room.
+ *
+ * The committed salt is NOT a secret and must never be treated as one: the
+ * derivation needs the root-commit SHA + origin URL too, which only
+ * repo-readers have. Repo access is the trust boundary (same as the git-refs
+ * transport).
+ *
+ * Wire format (JSON text frames over WebSocket):
+ *   client → relay:  { t: "pub", sender, iv, ct }        broadcast + cache
+ *   relay  → client: { t: "pub", sender, iv, ct }        live or warm-join replay
+ *   relay  → client: { t: "hello", peers }               on join (peer count)
+ * The relay never sees plaintext: `ct` is AES-GCM over the presence-blob JSON,
+ * `sender` is an HMAC-derived opaque id, `iv` is the per-message nonce.
+ *
+ * Uses WebCrypto only (globalThis.crypto.subtle) so the same module runs on
+ * Bun, Node ≥ 20, and Cloudflare Workers.
+ */
+const ROOM_INFO = "harnery-presence/room-id/v1";
+const KEY_INFO = "harnery-presence/room-key/v1";
+const SENDER_INFO = "harnery-presence/sender-id/v1";
+const HKDF_SALT = "harnery-presence/hkdf-salt/v1";
+/** Default derivation salt when a repo hasn't minted `.harnery/presence-salt`.
+ * Public by design (see module docs); committing a random per-repo salt just
+ * rotates the room away from anything derived before. */
+export const DEFAULT_ROOM_SALT = "harnery-presence-salt/v1";
+/**
+ * Normalize a git remote URL so every clone shape of the same repo derives
+ * the same room: `git@github.com:Org/Repo.git`, `ssh://git@github.com/org/repo`,
+ * and `https://github.com/org/repo.git` all → `github.com/org/repo`.
+ */
+export function normalizeOriginUrl(raw) {
+    let s = raw.trim();
+    // scp-like syntax: [user@]host:path
+    const scp = /^(?:[^@/]+@)?([^:/]+):(?!\/\/)(.+)$/.exec(s);
+    if (scp) {
+        s = `${scp[1]}/${scp[2]}`;
+    }
+    else {
+        // URL syntax: strip scheme, then credentials.
+        s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+        s = s.replace(/^[^@/]+@/, "");
+    }
+    // Drop an explicit port, trailing slashes, trailing .git; lowercase.
+    // (Slashes first so `…/repo.git/` still sheds its .git suffix.)
+    s = s.replace(/^([^/:]+):\d+\//, "$1/");
+    s = s.replace(/\/+$/, "");
+    s = s.replace(/\.git$/i, "");
+    return s.toLowerCase();
+}
+async function hkdfBits(ikm, info, bits) {
+    const key = await crypto.subtle.importKey("raw", ikm, "HKDF", false, [
+        "deriveBits",
+    ]);
+    return crypto.subtle.deriveBits({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new TextEncoder().encode(HKDF_SALT),
+        info: new TextEncoder().encode(info),
+    }, key, bits);
+}
+function hex(buf) {
+    const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/** Derive the room id, E2E key, and sender-id key from the repo identity. */
+export async function deriveRoomCredentials(inputs) {
+    const ikm = new TextEncoder().encode([
+        inputs.rootCommitSha.trim().toLowerCase(),
+        normalizeOriginUrl(inputs.originUrl),
+        inputs.salt ?? DEFAULT_ROOM_SALT,
+    ].join("\n"));
+    const roomBits = await hkdfBits(ikm, ROOM_INFO, 128);
+    const keyBits = await hkdfBits(ikm, KEY_INFO, 256);
+    const senderBits = await hkdfBits(ikm, SENDER_INFO, 256);
+    const key = await crypto.subtle.importKey("raw", keyBits, { name: "AES-GCM" }, false, [
+        "encrypt",
+        "decrypt",
+    ]);
+    return { roomId: hex(roomBits), key, senderKeyBytes: new Uint8Array(senderBits) };
+}
+/** Opaque, stable per-machine sender id: HMAC(senderKey, machineLabel). The
+ * relay caches last-message-per-sender by this without learning the label. */
+export async function computeSenderId(creds, machineLabel) {
+    const hmacKey = await crypto.subtle.importKey("raw", creds.senderKeyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = await crypto.subtle.sign("HMAC", hmacKey, new TextEncoder().encode(machineLabel));
+    return hex(sig).slice(0, 32);
+}
+function toB64(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin);
+}
+function fromB64(s) {
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** AES-GCM-encrypt a plaintext payload → { iv, ct } base64 pair. */
+export async function encryptPayload(creds, plaintext) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, creds.key, new TextEncoder().encode(plaintext));
+    return { iv: toB64(iv), ct: toB64(new Uint8Array(ct)) };
+}
+/** Decrypt an { iv, ct } pair. Returns null on any failure (wrong room key,
+ * tampered frame) — callers drop the frame silently. */
+export async function decryptPayload(creds, frame) {
+    try {
+        const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromB64(frame.iv) }, creds.key, fromB64(frame.ct));
+        return new TextDecoder().decode(pt);
+    }
+    catch {
+        return null;
+    }
+}
+/** Hard cap a relay enforces per text frame (ciphertext of a ~2KB blob is far
+ * smaller; anything bigger is abuse or a bug). */
+export const MAX_FRAME_BYTES = 16 * 1024;
+/** Parse + shape-validate an incoming relay frame. Null on anything off. */
+export function parseRelayFrame(raw) {
+    if (raw.length > MAX_FRAME_BYTES)
+        return null;
+    let j;
+    try {
+        j = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!j || typeof j !== "object")
+        return null;
+    const f = j;
+    if (f.t === "pub") {
+        if (typeof f.sender !== "string" ||
+            f.sender.length === 0 ||
+            f.sender.length > 64 ||
+            typeof f.iv !== "string" ||
+            typeof f.ct !== "string" ||
+            f.iv.length > 64 ||
+            f.ct.length > MAX_FRAME_BYTES) {
+            return null;
+        }
+        return { t: "pub", sender: f.sender, iv: f.iv, ct: f.ct };
+    }
+    if (f.t === "hello") {
+        if (typeof f.peers !== "number")
+            return null;
+        return { t: "hello", peers: f.peers };
+    }
+    return null;
+}
+/** Room ids are 32 lowercase hex chars; relays reject anything else. */
+export function isValidRoomId(roomId) {
+    return /^[0-9a-f]{32}$/.test(roomId);
+}

package/dist/core/workflow/billing.d.ts

@@ -20,7 +20,7 @@ import type { HarnessName } from "./types.js";
 /** The env var each harness CLI reads as an API key (preferred over a stored
  * login when set). Shared with the child-env builder's subscription-only
  * scrub. */
-export declare const API_KEY_VARS: Record<HarnessName, string>;
+export declare const API_KEY_VARS: Record<string, string>;
 export type LoginState = "present" | "absent" | "unknown";
 export type BillingMode = 
 /** No API key exported; the child rides the stored (subscription) login. */

package/dist/core/workflow/billing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"billing.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/billing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;YAEY;AACZ,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAIpD,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,WAAW;AACrB,4EAA4E;AAC1E,cAAc;AAChB,6EAA6E;GAC3E,SAAS;AACX;yEACyE;GACvE,kBAAkB,CAAC;AAEvB,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,WAAW,CAAC;IACrB;gEAC4D;IAC5D,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,YAAY,CAAC;AAEnE,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,GAAE,OAAY,GAAG,YAAY,CAyCjF"}
+{"version":3,"file":"billing.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/billing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;YAEY;AACZ,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI/C,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,WAAW;AACrB,4EAA4E;AAC1E,cAAc;AAChB,6EAA6E;GAC3E,SAAS;AACX;yEACyE;GACvE,kBAAkB,CAAC;AAEvB,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,WAAW,CAAC;IACrB;gEAC4D;IAC5D,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,YAAY,CAAC;AAEnE,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,GAAE,OAAY,GAAG,YAAY,CA+CjF"}

package/dist/core/workflow/billing.js

@@ -31,7 +31,7 @@ export function probeBilling(harness, io = {}) {
     const env = io.env ?? process.env;
     const home = io.home ?? homedir();
     const keyVar = API_KEY_VARS[harness];
-    const envKey = Boolean(env[keyVar]?.trim());
+    const envKey = keyVar ? Boolean(env[keyVar]?.trim()) : false;
     let login;
     let apiKeyPresent = envKey;
     let apiKeySource = envKey ? keyVar : null;
@@ -56,6 +56,12 @@ export function probeBilling(harness, io = {}) {
             // presence or absence we can't prove.
             login = "unknown";
             break;
+        default:
+            // External adapters own their authentication. The generic engine must
+            // not guess credential locations or fail a plugin on a built-in-only
+            // heuristic.
+            login = "unknown";
+            break;
     }
     const mode = apiKeyPresent && login === "present"
         ? "api-key-override"

package/dist/core/workflow/engine.d.ts

@@ -17,5 +17,10 @@
  *     cost, duration, and child session id (the resume + web-UI substrate).
  */
 import type { EngineOpts, RunReport } from "./types.js";
+export declare class WorkflowRunError extends Error {
+    readonly runId: string;
+    readonly proofPath: string;
+    constructor(message: string, runId: string, proofPath: string, cause?: unknown);
+}
 export declare function runWorkflow(scriptPath: string, opts: EngineOpts): Promise<RunReport>;
 //# sourceMappingURL=engine.d.ts.map

package/dist/core/workflow/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,KAAK,EAEV,UAAU,EAEV,SAAS,EAIV,MAAM,YAAY,CAAC;AASpB,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAwR1F"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAeH,OAAO,KAAK,EAEV,UAAU,EAEV,SAAS,EAOV,MAAM,YAAY,CAAC;AAUpB,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAM/E;AAED,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAqa1F"}