amalgm 0.1.125 → 0.1.126

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.125",
+  "version": "0.1.126",
   "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/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/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/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/agent-bundles/bundles.js

@@ -291,6 +291,35 @@ function externalMcpToolIdsForLoadout(toolIds, tools) {
     .map((tool) => tool.id);
 }
 
+function agentEntryId(entry) {
+  if (!isObject(entry)) return '';
+  const sourceAgentId = typeof entry.sourceAgentId === 'string' ? entry.sourceAgentId.trim() : '';
+  if (sourceAgentId) return sourceAgentId;
+  return typeof entry.agent?.sourceAgentId === 'string' ? entry.agent.sourceAgentId.trim() : '';
+}
+
+function referencedSubagentIds(entry) {
+  if (!isObject(entry)) return [];
+  const subagents = Array.isArray(entry.config?.subagents) ? entry.config.subagents : [];
+  return subagents
+    .map((subagent) => (typeof subagent?.agentId === 'string' ? subagent.agentId.trim() : ''))
+    .filter(Boolean);
+}
+
+function assertClosedAgentBundleGraph(bundle) {
+  const agentIds = new Set(bundle.agents.map(agentEntryId).filter(Boolean));
+  const missing = new Set();
+  for (const entry of bundle.agents) {
+    for (const agentId of referencedSubagentIds(entry)) {
+      if (!agentIds.has(agentId)) missing.add(agentId);
+    }
+  }
+
+  if (missing.size > 0) {
+    throw new Error(`Bundle is missing shared subagents: ${Array.from(missing).join(', ')}`);
+  }
+}
+
 function validateBundle(bundle) {
   if (!isObject(bundle)) throw new Error('bundle must be an object');
   if (bundle.kind !== BUNDLE_KIND) throw new Error(`Unsupported bundle kind: ${bundle.kind || 'unknown'}`);
@@ -300,6 +329,7 @@ function validateBundle(bundle) {
   if (!Array.isArray(bundle.agents) || bundle.agents.length === 0) {
     throw new Error('bundle must include at least one agent');
   }
+  assertClosedAgentBundleGraph(bundle);
   return bundle;
 }
 

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

@@ -4,8 +4,10 @@ const path = require('path');
 
 const DESKTOP_RELEASE_AUTOMATION_ID = 'internal-amalgm-desktop-release';
 const DESKTOP_RELEASE_TRIGGER_ID = 'internal-amalgm-desktop-release-github-push';
+const PR_CHECK_TRIGGER_ID = 'internal-amalgm-pr-check-github-pull-request';
 const DESKTOP_RELEASE_WORKFLOW_ID = 'internal-amalgm-desktop-release-workflow';
 const NPM_RELEASE_WORKFLOW_ID = 'internal-amalgm-npm-release-workflow';
+const PR_CHECK_WORKFLOW_ID = 'internal-amalgm-pr-check-workflow';
 
 function desktopReleaseRunnerPath() {
   return path.resolve(__dirname, '../events/desktop-release-runner.js');
@@ -15,6 +17,10 @@ function npmReleaseRunnerPath() {
   return path.resolve(__dirname, '../events/npm-release-runner.js');
 }
 
+function prCheckRunnerPath() {
+  return path.resolve(__dirname, '../events/pr-check-runner.js');
+}
+
 function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
@@ -339,11 +345,108 @@ function npmReleaseWorkflow(runnerPath = npmReleaseRunnerPath()) {
 })`;
 }
 
+function prCheckWorkflow(runnerPath = prCheckRunnerPath()) {
+  const escapedRunnerCommand = JSON.stringify(`node ${shellQuote(runnerPath)}`);
+  const escapedRunnerDir = JSON.stringify(path.dirname(runnerPath));
+  return `export default workflow({
+  trigger: event("github.pull_request"),
+
+  allowlist: {
+    localCompute: true,
+    secrets: [
+      "GH_TOKEN",
+      "GITHUB_TOKEN",
+      "AMALGM_PR_CHECK_CHECKOUT_ROOT",
+      "AMALGM_PR_CHECK_ENV_FILE",
+      "AMALGM_PR_CHECK_NODE_BIN",
+      "AMALGM_PR_CHECK_PATH_PREFIX",
+      "AMALGM_PR_CHECK_PYTHON",
+      "AMALGM_PR_CHECK_NPM_CACHE",
+      "AMALGM_PR_CHECK_ENGINE_COMMAND",
+      "AMALGM_PR_CHECK_UI_COMMAND",
+      "AMALGM_PR_CHECK_STATUS_CONTEXT",
+      "AMALGM_ENGINE_REPO_URL",
+      "AMALGM_UI_REPO_URL"
+    ]
+  },
+
+  limits: {
+    maxConcurrentRuns: 2,
+    queueLimit: 20,
+    cellTimeoutMs: 1800000,
+    codeTimeoutMs: 15000
+  },
+
+  cells: [
+    code("filter_pull_request", async ({ payload, headers, stop }) => {
+      const repository = String(payload?.repository?.full_name || "").trim()
+      const action = String(payload?.action || "").trim()
+      const pull = payload?.pull_request || {}
+      const baseBranch = String(pull?.base?.ref || "").trim()
+      const headSha = String(pull?.head?.sha || "").trim()
+      const headRef = String(pull?.head?.ref || "").trim()
+      const headRepository = String(pull?.head?.repo?.full_name || "").trim()
+      const number = Number(payload?.number || pull?.number || 0)
+      const allowedRepositories = ["amalgm-inc/amalgm-engine", "amalgm-inc/amalgm-ui"]
+      const allowedActions = ["opened", "synchronize", "reopened", "ready_for_review"]
+
+      if (!allowedRepositories.includes(repository)) stop()
+      if (!allowedActions.includes(action)) stop()
+      if (!["main", "preview"].includes(baseBranch)) stop()
+      if (!Number.isSafeInteger(number) || number <= 0) stop()
+      if (!/^[a-f0-9]{40}$/i.test(headSha)) stop()
+      if (pull?.draft) stop()
+      if (headRepository && headRepository !== repository) stop()
+
+      return {
+        repository,
+        action,
+        number,
+        baseBranch,
+        headRef,
+        headRepository,
+        headSha,
+        delivery: String(headers?.["x-github-delivery"] || "")
+      }
+    }),
+
+    cli("run_pr_check", {
+      cwd: ${escapedRunnerDir},
+      command: ${escapedRunnerCommand},
+      env: ({ cells, secrets }) => ({
+        GH_TOKEN: secrets.GH_TOKEN || secrets.GITHUB_TOKEN || "",
+        GITHUB_TOKEN: secrets.GITHUB_TOKEN || secrets.GH_TOKEN || "",
+        AMALGM_PR_CHECK_CHECKOUT_ROOT: secrets.AMALGM_PR_CHECK_CHECKOUT_ROOT || "",
+        AMALGM_PR_CHECK_ENV_FILE: secrets.AMALGM_PR_CHECK_ENV_FILE || "",
+        AMALGM_PR_CHECK_NODE_BIN: secrets.AMALGM_PR_CHECK_NODE_BIN || "",
+        AMALGM_PR_CHECK_PATH_PREFIX: secrets.AMALGM_PR_CHECK_PATH_PREFIX || "",
+        AMALGM_PR_CHECK_PYTHON: secrets.AMALGM_PR_CHECK_PYTHON || "",
+        AMALGM_PR_CHECK_NPM_CACHE: secrets.AMALGM_PR_CHECK_NPM_CACHE || "",
+        AMALGM_PR_CHECK_ENGINE_COMMAND: secrets.AMALGM_PR_CHECK_ENGINE_COMMAND || "",
+        AMALGM_PR_CHECK_UI_COMMAND: secrets.AMALGM_PR_CHECK_UI_COMMAND || "",
+        AMALGM_PR_CHECK_STATUS_CONTEXT: secrets.AMALGM_PR_CHECK_STATUS_CONTEXT || "",
+        AMALGM_ENGINE_REPO_URL: secrets.AMALGM_ENGINE_REPO_URL || "",
+        AMALGM_UI_REPO_URL: secrets.AMALGM_UI_REPO_URL || "",
+        AMALGM_PR_CHECK_SOURCE_REPO: cells.filter_pull_request.output.repository,
+        AMALGM_PR_CHECK_ACTION: cells.filter_pull_request.output.action,
+        AMALGM_PR_CHECK_NUMBER: String(cells.filter_pull_request.output.number),
+        AMALGM_PR_CHECK_BASE_BRANCH: cells.filter_pull_request.output.baseBranch,
+        AMALGM_PR_CHECK_HEAD_REF: cells.filter_pull_request.output.headRef,
+        AMALGM_PR_CHECK_HEAD_REPO: cells.filter_pull_request.output.headRepository,
+        AMALGM_PR_CHECK_HEAD_SHA: cells.filter_pull_request.output.headSha,
+        AMALGM_PR_CHECK_DELIVERY: cells.filter_pull_request.output.delivery
+      }),
+      timeoutMs: 1800000
+    })
+  ]
+})`;
+}
+
 function desktopReleaseAutomationSeed() {
   return {
     id: DESKTOP_RELEASE_AUTOMATION_ID,
     name: 'Run Amalgm release automation',
-    description: 'Internal workflow: publish npm runtime packages and signed macOS desktop releases from GitHub push webhooks.',
+    description: 'Internal workflow: run PR checks and publish npm/runtime releases from GitHub webhooks.',
     enabled: true,
     internal: true,
     triggers: [{
@@ -355,6 +458,15 @@ function desktopReleaseAutomationSeed() {
       event: 'push',
       sourceUrl: 'https://github.com/amalgm-inc',
       enabled: true,
+    }, {
+      id: PR_CHECK_TRIGGER_ID,
+      kind: 'event',
+      name: 'GitHub pull request',
+      description: 'GitHub pull_request webhook for amalgm-engine and amalgm-ui PR checks.',
+      source: 'github',
+      event: 'pull_request',
+      sourceUrl: 'https://github.com/amalgm-inc',
+      enabled: true,
     }],
     workflows: [{
       id: DESKTOP_RELEASE_WORKFLOW_ID,
@@ -457,6 +569,37 @@ function desktopReleaseAutomationSeed() {
         cellTimeoutMs: 1800000,
         codeTimeoutMs: 15000,
       },
+    }, {
+      id: PR_CHECK_WORKFLOW_ID,
+      name: 'Run PR checks',
+      description: 'Runs deterministic pre-merge checks for pull requests into main and preview.',
+      enabled: true,
+      internal: true,
+      workflowText: prCheckWorkflow(),
+      allowlist: {
+        localCompute: true,
+        secrets: [
+          'GH_TOKEN',
+          'GITHUB_TOKEN',
+          'AMALGM_PR_CHECK_CHECKOUT_ROOT',
+          'AMALGM_PR_CHECK_ENV_FILE',
+          'AMALGM_PR_CHECK_NODE_BIN',
+          'AMALGM_PR_CHECK_PATH_PREFIX',
+          'AMALGM_PR_CHECK_PYTHON',
+          'AMALGM_PR_CHECK_NPM_CACHE',
+          'AMALGM_PR_CHECK_ENGINE_COMMAND',
+          'AMALGM_PR_CHECK_UI_COMMAND',
+          'AMALGM_PR_CHECK_STATUS_CONTEXT',
+          'AMALGM_ENGINE_REPO_URL',
+          'AMALGM_UI_REPO_URL',
+        ],
+      },
+      limits: {
+        maxConcurrentRuns: 2,
+        queueLimit: 20,
+        cellTimeoutMs: 1800000,
+        codeTimeoutMs: 15000,
+      },
     }],
   };
 }
@@ -471,12 +614,16 @@ function internalAutomationSeeds() {
 module.exports = {
   DESKTOP_RELEASE_AUTOMATION_ID,
   DESKTOP_RELEASE_TRIGGER_ID,
+  PR_CHECK_TRIGGER_ID,
   DESKTOP_RELEASE_WORKFLOW_ID,
   NPM_RELEASE_WORKFLOW_ID,
+  PR_CHECK_WORKFLOW_ID,
   desktopReleaseAutomationSeed,
   desktopReleaseRunnerPath,
   desktopReleaseWorkflow,
   internalAutomationSeeds,
   npmReleaseRunnerPath,
   npmReleaseWorkflow,
+  prCheckRunnerPath,
+  prCheckWorkflow,
 };

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

@@ -0,0 +1,344 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+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 DEFAULT_STATUS_CONTEXT = 'amalgm/pr-check';
+
+function cleanString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function parseEnvFile(text) {
+  const env = {};
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(trimmed);
+    if (!match) continue;
+    let value = match[2] || '';
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.endsWith(quote)) {
+      value = value.slice(1, -1);
+    }
+    env[match[1]] = value;
+  }
+  return env;
+}
+
+function applyPrCheckEnv(env = process.env) {
+  const candidates = [
+    cleanString(env.AMALGM_PR_CHECK_ENV_FILE),
+    DEFAULT_ENV_FILE,
+  ].filter(Boolean);
+
+  for (const filePath of candidates) {
+    if (!fs.existsSync(filePath)) continue;
+    const values = parseEnvFile(fs.readFileSync(filePath, 'utf8'));
+    for (const [key, value] of Object.entries(values)) {
+      if (!cleanString(env[key])) env[key] = value;
+    }
+  }
+
+  return env;
+}
+
+function prependPath(env, dir) {
+  const cleanDir = cleanString(dir);
+  if (!cleanDir) return env.PATH || '';
+  const parts = String(env.PATH || '').split(path.delimiter).filter(Boolean);
+  return [cleanDir, ...parts.filter((part) => part !== cleanDir)].join(path.delimiter);
+}
+
+function prCheckToolEnv(baseEnv = process.env) {
+  const env = { ...baseEnv };
+  applyPrCheckEnv(env);
+  const nodeBin = cleanString(env.AMALGM_PR_CHECK_NODE_BIN);
+  if (nodeBin && fs.existsSync(nodeBin)) {
+    env.PATH = prependPath(env, path.dirname(nodeBin));
+  }
+  const pathPrefix = cleanString(env.AMALGM_PR_CHECK_PATH_PREFIX);
+  if (pathPrefix) env.PATH = prependPath(env, pathPrefix);
+  env.npm_config_python = cleanString(env.AMALGM_PR_CHECK_PYTHON)
+    || cleanString(env.npm_config_python)
+    || '/usr/bin/python3';
+  env.npm_config_cache = cleanString(env.AMALGM_PR_CHECK_NPM_CACHE)
+    || cleanString(env.npm_config_cache)
+    || path.join(os.tmpdir(), 'amalgm-pr-check-npm-cache');
+  env.npm_config_prefer_online = 'true';
+  env.npm_config_audit = 'false';
+  env.npm_config_fund = 'false';
+  if (!cleanString(env.GH_TOKEN) && cleanString(env.GITHUB_TOKEN)) {
+    env.GH_TOKEN = cleanString(env.GITHUB_TOKEN);
+  }
+  if (!cleanString(env.GITHUB_TOKEN) && cleanString(env.GH_TOKEN)) {
+    env.GITHUB_TOKEN = cleanString(env.GH_TOKEN);
+  }
+  return env;
+}
+
+function parsePayloadFromEnv(env = process.env) {
+  const payloadFile = cleanString(env.AMALGM_PR_CHECK_PAYLOAD_FILE);
+  const payloadJson = payloadFile ? fs.readFileSync(payloadFile, 'utf8') : cleanString(env.AMALGM_PR_CHECK_PAYLOAD_JSON);
+  if (!payloadJson) return null;
+  return JSON.parse(payloadJson);
+}
+
+function requestFromPayload(payload = {}, env = process.env) {
+  const pull = payload.pull_request || {};
+  const base = pull.base || {};
+  const head = pull.head || {};
+  const repository = cleanString(env.AMALGM_PR_CHECK_SOURCE_REPO || payload.repository?.full_name);
+  const baseBranch = cleanString(env.AMALGM_PR_CHECK_BASE_BRANCH || base.ref);
+  const headSha = cleanString(env.AMALGM_PR_CHECK_HEAD_SHA || head.sha);
+  const headRef = cleanString(env.AMALGM_PR_CHECK_HEAD_REF || head.ref);
+  const headRepository = cleanString(env.AMALGM_PR_CHECK_HEAD_REPO || head.repo?.full_name);
+  const number = Number(env.AMALGM_PR_CHECK_NUMBER || payload.number || pull.number || 0);
+  return {
+    payload,
+    action: cleanString(env.AMALGM_PR_CHECK_ACTION || payload.action),
+    repository,
+    number,
+    baseBranch,
+    headRef,
+    headSha,
+    headRepository,
+    draft: env.AMALGM_PR_CHECK_DRAFT
+      ? ['1', 'true', 'yes', 'on'].includes(cleanString(env.AMALGM_PR_CHECK_DRAFT).toLowerCase())
+      : Boolean(pull.draft),
+    delivery: cleanString(env.AMALGM_PR_CHECK_DELIVERY),
+    dryRun: ['1', 'true', 'yes', 'on'].includes(cleanString(env.AMALGM_PR_CHECK_DRY_RUN).toLowerCase()),
+  };
+}
+
+function requestFromEnv(env = process.env) {
+  return requestFromPayload(parsePayloadFromEnv(env) || {}, env);
+}
+
+function isFullSha(value) {
+  return /^[a-f0-9]{40}$/i.test(cleanString(value));
+}
+
+function repoShortName(fullName) {
+  return cleanString(fullName).split('/').pop() || 'repo';
+}
+
+function repoUrlForRequest(request, env = process.env) {
+  if (request.repository === ENGINE_REPO_FULL_NAME) {
+    return cleanString(env.AMALGM_ENGINE_REPO_URL) || DEFAULT_ENGINE_REPO_URL;
+  }
+  if (request.repository === UI_REPO_FULL_NAME) {
+    return cleanString(env.AMALGM_UI_REPO_URL) || DEFAULT_UI_REPO_URL;
+  }
+  return '';
+}
+
+function shouldHandleRequest(request) {
+  const allowedActions = new Set(['opened', 'synchronize', 'reopened', 'ready_for_review']);
+  if (![ENGINE_REPO_FULL_NAME, UI_REPO_FULL_NAME].includes(request.repository)) {
+    return { ok: false, reason: `Ignored repository "${request.repository || '(missing)'}".` };
+  }
+  if (!allowedActions.has(request.action)) {
+    return { ok: false, reason: `Ignored pull_request action "${request.action || '(missing)'}".` };
+  }
+  if (!['main', 'preview'].includes(request.baseBranch)) {
+    return { ok: false, reason: `Ignored base branch "${request.baseBranch || '(missing)'}".` };
+  }
+  if (!Number.isSafeInteger(request.number) || request.number <= 0) {
+    return { ok: false, reason: 'Ignored pull request without a valid number.' };
+  }
+  if (!isFullSha(request.headSha)) {
+    return { ok: false, reason: 'Ignored pull request without a full head SHA.' };
+  }
+  if (request.draft) {
+    return { ok: false, reason: 'Ignored draft pull request.' };
+  }
+  if (request.headRepository && request.headRepository !== request.repository) {
+    return { ok: false, reason: `Ignored forked pull request from "${request.headRepository}".` };
+  }
+  return { ok: true };
+}
+
+function commandForRequest(request, env = process.env) {
+  if (request.repository === ENGINE_REPO_FULL_NAME) {
+    return cleanString(env.AMALGM_PR_CHECK_ENGINE_COMMAND) || 'npm ci && npm run ci:pr';
+  }
+  if (request.repository === UI_REPO_FULL_NAME) {
+    return cleanString(env.AMALGM_PR_CHECK_UI_COMMAND) || 'npm ci && npm run ci:pr';
+  }
+  throw new Error(`Unsupported PR check repository: ${request.repository}`);
+}
+
+function run(command, args, options = {}) {
+  const printable = [command, ...args].join(' ');
+  console.log(`$ ${printable}`);
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    env: options.env || process.env,
+    encoding: 'utf8',
+    maxBuffer: Number(options.maxBuffer) || 200 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const error = new Error(`${printable} failed with exit code ${result.status ?? result.signal ?? 'unknown'}`);
+    error.stdout = result.stdout || '';
+    error.stderr = result.stderr || '';
+    throw error;
+  }
+  return result.stdout || '';
+}
+
+function runShell(command, options = {}) {
+  return run('/bin/sh', ['-lc', command], options);
+}
+
+function checkoutPullRequest(request, env = process.env) {
+  const checkoutRoot = cleanString(env.AMALGM_PR_CHECK_CHECKOUT_ROOT) || DEFAULT_CHECKOUT_ROOT;
+  const checkoutDir = path.join(checkoutRoot, repoShortName(request.repository), String(request.number));
+  const repoUrl = repoUrlForRequest(request, env);
+  if (!repoUrl) throw new Error(`No clone URL configured for ${request.repository}`);
+
+  fs.rmSync(checkoutDir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(checkoutDir), { recursive: true });
+  run('git', ['clone', '--no-checkout', repoUrl, checkoutDir], { env });
+  run('git', [
+    'fetch',
+    '--no-tags',
+    'origin',
+    `+refs/pull/${request.number}/head:refs/remotes/origin/pr-${request.number}`,
+  ], { cwd: checkoutDir, env });
+  const fetchedSha = cleanString(run('git', ['rev-parse', `refs/remotes/origin/pr-${request.number}`], { cwd: checkoutDir, env }));
+  if (fetchedSha !== request.headSha) {
+    throw new Error(`Fetched PR head ${fetchedSha} did not match webhook head ${request.headSha}`);
+  }
+  run('git', ['checkout', '--detach', request.headSha], { cwd: checkoutDir, env });
+  return checkoutDir;
+}
+
+function ghToken(env = process.env) {
+  return cleanString(env.GH_TOKEN) || cleanString(env.GITHUB_TOKEN);
+}
+
+function truncateDescription(value) {
+  const text = cleanString(value).replace(/\s+/g, ' ');
+  return text.length > 140 ? `${text.slice(0, 137)}...` : text;
+}
+
+function statusPayload(request, state, description, env = process.env) {
+  const context = cleanString(env.AMALGM_PR_CHECK_STATUS_CONTEXT) || DEFAULT_STATUS_CONTEXT;
+  const targetUrl = cleanString(env.AMALGM_PR_CHECK_TARGET_URL)
+    || `https://github.com/${request.repository}/pull/${request.number}`;
+  return {
+    state,
+    context,
+    description: truncateDescription(description),
+    targetUrl,
+  };
+}
+
+function postGithubStatus(request, state, description, env = process.env) {
+  const token = ghToken(env);
+  if (!token) {
+    console.warn('Missing GH_TOKEN/GITHUB_TOKEN; skipping GitHub status update.');
+    return false;
+  }
+  const payload = statusPayload(request, state, description, env);
+  const args = [
+    'api',
+    '-X',
+    'POST',
+    `repos/${request.repository}/statuses/${request.headSha}`,
+    '-f',
+    `state=${payload.state}`,
+    '-f',
+    `context=${payload.context}`,
+    '-f',
+    `description=${payload.description}`,
+    '-f',
+    `target_url=${payload.targetUrl}`,
+  ];
+  run('gh', args, { env: { ...env, GH_TOKEN: token, GITHUB_TOKEN: token } });
+  return true;
+}
+
+function runPrCheck(request, options = {}) {
+  applyPrCheckEnv(process.env);
+  const checkEnv = prCheckToolEnv(process.env);
+  const decision = shouldHandleRequest(request);
+  if (!decision.ok) {
+    console.log(decision.reason);
+    return { ok: true, skipped: true, reason: decision.reason };
+  }
+
+  const command = commandForRequest(request, checkEnv);
+  if (request.dryRun || options.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      repository: request.repository,
+      number: request.number,
+      baseBranch: request.baseBranch,
+      headSha: request.headSha,
+      command,
+      status: statusPayload(request, 'pending', 'PR check would run.', checkEnv),
+    };
+  }
+
+  postGithubStatus(request, 'pending', 'Amalgm PR check is running.', checkEnv);
+  const checkoutDir = checkoutPullRequest(request, checkEnv);
+  try {
+    runShell(command, { cwd: checkoutDir, env: checkEnv });
+    postGithubStatus(request, 'success', 'Amalgm PR check passed.', checkEnv);
+    return {
+      ok: true,
+      skipped: false,
+      repository: request.repository,
+      number: request.number,
+      baseBranch: request.baseBranch,
+      headSha: request.headSha,
+      checkoutDir,
+      command,
+    };
+  } catch (error) {
+    const detail = cleanString(error.stderr) || cleanString(error.stdout) || error.message;
+    postGithubStatus(request, 'failure', `Amalgm PR check failed: ${detail}`, checkEnv);
+    throw error;
+  }
+}
+
+function main() {
+  const request = requestFromEnv(process.env);
+  const result = runPrCheck(request);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error.stack || error.message || error);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  ENGINE_REPO_FULL_NAME,
+  UI_REPO_FULL_NAME,
+  commandForRequest,
+  requestFromEnv,
+  requestFromPayload,
+  runPrCheck,
+  shouldHandleRequest,
+  statusPayload,
+};

package/runtime/scripts/amalgm-mcp/tests/agent-bundles.test.js

@@ -135,3 +135,33 @@ test('installing an agent bundle creates local copies and rewrites subagent refs
   assert.notEqual(installedRootConfig.subagents[0].agentId, child.id);
   assert.equal(Boolean(resolveAgent(installedRootConfig.subagents[0].agentId)), true);
 });
+
+test('installing an agent bundle rejects missing shared subagents', () => {
+  assert.throws(
+    () => installAgentBundle({
+      kind: 'amalgm.agent.bundle',
+      schemaVersion: 1,
+      rootAgentId: 'missing-child-root',
+      title: 'Missing child root',
+      agents: [{
+        sourceAgentId: 'missing-child-root',
+        agent: {
+          name: 'Missing child root',
+          baseHarnessId: 'codex',
+          baseModelId: 'openai/gpt-5.5',
+        },
+        config: {
+          instructions: 'Root',
+          loadout: { toolIds: [] },
+          subagents: [{
+            id: 'missing-child-ref',
+            agentId: 'missing-child',
+            name: 'Missing child',
+            enabled: true,
+          }],
+        },
+      }],
+    }),
+    /missing shared subagents: missing-child/,
+  );
+});

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

@@ -27,10 +27,13 @@ test('automations store seeds the internal release webhook automation', () => {
   assert.deepEqual(automation.workflows.map((workflow) => workflow.id), [
     'internal-amalgm-desktop-release-workflow',
     'internal-amalgm-npm-release-workflow',
+    'internal-amalgm-pr-check-workflow',
   ]);
   assert.equal(automation.workflows[0].status, 'active');
   assert.equal(automation.workflows[1].status, 'active');
+  assert.equal(automation.workflows[2].status, 'active');
   assert.equal(automation.workflows[1].name, 'Publish npm runtime release');
+  assert.equal(automation.workflows[2].name, 'Run PR checks');
   assert.match(automation.workflows[0].workflowText, /String\(secrets\.CSC_LINK \|\| ""\)\.trim\(\)/);
   assert.doesNotMatch(automation.workflows[0].workflowText, /CSC_LINK: secrets\.CSC_LINK \|\| ""/);
   assert.match(automation.workflows[0].workflowText, /AMALGM_DESKTOP_RELEASE_PROVIDER/);
@@ -55,4 +58,12 @@ test('automations store seeds the internal release webhook automation', () => {
   assert.equal(trigger.event, 'push');
   assert.equal(trigger.webhookUrl, 'https://desktop-release.example/events');
   assert.match(trigger.secret, /^[a-f0-9]{32}$/);
+
+  const prTrigger = listTriggers().find((item) => item.id === 'internal-amalgm-pr-check-github-pull-request');
+  assert.ok(prTrigger);
+  assert.equal(prTrigger.kind, 'event');
+  assert.equal(prTrigger.source, 'github');
+  assert.equal(prTrigger.event, 'pull_request');
+  assert.equal(prTrigger.webhookUrl, 'https://desktop-release.example/events');
+  assert.match(prTrigger.secret, /^[a-f0-9]{32}$/);
 });

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

@@ -10,10 +10,12 @@ const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-desktop-release-s
 process.env.DATA_ROOT = tempRoot;
 
 const {
+  cleanupReleaseLane,
   createServer,
   latestArtifactName,
   latestDownloadTarget,
   parseDownloadPath,
+  releaseKeyForArtifact,
 } = require(path.resolve(__dirname, '../../../../infra/desktop-release-server/server.js'));
 
 test.after(() => {
@@ -26,6 +28,29 @@ function writeReleaseMetadata(lane, artifacts) {
   fs.writeFileSync(path.join(laneDir, 'desktop-release.json'), `${JSON.stringify({ lane, artifacts }, null, 2)}\n`);
 }
 
+function writeLaneFile(lane, fileName, mtimeOffsetMs = 0) {
+  const laneDir = path.join(tempRoot, lane);
+  fs.mkdirSync(laneDir, { recursive: true });
+  const filePath = path.join(laneDir, fileName);
+  fs.writeFileSync(filePath, fileName);
+  const when = new Date(Date.now() + mtimeOffsetMs);
+  fs.utimesSync(filePath, when, when);
+  return filePath;
+}
+
+function writeReleaseFiles(lane, version, mtimeOffsetMs = 0) {
+  const prefix = lane === 'preview' ? 'amalgm-preview' : 'amalgm';
+  const zipSuffix = lane === 'preview' ? 'arm64.zip' : 'arm64-mac.zip';
+  const files = [
+    `${prefix}-${version}-${zipSuffix}`,
+    `${prefix}-${version}-${zipSuffix}.blockmap`,
+    `${prefix}-${version}-arm64.dmg`,
+    `${prefix}-${version}-arm64.dmg.blockmap`,
+  ];
+  for (const fileName of files) writeLaneFile(lane, fileName, mtimeOffsetMs);
+  return files;
+}
+
 test('desktop release server resolves stable bridge download targets from metadata', () => {
   const artifacts = [
     'amalgm-0.1.1-arm64-mac.zip',
@@ -47,6 +72,45 @@ test('desktop release server resolves stable bridge download targets from metada
   });
 });
 
+test('desktop release server groups versioned release artifacts', () => {
+  assert.equal(
+    releaseKeyForArtifact('amalgm-0.1.139881837-arm64-mac.zip.blockmap'),
+    'amalgm@0.1.139881837',
+  );
+  assert.equal(
+    releaseKeyForArtifact('amalgm-preview-0.1.139882282-preview.1-arm64.dmg'),
+    'amalgm-preview@0.1.139882282-preview.1',
+  );
+  assert.equal(releaseKeyForArtifact('latest-mac.yml'), '');
+});
+
+test('desktop release server prunes stale lane artifacts after publish', () => {
+  const oldFiles = writeReleaseFiles('main', '0.1.100', -40_000);
+  const previousFiles = writeReleaseFiles('main', '0.1.101', -30_000);
+  const newestFiles = writeReleaseFiles('main', '0.1.102', -10_000);
+  const currentFiles = writeReleaseFiles('main', '0.1.099', -50_000);
+  writeLaneFile('main', 'latest-mac.yml', -5_000);
+  writeLaneFile('main', 'notes.txt', -5_000);
+  writeReleaseMetadata('main', [...currentFiles, 'latest-mac.yml']);
+
+  const uploadDir = path.join(tempRoot, '.uploads', 'main');
+  fs.mkdirSync(uploadDir, { recursive: true });
+  fs.writeFileSync(path.join(uploadDir, 'amalgm-0.1.103-arm64-mac.zip.part'), 'partial');
+
+  const result = cleanupReleaseLane('main', { keepReleaseCount: 1 });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.uploadsDeleted, 1);
+  for (const fileName of oldFiles) assert.equal(fs.existsSync(path.join(tempRoot, 'main', fileName)), false);
+  for (const fileName of previousFiles) assert.equal(fs.existsSync(path.join(tempRoot, 'main', fileName)), false);
+  for (const fileName of newestFiles) assert.equal(fs.existsSync(path.join(tempRoot, 'main', fileName)), true);
+  for (const fileName of currentFiles) assert.equal(fs.existsSync(path.join(tempRoot, 'main', fileName)), true);
+  assert.equal(fs.existsSync(path.join(tempRoot, 'main', 'latest-mac.yml')), true);
+  assert.equal(fs.existsSync(path.join(tempRoot, 'main', 'desktop-release.json')), true);
+  assert.equal(fs.existsSync(path.join(tempRoot, 'main', 'notes.txt')), true);
+  assert.equal(fs.readdirSync(uploadDir).length, 0);
+});
+
 test('desktop release server redirects public bridge download URLs to current assets', async () => {
   writeReleaseMetadata('preview', [
     'amalgm-preview-0.1.1-preview.1-arm64.zip',

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

@@ -0,0 +1,89 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  ENGINE_REPO_FULL_NAME,
+  UI_REPO_FULL_NAME,
+  commandForRequest,
+  requestFromPayload,
+  shouldHandleRequest,
+  statusPayload,
+} = require('../events/pr-check-runner');
+
+const HEAD_SHA = '1234567890abcdef1234567890abcdef12345678';
+
+function payload(overrides = {}) {
+  const repository = overrides.repository || ENGINE_REPO_FULL_NAME;
+  return {
+    action: overrides.action || 'synchronize',
+    number: overrides.number || 42,
+    repository: { full_name: repository },
+    pull_request: {
+      number: overrides.number || 42,
+      draft: Boolean(overrides.draft),
+      base: { ref: overrides.baseBranch || 'main' },
+      head: {
+        ref: overrides.headRef || 'feature/pr-check',
+        sha: overrides.headSha || HEAD_SHA,
+        repo: { full_name: overrides.headRepository || repository },
+      },
+    },
+  };
+}
+
+test('requestFromPayload normalizes a GitHub pull request payload', () => {
+  const request = requestFromPayload(payload({ repository: UI_REPO_FULL_NAME, baseBranch: 'preview' }));
+
+  assert.equal(request.repository, UI_REPO_FULL_NAME);
+  assert.equal(request.action, 'synchronize');
+  assert.equal(request.number, 42);
+  assert.equal(request.baseBranch, 'preview');
+  assert.equal(request.headSha, HEAD_SHA);
+  assert.equal(request.headRepository, UI_REPO_FULL_NAME);
+});
+
+test('shouldHandleRequest accepts same-repo PRs into main or preview', () => {
+  const request = requestFromPayload(payload({ repository: ENGINE_REPO_FULL_NAME, baseBranch: 'main' }));
+  assert.deepEqual(shouldHandleRequest(request), { ok: true });
+});
+
+test('shouldHandleRequest rejects unsupported PR shapes', () => {
+  assert.match(
+    shouldHandleRequest(requestFromPayload(payload({ baseBranch: 'feature' }))).reason,
+    /base branch/,
+  );
+  assert.match(
+    shouldHandleRequest(requestFromPayload(payload({ draft: true }))).reason,
+    /draft/,
+  );
+  assert.match(
+    shouldHandleRequest(requestFromPayload(payload({ headRepository: 'someone/fork' }))).reason,
+    /forked/,
+  );
+  assert.match(
+    shouldHandleRequest(requestFromPayload(payload({ action: 'closed' }))).reason,
+    /action/,
+  );
+});
+
+test('commandForRequest returns the repo-specific default command', () => {
+  assert.equal(
+    commandForRequest(requestFromPayload(payload({ repository: ENGINE_REPO_FULL_NAME })), {}),
+    'npm ci && npm run ci:pr',
+  );
+  assert.equal(
+    commandForRequest(requestFromPayload(payload({ repository: UI_REPO_FULL_NAME })), {}),
+    'npm ci && npm run ci:pr',
+  );
+});
+
+test('statusPayload uses the stable Amalgm PR check context', () => {
+  const request = requestFromPayload(payload({ repository: UI_REPO_FULL_NAME }));
+  const status = statusPayload(request, 'pending', 'Running the Amalgm PR check.', {});
+
+  assert.equal(status.state, 'pending');
+  assert.equal(status.context, 'amalgm/pr-check');
+  assert.equal(status.targetUrl, 'https://github.com/amalgm-inc/amalgm-ui/pull/42');
+});