amalgm 0.1.138 → 0.1.139

package/bin/amalgm.js

@@ -22,6 +22,79 @@ if (label && !process.env.AMALGM_RUNTIME_LABEL) process.env.AMALGM_RUNTIME_LABEL
 const userScope = takeFlag(process.argv, ['--user', '--user-id', '--runtime-user']);
 if (userScope && !process.env.AMALGM_RUNTIME_USER_ID) process.env.AMALGM_RUNTIME_USER_ID = userScope;
 
+function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(require('fs').readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function userEmail(record) {
+  return cleanString(record?.user_email || record?.userEmail || record?.email).toLowerCase();
+}
+
+function identityFromDir(dir) {
+  const path = require('path');
+  const record = readJson(path.join(dir, 'computer.json'), null) || {};
+  const auth = readJson(path.join(dir, 'auth.json'), null) || {};
+  const userId = cleanString(record.user_id) || cleanString(auth.user_id);
+  const email = userEmail(record) || userEmail(auth);
+  return userId && email ? { userId, email } : null;
+}
+
+function preflightCanonicalLayout() {
+  if (process.env.AMALGM_HOME || process.env.AMALGM_DIR) return;
+  const fs = require('fs');
+  const os = require('os');
+  const path = require('path');
+  const layout = require('../lib/layout');
+
+  try {
+    require('../lib/migrate-layout').migrateLayout({ home: os.homedir() });
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    console.warn(`[layout] Could not migrate Amalgm root automatically: ${message}`);
+  }
+
+  const homeDir = layout.resolveAmalgmHome(process.env);
+  const identities = [];
+  const rootIdentity = identityFromDir(homeDir);
+  if (rootIdentity) identities.push(rootIdentity);
+
+  for (const entry of layout.listUserEntries(homeDir)) {
+    const entryIdentity = identityFromDir(entry.dir);
+    if (entryIdentity) identities.push(entryIdentity);
+    const runtimesDir = path.join(entry.dir, 'runtimes');
+    let runtimeNames = [];
+    try {
+      runtimeNames = fs.readdirSync(runtimesDir);
+    } catch {}
+    for (const runtimeName of runtimeNames) {
+      const runtimeIdentity = identityFromDir(path.join(runtimesDir, runtimeName));
+      if (runtimeIdentity) identities.push(runtimeIdentity);
+    }
+  }
+
+  for (const identity of identities) {
+    try {
+      layout.ensureUserDir(homeDir, {
+        userId: identity.userId,
+        email: identity.email,
+      });
+    } catch (error) {
+      const message = error && error.message ? error.message : String(error);
+      console.warn(`[layout] Could not adopt email folder for ${identity.userId}: ${message}`);
+    }
+  }
+}
+
+preflightCanonicalLayout();
+
 require('../lib/cli').main(process.argv).catch((error) => {
   const message = error && error.message ? error.message : String(error);
   console.error(`Error: ${message}`);

package/lib/auth-store.js

@@ -67,6 +67,14 @@ function cleanString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : '';
 }
 
+function normalizeUserEmail(value) {
+  return cleanString(value).toLowerCase();
+}
+
+function userEmailFromRecord(record) {
+  return normalizeUserEmail(record?.user_email || record?.userEmail || record?.email);
+}
+
 function hasComputerSecrets(record) {
   if (!record || typeof record !== 'object') return false;
   return Array.from(SECRET_COMPUTER_KEYS).some((key) => cleanString(record[key]));
@@ -77,6 +85,8 @@ function publicComputerRecord(record, authFile = AUTH_FILE) {
     ...(record || {}),
     auth_file: path.basename(authFile),
   };
+  const email = userEmailFromRecord(out);
+  if (email) out.user_email = email;
   for (const key of SECRET_COMPUTER_KEYS) delete out[key];
   return out;
 }
@@ -89,8 +99,10 @@ function authFromRecord(record, existing = null) {
     updated_at: now,
   };
 
-  for (const key of ['computer_id', 'device_id', 'user_id', 'app_url']) {
-    const value = cleanString(record?.[key]);
+  for (const key of ['computer_id', 'device_id', 'user_id', 'user_email', 'app_url']) {
+    const value = key === 'user_email'
+      ? userEmailFromRecord(record)
+      : cleanString(record?.[key]);
     if (value) auth[key] = value;
   }
 
@@ -171,6 +183,7 @@ function mergeRecordAuth(record, auth) {
     merged.proxy_token_refreshed_at = cleanString(auth.proxy?.refreshed_at);
   }
   if (!merged.user_id) merged.user_id = cleanString(auth.user_id);
+  if (!merged.user_email) merged.user_email = normalizeUserEmail(auth.user_email);
   if (!merged.app_url) merged.app_url = cleanString(auth.app_url);
   return merged;
 }
@@ -310,4 +323,5 @@ module.exports = {
   RUNTIME_AUTH_FILE,
   RUNTIME_COMPUTER_FILE,
   saveComputerRecord,
+  userEmailFromRecord,
 };

package/lib/cli.js

@@ -58,6 +58,9 @@ const {
   proxyTokenNeedsRefresh,
   saveComputerRecord,
 } = require('./auth-store');
+const {
+  adoptIdentityFromRecord,
+} = require('./identity-adopt');
 const {
   agentCommandShimStatus,
   binaryStatus,
@@ -72,6 +75,7 @@ const {
 
 const PACKAGE_VERSION = require('../package.json').version;
 const SETUP_CODE_LENGTH = 16;
+const EXPLICIT_AMALGM_DIR = Boolean(process.env.AMALGM_DIR);
 
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -126,7 +130,7 @@ function usage() {
     '  AMALGM_AUTO_UPDATE    Auto-update before start unless set to 0/false/off',
     '  AMALGM_DISABLE_AUTO_UPDATE Set to 1 to disable startup/background auto-updates',
     '  AMALGM_DIR            Explicit runtime state dir override',
-    '  AMALGM_HOME           Runtime state root (default ~/.amalgm)',
+    '  AMALGM_HOME           Runtime state root (default ~/amalgm)',
     '  AMALGM_RUNTIME_LABEL  Runtime label: main, preview, or local',
     '  AMALGM_RUNTIME_USER_ID Runtime user scope',
     '  AMALGM_PROXY_TOKEN    Optional short-lived proxy token override',
@@ -486,15 +490,16 @@ async function registerComputer(appUrl, registrationToken, device, name) {
     app_version: PACKAGE_VERSION,
     registered_at: new Date().toISOString(),
   };
-  saveComputerRecord(record);
+  const saved = saveComputerRecord(record);
+  adoptIdentityFromRecord(saved, { logger: console });
 
-  console.log(`Registered computer: ${record.computer_id}`);
-  console.log(`Events URL: ${record.webhook_url}`);
-  if (!proxyTokenFromRecord(record)) {
+  console.log(`Registered computer: ${saved.computer_id}`);
+  console.log(`Events URL: ${saved.webhook_url}`);
+  if (!proxyTokenFromRecord(saved)) {
     console.log('HMAC proxy: not minted yet; Amalgm-managed egress will refresh after registration is complete.');
   }
   console.log('Run `amalgm start` to connect this machine.');
-  return record;
+  return saved;
 }
 
 async function refreshStoredProxyToken(record) {
@@ -515,12 +520,15 @@ async function refreshStoredProxyToken(record) {
 
   const next = {
     ...record,
+    user_email: refreshed.user_email || record.user_email,
     proxy_token: refreshed.proxy_token || record.proxy_token,
     proxy_token_expires_in: refreshed.proxy_token_expires_in || record.proxy_token_expires_in,
     proxy_token_expires_at: refreshed.proxy_token_expires_at || record.proxy_token_expires_at,
     proxy_token_refreshed_at: new Date().toISOString(),
   };
-  return saveComputerRecord(next);
+  const saved = saveComputerRecord(next);
+  adoptIdentityFromRecord(saved, { logger: console });
+  return saved;
 }
 
 async function loginWithSetupCode(appUrl, setupCode, device, name) {
@@ -811,6 +819,31 @@ function relaunchCurrentCommandAfterUpdate() {
   return Number.isInteger(result.status) ? result.status : 0;
 }
 
+function relaunchCurrentCommandAfterLayoutChange() {
+  const result = spawnSync(process.execPath, process.argv.slice(1), {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      AMALGM_LAYOUT_RELAUNCHED: '1',
+    },
+  });
+  if (result.error) throw result.error;
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    return 1;
+  }
+  return Number.isInteger(result.status) ? result.status : 0;
+}
+
+function shouldRelaunchForAdoptedDir(adoption) {
+  return Boolean(
+    adoption?.dir
+    && !EXPLICIT_AMALGM_DIR
+    && process.env.AMALGM_LAYOUT_RELAUNCHED !== '1'
+    && path.resolve(adoption.dir) !== path.resolve(AMALGM_DIR)
+  );
+}
+
 async function start(options) {
   ensureBaseDirs();
 
@@ -822,6 +855,7 @@ async function start(options) {
   assertRuntimePresent();
 
   let record = loadComputerRecord({ migrate: true });
+  let adoption = adoptIdentityFromRecord(record, { logger: console });
   const localOnly = !!options['local-only'];
   if (!localOnly && !hasRequiredComputerFields(record)) {
     throw new Error('This machine is not logged in. Run `amalgm login` to authorize it in your browser, or use `amalgm start --local-only` for local-only development.');
@@ -829,11 +863,18 @@ async function start(options) {
   if (!localOnly) {
     try {
       record = await refreshStoredProxyToken(record);
+      adoption = adoptIdentityFromRecord(record, { logger: console });
     } catch (error) {
       console.warn(`Could not refresh proxy token before start: ${error.message}`);
     }
   }
 
+  if (shouldRelaunchForAdoptedDir(adoption)) {
+    console.log(`Adopted Amalgm user folder ${adoption.dir}; restarting start command with canonical paths.`);
+    process.exitCode = relaunchCurrentCommandAfterLayoutChange();
+    return;
+  }
+
   ensureAgentRuntimeCommands({ logger: console });
 
   const pid = readPid();

package/lib/identity-adopt.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const {
+  AMALGM_HOME,
+} = require('./paths');
+const layout = require('./layout');
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function normalizeUserEmail(value) {
+  return cleanString(value).toLowerCase();
+}
+
+function userEmailFromRecord(record) {
+  return normalizeUserEmail(record?.user_email || record?.userEmail || record?.email);
+}
+
+function adoptIdentityFromRecord(record, options = {}) {
+  const userId = cleanString(record?.user_id);
+  const email = userEmailFromRecord(record);
+  if (!userId || !email) {
+    return { dir: null, adopted: false, reason: !userId ? 'missing-user-id' : 'missing-email' };
+  }
+
+  const homeDir = options.homeDir || AMALGM_HOME;
+  const logger = options.logger || console;
+  try {
+    const dir = layout.ensureUserDir(homeDir, { userId, email });
+    return { dir, adopted: true };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn?.(`[identity] email folder adoption deferred: ${message}`);
+    return { dir: null, adopted: false, reason: 'error', error: message };
+  }
+}
+
+module.exports = {
+  adoptIdentityFromRecord,
+  normalizeUserEmail,
+  userEmailFromRecord,
+};

package/lib/layout.js

@@ -16,9 +16,10 @@
  * Rules:
  * - The folder name is presentation; `.amalgm-user.json` is identity. If a
  *   folder is renamed, resolution recovers by scanning user manifests.
- * - Legacy layouts (hidden ~/.amalgm, uuid-named user folders) keep working:
- *   resolution falls back to them, and migrate-layout leaves compat symlinks
- *   at the old locations.
+ * - Hidden-root layouts are migrated to the visible root by startup preflight;
+ *   resolution itself does not silently stay on ~/.amalgm.
+ * - UUID-named user folders are compatibility aliases only after email
+ *   adoption. The runtime identity remains the userId in the manifest.
  * - Explicit env (AMALGM_HOME / AMALGM_DIR) always wins — isolated runtimes
  *   and tests depend on that.
  */
@@ -101,16 +102,14 @@ function isAmalgmRoot(dir) {
 /**
  * Where Amalgm state lives on this machine.
  *
- * Order: explicit AMALGM_HOME → initialized visible root (~/amalgm with a
- * root manifest) → migrated hidden alias (~/.amalgm symlink → its target) →
- * legacy hidden root (~/.amalgm directory) → visible root for fresh installs.
+ * Order: explicit AMALGM_HOME → visible root. A migrated ~/.amalgm symlink is
+ * allowed only as a pointer back to the visible root; an old hidden directory
+ * is intentionally ignored so new process trees don't keep depending on it.
  */
 function resolveAmalgmHome(env = process.env) {
   if (env.AMALGM_HOME) return path.resolve(env.AMALGM_HOME);
 
   const visible = visibleRootPath();
-  if (isAmalgmRoot(visible)) return visible;
-
   const hidden = hiddenRootPath();
   const hiddenStat = lstatOrNull(hidden);
   if (hiddenStat?.isSymbolicLink()) {
@@ -121,7 +120,6 @@ function resolveAmalgmHome(env = process.env) {
       return visible;
     }
   }
-  if (hiddenStat) return hidden;
   return visible;
 }
 
@@ -186,6 +184,14 @@ function writeUserManifest(userDir, { userId, email }) {
   return manifest;
 }
 
+function createCompatLink(linkPath, targetPath) {
+  if (process.platform === 'win32') {
+    fs.symlinkSync(targetPath, linkPath, 'junction');
+    return;
+  }
+  fs.symlinkSync(path.basename(targetPath), linkPath);
+}
+
 /** All user folders under <homeDir>/users. Real directories first, compat
  *  symlinks after, both sorted — so scans prefer canonical folders. */
 function listUserEntries(homeDir) {
@@ -299,7 +305,7 @@ function adoptUserEmail(homeDir, { userId, email }) {
   }
 
   fs.renameSync(current, target);
-  fs.symlinkSync(folderName, current); // relative sibling link, relocatable
+  createCompatLink(current, target);
   indexUserFolder(homeDir, folderName, { userId: cleanId, email });
   return { dir: target, renamed: true, from: current };
 }
@@ -321,6 +327,7 @@ module.exports = {
   emailFolderName,
   ensureRootManifest,
   ensureUserDir,
+  createCompatLink,
   findUserDirByUserId,
   hiddenRootPath,
   isAmalgmRoot,

package/lib/migrate-layout.js

@@ -101,7 +101,7 @@ function migrateRoot({ hiddenRoot, visibleRoot, dryRun, actions }) {
   actions.push(`symlink ${hiddenRoot} -> ${path.basename(visibleRoot)}`);
   if (!dryRun) {
     fs.renameSync(hiddenRoot, visibleRoot);
-    fs.symlinkSync(path.basename(visibleRoot), hiddenRoot); // relative sibling link
+    layout.createCompatLink(hiddenRoot, visibleRoot);
   }
   return { moved: true };
 }

package/lib/state-migration.js

@@ -11,6 +11,8 @@ const {
 
 const MARKER_FILE = path.join(AMALGM_DIR, '.user-state-migrated.json');
 const CLI_HOMES_BACKFILL_ID = 'cli-homes-merge-v1';
+const WORKSPACES_BACKFILL_ID = 'workspaces-merge-v1';
+const CONTEXT_BACKFILL_ID = 'context-merge-v1';
 
 const DATA_FILES = [
   'amalgm.db',
@@ -30,6 +32,7 @@ const DATA_DIRS = [
   'apps',
   'browser',
   'browser-sessions',
+  'context',
   'contexts',
   'harness-configs',
   'memories',
@@ -37,6 +40,7 @@ const DATA_DIRS = [
   'task-runs',
   'toolbox',
   'uploads',
+  'workspaces',
 ];
 
 function readJson(file, fallback = null) {
@@ -132,6 +136,8 @@ function migrateLegacyUserState() {
   const hadMarker = Boolean(marker);
   const completedMigrations = markerCompletedMigrations(marker);
   const needsCliHomesBackfill = !completedMigrations.has(CLI_HOMES_BACKFILL_ID);
+  const needsWorkspacesBackfill = !completedMigrations.has(WORKSPACES_BACKFILL_ID);
+  const needsContextBackfill = !completedMigrations.has(CONTEXT_BACKFILL_ID);
 
   fs.mkdirSync(AMALGM_DIR, { recursive: true, mode: 0o700 });
 
@@ -157,7 +163,23 @@ function migrateLegacyUserState() {
     completedMigrations.add(CLI_HOMES_BACKFILL_ID);
   }
 
-  if (!hadMarker || copied.length > 0 || needsCliHomesBackfill) {
+  if (needsWorkspacesBackfill) {
+    const workspacesSource = path.join(AMALGM_HOME, 'workspaces');
+    const workspacesTarget = path.join(AMALGM_DIR, 'workspaces');
+    if (mergeDirContents(workspacesSource, workspacesTarget)) copied.push('workspaces/');
+    completedMigrations.add(WORKSPACES_BACKFILL_ID);
+  }
+
+  if (needsContextBackfill) {
+    // System context (user-authored system-instructions.md) lives in the
+    // singular context/ dir; earlier migrations only covered plural contexts/.
+    const contextSource = path.join(AMALGM_HOME, 'context');
+    const contextTarget = path.join(AMALGM_DIR, 'context');
+    if (mergeDirContents(contextSource, contextTarget)) copied.push('context/');
+    completedMigrations.add(CONTEXT_BACKFILL_ID);
+  }
+
+  if (!hadMarker || copied.length > 0 || needsCliHomesBackfill || needsWorkspacesBackfill || needsContextBackfill) {
     writeJson(MARKER_FILE, {
       migrated_at: marker?.migrated_at || new Date().toISOString(),
       source: AMALGM_HOME,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.138",
+  "version": "0.1.139",
   "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/app-chat.js && node --check lib/react.js && node --check lib/auth-store.js && node --check lib/cli.js && node --check lib/layout.js && node --check lib/migrate-layout.js && node --check lib/paths.js && node --check lib/process-cleanup.js && node --check lib/runtime-identity.js && node --check lib/runtime-manifest.js && node --check lib/service.js && node --check lib/state-migration.js && node --check lib/supervisor.js && node --check lib/tunnel-chat.js && node --check lib/tunnel-events.js && node --check lib/updater.js && node --check runtime/lib/runtime-manifest.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/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/chat-core/tooling/runtime-home.js && node --check runtime/scripts/amalgm-mcp/index.js && node --check runtime/scripts/amalgm-mcp/config.js && node --check runtime/scripts/amalgm-mcp/events/pr-check-runner.js && node --check runtime/scripts/lib/project-paths.js && node --check runtime/scripts/lib/runtime-paths.js"
+    "check": "node --check bin/amalgm.js && node --check lib/app-chat.js && node --check lib/react.js && node --check lib/auth-store.js && node --check lib/cli.js && node --check lib/identity-adopt.js && node --check lib/layout.js && node --check lib/migrate-layout.js && node --check lib/paths.js && node --check lib/process-cleanup.js && node --check lib/runtime-identity.js && node --check lib/runtime-manifest.js && node --check lib/service.js && node --check lib/state-migration.js && node --check lib/supervisor.js && node --check lib/tunnel-chat.js && node --check lib/tunnel-events.js && node --check lib/updater.js && node --check runtime/lib/runtime-manifest.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/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/chat-core/tooling/runtime-home.js && node --check runtime/scripts/amalgm-mcp/index.js && node --check runtime/scripts/amalgm-mcp/config.js && node --check runtime/scripts/amalgm-mcp/events/pr-check-runner.js && node --check runtime/scripts/lib/project-paths.js && node --check runtime/scripts/lib/runtime-paths.js"
   },
   "engines": {
     "node": ">=20"

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

@@ -86,13 +86,18 @@ const BUILTIN_AGENT_BLUEPRINTS = [
   },
 ];
 
+// Every builtin agent starts with the core platform surface. `memories` must
+// be here: project context injected into the prompt names the memory tools,
+// so they have to actually be callable.
+const DEFAULT_BUILTIN_TOOL_IDS = ['agents', 'apps', 'automations', 'browser', 'memories', 'notifications'];
+
 const BUILTIN_AGENTS = BUILTIN_AGENT_BLUEPRINTS.map((agent) => ({
   ...agent,
   systemPrompt: '',
   files: [],
   skills: [],
   mcpAppIds: [],
-  loadout: { toolIds: [] },
+  loadout: { toolIds: [...DEFAULT_BUILTIN_TOOL_IDS] },
   mcp: { inheritAll: false, customServers: [], appIds: [] },
   builtin: false,
   deletable: true,
@@ -462,7 +467,7 @@ function seedBuiltinAgents(options = {}) {
         files: existing?.files || [],
         skills: existing?.skills || [],
         mcpAppIds: existing?.mcpAppIds || [],
-        loadout: existing?.loadout || existing?.tools || { toolIds: [] },
+        loadout: existing?.loadout || existing?.tools || { toolIds: [...DEFAULT_BUILTIN_TOOL_IDS] },
         mcp: {
           inheritAll: false,
           customServers: [],
@@ -755,6 +760,7 @@ function readAgentConvoLog(sessionId, limit = 50) {
 module.exports = {
   BUILTIN_AGENTS,
   BUILTIN_AGENT_IDS,
+  DEFAULT_BUILTIN_TOOL_IDS,
   ensureAgentsDirs,
   loadAgents,
   saveAgents,

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

@@ -7,7 +7,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { spawn } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 const { DEFAULT_CWD } = require('../config');
 const { runtimePort } = require('../../../lib/runtime-manifest');
 const { syncAppRoutesToGateway } = require('./advertise');
@@ -53,6 +53,26 @@ const APP_ENV_ALLOWLIST = [
   'PLAYWRIGHT_BROWSERS_PATH',
 ];
 
+function runtimeEnvFingerprint() {
+  // The part of the inherited env that must match for a saved PID to be
+  // trusted: where the platform stores state. If this moved, the process
+  // predates a layout migration and must be respawned.
+  return process.env.AMALGM_DIR || '';
+}
+
+async function killProcessTree(pid) {
+  try { process.kill(-pid, 'SIGTERM'); } catch {}
+  try { process.kill(pid, 'SIGTERM'); } catch {}
+  const deadline = Date.now() + 3000;
+  while (isProcessAlive(pid) && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  if (isProcessAlive(pid)) {
+    try { process.kill(-pid, 'SIGKILL'); } catch {}
+    try { process.kill(pid, 'SIGKILL'); } catch {}
+  }
+}
+
 function isProcessAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
@@ -63,6 +83,79 @@ function isProcessAlive(pid) {
   }
 }
 
+function parsePids(output) {
+  const pids = new Set();
+  String(output || '').split(/\s+/).forEach((value) => {
+    const pid = Number(value);
+    if (Number.isInteger(pid) && pid > 0) pids.add(pid);
+  });
+  return Array.from(pids);
+}
+
+function listeningPidsForPort(port) {
+  const parsed = Number(port);
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) return [];
+  const result = spawnSync('lsof', ['-nP', `-iTCP:${parsed}`, '-sTCP:LISTEN', '-t'], {
+    encoding: 'utf8',
+  });
+  if (result.error || !result.stdout) return [];
+  return parsePids(result.stdout);
+}
+
+function pidCommand(pid) {
+  const result = spawnSync('ps', ['eww', '-p', String(pid), '-o', 'command='], {
+    encoding: 'utf8',
+  });
+  if (result.error || result.status !== 0) return '';
+  return String(result.stdout || '');
+}
+
+function pidCwd(pid) {
+  const result = spawnSync('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], {
+    encoding: 'utf8',
+  });
+  if (result.error || result.status !== 0) return '';
+  const line = String(result.stdout || '').split('\n').find((item) => item.startsWith('n'));
+  return line ? line.slice(1) : '';
+}
+
+function isPathInside(parent, maybeChild) {
+  if (!parent || !maybeChild) return false;
+  const relative = path.relative(path.resolve(parent), path.resolve(maybeChild));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function isAppOwnedPid(app, pid) {
+  if (app.pid === pid) return true;
+  const command = pidCommand(pid);
+  if (command.includes(`AMALGM_APP_ID=${app.id}`) || command.includes(`AMALGM_APP_ID='${app.id}'`)) return true;
+  if (app.appRef && (command.includes(`AMALGM_APP_REF=${app.appRef}`) || command.includes(`AMALGM_APP_REF='${app.appRef}'`))) {
+    return true;
+  }
+  if (app.cwd && command.includes(path.resolve(app.cwd))) return true;
+  return isPathInside(app.cwd, pidCwd(pid));
+}
+
+async function killOwnedPortListeners(app, options = {}) {
+  const pids = listeningPidsForPort(app.port).filter((pid) => pid !== process.pid);
+  if (pids.length === 0) return [];
+
+  const owned = [];
+  const unknown = [];
+  for (const pid of pids) {
+    (isAppOwnedPid(app, pid) ? owned : unknown).push(pid);
+  }
+
+  if (unknown.length > 0 && options.failOnUnknown !== false) {
+    throw new Error(`Port ${app.port} is already in use by pid(s) ${unknown.join(', ')}; refusing to kill non-app process`);
+  }
+
+  for (const pid of owned) {
+    await killProcessTree(pid);
+  }
+  return owned;
+}
+
 async function syncRoutesBestEffort(reason) {
   try {
     await syncAppRoutesToGateway(reason);
@@ -215,24 +308,34 @@ async function startApp(appId) {
   }
 
   if (app.pid && isProcessAlive(app.pid)) {
-    const current = updateAppMeta(app.id, {
-      desiredState: 'running',
-      status: 'running',
-      error: null,
-    });
-    await syncRoutesBestEffort(`start:${appId}`);
-    return current;
+    if ((app.envFingerprint || '') === runtimeEnvFingerprint()) {
+      const current = updateAppMeta(app.id, {
+        desiredState: 'running',
+        status: 'running',
+        error: null,
+      });
+      await syncRoutesBestEffort(`start:${appId}`);
+      return current;
+    }
+    // The saved process was spawned under a different runtime env (e.g. the
+    // storage layout moved); adopting it would keep an app alive against
+    // stale AMALGM_* paths. Replace it.
+    await killProcessTree(app.pid);
+    updateAppMeta(app.id, { pid: null });
   }
 
   if (app.pid && !isProcessAlive(app.pid)) {
     updateAppMeta(app.id, { pid: null });
   }
 
+  await killOwnedPortListeners(app);
+
   const child = startAppProcess(app);
   const current = updateAppMeta(app.id, {
     desiredState: 'running',
     status: 'running',
     pid: child.pid,
+    envFingerprint: runtimeEnvFingerprint(),
     error: null,
     lastStartedAt: new Date().toISOString(),
   });
@@ -251,11 +354,13 @@ async function stopApp(appId, options = {}) {
 
   const child = running.get(appId);
   if (child?.pid) {
-    try { process.kill(-child.pid, 'SIGTERM'); } catch {}
-    try { child.kill('SIGTERM'); } catch {}
+    await killProcessTree(child.pid);
   } else if (app.pid) {
-    try { process.kill(app.pid, 'SIGTERM'); } catch {}
+    await killProcessTree(app.pid);
   }
+  await killOwnedPortListeners(app, { failOnUnknown: false }).catch((err) => {
+    console.warn(`[Apps] Could not clean listeners for ${appId} on port ${app.port}: ${err.message}`);
+  });
   running.delete(appId);
 
   setTimeout(() => stopping.delete(appId), 1000);