amalgm 0.1.138 → 0.1.139

package/runtime/scripts/amalgm-mcp/browser/backend.js

@@ -39,14 +39,17 @@ function pidIsRunning(pid) {
  */
 function bridgeFileCandidates() {
   const path = require('path');
-  const os = require('os');
   const dirs = [];
   if (process.env.AMALGM_RUNTIME_STATE_DIR) dirs.push(process.env.AMALGM_RUNTIME_STATE_DIR);
   const amalgmDir = process.env.AMALGM_DIR;
   const label = process.env.AMALGM_RUNTIME_LABEL || process.env.AMALGM_BRANCH;
   if (amalgmDir && label) dirs.push(path.join(amalgmDir, 'runtimes', label));
   if (amalgmDir) dirs.push(amalgmDir);
-  dirs.push(path.join(os.homedir(), '.amalgm'));
+  else {
+    try {
+      dirs.push(require('../../lib/runtime-paths').amalgmDir());
+    } catch {}
+  }
   return [...new Set(dirs)].map((dir) => path.join(dir, 'electron-browser-bridge.json'));
 }
 

package/runtime/scripts/amalgm-mcp/browser/cli.js

@@ -20,12 +20,13 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawn } = require('child_process');
+const { amalgmDir: resolveAmalgmDir } = require('../../lib/runtime-paths');
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DEFAULT_SESSION = 'default';
 
 function amalgmDir() {
-  return process.env.AMALGM_DIR || path.join(os.homedir(), '.amalgm');
+  return resolveAmalgmDir();
 }
 
 function ensureDir(dir) {

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

@@ -9,18 +9,21 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const runtimePaths = require('../lib/runtime-paths');
 
 const PORT = parseInt(process.env.AMALGM_MCP_PORT || '8083', 10);
 const MCP_PROTOCOL_VERSION = '2024-11-05';
 const CLI_HOMES_BACKFILL_ID = 'cli-homes-merge-v1';
+const WORKSPACES_BACKFILL_ID = 'workspaces-merge-v1';
+const CONTEXT_BACKFILL_ID = 'context-merge-v1';
 
-// Layout-aware home: visible ~/amalgm once initialized, legacy ~/.amalgm
-// otherwise. Explicit env always wins (isolated runtimes, tests).
+// Layout-aware home: visible ~/amalgm once initialized. User storage resolves
+// under users/<identity>; the root is only installation/device state.
 const AMALGM_HOME = require('./lib/layout').resolveAmalgmHome(process.env);
-const AMALGM_DIR = process.env.AMALGM_DIR || AMALGM_HOME;
+const AMALGM_DIR = process.env.AMALGM_DIR || runtimePaths.amalgmDir();
 const AMALGM_RUNTIME_LABEL = normalizeRuntimeLabel(process.env.AMALGM_RUNTIME_LABEL || process.env.AMALGM_BRANCH);
 const AMALGM_RUNTIME_STATE_DIR = process.env.AMALGM_RUNTIME_STATE_DIR
-  || path.join(AMALGM_DIR, 'runtimes', AMALGM_RUNTIME_LABEL);
+  || runtimePaths.runtimeStateDir();
 
 // Storage file/dir layout under AMALGM_DIR.
 const STORAGE_DIR = AMALGM_DIR; // tasks.json etc. live directly under ~/.amalgm
@@ -179,6 +182,8 @@ function migrateLegacyUserState() {
   const hadMarker = Boolean(markerData);
   const completedMigrations = markerCompletedMigrations(markerData);
   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 });
 
   const copied = [];
@@ -208,7 +213,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) is the singular
+    // context/ dir; earlier passes only migrated per-project state.
+    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) {
     fs.writeFileSync(marker, `${JSON.stringify({
       migrated_at: markerData?.migrated_at || new Date().toISOString(),
       source: AMALGM_HOME,

package/runtime/scripts/amalgm-mcp/events/desktop-release-runner.js

@@ -6,6 +6,7 @@ const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const yaml = require('js-yaml');
+const { resolveAmalgmHome } = require('../lib/layout');
 
 const ENGINE_REPO_FULL_NAME = 'amalgm-inc/amalgm-engine';
 const UI_REPO_FULL_NAME = 'amalgm-inc/amalgm-ui';
@@ -13,8 +14,9 @@ const DEFAULT_DESKTOP_RELEASE_REPO_FULL_NAME = 'amalgm-inc/amalgm-desktop-releas
 const DEFAULT_DESKTOP_LEGACY_BRIDGE_REPO_FULL_NAME = ENGINE_REPO_FULL_NAME;
 const DEFAULT_ENGINE_REPO_URL = 'https://github.com/amalgm-inc/amalgm-engine.git';
 const DEFAULT_UI_REPO_URL = 'https://github.com/amalgm-inc/amalgm-ui.git';
-const DEFAULT_CHECKOUT_ROOT = path.join(os.homedir(), '.amalgm', 'workflow-checkouts', 'amalgm-desktop-release');
-const DEFAULT_ENV_FILE = path.join(os.homedir(), '.amalgm', 'desktop-release.env');
+const AMALGM_HOME = resolveAmalgmHome(process.env);
+const DEFAULT_CHECKOUT_ROOT = path.join(AMALGM_HOME, 'workflow-checkouts', 'amalgm-desktop-release');
+const DEFAULT_ENV_FILE = path.join(AMALGM_HOME, 'desktop-release.env');
 const DEFAULT_CSC_NAME = 'amalgm, Inc. (C5S6UATV3L)';
 const DEFAULT_DESKTOP_UPDATE_BASE_URL = 'https://amalgm-desktop-releases.fly.dev';
 const DEFAULT_DESKTOP_RELEASE_FLY_APP = 'amalgm-desktop-releases';
@@ -119,6 +121,29 @@ function notarytoolCredentialArgs(env = process.env) {
   throw new Error('Missing Apple notarization credentials for manual desktop release notarization.');
 }
 
+function notarytoolSubmitTransportArgs(env = process.env) {
+  const raw = cleanString(env.AMALGM_DESKTOP_NOTARY_S3_ACCELERATION).toLowerCase();
+  if (!raw || ['0', 'false', 'no', 'off'].includes(raw)) return ['--no-s3-acceleration'];
+  if (['1', 'true', 'yes', 'on'].includes(raw)) return [];
+  throw new Error(`Unsupported AMALGM_DESKTOP_NOTARY_S3_ACCELERATION value: ${raw}`);
+}
+
+function prepareNotarySubmissionFile(filePath) {
+  const ext = path.extname(filePath) || '.dmg';
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-notary-submit-'));
+  const tempPath = path.join(
+    tempRoot,
+    `amalgm-notary-${process.pid}-${Date.now()}-${crypto.randomBytes(4).toString('hex')}${ext}`,
+  );
+  fs.copyFileSync(filePath, tempPath);
+  return {
+    filePath: tempPath,
+    cleanup() {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    },
+  };
+}
+
 function parseRepoFullName(value) {
   const raw = cleanString(value);
   const match = /^([^/\s]+)\/([^/\s]+)$/.exec(raw);
@@ -684,6 +709,13 @@ function envForBuild(
     DESKTOP_RELEASE_LANE: request.lane,
     DESKTOP_RELEASE_CHANNEL: request.lane === 'preview' ? 'preview' : 'latest',
     AMALGM_DESKTOP_THIN: desktopThinRuntimeBuildEnabled(baseEnv) ? '1' : '0',
+    AMALGM_DESKTOP_RENDERER_DELIVERY: desktopRendererDelivery(baseEnv),
+    AMALGM_DESKTOP_RUNTIME_DELIVERY: desktopRuntimeDelivery(baseEnv),
+    ...(desktopRendererDelivery(baseEnv) === 'bundled-next' ? {
+      NEXT_IMAGE_UNOPTIMIZED: '1',
+      NEXT_PUBLIC_SUPABASE_URL: '',
+      NEXT_PUBLIC_SUPABASE_ANON_KEY: '',
+    } : {}),
     AMALGM_RUNTIME_LABEL: request.lane === 'preview' ? 'preview' : 'main',
     AMALGM_BRANCH: request.lane,
     ELECTRON_VERSION: version,
@@ -737,6 +769,26 @@ function desktopThinRuntimeBuildEnabled(env = process.env) {
   throw new Error(`Unsupported AMALGM_DESKTOP_THIN value: ${raw}`);
 }
 
+function desktopRendererDelivery(env = process.env) {
+  const raw = cleanString(
+    env.AMALGM_DESKTOP_RENDERER_DELIVERY
+    || env.AMALGM_DESKTOP_UI_DELIVERY
+    || (cleanString(env.AMALGM_DESKTOP_UI_MODE).toLowerCase() === 'local' ? 'bundled-next' : ''),
+  ).toLowerCase();
+  if (!raw) return desktopThinRuntimeBuildEnabled(env) ? 'hosted' : 'bundled-next';
+  if (['hosted', 'remote', 'web'].includes(raw)) return 'hosted';
+  if (['bundled-next', 'bundled', 'local', 'next', 'local-next'].includes(raw)) return 'bundled-next';
+  throw new Error(`Unsupported AMALGM_DESKTOP_RENDERER_DELIVERY value: ${raw}`);
+}
+
+function desktopRuntimeDelivery(env = process.env) {
+  const raw = cleanString(env.AMALGM_DESKTOP_RUNTIME_DELIVERY).toLowerCase();
+  if (!raw) return desktopThinRuntimeBuildEnabled(env) ? 'npm' : 'bundled-with-npm-handoff';
+  if (['npm', 'managed-npm'].includes(raw)) return 'npm';
+  if (['bundled-with-npm-handoff', 'bundled', 'local', 'embedded'].includes(raw)) return 'bundled-with-npm-handoff';
+  throw new Error(`Unsupported AMALGM_DESKTOP_RUNTIME_DELIVERY value: ${raw}`);
+}
+
 function appOriginForLane(lane, env = process.env) {
   if (lane === 'preview') {
     return cleanString(env.AMALGM_DESKTOP_PREVIEW_APP_ORIGIN)
@@ -749,14 +801,8 @@ function appOriginForLane(lane, env = process.env) {
 }
 
 function writeBundledWebEnv(engineDir, lane, env = process.env) {
-  const supabaseUrl = cleanString(env.NEXT_PUBLIC_SUPABASE_URL);
-  const supabaseAnonKey = cleanString(env.NEXT_PUBLIC_SUPABASE_ANON_KEY);
-  if (!supabaseUrl) throw new Error('Missing NEXT_PUBLIC_SUPABASE_URL for bundled desktop web app.');
-  if (!supabaseAnonKey) throw new Error('Missing NEXT_PUBLIC_SUPABASE_ANON_KEY for bundled desktop web app.');
   const appOrigin = appOriginForLane(lane, env);
   fs.writeFileSync(path.join(engineDir, 'web', '.env'), [
-    `NEXT_PUBLIC_SUPABASE_URL=${supabaseUrl}`,
-    `NEXT_PUBLIC_SUPABASE_ANON_KEY=${supabaseAnonKey}`,
     `NEXT_PUBLIC_SITE_URL=${appOrigin}`,
     `NEXT_PUBLIC_APP_URL=${appOrigin}`,
     `NEXT_PUBLIC_AMALGM_RUNTIME_LABEL=${lane === 'preview' ? 'preview' : 'main'}`,
@@ -1015,46 +1061,52 @@ function waitForNotaryDecision(submissionId, artifactName, cwd, env, authArgs) {
 function submitArtifactForNotarization(filePath, cwd, env) {
   const { args: authArgs, credentialType } = notarytoolCredentialArgs(env);
   const startedAtMs = Date.now();
-  const artifactName = path.basename(filePath);
-  const result = runResult('xcrun', [
-    'notarytool',
-    'submit',
-    filePath,
-    ...authArgs,
-    '--no-progress',
-    '--output-format',
-    'json',
-  ], {
-    cwd,
-    env,
-    maxBuffer: 10 * 1024 * 1024,
-  });
+  const submissionFile = prepareNotarySubmissionFile(filePath);
+  const artifactName = path.basename(submissionFile.filePath);
+  try {
+    const result = runResult('xcrun', [
+      'notarytool',
+      'submit',
+      submissionFile.filePath,
+      ...notarytoolSubmitTransportArgs(env),
+      ...authArgs,
+      '--no-progress',
+      '--output-format',
+      'json',
+    ], {
+      cwd,
+      env,
+      maxBuffer: 10 * 1024 * 1024,
+    });
 
-  let submissionId = '';
-  if (cleanString(result.stdout)) {
-    try {
-      submissionId = parseNotarySubmissionId(parseJsonOutput(result.stdout, 'notarytool submit'));
-    } catch {
-      submissionId = '';
+    let submissionId = '';
+    if (cleanString(result.stdout)) {
+      try {
+        submissionId = parseNotarySubmissionId(parseJsonOutput(result.stdout, 'notarytool submit'));
+      } catch {
+        submissionId = '';
+      }
+    }
+    if (!submissionId) {
+      submissionId = parseNotarySubmissionId(waitForNotarySubmission(artifactName, startedAtMs, cwd, env, authArgs));
+    }
+    if (!submissionId) {
+      throw new Error(`Failed to resolve notary submission id for ${artifactName}.`);
+    }
+    if (result.status !== 0) {
+      console.warn(`notarytool submit exited with code ${result.status} for ${artifactName}; continuing with submission ${submissionId}.`);
     }
-  }
-  if (!submissionId) {
-    submissionId = parseNotarySubmissionId(waitForNotarySubmission(artifactName, startedAtMs, cwd, env, authArgs));
-  }
-  if (!submissionId) {
-    throw new Error(`Failed to resolve notary submission id for ${artifactName}.`);
-  }
-  if (result.status !== 0) {
-    console.warn(`notarytool submit exited with code ${result.status} for ${artifactName}; continuing with submission ${submissionId}.`);
-  }
 
-  const info = waitForNotaryDecision(submissionId, artifactName, cwd, env, authArgs);
-  return {
-    id: submissionId,
-    status: parseNotaryStatus(info),
-    credentialType,
-    info,
-  };
+    const info = waitForNotaryDecision(submissionId, artifactName, cwd, env, authArgs);
+    return {
+      id: submissionId,
+      status: parseNotaryStatus(info),
+      credentialType,
+      info,
+    };
+  } finally {
+    submissionFile.cleanup();
+  }
 }
 
 function manualNotarizeDesktopArtifacts({ engineDir, lane, env, artifactPaths, channelPath }) {
@@ -1701,18 +1753,30 @@ function publishDesktopRelease(request, options = {}) {
   run('git', ['push', 'origin', `refs/tags/v${version}`, '--force'], { cwd: engineDir });
   run('npm', ['version', '--no-git-tag-version', '--allow-same-version', version], { cwd: engineDir, env: releaseEnv });
   run('npm', ['run', 'compile'], { cwd: engineDir, env: releaseEnv });
-  const thinRuntimeBuild = desktopThinRuntimeBuildEnabled(releaseEnv);
+  const rendererDelivery = desktopRendererDelivery(releaseEnv);
+  const runtimeDelivery = desktopRuntimeDelivery(releaseEnv);
+  const hostedRenderer = rendererDelivery === 'hosted';
+  const npmRuntime = runtimeDelivery === 'npm';
   let appOrigin = appOriginForLane(request.lane, releaseEnv);
-  if (thinRuntimeBuild) {
-    if (!cleanString(releaseEnv.NEXT_PUBLIC_SUPABASE_URL)) {
-      throw new Error('Missing NEXT_PUBLIC_SUPABASE_URL for thin desktop auth metadata.');
-    }
-    console.log('Building thin hosted-UI desktop shell; skipping bundled runtime and Next.js renderer payload.');
+  if (hostedRenderer) {
+    console.log('Building hosted-UI desktop shell; skipping bundled Next.js renderer payload.');
   } else {
-    run('npm', ['run', 'npm:sync'], { cwd: engineDir, env: releaseEnv });
     copyUiIntoEngine(uiDir, engineDir);
     appOrigin = writeBundledWebEnv(engineDir, request.lane, releaseEnv);
-    run('npm', ['run', 'build:next'], { cwd: engineDir, env: releaseEnv });
+    run('npm', ['run', 'build:next'], {
+      cwd: engineDir,
+      env: {
+        ...releaseEnv,
+        NEXT_IMAGE_UNOPTIMIZED: '1',
+        NEXT_PUBLIC_SUPABASE_URL: '',
+        NEXT_PUBLIC_SUPABASE_ANON_KEY: '',
+      },
+    });
+  }
+  if (npmRuntime) {
+    console.log('Building desktop shell with managed npm runtime; skipping bundled engine runtime payload.');
+  } else {
+    run('npm', ['run', 'npm:sync'], { cwd: engineDir, env: releaseEnv });
   }
   if (request.lane === 'preview') run('npm', ['run', 'assets:preview-icon'], { cwd: engineDir, env: releaseEnv });
 
@@ -1826,7 +1890,9 @@ module.exports = {
   envForBuild,
   manualDesktopNotarizationEnabled,
   notarytoolCredentialArgs,
+  notarytoolSubmitTransportArgs,
   parseEnvFile,
+  prepareNotarySubmissionFile,
   parseUploadOffsetMismatch,
   publishLegacyGithubBridgeRelease,
   publishDesktopRelease,

package/runtime/scripts/amalgm-mcp/events/internal-workflows.js

@@ -1,8 +1,8 @@
 'use strict';
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
+const { resolveAmalgmHome } = require('../lib/layout');
 
 function findEngineRepoPath() {
   const explicit = process.env.AMALGM_ENGINE_REPO_PATH;
@@ -137,7 +137,7 @@ function engineNpmPublishWorkflow(repoPath) {
 function internalWorkflowSeeds() {
   if (!findEngineRepoPath()) return [];
   const repoPath = process.env.AMALGM_ENGINE_PUBLISH_REPO_PATH
-    || path.join(os.homedir(), '.amalgm', 'workflow-checkouts', 'amalgm-engine-publish');
+    || path.join(resolveAmalgmHome(process.env), 'workflow-checkouts', 'amalgm-engine-publish');
 
   return [
     {

package/runtime/scripts/amalgm-mcp/events/npm-release-runner.js

@@ -4,11 +4,13 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { resolveAmalgmHome } = require('../lib/layout');
 
 const ENGINE_REPO_FULL_NAME = 'amalgm-inc/amalgm-engine';
 const DEFAULT_ENGINE_REPO_URL = 'https://github.com/amalgm-inc/amalgm-engine.git';
-const DEFAULT_CHECKOUT_ROOT = path.join(os.homedir(), '.amalgm', 'workflow-checkouts', 'amalgm-npm-release');
-const DEFAULT_ENV_FILE = path.join(os.homedir(), '.amalgm', 'npm-release.env');
+const AMALGM_HOME = resolveAmalgmHome(process.env);
+const DEFAULT_CHECKOUT_ROOT = path.join(AMALGM_HOME, 'workflow-checkouts', 'amalgm-npm-release');
+const DEFAULT_ENV_FILE = path.join(AMALGM_HOME, 'npm-release.env');
 
 function cleanString(value) {
   return typeof value === 'string' ? value.trim() : '';

package/runtime/scripts/amalgm-mcp/events/pr-check-runner.js

@@ -4,13 +4,15 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { resolveAmalgmHome } = require('../lib/layout');
 
 const ENGINE_REPO_FULL_NAME = 'amalgm-inc/amalgm-engine';
 const UI_REPO_FULL_NAME = 'amalgm-inc/amalgm-ui';
 const DEFAULT_ENGINE_REPO_URL = 'https://github.com/amalgm-inc/amalgm-engine.git';
 const DEFAULT_UI_REPO_URL = 'https://github.com/amalgm-inc/amalgm-ui.git';
-const DEFAULT_CHECKOUT_ROOT = path.join(os.homedir(), '.amalgm', 'workflow-checkouts', 'amalgm-pr-check');
-const DEFAULT_ENV_FILE = path.join(os.homedir(), '.amalgm', 'pr-check.env');
+const AMALGM_HOME = resolveAmalgmHome(process.env);
+const DEFAULT_CHECKOUT_ROOT = path.join(AMALGM_HOME, 'workflow-checkouts', 'amalgm-pr-check');
+const DEFAULT_ENV_FILE = path.join(AMALGM_HOME, 'pr-check.env');
 const DEFAULT_STATUS_CONTEXT = 'amalgm/pr-check';
 
 function cleanString(value) {

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

@@ -61,8 +61,26 @@ function isHiddenFilesystemEntry(name) {
 
 function expandHome(targetPath) {
   if (targetPath === '~') return os.homedir();
+  // Platform-data token: clients address the user's amalgm data dir without
+  // knowing the on-disk layout (email folder, machine differences). This is
+  // the contract for uploads and md-library paths from the UI.
+  if (targetPath === '~amalgm') return AMALGM_DIR;
+  if (typeof targetPath === 'string' && targetPath.startsWith('~amalgm/')) {
+    return path.join(AMALGM_DIR, targetPath.slice('~amalgm/'.length));
+  }
   if (typeof targetPath === 'string' && targetPath.startsWith('~/')) {
-    return path.join(os.homedir(), targetPath.slice(2));
+    const expanded = path.join(os.homedir(), targetPath.slice(2));
+    // Transitional wire-compat: UI builds deployed before 2026-07-03 address
+    // platform data via the old hidden layout (uploads, notes-files,
+    // browser-sessions, ...). Redirect the whole legacy prefix into the user
+    // data dir — the wire-level equivalent of the removed ~/.amalgm symlink —
+    // so the hidden dir is never recreated on disk. Remove once all deployed
+    // UIs send ~amalgm/... paths.
+    const legacyHiddenRoot = path.join(os.homedir(), '.amalgm');
+    if (expanded === legacyHiddenRoot || expanded.startsWith(legacyHiddenRoot + path.sep)) {
+      return path.join(AMALGM_DIR, path.relative(legacyHiddenRoot, expanded));
+    }
+    return expanded;
   }
   return targetPath;
 }
@@ -772,6 +790,7 @@ module.exports = {
   handleWrite,
   _private: {
     buildFilesResource,
+    expandHome,
     buildUploadsResource,
     configuredRootPaths,
     filesResourceName,

package/runtime/scripts/amalgm-mcp/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/runtime/scripts/amalgm-mcp/lib/mcp-resolver.js

@@ -1,10 +1,10 @@
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
 
 const { buildSessionConfig, getMcpApp } = require('../../../lib/mcpApps/registry.js');
+const { amalgmDir } = require('../../lib/runtime-paths');
 
-const CONNECTIONS_FILE = path.join(os.homedir(), '.amalgm', 'mcp-connections.json');
+const CONNECTIONS_FILE = path.join(process.env.AMALGM_DIR || amalgmDir(), 'mcp-connections.json');
 
 function readConnectionsFile() {
   try {

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

@@ -155,15 +155,37 @@ function resolveProject(inputPath) {
 
 function projectFromInput(input) {
   if (input && typeof input === 'object' && cleanString(input.path)) {
+    // Workspace records must go through the same path canonicalization as
+    // string inputs. Boot/list passes feed raw row paths here; without this,
+    // a legacy managed-copy path and its canonical checkout fight over the
+    // same project row (each pass re-pins projectPath to its own view).
+    const canonical = canonicalProjectPath(input.path) || path.resolve(input.path);
     return {
       id: cleanString(input.id) || null,
-      path: path.resolve(input.path),
-      name: cleanString(input.name) || path.basename(path.resolve(input.path)),
+      path: canonical,
+      name: cleanString(input.name) || path.basename(canonical),
     };
   }
   return resolveProject(input);
 }
 
+function unregisteredProjectError(inputPath) {
+  const requested = cleanString(typeof inputPath === 'string' ? inputPath : inputPath?.path) || '(no path)';
+  let known = [];
+  try {
+    known = require('../workspace/store')
+      .listWorkspaces()
+      .map((workspace) => workspace?.path)
+      .filter(Boolean);
+  } catch {
+    // Listing is best-effort; the error is still actionable without it.
+  }
+  const hint = known.length
+    ? ` Registered project roots: ${known.join(', ')}.`
+    : ' No workspaces are registered on this computer.';
+  return new Error(`No registered Amalgm project contains: ${requested}.${hint} Register the checkout as a workspace or pass projectPath explicitly.`);
+}
+
 function atomicWrite(filePath, content) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
@@ -481,7 +503,7 @@ function listProjectContexts(options = {}) {
 function appendChangeLog(inputPath, body, options = {}) {
   const project = projectFromInput(inputPath);
   if (!project?.id) {
-    throw new Error(`No registered Amalgm project contains: ${cleanString(typeof inputPath === 'string' ? inputPath : inputPath?.path) || '(no path)'}`);
+    throw unregisteredProjectError(inputPath);
   }
   if (isSystemProject(project)) {
     throw new Error('The system context has system-instructions.md only — change logs are per-project.');
@@ -511,7 +533,7 @@ function appendChangeLog(inputPath, body, options = {}) {
 function writeContextDoc(inputPath, docKey, content, options = {}) {
   const project = projectFromInput(inputPath);
   if (!project?.id) {
-    throw new Error(`No registered Amalgm project contains: ${cleanString(typeof inputPath === 'string' ? inputPath : inputPath?.path) || '(no path)'}`);
+    throw unregisteredProjectError(inputPath);
   }
   if (isSystemProject(project) && docKey !== 'instructions') {
     throw new Error('The system context has system-instructions.md only — project goals, project state, and change logs are per-project.');
@@ -599,7 +621,7 @@ function upsertNoteSection(current, title, body) {
 function upsertProjectNote(inputPath, title, body, options = {}) {
   const project = projectFromInput(inputPath);
   if (!project?.id) {
-    throw new Error(`No registered Amalgm project contains: ${cleanString(typeof inputPath === 'string' ? inputPath : inputPath?.path) || '(no path)'}`);
+    throw unregisteredProjectError(inputPath);
   }
   if (isSystemProject(project)) {
     throw new Error('The system context has system-instructions.md only — project notes are per-project.');

package/runtime/scripts/amalgm-mcp/tests/agents-source-of-truth.test.js

@@ -120,3 +120,16 @@ test('agents create REST preserves caller id and creates per-agent config', asyn
   assert.equal(response.payload.agent.config.runtimeHomeLayout, 'per-agent');
   assert.equal(getAgentConfig(agentId).runtimeHomeLayout, 'per-agent');
 });
+
+test('freshly seeded builtin agents carry the default platform loadout including memories', () => {
+  const { DEFAULT_BUILTIN_TOOL_IDS } = require('../agents/store');
+  assert.ok(DEFAULT_BUILTIN_TOOL_IDS.includes('memories'));
+  for (const id of ['claude_code', 'codex']) {
+    const agent = getAllAgentsWithBuiltins().find((candidate) => candidate.id === id);
+    assert.ok(agent, `${id} should exist`);
+    assert.ok(
+      agent.loadout.toolIds.includes('memories'),
+      `${id} loadout should include memories, got: ${JSON.stringify(agent.loadout.toolIds)}`,
+    );
+  }
+});