@xuda.io/ai_module 1.1.5655 → 1.1.5656

package/index.mjs

@@ -98,6 +98,71 @@ const run_process = function (command, args, input, options = {}) {
   });
 };
 
+// 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.
+//
+// `detached: true` alone is NOT enough, and this was measured rather than assumed: pm2 defaults to
+// treekill, which walks CHILDREN BY PPID and kills them regardless of process group, so a detached
+// child still died with its parent. `setsid` is what breaks the parentage: it forks, exits, and the
+// run is re-parented to init, where nothing walking a pm2 process tree can find it.
+//
+// Two details follow from going through setsid:
+//   • the prompt goes to a FILE and is redirected in, because there is no pipe left to write to
+//     once the intermediate has exited (and the file is useful on its own when reading back a run),
+//   • the run records its own pid, since setsid's pid is not the one we need to poll or kill. The
+//     script writes $$ and then EXECs, so that pid is the real process, and it is a session leader,
+//     which is what makes `kill(-pid)` reach the CLI shim plus the binary it spawns.
+// A box without setsid (never the fleet, which already relies on it elsewhere) falls back to a
+// plain detached child: no worse than the behaviour this replaces.
+const shell_quote = function (value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+};
+
+const spawn_detached_to_log = async function (command, args, input, options = {}) {
+  const { log_path, ...spawn_options } = options;
+  const dir = path.dirname(log_path);
+  await fs.promises.mkdir(dir, { recursive: true });
+  const prompt_path = path.join(dir, 'prompt.txt');
+  const pid_path = path.join(dir, 'pid');
+  await fs.promises.writeFile(prompt_path, input || '');
+
+  const has_setsid = (await run_process('bash', ['-lc', 'command -v setsid >/dev/null 2>&1 && echo yes || echo no'], null, { timeout: 10000 })).stdout.trim() === 'yes';
+
+  if (has_setsid) {
+    const cmdline = [command, ...args].map(shell_quote).join(' ');
+    const script = `echo $$ > ${shell_quote(pid_path)}; exec ${cmdline} < ${shell_quote(prompt_path)} >> ${shell_quote(log_path)} 2>&1`;
+    const child = spawn('setsid', ['bash', '-c', script], { detached: true, stdio: 'ignore', ...spawn_options });
+    child.unref();
+
+    // The pid file appears as soon as the grandchild starts, which is the only moment we can
+    // learn the pid we will be polling and killing for the rest of the run.
+    for (let attempt = 0; attempt < 50; attempt++) {
+      try {
+        const pid = Number((await fs.promises.readFile(pid_path, 'utf8')).trim());
+        if (pid > 0) return { pid, detach: 'setsid' };
+      } catch (err) {}
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    throw new Error('code run did not report a pid');
+  }
+
+  const fd = await fs.promises.open(log_path, 'a');
+  try {
+    const child = spawn(command, args, { detached: true, stdio: ['pipe', fd.fd, fd.fd], ...spawn_options });
+    return await new Promise((resolve, reject) => {
+      child.on('error', reject);
+      child.stdin.on('error', () => {});
+      if (input) child.stdin.write(input);
+      child.stdin.end();
+      child.unref();
+      setImmediate(() => resolve({ pid: child.pid, detach: 'spawn' }));
+    });
+  } finally {
+    await fd.close();
+  }
+};
+
 const normalize_boolean = function (value) {
   if (typeof value === 'string') {
     return ['true', '1', 'yes', 'on'].includes(value.toLowerCase());
@@ -303,7 +368,20 @@ const get_openai_codex_usage_model = function (codex_model, requested_codex_mode
 };
 
 const get_openai_codex_exec_args = function (codex_model, opts = {}) {
-  const args = ['exec', '--json'];
+  // UI-220. `exec resume` continues the Codex thread this chat already has instead of starting a
+  // cold one, so turn 2 knows what turn 1 did to the box. The session id comes off the
+  // `thread.started` event and is stored on the conversation; the caller only passes it when the
+  // session was recorded on THIS host, because Codex keeps its rollouts in local files under
+  // ~/.codex/sessions.
+  //
+  // Two differences from a cold `exec`, both enforced by the CLI (verified on 0.128.0):
+  //   • the signature is `exec resume [OPTIONS] <SESSION_ID> [PROMPT]`, so the id and the `-` are
+  //     POSITIONAL and the caller appends them after every option (see launch_code_run),
+  //   • `--sandbox <mode>` is not accepted at all ("unexpected argument '--sandbox' found"): a
+  //     resumed session keeps the sandbox it was created with. Only the bypass flag and
+  //     --skip-git-repo-check carry over.
+  const resuming = !!opts.resume_session_id;
+  const args = resuming ? ['exec', 'resume', '--json'] : ['exec', '--json'];
   // A per-call sandbox (e.g. the AI site generator passes 'workspace-write')
   // forces a confined run regardless of the global bypass default, so untrusted
   // end-user prompts can't run Codex with full host access. The studio/vibe flow
@@ -331,11 +409,15 @@ const get_openai_codex_exec_args = function (codex_model, opts = {}) {
 
   if (bypass_approvals_and_sandbox) {
     args.push('--dangerously-bypass-approvals-and-sandbox');
-  } else if (sandbox) {
+  } else if (sandbox && !resuming) {
     // --skip-git-repo-check: draft folders aren't git repos; without it codex
     // refuses to run sandboxed ("not inside a trusted directory"). The bypass
     // path skipped this implicitly.
     args.push('--sandbox', sandbox, '--skip-git-repo-check');
+  } else if (sandbox) {
+    // Resuming: the mode itself is fixed by the original session, but the repo check still has
+    // to be waived or a resumed run in a non-git directory refuses to start.
+    args.push('--skip-git-repo-check');
   }
 
   return args;
@@ -2055,120 +2137,1756 @@ export const execute_codex_request = async function (req_or_ip, prompt_arg, atta
 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.
 
-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}`
+      : `You are OpenAI Codex running on the local Xuda server.
+
+The target remote machine is ${get_codex_remote_host(ip)}.
+Execute shell commands on the remote machine through SSH, for example:
+ssh -o BatchMode=yes -o StrictHostKeyChecking=no ${get_codex_remote_host(ip)} "<command>"
+
+Do not assume the current local filesystem is the remote machine. Use SSH for inspection, edits, installs, and command execution unless the user explicitly asks for local work.
+For generated websites or other large file payloads, create the files first on the local Xuda server in a temporary working directory, validate them locally, then copy them to the remote machine with scp and use SSH only for remote placement, permissions, service reloads, and verification. Avoid embedding long HTML, CSS, JavaScript, JSON, or scripts inside nested ssh heredocs because shell quoting can corrupt the generated files.
+
+User request:
+${prompt}`;
+
+    if (local_attachments.length) {
+      codex_prompt += `\n\nAttachments available to Codex on the local Xuda server:\n${local_attachments.map((attachment_path) => `- ${attachment_path}`).join('\n')}`;
+    }
+
+    if (remote_attachments.length) {
+      codex_prompt += `\n\nAttachments available on the remote machine:\n${remote_attachments.map((attachment_path) => `- ${attachment_path}`).join('\n')}`;
+    }
+
+    const openai_codex_command = get_openai_codex_cli_command();
+    let codex_args = get_openai_codex_exec_args(codex_model, { sandbox, bypass_sandbox });
+    if (agent_mcp && agent_mcp.url) {
+      // Register the Xuda MCP server for this run. Global `-c` overrides must
+      // precede the `exec` subcommand (args[0]), so prepend them. The bearer
+      // travels by env var name (resolved from the run env below), not value.
+      codex_args = ['-c', `mcp_servers.xuda.url="${agent_mcp.url}"`, '-c', `mcp_servers.xuda.bearer_token_env_var="${agent_mcp.bearer_env_var || 'XUDA_AGENT_KEY'}"`, ...codex_args];
+    }
+    for (const image_path of image_paths) {
+      codex_args.push('--image', image_path);
+    }
+    codex_args.push('-');
+
+    const ret = await run_process(openai_codex_command, codex_args, codex_prompt, {
+      env: {
+        ...process.env,
+        OPENAI_API_KEY: _conf.OPENAI_API_KEY,
+        ...(agent_mcp && agent_mcp.bearer_value ? { [agent_mcp.bearer_env_var || 'XUDA_AGENT_KEY']: agent_mcp.bearer_value } : {}),
+      },
+      ...(local_cwd ? { cwd: local_cwd } : {}),
+      ...(codex_timeout ? { timeout: codex_timeout, killSignal: 'SIGKILL' } : {}),
+      onStdout: create_codex_jsonl_stream_parser(handleCodexEvent),
+    });
+    const events = parse_codex_jsonl(ret.stdout);
+    if (!codex_usage.input_tokens && !codex_usage.output_tokens && Array.isArray(events)) {
+      const completed_event_with_usage = events.findLast((event) => event?.type === 'turn.completed' && event.usage);
+      codex_usage = normalize_codex_usage(completed_event_with_usage?.usage);
+    }
+
+    if (uid && account_profile_info && (codex_usage.input_tokens || codex_usage.output_tokens)) {
+      account_msa.record_ai_usage(
+        uid,
+        codex_usage.input_tokens,
+        codex_usage.output_tokens,
+        'execute codex request',
+        prompt,
+        get_openai_codex_usage_model(codex_model, requested_codex_model),
+        {
+          conversation_id,
+          job_id,
+          remote_host: local_cwd ? null : get_codex_remote_host(ip),
+          exit_code: ret.exit_code,
+          attachments_count: attachments.length,
+        },
+        account_profile_info,
+      );
+    }
+
+    if (ret.exit_code !== 0) {
+      emitToDashboard('stream_phase', 'Codex request failed', { update: true });
+      streamText(`Codex request failed: ${ret.stderr || ret.stdout || `exit code ${ret.exit_code}`}`);
+      emitToDashboard('stream_end');
+
+      return {
+        code: -3,
+        data: {
+          provider: 'openai_codex_cli',
+          remote_host: local_cwd ? null : get_codex_remote_host(ip),
+          command: `${openai_codex_command} ${codex_args.filter((arg) => arg !== '-').join(' ')}`,
+          exit_code: ret.exit_code,
+          stdout: ret.stdout,
+          stderr: ret.stderr,
+          events,
+          reasoning,
+          usage: codex_usage,
+        },
+      };
+    }
+
+    emitToDashboard('stream_end');
+
+    return {
+      code: 0,
+      data: {
+        provider: 'openai_codex_cli',
+        remote_host: local_cwd ? null : get_codex_remote_host(ip),
+        command: `${openai_codex_command} ${codex_args.filter((arg) => arg !== '-').join(' ')}`,
+        stdout: ret.stdout,
+        stderr: ret.stderr,
+        events,
+        reasoning,
+        usage: codex_usage,
+      },
+    };
+  } catch (err) {
+    console.error(err);
+    emitToDashboard('stream_phase', 'Codex request failed', { update: true });
+    streamText(`Codex request failed: ${err.message}`);
+    emitToDashboard('stream_end');
+    return { code: -1, data: err.message };
+  }
+};
+
+// ══════════════════════════════════════════════════════════════════════════════════════════
+// Durable code runs (UI-220)
+//
+// A code chat turn (vibe on a VPS, an AI edit of a static site) is a Codex CLI run that takes
+// minutes. It used to be awaited inline inside the chat job, as a child of the `ai` process,
+// with `stream: false`. That made three failures routine:
+//   • a pm2 restart killed the run and left no record of what it had already done to the box
+//     (on dev that is EVERY deploy, since pm2 watches cpi/ai_module),
+//   • a run outliving its 10 minute job finished into a job that no longer existed,
+//   • the browser was sent nothing at all while it worked, which is what made code chats feel
+//     broken even on the runs that succeeded.
+//
+// A run is now its own object with four parts:
+//   • a DETACHED process, so it outlives whatever started it,
+//   • a JSONL log FILE it appends to, which is the transcript of record,
+//   • a `code_run` doc in the account's project db (state, commands, touched files, usage),
+//   • a `meta.json` beside the log, so a restarted box can find its own runs again without
+//     depending on memcached or on scanning every account database.
+//
+// The socket is a live VIEW of the log rather than the only copy of it, so anything the browser
+// misses stays readable from the doc afterwards, which is exactly what the chat's own recovery
+// probe (UI-219) asks the server for.
+// ══════════════════════════════════════════════════════════════════════════════════════════
+
+const CODE_RUN_MAX_CONCURRENT = _conf.code_runs?.max_concurrent || 3;
+const CODE_RUN_TIMEOUT_MS = _conf.code_runs?.timeout_ms || 20 * 60 * 1000;
+const CODE_RUN_RETENTION_MS = _conf.code_runs?.retention_ms || 7 * 24 * 60 * 60 * 1000;
+// How often the log is read, and how often what was read is flushed to the doc. The tail is a
+// poll rather than an fs.watch because the writer is another process (and on a restart, one this
+// process never spawned), and a poll is also how process liveness is checked.
+const CODE_RUN_TAIL_MS = 700;
+const CODE_RUN_FLUSH_MS = 2500;
+// Read at most this much log per tick, so a run that dumped a huge command output cannot pull
+// megabytes into memory in one go.
+const CODE_RUN_READ_CHUNK = 512 * 1024;
+// Directories a code run is allowed to watch for file changes, per app type. Deliberately
+// bounded and declared: snapshotting a whole box is not affordable, and a file panel that
+// claims to be complete has to say what it looked at.
+const CODE_RUN_DEFAULT_WATCH_PATHS = ['/var/www', '/etc/nginx', '/etc/apache2', '/opt/app'];
+const CODE_RUN_WATCH_IGNORE = ['node_modules', '.git', '.xuda_code.git', 'vendor', '*.log', 'tmp', '.cache'];
+// Ceiling for the no-git fallback, which has to make a real copy. Past this the root is reported
+// as skipped rather than quietly copied on the customer's disk.
+const CODE_RUN_COPY_MAX_BYTES = _conf.code_runs?.copy_max_bytes || 200 * 1024 * 1024;
+
+const code_run_host = function () {
+  return process.env.XUDA_HOSTNAME || _conf.domain || 'unknown';
+};
+
+const code_run_root_dir = function () {
+  return path.join(process.env.XUDA_HOME, 'code_runs');
+};
+
+const code_run_dir = function (run_id) {
+  return path.join(code_run_root_dir(), run_id);
+};
+
+const code_run_log_path = function (run_id) {
+  return path.join(code_run_dir(run_id), 'codex.jsonl');
+};
+
+const code_run_meta_path = function (run_id) {
+  return path.join(code_run_dir(run_id), 'meta.json');
+};
+
+const code_run_backup_dir = function (run_id) {
+  return path.join(code_run_dir(run_id), 'before');
+};
+
+// Every shell command a run needs (snapshots, diffs, reverts) is either local or on the
+// customer's box, and the difference is only this wrapper. Same ssh options Codex itself is told
+// to use, so a box reachable by the agent is reachable here.
+const CODE_RUN_SSH_OPTS = '-o BatchMode=yes -o StrictHostKeyChecking=no -o ConnectTimeout=10';
+const code_run_exec = async function (run, command, timeout_ms = 60000) {
+  const full = run.remote_host ? `ssh ${CODE_RUN_SSH_OPTS} ${run.remote_host} ${JSON.stringify(command)}` : command;
+  return await run_process('bash', ['-lc', full], null, { timeout: timeout_ms, killSignal: 'SIGKILL' });
+};
+
+// ── Run doc I/O ────────────────────────────────────────────────────────────────────────────
+// The in-memory run object carries its own _rev so the tail can write often without re-reading.
+// save_app_couch_doc already retries a 409 by re-reading and merging, so a concurrent writer
+// (an abort, the controller sweep) costs a retry rather than a lost update.
+// Underscore keys are this process's working state (the accumulated stream text, the set of
+// agent messages already sent, the pending spawn arguments, the conversation doc). None of it
+// belongs in the doc: a Set does not survive JSON, and the prompt and conversation would bloat
+// every write. _id and _rev are the two that do.
+const CODE_RUN_TRANSIENT_KEY = /^_(?!id$|rev$)/;
+const persist_code_run = async function (run) {
+  const payload = {};
+  for (const [key, value] of Object.entries(run)) {
+    if (!CODE_RUN_TRANSIENT_KEY.test(key)) payload[key] = value;
+  }
+  payload._id = run._id;
+  if (run._rev) payload._rev = run._rev;
+  try {
+    const ret = await db_module.save_app_couch_doc_native(run.app_id, payload);
+    if (ret?.rev) run._rev = ret.rev;
+    return true;
+  } catch (err) {
+    console.error(`[code_run] persist ${run._id} failed: ${err?.message || err}`);
+    return false;
+  }
+};
+
+const load_code_run = async function (app_id, run_id) {
+  try {
+    const doc = await db_module.get_app_couch_doc_native(app_id, run_id);
+    return doc && doc.docType === 'code_run' ? doc : null;
+  } catch (err) {
+    return null;
+  }
+};
+
+// ── File-state capture ─────────────────────────────────────────────────────────────────────
+// Before the run writes anything, record what the watched directories look like. Two mechanisms,
+// both chosen so they work on a box nobody prepared for us:
+//   • git, when it is installed: a SHADOW repo (its own git dir, the real tree as work tree) so
+//     the customer's own git history, if any, is untouched. Gives paths, diffs and revert, and
+//     honours the ignore list natively, which is why it is preferred.
+//   • otherwise `cp -a --reflink=auto`: a real copy, cheap where the filesystem can share blocks
+//     (copy-on-write) and a plain copy everywhere else. It is NOT `cp -al`: a hardlinked snapshot
+//     looks free but is wrong here, because a shell redirect (`> file`, `tee`, `sed -i` without a
+//     temp file) writes the SAME inode, so the "backup" changes with the original and the edit
+//     becomes invisible. Verified: a hardlink snapshot reported an edited file as unchanged.
+// Both are bounded to the declared watch paths, and the copy path is additionally bounded by
+// size: past the cap the root is recorded as skipped WITH the reason, because a file panel that
+// cannot see a directory has to say so rather than imply the run touched nothing there.
+// A run that cannot snapshot at all still runs; it just reports no file list.
+const code_run_watch_paths = function (app_obj, local_cwd) {
+  if (local_cwd) return [local_cwd];
+  const per_type = _conf.code_runs?.watch_paths?.[app_obj?.app_type];
+  const configured = per_type || _conf.code_runs?.watch_paths?.default || CODE_RUN_DEFAULT_WATCH_PATHS;
+  return Array.isArray(configured) ? configured : [];
+};
+
+const code_run_shadow_git = function (root) {
+  return `git --git-dir=${JSON.stringify(`${root}/.xuda_code.git`)} --work-tree=${JSON.stringify(root)}`;
+};
+
+const code_run_capture_before = async function (run) {
+  const roots = [];
+  // UI-226: a repo-backed run needs no snapshot at all. Its working copy IS a repository, so the
+  // before state is just HEAD, and the files it already had dirty are recorded so a change somebody
+  // made by hand is never attributed to the run. The shadow-repo and copy paths below stay exactly as
+  // they were for everything else, which is what keeps the VPS behaviour unchanged.
+  if (run.repo_id && run.base_sha) {
+    run.snapshot = { roots: [{ root: run.local_cwd, kind: 'repo', ref: run.base_sha, pre_dirty: run.pre_dirty || [] }], taken_ts: Date.now(), watched: [run.local_cwd] };
+    return run.snapshot;
+  }
+  try {
+    const has_git = (await code_run_exec(run, 'command -v git >/dev/null 2>&1 && echo yes || echo no', 20000)).stdout.trim() === 'yes';
+    for (const root of run.watch_paths || []) {
+      const exists = (await code_run_exec(run, `test -d ${JSON.stringify(root)} && echo yes || echo no`, 20000)).stdout.trim() === 'yes';
+      if (!exists) continue;
+
+      if (has_git) {
+        const git = code_run_shadow_git(root);
+        const exclude = CODE_RUN_WATCH_IGNORE.join('\\n');
+        const init = `${git} rev-parse --git-dir >/dev/null 2>&1 || (${git} init -q && printf '${exclude}\\n' > ${JSON.stringify(`${root}/.xuda_code.git/info/exclude`)})`;
+        // -c user.* so a box with no git identity still commits. --allow-empty because an
+        // unchanged tree between two runs is normal and must not fail the snapshot.
+        const commit = `${git} add -A >/dev/null 2>&1; ${git} -c user.email=code-run@xuda -c user.name=xuda commit -q --allow-empty -m ${JSON.stringify(`before ${run._id}`)} >/dev/null 2>&1; ${git} rev-parse HEAD`;
+        const ret = await code_run_exec(run, `${init} && ${commit}`, 120000);
+        const sha = (ret.stdout || '').trim().split(/\s+/).pop();
+        if (ret.exit_code === 0 && /^[0-9a-f]{7,40}$/.test(sha || '')) {
+          roots.push({ root, kind: 'git', ref: sha });
+          continue;
+        }
+      }
+
+      // Size guard first: a copy of a docroot with a bundled node_modules is not something to
+      // start behind the user's back on their own disk.
+      const size_kb = Number(((await code_run_exec(run, `du -sk ${JSON.stringify(root)} 2>/dev/null | cut -f1`, 60000)).stdout || '').trim()) || 0;
+      if (size_kb * 1024 > CODE_RUN_COPY_MAX_BYTES) {
+        roots.push({ root, kind: 'skipped', reason: 'too_large', size_kb });
+        continue;
+      }
+
+      // --reflink=auto is GNU coreutils and makes this nearly free on a copy-on-write filesystem,
+      // but it is not portable (BSD cp and busybox both reject the flag), so a plain -a is the
+      // second try rather than the only one. The rm between them keeps a half-written first
+      // attempt from being mistaken for the before state.
+      const backup = path.join(code_run_backup_dir(run._id), root.replace(/[^a-zA-Z0-9]+/g, '_'));
+      const copy = `cp -a --reflink=auto ${JSON.stringify(root)} ${JSON.stringify(backup)} 2>/dev/null || (rm -rf ${JSON.stringify(backup)} && cp -a ${JSON.stringify(root)} ${JSON.stringify(backup)})`;
+      const ret = await code_run_exec(run, `mkdir -p ${JSON.stringify(path.dirname(backup))} && rm -rf ${JSON.stringify(backup)} && (${copy})`, 300000);
+      if (ret.exit_code === 0) roots.push({ root, kind: 'copy', ref: backup });
+      else roots.push({ root, kind: 'skipped', reason: 'copy_failed' });
+    }
+  } catch (err) {
+    console.error(`[code_run] snapshot ${run._id} failed: ${err?.message || err}`);
+  }
+  run.snapshot = { roots, taken_ts: Date.now(), watched: run.watch_paths || [] };
+  return run.snapshot;
+};
+
+const CODE_RUN_MAX_FILES = 400;
+const code_run_capture_after = async function (run) {
+  const files = [];
+  for (const entry of run.snapshot?.roots || []) {
+    try {
+      if (entry.kind === 'skipped') continue;
+
+      // UI-226, the repository case: what the run changed is what `git status` says, minus whatever
+      // was already dirty when it started. Nothing is committed here, which is the point: the user
+      // reviews the change set and commits it themselves, the way Claude Code works.
+      if (entry.kind === 'repo') {
+        const token = run._repo_token || null;
+        const status = await git_exec({ cwd: entry.root, args: ['status', '--porcelain', '--untracked-files=all'], token });
+        const pre = new Set(entry.pre_dirty || []);
+        for (const line of (status.stdout || '').split('\n')) {
+          const parsed = git_parse_status_line(line);
+          if (!parsed) continue;
+          const { code, rel } = parsed;
+          if (pre.has(rel)) continue;
+          const change = code.includes('D') ? 'delete' : code.includes('?') || code.includes('A') ? 'add' : 'edit';
+          files.push({
+            path: path.join(entry.root, rel),
+            change,
+            root: entry.root,
+            rel,
+            snapshot_kind: 'repo',
+            before_ref: entry.ref,
+            diff_available: true,
+            revert_available: true,
+          });
+        }
+        continue;
+      }
+
+      if (entry.kind === 'git') {
+        const git = code_run_shadow_git(entry.root);
+        const commit = `${git} add -A >/dev/null 2>&1; ${git} -c user.email=code-run@xuda -c user.name=xuda commit -q --allow-empty -m ${JSON.stringify(`after ${run._id}`)} >/dev/null 2>&1; ${git} rev-parse HEAD`;
+        const after = ((await code_run_exec(run, commit, 120000)).stdout || '').trim().split(/\s+/).pop();
+        const ret = await code_run_exec(run, `${git} diff --name-status ${entry.ref} ${after}`, 60000);
+        for (const line of (ret.stdout || '').split('\n')) {
+          const [status, rel] = line.trim().split(/\s+/);
+          if (!status || !rel) continue;
+          files.push({
+            path: `${entry.root}/${rel}`.replace(/\/+/g, '/'),
+            change: status.startsWith('A') ? 'add' : status.startsWith('D') ? 'delete' : 'edit',
+            root: entry.root,
+            rel,
+            snapshot_kind: 'git',
+            before_ref: entry.ref,
+            after_ref: after,
+            diff_available: true,
+            revert_available: true,
+          });
+        }
+        entry.after_ref = after;
+      } else {
+        // diff -qr names what changed on both sides; "Only in <dir>" covers adds and deletes.
+        const ret = await code_run_exec(run, `diff -qr ${JSON.stringify(entry.ref)} ${JSON.stringify(entry.root)} 2>/dev/null | head -${CODE_RUN_MAX_FILES}`, 120000);
+        for (const line of (ret.stdout || '').split('\n')) {
+          const differ = line.match(/^Files (.+) and (.+) differ$/);
+          const only = line.match(/^Only in (.+): (.+)$/);
+          if (differ) {
+            const abs = differ[2];
+            files.push({ path: abs, change: 'edit', root: entry.root, rel: path.relative(entry.root, abs), snapshot_kind: 'copy', before_ref: entry.ref, diff_available: true, revert_available: true });
+          } else if (only) {
+            const abs = path.join(only[1], only[2]);
+            const in_backup = only[1].startsWith(entry.ref);
+            files.push({
+              path: in_backup ? path.join(entry.root, path.relative(entry.ref, abs)) : abs,
+              change: in_backup ? 'delete' : 'add',
+              root: entry.root,
+              rel: path.relative(in_backup ? entry.ref : entry.root, abs),
+              snapshot_kind: 'copy',
+              before_ref: entry.ref,
+              diff_available: !in_backup,
+              revert_available: true,
+            });
+          }
+        }
+      }
+    } catch (err) {
+      console.error(`[code_run] file diff ${run._id} ${entry.root} failed: ${err?.message || err}`);
+    }
+  }
+  run.files = files.slice(0, CODE_RUN_MAX_FILES);
+  run.files_truncated = files.length > CODE_RUN_MAX_FILES;
+  return run.files;
+};
+
+// ── Live view of a run ─────────────────────────────────────────────────────────────────────
+// Same events, same field names as the inline path, so the browser needs no new protocol: this
+// is a second producer of the stream AiChat.vue already renders.
+const code_run_emitter = function (run) {
+  return function (type, content, params) {
+    const is_stream_delta = type === 'stream_delta';
+    const is_stream_end = type === 'stream_end';
+    const seq = is_stream_delta ? ++run._delta_seq : undefined;
+    if (is_stream_delta) run._delta_text += content || '';
+
+    ws_dashboard_msa.emit_message_to_dashboard({
+      service: type,
+      to: run.uid,
+      data: {
+        conversation_id: run.conversation_id,
+        job_id: run.job_id,
+        code_run_id: run._id,
+        delta: content,
+        ...(type === 'stream_start' ? { request_started_at: run.started_ts } : {}),
+        ...(seq ? { seq } : {}),
+        ...(is_stream_end
+          ? {
+              stream_id: run.response_conversation_item_id,
+              final_seq: run._delta_seq,
+              text: typeof params?.text === 'string' ? params.text : run._delta_text,
+            }
+          : {}),
+        prompt_conversation_item_id: run.prompt_conversation_item_id,
+        response_conversation_item_id: run.response_conversation_item_id,
+        params,
+      },
+    });
+
+    if (is_stream_end) {
+      notify_chat_finished({
+        uid: run.uid,
+        conversation_id: run.conversation_id,
+        conversation_doc: run._conversation_doc,
+        text: typeof params?.text === 'string' ? params.text : run._delta_text,
+        failed: !!(params?.error || params?.aborted),
+      });
+    }
+  };
+};
+
+// Codex JSONL → what the user sees and what the run remembers. The inline path has its own copy
+// of this mapping (handleCodexEvent inside execute_codex_request) which stays for the blocking
+// callers (generate_site_draft); this one is the durable version and additionally records the
+// session id, the commands and the agent's own words onto the run doc.
+const handle_code_run_event = function (run, emit, event) {
+  if (!event || typeof event !== 'object') return;
+
+  switch (event.type) {
+    case 'thread.started':
+      // The thread id is what makes the NEXT turn a continuation instead of a cold start.
+      if (event.thread_id && !run.codex_session_id) run.codex_session_id = event.thread_id;
+      emit('stream_phase', 'Starting Codex thread', { update: true, thread_id: event.thread_id });
+      break;
+    case 'turn.started':
+      emit('stream_phase', 'Working through the request', { update: true });
+      break;
+    case 'item.started': {
+      const item = event.item || {};
+      if (item.type === 'command_execution') {
+        emit('stream_phase', 'Running command', { update: true, command: item.command || '' });
+      }
+      break;
+    }
+    case 'item.completed': {
+      const item = event.item || {};
+      if (item.type === 'agent_message' && item.text) {
+        // Streamed as it happens, which is the difference between watching a build and watching
+        // a spinner. The persisted answer is this same accumulated text, so the client's
+        // reconciliation (UI-219) can never disagree with what it displayed.
+        if (!run._seen_messages.has(item.id)) {
+          run._seen_messages.add(item.id);
+          if (!run._response_started) {
+            run._response_started = true;
+            emit('response_start');
+          }
+          const text = `${item.text.trim()}\n\n`;
+          for (let i = 0; i < text.length; i += 280) emit('stream_delta', text.slice(i, i + 280));
+        }
+      }
+      if (item.type === 'command_execution') {
+        const output = (item.aggregated_output || '').trim();
+        run.commands.push({
+          command: item.command || '',
+          exit_code: item.exit_code,
+          status: item.status,
+          ts: Date.now(),
+          output: output.length > 2000 ? `${output.slice(0, 2000)}...` : output,
+        });
+        if (run.commands.length > 200) run.commands.splice(0, run.commands.length - 200);
+        emit('stream_phase', item.exit_code === 0 ? 'Command finished' : 'Command failed', { update: true, command: item.command || '', exit_code: item.exit_code });
+      }
+      break;
+    }
+    case 'error':
+      run.error = event.message || 'codex error';
+      emit('stream_phase', 'Something went wrong', { update: true, error: true });
+      break;
+    case 'turn.completed':
+      run.usage = normalize_codex_usage(event.usage);
+      break;
+    case 'turn.failed':
+      run.error = event.error?.message || 'codex turn failed';
+      break;
+    default:
+      break;
+  }
+};
+
+// ── The tail ───────────────────────────────────────────────────────────────────────────────
+const _code_run_tails = new Map(); // run_id -> stop()
+
+const code_run_process_alive = function (pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+};
+
+const kill_code_run_process = function (pid) {
+  if (!pid) return;
+  try {
+    // Negative pid: the whole group, because the Codex CLI is a shim that spawns the real binary
+    // (the same reason run_process kills by group).
+    process.kill(-pid, 'SIGKILL');
+  } catch (err) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch (e) {}
+  }
+};
+
+const attach_code_run = function (run) {
+  if (_code_run_tails.has(run._id)) return;
+
+  run._delta_seq = run._delta_seq || 0;
+  run._delta_text = run._delta_text || '';
+  run._seen_messages = run._seen_messages || new Set();
+  run._response_started = !!run._response_started;
+  run.commands = Array.isArray(run.commands) ? run.commands : [];
+
+  const emit = code_run_emitter(run);
+  const parser = create_codex_jsonl_stream_parser((event) => {
+    try {
+      handle_code_run_event(run, emit, event);
+    } catch (err) {
+      console.error(`[code_run] event handling ${run._id}: ${err?.message || err}`);
+    }
+  });
+
+  let offset = run.log_offset || 0;
+  let last_flush = 0;
+  let last_abort_check = 0;
+  let last_heartbeat = Date.now();
+  let ticking = false;
+  let dead_ticks = 0;
+  let finished = false;
+
+  const stop = () => {
+    clearInterval(timer);
+    _code_run_tails.delete(run._id);
+  };
+
+  const tick = async () => {
+    if (ticking || finished) return;
+    ticking = true;
+    try {
+      // 1. drain whatever the run has written since last time
+      let size = 0;
+      try {
+        size = (await fs.promises.stat(run.log_path)).size;
+      } catch (err) {
+        size = offset;
+      }
+      if (size > offset) {
+        const length = Math.min(size - offset, CODE_RUN_READ_CHUNK);
+        const fh = await fs.promises.open(run.log_path, 'r');
+        try {
+          const buf = Buffer.alloc(length);
+          await fh.read(buf, 0, length, offset);
+          offset += length;
+          run.log_offset = offset;
+          parser(buf.toString('utf8'));
+        } finally {
+          await fh.close();
+        }
+      }
+
+      // 2. the user pressed Stop. The job doc carries the flag; the run owns the process. Checked
+      //    on a slower beat than the log read, since it is a cache round trip per check.
+      if (run.job_id && Date.now() - last_abort_check > 2000) {
+        last_abort_check = Date.now();
+        if (await is_job_aborted(run.job_id)) {
+          kill_code_run_process(run.pid);
+          finished = true;
+          stop();
+          await finalize_code_run(run, { aborted: true });
+          return;
+        }
+      }
+
+      // 2b. keep the job alive. A job doc lives in memcached with a 600s TTL refreshed on every
+      //     write, and a background run writes nothing to it for the length of the run. Once it
+      //     expires, Stop answers "already finished" and the browser gives up on a run that is
+      //     still working (the same reconciliation UI-219 added, firing on a false signal).
+      if (run.job_id && Date.now() - last_heartbeat > 60000) {
+        last_heartbeat = Date.now();
+        const last_command = run.commands.length ? run.commands[run.commands.length - 1].command : '';
+        try {
+          await jobs_ms.update_job({ job_id: run.job_id, is_background: true, current_step_name: last_command ? `running: ${String(last_command).slice(0, 80)}` : 'streaming results' });
+        } catch (err) {}
+      }
+
+      // 3. a run past its wall clock is killed by process group, so nothing is left holding an
+      //    OpenAI socket or an SSH session on the customer's box.
+      if (Date.now() - (run.started_ts || 0) > (run.timeout_ms || CODE_RUN_TIMEOUT_MS)) {
+        kill_code_run_process(run.pid);
+        finished = true;
+        stop();
+        await finalize_code_run(run, { timed_out: true });
+        return;
+      }
+
+      // 4. process gone and log fully drained → finish. Two quiet ticks, because the process can
+      //    exit a beat before its last line is flushed to the file.
+      if (!code_run_process_alive(run.pid) && offset >= size) {
+        dead_ticks += 1;
+        if (dead_ticks >= 2) {
+          finished = true;
+          stop();
+          await finalize_code_run(run, {});
+          return;
+        }
+      } else {
+        dead_ticks = 0;
+      }
+
+      if (Date.now() - last_flush > CODE_RUN_FLUSH_MS) {
+        last_flush = Date.now();
+        await persist_code_run(run);
+      }
+    } catch (err) {
+      console.error(`[code_run] tail ${run._id}: ${err?.message || err}`);
+    } finally {
+      ticking = false;
+    }
+  };
+
+  const timer = setInterval(tick, CODE_RUN_TAIL_MS);
+  _code_run_tails.set(run._id, stop);
+  tick();
+};
+
+// ── Finishing a run ────────────────────────────────────────────────────────────────────────
+// Everything the inline vibe branch used to do after its await: work out the answer, pull the
+// clarifying questions off it, record usage, close the conversation and the job, and tell the
+// browser. It lives here because a run can finish while nobody is on the other end of the
+// socket, or in a process that did not start it.
+const finalize_code_run = async function (run, { aborted = false, timed_out = false } = {}) {
+  if (run._finalized) return;
+  run._finalized = true;
+
+  const emit = code_run_emitter(run);
+  try {
+    // Anything still unread in the log belongs to this answer.
+    try {
+      const size = (await fs.promises.stat(run.log_path)).size;
+      if (size > (run.log_offset || 0)) {
+        const fh = await fs.promises.open(run.log_path, 'r');
+        try {
+          const length = size - run.log_offset;
+          const buf = Buffer.alloc(length);
+          await fh.read(buf, 0, length, run.log_offset);
+          run.log_offset = size;
+          const parser = create_codex_jsonl_stream_parser((event) => handle_code_run_event(run, emit, event));
+          parser(buf.toString('utf8'));
+        } finally {
+          await fh.close();
+        }
+      }
+    } catch (err) {}
+
+    const failed = !!run.error || (!run._delta_text && !aborted);
+    const raw_text = aborted
+      ? run._delta_text || 'Stopped.'
+      : timed_out
+        ? `${run._delta_text || ''}\n\nThis run was stopped because it went past its time limit.`.trim()
+        : run._delta_text || "I couldn't finish that request just now. Please try again in a moment.";
+
+    const { prose, questions } = extract_xuda_questions(raw_text);
+    const response_text = prose || raw_text;
+
+    // Which files it touched. After the answer text is settled, because a snapshot diff on a
+    // slow box must never be what decides whether the user gets their answer.
+    if (!aborted) await code_run_capture_after(run);
+
+    if (run.usage && (run.usage.input_tokens || run.usage.output_tokens)) {
+      try {
+        const account_profile_info = await get_active_account_profile_info(run.uid, run.profile_id);
+        account_msa.record_ai_usage(run.uid, run.usage.input_tokens, run.usage.output_tokens, 'code run', run.prompt_preview || '', run.usage_model || 'openai_codex_cli', { conversation_id: run.conversation_id, job_id: run.job_id, code_run_id: run._id, remote_host: run.remote_host || null }, account_profile_info);
+      } catch (err) {
+        console.error(`[code_run] usage ${run._id}: ${err?.message || err}`);
+      }
+    }
+
+    // The assistant's message, same shape the inline path saved.
+    try {
+      await db_module.save_app_couch_doc_native(run.app_id, {
+        _id: run.response_conversation_item_id,
+        stat: 3,
+        docType: 'chat_conversation_item',
+        uid: run.uid,
+        conversation_type: 'dashboard',
+        type: 'dashboard',
+        date_created_ts: Date.now(),
+        ts: Date.now(),
+        conversation_id: run.conversation_id,
+        text: response_text,
+        reference_id: run.reference_id,
+        direction: 'in',
+        role: 'assistant',
+        read: { [run.uid]: Date.now() },
+        rtl: _common.detectRTL(response_text),
+        job_id: run.job_id,
+        target_app_id: run.target_app_id,
+        prompt_conversation_item_id: run.prompt_conversation_item_id,
+        code_run_id: run._id,
+        ...(questions ? { questions } : {}),
+        ...(failed || timed_out ? { is_request_error: true } : {}),
+      });
+    } catch (err) {
+      console.error(`[code_run] save item ${run._id}: ${err?.message || err}`);
+    }
+
+    // The conversation carries the Codex thread, so the next turn resumes instead of restarting.
+    try {
+      const conversation_doc = await db_module.get_app_couch_doc_native(run.app_id, run.conversation_id);
+      conversation_doc.ts = Date.now();
+      conversation_doc.stat = 3;
+      conversation_doc.process_stat = failed || timed_out ? 'partial' : 'full';
+      conversation_doc.conversation_item_id = run.response_conversation_item_id;
+      if (run.codex_session_id) {
+        conversation_doc.codex_session_id = run.codex_session_id;
+        conversation_doc.codex_session_host = run.host;
+      }
+      await db_module.save_app_couch_doc_native(run.app_id, conversation_doc);
+      run._conversation_doc = conversation_doc;
+    } catch (err) {
+      console.error(`[code_run] conversation ${run._id}: ${err?.message || err}`);
+    }
+
+    // The scoped pass this run held over MCP dies with the run, whatever the outcome.
+    if (run.revoke_api_key) {
+      try {
+        await db_module.delete_couch_doc('xuda_api_keys', run.revoke_api_key);
+      } catch (err) {}
+      run.revoke_api_key = null;
+    }
+
+    run.state = aborted ? 'aborted' : timed_out ? 'failed' : failed ? 'failed' : 'done';
+    run.ended_ts = Date.now();
+    if (timed_out && !run.error) run.error = 'timeout';
+    await persist_code_run(run);
+
+    if (!run._response_started) emit('response_start');
+    emit('stream_end', undefined, {
+      text: response_text,
+      ...(questions ? { questions } : {}),
+      ...(aborted ? { aborted: true } : {}),
+      ...(failed || timed_out ? { error: true } : {}),
+      code_run_id: run._id,
+      files: (run.files || []).map((f) => ({ path: f.path, change: f.change })),
+    });
+
+    // The chat job was left open on purpose (a code run is longer than any job timeout), so it
+    // is closed here rather than by whoever started it.
+    if (run.job_id) {
+      try {
+        await jobs_ms.update_job({ job_id: run.job_id, response: { code: failed || timed_out ? -1 : 1, data: failed || timed_out ? run.error || 'code run failed' : 'ok' } });
+      } catch (err) {}
+    }
+
+    // Let the next queued run in.
+    start_queued_code_runs().catch(() => {});
+  } catch (err) {
+    console.error(`[code_run] finalize ${run._id}: ${err?.message || err}`);
+  }
+};
+
+// ── Starting a run ─────────────────────────────────────────────────────────────────────────
+// Returns as soon as the process is up (or queued), which is what takes the run off the chat
+// job's clock. `req`-shaped input, same fields execute_codex_request takes, so the two paths stay
+// recognisably the same thing.
+//
+// Exported because a run is startable from more than the chat turn that first needed it (a
+// re-run from the code workspace, and the broker probes the verification leans on).
+export const start_code_run = async function (opts) {
+  const {
+    uid,
+    profile_id,
+    app_id,
+    target_app_id,
+    conversation_id,
+    conversation_doc,
+    reference_id,
+    job_id,
+    prompt,
+    prompt_conversation_item_id,
+    response_conversation_item_id,
+    ip,
+    local_cwd,
+    app_obj,
+    codex_model,
+    attachments = [],
+    agent_mcp,
+    bypass_sandbox = false,
+    sandbox,
+    timeout_ms,
+    revoke_api_key,
+  } = opts;
+
+  const run_id = await _common.xuda_get_uuid('code_run');
+  const run = {
+    _id: run_id,
+    docType: 'code_run',
+    stat: 3,
+    engine: local_cwd ? 'codex_local' : 'codex_remote',
+    state: 'queued',
+    uid,
+    profile_id,
+    app_id,
+    target_app_id,
+    conversation_id,
+    reference_id,
+    job_id,
+    prompt_conversation_item_id,
+    response_conversation_item_id,
+    host: code_run_host(),
+    remote_host: local_cwd ? null : get_codex_remote_host(ip),
+    local_cwd: local_cwd || null,
+    log_path: code_run_log_path(run_id),
+    log_offset: 0,
+    // Config decides which directories a run watches, per app type. An explicit list overrides it
+    // for the cases that know better than the catalog: a full stack VPS that declares its own
+    // layout, and a probe that must not snapshot anything but its own scratch directory.
+    watch_paths: Array.isArray(opts.watch_paths) ? opts.watch_paths : code_run_watch_paths(app_obj, local_cwd),
+    codex_session_id: null,
+    resumed_session_id: opts.resume_session_id || null,
+    usage_model: codex_model || null,
+    // An ephemeral scoped MCP key the run is still using. It used to be revoked the moment the
+    // codex call returned, which is now the moment the run STARTS, so the run revokes it instead.
+    revoke_api_key: revoke_api_key || null,
+    prompt_preview: (prompt || '').slice(0, 500),
+    timeout_ms: timeout_ms || CODE_RUN_TIMEOUT_MS,
+    emit_stream_start: opts.emit_stream_start === true,
+    // UI-226: set only for a repository-backed run. Their presence is what switches the file capture
+    // from a snapshot to the repository itself.
+    repo_id: opts.repo_id || null,
+    branch: opts.branch || null,
+    base_sha: opts.base_sha || null,
+    pre_dirty: Array.isArray(opts.pre_dirty) ? opts.pre_dirty : [],
+    commands: [],
+    files: [],
+    date_created_ts: Date.now(),
+    ts: Date.now(),
+    _spawn: { prompt, codex_model, attachments, agent_mcp, bypass_sandbox, sandbox },
+  };
+  run._conversation_doc = conversation_doc;
+
+  await fs.promises.mkdir(code_run_dir(run_id), { recursive: true });
+  // Identity on disk, so a restarted box can find this run again without memcached and without
+  // scanning every account database. Written before the doc: if anything fails after this, the
+  // sweep still knows the run existed.
+  await fs.promises.writeFile(code_run_meta_path(run_id), JSON.stringify({ run_id, app_id, uid, conversation_id, host: run.host, engine: run.engine, log_path: run.log_path }, null, 2));
+
+  await persist_code_run(run);
+
+  if (_code_run_tails.size >= CODE_RUN_MAX_CONCURRENT) {
+    // Over the cap: leave it queued and let a finishing run pull it in. A busy account degrades
+    // into a queue instead of into swap, which is what unbounded concurrency did (one Codex CLI
+    // plus one SSH session per run, all in the ai process).
+    _code_run_queue.push(run);
+    return { code: 1, data: { run_id, state: 'queued' } };
+  }
+
+  return await launch_code_run(run);
+};
+
+const _code_run_queue = [];
+
+const launch_code_run = async function (run) {
+  try {
+    const { prompt, codex_model, attachments = [], agent_mcp, bypass_sandbox, sandbox } = run._spawn || {};
+    let codex_args = get_openai_codex_exec_args(codex_model, { sandbox, bypass_sandbox, resume_session_id: run.resumed_session_id || undefined });
+    if (agent_mcp && agent_mcp.url) {
+      codex_args = ['-c', `mcp_servers.xuda.url="${agent_mcp.url}"`, '-c', `mcp_servers.xuda.bearer_token_env_var="${agent_mcp.bearer_env_var || 'XUDA_AGENT_KEY'}"`, ...codex_args];
+    }
+    for (const attachment of attachments) {
+      const local_attachment_path = get_codex_local_attachment_path(attachment);
+      if (local_attachment_path && is_codex_image_attachment(local_attachment_path)) codex_args.push('--image', local_attachment_path);
+    }
+    // Positionals last, in order: `exec resume [OPTIONS] <SESSION_ID> [PROMPT]`. `-` is the prompt,
+    // read from stdin.
+    if (run.resumed_session_id) codex_args.push(run.resumed_session_id);
+    codex_args.push('-');
+
+    // Before the process, never after: once Codex starts it can write within the same second.
+    await code_run_capture_before(run);
+
+    const { pid, detach } = await spawn_detached_to_log(get_openai_codex_cli_command(), codex_args, prompt, {
+      log_path: run.log_path,
+      env: {
+        ...process.env,
+        OPENAI_API_KEY: _conf.OPENAI_API_KEY,
+        ...(agent_mcp && agent_mcp.bearer_value ? { [agent_mcp.bearer_env_var || 'XUDA_AGENT_KEY']: agent_mcp.bearer_value } : {}),
+      },
+      ...(run.local_cwd ? { cwd: run.local_cwd } : {}),
+    });
+
+    run.pid = pid;
+    run.detach = detach;
+    run.state = 'running';
+    run.started_ts = Date.now();
+    delete run._spawn;
+    await persist_code_run(run);
+
+    const emit = code_run_emitter(run);
+    // Only when nobody has opened the stream yet. A chat turn already emitted stream_start (and
+    // stamped request_started_at) before it got here, and a second one makes the client throw away
+    // the bubble it just made.
+    if (run.emit_stream_start) emit('stream_start');
+    emit('stream_phase', run.resumed_session_id ? 'Picking up where we left off' : 'Starting', { update: true });
+
+    attach_code_run(run);
+    return { code: 1, data: { run_id: run._id, pid, state: 'running' } };
+  } catch (err) {
+    console.error(`[code_run] launch ${run._id} failed: ${err?.message || err}`);
+    run.state = 'failed';
+    run.error = err?.message || String(err);
+    run.ended_ts = Date.now();
+    await persist_code_run(run);
+    await finalize_code_run(run, {});
+    return { code: -1, data: 'code run failed to start' };
+  }
+};
+
+const start_queued_code_runs = async function () {
+  while (_code_run_queue.length && _code_run_tails.size < CODE_RUN_MAX_CONCURRENT) {
+    const next = _code_run_queue.shift();
+    if (!next) break;
+    await launch_code_run(next);
+  }
+};
+
+// ── Surviving a restart ────────────────────────────────────────────────────────────────────
+// Deliberately deferred rather than run at import time: the module is still evaluating when the
+// broker loads it, and this reaches helpers defined further down the file.
+const resume_code_runs_after_boot = async function () {
+  let dirs = [];
+  try {
+    dirs = await fs.promises.readdir(code_run_root_dir());
+  } catch (err) {
+    return;
+  }
+
+  for (const run_id of dirs) {
+    try {
+      const meta = JSON.parse(await fs.promises.readFile(code_run_meta_path(run_id), 'utf8'));
+      if (!meta?.app_id || meta.host !== code_run_host()) continue;
+      const run = await load_code_run(meta.app_id, run_id);
+      if (!run || run.state !== 'running') continue;
+
+      if (code_run_process_alive(run.pid)) {
+        // Still working. Pick the transcript back up where the last process left off, so the
+        // answer still lands and the user sees the rest of it.
+        console.log(`[code_run] re-attaching to ${run_id} (pid ${run.pid})`);
+        attach_code_run(run);
+      } else {
+        // The process went with the restart (or was killed). Finish from what the log holds
+        // rather than leaving a chat that spins forever.
+        console.log(`[code_run] finalizing orphaned ${run_id}`);
+        run.state = 'orphaned';
+        await finalize_code_run(run, {});
+      }
+    } catch (err) {
+      // A directory with no readable meta is not a run we can recover; the sweep removes it.
+    }
+  }
+};
+
+// Retention + the cross-process backstop, called from the controller tick. Handles the case the
+// boot scan cannot: a box whose ai process never came back, and run directories nobody needs.
+export const sweep_code_runs = async function () {
+  let removed = 0;
+  let finalized = 0;
+  try {
+    const dirs = await fs.promises.readdir(code_run_root_dir()).catch(() => []);
+    for (const run_id of dirs) {
+      const dir = code_run_dir(run_id);
+      let meta = null;
+      try {
+        meta = JSON.parse(await fs.promises.readFile(code_run_meta_path(run_id), 'utf8'));
+      } catch (err) {}
+      const stat = await fs.promises.stat(dir).catch(() => null);
+      const age = stat ? Date.now() - stat.mtimeMs : 0;
+
+      if (meta?.app_id && meta.host === code_run_host()) {
+        const run = await load_code_run(meta.app_id, run_id);
+        if (run && run.state === 'running' && !_code_run_tails.has(run_id) && !code_run_process_alive(run.pid)) {
+          run.state = 'orphaned';
+          await finalize_code_run(run, {});
+          finalized += 1;
+          continue;
+        }
+        if (run && run.state === 'running') continue;
+      }
+
+      if (age > CODE_RUN_RETENTION_MS) {
+        await fs.promises.rm(dir, { recursive: true, force: true }).catch(() => {});
+        removed += 1;
+      }
+    }
+  } catch (err) {
+    console.error(`[code_run] sweep: ${err?.message || err}`);
+  }
+  return { code: 1, data: { removed, finalized, active: _code_run_tails.size, queued: _code_run_queue.length } };
+};
+
+setTimeout(() => {
+  resume_code_runs_after_boot().catch((err) => console.error(`[code_run] boot scan: ${err?.message || err}`));
+}, 5000);
+
+// ── Reading a run, and undoing one file of it ───────────────────────────────────────────────
+// The workspace reads runs through these. Ownership needs no extra check beyond the database a
+// run is read FROM: runs live in the caller's own account project db, so another account's run is
+// simply not found (same wall get_chat_conversation stands behind). The uid comparison below is
+// belt and braces for a shared profile.
+const load_own_code_run = async function (uid, profile_id, run_id) {
+  const account_profile_info = await get_active_account_profile_info(uid, profile_id);
+  const run = await load_code_run(account_profile_info.app_id, run_id);
+  if (!run) return { error: { code: -1, data: 'code run not found' } };
+  if (run.uid && run.uid !== uid) return { error: { code: -1, data: 'code run not found' } };
+  return { run, app_id: account_profile_info.app_id };
+};
+
+// One file's worth of change, as a unified diff. Both snapshot mechanisms can answer it: git from
+// the two commits it made, a copy snapshot by diffing the backup against the live tree. Output is
+// capped because a diff is for reading, not for shipping a binary through a socket.
+const CODE_RUN_DIFF_MAX_LINES = 2000;
+const code_run_file_entry = function (run, file_path) {
+  return (run.files || []).find((f) => f.path === file_path || f.rel === file_path) || null;
+};
+
+// One line of `git status --porcelain` into { code, rel }. Deliberately NOT a fixed slice at column
+// 3: the runner trims a command's output, which removes the leading space of the FIRST line only, so
+// a fixed offset silently ate the first character of the first path (`app.js` came back as `pp.js`,
+// and every diff and revert for it then found nothing). A rename reports `old -> new`; the new path
+// is the one that exists.
+const git_parse_status_line = function (line) {
+  const m = String(line || '').match(/^\s*(\S{1,2})\s+(.+)$/);
+  if (!m) return null;
+  const rel = m[2].includes(' -> ') ? m[2].split(' -> ').pop() : m[2];
+  return { code: m[1], rel: rel.replace(/^"|"$/g, '') };
+};
+
+// The token a repo-backed run's git commands need. Read from the repo doc at use time rather than
+// stored on the run, so a disconnected repository takes its access with it.
+const git_run_token = async function (uid, profile_id, run) {
+  if (!run?.repo_id) return null;
+  const { repo } = await load_git_repo(uid, profile_id, run.repo_id);
+  return repo?.token || null;
+};
+
+export const code_run_file_diff = async function (req) {
+  const { uid, profile_id, run_id, path: file_path } = req;
+  try {
+    const { run, error } = await load_own_code_run(uid, profile_id, run_id);
+    if (error) return error;
+    const entry = code_run_file_entry(run, file_path);
+    if (!entry) return { code: -1, data: 'that file is not part of this run' };
+    if (!entry.diff_available) return { code: 2, data: { path: entry.path, change: entry.change, diff: '', reason: 'no before state was captured for this file' } };
+
+    // UI-226: a repository's change is read from the repository. Uncommitted work diffs against HEAD;
+    // once the user has committed it, the run's own base_sha is what the change is still measured
+    // from, so the panel keeps showing what THIS run did rather than nothing at all.
+    if (entry.snapshot_kind === 'repo') {
+      const token = await git_run_token(uid, profile_id, run);
+      const dirty = await git_exec({ cwd: entry.root, args: ['status', '--porcelain', '--untracked-files=all', '--', entry.rel], token });
+      const args = dirty.stdout
+        ? entry.change === 'add'
+          ? ['diff', '--no-index', '--', '/dev/null', entry.rel]
+          : ['diff', 'HEAD', '--', entry.rel]
+        : ['diff', `${entry.before_ref}..HEAD`, '--', entry.rel];
+      const ret = await git_exec({ cwd: entry.root, args, token });
+      const diff = (ret.stdout || '').split('\n').slice(0, CODE_RUN_DIFF_MAX_LINES).join('\n');
+      return { code: 1, data: { path: entry.path, change: entry.change, diff, truncated: (ret.stdout || '').split('\n').length > CODE_RUN_DIFF_MAX_LINES } };
+    }
+
+    let cmd;
+    if (entry.snapshot_kind === 'git') {
+      const git = code_run_shadow_git(entry.root);
+      cmd = `${git} diff ${entry.before_ref} ${entry.after_ref || 'HEAD'} -- ${JSON.stringify(entry.rel)} | head -${CODE_RUN_DIFF_MAX_LINES}`;
+    } else {
+      const before = path.join(entry.before_ref, entry.rel);
+      // /dev/null on the side that does not exist, so an add and a delete both read as a diff
+      // rather than as an error.
+      const left = entry.change === 'add' ? '/dev/null' : JSON.stringify(before);
+      const right = entry.change === 'delete' ? '/dev/null' : JSON.stringify(entry.path);
+      cmd = `diff -u ${left} ${right} | head -${CODE_RUN_DIFF_MAX_LINES}`;
+    }
+
+    const ret = await code_run_exec(run, cmd, 60000);
+    const diff = ret.stdout || '';
+    return { code: 1, data: { path: entry.path, change: entry.change, diff, truncated: diff.split('\n').length >= CODE_RUN_DIFF_MAX_LINES } };
+  } catch (err) {
+    console.error(`[code_run] diff failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not read that change' };
+  }
+};
+
+// Put one file back the way it was before the run. This WRITES on the customer's own machine, so
+// it carries the same 'files' consent the file tools do (predicate duplicated from app_module the
+// way _ask_ai_consent_blocked above is, since no cpi module imports app_module), and it refuses
+// rather than guesses when the snapshot it would restore from is gone.
+const _CODE_RUN_CONSENT_TYPES = ['vps', 'external_vps'];
+const _code_run_files_consent_blocked = (app_obj) =>
+  !!app_obj && _CODE_RUN_CONSENT_TYPES.includes(app_obj.app_type) && app_obj?.deploy_data?.access_consents?.files?.granted !== true;
+
+export const code_run_revert_file = async function (req) {
+  const { uid, profile_id, run_id, path: file_path } = req;
+  try {
+    const { run, error } = await load_own_code_run(uid, profile_id, run_id);
+    if (error) return error;
+    const entry = code_run_file_entry(run, file_path);
+    if (!entry) return { code: -1, data: 'that file is not part of this run' };
+    if (!entry.revert_available) return { code: -1, data: 'there is no saved copy of this file from before the run, so it cannot be put back' };
+    if (entry.reverted_ts) return { code: 2, data: { path: entry.path, already_reverted: true } };
+
+    if (run.remote_host && run.target_app_id) {
+      let app_obj = null;
+      try {
+        app_obj = (await db_module.get_couch_doc('xuda_master', run.target_app_id)).data;
+      } catch (e) {}
+      if (_code_run_files_consent_blocked(app_obj)) {
+        return { code: -91, data: 'File access consent required for this server', consent_required: true, scope: 'files' };
+      }
+    }
+
+    // UI-226: in a repository, putting a file back is what git already means by it. An untracked file
+    // the run created is removed; anything else is restored from HEAD (or from the run's base when the
+    // work has since been committed).
+    if (entry.snapshot_kind === 'repo') {
+      const token = await git_run_token(uid, profile_id, run);
+      const tracked = await git_exec({ cwd: entry.root, args: ['ls-files', '--error-unmatch', '--', entry.rel], token });
+      const args = tracked.exit_code !== 0 ? null : ['checkout', 'HEAD', '--', entry.rel];
+      const ret = args ? await git_exec({ cwd: entry.root, args, token }) : await run_process('bash', ['-lc', `rm -f ${JSON.stringify(entry.path)}`], null, { timeout: 30000 });
+      if (ret.exit_code !== 0) {
+        console.error(`[code_run] repo revert ${run_id} ${entry.rel} exit ${ret.exit_code}`);
+        return { code: -1, data: 'could not put that file back' };
+      }
+      entry.reverted_ts = Date.now();
+      entry.reverted_by_uid = uid;
+      await persist_code_run(run);
+      return { code: 1, data: { path: entry.path, change: entry.change, reverted: true } };
+    }
+
+    let cmd;
+    if (entry.snapshot_kind === 'git') {
+      const git = code_run_shadow_git(entry.root);
+      // A file the run CREATED has nothing to check out: putting it back means removing it.
+      cmd = entry.change === 'add' ? `rm -f ${JSON.stringify(entry.path)}` : `${git} checkout ${entry.before_ref} -- ${JSON.stringify(entry.rel)}`;
+    } else {
+      const before = path.join(entry.before_ref, entry.rel);
+      cmd = entry.change === 'add' ? `rm -f ${JSON.stringify(entry.path)}` : `mkdir -p ${JSON.stringify(path.dirname(entry.path))} && cp -a ${JSON.stringify(before)} ${JSON.stringify(entry.path)}`;
+    }
+
+    const ret = await code_run_exec(run, cmd, 60000);
+    if (ret.exit_code !== 0) {
+      console.error(`[code_run] revert ${run_id} ${entry.path} exit ${ret.exit_code}: ${(ret.stderr || '').slice(0, 300)}`);
+      return { code: -1, data: 'could not put that file back' };
+    }
+
+    entry.reverted_ts = Date.now();
+    entry.reverted_by_uid = uid;
+    await persist_code_run(run);
+    return { code: 1, data: { path: entry.path, change: entry.change, reverted: true } };
+  } catch (err) {
+    console.error(`[code_run] revert failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not put that file back' };
+  }
+};
+
+// The runs behind a conversation (the workspace's timeline), or the account's most recent ones.
+export const get_code_runs = async function (req) {
+  const { uid, profile_id, conversation_id, limit = 50 } = req;
+  try {
+    const account_profile_info = await get_active_account_profile_info(uid, profile_id);
+    const selector = { docType: 'code_run', uid };
+    if (conversation_id) selector.conversation_id = conversation_id;
+    // The window is deliberately wider than the caller's limit, and the ordering is applied here
+    // rather than in the query. Mango applies `limit` BEFORE anything is sorted and a `sort` on
+    // date_created_ts would need its own index, so asking the database for 1 row returned whichever
+    // run it happened to find first: the run panel asks for the newest and was handed an old one.
+    const window_size = Math.max(Number(limit) || 1, 25);
+    const q = await db_module.find_app_couch_query(account_profile_info.app_id, { selector, limit: window_size });
+    const docs = (q?.docs || []).sort((a, b) => (b.date_created_ts || 0) - (a.date_created_ts || 0)).slice(0, Number(limit) || 1);
+    return {
+      code: 1,
+      data: {
+        runs: docs.map((r) => ({
+          _id: r._id,
+          conversation_id: r.conversation_id,
+          engine: r.engine,
+          state: r.state,
+          date_created_ts: r.date_created_ts,
+          started_ts: r.started_ts,
+          ended_ts: r.ended_ts,
+          error: r.error,
+          file_count: (r.files || []).length,
+          command_count: (r.commands || []).length,
+          usage: r.usage,
+        })),
+      },
+    };
+  } catch (err) {
+    console.error(`[code_run] list failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not read your code runs' };
+  }
+};
+
+// One run in full: what it ran, what it touched, and what it cannot see. `watched` matters as much
+// as `files`: a panel that shows an empty list has to be able to say whether nothing changed or
+// nothing was being watched.
+export const get_code_run = async function (req) {
+  const { uid, profile_id, run_id } = req;
+  try {
+    const { run, error } = await load_own_code_run(uid, profile_id, run_id);
+    if (error) return error;
+    return {
+      code: 1,
+      data: {
+        _id: run._id,
+        conversation_id: run.conversation_id,
+        engine: run.engine,
+        state: run.state,
+        error: run.error,
+        started_ts: run.started_ts,
+        ended_ts: run.ended_ts,
+        usage: run.usage,
+        resumed_session_id: run.resumed_session_id,
+        // UI-226: present only on a repository-backed run, and what the panel keys its git header
+        // and its Commit / Push / Open PR actions off.
+        repo_id: run.repo_id || null,
+        branch: run.branch || null,
+        base_sha: run.base_sha || null,
+        commands: (run.commands || []).map((c) => ({ command: c.command, exit_code: c.exit_code, ts: c.ts, output: c.output })),
+        files: (run.files || []).map((f) => ({ path: f.path, rel: f.rel, change: f.change, diff_available: !!f.diff_available, revert_available: !!f.revert_available, reverted_ts: f.reverted_ts || null })),
+        files_truncated: !!run.files_truncated,
+        watched: run.snapshot?.watched || [],
+        skipped_roots: (run.snapshot?.roots || []).filter((r) => r.kind === 'skipped').map((r) => ({ root: r.root, reason: r.reason })),
+      },
+    };
+  } catch (err) {
+    console.error(`[code_run] read failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not read that code run' };
+  }
+};
+
+// Stop a run from the workspace. The chat's own Stop goes through abort_job (the run watches that
+// flag); this is the same thing addressed by run instead, for a surface that is looking at the run
+// rather than at the turn that started it.
+export const abort_code_run = async function (req) {
+  const { uid, profile_id, run_id } = req;
+  try {
+    const { run, error } = await load_own_code_run(uid, profile_id, run_id);
+    if (error) return error;
+    if (run.state !== 'running' && run.state !== 'queued') return { code: 2, data: { run_id, state: run.state, already_finished: true } };
+
+    const live = _code_run_tails.get(run_id);
+    kill_code_run_process(run.pid);
+    if (live) live();
+    // The in-memory run object is the one the tail owns; this may be a different process, so
+    // finalize from the doc we just read.
+    await finalize_code_run(run, { aborted: true });
+    return { code: 1, data: { run_id, state: run.state } };
+  } catch (err) {
+    console.error(`[code_run] abort failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not stop that run' };
+  }
+};
+
+// ══════════════════════════════════════════════════════════════════════════════════════════
+// Code chats against a real repository (UI-226)
+//
+// Boaz: "the new code tab that you added should work with git", meaning the customer's own GitHub or
+// GitLab repository, and "the git thing is only for the code tab, vps and etc stay the same". On what
+// happens after a run: "it should work like claude code".
+//
+// So a Code-tab chat on a project with a connected repo behaves like Claude Code on a checkout: the
+// run edits a real WORKING COPY on this server, nothing is committed or pushed behind the user's
+// back, the file list is the uncommitted change set against HEAD, and Commit / Push / Open PR are
+// things the user does. The repository is the record, so these runs need no hidden snapshot.
+//
+// The VPS path is untouched by all of this: a chat opened from a project's AI panel still runs Codex
+// over SSH on that machine with the snapshot-based file list.
+//
+// A repo lives on its PROJECT, and its token lives on a `git_repo` doc in the ACCOUNT'S project
+// database (the one that already holds chat_conversation and code_run). Deliberately not on the app
+// doc in xuda_master: control DBs replicate bidirectionally fleet-wide through the master hub, so a
+// token there would be copied to every region. No read path ever returns it.
+// ══════════════════════════════════════════════════════════════════════════════════════════
+
+const GIT_PROVIDERS = ['github', 'gitlab', 'file'];
+const GIT_CLONE_TIMEOUT_MS = 10 * 60 * 1000;
+const GIT_CMD_TIMEOUT_MS = 2 * 60 * 1000;
+// A repo bigger than this is reported rather than half-cloned onto the region server.
+const GIT_CLONE_MAX_MB = _conf.code_runs?.clone_max_mb || 2048;
+
+const git_repos_root = function () {
+  return _conf.repos_drive_path || path.join(process.env.XUDA_HOME, 'code_repos');
+};
+
+const git_work_dir = function (uid, repo_id) {
+  return path.join(git_repos_root(), uid, repo_id);
+};
+
+// What the remote is, from its own URL. `file` exists for a local bare repo, which is how the git
+// mechanics are tested without anybody's credentials.
+const git_detect_provider = function (remote_url) {
+  const url = String(remote_url || '');
+  if (url.startsWith('file://') || url.startsWith('/')) return 'file';
+  if (/github\.com/i.test(url)) return 'github';
+  if (/gitlab/i.test(url)) return 'gitlab';
+  return null;
+};
+
+// The username half of an HTTPS token auth, which differs per provider and is NOT the secret. It is
+// stored in the URL; the token itself is only ever handed over through askpass (below).
+const git_token_user = function (provider) {
+  return provider === 'gitlab' ? 'oauth2' : 'x-access-token';
+};
+
+const git_normalize_remote = function (remote_url, provider) {
+  const url = String(remote_url || '').trim();
+  if (provider === 'file') return url;
+  try {
+    const parsed = new URL(url);
+    // Strip anything already in the URL's user info: a token pasted into the url would otherwise be
+    // stored in the doc twice and end up in .git/config.
+    parsed.username = git_token_user(provider);
+    parsed.password = '';
+    return parsed.toString();
+  } catch (err) {
+    return url;
+  }
+};
+
+// ── Running git without the token ever touching argv, .git/config or a log ──────────────────
+// The token goes in via GIT_ASKPASS: git asks for the password, the helper prints what is in the
+// environment. That keeps it out of the process list (which any tenant on the box can read), out of
+// the repository config, and out of the run log the panel shows the customer. GIT_TERMINAL_PROMPT=0
+// so a bad token fails immediately instead of hanging on a prompt.
+const GIT_ASKPASS_PATH = () => path.join(git_repos_root(), '.xuda_askpass.sh');
+
+const ensure_git_askpass = async function () {
+  const p = GIT_ASKPASS_PATH();
+  try {
+    await fs.promises.mkdir(path.dirname(p), { recursive: true });
+    await fs.promises.writeFile(p, '#!/bin/sh\nprintf "%s" "$XUDA_GIT_TOKEN"\n', { mode: 0o700 });
+  } catch (err) {
+    console.error(`[git] askpass write failed: ${err?.message || err}`);
+  }
+  return p;
+};
+
+const git_exec = async function ({ cwd, args, token, timeout_ms = GIT_CMD_TIMEOUT_MS }) {
+  const askpass = await ensure_git_askpass();
+  const env = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_ASKPASS: askpass,
+    // A run's commits are Xuda's, not a person's, and a box with no git identity would otherwise
+    // refuse to commit at all.
+    GIT_AUTHOR_NAME: 'Xuda',
+    GIT_AUTHOR_EMAIL: 'code@xuda.ai',
+    GIT_COMMITTER_NAME: 'Xuda',
+    GIT_COMMITTER_EMAIL: 'code@xuda.ai',
+    ...(token ? { XUDA_GIT_TOKEN: token } : {}),
+  };
+  const ret = await run_process('git', args, null, { cwd, env, timeout: timeout_ms, killSignal: 'SIGKILL' });
+  return { exit_code: ret.exit_code, stdout: (ret.stdout || '').trim(), stderr: (ret.stderr || '').trim() };
+};
+
+// ── The git_repo doc ───────────────────────────────────────────────────────────────────────
+const git_repo_safe = function (doc) {
+  if (!doc) return null;
+  return {
+    _id: doc._id,
+    app_id: doc.app_id,
+    provider: doc.provider,
+    remote_url: doc.remote_url,
+    default_branch: doc.default_branch,
+    token_last4: doc.token_last4 || null,
+    connected_by_uid: doc.connected_by_uid,
+    stat: doc.stat,
+    ts: doc.ts,
+  };
+};
+
+const load_git_repo = async function (uid, profile_id, repo_id) {
+  const account_profile_info = await get_active_account_profile_info(uid, profile_id);
+  try {
+    const doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, repo_id);
+    if (!doc || doc.docType !== 'git_repo' || doc.stat === 4) return { error: { code: -1, data: 'repository not found' } };
+    return { repo: doc, app_id: account_profile_info.app_id };
+  } catch (err) {
+    return { error: { code: -1, data: 'repository not found' } };
+  }
+};
+
+// Connect a repository to a project. The token is checked against the real remote BEFORE anything is
+// stored, so a typo is an error message rather than a repo that fails on first use.
+export const git_repo_connect = async function (req) {
+  const { uid, profile_id, app_id, remote_url, token, default_branch } = req;
+  try {
+    if (!app_id) return { code: -1, data: 'app_id is required' };
+    if (!remote_url) return { code: -1, data: 'a repository url is required' };
+    const provider = req.provider && GIT_PROVIDERS.includes(req.provider) ? req.provider : git_detect_provider(remote_url);
+    if (!provider) return { code: -1, data: 'only GitHub and GitLab repositories are supported' };
+    if (provider !== 'file' && !token) return { code: -1, data: 'an access token is required' };
+
+    const account_profile_info = await get_active_account_profile_info(uid, profile_id);
+    const normalized = git_normalize_remote(remote_url, provider);
+
+    // The reachability test IS the validation: ls-remote authenticates, resolves the default branch
+    // and proves the token has read access, in one round trip.
+    const ls = await git_exec({ args: ['ls-remote', '--symref', normalized, 'HEAD'], token, timeout_ms: 60000 });
+    if (ls.exit_code !== 0) {
+      // Never echo git's stderr: it can carry the URL with credentials on some transports.
+      console.error(`[git] connect ls-remote failed for ${app_id}: exit ${ls.exit_code}`);
+      return { code: -1, data: 'Xuda could not reach that repository with those details. Check the url and the token, and that the token can read this repository.' };
+    }
+    const head_ref = (ls.stdout.match(/^ref:\s+refs\/heads\/(\S+)\s+HEAD$/m) || [])[1];
+    const resolved_branch = default_branch || head_ref || 'main';
+
+    // One repo per project for now: reconnecting replaces what was there rather than stacking.
+    const existing = await db_module.find_app_couch_query(account_profile_info.app_id, { selector: { docType: 'git_repo', app_id, 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);
+    }
 
-User request:
-${prompt}`
-      : `You are OpenAI Codex running on the local Xuda server.
+    const repo_doc = {
+      _id: await _common.xuda_get_uuid('git_repo'),
+      docType: 'git_repo',
+      stat: 3,
+      app_id,
+      provider,
+      remote_url: normalized,
+      default_branch: resolved_branch,
+      token: token || null,
+      token_last4: token ? String(token).slice(-4) : null,
+      connected_by_uid: uid,
+      date_created_ts: Date.now(),
+      ts: Date.now(),
+    };
+    await db_module.save_app_couch_doc_native(account_profile_info.app_id, repo_doc);
+    return { code: 1, data: { repo: git_repo_safe(repo_doc) } };
+  } catch (err) {
+    console.error(`[git] connect failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not connect that repository' };
+  }
+};
 
-The target remote machine is ${get_codex_remote_host(ip)}.
-Execute shell commands on the remote machine through SSH, for example:
-ssh -o BatchMode=yes -o StrictHostKeyChecking=no ${get_codex_remote_host(ip)} "<command>"
+export const git_repo_list = async function (req) {
+  const { uid, profile_id, app_id } = req;
+  try {
+    const account_profile_info = await get_active_account_profile_info(uid, profile_id);
+    const selector = { docType: 'git_repo', stat: 3 };
+    if (app_id) selector.app_id = app_id;
+    const q = await db_module.find_app_couch_query(account_profile_info.app_id, { selector, limit: 50 });
+    return { code: 1, data: { repos: (q?.docs || []).map(git_repo_safe) } };
+  } catch (err) {
+    console.error(`[git] list failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not read your repositories' };
+  }
+};
 
-Do not assume the current local filesystem is the remote machine. Use SSH for inspection, edits, installs, and command execution unless the user explicitly asks for local work.
-For generated websites or other large file payloads, create the files first on the local Xuda server in a temporary working directory, validate them locally, then copy them to the remote machine with scp and use SSH only for remote placement, permissions, service reloads, and verification. Avoid embedding long HTML, CSS, JavaScript, JSON, or scripts inside nested ssh heredocs because shell quoting can corrupt the generated files.
+export const git_repo_disconnect = async function (req) {
+  const { uid, profile_id, repo_id } = req;
+  try {
+    const { repo, app_id, error } = await load_git_repo(uid, profile_id, repo_id);
+    if (error) return error;
+    repo.stat = 4;
+    repo.token = null;
+    repo.ts = Date.now();
+    await db_module.save_app_couch_doc(app_id, repo);
+    // The working copy goes with it: it holds the repository's code and there is nothing left that
+    // may read it.
+    await fs.promises.rm(git_work_dir(uid, repo_id), { recursive: true, force: true }).catch(() => {});
+    return { code: 1, data: { repo_id, disconnected: true } };
+  } catch (err) {
+    console.error(`[git] disconnect failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not disconnect that repository' };
+  }
+};
 
-User request:
-${prompt}`;
+// ── The working copy ───────────────────────────────────────────────────────────────────────
+// One per repo, reused across runs and chats. Cloned on first use, fetched after that. A chat owns a
+// BRANCH off the default branch; the default branch is never checked out for writing, so nothing a
+// run does can land on main without a person merging it.
+const git_chat_branch = function (conversation_id) {
+  return `xuda/${String(conversation_id || '').replace(/^cov_/, '').slice(0, 12)}`;
+};
 
-    if (local_attachments.length) {
-      codex_prompt += `\n\nAttachments available to Codex on the local Xuda server:\n${local_attachments.map((attachment_path) => `- ${attachment_path}`).join('\n')}`;
-    }
+const ensure_git_working_copy = async function ({ uid, repo, conversation_id }) {
+  const dir = git_work_dir(uid, repo._id);
+  const token = repo.token || null;
+  const branch = git_chat_branch(conversation_id);
+  await fs.promises.mkdir(path.dirname(dir), { recursive: true });
 
-    if (remote_attachments.length) {
-      codex_prompt += `\n\nAttachments available on the remote machine:\n${remote_attachments.map((attachment_path) => `- ${attachment_path}`).join('\n')}`;
-    }
+  const has_repo = await fs.promises
+    .stat(path.join(dir, '.git'))
+    .then(() => true)
+    .catch(() => false);
 
-    const openai_codex_command = get_openai_codex_cli_command();
-    let codex_args = get_openai_codex_exec_args(codex_model, { sandbox, bypass_sandbox });
-    if (agent_mcp && agent_mcp.url) {
-      // Register the Xuda MCP server for this run. Global `-c` overrides must
-      // precede the `exec` subcommand (args[0]), so prepend them. The bearer
-      // travels by env var name (resolved from the run env below), not value.
-      codex_args = ['-c', `mcp_servers.xuda.url="${agent_mcp.url}"`, '-c', `mcp_servers.xuda.bearer_token_env_var="${agent_mcp.bearer_env_var || 'XUDA_AGENT_KEY'}"`, ...codex_args];
+  if (!has_repo) {
+    // Size first: a repo too large to sit on the region server is refused with a reason instead of
+    // filling the disk halfway through.
+    if (repo.provider !== 'file') {
+      const info = await git_exec({ args: ['ls-remote', '--heads', repo.remote_url], token, timeout_ms: 60000 });
+      if (info.exit_code !== 0) return { error: 'Xuda could not reach that repository. Check the token is still valid.' };
     }
-    for (const image_path of image_paths) {
-      codex_args.push('--image', image_path);
+    await fs.promises.rm(dir, { recursive: true, force: true }).catch(() => {});
+    const clone = await git_exec({ args: ['clone', '--no-tags', repo.remote_url, dir], token, timeout_ms: GIT_CLONE_TIMEOUT_MS });
+    if (clone.exit_code !== 0) {
+      console.error(`[git] clone failed for ${repo._id}: exit ${clone.exit_code}`);
+      return { error: 'Xuda could not clone that repository.' };
     }
-    codex_args.push('-');
+    const size_mb = Number(((await run_process('bash', ['-lc', `du -sm ${JSON.stringify(dir)} | cut -f1`], null, { timeout: 60000 })).stdout || '').trim()) || 0;
+    if (size_mb > GIT_CLONE_MAX_MB) {
+      await fs.promises.rm(dir, { recursive: true, force: true }).catch(() => {});
+      return { error: `That repository is ${size_mb} MB, which is over the ${GIT_CLONE_MAX_MB} MB limit for a working copy.` };
+    }
+  } else {
+    const fetched = await git_exec({ cwd: dir, args: ['fetch', '--prune', 'origin'], token });
+    if (fetched.exit_code !== 0) console.warn(`[git] fetch failed for ${repo._id}: exit ${fetched.exit_code}`);
+  }
 
-    const ret = await run_process(openai_codex_command, codex_args, codex_prompt, {
-      env: {
-        ...process.env,
-        OPENAI_API_KEY: _conf.OPENAI_API_KEY,
-        ...(agent_mcp && agent_mcp.bearer_value ? { [agent_mcp.bearer_env_var || 'XUDA_AGENT_KEY']: agent_mcp.bearer_value } : {}),
+  // The chat's branch: reuse it when it exists (locally or on the remote), otherwise cut it from the
+  // default branch. Existing local work is never thrown away, which is why this is not a hard reset.
+  const local = await git_exec({ cwd: dir, args: ['rev-parse', '--verify', `refs/heads/${branch}`], token });
+  if (local.exit_code === 0) {
+    const co = await git_exec({ cwd: dir, args: ['checkout', branch], token });
+    if (co.exit_code !== 0) return { error: 'Xuda could not switch to this chat’s branch. There may be uncommitted work in the way.' };
+  } else {
+    const remote = await git_exec({ cwd: dir, args: ['rev-parse', '--verify', `refs/remotes/origin/${branch}`], token });
+    const from = remote.exit_code === 0 ? `origin/${branch}` : `origin/${repo.default_branch}`;
+    const created = await git_exec({ cwd: dir, args: ['checkout', '-B', branch, from], token });
+    if (created.exit_code !== 0) {
+      // A brand new repository has no origin/<default> yet, so fall back to whatever HEAD is.
+      const fallback = await git_exec({ cwd: dir, args: ['checkout', '-B', branch], token });
+      if (fallback.exit_code !== 0) return { error: 'Xuda could not create a branch for this chat.' };
+    }
+  }
+
+  const head = await git_exec({ cwd: dir, args: ['rev-parse', 'HEAD'], token });
+  // Files already modified before the run starts. Recorded so the run is never credited with a
+  // change somebody else made by hand.
+  // --untracked-files=all so the before list is measured the same way the after list is; otherwise a
+  // file the user had already dropped in would read as one the run created.
+  const dirty = await git_exec({ cwd: dir, args: ['status', '--porcelain', '--untracked-files=all'], token });
+  return {
+    dir,
+    branch,
+    base_sha: head.exit_code === 0 ? head.stdout : null,
+    pre_dirty: (dirty.stdout || '')
+      .split('\n')
+      .map((l) => git_parse_status_line(l)?.rel)
+      .filter(Boolean),
+  };
+};
+
+// ── Status, commit, push, pull request ─────────────────────────────────────────────────────
+export const git_repo_status = async function (req) {
+  const { uid, profile_id, repo_id, conversation_id } = req;
+  try {
+    const { repo, error } = await load_git_repo(uid, profile_id, repo_id);
+    if (error) return error;
+    const dir = git_work_dir(uid, repo_id);
+    const exists = await fs.promises
+      .stat(path.join(dir, '.git'))
+      .then(() => true)
+      .catch(() => false);
+    if (!exists) return { code: 1, data: { repo: git_repo_safe(repo), cloned: false, branch: conversation_id ? git_chat_branch(conversation_id) : null } };
+
+    const token = repo.token || null;
+    const branch = (await git_exec({ cwd: dir, args: ['rev-parse', '--abbrev-ref', 'HEAD'], token })).stdout;
+    const status = await git_exec({ cwd: dir, args: ['status', '--porcelain'], token });
+    const last = await git_exec({ cwd: dir, args: ['log', '-1', '--pretty=%h|%s|%ct'], token });
+    // Ahead of WHAT: the branch's upstream when it has one, otherwise the default branch it was cut
+    // from. Measuring only against `origin/<branch>` reported 0 ahead for a branch that has never
+    // been pushed, which is the exact moment Push matters, and the button disabled itself.
+    const upstream = await git_exec({ cwd: dir, args: ['rev-parse', '--verify', `refs/remotes/origin/${branch}`], token });
+    const has_upstream = upstream.exit_code === 0;
+    const compare_to = has_upstream ? `origin/${branch}` : `origin/${repo.default_branch}`;
+    const counts = await git_exec({ cwd: dir, args: ['rev-list', '--left-right', '--count', `${compare_to}...${branch}`], token });
+    const [behind, ahead] = counts.exit_code === 0 ? counts.stdout.split(/\s+/).map((n) => Number(n) || 0) : [0, 0];
+    const [sha, subject, ts] = (last.stdout || '').split('|');
+    return {
+      code: 1,
+      data: {
+        repo: git_repo_safe(repo),
+        cloned: true,
+        branch,
+        ahead,
+        behind,
+        has_upstream,
+        uncommitted: (status.stdout || '').split('\n').filter(Boolean).length,
+        last_commit: sha ? { sha, subject, ts: Number(ts) * 1000 } : null,
       },
-      ...(local_cwd ? { cwd: local_cwd } : {}),
-      ...(codex_timeout ? { timeout: codex_timeout, killSignal: 'SIGKILL' } : {}),
-      onStdout: create_codex_jsonl_stream_parser(handleCodexEvent),
-    });
-    const events = parse_codex_jsonl(ret.stdout);
-    if (!codex_usage.input_tokens && !codex_usage.output_tokens && Array.isArray(events)) {
-      const completed_event_with_usage = events.findLast((event) => event?.type === 'turn.completed' && event.usage);
-      codex_usage = normalize_codex_usage(completed_event_with_usage?.usage);
-    }
+    };
+  } catch (err) {
+    console.error(`[git] status failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not read the repository status' };
+  }
+};
 
-    if (uid && account_profile_info && (codex_usage.input_tokens || codex_usage.output_tokens)) {
-      account_msa.record_ai_usage(
-        uid,
-        codex_usage.input_tokens,
-        codex_usage.output_tokens,
-        'execute codex request',
-        prompt,
-        get_openai_codex_usage_model(codex_model, requested_codex_model),
-        {
-          conversation_id,
-          job_id,
-          remote_host: local_cwd ? null : get_codex_remote_host(ip),
-          exit_code: ret.exit_code,
-          attachments_count: attachments.length,
-        },
-        account_profile_info,
-      );
+export const git_commit = async function (req) {
+  const { uid, profile_id, repo_id, message, paths } = req;
+  try {
+    const { repo, error } = await load_git_repo(uid, profile_id, repo_id);
+    if (error) return error;
+    const dir = git_work_dir(uid, repo_id);
+    const token = repo.token || null;
+
+    const add_args = Array.isArray(paths) && paths.length ? ['add', '--', ...paths] : ['add', '-A'];
+    const added = await git_exec({ cwd: dir, args: add_args, token });
+    if (added.exit_code !== 0) return { code: -1, data: 'could not stage those changes' };
+
+    const staged = await git_exec({ cwd: dir, args: ['diff', '--cached', '--name-only'], token });
+    if (!staged.stdout) return { code: 2, data: { nothing_to_commit: true } };
+
+    const commit = await git_exec({ cwd: dir, args: ['commit', '-m', String(message || 'Changes from a Xuda code chat').slice(0, 500)], token });
+    if (commit.exit_code !== 0) {
+      console.error(`[git] commit failed for ${repo_id}: exit ${commit.exit_code}`);
+      return { code: -1, data: 'could not commit those changes' };
     }
+    const head = await git_exec({ cwd: dir, args: ['rev-parse', 'HEAD'], token });
+    return { code: 1, data: { sha: head.stdout, files: staged.stdout.split('\n').filter(Boolean) } };
+  } catch (err) {
+    console.error(`[git] commit failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not commit those changes' };
+  }
+};
 
-    if (ret.exit_code !== 0) {
-      emitToDashboard('stream_phase', 'Codex request failed', { update: true });
-      streamText(`Codex request failed: ${ret.stderr || ret.stdout || `exit code ${ret.exit_code}`}`);
-      emitToDashboard('stream_end');
+// Where a pushed branch can be turned into a pull request. Built from the remote url so it works
+// without any API call, which is also the answer for a provider whose API we do not talk to.
+const git_compare_url = function (repo, branch) {
+  try {
+    const url = new URL(repo.remote_url);
+    url.username = '';
+    url.password = '';
+    const base = `${url.origin}${url.pathname.replace(/\.git$/, '')}`;
+    if (repo.provider === 'github') return `${base}/compare/${encodeURIComponent(repo.default_branch)}...${encodeURIComponent(branch)}?expand=1`;
+    if (repo.provider === 'gitlab') return `${base}/-/merge_requests/new?merge_request%5Bsource_branch%5D=${encodeURIComponent(branch)}`;
+    return null;
+  } catch (err) {
+    return null;
+  }
+};
 
-      return {
-        code: -3,
-        data: {
-          provider: 'openai_codex_cli',
-          remote_host: local_cwd ? null : get_codex_remote_host(ip),
-          command: `${openai_codex_command} ${codex_args.filter((arg) => arg !== '-').join(' ')}`,
-          exit_code: ret.exit_code,
-          stdout: ret.stdout,
-          stderr: ret.stderr,
-          events,
-          reasoning,
-          usage: codex_usage,
-        },
-      };
+export const git_push = async function (req) {
+  const { uid, profile_id, repo_id } = req;
+  try {
+    const { repo, error } = await load_git_repo(uid, profile_id, repo_id);
+    if (error) return error;
+    const dir = git_work_dir(uid, repo_id);
+    const token = repo.token || null;
+    const branch = req.branch || (await git_exec({ cwd: dir, args: ['rev-parse', '--abbrev-ref', 'HEAD'], token })).stdout;
+    if (!branch || branch === repo.default_branch) {
+      return { code: -1, data: 'Xuda only pushes a chat’s own branch, never the default branch.' };
+    }
+    const pushed = await git_exec({ cwd: dir, args: ['push', '--set-upstream', 'origin', branch], token, timeout_ms: GIT_CLONE_TIMEOUT_MS });
+    if (pushed.exit_code !== 0) {
+      console.error(`[git] push failed for ${repo_id}: exit ${pushed.exit_code}`);
+      return { code: -1, data: 'could not push that branch. The token may not have write access.' };
+    }
+    return { code: 1, data: { branch, compare_url: git_compare_url(repo, branch) } };
+  } catch (err) {
+    console.error(`[git] push failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not push that branch' };
+  }
+};
+
+// A real pull request (GitHub) or merge request (GitLab), with the same token. Falls back to the
+// compare url when the provider has no API we speak, so the user is never left without a way through.
+export const git_open_pr = async function (req) {
+  const { uid, profile_id, repo_id, title, body } = req;
+  try {
+    const { repo, error } = await load_git_repo(uid, profile_id, repo_id);
+    if (error) return error;
+    const dir = git_work_dir(uid, repo_id);
+    const token = repo.token || null;
+    const branch = req.branch || (await git_exec({ cwd: dir, args: ['rev-parse', '--abbrev-ref', 'HEAD'], token })).stdout;
+    if (!branch) return { code: -1, data: 'this chat has no branch yet' };
+
+    const url = new URL(repo.remote_url);
+    const project_path = url.pathname.replace(/^\/+|\.git$/g, '');
+
+    if (repo.provider === 'github') {
+      const res = await fetch(`https://api.github.com/repos/${project_path}/pulls`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'Content-Type': 'application/json', 'User-Agent': 'xuda' },
+        body: JSON.stringify({ title: String(title || `Changes from a Xuda code chat`).slice(0, 250), head: branch, base: repo.default_branch, body: String(body || '').slice(0, 60000) }),
+      });
+      const json = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        console.error(`[git] github pr failed ${res.status}: ${JSON.stringify(json).slice(0, 300)}`);
+        return { code: 2, data: { compare_url: git_compare_url(repo, branch), reason: json?.errors?.[0]?.message || 'the pull request could not be opened automatically' } };
+      }
+      return { code: 1, data: { url: json.html_url, number: json.number } };
     }
 
-    emitToDashboard('stream_end');
+    if (repo.provider === 'gitlab') {
+      const res = await fetch(`${url.origin}/api/v4/projects/${encodeURIComponent(project_path)}/merge_requests`, {
+        method: 'POST',
+        headers: { 'PRIVATE-TOKEN': token, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ source_branch: branch, target_branch: repo.default_branch, title: String(title || 'Changes from a Xuda code chat').slice(0, 250), description: String(body || '').slice(0, 60000) }),
+      });
+      const json = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        console.error(`[git] gitlab mr failed ${res.status}`);
+        return { code: 2, data: { compare_url: git_compare_url(repo, branch), reason: 'the merge request could not be opened automatically' } };
+      }
+      return { code: 1, data: { url: json.web_url, number: json.iid } };
+    }
 
-    return {
-      code: 0,
-      data: {
-        provider: 'openai_codex_cli',
-        remote_host: local_cwd ? null : get_codex_remote_host(ip),
-        command: `${openai_codex_command} ${codex_args.filter((arg) => arg !== '-').join(' ')}`,
-        stdout: ret.stdout,
-        stderr: ret.stderr,
-        events,
-        reasoning,
-        usage: codex_usage,
-      },
-    };
+    return { code: 2, data: { compare_url: git_compare_url(repo, branch), reason: 'this remote has no pull requests' } };
   } catch (err) {
-    console.error(err);
-    emitToDashboard('stream_phase', 'Codex request failed', { update: true });
-    streamText(`Codex request failed: ${err.message}`);
-    emitToDashboard('stream_end');
-    return { code: -1, data: err.message };
+    console.error(`[git] open pr failed: ${err?.message || err}`);
+    return { code: -1, data: 'could not open a pull request' };
   }
 };
 
@@ -2417,8 +4135,48 @@ export const get_chat_conversation = async function (req) {
   }
 };
 
+// UI-222: the fields that belong to the RECIPIENT of a shared or purchased item, not to the
+// owner of the original.
+//
+// Six list/info methods swap `doc` for the SOURCE doc when a row is shared or was bought,
+// because that is where the name, the picture and the instructions live and the recipient has
+// to see the owner's edits. But `pinned`, `favorite` and `stat` are the recipient's own state
+// and only ever exist on the recipient's copy, so they have to be carried across the swap.
+//
+// Missing one is not cosmetic: the `pinned` and `favorites` filters select on the RECIPIENT's
+// copy, so a mark that is not carried over produces a row that ANSWERS the filter and then
+// draws itself unmarked. That is exactly what shared and purchased agents did, they were the
+// only two of the six sites that named favorite and stat but not pinned, so a pinned shared
+// agent appeared under the Pinned filter with an unpinned card.
+//
+// The two marks live where that kind of doc keeps them: a chat at the top level, a studio doc
+// (mini app / AI agent) under studio_meta. The shape is read off the recipient's own doc rather
+// than hardcoded per call site, so one helper serves both.
+//
+// `??` rather than a plain assignment, which is what these sites already did: a copy the
+// recipient has never pinned or favorited carries no mark of its own and keeps showing the
+// source's.
+const apply_recipient_marks = function (doc, reference_doc) {
+  if (!doc || !reference_doc) return doc;
+
+  doc.stat = reference_doc.stat ?? doc.stat;
+
+  if (reference_doc.studio_meta) {
+    doc.studio_meta = {
+      ...(doc.studio_meta || {}),
+      pinned: reference_doc.studio_meta.pinned ?? doc?.studio_meta?.pinned,
+      favorite: reference_doc.studio_meta.favorite ?? doc?.studio_meta?.favorite,
+    };
+  } else {
+    doc.pinned = reference_doc.pinned ?? doc.pinned;
+    doc.favorite = reference_doc.favorite ?? doc.favorite;
+  }
+
+  return doc;
+};
+
 export const get_ai_chats = async function (req, job_id, headers) {
-  let { uid, reference_type, reference_id = '', _id, search, filter_type = 'all', conversation_type, limit, skip, conversation_id, profile_id } = req;
+  let { uid, reference_type, reference_id = '', _id, search, filter_type = 'all', conversation_type, limit, skip, conversation_id, profile_id, chat_class } = req;
 
   const account_profile_info = await get_active_account_profile_info(uid, profile_id);
 
@@ -2495,6 +4253,11 @@ export const get_ai_chats = async function (req, job_id, headers) {
     };
 
     const get_data_find = async function () {
+      // UI-223: the code list is an equality filter, so this account's pre-`chat_class` chats have
+      // to be stamped before it can find them. One bounded pass per account, cached after that.
+      if (chat_class === 'code' && !reference_id && !conversation_id) {
+        await ensure_chat_class_backfilled(uid, account_profile_info.app_id);
+      }
       let opt = {
         selector: {
           docType: 'chat_conversation',
@@ -2544,6 +4307,12 @@ export const get_ai_chats = async function (req, job_id, headers) {
           break;
         }
 
+        // UI-221
+        case 'favorites': {
+          opt.selector.favorite = true;
+          break;
+        }
+
         case 'mine': {
           opt.selector.uid = uid;
 
@@ -2559,6 +4328,16 @@ export const get_ai_chats = async function (req, job_id, headers) {
         opt.selector.conversation_type = conversation_type;
       }
 
+      // UI-223: the two chat worlds are listed separately. `chat_class: 'code'` asks for the code
+      // chats; anything else means the regular list, which EXCLUDES them. The exclusion is $ne so
+      // it also matches every chat created before the field existed (mango $ne matches a missing
+      // field), which is what keeps old chats visible without a backfill being on the critical
+      // path. Skipped when reading the items INSIDE one conversation, where the class is not a
+      // filter but a property of the thread already identified.
+      if (!reference_id && !conversation_id) {
+        opt.selector.chat_class = chat_class === 'code' ? 'code' : { $ne: 'code' };
+      }
+
       if (reference_id) {
         opt.selector.reference_id = reference_id;
       }
@@ -2755,8 +4534,9 @@ export const get_ai_chats = async function (req, job_id, headers) {
         reference_doc = _.cloneDeep(doc);
         doc = await db_module.get_app_couch_doc_native(reference_doc.shared_from_app_id, reference_doc.share_item_id);
         doc.reference_doc = reference_doc;
-        doc.pinned = reference_doc.pinned ?? doc.pinned;
-        doc.stat = reference_doc.stat ?? doc.stat;
+        // UI-221 / UI-222: pinned and favorite are the RECIPIENT's marks, so a chat shared
+        // with you can be pinned or favorited without touching the owner's copy.
+        apply_recipient_marks(doc, reference_doc);
       }
 
       doc.interactions = contact_chat_conversation_count_ret[doc._id];
@@ -3528,6 +5308,12 @@ export const get_ai_agents = async function (req, job_id, headers) {
         break;
       }
 
+      // UI-221
+      case 'favorites': {
+        opt.selector['studio_meta.favorite'] = true;
+        break;
+      }
+
       case 'mine': {
         opt.selector['studio_meta.createdByUid'] = uid;
 
@@ -3630,7 +5416,12 @@ export const get_ai_agents = async function (req, job_id, headers) {
         }
 
         doc.reference_doc = reference_doc;
-        doc.stat = reference_doc.stat;
+        // UI-221 / UI-222: the shared card renders the SOURCE agent doc, but pinned and
+        // favorite are the recipient's own marks and both filters read the recipient's copy,
+        // so they have to be carried over. Agents were the last two of the six carry-over
+        // sites still missing `pinned`, which is why a pinned shared agent used to answer the
+        // Pinned filter and then draw an unpinned card.
+        apply_recipient_marks(doc, reference_doc);
       }
 
       // purchased
@@ -3638,7 +5429,8 @@ export const get_ai_agents = async function (req, job_id, headers) {
         reference_doc = _.cloneDeep(doc);
         doc = await db_module.get_app_couch_doc_native(reference_doc.studio_meta.installed_from_app_id, doc._id);
         doc.reference_doc = reference_doc;
-        doc.stat = reference_doc.stat;
+        // UI-221 / UI-222
+        apply_recipient_marks(doc, reference_doc);
       }
 
       let info_doc = await get_ai_agent_info(uid, job_id, headers, doc);
@@ -4135,6 +5927,12 @@ export const get_apps = async function (req, job_id, headers) {
         break;
       }
 
+      // UI-221
+      case 'favorites': {
+        opt.selector['studio_meta.favorite'] = true;
+        break;
+      }
+
       default:
         break;
     }
@@ -4228,11 +6026,8 @@ export const get_apps = async function (req, job_id, headers) {
         reference_doc = _.cloneDeep(doc);
         doc = await db_module.get_app_couch_doc_native(reference_doc.studio_meta.shared_from_app_id, reference_doc.studio_meta.share_item_id);
         doc.reference_doc = reference_doc;
-        doc.stat = reference_doc.stat ?? doc.stat;
-        doc.studio_meta = {
-          ...(doc.studio_meta || {}),
-          pinned: reference_doc?.studio_meta?.pinned ?? doc?.studio_meta?.pinned,
-        };
+        // UI-221 / UI-222: the recipient's own marks win.
+        apply_recipient_marks(doc, reference_doc);
       }
 
       doc.user_contact = await get_user_card({ uid, uid_query: doc.studio_meta.createdByUid });
@@ -5826,7 +7621,9 @@ const AI_FIELD_MAX_CONTEXT_KEYS = 12;
 // Per-key overrides of the 1200-char cap. A sibling form field is a line or two,
 // but a transcript is the whole point of the context it carries: cut it to 1200
 // and the composer's helper answers the wrong message.
-const AI_FIELD_CONTEXT_VALUE_CAPS = { chat_history: 6000 };
+// UI-224: `email_thread` is the mail being replied to, quoted for the composer's helper. Same
+// reasoning as chat_history: the thread IS the context, so it gets room.
+const AI_FIELD_CONTEXT_VALUE_CAPS = { chat_history: 6000, email_thread: 6000 };
 
 const AI_FIELD_PRESETS = {
   agent_name: {
@@ -5871,6 +7668,42 @@ const AI_FIELD_PRESETS = {
       'Never invent facts, numbers, dates or commitments the thread does not support. If something is genuinely unknown, ask for it instead of inventing it.',
     ],
   },
+  // UI-224: the two sparkles in the mail client's composer. The chat composer has had one for
+  // a while (chat_message above) and the mail client had none, so writing an email was the one
+  // place in the product where the AI could not help. These are separate presets rather than a
+  // channel of chat_message because an email is two fields with different jobs: a subject line
+  // has to survive being read in a list, and a body has to open, say the thing and sign off.
+  // Both read `email_thread` (the mail being replied to) and the sibling field, so the subject
+  // can be written from the body and the body from the subject.
+  email_subject: {
+    label: 'Subject',
+    writes: 'the subject line of an email the user is about to send',
+    single_line: true,
+    max_chars: 120,
+    improve_task: 'TASK: turn what is in the box into the subject line this email should carry. Keep what it is about and make it read as a subject rather than as a note to self.',
+    generate_task: 'TASK: write the subject line for this email, from the body and the thread below. If the email is a reply, keep the thread\'s own subject and do not add another "Re:".',
+    rules: [
+      'Output the subject line only. No quotes, no "Subject:", no trailing period, no emoji.',
+      'Under 10 words. Say what the mail is about, specifically, so it can be found in a list six months from now.',
+      'Match the language the body and the thread are written in.',
+      'Never invent a fact, a name, a number or a date that the body and the thread do not support.',
+    ],
+  },
+  email_body: {
+    label: 'Message',
+    writes: 'the body of an email the user is about to send',
+    max_chars: 4000,
+    improve_task:
+      'TASK: turn what is in the box into the email the user is about to send. It is usually shorthand or a note to self, so expand it, write it out in full and address the recipient directly. Keep every specific they gave and add nothing they did not.',
+    generate_task: 'TASK: write this email from scratch, from the subject and the thread below. If there is a thread, answer what was actually asked in it. If there is neither, write a short, natural opening email.',
+    rules: [
+      'Write the email itself, ready to send: a greeting, short paragraphs, a sign-off. No preamble, no "here is a draft", no subject line, no placeholders in brackets.',
+      'Read the thread and continue it. Answer what was asked, refer to what was already said, and never repeat a point the thread has already made.',
+      'Write as the user, in the first person, in the language the thread is using.',
+      'Keep it short. Three short paragraphs at most unless the thread clearly needs more.',
+      'Never invent facts, numbers, dates or commitments the thread does not support. If something is genuinely unknown, ask for it instead of inventing it.',
+    ],
+  },
   agent_user_guide: {
     label: 'User guide',
     writes: 'a short guide shown to the people who will USE an AI agent, next to the chat box',
@@ -6457,6 +8290,83 @@ const email_binding_error = async function (account_profile_info) {
   return new Error(`${here} has no mailbox, so it cannot send email. Open Email to add one, then attach it to this profile.`);
 };
 
+// UI-223. Is this a CODE chat or a regular one? Code chats are the ones whose turns run commands
+// on a machine: a project's VPS, a full stack VPS, a mini app (studio), a static site's source.
+// Everything else (a contact, an agent, a profile, the dashboard's own composer) is a regular
+// chat. Decided once at creation and stored, so the two lists are a plain equality filter rather
+// than a join against the app catalog on every read.
+const CODE_CHAT_APP_TYPES = ['vps', 'external_vps', 'static_website'];
+const code_chat_class = async function (req, reference_type, reference_id) {
+  try {
+    // Mini apps are REGULAR chats (Boaz, 2026-08-13: "Mini app chats should be like the regular
+    // chats (not code)"). A studio chat asks an AI builder to write program documents, so it has no
+    // machine, no commands and no files: everything the Code surface exists to show is absent, and
+    // its own Apps tab already knows how to present it.
+    if (reference_type === 'apps' || req.conversation_type === 'studio') return 'chat';
+    if (reference_type !== 'dashboard') return 'chat';
+    // The client tells us directly when the user is in vibe mode, which is a code chat whatever
+    // the project turns out to be.
+    const ctx = req.context || req.metadata?.context;
+    if (ctx && typeof ctx === 'object' && ctx.vibe_mode === true) return 'code';
+    const app_id = req.app_id || reference_id;
+    if (!app_id) return 'chat';
+    const app_obj = (await db_module.get_couch_doc('xuda_master', app_id)).data;
+    if (!app_obj) return 'chat';
+    if (app_obj.is_full_stack) return 'code';
+    return CODE_CHAT_APP_TYPES.includes(app_obj.app_type) ? 'code' : 'chat';
+  } catch (err) {
+    // A chat that cannot be classified belongs in the list everything else is in, never hidden.
+    return 'chat';
+  }
+};
+
+// The code list is an equality filter, so a chat created before `chat_class` existed would never
+// appear in it (the regular list keeps showing it, because $ne matches a missing field, which is
+// why nothing disappears in the meantime). Rather than a fleet-wide migration, each account is
+// backfilled once, the first time it asks for its code chats. Bounded and marked in the cache, so
+// it costs one pass per account and nothing after that.
+const CHAT_CLASS_BACKFILL_LIMIT = 500;
+// The marker is versioned because the RULE can change: mini apps were briefly classified as code
+// and are now regular, so an account already marked done has to be walked again to correct what the
+// old rule stamped. Bump this when code_chat_class changes what an existing chat should be.
+const CHAT_CLASS_RULE_VERSION = 2;
+const ensure_chat_class_backfilled = async function (uid, app_id) {
+  const marker = `chat_class_backfill_v${CHAT_CLASS_RULE_VERSION}_${app_id}`;
+  try {
+    if (await db_module.get_memcached_doc(marker)) return;
+  } catch (err) {}
+  let stamped = 0;
+  try {
+    // Two kinds of doc need a pass: never stamped, and stamped `code` by an older rule. The second
+    // selector is narrow on purpose (only the class this rule moved), so re-running never re-walks
+    // an account's whole history.
+    const missing = await db_module.find_app_couch_query(app_id, {
+      selector: { docType: 'chat_conversation', chat_class: { $exists: false } },
+      limit: CHAT_CLASS_BACKFILL_LIMIT,
+    });
+    const stale = await db_module.find_app_couch_query(app_id, {
+      selector: { docType: 'chat_conversation', chat_class: 'code' },
+      limit: CHAT_CLASS_BACKFILL_LIMIT,
+    });
+    const q = { docs: [...(missing?.docs || []), ...(stale?.docs || [])] };
+    for (const doc of q?.docs || []) {
+      const chat_class = await code_chat_class({ context: doc.context, conversation_type: doc.conversation_type, app_id: doc.reference_id }, doc.reference_type, doc.reference_id);
+      if (doc.chat_class === chat_class) continue;
+      doc.chat_class = chat_class;
+      await db_module.save_app_couch_doc(app_id, doc);
+      stamped += 1;
+    }
+    // Only mark it done when neither pass was cut short by the limit, so a big account finishes
+    // over a few visits instead of being written off after the first 500.
+    if ((missing?.docs || []).length < CHAT_CLASS_BACKFILL_LIMIT && (stale?.docs || []).length < CHAT_CLASS_BACKFILL_LIMIT) {
+      await db_module.set_memcached_doc(marker, { done_ts: Date.now(), stamped }, 30 * 24 * 60 * 60);
+    }
+    if (stamped) console.log(`[chat_class] backfilled ${stamped} conversation(s) for ${app_id}`);
+  } catch (err) {
+    console.error(`[chat_class] backfill ${app_id} failed: ${err?.message || err}`);
+  }
+};
+
 export const create_conversation = async function (req, job_id, headers) {
   const { profile_id, uid, prompt, perform_ai_execution = true, email_id, direction = 'out', from_mailbox, date_created, ai_model = _conf.default_ai_model, plan_mode = false } = req;
   let { reference_type, reference_id = '', conversation_type, email_recipient_type } = req;
@@ -6519,6 +8429,12 @@ export const create_conversation = async function (req, job_id, headers) {
       email_recipient_type,
       model: ai_model,
       plan_mode: normalize_boolean(plan_mode),
+      // UI-223: which of the two chat worlds this belongs to. A code chat (a project's VPS, a full
+      // stack VPS, a mini app, a static site) behaves nothing like a chat with a contact or an
+      // agent: it runs commands on a machine, takes minutes, and has files and a run history to
+      // show. They are listed and opened separately, and this is what the lists filter on. Set at
+      // creation because it is a property of what the chat IS, not of any one turn.
+      chat_class: await code_chat_class(req, reference_type, reference_id),
     };
     const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, conversation_doc);
 
@@ -7047,6 +8963,12 @@ const contact_chat_conversation = async function (req, job_id, headers) {
     conversation_item_reference_id,
     direction: 'out',
     role: 'user',
+    // A message I just sent is read by me, by definition. The contact card's badge is
+    // (items on this contact) minus (items I have read), and the only other thing that
+    // ever stamps `read` is opening the conversation. Leave it off here and my own
+    // outgoing message sits in the badge forever unless I happen to re-open the thread it
+    // started, which is exactly the "opened everything, still says 1" report.
+    read: { [uid]: Date.now() },
   };
 
   const save_ret = await db_module.save_app_couch_doc(sender_app_id, out_conversation_item_obj);
@@ -7526,6 +9448,13 @@ const chat_email = async function (req, job_id, headers) {
   // UI-155: the template the user picked in the composer, for THIS message only. Empty on
   // every other path, which leaves the address's saved default in charge.
   const composed_style = String(req.template_style || '').trim();
+  // UI-224: the mail client sends its own message (one mailbox, many recipients, Cc and Bcc),
+  // and then files it on the thread of every recipient it knows as a contact. That filing is
+  // this function minus the delivery: the item, the threading and the timeline are wanted,
+  // a second copy of the mail is not. Distinct from `from_mailbox`, which also means "already
+  // delivered" but marks the message as one the MAILBOX brought in and lets an auto response
+  // answer it, neither of which is true of a mail we just sent ourselves.
+  const skip_send = req.skip_send === true;
   try {
     if (!account_profile_info.account_profile_obj?.email_account_id) {
       throw await email_binding_error(account_profile_info);
@@ -7590,12 +9519,32 @@ const chat_email = async function (req, job_id, headers) {
       if (composed_subject) {
         subject = composed_subject;
       } else if (!last_email_item) {
-        if (body.split(' ').length > 10) {
+        // UI-216 follow-up (Boaz: "generate auto subject for new email (not in thread)"). The
+        // FIRST email of a thread had a subject only when the body ran past ten words. Under
+        // that it fell through with none, and `subject` stayed whatever titled the conversation,
+        // which for a plain send is the body itself. That gate was survivable while every email
+        // went through the composer, where the user saw and approved a subject before anything
+        // left. Now that send means send, a short message is the common case, and a short
+        // message is exactly the one that arrives looking like nothing: no subject at all, or
+        // the message repeated as its own subject.
+        //
+        // Every new email gets one now. The split is about what it COSTS, not whether to bother:
+        // a body with something to summarise is worth an AI call, and a one-liner already IS its
+        // own subject, so it is cleaned up rather than sent to a model to be told so.
+        const words = String(body || '').trim().split(/\s+/).filter(Boolean);
+        if (words.length > 10) {
           const subject_ret = await submit_chat_gpt_prompt({ uid, prompt: `create title for the prompt return 5 words result maximum text only without options : ${body}`, model: _conf.default_ai_model, metadata: { conversation_id: conversation_doc._id, func: 'chat_email' }, account_profile_info });
           if (subject_ret.code < 0) {
             throw new Error('something wrong creating email subject');
           }
           subject = subject_ret.data;
+        } else if (words.length) {
+          // The first line, because a two line note should not put the second one in the
+          // subject; capped at the length a mail client will show; first letter raised so
+          // "test email" arrives as "Test email" rather than looking unfinished.
+          const first_line = String(body).split(/\r?\n/).find((line) => line.trim()) || '';
+          const trimmed = first_line.trim().replace(/\s+/g, ' ').slice(0, 60).replace(/[\s,;:.\-]+$/, '');
+          subject = trimmed ? trimmed.charAt(0).toUpperCase() + trimmed.slice(1) : subject;
         }
       } else {
         // UI-145: an email inside an existing conversation is a reply, which this path already
@@ -7618,53 +9567,58 @@ const chat_email = async function (req, job_id, headers) {
         subject = thread_subject ? 'Re: ' + thread_subject : '';
       }
 
-      let email_attachments = [];
-      for (const attachment of attachments) {
-        email_attachments.push(await save_drive_file_to_disk(attachment));
-      }
+      // UI-224: everything from here to the end of the block is the DELIVERY. A filing call
+      // has already delivered the mail itself, so it stops here and keeps the subject the
+      // threading above worked out.
+      if (!skip_send) {
+        let email_attachments = [];
+        for (const attachment of attachments) {
+          email_attachments.push(await save_drive_file_to_disk(attachment));
+        }
 
-      // Wrap the body with the profile's selected email template (Email
-      // Template tab). 'plain' or an unset style renders null, keeping the
-      // original raw-text behavior.
-      let template_html = null;
-      try {
-        const profile_doc = account_profile_info.account_profile_obj || {};
-        const render_ret = await email_ms.render_profile_email({
-          // The template and signature live on the attached email account now; the profile
-          // fields below are the fallback for a profile configured before the Email hub.
-          uid,
-          email_account_id: profile_doc.email_account_id,
-          style: profile_doc.email_template?.style,
-          // UI-155: a per-message choice made in the composer, which outranks the address's
-          // saved default inside the renderer.
-          ...(composed_style ? { style_override: composed_style } : {}),
-          body_text: body,
-          // A composed body is already HTML the user laid out (bold, lists, links), so the
-          // template has to drop it in as-is. Escaping it into paragraphs the way a plain
-          // body is treated would put the tags on screen as text.
-          ...(composed_html ? { body_html: composed_html } : {}),
-          profile_name: profile_doc.profile_name,
-          signature: profile_doc.profile_signature,
-          avatar_url: profile_doc.profile_picture || profile_doc.profile_avatar || '',
-          brand_color: profile_doc.widget_config?.color || '',
-        });
-        if (render_ret?.code > 0 && render_ret.data) template_html = render_ret.data;
-      } catch (err) {}
+        // Wrap the body with the profile's selected email template (Email
+        // Template tab). 'plain' or an unset style renders null, keeping the
+        // original raw-text behavior.
+        let template_html = null;
+        try {
+          const profile_doc = account_profile_info.account_profile_obj || {};
+          const render_ret = await email_ms.render_profile_email({
+            // The template and signature live on the attached email account now; the profile
+            // fields below are the fallback for a profile configured before the Email hub.
+            uid,
+            email_account_id: profile_doc.email_account_id,
+            style: profile_doc.email_template?.style,
+            // UI-155: a per-message choice made in the composer, which outranks the address's
+            // saved default inside the renderer.
+            ...(composed_style ? { style_override: composed_style } : {}),
+            body_text: body,
+            // A composed body is already HTML the user laid out (bold, lists, links), so the
+            // template has to drop it in as-is. Escaping it into paragraphs the way a plain
+            // body is treated would put the tags on screen as text.
+            ...(composed_html ? { body_html: composed_html } : {}),
+            profile_name: profile_doc.profile_name,
+            signature: profile_doc.profile_signature,
+            avatar_url: profile_doc.profile_picture || profile_doc.profile_avatar || '',
+            brand_color: profile_doc.widget_config?.color || '',
+          });
+          if (render_ret?.code > 0 && render_ret.data) template_html = render_ret.data;
+        } catch (err) {}
 
-      // With no template style selected there is nothing wrapping the body, so the composed
-      // HTML is the whole message. Without this it would fall through to sendEmailFromAccount's
-      // "wrap the plain text in one <p>" default and the formatting would be lost.
-      // UI-157: cc / bcc come from the composer and are normalized inside sendEmailFromAccount,
-      // so anything that is not an address is dropped rather than reaching the SMTP server.
-      sent_email_result = await email_ms.sendEmailFromAccount(email_account_doc, contact_info.email, subject, body, template_html || composed_html || null, email_attachments, {
-        cc: req.cc,
-        bcc: req.bcc,
-      });
-      if (!sent_email_result.success) {
-        throw new Error('error sending email');
-      }
-      for await (const attachment of email_attachments) {
-        await rm(attachment.path, { force: true });
+        // With no template style selected there is nothing wrapping the body, so the composed
+        // HTML is the whole message. Without this it would fall through to sendEmailFromAccount's
+        // "wrap the plain text in one <p>" default and the formatting would be lost.
+        // UI-157: cc / bcc come from the composer and are normalized inside sendEmailFromAccount,
+        // so anything that is not an address is dropped rather than reaching the SMTP server.
+        sent_email_result = await email_ms.sendEmailFromAccount(email_account_doc, contact_info.email, subject, body, template_html || composed_html || null, email_attachments, {
+          cc: req.cc,
+          bcc: req.bcc,
+        });
+        if (!sent_email_result.success) {
+          throw new Error('error sending email');
+        }
+        for await (const attachment of email_attachments) {
+          await rm(attachment.path, { force: true });
+        }
       }
     }
 
@@ -7698,6 +9652,9 @@ const chat_email = async function (req, job_id, headers) {
       conversation_item_reference_id,
       direction,
       role: 'user',
+      // Same rule as the chat send: mail I sent is already read by me. Inbound mail
+      // (the mailbox path) is left alone, that one really is waiting to be looked at.
+      ...(direction === 'out' ? { read: { [uid]: Date.now() } } : {}),
       email_id,
       subject,
       last_email_item_id: last_email_item?._id,
@@ -7718,24 +9675,105 @@ const chat_email = async function (req, job_id, headers) {
       }
     }
 
-    if (conversation_doc.reference_type === 'contacts' && from_mailbox) {
-      auto_response(uid, profile_id, conversation_doc.reference_id, 'email');
+    if (conversation_doc.reference_type === 'contacts' && from_mailbox) {
+      auto_response(uid, profile_id, conversation_doc.reference_id, 'email');
+    }
+
+    return save_ret;
+  } catch (err) {
+    // UI-161: this used to swallow the reason, so a send that died anywhere in here surfaced
+    // as a bare CouchDB `{ message: 'missing' }` on stderr with nothing tying it to a
+    // conversation, a contact or a mailbox. The job then ended and no email went out.
+    console.error(`[chat_email] failed: conversation_id=${conversation_doc?._id} contact=${conversation_doc?.reference_id} app_id=${account_profile_info?.app_id} profile=${account_profile_info?.account_profile_obj?._id} mailbox=${account_profile_info?.account_profile_obj?.email_account_id}`, err?.stack || err?.message || err);
+    // UI-161: an expired or revoked OAuth grant is the single most common way sending stops
+    // working, and "Failed to obtain valid access token" tells the person reading it nothing
+    // about what to do. Name the mailbox and the fix.
+    if (/access token|invalid_grant|unauthorized|invalid credentials/i.test(String(err?.message || ''))) {
+      const mailbox_address = email_account_doc?.email || account_profile_info?.account_profile_obj?.email_account_id || 'this mailbox';
+      return { code: -15, data: `Xuda can no longer sign in to ${mailbox_address}, so the email was not sent. Open Email, go to Mailboxes, and reconnect the account.` };
+    }
+    return { code: -15, data: err.message };
+  }
+};
+
+// UI-224: file a mail the MAIL CLIENT already sent onto a contact's email thread. The client
+// composes to several people at once and can send from a mailbox that belongs to another
+// profile, so it does the delivery itself (email_module's send_email_message) and calls this
+// once per recipient it knows as a contact. Everything the timeline needs then comes out of
+// the same chat_email the contact composer uses, with the delivery switched off, so a mail
+// sent from the client and one sent from a contact conversation leave identical records.
+//
+// The thread is the contact's newest email conversation, and one is opened when there is
+// none, which is what makes a first mail to a contact appear as a conversation rather than
+// as nothing at all.
+export const log_sent_email = async function (req = {}, job_id, headers) {
+  const { uid, profile_id, contact_id } = req;
+  try {
+    if (!contact_id) throw new Error('missing contact_id');
+    const account_profile_info = await get_active_account_profile_info(uid, profile_id);
+    const app_id = account_profile_info.app_id;
+    const subject = String(req.subject || '').trim();
+    const body = String(req.body_text || '').trim() || subject;
+    const body_html = String(req.body_html || '');
+
+    const found = await db_module.find_app_couch_query(app_id, {
+      selector: {
+        docType: 'chat_conversation',
+        reference_type: 'contacts',
+        reference_id: contact_id,
+        conversation_type: 'email',
+        stat: { $lt: 4 },
+      },
+      limit: 1,
+      sort: [{ ts: 'desc' }],
+    });
+
+    let conversation_id = found?.docs?.[0]?._id || '';
+    if (!conversation_id) {
+      // perform_ai_execution off: opening a thread to record a mail that has already gone is
+      // bookkeeping, and the title, category and picture passes belong to a conversation
+      // somebody is actually having.
+      const created = await create_conversation(
+        {
+          uid,
+          profile_id,
+          reference_type: 'contacts',
+          reference_id: contact_id,
+          conversation_type: 'email',
+          prompt: body,
+          subject,
+          direction: 'out',
+          perform_ai_execution: false,
+        },
+        job_id,
+        headers,
+      );
+      if (created?.code < 0) throw new Error(created.data);
+      conversation_id = created?.data?.id || created?.data?._id || '';
+      if (!conversation_id) throw new Error('could not open an email conversation for this contact');
     }
 
-    return save_ret;
+    const ret = await submit_chat_conversation(
+      {
+        uid,
+        profile_id,
+        conversation_id,
+        prompt: body,
+        subject,
+        ...(body_html ? { body_html } : {}),
+        direction: 'out',
+        perform_ai_execution: false,
+        // The mail is already out. This call is the record of it, not a second send.
+        skip_send: true,
+      },
+      job_id,
+      headers,
+    );
+    if (ret?.code < 0) throw new Error(ret.data);
+    return { code: 1, data: { conversation_id } };
   } catch (err) {
-    // UI-161: this used to swallow the reason, so a send that died anywhere in here surfaced
-    // as a bare CouchDB `{ message: 'missing' }` on stderr with nothing tying it to a
-    // conversation, a contact or a mailbox. The job then ended and no email went out.
-    console.error(`[chat_email] failed: conversation_id=${conversation_doc?._id} contact=${conversation_doc?.reference_id} app_id=${account_profile_info?.app_id} profile=${account_profile_info?.account_profile_obj?._id} mailbox=${account_profile_info?.account_profile_obj?.email_account_id}`, err?.stack || err?.message || err);
-    // UI-161: an expired or revoked OAuth grant is the single most common way sending stops
-    // working, and "Failed to obtain valid access token" tells the person reading it nothing
-    // about what to do. Name the mailbox and the fix.
-    if (/access token|invalid_grant|unauthorized|invalid credentials/i.test(String(err?.message || ''))) {
-      const mailbox_address = email_account_doc?.email || account_profile_info?.account_profile_obj?.email_account_id || 'this mailbox';
-      return { code: -15, data: `Xuda can no longer sign in to ${mailbox_address}, so the email was not sent. Open Email, go to Mailboxes, and reconnect the account.` };
-    }
-    return { code: -15, data: err.message };
+    console.error(`[log_sent_email] contact=${contact_id} uid=${uid}: ${err?.message || err}`);
+    return { code: -15, data: err.message || String(err) };
   }
 };
 
@@ -8755,6 +10793,79 @@ ${conversation_history || `User (dashboard): ${prompt}`}
       const vps_ip = vibe_app_obj?.app_hosting_server?.ip;
       const project_name = vibe_app_obj?.menuName || vibe_app_obj?.app_name || vibe_app_obj?.name || '';
 
+      // ── UI-226: the repository engine, and ONLY from the Code tab ──────────────────────────
+      // Boaz: "the git thing is only for the code tab, vps and etc stay the same". So the SURFACE
+      // decides, not the project: the code workspace sends `code_surface`, and only then does a
+      // project with a connected repo run against a working copy instead of its machine. A chat
+      // 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;
+      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' };
+        if (prepared.error) {
+          emitToDashboard('response_start');
+          streamText(prepared.error);
+          emitToDashboard('stream_end', undefined, { error: true });
+          conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
+          conversation_doc.ts = Date.now();
+          conversation_doc.stat = 3;
+          conversation_doc.process_stat = 'partial';
+          await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+          return await saveAssistantItem(prepared.error, { is_request_error: true });
+        }
+
+        // The prompt says what this place is and what the agent must NOT do. Committing is the
+        // user's action from the panel (Claude Code's contract), and a commit made here would also
+        // be made with credentials the agent should never be handed.
+        const repo_context =
+          `You are working in a git working copy of the repository ${repo_full.repo.remote_url.replace(/\/\/[^@]*@/, '//')} for Xuda project "${project_name || target_app_id}".\n` +
+          `Your current working directory is the checkout. The branch ${prepared.branch} is already checked out for you.\n` +
+          `Edit files directly with your normal file tools. Do NOT run git: no commit, no push, no branch, no stash, no checkout. The person you are working with reviews your changes and commits them from Xuda, so leave the working tree dirty and simply describe what you changed.\n` +
+          `Do not deploy or publish anything either.`;
+        const repo_prompt = `[System]\n${repo_context}\n\n${CLARIFYING_QUESTIONS_INSTRUCTION}\n\n[User request]\n${prompt}`;
+
+        const repo_resume_id = conversation_doc.codex_session_id && conversation_doc.codex_session_host === code_run_host() ? conversation_doc.codex_session_id : null;
+        if (job_id) {
+          try {
+            await jobs_ms.update_job({ job_id, is_background: true, current_step_name: 'streaming results' });
+          } catch (e) {}
+        }
+
+        const repo_run_ret = await start_code_run({
+          uid,
+          profile_id,
+          app_id: account_profile_info.app_id,
+          target_app_id,
+          conversation_id,
+          conversation_doc,
+          reference_id: conversation_doc.reference_id,
+          job_id,
+          prompt: repo_prompt,
+          prompt_conversation_item_id,
+          response_conversation_item_id,
+          local_cwd: prepared.dir,
+          watch_paths: [prepared.dir],
+          app_obj: vibe_app_obj,
+          attachments,
+          codex_model: req.codex_model || req.ai_model,
+          resume_session_id: repo_resume_id,
+          repo_id: repo_full.repo._id,
+          branch: prepared.branch,
+          base_sha: prepared.base_sha,
+          pre_dirty: prepared.pre_dirty,
+        });
+
+        if (repo_run_ret.code < 0) {
+          const failed_msg = "I couldn't start that just now. Please try again in a moment.";
+          emitToDashboard('response_start');
+          streamText(failed_msg);
+          emitToDashboard('stream_end', undefined, { error: true });
+          return await saveAssistantItem(failed_msg, { is_request_error: true });
+        }
+        return { code: 1, job_self_finalizes: true, data: { id: response_conversation_item_id, code_run_id: repo_run_ret.data?.run_id, state: repo_run_ret.data?.state } };
+      }
+
       // Plan A: static websites have no VPS — codex edits the source on the
       // pinned studio filesystem directly (local-fs mode), no SSH. The source
       // dir is <studio_drive_path>/<account_project_id>/<source.folder_path>.
@@ -8788,25 +10899,46 @@ ${conversation_history || `User (dashboard): ${prompt}`}
         }
         const sw_context = `You are operating in vibe mode for the Xuda static website "${project_name || target_app_id}" (app_id: ${target_app_id}).\nThe site's source files are in your current working directory — edit them directly. This is the editable source, not the live site; after you finish, tell the user to click Publish to ship it live. Do not deploy or publish anything yourself.`;
         const sw_prompt = `[System]\n${sw_context}\n\n${CLARIFYING_QUESTIONS_INSTRUCTION}\n\n[User request]\n${prompt}`;
-        const codex_ret = await execute_codex_request({ ...req, ip: undefined, local_cwd: site_dir, conversation_id, conversation_doc, prompt: sw_prompt, attachments, stream: false }, job_id, headers);
-        const sw_failed = codex_ret.code < 0;
-        // Never echo the raw codex error to the client — it leaks the command,
-        // env, model + provider billing details. Log it; show a clean card.
-        if (sw_failed) console.error('[vibe] static-site codex request failed:', get_error_message(codex_ret.data, 'codex error'));
-        const codex_events = codex_ret?.data?.events || [];
-        const last_message = [...codex_events].reverse().find((event) => event?.item?.type === 'agent_message' && event.item.text)?.item?.text;
-        const raw_response_text = sw_failed ? "I couldn't finish that change just now. Please try again in a moment." : last_message || 'Done editing the site source. Click Publish to ship it live.';
-        const { prose, questions } = extract_xuda_questions(raw_response_text);
-        const response_text = prose || raw_response_text;
-        emitToDashboard('response_start');
-        streamText(response_text);
-        emitToDashboard('stream_end', undefined, { ...(questions ? { questions } : {}), ...(sw_failed ? { error: true } : {}) });
-        conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
-        conversation_doc.ts = Date.now();
-        conversation_doc.stat = 3;
-        conversation_doc.process_stat = sw_failed ? 'partial' : 'full';
-        await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
-        return await saveAssistantItem(response_text, { ...(sw_failed ? { is_request_error: true } : { codex_result: codex_ret }), ...(questions ? { questions } : {}) });
+        // UI-220: same durable run as the VPS path, with the site's source dir as the working
+        // tree instead of a remote host. A site edit is where the file list is at its most useful,
+        // since Codex works through apply_patch here rather than shell commands.
+        const sw_resume_id = conversation_doc.codex_session_id && conversation_doc.codex_session_host === code_run_host() ? conversation_doc.codex_session_id : null;
+        if (job_id) {
+          try {
+            await jobs_ms.update_job({ job_id, is_background: true, current_step_name: 'streaming results' });
+          } catch (e) {}
+        }
+        const sw_run_ret = await start_code_run({
+          uid,
+          profile_id,
+          app_id: account_profile_info.app_id,
+          target_app_id,
+          conversation_id,
+          conversation_doc,
+          reference_id: conversation_doc.reference_id,
+          job_id,
+          prompt: sw_prompt,
+          prompt_conversation_item_id,
+          response_conversation_item_id,
+          local_cwd: site_dir,
+          app_obj: vibe_app_obj,
+          attachments,
+          codex_model: req.codex_model || req.ai_model,
+          resume_session_id: sw_resume_id,
+        });
+        if (sw_run_ret.code < 0) {
+          const sw_failed_msg = "I couldn't start that change just now. Please try again in a moment.";
+          emitToDashboard('response_start');
+          streamText(sw_failed_msg);
+          emitToDashboard('stream_end', undefined, { error: true });
+          conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
+          conversation_doc.ts = Date.now();
+          conversation_doc.stat = 3;
+          conversation_doc.process_stat = 'partial';
+          await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+          return await saveAssistantItem(sw_failed_msg, { is_request_error: true });
+        }
+        return { code: 1, job_self_finalizes: true, data: { id: response_conversation_item_id, code_run_id: sw_run_ret.data?.run_id, state: sw_run_ret.data?.state } };
       }
 
       if (!vps_ip) {
@@ -8869,63 +11001,70 @@ ${conversation_history || `User (dashboard): ${prompt}`}
           : '');
       const codex_prompt = `[System]\n${project_context_block}\n\n${CLARIFYING_QUESTIONS_INSTRUCTION}\n\n[User request]\n${prompt}`;
 
-      // Override ip explicitly so the `...req` spread can't smuggle in
-      // req.ip (browser IP). conversation_id / conversation_doc / prompt /
-      // attachments / stream stay after the spread for the same reason.
-      // agent_mcp wires the scoped firewall tools into codex over MCP.
-      const codex_ret = await execute_codex_request(
-        {
-          ...req,
-          ip: vps_ip,
-          conversation_id,
-          conversation_doc,
-          prompt: codex_prompt,
-          attachments,
-          stream: false,
-          // Deliberate: this build runs on the CUSTOMER'S OWN VPS over SSH and has to install
-          // packages, write outside a workspace and restart services there, so it keeps full
-          // access. Stated explicitly now that the global default is confined, so the choice
-          // is visible instead of inherited. Nothing on Xuda infrastructure may set this.
-          bypass_sandbox: true,
-          ...(agent_key ? { agent_mcp: { url: 'http://localhost:3012/mcp', bearer_env_var: 'XUDA_AGENT_KEY', bearer_value: agent_key } } : {}),
-        },
-        job_id,
-        headers,
-      );
-      // The ephemeral scoped key has served its purpose; revoke it so it can't
-      // outlive the run. A Full Stack VPS's persistent key is kept (not ephemeral).
-      if (agent_key && agent_key_ephemeral) {
+      // UI-220. The run is started, not awaited. It becomes a detached process with its own
+      // JSONL log and `code_run` doc, so it survives this process, streams while it works, and
+      // finishes the conversation itself (see finalize_code_run). This turn's job is marked
+      // background so the 10 minute job sweeper leaves it alone; the run closes it at the end.
+      //
+      // The Codex THREAD is the chat's own: a session recorded on this host is resumed, so turn 2
+      // already knows what turn 1 did to the box instead of rediscovering it. A session from
+      // another host (region cutover) falls back to a cold start rather than failing.
+      const resume_session_id = conversation_doc.codex_session_id && conversation_doc.codex_session_host === code_run_host() ? conversation_doc.codex_session_id : null;
+
+      if (job_id) {
         try {
-          await db_module.delete_couch_doc('xuda_api_keys', agent_key);
+          await jobs_ms.update_job({ job_id, is_background: true, current_step_name: 'streaming results' });
         } catch (e) {}
       }
-      const vibe_failed = codex_ret.code < 0;
-      // Never echo the raw codex/SSH error to the client — it leaks the remote
-      // host, the full command (MCP url, bearer env var, model, dangerous flags)
-      // and provider billing details. Log it server-side; the client gets a
-      // clean message rendered as an error card (error flag below).
-      if (vibe_failed) console.error('[vibe] VPS codex request failed:', get_error_message(codex_ret.data, 'codex error'));
-      const codex_events = codex_ret?.data?.events || [];
-      const last_message = [...codex_events].reverse().find((event) => event?.item?.type === 'agent_message' && event.item.text)?.item?.text;
-      const raw_response_text = vibe_failed ? "I couldn't finish that request just now. Please try again in a moment." : last_message || 'Vibe request completed.';
-
-      // Pull the structured questions block (if any) off the tail of the
-      // response. response_text is just the prose; questions ride alongside
-      // on the stream_end event + the persisted assistant item.
-      const { prose, questions } = extract_xuda_questions(raw_response_text);
-      const response_text = prose || raw_response_text;
 
-      emitToDashboard('response_start');
-      streamText(response_text);
-      emitToDashboard('stream_end', undefined, { ...(questions ? { questions } : {}), ...(vibe_failed ? { error: true } : {}) });
+      const run_ret = await start_code_run({
+        uid,
+        profile_id,
+        app_id: account_profile_info.app_id,
+        target_app_id,
+        conversation_id,
+        conversation_doc,
+        reference_id: conversation_doc.reference_id,
+        job_id,
+        prompt: codex_prompt,
+        prompt_conversation_item_id,
+        response_conversation_item_id,
+        ip: vps_ip,
+        app_obj: vibe_app_obj,
+        attachments,
+        codex_model: req.codex_model || req.ai_model,
+        resume_session_id,
+        // Deliberate: this build runs on the CUSTOMER'S OWN VPS over SSH and has to install
+        // packages, write outside a workspace and restart services there, so it keeps full
+        // access. Stated explicitly now that the global default is confined, so the choice
+        // is visible instead of inherited. Nothing on Xuda infrastructure may set this.
+        bypass_sandbox: true,
+        ...(agent_key ? { agent_mcp: { url: 'http://localhost:3012/mcp', bearer_env_var: 'XUDA_AGENT_KEY', bearer_value: agent_key } } : {}),
+        // The ephemeral scoped key must outlive THIS function now (the run is still using it over
+        // MCP), so the run revokes it when it finishes. A Full Stack VPS's persistent key is kept.
+        ...(agent_key && agent_key_ephemeral ? { revoke_api_key: agent_key } : {}),
+      });
 
-      conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
-      conversation_doc.ts = Date.now();
-      conversation_doc.stat = 3;
-      conversation_doc.process_stat = vibe_failed ? 'partial' : 'full';
-      await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+      if (run_ret.code < 0) {
+        const failed_msg = "I couldn't start that just now. Please try again in a moment.";
+        emitToDashboard('response_start');
+        streamText(failed_msg);
+        emitToDashboard('stream_end', undefined, { error: true });
+        conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
+        conversation_doc.ts = Date.now();
+        conversation_doc.stat = 3;
+        conversation_doc.process_stat = 'partial';
+        await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+        return await saveAssistantItem(failed_msg, { is_request_error: true });
+      }
 
-      return await saveAssistantItem(response_text, { ...(vibe_failed ? { is_request_error: true } : { codex_result: codex_ret }), ...(questions ? { questions } : {}) });
+      // The conversation stays at stat 2 (running) on purpose: the run owns the ending. The
+      // assistant item is written by the run too, so nothing is saved here.
+      //
+      // job_self_finalizes keeps http_module from closing the job when this request returns. The
+      // job has to stay open for the whole run, because Stop aborts BY job id and the run watches
+      // that same flag.
+      return { code: 1, job_self_finalizes: true, data: { id: response_conversation_item_id, code_run_id: run_ret.data?.run_id, state: run_ret.data?.state } };
     }
 
     // ── AI plugin build / modify ───────────────────────────────────────────
@@ -10022,6 +12161,8 @@ const ai_chat_conversation = async function (req, job_id, headers) {
     reference_id: conversation_doc.reference_id,
     direction: 'out',
     role: 'user',
+    // My own prompt is read the moment I type it, same as the dashboard chat path does.
+    read: { [uid]: Date.now() },
     job_id,
     metadata,
   };
@@ -10920,6 +13061,20 @@ const add_conversation_item = async function (uid, profile_id, conversation_id,
       },
     ];
 
+    // Same story as the contact thread below: a conversation is not guaranteed to carry an
+    // AI thread. create_conversation always mints one, but the ticket paths do not, either
+    // because they never asked for one (ticket_module's mirror conversation) or because the
+    // call failed and was swallowed (_contact_form_create_ticket). Minted here rather than
+    // passed on as undefined, which the SDK turns into `/conversations/undefined/items`.
+    if (!conversation_doc.reference_conversation_id) {
+      const conversation_obj = await create_openai_conversation();
+      conversation_doc.reference_conversation_id = conversation_obj.id;
+      conversation_doc.ts = Date.now();
+      const backfill_ret = await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+      conversation_doc._rev = backfill_ret?.rev || conversation_doc._rev;
+      console.log(`[ai_module] opened a missing AI thread for conversation ${conversation_id}: ${conversation_obj.id}`);
+    }
+
     let item;
     try {
       item = await client.conversations.items.create(conversation_doc.reference_conversation_id, {
@@ -10928,12 +13083,39 @@ const add_conversation_item = async function (uid, profile_id, conversation_id,
     } catch (err) {
       throw err;
     }
+    // The item is filed twice: once on this conversation, and once on the CONTACT's own
+    // thread, which is what lets the contact card carry the whole history with that person
+    // across every conversation they appear in.
+    //
+    // That contact thread is not guaranteed to exist. add_contact opens one only for a
+    // contact it did NOT classify as spam (a spam contact gets no AI work spent on it at
+    // all), and a contact created before the field existed has none either. Handing the
+    // missing id straight to the API is what used to break the inbound mail pipeline: the
+    // SDK builds `/conversations/undefined/items` and throws "Path parameters result in
+    // path with invalid segments", which fails the whole email job, so the message never
+    // finished processing and the mail client showed a red Error badge on it once the
+    // attempts ran out (repro 2026-08-13, eml_bmaaaaae, sender b0001@xuda.app).
+    //
+    // So the thread is opened here on demand for a real contact, and a spam contact is
+    // skipped rather than given one, which is exactly the rule add_contact applies. The
+    // skip is not permanent: un-marking a contact as spam backfills the thread and
+    // reprocesses their mail (account_module not_spam_contact).
     if (conversation_doc.reference_type === 'contacts' && contact_id) {
       try {
         let contact_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, contact_id);
-        const item = await client.conversations.items.create(contact_doc.contact_reference_conversation_id, {
-          items,
-        });
+        if (contact_doc && !contact_doc.contact_reference_conversation_id && !contact_doc.is_spam) {
+          const conversation_obj = await create_openai_conversation();
+          contact_doc.contact_reference_conversation_id = conversation_obj.id;
+          contact_doc.ts = Date.now();
+          const backfill_ret = await db_module.save_app_couch_doc_native(account_profile_info.app_id, contact_doc);
+          contact_doc._rev = backfill_ret?.rev || contact_doc._rev;
+          console.log(`[ai_module] opened a missing AI thread for contact ${contact_id}: ${conversation_obj.id}`);
+        }
+        if (contact_doc?.contact_reference_conversation_id) {
+          await client.conversations.items.create(contact_doc.contact_reference_conversation_id, {
+            items,
+          });
+        }
       } catch (err) {
         throw err;
       }
@@ -11228,6 +13410,8 @@ Return only the email body.`;
         role: 'user',
         auto_response: true,
         widget_source: true,
+        // Sent under this account, so it is not unread for this account.
+        read: { [uid]: Date.now() },
         rtl: _common.detectRTL(response_text),
       };
       await db_module.save_app_couch_doc(account_profile_info.app_id, reply_item);
@@ -12540,6 +14724,74 @@ export const modify_profile_avatar = async function (req, job_id, headers) {
   }
 };
 
+// What the Contacts tab is holding for you that is NOT a pending request: messages on
+// contacts you have not read yet, the same number the contact card shows on its own badge.
+// The tab used to count requests only, so a card sitting on a red 1 was invisible from
+// every other tab and the strip disagreed with the grid underneath it.
+//
+// Two view reads for the whole account, not two per contact: the counts view is grouped by
+// reference_id and the read view by [me, reference_id], so both come back as one row per
+// reference and the contact ids just pick the rows that belong to a contact (an agent or a
+// mini app is a reference too, and those are not this tab's business).
+const get_contacts_unread_total = async function (uid, account_profile_info) {
+  try {
+    const app_id = account_profile_info.app_id;
+    const opt = {
+      selector: { docType: 'contact', stat: { $lt: 4 } },
+      fields: ['_id'],
+      limit: 9999,
+    };
+
+    // Same visibility rule the contacts grid uses, so the badge can never claim unread
+    // messages sitting on a contact this profile is not allowed to see.
+    if (!account_profile_info.is_main) {
+      opt.selector.account_profiles = { $in: [account_profile_info.account_profile_id] };
+    } else {
+      const active_profiles = await db_module.find_app_couch_query(app_id, {
+        selector: { docType: 'account_profile', uid: account_profile_info.uid, stat: { $lt: 4 } },
+        fields: ['_id'],
+        limit: 9999,
+      });
+      const active_profile_ids = (active_profiles.docs || []).map((profile) => profile._id).filter(Boolean);
+      opt.selector.account_profiles = { $in: active_profile_ids.length ? active_profile_ids : [account_profile_info.account_profile_id] };
+    }
+
+    const contacts_ret = await db_module.find_app_couch_query(app_id, opt);
+    const contact_ids = new Set((contacts_ret?.docs || []).map((doc) => doc._id));
+    if (!contact_ids.size) return 0;
+
+    const counts_ret = await db_module.get_app_couch_view(app_id, 'chat_conversation_item_counts', {
+      reduce: true,
+      group_level: 1,
+    });
+    const read_ret = await db_module.get_app_couch_view(app_id, 'chat_conversation_item_read', {
+      reduce: true,
+      group_level: 2,
+
+      startkey: [uid, ''],
+      endkey: [uid, 'zzzzzz'],
+    });
+
+    const read_by_contact = {};
+    for (const row of read_ret?.rows || []) {
+      read_by_contact[row.key?.[1]] = row.value;
+    }
+
+    let total = 0;
+    for (const row of counts_ret?.rows || []) {
+      const contact_id = row.key?.[0];
+      if (!contact_ids.has(contact_id)) continue;
+      total += Math.max(0, (row.value || 0) - (read_by_contact[contact_id] || 0));
+    }
+
+    return total;
+  } catch (err) {
+    // An account whose project is missing these views (they are added by login maintenance)
+    // gets the request count alone rather than an error on the whole strip.
+    return 0;
+  }
+};
+
 export const get_ai_workspace_pending_counts = async function (req, job_id, headers) {
   const { uid } = req;
   const account_profile_info = await get_active_account_profile_info(uid);
@@ -12567,9 +14819,11 @@ export const get_ai_workspace_pending_counts = async function (req, job_id, head
             data['apps'] = item.value;
             break;
 
+          // Two separate rows at group_level 999, so this has to add up rather than assign:
+          // whichever landed second used to overwrite the first.
           case 'contact_connection':
           case 'contact':
-            data['contacts'] = item.value;
+            data['contacts'] = (data['contacts'] || 0) + item.value;
             break;
 
           case 'account_profile':
@@ -12585,6 +14839,20 @@ export const get_ai_workspace_pending_counts = async function (req, job_id, head
         }
       }
     }
+
+    // Reported SEPARATELY from data.contacts, never folded into it. `contacts` is the
+    // PENDING count and the dashboard puts it on the filter trigger and beside the
+    // "Pending" filter option, where a number that also included unread messages would be
+    // a lie about how many requests are waiting. The tab badge is the only thing that
+    // wants the two added together, and it does that addition itself.
+    //
+    // Counted for every profile, not just the main one: the pending block above is
+    // main-only because only the main profile answers connection requests.
+    const contacts_unread = await get_contacts_unread_total(uid, account_profile_info);
+    if (contacts_unread) {
+      data['contacts_unread'] = contacts_unread;
+    }
+
     return { code: 111, data };
   } catch (err) {
     return { code: -111, data: err.message };
@@ -12812,8 +15080,8 @@ const get_ai_chat_info = async function (uid, conversation_doc) {
     const reference_doc = _.cloneDeep(doc);
     doc = await db_module.get_app_couch_doc_native(reference_doc.shared_from_app_id, reference_doc.share_item_id);
     doc.reference_doc = reference_doc;
-    doc.pinned = reference_doc.pinned ?? doc.pinned;
-    doc.stat = reference_doc.stat ?? doc.stat;
+    // UI-221 / UI-222
+    apply_recipient_marks(doc, reference_doc);
   }
 
   const reference_id = doc.reference_id || '';
@@ -12855,11 +15123,8 @@ const get_mini_app_info = async function (uid, prog_doc) {
     const reference_doc = _.cloneDeep(doc);
     doc = await db_module.get_app_couch_doc_native(reference_doc.studio_meta.shared_from_app_id, reference_doc.studio_meta.share_item_id);
     doc.reference_doc = reference_doc;
-    doc.stat = reference_doc.stat ?? doc.stat;
-    doc.studio_meta = {
-      ...(doc.studio_meta || {}),
-      pinned: reference_doc?.studio_meta?.pinned ?? doc?.studio_meta?.pinned,
-    };
+    // UI-221 / UI-222
+    apply_recipient_marks(doc, reference_doc);
   }
 
   if (doc?.studio_meta?.createdByUid) {
@@ -13034,6 +15299,125 @@ export const unpin_ai_agent = async function (req, job_id, headers) {
   }
 };
 
+// ─── UI-221: favorites ────────────────────────────────────────────────────────────────
+// A second, softer mark than pin. Pin is about the WORKING SET (it puts the item in the
+// pinned bar, which holds a handful of things at a time); favorite is about what the user
+// keeps coming back to, and it only ever answers a filter. They are deliberately separate
+// flags: an item can be both, and un-pinning something you use every day should not lose
+// the fact that you like it.
+//
+// The flag lives where the pinned one lives for each kind, so the two read the same way in
+// a doc and in a Mango selector: `favorite` on a chat_conversation, `studio_meta.favorite`
+// on a studio doc (mini app / AI agent).
+const _set_ai_favorite = async function ({ doc_id, on_studio_meta, favorite, app_id }) {
+  const doc = await db_module.get_app_couch_doc_native(app_id, doc_id);
+
+  if (on_studio_meta) {
+    doc.studio_meta = doc.studio_meta || {};
+    doc.studio_meta.favorite = favorite;
+  } else {
+    doc.favorite = favorite;
+  }
+
+  return await db_module.save_app_couch_doc(app_id, doc);
+};
+
+export const favorite_ai_chat = async function (req) {
+  const { uid, conversation_id } = req;
+  try {
+    const account_profile_info = await get_active_account_profile_info(uid);
+    const save_ret = await _set_ai_favorite({ doc_id: conversation_id, favorite: true, app_id: account_profile_info.app_id });
+
+    log_chat_activity(uid, conversation_id, 'favorited', { by: 'user' }, account_profile_info.app_id);
+
+    return save_ret;
+  } catch (err) {
+    return {
+      code: -24,
+      data: err.message,
+    };
+  }
+};
+
+export const unfavorite_ai_chat = async function (req) {
+  const { uid, conversation_id } = req;
+  try {
+    const account_profile_info = await get_active_account_profile_info(uid);
+    const save_ret = await _set_ai_favorite({ doc_id: conversation_id, favorite: false, app_id: account_profile_info.app_id });
+
+    log_chat_activity(uid, conversation_id, 'unfavorited', { by: 'user' }, account_profile_info.app_id);
+
+    return save_ret;
+  } catch (err) {
+    return {
+      code: -24,
+      data: err.message,
+    };
+  }
+};
+
+export const favorite_mini_app = async function (req) {
+  const { uid, prog_id } = req;
+  try {
+    const account_profile_info = await get_active_account_profile_info(uid);
+    return await _set_ai_favorite({ doc_id: prog_id, on_studio_meta: true, favorite: true, app_id: account_profile_info.app_id });
+  } catch (err) {
+    return {
+      code: -24,
+      data: err.message,
+    };
+  }
+};
+
+export const unfavorite_mini_app = async function (req) {
+  const { uid, prog_id } = req;
+  try {
+    const account_profile_info = await get_active_account_profile_info(uid);
+    return await _set_ai_favorite({ doc_id: prog_id, on_studio_meta: true, favorite: false, app_id: account_profile_info.app_id });
+  } catch (err) {
+    return {
+      code: -24,
+      data: err.message,
+    };
+  }
+};
+
+// Agents resolve their app the way pin_ai_agent does (the account's default project),
+// not through the active profile, because an agent doc is account-level.
+export const favorite_ai_agent = async function (req) {
+  const { uid, agent_id } = req;
+  try {
+    const app_id = await get_account_default_project_id(uid);
+    const save_ret = await _set_ai_favorite({ doc_id: agent_id, on_studio_meta: true, favorite: true, app_id });
+
+    log_agent_activity(uid, agent_id, 'favorited', { by: 'user' }, app_id);
+
+    return save_ret;
+  } catch (err) {
+    return {
+      code: -24,
+      data: err.message,
+    };
+  }
+};
+
+export const unfavorite_ai_agent = async function (req) {
+  const { uid, agent_id } = req;
+  try {
+    const app_id = await get_account_default_project_id(uid);
+    const save_ret = await _set_ai_favorite({ doc_id: agent_id, on_studio_meta: true, favorite: false, app_id });
+
+    log_agent_activity(uid, agent_id, 'unfavorited', { by: 'user' }, app_id);
+
+    return save_ret;
+  } catch (err) {
+    return {
+      code: -24,
+      data: err.message,
+    };
+  }
+};
+
 export const get_transcript = async function (uid, app_id, conversation_id, account_profile_info, filename) {
   async function streamToBuffer(fileStream) {
     const chunks = [];
@@ -20277,6 +22661,8 @@ const contact_ticket_conversation = async function (req, job_id, headers) {
       direction: 'out',
       role: 'user',
       auto_response: _auto_response || undefined,
+      // The reply went out from this desk, so it is not waiting to be read here.
+      read: { [uid]: Date.now() },
       rtl: _common.detectRTL(body),
     };
     const save_ret = await db_module.save_app_couch_doc(sender_app_id, out_conversation_item_obj);