@ganglion/xacpx 0.17.0-beta.6 → 0.17.0-beta.7

package/README.md

@@ -29,7 +29,7 @@ If you need to code or work remotely on a temporary basis, `xacpx` gives you a f
 
 ### Prerequisites
 
-- Node.js 22+ or Bun
+- Node.js 22.12+ or Bun
 - A working agent CLI you intend to use, such as Codex / Claude Code / Gemini / OpenCode
 - A phone with WeChat, Feishu, or Yuanbao installed
 

package/dist/cli.js

@@ -5310,6 +5310,9 @@ var init_agent_templates = __esm(() => {
     factorydroid: {
       driver: "factorydroid"
     },
+    "grok-build": {
+      driver: "grok-build"
+    },
     iflow: {
       driver: "iflow"
     },
@@ -5322,6 +5325,9 @@ var init_agent_templates = __esm(() => {
     kiro: {
       driver: "kiro"
     },
+    mux: {
+      driver: "mux"
+    },
     opencode: {
       driver: "opencode"
     },
@@ -35123,11 +35129,385 @@ var init_workspace_fs = __esm(() => {
   };
 });
 
+// src/control/workspace-git.ts
+import { execFile as execFile2 } from "node:child_process";
+import { createHash as createHash4 } from "node:crypto";
+import { lstat, mkdir as mkdir10, realpath as realpath2 } from "node:fs/promises";
+import { homedir as homedir13 } from "node:os";
+import { basename as basename4, isAbsolute as isAbsolute4, join as join22, resolve as resolve4, sep as sep2 } from "node:path";
+import { promisify as promisify2 } from "node:util";
+function expandHome3(path14) {
+  if (path14 === "~")
+    return homedir13();
+  if (path14.startsWith(`~${sep2}`) || path14.startsWith("~/"))
+    return resolve4(homedir13(), path14.slice(2));
+  return path14;
+}
+
+class WorkspaceGit {
+  listWorkspaces;
+  managedWorktreesRoot;
+  writeTails = new Map;
+  constructor(listWorkspaces, options = {}) {
+    this.listWorkspaces = listWorkspaces;
+    this.managedWorktreesRoot = options.managedWorktreesRoot ?? join22(homedir13(), ".xacpx", "worktrees");
+  }
+  async rootFor(workspace3) {
+    const ref = this.listWorkspaces().find((item) => item.name === workspace3);
+    if (!ref)
+      throw new Error("unknown-workspace");
+    try {
+      return await realpath2(expandHome3(ref.cwd));
+    } catch {
+      throw new Error("workspace-root-missing");
+    }
+  }
+  async run(root, args) {
+    return (await this.runRaw(root, args)).trim();
+  }
+  async runRaw(root, args) {
+    const result = await execFileAsync2("git", ["-C", root, ...args], {
+      timeout: GIT_TIMEOUT_MS2,
+      killSignal: "SIGKILL",
+      maxBuffer: GIT_MAX_BUFFER2
+    });
+    return result.stdout;
+  }
+  validatePaths(paths) {
+    if (!paths.length)
+      throw new Error("git-paths-required");
+    for (const path14 of paths) {
+      if (!path14 || isAbsolute4(path14) || path14.split(/[\\/]/).includes("..")) {
+        throw new Error("invalid-git-path");
+      }
+    }
+    return paths;
+  }
+  async validateBranch(root, raw) {
+    const branch = raw.trim();
+    if (!branch)
+      throw new Error("branch-required");
+    try {
+      await this.run(root, ["check-ref-format", "--branch", branch]);
+    } catch {
+      throw new Error("invalid-branch-name");
+    }
+    return branch;
+  }
+  async validateStartPoint(root, raw) {
+    const startPoint = raw?.trim();
+    if (!startPoint)
+      return;
+    try {
+      await this.run(root, ["rev-parse", "--verify", "--end-of-options", `${startPoint}^{commit}`]);
+    } catch {
+      throw new Error("invalid-start-point");
+    }
+    return startPoint;
+  }
+  async includeRenameSources(root, paths) {
+    const selected = new Set(paths);
+    const expanded = new Set(paths);
+    const fields = (await this.runRaw(root, ["-c", "core.quotePath=false", "status", "--porcelain", "-z"])).split("\x00");
+    for (let index = 0;index < fields.length; index += 1) {
+      const field = fields[index];
+      if (!field)
+        continue;
+      const status = field.slice(0, 2);
+      const path14 = field.slice(3);
+      if (status[0] !== "R" && status[0] !== "C")
+        continue;
+      const originalPath = fields[++index];
+      if (originalPath && selected.has(path14))
+        expanded.add(originalPath);
+    }
+    return [...expanded];
+  }
+  async withWrite(workspace3, action) {
+    const previous = this.writeTails.get(workspace3) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve5) => {
+      release = resolve5;
+    });
+    const tail2 = previous.catch(() => {}).then(() => current);
+    this.writeTails.set(workspace3, tail2);
+    await previous.catch(() => {});
+    try {
+      return await action();
+    } finally {
+      release();
+      if (this.writeTails.get(workspace3) === tail2)
+        this.writeTails.delete(workspace3);
+    }
+  }
+  async stage(workspace3, paths) {
+    await this.withWrite(workspace3, async () => {
+      const root = await this.rootFor(workspace3);
+      await this.run(root, ["--literal-pathspecs", "add", "--", ...this.validatePaths(paths)]);
+    });
+  }
+  async unstage(workspace3, paths) {
+    await this.withWrite(workspace3, async () => {
+      const root = await this.rootFor(workspace3);
+      const valid = await this.includeRenameSources(root, this.validatePaths(paths));
+      try {
+        await this.run(root, ["--literal-pathspecs", "restore", "--staged", "--", ...valid]);
+      } catch {
+        await this.run(root, ["--literal-pathspecs", "reset", "--", ...valid]);
+      }
+    });
+  }
+  async commit(workspace3, message) {
+    return this.withWrite(workspace3, async () => {
+      const root = await this.rootFor(workspace3);
+      const normalized = message.trim();
+      if (!normalized)
+        throw new Error("commit-message-required");
+      await this.run(root, ["commit", "-m", normalized]);
+      const hash = await this.run(root, ["rev-parse", "HEAD"]);
+      const shortHash2 = await this.run(root, ["rev-parse", "--short", "HEAD"]);
+      const summary = await this.run(root, ["show", "-s", "--format=%s", "HEAD"]);
+      return { hash, shortHash: shortHash2, summary };
+    });
+  }
+  async checkout(workspace3, options) {
+    await this.withWrite(workspace3, async () => {
+      const root = await this.rootFor(workspace3);
+      const branch = await this.validateBranch(root, options.branch);
+      if (await this.runRaw(root, ["status", "--porcelain", "-z"]) !== "") {
+        throw new Error("dirty-worktree");
+      }
+      if (options.create) {
+        const startPoint = await this.validateStartPoint(root, options.startPoint);
+        await this.run(root, ["switch", "-c", branch, ...startPoint ? [startPoint] : []]);
+        return;
+      }
+      await this.run(root, ["switch", branch]);
+    });
+  }
+  async fetch(workspace3, remote = "origin") {
+    await this.withWrite(workspace3, async () => {
+      const root = await this.rootFor(workspace3);
+      await this.assertRemote(root, remote);
+      await this.run(root, ["fetch", "--prune", "--", remote]);
+    });
+  }
+  async pull(workspace3) {
+    await this.withWrite(workspace3, async () => {
+      const root = await this.rootFor(workspace3);
+      if (await this.runRaw(root, ["status", "--porcelain", "-z"]) !== "") {
+        throw new Error("dirty-worktree");
+      }
+      try {
+        await this.run(root, ["rev-parse", "--verify", "@{upstream}"]);
+      } catch {
+        throw new Error("no-upstream");
+      }
+      await this.run(root, ["pull", "--ff-only"]);
+    });
+  }
+  async push(workspace3, options = {}) {
+    await this.withWrite(workspace3, async () => {
+      const root = await this.rootFor(workspace3);
+      if (options.setUpstream) {
+        const remote = options.remote?.trim() || "origin";
+        await this.assertRemote(root, remote);
+        const branch = await this.run(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+        if (branch === "HEAD")
+          throw new Error("detached-head");
+        await this.run(root, ["push", "--set-upstream", "--", remote, branch]);
+        return;
+      }
+      try {
+        await this.run(root, ["rev-parse", "--verify", "@{upstream}"]);
+      } catch {
+        throw new Error("no-upstream");
+      }
+      await this.run(root, ["push"]);
+    });
+  }
+  async createWorktree(workspace3, options) {
+    return this.withWrite(workspace3, async () => {
+      const root = await this.rootFor(workspace3);
+      const branch = await this.validateBranch(root, options.branch);
+      const startPoint = await this.validateStartPoint(root, options.startPoint);
+      await mkdir10(this.managedWorktreesRoot, { recursive: true });
+      const managedRoot = await realpath2(this.managedWorktreesRoot);
+      const commonDir = await this.run(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+      const top = await this.run(root, ["rev-parse", "--show-toplevel"]);
+      const repoKey = `${basename4(top)}-${createHash4("sha256").update(commonDir).digest("hex").slice(0, 8)}`;
+      const branchSlug = branch.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "branch";
+      const branchKey = `${branchSlug}-${createHash4("sha256").update(branch).digest("hex").slice(0, 6)}`;
+      const repoDir = join22(managedRoot, repoKey);
+      try {
+        const existing = await lstat(repoDir);
+        if (!existing.isDirectory() || existing.isSymbolicLink())
+          throw new Error("worktree-path-unsafe");
+      } catch (error2) {
+        if (error2.code !== "ENOENT")
+          throw error2;
+        await mkdir10(repoDir);
+      }
+      const realRepoDir = await realpath2(repoDir);
+      if (!realRepoDir.startsWith(managedRoot + sep2))
+        throw new Error("worktree-path-unsafe");
+      const target = join22(realRepoDir, branchKey);
+      try {
+        await lstat(target);
+        throw new Error("worktree-path-exists");
+      } catch (error2) {
+        if (error2.code !== "ENOENT")
+          throw error2;
+      }
+      if (options.createBranch) {
+        await this.run(root, ["worktree", "add", "-b", branch, target, ...startPoint ? [startPoint] : []]);
+      } else {
+        await this.run(root, ["worktree", "add", target, branch]);
+      }
+      const createdPath = await realpath2(target);
+      if (!createdPath.startsWith(managedRoot + sep2))
+        throw new Error("worktree-path-unsafe");
+      return { path: createdPath, branch, linked: true };
+    });
+  }
+  async removeManagedWorktree(workspace3, path14) {
+    await this.withWrite(workspace3, async () => {
+      const root = await this.rootFor(workspace3);
+      const managedRoot = await realpath2(this.managedWorktreesRoot);
+      const target = await realpath2(path14);
+      if (!target.startsWith(managedRoot + sep2))
+        throw new Error("worktree-outside-managed-root");
+      const worktrees = await this.readWorktrees(root);
+      const worktree = worktrees.find((item) => item.path === target);
+      if (!worktree)
+        throw new Error("worktree-not-found");
+      if (worktree.current)
+        throw new Error("cannot-remove-current-worktree");
+      await this.run(root, ["worktree", "remove", target]);
+    });
+  }
+  async assertRemote(root, remote) {
+    const normalized = remote.trim();
+    if (normalized.startsWith("-"))
+      throw new Error("invalid-remote");
+    const remotes = (await this.run(root, ["remote"])).split(`
+`).filter(Boolean);
+    if (!normalized || !remotes.includes(normalized))
+      throw new Error("unknown-remote");
+  }
+  async status(workspace3) {
+    const root = await this.rootFor(workspace3);
+    try {
+      await this.run(root, ["rev-parse", "--is-inside-work-tree"]);
+    } catch {
+      throw new Error("not-a-git-repo");
+    }
+    let head;
+    try {
+      head = await this.run(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    } catch {
+      try {
+        head = await this.run(root, ["symbolic-ref", "--short", "HEAD"]);
+      } catch {
+        head = "HEAD";
+      }
+    }
+    const branch = head === "HEAD" ? undefined : head;
+    let upstream;
+    let ahead = 0;
+    let behind = 0;
+    try {
+      upstream = await this.run(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
+      const [aheadRaw = "0", behindRaw = "0"] = (await this.run(root, ["rev-list", "--left-right", "--count", "HEAD...@{upstream}"])).split(/\s+/);
+      ahead = Number(aheadRaw) || 0;
+      behind = Number(behindRaw) || 0;
+    } catch {
+      upstream = undefined;
+    }
+    const worktrees = await this.readWorktrees(root);
+    const currentWorktree = worktrees.find((item) => item.current);
+    if (!currentWorktree)
+      throw new Error("git-worktree-context-missing");
+    const branchesRaw = await this.run(root, [
+      "for-each-ref",
+      "--format=%(refname:short)%00%(worktreepath)",
+      "refs/heads"
+    ]);
+    const branches = branchesRaw === "" ? [] : branchesRaw.split(`
+`).map((line) => {
+      const [name = "", worktreePath = ""] = line.split("\x00");
+      return {
+        name,
+        current: name === branch,
+        ...worktreePath ? { worktreePath } : {}
+      };
+    });
+    const statusRaw = await this.runRaw(root, ["-c", "core.quotePath=false", "status", "--porcelain", "-z"]);
+    const files = [];
+    const fields = statusRaw.split("\x00");
+    for (let index = 0;index < fields.length; index += 1) {
+      const field = fields[index];
+      if (!field)
+        continue;
+      const status = field.slice(0, 2);
+      const path14 = field.slice(3);
+      if (status[0] === "R" || status[0] === "C")
+        index += 1;
+      files.push({ path: path14, status });
+    }
+    files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    return {
+      workspace: workspace3,
+      ...branch ? { branch } : {},
+      detached: !branch,
+      ...upstream ? { upstream } : {},
+      ahead,
+      behind,
+      worktree: { root: currentWorktree.path, linked: currentWorktree.linked },
+      files,
+      branches,
+      worktrees
+    };
+  }
+  async readWorktrees(root) {
+    const output = await this.run(root, ["worktree", "list", "--porcelain"]);
+    const blocks = output.split(/\n\n+/).filter(Boolean);
+    const parsed = blocks.map((block) => {
+      let path14 = "";
+      let branch;
+      let detached = false;
+      for (const line of block.split(`
+`)) {
+        if (line.startsWith("worktree "))
+          path14 = line.slice("worktree ".length);
+        else if (line.startsWith("branch refs/heads/"))
+          branch = line.slice("branch refs/heads/".length);
+        else if (line === "detached")
+          detached = true;
+      }
+      return { path: path14, branch, detached };
+    });
+    const currentRoot = await realpath2(root);
+    return parsed.map((item, index) => ({
+      path: item.path,
+      ...item.branch ? { branch: item.branch } : {},
+      ...item.detached ? { detached: true } : {},
+      current: item.path === currentRoot,
+      linked: index !== 0
+    }));
+  }
+}
+var execFileAsync2, GIT_TIMEOUT_MS2 = 30000, GIT_MAX_BUFFER2;
+var init_workspace_git = __esm(() => {
+  execFileAsync2 = promisify2(execFile2);
+  GIT_MAX_BUFFER2 = 8 * 1024 * 1024;
+});
+
 // src/control/turn-support.ts
 async function raceWithTimeout(promise2, ms) {
   let timer;
-  const timeout = new Promise((resolve4) => {
-    timer = setTimeout(resolve4, ms);
+  const timeout = new Promise((resolve5) => {
+    timer = setTimeout(resolve5, ms);
   });
   try {
     await Promise.race([promise2, timeout]);
@@ -35408,8 +35788,8 @@ class TurnQueue {
         params.abortSignal.addEventListener("abort", () => controller.abort(), { once: true });
     }
     let resolveSettled;
-    const settled = new Promise((resolve4) => {
-      resolveSettled = resolve4;
+    const settled = new Promise((resolve5) => {
+      resolveSettled = resolve5;
     });
     this.inFlight.set(key, { controller, settled });
     if (params.drained) {
@@ -35530,9 +35910,12 @@ class ControlService {
   deps;
   runner;
   turnQueue;
+  workspaceGit;
   modelSetTails = new Map;
+  worktreeRegistrationTails = new Map;
   constructor(deps) {
     this.deps = deps;
+    this.workspaceGit = new WorkspaceGit(() => this.deps.workspaces.list().map((w) => ({ name: w.name, cwd: w.cwd })), { ...deps.gitWorktreesRoot ? { managedWorktreesRoot: deps.gitWorktreesRoot } : {} });
     this.runner = new SessionTurnRunner(deps);
     this.turnQueue = new TurnQueue({
       runTurn: (req, signal, onActivity) => this.runner.run(req, signal, onActivity),
@@ -35559,6 +35942,75 @@ class ControlService {
   workspaceGitDiff(workspace3, path15) {
     return this.workspaceFs.gitDiff(workspace3, path15);
   }
+  workspaceGitStatus(workspace3) {
+    return this.workspaceGit.status(workspace3);
+  }
+  async mutateWorkspaceGit(operation) {
+    if (!this.deps.filesWriteEnabled())
+      throw new Error("files-write-disabled");
+    return operation();
+  }
+  async withWorktreeRegistration(workspaceName, operation) {
+    const previous = this.worktreeRegistrationTails.get(workspaceName) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve5) => {
+      release = resolve5;
+    });
+    const tail2 = previous.catch(() => {}).then(() => current);
+    this.worktreeRegistrationTails.set(workspaceName, tail2);
+    await previous.catch(() => {});
+    try {
+      return await operation();
+    } finally {
+      release();
+      if (this.worktreeRegistrationTails.get(workspaceName) === tail2) {
+        this.worktreeRegistrationTails.delete(workspaceName);
+      }
+    }
+  }
+  gitStage(workspace3, paths) {
+    return this.mutateWorkspaceGit(() => this.workspaceGit.stage(workspace3, paths));
+  }
+  gitUnstage(workspace3, paths) {
+    return this.mutateWorkspaceGit(() => this.workspaceGit.unstage(workspace3, paths));
+  }
+  gitCommit(workspace3, message) {
+    return this.mutateWorkspaceGit(() => this.workspaceGit.commit(workspace3, message));
+  }
+  gitFetch(workspace3, remote) {
+    return this.mutateWorkspaceGit(() => this.workspaceGit.fetch(workspace3, remote));
+  }
+  gitPull(workspace3) {
+    return this.mutateWorkspaceGit(() => this.workspaceGit.pull(workspace3));
+  }
+  gitPush(workspace3, options) {
+    return this.mutateWorkspaceGit(() => this.workspaceGit.push(workspace3, options));
+  }
+  gitCheckout(workspace3, options) {
+    return this.mutateWorkspaceGit(() => this.workspaceGit.checkout(workspace3, options));
+  }
+  async gitCreateWorktree(workspace3, input) {
+    const workspaceName = input.workspaceName.trim();
+    if (!workspaceName)
+      throw new Error("workspace-name-required");
+    return this.mutateWorkspaceGit(() => this.withWorktreeRegistration(workspaceName, async () => {
+      if (this.deps.workspaces.list().some((item) => item.name === workspaceName)) {
+        throw new Error("workspace-name-exists");
+      }
+      const worktree = await this.workspaceGit.createWorktree(workspace3, input);
+      try {
+        const registered = await this.deps.workspaces.create(workspaceName, worktree.path, `Git worktree for ${worktree.branch}`);
+        return { worktree, workspace: registered };
+      } catch (registrationError) {
+        try {
+          await this.workspaceGit.removeManagedWorktree(workspace3, worktree.path);
+        } catch (rollbackError) {
+          throw new AggregateError([registrationError, rollbackError], "workspace-registration-rollback-failed");
+        }
+        throw registrationError;
+      }
+    }));
+  }
   searchWorkspace(workspace3, opts) {
     return this.workspaceFs.search(workspace3, opts);
   }
@@ -35641,8 +36093,8 @@ class ControlService {
   async runModelSetExclusive(sessionAlias, operation) {
     const previous = this.modelSetTails.get(sessionAlias) ?? Promise.resolve();
     let release;
-    const gate = new Promise((resolve4) => {
-      release = resolve4;
+    const gate = new Promise((resolve5) => {
+      release = resolve5;
     });
     const tail2 = previous.catch(() => {}).then(() => gate);
     this.modelSetTails.set(sessionAlias, tail2);
@@ -35858,6 +36310,7 @@ var init_control_service = __esm(() => {
   init_channel_scope();
   init_native_session_history();
   init_workspace_fs();
+  init_workspace_git();
   init_session_turn_runner();
   init_turn_queue();
   init_turn_support();
@@ -36078,10 +36531,10 @@ var init_terminal_service = __esm(() => {
 
 // src/control/upload-store.ts
 import { mkdtemp as mkdtemp2, readdir as readdir5, rm as rm11, stat as stat4, writeFile as writeFile9 } from "node:fs/promises";
-import { homedir as homedir13 } from "node:os";
+import { homedir as homedir14 } from "node:os";
 import path15 from "node:path";
 function defaultRootDir() {
-  const home = process.env.HOME ?? homedir13();
+  const home = process.env.HOME ?? homedir14();
   return path15.join(coreHomeDir(home), "runtime", "uploads");
 }
 function sanitizeUploadFilename(raw) {
@@ -36113,8 +36566,8 @@ class UploadStore {
     if (bytes.byteLength > this.maxBytes)
       throw new Error("file-too-large");
     const safeName = sanitizeUploadFilename(filename);
-    const { mkdir: mkdir10 } = await import("node:fs/promises");
-    await mkdir10(this.rootDir, { recursive: true });
+    const { mkdir: mkdir11 } = await import("node:fs/promises");
+    await mkdir11(this.rootDir, { recursive: true });
     const dir = await mkdtemp2(path15.join(this.rootDir, "u-"));
     const filePath = path15.join(dir, safeName);
     await writeFile9(filePath, bytes);
@@ -36156,54 +36609,52 @@ var init_upload_store = __esm(() => {
 });
 
 // src/config/agent-catalog.ts
-import { existsSync as existsSync3 } from "node:fs";
-import { delimiter as delimiter2, join as join22 } from "node:path";
-function isBinaryOnPath(binary) {
-  const path16 = process.env.PATH ?? "";
-  const exts = process.platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
-  for (const dir of path16.split(delimiter2)) {
-    if (!dir)
-      continue;
-    for (const ext of exts) {
-      try {
-        if (existsSync3(join22(dir, binary + ext)))
-          return true;
-      } catch {}
-    }
-  }
-  return false;
+function probeTarget(command) {
+  return command.trim().split(/\s+/)[0] ?? "";
 }
-function listAgentCatalog(config4, probe = isBinaryOnPath) {
+function listAgentCatalog(config4, { registry: registry2, probe = (binary) => isExecutableOnPath(binary) }) {
   const agents = config4.agents ?? {};
   const driverConfigured = (driver) => Object.entries(agents).some(([name, a]) => name === driver || a.driver === driver);
   return listAgentTemplates().map((driver) => {
-    let installed;
-    if (BUILTIN_DRIVERS.has(driver)) {
-      installed = "builtin";
-    } else {
-      const binary = DRIVER_BINARIES[driver] ?? driver;
-      installed = probe(binary) ? "yes" : "unknown";
-    }
+    const binary = probeTarget(registry2?.resolve(driver) ?? driver);
+    const installed = binary === "npx" || binary === "uvx" ? "builtin" : probe(binary) ? "yes" : "unknown";
     return { driver, configured: driverConfigured(driver), installed };
   });
 }
-var BUILTIN_DRIVERS, DRIVER_BINARIES;
 var init_agent_catalog = __esm(() => {
   init_agent_templates();
-  BUILTIN_DRIVERS = new Set(["codex", "claude"]);
-  DRIVER_BINARIES = {
-    cursor: "cursor-agent"
+  init_local_agent_bin();
+});
+
+// src/transport/agent-registry.ts
+import { createRequire as createRequire7 } from "node:module";
+function createAcpxAgentRegistryLoader(deps = {}) {
+  let cached2;
+  return () => {
+    if (cached2 !== undefined)
+      return cached2;
+    try {
+      cached2 = (deps.loadRuntime ?? loadRuntime)().createAgentRegistry();
+    } catch (error2) {
+      cached2 = null;
+      deps.logger?.error("transport.agent_registry.unavailable", "could not read acpx's agent registry; install hints fall back to probing the driver name, so an installed CLI may show as not detected", { error: error2 instanceof Error ? error2.message : String(error2) });
+    }
+    return cached2;
   };
+}
+var require6, loadRuntime = () => require6("acpx/runtime");
+var init_agent_registry = __esm(() => {
+  require6 = createRequire7(import.meta.url);
 });
 
 // src/config/config-watcher.ts
 import { watch } from "node:fs";
-import { basename as basename4, dirname as dirname13 } from "node:path";
+import { basename as basename5, dirname as dirname13 } from "node:path";
 function startConfigWatcher(options) {
   const { configPath, onChange, debounceMs = 100, logger } = options;
   const watchFactory = options.watchFactory ?? watch;
   const dir = dirname13(configPath);
-  const target = basename4(configPath);
+  const target = basename5(configPath);
   let timer;
   let watcher;
   const fire = () => {
@@ -36218,7 +36669,7 @@ function startConfigWatcher(options) {
   };
   try {
     watcher = watchFactory(dir, { persistent: false }, (_event, filename) => {
-      if (filename !== null && basename4(filename.toString()) !== target)
+      if (filename !== null && basename5(filename.toString()) !== target)
         return;
       if (timer)
         clearTimeout(timer);
@@ -36257,7 +36708,7 @@ __export(exports_main, {
   buildApp: () => buildApp
 });
 import { randomUUID as randomUUID5 } from "node:crypto";
-import { homedir as homedir14 } from "node:os";
+import { homedir as homedir15 } from "node:os";
 import { dirname as dirname14, join as join23 } from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 function startProgressHeartbeat(orchestration3, config4, logger, channel) {
@@ -36761,6 +37212,7 @@ async function buildApp(paths, deps = {}) {
     shell: () => terminalShell(config4)
   });
   const uploadStore = new UploadStore;
+  const loadAgentRegistry = createAcpxAgentRegistryLoader({ logger });
   uploadStore.cleanup();
   const uploadCleanupInterval = setInterval(() => void uploadStore.cleanup().catch(() => {}), 60 * 60 * 1000);
   const control = new ControlService({
@@ -36780,7 +37232,7 @@ async function buildApp(paths, deps = {}) {
     events: controlEvents,
     agents: {
       list: () => Object.entries(config4.agents).map(([name, agentConfig]) => ({ name, driver: agentConfig.driver })),
-      catalog: () => listAgentCatalog(config4),
+      catalog: () => listAgentCatalog(config4, { registry: loadAgentRegistry() }),
       create: async (name, driver) => {
         const updated = await configStore.upsertAgent(name, { driver });
         replaceRuntimeConfig(config4, updated);
@@ -36983,7 +37435,7 @@ async function prepareChannelMedia(configPath, config4) {
   return { mediaStore, channelDeps: { mediaStore, allowedMediaRoots } };
 }
 function resolveRuntimePaths() {
-  const home = process.env.HOME ?? homedir14();
+  const home = process.env.HOME ?? homedir15();
   if (!home) {
     throw new Error("Unable to resolve the current user home directory");
   }
@@ -37059,6 +37511,7 @@ var init_main = __esm(async () => {
   init_terminal_service();
   init_upload_store();
   init_agent_catalog();
+  init_agent_registry();
   init_config_watcher();
   init_perf_tracer();
   init_bootstrap();
@@ -37113,7 +37566,7 @@ function buildDetails(metadata, version2, verbose) {
 }
 async function defaultRunVersion(command) {
   const spawnSpec = resolveSpawnCommand(command, ["--version"]);
-  return await new Promise((resolve4, reject) => {
+  return await new Promise((resolve5, reject) => {
     const child = spawn12(spawnSpec.command, spawnSpec.args, {
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -37130,7 +37583,7 @@ async function defaultRunVersion(command) {
       if (code === 0) {
         const version2 = stdout2.trim() || stderr.trim();
         if (version2.length > 0) {
-          resolve4(version2);
+          resolve5(version2);
           return;
         }
       }
@@ -37254,10 +37707,10 @@ var init_config_check = __esm(async () => {
 // src/doctor/checks/daemon-check.ts
 import { readdir as readdir6, readFile as readFile16, rm as rm12 } from "node:fs/promises";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
-import { homedir as homedir15 } from "node:os";
+import { homedir as homedir16 } from "node:os";
 import { join as join24 } from "node:path";
 async function checkDaemon(options = {}) {
-  const home = options.home ?? process.env.HOME ?? homedir15();
+  const home = options.home ?? process.env.HOME ?? homedir16();
   const runtimeDir = options.configPath ? resolveRuntimeDirFromConfigPath(options.configPath) : undefined;
   const paths = (options.resolveDaemonPaths ?? resolveDaemonPaths)({
     home,
@@ -37422,10 +37875,10 @@ var init_daemon_check = __esm(() => {
 
 // src/doctor/checks/logs-check.ts
 import { stat as stat5, readdir as readdir7 } from "node:fs/promises";
-import { basename as basename5, join as join25 } from "node:path";
-import { homedir as homedir16 } from "node:os";
+import { basename as basename6, join as join25 } from "node:path";
+import { homedir as homedir17 } from "node:os";
 async function checkLogs(options = {}) {
-  const home = options.home ?? process.env.HOME ?? homedir16();
+  const home = options.home ?? process.env.HOME ?? homedir17();
   const runtimeDir = options.configPath ? resolveRuntimeDirFromConfigPath(options.configPath) : undefined;
   const paths = (options.resolveDaemonPaths ?? resolveDaemonPaths)({
     home,
@@ -37452,7 +37905,7 @@ async function checkLogs(options = {}) {
       `error: ${formatError6(error2)}`
     ]);
   }
-  const baseNames = [basename5(paths.appLog), basename5(paths.stdoutLog), basename5(paths.stderrLog)];
+  const baseNames = [basename6(paths.appLog), basename6(paths.stdoutLog), basename6(paths.stderrLog)];
   const tracked = new Set(baseNames);
   const matched = entries.filter((entry) => isTrackedLogName(entry, tracked));
   const files = [];
@@ -37607,9 +38060,9 @@ var init_orchestration_health = __esm(() => {
 });
 
 // src/doctor/checks/orchestration-socket-check.ts
-import { homedir as homedir17 } from "node:os";
+import { homedir as homedir18 } from "node:os";
 async function checkOrchestrationSocket(options = {}) {
-  const home = options.home ?? process.env.HOME ?? homedir17();
+  const home = options.home ?? process.env.HOME ?? homedir18();
   const runtimeDir = options.configPath ? resolveRuntimeDirFromConfigPath(options.configPath) : undefined;
   const paths = (options.resolveDaemonPaths ?? resolveDaemonPaths)({
     home,
@@ -37784,9 +38237,9 @@ var init_plugin_check = __esm(async () => {
 import { constants } from "node:fs";
 import { access as access4, stat as stat6 } from "node:fs/promises";
 import { dirname as dirname15 } from "node:path";
-import { homedir as homedir18 } from "node:os";
+import { homedir as homedir19 } from "node:os";
 async function checkRuntime(options = {}) {
-  const home = options.home ?? process.env.HOME ?? homedir18();
+  const home = options.home ?? process.env.HOME ?? homedir19();
   const runtimeDir = options.configPath ? resolveRuntimeDirFromConfigPath(options.configPath) : undefined;
   const paths = (options.resolveDaemonPaths ?? resolveDaemonPaths)({
     home,
@@ -38419,10 +38872,10 @@ var init_render_doctor = __esm(() => {
 });
 
 // src/doctor/doctor.ts
-import { homedir as homedir19 } from "node:os";
+import { homedir as homedir20 } from "node:os";
 import { join as join26 } from "node:path";
 async function runDoctor(options = {}, deps = {}) {
-  const home = deps.home ?? process.env.HOME ?? homedir19();
+  const home = deps.home ?? process.env.HOME ?? homedir20();
   const runtimePaths = resolveDoctorRuntimePaths(home, deps.resolveRuntimePaths);
   const sharedLoadConfig = createSharedLoadConfig(runtimePaths, deps.loadConfig ?? loadConfig);
   const runners = [
@@ -38759,8 +39212,8 @@ var init_doctor2 = __esm(async () => {
 // src/cli.ts
 init_core_home();
 import { randomUUID as randomUUID6 } from "node:crypto";
-import { homedir as homedir20 } from "node:os";
-import { dirname as dirname16, join as join27, sep as sep2 } from "node:path";
+import { homedir as homedir21 } from "node:os";
+import { dirname as dirname16, join as join27, sep as sep3 } from "node:path";
 import { fileURLToPath as fileURLToPath7 } from "node:url";
 
 // src/runtime/migrate-core-home.ts
@@ -55073,7 +55526,7 @@ async function defaultRun(options = {}) {
   const firstRunOnboarding = options.firstRunOnboarding ?? decodeFirstRunOnboarding(coreEnv("FIRST_RUN_ONBOARDING"));
   await runConsole2(runtimePaths, {
     buildApp: (paths) => buildApp2(paths, {
-      defaultLoggingLevel: resolveCliEntryPath2().includes(`${sep2}src${sep2}`) ? "debug" : "info",
+      defaultLoggingLevel: resolveCliEntryPath2().includes(`${sep3}src${sep3}`) ? "debug" : "info",
       channel: channelRegistry
     }),
     beforeReady: firstRunOnboarding ? async (runtime) => {
@@ -55084,7 +55537,7 @@ async function defaultRun(options = {}) {
     daemonRuntime,
     ...firstLockCreator ? {
       consumerLockFactory: (runtime) => firstLockCreator.create({
-        lockFilePath: `${daemonPaths.runtimeDir}${sep2}${firstLockCreator.channel.id}-consumer.lock.json`,
+        lockFilePath: `${daemonPaths.runtimeDir}${sep3}${firstLockCreator.channel.id}-consumer.lock.json`,
         onDiagnostic: async (event, context) => {
           await runtime.logger.info(`${firstLockCreator.channel.id}.consumer_lock.${event}`, `${firstLockCreator.channel.id} consumer lock diagnostic`, context);
         }
@@ -55279,7 +55732,7 @@ async function defaultPromptSecret(message) {
   process.stdout.write(message);
   process.stdin.setRawMode(true);
   process.stdin.resume();
-  return await new Promise((resolve4, reject) => {
+  return await new Promise((resolve5, reject) => {
     const chunks = [];
     let inEscape = false;
     const cleanup = () => {
@@ -55310,7 +55763,7 @@ async function defaultPromptSecret(message) {
         if (char === "\r" || char === `
 `) {
           cleanup();
-          resolve4(chunks.join(""));
+          resolve5(chunks.join(""));
           return;
         }
         if (char === "" || char === "\b") {
@@ -55365,7 +55818,7 @@ function decodeFirstRunOnboarding(raw) {
   return null;
 }
 function requireHome2() {
-  const home = process.env.HOME ?? homedir20();
+  const home = process.env.HOME ?? homedir21();
   if (!home) {
     throw new Error("Unable to resolve the current user home directory");
   }

package/dist/config/agent-catalog.d.ts

@@ -4,11 +4,29 @@ export interface AgentCatalogEntry {
     configured: boolean;
     installed: "builtin" | "yes" | "unknown";
 }
-/** True if `binary` is found in any PATH directory (no extension assumptions on POSIX). */
-export declare function isBinaryOnPath(binary: string): boolean;
+/** Narrow view of acpx's registry supplied by the transport boundary. */
+export interface AgentCommandRegistry {
+    resolve(driver: string): string;
+}
+export interface ListAgentCatalogOptions {
+    registry: AgentCommandRegistry | null;
+    probe?: (binary: string) => boolean;
+}
 /**
- * Catalog of every acpx driver xacpx knows (from `listAgentTemplates()`), each
- * tagged with whether it's already configured and a best-effort install hint.
- * `probe` is injectable for tests; defaults to a real PATH lookup.
+ * Catalog of every acpx driver xacpx knows (from `listAgentTemplates()`), each tagged with
+ * whether it's already configured and a best-effort install hint.
+ *
+ * The probe target is derived from the acpx registry supplied by the transport boundary,
+ * so it can't drift from acpx the way a hand-copied table did. It resolves aliases too
+ * (`factory-droid` and `factorydroid` both reach `droid exec --output-format acp`). What we
+ * derive is acpx's DEFAULT command for a
+ * driver: its registry accepts an `overrides` map (which acpx populates from ~/.acpx/config.json)
+ * that we do not reconstruct, and xacpx itself may substitute a local CLI at spawn time
+ * (resolveLocalAgentCommand). Neither changes the answer for any driver today.
+ *
+ * `resolve()` does not throw on an unknown name — it echoes the name back — so a driver acpx
+ * has dropped degrades to probing a binary of the same name.
+ *
+ * The transport layer supplies `registry`; `probe` remains injectable for tests.
  */
-export declare function listAgentCatalog(config: AppConfig, probe?: (binary: string) => boolean): AgentCatalogEntry[];
+export declare function listAgentCatalog(config: AppConfig, { registry, probe }: ListAgentCatalogOptions): AgentCatalogEntry[];

package/dist/control/control-service.d.ts

@@ -9,6 +9,7 @@ import type { OrchestrationTaskRecord } from "../orchestration/orchestration-typ
 import type { ControlEventBus } from "./control-event-bus";
 import type { AgentCatalogEntry } from "../config/agent-catalog";
 import { type DirListing, type FileContent, type SearchOptions, type SearchResult, type WorkspaceDiff } from "./workspace-fs";
+import { type GitCheckoutOptions, type GitCommitResult, type GitPushOptions, type GitStatus, type GitWorktreeCreateOptions, type GitWorktreeCreateResult } from "./workspace-git";
 import type { PromptAttachmentRef } from "@ganglion/xacpx-relay-protocol";
 import type { UploadStore } from "./upload-store.js";
 import { type TurnIdleTimeoutDetail } from "./turn-support";
@@ -89,6 +90,8 @@ export interface ControlServiceDeps {
     terminal: import("./terminal-service").TerminalService;
     terminalEnabled: () => boolean;
     filesWriteEnabled: () => boolean;
+    /** Test/embedding override; production defaults to ~/.xacpx/worktrees. */
+    gitWorktreesRoot?: string;
     turnIdleTimeoutMs?: () => number;
     onTurnIdleTimeout?: (detail: TurnIdleTimeoutDetail) => void;
 }
@@ -136,12 +139,30 @@ export declare class ControlService {
     private readonly deps;
     private readonly runner;
     private readonly turnQueue;
+    private readonly workspaceGit;
     private readonly modelSetTails;
+    private readonly worktreeRegistrationTails;
     constructor(deps: ControlServiceDeps);
     private readonly workspaceFs;
     listDirectory(workspace: string, path?: string): Promise<DirListing>;
     readWorkspaceFile(workspace: string, path: string): Promise<FileContent>;
     workspaceGitDiff(workspace: string, path?: string): Promise<WorkspaceDiff>;
+    workspaceGitStatus(workspace: string): Promise<GitStatus>;
+    private mutateWorkspaceGit;
+    private withWorktreeRegistration;
+    gitStage(workspace: string, paths: string[]): Promise<void>;
+    gitUnstage(workspace: string, paths: string[]): Promise<void>;
+    gitCommit(workspace: string, message: string): Promise<GitCommitResult>;
+    gitFetch(workspace: string, remote?: string): Promise<void>;
+    gitPull(workspace: string): Promise<void>;
+    gitPush(workspace: string, options?: GitPushOptions): Promise<void>;
+    gitCheckout(workspace: string, options: GitCheckoutOptions): Promise<void>;
+    gitCreateWorktree(workspace: string, input: GitWorktreeCreateOptions & {
+        workspaceName: string;
+    }): Promise<{
+        worktree: GitWorktreeCreateResult;
+        workspace: ControlWorkspaceInfo;
+    }>;
     searchWorkspace(workspace: string, opts: SearchOptions): Promise<SearchResult>;
     fsCreate(workspace: string, path: string, kind: "file" | "dir"): Promise<{
         path: string;

package/dist/control/workspace-git.d.ts

@@ -0,0 +1,93 @@
+export interface GitWorkspaceRef {
+    name: string;
+    cwd: string;
+}
+export interface GitBranchInfo {
+    name: string;
+    current: boolean;
+    /** Present when Git reports this branch checked out in a worktree. */
+    worktreePath?: string;
+}
+export interface GitWorktreeInfo {
+    path: string;
+    branch?: string;
+    detached?: boolean;
+    current: boolean;
+    linked: boolean;
+}
+export interface GitStatus {
+    workspace: string;
+    branch?: string;
+    detached: boolean;
+    upstream?: string;
+    ahead: number;
+    behind: number;
+    worktree: {
+        root: string;
+        linked: boolean;
+    };
+    files: Array<{
+        path: string;
+        status: string;
+    }>;
+    branches: GitBranchInfo[];
+    worktrees: GitWorktreeInfo[];
+}
+export interface GitCommitResult {
+    hash: string;
+    shortHash: string;
+    summary: string;
+}
+export interface GitCheckoutOptions {
+    branch: string;
+    create?: boolean;
+    startPoint?: string;
+}
+export interface GitPushOptions {
+    setUpstream?: boolean;
+    remote?: string;
+}
+export interface GitWorktreeCreateOptions {
+    branch: string;
+    createBranch?: boolean;
+    startPoint?: string;
+}
+export interface GitWorktreeCreateResult {
+    path: string;
+    branch: string;
+    linked: true;
+}
+export declare class WorkspaceGit {
+    private readonly listWorkspaces;
+    private readonly managedWorktreesRoot;
+    private readonly writeTails;
+    constructor(listWorkspaces: () => GitWorkspaceRef[], options?: {
+        managedWorktreesRoot?: string;
+    });
+    private rootFor;
+    private run;
+    private runRaw;
+    private validatePaths;
+    private validateBranch;
+    private validateStartPoint;
+    private includeRenameSources;
+    /** Git write commands for one configured workspace share a FIFO. Reads remain
+     * concurrent, and a failed write releases the next command instead of poisoning
+     * the queue. */
+    private withWrite;
+    stage(workspace: string, paths: string[]): Promise<void>;
+    unstage(workspace: string, paths: string[]): Promise<void>;
+    commit(workspace: string, message: string): Promise<GitCommitResult>;
+    checkout(workspace: string, options: GitCheckoutOptions): Promise<void>;
+    fetch(workspace: string, remote?: string): Promise<void>;
+    pull(workspace: string): Promise<void>;
+    push(workspace: string, options?: GitPushOptions): Promise<void>;
+    createWorktree(workspace: string, options: GitWorktreeCreateOptions): Promise<GitWorktreeCreateResult>;
+    /** Internal compensation for a failed workspace-registration step. Not exposed as a
+     * user-facing delete operation: it only accepts a non-current worktree beneath the
+     * server-managed root. */
+    removeManagedWorktree(workspace: string, path: string): Promise<void>;
+    private assertRemote;
+    status(workspace: string): Promise<GitStatus>;
+    private readWorktrees;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganglion/xacpx",
-  "version": "0.17.0-beta.6",
+  "version": "0.17.0-beta.7",
   "description": "随时随地通过聊天频道（微信 / 飞书 / 元宝等）远程控制 `acpx` 上的 Claude Code、Codex 等 Agents。",
   "keywords": [
     "acpx",
@@ -99,7 +99,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12"
   },
   "devDependencies": {
     "@types/proper-lockfile": "^4.1.4",