amalgm 0.1.43 → 0.1.44

package/README.md

@@ -22,7 +22,19 @@ amalgm login --setup-code ABCD-EFGH-JKLM-NPQR
 
 `amalgm doctor` checks the installed runtime, login record, service supervisor, required local ports, daemon state, and whether an HMAC proxy token is available.
 
-`amalgm start` installs/starts the best available service supervisor for the machine, then the supervisor runs `amalgm run` and keeps the local essentials alive:
+`amalgm run` is the foreground runtime supervisor. It reads the declared service manifest, starts each local service, health-checks them, and restarts unhealthy children with backoff. In a container you control, make this the container command/entrypoint, ideally behind a tiny init such as Docker `--init`, `tini`, or the provider's init wrapper:
+
+```sh
+amalgm run
+```
+
+`amalgm start` is the host attachment helper. It installs/starts the best available launcher for the machine, then that launcher runs `amalgm run`:
+
+- macOS host: LaunchAgent
+- Linux host with real user systemd: systemd user service
+- random/container shell where no service manager is available: portable best-effort watchdog
+
+The runtime supervisor keeps the declared local essentials alive:
 
 - port monitor on `8081`
 - filesystem/auth watcher on `8082`
@@ -31,7 +43,7 @@ amalgm login --setup-code ABCD-EFGH-JKLM-NPQR
 - events/previews/artifact tunnel to `wire.events.amalgm.ai`
 - chat tunnel to `amalgm-chat-gateway`
 
-The npm supervisor binds local services to `127.0.0.1` by default and connects them outward through the registered Amalgm tunnels. For development without cloud registration, use `amalgm start --local-only`. For direct foreground debugging, use `amalgm start --foreground`.
+The npm supervisor binds local services to `127.0.0.1` by default and connects them outward through the registered Amalgm tunnels. For development without cloud registration, use `amalgm start --local-only`. For direct foreground debugging, use `amalgm run` or `amalgm start --foreground`.
 
 Useful commands:
 

package/lib/cli.js

@@ -33,6 +33,12 @@ const {
   runtimeServiceProcesses,
   supervisorProcesses,
 } = require('./process-cleanup');
+const {
+  runtimePortsForStatus,
+  runtimeServiceNames,
+  runtimeServiceScripts,
+  runtimeServices,
+} = require('./runtime-manifest');
 const {
   deleteComputerAuth,
   loadComputerRecord,
@@ -89,6 +95,7 @@ function usage() {
     'Usage:',
     '  amalgm login [--app-url https://amalgm.ai] [--name "My Mac"] [--setup-code ABCD-EFGH-JKLM-NPQR] [--no-open] [--no-poll]',
     '  amalgm start [--foreground] [--local-only]',
+    '  amalgm run [--local-only]',
     '  amalgm stop',
     '  amalgm status',
     '  amalgm doctor',
@@ -144,36 +151,13 @@ function runtimeEntry(relativePath) {
 }
 
 function runtimeMissingFiles() {
-  const required = [
-    runtimeEntry('scripts/amalgm-mcp/index.js'),
-    runtimeEntry('scripts/chat-server.js'),
-    runtimeEntry('scripts/fs-watcher.js'),
-    runtimeEntry('scripts/local-gateway.js'),
-    runtimeEntry('scripts/port-monitor.js'),
-  ];
+  const required = runtimeServiceScripts().map((script) => runtimeEntry(script));
   return required.filter((file) => !fs.existsSync(file));
 }
 
 function servicePorts() {
   const state = readJson(RUNTIME_STATE_FILE, null);
-  const statePorts = state?.ports || {};
-  if (Number.isInteger(state?.gateway_port)) {
-    return [
-      ['local-gateway', Number(state.gateway_port)],
-      ['port-monitor', Number(statePorts.port_monitor || 0)],
-      ['fs-watcher', Number(statePorts.fs_watcher || 0)],
-      ['amalgm-mcp', Number(statePorts.amalgm_mcp || 0)],
-      ['chat-server', Number(statePorts.chat_server || 0)],
-    ].filter(([, port]) => Number.isInteger(port) && port > 0);
-  }
-
-  return [
-    ['local-gateway', Number(process.env.AMALGM_GATEWAY_PORT || 28781)],
-    ['port-monitor', Number(process.env.PORT_MONITOR_PORT || 8081)],
-    ['fs-watcher', Number(process.env.FS_WATCHER_PORT || 8082)],
-    ['amalgm-mcp', Number(process.env.AMALGM_MCP_PORT || 8083)],
-    ['chat-server', Number(process.env.CHAT_SERVER_PORT || 8084)],
-  ];
+  return runtimePortsForStatus(state, process.env);
 }
 
 function hasRequiredComputerFields(record) {
@@ -357,13 +341,7 @@ function isPortFree(port, host = '127.0.0.1') {
 
 async function unavailableServicePorts() {
   const results = [];
-  const explicitEnvByService = new Map([
-    ['local-gateway', 'AMALGM_GATEWAY_PORT'],
-    ['port-monitor', 'PORT_MONITOR_PORT'],
-    ['fs-watcher', 'FS_WATCHER_PORT'],
-    ['amalgm-mcp', 'AMALGM_MCP_PORT'],
-    ['chat-server', 'CHAT_SERVER_PORT'],
-  ]);
+  const explicitEnvByService = new Map(runtimeServices().map((service) => [service.name, service.envName]));
   for (const [name, port] of servicePorts()) {
     const envName = explicitEnvByService.get(name);
     if (!envName || !process.env[envName]) continue;
@@ -963,7 +941,7 @@ async function stop() {
   console.log('Amalgm stopped.');
 }
 
-async function checkHttp(port, pathName = '/healthz') {
+async function checkHttpOnce(port, pathName = '/healthz', timeoutMs = 1500) {
   return new Promise((resolve) => {
     const req = http.request(
       {
@@ -971,7 +949,7 @@ async function checkHttp(port, pathName = '/healthz') {
         port,
         path: pathName,
         method: 'GET',
-        timeout: 1000,
+        timeout: timeoutMs,
       },
       (res) => {
         res.resume();
@@ -987,6 +965,16 @@ async function checkHttp(port, pathName = '/healthz') {
   });
 }
 
+async function checkHttp(port, pathName = '/healthz', options = {}) {
+  const attempts = Math.max(1, Number(options.attempts || 3));
+  const timeoutMs = Math.max(500, Number(options.timeoutMs || 1500));
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (await checkHttpOnce(port, pathName, timeoutMs)) return true;
+    if (attempt < attempts - 1) await sleep(150);
+  }
+  return false;
+}
+
 async function waitForServices(timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   let latest = [];
@@ -1039,15 +1027,24 @@ async function status() {
 
   const runtimeChildren = runtimeServiceProcesses();
   const runtimeSupervisors = supervisorProcesses();
-  if (runtimeChildren.length > 5 || runtimeSupervisors.length > 1) {
+  const expectedServiceCount = runtimeServiceNames().length;
+  if (runtimeChildren.length > expectedServiceCount || runtimeSupervisors.length > 1) {
     console.log(
       `Warning: multiple Amalgm runtime processes detected (${runtimeSupervisors.length} supervisor, ${runtimeChildren.length} services). Run \`amalgm stop && amalgm start\`.`,
     );
   }
 
+  const serviceStateByName = new Map(
+    (Array.isArray(runtimeState?.services) ? runtimeState.services : [])
+      .map((service) => [service.name, service]),
+  );
   for (const [name, port] of servicePorts()) {
     const ok = await checkHttp(port);
-    console.log(`${name.padEnd(13)} ${ok ? 'up' : 'down'}  http://127.0.0.1:${port}`);
+    const serviceState = serviceStateByName.get(name);
+    const detail = serviceState?.status && serviceState.status !== 'running'
+      ? ` (${serviceState.status}${serviceState.reason ? `: ${serviceState.reason}` : ''})`
+      : '';
+    console.log(`${name.padEnd(13)} ${ok ? 'up' : 'down'}  http://127.0.0.1:${port}${detail}`);
   }
 }
 
@@ -1120,7 +1117,7 @@ async function doctor() {
   add('daemon', daemonRunning, daemonRunning ? `pid ${pid}` : 'stopped', daemonRunning ? 'ok' : 'warn');
   const runtimeChildren = runtimeServiceProcesses();
   const runtimeSupervisors = supervisorProcesses();
-  const expectedServices = daemonRunning ? 5 : 0;
+  const expectedServices = daemonRunning ? runtimeServiceNames().length : 0;
   const cleanProcessShape = runtimeSupervisors.length <= 1 && runtimeChildren.length <= expectedServices;
   add(
     'runtime processes',
@@ -1136,15 +1133,25 @@ async function doctor() {
       'warn',
     );
   }
+  const runtimeServiceState = Array.isArray(readJson(RUNTIME_STATE_FILE, null)?.services)
+    ? readJson(RUNTIME_STATE_FILE, null).services
+    : [];
+  const unhealthyState = runtimeServiceState.filter((service) => (
+    service.status && !['running', 'starting'].includes(service.status)
+  ));
+  if (runtimeServiceState.length > 0) {
+    add(
+      'service states',
+      unhealthyState.length === 0,
+      unhealthyState.length === 0
+        ? `${runtimeServiceState.length} declared service(s) running/starting`
+        : unhealthyState.map((service) => `${service.name}:${service.status}`).join(', '),
+      unhealthyState.length === 0 ? 'ok' : 'warn',
+    );
+  }
 
   for (const [name, port] of servicePorts()) {
-    const envName = {
-      'local-gateway': 'AMALGM_GATEWAY_PORT',
-      'port-monitor': 'PORT_MONITOR_PORT',
-      'fs-watcher': 'FS_WATCHER_PORT',
-      'amalgm-mcp': 'AMALGM_MCP_PORT',
-      'chat-server': 'CHAT_SERVER_PORT',
-    }[name];
+    const envName = runtimeServices().find((service) => service.name === name)?.envName;
     const ok = daemonRunning ? await checkHttp(port) : (!process.env[envName] || await isPortFree(port));
     add(
       `${name} port`,

package/lib/process-cleanup.js

@@ -9,23 +9,17 @@ const {
   PACKAGE_ROOT,
   RUNTIME_DIR,
 } = require('./paths');
+const {
+  runtimeServiceScripts,
+} = require('./runtime-manifest');
 
-const RUNTIME_SERVICE_MARKERS = [
-  path.join(RUNTIME_DIR, 'scripts', 'port-monitor.js'),
-  path.join(RUNTIME_DIR, 'scripts', 'fs-watcher.js'),
-  path.join(RUNTIME_DIR, 'scripts', 'chat-server.js'),
-  path.join(RUNTIME_DIR, 'scripts', 'local-gateway.js'),
-  path.join(RUNTIME_DIR, 'scripts', 'amalgm-mcp', 'index.js'),
-].map((value) => value.replace(/\\/g, '/'));
-const RUNTIME_SERVICE_SUFFIXES = [
-  'runtime/scripts/port-monitor.js',
-  'runtime/scripts/fs-watcher.js',
-  'runtime/scripts/chat-server.js',
-  'runtime/scripts/local-gateway.js',
-  'runtime/scripts/amalgm-mcp/index.js',
-];
+const RUNTIME_SERVICE_MARKERS = runtimeServiceScripts()
+  .map((script) => path.join(RUNTIME_DIR, script).replace(/\\/g, '/'));
+const RUNTIME_SERVICE_SUFFIXES = runtimeServiceScripts()
+  .map((script) => `runtime/${script}`.replace(/\\/g, '/'));
 
 const SUPERVISOR_MARKER = path.join(PACKAGE_ROOT, 'bin', 'amalgm.js').replace(/\\/g, '/');
+const SUPERVISOR_SUFFIX = '/bin/amalgm.js';
 
 function isPidRunning(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -67,6 +61,19 @@ function readProcCommand(pid) {
   }
 }
 
+function readProcPpid(pid) {
+  try {
+    const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const lastParen = stat.lastIndexOf(')');
+    if (lastParen === -1) return null;
+    const parts = stat.slice(lastParen + 2).trim().split(/\s+/);
+    const ppid = Number(parts[1]);
+    return Number.isInteger(ppid) ? ppid : null;
+  } catch {
+    return null;
+  }
+}
+
 function readProcEnv(pid) {
   const raw = readProcString(`/proc/${pid}/environ`);
   if (!raw) return null;
@@ -88,6 +95,7 @@ function listProcProcesses() {
       .filter((pid) => Number.isInteger(pid) && pid > 0)
       .map((pid) => ({
         pid,
+        ppid: readProcPpid(pid),
         command: readProcCommand(pid),
         env: readProcEnv(pid),
       }))
@@ -99,7 +107,7 @@ function listProcProcesses() {
 
 function listPsProcesses() {
   try {
-    const result = spawnSync('ps', ['-eo', 'pid=,command='], {
+    const result = spawnSync('ps', ['-eo', 'pid=,ppid=,command='], {
       encoding: 'utf8',
       timeout: 2000,
     });
@@ -107,11 +115,12 @@ function listPsProcesses() {
     return String(result.stdout || '')
       .split('\n')
       .map((line) => {
-        const match = line.trim().match(/^(\d+)\s+(.+)$/);
+        const match = line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
         if (!match) return null;
         return {
           pid: Number(match[1]),
-          command: match[2],
+          ppid: Number(match[2]),
+          command: match[3],
           env: null,
         };
       })
@@ -122,7 +131,12 @@ function listPsProcesses() {
 }
 
 function listProcesses() {
-  return listProcProcesses() || listPsProcesses();
+  const processes = listProcProcesses() || listPsProcesses();
+  const commandByPid = new Map(processes.map((item) => [item.pid, item.command]));
+  return processes.map((item) => ({
+    ...item,
+    parentCommand: commandByPid.get(item.ppid) || readProcCommand(item.ppid),
+  }));
 }
 
 function normalizedCommand(command) {
@@ -134,10 +148,14 @@ function envMatchesAmalgmDir(env) {
   return path.resolve(env.AMALGM_DIR) === path.resolve(AMALGM_DIR);
 }
 
-function commandLooksLikeRuntimeService(command) {
+function commandLooksLikeRuntimeService(command, item = null, options = {}) {
   const normalized = normalizedCommand(command);
-  return RUNTIME_SERVICE_MARKERS.some((marker) => normalized.includes(marker))
-    || RUNTIME_SERVICE_SUFFIXES.some((marker) => normalized.includes(marker));
+  if (RUNTIME_SERVICE_MARKERS.some((marker) => normalized.includes(marker))) return true;
+  if (!RUNTIME_SERVICE_SUFFIXES.some((marker) => normalized.includes(marker))) return false;
+  if (item?.env && envMatchesAmalgmDir(item.env)) return true;
+  if (!options.includeOrphanedForeign) return false;
+  const parent = normalizedCommand(item?.parentCommand || '');
+  return !commandLooksLikeAnySupervisor(parent);
 }
 
 function commandLooksLikeSupervisor(command) {
@@ -145,11 +163,16 @@ function commandLooksLikeSupervisor(command) {
   return normalized.includes(SUPERVISOR_MARKER) && /\brun\b/.test(normalized);
 }
 
+function commandLooksLikeAnySupervisor(command) {
+  const normalized = normalizedCommand(command);
+  return normalized.includes(SUPERVISOR_SUFFIX) && /\brun\b/.test(normalized);
+}
+
 function runtimeServiceProcesses(options = {}) {
   const exclude = new Set([process.pid, ...(options.excludePids || [])].filter(Number.isInteger));
   return listProcesses()
     .filter((item) => !exclude.has(item.pid))
-    .filter((item) => commandLooksLikeRuntimeService(item.command))
+    .filter((item) => commandLooksLikeRuntimeService(item.command, item, options))
     .filter((item) => envMatchesAmalgmDir(item.env));
 }
 
@@ -197,7 +220,10 @@ function terminateProcesses(processes, options = {}) {
 }
 
 function cleanupStaleRuntimeProcesses(options = {}) {
-  const stale = runtimeServiceProcesses(options);
+  const stale = runtimeServiceProcesses({
+    includeOrphanedForeign: true,
+    ...options,
+  });
   const supervisors = options.includeSupervisors ? supervisorProcesses(options) : [];
   return terminateProcesses([...stale, ...supervisors], options);
 }

package/lib/runtime-manifest.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const RUNTIME_SERVICES = [
+  {
+    name: 'local-gateway',
+    script: 'scripts/local-gateway.js',
+    portKey: 'gateway',
+    envName: 'AMALGM_GATEWAY_PORT',
+    stateKey: 'gateway',
+    defaultPort: 28781,
+    launchOrder: 50,
+  },
+  {
+    name: 'port-monitor',
+    script: 'scripts/port-monitor.js',
+    portKey: 'portMonitor',
+    envName: 'PORT_MONITOR_PORT',
+    stateKey: 'port_monitor',
+    defaultPort: 8081,
+    launchOrder: 10,
+  },
+  {
+    name: 'fs-watcher',
+    script: 'scripts/fs-watcher.js',
+    portKey: 'fsWatcher',
+    envName: 'FS_WATCHER_PORT',
+    stateKey: 'fs_watcher',
+    defaultPort: 8082,
+    launchOrder: 20,
+  },
+  {
+    name: 'amalgm-mcp',
+    script: 'scripts/amalgm-mcp/index.js',
+    portKey: 'amalgmMcp',
+    envName: 'AMALGM_MCP_PORT',
+    stateKey: 'amalgm_mcp',
+    defaultPort: 8083,
+    launchOrder: 40,
+  },
+  {
+    name: 'chat-server',
+    script: 'scripts/chat-server.js',
+    portKey: 'chatServer',
+    envName: 'CHAT_SERVER_PORT',
+    stateKey: 'chat_server',
+    defaultPort: 8084,
+    launchOrder: 30,
+  },
+];
+
+function runtimeServices() {
+  return RUNTIME_SERVICES.map((service) => ({ ...service }));
+}
+
+function runtimeLaunchServices() {
+  return runtimeServices().sort((left, right) => left.launchOrder - right.launchOrder);
+}
+
+function runtimeServiceNames() {
+  return RUNTIME_SERVICES.map((service) => service.name);
+}
+
+function runtimeServiceScripts() {
+  return RUNTIME_SERVICES.map((service) => service.script);
+}
+
+function runtimeServiceByName(name) {
+  return RUNTIME_SERVICES.find((service) => service.name === name) || null;
+}
+
+function runtimePortsFromState(state) {
+  const statePorts = state?.ports || {};
+  const values = {};
+  for (const service of RUNTIME_SERVICES) {
+    if (service.stateKey === 'gateway' && Number.isInteger(state?.gateway_port)) {
+      values[service.name] = Number(state.gateway_port);
+      continue;
+    }
+    const port = Number(statePorts[service.stateKey] || 0);
+    if (Number.isInteger(port) && port > 0) values[service.name] = port;
+  }
+  return values;
+}
+
+function runtimePortsFromEnv(env = process.env) {
+  const values = {};
+  for (const service of RUNTIME_SERVICES) {
+    const port = Number(env[service.envName] || service.defaultPort);
+    if (Number.isInteger(port) && port > 0) values[service.name] = port;
+  }
+  return values;
+}
+
+function runtimePortsForStatus(state, env = process.env) {
+  const fromState = runtimePortsFromState(state);
+  const fromEnv = runtimePortsFromEnv(env);
+  return RUNTIME_SERVICES
+    .map((service) => [service.name, fromState[service.name] || fromEnv[service.name]])
+    .filter(([, port]) => Number.isInteger(port) && port > 0);
+}
+
+function runtimePortsState(ports) {
+  const statePorts = {};
+  for (const service of RUNTIME_SERVICES) {
+    const port = Number(ports?.[service.portKey] || 0);
+    if (!Number.isInteger(port) || port <= 0) continue;
+    if (service.stateKey !== 'gateway') statePorts[service.stateKey] = port;
+  }
+  return {
+    gateway_port: Number(ports?.gateway || 0) || undefined,
+    gateway_url: ports?.gateway ? `http://127.0.0.1:${ports.gateway}` : undefined,
+    ports: statePorts,
+    services: RUNTIME_SERVICES.map((service) => ({
+      name: service.name,
+      port: Number(ports?.[service.portKey] || 0) || null,
+      health_path: '/healthz',
+    })),
+  };
+}
+
+module.exports = {
+  runtimeLaunchServices,
+  runtimePortsForStatus,
+  runtimePortsFromEnv,
+  runtimePortsFromState,
+  runtimePortsState,
+  runtimeServiceByName,
+  runtimeServiceNames,
+  runtimeServiceScripts,
+  runtimeServices,
+};

package/lib/service.js

@@ -292,6 +292,8 @@ function writePortableNodeScript(localOnly) {
     daemonLog: path.join(LOG_DIR, 'daemon.log'),
     serviceLog: SERVICE_LOG_FILE,
     restartDelayMs: Math.max(1000, Number(process.env.AMALGM_SERVICE_RESTART_DELAY || 5) * 1000),
+    maxRestartDelayMs: Math.max(5000, Number(process.env.AMALGM_SERVICE_MAX_RESTART_DELAY || 60) * 1000),
+    stableAfterMs: Math.max(10000, Number(process.env.AMALGM_SERVICE_STABLE_AFTER || 60) * 1000),
     env: buildServiceEnv(localOnly),
   };
   const source = `'use strict';
@@ -307,6 +309,8 @@ const config = ${JSON.stringify(config, null, 2)};
 let child = null;
 let stopping = false;
 let exiting = false;
+let restartDelayMs = config.restartDelayMs;
+let childStartedAt = 0;
 
 function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -418,6 +422,7 @@ function launch() {
   });
   append(config.serviceLog, 'starting amalgm run');
   const fd = fs.openSync(config.daemonLog, 'a');
+  childStartedAt = Date.now();
   child = spawn(config.nodeBin, [config.amalgmBin, 'run'], {
     cwd: process.env.HOME || process.cwd(),
     env: { ...process.env, ...config.env },
@@ -426,10 +431,15 @@ function launch() {
   });
   try { fs.closeSync(fd); } catch {}
   child.on('exit', (code, signal) => {
+    const runtimeMs = Date.now() - childStartedAt;
     append(config.serviceLog, \`amalgm run exited code=\${code ?? ''} signal=\${signal ?? ''}\`);
     child = null;
     if (stopping || fs.existsSync(config.stopFile)) return cleanup(0);
-    setTimeout(launch, config.restartDelayMs);
+    if (runtimeMs >= config.stableAfterMs) restartDelayMs = config.restartDelayMs;
+    const delay = restartDelayMs;
+    restartDelayMs = Math.min(restartDelayMs * 2, config.maxRestartDelayMs);
+    append(config.serviceLog, \`restarting amalgm run in \${delay}ms\`);
+    setTimeout(launch, delay);
   });
 }
 

package/lib/supervisor.js

@@ -2,6 +2,7 @@
 
 const crypto = require('crypto');
 const fs = require('fs');
+const http = require('http');
 const os = require('os');
 const path = require('path');
 const { spawn, spawnSync } = require('child_process');
@@ -31,8 +32,28 @@ const {
   isPidRunning,
   supervisorProcesses,
 } = require('./process-cleanup');
+const {
+  runtimeLaunchServices,
+  runtimePortsState,
+  runtimeServiceScripts,
+} = require('./runtime-manifest');
 const PACKAGE_VERSION = require('../package.json').version;
 
+const CHILD_RESTART_POLICY = {
+  initialDelayMs: 1000,
+  maxDelayMs: 30000,
+  stableAfterMs: 30000,
+  maxRestarts: 8,
+  windowMs: 60000,
+};
+
+const CHILD_HEALTH_POLICY = {
+  graceMs: 8000,
+  intervalMs: 10000,
+  timeoutMs: 2500,
+  maxFailures: 3,
+};
+
 function ensureDir(dir, mode = 0o700) {
   fs.mkdirSync(dir, { recursive: true, mode });
   try {
@@ -103,13 +124,7 @@ function runtimeEntry(relativePath) {
 }
 
 function assertRuntimePresent() {
-  const required = [
-    runtimeEntry('scripts/amalgm-mcp/index.js'),
-    runtimeEntry('scripts/chat-server.js'),
-    runtimeEntry('scripts/fs-watcher.js'),
-    runtimeEntry('scripts/local-gateway.js'),
-    runtimeEntry('scripts/port-monitor.js'),
-  ];
+  const required = runtimeServiceScripts().map((script) => runtimeEntry(script));
   const missing = required.filter((file) => !fs.existsSync(file));
   if (missing.length > 0) {
     throw new Error(
@@ -177,7 +192,7 @@ function ensureRuntimeToken() {
   return token;
 }
 
-function baseRuntimeEnv(record, ports) {
+function baseRuntimeEnv(record, ports, options = {}) {
   const workspaceRoot =
     process.env.AMALGM_WORKSPACES_DIR ||
     process.env.AMALGM_PROJECTS_DIR ||
@@ -185,11 +200,13 @@ function baseRuntimeEnv(record, ports) {
   ensureDir(workspaceRoot);
   const defaultCwd = process.env.AMALGM_DEFAULT_CWD || workspaceRoot;
   const proxyToken = proxyTokenFromRecord(record);
+  const localOnly = !!options.localOnly || process.env.AMALGM_LOCAL_ONLY === 'true';
   const env = {
     ...safeBaseProcessEnv(),
     AMALGM_RUNTIME_SOURCE: 'npm',
     AMALGM_RUNTIME_TOKEN: record?.runtime_token || process.env.AMALGM_RUNTIME_TOKEN || '',
     AMALGM_LOCAL_MODE: 'true',
+    AMALGM_LOCAL_ONLY: localOnly ? 'true' : 'false',
     AMALGM_BIND_HOST: process.env.AMALGM_BIND_HOST || '127.0.0.1',
     AMALGM_AUTH_BACKUP_ENABLED: process.env.AMALGM_AUTH_BACKUP_ENABLED || 'false',
     AMALGM_CREATE_AUTH_WATCH_DIRS: process.env.AMALGM_CREATE_AUTH_WATCH_DIRS || 'false',
@@ -221,40 +238,16 @@ function baseRuntimeEnv(record, ports) {
   return env;
 }
 
-function serviceSpecs(record, ports) {
-  const env = baseRuntimeEnv(record, ports);
-  return [
-    {
-      name: 'port-monitor',
-      command: process.execPath,
-      args: [runtimeEntry('scripts/port-monitor.js')],
-      env: { ...env, PORT: process.env.PORT || '0' },
-    },
-    {
-      name: 'fs-watcher',
-      command: process.execPath,
-      args: [runtimeEntry('scripts/fs-watcher.js')],
-      env,
-    },
-    {
-      name: 'chat-server',
-      command: process.execPath,
-      args: [runtimeEntry('scripts/chat-server.js')],
-      env,
-    },
-    {
-      name: 'amalgm-mcp',
-      command: process.execPath,
-      args: [runtimeEntry('scripts/amalgm-mcp/index.js')],
-      env,
-    },
-    {
-      name: 'local-gateway',
-      command: process.execPath,
-      args: [runtimeEntry('scripts/local-gateway.js')],
-      env,
-    },
-  ];
+function serviceSpecs(record, ports, options = {}) {
+  const env = baseRuntimeEnv(record, ports, options);
+  return runtimeLaunchServices().map((service) => ({
+    name: service.name,
+    command: process.execPath,
+    args: [runtimeEntry(service.script)],
+    env: service.name === 'port-monitor' ? { ...env, PORT: process.env.PORT || '0' } : env,
+    port: ports[service.portKey],
+    healthPath: '/healthz',
+  }));
 }
 
 function isPortFree(port, host = '127.0.0.1') {
@@ -319,13 +312,11 @@ async function pickPort(name, envName, preferred, used) {
 
 async function resolveRuntimePorts() {
   const used = new Set();
-  return {
-    gateway: await pickPort('local-gateway', 'AMALGM_GATEWAY_PORT', 28781, used),
-    portMonitor: await pickPort('port-monitor', 'PORT_MONITOR_PORT', 8081, used),
-    fsWatcher: await pickPort('fs-watcher', 'FS_WATCHER_PORT', 8082, used),
-    amalgmMcp: await pickPort('amalgm-mcp', 'AMALGM_MCP_PORT', 8083, used),
-    chatServer: await pickPort('chat-server', 'CHAT_SERVER_PORT', 8084, used),
-  };
+  const ports = {};
+  for (const service of runtimeLaunchServices()) {
+    ports[service.portKey] = await pickPort(service.name, service.envName, service.defaultPort, used);
+  }
+  return ports;
 }
 
 function openServiceLog(name) {
@@ -348,14 +339,150 @@ function writePrefixed(stream, name, chunk, consoleStream) {
   }
 }
 
+function updateRuntimeState(update) {
+  const current = readJson(RUNTIME_STATE_FILE, {});
+  if (!current || (current.pid !== process.pid && current.supervisor_pid !== process.pid)) return;
+  writeJsonSecret(RUNTIME_STATE_FILE, {
+    ...current,
+    ...update,
+    updated_at: new Date().toISOString(),
+  });
+}
+
+function appendServiceState(name, update) {
+  const current = readJson(RUNTIME_STATE_FILE, {});
+  if (!current || (current.pid !== process.pid && current.supervisor_pid !== process.pid)) return;
+  const services = Array.isArray(current.services) ? current.services : [];
+  const next = services.map((service) => (
+    service.name === name ? { ...service, ...update } : service
+  ));
+  updateRuntimeState({ services: next });
+}
+
+function checkServiceHealth(spec, timeoutMs = CHILD_HEALTH_POLICY.timeoutMs) {
+  if (!spec.port) return Promise.resolve(true);
+  return new Promise((resolve) => {
+    const req = http.request(
+      {
+        host: '127.0.0.1',
+        port: spec.port,
+        path: spec.healthPath || '/healthz',
+        method: 'GET',
+        timeout: timeoutMs,
+      },
+      (res) => {
+        res.resume();
+        res.on('end', () => resolve(res.statusCode >= 200 && res.statusCode < 500));
+      },
+    );
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.on('error', () => resolve(false));
+    req.end();
+  });
+}
+
 function createManagedProcess(spec, options) {
   const { stream } = openServiceLog(spec.name);
   let child = null;
   let stopped = false;
   let restartTimer = null;
+  let healthTimer = null;
+  let healthFailures = 0;
+  let startedAt = 0;
+  let restartDelayMs = CHILD_RESTART_POLICY.initialDelayMs;
+  let restartHistory = [];
+  let state = 'starting';
+
+  const setState = (nextState, extra = {}) => {
+    state = nextState;
+    appendServiceState(spec.name, {
+      status: state,
+      pid: child?.pid || null,
+      restart_count_window: restartHistory.length,
+      ...extra,
+    });
+  };
+
+  const clearHealthTimer = () => {
+    if (healthTimer) clearTimeout(healthTimer);
+    healthTimer = null;
+  };
+
+  const scheduleHealthCheck = () => {
+    clearHealthTimer();
+    if (stopped) return;
+    healthTimer = setTimeout(async () => {
+      if (stopped || !child) return;
+      if (Date.now() - startedAt < CHILD_HEALTH_POLICY.graceMs) {
+        scheduleHealthCheck();
+        return;
+      }
+      const ok = await checkServiceHealth(spec);
+      if (stopped || !child) return;
+      if (ok) {
+        healthFailures = 0;
+        if (state !== 'running') setState('running');
+      } else {
+        healthFailures += 1;
+        writePrefixed(
+          stream,
+          spec.name,
+          `health check failed (${healthFailures}/${CHILD_HEALTH_POLICY.maxFailures})\n`,
+          options.foreground ? process.stderr : null,
+        );
+        if (healthFailures >= CHILD_HEALTH_POLICY.maxFailures) {
+          setState('restarting', { reason: 'health_check_failed' });
+          try {
+            child.kill('SIGTERM');
+          } catch {
+            // noop
+          }
+          const pid = child.pid;
+          setTimeout(() => {
+            if (child && child.pid === pid) {
+              try {
+                child.kill('SIGKILL');
+              } catch {
+                // noop
+              }
+            }
+          }, 5000);
+          return;
+        }
+      }
+      scheduleHealthCheck();
+    }, CHILD_HEALTH_POLICY.intervalMs);
+  };
+
+  const canRestart = () => {
+    const now = Date.now();
+    restartHistory = restartHistory.filter((time) => now - time <= CHILD_RESTART_POLICY.windowMs);
+    if (restartHistory.length >= CHILD_RESTART_POLICY.maxRestarts) {
+      setState('degraded', {
+        reason: 'restart_limit_exceeded',
+        next_retry_at: null,
+      });
+      writePrefixed(
+        stream,
+        spec.name,
+        `entered degraded state after ${restartHistory.length} restarts in ${CHILD_RESTART_POLICY.windowMs}ms\n`,
+        options.foreground ? process.stderr : null,
+      );
+      return false;
+    }
+    restartHistory.push(now);
+    return true;
+  };
 
   const launch = () => {
     if (stopped) return;
+    clearHealthTimer();
+    healthFailures = 0;
+    startedAt = Date.now();
+    setState('starting');
     child = spawn(spec.command, spec.args, {
       cwd: RUNTIME_DIR,
       env: spec.env,
@@ -369,6 +496,8 @@ function createManagedProcess(spec, options) {
       `started pid=${child.pid} command=${[spec.command, ...spec.args].join(' ')}\n`,
       options.foreground ? process.stdout : null,
     );
+    setState('running', { started_at: new Date(startedAt).toISOString() });
+    scheduleHealthCheck();
 
     child.stdout.on('data', (chunk) => {
       writePrefixed(stream, spec.name, chunk, options.foreground ? process.stdout : null);
@@ -377,15 +506,35 @@ function createManagedProcess(spec, options) {
       writePrefixed(stream, spec.name, chunk, options.foreground ? process.stderr : null);
     });
     child.on('exit', (code, signal) => {
+      clearHealthTimer();
       writePrefixed(
         stream,
         spec.name,
         `exited code=${code ?? ''} signal=${signal ?? ''}\n`,
         options.foreground ? process.stderr : null,
       );
+      const runtimeMs = Date.now() - startedAt;
       child = null;
       if (!stopped) {
-        restartTimer = setTimeout(launch, 2000);
+        if (runtimeMs >= CHILD_RESTART_POLICY.stableAfterMs) {
+          restartDelayMs = CHILD_RESTART_POLICY.initialDelayMs;
+          restartHistory = [];
+        }
+        if (!canRestart()) return;
+        const delay = restartDelayMs;
+        restartDelayMs = Math.min(restartDelayMs * 2, CHILD_RESTART_POLICY.maxDelayMs);
+        setState('restarting', {
+          exit_code: code ?? null,
+          exit_signal: signal || null,
+          next_retry_at: new Date(Date.now() + delay).toISOString(),
+        });
+        writePrefixed(
+          stream,
+          spec.name,
+          `restart scheduled in ${delay}ms\n`,
+          options.foreground ? process.stderr : null,
+        );
+        restartTimer = setTimeout(launch, delay);
       }
     });
   };
@@ -396,6 +545,8 @@ function createManagedProcess(spec, options) {
     stop() {
       stopped = true;
       if (restartTimer) clearTimeout(restartTimer);
+      clearHealthTimer();
+      setState('stopping');
       if (child && !child.killed) {
         try {
           child.kill('SIGTERM');
@@ -465,6 +616,7 @@ async function startSupervisor(options = {}) {
     device_id: record?.device_id || null,
     event_ref: record?.event_ref || null,
     local_only: !!options.localOnly,
+    services: [],
     started_at: new Date().toISOString(),
   });
   if (!storedRecord?.computer_id && options.foreground) {
@@ -479,7 +631,8 @@ async function startSupervisor(options = {}) {
     FS_WATCHER_PORT: String(ports.fsWatcher),
     PORT_MONITOR_PORT: String(ports.portMonitor),
   });
-  const managed = serviceSpecs(record, ports).map((spec) => createManagedProcess(spec, options));
+  updateRuntimeState(runtimePortsState(ports));
+  const managed = serviceSpecs(record, ports, options).map((spec) => createManagedProcess(spec, options));
   const tunnels = [];
 
   if (!options.localOnly && record?.tunnel_url && record?.tunnel_token) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.43",
+  "version": "0.1.44",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,
@@ -17,7 +17,7 @@
     "sync-runtime": "node ../../scripts/sync-npm-package-runtime.mjs",
     "prepack": "node ../../scripts/sync-npm-package-runtime.mjs",
     "pack:dry": "npm pack --dry-run",
-    "check": "node --check bin/amalgm.js && node --check lib/auth-store.js && node --check lib/cli.js && node --check lib/paths.js && node --check lib/process-cleanup.js && node --check lib/service.js && node --check lib/supervisor.js && node --check lib/tunnel-chat.js && node --check lib/tunnel-events.js && node --check runtime/scripts/runtime-auth.js && node --check runtime/scripts/proxy-token-store.js && node --check runtime/scripts/local-gateway.js && node --check runtime/scripts/port-monitor.js && node --check runtime/scripts/fs-watcher.js && node --check runtime/scripts/chat-server.js && node --check runtime/scripts/chat-server/index.js && node --check runtime/scripts/chat-server/config.js && node --check runtime/scripts/chat-core/tooling/native-binaries.js && node --check runtime/scripts/chat-core/tooling/package-import.js && node --check runtime/scripts/amalgm-mcp/index.js && node --check runtime/scripts/amalgm-mcp/config.js"
+    "check": "node --check bin/amalgm.js && node --check lib/auth-store.js && node --check lib/cli.js && node --check lib/paths.js && node --check lib/process-cleanup.js && node --check lib/runtime-manifest.js && node --check lib/service.js && node --check lib/supervisor.js && node --check lib/tunnel-chat.js && node --check lib/tunnel-events.js && node --check runtime/scripts/runtime-auth.js && node --check runtime/scripts/proxy-token-store.js && node --check runtime/scripts/local-gateway.js && node --check runtime/scripts/port-monitor.js && node --check runtime/scripts/fs-watcher.js && node --check runtime/scripts/chat-server.js && node --check runtime/scripts/chat-server/index.js && node --check runtime/scripts/chat-server/config.js && node --check runtime/scripts/chat-core/tooling/native-binaries.js && node --check runtime/scripts/chat-core/tooling/package-import.js && node --check runtime/scripts/amalgm-mcp/index.js && node --check runtime/scripts/amalgm-mcp/config.js"
   },
   "engines": {
     "node": ">=20"

package/runtime/scripts/local-gateway.js

@@ -293,11 +293,14 @@ function ensurePtySpawnHelperExecutable() {
 
 function writeRuntimeState(actualPort) {
   const computer = readJson(path.join(AMALGM_DIR, 'computer.json'), null);
+  const previous = readJson(STATE_FILE, {});
   writeJsonSecret(STATE_FILE, {
+    ...previous,
     schema_version: 1,
     owner: OWNER,
     source: OWNER,
     pid: process.pid,
+    gateway_pid: process.pid,
     supervisor_pid: process.ppid,
     version: VERSION,
     package_version: VERSION,
@@ -315,6 +318,7 @@ function writeRuntimeState(actualPort) {
     },
     computer_id: computer?.computer_id || process.env.AMALGM_COMPUTER_ID || '',
     user_id: computer?.user_id || process.env.AMALGM_USER_ID || '',
+    services: Array.isArray(previous.services) ? previous.services : [],
     updated_at: new Date().toISOString(),
   });
 }