@xuda.io/ai_module 1.1.5656 → 1.1.5658

package/index_ms.mjs

@@ -69,10 +69,30 @@ export const git_repo_list = async function (...args) {
   return await broker.send_to_queue("git_repo_list", ...args);
 };
 
+export const xudex_key_set = async function (...args) {
+  return await broker.send_to_queue("xudex_key_set", ...args);
+};
+
+export const xudex_key_list = async function (...args) {
+  return await broker.send_to_queue("xudex_key_list", ...args);
+};
+
+export const xudex_key_delete = async function (...args) {
+  return await broker.send_to_queue("xudex_key_delete", ...args);
+};
+
+export const xudex_engine_list = async function (...args) {
+  return await broker.send_to_queue("xudex_engine_list", ...args);
+};
+
 export const git_repo_disconnect = async function (...args) {
   return await broker.send_to_queue("git_repo_disconnect", ...args);
 };
 
+export const xudex_run = async function (...args) {
+  return await broker.send_to_queue("xudex_run", ...args);
+};
+
 export const git_repo_status = async function (...args) {
   return await broker.send_to_queue("git_repo_status", ...args);
 };
@@ -113,6 +133,10 @@ export const unarchive_ai_chat = async function (...args) {
   return await broker.send_to_queue("unarchive_ai_chat", ...args);
 };
 
+export const rename_ai_chat = async function (...args) {
+  return await broker.send_to_queue("rename_ai_chat", ...args);
+};
+
 export const get_ai_agent_info = async function (...args) {
   return await broker.send_to_queue("get_ai_agent_info", ...args);
 };
@@ -153,6 +177,10 @@ export const delete_mini_app = async function (...args) {
   return await broker.send_to_queue("delete_mini_app", ...args);
 };
 
+export const rename_mini_app = async function (...args) {
+  return await broker.send_to_queue("rename_mini_app", ...args);
+};
+
 export const start_cli_agent_conversation = async function (...args) {
   return await broker.send_to_queue("start_cli_agent_conversation", ...args);
 };
@@ -289,6 +317,10 @@ export const create_mini_app = async function (...args) {
   return await broker.send_to_queue("create_mini_app", ...args);
 };
 
+export const emit_mini_app_doc_updated = async function (...args) {
+  return await broker.send_to_queue("emit_mini_app_doc_updated", ...args);
+};
+
 export const pin_ai_chat = async function (...args) {
   return await broker.send_to_queue("pin_ai_chat", ...args);
 };

package/index_msa.mjs

@@ -69,10 +69,30 @@ export const git_repo_list =  function (...args) {
    broker.send_to_queue_async("git_repo_list", ...args);
 };
 
+export const xudex_key_set =  function (...args) {
+   broker.send_to_queue_async("xudex_key_set", ...args);
+};
+
+export const xudex_key_list =  function (...args) {
+   broker.send_to_queue_async("xudex_key_list", ...args);
+};
+
+export const xudex_key_delete =  function (...args) {
+   broker.send_to_queue_async("xudex_key_delete", ...args);
+};
+
+export const xudex_engine_list =  function (...args) {
+   broker.send_to_queue_async("xudex_engine_list", ...args);
+};
+
 export const git_repo_disconnect =  function (...args) {
    broker.send_to_queue_async("git_repo_disconnect", ...args);
 };
 
+export const xudex_run =  function (...args) {
+   broker.send_to_queue_async("xudex_run", ...args);
+};
+
 export const git_repo_status =  function (...args) {
    broker.send_to_queue_async("git_repo_status", ...args);
 };
@@ -113,6 +133,10 @@ export const unarchive_ai_chat =  function (...args) {
    broker.send_to_queue_async("unarchive_ai_chat", ...args);
 };
 
+export const rename_ai_chat =  function (...args) {
+   broker.send_to_queue_async("rename_ai_chat", ...args);
+};
+
 export const get_ai_agent_info =  function (...args) {
    broker.send_to_queue_async("get_ai_agent_info", ...args);
 };
@@ -153,6 +177,10 @@ export const delete_mini_app =  function (...args) {
    broker.send_to_queue_async("delete_mini_app", ...args);
 };
 
+export const rename_mini_app =  function (...args) {
+   broker.send_to_queue_async("rename_mini_app", ...args);
+};
+
 export const start_cli_agent_conversation =  function (...args) {
    broker.send_to_queue_async("start_cli_agent_conversation", ...args);
 };
@@ -289,6 +317,10 @@ export const create_mini_app =  function (...args) {
    broker.send_to_queue_async("create_mini_app", ...args);
 };
 
+export const emit_mini_app_doc_updated =  function (...args) {
+   broker.send_to_queue_async("emit_mini_app_doc_updated", ...args);
+};
+
 export const pin_ai_chat =  function (...args) {
    broker.send_to_queue_async("pin_ai_chat", ...args);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xuda.io/ai_module",
-  "version": "1.1.5656",
+  "version": "1.1.5658",
   "description": "Xuda AI Module",
   "main": "index.mjs",
   "type": "module",
@@ -18,7 +18,7 @@
     "openai": "^6.7.0",
     "puppeteer-extra": "^3.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",
-    "sharp": "^0.34.4",
+    "sharp": "^0.35.0",
     "uglify-js": "^3.19.3",
     "utf8": "^3.0.0",
     "vm2": "^3.10.0",

package/xudex_engines.mjs

@@ -0,0 +1,323 @@
+// Xudex engines: the seam between "an agent did some work" and "which CLI did it".
+//
+// docs/plans/xudex.md 5.1. An engine is four things and no more:
+//
+//   1. AUTH            what environment it needs to be allowed to run
+//   2. A LAUNCH        the argv, including how to resume an existing thread
+//   3. A THREAD HANDLE the id that makes turn 2 a continuation instead of a cold start
+//   4. A PARSER        its streaming output, mapped onto one vocabulary
+//
+// Everything else is already engine-agnostic, and that is not luck: UI-226 deliberately
+// made file capture REPOSITORY-based (`git status` minus what was dirty at the start,
+// `git diff HEAD`) rather than asking the agent what it changed. So diffs, revert, the
+// file list, commit, push and the PR all work identically whatever ran, and adding an
+// engine cannot break them. That decision is why multi-engine costs a parser here instead
+// of a rewrite everywhere.
+//
+// ── The normalized vocabulary ──────────────────────────────────────────────────────────
+// Every adapter maps its own output onto these, and nothing above this file may branch on
+// the engine. If a caller ever needs to ask "was this codex", the abstraction has failed.
+//
+//   { type: 'session', session_id }        the thread handle, for resuming
+//   { type: 'phase',   text }              what to show while it works
+//   { type: 'command', command, stage }    a shell command it ran
+//   { type: 'message', text }              words for the customer
+//   { type: 'usage',   input_tokens, output_tokens }
+//   { type: 'error',   message }
+//   { type: 'done',    ok }
+//
+// ── Verification status, stated plainly ────────────────────────────────────────────────
+// The CODEX adapter mirrors the argv and event handling already proven in this module
+// (`exec --json`, `exec resume`, `thread.started`, `item.completed`), so it is a
+// restatement of working code. The CLAUDE CODE adapter is written to that CLI's documented
+// contract and is NOT yet verified against the real binary: it is not installed on dev and
+// there is no BYOK key to run it with. Its flags and event names therefore live in config
+// so a mismatch is a config fix rather than a code change, and it must be exercised
+// against the real CLI before anyone is told it works.
+
+import path from 'node:path';
+
+if (!global._conf) {
+  global._conf = (await import(path.join(process.env.XUDA_HOME, 'common', 'load_conf.mjs'))).loadConf();
+}
+
+const engines_conf = () => global._conf.xudex?.engines || {};
+
+const num = (...values) => {
+  for (const v of values) {
+    if (typeof v === 'number' && Number.isFinite(v)) return v;
+    if (typeof v === 'string' && v.trim() && Number.isFinite(Number(v))) return Number(v);
+  }
+  return 0;
+};
+
+// Token counts arrive under a dozen different spellings depending on the engine and its
+// version, so normalizing them is worth doing once here rather than at every call site.
+// This mirrors normalize_codex_usage in index.mjs, widened for the other providers.
+export const normalize_usage = function (usage) {
+  if (!usage || typeof usage !== 'object') return { input_tokens: 0, output_tokens: 0 };
+  return {
+    input_tokens: num(
+      usage.input_tokens,
+      usage.inputTokens,
+      usage.prompt_tokens,
+      usage.promptTokens,
+      usage.total_input_tokens,
+      usage.total_token_usage?.input_tokens,
+      usage.totalTokenUsage?.inputTokens,
+    ),
+    output_tokens: num(
+      usage.output_tokens,
+      usage.outputTokens,
+      usage.completion_tokens,
+      usage.completionTokens,
+      usage.total_output_tokens,
+      usage.total_token_usage?.output_tokens,
+      usage.totalTokenUsage?.outputTokens,
+    ),
+  };
+};
+
+// Both engines speak JSON lines, so the line splitter is shared. It keeps a partial tail
+// between chunks, because a stream chunk boundary lands mid-line often enough that not
+// handling it looks like random missing events.
+export const create_line_parser = function (on_object) {
+  let buffer = '';
+  return function (chunk) {
+    buffer += chunk;
+    const lines = buffer.split(/\r?\n/);
+    buffer = lines.pop() || '';
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        on_object(JSON.parse(line));
+      } catch (err) {
+        // A non-JSON line is the CLI talking to a human (a warning, a banner). It is not an
+        // error and it is not an event; dropping it is correct.
+      }
+    }
+  };
+};
+
+// ── Codex ──────────────────────────────────────────────────────────────────────────────
+const codex_adapter = {
+  key: 'codex',
+  label: 'Codex',
+  provider: 'openai',
+  byok: false,
+
+  // `exec resume [OPTIONS] <SESSION_ID> [PROMPT]`: the id and the prompt are POSITIONAL and
+  // go last, and `--sandbox` is rejected outright on a resume because a resumed session
+  // keeps the sandbox it was created with. Both were verified against the CLI (0.128.0)
+  // when the vibe path was built; this is a restatement of that, not a new claim.
+  build_args({ model, resume_session_id, sandbox, bypass_sandbox } = {}) {
+    const resuming = !!resume_session_id;
+    const args = resuming ? ['exec', 'resume', '--json'] : ['exec', '--json'];
+    if (model) args.push('--model', model);
+    if (bypass_sandbox === true) {
+      args.push('--dangerously-bypass-approvals-and-sandbox');
+    } else if (sandbox && !resuming) {
+      // Without --skip-git-repo-check a sandboxed run refuses to start outside a git repo.
+      args.push('--sandbox', sandbox, '--skip-git-repo-check');
+    } else if (sandbox) {
+      args.push('--skip-git-repo-check');
+    }
+    if (resuming) args.push(resume_session_id);
+    return args;
+  },
+
+  env({ api_key } = {}) {
+    // Codex runs on OUR key by default, which is what makes the free tier usable before a
+    // customer has any key of their own. A BYOK key simply overrides it.
+    return api_key ? { OPENAI_API_KEY: api_key } : {};
+  },
+
+  normalize(event) {
+    if (!event || typeof event !== 'object') return [];
+    switch (event.type) {
+      case 'thread.started':
+        return event.thread_id ? [{ type: 'session', session_id: event.thread_id }, { type: 'phase', text: 'Starting Codex thread' }] : [];
+      case 'turn.started':
+        return [{ type: 'phase', text: 'Working through the request' }];
+      case 'item.started': {
+        const item = event.item || {};
+        return item.type === 'command_execution' ? [{ type: 'command', command: item.command || '', stage: 'start' }] : [];
+      }
+      case 'item.completed': {
+        const item = event.item || {};
+        if (item.type === 'agent_message' && item.text) return [{ type: 'message', text: item.text }];
+        if (item.type === 'command_execution') return [{ type: 'command', command: item.command || '', stage: 'end', exit_code: item.exit_code ?? null }];
+        return [];
+      }
+      case 'turn.completed': {
+        const out = [];
+        if (event.usage) out.push({ type: 'usage', ...normalize_usage(event.usage) });
+        out.push({ type: 'done', ok: true });
+        return out;
+      }
+      case 'turn.failed':
+      case 'error':
+        return [{ type: 'error', message: event.message || event.error?.message || 'the engine reported an error' }];
+      default:
+        return [];
+    }
+  },
+};
+
+// ── Claude Code ────────────────────────────────────────────────────────────────────────
+// BYOK only, deliberately. We do not front Anthropic tokens for customers, so a run without
+// a key is refused before it starts rather than failing halfway with a provider error.
+const claude_code_adapter = {
+  key: 'claude_code',
+  label: 'Claude Code',
+  provider: 'anthropic',
+  byok: true,
+
+  build_args({ model, resume_session_id } = {}) {
+    // `-p` is the non-interactive print mode; stream-json is what makes progress visible
+    // rather than arriving in one lump at the end.
+    const args = ['-p', '--output-format', 'stream-json', '--verbose'];
+    if (model) args.push('--model', model);
+    if (resume_session_id) args.push('--resume', resume_session_id);
+    // The workspace is already the isolation boundary (plan 3.1): the machine exists so
+    // untrusted code can run somewhere that is not our region server. A second permission
+    // prompt inside it would just hang a non-interactive run forever.
+    args.push('--dangerously-skip-permissions');
+    return args;
+  },
+
+  env({ api_key } = {}) {
+    return api_key ? { ANTHROPIC_API_KEY: api_key } : {};
+  },
+
+  normalize(event) {
+    if (!event || typeof event !== 'object') return [];
+    switch (event.type) {
+      case 'system':
+        return event.session_id ? [{ type: 'session', session_id: event.session_id }, { type: 'phase', text: 'Starting Claude Code session' }] : [];
+      case 'assistant': {
+        const out = [];
+        for (const block of event.message?.content || []) {
+          if (block.type === 'text' && block.text) out.push({ type: 'message', text: block.text });
+          // Claude Code reports a shell call as a tool_use block rather than its own event
+          // type, which is the one real shape difference from codex.
+          else if (block.type === 'tool_use') {
+            out.push({ type: 'command', command: block.input?.command || block.name || '', stage: 'start' });
+          }
+        }
+        if (event.message?.usage) out.push({ type: 'usage', ...normalize_usage(event.message.usage) });
+        return out;
+      }
+      case 'result': {
+        const out = [];
+        if (event.session_id) out.push({ type: 'session', session_id: event.session_id });
+        if (event.usage) out.push({ type: 'usage', ...normalize_usage(event.usage) });
+        if (event.is_error || event.subtype === 'error') {
+          out.push({ type: 'error', message: event.result || event.error || 'the engine reported an error' });
+        } else {
+          out.push({ type: 'done', ok: true });
+        }
+        return out;
+      }
+      default:
+        return [];
+    }
+  },
+};
+
+const ADAPTERS = { codex: codex_adapter, claude_code: claude_code_adapter };
+
+// The registry. Config decides which engines a box offers and what binary each one is, so a
+// third engine is a config entry plus one adapter object, which is what plan 5.1 promised.
+export const list_engines = function () {
+  const conf = engines_conf();
+  return Object.keys(conf)
+    .filter((k) => ADAPTERS[k])
+    .map((k) => ({
+      key: k,
+      label: conf[k].label || ADAPTERS[k].label,
+      provider: ADAPTERS[k].provider,
+      byok: ADAPTERS[k].byok,
+      is_default: conf[k].default === true,
+    }));
+};
+
+export const get_engine = function (key) {
+  const conf = engines_conf();
+  const engine_key = key && conf[key] && ADAPTERS[key] ? key : Object.keys(conf).find((k) => conf[k].default === true && ADAPTERS[k]);
+  if (!engine_key) return null;
+  return { ...ADAPTERS[engine_key], command: conf[engine_key].command || engine_key, config: conf[engine_key] };
+};
+
+// Everything needed to actually start a run, in one object, so the caller does not assemble
+// argv by hand and cannot forget the key.
+//
+// A BYOK engine with no key is refused HERE, before anything is spawned. The alternative is
+// a run that starts, burns a workspace slot, and dies on a provider 401 that reads to the
+// customer like our failure.
+export const prepare_launch = function ({ engine: engine_key, model, resume_session_id, api_key, sandbox, bypass_sandbox } = {}) {
+  const engine = get_engine(engine_key);
+  if (!engine) return { error: 'That engine is not available.' };
+  if (engine.byok && !api_key) {
+    return {
+      error: `${engine.label} runs on your own API key. Add an ${engine.provider === 'anthropic' ? 'Anthropic' : engine.provider} API key in settings, then try again.`,
+      needs_key: engine.provider,
+    };
+  }
+  return {
+    engine: engine.key,
+    label: engine.label,
+    command: engine.command,
+    args: engine.build_args({ model, resume_session_id, sandbox, bypass_sandbox }),
+    env: engine.env({ api_key }),
+    resuming: !!resume_session_id,
+  };
+};
+
+// One stream, normalized. The caller gets our vocabulary and never sees the engine's.
+export const create_stream = function (engine_key, on_event) {
+  const engine = get_engine(engine_key);
+  if (!engine) return () => {};
+  return create_line_parser((raw) => {
+    for (const normalized of engine.normalize(raw)) on_event(normalized);
+  });
+};
+
+// Fold a normalized stream into the few things a run has to remember. Kept separate from
+// the parser so a caller can stream for the UI and summarize for the record with one pass.
+export const create_run_state = function () {
+  const state = { session_id: null, messages: [], commands: [], usage: { input_tokens: 0, output_tokens: 0 }, error: null, done: false };
+  return {
+    state,
+    accept(event) {
+      switch (event.type) {
+        case 'session':
+          if (!state.session_id) state.session_id = event.session_id;
+          break;
+        case 'message':
+          state.messages.push(event.text);
+          break;
+        case 'command':
+          if (event.stage === 'start') state.commands.push(event.command);
+          break;
+        case 'usage':
+          // Engines report usage cumulatively in some versions and per-turn in others, so
+          // take the larger rather than summing: summing double-counts a cumulative report,
+          // and that error grows with the length of the conversation.
+          state.usage.input_tokens = Math.max(state.usage.input_tokens, event.input_tokens || 0);
+          state.usage.output_tokens = Math.max(state.usage.output_tokens, event.output_tokens || 0);
+          break;
+        case 'error':
+          // Verbatim, per plan 5.2. With BYOK we cannot see the customer's balance or rate
+          // limits, so a 429 from their account must read as their provider saying no, not
+          // as Xudex breaking.
+          state.error = event.message;
+          break;
+        case 'done':
+          state.done = true;
+          break;
+      }
+      return state;
+    },
+  };
+};

package/xudex_mirror.mjs

@@ -0,0 +1,200 @@
+// Xudex git mirror: how a repository reaches a machine we do not fully trust.
+//
+// docs/plans/xudex.md 9.2. UI-226's verified property is that a repository token never leaves the
+// region server: it is validated by an authenticated ls-remote before anything is stored, kept on a
+// git_repo doc in the account's project database rather than in xuda_master (which replicates
+// fleet-wide), and handed to git only through GIT_ASKPASS so it never lands in an argv, in
+// .git/config, or in the run log the customer sees.
+//
+// Moving the working copy onto a customer machine would break exactly that, because the machine would
+// then need the token to fetch and to push. So it does not get one. The region server keeps a BARE
+// MIRROR per repository and is the only thing that ever authenticates upstream:
+//
+//     upstream  <--(token, here)-->  mirror  <--(no credentials)-->  workspace
+//
+// A push travels workspace -> mirror -> upstream, and only the last leg is authenticated.
+//
+// The mirror pays for itself twice: it is also a warm local cache, so a second clone is a local copy
+// instead of a network fetch. That matters more than it looks. A reclaimed free account (plan 3.4)
+// re-clones every project on its next message and CI clones onto an ephemeral workspace, so without
+// the mirror every one of those is a full fetch against the provider from one address, which is slow
+// and a good way to get our own address rate limited by GitHub.
+//
+// ── One deliberate non-choice ──────────────────────────────────────────────────────────────────
+// This is NOT `git clone --mirror`, despite the name. That sets `remote.origin.mirror`, which makes a
+// later `git push` mean "make the remote look exactly like me", including DELETING upstream branches
+// this copy has not heard about yet. A bare clone with an explicit fetch refspec stores the same
+// content with none of that reach, and every push here names its refspec rather than relying on a
+// default.
+
+import fs from 'fs';
+import path from 'node:path';
+
+const DEFAULTS = {
+  clone_timeout_ms: 10 * 60 * 1000,
+  clone_max_mb: 2048,
+};
+
+// `git_exec` is injected rather than imported: it lives in index.mjs, it is the thing that knows how
+// to hand a token to git without it touching an argv, and a second copy of that is the last thing
+// this codebase needs. `du_mb` likewise wraps the module's own process spawner.
+export const create_mirror = function ({ git_exec, du_mb, mirror_root, clone_timeout_ms, clone_max_mb }) {
+  if (typeof git_exec !== 'function') throw new Error('create_mirror needs git_exec');
+  if (typeof mirror_root !== 'function') throw new Error('create_mirror needs a mirror_root resolver');
+  const CLONE_TIMEOUT_MS = clone_timeout_ms || DEFAULTS.clone_timeout_ms;
+  const CLONE_MAX_MB = clone_max_mb || DEFAULTS.clone_max_mb;
+
+  const mirror_dir = (uid, repo_id) => path.join(mirror_root(), String(uid), `${repo_id}.git`);
+
+  const exists = async (dir) =>
+    await fs.promises
+      .stat(path.join(dir, 'HEAD'))
+      .then(() => true)
+      .catch(() => false);
+
+  return {
+    mirror_dir,
+
+    // Create the mirror on first use, refresh it after that. This is the only function that reads
+    // from the customer's provider, so it is the only one that needs their token to do it.
+    async ensure({ uid, repo }) {
+      const dir = mirror_dir(uid, repo._id);
+      const token = repo.token || null;
+      await fs.promises.mkdir(path.dirname(dir), { recursive: true });
+
+      if (!(await exists(dir))) {
+        await fs.promises.rm(dir, { recursive: true, force: true }).catch(() => {});
+        const cloned = await git_exec({ args: ['clone', '--bare', '--no-tags', repo.remote_url, dir], token, timeout_ms: CLONE_TIMEOUT_MS });
+        if (cloned.exit_code !== 0) {
+          console.error(`[xudex] mirror clone failed for ${repo._id}: exit ${cloned.exit_code}`);
+          return { error: 'Xuda could not clone that repository.' };
+        }
+        // A bare clone carries no fetch refspec, so without this the mirror would never learn about a
+        // new branch again. Set once, at creation, rather than on every refresh.
+        await git_exec({ cwd: dir, args: ['config', 'remote.origin.fetch', '+refs/heads/*:refs/heads/*'] });
+        const size_mb = du_mb ? await du_mb(dir) : 0;
+        if (size_mb > 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 ${CLONE_MAX_MB} MB limit.` };
+        }
+        return { dir, created: true };
+      }
+
+      const fetched = await git_exec({ cwd: dir, args: ['fetch', '--prune', 'origin'], token, timeout_ms: CLONE_TIMEOUT_MS });
+      // A stale mirror still serves a clone, so a failed refresh is a warning rather than an error:
+      // the customer gets slightly old code instead of no code, and the next run tries again.
+      if (fetched.exit_code !== 0) console.warn(`[xudex] mirror fetch failed for ${repo._id}: exit ${fetched.exit_code}`);
+      return { dir, created: false, stale: fetched.exit_code !== 0 };
+    },
+
+    // Clone a workspace from the mirror. No token is passed and none is needed, which is the whole
+    // point: this is the call that runs against the machine we trust least.
+    async clone_workspace({ mirror_dir: from, dest, branch, default_branch }) {
+      await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+      await fs.promises.rm(dest, { recursive: true, force: true }).catch(() => {});
+      const cloned = await git_exec({ args: ['clone', '--no-tags', from, dest], timeout_ms: CLONE_TIMEOUT_MS });
+      if (cloned.exit_code !== 0) {
+        console.error(`[xudex] workspace clone from mirror failed: exit ${cloned.exit_code}`);
+        return { error: 'Xuda could not prepare a working copy for this project.' };
+      }
+
+      if (branch) {
+        // Same branch contract as the Code tab: a chat owns a branch and the default branch is never
+        // checked out for writing, so nothing a run does can land on main without a person merging it.
+        const on_mirror = await git_exec({ cwd: dest, args: ['rev-parse', '--verify', `refs/remotes/origin/${branch}`] });
+        const from_ref = on_mirror.exit_code === 0 ? `origin/${branch}` : `origin/${default_branch}`;
+        const created = await git_exec({ cwd: dest, args: ['checkout', '-B', branch, from_ref] });
+        if (created.exit_code !== 0) {
+          // A repository with no commits yet has no origin/<default> to branch from.
+          const fallback = await git_exec({ cwd: dest, args: ['checkout', '-B', branch] });
+          if (fallback.exit_code !== 0) return { error: 'Xuda could not create a branch for this project.' };
+        }
+      }
+
+      const head = await git_exec({ cwd: dest, args: ['rev-parse', 'HEAD'] });
+      return { dir: dest, branch: branch || null, base_sha: head.exit_code === 0 ? head.stdout : null };
+    },
+
+    // Clone if the workspace is new, refresh it if it is not. A persistent machine keeps its
+    // working copy between runs, and that warmth is most of what the paid tiers are selling, so
+    // re-cloning every run would throw away the thing being paid for (and any uncommitted work
+    // sitting in the tree). Only a workspace that does not exist yet is cloned.
+    async sync_workspace({ mirror_dir: from, dest, branch, default_branch }) {
+      const has_git = await fs.promises
+        .stat(path.join(dest, '.git'))
+        .then(() => true)
+        .catch(() => false);
+
+      if (!has_git) return await this.clone_workspace({ mirror_dir: from, dest, branch, default_branch });
+
+      const fetched = await git_exec({ cwd: dest, args: ['fetch', '--prune', 'origin'], timeout_ms: CLONE_TIMEOUT_MS });
+      if (fetched.exit_code !== 0) console.warn(`[xudex] workspace fetch from mirror failed: exit ${fetched.exit_code}`);
+
+      if (branch) {
+        // Reuse the branch when it is already here rather than resetting onto the remote: a
+        // checkout that discarded uncommitted work would silently delete whatever the last run
+        // produced and the customer has not committed yet.
+        const local = await git_exec({ cwd: dest, args: ['rev-parse', '--verify', `refs/heads/${branch}`] });
+        if (local.exit_code === 0) {
+          const co = await git_exec({ cwd: dest, args: ['checkout', branch] });
+          if (co.exit_code !== 0) return { error: 'Xuda could not switch to this chat branch. There may be uncommitted work in the way.' };
+        } else {
+          const on_mirror = await git_exec({ cwd: dest, args: ['rev-parse', '--verify', `refs/remotes/origin/${branch}`] });
+          const from_ref = on_mirror.exit_code === 0 ? `origin/${branch}` : `origin/${default_branch}`;
+          const created = await git_exec({ cwd: dest, args: ['checkout', '-B', branch, from_ref] });
+          if (created.exit_code !== 0) {
+            const fallback = await git_exec({ cwd: dest, args: ['checkout', '-B', branch] });
+            if (fallback.exit_code !== 0) return { error: 'Xuda could not create a branch for this project.' };
+          }
+        }
+      }
+
+      const head = await git_exec({ cwd: dest, args: ['rev-parse', 'HEAD'] });
+      return { dir: dest, branch: branch || null, base_sha: head.exit_code === 0 ? head.stdout : null, reused: true };
+    },
+
+    // Workspace to mirror. Runs with the workspace's own git, over a path or a VPN url, and never
+    // sees a credential.
+    async push_from_workspace({ work_dir, mirror_dir: to, branch }) {
+      if (!branch) return { error: 'no branch to push' };
+      const pushed = await git_exec({ cwd: work_dir, args: ['push', to, `refs/heads/${branch}:refs/heads/${branch}`], timeout_ms: CLONE_TIMEOUT_MS });
+      if (pushed.exit_code !== 0) {
+        console.error(`[xudex] workspace push to mirror failed for ${branch}: exit ${pushed.exit_code}`);
+        return { error: 'Xuda could not save that branch.' };
+      }
+      return { pushed: true, branch };
+    },
+
+    // Mirror to upstream: the authenticated leg, and the only one.
+    //
+    // The default branch is refused here as well as in git_push. That is not redundant. git_push
+    // guards the button a person clicks; this guards the path a machine drives, and the machine is
+    // precisely the part the mirror exists to distrust.
+    async push_upstream({ uid, repo, branch }) {
+      if (!branch) return { error: 'no branch to push' };
+      if (branch === repo.default_branch) {
+        return { error: `Xuda does not push ${repo.default_branch} for you. Open a pull request instead.` };
+      }
+      const dir = mirror_dir(uid, repo._id);
+      if (!(await exists(dir))) return { error: 'this repository has no mirror yet' };
+      const pushed = await git_exec({
+        cwd: dir,
+        args: ['push', 'origin', `refs/heads/${branch}:refs/heads/${branch}`],
+        token: repo.token || null,
+        timeout_ms: CLONE_TIMEOUT_MS,
+      });
+      if (pushed.exit_code !== 0) {
+        console.error(`[xudex] mirror push failed for ${repo._id} ${branch}: exit ${pushed.exit_code}`);
+        return { error: 'Xuda could not push that branch to your repository.' };
+      }
+      return { pushed: true, branch };
+    },
+
+    // Forget a repository entirely. Called on disconnect, beside the working copy removal that
+    // git_repo_disconnect already does.
+    async forget({ uid, repo_id }) {
+      await fs.promises.rm(mirror_dir(uid, repo_id), { recursive: true, force: true }).catch(() => {});
+      return true;
+    },
+  };
+};