amalgm 0.1.157 → 0.1.158

package/lib/cli.js

@@ -120,7 +120,7 @@ function usage() {
     '  amalgm stop',
     '  amalgm status',
     '  amalgm doctor',
-    '  amalgm service [install|start|stop|status|uninstall] [--mode auto|systemd|launchd|portable]',
+    '  amalgm service [install|start|stop|status|uninstall] [--mode auto|systemd|launchd|windows|portable]',
     '  amalgm update [--tag latest|canary]',
     '  amalgm logs [service]',
     '  amalgm logout',

package/lib/service.js

@@ -258,8 +258,8 @@ function normalizeMode(mode) {
   const value = String(mode || 'auto').trim().toLowerCase();
   if (!value || value === 'auto') return 'auto';
   if (value === 'watchdog') return 'portable';
-  if (['portable', 'systemd', 'launchd'].includes(value)) return value;
-  throw new Error(`Unsupported service mode "${mode}". Use auto, systemd, launchd, or portable.`);
+  if (['portable', 'systemd', 'launchd', 'windows'].includes(value)) return value;
+  throw new Error(`Unsupported service mode "${mode}". Use auto, systemd, launchd, windows, or portable.`);
 }
 
 function detectServiceBackend(mode = 'auto') {
@@ -273,6 +273,10 @@ function detectServiceBackend(mode = 'auto') {
     if (!systemdAvailable()) throw new Error('systemd --user is not available in this session.');
     return { backend: 'systemd', detail: 'systemd user service' };
   }
+  if (requested === 'windows') {
+    if (process.platform !== 'win32') throw new Error('Windows startup is not available on this machine.');
+    return { backend: 'windows', detail: 'Windows per-user startup entry' };
+  }
   if (requested === 'portable') {
     return {
       backend: 'portable',
@@ -280,6 +284,7 @@ function detectServiceBackend(mode = 'auto') {
     };
   }
   if (launchdAvailable()) return { backend: 'launchd', detail: 'macOS LaunchAgent' };
+  if (process.platform === 'win32') return { backend: 'windows', detail: 'Windows per-user startup entry' };
   if (inContainer) {
     return {
       backend: 'portable',
@@ -633,6 +638,34 @@ function systemdUnitPath() {
   return path.join(os.homedir(), '.config', 'systemd', 'user', `${SERVICE_LABEL}.service`);
 }
 
+function windowsStartupDir(env = process.env) {
+  const appData = String(env.APPDATA || '').trim();
+  const roaming = appData || path.join(os.homedir(), 'AppData', 'Roaming');
+  return path.join(roaming, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+}
+
+function windowsStartupScriptPath(env = process.env) {
+  return path.join(windowsStartupDir(env), `Amalgm-${SERVICE_LABEL_SCOPE}.vbs`);
+}
+
+function vbsString(value) {
+  return `"${String(value).replace(/"/g, '""')}"`;
+}
+
+function writeWindowsStartupScript(localOnly, env = process.env) {
+  const startupPath = windowsStartupScriptPath(env);
+  ensureDir(path.dirname(startupPath), 0o700);
+  const watchdogPath = writePortableNodeScript(localOnly);
+  const command = `"${process.execPath}" "${watchdogPath}"`;
+  const source = [
+    "Set AmalgmShell = CreateObject(\"WScript.Shell\")",
+    `AmalgmShell.Run ${vbsString(command)}, 0, False`,
+    '',
+  ].join('\r\n');
+  fs.writeFileSync(startupPath, source, { mode: 0o600 });
+  return startupPath;
+}
+
 function writeSystemdUnit(localOnly) {
   const unitPath = systemdUnitPath();
   ensureDir(path.dirname(unitPath), 0o700);
@@ -696,6 +729,9 @@ function installService(options = {}) {
   } else if (backend === 'systemd') {
     files.unit = writeSystemdUnit(localOnly);
     spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore', timeout: 5000 });
+  } else if (backend === 'windows') {
+    files.nodeScript = writePortableNodeScript(localOnly);
+    files.startup = writeWindowsStartupScript(localOnly);
   } else {
     files.script = writePortableScript(localOnly);
     files.nodeScript = writePortableNodeScript(localOnly);
@@ -902,6 +938,10 @@ function uninstallService() {
     spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore', timeout: 5000 });
   } else if (state?.backend === 'launchd') {
     removeFile(state?.files?.plist || launchdPlistPath());
+  } else if (state?.backend === 'windows') {
+    removeFile(state?.files?.startup || windowsStartupScriptPath());
+    removeFile(SERVICE_SCRIPT_FILE);
+    removeFile(SERVICE_NODE_SCRIPT_FILE);
   } else {
     removeFile(SERVICE_SCRIPT_FILE);
     removeFile(SERVICE_NODE_SCRIPT_FILE);
@@ -947,6 +987,10 @@ function getServiceStatus() {
       || fs.existsSync(state?.files?.nodeScript || SERVICE_NODE_SCRIPT_FILE);
     pid = readPidFile(SERVICE_PID_FILE);
     running = isPidRunning(pid);
+  } else if (backend === 'windows') {
+    installed = fs.existsSync(state?.files?.startup || windowsStartupScriptPath());
+    pid = readPidFile(SERVICE_PID_FILE);
+    running = isPidRunning(pid);
   }
 
   return {
@@ -970,6 +1014,8 @@ module.exports = {
     serviceStateCanOwnRuntime,
     writeLaunchdPlist,
     writePortableNodeScript,
+    windowsStartupScriptPath,
+    writeWindowsStartupScript,
     writeSystemdUnit,
   },
   detectServiceBackend,

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 joinInflight = new Map();
   const inboundChains = new Map();
 
   let enabled = false;
@@ -239,12 +240,14 @@ function createSharedRealtimeTunnel({
       const result = await localStateJson('GET', '/state/shared/replicas');
       for (const replica of Array.isArray(result?.replicas) ? result.replicas : []) {
         if (!replica?.resourceId) continue;
-        send({
+        const requestId = `join_${crypto.randomBytes(12).toString('hex')}`;
+        const queued = send({
           type: 'shared.resource.join',
-          request_id: `join_${crypto.randomBytes(12).toString('hex')}`,
+          request_id: requestId,
           resource_id: replica.resourceId,
           after_version: replica.appliedVersion || 0,
         });
+        if (queued) joinInflight.set(requestId, replica.resourceId);
       }
     } catch {
       // The local service can still be starting; wake reconnect retries.
@@ -393,6 +396,27 @@ function createSharedRealtimeTunnel({
   }
 
   function handleError(frame) {
+    const joinedResource = joinInflight.get(frame.request_id);
+    if (joinedResource) {
+      joinInflight.delete(frame.request_id);
+      if (frame.code === 'shared_tail_pruned' || frame.code === 'shared_tail_too_large') {
+        // The official tail can no longer reach this replica's cursor —
+        // compaction pruned past it, or the gap outgrew incremental
+        // recovery. Recover through a fresh snapshot attachment; its ack
+        // merges the snapshot, jumps the replica cursor, and re-joins.
+        void localStateJson('POST', '/state/shared/replicas/rehydrate', {
+          resourceId: joinedResource,
+        }).then(() => {
+          scheduleAttachmentDrain();
+        }).catch((error) => {
+          warn(`shared rehydration request failed for ${joinedResource}: ${error?.message || error}`);
+        });
+      } else {
+        warn(`shared join failed for ${joinedResource}: ${frame.code || 'shared_error'}: ${frame.message || ''}`);
+      }
+      return;
+    }
+
     const attachment = attachmentInflight.get(frame.request_id);
     if (attachment) {
       void localStateJson('POST', '/state/shared/attachments/fail', {
@@ -472,6 +496,7 @@ function createSharedRealtimeTunnel({
         handleError(frame);
         return true;
       case 'shared.resource.joined':
+        joinInflight.delete(frame.request_id);
         void localStateJson('POST', '/state/shared/replicas/authority', {
           resourceId: frame.resource_id,
           authorityEpoch: frame.authority_epoch,
@@ -499,6 +524,7 @@ function createSharedRealtimeTunnel({
     mutationInflight.clear();
     promotionInflight.clear();
     attachmentInflight.clear();
+    joinInflight.clear();
     inboundChains.clear();
     if (wakeRequest) wakeRequest.destroy();
     wakeRequest = null;

package/package.json

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

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

@@ -95,6 +95,10 @@ async function handleStateRoutes(ctx) {
       await sharedRest.handleReplicaAuthority(await ctx.readJsonBody(), ctx.sendJson);
       return true;
     }
+    if (ctx.pathname === '/state/shared/replicas/rehydrate') {
+      await sharedRest.handleReplicaRehydrate(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
     if (ctx.pathname === '/state/shared/promote') {
       await sharedRest.handlePromotionStart(await ctx.readJsonBody(), ctx.sendJson);
       return true;

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

@@ -1,5 +1,7 @@
 'use strict';
 
+const crypto = require('crypto');
+
 const { cachedStatement, openLocalDb } = require('./db');
 const { appendStateEvent } = require('./events');
 
@@ -170,6 +172,57 @@ function failAttachment(attachmentIdInput, failure, options = {}) {
   );
 }
 
+/**
+ * Re-runs the snapshot attachment for a replica the official tail can no
+ * longer reach (its cursor fell behind compaction's pruned floor). The
+ * attachment row is the durable request: an existing one cycles back to
+ * pending; a replica born from promotion — which never attached — gets one.
+ */
+function requestRehydration(input, options = {}) {
+  const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
+  if (!SHARED_RESOURCE_ID.test(resourceId)) throw invalid('resourceId has an invalid format');
+  const database = options.database || openLocalDb();
+  const replica = require('./replicas').getReplicaByResourceId(resourceId, { database });
+  if (!replica) throw invalid(`shared resource ${resourceId} has no local replica`, 404);
+  const now = new Date().toISOString();
+  const existing = cachedStatement(
+    database,
+    'SELECT * FROM shared_resource_attachments WHERE resource_id = ?',
+  ).get(resourceId);
+  let attachmentId;
+  if (existing) {
+    attachmentId = existing.attachment_id;
+    cachedStatement(database, `
+      UPDATE shared_resource_attachments
+      SET attachment_state = 'pending',
+          next_attempt_at = NULL,
+          last_error = NULL,
+          updated_at = ?
+      WHERE attachment_id = ?
+    `).run(now, attachmentId);
+  } else {
+    attachmentId = `att_${crypto.randomBytes(16).toString('base64url')}`;
+    cachedStatement(database, `
+      INSERT INTO shared_resource_attachments (
+        attachment_id, resource_id, local_path, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?)
+    `).run(attachmentId, resourceId, replica.localPath, now, now);
+  }
+  const attachment = normalizeRow(
+    cachedStatement(database, 'SELECT * FROM shared_resource_attachments WHERE attachment_id = ?')
+      .get(attachmentId),
+  );
+  appendStateEvent({
+    resource: 'shared:attachments',
+    op: 'update',
+    id: attachmentId,
+    sharedResourceId: resourceId,
+    value: { state: 'pending' },
+    source: 'shared:rehydration',
+  });
+  return { attachment, requeued: Boolean(existing) };
+}
+
 function getAttachment(attachmentId, options = {}) {
   const database = options.database || openLocalDb();
   return normalizeRow(
@@ -184,4 +237,5 @@ module.exports = {
   enqueueAttachment,
   failAttachment,
   getAttachment,
+  requestRehydration,
 };

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

@@ -1044,26 +1044,44 @@ function installCloudDocSnapshot(pathInput, input) {
   } catch (error) {
     throw invalid(`invalid Yjs snapshot: ${error?.message || error}`);
   }
+  const replicas = require('./replicas');
   const entry = loadDocEntry(pathInput);
-  const currentText = entry.doc.getText(TEXT_KEY).toString();
-  if (currentText.length > 0) {
+  const existingReplica = replicas.getReplicaByResourceId(input?.resourceId);
+  if (existingReplica) {
+    // Rehydration: this replica fell behind the pruned official tail, so the
+    // authority serves a full snapshot instead. Applying it to the live doc
+    // is a CRDT merge — official state and unsynced local edits both survive,
+    // and the outbox still carries those local edits to the cloud.
+    if (existingReplica.localResource !== entry.resource) {
+      throw invalid(`shared resource ${input?.resourceId} is bound to a different local file`, 409);
+    }
+  } else if (entry.doc.getText(TEXT_KEY).toString().length > 0) {
     throw invalid('cloud snapshot attachment requires an empty local text file', 409);
   }
   const origin = { amalgmMutation: true, source: 'cloud-snapshot', patch: null };
   Y.applyUpdate(entry.doc, new Uint8Array(bytes), origin);
   persistDocState(Y, entry);
   flushDocToDisk(Y, entry);
-  const registered = require('./replicas').registerReplica({
-    resourceId: input?.resourceId,
-    localResource: entry.resource,
-    localPath: entry.path,
-    contract: input?.contract,
-    schemaVersion: input?.schemaVersion,
-    authorityEpoch: input?.authorityEpoch,
-    appliedVersion: input?.snapshotVersion,
-    snapshotVersion: input?.snapshotVersion,
-    snapshotChecksum: checksum,
-  });
+  const registered = existingReplica
+    ? {
+      replica: replicas.advanceReplicaSnapshot({
+        resourceId: input?.resourceId,
+        snapshotVersion: input?.snapshotVersion,
+        snapshotChecksum: checksum,
+        authorityEpoch: input?.authorityEpoch,
+      }),
+    }
+    : replicas.registerReplica({
+      resourceId: input?.resourceId,
+      localResource: entry.resource,
+      localPath: entry.path,
+      contract: input?.contract,
+      schemaVersion: input?.schemaVersion,
+      authorityEpoch: input?.authorityEpoch,
+      appliedVersion: input?.snapshotVersion,
+      snapshotVersion: input?.snapshotVersion,
+      snapshotChecksum: checksum,
+    });
   // File and SQLite binding are current before a mounted UI can observe the
   // snapshot. Applying this full Yjs state is idempotent for an already-open
   // recipient surface.

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

@@ -193,7 +193,50 @@ function refreshReplicaAuthority(input, options = {}) {
   return getReplicaByResourceId(resourceId, { database });
 }
 
+/**
+ * A freshly attached official snapshot subsumes every version at or before
+ * it, so the replica's cursors jump forward to the snapshot — never backward:
+ * a replica that already applied past the snapshot keeps its position.
+ */
+function advanceReplicaSnapshot(input, options = {}) {
+  const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
+  const snapshotVersion = integer(input?.snapshotVersion, 'snapshotVersion', 0);
+  const snapshotChecksum = requiredText(input?.snapshotChecksum, 'snapshotChecksum', 64);
+  if (!/^[0-9a-f]{64}$/.test(snapshotChecksum)) {
+    throw invalid('snapshotChecksum must be lowercase sha256 hex');
+  }
+  const authorityEpoch = integer(input?.authorityEpoch, 'authorityEpoch', 1);
+  const database = options.database || openLocalDb();
+  const row = cachedStatement(
+    database,
+    'SELECT * FROM shared_resource_replicas WHERE resource_id = ?',
+  ).get(resourceId);
+  if (!row) throw invalid(`unknown shared replica ${resourceId}`, 404);
+  cachedStatement(database, `
+    UPDATE shared_resource_replicas
+    SET applied_version = MAX(applied_version, ?),
+        snapshot_version = MAX(snapshot_version, ?),
+        snapshot_checksum = CASE WHEN snapshot_version <= ? THEN ? ELSE snapshot_checksum END,
+        authority_epoch = MAX(authority_epoch, ?),
+        sync_status = 'synced',
+        last_error = NULL,
+        updated_at = ?
+    WHERE resource_id = ?
+  `).run(
+    snapshotVersion,
+    snapshotVersion,
+    snapshotVersion,
+    snapshotChecksum,
+    authorityEpoch,
+    new Date().toISOString(),
+    resourceId,
+  );
+  trace('replica-rehydrate', { resourceId, snapshotVersion });
+  return getReplicaByResourceId(resourceId, { database });
+}
+
 module.exports = {
+  advanceReplicaSnapshot,
   getReplicaByLocalResource,
   getReplicaByResourceId,
   listReplicas,

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

@@ -61,6 +61,14 @@ async function handleReplicaAuthority(body, sendJson) {
   }
 }
 
+async function handleReplicaRehydrate(body, sendJson) {
+  try {
+    sendJson(202, require('./attachments').requestRehydration({ resourceId: body?.resourceId }));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
 async function handlePromotionStart(body, sendJson) {
   try {
     const opened = require('./docs').openDoc(body?.path);
@@ -264,4 +272,5 @@ module.exports = {
   handleReplicaAuthority,
   handleReplicaList,
   handleReplicaRegister,
+  handleReplicaRehydrate,
 };

package/runtime/scripts/amalgm-mcp/tests/desktop-release-server.test.js

@@ -29,6 +29,12 @@ function writeReleaseMetadata(lane, artifacts, extra = {}) {
   fs.writeFileSync(path.join(laneDir, 'desktop-release.json'), `${JSON.stringify({ lane, artifacts, ...extra }, null, 2)}\n`);
 }
 
+function writeWindowsReleaseMetadata(lane, artifacts, extra = {}) {
+  const laneDir = path.join(tempRoot, lane);
+  fs.mkdirSync(laneDir, { recursive: true });
+  fs.writeFileSync(path.join(laneDir, 'desktop-release.windows.json'), `${JSON.stringify({ lane, platform: 'windows', artifacts, ...extra }, null, 2)}\n`);
+}
+
 function writeLaneFile(lane, fileName, mtimeOffsetMs = 0) {
   const laneDir = path.join(tempRoot, lane);
   fs.mkdirSync(laneDir, { recursive: true });
@@ -72,6 +78,7 @@ test('desktop release server resolves stable bridge download targets from metada
 
   assert.deepEqual(parseDownloadPath('/main/download'), { lane: 'main', kind: 'dmg' });
   assert.deepEqual(parseDownloadPath('/main/download/zip'), { lane: 'main', kind: 'zip' });
+  assert.deepEqual(parseDownloadPath('/main/download/exe'), { lane: 'main', kind: 'exe' });
   assert.deepEqual(parseDownloadPath('/main/latest.dmg'), { lane: 'main', kind: 'dmg' });
   assert.equal(parseDownloadPath('/main/latest-mac.yml'), null);
   assert.equal(latestArtifactName({ artifacts }, 'dmg'), 'amalgm-local-ui-0.1.1-arm64.dmg');
@@ -81,6 +88,37 @@ test('desktop release server resolves stable bridge download targets from metada
   });
 });
 
+test('desktop release server exposes the current Windows installer', async () => {
+  const exeName = 'amalgm-local-ui-0.1.2-x64.exe';
+  writeLaneFile('main', exeName);
+  writeWindowsReleaseMetadata('main', [exeName, `${exeName}.blockmap`, 'latest.yml'], {
+    version: '0.1.2',
+    primaryDownload: {
+      platform: 'windows',
+      kind: 'exe',
+      artifact: exeName,
+      size: 123,
+      sha512: 'windows-sha',
+    },
+  });
+
+  assert.equal(latestDownloadTarget('main', 'exe').artifactName, exeName);
+
+  const server = createServer();
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address();
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/main/download/exe`, { redirect: 'manual' });
+    assert.equal(response.status, 302);
+    assert.equal(
+      response.headers.get('location'),
+      `http://127.0.0.1:${port}/main/${exeName}?download=amalgm-Windows.exe`,
+    );
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+});
+
 test('desktop release server honors explicit metadata artifact descriptors', () => {
   const metadata = {
     artifacts: [

package/runtime/scripts/amalgm-mcp/tests/shared-tunnel-rehydration.test.js

@@ -0,0 +1,115 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+
+const { createSharedRealtimeTunnel } = require('../../../../packages/amalgm/lib/shared-realtime-tunnel');
+
+const RESOURCE = 'shr_tunnel_rehydrate1';
+
+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}`);
+}
+
+// The tunnel client against a real (local, in-test) state service: a join
+// answered with shared_tail_pruned or shared_tail_too_large must turn into a
+// rehydration request plus an attachment drain; any other join failure must not.
+test('a pruned-tail join answer triggers rehydration through the local state service', 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 });
+      if (req.url === '/state/shared/replicas') {
+        res.setHeader('content-type', 'application/json');
+        res.end(JSON.stringify({ replicas: [{ resourceId: RESOURCE, appliedVersion: 3 }] }));
+        return;
+      }
+      if (req.url.startsWith('/state/stream')) {
+        res.writeHead(200, { 'content-type': 'text/event-stream' });
+        res.write('\n');
+        return; // stays open: it is only a wake signal
+      }
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ mutations: [], promotions: [], attachments: [] }));
+    });
+  });
+  await new Promise((resolve) => { server.listen(0, '127.0.0.1', resolve); });
+  const port = server.address().port;
+
+  const sentFrames = [];
+  const tunnel = createSharedRealtimeTunnel({
+    send: (frame) => { sentFrames.push(frame); return true; },
+    sendLarge: (frame) => { sentFrames.push(frame); return true; },
+    localPort: () => port,
+    localHeaders: (headers) => ({ ...headers }),
+    warn: () => {},
+  });
+
+  try {
+    tunnel.enable(['shared.mutation.v1']);
+    await until(
+      () => sentFrames.some((frame) => frame.type === 'shared.resource.join'),
+      'the reconnect join',
+    );
+    const join = sentFrames.find((frame) => frame.type === 'shared.resource.join');
+    assert.equal(join.resource_id, RESOURCE);
+    assert.equal(join.after_version, 3, 'the join carries the durable replica cursor');
+
+    tunnel.handleFrame({
+      type: 'shared.error',
+      request_id: join.request_id,
+      resource_id: RESOURCE,
+      code: 'shared_tail_pruned',
+      message: 'versions after 3 were folded into snapshot v40',
+      status: 409,
+      retryable: false,
+    });
+    await until(
+      () => calls.some((call) => call.path === '/state/shared/replicas/rehydrate'),
+      'the rehydration request',
+    );
+    const rehydrate = calls.find((call) => call.path === '/state/shared/replicas/rehydrate');
+    assert.equal(rehydrate.method, 'POST');
+    assert.deepEqual(rehydrate.body, { resourceId: RESOURCE });
+    await until(
+      () => calls.some((call) => call.path === '/state/shared/attachments/claim'),
+      'the attachment drain that carries the rehydration',
+    );
+
+    // A join failure that is not about the tail must not trigger rehydration.
+    const rehydrations = () => calls.filter((call) => call.path === '/state/shared/replicas/rehydrate').length;
+    const before = rehydrations();
+    sentFrames.length = 0;
+    tunnel.enable(['shared.mutation.v1']); // re-pump: a fresh join for the same replica
+    await until(
+      () => sentFrames.some((frame) => frame.type === 'shared.resource.join'),
+      'the second join',
+    );
+    const secondJoin = sentFrames.find((frame) => frame.type === 'shared.resource.join');
+    tunnel.handleFrame({
+      type: 'shared.error',
+      request_id: secondJoin.request_id,
+      resource_id: RESOURCE,
+      code: 'shared_resource_read_forbidden',
+      message: 'shared resource is unavailable',
+      status: 403,
+      retryable: false,
+    });
+    await sleep(50);
+    assert.equal(rehydrations(), before, 'a permission failure is not a rehydration signal');
+  } finally {
+    tunnel.stop();
+    server.close();
+  }
+});

package/runtime/scripts/amalgm-mcp/tests/state-shared-replica.test.js

@@ -463,3 +463,68 @@ test('an executable file stays executable through a live write', () => {
     committedAt: '2026-07-15T20:00:03.000Z',
   });
 });
+
+// Compaction on the authority prunes official rows the moment a verified
+// snapshot covers them (past the retention window). A replica whose cursor
+// fell behind that floor recovers through a fresh snapshot attachment — and
+// because applying a full Yjs state is a CRDT merge, its unsynced local
+// edits survive the jump.
+test('a pruned-tail replica rehydrates: snapshot merge keeps unsynced local edits and jumps the cursor', () => {
+  const recipientResourceId = 'shr_qrstuvwxyzabcdef';
+  const recipientPath = path.join(docDir, 'recipient.md');
+  const opened = docs.openDoc(recipientPath);
+
+  // An unsynced local edit: journaled for the cloud, never acknowledged.
+  const client = clientFromState(opened.state);
+  const localUpdate = captureEdit(client, (text) => text.insert(0, 'local-unsynced '));
+  docs.applyDocMutations(recipientPath, [
+    { mutationId: 'mut_rehydrate_local_1', update: localUpdate },
+  ]);
+
+  // Meanwhile the cloud moved to version 40 and pruned the tail. Its
+  // snapshot contains an edit this replica never received.
+  const cloudDoc = clientFromState(opened.state);
+  cloudDoc.getText('content').insert(cloudDoc.getText('content').length, 'cloud-edit\n');
+  const cloudSnapshot = Buffer.from(Y.encodeStateAsUpdate(cloudDoc));
+  const checksum = require('crypto').createHash('sha256').update(cloudSnapshot).digest('hex');
+
+  const { requestRehydration } = require('../state/attachments');
+  const requested = requestRehydration({ resourceId: recipientResourceId });
+  assert.equal(requested.requeued, true, 'the original attachment row is the durable request');
+  assert.equal(requested.attachment.state, 'pending');
+  const claims = claimAttachments();
+  assert.ok(claims.some((claim) => claim.attachmentId === requested.attachment.attachmentId));
+
+  const attached = acknowledgeAttachment(requested.attachment.attachmentId, {
+    resourceId: recipientResourceId,
+    authorityEpoch: 3,
+    headVersion: 40,
+    snapshotVersion: 40,
+    snapshotChecksum: checksum,
+    snapshotBase64: cloudSnapshot.toString('base64'),
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+  });
+  assert.equal(attached.attachment.state, 'attached');
+
+  const replica = getReplicaByResourceId(recipientResourceId);
+  assert.equal(replica.appliedVersion, 40, 'the cursor jumps to the snapshot');
+  assert.equal(replica.snapshotVersion, 40);
+
+  const text = fs.readFileSync(recipientPath, 'utf8');
+  assert.ok(text.includes('local-unsynced '), 'the unsynced local edit survives rehydration');
+  assert.ok(text.includes('cloud-edit'), 'the official cloud state arrives');
+
+  // The local edit is still owed to the cloud: rehydration never empties the outbox.
+  const pending = getMutation(`resource:${recipientResourceId}`, 'mut_rehydrate_local_1');
+  assert.notEqual(pending.state, 'synced');
+});
+
+test('a promotion-born replica (which never attached) gets an attachment row for rehydration', () => {
+  const { requestRehydration } = require('../state/attachments');
+  const requested = requestRehydration({ resourceId });
+  assert.equal(requested.requeued, false, 'the sharer has no attachment history; one is created');
+  assert.equal(requested.attachment.state, 'pending');
+  assert.equal(requested.attachment.resourceId, resourceId);
+  assert.equal(requested.attachment.localPath, target);
+});

package/runtime/scripts/amalgm-mcp/tests/windows-release-publish.test.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const test = require('node:test');
+
+test('Windows publisher uploads local artifacts and activates the web download', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-windows-publish-'));
+  const buildDir = path.join(tempRoot, 'build');
+  const dataRoot = path.join(tempRoot, 'data');
+  const uploadToken = 'windows-publish-test-token';
+  fs.mkdirSync(buildDir, { recursive: true });
+  fs.writeFileSync(path.join(buildDir, 'amalgm-local-ui-0.1.201-x64.exe'), 'fake windows installer');
+  fs.writeFileSync(path.join(buildDir, 'amalgm-local-ui-0.1.201-x64.exe.blockmap'), 'fake blockmap');
+  fs.writeFileSync(path.join(buildDir, 'latest.yml'), [
+    'version: 0.1.201',
+    'path: amalgm-local-ui-0.1.201-x64.exe',
+    'sha512: fake-sha',
+    '',
+  ].join('\n'));
+
+  const previousDataRoot = process.env.DATA_ROOT;
+  const previousUploadToken = process.env.UPLOAD_TOKEN;
+  process.env.DATA_ROOT = dataRoot;
+  process.env.UPLOAD_TOKEN = uploadToken;
+  const serverPath = path.resolve(__dirname, '../../../../infra/desktop-release-server/server.js');
+  delete require.cache[serverPath];
+  const { createServer } = require(serverPath);
+  const server = createServer();
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address();
+
+  try {
+    const scriptPath = path.resolve(__dirname, '../../../../scripts/publish-windows-release.mjs');
+    const child = spawn(process.execPath, [scriptPath, 'main'], {
+      cwd: path.resolve(__dirname, '../../../..'),
+      env: {
+        ...process.env,
+        AMALGM_WINDOWS_BUILD_DIR: buildDir,
+        AMALGM_DESKTOP_RELEASE_UPLOAD_URL: `http://127.0.0.1:${port}`,
+        AMALGM_DESKTOP_RELEASE_UPLOAD_TOKEN: uploadToken,
+        AMALGM_DESKTOP_ENGINE_SHA: 'engine-test-sha',
+        AMALGM_DESKTOP_UI_SHA: 'ui-test-sha',
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    const status = await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        child.kill('SIGKILL');
+        reject(new Error('Windows publisher test timed out'));
+      }, 30_000);
+      child.once('error', (error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+      child.once('exit', (code) => {
+        clearTimeout(timer);
+        resolve(code);
+      });
+    });
+
+    assert.equal(status, 0, [stdout, stderr].filter(Boolean).join('\n'));
+    assert.equal(fs.existsSync(path.join(dataRoot, 'main', 'amalgm-local-ui-0.1.201-x64.exe')), true);
+    assert.equal(fs.existsSync(path.join(dataRoot, 'main', 'latest.yml')), true);
+    const metadata = JSON.parse(fs.readFileSync(path.join(dataRoot, 'main', 'desktop-release.windows.json'), 'utf8'));
+    assert.equal(metadata.version, '0.1.201');
+    assert.equal(metadata.primaryDownload.kind, 'exe');
+    assert.equal(metadata.uiSha, 'ui-test-sha');
+
+    const response = await fetch(`http://127.0.0.1:${port}/main/download/exe`, { redirect: 'manual' });
+    assert.equal(response.status, 302);
+    assert.match(response.headers.get('location'), /amalgm-local-ui-0\.1\.201-x64\.exe/);
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+    if (previousDataRoot === undefined) delete process.env.DATA_ROOT;
+    else process.env.DATA_ROOT = previousDataRoot;
+    if (previousUploadToken === undefined) delete process.env.UPLOAD_TOKEN;
+    else process.env.UPLOAD_TOKEN = previousUploadToken;
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+});