amalgm 0.1.148 → 0.1.149

package/package.json

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

package/runtime/scripts/amalgm-mcp/apps/health.js

@@ -0,0 +1,216 @@
+/**
+ * App health contract — the push side of supervision.
+ *
+ * Apps announce their own liveness; the runtime never probes them. Two
+ * signals cover every failure mode:
+ *
+ *   - process exit events (supervisor.js) detect death — instant and free
+ *   - missed heartbeats (this module) detect zombies: alive but hung
+ *
+ * An app opts in by POSTing /apps/ready (or just /apps/heartbeat) using the
+ * AMALGM_MCP_URL + AMALGM_RUNTIME_TOKEN already in its environment. Apps that
+ * never opt in keep exactly today's behavior: the runtime spends zero effort
+ * on them beyond watching the exit event.
+ *
+ * Liveness bookkeeping lives in memory: a heartbeat is runtime-scoped truth
+ * (a restarted runtime starts blank and apps re-announce), and persisting
+ * every beat would churn apps.json + the state stream for no reader. Only
+ * *transitions* (ready, running<->unresponsive) touch the app record.
+ */
+
+const { getApp, updateAppMeta } = require('./store');
+const { syncAppRoutesToGateway } = require('./advertise');
+
+const APP_HEALTH_POLICY = {
+  defaultIntervalMs: 30_000,
+  minIntervalMs: 5_000,
+  maxIntervalMs: 300_000,
+  // Beats an app may miss before it is considered unresponsive.
+  missedBeats: 3,
+  sweepIntervalMs: 10_000,
+};
+
+// appId -> { readyAt, lastHeartbeatAt, intervalMs } (epoch ms)
+const enrolled = new Map();
+let sweepTimer = null;
+
+function clampIntervalMs(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return APP_HEALTH_POLICY.defaultIntervalMs;
+  return Math.min(Math.max(parsed, APP_HEALTH_POLICY.minIntervalMs), APP_HEALTH_POLICY.maxIntervalMs);
+}
+
+function unresponsiveAfterMs(entry) {
+  return entry.intervalMs * APP_HEALTH_POLICY.missedBeats;
+}
+
+// A beat only counts for an app the supervisor wants running. Anything else
+// (stopped, degraded, mid-restart) is a straggler process talking past its
+// lifecycle; enrolling it would resurrect state the supervisor just settled.
+function acceptsHealthSignals(app) {
+  return Boolean(
+    app
+    && app.desiredState === 'running'
+    && (app.status === 'running' || app.status === 'unresponsive'),
+  );
+}
+
+function snapshotEntry(appId, entry, now = Date.now()) {
+  return {
+    appId,
+    readyAt: entry.readyAt ? new Date(entry.readyAt).toISOString() : null,
+    lastHeartbeatAt: entry.lastHeartbeatAt ? new Date(entry.lastHeartbeatAt).toISOString() : null,
+    heartbeatIntervalMs: entry.intervalMs,
+    heartbeatAgeMs: entry.lastHeartbeatAt ? Math.max(0, now - entry.lastHeartbeatAt) : null,
+  };
+}
+
+async function syncRoutesBestEffort(reason) {
+  try {
+    await syncAppRoutesToGateway(reason);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`[Apps] App route sync failed (${reason}): ${message}`);
+  }
+}
+
+function recoverIfUnresponsive(app, now) {
+  if (app.status !== 'unresponsive') return;
+  console.log(`[App:${app.id}] heartbeat resumed; marking running again`);
+  updateAppMeta(app.id, {
+    status: 'running',
+    error: null,
+    lastHeartbeatAt: new Date(now).toISOString(),
+  });
+  void syncRoutesBestEffort(`heartbeat-recovered:${app.id}`);
+}
+
+/**
+ * The app announced it is up. Optional first call — a bare heartbeat enrolls
+ * too — but ready() is the place to declare a custom heartbeat interval and
+ * it stamps readyAt on the record once per process generation.
+ */
+function recordReady(appId, options = {}, now = Date.now()) {
+  const app = getApp(appId);
+  if (!app) return { accepted: false, reason: 'not_found' };
+  if (!acceptsHealthSignals(app)) return { accepted: false, reason: `status_${app.status}` };
+
+  const entry = {
+    readyAt: now,
+    lastHeartbeatAt: now,
+    intervalMs: clampIntervalMs(options.heartbeatIntervalMs),
+  };
+  enrolled.set(appId, entry);
+
+  updateAppMeta(appId, {
+    readyAt: new Date(now).toISOString(),
+    lastHeartbeatAt: new Date(now).toISOString(),
+    heartbeatIntervalMs: entry.intervalMs,
+  });
+  recoverIfUnresponsive(app, now);
+  return { accepted: true, health: snapshotEntry(appId, entry, now) };
+}
+
+/**
+ * Periodic "still fine" from the app. Memory-only on the steady path; touches
+ * the record only when it flips an unresponsive app back to running.
+ */
+function recordHeartbeat(appId, now = Date.now()) {
+  let entry = enrolled.get(appId);
+  if (!entry) {
+    // First contact from this process generation: validate against the store
+    // once, then stay off disk for every subsequent beat.
+    const app = getApp(appId);
+    if (!app) return { accepted: false, reason: 'not_found' };
+    if (!acceptsHealthSignals(app)) return { accepted: false, reason: `status_${app.status}` };
+    entry = {
+      readyAt: null,
+      lastHeartbeatAt: now,
+      intervalMs: clampIntervalMs(app.heartbeatIntervalMs),
+    };
+    enrolled.set(appId, entry);
+    recoverIfUnresponsive(app, now);
+    return { accepted: true, health: snapshotEntry(appId, entry, now) };
+  }
+
+  const wasOverdue = now - entry.lastHeartbeatAt > unresponsiveAfterMs(entry);
+  entry.lastHeartbeatAt = now;
+  if (wasOverdue) {
+    const app = getApp(appId);
+    if (app) recoverIfUnresponsive(app, now);
+  }
+  return { accepted: true, health: snapshotEntry(appId, entry, now) };
+}
+
+/** Live view for list/status surfaces. Null for apps that never enrolled. */
+function healthSnapshot(appId, now = Date.now()) {
+  const entry = enrolled.get(appId);
+  return entry ? snapshotEntry(appId, entry, now) : null;
+}
+
+/**
+ * Forget an app's enrollment. Called by the supervisor whenever the process
+ * generation ends (exit, stop, delete) — the next process must re-announce.
+ */
+function clearAppHealth(appId) {
+  enrolled.delete(appId);
+}
+
+/**
+ * One monitor pass. Pure bookkeeping over the in-memory map — no process
+ * probing, no disk reads unless an app actually transitions. Exported so
+ * tests can drive time explicitly instead of racing timers.
+ */
+function sweepOnce(now = Date.now()) {
+  const transitioned = [];
+  for (const [appId, entry] of enrolled) {
+    if (now - entry.lastHeartbeatAt <= unresponsiveAfterMs(entry)) continue;
+
+    const app = getApp(appId);
+    if (!app || app.desiredState !== 'running' || app.status !== 'running') {
+      // Lifecycle moved on (stopped/degraded/deleted); the supervisor owns
+      // that state — drop the stale enrollment instead of fighting it.
+      if (!app || app.status === 'stopped' || app.status === 'degraded') enrolled.delete(appId);
+      continue;
+    }
+
+    const silentSeconds = Math.round((now - entry.lastHeartbeatAt) / 1000);
+    console.error(`[App:${appId}] unresponsive: no heartbeat for ${silentSeconds}s (expected every ${Math.round(entry.intervalMs / 1000)}s)`);
+    updateAppMeta(appId, {
+      status: 'unresponsive',
+      error: `No heartbeat for ${silentSeconds}s (app declared one every ${Math.round(entry.intervalMs / 1000)}s). Process is alive but not responding.`,
+      lastHeartbeatAt: new Date(entry.lastHeartbeatAt).toISOString(),
+    });
+    void syncRoutesBestEffort(`unresponsive:${appId}`);
+    transitioned.push(appId);
+  }
+  return transitioned;
+}
+
+function startHealthMonitor() {
+  if (sweepTimer) return;
+  sweepTimer = setInterval(() => {
+    try {
+      sweepOnce();
+    } catch (err) {
+      console.warn('[Apps] Health sweep failed:', err instanceof Error ? err.message : String(err));
+    }
+  }, APP_HEALTH_POLICY.sweepIntervalMs);
+  sweepTimer.unref();
+}
+
+function stopHealthMonitor() {
+  if (sweepTimer) clearInterval(sweepTimer);
+  sweepTimer = null;
+}
+
+module.exports = {
+  APP_HEALTH_POLICY,
+  clearAppHealth,
+  healthSnapshot,
+  recordHeartbeat,
+  recordReady,
+  startHealthMonitor,
+  stopHealthMonitor,
+  sweepOnce,
+};

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

@@ -3,6 +3,7 @@
  */
 
 const { getApp, getConnectedRoutes, loadApps, updateAppMeta } = require('./store');
+const { healthSnapshot, recordHeartbeat, recordReady } = require('./health');
 const {
   deleteApp,
   connectDns,
@@ -32,6 +33,14 @@ function appPayload(app, options = {}) {
   return options.legacy ? { artifact: legacyApp(app) } : { app };
 }
 
+// The persisted record carries health *transitions* (readyAt, status flips);
+// per-beat liveness lives in memory only. List responses merge the live view
+// in under `health` so readers see heartbeat age without apps.json churn.
+function withLiveHealth(app) {
+  const health = healthSnapshot(app.id);
+  return health ? { ...app, health } : app;
+}
+
 async function handleList(sendJson, options = {}) {
   const data = loadApps();
   if (options.legacy) {
@@ -40,7 +49,7 @@ async function handleList(sendJson, options = {}) {
       artifacts: data.apps.map(legacyApp),
     });
   }
-  sendJson(200, data);
+  sendJson(200, { version: data.version, apps: data.apps.map(withLiveHealth) });
 }
 
 async function handleRoutes(sendJson, options = {}) {
@@ -131,6 +140,31 @@ async function handleUpdate(body, sendJson, options = {}) {
   }
 }
 
+// Health contract endpoints. Called by the app itself (it has AMALGM_MCP_URL
+// + AMALGM_RUNTIME_TOKEN in its env), so they must stay cheap: heartbeat is
+// memory-only after first contact.
+async function handleReady(body, sendJson) {
+  const appId = appIdFromBody(body);
+  if (!appId) return sendJson(400, { error: 'app_id is required' });
+  const result = recordReady(appId, {
+    heartbeatIntervalMs: body?.heartbeat_interval_ms ?? body?.heartbeatIntervalMs,
+  });
+  if (!result.accepted && result.reason === 'not_found') {
+    return sendJson(404, { error: 'App not found' });
+  }
+  sendJson(200, { ok: result.accepted, ...(result.reason ? { reason: result.reason } : {}), health: result.health || null });
+}
+
+async function handleHeartbeat(body, sendJson) {
+  const appId = appIdFromBody(body);
+  if (!appId) return sendJson(400, { error: 'app_id is required' });
+  const result = recordHeartbeat(appId);
+  if (!result.accepted && result.reason === 'not_found') {
+    return sendJson(404, { error: 'App not found' });
+  }
+  sendJson(200, { ok: result.accepted, ...(result.reason ? { reason: result.reason } : {}), health: result.health || null });
+}
+
 async function handleConnectDns(body, sendJson, options = {}) {
   try {
     const appId = appIdFromBody(body);
@@ -157,7 +191,9 @@ module.exports = {
   handleConnectDns,
   handleDelete,
   handleDisconnectDns,
+  handleHeartbeat,
   handleList,
+  handleReady,
   handleRedeploy,
   handleRegister,
   handleRoutes,

package/runtime/scripts/amalgm-mcp/apps/store.js

@@ -164,6 +164,9 @@ function getConnectedRoutes() {
       && app.status !== 'stopped'
       && app.status !== 'error'
       && app.status !== 'degraded'
+      // Declared a heartbeat and stopped sending it: alive but hung. Routing
+      // traffic to a zombie is worse than routing none.
+      && app.status !== 'unresponsive'
       && app.port
       && app.appRef,
     )

package/runtime/scripts/amalgm-mcp/apps/supervisor.js

@@ -11,6 +11,7 @@ const { spawn } = require('child_process');
 const { APPS_DIR, DEFAULT_CWD } = require('../config');
 const { runtimePort } = require('../../../lib/runtime-manifest');
 const { syncAppRoutesToGateway } = require('./advertise');
+const { clearAppHealth } = require('./health');
 const {
   allocatePort,
   allocateUniqueAppRef,
@@ -346,6 +347,8 @@ function startAppProcess(app) {
     if (activeChild && activeChild !== child) return;
     running.delete(app.id);
     closeAppLog(app.id);
+    // This process generation is over; the next one must re-announce health.
+    clearAppHealth(app.id);
     const wasStopping = stopping.has(app.id);
     stopping.delete(app.id);
     if (wasStopping) return;
@@ -452,6 +455,10 @@ async function startApp(appId) {
     envFingerprint: runtimeEnvFingerprint(),
     error: null,
     lastStartedAt: new Date().toISOString(),
+    // Health announcements belong to a process generation; a fresh spawn
+    // starts unannounced until it calls /apps/ready or /apps/heartbeat.
+    readyAt: null,
+    lastHeartbeatAt: null,
   });
   await syncRoutesBestEffort(`start:${appId}`);
   return current;
@@ -477,6 +484,7 @@ async function stopApp(appId, options = {}) {
   });
   running.delete(appId);
   closeAppLog(appId);
+  clearAppHealth(appId);
 
   setTimeout(() => stopping.delete(appId), 1000);
   const current = updateAppMeta(appId, {

package/runtime/scripts/amalgm-mcp/apps/tools.js

@@ -8,6 +8,7 @@
 
 const { textResult, errorResult } = require('../lib/tool-result');
 const { getConnectedRoutes, loadApps } = require('./store');
+const { healthSnapshot } = require('./health');
 const {
   connectDns,
   disconnectDns,
@@ -17,6 +18,15 @@ const {
   stopApp,
 } = require('./supervisor');
 
+function healthSummary(app) {
+  const live = healthSnapshot(app.id);
+  if (live?.lastHeartbeatAt) {
+    return `health: heartbeat ${Math.round(live.heartbeatAgeMs / 1000)}s ago (every ${Math.round(live.heartbeatIntervalMs / 1000)}s)`;
+  }
+  if (app.readyAt) return `health: ready at ${app.readyAt}`;
+  return null;
+}
+
 function appSummary(app) {
   return [
     `${app.name} (${app.id})`,
@@ -26,6 +36,7 @@ function appSummary(app) {
     `dns: ${app.dnsConnected ? app.publicUrl : 'disconnected'}`,
     `autostart: ${app.autostart !== false}`,
     `keepAlive: ${app.keepAlive !== false}`,
+    healthSummary(app),
     app.error ? `error: ${app.error}` : null,
   ].filter(Boolean).join('\n');
 }

package/runtime/scripts/amalgm-mcp/automations/store.js

@@ -1052,6 +1052,13 @@ function listPublicAutomations() {
   return publicAutomationGraph().automations;
 }
 
+// One graph build for callers that need automations + triggers + workflows
+// together (the state snapshot); the per-list functions above each rebuild
+// the full graph.
+function listPublicAutomationGraph() {
+  return publicAutomationGraph();
+}
+
 function listTriggers() {
   return readAutomationGraph().triggers;
 }
@@ -1666,6 +1673,7 @@ module.exports = {
   listAutomationRuns,
   listAutomations,
   listEventTriggersForIngress,
+  listPublicAutomationGraph,
   listPublicAutomations,
   listPublicTriggers,
   listPublicWorkflows,

package/runtime/scripts/amalgm-mcp/index.js

@@ -101,6 +101,7 @@ async function boot() {
   const { ensureAgentsDirs } = require('./agents/store');
   const { ensureAppsDirs } = require('./apps/store');
   const { startAppRouteSyncLoop } = require('./apps/advertise');
+  const { startHealthMonitor } = require('./apps/health');
   const { startRegisteredApps } = require('./apps/supervisor');
   const { startProjectContextService } = require('./project-context/store');
 
@@ -111,6 +112,7 @@ async function boot() {
 
   await startRegisteredApps();
   startAppRouteSyncLoop();
+  startHealthMonitor();
   require('./state/ports').startPortsBridge();
 }
 

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

@@ -49,6 +49,14 @@ async function handleAppRoutes(ctx) {
     await appsRest.handleUpdate(await ctx.readJsonBody(), ctx.sendJson, options);
     return true;
   }
+  if (route.path === '/ready' && ctx.method === 'POST') {
+    await appsRest.handleReady(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (route.path === '/heartbeat' && ctx.method === 'POST') {
+    await appsRest.handleHeartbeat(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
   if (route.path === '/connect-dns' && ctx.method === 'POST') {
     await appsRest.handleConnectDns(await ctx.readJsonBody(), ctx.sendJson, options);
     return true;

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

@@ -444,81 +444,7 @@ function migrate(database = openLocalDb()) {
       ON browser_login_sessions(expires_at);
 
   `);
-  migrateLegacyToolboxTables(database);
-  removeInheritedHarnessTools(database);
-}
-
-function tableExists(database, tableName) {
-  const row = database.prepare(
-    "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?"
-  ).get(tableName);
-  return Boolean(row);
-}
-
-function migrateLegacyToolboxTables(database) {
-  if (tableExists(database, 'toolbox_tools')) {
-    database.prepare(`
-      INSERT OR IGNORE INTO tools (
-        id,
-        name,
-        type,
-        owner,
-        origin,
-        status,
-        updated_at,
-        tool_json
-      )
-      SELECT
-        id,
-        name,
-        type,
-        owner,
-        origin,
-        status,
-        updated_at,
-        tool_json
-      FROM toolbox_tools
-    `).run();
-  }
-
-  if (tableExists(database, 'toolbox_actions')) {
-    database.prepare(`
-      INSERT OR IGNORE INTO tool_actions (
-        id,
-        tool_id,
-        name,
-        status,
-        updated_at,
-        action_json
-      )
-      SELECT
-        legacy.id,
-        legacy.tool_id,
-        legacy.name,
-        legacy.status,
-        legacy.updated_at,
-        legacy.action_json
-      FROM toolbox_actions legacy
-      INNER JOIN tools ON tools.id = legacy.tool_id
-    `).run();
-  }
-}
-
-function removeInheritedHarnessTools(database) {
-  database.prepare(`
-    DELETE FROM tool_actions
-    WHERE tool_id IN (
-      SELECT id FROM tools
-      WHERE owner IN ('codex')
-        AND origin = 'catalog'
-    )
-  `).run();
-
-  database.prepare(`
-    DELETE FROM tools
-    WHERE owner IN ('codex')
-      AND origin = 'catalog'
-  `).run();
+  require('./migrations').runLegacyMigrations(database);
 }
 
 function closeLocalDb() {

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

@@ -6,11 +6,17 @@ const { openLocalDb } = require('./db');
 const emitter = new EventEmitter();
 emitter.setMaxListeners(200);
 
-const DEFAULT_EVENT_LOG_RETENTION_HOURS = 24;
+// The event log is a short reconnect buffer, not durable history: clients
+// bridge brief stream blips from it, and anything older is served better by a
+// fresh snapshot (the stream sends `reset` when history is gone). Kept just
+// long enough to ride out sleep/wake and flaky-network windows.
+const DEFAULT_EVENT_LOG_RETENTION_HOURS = 0.25;
 const DEFAULT_EVENT_LOG_PRUNE_BATCH_SIZE = 1000;
 const DEFAULT_EVENT_LOG_PRUNE_INTERVAL_MS = 60_000;
+const EVENT_LOG_PRUNE_DELAY_MS = 1_000;
 
 let lastPruneAttemptAt = 0;
+let pruneTimer = null;
 
 function positiveNumber(value, fallback) {
   const parsed = Number(value);
@@ -111,7 +117,19 @@ function insertStateEvent(database, input) {
 
 function publishStateEvent(event) {
   if (event) emitter.emit('event', event);
-  maybePruneEventLog();
+  scheduleEventLogPrune();
+}
+
+// Retention runs off the publish hot path: publishing only arms a short
+// one-shot timer, so the DELETE never adds latency to a write. The 60s
+// throttle inside maybePruneEventLog still bounds how often it runs.
+function scheduleEventLogPrune() {
+  if (pruneTimer) return;
+  pruneTimer = setTimeout(() => {
+    pruneTimer = null;
+    maybePruneEventLog();
+  }, EVENT_LOG_PRUNE_DELAY_MS);
+  if (typeof pruneTimer.unref === 'function') pruneTimer.unref();
 }
 
 function currentSeq() {

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

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * One-time data migrations that run after the schema is ensured. Everything
+ * here is idempotent (guarded by table existence or INSERT OR IGNORE /
+ * targeted DELETEs), so re-running on every open is safe.
+ */
+
+function tableExists(database, tableName) {
+  const row = database.prepare(
+    "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?"
+  ).get(tableName);
+  return Boolean(row);
+}
+
+// Imports rows from the pre-rename toolbox_tools/toolbox_actions tables into
+// tools/tool_actions on machines that still carry them.
+function migrateLegacyToolboxTables(database) {
+  if (tableExists(database, 'toolbox_tools')) {
+    database.prepare(`
+      INSERT OR IGNORE INTO tools (
+        id,
+        name,
+        type,
+        owner,
+        origin,
+        status,
+        updated_at,
+        tool_json
+      )
+      SELECT
+        id,
+        name,
+        type,
+        owner,
+        origin,
+        status,
+        updated_at,
+        tool_json
+      FROM toolbox_tools
+    `).run();
+  }
+
+  if (tableExists(database, 'toolbox_actions')) {
+    database.prepare(`
+      INSERT OR IGNORE INTO tool_actions (
+        id,
+        tool_id,
+        name,
+        status,
+        updated_at,
+        action_json
+      )
+      SELECT
+        legacy.id,
+        legacy.tool_id,
+        legacy.name,
+        legacy.status,
+        legacy.updated_at,
+        legacy.action_json
+      FROM toolbox_actions legacy
+      INNER JOIN tools ON tools.id = legacy.tool_id
+    `).run();
+  }
+}
+
+// Harness-inherited codex catalog tools were seeded by an older release and
+// are now provided dynamically; stale rows are removed on open.
+function removeInheritedHarnessTools(database) {
+  database.prepare(`
+    DELETE FROM tool_actions
+    WHERE tool_id IN (
+      SELECT id FROM tools
+      WHERE owner IN ('codex')
+        AND origin = 'catalog'
+    )
+  `).run();
+
+  database.prepare(`
+    DELETE FROM tools
+    WHERE owner IN ('codex')
+      AND origin = 'catalog'
+  `).run();
+}
+
+function runLegacyMigrations(database) {
+  migrateLegacyToolboxTables(database);
+  removeInheritedHarnessTools(database);
+}
+
+module.exports = { runLegacyMigrations };

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

@@ -12,6 +12,11 @@ function parsePositiveInt(value, fallback) {
   return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
 }
 
+// Streams replay at most this many missed events on connect. Beyond it a
+// fresh snapshot is strictly cheaper than replaying history that mostly
+// overwrites itself, so the client is told to reset instead.
+const STREAM_REPLAY_MAX_EVENTS = 1000;
+
 function sendSseEvent(res, event) {
   res.write(`id: ${event.seq}\n`);
   res.write('event: state\n');
@@ -60,11 +65,23 @@ function handleStream(req, res, query) {
     return;
   }
 
+  const backlog = listEventsAfter(after, { limit: STREAM_REPLAY_MAX_EVENTS + 1 });
+  if (backlog.length > STREAM_REPLAY_MAX_EVENTS) {
+    sendSseControl(res, 'reset', {
+      code: 'state_replay_too_large',
+      message: 'Too many missed events to replay; fetch a fresh snapshot.',
+      after,
+      reset: true,
+    });
+    res.end();
+    return;
+  }
+
   const unsubscribe = subscribeStateEvents((event) => {
     if (event.seq > after) sendSseEvent(res, event);
   });
 
-  for (const event of listEventsAfter(after, { limit: 5000 })) {
+  for (const event of backlog) {
     sendSseEvent(res, event);
   }
 

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

@@ -10,14 +10,17 @@ function normalizeResources(resources) {
   return clean.length > 0 ? Array.from(new Set(clean)) : DEFAULT_RESOURCES;
 }
 
+function automationGraph(cache) {
+  cache.automationGraph ||= require('../automations/store').listPublicAutomationGraph();
+  return cache.automationGraph;
+}
+
 function readResource(resource, cache) {
   switch (resource) {
     case 'automations':
-      cache.automations ||= require('../automations/store').listPublicAutomations();
-      return cache.automations;
+      return automationGraph(cache).automations;
     case 'triggers':
-      cache.triggers ||= require('../automations/store').listPublicTriggers();
-      return cache.triggers;
+      return automationGraph(cache).triggers;
     case 'automation_runs':
       return require('../automations/store').listAutomationRuns({ limit: 300 });
     case 'workflow_cell_runs':
@@ -31,8 +34,7 @@ function readResource(resource, cache) {
     case 'event_triggers':
       return require('../events/store').loadEventTriggers().triggers;
     case 'workflows':
-      cache.workflows ||= require('../automations/store').listPublicWorkflows();
-      return cache.workflows;
+      return automationGraph(cache).workflows;
     case 'agents': {
       const { agentWithConfig } = require('../agent-config/store');
       return require('../agents/store').getAllAgentsWithBuiltins()
@@ -97,10 +99,19 @@ function buildSnapshot(resourcesInput) {
 
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const beforeSeq = currentSeq();
+    // The cache is per-attempt on purpose: a retry exists because a write
+    // landed mid-read, so reusing reads across attempts would serve the very
+    // staleness the retry is trying to escape.
     const cache = {};
     const data = {};
     for (const resource of resources) {
-      const value = readResource(resource, cache);
+      let value;
+      try {
+        value = readResource(resource, cache);
+      } catch (error) {
+        console.warn(`[LocalLive] Failed to read snapshot resource "${resource}":`, error?.message || error);
+        throw error;
+      }
       if (value !== undefined) data[resource] = value;
     }
     const afterSeq = currentSeq();
@@ -110,7 +121,11 @@ function buildSnapshot(resourcesInput) {
     lastUnstable = { seq: beforeSeq, stable: false, resources: data };
   }
 
-  return lastUnstable || { seq: currentSeq(), stable: true, resources: {} };
+  if (lastUnstable) {
+    console.warn(`[LocalLive] Snapshot did not stabilize after 3 attempts (writes kept landing mid-read); serving best-effort data at seq ${lastUnstable.seq}.`);
+    return lastUnstable;
+  }
+  return { seq: currentSeq(), stable: true, resources: {} };
 }
 
 module.exports = { DEFAULT_RESOURCES, buildSnapshot, normalizeResources };

package/runtime/scripts/amalgm-mcp/tests/apps-health-e2e.test.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * End-to-end dogfood of the app health contract: the supervisor spawns a real
+ * app process that uses @amalgm/app (packages/app) to announce itself over
+ * real HTTP to the real /apps routes. Nothing is mocked.
+ */
+
+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-app-health-e2e-'));
+process.env.AMALGM_DIR = path.join(tempRoot, 'user');
+process.env.AMALGM_HOME = path.join(tempRoot, 'home');
+process.env.AMALGM_RUNTIME_LABEL = 'test';
+process.env.AMALGM_WORKSPACES_DIR = path.join(process.env.AMALGM_DIR, 'workspaces');
+process.env.AMALGM_RUNTIME_AUTH = 'disabled';
+
+const { createRuntimeHttpServer } = require('../server/http-service');
+const { handleAppRoutes } = require('../server/routes/apps');
+const { getApp, saveApps } = require('../apps/store');
+const { healthSnapshot } = require('../apps/health');
+const { startApp, stopApp } = require('../apps/supervisor');
+
+const SDK_PATH = path.resolve(__dirname, '../../../../packages/app');
+
+function waitFor(predicate, label, timeoutMs = 10_000) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const tick = async () => {
+      try {
+        if (await predicate()) return resolve();
+      } catch {}
+      if (Date.now() >= deadline) return reject(new Error(`Timed out waiting for ${label}`));
+      setTimeout(tick, 100);
+    };
+    tick();
+  });
+}
+
+function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const net = require('net');
+    const server = net.createServer();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+test('a spawned app announces itself through @amalgm/app and the runtime hears it', async (t) => {
+  // Real /apps routes on an ephemeral port; the supervisor hands this port to
+  // the app as AMALGM_MCP_URL via AMALGM_MCP_PORT.
+  const server = createRuntimeHttpServer((ctx) => handleAppRoutes(ctx));
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  t.after(() => server.close());
+  process.env.AMALGM_MCP_PORT = String(server.address().port);
+
+  const appCwd = fs.mkdtempSync(path.join(tempRoot, 'lease-app-'));
+  const script = path.join(appCwd, 'server.js');
+  fs.writeFileSync(script, [
+    `const sdk = require(${JSON.stringify(SDK_PATH)});`,
+    "require('http').createServer((req, res) => res.end('ok'))",
+    "  .listen(Number(process.env.PORT), '127.0.0.1', () => {",
+    '    sdk.connect({ heartbeatIntervalMs: 5000 });',
+    '  });',
+    '',
+  ].join('\n'));
+
+  const appPort = await getFreePort();
+  saveApps({
+    version: 1,
+    apps: [{
+      id: 'app-lease-e2e',
+      kind: 'app',
+      name: 'Lease E2E',
+      cwd: appCwd,
+      port: appPort,
+      startCommand: `"${process.execPath}" "${script}"`,
+      appRef: 'leasee2e0000',
+      publicUrl: 'https://leasee2e0000.apps.amalgm.ai/',
+      dnsConnected: false,
+      autostart: true,
+      keepAlive: false,
+      desiredState: 'running',
+      status: 'registered',
+      pid: null,
+    }],
+  });
+
+  const app = await startApp('app-lease-e2e');
+  t.after(() => stopApp('app-lease-e2e').catch(() => {}));
+  assert.equal(app.status, 'running');
+  assert.equal(app.readyAt, null, 'a fresh spawn starts unannounced');
+
+  await waitFor(() => Boolean(getApp('app-lease-e2e').readyAt), 'app to announce ready');
+
+  const announced = getApp('app-lease-e2e');
+  assert.equal(announced.status, 'running');
+  assert.equal(announced.heartbeatIntervalMs, 5000);
+
+  const live = healthSnapshot('app-lease-e2e');
+  assert.notEqual(live, null);
+  assert.equal(live.heartbeatIntervalMs, 5000);
+  assert.equal(typeof live.lastHeartbeatAt, 'string');
+
+  // Stopping the app ends the process generation: enrollment is forgotten.
+  await stopApp('app-lease-e2e');
+  assert.equal(healthSnapshot('app-lease-e2e'), null);
+  assert.equal(getApp('app-lease-e2e').status, 'stopped');
+});

package/runtime/scripts/amalgm-mcp/tests/apps-health.test.js

@@ -0,0 +1,150 @@
+'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-app-health-'));
+process.env.AMALGM_DIR = path.join(tempRoot, 'user');
+process.env.AMALGM_HOME = path.join(tempRoot, 'home');
+process.env.AMALGM_RUNTIME_LABEL = 'test';
+process.env.AMALGM_WORKSPACES_DIR = path.join(process.env.AMALGM_DIR, 'workspaces');
+delete process.env.AMALGM_RUNTIME_TOKEN;
+delete process.env.AMALGM_LOCAL_MODE;
+process.env.AMALGM_RUNTIME_AUTH = 'disabled';
+
+const { getApp, getConnectedRoutes, saveApps } = require('../apps/store');
+const {
+  APP_HEALTH_POLICY,
+  clearAppHealth,
+  healthSnapshot,
+  recordHeartbeat,
+  recordReady,
+  sweepOnce,
+} = require('../apps/health');
+
+let appCounter = 0;
+
+function seedApp(overrides = {}) {
+  appCounter += 1;
+  const id = overrides.id || `app-health-${appCounter}`;
+  saveApps({
+    version: 1,
+    apps: [{
+      id,
+      kind: 'app',
+      name: `Health ${appCounter}`,
+      cwd: tempRoot,
+      port: 9100 + appCounter,
+      startCommand: 'node server.js',
+      appRef: `health${appCounter}00000`.slice(0, 12),
+      publicUrl: `https://health${appCounter}.apps.amalgm.ai/`,
+      dnsConnected: true,
+      autostart: true,
+      keepAlive: true,
+      desiredState: 'running',
+      status: 'running',
+      pid: 4242,
+      ...overrides,
+    }],
+  });
+  return id;
+}
+
+test('a silent app is never touched by the monitor', () => {
+  const id = seedApp();
+  const transitioned = sweepOnce(Date.now() + 60 * 60_000);
+  assert.deepEqual(transitioned, []);
+  assert.equal(getApp(id).status, 'running');
+  assert.equal(healthSnapshot(id), null);
+});
+
+test('ready enrolls, stamps the record, and clamps the declared interval', () => {
+  const id = seedApp();
+  const result = recordReady(id, { heartbeatIntervalMs: 1 });
+  assert.equal(result.accepted, true);
+  assert.equal(result.health.heartbeatIntervalMs, APP_HEALTH_POLICY.minIntervalMs);
+
+  const app = getApp(id);
+  assert.equal(typeof app.readyAt, 'string');
+  assert.equal(typeof app.lastHeartbeatAt, 'string');
+  assert.equal(app.heartbeatIntervalMs, APP_HEALTH_POLICY.minIntervalMs);
+  clearAppHealth(id);
+});
+
+test('missed heartbeats mark a running app unresponsive and drop its route', () => {
+  const id = seedApp();
+  const start = Date.now();
+  recordHeartbeat(id, start);
+  assert.equal(getConnectedRoutes().some((route) => route.port === getApp(id).port), true);
+
+  const interval = APP_HEALTH_POLICY.defaultIntervalMs;
+  const withinBudget = sweepOnce(start + interval * APP_HEALTH_POLICY.missedBeats);
+  assert.deepEqual(withinBudget, [], 'not overdue until the missed-beat budget is spent');
+
+  const overdue = sweepOnce(start + interval * APP_HEALTH_POLICY.missedBeats + 1);
+  assert.deepEqual(overdue, [id]);
+  const app = getApp(id);
+  assert.equal(app.status, 'unresponsive');
+  assert.match(app.error, /No heartbeat/);
+  assert.equal(getConnectedRoutes().some((route) => route.port === app.port), false);
+  clearAppHealth(id);
+});
+
+test('a resumed heartbeat recovers an unresponsive app', () => {
+  const id = seedApp();
+  const start = Date.now();
+  recordHeartbeat(id, start);
+  sweepOnce(start + APP_HEALTH_POLICY.defaultIntervalMs * APP_HEALTH_POLICY.missedBeats + 1);
+  assert.equal(getApp(id).status, 'unresponsive');
+
+  const result = recordHeartbeat(id, start + APP_HEALTH_POLICY.defaultIntervalMs * 4);
+  assert.equal(result.accepted, true);
+  const app = getApp(id);
+  assert.equal(app.status, 'running');
+  assert.equal(app.error, null);
+  assert.equal(getConnectedRoutes().some((route) => route.port === app.port), true);
+  clearAppHealth(id);
+});
+
+test('signals from unknown or settled apps are rejected, not enrolled', () => {
+  assert.equal(recordReady('app-none').accepted, false);
+  assert.equal(recordReady('app-none').reason, 'not_found');
+  assert.equal(recordHeartbeat('app-none').accepted, false);
+
+  const stopped = seedApp({ desiredState: 'stopped', status: 'stopped' });
+  const result = recordHeartbeat(stopped);
+  assert.equal(result.accepted, false);
+  assert.equal(result.reason, 'status_stopped');
+  assert.equal(healthSnapshot(stopped), null);
+
+  const degraded = seedApp({ status: 'degraded' });
+  assert.equal(recordReady(degraded).accepted, false);
+});
+
+test('the monitor defers to the supervisor when the lifecycle moved on', () => {
+  const id = seedApp();
+  const start = Date.now();
+  recordHeartbeat(id, start);
+
+  // Supervisor stopped the app after enrollment (e.g. user stop raced a beat).
+  seedApp({ id, desiredState: 'stopped', status: 'stopped' });
+  const transitioned = sweepOnce(start + APP_HEALTH_POLICY.defaultIntervalMs * 10);
+  assert.deepEqual(transitioned, []);
+  assert.equal(getApp(id).status, 'stopped');
+  assert.equal(healthSnapshot(id), null, 'stale enrollment is dropped');
+});
+
+test('clearAppHealth ends the process generation', () => {
+  const id = seedApp();
+  recordHeartbeat(id);
+  assert.notEqual(healthSnapshot(id), null);
+  clearAppHealth(id);
+  assert.equal(healthSnapshot(id), null);
+
+  const transitioned = sweepOnce(Date.now() + 60 * 60_000);
+  assert.deepEqual(transitioned, []);
+  assert.equal(getApp(id).status, 'running', 'a cleared app is silent, not unresponsive');
+});

package/runtime/scripts/amalgm-mcp/tests/state-stream-replay.test.js

@@ -0,0 +1,93 @@
+'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 { EventEmitter } = require('events');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-state-stream-test-'));
+process.env.AMALGM_DIR = path.join(tempRoot, '.amalgm');
+
+const { closeLocalDb, openLocalDb } = require('../state/db');
+const { insertStateEvent } = require('../state/events');
+const { handleStream } = require('../state/rest');
+
+test.after(() => {
+  closeLocalDb();
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+function fakeStream() {
+  const req = new EventEmitter();
+  const chunks = [];
+  let ended = false;
+  const res = {
+    writeHead: () => {},
+    write: (chunk) => {
+      chunks.push(String(chunk));
+    },
+    end: () => {
+      ended = true;
+    },
+  };
+  const close = () => req.emit('close');
+  return {
+    req,
+    res,
+    close,
+    output: () => chunks.join(''),
+    ended: () => ended,
+  };
+}
+
+function insertEvents(count, startId = 0) {
+  const db = openLocalDb();
+  for (let i = 0; i < count; i += 1) {
+    insertStateEvent(db, {
+      resource: 'apps',
+      op: 'replace',
+      value: [{ id: `app-${startId + i}` }],
+      source: 'test',
+    });
+  }
+}
+
+test('stream replays a small backlog as state events', () => {
+  insertEvents(3);
+  const stream = fakeStream();
+
+  handleStream(stream.req, stream.res, { after: '0' });
+  stream.close();
+
+  const output = stream.output();
+  assert.equal((output.match(/event: state/g) || []).length, 3);
+  assert.ok(!output.includes('event: reset'), 'small backlog must not reset');
+  assert.equal(stream.ended(), false, 'stream stays open for live events');
+});
+
+test('stream resets instead of replaying an oversized backlog', () => {
+  insertEvents(1100, 1000);
+  const stream = fakeStream();
+
+  handleStream(stream.req, stream.res, { after: '0' });
+
+  const output = stream.output();
+  assert.ok(output.includes('event: reset'), 'oversized backlog must reset');
+  assert.ok(output.includes('state_replay_too_large'));
+  assert.ok(!output.includes('event: state'), 'no partial replay before reset');
+  assert.equal(stream.ended(), true, 'stream ends after reset');
+});
+
+test('stream replays only events after the requested seq', () => {
+  const stream = fakeStream();
+
+  // 1103 events exist; ask for everything after all but two of them.
+  handleStream(stream.req, stream.res, { after: '1101' });
+  stream.close();
+
+  const output = stream.output();
+  assert.equal((output.match(/event: state/g) || []).length, 2);
+  assert.ok(!output.includes('event: reset'));
+});