amalgm 0.1.239 → 0.1.241

package/lib/shared-realtime-tunnel.js

@@ -545,9 +545,13 @@ function createSharedRealtimeTunnel({
       void localStateJson('POST', '/state/shared/attachments/fail', {
         attachmentId: identity.attachmentId,
         message: error?.message || 'local snapshot materialization failed',
-        retryable: false,
+        // The gateway already authorized and completed this attachment.
+        // A local materialization failure is weather (busy disk, concurrent
+        // save, restart), never proof that the binding is permanently bad.
+        retryable: true,
       }).catch(() => {});
       attachmentInflight.delete(frame.request_id);
+      scheduleAttachmentDrain(RETRY_MS);
     });
   }
 
@@ -614,9 +618,18 @@ function createSharedRealtimeTunnel({
   }
 
   function handleError(frame) {
-    if (repoUploadInflight.has(frame.request_id)) {
-      repoUploadInflight.delete(frame.request_id);
-      scheduleRepoObjects(RETRY_MS);
+    const failedUpload = repoUploadInflight.get(frame.request_id);
+    if (failedUpload) {
+      void localStateJson('POST', '/state/repo-objects/uploads/fail', {
+        resourceId: failedUpload.resourceId,
+        sha256: failedUpload.sha256,
+        retryable: frame.retryable !== false,
+        code: frame.code,
+        message: frame.message,
+      }).finally(() => {
+        repoUploadInflight.delete(frame.request_id);
+        scheduleRepoObjects();
+      });
       return;
     }
     if (repoDownloadInflight.has(frame.request_id)) {
@@ -697,6 +710,7 @@ function createSharedRealtimeTunnel({
     void localStateJson('POST', '/state/mutations/fail', {
       resourceId: identity.resourceId,
       mutationId: identity.mutationId,
+      code: frame.code,
       message: `${frame.code || 'shared_error'}: ${frame.message || 'shared mutation failed'}`,
       retryable: frame.retryable !== false,
     }).finally(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.239",
+  "version": "0.1.241",
   "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

@@ -599,18 +599,26 @@ function getCookieCloudBootstrap(options = {}) {
 
 function installCookieCloudBootstrap(input = {}, options = {}) {
   const database = options.database || require('../state/db').openLocalDb();
-  const replica = cookieCloudReplica({ database });
-  if (!replica || input.resourceId !== replica.resourceId) {
+  const replicas = require('../state/replicas');
+  const envelope = replicas.validateSnapshotEnvelope(input, {
+    contract: COOKIE_CLOUD_CONTRACT,
+    schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
+  });
+  const expectedResourceId = privateCookieResourceId(
+    require('../workspace/identity').userId(),
+  );
+  if (!expectedResourceId || envelope.resourceId !== expectedResourceId) {
     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')));
+  if (remote.version !== envelope.snapshotVersion) {
+    throw new Error('Private cookie snapshot version mismatch');
+  }
+  const replica = cookieCloudReplica({ database });
   const pending = require('../state/mutations').listPendingCloudMutations(replica.resourceId, { database });
   const pendingKeys = new Set(pending.map((mutation) => mutation.operation?.key).filter(Boolean));
   // A base snapshot behind the official head is not the current cloud jar.
@@ -618,28 +626,62 @@ function installCookieCloudBootstrap(input = {}, options = {}) {
   // as pre-cloud work and create an echo loop on every reconnect. The gateway
   // normally compacts private resources to head before bootstrap; this guard
   // makes the runtime fail closed if an older gateway sends a stale base.
-  const snapshotIsCurrent = Number(input.snapshotVersion) >= Number(input.headVersion);
+  const snapshotIsCurrent = envelope.snapshotVersion === envelope.headVersion;
   const bootstrapOperations = snapshotIsCurrent
     ? localBootstrapOperations(local, remote, pendingKeys)
     : [];
 
+  if (!snapshotIsCurrent) {
+    // A stale prefix is useful only as an identity check for a prefix this
+    // machine has already applied. Advancing to a newer stale prefix without
+    // installing its bytes would make the cursor lie; installing it would
+    // overwrite local legacy state before a head snapshot can classify it.
+    const currentReplica = replicas.refreshReplicaAuthority({
+      resourceId: replica.resourceId,
+      authorityEpoch: envelope.authorityEpoch,
+      headVersion: envelope.headVersion,
+      contract: COOKIE_CLOUD_CONTRACT,
+      schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
+    }, { database });
+    return {
+      replica: currentReplica,
+      jar: readCookieJar(),
+      bootstrappedMutations: 0,
+      bootstrapDeferred: true,
+    };
+  }
+
+  // Legacy local values become durable mutations before the official
+  // snapshot can replace the physical jar. If the process dies after the
+  // replacement, restart can replay these rows; in-memory bootstrapOperations
+  // are never the only copy of user state.
+  let currentReplica = replica;
+  for (const operation of bootstrapOperations) {
+    commitCookieOperation(operation, currentReplica, { database });
+    currentReplica = cookieCloudReplica({ database });
+  }
+  const durablePending = require('../state/mutations')
+    .listPendingCloudMutations(replica.resourceId, { database });
+
   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,
+  if (options.testHooks?.crashAfterSnapshotPersist === true) {
+    throw new Error('simulated cookie bootstrap crash after snapshot persist');
+  }
+  replicas.advanceReplicaSnapshot({
+      resourceId: replica.resourceId,
+      snapshotVersion: envelope.snapshotVersion,
+      snapshotChecksum: checksum,
+      authorityEpoch: envelope.authorityEpoch,
   }, { database });
-  refreshReplicaAuthority({
+  replicas.refreshReplicaAuthority({
     resourceId: replica.resourceId,
-    authorityEpoch: Number(input.authorityEpoch) || 1,
-    headVersion: Number(input.headVersion) || 0,
+    authorityEpoch: envelope.authorityEpoch,
+    headVersion: envelope.headVersion,
     contract: COOKIE_CLOUD_CONTRACT,
     schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
   }, { database });
@@ -647,12 +689,18 @@ function installCookieCloudBootstrap(input = {}, options = {}) {
   // 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 });
+  for (const mutation of durablePending) {
+    materializeCookieOperation(mutation.operation);
+    if (mutation.state === 'saving-local' && mutation.materializedAt === null) {
+      require('../state/mutations').completeMaterializedMutation(
+        mutation.channelId,
+        mutation.mutationId,
+        cookieEvent(mutation.operation, mutation.mutationId),
+        { database },
+      );
+    }
   }
+  currentReplica = cookieCloudReplica({ database });
   return {
     replica: currentReplica,
     jar: readCookieJar(),

package/runtime/scripts/amalgm-mcp/project-context/store.js

@@ -16,9 +16,9 @@
  *   system-instructions.md    global user-authored instructions under AMALGM_DIR
  *
  * Direct disk edits (editors, agents with their own file tools) are picked up
- * by the per-project fs watcher and the fs REST hooks, which funnel into the
- * same reconcile path. Reconcile is idempotent: unchanged revisions emit no
- * events.
+ * by the per-project fs watcher, a bounded verifier for notifications the OS
+ * may drop, and the fs REST hooks. All three funnel into the same reconcile
+ * path. Reconcile is idempotent: unchanged revisions emit no events.
  *
  * Everything that emits events runs in the amalgm-mcp process — Local Live
  * only streams events appended in-process. chat-core (chat-server process)
@@ -56,11 +56,13 @@ const {
 
 const RESOURCE = 'project_context';
 const WATCH_DEBOUNCE_MS = 200;
+const WATCH_VERIFY_MS = 5_000;
 // The system scope carries user-authored instructions that apply to every
 // session on this computer. It has no change log or project state.
 const SYSTEM_CONTEXT_ID = 'system';
 
-const watchers = new Map(); // projectId -> { watcher, timer, projectPath }
+const watchers = new Map(); // projectId -> { watcher, timer, project, projectPath }
+let watchVerificationTimer = null;
 
 function systemProject() {
   return { id: SYSTEM_CONTEXT_ID, path: path.resolve(AMALGM_DIR), name: 'Amalgm System' };
@@ -683,12 +685,50 @@ function closeWatcher(projectId) {
   const entry = watchers.get(projectId);
   if (!entry) return;
   if (entry.timer) clearTimeout(entry.timer);
-  try {
-    entry.watcher.close();
-  } catch {
-    // Already closed.
+  if (entry.watcher) {
+    try {
+      entry.watcher.close();
+    } catch {
+      // Already closed.
+    }
   }
   watchers.delete(projectId);
+  if (watchers.size === 0 && watchVerificationTimer) {
+    clearInterval(watchVerificationTimer);
+    watchVerificationTimer = null;
+  }
+}
+
+/**
+ * `fs.watch` is a latency hint, not durable evidence: kernels may coalesce or
+ * drop notifications. This bounded pass owns that wait and makes every
+ * watched context converge even when no callback arrives.
+ */
+function verifyProjectContextWatchers() {
+  for (const entry of watchers.values()) {
+    try {
+      reconcileProjectContext(entry.project, { source: 'project-context:verify' });
+      if (!entry.watcher) {
+        entry.watcher = openProjectContextWatcher(entry.project);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(
+        `[ProjectContext] Bounded verify failed for ${entry.projectPath}: ${message}`,
+      );
+    }
+  }
+}
+
+function ensureWatchVerification() {
+  if (watchVerificationTimer || watchers.size === 0) return;
+  watchVerificationTimer = setInterval(
+    verifyProjectContextWatchers,
+    WATCH_VERIFY_MS,
+  );
+  if (typeof watchVerificationTimer.unref === 'function') {
+    watchVerificationTimer.unref();
+  }
 }
 
 /**
@@ -697,13 +737,7 @@ function closeWatcher(projectId) {
  * harmless: by the time the debounce fires, disk matches the row and no event
  * is emitted.
  */
-function watchProjectContext(input) {
-  const project = projectFromInput(input);
-  if (!project?.id || !project?.path) return;
-  const existing = watchers.get(project.id);
-  if (existing?.projectPath === project.path) return;
-  if (existing) closeWatcher(project.id);
-
+function openProjectContextWatcher(project) {
   const root = contextPathsFor(project).root;
   let watcher;
   try {
@@ -723,12 +757,46 @@ function watchProjectContext(input) {
       if (typeof entry.timer.unref === 'function') entry.timer.unref();
     });
   } catch {
-    // Context dir missing or unwatchable — best effort; REST hooks still cover writes.
-    return;
+    // The bounded verifier remains the durable fallback and retries this hint.
+    return null;
   }
-  watcher.on('error', () => closeWatcher(project.id));
+  watcher.on('error', () => {
+    const entry = watchers.get(project.id);
+    if (!entry || entry.watcher !== watcher) return;
+    try {
+      watcher.close();
+    } catch {
+      // Already closed.
+    }
+    entry.watcher = null;
+  });
   if (typeof watcher.unref === 'function') watcher.unref();
-  watchers.set(project.id, { watcher, timer: null, projectPath: project.path });
+  return watcher;
+}
+
+function watchProjectContext(input) {
+  const project = projectFromInput(input);
+  if (!project?.id || !project?.path) return;
+  const existing = watchers.get(project.id);
+  if (existing?.projectPath === project.path) {
+    existing.project = project;
+    if (!existing.watcher) {
+      existing.watcher = openProjectContextWatcher(project);
+    }
+    ensureWatchVerification();
+    return;
+  }
+  if (existing) closeWatcher(project.id);
+
+  const entry = {
+    watcher: null,
+    timer: null,
+    project,
+    projectPath: project.path,
+  };
+  watchers.set(project.id, entry);
+  entry.watcher = openProjectContextWatcher(project);
+  ensureWatchVerification();
 }
 
 /** fs REST hook: reconcile when a context doc is touched outside the store. */

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

@@ -59,6 +59,19 @@ async function handleStateRoutes(ctx) {
       ));
       return true;
     }
+    if (ctx.pathname === '/state/repo-objects/uploads/fail') {
+      const body = await ctx.readJsonBody();
+      ctx.sendJson(200, require('../../workspace/objects').failUpload(
+        body?.resourceId,
+        body?.sha256,
+        {
+          retryable: body?.retryable,
+          code: body?.code,
+          message: body?.message,
+        },
+      ));
+      return true;
+    }
     if (ctx.pathname === '/state/repo-objects/downloads/claim') {
       ctx.sendJson(200, { download: require('../../workspace/objects').claimDownload() });
       return true;

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

@@ -4,7 +4,7 @@ const crypto = require('crypto');
 
 const { cachedStatement, openLocalDb } = require('./db');
 const { isSharedResourceId } = require('./cloud-resource-id');
-const { appendStateEvent } = require('./events');
+const { appendStateEvent, insertStateEvent } = require('./events');
 
 const ATTACHMENT_ID = /^[A-Za-z0-9_-]{16,160}$/;
 
@@ -30,6 +30,10 @@ function normalizeRow(row) {
     attemptCount: Number(row.attempt_count),
     nextAttemptAt: row.next_attempt_at || null,
     lastError: row.last_error || null,
+    // Legacy requests predate the fence. Their target was required to be
+    // empty, so zero is the only conservative boundary: every surviving or
+    // newly captured local mutation remains overlay.
+    journalCursor: row.journal_cursor == null ? 0 : Number(row.journal_cursor),
     createdAt: row.created_at,
     updatedAt: row.updated_at,
   };
@@ -54,12 +58,16 @@ function enqueueAttachment(input, options = {}) {
     return { attachment, duplicate: true };
   }
   const now = new Date().toISOString();
+  const journalCursor = Number(
+    cachedStatement(database, 'SELECT COALESCE(MAX(journal_id), 0) AS cursor FROM mutation_journal')
+      .get().cursor,
+  );
   try {
     cachedStatement(database, `
       INSERT INTO shared_resource_attachments (
-        attachment_id, resource_id, local_path, created_at, updated_at
-      ) VALUES (?, ?, ?, ?, ?)
-    `).run(attachmentId, resourceId, localPath, now, now);
+        attachment_id, resource_id, local_path, journal_cursor, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?)
+    `).run(attachmentId, resourceId, localPath, journalCursor, now, now);
   } catch (error) {
     if (String(error?.code || '').includes('CONSTRAINT')) {
       throw invalid('that resource or local path already has an attachment request', 409);
@@ -70,14 +78,22 @@ function enqueueAttachment(input, options = {}) {
     cachedStatement(database, 'SELECT * FROM shared_resource_attachments WHERE attachment_id = ?')
       .get(attachmentId),
   );
-  appendStateEvent({
+  const eventInput = {
     resource: 'shared:attachments',
     op: 'update',
     id: attachmentId,
     sharedResourceId: resourceId,
     value: { state: 'pending' },
     source: 'shared:attachment',
-  });
+  };
+  if (options.deferEvent === true) {
+    return {
+      attachment,
+      duplicate: false,
+      deferredEvent: insertStateEvent(database, eventInput),
+    };
+  }
+  appendStateEvent(eventInput);
   return { attachment, duplicate: false };
 }
 
@@ -129,13 +145,16 @@ function acknowledgeAttachment(attachmentIdInput, payload, options = {}) {
 
   const installed = payload?.contract === 'workspace-tree@1'
     ? require('../workspace/tree-store').installCloudTreeSnapshot(attachment.localPath, payload, { database })
-    : payload?.contract === 'code-project-stream@1'
+    : payload?.contract === 'code-project-stream@2'
       ? require('../workspace/project-stream').installSnapshot(
         attachment.localPath,
         payload,
         { database },
       )
-      : require('./docs').installCloudDocSnapshot(attachment.localPath, payload);
+      : require('./docs').installCloudDocSnapshot(attachment.localPath, {
+        ...payload,
+        attachmentJournalCursor: attachment.journalCursor,
+      });
   const now = new Date().toISOString();
   cachedStatement(database, `
     UPDATE shared_resource_attachments
@@ -200,21 +219,30 @@ function requestRehydration(input, options = {}) {
   let attachmentId;
   if (existing) {
     attachmentId = existing.attachment_id;
+    const journalCursor = Number(
+      cachedStatement(database, 'SELECT COALESCE(MAX(journal_id), 0) AS cursor FROM mutation_journal')
+        .get().cursor,
+    );
     cachedStatement(database, `
       UPDATE shared_resource_attachments
       SET attachment_state = 'pending',
           next_attempt_at = NULL,
           last_error = NULL,
+          journal_cursor = ?,
           updated_at = ?
       WHERE attachment_id = ?
-    `).run(now, attachmentId);
+    `).run(journalCursor, now, attachmentId);
   } else {
     attachmentId = `att_${crypto.randomBytes(16).toString('base64url')}`;
+    const journalCursor = Number(
+      cachedStatement(database, 'SELECT COALESCE(MAX(journal_id), 0) AS cursor FROM mutation_journal')
+        .get().cursor,
+    );
     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);
+        attachment_id, resource_id, local_path, journal_cursor, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?)
+    `).run(attachmentId, resourceId, replica.localPath, journalCursor, now, now);
   }
   const attachment = normalizeRow(
     cachedStatement(database, 'SELECT * FROM shared_resource_attachments WHERE attachment_id = ?')