@xuda.io/ai_module 1.1.5659 → 1.1.5661

package/index.mjs

@@ -37,7 +37,7 @@ const run_process = function (command, args, input, options = {}) {
     // leaves the native process orphaned (PPID 1), still holding its OpenAI
     // socket and running forever past the deadline. We instead run the child in
     // its own process group (detached) and kill the whole group ourselves.
-    const { onStdout, onStderr, timeout, killSignal = 'SIGKILL', ...spawn_options } = options;
+    const { onStdout, onStderr, timeout, killSignal = 'SIGKILL', abort_check, abort_interval_ms, ...spawn_options } = options;
     const child = spawn(command, args, {
       stdio: ['pipe', 'pipe', 'pipe'],
       ...(timeout ? { detached: true } : {}),
@@ -66,6 +66,30 @@ const run_process = function (command, args, input, options = {}) {
         }, timeout)
       : null;
 
+    // A caller that can decide, part way through, that this process must stop. Used by the
+    // Xucode run tracker to end a run it has judged (plan 9.3 layer 6) without waiting for the
+    // timeout, which is the whole difference between minutes of stolen cycles and half an hour.
+    // It reuses kill_tree for the same reason the timeout does: signalling the direct child
+    // leaves the native binary running.
+    let aborted_reason = null;
+    const abort_timer = typeof abort_check === 'function'
+      ? setInterval(async () => {
+          try {
+            const reason = await abort_check();
+            if (!reason) return;
+            aborted_reason = String(reason);
+            stderr += `\n${aborted_reason}`;
+            kill_tree(killSignal);
+          } catch (e) {
+            // A judge that throws must never take down the process it is judging.
+          }
+        }, Number(abort_interval_ms) || 5000)
+      : null;
+    const clear_timers = () => {
+      if (timer) clearTimeout(timer);
+      if (abort_timer) clearInterval(abort_timer);
+    };
+
     child.stdout.on('data', (chunk) => {
       const text = chunk.toString();
       stdout += text;
@@ -83,12 +107,12 @@ const run_process = function (command, args, input, options = {}) {
     });
 
     child.on('error', (err) => {
-      if (timer) clearTimeout(timer);
+      clear_timers();
       reject(err);
     });
     child.on('close', (exit_code) => {
-      if (timer) clearTimeout(timer);
-      resolve({ exit_code, stdout, stderr, timed_out });
+      clear_timers();
+      resolve({ exit_code, stdout, stderr, timed_out, aborted: !!aborted_reason, abort_reason: aborted_reason });
     });
 
     if (input) {
@@ -98,26 +122,28 @@ const run_process = function (command, args, input, options = {}) {
   });
 };
 
-// UI-228 (xudex). The runtime seam: every xudex layer asks this for a WORKSPACE and never learns
-// whether it got a VM, an ephemeral runner or a local working copy. See xudex_runtime.mjs and
-// docs/plans/xudex.md section 3.8. Instantiated here rather than inside that file because
+// UI-228 (xucode). The runtime seam: every xucode layer asks this for a WORKSPACE and never learns
+// whether it got a VM, an ephemeral runner or a local working copy. See xucode_runtime.mjs and
+// docs/plans/xucode.md section 3.8. Instantiated here rather than inside that file because
 // run_process above is the only spawn wrapper whose detached process-group kill actually stops a
 // Codex run, and a second copy of that fix is the last thing this codebase needs.
-const { create_runtime: _create_xudex_runtime } = await import('./xudex_runtime.mjs');
-const { create_mirror: _create_xudex_mirror } = await import('./xudex_mirror.mjs');
+const { create_runtime: _create_xucode_runtime } = await import('./xucode_runtime.mjs');
+const { create_mirror: _create_xucode_mirror } = await import('./xucode_mirror.mjs');
 // The run tracker watches a workspace through the same handle everything else uses, so it
-// works identically on a VM, an ephemeral runner or a container. See xudex_tracker.mjs.
-const { create_run_tracker: create_xudex_run_tracker } = await import('./xudex_tracker.mjs');
+// works identically on a VM, an ephemeral runner or a container. See xucode_tracker.mjs.
+const { create_run_tracker: create_xucode_run_tracker } = await import('./xucode_tracker.mjs');
 // The engine registry: codex and Claude Code behind one launch/parse contract, so nothing above
-// this line branches on which CLI is running. See xudex_engines.mjs.
-const xudex_engines = await import('./xudex_engines.mjs');
-// The verify loop: what makes a xudex run different from a terminal that says "done" and
-// leaves your build broken. See xudex_verify.mjs.
-const xudex_verify = await import('./xudex_verify.mjs');
-// The last gate of that loop: is the app still actually running. See xudex_preview.mjs.
-const { create_preview: _create_xudex_preview } = await import('./xudex_preview.mjs');
-const xudex_preview = _create_xudex_preview({});
-const xudex_runtime = _create_xudex_runtime({ run_process });
+// this line branches on which CLI is running. See xucode_engines.mjs.
+const xucode_engines = await import('./xucode_engines.mjs');
+// The verify loop: what makes a xucode run different from a terminal that says "done" and
+// leaves your build broken. See xucode_verify.mjs.
+const xucode_verify = await import('./xucode_verify.mjs');
+// Where the provider credential lives. The machine gets a run token; this box keeps the key.
+const xucode_proxy = await import('./xucode_proxy.mjs');
+// The last gate of that loop: is the app still actually running. See xucode_preview.mjs.
+const { create_preview: _create_xucode_preview, preview_host: xucode_preview_host } = await import('./xucode_preview.mjs');
+const xucode_preview = _create_xucode_preview({});
+const xucode_runtime = _create_xucode_runtime({ run_process });
 
 // UI-220. Same spawn, opposite lifetime: start the process, hand back its pid and walk away, with
 // stdout and stderr going straight to a file that never passes through this process. A code run
@@ -531,10 +557,10 @@ const bot_ms = await import(`${module_path}/bot_protection_module/index_ms.mjs`)
 // Owns whether the AI answers, and with what, on every channel. This module used to decide
 // it from flat fields on the profile doc; see auto_response() below.
 const auto_response_ms = await import(`${module_path}/auto_response_module/index_ms.mjs`);
-// UI-228: the `xudex_run` identity gate. Declared at level 2 in verify_policy and currently
+// UI-228: the `xucode_run` identity gate. Declared at level 2 in verify_policy and currently
 // SHADOWED, so this reports and never denies until the platform enforcement floor moves.
 const verify_ms = await import(`${module_path}/verify_module/index_ms.mjs`);
-// UI-228: `xudex_touch`, which is what the idle clock that suspends a machine measures from.
+// UI-228: `xucode_touch`, which is what the idle clock that suspends a machine measures from.
 // The ASYNC wrapper deliberately: nothing about a run should wait on a timestamp being written.
 const deploy_msa = await import(`${module_path}/deploy_module/index_msa.mjs`);
 // The SYNC twin: the VM substrate has to know which machine it got and what Proxmox answered,
@@ -543,7 +569,7 @@ const deploy_ms = await import(`${module_path}/deploy_module/index_ms.mjs`);
 // The entitlement rules themselves, imported as plain logic rather than called over the broker.
 // They are a pure function of the account document, so a queue round trip would buy nothing and
 // cost a hop on the path of every single run.
-const xudex_deploy_rules = await import(`${module_path}/deploy_module/xudex.mjs`);
+const xucode_deploy_rules = await import(`${module_path}/deploy_module/xucode.mjs`);
 
 const ws_dashboard_msa = await import(`${module_path}/ws_dashboard_module/index_msa.mjs`);
 // Sync twin of the above: the chat-finished alert has to ASK whether the user is
@@ -3447,7 +3473,7 @@ export const get_code_run = async function (req) {
         repo_id: run.repo_id || null,
         branch: run.branch || null,
         base_sha: run.base_sha || null,
-        // UI-228: what the verification found. Present only on a xudex run, and the reason the
+        // UI-228: what the verification found. Present only on a xucode run, and the reason the
         // panel can say "test failed" with the output instead of leaving the customer to guess
         // why the answer sounded confident and the build is red.
         verify: run.verify || null,
@@ -3686,7 +3712,7 @@ export const git_repo_list = async function (req) {
 };
 
 // ── UI-228: BYOK provider keys ─────────────────────────────────────────────────────────────
-// docs/plans/xudex.md 5.2. Claude Code and every engine after it run on the CUSTOMER'S key, not
+// docs/plans/xucode.md 5.2. Claude Code and every engine after it run on the CUSTOMER'S key, not
 // ours. That removes model cost from our books entirely and turns efficiency work into their
 // saving rather than our margin, which is a better product and an honest one.
 //
@@ -3694,40 +3720,40 @@ export const git_repo_list = async function (req) {
 // doc in the ACCOUNT'S project database, never on the app doc in xuda_master, because control DBs
 // replicate bidirectionally fleet-wide through the master hub and a secret there would be copied
 // to every region. No read path returns more than the last four characters.
-const XUDEX_KEY_PROVIDERS = ['anthropic', 'openai'];
+const XUCODE_KEY_PROVIDERS = ['anthropic', 'openai'];
 
 // What a key looks like, checked only enough to catch a paste that obviously is not one. This is
 // deliberately not strict: providers change their prefixes, and refusing a valid key is worse than
 // accepting an invalid one that fails clearly on first use.
-const xudex_key_shape_error = function (provider, api_key) {
+const xucode_key_shape_error = function (provider, api_key) {
   const key = String(api_key || '').trim();
   if (key.length < 20) return 'That does not look like an API key. Paste the whole key.';
   if (provider === 'anthropic' && !key.startsWith('sk-ant-')) {
     // The single most common wrong thing to paste, so it is worth naming: a Claude Pro or Max
     // SUBSCRIPTION cannot drive Claude Code on our machines, whatever it can do on a laptop.
     // Saying it here costs one line and saves a support conversation with every team that tries.
-    return 'That does not look like an Anthropic API key (they start with sk-ant-). A Claude Pro or Max subscription will not work here: Xudex needs an API key with credits on it, from console.anthropic.com.';
+    return 'That does not look like an Anthropic API key (they start with sk-ant-). A Claude Pro or Max subscription will not work here: Xucode needs an API key with credits on it, from console.anthropic.com.';
   }
   if (provider === 'openai' && !key.startsWith('sk-')) return 'That does not look like an OpenAI API key (they start with sk-).';
   return null;
 };
 
-const xudex_key_safe = function (doc) {
+const xucode_key_safe = function (doc) {
   if (!doc) return null;
   return { provider: doc.provider, last4: doc.key_last4 || null, added_by_uid: doc.added_by_uid, ts: doc.ts };
 };
 
-export const xudex_key_set = async function (req) {
+export const xucode_key_set = async function (req) {
   const { uid, profile_id, provider, api_key } = req;
   try {
-    if (!XUDEX_KEY_PROVIDERS.includes(provider)) return { code: -1, data: 'that provider is not supported' };
-    const shape_error = xudex_key_shape_error(provider, api_key);
+    if (!XUCODE_KEY_PROVIDERS.includes(provider)) return { code: -1, data: 'that provider is not supported' };
+    const shape_error = xucode_key_shape_error(provider, api_key);
     if (shape_error) return { code: -1, data: shape_error };
 
     const account_profile_info = await get_active_account_profile_info(uid, profile_id);
     // One key per provider per account: adding a new one replaces the old rather than stacking,
     // so there is never a question of which of two keys a run used.
-    const existing = await db_module.find_app_couch_query(account_profile_info.app_id, { selector: { docType: 'xudex_key', provider, stat: 3 }, limit: 5 });
+    const existing = await db_module.find_app_couch_query(account_profile_info.app_id, { selector: { docType: 'xucode_key', provider, stat: 3 }, limit: 5 });
     for (const doc of existing?.docs || []) {
       doc.stat = 4;
       doc.ts = Date.now();
@@ -3735,8 +3761,8 @@ export const xudex_key_set = async function (req) {
     }
 
     const key_doc = {
-      _id: await _common.xuda_get_uuid('xudex_key'),
-      docType: 'xudex_key',
+      _id: await _common.xuda_get_uuid('xucode_key'),
+      docType: 'xucode_key',
       stat: 3,
       provider,
       api_key: String(api_key).trim(),
@@ -3746,29 +3772,29 @@ export const xudex_key_set = async function (req) {
       ts: Date.now(),
     };
     await db_module.save_app_couch_doc_native(account_profile_info.app_id, key_doc);
-    return { code: 1, data: { key: xudex_key_safe(key_doc) } };
+    return { code: 1, data: { key: xucode_key_safe(key_doc) } };
   } catch (err) {
-    console.error(`[xudex] key set failed: ${err?.message || err}`);
+    console.error(`[xucode] key set failed: ${err?.message || err}`);
     return { code: -1, data: 'could not save that key' };
   }
 };
 
-export const xudex_key_list = async function (req) {
+export const xucode_key_list = async function (req) {
   const { uid, profile_id } = req;
   try {
     const account_profile_info = await get_active_account_profile_info(uid, profile_id);
-    const q = await db_module.find_app_couch_query(account_profile_info.app_id, { selector: { docType: 'xudex_key', stat: 3 }, limit: 20 });
-    return { code: 1, data: { keys: (q?.docs || []).map(xudex_key_safe) } };
+    const q = await db_module.find_app_couch_query(account_profile_info.app_id, { selector: { docType: 'xucode_key', stat: 3 }, limit: 20 });
+    return { code: 1, data: { keys: (q?.docs || []).map(xucode_key_safe) } };
   } catch (err) {
     return { code: -1, data: 'could not read your keys' };
   }
 };
 
-export const xudex_key_delete = async function (req) {
+export const xucode_key_delete = async function (req) {
   const { uid, profile_id, provider } = req;
   try {
     const account_profile_info = await get_active_account_profile_info(uid, profile_id);
-    const q = await db_module.find_app_couch_query(account_profile_info.app_id, { selector: { docType: 'xudex_key', provider, stat: 3 }, limit: 5 });
+    const q = await db_module.find_app_couch_query(account_profile_info.app_id, { selector: { docType: 'xucode_key', provider, stat: 3 }, limit: 5 });
     let removed = 0;
     for (const doc of q?.docs || []) {
       doc.stat = 4;
@@ -3783,12 +3809,26 @@ export const xudex_key_delete = async function (req) {
   }
 };
 
-// Internal: the key itself, for a run that is about to start. The only path that reads it, and it
-// never leaves this process except as an environment variable on the engine's own child.
-const xudex_resolve_api_key = async function (uid, profile_id, provider) {
+// Does this account have its own key for a provider, and WHERE does it live. Deliberately asks for
+// `_id` only: the run path no longer needs to see a customer key at all when the proxy is on, and
+// the safest way to keep a secret out of a process is not to load it. The app id goes into the run
+// token so the proxy can do the read on our side.
+const xucode_key_ref = async function (uid, profile_id, provider) {
   try {
     const account_profile_info = await get_active_account_profile_info(uid, profile_id);
-    const q = await db_module.find_app_couch_query(account_profile_info.app_id, { selector: { docType: 'xudex_key', provider, stat: 3 }, limit: 1 });
+    const q = await db_module.find_app_couch_query(account_profile_info.app_id, { selector: { docType: 'xucode_key', provider, stat: 3 }, limit: 1, fields: ['_id'] });
+    return { app_id: account_profile_info.app_id, has_key: !!q?.docs?.length };
+  } catch (err) {
+    return { app_id: null, has_key: false };
+  }
+};
+
+// Internal: the key itself, for a run that is about to start. Only reached when the proxy is OFF,
+// which is the one case where the engine still needs the key in its own environment.
+const xucode_resolve_api_key = async function (uid, profile_id, provider) {
+  try {
+    const account_profile_info = await get_active_account_profile_info(uid, profile_id);
+    const q = await db_module.find_app_couch_query(account_profile_info.app_id, { selector: { docType: 'xucode_key', provider, stat: 3 }, limit: 1 });
     return q?.docs?.[0]?.api_key || null;
   } catch (err) {
     return null;
@@ -3796,24 +3836,124 @@ const xudex_resolve_api_key = async function (uid, profile_id, provider) {
 };
 
 // What the run path asks for: everything needed to launch, or a refusal a customer can act on.
-// Kept here rather than in xudex_engines.mjs because only this file can read the key store.
+// Kept here rather than in xucode_engines.mjs because only this file can read the key store.
 //
 // DELIBERATELY NOT EXPORTED. Its return value contains `launch.env`, which holds the customer's
 // provider API key, and every `export const` in this module gets a generated queue wrapper and is
 // therefore callable over the broker. Exporting this would put a customer's key one internal
 // broker call away from anybody, for no benefit at all: the only caller is the run path, which
 // lives in this same file.
-const xudex_prepare_engine = async function ({ uid, profile_id, engine, model, resume_session_id, sandbox } = {}) {
-  const descriptor = xudex_engines.get_engine(engine);
+const xucode_prepare_engine = async function ({ uid, profile_id, engine, model, resume_session_id, sandbox, run_id, project_id } = {}) {
+  const descriptor = xucode_engines.get_engine(engine);
   if (!descriptor) return { code: -1, data: 'That engine is not available.' };
-  const api_key = descriptor.byok ? await xudex_resolve_api_key(uid, profile_id, descriptor.provider) : null;
-  const launch = xudex_engines.prepare_launch({ engine, model, resume_session_id, api_key, sandbox });
+
+  // Does this account have its own key for this provider. Asked WITHOUT reading it, because with
+  // the proxy on nothing in this process needs to see one.
+  const key_ref = await xucode_key_ref(uid, profile_id, descriptor.provider);
+
+  // A BYOK engine with no key is refused HERE, before a workspace is prepared or a machine woken.
+  // The check moved up from prepare_launch because a proxied launch legitimately carries no key,
+  // so "no key in hand" stopped being the same question as "this account cannot run this engine".
+  if (descriptor.byok && !key_ref.has_key) {
+    return {
+      code: -1,
+      data: `${descriptor.label} runs on your own API key. Add an ${descriptor.provider === 'anthropic' ? 'Anthropic' : descriptor.provider} API key in settings, then try again.`,
+      needs_key: descriptor.provider,
+    };
+  }
+
+  // ── Where the credential lives ────────────────────────────────────────────────────────────
+  // NO provider key reaches the machine, whoever owns it. The machine gets a signed run token and
+  // the region server attaches the real credential: the customer's own when they have one for this
+  // provider, ours otherwise (xucode_proxy.mjs).
+  //
+  // BYOK rides the same path deliberately. The first argument for the proxy was that OUR shared
+  // key must not sit on a box running AI-written code, but a customer's key on that same box is
+  // the same exposure with a different victim, and "they chose it" is a thin defence when the
+  // machine is ours.
+  const pconf = _conf.xucode?.proxy || {};
+  const secret = xucode_proxy.proxy_secret();
+  if (pconf.enabled !== false && secret) {
+    const ttl = (Number(_conf.xucode?.run_timeout_ms) || 30 * 60 * 1000) + (Number(pconf.token_ttl_slack_ms) || 15 * 60 * 1000);
+    const minted = xucode_proxy.mint_token({
+      run_id,
+      uid,
+      project_id,
+      engine: descriptor.key,
+      provider: descriptor.provider,
+      // Present means "this run spends the customer's own account". Absent means ours.
+      key_app_id: key_ref.has_key ? key_ref.app_id : null,
+      ttl_ms: ttl,
+      secret,
+    });
+    if (minted.error) return { code: -1, data: 'Xuda could not prepare a credential for this run.' };
+    const base = pconf.base_url || `https://${process.env.XUDA_HOSTNAME || _conf.domain}${pconf.prefix || '/cpi/xucode_proxy'}`;
+    const proxy = { base_url: base, token: minted.token, home: `${pconf.engine_home_root || '/srv/xucode/.engine'}/${run_id}` };
+    const launch = xucode_engines.prepare_launch({ engine, model, resume_session_id, sandbox, proxy });
+    if (launch.error) return { code: -1, data: launch.error, needs_key: launch.needs_key || null };
+    return { code: 1, launch, has_key: key_ref.has_key, proxied: true, byok: key_ref.has_key };
+  }
+
+  // Proxy off. The key travels to the machine in the engine's environment, which is correct when
+  // the substrate IS this server and a real exposure anywhere else, so it is said out loud rather
+  // than happening quietly.
+  const api_key = key_ref.has_key ? await xucode_resolve_api_key(uid, profile_id, descriptor.provider) : descriptor.provider === 'openai' ? _conf.OPENAI_API_KEY || null : null;
+  console.warn(`[xucode] proxy disabled: ${descriptor.key} will run with ${key_ref.has_key ? "the customer's" : 'the platform'} key in its environment`);
+  const launch = xucode_engines.prepare_launch({ engine, model, resume_session_id, api_key, sandbox });
   if (launch.error) return { code: -1, data: launch.error, needs_key: launch.needs_key || null };
-  return { code: 1, launch, has_key: !!api_key };
+  return { code: 1, launch, has_key: !!api_key, proxied: false, byok: key_ref.has_key };
 };
 
-export const xudex_engine_list = async function () {
-  return { code: 1, data: { engines: xudex_engines.list_engines() } };
+// What the Code tab shows for a project's preview (plan 7).
+//
+// Deliberately does NOT wake a sleeping machine. A panel that polls would otherwise keep every
+// machine awake forever, which is the opposite of what sleep is for and would bill the customer
+// for a screen they left open. So a sleeping machine reports 'asleep' with its URL, and the next
+// run wakes it in the normal way.
+//
+// The URL is derived rather than stored, so it is always the one the router will resolve; there is
+// no second copy to drift. `listening` is the only part that needs the machine, and it is asked
+// for only when the machine is already up.
+export const xucode_preview_status = async function (req) {
+  const { uid, profile_id, app_id } = req || {};
+  try {
+    if (!app_id) return { code: -1, data: 'app_id is required' };
+    const host = xucode_preview_host(app_id);
+    const port = xucode_preview.preview_port(app_id);
+    const base = { url: host ? `https://${host}/` : null, port };
+
+    // `no_wake`: a status read must never resume a machine, or a panel left open keeps every
+    // machine awake and bills the customer for a screen nobody is watching.
+    const machine = await deploy_ms.xucode_machine_for({ uid, app_id, no_wake: true }).catch(() => null);
+    if (!machine || machine.code < 0) {
+      // Asleep, quarantined and "no machine at all" are three different answers, and the customer
+      // deserves the right one: only the middle is a fault.
+      const state = machine?.asleep ? 'asleep' : machine?.quarantined ? 'quarantined' : 'unavailable';
+      return { code: 1, data: { ...base, state, why: String(machine?.data || 'this project has no machine yet') } };
+    }
+
+    // The machine is up (xucode_machine_for refuses a quarantined one and wakes nothing that is
+    // merely asleep beyond its own resume path), so it is safe to ask whether anything is serving.
+    const dir = path.join(_conf.xucode?.projects_root || '/srv/xucode', String(app_id));
+    let listening = false;
+    try {
+      const workspace = await xucode_runtime.acquire({ uid, project_id: app_id, app_id, dir });
+      const status = await xucode_preview.status(workspace, app_id, port);
+      listening = status?.listening === true;
+      await workspace.release().catch(() => {});
+    } catch (e) {
+      return { code: 1, data: { ...base, state: 'unavailable', why: 'Xuda could not reach this project just now.' } };
+    }
+
+    return { code: 1, data: { ...base, state: listening ? 'running' : 'stopped' } };
+  } catch (err) {
+    console.error(`[xucode] preview status failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not read the preview' };
+  }
+};
+
+export const xucode_engine_list = async function () {
+  return { code: 1, data: { engines: xucode_engines.list_engines() } };
 };
 
 export const git_repo_disconnect = async function (req) {
@@ -3912,25 +4052,25 @@ const ensure_git_working_copy = async function ({ uid, repo, conversation_id })
 };
 
 // ── UI-228: the bare mirror ────────────────────────────────────────────────────────────────
-// See xudex_mirror.mjs for why this exists: it is what lets a working copy live on a machine that
+// See xucode_mirror.mjs for why this exists: it is what lets a working copy live on a machine that
 // never holds the customer's token. git_exec is handed over rather than re-implemented, because it is
 // the only thing here that knows how to give git a credential without it landing in an argv.
 // UI-228: the VM substrate, registered as the second implementation of the runtime interface.
-// It reaches the machine over the Proxmox guest agent rather than SSH, because a xudex box is
-// app_type 'vps' and customer VPS on this platform are keyless by design. See xudex_vm.mjs.
+// It reaches the machine over the Proxmox guest agent rather than SSH, because a xucode box is
+// app_type 'vps' and customer VPS on this platform are keyless by design. See xucode_vm.mjs.
 //
 // `resolve_machine` and the Proxmox client are injected rather than imported: only deploy_module
 // owns Proxmox, and asking it over the broker keeps that ownership where it belongs.
-const { create_vm_substrate: _create_xudex_vm } = await import('./xudex_vm.mjs');
-xudex_runtime.register(
-  _create_xudex_vm({
+const { create_vm_substrate: _create_xucode_vm } = await import('./xucode_vm.mjs');
+xucode_runtime.register(
+  _create_xucode_vm({
     pve_request: async (node_doc, method, url, body) => {
       const ret = await deploy_ms.proxmox_api_request({ node_doc, method, url, body });
       if (!ret || ret.code < 0) throw new Error(ret?.data || 'proxmox request failed');
       return ret.data;
     },
     resolve_machine: async ({ uid, app_id }) => {
-      const ret = await deploy_ms.xudex_machine_for({ uid, app_id });
+      const ret = await deploy_ms.xucode_machine_for({ uid, app_id });
       return ret?.code > 0 ? ret.data : null;
     },
   }),
@@ -3943,28 +4083,28 @@ xudex_runtime.register(
 //
 // A substrate that is registered but not available is the normal case, not a fault: `local` is
 // gated off outside dev on purpose (plan 3.1), and `vm` is unavailable on a box with no Proxmox.
-console.log(`[xudex] runtime substrates: ${xudex_runtime.list().map((s) => `${s.kind}=${s.available ? 'available' : 'off'}`).join(' ') || 'none'}`);
+console.log(`[xucode] runtime substrates: ${xucode_runtime.list().map((s) => `${s.kind}=${s.available ? 'available' : 'off'}`).join(' ') || 'none'}`);
 
-const xudex_mirror = _create_xudex_mirror({
+const xucode_mirror = _create_xucode_mirror({
   git_exec,
   du_mb: async (dir) =>
     Number(((await run_process('bash', ['-lc', `du -sm ${JSON.stringify(dir)} | cut -f1`], null, { timeout: 60000 })).stdout || '').trim()) || 0,
-  mirror_root: () => _conf.xudex?.mirror_path || path.join(git_repos_root(), '_mirrors'),
+  mirror_root: () => _conf.xucode?.mirror_path || path.join(git_repos_root(), '_mirrors'),
   clone_timeout_ms: GIT_CLONE_TIMEOUT_MS,
   clone_max_mb: GIT_CLONE_MAX_MB,
 });
 
 // UI-228: the whole chain in one place. Deliberately constructed HERE rather than beside the
-// other xudex imports at the top of the file: it needs `xudex_mirror` and `git_exec`, both of
+// other xucode imports at the top of the file: it needs `xucode_mirror` and `git_exec`, both of
 // which are defined further down, and a top-level const that reads them earlier is a temporal
 // dead zone error that takes the whole module down at boot. `node --check` does not catch it.
-const { create_runner: _create_xudex_runner } = await import('./xudex_run.mjs');
-const xudex_runner = _create_xudex_runner({
-  runtime: xudex_runtime,
-  mirror: xudex_mirror,
-  engines: xudex_engines,
-  verify: xudex_verify,
-  tracker_factory: ({ workspace }) => create_xudex_run_tracker({ workspace }),
+const { create_runner: _create_xucode_runner } = await import('./xucode_run.mjs');
+const xucode_runner = _create_xucode_runner({
+  runtime: xucode_runtime,
+  mirror: xucode_mirror,
+  engines: xucode_engines,
+  verify: xucode_verify,
+  tracker_factory: ({ workspace }) => create_xucode_run_tracker({ workspace }),
   run_process,
   git_exec,
 });
@@ -3976,54 +4116,54 @@ const xudex_runner = _create_xudex_runner({
 // The monthly cap from the plan (50 on free, unlimited above it). Counted from the tracker's own
 // records, which is the second of the three jobs section 9.4 gives that component: one meter, not
 // a separate counter that can drift away from what actually ran.
-const xudex_runs_this_month = async function (app_db_id) {
+const xucode_runs_this_month = async function (app_db_id) {
   const since = new Date();
   since.setUTCDate(1);
   since.setUTCHours(0, 0, 0, 0);
   try {
-    const q = await db_module.find_app_couch_query(app_db_id, { selector: { docType: 'xudex_run', ts: { $gte: since.getTime() } }, limit: 1000 });
+    const q = await db_module.find_app_couch_query(app_db_id, { selector: { docType: 'xucode_run', ts: { $gte: since.getTime() } }, limit: 1000 });
     return (q?.docs || []).length;
   } catch (err) {
     // A failed count must not block a paying customer's work. Erring toward letting the run
     // happen is the right way round: the cap protects margin, and the abuse layers protect the
     // thing that actually matters.
-    console.warn(`[xudex] run count failed: ${err.message}`);
+    console.warn(`[xucode] run count failed: ${err.message}`);
     return 0;
   }
 };
 
-export const xudex_run = async function (req) {
+export const xucode_run = async function (req) {
   const { uid, profile_id, app_id, conversation_id, prompt, engine, model } = req;
   try {
-    if (_conf.xudex?.enabled !== true) return { code: -1, data: 'Xudex is not available yet.' };
+    if (_conf.xucode?.enabled !== true) return { code: -1, data: 'Xucode is not available yet.' };
     if (!app_id) return { code: -1, data: 'app_id is required' };
     if (!prompt || !String(prompt).trim()) return { code: -1, data: 'There is nothing to do: the request was empty.' };
 
-    // 1. Entitlement. The same rules deploy_xudex uses to hand out a machine, asked again here,
+    // 1. Entitlement. The same rules deploy_xucode uses to hand out a machine, asked again here,
     // because a membership can lapse between provisioning a machine and using it.
     //
     // Asked BEFORE resolving the profile's project database, deliberately. That lookup throws on
     // an account it cannot find, and a throw lands in the catch at the bottom as "please try
     // again", which is the least useful thing we could say to someone whose real problem is that
-    // their membership does not include Xudex. Cheap checks first, and each with its own answer.
+    // their membership does not include Xucode. Cheap checks first, and each with its own answer.
     let account_doc = null;
     try {
       const acct = await db_module.get_couch_doc('xuda_accounts', uid);
       account_doc = acct?.code > -1 ? acct.data : null;
     } catch (e) {}
     if (!account_doc) return { code: -1, data: 'Xuda could not read your account just now. Please try again.' };
-    const ent = xudex_deploy_rules.xudex_entitlement(account_doc);
+    const ent = xucode_deploy_rules.xucode_entitlement(account_doc);
     if (!ent.allowed) return { code: -1, data: ent.reason, needs_membership: true };
 
-    // 2. The identity gate. It is SHADOWED today (verify_policy declares xudex_run at level 2 and
+    // 2. The identity gate. It is SHADOWED today (verify_policy declares xucode_run at level 2 and
     // the platform enforcement floor is above it), so this reports what it would have refused and
     // lets the run proceed. When the floor moves, this line starts denying without being touched.
     try {
-      const gate = await verify_ms.verify_gate_check_for_uid({ data: { uid, product: 'xudex_run' } });
+      const gate = await verify_ms.verify_gate_check_for_uid({ data: { uid, product: 'xucode_run' } });
       if (gate?.code > 0 && gate.data && gate.data.allow === false) {
         return {
           code: -412,
-          data: gate.data.message || 'Identity verification is required before running code on Xudex.',
+          data: gate.data.message || 'Identity verification is required before running code on Xucode.',
           error: 'id_verification_required',
           required_level: gate.data.required_level,
           level: gate.data.level,
@@ -4032,7 +4172,7 @@ export const xudex_run = async function (req) {
       }
     } catch (e) {
       // A verification service that is down must not stop paying customers working.
-      console.warn(`[xudex] gate check failed, allowing: ${e.message}`);
+      console.warn(`[xucode] gate check failed, allowing: ${e.message}`);
     }
 
     // 3. The monthly cap. The project database is resolved here, at the first point that actually
@@ -4040,13 +4180,13 @@ export const xudex_run = async function (req) {
     const account_profile_info = await get_active_account_profile_info(uid, profile_id);
     const cap = Number(ent.flags?.runs_per_month);
     if (Number.isFinite(cap) && cap > 0) {
-      const used = await xudex_runs_this_month(account_profile_info.app_id);
+      const used = await xucode_runs_this_month(account_profile_info.app_id);
       if (used >= cap) {
-        return { code: -1, data: `You have used all ${cap} Xudex runs on your plan this month. They reset at the start of next month, or you can upgrade for unlimited runs.`, cap_reached: true, used, cap };
+        return { code: -1, data: `You have used all ${cap} Xucode runs on your plan this month. They reset at the start of next month, or you can upgrade for unlimited runs.`, cap_reached: true, used, cap };
       }
     }
 
-    // 4. The repository. A xudex run without one has nothing to work on, and saying so is better
+    // 4. The repository. A xucode run without one has nothing to work on, and saying so is better
     // than starting an engine in an empty directory and letting it improvise.
     const repo_list = await git_repo_list({ uid, profile_id, app_id });
     const repo_ref = repo_list?.data?.repos?.[0];
@@ -4056,12 +4196,17 @@ export const xudex_run = async function (req) {
 
     // 5. The engine, and its key. A BYOK engine with no key is refused here, before a workspace is
     // prepared or a machine is woken.
-    const prepared = await xudex_prepare_engine({ uid, profile_id, engine, model, resume_session_id: req.resume_session_id || null });
+    //
+    // The run id is minted HERE rather than at the end with the record, because the proxy token
+    // is scoped to it: the id has to exist before anything can be authorized against it. It goes
+    // onto the record too, so a line in the proxy log and a run in the database are the same run.
+    const run_id = await _common.xuda_get_uuid('xucode_run');
+    const prepared = await xucode_prepare_engine({ uid, profile_id, engine, model, resume_session_id: req.resume_session_id || null, run_id, project_id: app_id });
     if (prepared.code < 0) return { code: -1, data: prepared.data, needs_key: prepared.needs_key || null };
 
     // 6. Run it.
     const emit = typeof req.on_event === 'function' ? req.on_event : null;
-    const ret = await xudex_runner.run({
+    const ret = await xucode_runner.run({
       uid,
       repo: repo_full.repo,
       project_id: app_id,
@@ -4070,32 +4215,55 @@ export const xudex_run = async function (req) {
       launch: prepared.launch,
       emit,
       max_repair_attempts: req.max_repair_attempts,
-      verify_ctx: await xudex_verify_context(app_id),
+      // A factory, not a value: the project's files live on whichever machine the runner ends up
+      // acquiring, so this can only be answered once that machine exists.
+      verify_ctx_factory: (workspace) => xucode_verify_context_for(workspace, app_id),
     });
 
     // 7. The record. It is the run meter, the abuse evidence and the benchmark sample all at once,
     // so it is written whether the run succeeded or not.
     if (ret.record) {
       try {
-        await db_module.save_app_couch_doc_native(account_profile_info.app_id, { _id: await _common.xuda_get_uuid('xudex_run'), ...ret.record, app_id, uid });
+        await db_module.save_app_couch_doc_native(account_profile_info.app_id, { _id: run_id, ...ret.record, app_id, uid });
       } catch (e) {
-        console.error(`[xudex] could not persist the run record: ${e.message}`);
+        console.error(`[xucode] could not persist the run record: ${e.message}`);
       }
       if (ret.record.verdict === 'flag') {
-        // Log-only until the thresholds have been tuned against real builds (9.4). Loud, because
-        // this is the line somebody will grep for when an abuse complaint arrives.
-        console.warn(`[xudex] RUN FLAGGED uid=${uid} app=${app_id} reasons=${(ret.record.reasons || []).join('; ')} enforced=${ret.record.enforced}`);
+        // Loud either way, because this is the line somebody will grep for when an abuse
+        // complaint arrives. `enforced` says whether anything was actually done about it, which
+        // is a separate question and stays configurable (9.4).
+        console.warn(`[xucode] RUN FLAGGED uid=${uid} app=${app_id} reasons=${(ret.record.reasons || []).join('; ')} enforced=${ret.record.enforced}`);
+      }
+
+      // Layer 6 (9.3). The run has already been stopped by this point; this is what stops the
+      // NEXT one, which is the half that actually ends an abuser rather than inconveniencing
+      // them. Only ever reached with `tracker.enforce` on, so the default remains observe.
+      if (ret.record.enforced === true) {
+        try {
+          const q = await deploy_msa.xucode_quarantine({ app_id, uid, reasons: ret.record.reasons || [], run_id });
+          if (q?.code < 0) console.error(`[xucode] quarantine failed for ${app_id}: ${q.data}`);
+        } catch (e) {
+          console.error(`[xucode] quarantine threw for ${app_id}: ${e?.message || e}`);
+        }
       }
     }
 
-    // 8. Keep the machine awake for as long as it is being used.
-    try {
-      await deploy_msa.xudex_touch({ app_id });
-    } catch (e) {}
+    // 8. Keep the machine awake for as long as it is being used. Skipped for a run we just
+    // stopped: touching it would reset the idle clock on a machine we want left alone.
+    if (!ret.killed && ret.record?.enforced !== true) {
+      try {
+        // `uid` matters here: `app_id` is the PROJECT, and touch operates on the MACHINE. Passing
+        // the project alone is why this silently did nothing on every run until now.
+        const touched = await deploy_msa.xucode_touch({ app_id, uid });
+        if (touched?.code < 0) console.warn(`[xucode] could not refresh activity for ${app_id}: ${touched.data}`);
+      } catch (e) {
+        console.warn(`[xucode] touch threw for ${app_id}: ${e?.message || e}`);
+      }
+    }
 
     return ret;
   } catch (err) {
-    console.error(`[xudex] run failed: ${err?.message || err}`);
+    console.error(`[xucode] run failed: ${err?.message || err}`);
     return { code: -1, data: 'That run could not be completed. Please try again.' };
   }
 };
@@ -4103,31 +4271,36 @@ export const xudex_run = async function (req) {
 // What the verify loop needs to know about the project: its manifest, its top-level files and
 // whether dependencies are installed. Read from the working copy rather than assumed, because a
 // project whose package.json changed between runs plans different gates.
-const xudex_verify_context = async function (project_id) {
-  const dir = path.join(_conf.xudex?.projects_root || '/srv/xudex', String(project_id));
+// Read from the WORKSPACE, not from this server's disk.
+//
+// This is the clone bug again, one layer up, and it is worth naming because it is the mistake
+// this architecture invites. Reading `/srv/xucode/<project>` locally was correct while runs
+// happened on the region server; once the workspace moved onto a machine, that path is simply
+// absent here, the read throws, and the catch below hands the verify loop an empty project. The
+// visible symptom is the worst kind: a run reporting "nothing to verify" over a repository with
+// a perfectly good test script, which is a verdict nobody should trust.
+//
+// Anything that needs to look at the project's files has to ask the workspace, because the
+// workspace is the only thing that knows which computer they are on.
+const xucode_verify_context_for = async function (workspace, project_id) {
   try {
-    const files = await fs.promises.readdir(dir);
+    const files = await workspace.list_dir('.');
     let manifest = null;
     if (files.includes('package.json')) {
       try {
-        manifest = JSON.parse(await fs.promises.readFile(path.join(dir, 'package.json'), 'utf8'));
+        manifest = JSON.parse(await workspace.read_file('package.json'));
       } catch (e) {
-        // A malformed package.json is the project's problem to fix, and the verify loop will say
-        // so through whatever gate trips on it. It is not a reason to refuse the run.
-        console.warn(`[xudex] unreadable package.json in ${project_id}`);
+        console.warn(`[xucode] unreadable package.json in ${project_id}`);
       }
     }
     return {
       manifest,
       files,
       node_modules_present: files.includes('node_modules'),
-      // The runtime gate. Built here rather than inside the verify loop because only this layer
-      // knows which project it is and how to reach its dev server; the loop just calls it and
-      // treats a dead app like any other failing step, which means a broken preview goes back to
-      // the engine through the same repair path as a broken test.
-      runtime_check: xudex_preview.runtime_check({ project_id, manifest, package_manager: detect_pm(files) }),
+      runtime_check: xucode_preview.runtime_check({ project_id, manifest, package_manager: detect_pm(files) }),
     };
   } catch (err) {
+    console.warn(`[xucode] could not read the project on its machine: ${err?.message || err}`);
     return { manifest: null, files: [], node_modules_present: false };
   }
 };
@@ -11339,8 +11512,8 @@ ${conversation_history || `User (dashboard): ${prompt}`}
       const from_code_surface = get_dashboard_context_obj(req, conversation_doc)?.code_surface === true;
       const project_repo = from_code_surface ? (await git_repo_list({ uid, profile_id, app_id: target_app_id })).data?.repos?.[0] : null;
 
-      // ── UI-228: the Xudex route ─────────────────────────────────────────────────────────
-      // The same surface, a different engine underneath. A Xudex run adds what the Code tab
+      // ── UI-228: the Xucode route ─────────────────────────────────────────────────────────
+      // The same surface, a different engine underneath. A Xucode run adds what the Code tab
       // cannot do today: it verifies the change against the project's own build and tests before
       // answering, hands failures back for a bounded repair, and records what the run cost.
       //
@@ -11348,9 +11521,9 @@ ${conversation_history || `User (dashboard): ${prompt}`}
       // path below is dev-verified and working; this one is newer. `route_code_tab` is false in
       // prod, true on dev, so it can be turned on for real once it has been watched, and turned
       // off in one config edit if it misbehaves, with no deploy and no code change.
-      if (project_repo && _conf.xudex?.enabled === true && _conf.xudex?.route_code_tab === true) {
-        emitToDashboard('stream_phase', 'Starting Xudex run');
-        const xret = await xudex_run({
+      if (project_repo && _conf.xucode?.enabled === true && _conf.xucode?.route_code_tab === true) {
+        emitToDashboard('stream_phase', 'Starting Xucode run');
+        const xret = await xucode_run({
           uid,
           profile_id,
           app_id: target_app_id,
@@ -11360,7 +11533,7 @@ ${conversation_history || `User (dashboard): ${prompt}`}
           // workspace already puts code_surface and project_id, so read it from there first and
           // fall back to a top-level field for any caller that sets one. Unset means the engine
           // registry's own default decides, rather than a name hard-coded here.
-          engine: get_dashboard_context_obj(req, conversation_doc)?.xudex_engine || req.xudex_engine || null,
+          engine: get_dashboard_context_obj(req, conversation_doc)?.xucode_engine || req.xucode_engine || null,
           model: req.codex_model || req.ai_model || null,
           resume_session_id: conversation_doc.codex_session_id && conversation_doc.codex_session_host === code_run_host() ? conversation_doc.codex_session_id : null,
           on_event: (event) => {
@@ -11403,7 +11576,7 @@ ${conversation_history || `User (dashboard): ${prompt}`}
         emitToDashboard('stream_end');
         // A code_run doc, so the workspace panel keeps working unchanged. The panel loads the
         // latest run for a conversation and renders files, diffs, revert and the git header from
-        // it; without this a xudex run would leave it saying "nothing has run in this chat yet"
+        // it; without this a xucode run would leave it saying "nothing has run in this chat yet"
         // right after a run, and every one of those features would have to be rebuilt against a
         // second representation of the same thing.
         try {
@@ -11411,7 +11584,7 @@ ${conversation_history || `User (dashboard): ${prompt}`}
             _id: await _common.xuda_get_uuid('code_run'),
             docType: 'code_run',
             stat: 3,
-            engine: xret.data.engine || 'xudex',
+            engine: xret.data.engine || 'xucode',
             state: xret.data.ok ? 'done' : 'failed',
             uid,
             profile_id,
@@ -11427,7 +11600,7 @@ ${conversation_history || `User (dashboard): ${prompt}`}
             started_ts: xret.record?.started_ts || Date.now(),
             ended_ts: xret.record?.ended_ts || Date.now(),
             usage: xret.record?.tokens || null,
-            // Revert is deliberately NOT offered on a xudex run yet: the file lives on the
+            // Revert is deliberately NOT offered on a xucode run yet: the file lives on the
             // machine, and code_run_revert_file works against the region server's own copy. A
             // Revert button that quietly did nothing is worse than no button.
             files: (xret.data.files || []).map((f) => ({ path: f.rel, rel: f.rel, change: f.status === '??' ? 'add' : f.status === 'D' ? 'delete' : 'change', diff_available: false, revert_available: false })),
@@ -11443,10 +11616,10 @@ ${conversation_history || `User (dashboard): ${prompt}`}
             ts: Date.now(),
           });
         } catch (e) {
-          console.error(`[xudex] could not save the run doc: ${e.message}`);
+          console.error(`[xucode] could not save the run doc: ${e.message}`);
         }
 
-        return await saveAssistantItem(answer, { xudex: true, verified: xret.data.ok, files: xret.data.files, branch: xret.data.branch });
+        return await saveAssistantItem(answer, { xucode: true, verified: xret.data.ok, files: xret.data.files, branch: xret.data.branch });
       }
 
       if (project_repo) {