amalgm 0.1.159 → 0.1.160

package/lib/shared-realtime-tunnel.js

@@ -26,6 +26,7 @@ function createSharedRealtimeTunnel({
   const mutationInflight = new Map();
   const promotionInflight = new Map();
   const attachmentInflight = new Map();
+  const privateEnsureInflight = new Map();
   const joinInflight = new Map();
   const inboundChains = new Map();
 
@@ -40,6 +41,31 @@ function createSharedRealtimeTunnel({
   let attachmentRetryTimer = null;
   let localFailures = 0;
 
+  async function ensurePrivateCookieResource() {
+    if (!enabled || privateEnsureInflight.size > 0) return;
+    try {
+      const bootstrap = await localStateJson('GET', '/browser/cookie-jar/cloud/bootstrap');
+      if (!bootstrap?.enabled || !bootstrap.resourceId) return;
+      const requestId = `private_${crypto.randomBytes(12).toString('hex')}`;
+      if (!sendLarge({
+        type: 'private.resource.ensure',
+        request_id: requestId,
+        resource_id: bootstrap.resourceId,
+        contract: bootstrap.contract,
+        schema_version: bootstrap.schemaVersion,
+        snapshot_b64: bootstrap.snapshotBase64,
+        snapshot_checksum: bootstrap.snapshotChecksum,
+        snapshot_bytes: bootstrap.snapshotBytes,
+      })) {
+        scheduleMutationDrain(RETRY_MS);
+        return;
+      }
+      privateEnsureInflight.set(requestId, bootstrap.resourceId);
+    } catch (error) {
+      warn(`private cookie bootstrap unavailable: ${error?.message || error}`);
+    }
+  }
+
   function localStateJson(method, requestPath, body) {
     const payload = body === undefined ? null : Buffer.from(JSON.stringify(body));
     return new Promise((resolve, reject) => {
@@ -323,6 +349,7 @@ function createSharedRealtimeTunnel({
   function startPump() {
     if (!enabled) return;
     startWakeStream();
+    void ensurePrivateCookieResource();
     void joinReplicas();
     scheduleAttachmentDrain();
     schedulePromotionDrain();
@@ -375,6 +402,28 @@ function createSharedRealtimeTunnel({
     });
   }
 
+  function handlePrivateReady(frame) {
+    const resourceId = privateEnsureInflight.get(frame.request_id);
+    if (!resourceId || resourceId !== frame.resource_id) return;
+    void localStateJson('POST', '/browser/cookie-jar/cloud/install', {
+      resourceId: frame.resource_id,
+      authorityEpoch: frame.authority_epoch,
+      headVersion: frame.head_version,
+      snapshotVersion: frame.snapshot_version,
+      snapshotChecksum: frame.snapshot_checksum,
+      snapshotBase64: frame.snapshot_b64,
+      contract: frame.contract,
+      schemaVersion: frame.schema_version,
+    }).then(() => {
+      privateEnsureInflight.delete(frame.request_id);
+      void joinReplicas();
+      scheduleMutationDrain();
+    }).catch((error) => {
+      warn(`private cookie snapshot was not installed: ${error?.message || error}`);
+      setTimeout(() => enabled && handlePrivateReady(frame), RETRY_MS).unref?.();
+    });
+  }
+
   function handleAck(frame) {
     const identity = mutationInflight.get(frame.request_id) || {
       resourceId: frame.resource_id,
@@ -396,6 +445,15 @@ function createSharedRealtimeTunnel({
   }
 
   function handleError(frame) {
+    const privateResource = privateEnsureInflight.get(frame.request_id);
+    if (privateResource) {
+      privateEnsureInflight.delete(frame.request_id);
+      warn(`private cookie bootstrap failed for ${privateResource}: ${frame.code || 'shared_error'}: ${frame.message || ''}`);
+      if (frame.retryable !== false) {
+        setTimeout(() => enabled && void ensurePrivateCookieResource(), RETRY_MS).unref?.();
+      }
+      return;
+    }
     const joinedResource = joinInflight.get(frame.request_id);
     if (joinedResource) {
       joinInflight.delete(frame.request_id);
@@ -505,6 +563,9 @@ function createSharedRealtimeTunnel({
           schemaVersion: frame.schema_version,
         }).catch(() => {});
         return true;
+      case 'private.resource.ready':
+        handlePrivateReady(frame);
+        return true;
       default:
         return false;
     }
@@ -524,6 +585,7 @@ function createSharedRealtimeTunnel({
     mutationInflight.clear();
     promotionInflight.clear();
     attachmentInflight.clear();
+    privateEnsureInflight.clear();
     joinInflight.clear();
     inboundChains.clear();
     if (wakeRequest) wakeRequest.destroy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.159",
+  "version": "0.1.160",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/browser/cookie-jar.js

@@ -23,8 +23,12 @@ const {
   COOKIE_SOURCE_BUNDLE_ID,
   DEFAULT_COOKIE_SOURCE_PROFILE_ID,
 } = require('./cookie-source');
+const crypto = require('crypto');
 
 const COOKIE_JAR_SCHEMA_VERSION = 1;
+const COOKIE_CLOUD_CONTRACT = 'browser-cookie-jar@1';
+const COOKIE_CLOUD_RESOURCE = 'browser-cookie-jar';
+const COOKIE_CLOUD_PATH = 'amalgm://browser-cookie-jar/default';
 const MAX_MUTATIONS_PER_MERGE = 10_000;
 const MAX_TOMBSTONES = 4_096;
 const DEFAULT_EXCLUDED_HOST_SUFFIXES = [
@@ -224,6 +228,16 @@ function publicSnapshot(jar) {
   };
 }
 
+function cloudSnapshot(jar = loadInternalCookieJar()) {
+  return {
+    schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
+    version: jar.version,
+    updatedAt: nowIso(),
+    records: [...jar.records.values()].sort((a, b) => a.key.localeCompare(b.key)),
+    tombstones: [...jar.tombstones.values()].sort((a, b) => a.key.localeCompare(b.key)),
+  };
+}
+
 function readCookieJar() {
   return publicSnapshot(loadInternalCookieJar());
 }
@@ -264,7 +278,7 @@ function deleteKeyFor(input) {
   return cookieKey(input);
 }
 
-function mergeCookieJar(input = {}) {
+function mergeCookieJarMaterialized(input = {}) {
   const sourceId = cleanSourceId(input.sourceId);
   const extraHosts = Array.isArray(input.excludeHosts) ? input.excludeHosts : [];
   const upserts = Array.isArray(input.upserts) ? input.upserts : [];
@@ -275,7 +289,7 @@ function mergeCookieJar(input = {}) {
 
   let jar = loadInternalCookieJar();
   const nextRevision = jar.version + 1;
-  const changedAt = nowIso();
+  const changedAt = String(input.changedAt || nowIso());
   let changed = false;
 
   for (const inputCookie of upserts) {
@@ -319,6 +333,344 @@ function mergeCookieJar(input = {}) {
   return publicSnapshot(persistCookieJar(jar));
 }
 
+function privateCookieResourceId(forUserId) {
+  const clean = String(forUserId || '').trim();
+  if (!clean) return null;
+  const digest = crypto
+    .createHash('sha256')
+    .update(`private-user:${clean}:${COOKIE_CLOUD_CONTRACT}`)
+    .digest('base64url')
+    .slice(0, 32);
+  return `pvr_${digest}`;
+}
+
+function cookieCloudReplica(options = {}) {
+  const { machineId, userId } = require('../workspace/identity');
+  const ownerUserId = userId();
+  const resourceId = privateCookieResourceId(ownerUserId);
+  if (!resourceId) return null;
+  const database = options.database || require('../state/db').openLocalDb();
+  const { getReplicaByResourceId, registerReplica } = require('../state/replicas');
+  const existing = getReplicaByResourceId(resourceId, { database });
+  if (existing) return { ...existing, deviceId: machineId(), ownerUserId };
+  const registered = registerReplica({
+    resourceId,
+    localResource: COOKIE_CLOUD_RESOURCE,
+    localPath: COOKIE_CLOUD_PATH,
+    contract: COOKIE_CLOUD_CONTRACT,
+    schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
+    authorityEpoch: 1,
+    appliedVersion: 0,
+    snapshotVersion: 0,
+  }, { database });
+  return { ...registered.replica, deviceId: machineId(), ownerUserId };
+}
+
+function operationForUpsert(inputCookie, sourceId, extraHosts, changedAt) {
+  const cookie = normalizeJarCookie(inputCookie);
+  if (!validCookie(cookie, extraHosts)) return null;
+  if (isExpiredCookie(cookie)) {
+    return {
+      kind: 'cookie.delete',
+      key: cookieKey(cookie),
+      sourceId,
+      changedAt,
+    };
+  }
+  return {
+    kind: 'cookie.upsert',
+    key: cookieKey(cookie),
+    cookie,
+    sourceId,
+    changedAt,
+  };
+}
+
+function operationForDelete(input, sourceId, extraHosts, changedAt) {
+  if (input && typeof input === 'object' && hostIsExcluded(input.domain, extraHosts)) return null;
+  const key = deleteKeyFor(input);
+  if (!key) return null;
+  return { kind: 'cookie.delete', key, sourceId, changedAt };
+}
+
+function operationChangesJar(operation, snapshot = readCookieJar()) {
+  if (!operation) return false;
+  if (operation.kind === 'cookie.upsert') {
+    const current = (snapshot.cookies || []).find((cookie) => cookieKey(cookie) === operation.key);
+    return !current || cookieFingerprint(current) !== cookieFingerprint(operation.cookie);
+  }
+  return (snapshot.cookies || []).some((cookie) => cookieKey(cookie) === operation.key)
+    || !(snapshot.tombstones || []).some((item) => item.key === operation.key);
+}
+
+function materializeCookieOperation(operation) {
+  if (operation.kind === 'cookie.upsert') {
+    return mergeCookieJarMaterialized({
+      sourceId: operation.sourceId,
+      upserts: [operation.cookie],
+      changedAt: operation.changedAt,
+    });
+  }
+  if (operation.kind === 'cookie.delete') {
+    return mergeCookieJarMaterialized({
+      sourceId: operation.sourceId,
+      deletes: [operation.key],
+      changedAt: operation.changedAt,
+    });
+  }
+  throw new Error(`Unsupported ${COOKIE_CLOUD_CONTRACT} operation ${JSON.stringify(operation.kind)}`);
+}
+
+function cookieEvent(operation, mutationId) {
+  return {
+    resource: COOKIE_CLOUD_RESOURCE,
+    op: operation.kind === 'cookie.delete' ? 'delete' : 'update',
+    id: crypto.createHash('sha256').update(operation.key).digest('hex').slice(0, 24),
+    value: { protected: true, kind: operation.kind },
+    source: `browser-cookie-jar:${operation.sourceId}`,
+    clientMutationId: mutationId,
+  };
+}
+
+function commitCookieOperation(operation, replica = cookieCloudReplica(), options = {}) {
+  if (!replica) return materializeCookieOperation(operation);
+  const mutationId = options.mutationId || `mut_${crypto.randomBytes(18).toString('base64url')}`;
+  const database = options.database || require('../state/db').openLocalDb();
+  let snapshot;
+  require('../state/mutations').commitLocalMutation({
+    channelId: `resource:${replica.resourceId}`,
+    localResource: COOKIE_CLOUD_RESOURCE,
+    cloudResourceId: replica.resourceId,
+    mutationId,
+    deviceId: replica.deviceId,
+    authorityEpoch: replica.authorityEpoch,
+    baseCloudVersion: replica.appliedVersion,
+    contract: COOKIE_CLOUD_CONTRACT,
+    schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
+    operationKind: operation.kind,
+    operation,
+  }, {
+    database,
+    materialize() {
+      snapshot = materializeCookieOperation(operation);
+    },
+    event: cookieEvent(operation, mutationId),
+  });
+  return snapshot || readCookieJar();
+}
+
+function mergeCookieJar(input = {}) {
+  const replica = cookieCloudReplica();
+  if (!replica) return mergeCookieJarMaterialized(input);
+  const sourceId = cleanSourceId(input.sourceId);
+  const extraHosts = Array.isArray(input.excludeHosts) ? input.excludeHosts : [];
+  const upserts = Array.isArray(input.upserts) ? input.upserts : [];
+  const deletes = Array.isArray(input.deletes) ? input.deletes : [];
+  if (upserts.length + deletes.length > MAX_MUTATIONS_PER_MERGE) {
+    throw new Error(`Cookie mutation batch exceeds ${MAX_MUTATIONS_PER_MERGE}`);
+  }
+
+  let snapshot = readCookieJar();
+  for (const inputCookie of upserts) {
+    const operation = operationForUpsert(inputCookie, sourceId, extraHosts, nowIso());
+    if (!operationChangesJar(operation, snapshot)) continue;
+    snapshot = commitCookieOperation(operation, replica);
+  }
+  for (const deletion of deletes) {
+    const operation = operationForDelete(deletion, sourceId, extraHosts, nowIso());
+    if (!operationChangesJar(operation, snapshot)) continue;
+    snapshot = commitCookieOperation(operation, replica);
+  }
+  return snapshot;
+}
+
+function normalizeCloudSnapshot(input) {
+  if (!input || input.schemaVersion !== COOKIE_JAR_SCHEMA_VERSION) {
+    throw new Error(`Unsupported ${COOKIE_CLOUD_CONTRACT} snapshot`);
+  }
+  const inputRecords = Array.isArray(input.records) ? input.records : [];
+  const inputTombstones = Array.isArray(input.tombstones) ? input.tombstones : [];
+  if (inputRecords.length + inputTombstones.length > MAX_MUTATIONS_PER_MERGE + MAX_TOMBSTONES) {
+    throw new Error('Cookie cloud snapshot is too large');
+  }
+  const records = new Map();
+  const tombstones = new Map();
+  for (const item of inputRecords) {
+    const cookie = normalizeJarCookie(item?.cookie || {});
+    if (!validCookie(cookie)) continue;
+    const key = cookieKey(cookie);
+    if (item?.key && item.key !== key) throw new Error('Cookie cloud snapshot key mismatch');
+    records.set(key, {
+      key,
+      cookie,
+      revision: Math.max(0, Number(item?.revision) || 0),
+      sourceId: cleanSourceId(item?.sourceId),
+      updatedAt: String(item?.updatedAt || input.updatedAt || nowIso()),
+    });
+  }
+  for (const item of inputTombstones) {
+    const key = String(item?.key || '');
+    if (!key) continue;
+    tombstones.set(key, {
+      key,
+      revision: Math.max(0, Number(item?.revision) || 0),
+      sourceId: cleanSourceId(item?.sourceId),
+      deletedAt: String(item?.deletedAt || input.updatedAt || nowIso()),
+    });
+  }
+  for (const [key, record] of records) {
+    const tombstone = tombstones.get(key);
+    if (!tombstone) continue;
+    if (tombstone.deletedAt >= record.updatedAt) records.delete(key);
+    else tombstones.delete(key);
+  }
+  return {
+    schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
+    version: Math.max(0, Number(input.version) || 0),
+    records,
+    tombstones: pruneTombstones(tombstones),
+  };
+}
+
+function persistCloudSnapshot(input) {
+  const normalized = normalizeCloudSnapshot(input);
+  return persistCookieJar({
+    exists: true,
+    version: normalized.version,
+    bundle: null,
+    records: normalized.records,
+    tombstones: normalized.tombstones,
+    migratedFromLegacy: false,
+  });
+}
+
+function timestampForEntry(record, tombstone) {
+  return String(record?.updatedAt || tombstone?.deletedAt || '');
+}
+
+function localBootstrapOperations(local, remote, pendingKeys) {
+  const operations = [];
+  const keys = new Set([...local.records.keys(), ...local.tombstones.keys()]);
+  for (const key of keys) {
+    if (pendingKeys.has(key)) continue;
+    const localRecord = local.records.get(key);
+    const localTombstone = local.tombstones.get(key);
+    const remoteRecord = remote.records.get(key);
+    const remoteTombstone = remote.tombstones.get(key);
+    const localTime = timestampForEntry(localRecord, localTombstone);
+    const remoteTime = timestampForEntry(remoteRecord, remoteTombstone);
+    if (!localTime || localTime <= remoteTime) continue;
+    if (localRecord) {
+      operations.push({
+        kind: 'cookie.upsert',
+        key,
+        cookie: localRecord.cookie,
+        sourceId: `${localRecord.sourceId}:bootstrap`,
+        changedAt: localRecord.updatedAt,
+      });
+    } else if (localTombstone) {
+      operations.push({
+        kind: 'cookie.delete',
+        key,
+        sourceId: `${localTombstone.sourceId}:bootstrap`,
+        changedAt: localTombstone.deletedAt,
+      });
+    }
+  }
+  return operations;
+}
+
+function getCookieCloudBootstrap(options = {}) {
+  const replica = cookieCloudReplica(options);
+  if (!replica) return { enabled: false, reason: 'runtime is not enrolled to a user' };
+  const bytes = Buffer.from(JSON.stringify(cloudSnapshot()), 'utf8');
+  return {
+    enabled: true,
+    resourceId: replica.resourceId,
+    contract: COOKIE_CLOUD_CONTRACT,
+    schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
+    authorityEpoch: replica.authorityEpoch,
+    appliedVersion: replica.appliedVersion,
+    snapshotBase64: bytes.toString('base64'),
+    snapshotBytes: bytes.length,
+    snapshotChecksum: crypto.createHash('sha256').update(bytes).digest('hex'),
+  };
+}
+
+function installCookieCloudBootstrap(input = {}, options = {}) {
+  const database = options.database || require('../state/db').openLocalDb();
+  const replica = cookieCloudReplica({ database });
+  if (!replica || input.resourceId !== replica.resourceId) {
+    throw new Error('Private cookie resource does not belong to this runtime user');
+  }
+  if (input.contract !== COOKIE_CLOUD_CONTRACT || Number(input.schemaVersion) !== COOKIE_JAR_SCHEMA_VERSION) {
+    throw new Error('Private cookie resource contract changed');
+  }
+  const bytes = Buffer.from(String(input.snapshotBase64 || ''), 'base64');
+  const checksum = crypto.createHash('sha256').update(bytes).digest('hex');
+  if (checksum !== input.snapshotChecksum) throw new Error('Private cookie snapshot checksum mismatch');
+  const local = loadInternalCookieJar();
+  const remote = normalizeCloudSnapshot(JSON.parse(bytes.toString('utf8')));
+  const pending = require('../state/mutations').listPendingCloudMutations(replica.resourceId, { database });
+  const pendingKeys = new Set(pending.map((mutation) => mutation.operation?.key).filter(Boolean));
+  const bootstrapOperations = localBootstrapOperations(local, remote, pendingKeys);
+
+  persistCloudSnapshot({
+    schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
+    version: remote.version,
+    records: [...remote.records.values()],
+    tombstones: [...remote.tombstones.values()],
+  });
+  const { advanceReplicaSnapshot, refreshReplicaAuthority } = require('../state/replicas');
+  advanceReplicaSnapshot({
+    resourceId: replica.resourceId,
+    snapshotVersion: Number(input.snapshotVersion) || 0,
+    snapshotChecksum: checksum,
+    authorityEpoch: Number(input.authorityEpoch) || 1,
+  }, { database });
+  refreshReplicaAuthority({
+    resourceId: replica.resourceId,
+    authorityEpoch: Number(input.authorityEpoch) || 1,
+    headVersion: Number(input.headVersion) || 0,
+    contract: COOKIE_CLOUD_CONTRACT,
+    schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
+  }, { database });
+
+  // Snapshot installation never discards local work. Already-journaled edits
+  // replay from their durable rows; pre-cloud legacy entries become ordinary
+  // new mutations through the same commit path.
+  for (const mutation of pending) materializeCookieOperation(mutation.operation);
+  let currentReplica = cookieCloudReplica({ database });
+  for (const operation of bootstrapOperations) {
+    commitCookieOperation(operation, currentReplica, { database });
+    currentReplica = cookieCloudReplica({ database });
+  }
+  return { replica: currentReplica, jar: readCookieJar(), bootstrappedMutations: bootstrapOperations.length };
+}
+
+function applyCloudCookieMutation(input = {}, options = {}) {
+  const envelope = input.envelope || {};
+  if (envelope.contract !== COOKIE_CLOUD_CONTRACT) {
+    throw new Error(`Cannot apply ${String(envelope.contract)} to the cookie jar`);
+  }
+  const database = options.database || require('../state/db').openLocalDb();
+  const mutationId = String(envelope.mutationId || '');
+  return require('../state/mutations').ingestCloudMutation({
+    localResource: COOKIE_CLOUD_RESOURCE,
+    envelope,
+    version: input.version,
+    committedAt: input.committedAt,
+  }, {
+    database,
+    materialize(mutation) {
+      materializeCookieOperation(mutation.operation);
+    },
+    event(mutation) {
+      return cookieEvent(mutation.operation, mutationId);
+    },
+  });
+}
+
 function diffCookieSnapshots(before = [], after = [], options = {}) {
   const beforeMap = new Map(normalizeCookieList(before, options.excludeHosts).map((cookie) => [cookieKey(cookie), cookie]));
   const afterMap = new Map(normalizeCookieList(after, options.excludeHosts).map((cookie) => [cookieKey(cookie), cookie]));
@@ -350,15 +702,21 @@ function cookieJarState(snapshot = readCookieJar()) {
 }
 
 module.exports = {
+  COOKIE_CLOUD_CONTRACT,
   COOKIE_JAR_SCHEMA_VERSION,
   DEFAULT_EXCLUDED_HOST_SUFFIXES,
+  applyCloudCookieMutation,
+  cloudSnapshot,
   cookieFingerprint,
   cookieJarState,
   cookieKey,
   cookiesMissingFromJar,
   diffCookieSnapshots,
+  getCookieCloudBootstrap,
   hostIsExcluded,
+  installCookieCloudBootstrap,
   mergeCookieJar,
   normalizeCookieList,
+  privateCookieResourceId,
   readCookieJar,
 };

package/runtime/scripts/amalgm-mcp/browser/rest.js

@@ -13,6 +13,8 @@ const {
   createBrowserLoginSession,
   deleteBrowserAuthBundle,
   getBrowserAuthBundle,
+  getCookieCloudBootstrap,
+  installCookieCloudBootstrap,
   listBrowserLoginSessions,
   listBrowserAuthBundles,
   listBrowserProfiles,
@@ -121,6 +123,22 @@ function handleCookieJarMerge(body = {}, sendJson) {
   sendJson(200, { jar });
 }
 
+function handleCookieCloudBootstrap(sendJson) {
+  try {
+    sendJson(200, getCookieCloudBootstrap());
+  } catch (error) {
+    sendJson(500, { error: error?.message || 'cookie cloud bootstrap failed' });
+  }
+}
+
+function handleCookieCloudInstall(body = {}, sendJson) {
+  try {
+    sendJson(200, installCookieCloudBootstrap(body));
+  } catch (error) {
+    sendJson(Number(error?.statusCode) || 400, { error: error?.message || 'cookie cloud install failed' });
+  }
+}
+
 async function handleAuthBundleExport(body = {}, sendJson) {
   const result = await exportAuthBundleFromProfile(body);
   sendJson(200, { bundle: result.bundle });
@@ -333,6 +351,8 @@ module.exports = {
   handleAuthBundlesList,
   handleCookieJarGet,
   handleCookieJarMerge,
+  handleCookieCloudBootstrap,
+  handleCookieCloudInstall,
   handleLoginSessionCancel,
   handleLoginSessionComplete,
   handleLoginSessionCreate,

package/runtime/scripts/amalgm-mcp/server/routes/browser.js

@@ -13,6 +13,16 @@ async function handleBrowserRoutes(ctx) {
     browserRest.handleCookieJarMerge(await ctx.readJsonBody(), ctx.sendJson);
     return true;
   }
+  if (ctx.pathname === '/browser/cookie-jar/cloud/bootstrap' && ctx.method === 'GET') {
+    ctx.res.setHeader('Cache-Control', 'no-store');
+    browserRest.handleCookieCloudBootstrap(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/browser/cookie-jar/cloud/install' && ctx.method === 'POST') {
+    ctx.res.setHeader('Cache-Control', 'no-store');
+    browserRest.handleCookieCloudInstall(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
   if (ctx.pathname === '/browser/profiles' && ctx.method === 'GET') {
     browserRest.handleProfilesList(ctx.sendJson);
     return true;

package/runtime/scripts/amalgm-mcp/state/mutation-contracts.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Runtime-side persistence policy for mutation contracts.
+ *
+ * The mutation journal is the durable cloud outbox, so sensitive operations
+ * must be protected before they enter it. Transport callers explicitly decode
+ * the row while it is in memory; diagnostics only receive the redacted shape.
+ */
+
+const { decryptJson, encryptJson } = require('../browser/auth-vault');
+
+const COOKIE_CONTRACT = 'browser-cookie-jar@1';
+const PROTECTED_KIND = 'amalgm.encrypted-json@1';
+
+function isSensitiveContract(contract) {
+  return contract === COOKIE_CONTRACT;
+}
+
+function protectOperation(contract, operation) {
+  if (!isSensitiveContract(contract)) return operation;
+  return {
+    kind: PROTECTED_KIND,
+    contract,
+    envelope: encryptJson(operation).envelope,
+  };
+}
+
+function revealOperation(contract, stored) {
+  if (!isSensitiveContract(contract)) return stored;
+  if (
+    !stored
+    || stored.kind !== PROTECTED_KIND
+    || stored.contract !== contract
+    || !stored.envelope
+  ) {
+    throw new Error(`Mutation payload for ${contract} is not protected`);
+  }
+  return decryptJson(stored.envelope);
+}
+
+function diagnosticOperation(contract, operation) {
+  if (!isSensitiveContract(contract)) return operation;
+  return {
+    kind: operation && typeof operation === 'object' ? operation.kind || 'redacted' : 'redacted',
+    protected: true,
+  };
+}
+
+module.exports = {
+  COOKIE_CONTRACT,
+  diagnosticOperation,
+  isSensitiveContract,
+  protectOperation,
+  revealOperation,
+};

package/runtime/scripts/amalgm-mcp/state/mutations.js

@@ -14,12 +14,17 @@
 
 const { cachedStatement, openLocalDb } = require('./db');
 const { insertStateEvent, publishStateEvent } = require('./events');
+const {
+  diagnosticOperation,
+  protectOperation,
+  revealOperation,
+} = require('./mutation-contracts');
 const { trace } = require('./trace');
 
 const MAX_MUTATION_BYTES = 4 * 1024 * 1024;
 const DEFAULT_CLAIM_LIMIT = 100;
 const DEFAULT_CLAIM_LEASE_MS = 30_000;
-const SHARED_RESOURCE_ID = /^shr_[A-Za-z0-9_-]{16,128}$/;
+const CLOUD_RESOURCE_ID = /^(?:shr|pvr)_[A-Za-z0-9_-]{16,128}$/;
 const MUTATION_ID = /^[A-Za-z0-9_-]{16,160}$/;
 const OPERATION_KIND = /^[a-z][a-z0-9._:-]{0,63}$/;
 const CONTRACT = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/;
@@ -96,24 +101,28 @@ function normalizeMutationInput(input) {
     throw invalid(`operation exceeds the ${MAX_MUTATION_BYTES}-byte durable mutation limit`, 413);
   }
 
-  const sharedResourceId = input.sharedResourceId == null
+  // `shared_resource_id` is the installed SQLite compatibility column. The
+  // core treats it as a cloud resource id; `shr_` uses shared authority and
+  // `pvr_` uses same-user-private authority.
+  const cloudResourceInput = input.cloudResourceId ?? input.sharedResourceId;
+  const sharedResourceId = cloudResourceInput == null
     ? null
-    : cleanText(input.sharedResourceId, 'sharedResourceId', 132);
-  if (sharedResourceId && !SHARED_RESOURCE_ID.test(sharedResourceId)) {
-    throw invalid('sharedResourceId must be an opaque id beginning with shr_');
+    : cleanText(cloudResourceInput, 'cloudResourceId', 132);
+  if (sharedResourceId && !CLOUD_RESOURCE_ID.test(sharedResourceId)) {
+    throw invalid('cloudResourceId must be an opaque id beginning with shr_ or pvr_');
   }
   if (sharedResourceId && channelId !== `resource:${sharedResourceId}`) {
-    throw invalid('a shared mutation channelId must be resource:<sharedResourceId>');
+    throw invalid('a cloud mutation channelId must be resource:<cloudResourceId>');
   }
 
   const authorityEpoch = nonNegativeInteger(input.authorityEpoch, 'authorityEpoch');
   const baseCloudVersion = nonNegativeInteger(input.baseCloudVersion, 'baseCloudVersion');
   const deviceId = input.deviceId == null ? null : cleanText(input.deviceId, 'deviceId', 256);
   if (sharedResourceId && authorityEpoch < 1) {
-    throw invalid('shared mutations require authorityEpoch >= 1');
+    throw invalid('cloud mutations require authorityEpoch >= 1');
   }
   if (sharedResourceId && !deviceId) {
-    throw invalid('shared mutations require deviceId');
+    throw invalid('cloud mutations require deviceId');
   }
 
   const localRevision = input.localRevision == null
@@ -123,6 +132,7 @@ function normalizeMutationInput(input) {
   return {
     channelId,
     localResource,
+    cloudResourceId: sharedResourceId,
     sharedResourceId,
     mutationId,
     deviceId,
@@ -137,12 +147,15 @@ function normalizeMutationInput(input) {
   };
 }
 
-function normalizeJournalRow(row) {
+function normalizeJournalRow(row, options = {}) {
   if (!row) return null;
+  const storedOperation = safeJsonParse(row.operation_json);
+  const operation = revealOperation(row.contract, storedOperation);
   return {
     journalId: Number(row.journal_id),
     channelId: row.channel_id,
     localResource: row.local_resource,
+    cloudResourceId: row.shared_resource_id || null,
     sharedResourceId: row.shared_resource_id || null,
     mutationId: row.mutation_id,
     deviceId: row.device_id || null,
@@ -154,7 +167,9 @@ function normalizeJournalRow(row) {
     contract: row.contract,
     schemaVersion: Number(row.schema_version),
     operationKind: row.operation_kind,
-    operation: safeJsonParse(row.operation_json),
+    operation: options.diagnostic === true
+      ? diagnosticOperation(row.contract, operation)
+      : operation,
     origin: row.mutation_origin,
     state: row.mutation_state,
     localRevision: row.local_revision == null ? null : Number(row.local_revision),
@@ -177,6 +192,10 @@ function getMutationRow(database, channelId, mutationId) {
 }
 
 function sameMutation(existing, mutation) {
+  const existingOperation = revealOperation(
+    existing.contract,
+    safeJsonParse(existing.operation_json),
+  );
   return existing.local_resource === mutation.localResource
     && (existing.shared_resource_id || null) === mutation.sharedResourceId
     && (existing.device_id || null) === mutation.deviceId
@@ -185,11 +204,15 @@ function sameMutation(existing, mutation) {
     && existing.contract === mutation.contract
     && Number(existing.schema_version) === mutation.schemaVersion
     && existing.operation_kind === mutation.operationKind
-    && existing.operation_json === mutation.operationJson
+    && JSON.stringify(existingOperation) === mutation.operationJson
     && (existing.local_revision == null ? null : Number(existing.local_revision)) === mutation.localRevision;
 }
 
 function sameCloudEnvelope(existing, mutation) {
+  const existingOperation = revealOperation(
+    existing.contract,
+    safeJsonParse(existing.operation_json),
+  );
   return existing.local_resource === mutation.localResource
     && (existing.shared_resource_id || null) === mutation.sharedResourceId
     && (existing.device_id || null) === mutation.deviceId
@@ -198,7 +221,7 @@ function sameCloudEnvelope(existing, mutation) {
     && existing.contract === mutation.contract
     && Number(existing.schema_version) === mutation.schemaVersion
     && existing.operation_kind === mutation.operationKind
-    && existing.operation_json === mutation.operationJson;
+    && JSON.stringify(existingOperation) === mutation.operationJson;
 }
 
 function journalMutation(input, options = {}) {
@@ -248,7 +271,7 @@ function journalMutation(input, options = {}) {
       mutation.contract,
       mutation.schemaVersion,
       mutation.operationKind,
-      mutation.operationJson,
+      JSON.stringify(protectOperation(mutation.contract, mutation.operation)),
       mutation.localRevision,
     );
 
@@ -405,7 +428,7 @@ function journalCloudMutation(input, options = {}) {
       throw invalid(`shared resource ${sharedResourceId} contract changed`, 409);
     }
 
-    const existing = findSharedMutationRow(database, sharedResourceId, mutation.mutationId);
+    const existing = findCloudMutationRow(database, sharedResourceId, mutation.mutationId);
     if (existing) {
       if (!sameCloudEnvelope(existing, mutation)) {
         throw invalid(`mutationId ${mutation.mutationId} was reused with different content`, 409);
@@ -499,7 +522,7 @@ function journalCloudMutation(input, options = {}) {
       mutation.contract,
       mutation.schemaVersion,
       mutation.operationKind,
-      mutation.operationJson,
+      JSON.stringify(protectOperation(mutation.contract, mutation.operation)),
       committedAt,
       now,
       now,
@@ -582,15 +605,17 @@ function commitLocalMutation(input, options = {}) {
 
 function getMutation(channelId, mutationId, options = {}) {
   const database = options.database || openLocalDb();
-  return normalizeJournalRow(getMutationRow(database, channelId, mutationId));
+  return normalizeJournalRow(getMutationRow(database, channelId, mutationId), {
+    diagnostic: options.revealOperation !== true,
+  });
 }
 
 function cloudEnvelope(mutation) {
-  if (!mutation.sharedResourceId || !mutation.deviceId) {
+  if (!mutation.cloudResourceId || !mutation.deviceId) {
     throw invalid(`mutation ${mutation.mutationId} is not cloud-deliverable`, 409);
   }
   return {
-    resourceId: mutation.sharedResourceId,
+    resourceId: mutation.cloudResourceId,
     authorityEpoch: mutation.authorityEpoch,
     mutationId: mutation.mutationId,
     deviceId: mutation.deviceId,
@@ -652,7 +677,7 @@ function claimCloudMutations(options = {}) {
   })();
 }
 
-function findSharedMutationRow(database, sharedResourceId, mutationId) {
+function findCloudMutationRow(database, sharedResourceId, mutationId) {
   return cachedStatement(database, `
     SELECT * FROM mutation_journal
     WHERE shared_resource_id = ? AND mutation_id = ?
@@ -671,7 +696,7 @@ function acknowledgeCloudMutation(sharedResourceIdInput, mutationIdInput, acknow
   const database = options.database || openLocalDb();
 
   return database.transaction(() => {
-    const row = findSharedMutationRow(database, sharedResourceId, mutationId);
+    const row = findCloudMutationRow(database, sharedResourceId, mutationId);
     if (!row) throw invalid(`unknown shared mutation ${mutationId}`, 404);
     if (row.mutation_state === 'synced') {
       if (Number(row.official_cloud_version) !== version) {
@@ -715,7 +740,7 @@ function failCloudMutation(sharedResourceIdInput, mutationIdInput, failure, opti
     ? (failure?.retryAt || new Date(Date.now() + 1000).toISOString())
     : null;
   const database = options.database || openLocalDb();
-  const row = findSharedMutationRow(database, sharedResourceId, mutationId);
+  const row = findCloudMutationRow(database, sharedResourceId, mutationId);
   if (!row) throw invalid(`unknown shared mutation ${mutationId}`, 404);
   if (row.mutation_state === 'synced') return normalizeJournalRow(row);
 
@@ -750,7 +775,7 @@ function markMutationConflicted(sharedResourceIdInput, mutationIdInput, messageI
     WHERE shared_resource_id = ? AND mutation_id = ? AND mutation_state != 'synced'
   `).run(message, now, sharedResourceId, mutationId);
   if (!result.changes) throw invalid(`unknown or synced shared mutation ${mutationId}`, 404);
-  return normalizeJournalRow(findSharedMutationRow(database, sharedResourceId, mutationId));
+  return normalizeJournalRow(findCloudMutationRow(database, sharedResourceId, mutationId));
 }
 
 function listMutations(options = {}) {
@@ -768,7 +793,27 @@ function listMutations(options = {}) {
         ORDER BY journal_id ASC
         LIMIT ?
       `).all(limit);
-  return rows.map(normalizeJournalRow);
+  return rows.map((row) => normalizeJournalRow(row, { diagnostic: true }));
+}
+
+/**
+ * Internal recovery view used by contract materializers after installing a
+ * newer snapshot. It reads the journal without claiming rows or changing
+ * their retry leases.
+ */
+function listPendingCloudMutations(resourceIdInput, options = {}) {
+  const resourceId = cleanText(resourceIdInput, 'resourceId', 132);
+  if (!CLOUD_RESOURCE_ID.test(resourceId)) {
+    throw invalid('resourceId must be an opaque cloud resource id');
+  }
+  const database = options.database || openLocalDb();
+  return cachedStatement(database, `
+    SELECT * FROM mutation_journal
+    WHERE shared_resource_id = ?
+      AND mutation_origin = 'local'
+      AND mutation_state != 'synced'
+    ORDER BY journal_id ASC
+  `).all(resourceId).map((row) => normalizeJournalRow(row));
 }
 
 function pruneMutationJournal(options = {}) {
@@ -814,6 +859,7 @@ module.exports = {
   ingestCloudMutation,
   journalCloudMutation,
   journalMutation,
+  listPendingCloudMutations,
   listMutations,
   markMutationConflicted,
   pruneMutationJournal,

package/runtime/scripts/amalgm-mcp/state/replicas.js

@@ -11,7 +11,7 @@
 const { cachedStatement, openLocalDb } = require('./db');
 const { trace } = require('./trace');
 
-const SHARED_RESOURCE_ID = /^shr_[A-Za-z0-9_-]{16,128}$/;
+const CLOUD_RESOURCE_ID = /^(?:shr|pvr)_[A-Za-z0-9_-]{16,128}$/;
 const CONTRACT = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/;
 
 function invalid(message, statusCode = 400) {
@@ -55,8 +55,8 @@ function normalizeReplica(row) {
 
 function registerReplica(input, options = {}) {
   const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
-  if (!SHARED_RESOURCE_ID.test(resourceId)) {
-    throw invalid('resourceId must be an opaque id beginning with shr_');
+  if (!CLOUD_RESOURCE_ID.test(resourceId)) {
+    throw invalid('resourceId must be an opaque id beginning with shr_ or pvr_');
   }
   const localResource = requiredText(input?.localResource, 'localResource');
   const localPath = requiredText(input?.localPath, 'localPath', 4096);
@@ -86,7 +86,7 @@ function registerReplica(input, options = {}) {
       || normalized.contract !== contract
       || normalized.schemaVersion !== schemaVersion
     ) {
-      throw invalid(`shared resource ${resourceId} is already bound differently`, 409);
+      throw invalid(`cloud resource ${resourceId} is already bound differently`, 409);
     }
     return { replica: normalized, duplicate: true };
   }
@@ -123,7 +123,7 @@ function registerReplica(input, options = {}) {
     );
   } catch (error) {
     if (String(error?.code || '').includes('CONSTRAINT')) {
-      throw invalid('that local file is already bound to another shared resource', 409);
+      throw invalid('that local materialization is already bound to another cloud resource', 409);
     }
     throw error;
   }

package/runtime/scripts/amalgm-mcp/state/shared-rest.js

@@ -267,7 +267,11 @@ async function handleMutationFail(body, sendJson) {
 
 async function handleMutationIngest(body, sendJson) {
   try {
-    sendJson(200, require('./docs').applyCloudDocMutation(body));
+    const contract = body?.envelope?.contract;
+    const result = contract === 'browser-cookie-jar@1'
+      ? require('../browser/cookie-jar').applyCloudCookieMutation(body)
+      : require('./docs').applyCloudDocMutation(body);
+    sendJson(200, result);
   } catch (error) {
     sendHandlerError(error, sendJson);
   }

package/runtime/scripts/amalgm-mcp/tests/browser-cookie-cloud.test.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-cookie-cloud-'));
+const userId = '11111111-1111-4111-8111-111111111111';
+process.env.AMALGM_DIR = path.join(tempRoot, '.amalgm');
+process.env.AMALGM_BROWSER_AUTH_KEY = 'e'.repeat(64);
+fs.mkdirSync(process.env.AMALGM_DIR, { recursive: true });
+fs.writeFileSync(path.join(process.env.AMALGM_DIR, 'computer.json'), JSON.stringify({
+  computer_id: 'machine-cookie-a',
+  user_id: userId,
+}));
+
+const { closeLocalDb, openLocalDb } = require('../state/db');
+const { listEventsAfter } = require('../state/events');
+const {
+  acknowledgeCloudMutation,
+  claimCloudMutations,
+  getMutation,
+} = require('../state/mutations');
+const {
+  COOKIE_CLOUD_CONTRACT,
+  applyCloudCookieMutation,
+  getCookieCloudBootstrap,
+  mergeCookieJar,
+  privateCookieResourceId,
+  readCookieJar,
+} = require('../browser/cookie-jar');
+const { deleteBrowserAuthBundle } = require('../browser/auth-bundles');
+const { COOKIE_SOURCE_BUNDLE_ID } = require('../browser/cookie-source');
+
+function cookie(name, value) {
+  return {
+    name,
+    value,
+    domain: '.example.com',
+    path: '/',
+    expires: -1,
+    httpOnly: true,
+    secure: true,
+    sameSite: 'Lax',
+  };
+}
+
+test.beforeEach(() => {
+  const db = openLocalDb();
+  deleteBrowserAuthBundle(COOKIE_SOURCE_BUNDLE_ID);
+  db.prepare('DELETE FROM event_log').run();
+  db.prepare('DELETE FROM mutation_journal').run();
+  db.prepare('DELETE FROM shared_resource_replicas').run();
+});
+
+test.after(() => {
+  closeLocalDb();
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('signed-in cookie edits use the common encrypted journal/outbox', () => {
+  const secret = 'cloud-cookie-secret';
+  const result = mergeCookieJar({ sourceId: 'electron', upserts: [cookie('session', secret)] });
+  assert.equal(result.cookies[0].value, secret);
+
+  const db = openLocalDb();
+  const row = db.prepare('SELECT * FROM mutation_journal').get();
+  assert.ok(row.shared_resource_id.startsWith('pvr_'));
+  assert.equal(row.contract, COOKIE_CLOUD_CONTRACT);
+  assert.equal(row.operation_json.includes(secret), false, 'SQLite never stores plaintext cookie values');
+
+  const [claim] = claimCloudMutations({ database: db });
+  assert.equal(claim.envelope.operation.cookie.value, secret, 'the authenticated TLS transport gets the decoded operation');
+  assert.deepEqual(getMutation(row.channel_id, row.mutation_id, { database: db }).operation, {
+    kind: 'cookie.upsert',
+    protected: true,
+  });
+  assert.equal(JSON.stringify(listEventsAfter(0)).includes(secret), false, 'Local Live events are metadata-only');
+});
+
+test('official cookie mutations materialize in order and deletions stay tombstoned', () => {
+  mergeCookieJar({ sourceId: 'machine-a', upserts: [cookie('local', 'local-secret')] });
+  const db = openLocalDb();
+  const [localClaim] = claimCloudMutations({ database: db });
+  acknowledgeCloudMutation(localClaim.envelope.resourceId, localClaim.envelope.mutationId, {
+    version: 1,
+    committedAt: '2026-07-20T20:00:00.000Z',
+  }, { database: db });
+
+  const remoteCookie = cookie('remote', 'remote-secret');
+  const key = require('../browser/cookie-jar').cookieKey(remoteCookie);
+  const common = {
+    resourceId: localClaim.envelope.resourceId,
+    authorityEpoch: 1,
+    deviceId: 'machine-cookie-b',
+    contract: COOKIE_CLOUD_CONTRACT,
+    schemaVersion: 1,
+  };
+  applyCloudCookieMutation({
+    version: 2,
+    committedAt: '2026-07-20T20:01:00.000Z',
+    envelope: {
+      ...common,
+      mutationId: 'mut_cookie_remote_0001',
+      baseVersion: 1,
+      operationKind: 'cookie.upsert',
+      operation: {
+        kind: 'cookie.upsert',
+        key,
+        cookie: remoteCookie,
+        sourceId: 'machine-b',
+        changedAt: '2026-07-20T20:01:00.000Z',
+      },
+    },
+  }, { database: db });
+  assert.equal(readCookieJar().cookies.some((item) => item.value === 'remote-secret'), true);
+
+  applyCloudCookieMutation({
+    version: 3,
+    committedAt: '2026-07-20T20:02:00.000Z',
+    envelope: {
+      ...common,
+      mutationId: 'mut_cookie_remote_0002',
+      baseVersion: 2,
+      operationKind: 'cookie.delete',
+      operation: {
+        kind: 'cookie.delete',
+        key,
+        sourceId: 'machine-b',
+        changedAt: '2026-07-20T20:02:00.000Z',
+      },
+    },
+  }, { database: db });
+  const deleted = readCookieJar();
+  assert.equal(deleted.cookies.some((item) => item.name === 'remote'), false);
+  assert.equal(deleted.tombstones.some((item) => item.key === key), true);
+  assert.equal(JSON.stringify(listEventsAfter(0)).includes('remote-secret'), false);
+});
+
+test('the private resource is deterministic per user and bootstrap is automatic', () => {
+  mergeCookieJar({ sourceId: 'headless', upserts: [cookie('bootstrap', 'bootstrap-secret')] });
+  const bootstrap = getCookieCloudBootstrap();
+  assert.equal(bootstrap.enabled, true);
+  assert.equal(bootstrap.resourceId, privateCookieResourceId(userId));
+  assert.notEqual(
+    bootstrap.resourceId,
+    privateCookieResourceId('22222222-2222-4222-8222-222222222222'),
+  );
+  assert.equal(JSON.parse(Buffer.from(bootstrap.snapshotBase64, 'base64').toString('utf8')).schemaVersion, 1);
+});

package/runtime/scripts/amalgm-mcp/tests/private-cookie-tunnel.test.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const crypto = require('crypto');
+const http = require('http');
+
+const { createSharedRealtimeTunnel } = require('../../../../packages/amalgm/lib/shared-realtime-tunnel');
+
+const RESOURCE = 'pvr_private_cookie_tunnel_01';
+const SNAPSHOT = Buffer.from(JSON.stringify({
+  schemaVersion: 1,
+  version: 0,
+  updatedAt: '2026-07-20T20:00:00.000Z',
+  records: [],
+  tombstones: [],
+}));
+
+function sleep(ms) {
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+async function until(predicate, label) {
+  for (let i = 0; i < 100; i += 1) {
+    if (predicate()) return;
+    await sleep(10);
+  }
+  assert.fail(`timed out waiting for ${label}`);
+}
+
+test('the authenticated tunnel automatically ensures, installs, and joins the private cookie resource', async () => {
+  const calls = [];
+  const server = http.createServer((req, res) => {
+    let body = '';
+    req.on('data', (chunk) => { body += chunk; });
+    req.on('end', () => {
+      calls.push({ method: req.method, path: req.url, body: body ? JSON.parse(body) : null });
+      res.setHeader('content-type', 'application/json');
+      if (req.url === '/browser/cookie-jar/cloud/bootstrap') {
+        res.end(JSON.stringify({
+          enabled: true,
+          resourceId: RESOURCE,
+          contract: 'browser-cookie-jar@1',
+          schemaVersion: 1,
+          snapshotBase64: SNAPSHOT.toString('base64'),
+          snapshotBytes: SNAPSHOT.length,
+          snapshotChecksum: crypto.createHash('sha256').update(SNAPSHOT).digest('hex'),
+        }));
+        return;
+      }
+      if (req.url === '/state/shared/replicas') {
+        res.end(JSON.stringify({ replicas: [{ resourceId: RESOURCE, appliedVersion: 0 }] }));
+        return;
+      }
+      if (req.url?.startsWith('/state/stream')) {
+        res.writeHead(200, { 'content-type': 'text/event-stream' });
+        res.write('\n');
+        return;
+      }
+      res.end(JSON.stringify({ mutations: [], promotions: [], attachments: [], ok: true }));
+    });
+  });
+  await new Promise((resolve) => { server.listen(0, '127.0.0.1', resolve); });
+  const port = server.address().port;
+  const sent = [];
+  const tunnel = createSharedRealtimeTunnel({
+    send(frame) { sent.push(frame); return true; },
+    sendLarge(frame) { sent.push(frame); return true; },
+    localPort: () => port,
+    localHeaders: (headers) => ({ ...headers }),
+    warn: () => {},
+  });
+
+  try {
+    tunnel.enable(['shared.mutation.v1', 'private.cookie.v1']);
+    await until(() => sent.some((frame) => frame.type === 'private.resource.ensure'), 'private ensure frame');
+    const ensure = sent.find((frame) => frame.type === 'private.resource.ensure');
+    assert.equal(ensure.resource_id, RESOURCE);
+    assert.equal(ensure.contract, 'browser-cookie-jar@1');
+
+    tunnel.handleFrame({
+      type: 'private.resource.ready',
+      request_id: ensure.request_id,
+      resource_id: RESOURCE,
+      authority_epoch: 1,
+      head_version: 0,
+      snapshot_version: 0,
+      snapshot_checksum: crypto.createHash('sha256').update(SNAPSHOT).digest('hex'),
+      snapshot_b64: SNAPSHOT.toString('base64'),
+      contract: 'browser-cookie-jar@1',
+      schema_version: 1,
+      duplicate: false,
+    });
+    await until(
+      () => calls.some((call) => call.path === '/browser/cookie-jar/cloud/install'),
+      'local private snapshot install',
+    );
+    const install = calls.find((call) => call.path === '/browser/cookie-jar/cloud/install');
+    assert.equal(install.body.resourceId, RESOURCE);
+    await until(
+      () => sent.filter((frame) => frame.type === 'shared.resource.join' && frame.resource_id === RESOURCE).length >= 2,
+      'post-install private resource join',
+    );
+  } finally {
+    tunnel.stop();
+    server.close();
+  }
+});