codeharbor 0.1.9 → 0.1.11

package/dist/cli.js

@@ -24,19 +24,20 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli.ts
+var import_node_child_process6 = require("child_process");
 var import_node_fs11 = __toESM(require("fs"));
 var import_node_path12 = __toESM(require("path"));
 var import_commander = require("commander");
 
 // src/app.ts
-var import_node_child_process3 = require("child_process");
+var import_node_child_process4 = require("child_process");
 var import_node_util2 = require("util");
 
 // src/admin-server.ts
-var import_node_child_process = require("child_process");
-var import_node_fs2 = __toESM(require("fs"));
+var import_node_child_process2 = require("child_process");
+var import_node_fs4 = __toESM(require("fs"));
 var import_node_http = __toESM(require("http"));
-var import_node_path2 = __toESM(require("path"));
+var import_node_path4 = __toESM(require("path"));
 var import_node_util = require("util");
 
 // src/init.ts
@@ -219,117 +220,413 @@ async function askYesNo(rl, question, defaultValue) {
   return answer === "y" || answer === "yes";
 }
 
-// src/admin-server.ts
-var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
-var HttpError = class extends Error {
-  statusCode;
-  constructor(statusCode, message) {
-    super(message);
-    this.statusCode = statusCode;
+// src/service-manager.ts
+var import_node_child_process = require("child_process");
+var import_node_fs3 = __toESM(require("fs"));
+var import_node_os2 = __toESM(require("os"));
+var import_node_path3 = __toESM(require("path"));
+
+// src/runtime-home.ts
+var import_node_fs2 = __toESM(require("fs"));
+var import_node_os = __toESM(require("os"));
+var import_node_path2 = __toESM(require("path"));
+var LEGACY_RUNTIME_HOME = "/opt/codeharbor";
+var USER_RUNTIME_HOME_DIR = ".codeharbor";
+var DEFAULT_RUNTIME_HOME = import_node_path2.default.resolve(import_node_os.default.homedir(), USER_RUNTIME_HOME_DIR);
+var RUNTIME_HOME_ENV_KEY = "CODEHARBOR_HOME";
+function resolveRuntimeHome(env = process.env) {
+  const configured = env[RUNTIME_HOME_ENV_KEY]?.trim();
+  if (configured) {
+    return import_node_path2.default.resolve(configured);
   }
-};
-var AdminServer = class {
-  config;
-  logger;
-  stateStore;
-  configService;
-  host;
-  port;
-  adminToken;
-  adminIpAllowlist;
-  adminAllowedOrigins;
-  cwd;
-  checkCodex;
-  checkMatrix;
-  server = null;
-  address = null;
-  constructor(config, logger, stateStore, configService, options) {
-    this.config = config;
-    this.logger = logger;
-    this.stateStore = stateStore;
-    this.configService = configService;
-    this.host = options.host;
-    this.port = options.port;
-    this.adminToken = options.adminToken;
-    this.adminIpAllowlist = normalizeAllowlist(options.adminIpAllowlist ?? []);
-    this.adminAllowedOrigins = normalizeOriginAllowlist(options.adminAllowedOrigins ?? []);
-    this.cwd = options.cwd ?? process.cwd();
-    this.checkCodex = options.checkCodex ?? defaultCheckCodex;
-    this.checkMatrix = options.checkMatrix ?? defaultCheckMatrix;
+  const legacyEnvPath = import_node_path2.default.resolve(LEGACY_RUNTIME_HOME, ".env");
+  if (import_node_fs2.default.existsSync(legacyEnvPath)) {
+    return LEGACY_RUNTIME_HOME;
   }
-  getAddress() {
-    return this.address;
+  return resolveUserRuntimeHome(env);
+}
+function resolveUserRuntimeHome(env = process.env) {
+  const home = env.HOME?.trim() || import_node_os.default.homedir();
+  return import_node_path2.default.resolve(home, USER_RUNTIME_HOME_DIR);
+}
+
+// src/service-manager.ts
+var SYSTEMD_DIR = "/etc/systemd/system";
+var MAIN_SERVICE_NAME = "codeharbor.service";
+var ADMIN_SERVICE_NAME = "codeharbor-admin.service";
+function resolveDefaultRunUser(env = process.env) {
+  const sudoUser = env.SUDO_USER?.trim();
+  if (sudoUser) {
+    return sudoUser;
   }
-  async start() {
-    if (this.server) {
-      return;
+  const user = env.USER?.trim();
+  if (user) {
+    return user;
+  }
+  try {
+    return import_node_os2.default.userInfo().username;
+  } catch {
+    return "root";
+  }
+}
+function resolveRuntimeHomeForUser(runUser, env = process.env, explicitRuntimeHome) {
+  const configuredRuntimeHome = explicitRuntimeHome?.trim() || env[RUNTIME_HOME_ENV_KEY]?.trim();
+  if (configuredRuntimeHome) {
+    return import_node_path3.default.resolve(configuredRuntimeHome);
+  }
+  const userHome = resolveUserHome(runUser);
+  if (userHome) {
+    return import_node_path3.default.resolve(userHome, USER_RUNTIME_HOME_DIR);
+  }
+  return import_node_path3.default.resolve(import_node_os2.default.homedir(), USER_RUNTIME_HOME_DIR);
+}
+function buildMainServiceUnit(options) {
+  validateUnitOptions(options);
+  const runtimeHome2 = import_node_path3.default.resolve(options.runtimeHome);
+  return [
+    "[Unit]",
+    "Description=CodeHarbor main service",
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    `User=${options.runUser}`,
+    `WorkingDirectory=${runtimeHome2}`,
+    `Environment=CODEHARBOR_HOME=${runtimeHome2}`,
+    `ExecStart=${import_node_path3.default.resolve(options.nodeBinPath)} ${import_node_path3.default.resolve(options.cliScriptPath)} start`,
+    "Restart=always",
+    "RestartSec=3",
+    "NoNewPrivileges=true",
+    "PrivateTmp=true",
+    "ProtectSystem=full",
+    "ProtectHome=false",
+    `ReadWritePaths=${runtimeHome2}`,
+    "",
+    "[Install]",
+    "WantedBy=multi-user.target",
+    ""
+  ].join("\n");
+}
+function buildAdminServiceUnit(options) {
+  validateUnitOptions(options);
+  const runtimeHome2 = import_node_path3.default.resolve(options.runtimeHome);
+  return [
+    "[Unit]",
+    "Description=CodeHarbor admin service",
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    `User=${options.runUser}`,
+    `WorkingDirectory=${runtimeHome2}`,
+    `Environment=CODEHARBOR_HOME=${runtimeHome2}`,
+    `ExecStart=${import_node_path3.default.resolve(options.nodeBinPath)} ${import_node_path3.default.resolve(options.cliScriptPath)} admin serve`,
+    "Restart=always",
+    "RestartSec=3",
+    "NoNewPrivileges=true",
+    "PrivateTmp=true",
+    "ProtectSystem=full",
+    "ProtectHome=false",
+    `ReadWritePaths=${runtimeHome2}`,
+    "",
+    "[Install]",
+    "WantedBy=multi-user.target",
+    ""
+  ].join("\n");
+}
+function installSystemdServices(options) {
+  assertLinuxWithSystemd();
+  assertRootPrivileges();
+  const output = options.output ?? process.stdout;
+  const runUser = options.runUser.trim();
+  const runtimeHome2 = import_node_path3.default.resolve(options.runtimeHome);
+  validateSimpleValue(runUser, "runUser");
+  validateSimpleValue(runtimeHome2, "runtimeHome");
+  validateSimpleValue(options.nodeBinPath, "nodeBinPath");
+  validateSimpleValue(options.cliScriptPath, "cliScriptPath");
+  ensureUserExists(runUser);
+  const runGroup = resolveUserGroup(runUser);
+  import_node_fs3.default.mkdirSync(runtimeHome2, { recursive: true });
+  runCommand("chown", ["-R", `${runUser}:${runGroup}`, runtimeHome2]);
+  const mainPath = import_node_path3.default.join(SYSTEMD_DIR, MAIN_SERVICE_NAME);
+  const adminPath = import_node_path3.default.join(SYSTEMD_DIR, ADMIN_SERVICE_NAME);
+  const unitOptions = {
+    runUser,
+    runtimeHome: runtimeHome2,
+    nodeBinPath: options.nodeBinPath,
+    cliScriptPath: options.cliScriptPath
+  };
+  import_node_fs3.default.writeFileSync(mainPath, buildMainServiceUnit(unitOptions), "utf8");
+  if (options.installAdmin) {
+    import_node_fs3.default.writeFileSync(adminPath, buildAdminServiceUnit(unitOptions), "utf8");
+  }
+  runSystemctl(["daemon-reload"]);
+  if (options.startNow) {
+    runSystemctl(["enable", "--now", MAIN_SERVICE_NAME]);
+    if (options.installAdmin) {
+      runSystemctl(["enable", "--now", ADMIN_SERVICE_NAME]);
+    }
+  } else {
+    runSystemctl(["enable", MAIN_SERVICE_NAME]);
+    if (options.installAdmin) {
+      runSystemctl(["enable", ADMIN_SERVICE_NAME]);
     }
-    this.server = import_node_http.default.createServer((req, res) => {
-      void this.handleRequest(req, res);
-    });
-    await new Promise((resolve, reject) => {
-      if (!this.server) {
-        reject(new Error("admin server is not initialized"));
-        return;
-      }
-      this.server.once("error", reject);
-      this.server.listen(this.port, this.host, () => {
-        this.server?.removeListener("error", reject);
-        const address = this.server?.address();
-        if (!address || typeof address === "string") {
-          reject(new Error("failed to resolve admin server address"));
-          return;
-        }
-        this.address = {
-          host: address.address,
-          port: address.port
-        };
-        resolve();
-      });
-    });
   }
-  async stop() {
-    if (!this.server) {
-      return;
+  output.write(`Installed systemd unit: ${mainPath}
+`);
+  if (options.installAdmin) {
+    output.write(`Installed systemd unit: ${adminPath}
+`);
+  }
+  output.write("Done. Check status with: systemctl status codeharbor --no-pager\n");
+}
+function uninstallSystemdServices(options) {
+  assertLinuxWithSystemd();
+  assertRootPrivileges();
+  const output = options.output ?? process.stdout;
+  const mainPath = import_node_path3.default.join(SYSTEMD_DIR, MAIN_SERVICE_NAME);
+  const adminPath = import_node_path3.default.join(SYSTEMD_DIR, ADMIN_SERVICE_NAME);
+  stopAndDisableIfPresent(MAIN_SERVICE_NAME);
+  if (import_node_fs3.default.existsSync(mainPath)) {
+    import_node_fs3.default.unlinkSync(mainPath);
+  }
+  if (options.removeAdmin) {
+    stopAndDisableIfPresent(ADMIN_SERVICE_NAME);
+    if (import_node_fs3.default.existsSync(adminPath)) {
+      import_node_fs3.default.unlinkSync(adminPath);
     }
-    const server = this.server;
-    this.server = null;
-    this.address = null;
-    await new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve();
-      });
-    });
   }
-  async handleRequest(req, res) {
-    try {
-      const url = new URL(req.url ?? "/", "http://localhost");
-      this.setSecurityHeaders(res);
-      const corsDecision = this.resolveCors(req);
-      this.setCorsHeaders(res, corsDecision);
-      if (!this.isClientAllowed(req)) {
-        this.sendJson(res, 403, {
-          ok: false,
-          error: "Forbidden by ADMIN_IP_ALLOWLIST."
-        });
-        return;
-      }
-      if (url.pathname.startsWith("/api/admin/") && corsDecision.origin && !corsDecision.allowed) {
-        this.sendJson(res, 403, {
-          ok: false,
-          error: "Forbidden by ADMIN_ALLOWED_ORIGINS."
-        });
-        return;
-      }
-      if (req.method === "OPTIONS") {
-        if (corsDecision.origin && !corsDecision.allowed) {
-          this.sendJson(res, 403, {
-            ok: false,
-            error: "Forbidden by ADMIN_ALLOWED_ORIGINS."
+  runSystemctl(["daemon-reload"]);
+  runSystemctlIgnoreFailure(["reset-failed"]);
+  output.write(`Removed systemd unit: ${mainPath}
+`);
+  if (options.removeAdmin) {
+    output.write(`Removed systemd unit: ${adminPath}
+`);
+  }
+  output.write("Done.\n");
+}
+function restartSystemdServices(options) {
+  assertLinuxWithSystemd();
+  assertRootPrivileges();
+  const output = options.output ?? process.stdout;
+  runSystemctl(["restart", MAIN_SERVICE_NAME]);
+  output.write(`Restarted service: ${MAIN_SERVICE_NAME}
+`);
+  if (options.restartAdmin) {
+    runSystemctl(["restart", ADMIN_SERVICE_NAME]);
+    output.write(`Restarted service: ${ADMIN_SERVICE_NAME}
+`);
+  }
+  output.write("Done.\n");
+}
+function resolveUserHome(runUser) {
+  try {
+    const passwdRaw = import_node_fs3.default.readFileSync("/etc/passwd", "utf8");
+    const line = passwdRaw.split(/\r?\n/).find((item) => item.startsWith(`${runUser}:`));
+    if (!line) {
+      return null;
+    }
+    const fields = line.split(":");
+    return fields[5] ? fields[5].trim() : null;
+  } catch {
+    return null;
+  }
+}
+function validateUnitOptions(options) {
+  validateSimpleValue(options.runUser, "runUser");
+  validateSimpleValue(options.runtimeHome, "runtimeHome");
+  validateSimpleValue(options.nodeBinPath, "nodeBinPath");
+  validateSimpleValue(options.cliScriptPath, "cliScriptPath");
+}
+function validateSimpleValue(value, key) {
+  if (!value.trim()) {
+    throw new Error(`${key} cannot be empty.`);
+  }
+  if (/[\r\n]/.test(value)) {
+    throw new Error(`${key} contains invalid newline characters.`);
+  }
+}
+function assertLinuxWithSystemd() {
+  if (process.platform !== "linux") {
+    throw new Error("Systemd service install only supports Linux.");
+  }
+  try {
+    (0, import_node_child_process.execFileSync)("systemctl", ["--version"], { stdio: "ignore" });
+  } catch {
+    throw new Error("systemctl is required but not found.");
+  }
+}
+function assertRootPrivileges() {
+  if (typeof process.getuid !== "function") {
+    return;
+  }
+  if (process.getuid() !== 0) {
+    throw new Error("Root privileges are required. Run with sudo.");
+  }
+}
+function ensureUserExists(runUser) {
+  runCommand("id", ["-u", runUser]);
+}
+function resolveUserGroup(runUser) {
+  return runCommand("id", ["-gn", runUser]).trim();
+}
+function runSystemctl(args) {
+  runCommand("systemctl", args);
+}
+function stopAndDisableIfPresent(unitName) {
+  runSystemctlIgnoreFailure(["disable", "--now", unitName]);
+}
+function runSystemctlIgnoreFailure(args) {
+  try {
+    runCommand("systemctl", args);
+  } catch {
+  }
+}
+function runCommand(file, args) {
+  try {
+    return (0, import_node_child_process.execFileSync)(file, args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (error) {
+    throw new Error(formatCommandError(file, args, error), { cause: error });
+  }
+}
+function formatCommandError(file, args, error) {
+  const command = `${file} ${args.join(" ")}`.trim();
+  if (error && typeof error === "object") {
+    const maybeError = error;
+    const stderr = bufferToTrimmedString(maybeError.stderr);
+    const stdout = bufferToTrimmedString(maybeError.stdout);
+    const details = stderr || stdout || maybeError.message || "command failed";
+    return `Command failed: ${command}. ${details}`;
+  }
+  return `Command failed: ${command}. ${String(error)}`;
+}
+function bufferToTrimmedString(value) {
+  if (!value) {
+    return "";
+  }
+  const text = typeof value === "string" ? value : value.toString("utf8");
+  return text.trim();
+}
+
+// src/admin-server.ts
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process2.execFile);
+var HttpError = class extends Error {
+  statusCode;
+  constructor(statusCode, message) {
+    super(message);
+    this.statusCode = statusCode;
+  }
+};
+var AdminServer = class {
+  config;
+  logger;
+  stateStore;
+  configService;
+  host;
+  port;
+  adminToken;
+  adminIpAllowlist;
+  adminAllowedOrigins;
+  cwd;
+  checkCodex;
+  checkMatrix;
+  restartServices;
+  server = null;
+  address = null;
+  constructor(config, logger, stateStore, configService, options) {
+    this.config = config;
+    this.logger = logger;
+    this.stateStore = stateStore;
+    this.configService = configService;
+    this.host = options.host;
+    this.port = options.port;
+    this.adminToken = options.adminToken;
+    this.adminIpAllowlist = normalizeAllowlist(options.adminIpAllowlist ?? []);
+    this.adminAllowedOrigins = normalizeOriginAllowlist(options.adminAllowedOrigins ?? []);
+    this.cwd = options.cwd ?? process.cwd();
+    this.checkCodex = options.checkCodex ?? defaultCheckCodex;
+    this.checkMatrix = options.checkMatrix ?? defaultCheckMatrix;
+    this.restartServices = options.restartServices ?? defaultRestartServices;
+  }
+  getAddress() {
+    return this.address;
+  }
+  async start() {
+    if (this.server) {
+      return;
+    }
+    this.server = import_node_http.default.createServer((req, res) => {
+      void this.handleRequest(req, res);
+    });
+    await new Promise((resolve, reject) => {
+      if (!this.server) {
+        reject(new Error("admin server is not initialized"));
+        return;
+      }
+      this.server.once("error", reject);
+      this.server.listen(this.port, this.host, () => {
+        this.server?.removeListener("error", reject);
+        const address = this.server?.address();
+        if (!address || typeof address === "string") {
+          reject(new Error("failed to resolve admin server address"));
+          return;
+        }
+        this.address = {
+          host: address.address,
+          port: address.port
+        };
+        resolve();
+      });
+    });
+  }
+  async stop() {
+    if (!this.server) {
+      return;
+    }
+    const server = this.server;
+    this.server = null;
+    this.address = null;
+    await new Promise((resolve, reject) => {
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+  async handleRequest(req, res) {
+    try {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      this.setSecurityHeaders(res);
+      const corsDecision = this.resolveCors(req);
+      this.setCorsHeaders(res, corsDecision);
+      if (!this.isClientAllowed(req)) {
+        this.sendJson(res, 403, {
+          ok: false,
+          error: "Forbidden by ADMIN_IP_ALLOWLIST."
+        });
+        return;
+      }
+      if (url.pathname.startsWith("/api/admin/") && corsDecision.origin && !corsDecision.allowed) {
+        this.sendJson(res, 403, {
+          ok: false,
+          error: "Forbidden by ADMIN_ALLOWED_ORIGINS."
+        });
+        return;
+      }
+      if (req.method === "OPTIONS") {
+        if (corsDecision.origin && !corsDecision.allowed) {
+          this.sendJson(res, 403, {
+            ok: false,
+            error: "Forbidden by ADMIN_ALLOWED_ORIGINS."
           });
           return;
         }
@@ -419,6 +716,33 @@ var AdminServer = class {
         });
         return;
       }
+      if (req.method === "POST" && url.pathname === "/api/admin/service/restart") {
+        const body = asObject(await readJsonBody(req), "service restart payload");
+        const restartAdmin = normalizeBoolean(body.withAdmin, false);
+        const actor = readActor(req);
+        try {
+          const result = await this.restartServices(restartAdmin);
+          this.stateStore.appendConfigRevision(
+            actor,
+            restartAdmin ? "restart services (main + admin)" : "restart service (main)",
+            JSON.stringify({
+              type: "service_restart",
+              restartAdmin,
+              restarted: result.restarted
+            })
+          );
+          this.sendJson(res, 200, {
+            ok: true,
+            restarted: result.restarted
+          });
+          return;
+        } catch (error) {
+          throw new HttpError(
+            500,
+            `Service restart failed: ${formatError(error)}. Ensure service has root privileges or run CLI command manually.`
+          );
+        }
+      }
       this.sendJson(res, 404, {
         ok: false,
         error: `Not found: ${req.method ?? "GET"} ${url.pathname}`
@@ -449,7 +773,7 @@ var AdminServer = class {
       updatedKeys.push("matrixCommandPrefix");
     }
     if ("codexWorkdir" in body) {
-      const workdir = import_node_path2.default.resolve(String(body.codexWorkdir ?? "").trim());
+      const workdir = import_node_path4.default.resolve(String(body.codexWorkdir ?? "").trim());
       ensureDirectory(workdir, "codexWorkdir");
       this.config.codexWorkdir = workdir;
       envUpdates.CODEX_WORKDIR = workdir;
@@ -599,6 +923,27 @@ var AdminServer = class {
         updatedKeys.push("cliCompat.fetchMedia");
       }
     }
+    if ("agentWorkflow" in body) {
+      const workflow = asObject(body.agentWorkflow, "agentWorkflow");
+      const currentAgentWorkflow = ensureAgentWorkflowConfig(this.config);
+      if ("enabled" in workflow) {
+        const value = normalizeBoolean(workflow.enabled, currentAgentWorkflow.enabled);
+        currentAgentWorkflow.enabled = value;
+        envUpdates.AGENT_WORKFLOW_ENABLED = String(value);
+        updatedKeys.push("agentWorkflow.enabled");
+      }
+      if ("autoRepairMaxRounds" in workflow) {
+        const value = normalizePositiveInt(
+          workflow.autoRepairMaxRounds,
+          currentAgentWorkflow.autoRepairMaxRounds,
+          0,
+          10
+        );
+        currentAgentWorkflow.autoRepairMaxRounds = value;
+        envUpdates.AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS = String(value);
+        updatedKeys.push("agentWorkflow.autoRepairMaxRounds");
+      }
+    }
     if (updatedKeys.length === 0) {
       throw new HttpError(400, "No supported global config fields provided.");
     }
@@ -652,11 +997,11 @@ var AdminServer = class {
     return this.adminIpAllowlist.includes(normalizedRemote);
   }
   persistEnvUpdates(updates) {
-    const envPath = import_node_path2.default.resolve(this.cwd, ".env");
-    const examplePath = import_node_path2.default.resolve(this.cwd, ".env.example");
-    const template = import_node_fs2.default.existsSync(envPath) ? import_node_fs2.default.readFileSync(envPath, "utf8") : import_node_fs2.default.existsSync(examplePath) ? import_node_fs2.default.readFileSync(examplePath, "utf8") : "";
+    const envPath = import_node_path4.default.resolve(this.cwd, ".env");
+    const examplePath = import_node_path4.default.resolve(this.cwd, ".env.example");
+    const template = import_node_fs4.default.existsSync(envPath) ? import_node_fs4.default.readFileSync(envPath, "utf8") : import_node_fs4.default.existsSync(examplePath) ? import_node_fs4.default.readFileSync(examplePath, "utf8") : "";
     const next = applyEnvOverrides(template, updates);
-    import_node_fs2.default.writeFileSync(envPath, next, "utf8");
+    import_node_fs4.default.writeFileSync(envPath, next, "utf8");
   }
   resolveCors(req) {
     const origin = normalizeOriginHeader(req.headers.origin);
@@ -683,7 +1028,7 @@ var AdminServer = class {
     }
     res.setHeader("Access-Control-Allow-Origin", corsDecision.origin);
     res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Admin-Token, X-Admin-Actor");
-    res.setHeader("Access-Control-Allow-Methods", "GET, PUT, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Methods", "GET, PUT, POST, DELETE, OPTIONS");
     appendVaryHeader(res, "Origin");
   }
   setSecurityHeaders(res) {
@@ -719,9 +1064,23 @@ function buildGlobalConfigSnapshot(config) {
     matrixProgressMinIntervalMs: config.matrixProgressMinIntervalMs,
     matrixTypingTimeoutMs: config.matrixTypingTimeoutMs,
     sessionActiveWindowMinutes: config.sessionActiveWindowMinutes,
-    cliCompat: { ...config.cliCompat }
+    cliCompat: { ...config.cliCompat },
+    agentWorkflow: { ...ensureAgentWorkflowConfig(config) }
   };
 }
+function ensureAgentWorkflowConfig(config) {
+  const mutable = config;
+  const existing = mutable.agentWorkflow;
+  if (existing && typeof existing.enabled === "boolean" && Number.isFinite(existing.autoRepairMaxRounds)) {
+    return existing;
+  }
+  const fallback = {
+    enabled: false,
+    autoRepairMaxRounds: 1
+  };
+  mutable.agentWorkflow = fallback;
+  return fallback;
+}
 function formatAuditEntry(entry) {
   return {
     id: entry.id,
@@ -740,6 +1099,22 @@ function parseJsonLoose(raw) {
     return raw;
   }
 }
+async function defaultRestartServices(restartAdmin) {
+  const outputChunks = [];
+  const output = {
+    write: (chunk) => {
+      outputChunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+      return true;
+    }
+  };
+  restartSystemdServices({
+    restartAdmin,
+    output
+  });
+  return {
+    restarted: restartAdmin ? ["codeharbor", "codeharbor-admin"] : ["codeharbor"]
+  };
+}
 function isUiPath(pathname) {
   return pathname === "/" || pathname === "/index.html" || pathname === "/settings/global" || pathname === "/settings/rooms" || pathname === "/health" || pathname === "/audit";
 }
@@ -888,7 +1263,7 @@ function normalizeNonNegativeInt(value, fallback) {
   return normalizePositiveInt(value, fallback, 0, Number.MAX_SAFE_INTEGER);
 }
 function ensureDirectory(targetPath, fieldName) {
-  if (!import_node_fs2.default.existsSync(targetPath) || !import_node_fs2.default.statSync(targetPath).isDirectory()) {
+  if (!import_node_fs4.default.existsSync(targetPath) || !import_node_fs4.default.statSync(targetPath).isDirectory()) {
     throw new HttpError(400, `${fieldName} must be an existing directory: ${targetPath}`);
   }
 }
@@ -1221,10 +1596,17 @@ var ADMIN_CONSOLE_HTML = `<!doctype html>
             <input id="global-cli-throttle" type="number" min="0" />
           </label>
           <label class="checkbox"><input id="global-cli-fetch-media" type="checkbox" /><span>Fetch media attachments</span></label>
+          <label class="checkbox"><input id="global-agent-enabled" type="checkbox" /><span>Enable multi-agent workflow</span></label>
+          <label class="field">
+            <span class="field-label">Workflow auto-repair rounds</span>
+            <input id="global-agent-repair-rounds" type="number" min="0" max="10" />
+          </label>
         </div>
         <div class="actions">
           <button id="global-save-btn" type="button">Save Global Config</button>
           <button id="global-reload-btn" type="button" class="secondary">Reload</button>
+          <button id="global-restart-main-btn" type="button" class="secondary">Restart Main Service</button>
+          <button id="global-restart-all-btn" type="button" class="secondary">Restart Main + Admin</button>
         </div>
         <p class="muted">Saving global config updates .env and requires restart to fully take effect.</p>
       </section>
@@ -1367,6 +1749,12 @@ var ADMIN_CONSOLE_HTML = `<!doctype html>
 
         document.getElementById("global-save-btn").addEventListener("click", saveGlobal);
         document.getElementById("global-reload-btn").addEventListener("click", loadGlobal);
+        document.getElementById("global-restart-main-btn").addEventListener("click", function () {
+          restartManagedServices(false);
+        });
+        document.getElementById("global-restart-all-btn").addEventListener("click", function () {
+          restartManagedServices(true);
+        });
         document.getElementById("room-load-btn").addEventListener("click", loadRoom);
         document.getElementById("room-save-btn").addEventListener("click", saveRoom);
         document.getElementById("room-delete-btn").addEventListener("click", deleteRoom);
@@ -1488,6 +1876,7 @@ var ADMIN_CONSOLE_HTML = `<!doctype html>
             var rateLimiter = data.rateLimiter || {};
             var trigger = data.defaultGroupTriggerPolicy || {};
             var cliCompat = data.cliCompat || {};
+            var agentWorkflow = data.agentWorkflow || {};
 
             document.getElementById("global-matrix-prefix").value = data.matrixCommandPrefix || "";
             document.getElementById("global-workdir").value = data.codexWorkdir || "";
@@ -1513,6 +1902,10 @@ var ADMIN_CONSOLE_HTML = `<!doctype html>
             document.getElementById("global-cli-disable-split").checked = Boolean(cliCompat.disableReplyChunkSplit);
             document.getElementById("global-cli-throttle").value = String(cliCompat.progressThrottleMs || 0);
             document.getElementById("global-cli-fetch-media").checked = Boolean(cliCompat.fetchMedia);
+            document.getElementById("global-agent-enabled").checked = Boolean(agentWorkflow.enabled);
+            document.getElementById("global-agent-repair-rounds").value = String(
+              typeof agentWorkflow.autoRepairMaxRounds === "number" ? agentWorkflow.autoRepairMaxRounds : 1
+            );
 
             showNotice("ok", "Global config loaded.");
           } catch (error) {
@@ -1550,6 +1943,10 @@ var ADMIN_CONSOLE_HTML = `<!doctype html>
                 disableReplyChunkSplit: asBool("global-cli-disable-split"),
                 progressThrottleMs: asNumber("global-cli-throttle", 300),
                 fetchMedia: asBool("global-cli-fetch-media")
+              },
+              agentWorkflow: {
+                enabled: asBool("global-agent-enabled"),
+                autoRepairMaxRounds: asNumber("global-agent-repair-rounds", 1)
               }
             };
             var response = await apiRequest("/api/admin/config/global", "PUT", body);
@@ -1561,11 +1958,24 @@ var ADMIN_CONSOLE_HTML = `<!doctype html>
           }
         }
 
-        async function refreshRoomList() {
+        async function restartManagedServices(withAdmin) {
           try {
-            var response = await apiRequest("/api/admin/config/rooms", "GET");
-            var items = Array.isArray(response.data) ? response.data : [];
-            roomListBody.innerHTML = "";
+            var response = await apiRequest("/api/admin/service/restart", "POST", {
+              withAdmin: Boolean(withAdmin)
+            });
+            var restarted = Array.isArray(response.restarted) ? response.restarted.join(", ") : "codeharbor";
+            var suffix = withAdmin ? " Admin page may reconnect during restart." : "";
+            showNotice("warn", "Restart requested: " + restarted + "." + suffix);
+          } catch (error) {
+            showNotice("error", "Failed to restart service(s): " + error.message);
+          }
+        }
+
+        async function refreshRoomList() {
+          try {
+            var response = await apiRequest("/api/admin/config/rooms", "GET");
+            var items = Array.isArray(response.data) ? response.data : [];
+            roomListBody.innerHTML = "";
             if (items.length === 0) {
               renderEmptyRow(roomListBody, 4, "No room settings.");
               return;
@@ -1786,8 +2196,8 @@ async function defaultCheckMatrix(homeserver, timeoutMs) {
 
 // src/channels/matrix-channel.ts
 var import_promises2 = __toESM(require("fs/promises"));
-var import_node_os = __toESM(require("os"));
-var import_node_path3 = __toESM(require("path"));
+var import_node_os3 = __toESM(require("os"));
+var import_node_path5 = __toESM(require("path"));
 var import_matrix_js_sdk = require("matrix-js-sdk");
 
 // src/utils/message.ts
@@ -2210,10 +2620,10 @@ var MatrixChannel = class {
     }
     const bytes = Buffer.from(await response.arrayBuffer());
     const extension = resolveFileExtension(fileName, mimeType);
-    const directory = import_node_path3.default.join(import_node_os.default.tmpdir(), "codeharbor-media");
+    const directory = import_node_path5.default.join(import_node_os3.default.tmpdir(), "codeharbor-media");
     await import_promises2.default.mkdir(directory, { recursive: true });
     const safeEventId = sanitizeFilename(eventId);
-    const targetPath = import_node_path3.default.join(directory, `${safeEventId}-${index}${extension}`);
+    const targetPath = import_node_path5.default.join(directory, `${safeEventId}-${index}${extension}`);
     await import_promises2.default.writeFile(targetPath, bytes);
     return targetPath;
   }
@@ -2298,7 +2708,7 @@ function sanitizeFilename(value) {
   return value.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
 }
 function resolveFileExtension(fileName, mimeType) {
-  const ext = import_node_path3.default.extname(fileName).trim();
+  const ext = import_node_path5.default.extname(fileName).trim();
   if (ext) {
     return ext;
   }
@@ -2315,14 +2725,14 @@ function resolveFileExtension(fileName, mimeType) {
 }
 
 // src/config-service.ts
-var import_node_fs3 = __toESM(require("fs"));
-var import_node_path4 = __toESM(require("path"));
+var import_node_fs5 = __toESM(require("fs"));
+var import_node_path6 = __toESM(require("path"));
 var ConfigService = class {
   stateStore;
   defaultWorkdir;
   constructor(stateStore, defaultWorkdir) {
     this.stateStore = stateStore;
-    this.defaultWorkdir = import_node_path4.default.resolve(defaultWorkdir);
+    this.defaultWorkdir = import_node_path6.default.resolve(defaultWorkdir);
   }
   resolveRoomConfig(roomId, fallbackPolicy) {
     const room = this.stateStore.getRoomSettings(roomId);
@@ -2393,8 +2803,8 @@ function normalizeRoomSettingsInput(input) {
   if (!roomId) {
     throw new Error("roomId is required.");
   }
-  const workdir = import_node_path4.default.resolve(input.workdir);
-  if (!import_node_fs3.default.existsSync(workdir) || !import_node_fs3.default.statSync(workdir).isDirectory()) {
+  const workdir = import_node_path6.default.resolve(input.workdir);
+  if (!import_node_fs5.default.existsSync(workdir) || !import_node_fs5.default.statSync(workdir).isDirectory()) {
     throw new Error(`workdir does not exist or is not a directory: ${workdir}`);
   }
   return {
@@ -2409,7 +2819,7 @@ function normalizeRoomSettingsInput(input) {
 }
 
 // src/executor/codex-executor.ts
-var import_node_child_process2 = require("child_process");
+var import_node_child_process3 = require("child_process");
 var import_node_readline = __toESM(require("readline"));
 var CodexExecutionCancelledError = class extends Error {
   constructor(message = "codex execution cancelled") {
@@ -2427,7 +2837,7 @@ var CodexExecutor = class {
   }
   startExecution(prompt, sessionId, onProgress, startOptions) {
     const args = buildCodexArgs(prompt, sessionId, this.options, startOptions);
-    const child = (0, import_node_child_process2.spawn)(this.options.bin, args, {
+    const child = (0, import_node_child_process3.spawn)(this.options.bin, args, {
       cwd: startOptions?.workdir ?? this.options.workdir,
       env: {
         ...process.env,
@@ -2663,20 +3073,20 @@ var import_async_mutex = require("async-mutex");
 var import_promises3 = __toESM(require("fs/promises"));
 
 // src/compat/cli-compat-recorder.ts
-var import_node_fs4 = __toESM(require("fs"));
-var import_node_path5 = __toESM(require("path"));
+var import_node_fs6 = __toESM(require("fs"));
+var import_node_path7 = __toESM(require("path"));
 var CliCompatRecorder = class {
   filePath;
   chain = Promise.resolve();
   constructor(filePath) {
-    this.filePath = import_node_path5.default.resolve(filePath);
-    import_node_fs4.default.mkdirSync(import_node_path5.default.dirname(this.filePath), { recursive: true });
+    this.filePath = import_node_path7.default.resolve(filePath);
+    import_node_fs6.default.mkdirSync(import_node_path7.default.dirname(this.filePath), { recursive: true });
   }
   append(entry) {
     const payload = `${JSON.stringify(entry)}
 `;
     this.chain = this.chain.then(async () => {
-      await import_node_fs4.default.promises.appendFile(this.filePath, payload, "utf8");
+      await import_node_fs6.default.promises.appendFile(this.filePath, payload, "utf8");
     });
     return this.chain;
   }
@@ -2880,6 +3290,273 @@ function computeRetryAfter(timestamps, windowMs, now) {
   return Math.max(0, oldest + windowMs - now);
 }
 
+// src/workflow/multi-agent-workflow.ts
+var MultiAgentWorkflowRunner = class {
+  executor;
+  logger;
+  config;
+  constructor(executor, logger, config) {
+    this.executor = executor;
+    this.logger = logger;
+    this.config = config;
+  }
+  isEnabled() {
+    return this.config.enabled;
+  }
+  async run(input) {
+    const startedAt = Date.now();
+    const objective = input.objective.trim();
+    if (!objective) {
+      throw new Error("workflow objective cannot be empty.");
+    }
+    const maxRepairRounds = Math.max(0, this.config.autoRepairMaxRounds);
+    let plannerSessionId = null;
+    let executorSessionId = null;
+    let reviewerSessionId = null;
+    let activeHandle = null;
+    let cancelled = false;
+    input.onRegisterCancel?.(() => {
+      cancelled = true;
+      activeHandle?.cancel();
+    });
+    await emitProgress(input, {
+      stage: "planner",
+      round: 0,
+      message: "Planner \u6B63\u5728\u751F\u6210\u6267\u884C\u8BA1\u5212"
+    });
+    const planResult = await this.executeRole(
+      "planner",
+      buildPlannerPrompt(objective),
+      plannerSessionId,
+      input.workdir,
+      () => cancelled,
+      (handle) => {
+        activeHandle = handle;
+      }
+    );
+    plannerSessionId = planResult.sessionId;
+    const plan = planResult.reply;
+    await emitProgress(input, {
+      stage: "executor",
+      round: 0,
+      message: "Executor \u6B63\u5728\u6839\u636E\u8BA1\u5212\u6267\u884C\u4EFB\u52A1"
+    });
+    let outputResult = await this.executeRole(
+      "executor",
+      buildExecutorPrompt(objective, plan),
+      executorSessionId,
+      input.workdir,
+      () => cancelled,
+      (handle) => {
+        activeHandle = handle;
+      }
+    );
+    executorSessionId = outputResult.sessionId;
+    let finalReviewReply = "";
+    let approved = false;
+    let repairRounds = 0;
+    for (let attempt = 0; attempt <= maxRepairRounds; attempt += 1) {
+      await emitProgress(input, {
+        stage: "reviewer",
+        round: attempt,
+        message: `Reviewer \u6B63\u5728\u8FDB\u884C\u8D28\u91CF\u5BA1\u67E5\uFF08round ${attempt + 1}\uFF09`
+      });
+      const reviewResult = await this.executeRole(
+        "reviewer",
+        buildReviewerPrompt(objective, plan, outputResult.reply),
+        reviewerSessionId,
+        input.workdir,
+        () => cancelled,
+        (handle) => {
+          activeHandle = handle;
+        }
+      );
+      reviewerSessionId = reviewResult.sessionId;
+      finalReviewReply = reviewResult.reply;
+      const verdict = parseReviewerVerdict(finalReviewReply);
+      if (verdict.approved) {
+        approved = true;
+        break;
+      }
+      if (attempt >= maxRepairRounds) {
+        break;
+      }
+      repairRounds = attempt + 1;
+      await emitProgress(input, {
+        stage: "repair",
+        round: repairRounds,
+        message: `Executor \u6B63\u5728\u6309 Reviewer \u53CD\u9988\u8FDB\u884C\u4FEE\u590D\uFF08round ${repairRounds}\uFF09`
+      });
+      outputResult = await this.executeRole(
+        "executor",
+        buildRepairPrompt(objective, plan, outputResult.reply, verdict.feedback, repairRounds),
+        executorSessionId,
+        input.workdir,
+        () => cancelled,
+        (handle) => {
+          activeHandle = handle;
+        }
+      );
+      executorSessionId = outputResult.sessionId;
+    }
+    const durationMs = Date.now() - startedAt;
+    this.logger.info("Multi-agent workflow finished", {
+      objective,
+      approved,
+      repairRounds,
+      durationMs
+    });
+    return {
+      objective,
+      plan,
+      output: outputResult.reply,
+      review: finalReviewReply,
+      approved,
+      repairRounds,
+      durationMs
+    };
+  }
+  async executeRole(role, prompt, sessionId, workdir, getCancelled, setActiveHandle) {
+    if (getCancelled()) {
+      throw new CodexExecutionCancelledError("workflow cancelled");
+    }
+    const handle = this.executor.startExecution(prompt, sessionId, void 0, { workdir });
+    setActiveHandle(handle);
+    try {
+      const result = await handle.result;
+      return {
+        sessionId: result.sessionId,
+        reply: result.reply
+      };
+    } finally {
+      setActiveHandle(null);
+    }
+  }
+};
+async function emitProgress(input, event) {
+  if (!input.onProgress) {
+    return;
+  }
+  await input.onProgress(event);
+}
+function buildPlannerPrompt(objective) {
+  return [
+    "[role:planner]",
+    "\u4F60\u662F\u8F6F\u4EF6\u4EA4\u4ED8\u89C4\u5212\u4EE3\u7406\u3002\u8BF7\u57FA\u4E8E\u76EE\u6807\u7ED9\u51FA\u53EF\u6267\u884C\u8BA1\u5212\u3002",
+    "\u8F93\u51FA\u8981\u6C42\uFF1A",
+    "1. \u4EFB\u52A1\u62C6\u89E3\uFF083-7 \u6B65\uFF09",
+    "2. \u6BCF\u6B65\u8F93\u5165/\u8F93\u51FA",
+    "3. \u98CE\u9669\u4E0E\u56DE\u9000\u65B9\u6848",
+    "",
+    `\u76EE\u6807\uFF1A${objective}`
+  ].join("\n");
+}
+function buildExecutorPrompt(objective, plan) {
+  return [
+    "[role:executor]",
+    "\u4F60\u662F\u8F6F\u4EF6\u6267\u884C\u4EE3\u7406\u3002\u8BF7\u6839\u636E\u8BA1\u5212\u5B8C\u6210\u4EA4\u4ED8\u5185\u5BB9\u3002",
+    "\u8F93\u51FA\u8981\u6C42\uFF1A",
+    "1. \u76F4\u63A5\u7ED9\u51FA\u6700\u7EC8\u53EF\u6267\u884C\u7ED3\u679C",
+    "2. \u8BF4\u660E\u4F60\u5B9E\u9645\u5B8C\u6210\u4E86\u54EA\u4E9B\u6B65\u9AA4",
+    "3. \u5982\u679C\u9700\u8981\u6587\u4EF6\u843D\u76D8\uFF0C\u8BF7\u7ED9\u51FA\u7EDD\u5BF9\u8DEF\u5F84",
+    "",
+    `\u76EE\u6807\uFF1A${objective}`,
+    "",
+    "[planner_plan]",
+    plan,
+    "[/planner_plan]"
+  ].join("\n");
+}
+function buildReviewerPrompt(objective, plan, output) {
+  return [
+    "[role:reviewer]",
+    "\u4F60\u662F\u8D28\u91CF\u5BA1\u67E5\u4EE3\u7406\u3002\u8BF7\u4E25\u683C\u5BA1\u67E5\u6267\u884C\u7ED3\u679C\u662F\u5426\u8FBE\u6210\u76EE\u6807\u3002",
+    "\u8F93\u51FA\u683C\u5F0F\u5FC5\u987B\u5305\u542B\u4EE5\u4E0B\u5B57\u6BB5\uFF1A",
+    "VERDICT: APPROVED \u6216 REJECTED",
+    "SUMMARY: \u4E00\u53E5\u8BDD\u603B\u7ED3",
+    "ISSUES:",
+    "- issue 1",
+    "- issue 2",
+    "SUGGESTIONS:",
+    "- suggestion 1",
+    "- suggestion 2",
+    "",
+    `\u76EE\u6807\uFF1A${objective}`,
+    "",
+    "[planner_plan]",
+    plan,
+    "[/planner_plan]",
+    "",
+    "[executor_output]",
+    output,
+    "[/executor_output]"
+  ].join("\n");
+}
+function buildRepairPrompt(objective, plan, previousOutput, reviewerFeedback, round) {
+  return [
+    "[role:executor]",
+    `\u4F60\u662F\u8F6F\u4EF6\u6267\u884C\u4EE3\u7406\u3002\u8BF7\u6839\u636E\u5BA1\u67E5\u53CD\u9988\u8FDB\u884C\u7B2C ${round} \u8F6E\u4FEE\u590D\u5E76\u8F93\u51FA\u6700\u7EC8\u7248\u672C\u3002`,
+    "\u8981\u6C42\uFF1A\u4FDD\u6301\u6B63\u786E\u5185\u5BB9\uFF0C\u4FEE\u590D\u95EE\u9898\uFF0C\u4E0D\u8981\u4E22\u5931\u5DF2\u5B8C\u6210\u90E8\u5206\u3002",
+    "",
+    `\u76EE\u6807\uFF1A${objective}`,
+    "",
+    "[planner_plan]",
+    plan,
+    "[/planner_plan]",
+    "",
+    "[previous_output]",
+    previousOutput,
+    "[/previous_output]",
+    "",
+    "[reviewer_feedback]",
+    reviewerFeedback,
+    "[/reviewer_feedback]"
+  ].join("\n");
+}
+function parseReviewerVerdict(review) {
+  const approved = /\bVERDICT\s*:\s*APPROVED\b/i.test(review);
+  const rejected = /\bVERDICT\s*:\s*REJECTED\b/i.test(review);
+  if (approved) {
+    return { approved: true, feedback: review };
+  }
+  if (rejected) {
+    return { approved: false, feedback: review };
+  }
+  return {
+    approved: false,
+    feedback: review.trim() || "Reviewer \u672A\u8FD4\u56DE\u89C4\u8303 verdict\uFF0C\u9ED8\u8BA4\u6309 REJECTED \u5904\u7406\u3002"
+  };
+}
+function parseWorkflowCommand(text) {
+  const normalized = text.trim();
+  if (!normalized.startsWith("/agents")) {
+    return null;
+  }
+  const parts = normalized.split(/\s+/);
+  if (parts.length === 1 || parts[1]?.toLowerCase() === "status") {
+    return { kind: "status" };
+  }
+  if (parts[1]?.toLowerCase() !== "run") {
+    return null;
+  }
+  const objective = normalized.replace(/^\/agents\s+run\s*/i, "").trim();
+  return {
+    kind: "run",
+    objective
+  };
+}
+function createIdleWorkflowSnapshot() {
+  return {
+    state: "idle",
+    startedAt: null,
+    endedAt: null,
+    objective: null,
+    approved: null,
+    repairRounds: 0,
+    error: null
+  };
+}
+
 // src/orchestrator.ts
 var RequestMetrics = class {
   total = 0;
@@ -2965,6 +3642,8 @@ var Orchestrator = class {
   rateLimiter;
   cliCompat;
   cliCompatRecorder;
+  workflowRunner;
+  workflowSnapshots = /* @__PURE__ */ new Map();
   metrics = new RequestMetrics();
   lastLockPruneAt = 0;
   constructor(channel, executor, stateStore, logger, options) {
@@ -3011,6 +3690,10 @@ var Orchestrator = class {
         maxConcurrentPerRoom: 4
       }
     );
+    this.workflowRunner = new MultiAgentWorkflowRunner(this.executor, this.logger, {
+      enabled: options?.multiAgentWorkflow?.enabled ?? false,
+      autoRepairMaxRounds: options?.multiAgentWorkflow?.autoRepairMaxRounds ?? 1
+    });
     this.sessionRuntime = new CodexSessionRuntime(this.executor);
   }
   async handleMessage(message) {
@@ -3054,6 +3737,12 @@ var Orchestrator = class {
         this.stateStore.markEventProcessed(sessionKey, message.eventId);
         return;
       }
+      const workflowCommand = this.workflowRunner.isEnabled() ? parseWorkflowCommand(route.prompt) : null;
+      if (workflowCommand?.kind === "status") {
+        await this.handleWorkflowStatusCommand(sessionKey, message);
+        this.stateStore.markEventProcessed(sessionKey, message.eventId);
+        return;
+      }
       const rateDecision = this.rateLimiter.tryAcquire({
         userId: message.senderId,
         roomId: message.conversationId
@@ -3071,6 +3760,37 @@ var Orchestrator = class {
         });
         return;
       }
+      if (workflowCommand?.kind === "run") {
+        const executionStartedAt = Date.now();
+        let sendDurationMs2 = 0;
+        this.stateStore.activateSession(sessionKey, this.sessionActiveWindowMs);
+        try {
+          const sendStartedAt = Date.now();
+          await this.handleWorkflowRunCommand(
+            workflowCommand.objective,
+            sessionKey,
+            message,
+            requestId,
+            roomConfig.workdir
+          );
+          sendDurationMs2 += Date.now() - sendStartedAt;
+          this.stateStore.markEventProcessed(sessionKey, message.eventId);
+          this.metrics.record("success", queueWaitMs, Date.now() - executionStartedAt, sendDurationMs2);
+        } catch (error) {
+          sendDurationMs2 += await this.sendWorkflowFailure(message.conversationId, error);
+          this.stateStore.commitExecutionHandled(sessionKey, message.eventId);
+          const status = classifyExecutionOutcome(error);
+          this.metrics.record(status, queueWaitMs, Date.now() - executionStartedAt, sendDurationMs2);
+          this.logger.error("Workflow request failed", {
+            requestId,
+            sessionKey,
+            error: formatError2(error)
+          });
+        } finally {
+          rateDecision.release?.();
+        }
+        return;
+      }
       this.stateStore.activateSession(sessionKey, this.sessionActiveWindowMs);
       const previousCodexSessionId = this.stateStore.getCodexSessionId(sessionKey);
       const executionPrompt = this.buildExecutionPrompt(route.prompt, message);
@@ -3291,6 +4011,7 @@ var Orchestrator = class {
     const metrics = this.metrics.snapshot(this.runningExecutions.size);
     const limiter = this.rateLimiter.snapshot();
     const runtime = this.sessionRuntime.getRuntimeStats();
+    const workflow = this.workflowSnapshots.get(sessionKey) ?? createIdleWorkflowSnapshot();
     await this.channel.sendNotice(
       message.conversationId,
       `[CodeHarbor] \u5F53\u524D\u72B6\u6001
@@ -3303,9 +4024,122 @@ var Orchestrator = class {
 - \u6307\u6807: total=${metrics.total}, success=${metrics.success}, failed=${metrics.failed}, timeout=${metrics.timeout}, cancelled=${metrics.cancelled}, rate_limited=${metrics.rateLimited}
 - \u5E73\u5747\u8017\u65F6: queue=${metrics.avgQueueMs}ms, exec=${metrics.avgExecMs}ms, send=${metrics.avgSendMs}ms
 - \u9650\u6D41\u5E76\u53D1: global=${limiter.activeGlobal}, users=${limiter.activeUsers}, rooms=${limiter.activeRooms}
-- CLI runtime: workers=${runtime.workerCount}, running=${runtime.runningCount}, compat_mode=${this.cliCompat.enabled ? "on" : "off"}`
+- CLI runtime: workers=${runtime.workerCount}, running=${runtime.runningCount}, compat_mode=${this.cliCompat.enabled ? "on" : "off"}
+- Multi-Agent workflow: enabled=${this.workflowRunner.isEnabled() ? "on" : "off"}, state=${workflow.state}`
+    );
+  }
+  async handleWorkflowStatusCommand(sessionKey, message) {
+    const snapshot = this.workflowSnapshots.get(sessionKey) ?? createIdleWorkflowSnapshot();
+    await this.channel.sendNotice(
+      message.conversationId,
+      `[CodeHarbor] Multi-Agent \u5DE5\u4F5C\u6D41\u72B6\u6001
+- state: ${snapshot.state}
+- startedAt: ${snapshot.startedAt ?? "N/A"}
+- endedAt: ${snapshot.endedAt ?? "N/A"}
+- objective: ${snapshot.objective ?? "N/A"}
+- approved: ${snapshot.approved === null ? "N/A" : snapshot.approved ? "yes" : "no"}
+- repairRounds: ${snapshot.repairRounds}
+- error: ${snapshot.error ?? "N/A"}`
     );
   }
+  async handleWorkflowRunCommand(objective, sessionKey, message, requestId, workdir) {
+    const normalizedObjective = objective.trim();
+    if (!normalizedObjective) {
+      await this.channel.sendNotice(message.conversationId, "[CodeHarbor] /agents run \u9700\u8981\u63D0\u4F9B\u4EFB\u52A1\u76EE\u6807\u3002");
+      return;
+    }
+    const requestStartedAt = Date.now();
+    let progressNoticeEventId = null;
+    const progressCtx = {
+      conversationId: message.conversationId,
+      isDirectMessage: message.isDirectMessage,
+      getProgressNoticeEventId: () => progressNoticeEventId,
+      setProgressNoticeEventId: (next) => {
+        progressNoticeEventId = next;
+      }
+    };
+    const startedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+    this.workflowSnapshots.set(sessionKey, {
+      state: "running",
+      startedAt: startedAtIso,
+      endedAt: null,
+      objective: normalizedObjective,
+      approved: null,
+      repairRounds: 0,
+      error: null
+    });
+    const stopTyping = this.startTypingHeartbeat(message.conversationId);
+    let cancelWorkflow = () => {
+    };
+    let cancelRequested = false;
+    this.runningExecutions.set(sessionKey, {
+      requestId,
+      startedAt: requestStartedAt,
+      cancel: () => {
+        cancelRequested = true;
+        cancelWorkflow();
+      }
+    });
+    await this.sendProgressUpdate(progressCtx, "[CodeHarbor] Multi-Agent workflow \u542F\u52A8\uFF1APlanner -> Executor -> Reviewer");
+    try {
+      const result = await this.workflowRunner.run({
+        objective: normalizedObjective,
+        workdir,
+        onRegisterCancel: (cancel) => {
+          cancelWorkflow = cancel;
+          if (cancelRequested) {
+            cancelWorkflow();
+          }
+        },
+        onProgress: async (event) => {
+          const stepLabel = event.stage.toUpperCase();
+          await this.sendProgressUpdate(progressCtx, `[CodeHarbor] [${stepLabel}] ${event.message}`);
+        }
+      });
+      const endedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+      this.workflowSnapshots.set(sessionKey, {
+        state: "succeeded",
+        startedAt: startedAtIso,
+        endedAt: endedAtIso,
+        objective: normalizedObjective,
+        approved: result.approved,
+        repairRounds: result.repairRounds,
+        error: null
+      });
+      await this.channel.sendMessage(message.conversationId, buildWorkflowResultReply(result));
+      await this.finishProgress(progressCtx, `\u591A\u667A\u80FD\u4F53\u6D41\u7A0B\u5B8C\u6210\uFF08\u8017\u65F6 ${formatDurationMs(Date.now() - requestStartedAt)}\uFF09`);
+    } catch (error) {
+      const status = classifyExecutionOutcome(error);
+      const endedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+      this.workflowSnapshots.set(sessionKey, {
+        state: status === "cancelled" ? "idle" : "failed",
+        startedAt: startedAtIso,
+        endedAt: endedAtIso,
+        objective: normalizedObjective,
+        approved: null,
+        repairRounds: 0,
+        error: formatError2(error)
+      });
+      await this.finishProgress(progressCtx, buildFailureProgressSummary(status, requestStartedAt, error));
+      throw error;
+    } finally {
+      const running = this.runningExecutions.get(sessionKey);
+      if (running?.requestId === requestId) {
+        this.runningExecutions.delete(sessionKey);
+      }
+      await stopTyping();
+    }
+  }
+  async sendWorkflowFailure(conversationId, error) {
+    const startedAt = Date.now();
+    const status = classifyExecutionOutcome(error);
+    if (status === "cancelled") {
+      await this.channel.sendNotice(conversationId, "[CodeHarbor] Multi-Agent workflow \u5DF2\u53D6\u6D88\u3002");
+      return Date.now() - startedAt;
+    }
+    await this.channel.sendMessage(conversationId, `[CodeHarbor] Multi-Agent workflow \u5931\u8D25: ${formatError2(error)}`);
+    return Date.now() - startedAt;
+  }
   async handleStopCommand(sessionKey, message, requestId) {
     this.stateStore.deactivateSession(sessionKey);
     this.stateStore.clearCodexSessionId(sessionKey);
@@ -3619,10 +4453,29 @@ function buildFailureProgressSummary(status, startedAt, error) {
   }
   return `\u5904\u7406\u5931\u8D25\uFF08\u8017\u65F6 ${elapsed}\uFF09: ${formatError2(error)}`;
 }
+function buildWorkflowResultReply(result) {
+  return `[CodeHarbor] Multi-Agent workflow \u5B8C\u6210
+- objective: ${result.objective}
+- approved: ${result.approved ? "yes" : "no"}
+- repairRounds: ${result.repairRounds}
+- duration: ${formatDurationMs(result.durationMs)}
+
+[planner]
+${result.plan}
+[/planner]
+
+[executor]
+${result.output}
+[/executor]
+
+[reviewer]
+${result.review}
+[/reviewer]`;
+}
 
 // src/store/state-store.ts
-var import_node_fs5 = __toESM(require("fs"));
-var import_node_path6 = __toESM(require("path"));
+var import_node_fs7 = __toESM(require("fs"));
+var import_node_path8 = __toESM(require("path"));
 var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
 var PRUNE_INTERVAL_MS = 5 * 60 * 1e3;
 var SQLITE_MODULE_ID = `node:${"sqlite"}`;
@@ -3648,7 +4501,7 @@ var StateStore = class {
     this.maxProcessedEventsPerSession = maxProcessedEventsPerSession;
     this.maxSessionAgeMs = maxSessionAgeDays * ONE_DAY_MS;
     this.maxSessions = maxSessions;
-    import_node_fs5.default.mkdirSync(import_node_path6.default.dirname(this.dbPath), { recursive: true });
+    import_node_fs7.default.mkdirSync(import_node_path8.default.dirname(this.dbPath), { recursive: true });
     this.db = new DatabaseSync(this.dbPath);
     this.initializeSchema();
     this.importLegacyStateIfNeeded();
@@ -3893,7 +4746,7 @@ var StateStore = class {
     `);
   }
   importLegacyStateIfNeeded() {
-    if (!this.legacyJsonPath || !import_node_fs5.default.existsSync(this.legacyJsonPath)) {
+    if (!this.legacyJsonPath || !import_node_fs7.default.existsSync(this.legacyJsonPath)) {
       return;
     }
     const countRow = this.db.prepare("SELECT COUNT(*) AS count FROM sessions").get();
@@ -3976,7 +4829,7 @@ var StateStore = class {
 };
 function loadLegacyState(filePath) {
   try {
-    const raw = import_node_fs5.default.readFileSync(filePath, "utf8");
+    const raw = import_node_fs7.default.readFileSync(filePath, "utf8");
     const parsed = JSON.parse(raw);
     if (!parsed.sessions || typeof parsed.sessions !== "object") {
       return null;
@@ -4019,7 +4872,7 @@ function boolToInt(value) {
 }
 
 // src/app.ts
-var execFileAsync2 = (0, import_node_util2.promisify)(import_node_child_process3.execFile);
+var execFileAsync2 = (0, import_node_util2.promisify)(import_node_child_process4.execFile);
 var CodeHarborApp = class {
   config;
   logger;
@@ -4061,6 +4914,7 @@ var CodeHarborApp = class {
       roomTriggerPolicies: config.roomTriggerPolicies,
       rateLimiterOptions: config.rateLimiter,
       cliCompat: config.cliCompat,
+      multiAgentWorkflow: config.agentWorkflow,
       configService: this.configService,
       defaultCodexWorkdir: config.codexWorkdir
     });
@@ -4167,8 +5021,8 @@ function isNonLoopbackHost(host) {
 }
 
 // src/config.ts
-var import_node_fs6 = __toESM(require("fs"));
-var import_node_path7 = __toESM(require("path"));
+var import_node_fs8 = __toESM(require("fs"));
+var import_node_path9 = __toESM(require("path"));
 var import_dotenv2 = __toESM(require("dotenv"));
 var import_zod = require("zod");
 var configSchema = import_zod.z.object({
@@ -4185,6 +5039,8 @@ var configSchema = import_zod.z.object({
   CODEX_APPROVAL_POLICY: import_zod.z.string().optional(),
   CODEX_EXTRA_ARGS: import_zod.z.string().default(""),
   CODEX_EXTRA_ENV_JSON: import_zod.z.string().default(""),
+  AGENT_WORKFLOW_ENABLED: import_zod.z.string().default("false").transform((v) => v.toLowerCase() === "true"),
+  AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS: import_zod.z.string().default("1").transform((v) => Number.parseInt(v, 10)).pipe(import_zod.z.number().int().min(0).max(10)),
   STATE_DB_PATH: import_zod.z.string().default("data/state.db"),
   STATE_PATH: import_zod.z.string().default("data/state.json"),
   MAX_PROCESSED_EVENTS_PER_SESSION: import_zod.z.string().default("200").transform((v) => Number.parseInt(v, 10)).pipe(import_zod.z.number().int().positive()),
@@ -4227,15 +5083,19 @@ var configSchema = import_zod.z.object({
   matrixCommandPrefix: v.MATRIX_COMMAND_PREFIX,
   codexBin: v.CODEX_BIN,
   codexModel: v.CODEX_MODEL?.trim() || null,
-  codexWorkdir: import_node_path7.default.resolve(v.CODEX_WORKDIR),
+  codexWorkdir: import_node_path9.default.resolve(v.CODEX_WORKDIR),
   codexDangerousBypass: v.CODEX_DANGEROUS_BYPASS,
   codexExecTimeoutMs: v.CODEX_EXEC_TIMEOUT_MS,
   codexSandboxMode: v.CODEX_SANDBOX_MODE?.trim() || null,
   codexApprovalPolicy: v.CODEX_APPROVAL_POLICY?.trim() || null,
   codexExtraArgs: parseExtraArgs(v.CODEX_EXTRA_ARGS),
   codexExtraEnv: parseExtraEnv(v.CODEX_EXTRA_ENV_JSON),
-  stateDbPath: import_node_path7.default.resolve(v.STATE_DB_PATH),
-  legacyStateJsonPath: v.STATE_PATH.trim() ? import_node_path7.default.resolve(v.STATE_PATH) : null,
+  agentWorkflow: {
+    enabled: v.AGENT_WORKFLOW_ENABLED,
+    autoRepairMaxRounds: v.AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS
+  },
+  stateDbPath: import_node_path9.default.resolve(v.STATE_DB_PATH),
+  legacyStateJsonPath: v.STATE_PATH.trim() ? import_node_path9.default.resolve(v.STATE_PATH) : null,
   maxProcessedEventsPerSession: v.MAX_PROCESSED_EVENTS_PER_SESSION,
   maxSessionAgeDays: v.MAX_SESSION_AGE_DAYS,
   maxSessions: v.MAX_SESSIONS,
@@ -4266,7 +5126,7 @@ var configSchema = import_zod.z.object({
     disableReplyChunkSplit: v.CLI_COMPAT_DISABLE_REPLY_CHUNK_SPLIT,
     progressThrottleMs: v.CLI_COMPAT_PROGRESS_THROTTLE_MS,
     fetchMedia: v.CLI_COMPAT_FETCH_MEDIA,
-    recordPath: v.CLI_COMPAT_RECORD_PATH.trim() ? import_node_path7.default.resolve(v.CLI_COMPAT_RECORD_PATH) : null
+    recordPath: v.CLI_COMPAT_RECORD_PATH.trim() ? import_node_path9.default.resolve(v.CLI_COMPAT_RECORD_PATH) : null
   },
   doctorHttpTimeoutMs: v.DOCTOR_HTTP_TIMEOUT_MS,
   adminBindHost: v.ADMIN_BIND_HOST.trim() || "127.0.0.1",
@@ -4276,7 +5136,7 @@ var configSchema = import_zod.z.object({
   adminAllowedOrigins: parseCsvList(v.ADMIN_ALLOWED_ORIGINS),
   logLevel: v.LOG_LEVEL
 }));
-function loadEnvFromFile(filePath = import_node_path7.default.resolve(process.cwd(), ".env"), env = process.env) {
+function loadEnvFromFile(filePath = import_node_path9.default.resolve(process.cwd(), ".env"), env = process.env) {
   import_dotenv2.default.config({
     path: filePath,
     processEnv: env,
@@ -4289,9 +5149,9 @@ function loadConfig(env = process.env) {
     const message = parsed.error.issues.map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`).join("; ");
     throw new Error(`Invalid configuration: ${message}`);
   }
-  import_node_fs6.default.mkdirSync(import_node_path7.default.dirname(parsed.data.stateDbPath), { recursive: true });
+  import_node_fs8.default.mkdirSync(import_node_path9.default.dirname(parsed.data.stateDbPath), { recursive: true });
   if (parsed.data.legacyStateJsonPath) {
-    import_node_fs6.default.mkdirSync(import_node_path7.default.dirname(parsed.data.legacyStateJsonPath), { recursive: true });
+    import_node_fs8.default.mkdirSync(import_node_path9.default.dirname(parsed.data.legacyStateJsonPath), { recursive: true });
   }
   return parsed.data;
 }
@@ -4364,8 +5224,8 @@ function parseCsvList(raw) {
 }
 
 // src/config-snapshot.ts
-var import_node_fs7 = __toESM(require("fs"));
-var import_node_path8 = __toESM(require("path"));
+var import_node_fs9 = __toESM(require("fs"));
+var import_node_path10 = __toESM(require("path"));
 var import_zod2 = require("zod");
 var CONFIG_SNAPSHOT_SCHEMA_VERSION = 1;
 var CONFIG_SNAPSHOT_ENV_KEYS = [
@@ -4382,6 +5242,8 @@ var CONFIG_SNAPSHOT_ENV_KEYS = [
   "CODEX_APPROVAL_POLICY",
   "CODEX_EXTRA_ARGS",
   "CODEX_EXTRA_ENV_JSON",
+  "AGENT_WORKFLOW_ENABLED",
+  "AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS",
   "STATE_DB_PATH",
   "STATE_PATH",
   "MAX_PROCESSED_EVENTS_PER_SESSION",
@@ -4444,6 +5306,8 @@ var envSnapshotSchema = import_zod2.z.object({
   CODEX_APPROVAL_POLICY: import_zod2.z.string(),
   CODEX_EXTRA_ARGS: import_zod2.z.string(),
   CODEX_EXTRA_ENV_JSON: jsonObjectStringSchema("CODEX_EXTRA_ENV_JSON", true),
+  AGENT_WORKFLOW_ENABLED: booleanStringSchema("AGENT_WORKFLOW_ENABLED"),
+  AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS: integerStringSchema("AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS", 0, 10),
   STATE_DB_PATH: import_zod2.z.string().min(1),
   STATE_PATH: import_zod2.z.string(),
   MAX_PROCESSED_EVENTS_PER_SESSION: integerStringSchema("MAX_PROCESSED_EVENTS_PER_SESSION", 1),
@@ -4548,9 +5412,9 @@ async function runConfigExportCommand(options = {}) {
     const snapshot = buildConfigSnapshot(config, stateStore.listRoomSettings(), options.now ?? /* @__PURE__ */ new Date());
     const serialized = serializeConfigSnapshot(snapshot);
     if (options.outputPath) {
-      const targetPath = import_node_path8.default.resolve(cwd, options.outputPath);
-      import_node_fs7.default.mkdirSync(import_node_path8.default.dirname(targetPath), { recursive: true });
-      import_node_fs7.default.writeFileSync(targetPath, serialized, "utf8");
+      const targetPath = import_node_path10.default.resolve(cwd, options.outputPath);
+      import_node_fs9.default.mkdirSync(import_node_path10.default.dirname(targetPath), { recursive: true });
+      import_node_fs9.default.writeFileSync(targetPath, serialized, "utf8");
       output.write(`Exported config snapshot to ${targetPath}
 `);
       return;
@@ -4564,8 +5428,8 @@ async function runConfigImportCommand(options) {
   const cwd = options.cwd ?? process.cwd();
   const output = options.output ?? process.stdout;
   const actor = options.actor?.trim() || "cli:config-import";
-  const sourcePath = import_node_path8.default.resolve(cwd, options.filePath);
-  if (!import_node_fs7.default.existsSync(sourcePath)) {
+  const sourcePath = import_node_path10.default.resolve(cwd, options.filePath);
+  if (!import_node_fs9.default.existsSync(sourcePath)) {
     throw new Error(`Config snapshot file not found: ${sourcePath}`);
   }
   const snapshot = parseConfigSnapshot(parseJsonFile(sourcePath));
@@ -4595,7 +5459,7 @@ async function runConfigImportCommand(options) {
     synchronizeRoomSettings(stateStore, normalizedRooms);
     stateStore.appendConfigRevision(
       actor,
-      `import config snapshot from ${import_node_path8.default.basename(sourcePath)}`,
+      `import config snapshot from ${import_node_path10.default.basename(sourcePath)}`,
       JSON.stringify({
         type: "config_snapshot_import",
         sourcePath,
@@ -4609,7 +5473,7 @@ async function runConfigImportCommand(options) {
   output.write(
     [
       `Imported config snapshot from ${sourcePath}`,
-      `- updated .env in ${import_node_path8.default.resolve(cwd, ".env")}`,
+      `- updated .env in ${import_node_path10.default.resolve(cwd, ".env")}`,
       `- synchronized room settings: ${normalizedRooms.length}`,
       "- restart required: yes (global env settings are restart-scoped)"
     ].join("\n") + "\n"
@@ -4630,6 +5494,8 @@ function buildSnapshotEnv(config) {
     CODEX_APPROVAL_POLICY: config.codexApprovalPolicy ?? "",
     CODEX_EXTRA_ARGS: config.codexExtraArgs.join(" "),
     CODEX_EXTRA_ENV_JSON: serializeJsonObject(config.codexExtraEnv),
+    AGENT_WORKFLOW_ENABLED: String(config.agentWorkflow.enabled),
+    AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS: String(config.agentWorkflow.autoRepairMaxRounds),
     STATE_DB_PATH: config.stateDbPath,
     STATE_PATH: config.legacyStateJsonPath ?? "",
     MAX_PROCESSED_EVENTS_PER_SESSION: String(config.maxProcessedEventsPerSession),
@@ -4669,7 +5535,7 @@ function buildSnapshotEnv(config) {
 }
 function parseJsonFile(filePath) {
   try {
-    const raw = import_node_fs7.default.readFileSync(filePath, "utf8");
+    const raw = import_node_fs9.default.readFileSync(filePath, "utf8");
     return JSON.parse(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -4681,525 +5547,233 @@ function parseJsonFile(filePath) {
 function normalizeSnapshotEnv(env, cwd) {
   return {
     ...env,
-    CODEX_WORKDIR: import_node_path8.default.resolve(cwd, env.CODEX_WORKDIR),
-    STATE_DB_PATH: import_node_path8.default.resolve(cwd, env.STATE_DB_PATH),
-    STATE_PATH: env.STATE_PATH.trim() ? import_node_path8.default.resolve(cwd, env.STATE_PATH) : "",
-    CLI_COMPAT_RECORD_PATH: env.CLI_COMPAT_RECORD_PATH.trim() ? import_node_path8.default.resolve(cwd, env.CLI_COMPAT_RECORD_PATH) : ""
+    CODEX_WORKDIR: import_node_path10.default.resolve(cwd, env.CODEX_WORKDIR),
+    STATE_DB_PATH: import_node_path10.default.resolve(cwd, env.STATE_DB_PATH),
+    STATE_PATH: env.STATE_PATH.trim() ? import_node_path10.default.resolve(cwd, env.STATE_PATH) : "",
+    CLI_COMPAT_RECORD_PATH: env.CLI_COMPAT_RECORD_PATH.trim() ? import_node_path10.default.resolve(cwd, env.CLI_COMPAT_RECORD_PATH) : ""
   };
 }
 function normalizeSnapshotRooms(rooms, cwd) {
-  const normalized = [];
-  const seen = /* @__PURE__ */ new Set();
-  for (const room of rooms) {
-    const roomId = room.roomId.trim();
-    if (!roomId) {
-      throw new Error("roomId is required for every room in snapshot.");
-    }
-    if (seen.has(roomId)) {
-      throw new Error(`Duplicate roomId in snapshot: ${roomId}`);
-    }
-    seen.add(roomId);
-    const workdir = import_node_path8.default.resolve(cwd, room.workdir);
-    ensureDirectory2(workdir, `room workdir (${roomId})`);
-    normalized.push({
-      roomId,
-      enabled: room.enabled,
-      allowMention: room.allowMention,
-      allowReply: room.allowReply,
-      allowActiveWindow: room.allowActiveWindow,
-      allowPrefix: room.allowPrefix,
-      workdir
-    });
-  }
-  return normalized;
-}
-function synchronizeRoomSettings(stateStore, rooms) {
-  const incoming = new Map(rooms.map((room) => [room.roomId, room]));
-  const existing = stateStore.listRoomSettings();
-  for (const room of existing) {
-    if (!incoming.has(room.roomId)) {
-      stateStore.deleteRoomSettings(room.roomId);
-    }
-  }
-  for (const room of rooms) {
-    stateStore.upsertRoomSettings(room);
-  }
-}
-function persistEnvSnapshot(cwd, env) {
-  const envPath = import_node_path8.default.resolve(cwd, ".env");
-  const examplePath = import_node_path8.default.resolve(cwd, ".env.example");
-  const template = import_node_fs7.default.existsSync(envPath) ? import_node_fs7.default.readFileSync(envPath, "utf8") : import_node_fs7.default.existsSync(examplePath) ? import_node_fs7.default.readFileSync(examplePath, "utf8") : "";
-  const overrides = {};
-  for (const key of CONFIG_SNAPSHOT_ENV_KEYS) {
-    overrides[key] = env[key];
-  }
-  const next = applyEnvOverrides(template, overrides);
-  import_node_fs7.default.writeFileSync(envPath, next, "utf8");
-}
-function ensureDirectory2(dirPath, label) {
-  if (!import_node_fs7.default.existsSync(dirPath) || !import_node_fs7.default.statSync(dirPath).isDirectory()) {
-    throw new Error(`${label} does not exist or is not a directory: ${dirPath}`);
-  }
-}
-function parseIntStrict(raw) {
-  const value = Number.parseInt(raw, 10);
-  if (!Number.isFinite(value)) {
-    throw new Error(`Invalid integer value: ${raw}`);
-  }
-  return value;
-}
-function serializeJsonObject(value) {
-  return Object.keys(value).length > 0 ? JSON.stringify(value) : "";
-}
-function booleanStringSchema(key) {
-  return import_zod2.z.string().refine((value) => BOOLEAN_STRING.test(value), {
-    message: `${key} must be a boolean string (true/false).`
-  });
-}
-function integerStringSchema(key, min, max = Number.MAX_SAFE_INTEGER) {
-  return import_zod2.z.string().refine((value) => {
-    const trimmed = value.trim();
-    if (!INTEGER_STRING.test(trimmed)) {
-      return false;
-    }
-    const parsed = Number.parseInt(trimmed, 10);
-    if (!Number.isFinite(parsed)) {
-      return false;
-    }
-    return parsed >= min && parsed <= max;
-  }, {
-    message: `${key} must be an integer string in range [${min}, ${max}].`
-  });
-}
-function jsonObjectStringSchema(key, allowEmpty) {
-  return import_zod2.z.string().refine((value) => {
-    const trimmed = value.trim();
-    if (!trimmed) {
-      return allowEmpty;
-    }
-    let parsed;
-    try {
-      parsed = JSON.parse(trimmed);
-    } catch {
-      return false;
-    }
-    return Boolean(parsed) && typeof parsed === "object" && !Array.isArray(parsed);
-  }, {
-    message: `${key} must be an empty string or a JSON object string.`
-  });
-}
-
-// src/preflight.ts
-var import_node_child_process4 = require("child_process");
-var import_node_fs8 = __toESM(require("fs"));
-var import_node_path9 = __toESM(require("path"));
-var import_node_util3 = require("util");
-var execFileAsync3 = (0, import_node_util3.promisify)(import_node_child_process4.execFile);
-var REQUIRED_ENV_KEYS = ["MATRIX_HOMESERVER", "MATRIX_USER_ID", "MATRIX_ACCESS_TOKEN"];
-async function runStartupPreflight(options = {}) {
-  const env = options.env ?? process.env;
-  const cwd = options.cwd ?? process.cwd();
-  const checkCodexBinary = options.checkCodexBinary ?? defaultCheckCodexBinary;
-  const fileExists = options.fileExists ?? import_node_fs8.default.existsSync;
-  const isDirectory = options.isDirectory ?? defaultIsDirectory;
-  const issues = [];
-  const envPath = import_node_path9.default.resolve(cwd, ".env");
-  if (!fileExists(envPath)) {
-    issues.push({
-      level: "warn",
-      code: "missing_dotenv",
-      check: ".env",
-      message: `No .env file found at ${envPath}.`,
-      fix: 'Run "codeharbor init" to create baseline config.'
-    });
-  }
-  for (const key of REQUIRED_ENV_KEYS) {
-    if (!readEnv(env, key)) {
-      issues.push({
-        level: "error",
-        code: "missing_env",
-        check: key,
-        message: `${key} is required.`,
-        fix: `Run "codeharbor init" or set ${key} in .env.`
-      });
-    }
-  }
-  const matrixHomeserver = readEnv(env, "MATRIX_HOMESERVER");
-  if (matrixHomeserver) {
-    try {
-      new URL(matrixHomeserver);
-    } catch {
-      issues.push({
-        level: "error",
-        code: "invalid_matrix_homeserver",
-        check: "MATRIX_HOMESERVER",
-        message: `Invalid URL: "${matrixHomeserver}".`,
-        fix: "Set MATRIX_HOMESERVER to a full URL, for example https://matrix.example.com."
-      });
-    }
-  }
-  const matrixUserId = readEnv(env, "MATRIX_USER_ID");
-  if (matrixUserId && !/^@[^:\s]+:.+/.test(matrixUserId)) {
-    issues.push({
-      level: "error",
-      code: "invalid_matrix_user_id",
-      check: "MATRIX_USER_ID",
-      message: `Unexpected Matrix user id format: "${matrixUserId}".`,
-      fix: "Set MATRIX_USER_ID like @bot:example.com."
-    });
-  }
-  const codexBin = readEnv(env, "CODEX_BIN") || "codex";
-  try {
-    await checkCodexBinary(codexBin);
-  } catch (error) {
-    const reason = error instanceof Error && error.message ? ` (${error.message})` : "";
-    issues.push({
-      level: "error",
-      code: "missing_codex_bin",
-      check: "CODEX_BIN",
-      message: `Unable to execute "${codexBin}"${reason}.`,
-      fix: `Install Codex CLI and ensure "${codexBin}" is in PATH, or set CODEX_BIN=/absolute/path/to/codex.`
-    });
-  }
-  const configuredWorkdir = readEnv(env, "CODEX_WORKDIR");
-  const workdir = import_node_path9.default.resolve(cwd, configuredWorkdir || cwd);
-  if (!fileExists(workdir) || !isDirectory(workdir)) {
-    issues.push({
-      level: "error",
-      code: "invalid_codex_workdir",
-      check: "CODEX_WORKDIR",
-      message: `Working directory does not exist or is not a directory: ${workdir}.`,
-      fix: `Set CODEX_WORKDIR to an existing directory, for example CODEX_WORKDIR=${cwd}.`
-    });
-  }
-  return {
-    ok: issues.every((issue) => issue.level !== "error"),
-    issues
-  };
-}
-function formatPreflightReport(result, commandName) {
-  const lines = [];
-  const errors = result.issues.filter((issue) => issue.level === "error").length;
-  const warnings = result.issues.filter((issue) => issue.level === "warn").length;
-  if (result.ok) {
-    lines.push(`Preflight check passed for "codeharbor ${commandName}" with ${warnings} warning(s).`);
-  } else {
-    lines.push(
-      `Preflight check failed for "codeharbor ${commandName}" with ${errors} error(s) and ${warnings} warning(s).`
-    );
-  }
-  for (const issue of result.issues) {
-    const level = issue.level.toUpperCase();
-    lines.push(`- [${level}] ${issue.check}: ${issue.message}`);
-    lines.push(`  fix: ${issue.fix}`);
-  }
-  return `${lines.join("\n")}
-`;
-}
-async function defaultCheckCodexBinary(bin) {
-  await execFileAsync3(bin, ["--version"]);
-}
-function defaultIsDirectory(targetPath) {
-  try {
-    return import_node_fs8.default.statSync(targetPath).isDirectory();
-  } catch {
-    return false;
-  }
-}
-function readEnv(env, key) {
-  return env[key]?.trim() ?? "";
-}
-
-// src/runtime-home.ts
-var import_node_fs9 = __toESM(require("fs"));
-var import_node_os2 = __toESM(require("os"));
-var import_node_path10 = __toESM(require("path"));
-var LEGACY_RUNTIME_HOME = "/opt/codeharbor";
-var USER_RUNTIME_HOME_DIR = ".codeharbor";
-var DEFAULT_RUNTIME_HOME = import_node_path10.default.resolve(import_node_os2.default.homedir(), USER_RUNTIME_HOME_DIR);
-var RUNTIME_HOME_ENV_KEY = "CODEHARBOR_HOME";
-function resolveRuntimeHome(env = process.env) {
-  const configured = env[RUNTIME_HOME_ENV_KEY]?.trim();
-  if (configured) {
-    return import_node_path10.default.resolve(configured);
-  }
-  const legacyEnvPath = import_node_path10.default.resolve(LEGACY_RUNTIME_HOME, ".env");
-  if (import_node_fs9.default.existsSync(legacyEnvPath)) {
-    return LEGACY_RUNTIME_HOME;
-  }
-  return resolveUserRuntimeHome(env);
-}
-function resolveUserRuntimeHome(env = process.env) {
-  const home = env.HOME?.trim() || import_node_os2.default.homedir();
-  return import_node_path10.default.resolve(home, USER_RUNTIME_HOME_DIR);
-}
-
-// src/service-manager.ts
-var import_node_child_process5 = require("child_process");
-var import_node_fs10 = __toESM(require("fs"));
-var import_node_os3 = __toESM(require("os"));
-var import_node_path11 = __toESM(require("path"));
-var SYSTEMD_DIR = "/etc/systemd/system";
-var MAIN_SERVICE_NAME = "codeharbor.service";
-var ADMIN_SERVICE_NAME = "codeharbor-admin.service";
-function resolveDefaultRunUser(env = process.env) {
-  const sudoUser = env.SUDO_USER?.trim();
-  if (sudoUser) {
-    return sudoUser;
-  }
-  const user = env.USER?.trim();
-  if (user) {
-    return user;
-  }
-  try {
-    return import_node_os3.default.userInfo().username;
-  } catch {
-    return "root";
-  }
-}
-function resolveRuntimeHomeForUser(runUser, env = process.env, explicitRuntimeHome) {
-  const configuredRuntimeHome = explicitRuntimeHome?.trim() || env[RUNTIME_HOME_ENV_KEY]?.trim();
-  if (configuredRuntimeHome) {
-    return import_node_path11.default.resolve(configuredRuntimeHome);
-  }
-  const userHome = resolveUserHome(runUser);
-  if (userHome) {
-    return import_node_path11.default.resolve(userHome, USER_RUNTIME_HOME_DIR);
-  }
-  return import_node_path11.default.resolve(import_node_os3.default.homedir(), USER_RUNTIME_HOME_DIR);
-}
-function buildMainServiceUnit(options) {
-  validateUnitOptions(options);
-  const runtimeHome2 = import_node_path11.default.resolve(options.runtimeHome);
-  return [
-    "[Unit]",
-    "Description=CodeHarbor main service",
-    "After=network-online.target",
-    "Wants=network-online.target",
-    "",
-    "[Service]",
-    "Type=simple",
-    `User=${options.runUser}`,
-    `WorkingDirectory=${runtimeHome2}`,
-    `Environment=CODEHARBOR_HOME=${runtimeHome2}`,
-    `ExecStart=${import_node_path11.default.resolve(options.nodeBinPath)} ${import_node_path11.default.resolve(options.cliScriptPath)} start`,
-    "Restart=always",
-    "RestartSec=3",
-    "NoNewPrivileges=true",
-    "PrivateTmp=true",
-    "ProtectSystem=full",
-    "ProtectHome=false",
-    `ReadWritePaths=${runtimeHome2}`,
-    "",
-    "[Install]",
-    "WantedBy=multi-user.target",
-    ""
-  ].join("\n");
-}
-function buildAdminServiceUnit(options) {
-  validateUnitOptions(options);
-  const runtimeHome2 = import_node_path11.default.resolve(options.runtimeHome);
-  return [
-    "[Unit]",
-    "Description=CodeHarbor admin service",
-    "After=network-online.target",
-    "Wants=network-online.target",
-    "",
-    "[Service]",
-    "Type=simple",
-    `User=${options.runUser}`,
-    `WorkingDirectory=${runtimeHome2}`,
-    `Environment=CODEHARBOR_HOME=${runtimeHome2}`,
-    `ExecStart=${import_node_path11.default.resolve(options.nodeBinPath)} ${import_node_path11.default.resolve(options.cliScriptPath)} admin serve`,
-    "Restart=always",
-    "RestartSec=3",
-    "NoNewPrivileges=true",
-    "PrivateTmp=true",
-    "ProtectSystem=full",
-    "ProtectHome=false",
-    `ReadWritePaths=${runtimeHome2}`,
-    "",
-    "[Install]",
-    "WantedBy=multi-user.target",
-    ""
-  ].join("\n");
-}
-function installSystemdServices(options) {
-  assertLinuxWithSystemd();
-  assertRootPrivileges();
-  const output = options.output ?? process.stdout;
-  const runUser = options.runUser.trim();
-  const runtimeHome2 = import_node_path11.default.resolve(options.runtimeHome);
-  validateSimpleValue(runUser, "runUser");
-  validateSimpleValue(runtimeHome2, "runtimeHome");
-  validateSimpleValue(options.nodeBinPath, "nodeBinPath");
-  validateSimpleValue(options.cliScriptPath, "cliScriptPath");
-  ensureUserExists(runUser);
-  const runGroup = resolveUserGroup(runUser);
-  import_node_fs10.default.mkdirSync(runtimeHome2, { recursive: true });
-  runCommand("chown", ["-R", `${runUser}:${runGroup}`, runtimeHome2]);
-  const mainPath = import_node_path11.default.join(SYSTEMD_DIR, MAIN_SERVICE_NAME);
-  const adminPath = import_node_path11.default.join(SYSTEMD_DIR, ADMIN_SERVICE_NAME);
-  const unitOptions = {
-    runUser,
-    runtimeHome: runtimeHome2,
-    nodeBinPath: options.nodeBinPath,
-    cliScriptPath: options.cliScriptPath
-  };
-  import_node_fs10.default.writeFileSync(mainPath, buildMainServiceUnit(unitOptions), "utf8");
-  if (options.installAdmin) {
-    import_node_fs10.default.writeFileSync(adminPath, buildAdminServiceUnit(unitOptions), "utf8");
-  }
-  runSystemctl(["daemon-reload"]);
-  if (options.startNow) {
-    runSystemctl(["enable", "--now", MAIN_SERVICE_NAME]);
-    if (options.installAdmin) {
-      runSystemctl(["enable", "--now", ADMIN_SERVICE_NAME]);
-    }
-  } else {
-    runSystemctl(["enable", MAIN_SERVICE_NAME]);
-    if (options.installAdmin) {
-      runSystemctl(["enable", ADMIN_SERVICE_NAME]);
-    }
-  }
-  output.write(`Installed systemd unit: ${mainPath}
-`);
-  if (options.installAdmin) {
-    output.write(`Installed systemd unit: ${adminPath}
-`);
-  }
-  output.write("Done. Check status with: systemctl status codeharbor --no-pager\n");
-}
-function uninstallSystemdServices(options) {
-  assertLinuxWithSystemd();
-  assertRootPrivileges();
-  const output = options.output ?? process.stdout;
-  const mainPath = import_node_path11.default.join(SYSTEMD_DIR, MAIN_SERVICE_NAME);
-  const adminPath = import_node_path11.default.join(SYSTEMD_DIR, ADMIN_SERVICE_NAME);
-  stopAndDisableIfPresent(MAIN_SERVICE_NAME);
-  if (import_node_fs10.default.existsSync(mainPath)) {
-    import_node_fs10.default.unlinkSync(mainPath);
-  }
-  if (options.removeAdmin) {
-    stopAndDisableIfPresent(ADMIN_SERVICE_NAME);
-    if (import_node_fs10.default.existsSync(adminPath)) {
-      import_node_fs10.default.unlinkSync(adminPath);
-    }
-  }
-  runSystemctl(["daemon-reload"]);
-  runSystemctlIgnoreFailure(["reset-failed"]);
-  output.write(`Removed systemd unit: ${mainPath}
-`);
-  if (options.removeAdmin) {
-    output.write(`Removed systemd unit: ${adminPath}
-`);
-  }
-  output.write("Done.\n");
-}
-function restartSystemdServices(options) {
-  assertLinuxWithSystemd();
-  assertRootPrivileges();
-  const output = options.output ?? process.stdout;
-  runSystemctl(["restart", MAIN_SERVICE_NAME]);
-  output.write(`Restarted service: ${MAIN_SERVICE_NAME}
-`);
-  if (options.restartAdmin) {
-    runSystemctl(["restart", ADMIN_SERVICE_NAME]);
-    output.write(`Restarted service: ${ADMIN_SERVICE_NAME}
-`);
-  }
-  output.write("Done.\n");
-}
-function resolveUserHome(runUser) {
-  try {
-    const passwdRaw = import_node_fs10.default.readFileSync("/etc/passwd", "utf8");
-    const line = passwdRaw.split(/\r?\n/).find((item) => item.startsWith(`${runUser}:`));
-    if (!line) {
-      return null;
+  const normalized = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const room of rooms) {
+    const roomId = room.roomId.trim();
+    if (!roomId) {
+      throw new Error("roomId is required for every room in snapshot.");
     }
-    const fields = line.split(":");
-    return fields[5] ? fields[5].trim() : null;
-  } catch {
-    return null;
+    if (seen.has(roomId)) {
+      throw new Error(`Duplicate roomId in snapshot: ${roomId}`);
+    }
+    seen.add(roomId);
+    const workdir = import_node_path10.default.resolve(cwd, room.workdir);
+    ensureDirectory2(workdir, `room workdir (${roomId})`);
+    normalized.push({
+      roomId,
+      enabled: room.enabled,
+      allowMention: room.allowMention,
+      allowReply: room.allowReply,
+      allowActiveWindow: room.allowActiveWindow,
+      allowPrefix: room.allowPrefix,
+      workdir
+    });
   }
+  return normalized;
 }
-function validateUnitOptions(options) {
-  validateSimpleValue(options.runUser, "runUser");
-  validateSimpleValue(options.runtimeHome, "runtimeHome");
-  validateSimpleValue(options.nodeBinPath, "nodeBinPath");
-  validateSimpleValue(options.cliScriptPath, "cliScriptPath");
-}
-function validateSimpleValue(value, key) {
-  if (!value.trim()) {
-    throw new Error(`${key} cannot be empty.`);
+function synchronizeRoomSettings(stateStore, rooms) {
+  const incoming = new Map(rooms.map((room) => [room.roomId, room]));
+  const existing = stateStore.listRoomSettings();
+  for (const room of existing) {
+    if (!incoming.has(room.roomId)) {
+      stateStore.deleteRoomSettings(room.roomId);
+    }
   }
-  if (/[\r\n]/.test(value)) {
-    throw new Error(`${key} contains invalid newline characters.`);
+  for (const room of rooms) {
+    stateStore.upsertRoomSettings(room);
   }
 }
-function assertLinuxWithSystemd() {
-  if (process.platform !== "linux") {
-    throw new Error("Systemd service install only supports Linux.");
-  }
-  try {
-    (0, import_node_child_process5.execFileSync)("systemctl", ["--version"], { stdio: "ignore" });
-  } catch {
-    throw new Error("systemctl is required but not found.");
+function persistEnvSnapshot(cwd, env) {
+  const envPath = import_node_path10.default.resolve(cwd, ".env");
+  const examplePath = import_node_path10.default.resolve(cwd, ".env.example");
+  const template = import_node_fs9.default.existsSync(envPath) ? import_node_fs9.default.readFileSync(envPath, "utf8") : import_node_fs9.default.existsSync(examplePath) ? import_node_fs9.default.readFileSync(examplePath, "utf8") : "";
+  const overrides = {};
+  for (const key of CONFIG_SNAPSHOT_ENV_KEYS) {
+    overrides[key] = env[key];
   }
+  const next = applyEnvOverrides(template, overrides);
+  import_node_fs9.default.writeFileSync(envPath, next, "utf8");
 }
-function assertRootPrivileges() {
-  if (typeof process.getuid !== "function") {
-    return;
+function ensureDirectory2(dirPath, label) {
+  if (!import_node_fs9.default.existsSync(dirPath) || !import_node_fs9.default.statSync(dirPath).isDirectory()) {
+    throw new Error(`${label} does not exist or is not a directory: ${dirPath}`);
   }
-  if (process.getuid() !== 0) {
-    throw new Error("Root privileges are required. Run with sudo.");
+}
+function parseIntStrict(raw) {
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isFinite(value)) {
+    throw new Error(`Invalid integer value: ${raw}`);
   }
+  return value;
 }
-function ensureUserExists(runUser) {
-  runCommand("id", ["-u", runUser]);
+function serializeJsonObject(value) {
+  return Object.keys(value).length > 0 ? JSON.stringify(value) : "";
 }
-function resolveUserGroup(runUser) {
-  return runCommand("id", ["-gn", runUser]).trim();
+function booleanStringSchema(key) {
+  return import_zod2.z.string().refine((value) => BOOLEAN_STRING.test(value), {
+    message: `${key} must be a boolean string (true/false).`
+  });
 }
-function runSystemctl(args) {
-  runCommand("systemctl", args);
+function integerStringSchema(key, min, max = Number.MAX_SAFE_INTEGER) {
+  return import_zod2.z.string().refine((value) => {
+    const trimmed = value.trim();
+    if (!INTEGER_STRING.test(trimmed)) {
+      return false;
+    }
+    const parsed = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(parsed)) {
+      return false;
+    }
+    return parsed >= min && parsed <= max;
+  }, {
+    message: `${key} must be an integer string in range [${min}, ${max}].`
+  });
 }
-function stopAndDisableIfPresent(unitName) {
-  runSystemctlIgnoreFailure(["disable", "--now", unitName]);
+function jsonObjectStringSchema(key, allowEmpty) {
+  return import_zod2.z.string().refine((value) => {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return allowEmpty;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      return false;
+    }
+    return Boolean(parsed) && typeof parsed === "object" && !Array.isArray(parsed);
+  }, {
+    message: `${key} must be an empty string or a JSON object string.`
+  });
 }
-function runSystemctlIgnoreFailure(args) {
-  try {
-    runCommand("systemctl", args);
-  } catch {
+
+// src/preflight.ts
+var import_node_child_process5 = require("child_process");
+var import_node_fs10 = __toESM(require("fs"));
+var import_node_path11 = __toESM(require("path"));
+var import_node_util3 = require("util");
+var execFileAsync3 = (0, import_node_util3.promisify)(import_node_child_process5.execFile);
+var REQUIRED_ENV_KEYS = ["MATRIX_HOMESERVER", "MATRIX_USER_ID", "MATRIX_ACCESS_TOKEN"];
+async function runStartupPreflight(options = {}) {
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const checkCodexBinary = options.checkCodexBinary ?? defaultCheckCodexBinary;
+  const fileExists = options.fileExists ?? import_node_fs10.default.existsSync;
+  const isDirectory = options.isDirectory ?? defaultIsDirectory;
+  const issues = [];
+  const envPath = import_node_path11.default.resolve(cwd, ".env");
+  if (!fileExists(envPath)) {
+    issues.push({
+      level: "warn",
+      code: "missing_dotenv",
+      check: ".env",
+      message: `No .env file found at ${envPath}.`,
+      fix: 'Run "codeharbor init" to create baseline config.'
+    });
   }
-}
-function runCommand(file, args) {
-  try {
-    return (0, import_node_child_process5.execFileSync)(file, args, {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"]
+  for (const key of REQUIRED_ENV_KEYS) {
+    if (!readEnv(env, key)) {
+      issues.push({
+        level: "error",
+        code: "missing_env",
+        check: key,
+        message: `${key} is required.`,
+        fix: `Run "codeharbor init" or set ${key} in .env.`
+      });
+    }
+  }
+  const matrixHomeserver = readEnv(env, "MATRIX_HOMESERVER");
+  if (matrixHomeserver) {
+    try {
+      new URL(matrixHomeserver);
+    } catch {
+      issues.push({
+        level: "error",
+        code: "invalid_matrix_homeserver",
+        check: "MATRIX_HOMESERVER",
+        message: `Invalid URL: "${matrixHomeserver}".`,
+        fix: "Set MATRIX_HOMESERVER to a full URL, for example https://matrix.example.com."
+      });
+    }
+  }
+  const matrixUserId = readEnv(env, "MATRIX_USER_ID");
+  if (matrixUserId && !/^@[^:\s]+:.+/.test(matrixUserId)) {
+    issues.push({
+      level: "error",
+      code: "invalid_matrix_user_id",
+      check: "MATRIX_USER_ID",
+      message: `Unexpected Matrix user id format: "${matrixUserId}".`,
+      fix: "Set MATRIX_USER_ID like @bot:example.com."
     });
+  }
+  const codexBin = readEnv(env, "CODEX_BIN") || "codex";
+  try {
+    await checkCodexBinary(codexBin);
   } catch (error) {
-    throw new Error(formatCommandError(file, args, error), { cause: error });
+    const reason = error instanceof Error && error.message ? ` (${error.message})` : "";
+    issues.push({
+      level: "error",
+      code: "missing_codex_bin",
+      check: "CODEX_BIN",
+      message: `Unable to execute "${codexBin}"${reason}.`,
+      fix: `Install Codex CLI and ensure "${codexBin}" is in PATH, or set CODEX_BIN=/absolute/path/to/codex.`
+    });
+  }
+  const configuredWorkdir = readEnv(env, "CODEX_WORKDIR");
+  const workdir = import_node_path11.default.resolve(cwd, configuredWorkdir || cwd);
+  if (!fileExists(workdir) || !isDirectory(workdir)) {
+    issues.push({
+      level: "error",
+      code: "invalid_codex_workdir",
+      check: "CODEX_WORKDIR",
+      message: `Working directory does not exist or is not a directory: ${workdir}.`,
+      fix: `Set CODEX_WORKDIR to an existing directory, for example CODEX_WORKDIR=${cwd}.`
+    });
   }
+  return {
+    ok: issues.every((issue) => issue.level !== "error"),
+    issues
+  };
 }
-function formatCommandError(file, args, error) {
-  const command = `${file} ${args.join(" ")}`.trim();
-  if (error && typeof error === "object") {
-    const maybeError = error;
-    const stderr = bufferToTrimmedString(maybeError.stderr);
-    const stdout = bufferToTrimmedString(maybeError.stdout);
-    const details = stderr || stdout || maybeError.message || "command failed";
-    return `Command failed: ${command}. ${details}`;
+function formatPreflightReport(result, commandName) {
+  const lines = [];
+  const errors = result.issues.filter((issue) => issue.level === "error").length;
+  const warnings = result.issues.filter((issue) => issue.level === "warn").length;
+  if (result.ok) {
+    lines.push(`Preflight check passed for "codeharbor ${commandName}" with ${warnings} warning(s).`);
+  } else {
+    lines.push(
+      `Preflight check failed for "codeharbor ${commandName}" with ${errors} error(s) and ${warnings} warning(s).`
+    );
   }
-  return `Command failed: ${command}. ${String(error)}`;
+  for (const issue of result.issues) {
+    const level = issue.level.toUpperCase();
+    lines.push(`- [${level}] ${issue.check}: ${issue.message}`);
+    lines.push(`  fix: ${issue.fix}`);
+  }
+  return `${lines.join("\n")}
+`;
 }
-function bufferToTrimmedString(value) {
-  if (!value) {
-    return "";
+async function defaultCheckCodexBinary(bin) {
+  await execFileAsync3(bin, ["--version"]);
+}
+function defaultIsDirectory(targetPath) {
+  try {
+    return import_node_fs10.default.statSync(targetPath).isDirectory();
+  } catch {
+    return false;
   }
-  const text = typeof value === "string" ? value : value.toString("utf8");
-  return text.trim();
+}
+function readEnv(env, key) {
+  return env[key]?.trim() ?? "";
 }
 
 // src/cli.ts
@@ -5302,6 +5876,7 @@ configCommand.command("import").description("Import config snapshot from JSON").
 });
 serviceCommand.command("install").description("Install and enable codeharbor systemd service (requires root)").option("--run-user <user>", "service user (default: sudo user or current user)").option("--runtime-home <path>", "runtime home used as CODEHARBOR_HOME").option("--with-admin", "also install codeharbor-admin.service").option("--no-start", "enable service without starting immediately").action((options) => {
   try {
+    maybeReexecServiceCommandWithSudo();
     const runUser = options.runUser?.trim() || resolveDefaultRunUser();
     const runtimeHomePath = resolveRuntimeHomeForUser(runUser, process.env, options.runtimeHome);
     installSystemdServices({
@@ -5317,9 +5892,10 @@ serviceCommand.command("install").description("Install and enable codeharbor sys
 `);
     process.stderr.write(
       [
-        "Hint: run with sudo and absolute CLI path, for example:",
-        '  sudo "$(command -v codeharbor)" service install --with-admin',
-        "  (remove --with-admin if you only want the main service)",
+        "Hint:",
+        "  - Run directly: codeharbor service install --with-admin",
+        "  - The command auto-elevates with sudo when needed.",
+        `  - Fallback explicit form: ${buildExplicitSudoCommand("service install --with-admin")}`,
         ""
       ].join("\n")
     );
@@ -5328,6 +5904,7 @@ serviceCommand.command("install").description("Install and enable codeharbor sys
 });
 serviceCommand.command("uninstall").description("Remove codeharbor systemd service (requires root)").option("--with-admin", "also remove codeharbor-admin.service").action((options) => {
   try {
+    maybeReexecServiceCommandWithSudo();
     uninstallSystemdServices({
       removeAdmin: options.withAdmin ?? false
     });
@@ -5336,8 +5913,10 @@ serviceCommand.command("uninstall").description("Remove codeharbor systemd servi
 `);
     process.stderr.write(
       [
-        "Hint: run with sudo and absolute CLI path, for example:",
-        '  sudo "$(command -v codeharbor)" service uninstall --with-admin',
+        "Hint:",
+        "  - Run directly: codeharbor service uninstall --with-admin",
+        "  - The command auto-elevates with sudo when needed.",
+        `  - Fallback explicit form: ${buildExplicitSudoCommand("service uninstall --with-admin")}`,
         ""
       ].join("\n")
     );
@@ -5346,6 +5925,7 @@ serviceCommand.command("uninstall").description("Remove codeharbor systemd servi
 });
 serviceCommand.command("restart").description("Restart installed codeharbor systemd service (requires root)").option("--with-admin", "also restart codeharbor-admin.service").action((options) => {
   try {
+    maybeReexecServiceCommandWithSudo();
     restartSystemdServices({
       restartAdmin: options.withAdmin ?? false
     });
@@ -5354,9 +5934,10 @@ serviceCommand.command("restart").description("Restart installed codeharbor syst
 `);
     process.stderr.write(
       [
-        "Hint: run with sudo and absolute CLI path, for example:",
-        '  sudo "$(command -v codeharbor)" service restart --with-admin',
-        "  (remove --with-admin if you only want the main service)",
+        "Hint:",
+        "  - Run directly: codeharbor service restart --with-admin",
+        "  - The command auto-elevates with sudo when needed.",
+        `  - Fallback explicit form: ${buildExplicitSudoCommand("service restart --with-admin")}`,
         ""
       ].join("\n")
     );
@@ -5439,6 +6020,32 @@ function resolveCliScriptPath() {
   }
   return import_node_path12.default.resolve(__dirname, "cli.js");
 }
+function maybeReexecServiceCommandWithSudo() {
+  if (typeof process.getuid !== "function" || process.getuid() === 0) {
+    return;
+  }
+  const serviceArgs = process.argv.slice(2);
+  if (serviceArgs.length === 0 || serviceArgs[0] !== "service") {
+    return;
+  }
+  const cliScriptPath = resolveCliScriptPath();
+  const child = (0, import_node_child_process6.spawnSync)("sudo", [process.execPath, cliScriptPath, ...serviceArgs], {
+    stdio: "inherit"
+  });
+  if (child.error) {
+    throw new Error(`failed to auto-elevate with sudo: ${child.error.message}`);
+  }
+  process.exit(child.status ?? 1);
+}
+function shellQuote(value) {
+  if (!value) {
+    return "''";
+  }
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function buildExplicitSudoCommand(subcommand) {
+  return `sudo ${shellQuote(process.execPath)} ${shellQuote(resolveCliScriptPath())} ${subcommand}`;
+}
 function formatError3(error) {
   if (error instanceof Error) {
     return error.message;