amalgm 0.1.138 → 0.1.139

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

@@ -0,0 +1,190 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const http = require('http');
+const net = require('net');
+const os = require('os');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-app-supervisor-'));
+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');
+
+const { saveApps } = require('../apps/store');
+const { startApp, stopApp } = require('../apps/supervisor');
+
+function hasLsof() {
+  const result = spawnSync('lsof', ['-v'], { encoding: 'utf8' });
+  return !result.error;
+}
+
+function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+function waitFor(predicate, label) {
+  const deadline = Date.now() + 5000;
+  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 requestBody(port) {
+  return new Promise((resolve, reject) => {
+    const req = http.get({ hostname: '127.0.0.1', port, path: '/', timeout: 1000 }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => resolve(body));
+    });
+    req.on('error', reject);
+    req.on('timeout', () => {
+      req.destroy(new Error('request timed out'));
+    });
+  });
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function killPid(pid) {
+  if (!pid || !isAlive(pid)) return;
+  try { process.kill(-pid, 'SIGTERM'); } catch {}
+  try { process.kill(pid, 'SIGTERM'); } catch {}
+}
+
+function writeServerScript(dir, response) {
+  const file = path.join(dir, `${response}-server.js`);
+  fs.writeFileSync(
+    file,
+    `require('http').createServer((req,res)=>res.end(${JSON.stringify(response)})).listen(Number(process.env.PORT || process.argv[2]), '0.0.0.0');\n`,
+  );
+  return file;
+}
+
+function spawnServer(script, port, cwd, extraEnv = {}) {
+  const child = spawn(process.execPath, [script, String(port)], {
+    cwd,
+    detached: true,
+    env: { ...process.env, ...extraEnv },
+    stdio: 'ignore',
+  });
+  child.unref();
+  return child;
+}
+
+test('startApp clears an app-owned orphan listener when the saved pid is gone', async (t) => {
+  if (!hasLsof()) {
+    t.skip('lsof is required for port-owner cleanup');
+    return;
+  }
+
+  const appCwd = fs.mkdtempSync(path.join(tempRoot, 'owned-app-'));
+  const staleCwd = path.join(appCwd, '.next', 'standalone');
+  fs.mkdirSync(staleCwd, { recursive: true });
+  const freshScript = writeServerScript(appCwd, 'fresh');
+  const staleScript = writeServerScript(appCwd, 'stale');
+  const port = await getFreePort();
+
+  const stale = spawnServer(staleScript, port, staleCwd);
+  t.after(() => {
+    killPid(stale.pid);
+    stopApp('app-owned-orphan').catch(() => {});
+  });
+  await waitFor(async () => (await requestBody(port)) === 'stale', 'stale app listener');
+
+  saveApps({
+    version: 1,
+    apps: [{
+      id: 'app-owned-orphan',
+      kind: 'app',
+      name: 'Owned Orphan',
+      cwd: appCwd,
+      port,
+      startCommand: `"${process.execPath}" "${freshScript}"`,
+      appRef: 'ownedorphan',
+      publicUrl: 'https://ownedorphan.apps.amalgm.ai/',
+      dnsConnected: false,
+      autostart: true,
+      keepAlive: true,
+      desiredState: 'running',
+      status: 'restarting',
+      pid: null,
+    }],
+  });
+
+  const app = await startApp('app-owned-orphan');
+  assert.equal(app.status, 'running');
+  assert.equal(app.pid > 0, true);
+  await waitFor(() => !isAlive(stale.pid), 'stale listener exit');
+  await waitFor(async () => (await requestBody(port)) === 'fresh', 'fresh app listener');
+});
+
+test('startApp refuses to kill an unknown listener on the requested port', async (t) => {
+  if (!hasLsof()) {
+    t.skip('lsof is required for port-owner cleanup');
+    return;
+  }
+
+  const appCwd = fs.mkdtempSync(path.join(tempRoot, 'unknown-app-'));
+  const unrelatedCwd = fs.mkdtempSync(path.join(tempRoot, 'unrelated-'));
+  const unrelatedScript = writeServerScript(unrelatedCwd, 'unrelated');
+  const freshScript = writeServerScript(appCwd, 'fresh');
+  const port = await getFreePort();
+
+  const unrelated = spawnServer(unrelatedScript, port, unrelatedCwd);
+  t.after(() => killPid(unrelated.pid));
+  await waitFor(async () => (await requestBody(port)) === 'unrelated', 'unrelated listener');
+
+  saveApps({
+    version: 1,
+    apps: [{
+      id: 'app-unknown-port',
+      kind: 'app',
+      name: 'Unknown Port',
+      cwd: appCwd,
+      port,
+      startCommand: `"${process.execPath}" "${freshScript}"`,
+      appRef: 'unknownport',
+      publicUrl: 'https://unknownport.apps.amalgm.ai/',
+      dnsConnected: false,
+      autostart: true,
+      keepAlive: true,
+      desiredState: 'running',
+      status: 'restarting',
+      pid: null,
+    }],
+  });
+
+  await assert.rejects(
+    () => startApp('app-unknown-port'),
+    /refusing to kill non-app process/,
+  );
+  assert.equal(isAlive(unrelated.pid), true);
+  assert.equal(await requestBody(port), 'unrelated');
+});

package/runtime/scripts/amalgm-mcp/tests/browser-routing.test.js

@@ -154,19 +154,18 @@ test('ownership routing: a session home is decided at first use and sticks', ()
   });
 });
 
-test('entrypoint routing: candidate order is state dir, derived label dir, AMALGM_DIR, home', () => {
+test('entrypoint routing: candidate order is state dir, derived label dir, AMALGM_DIR — no legacy home fallback', () => {
   withEnv({
     AMALGM_RUNTIME_STATE_DIR: '/tmp/a-state',
     AMALGM_DIR: '/tmp/a-dir',
     AMALGM_RUNTIME_LABEL: 'main',
   }, () => {
     const candidates = engine.bridgeFileCandidates();
-    assert.deepEqual(candidates.slice(0, 3), [
+    assert.deepEqual(candidates, [
       '/tmp/a-state/electron-browser-bridge.json',
       '/tmp/a-dir/runtimes/main/electron-browser-bridge.json',
       '/tmp/a-dir/electron-browser-bridge.json',
     ]);
-    assert.equal(candidates[3], path.join(os.homedir(), '.amalgm', 'electron-browser-bridge.json'));
   });
 });
 

package/runtime/scripts/amalgm-mcp/tests/config-migration.test.js

@@ -6,7 +6,9 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const ORIGINAL_ENV = { ...process.env };
+const ORIGINAL_ENV = Object.fromEntries(
+  Object.entries(process.env).filter(([key]) => !key.startsWith('AMALGM_')),
+);
 const SCRIPT_DIR = path.resolve(__dirname, '..');
 const TEST_TMP_DIR = path.join(__dirname, '.tmp');
 
@@ -83,6 +85,40 @@ test('runtime config backfills legacy cli homes after the runtime marker already
     const marker = readJson(markerPath);
     assert.ok(marker.copied.includes('cli-homes/'));
     assert.ok(marker.completed_migrations.includes('cli-homes-merge-v1'));
+    assert.ok(marker.completed_migrations.includes('workspaces-merge-v1'));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('runtime config resolves missing AMALGM_DIR to the manifest user folder', () => {
+  fs.mkdirSync(TEST_TMP_DIR, { recursive: true });
+  const root = fs.mkdtempSync(path.join(TEST_TMP_DIR, 'amalgm-runtime-paths-'));
+  try {
+    resetEnv();
+    const home = path.join(root, '.amalgm');
+    const userDir = path.join(home, 'users', 'aayush@example.com');
+    fs.mkdirSync(userDir, { recursive: true });
+    fs.writeFileSync(path.join(home, '.amalgm-root.json'), `${JSON.stringify({
+      schemaVersion: 1,
+      installationId: 'test-install',
+      users: {},
+    })}\n`);
+    fs.writeFileSync(path.join(userDir, '.amalgm-user.json'), `${JSON.stringify({
+      schemaVersion: 1,
+      userId: 'user-123',
+      canonicalEmail: 'aayush@example.com',
+    })}\n`);
+    process.env.HOME = root;
+    process.env.AMALGM_HOME = home;
+    process.env.AMALGM_RUNTIME_LABEL = 'main';
+    process.env.AMALGM_RUNTIME_USER_ID = 'user-123';
+    clearScriptModules();
+
+    const config = require('../config');
+
+    assert.equal(config.AMALGM_DIR, userDir);
+    assert.equal(config.LOCAL_DB_FILE, path.join(userDir, 'amalgm.db'));
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }

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

@@ -27,8 +27,10 @@ const {
   envForBuild,
   manualDesktopNotarizationEnabled,
   notarytoolCredentialArgs,
+  notarytoolSubmitTransportArgs,
   parseEnvFile,
   parseUploadOffsetMismatch,
+  prepareNotarySubmissionFile,
   publishDesktopRelease,
   recreateZipFromAppBundle,
   recoverableUploadOffset,
@@ -230,6 +232,33 @@ test('desktop release runner preserves explicit bundled desktop builds', () => {
   );
 
   assert.equal(env.AMALGM_DESKTOP_THIN, '0');
+  assert.equal(env.AMALGM_DESKTOP_RENDERER_DELIVERY, 'bundled-next');
+  assert.equal(env.AMALGM_DESKTOP_RUNTIME_DELIVERY, 'bundled-with-npm-handoff');
+  assert.equal(env.NEXT_IMAGE_UNOPTIMIZED, '1');
+  assert.equal(env.NEXT_PUBLIC_SUPABASE_URL, '');
+  assert.equal(env.NEXT_PUBLIC_SUPABASE_ANON_KEY, '');
+});
+
+test('desktop release runner supports bundled UI with npm runtime', () => {
+  const env = envForBuild(
+    {
+      GH_TOKEN: 'token',
+      AMALGM_DESKTOP_RENDERER_DELIVERY: 'bundled-next',
+      AMALGM_DESKTOP_RUNTIME_DELIVERY: 'npm',
+    },
+    { lane: 'preview', delivery: 'delivery-id' },
+    '0.1.124-canary.1',
+    '0.1.124000001-preview.1',
+    { engineRef: 'engine', uiRef: 'ui' },
+    { engineSha: 'engine-sha', uiSha: 'ui-sha' },
+    'https://preview.amalgm.ai',
+  );
+
+  assert.equal(env.AMALGM_DESKTOP_RENDERER_DELIVERY, 'bundled-next');
+  assert.equal(env.AMALGM_DESKTOP_RUNTIME_DELIVERY, 'npm');
+  assert.equal(env.NEXT_IMAGE_UNOPTIMIZED, '1');
+  assert.equal(env.NEXT_PUBLIC_SUPABASE_URL, '');
+  assert.equal(env.NEXT_PUBLIC_SUPABASE_ANON_KEY, '');
 });
 
 test('desktop release runner omits blank certificate file secrets', () => {
@@ -297,6 +326,9 @@ test('desktop release runner resolves manual notarization credentials and CLI id
       credentialType: 'apple-id',
     });
 
+    assert.deepEqual(notarytoolSubmitTransportArgs({}), ['--no-s3-acceleration']);
+    assert.deepEqual(notarytoolSubmitTransportArgs({ AMALGM_DESKTOP_NOTARY_S3_ACCELERATION: '1' }), []);
+
     assert.equal(
       codesignIdentityForCli({ CSC_NAME: 'amalgm, Inc. (C5S6UATV3L)' }),
       'Developer ID Application: amalgm, Inc. (C5S6UATV3L)',
@@ -322,6 +354,25 @@ test('desktop release runner resolves manual notarization credentials and CLI id
   }
 });
 
+test('desktop release runner submits notarization from a short temporary path', () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm desktop notary source '));
+  const sourcePath = path.join(tempRoot, 'amalgm local ui.dmg');
+  fs.writeFileSync(sourcePath, 'signed-dmg');
+
+  const prepared = prepareNotarySubmissionFile(sourcePath);
+  try {
+    assert.equal(path.extname(prepared.filePath), '.dmg');
+    assert.equal(path.basename(prepared.filePath).includes(' '), false);
+    assert.equal(prepared.filePath.startsWith(os.tmpdir()), true);
+    assert.equal(fs.readFileSync(prepared.filePath, 'utf8'), 'signed-dmg');
+  } finally {
+    prepared.cleanup();
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+
+  assert.equal(fs.existsSync(prepared.filePath), false);
+});
+
 test('desktop release runner resolves app-builder binary path from checkout node_modules or override', () => {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-desktop-release-app-builder-'));
   const engineDir = path.join(tempRoot, 'engine');

package/runtime/scripts/amalgm-mcp/tests/files-resource.test.js

@@ -25,3 +25,28 @@ test('files resource omits dot-prefixed filesystem entries', (t) => {
   );
   assert.equal(snapshot.files.some((file) => file.name.startsWith('.')), false);
 });
+
+test('expandHome: ~amalgm token resolves to the user data dir; legacy hidden uploads redirect', () => {
+  const { expandHome } = require('../fs/rest')._private;
+  const { AMALGM_DIR } = require('../config');
+
+  assert.equal(expandHome('~amalgm'), AMALGM_DIR);
+  assert.equal(expandHome('~amalgm/uploads/s1/a.png'), path.join(AMALGM_DIR, 'uploads', 's1', 'a.png'));
+  // Pre-2026-07 UI builds send old hidden-layout paths (uploads, notes-files,
+  // browser-sessions, ...); the whole prefix must land in the user data dir,
+  // never recreate ~/.amalgm on disk.
+  assert.equal(
+    expandHome('~/.amalgm/uploads/s1/a.png'),
+    path.join(AMALGM_DIR, 'uploads', 's1', 'a.png'),
+  );
+  assert.equal(
+    expandHome('~/.amalgm/notes-files/n.png'),
+    path.join(AMALGM_DIR, 'notes-files', 'n.png'),
+  );
+  assert.equal(
+    expandHome('~/.amalgm/browser-sessions/rec.webm'),
+    path.join(AMALGM_DIR, 'browser-sessions', 'rec.webm'),
+  );
+  // Ordinary home paths are untouched.
+  assert.equal(expandHome('~/Documents/x.txt'), path.join(os.homedir(), 'Documents', 'x.txt'));
+});

package/runtime/scripts/amalgm-mcp/tests/project-context.test.js

@@ -416,3 +416,62 @@ test('watcher reconciles direct disk edits', async () => {
   assert.notEqual(row.contextRevision, before, 'watcher updated the row');
   assert.ok(row.prompt.projectState.includes('Watched edit.'));
 });
+
+// ---------------------------------------------------------------------------
+// 2026-07-03 regression: the "amalgm repos" project row flip-flopped between a
+// managed workspace copy and the real home checkout. String inputs went
+// through canonicalProjectPath but workspace-record (object) inputs did not,
+// so every boot pass re-pinned projectPath to the raw row path.
+// ---------------------------------------------------------------------------
+
+test('workspace-record inputs canonicalize legacy managed paths to the home checkout', () => {
+  const legacyRoot = fs.mkdtempSync(path.join(tempRoot, 'legacy-ws-'));
+  const fakeHome = fs.mkdtempSync(path.join(tempRoot, 'home-'));
+  const realCheckout = path.join(fakeHome, 'my repo');
+  fs.mkdirSync(realCheckout, { recursive: true });
+  const managedCopy = path.join(legacyRoot, 'my repo');
+  fs.mkdirSync(managedCopy, { recursive: true });
+
+  const prevHome = process.env.HOME;
+  const prevLegacy = process.env.AMALGM_LEGACY_WORKSPACES_DIR;
+  process.env.HOME = fakeHome;
+  process.env.AMALGM_LEGACY_WORKSPACES_DIR = legacyRoot;
+  try {
+    const workspace = upsertWorkspace(
+      { path: managedCopy, name: 'my repo', source: 'managed', managed: true },
+      { source: 'test' },
+    );
+    const record = store.reconcileProjectContext(
+      { id: workspace.id, path: managedCopy, name: 'my repo' },
+      { source: 'test', force: true },
+    );
+    assert.equal(record.projectPath, path.resolve(realCheckout));
+  } finally {
+    process.env.HOME = prevHome;
+    if (prevLegacy === undefined) delete process.env.AMALGM_LEGACY_WORKSPACES_DIR;
+    else process.env.AMALGM_LEGACY_WORKSPACES_DIR = prevLegacy;
+  }
+});
+
+test('resolveProject picks the deepest containing workspace for nested checkouts', () => {
+  const { projectPath: rootPath, workspace: rootWorkspace } = makeProject('nest-root');
+  const childPath = path.join(rootPath, 'child-repo');
+  fs.mkdirSync(childPath, { recursive: true });
+  const childWorkspace = upsertWorkspace(
+    { path: childPath, name: 'child-repo', source: 'computer' },
+    { source: 'test' },
+  );
+
+  assert.equal(store.resolveProject(path.join(childPath, 'src', 'x.ts')).id, childWorkspace.id);
+  assert.equal(store.resolveProject(rootPath).id, rootWorkspace.id);
+});
+
+test('memory writes outside any workspace fail with an actionable error', () => {
+  const orphan = fs.mkdtempSync(path.join(tempRoot, 'orphan-'));
+  assert.throws(
+    () => store.appendChangeLog(orphan, '- test entry'),
+    (error) =>
+      /No registered Amalgm project contains/.test(error.message)
+      && /Registered project roots/.test(error.message),
+  );
+});

package/runtime/scripts/amalgm-mcp/toolbox/runner.js

@@ -57,7 +57,12 @@ function collectOutput(child, resolve, reject, timeoutMs) {
 
 function safeEnv(extraEnv) {
   const env = {};
-  for (const key of ['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LC_ALL', 'TERM', 'TMPDIR']) {
+  for (const key of [
+    'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LC_ALL', 'TERM', 'TMPDIR',
+    // Platform location contract: CLI tools resolve amalgm-owned state (apps.json,
+    // toolbox, workspaces) through these instead of guessing from HOME.
+    'AMALGM_DIR', 'AMALGM_HOME', 'AMALGM_WORKSPACES_DIR',
+  ]) {
     if (process.env[key]) env[key] = process.env[key];
   }
   if (extraEnv && typeof extraEnv === 'object' && !Array.isArray(extraEnv)) {

package/runtime/scripts/chat-core/contract.js

@@ -482,8 +482,8 @@ function createContract(payload, options = {}) {
     sessionId,
     localBaseUrl,
     proxyToken: options.proxyToken || PROXY_TOKEN,
-    proxyBaseUrl: options.proxyBaseUrl || PROXY_BASE_URL || 'https://amalgm-api-proxy-v2.fly.dev',
-    amalgmDir: options.amalgmDir || AMALGM_DIR || path.join(process.env.HOME || '.', '.amalgm'),
+    proxyBaseUrl: options.proxyBaseUrl || PROXY_BASE_URL || DEFAULT_PROXY_BASE_URL,
+    amalgmDir: options.amalgmDir || AMALGM_DIR,
     userId,
     credentialId: payload.credentialId || payload.byokCredentialId || null,
     modelId,

package/runtime/scripts/chat-core/credentials/store.js

@@ -4,6 +4,7 @@ const crypto = require('crypto');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { amalgmDir: resolveAmalgmDir } = require('../../lib/runtime-paths');
 
 const STORE_VERSION = 1;
 const CIPHER = 'aes-256-gcm';
@@ -18,7 +19,7 @@ const DEFAULT_BASE_URL_BY_PROVIDER = {
 };
 
 function credentialsPath(amalgmDir) {
-  return path.join(amalgmDir || path.join(os.homedir(), '.amalgm'), '.credentials');
+  return path.join(amalgmDir || resolveAmalgmDir(), '.credentials');
 }
 
 function machineSecret() {

package/runtime/scripts/chat-core/recorder.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { amalgmDir } = require('../lib/runtime-paths');
 
 const SENSITIVE_KEY = /(api[-_]?key|authorization|auth|bearer|cookie|password|secret|credential|access[-_]?token|refresh[-_]?token|session[-_]?token|id[-_]?token)/i;
 
@@ -12,7 +13,7 @@ function recordEnabled() {
 
 function recordPath() {
   if (process.env.CHAT_CORE_RECORD_PATH) return process.env.CHAT_CORE_RECORD_PATH;
-  const root = process.env.AMALGM_DIR || path.join(os.homedir(), '.amalgm');
+  const root = amalgmDir();
   const session = process.env.CHAT_CORE_RECORD_SESSION || new Date().toISOString().slice(0, 10);
   return path.join(root, 'chat-core-recordings', `${session}.ndjson`);
 }

package/runtime/scripts/chat-core/tooling/native-binaries.js

@@ -4,9 +4,10 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { amalgmDir: resolveAmalgmDir } = require('../../lib/runtime-paths');
 
 function amalgmDir() {
-  return process.env.AMALGM_DIR || path.join(os.homedir(), '.amalgm');
+  return resolveAmalgmDir();
 }
 
 function nativeNodeModulesDirs() {

package/runtime/scripts/chat-server/config.js

@@ -7,20 +7,20 @@
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
 const {
   DEFAULT_PROXY_BASE_URL,
   ensureFreshProxyToken,
   proxyBaseUrl,
   readProxyToken,
 } = require('../proxy-token-store');
+const { amalgmDir } = require('../lib/runtime-paths');
 const { runtimePort } = require('../../lib/runtime-manifest');
 
 // ── Paths ──────────────────────────────────────────────────────────────────
 // Set by the orchestrator (entrypoint.sh or electron/main.ts).
 // The code never decides these — it just reads them.
 
-const AMALGM_DIR = process.env.AMALGM_DIR || path.join(os.homedir(), '.amalgm');
+const AMALGM_DIR = amalgmDir();
 const DEFAULT_CWD = process.env.AMALGM_DEFAULT_CWD || '/workspace';
 
 // ── Server ──────────────────────────────────────────────────────────────────

package/runtime/scripts/credential-adapter.js

@@ -10,8 +10,8 @@
  */
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
+const { amalgmDir } = require('./lib/runtime-paths');
 
 const VALID_HARNESS_IDS = ['claude_code', 'codex', 'opencode', 'pi'];
 const VALID_AUTH_MODES = ['amalgm', 'provider_auth', 'byok'];
@@ -22,7 +22,7 @@ const SUPPORTED_AUTH_BY_HARNESS = {
   pi: ['amalgm', 'byok', 'provider_auth'],
 };
 
-const AMALGM_DIR = process.env.AMALGM_DIR || path.join(os.homedir(), '.amalgm');
+const AMALGM_DIR = amalgmDir();
 const AUTH_MODES_FILE = path.join(AMALGM_DIR, 'auth-modes.json');
 const AUTH_MODE_LEGACY_FILE = path.join(AMALGM_DIR, 'auth-mode');
 

package/runtime/scripts/lib/runtime-paths.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const os = require('os');
+const fs = require('fs');
 const path = require('path');
 
 function normalizeRuntimeLabel(value) {
@@ -10,8 +11,67 @@ function normalizeRuntimeLabel(value) {
   return 'main';
 }
 
+function sanitizeScopeSegment(value, fallback = 'local') {
+  const clean = String(value || '')
+    .trim()
+    .replace(/[^A-Za-z0-9_.@-]/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return clean || fallback;
+}
+
+function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function userIdFromRecord(record) {
+  return typeof record?.user_id === 'string' && record.user_id.trim()
+    ? record.user_id.trim()
+    : '';
+}
+
+function discoverUserScope(homeDir, label) {
+  const explicit = process.env.AMALGM_RUNTIME_USER_ID
+    || process.env.AMALGM_USER_SCOPE
+    || process.env.AMALGM_USER_ID;
+  if (explicit) return sanitizeScopeSegment(explicit);
+
+  const rootUser = userIdFromRecord(readJson(path.join(homeDir, 'computer.json'), null))
+    || userIdFromRecord(readJson(path.join(homeDir, 'auth.json'), null));
+  if (rootUser) return sanitizeScopeSegment(rootUser);
+
+  const layout = require('../amalgm-mcp/lib/layout');
+  for (const entry of layout.listUserEntries(homeDir)) {
+    if (entry.manifest?.userId) return sanitizeScopeSegment(entry.manifest.userId);
+    if (entry.userId) return sanitizeScopeSegment(entry.userId);
+  }
+
+  const usersDir = path.join(homeDir, 'users');
+  try {
+    for (const entry of fs.readdirSync(usersDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const userDir = path.join(usersDir, entry.name);
+      const scopedUser = userIdFromRecord(readJson(path.join(userDir, 'computer.json'), null))
+        || userIdFromRecord(readJson(path.join(userDir, 'auth.json'), null))
+        || userIdFromRecord(readJson(path.join(userDir, label, 'computer.json'), null))
+        || userIdFromRecord(readJson(path.join(userDir, label, 'auth.json'), null));
+      if (scopedUser) return sanitizeScopeSegment(scopedUser);
+    }
+  } catch {
+    // No users yet.
+  }
+
+  return 'local';
+}
+
 function amalgmDir() {
-  return process.env.AMALGM_DIR || require('../amalgm-mcp/lib/layout').resolveAmalgmHome(process.env);
+  if (process.env.AMALGM_DIR) return process.env.AMALGM_DIR;
+  const layout = require('../amalgm-mcp/lib/layout');
+  const home = layout.resolveAmalgmHome(process.env);
+  return layout.resolveUserDir(home, discoverUserScope(home, runtimeLabel()));
 }
 
 function runtimeLabel() {

package/runtime/scripts/local-gateway.js

@@ -24,6 +24,7 @@ const {
 } = require('./runtime-auth');
 const { runtimePort } = require('../lib/runtime-manifest');
 const {
+  amalgmDir,
   runtimeLogDir,
   runtimeStateDir,
   runtimeStateFile,
@@ -49,7 +50,7 @@ function loadPty() {
 
 const pty = loadPty();
 
-const AMALGM_DIR = process.env.AMALGM_DIR || path.join(os.homedir(), '.amalgm');
+const AMALGM_DIR = amalgmDir();
 const STATE_FILE = runtimeStateFile();
 const RUNTIME_COMPUTER_FILE = path.join(runtimeStateDir(), 'computer.json');
 const APPS_FILE = path.join(AMALGM_DIR, 'apps.json');