@xuda.io/ai_module 1.1.5656 → 1.1.5658

package/index.mjs

@@ -98,6 +98,27 @@ 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
+// 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');
+// 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');
+// 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 });
+
 // 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
 // has to survive a pm2 restart, and on dev pm2 watches cpi/ai_module so every deploy is one.
@@ -270,11 +291,23 @@ const get_cheapest_ai_model_code = function () {
   return best?.code || _conf.default_ai_model || null;
 };
 
+// Default model for a Codex run nobody picked a model for (the picker's "Auto").
+// Deliberately NOT the cheapest catalog entry. A Codex run is not a chat turn: it
+// drives real tools over many turns, and the cheapest model cannot hold that shape.
+// Measured on dev 2026-08-13, a from-scratch site build on gpt-5-nano emitted three
+// shell calls the CLI refused to parse ("failed to parse function arguments:
+// duplicate field `cmd`"), fell back to writing the page through a bash heredoc that
+// died on "syntax error near unexpected token `('", and spent its entire wall-clock
+// budget with nothing written to disk. A run that fails costs its full spend and
+// ships nothing, so the cheap default was never actually the cheap option.
+const CODEX_DEFAULT_MODEL_CODE = 'gpt-2';
 const get_openai_codex_model = function () {
   // Codex is user-selectable per request (req.codex_model); when nothing is picked
-  // the default is the CHEAPEST catalog model. Returns a catalog code (resolved to a
-  // real OpenAI id at exec time by get_openai_codex_exec_args).
-  return _conf.openai_codex_model || get_cheapest_ai_model_code();
+  // we use the default above. Returns a catalog code (resolved to a real OpenAI id
+  // at exec time by get_openai_codex_exec_args). Falls back to the cheapest
+  // codex-eligible entry only if that code is missing from the catalog.
+  const fallback = _conf.openai_codex_default_model || CODEX_DEFAULT_MODEL_CODE;
+  return _conf.openai_codex_model || (_is_codex_model(fallback) ? fallback : get_cheapest_ai_model_code());
 };
 
 // Map a legacy ai_models key still stored on old profiles/agents (e.g. 'gpt-5.4') to
@@ -498,6 +531,19 @@ 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
+// 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.
+// 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,
+// so those two calls need a reply rather than a fire-and-forget.
+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 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
@@ -2135,9 +2181,11 @@ export const execute_codex_request = async function (req_or_ip, prompt_arg, atta
       ? `You are OpenAI Codex editing a static website on the local Xuda server.
 
 The site's source files are in your current working directory: ${local_cwd}
-Edit them directly with your normal file tools (read, search, apply patches) — everything is local; do NOT use SSH or scp. Keep changes scoped to the user's request and preserve the rest of the site.
+Edit them directly with your normal file tools (read, search, apply patches). Everything is local, so do NOT use SSH or scp. Keep changes scoped to the user's request and preserve the rest of the site.
+
+WRITE FILES WITH apply_patch, NEVER THROUGH THE SHELL. Do not create or overwrite HTML, CSS, JS or JSON with heredocs (cat <<'EOF' > file), echo, printf or sed. Site markup is full of quotes, parentheses and $ characters, and the shell mangles them: the file lands corrupted, or bash dies on "syntax error near unexpected token" and the whole build burns its time budget retrying. Use the shell only to list, read and check files.
 
-This is the editable source, not the live site. Do NOT deploy or publish anything — the user publishes separately by clicking Publish. When you finish, briefly summarize what you changed.
+This is the editable source, not the live site. Do NOT deploy or publish anything, the user publishes separately by clicking Publish. When you finish, briefly summarize what you changed.
 
 User request:
 ${prompt}`
@@ -3633,6 +3681,137 @@ 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
+// 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.
+//
+// The key is stored exactly where UI-226 puts a git token, and for exactly the same reason: on a
+// 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'];
+
+// 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 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.';
+  }
+  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) {
+  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) {
+  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 (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 });
+    for (const doc of existing?.docs || []) {
+      doc.stat = 4;
+      doc.ts = Date.now();
+      await db_module.save_app_couch_doc(account_profile_info.app_id, doc);
+    }
+
+    const key_doc = {
+      _id: await _common.xuda_get_uuid('xudex_key'),
+      docType: 'xudex_key',
+      stat: 3,
+      provider,
+      api_key: String(api_key).trim(),
+      key_last4: String(api_key).trim().slice(-4),
+      added_by_uid: uid,
+      date_created_ts: Date.now(),
+      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) } };
+  } catch (err) {
+    console.error(`[xudex] key set failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not save that key' };
+  }
+};
+
+export const xudex_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) } };
+  } catch (err) {
+    return { code: -1, data: 'could not read your keys' };
+  }
+};
+
+export const xudex_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 });
+    let removed = 0;
+    for (const doc of q?.docs || []) {
+      doc.stat = 4;
+      doc.api_key = null;
+      doc.ts = Date.now();
+      await db_module.save_app_couch_doc(account_profile_info.app_id, doc);
+      removed++;
+    }
+    return { code: 1, data: { removed } };
+  } catch (err) {
+    return { code: -1, data: 'could not remove that key' };
+  }
+};
+
+// 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) {
+  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 });
+    return q?.docs?.[0]?.api_key || null;
+  } catch (err) {
+    return null;
+  }
+};
+
+// 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.
+//
+// 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);
+  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 });
+  if (launch.error) return { code: -1, data: launch.error, needs_key: launch.needs_key || null };
+  return { code: 1, launch, has_key: !!api_key };
+};
+
+export const xudex_engine_list = async function () {
+  return { code: 1, data: { engines: xudex_engines.list_engines() } };
+};
+
 export const git_repo_disconnect = async function (req) {
   const { uid, profile_id, repo_id } = req;
   try {
@@ -3728,6 +3907,234 @@ 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
+// 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.
+//
+// `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({
+    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 });
+      return ret?.code > 0 ? ret.data : null;
+    },
+  }),
+);
+
+// One line at boot so a box can be asked what it can actually run without adding an endpoint for
+// it. Logged HERE rather than beside the runtime's construction: the VM substrate registers at this
+// point in the file, so a log line further up would always report `local` alone and read like the
+// VM support had failed to load.
+//
+// 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'}`);
+
+const xudex_mirror = _create_xudex_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'),
+  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
+// 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 }),
+  run_process,
+  git_exec,
+});
+
+// ── UI-228: the run, as a method ───────────────────────────────────────────────────────────
+// Everything the runner does not decide: may this account run at all, has it run too much this
+// month, which repository, which engine, and where the record goes afterwards.
+
+// 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 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 });
+    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}`);
+    return 0;
+  }
+};
+
+export const xudex_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 (!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,
+    // 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.
+    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);
+    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
+    // 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' } });
+      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.',
+          error: 'id_verification_required',
+          required_level: gate.data.required_level,
+          level: gate.data.level,
+          missing_claims: gate.data.missing_claims || [],
+        };
+      }
+    } catch (e) {
+      // A verification service that is down must not stop paying customers working.
+      console.warn(`[xudex] gate check failed, allowing: ${e.message}`);
+    }
+
+    // 3. The monthly cap. The project database is resolved here, at the first point that actually
+    // needs it.
+    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);
+      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 };
+      }
+    }
+
+    // 4. The repository. A xudex 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];
+    if (!repo_ref) return { code: -1, data: 'Connect a repository to this project first, then try again.', needs_repo: true };
+    const repo_full = await load_git_repo(uid, profile_id, repo_ref._id);
+    if (repo_full.error) return repo_full.error;
+
+    // 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 });
+    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({
+      uid,
+      repo: repo_full.repo,
+      project_id: app_id,
+      conversation_id,
+      prompt,
+      launch: prepared.launch,
+      emit,
+      max_repair_attempts: req.max_repair_attempts,
+      verify_ctx: await xudex_verify_context(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 });
+      } catch (e) {
+        console.error(`[xudex] 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}`);
+      }
+    }
+
+    // 8. Keep the machine awake for as long as it is being used.
+    try {
+      await deploy_msa.xudex_touch({ app_id });
+    } catch (e) {}
+
+    return ret;
+  } catch (err) {
+    console.error(`[xudex] run failed: ${err?.message || err}`);
+    return { code: -1, data: 'That run could not be completed. Please try again.' };
+  }
+};
+
+// 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));
+  try {
+    const files = await fs.promises.readdir(dir);
+    let manifest = null;
+    if (files.includes('package.json')) {
+      try {
+        manifest = JSON.parse(await fs.promises.readFile(path.join(dir, 'package.json'), 'utf8'));
+      } 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}`);
+      }
+    }
+    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) }),
+    };
+  } catch (err) {
+    return { manifest: null, files: [], node_modules_present: false };
+  }
+};
+
+// Same rule the verify loop uses: the lockfile decides, not a preference.
+const detect_pm = function (files = []) {
+  if (files.includes('pnpm-lock.yaml')) return 'pnpm';
+  if (files.includes('yarn.lock')) return 'yarn';
+  return 'npm';
+};
+
 // ── Status, commit, push, pull request ─────────────────────────────────────────────────────
 export const git_repo_status = async function (req) {
   const { uid, profile_id, repo_id, conversation_id } = req;
@@ -3905,6 +4312,16 @@ export const git_open_pr = async function (req) {
 // run, so this caps OpenAI cost and protects the shared host from spawn floods.
 const SW_GEN_RATE_PER_HOUR = _conf.sw_gen_rate_per_hour || 20;
 const SW_GEN_MAX_CONCURRENT = _conf.sw_gen_max_concurrent || 2;
+// Wall-clock budget for the Codex run itself. A site build is not a chat turn:
+// a from-scratch multi-page site (design system, responsive pass, generated
+// favicon) routinely ran past the old 240s ceiling, and every one of those came
+// back as "The AI took too long to respond" with nothing to show. Only safe
+// alongside the heartbeat in generate_site_draft — see the comment there.
+const SW_GEN_CODEX_TIMEOUT = _conf.sw_gen_codex_timeout || 480000;
+// How often the run touches its job while Codex works. Must stay well under
+// BOTH the inactivity sweeper's job_timeout and the 600s memcached TTL on the
+// job doc, since a single update_job refreshes both.
+const SW_GEN_HEARTBEAT_MS = 30000;
 const _sw_gen_acquire = async (uid) => {
   const now = Date.now();
   const rl_key = `sw_gen_rl_${uid}`;
@@ -4054,7 +4471,33 @@ When done, briefly summarize what you built.`;
       // Model pick from the generate screen (UI-13 #4): forward only a codex-eligible
       // catalog code; anything else (or none) uses the default model.
       const picked_model = _is_codex_model(data.model || data.codex_model) ? (data.model || data.codex_model) : null;
-      const codex_ret = await execute_codex_request({ uid, ip: undefined, local_cwd: dir, prompt: built_prompt, stream: false, sandbox: 'workspace-write', codex_timeout: 240000, codex_model: picked_model });
+      // The Codex step is the long one and it reports nothing while it runs
+      // (stream: false), so the job would sit untouched for its whole duration.
+      // Two things kill a silent job: kill_inactive_jobs fails anything whose
+      // `ts` is older than job_timeout, and the job doc itself is memcached on a
+      // 600s TTL — once that expires, update_job's get_job finds nothing and
+      // returns early, so the finalize at the end of this function lands on a
+      // job that no longer exists and the browser is never told anything. One
+      // beat every 30s refreshes both (set_job rewrites the doc with a fresh
+      // TTL) and doubles as liveness on the wire for the builder's panel. The
+      // sweeper is deliberately left armed rather than opting out with
+      // is_background: if this run truly wedges, the beat stops with it and the
+      // sweeper still closes the job.
+      const beat_until = Date.now() + SW_GEN_CODEX_TIMEOUT + 60000;
+      const beat = setInterval(() => {
+        // Stop beating once the run is past any budget it could legitimately be
+        // using. Beating forever would keep re-arming the job's clock, which is
+        // exactly how a wedged run becomes invisible: the sweeper only fires on
+        // a job that has gone quiet.
+        if (Date.now() > beat_until) return clearInterval(beat);
+        if (job_id) jobs_ms.update_job({ job_id, current_step: 2, current_step_name: 'Generating with AI' }).catch(() => {});
+      }, SW_GEN_HEARTBEAT_MS);
+      let codex_ret;
+      try {
+        codex_ret = await execute_codex_request({ uid, ip: undefined, local_cwd: dir, prompt: built_prompt, stream: false, sandbox: 'workspace-write', codex_timeout: SW_GEN_CODEX_TIMEOUT, codex_model: picked_model });
+      } finally {
+        clearInterval(beat);
+      }
       if (!codex_ret || codex_ret.code < 0) {
         // On a non-zero codex exit, codex_ret.data is an object whose real reason
         // lives in `stderr` (not `message`); only the early guards return a plain
@@ -4723,6 +5166,51 @@ export const unarchive_ai_chat = async function (req) {
   }
 };
 
+// UI-235: a chat is named once, by the model, out of the opening words, and that name is
+// then the only thing the card, the Recent row and every search hit carry. Until now there
+// was no way to change it. The rename is recorded on the chat activity trail next to the
+// "Named by the AI" row it replaces, so the trail says who called it what and when.
+//
+// The caller's own copy only. A shared chat draws its title from the OWNER's doc
+// (get_ai_chat_info resolves the source), so renaming a recipient's pointer would change
+// nothing on screen and is refused with a sentence saying so rather than silently.
+export const rename_ai_chat = async function (req) {
+  const { conversation_id, title, uid } = req;
+
+  try {
+    if (!conversation_id) throw new Error('conversation_id is missing');
+
+    const new_title = String(title ?? '')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .slice(0, 120);
+    if (!new_title) throw new Error('A name is required');
+
+    const account_profile_info = await get_active_account_profile_info(uid);
+    const conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
+
+    if (!conversation_doc || conversation_doc.docType !== 'chat_conversation') throw new Error(`chat ${conversation_id} not found`);
+    if (conversation_doc.shared_from_uid) throw new Error('A shared chat is renamed by the person who owns it');
+    if (conversation_doc.uid !== uid && conversation_doc?.account_profile_info?.uid !== uid) throw new Error('Operation not allowed');
+
+    const previous_title = conversation_doc.title || '';
+    if (previous_title === new_title) return { code: 1, data: { conversation_id, title: new_title } };
+
+    conversation_doc.title = new_title;
+    // The model names a new chat a few seconds after it is created, which can land AFTER a
+    // rename typed straight away. This is what tells it to leave the name alone.
+    conversation_doc.title_set_by = 'user';
+    conversation_doc.ts = Date.now();
+    const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, conversation_doc);
+
+    log_chat_activity(uid, conversation_id, 'renamed', { by: 'user', from: previous_title, title: new_title }, account_profile_info.app_id);
+
+    return { code: 1, data: { conversation_id, title: new_title, save_ret } };
+  } catch (err) {
+    return { code: -3, data: err.message };
+  }
+};
+
 // export const create_studio_app = async function (subject) {
 //   try {
 //     let prompt = `
@@ -5773,6 +6261,44 @@ export const delete_mini_app = async function (req) {
   }
 };
 
+// UI-235: the mini app half of the rename. Same card, same kebab, so the same action has to
+// be there whichever tab it is drawn in. menuName is what every surface shows and menuTitle
+// is what the app's own header shows, and create_mini_app writes the model's name into both,
+// so a rename that moved only one of them would leave the app titled its old name inside.
+export const rename_mini_app = async function (req) {
+  const { prog_id, title, uid } = req;
+
+  try {
+    if (!prog_id) throw new Error('prog_id is missing');
+
+    const new_title = String(title ?? '')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .slice(0, 120);
+    if (!new_title) throw new Error('A name is required');
+
+    const account_profile_info = await get_active_account_profile_info(uid);
+    const prog_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, prog_id);
+
+    if (!prog_doc?.studio_meta?.miniApp) throw new Error(`mini app ${prog_id} not found`);
+    if (prog_doc.studio_meta.shared_from_uid) throw new Error('A shared mini app is renamed by the person who owns it');
+    if (prog_doc.studio_meta.createdByUid !== uid && prog_doc?.studio_meta?.account_profile_info?.uid !== uid) throw new Error('Operation not allowed');
+
+    const previous_title = prog_doc.properties?.menuName || '';
+    if (previous_title === new_title) return { code: 1, data: { prog_id, title: new_title } };
+
+    prog_doc.properties = prog_doc.properties || {};
+    prog_doc.properties.menuName = new_title;
+    prog_doc.properties.menuTitle = new_title;
+    prog_doc.ts = Date.now();
+    const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, prog_doc);
+
+    return { code: 1, data: { prog_id, title: new_title, save_ret } };
+  } catch (err) {
+    return { code: -9, data: err.message };
+  }
+};
+
 export const start_cli_agent_conversation = async function (req) {
   const { uid, agent_id } = req;
   if (!uid) return { code: -1, data: 'uid required' };
@@ -6662,7 +7188,10 @@ export const get_ai_chat_activity = async function (req) {
     });
     // The title only ever differs from the opening words when the AI named it, which is the
     // whole reason the row is worth having.
-    if (conversation_doc.title && conversation_doc.prompt && conversation_doc.title !== getFirstNWords(conversation_doc.prompt, 10)) {
+    // UI-235: unless a person renamed it. This row is reconstructed from the title the doc
+    // holds NOW, so after a rename it would put the user's name in the AI's mouth. Nothing is
+    // lost by dropping it: the recorded rename row carries the name it replaced.
+    if (conversation_doc.title_set_by !== 'user' && conversation_doc.title && conversation_doc.prompt && conversation_doc.title !== getFirstNWords(conversation_doc.prompt, 10)) {
       add('title_set', conversation_doc.ts || created_ts, { by: 'ai', title: conversation_doc.title });
     }
     if (conversation_doc?.category_info?.category) add('categorized', conversation_doc.ts || created_ts, { by: 'ai', category: conversation_doc.category_info.category });
@@ -8534,12 +9063,17 @@ const process_conversation = async function (uid, conversation_id, account_profi
       const title = await submit_chat_gpt_prompt({ uid, prompt: `create title for the prompt return 5 words result maximum text only without options : ${prompt}`, model: _conf.default_ai_model, metadata: { conversation_id: conversation_doc._id, func: 'create_conversation' }, account_profile_info });
 
       conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_doc._id);
-      conversation_doc.title = title.data;
+      // UI-235: the name the model comes back with is seconds late, and a user who renamed
+      // the chat in the meantime would watch their name be overwritten. A name typed by a
+      // person wins over a name guessed from the opening words.
+      if (conversation_doc.title_set_by !== 'user') {
+        conversation_doc.title = title.data;
 
-      await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
-      // UI-202: the chat is renamed from the opening words to whatever the model calls it,
-      // which is the one thing about a chat people ask "where did that come from" about.
-      log_chat_activity(uid, conversation_doc._id, 'title_set', { by: 'ai', title: conversation_doc.title }, account_profile_info.app_id);
+        await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+        // UI-202: the chat is renamed from the opening words to whatever the model calls it,
+        // which is the one thing about a chat people ask "where did that come from" about.
+        log_chat_activity(uid, conversation_doc._id, 'title_set', { by: 'ai', title: conversation_doc.title }, account_profile_info.app_id);
+      }
     }
   }
   /// categorize prompt
@@ -10800,6 +11334,68 @@ ${conversation_history || `User (dashboard): ${prompt}`}
       // opened from the project's own AI panel never takes this path, so VPS work is untouched.
       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
+      // 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.
+      //
+      // Behind a config flag, and the fallback is deliberate rather than defensive. The UI-226
+      // 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({
+          uid,
+          profile_id,
+          app_id: target_app_id,
+          conversation_id,
+          prompt,
+          engine: req.xudex_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) => {
+            if (event.type === 'phase') emitToDashboard('stream_phase', event.text, { update: true });
+            else if (event.type === 'command') emitToDashboard('stream_phase', `Running ${event.command}`, { update: true });
+          },
+        });
+
+        if (xret.code < 0) {
+          // Refusals here are things the customer can act on (no repository, no API key, out of
+          // runs, membership too low), so they are shown as written rather than flattened into a
+          // generic failure.
+          const msg = typeof xret.data === 'string' ? xret.data : 'That run could not be completed.';
+          emitToDashboard('response_start');
+          streamText(msg);
+          emitToDashboard('stream_end', undefined, { error: true });
+          return await saveAssistantItem(msg, { is_request_error: true });
+        }
+
+        // The engine's words and OUR verdict, kept apart on the way out exactly as they are kept
+        // apart inside the runner: an engine that declares victory over a red build must not be
+        // able to borrow the verification's credibility for it.
+        const parts = [xret.data.message || '', '', xret.data.ok ? `Verified: ${xret.data.verdict}.` : `Not verified: ${xret.data.verdict}.`];
+        if (!xret.data.ok && xret.data.failed) {
+          parts.push('', `The ${xret.data.failed.name} step said:`, '```', xret.data.failed.output || '', '```');
+          if (xret.data.pre_existing_failure) parts.push('', 'This looks like it was already failing before this change, so it may not be caused by what you asked for.');
+        }
+        const answer = parts.join('\n').trim();
+
+        if (xret.data.session_id) {
+          conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
+          conversation_doc.codex_session_id = xret.data.session_id;
+          conversation_doc.codex_session_host = code_run_host();
+          conversation_doc.ts = Date.now();
+          await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+        }
+
+        emitToDashboard('response_start');
+        streamText(answer);
+        emitToDashboard('stream_end');
+        return await saveAssistantItem(answer, { xudex: true, verified: xret.data.ok, files: xret.data.files, branch: xret.data.branch });
+      }
+
       if (project_repo) {
         const repo_full = await load_git_repo(uid, profile_id, project_repo._id);
         const prepared = repo_full.repo ? await ensure_git_working_copy({ uid, repo: repo_full.repo, conversation_id }) : { error: 'repository not found' };
@@ -13942,7 +14538,7 @@ const create_and_upload_image_to_drive = async function (drive_type, file_path,
 };
 
 export const create_avatar = async function (req, job_id, headers) {
-  const { docType, uid, url, _id, name, account_type } = req;
+  const { docType, uid, url, _id, name, account_type, age } = req;
   let { metadata } = req;
   try {
     if (!['account', 'account_profile'].includes(docType)) {
@@ -13953,6 +14549,14 @@ export const create_avatar = async function (req, job_id, headers) {
       throw new Error('invalid account_type value');
     }
 
+    // Make older / make younger, from the avatar window. Validated as one of two
+    // words rather than carried through as free text: what the client picks here
+    // ends up in an instruction to an image model, and the wording of that
+    // instruction belongs to this module.
+    if (age && !AVATAR_AGE_PROMPTS[age]) {
+      throw new Error('invalid age value');
+    }
+
     if (!url || url.substr(0, 8) !== 'https://') {
       throw new Error('invalid url');
     }
@@ -13969,7 +14573,7 @@ export const create_avatar = async function (req, job_id, headers) {
       metadata = account_info;
     }
     metadata.is_user = true;
-    return await get_profile_avatar(url, uid, null, account_profile_info, account_type, docType, _id, metadata, undefined, name, account_info.email, job_id, headers);
+    return await get_profile_avatar(url, uid, null, account_profile_info, account_type, docType, _id, metadata, undefined, name, account_info.email, job_id, headers, age);
   } catch (err) {
     return {
       code: -25,
@@ -14035,12 +14639,70 @@ export const generate_login_screen = async function (req, job_id, headers = {})
   }
 };
 
-export const get_profile_avatar = async function (profile_picture, uid, prompt, account_profile_info, account_type, docType = 'account', _id, metadata = {}, business_size = 'unknown', name, email, job_id, headers) {
+// The stages this run goes through, in the order it goes through them, in the
+// words the person waiting is shown. They are written onto the job, which is
+// what carries them to the browser over the job_info socket.
+//
+// Boaz, 2026-08-13: "i cant see the progress and also it takes forever". Both
+// halves of that were true and the first made the second worse: the work is a
+// download, two vision calls, an optional image-model restoration, a background
+// removal and an upload, all behind a single job id that reported nothing until
+// it was finished, so a two minute run and a stuck one looked exactly alike.
+const AVATAR_STEP_READ = 'Reading your picture';
+const AVATAR_STEP_CHECK = 'Checking the picture';
+const AVATAR_STEP_RESTORE = 'Restoring the picture';
+const AVATAR_STEP_FACE = 'Turning it to the camera';
+const AVATAR_STEP_MAKE = 'Making the portrait';
+const AVATAR_STEP_SAVE = 'Saving it';
+const AVATAR_STEPS = [AVATAR_STEP_READ, AVATAR_STEP_CHECK, AVATAR_STEP_RESTORE, AVATAR_STEP_FACE, AVATAR_STEP_MAKE, AVATAR_STEP_SAVE];
+
+// How big the SOURCE picture is allowed to be on its way through here. The
+// avatar is rendered at 1024, restoration downsizes to 1536 on its own account,
+// and nothing in the pipeline reads more detail than that, so carrying a 12
+// megapixel phone photo the whole way buys nothing but a slow lossless PNG
+// re-encode, a multi-megabyte upload to the vision model, and a background
+// removal over four times the pixels that survive to the end.
+const AVATAR_SOURCE_MAX_DIM = 1536;
+// What the inspections are shown. They answer "is there a real face here, is it
+// blurry, is it cropped" (questions a thumbnail settles) and shipping the
+// picture is the slow half of that call.
+const AVATAR_INSPECT_MAX_DIM = 768;
+
+// Boaz, 2026-08-13: "add to this screen make older / younger / regenerate".
+// The wording lives here rather than travelling from the browser, so the client
+// picks a variant and never writes an instruction for the image model itself.
+const AVATAR_PASSPORT_PROMPT =
+  'Return a passport style portrait of the same person on a fully transparent background: head and shoulders only, facing the camera, eyes open, neutral expression, even lighting, no scenery, no props, no text, no border. Keep it unmistakably the same person.';
+const AVATAR_AGE_PROMPTS = {
+  older: `${AVATAR_PASSPORT_PROMPT} Age them by roughly twenty years: grey the hair, add natural lines and skin texture for their later years. Keep the same face shape, eyes, nose, mouth, hairline, skin tone, gender and clothing.`,
+  younger: `${AVATAR_PASSPORT_PROMPT} Take roughly twenty years off them: smooth age lines, restore younger hair colour and fuller skin. Keep the same face shape, eyes, nose, mouth, hairline, skin tone, gender and clothing.`,
+};
+
+export const get_profile_avatar = async function (profile_picture, uid, prompt, account_profile_info, account_type, docType = 'account', _id, metadata = {}, business_size = 'unknown', name, email, job_id, headers, age) {
   const tempDir = os.tmpdir();
   const uniqueId = Date.now() + '_' + Math.random().toString(36).substring(7);
   const tempOutputPath = path.join(tempDir, `output_${uniqueId}.png`);
   const { is_user } = metadata;
   let filename = email || _id || name;
+
+  // Progress, and the timings behind it. Fire and forget in both directions: a
+  // progress update that fails must never take the avatar down with it, and the
+  // log line is what says WHICH stage is the slow one on any given photo.
+  const started_ts = Date.now();
+  let stage_ts = started_ts;
+  const step = function (current_step_name) {
+    console.log(`[avatar] ${current_step_name} (+${((Date.now() - started_ts) / 1000).toFixed(1)}s)`);
+    if (!job_id) return;
+    jobs_ms.update_job({ job_id, steps: AVATAR_STEPS, total_steps: AVATAR_STEPS.length, current_step_name }).catch(() => {});
+  };
+  const mark = function (what) {
+    console.log(`[avatar] ${what} took ${((Date.now() - stage_ts) / 1000).toFixed(1)}s`);
+    stage_ts = Date.now();
+  };
+
+  // An age variant is a prompted edit of the picture the caller handed us, so
+  // it rides the same route the legacy `prompt` argument already had.
+  if (!prompt && AVATAR_AGE_PROMPTS[age]) prompt = AVATAR_AGE_PROMPTS[age];
   // inspect_profile_picture tests ret.code before reading it; this one did not.
   // submit_chat_gpt_prompt reports a FAILED call as
   // { code: -5, data: err.message }, putting prose in the very field the success
@@ -14068,7 +14730,10 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
     needs_restoration: false,
   };
 
-  const inspect_person_in_image = async function (base64) {
+  // Takes a ready data url rather than raw base64: what this call is shown is a
+  // thumbnail (shrink_for_inspection), which is a JPEG, and hard-coding the png
+  // mime type here would describe it wrongly.
+  const inspect_person_in_image = async function (image_url) {
     try {
       const ret = await submit_chat_gpt_prompt({
         uid,
@@ -14083,7 +14748,7 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
               },
               {
                 type: 'input_image',
-                image_url: `data:image/png;base64,${base64}`,
+                image_url,
               },
             ],
           },
@@ -14122,9 +14787,12 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
 
   try {
     let imageBase64;
-    const image_blob_ret = await get_image_blob_from_downloaded_image(profile_picture);
+    step(AVATAR_STEP_READ);
+    const image_blob_ret = await get_image_blob_from_downloaded_image(profile_picture, { max_dim: AVATAR_SOURCE_MAX_DIM });
+    mark('reading the picture');
     let avatar_source = '';
     if (prompt) {
+      step(AVATAR_STEP_MAKE);
       const model = transparent_image_model();
       let ai_avatar_response;
       try {
@@ -14139,7 +14807,24 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
         throw err;
       }
       imageBase64 = ai_avatar_response.data[0].b64_json;
+      mark('the image model');
       account_msa.record_ai_usage(uid, ai_avatar_response.usage.input_tokens, ai_avatar_response.usage.output_tokens, 'profile avatar', prompt, model, { profile_picture }, account_profile_info);
+      // Framed like every other avatar rather than however the model happened to
+      // compose it. An age variant is the SAME portrait a moment later in life,
+      // so it has to sit in the frame the same way the one it replaces did, or
+      // switching between them reads as two different pictures of two different
+      // people. Background removal only if the model would not draw one through:
+      // edit_image_transparent degrades to an opaque render when the resolved
+      // model refuses a transparent background (UI-138).
+      imageBase64 = await normalizeAuthenticProfileAvatar(imageBase64, {
+        remove_background: !(await has_transparent_pixels(Buffer.from(imageBase64, 'base64'))),
+      });
+      mark('framing the portrait');
+      // An age variant is still the account holder's own face, so it must not be
+      // labelled a stand-in: 'fictional' is what the window warns about, and it
+      // is reserved for a likeness invented because the photo could not carry a
+      // real one.
+      if (age) avatar_source = 'authentic profile';
     } else {
       imageBase64 = Buffer.from(await image_blob_ret.image_blob.arrayBuffer()).toString('base64');
       if (account_type === 'business') {
@@ -14317,14 +15002,19 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
           avatar_source = 'fictional';
         };
         // personal account
-        let person_inspection = await inspect_person_in_image(imageBase64);
+        step(AVATAR_STEP_CHECK);
+        let person_inspection = await inspect_person_in_image(await shrink_for_inspection(imageBase64));
+        mark('the inspection');
         const wants_restoration = person_inspection.needs_restoration || person_inspection.is_too_blurry;
 
         if (wants_restoration && person_inspection.is_real_person_in_picture && !person_inspection.is_too_small) {
           console.log('Source photo flagged for restoration, calling gpt-image-1...');
+          step(AVATAR_STEP_RESTORE);
           try {
             const restored_base64 = await restoreFaceWithOpenAI(imageBase64, { uid, account_profile_info, profile_picture });
-            const verify = await inspect_person_in_image(restored_base64);
+            mark('the restoration');
+            const verify = await inspect_person_in_image(await shrink_for_inspection(restored_base64));
+            mark('the restoration check');
             if (verify.is_real_person_in_picture && !verify.is_too_blurry && !verify.is_face_too_cropped) {
               imageBase64 = restored_base64;
               person_inspection = verify;
@@ -14340,19 +15030,68 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
         const can_create_authentic_avatar = source_quality.is_usable && person_inspection.is_real_person_in_picture && !person_inspection.is_too_blurry && !person_inspection.is_too_small;
 
         if (can_create_authentic_avatar) {
+          // Boaz, 2026-08-13: "the head should face to the camera and not
+          // tilted". The lean is a rotation and is handled in the framing; which
+          // way someone FACES is not. A three-quarter photo has an ear and half
+          // a jaw hidden, and no crop, rotation or cut-out brings them back, so
+          // the only honest way to turn a head towards the camera is to redraw
+          // it. That is what the image model does here, on the one signal that
+          // says it is needed: the inspection above already reports whether the
+          // face is front-facing, and until now nothing read it.
+          //
+          // Deliberately narrow, because it is the expensive path: about a
+          // minute and one image generation against the account's credits,
+          // where the cut-out route takes ten seconds and costs nothing. A photo
+          // that already faces the camera never comes near it.
+          let turned = false;
+          if (!person_inspection.is_front_facing) {
+            step(AVATAR_STEP_FACE);
+            console.log('Photo is not front-facing, redrawing it towards the camera...');
+            const model = transparent_image_model();
+            try {
+              const ai_ret = await edit_image_transparent({
+                model: resolve_ai_model(model),
+                image: await toFile(Buffer.from(imageBase64, 'base64'), 'portrait.png', { type: 'image/png' }),
+                prompt: `${AVATAR_PASSPORT_PROMPT} Turn the head to face the camera straight on. Change nothing else about them: same face, same age, same skin tone, same hair, same clothing, same expression.`,
+              });
+              report_ai_status(model);
+              const drawn = ai_ret?.data?.[0]?.b64_json;
+              if (drawn) {
+                imageBase64 = drawn;
+                turned = true;
+                if (ai_ret.usage) {
+                  account_msa.record_ai_usage(uid, ai_ret.usage.input_tokens, ai_ret.usage.output_tokens, 'avatar front facing', 'face the camera', model, { profile_picture }, account_profile_info);
+                }
+              }
+            } catch (err) {
+              // The photo they gave us is still a photo of them. Carrying on
+              // with it beats failing the avatar over the angle of a head.
+              report_ai_status(model, err);
+              console.error('Could not turn the portrait to the camera, using the photo as it is:', err.message);
+            }
+            mark('turning it to the camera');
+          }
+
           // No face box any more. The framing is measured off the cut-out
           // itself (frameSubjectAsAvatar), so asking a vision model where the
           // face is bought nothing but a round trip and a number that could be
           // wrong — and being wrong is what cropped a real avatar's head off.
+          step(AVATAR_STEP_MAKE);
           imageBase64 = await normalizeAuthenticProfileAvatar(imageBase64, {
-            remove_background: !image_blob_ret.is_transparent,
+            // A redrawn portrait comes back on its own transparent background,
+            // so there is nothing left to remove.
+            remove_background: turned ? !(await has_transparent_pixels(Buffer.from(imageBase64, 'base64'))) : !image_blob_ret.is_transparent,
           });
+          mark('the cut-out and framing');
           avatar_source = 'authentic profile';
         } else {
+          step(AVATAR_STEP_MAKE);
           await create_fictional_avatar();
+          mark('the invented likeness');
         }
       }
     }
+    step(AVATAR_STEP_SAVE);
     console.log('Normalizing final avatar to 1024 with transparent padding...');
     imageBase64 = await normalizeBase64To1024(imageBase64);
 
@@ -14373,6 +15112,8 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
 
     let drive_ret = await drive_ms.upload_drive_file_user({ uid, path: '/Profile Images' }, job_id, headers, file_obj);
     drive_ret.data.avatar_source = avatar_source;
+    mark('saving the file');
+    console.log(`[avatar] done in ${((Date.now() - started_ts) / 1000).toFixed(1)}s`);
 
     return drive_ret;
   } catch (error) {
@@ -14380,6 +15121,7 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
     if (error.response?.data) {
       console.error('OpenAI API response:', error.response.data);
     }
+    console.log(`[avatar] failed after ${((Date.now() - started_ts) / 1000).toFixed(1)}s: ${error.message}`);
     return { code: -56, data: error.message };
   }
 };
@@ -15136,6 +15878,47 @@ const get_mini_app_info = async function (uid, prog_doc) {
   return doc;
 };
 
+// UI-236: the apps grid's live-update path. get_apps answers a fetch and nothing was ever
+// pushed afterwards, so a mini app renamed, archived or re-thumbnailed elsewhere sat stale
+// on screen while the chats grid moved on its own. Results.vue has carried the
+// mini_app_doc_updated handler all along; this is the emit it was waiting for.
+//
+// The audience is the account that owns the PROJECT DATABASE the doc lives in, and the
+// caller passes it (controller_module already holds app_obj.app_uId). It is never read off
+// the doc, because no field on the doc answers the question: across the 98 mini app studio
+// docs on dev, doc.uid is unset on every single one, createdByUid is the ORIGINAL author and
+// points at a different account on 33 of them (a marketplace install or a share keeps the
+// author's uid), and a shared reference copy carries no createdByUid at all. Emitting to
+// createdByUid would push one account's row into another account's dashboard.
+export const emit_mini_app_doc_updated = async function (req) {
+  const { app_id, uid, doc } = req || {};
+  try {
+    if (!app_id || !uid || !doc?._id) return { code: 0, data: 'nothing to emit' };
+    // Exactly what get_apps selects on, so this fires for precisely the docs that can be
+    // rows in that grid and for nothing else.
+    if (doc.docType !== 'studio' || !doc?.studio_meta?.miniApp) return { code: 0, data: 'not a mini app' };
+
+    // The shape get_apps builds its rows from (the shared-copy swap onto the origin doc plus
+    // apply_recipient_marks, user_contact, privilege), because update_fn in the dashboard
+    // Object.assigns this straight into the row it already has, and unshifts it when the row
+    // is new. The raw prog doc would overwrite a good row with a half one.
+    const data = await get_mini_app_info(uid, doc);
+
+    ws_dashboard_msa.emit_message_to_dashboard({
+      service: 'mini_app_doc_updated',
+      to: [uid],
+      data,
+    });
+
+    return { code: 1, data: { prog_id: doc._id, to: uid } };
+  } catch (err) {
+    // Never throws: this hangs off the change reader, and a grid that fails to move is not a
+    // reason to break the checker and history pipeline running beside it.
+    console.error('[emit_mini_app_doc_updated]', doc?._id, err?.message || err);
+    return { code: -1, data: err?.message || String(err) };
+  }
+};
+
 export const pin_ai_chat = async function (req) {
   const { uid, conversation_id } = req;
   try {
@@ -15812,6 +16595,55 @@ function normalizeFilename(name) {
     .replace(/^_+|_+$/g, ''); // trim leading/trailing underscores
 }
 
+// A thumbnail to ask a vision model about, as a ready data url.
+//
+// The inspections decide whether a real face is visible and whether it is
+// blurry, cropped or degraded, all of which a 768px JPEG answers exactly as
+// well as the full picture, at a fortieth of the bytes. Uploading the original
+// was pure waiting: a phone photo re-encoded to lossless PNG is megabytes, and
+// it went up the wire twice on any photo that got restored.
+//
+// Only ever shrinks. A picture already smaller than this is passed through, so
+// "is it too small" still sees the size the person actually uploaded.
+async function shrink_for_inspection(base64Image) {
+  try {
+    const jpeg = await sharp(Buffer.from(base64Image, 'base64'))
+      .flatten({ background: { r: 255, g: 255, b: 255 } })
+      .resize({ width: AVATAR_INSPECT_MAX_DIM, height: AVATAR_INSPECT_MAX_DIM, fit: 'inside', withoutEnlargement: true })
+      .jpeg({ quality: 82 })
+      .toBuffer();
+    return `data:image/jpeg;base64,${jpeg.toString('base64')}`;
+  } catch (err) {
+    // Never lose the inspection over the optimisation that was meant to speed
+    // it up: fall back to shipping the picture as it stands.
+    console.error('shrink_for_inspection failed, sending the full picture:', err.message);
+    return `data:image/png;base64,${base64Image}`;
+  }
+}
+
+// Does this image actually carry transparency? An alpha channel on its own does
+// not mean it is used, which is the whole question when deciding whether a
+// picture still needs its background removed.
+async function has_transparent_pixels(inputBuffer) {
+  try {
+    const image = sharp(inputBuffer);
+    const metadata = await image.metadata();
+    if (!metadata.hasAlpha) return false;
+
+    const { data, info } = await image.ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    const channels = info.channels;
+    for (let i = channels - 1; i < data.length; i += channels) {
+      if (data[i] < 255) return true;
+    }
+    return false;
+  } catch (err) {
+    // Unreadable: assume it is opaque, which only means the background removal
+    // runs on something that may not need it. The other way round leaves a
+    // photograph's own background sitting in the avatar.
+    return false;
+  }
+}
+
 async function inspectAvatarSourceQuality(base64Image) {
   const inputBuffer = Buffer.from(base64Image, 'base64');
   const metadata = await sharp(inputBuffer).metadata();
@@ -15839,18 +16671,56 @@ async function inspectAvatarSourceQuality(base64Image) {
 //
 // That describes the PRODUCT, not one route to it, so this route — which reaches
 // the same result with sharp instead of a model — has to land in the same place.
-// It did not. It framed to a "passport" geometry of its own invention: the head
-// at 62% of the frame, sized and positioned from a vision model's face box, with
-// no margin guaranteed anywhere. Two of the four requirements were missed
-// outright, and when the face box came back short the crop took the crown off
-// the top of a real account's avatar.
 //
-// These two numbers are the "top margin" and a little air at the sides.
-// Everything else the spec asks for — centred, covering the picture,
-// transparent — falls out of the composition rather than being tuned.
+// These two numbers are the "top margin" and a little air at the sides, used
+// when the whole SUBJECT is what gets fitted: a cut-out with no readable head in
+// it, where passport proportions have nothing to measure from.
+// The margins are what "centered with paddind" (Boaz) means on this route: the
+// subject is fitted whole, so without them it touches the frame, and a circle
+// drawn over that clips the very edges of a person who was already fully in
+// shot. Roomier than they were for that reason.
 const AVATAR_SIZE = 1024;
-const AVATAR_TOP_MARGIN = 0.06;
-const AVATAR_SIDE_MARGIN = 0.02;
+const AVATAR_TOP_MARGIN = 0.12;
+const AVATAR_SIDE_MARGIN = 0.08;
+
+// Boaz, 2026-08-13: "fix the avatar (base on the profile picture) to transform
+// as passport portraite picture transparent".
+//
+// A passport portrait is a stated geometry, not a style: the head is a fixed
+// share of the frame, sits square in the middle of it, and has air above the
+// crown. These are the ICAO proportions, at the roomy end of the band because
+// every surface in Xuda draws this inside a CIRCLE, and a crop tuned for a
+// rectangle loses its corners there.
+//
+// This is the second attempt at passport framing here and it fails differently
+// from the first. That one sized the head from a VISION MODEL's face box, and
+// when the box came back short the crop took the crown off the top of a real
+// account's avatar. Nothing is asked of a model here: the background is already
+// gone, so the cut-out's own silhouette says where the head is, and the frame is
+// positioned FROM THE CROWN: the top of the head is placed, never computed as
+// a leftover, so it cannot be cropped away.
+// Boaz, 2026-08-13, on the first passport avatar: "the avatar should show head
+// and shoulders centered with paddind". These numbers are lower than the ICAO
+// band on purpose, because the frame is not what anyone sees: every surface in
+// Xuda draws this file inside a CIRCLE, and the inscribed circle of a square
+// keeps only the middle of it. At a passport-tight 0.6 the shoulders live in the
+// corners, which is exactly where the circle cuts, so a correctly framed
+// head-and-shoulders portrait arrived on screen as a head floating on its own.
+// Sized so the shoulders survive the circle and there is air above the crown.
+const PASSPORT_HEAD_HEIGHT = 0.46; // crown to chin, as a share of the frame
+const PASSPORT_CROWN_TOP = 0.17; // air above the crown, same
+// A head that measures wildly out of proportion means the silhouette was read
+// wrong (a hat, a raised hand, a segmenter that kept a chair back). Sizing off a
+// bad measurement is what produces a nose filling the frame, so the scale is
+// held to a band where the head stays recognisably a head.
+const PASSPORT_HEAD_WIDTH_MIN = 0.3;
+const PASSPORT_HEAD_WIDTH_MAX = 0.75;
+// The shoulder line lands a little below the chin, in the middle of the flare
+// rather than at its start, so the chin is this far back up towards the crown.
+// Measured against real cut-outs (a full-length selfie and a tight portrait):
+// it lands within a few per cent, and what error is left runs SHORT of the chin,
+// which frames a slightly larger head rather than cropping into the face.
+const SHOULDER_TO_CHIN = 0.9;
 
 // Frame a background-removed portrait to that spec.
 //
@@ -15861,6 +16731,16 @@ async function frameSubjectAsAvatar(segmentedBuffer) {
   const bounds = await measureOpaqueBounds(segmentedBuffer);
   if (!bounds) return sharp(segmentedBuffer).png({ force: true }).toBuffer();
 
+  // Passport geometry when the head could be found, which is the normal case
+  // for a portrait. Everything below is the fallback for a cut-out with no
+  // readable head in it, and fits the whole subject instead.
+  const head = resolveHeadGeometry(bounds);
+  console.log(
+    `[avatar] framing ${bounds.width}x${bounds.height}: ${head ? `passport, head ${head.crownY} to ${head.chinY}, centre ${Math.round(head.headCenterX)}` : 'no head measured, fitting the whole subject'}`,
+  );
+  const passport = await framePassportPortrait(segmentedBuffer, bounds);
+  if (passport) return passport;
+
   // The subject's own edges rather than every opaque pixel, on BOTH axes. A
   // speck above the head shrinks the person to make room for a stray pixel; a
   // speck beside them widens the frame and pushes them off centre, which breaks
@@ -15890,22 +16770,151 @@ async function frameSubjectAsAvatar(segmentedBuffer) {
     .toBuffer();
 }
 
+// Passport proportions, measured off the silhouette.
+//
+// The frame is placed rather than cropped to: the crown goes at
+// PASSPORT_CROWN_TOP and the head is scaled to PASSPORT_HEAD_HEIGHT, so the top
+// of the head has a guaranteed position instead of being whatever survives a
+// crop. Whatever falls outside the frame after that is shoulder, which is what a
+// passport photo cuts anyway.
+//
+// Returns null when the head could not be measured, so the caller can fall back
+// to fitting the whole subject.
+// Was a head measured at all? measureHead reports nothing rather than a guess
+// when the silhouette does not say, and this is the one place that reading is
+// turned into "frame it as a passport portrait" or "leave the framing alone".
+function resolveHeadGeometry(bounds) {
+  if (!bounds || !(bounds.chinY > bounds.crownY) || !(bounds.headWidth > 1)) return null;
+  return { crownY: bounds.crownY, chinY: bounds.chinY, headCenterX: bounds.headCenterX, headWidth: bounds.headWidth };
+}
+
+async function framePassportPortrait(segmentedBuffer, bounds) {
+  const head = resolveHeadGeometry(bounds);
+  if (!head) return null;
+  const { crownY, chinY, headCenterX, headWidth } = head;
+
+  // The square of SOURCE pixels that becomes the 1024 frame. Solved for rather
+  // than scaled to, so the crop happens at the picture's own size and the resize
+  // is one bounded step at the end: a small head in a large photo needs a four
+  // times enlargement, and doing that to the whole picture first would mean
+  // resampling a hundred megapixels to throw nearly all of them away.
+  const headHeight = chinY - crownY + 1;
+  let window = headHeight / PASSPORT_HEAD_HEIGHT;
+
+  // Sanity, not taste, and only where it means anything: a head measured off the
+  // SILHOUETTE that lands outside this width band was misread, and the clamp is
+  // what keeps a bad reading from becoming an avatar of somebody's nose. There
+  // is no width to check when the head came from the inspection, which reports a
+  // height and has already been held to it.
+  if (headWidth > 1) {
+    if (headWidth / window > PASSPORT_HEAD_WIDTH_MAX) window = headWidth / PASSPORT_HEAD_WIDTH_MAX;
+    if (headWidth / window < PASSPORT_HEAD_WIDTH_MIN) window = headWidth / PASSPORT_HEAD_WIDTH_MIN;
+  }
+
+  // Never further out than the framing this replaces. Whatever the measurement
+  // does, the worst case is then the whole subject fitted to the frame, which is
+  // what every avatar looked like before passport framing existed. It bounds the
+  // damage of a bad reading to "no better than yesterday" instead of "the face
+  // is a stamp in the middle of a body".
+  const subject_window = (bounds.footY - bounds.crownY + 1) / (1 - AVATAR_TOP_MARGIN);
+  window = Math.max(2, Math.round(Math.min(window, subject_window)));
+  if (!Number.isFinite(window)) return null;
+
+  // Centred on the head, with the crown at its mark.
+  const windowLeft = Math.round(headCenterX - window / 2);
+  const windowTop = Math.round(crownY - window * PASSPORT_CROWN_TOP);
+
+  // The window can hang off any edge: a head near the top of its photo, a
+  // portrait narrower than the frame. So the picture is padded with transparency
+  // first and the window then always lands inside it. Padded rather than nudged
+  // back in: moving the window would put the head somewhere other than where the
+  // spec says it goes, which is the whole point of framing this way.
+  const pad_left = Math.max(0, -windowLeft);
+  const pad_top = Math.max(0, -windowTop);
+  const pad_right = Math.max(0, windowLeft + window - bounds.width);
+  const pad_bottom = Math.max(0, windowTop + window - bounds.height);
+
+  const padded =
+    pad_left || pad_top || pad_right || pad_bottom
+      ? await sharp(segmentedBuffer)
+          .ensureAlpha()
+          .extend({ top: pad_top, bottom: pad_bottom, left: pad_left, right: pad_right, background: { r: 0, g: 0, b: 0, alpha: 0 } })
+          .png({ force: true })
+          .toBuffer()
+      : segmentedBuffer;
+
+  return sharp(padded)
+    .ensureAlpha()
+    .extract({ left: windowLeft + pad_left, top: windowTop + pad_top, width: window, height: window })
+    .resize(AVATAR_SIZE, AVATAR_SIZE, { fit: 'fill' })
+    .png({ force: true })
+    .toBuffer();
+}
+
+// Boaz, 2026-08-13: "the head should face to the camera and not tilted".
+//
+// The half of that a crop can honestly do is the LEAN. On a portrait the line
+// from the middle of the chest to the middle of the head is vertical; when
+// someone tips their head, or the camera was not level, that line tilts, and the
+// angle it is off by is the correction. Both centres come out of the measurement
+// the framing already does, so this costs one rotation and nothing else.
+//
+// Deliberately timid. Only acts past a couple of degrees (below that there is
+// nothing to see and the estimate is noise), never turns more than fifteen (a
+// bigger reading means the silhouette was misread, not that the person is nearly
+// horizontal), and rotates about the head rather than the picture, so what is
+// straightened is the face.
+//
+// Which way the person FACES is the other half, and it is not a rotation: a
+// three-quarter view has one ear hidden, and no amount of turning the picture
+// brings it back. That needs the image model, which is what the older/younger
+// route already uses.
+const AVATAR_TILT_MIN_DEG = 2;
+const AVATAR_TILT_MAX_DEG = 15;
+async function straightenSubject(segmentedBuffer, bounds) {
+  try {
+    if (!bounds || bounds.chestCenterX == null || bounds.headCenterX == null || bounds.chinY == null) return segmentedBuffer;
+    const rise = bounds.chestY - (bounds.crownY + bounds.chinY) / 2;
+    if (!(rise > 1)) return segmentedBuffer;
+    const deg = (Math.atan2(bounds.headCenterX - bounds.chestCenterX, rise) * 180) / Math.PI;
+    if (!Number.isFinite(deg) || Math.abs(deg) < AVATAR_TILT_MIN_DEG || Math.abs(deg) > AVATAR_TILT_MAX_DEG) return segmentedBuffer;
+
+    console.log(`[avatar] straightening a ${deg.toFixed(1)} degree lean`);
+    return await sharp(segmentedBuffer)
+      .ensureAlpha()
+      .rotate(-deg, { background: { r: 0, g: 0, b: 0, alpha: 0 } })
+      .png({ force: true })
+      .toBuffer();
+  } catch (err) {
+    // A picture that is not straightened is a picture that is not straightened.
+    // Losing the avatar over it would be the worse trade.
+    console.error('[avatar] could not straighten the subject:', err.message);
+    return segmentedBuffer;
+  }
+}
+
 async function normalizeAuthenticProfileAvatar(base64Image, options = {}) {
   const { remove_background = true } = options;
   const inputBuffer = Buffer.from(base64Image, 'base64');
   const orientedBuffer = await sharp(inputBuffer).rotate().png({ force: true }).toBuffer();
   const segmentedBuffer = remove_background ? await removePortraitBackground(orientedBuffer) : orientedBuffer;
 
-  const framedBuffer = await frameSubjectAsAvatar(segmentedBuffer);
+  // Level first, frame second: the framing measures a crown, a chin and a
+  // centre, and all three move when the picture turns.
+  const uprightBuffer = await straightenSubject(segmentedBuffer, await measureOpaqueBounds(segmentedBuffer));
+
+  const framedBuffer = await frameSubjectAsAvatar(uprightBuffer);
 
   const subjectBuffer = await sharp(framedBuffer).modulate({ brightness: 1.02, saturation: 1.04 }).sharpen({ sigma: 0.35, m1: 0.4, m2: 0.2 }).png({ quality: 98, compressionLevel: 8, force: true }).toBuffer();
 
   return subjectBuffer.toString('base64');
 }
 
+// Takes an already oriented PNG buffer. It used to rotate and re-encode one of
+// its own, which on a multi-megapixel photo is a second full lossless PNG round
+// trip for a picture its only caller had just produced exactly that way.
 async function removePortraitBackground(inputBuffer) {
-  const orientedBuffer = await sharp(inputBuffer).rotate().png({ force: true }).toBuffer();
-  const inputBlob = new Blob([orientedBuffer], { type: 'image/png' });
+  const inputBlob = new Blob([inputBuffer], { type: 'image/png' });
 
   const outputBlob = await imglyRemoveBackground(inputBlob, {
     model: 'medium',
@@ -15977,21 +16986,237 @@ async function measureOpaqueBounds(inputBuffer) {
     return to;
   };
 
+  // The subject's own edges, specks excluded. crownY is the top of the head.
+  const crownY = firstIndex(rowCounts, minY, maxY, rowFloor);
+  const footY = lastIndex(rowCounts, minY, maxY, rowFloor);
+
   return {
     minX,
     minY,
     maxX,
     maxY,
-    // The subject's own edges, specks excluded. crownY is the top of the head.
-    crownY: firstIndex(rowCounts, minY, maxY, rowFloor),
-    footY: lastIndex(rowCounts, minY, maxY, rowFloor),
+    crownY,
+    footY,
     bodyMinX: firstIndex(colCounts, minX, maxX, colFloor),
     bodyMaxX: lastIndex(colCounts, minX, maxX, colFloor),
+    ...measureHead(data, width, channels, alphaThreshold, rowCounts, crownY, footY),
     width,
     height,
   };
 }
 
+// The HEAD inside that silhouette: where it ends, and where its middle is.
+//
+// There is no face model in this pipeline and one is not worth a megabyte of
+// download to answer this. A background-removed portrait gives the head away by
+// its shape: the head is the narrow mass at the top and the shoulders below it
+// are markedly wider, so the row where the silhouette pinches is the neck, and
+// the chin is just above it. Exactly the reading the picture window already
+// makes on the client to centre a face in its circle.
+//
+// Returns nothing measurable (chinY null) rather than a guess when the shape
+// says nothing, so the caller can frame the whole subject instead of trusting a
+// number it invented.
+function measureHead(data, width, channels, alphaThreshold, rowCounts, crownY, footY) {
+  const none = { chinY: null, headCenterX: null, headWidth: 0 };
+  const height = footY - crownY + 1;
+  if (height < 8) return none;
+
+  // Smoothed, because the reading below is about the SHAPE of the silhouette,
+  // and a strand of hair or a gap in the cut-out is not part of the shape.
+  const span = Math.max(1, Math.round(height * 0.01));
+  const smooth = new Float64Array(height);
+  for (let i = 0; i < height; i++) {
+    let sum = 0;
+    let n = 0;
+    for (let k = -span; k <= span; k++) {
+      const j = i + k;
+      if (j >= 0 && j < height) {
+        sum += rowCounts[crownY + j];
+        n++;
+      }
+    }
+    smooth[i] = sum / n;
+  }
+
+  // Walk down from the crown looking for the first widen, pinch, widen: out
+  // through the head, in at the neck, out again at the shoulders.
+  //
+  // Deliberately not "the widest row in the top third", which is what this used
+  // to do. That assumes the head is a known share of whatever is in frame, and
+  // it is not: on a photo taken a few steps back the shoulders are already
+  // inside the top third, so they won the "widest row" and the head then
+  // measured as the entire body. That assumption is why one photo framed well
+  // and the next one did not, so it is the assumption that had to go.
+  const DIP = 0.85; // how far below the head's own width the neck has to pinch
+  const RISE = 1.2; // and how much wider the shoulders have to come back
+  let peak = 0;
+  let neck = -1;
+  let neckW = Infinity;
+  for (let i = 0; i < height; i++) {
+    const w = smooth[i];
+    // Still on the way out through the head. A new peak well above a candidate
+    // pinch means that pinch was noise on the way up, so the search restarts.
+    if (w > peak && (neck < 0 || w > neckW * RISE)) {
+      peak = w;
+      neck = -1;
+      neckW = Infinity;
+    }
+    if (peak > 0 && w <= peak * DIP) {
+      if (w < neckW) {
+        neckW = w;
+        neck = crownY + i;
+      } else if (w >= neckW * RISE) {
+        break; // pinched and widened again: that was the neck
+      }
+    }
+  }
+  // A pinch needs something wider BELOW it to be a neck rather than a chin at
+  // the bottom edge of the picture. Measured against the widest row under the
+  // pinch, not the last one: a portrait can taper again at the very bottom (an
+  // arm leaving the frame, a jacket cut off) and reading only the final row
+  // called a perfectly good neck unconfirmed.
+  let below = 0;
+  for (let i = neck > -1 ? neck - crownY + 1 : height; i < height; i++) if (smooth[i] > below) below = smooth[i];
+  const confirmed = neck > -1 && below >= neckW * RISE;
+
+  let widest = 0;
+  let widestAt = crownY;
+  for (let y = crownY; y <= footY; y++) {
+    if (rowCounts[y] > widest) {
+      widest = rowCounts[y];
+      widestAt = y;
+    }
+  }
+  // Is there a BODY below the head at all? The two cases need opposite answers,
+  // so this comes before anything else.
+  //
+  // Read at the BOTTOM EDGE rather than by asking where the widest row is. A
+  // head tapers: the lowest rows of a head-only cut-out are a jaw or a neck, a
+  // fraction of the width at the cheeks. A body does not: shoulders, arms and
+  // clothing run out of the frame at close to full width. Asking instead
+  // "is the widest row near the bottom" reads a portrait whose hair flares at
+  // chest height as head-only, and that mistake frames a whole person as if
+  // they were one head.
+  // Read just ABOVE the bottom edge, and take the widest row there rather than
+  // the average. Straightening a lean rotates the cut-out, which leaves
+  // transparent wedges in the bottom corners: averaging the last rows counts
+  // those wedges as the person getting narrower, and a straightened portrait
+  // then reads as head-only. A band a little higher up is past them.
+  let bottom_width = 0;
+  const bottom_from = Math.max(crownY, footY - Math.round(height * 0.15));
+  const bottom_to = Math.max(bottom_from, footY - Math.round(height * 0.03));
+  for (let y = bottom_from; y <= bottom_to; y++) if (rowCounts[y] > bottom_width) bottom_width = rowCounts[y];
+  // Two thirds of the widest row is the line between the two. Shoulders, arms
+  // and clothing leave the frame at nearly full width; a head is well past its
+  // cheeks by the time it reaches its own last rows, so it never gets there.
+  const has_body = bottom_width >= widest * 0.7;
+
+  let chinY;
+  if (confirmed) {
+    // The chin sits a little ABOVE the narrowest point, which is mid-neck.
+    // Clamped to a band as a backstop: a head is roughly two fifths of a
+    // head-and-shoulders subject and never two thirds, so one freak narrow row
+    // cannot drag the chin down onto the chest.
+    const pinch = Math.min(Math.max(neck - crownY, height * 0.2), height * 0.6);
+    chinY = Math.round(crownY + pinch * 0.94);
+  } else if (has_body) {
+    // No pinch, but there IS a body: hair over the shoulders, a scarf, a collar.
+    // Very common, and the case that broke the first version of this, which read
+    // the whole person as one head and framed a body's worth of picture with the
+    // face a thumbnail in the middle of it.
+    //
+    // Read the SHOULDER LINE instead: the row where the silhouette widens
+    // FASTEST. Above it the outline is a head, which widens gently and then
+    // holds; at the shoulders it flares. The steepest row sits a little below
+    // the chin, in the middle of that flare, so the chin is a fraction of the
+    // way back up towards the crown.
+    //
+    // Measured as a rate of change rather than against a threshold width, and
+    // that is the point: a threshold has to be a fraction of SOMETHING, and
+    // every candidate (the widest row, the frame) changes meaning between a
+    // full-length photo and a tight portrait. A tight portrait is not
+    // hypothetical, it is what this same function produces, so the rule has to
+    // survive being pointed at its own output.
+    const shoulder = steepestWidening(smooth, height);
+    if (shoulder < 0) return none;
+    chinY = Math.round(crownY + Math.min(Math.max(shoulder * SHOULDER_TO_CHIN, height * 0.12), height * 0.7));
+  } else {
+    // A head-only cut-out with no shoulders in frame. The whole subject IS the
+    // head, which is the honest reading and the one that keeps the crown where
+    // it belongs.
+    chinY = footY;
+  }
+
+  // Middle and width of the head itself, measured over the head band only, so
+  // wide shoulders cannot drag either sideways.
+  let sumX = 0;
+  let count = 0;
+  let headMinX = width;
+  let headMaxX = -1;
+  for (let y = crownY; y <= chinY; y++) {
+    for (let x = 0; x < width; x++) {
+      if (data[(y * width + x) * channels + (channels - 1)] > alphaThreshold) {
+        sumX += x;
+        count++;
+        if (x < headMinX) headMinX = x;
+        if (x > headMaxX) headMaxX = x;
+      }
+    }
+  }
+  if (!count || headMaxX < 0) return none;
+
+  // The same reading again over the CHEST, which is what the head is leaning
+  // against. Two centres and the distance between them is a line that should be
+  // vertical on a portrait, and the angle it is off by is the lean.
+  let chestSumX = 0;
+  let chestCount = 0;
+  const chestTop = Math.min(footY, chinY + Math.round((chinY - crownY) * 0.15));
+  const chestBottom = Math.min(footY, chinY + Math.round((chinY - crownY) * 0.6));
+  for (let y = chestTop; y <= chestBottom; y++) {
+    for (let x = 0; x < width; x++) {
+      if (data[(y * width + x) * channels + (channels - 1)] > alphaThreshold) {
+        chestSumX += x;
+        chestCount++;
+      }
+    }
+  }
+
+  // Last check, and the one that catches the reading going wrong rather than
+  // being imprecise: a head is never three times wider than it is tall. When it
+  // measures that way the "shoulder line" was the hair flaring out below the
+  // crown, which happens on a picture that is ALREADY a tight portrait, where
+  // the head fills the frame and its own widening is the steepest thing in it.
+  // Hair keeps this loose: a spread of hair genuinely makes a head wider than it
+  // is tall, so only the absurd is rejected.
+  const headWidth = headMaxX - headMinX + 1;
+  if (chinY - crownY + 1 < headWidth * 0.5) return none;
+
+  const headCenterX = sumX / count;
+  return { chinY, headCenterX, headWidth, chestCenterX: chestCount ? chestSumX / chestCount : null, chestY: chestCount ? (chestTop + chestBottom) / 2 : null };
+}
+
+// Where the silhouette widens fastest, as an offset below the crown. Measured
+// over a window rather than row to row, so a ragged edge cannot win, and
+// searched between a twelfth and seven tenths of the way down: the chin is never
+// in the top of the hair, and anything past two thirds is chest.
+//
+// Returns -1 if there is nothing to measure.
+function steepestWidening(smooth, height) {
+  const span = Math.max(2, Math.round(height * 0.03));
+  const at = (i) => smooth[Math.min(height - 1, Math.max(0, i))];
+  let best = 0;
+  let bestAt = -1;
+  for (let i = Math.round(height * 0.08); i <= Math.round(height * 0.7); i++) {
+    const rise = at(i + span) - at(i - span);
+    if (rise > best) {
+      best = rise;
+      bestAt = i;
+    }
+  }
+  return bestAt;
+}
+
 async function restoreFaceWithOpenAI(base64Image, ctx = {}) {
   const { uid, account_profile_info, profile_picture } = ctx;
   const inputBuffer = Buffer.from(base64Image, 'base64');
@@ -16213,9 +17438,15 @@ export const inspect_profile_picture = async function (req, job_id, headers) {
   }
 };
 
-const get_image_blob_from_downloaded_image = async function (url) {
-  async function hasTransparentBackground(filePath) {
-    const image = sharp(filePath);
+// `max_dim`, when a caller asks for it, caps the longest side of the picture
+// this hands back. Nothing is lost by it as long as the caller renders smaller
+// than the cap; what is saved is real, because everything downstream (a
+// lossless PNG re-encode, an upload to an image model, a background removal, an
+// alpha scan) costs in proportion to the pixel count, and a phone camera hands
+// us sixteen times the pixels a 1024 avatar can use.
+const get_image_blob_from_downloaded_image = async function (url, { max_dim } = {}) {
+  async function hasTransparentBackground(input) {
+    const image = sharp(input);
     const metadata = await image.metadata();
 
     // If the image doesn't have an alpha channel at all → no transparency possible
@@ -16250,7 +17481,29 @@ const get_image_blob_from_downloaded_image = async function (url) {
     let buffer;
 
     let is_transparent = false;
-    if (ext === '.png') {
+    let oversized = false;
+    if (max_dim) {
+      try {
+        const meta = await sharp(filePath).metadata();
+        oversized = Math.max(meta.width || 0, meta.height || 0) > max_dim;
+      } catch (e) {
+        /* unreadable metadata: leave it to the paths below, which throw properly */
+      }
+    }
+
+    if (oversized) {
+      console.log(`Capping ${path.basename(filePath)} to ${max_dim}px...`);
+      // compressionLevel 6 rather than 9: this is a lossless format either way,
+      // so the top level only trades seconds of CPU for bytes on a file that
+      // never leaves this box.
+      buffer = await sharp(filePath)
+        .resize({ width: max_dim, height: max_dim, fit: 'inside', withoutEnlargement: true })
+        .png({ compressionLevel: 6, force: true })
+        .toBuffer();
+      // Measured on the capped copy, which is the one that goes on: sixteen
+      // times fewer pixels to walk for the same answer.
+      is_transparent = await hasTransparentBackground(buffer);
+    } else if (ext === '.png') {
       buffer = await fs.promises.readFile(filePath);
       is_transparent = await hasTransparentBackground(filePath);
     } else {