@inceptionstack/roundhouse 0.3.12 → 0.3.14

package/README.md

@@ -95,7 +95,10 @@ roundhouse install    # installs as systemd service, starts automatically
 roundhouse <command>
 
 Commands:
-  start               Start the gateway (foreground)
+  setup               One-command install & configure (also works via npx)
+  pair                Pair Telegram account for notifications
+  start               Start the gateway daemon
+  run                 Run the gateway in foreground
   tui [thread]        Open agent TUI on a gateway session
   install             Install as a systemd daemon (requires sudo)
   uninstall           Remove the systemd daemon
@@ -105,6 +108,9 @@ Commands:
   stop                Stop the daemon
   restart             Restart the daemon
   config              Show config path and contents
+  agent <message>     Send a message to the agent and print response
+  doctor [--fix]      Check system health and configuration
+  cron <command>      Manage scheduled jobs (add, list, trigger, etc.)
 ```
 
 ### `roundhouse status`
@@ -441,7 +447,9 @@ No other changes needed — the gateway's unified handler covers all platforms.
 | `src/router.ts` | `AgentRouter` interface + `SingleAgentRouter` |
 | `src/types.ts` | Core interfaces: `AgentAdapter`, `AgentStreamEvent`, `AgentRouter`, `GatewayConfig` |
 | `src/util.ts` | Pure utilities: `splitMessage`, `isAllowed`, `threadIdToDir`, `startTypingLoop` |
-| `src/cli/cli.ts` | CLI: start, install, tui, update, logs, etc. |
+| `src/cli/cli.ts` | CLI: start, run, install, tui, update, logs, etc. |
+| `src/cli/env-file.ts` | Shared env file parsing, serialization, and quoting |
+| `src/cli/systemd.ts` | Shared systemd service management (unit generation, install, status) |
 | `src/cli/doctor.ts` | CLI doctor command |
 | `src/cli/doctor/runner.ts` | Shared doctor runner (CLI + gateway) |
 | `src/cli/doctor/checks/` | Individual health check modules |

package/architecture.md

@@ -268,9 +268,11 @@ index.ts
 cli/cli.ts
   ├── config.ts (DEFAULT_CONFIG, CONFIG_PATH, loadConfig, etc.)
   ├── agents/registry.ts (getAgentSdkPackage)
+  ├── cli/env-file.ts (parseEnvFile, serializeEnvFile, envQuote)
+  ├── cli/systemd.ts (resolveExecStart, generateUnit, writeServiceUnit, systemctl, etc.)
   ├── cli/doctor.ts → cli/doctor/runner.ts → cli/doctor/checks/*
   ├── cli/cron.ts → cron/store.ts, cron/runner.ts, cron/helpers.ts
-  └── (node:fs, node:child_process for daemon management)
+  └── cli/setup.ts → cli/env-file.ts, cli/systemd.ts, cli/setup-telegram.ts
 
 gateway.ts also imports:
   → cli/doctor/runner.ts for /doctor command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",

package/src/cli/cli.ts

@@ -6,10 +6,9 @@
 
 import { resolve, dirname } from "node:path";
 import { homedir } from "node:os";
-import { readFile, writeFile, mkdir, mkdtemp } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { readdirSync, statSync } from "node:fs";
-import { execSync, execFileSync, spawnSync, spawn } from "node:child_process";
+import { execSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -23,12 +22,22 @@ import {
   resolveEnvFilePath,
 } from "../config";
 import { getAgentSdkPackage } from "../agents/registry";
+import { parseEnvFile, serializeEnvFile, envQuote } from "./env-file";
+import {
+  SERVICE_PATH,
+  systemctl,
+  runSudo,
+  isServiceInstalled,
+  isServiceActive,
+  systemctlShow,
+  resolveExecStart,
+  generateUnit,
+  writeServiceUnit,
+} from "./systemd";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const SERVICE_PATH = `/etc/systemd/system/${SERVICE_NAME}.service`;
-
 // ── Shell helpers ───────────────────────────────────
 
 function run(cmd: string, opts?: { silent?: boolean }): string {
@@ -40,22 +49,28 @@ function run(cmd: string, opts?: { silent?: boolean }): string {
   }
 }
 
-function runSudo(...args: string[]): void {
-  // Try non-interactive first, fall back to interactive for password prompts
-  const result = spawnSync("sudo", ["-n", ...args], { stdio: "inherit" });
-  if (result.status !== 0) {
-    execFileSync("sudo", args, { stdio: "inherit" });
+// ── Commands ────────────────────────────────────────
+
+async function cmdStart() {
+  if (isServiceInstalled()) {
+    if (isServiceActive()) {
+      console.log("Roundhouse is already running.");
+      console.log("  Use: roundhouse restart   to restart");
+      console.log("       roundhouse status    to check status");
+      console.log("       roundhouse logs      to tail logs");
+      return;
+    }
+    systemctl("start", "Daemon started.");
+    return;
   }
-}
 
-function systemctl(verb: string, message?: string): void {
-  runSudo("systemctl", verb, SERVICE_NAME);
-  if (message) console.log(`  ✅ ${message}`);
+  // No systemd service — fall back to foreground
+  console.log("No systemd service found. Running in foreground (use Ctrl+C to stop)...");
+  console.log("  Tip: run 'roundhouse install' to set up the systemd daemon.\n");
+  await cmdRun();
 }
 
-// ── Commands ────────────────────────────────────────
-
-async function cmdStart() {
+async function cmdRun() {
   process.env.ROUNDHOUSE_CONFIG = CONFIG_PATH;
   const indexPath = resolve(__dirname, "..", "index.ts");
   const jsPath = resolve(__dirname, "..", "dist", "index.js");
@@ -85,22 +100,16 @@ async function cmdInstall() {
 
   // Write environment file for secrets — merge with existing to preserve manually-added keys
   const ENV_KEYS = ["TELEGRAM_BOT_TOKEN", "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "BOT_USERNAME", "ALLOWED_USERS", "NOTIFY_CHAT_IDS", "AWS_PROFILE", "AWS_DEFAULT_REGION", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"];
-  const existing = new Map<string, string>();
   const resolvedEnvPath = await resolveEnvFilePath();
-  if (await fileExists(resolvedEnvPath)) {
-    const raw = await readFile(resolvedEnvPath, "utf8");
-    for (const line of raw.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#")) continue;
-      const eq = trimmed.indexOf("=");
-      if (eq > 0) existing.set(trimmed.slice(0, eq), trimmed.slice(eq + 1));
-    }
-  }
+  const existing = await fileExists(resolvedEnvPath)
+    ? parseEnvFile(await readFile(resolvedEnvPath, "utf8"))
+    : new Map<string, string>();
+
   // Override with current env vars for known keys
   let envChanged = false;
   for (const key of ENV_KEYS) {
     if (process.env[key]) {
-      existing.set(key, `"${process.env[key].replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$$").replace(/`/g, "\\`").replace(/\n/g, "\\n")}"`);
+      existing.set(key, envQuote(process.env[key]));
       envChanged = true;
     }
   }
@@ -108,56 +117,14 @@ async function cmdInstall() {
     if (resolvedEnvPath !== ENV_FILE_PATH && await fileExists(resolvedEnvPath)) {
       console.log(`  Copying env file from ${resolvedEnvPath} to ${ENV_FILE_PATH}`);
     }
-    const envFileContent = [...existing.entries()].map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
-    await writeFile(ENV_FILE_PATH, envFileContent, { mode: 0o600 });
+    await writeFile(ENV_FILE_PATH, serializeEnvFile(existing), { mode: 0o600 });
     console.log(`  Environment file: ${ENV_FILE_PATH}`);
   }
 
-  // Resolve paths — prefer the installed bin, fall back to tsx + source
-  const binPath = run("which roundhouse", { silent: true });
-  const nodePath = run("which node", { silent: true }) || process.execPath;
-  const tsxPath = resolve(__dirname, "..", "..", "node_modules", ".bin", "tsx");
-  const srcIndex = resolve(__dirname, "..", "index.ts");
-
-  let execStart: string;
-  if (binPath) {
-    execStart = `${nodePath} ${binPath} start`;
-  } else {
-    // No global install — use tsx directly
-    const tsxBin = run("which tsx", { silent: true }) || tsxPath;
-    execStart = `${tsxBin} ${srcIndex}`;
-  }
-
-  // Compute PATH that includes node's bin dir (for mise/nvm setups)
-  const nodeBinDir = dirname(nodePath);
-  const pathValue = `${nodeBinDir}:/usr/local/bin:/usr/bin:/bin`;
-
-  const unit = `[Unit]
-Description=Roundhouse Chat Gateway
-After=network.target
-
-[Service]
-Type=simple
-User=${process.env.USER || "root"}
-WorkingDirectory=${homedir()}
-ExecStart=${execStart}
-Restart=on-failure
-RestartSec=5
-EnvironmentFile=-${ENV_FILE_PATH}
-Environment=ROUNDHOUSE_CONFIG=${CONFIG_PATH}
-Environment=NODE_ENV=production
-Environment=PATH=${pathValue}
-
-[Install]
-WantedBy=multi-user.target
-`;
-
-  const tmpDir = await mkdtemp(resolve(tmpdir(), "roundhouse-"));
-  const tmpUnit = resolve(tmpDir, `${SERVICE_NAME}.service`);
-  await writeFile(tmpUnit, unit, { mode: 0o600 });
-  runSudo("cp", tmpUnit, SERVICE_PATH);
-  runSudo("rm", "-rf", "--", tmpDir);
-  runSudo("systemctl", "daemon-reload");
+  // Generate and install systemd unit
+  const { execStart, nodeBinDir } = resolveExecStart();
+  const unit = generateUnit({ execStart, nodeBinDir });
+  await writeServiceUnit(unit);
   systemctl("enable");
   systemctl("start", "Daemon installed and started.");
 
@@ -195,10 +162,7 @@ async function cmdUpdate() {
 }
 
 async function cmdStatus() {
-  // Show systemd status
-  const isActive = run(`systemctl is-active ${SERVICE_NAME}`, { silent: true }) === "active";
-
-  if (!isActive) {
+  if (!isServiceActive()) {
     console.log("\n  ❌ Roundhouse is not running.\n");
     console.log("  Install with: roundhouse install");
     console.log("  Or start foreground: roundhouse start\n");
@@ -212,9 +176,9 @@ async function cmdStatus() {
   } catch {}
 
   // Gather systemd info
-  const pid = run(`systemctl show -p MainPID --value ${SERVICE_NAME}`, { silent: true });
-  const activeState = run(`systemctl show -p ActiveState --value ${SERVICE_NAME}`, { silent: true });
-  const startedAt = run(`systemctl show -p ActiveEnterTimestamp --value ${SERVICE_NAME}`, { silent: true });
+  const pid = systemctlShow("MainPID");
+  const activeState = systemctlShow("ActiveState");
+  const startedAt = systemctlShow("ActiveEnterTimestamp");
 
   // Compute uptime
   let uptimeStr = "unknown";
@@ -417,7 +381,8 @@ Usage:
 Commands:
   setup               One-command install & configure (also works via npx)
   pair                Pair Telegram account for notifications
-  start               Start the gateway (foreground)
+  start               Start the gateway daemon
+  run                 Run the gateway in foreground
   tui [thread]        Open agent TUI on a gateway session
   install             Install as a systemd daemon (requires sudo)
   uninstall           Remove the systemd daemon
@@ -600,6 +565,7 @@ const commands: Record<string, () => void | Promise<void>> = {
   setup: () => cmdSetup(process.argv.slice(3)),
   pair: () => cmdPair(process.argv.slice(3)),
   start: cmdStart,
+  run: cmdRun,
   install: cmdInstall,
   uninstall: cmdUninstall,
   update: cmdUpdate,

package/src/cli/env-file.ts

@@ -0,0 +1,40 @@
+/**
+ * cli/env-file.ts — Shared env file parsing and quoting
+ *
+ * Used by install, setup, status, doctor, and pair commands.
+ */
+
+/**
+ * Parse a systemd-compatible env file into a key→value map.
+ * Skips blank lines and comments (#).
+ */
+export function parseEnvFile(content: string): Map<string, string> {
+  const entries = new Map<string, string>();
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq > 0) entries.set(trimmed.slice(0, eq), trimmed.slice(eq + 1));
+  }
+  return entries;
+}
+
+/**
+ * Serialize a key→value map to env file content.
+ */
+export function serializeEnvFile(entries: Map<string, string>): string {
+  return [...entries.entries()].map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
+}
+
+/**
+ * Shell-escape a value for env files (double-quoted).
+ */
+export function envQuote(value: string): string {
+  const escaped = value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, "\\$")
+    .replace(/`/g, "\\`")
+    .replace(/\n/g, "\\n");
+  return `"${escaped}"`;
+}

package/src/cli/setup.ts

@@ -12,7 +12,7 @@
 import { homedir, platform } from "node:os";
 import { resolve, dirname } from "node:path";
 import { readFile, writeFile, mkdir, rename, unlink, realpath, stat } from "node:fs/promises";
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { BOT_COMMANDS } from "../commands";
 import {
@@ -21,6 +21,17 @@ import {
   ENV_FILE_PATH as ENV_PATH,
   fileExists,
 } from "../config";
+import { envQuote, parseEnvFile } from "./env-file";
+import {
+  whichSync,
+  systemctl,
+  isServiceActive,
+  systemctlShow,
+  resolveExecStart,
+  generateUnit,
+  writeServiceUnit,
+  hasSudoAccess,
+} from "./systemd";
 import {
   validateBotToken,
   checkWebhook,
@@ -90,18 +101,6 @@ async function atomicWriteText(path: string, content: string, mode = 0o600): Pro
   }
 }
 
-/** Shell-escape a value for env files */
-function envQuote(value: string): string {
-  // Escape backslash, double-quote, dollar, backtick, newline
-  const escaped = value
-    .replace(/\\/g, "\\\\")
-    .replace(/"/g, '\\"')
-    .replace(/\$/g, "\\$")
-    .replace(/`/g, "\\`")
-    .replace(/\n/g, "\\n");
-  return `"${escaped}"`;
-}
-
 function execSafe(cmd: string, args: string[], opts: { silent?: boolean; input?: string } = {}): string {
   try {
     const result = execFileSync(cmd, args, {
@@ -124,11 +123,6 @@ function execOrFail(cmd: string, args: string[], label: string): string {
   }
 }
 
-function whichSync(cmd: string): string | null {
-  const result = execSafe("which", [cmd], { silent: true });
-  return result || null;
-}
-
 // ── Arg parser ───────────────────────────────────────
 
 export function parseSetupArgs(argv: string[]): SetupOptions {
@@ -316,11 +310,10 @@ async function stepStopGateway(): Promise<void> {
     return;
   }
 
-  const isActive = execSafe("systemctl", ["is-active", "roundhouse"], { silent: true });
-  if (isActive === "active") {
+  if (isServiceActive()) {
     log("   Stopping existing gateway...");
     try {
-      execFileSync("sudo", ["-n", "systemctl", "stop", "roundhouse"], { stdio: "pipe", timeout: 30_000 });
+      systemctl("stop");
       ok("Service stopped");
     } catch {
       warn("Could not stop service (may need sudo). Continuing anyway.");
@@ -606,26 +599,21 @@ async function stepConfigure(
 
   if (opts.provider === "amazon-bedrock") {
     // Preserve existing AWS config
-    let existingEnv: Record<string, string> = {};
+    let existingEnv = new Map<string, string>();
     try {
-      const raw = await readFile(ENV_PATH, "utf8");
-      for (const line of raw.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith("#")) continue;
-        const eq = trimmed.indexOf("=");
-        if (eq > 0) existingEnv[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
-      }
+      existingEnv = parseEnvFile(await readFile(ENV_PATH, "utf8"));
     } catch {}
+    const getExisting = (key: string) => existingEnv.get(key);
 
     if (!envLines.some((l) => l.startsWith("AWS_PROFILE="))) {
-      envLines.push(`AWS_PROFILE=${existingEnv.AWS_PROFILE ?? '"default"'}`);
+      envLines.push(`AWS_PROFILE=${getExisting("AWS_PROFILE") ?? '"default"'}`);
     }
     if (!envLines.some((l) => l.startsWith("AWS_DEFAULT_REGION="))) {
-      envLines.push(`AWS_DEFAULT_REGION=${existingEnv.AWS_DEFAULT_REGION ?? '"us-east-1"'}`);
+      envLines.push(`AWS_DEFAULT_REGION=${getExisting("AWS_DEFAULT_REGION") ?? '"us-east-1"'}`);
     }
     // Pi agent requires AWS_REGION (not just AWS_DEFAULT_REGION) to discover Bedrock models
     if (!envLines.some((l) => l.startsWith("AWS_REGION="))) {
-      envLines.push(`AWS_REGION=${existingEnv.AWS_REGION ?? existingEnv.AWS_DEFAULT_REGION ?? '"us-east-1"'}`);
+      envLines.push(`AWS_REGION=${getExisting("AWS_REGION") ?? getExisting("AWS_DEFAULT_REGION") ?? '"us-east-1"'}`);
     }
   }
 
@@ -711,19 +699,13 @@ async function stepInstallSystemd(opts: SetupOptions): Promise<void> {
   }
 
   // Check sudo
-  const hasSudo = spawnSync("sudo", ["-n", "true"], { stdio: "pipe" }).status === 0;
-  if (!hasSudo) {
+  if (!hasSudoAccess()) {
     warn("No passwordless sudo — cannot install systemd service");
     log("   Run manually: roundhouse start");
     log("   Or install with: sudo roundhouse install");
     return;
   }
 
-  // Resolve paths
-  const roundhouseBin = whichSync("roundhouse") ?? resolve(dirname(process.execPath), "roundhouse");
-  const psstBin = opts.psst ? whichSync("psst") : null;
-  const nodeBin = process.execPath;
-  const nodeBinDir = dirname(nodeBin);
   const user = process.env.USER || process.env.LOGNAME;
   if (!user) {
     warn("Cannot determine current user ($USER not set). Skipping systemd.");
@@ -731,60 +713,16 @@ async function stepInstallSystemd(opts: SetupOptions): Promise<void> {
     return;
   }
 
-  // Guard against newline injection in interpolated values
-  const unitPaths = { user, roundhouseBin, nodeBin, nodeBinDir, psstBin, home: homedir(), cwd: opts.cwd };
-  for (const [key, val] of Object.entries(unitPaths)) {
-    if (val && /[\n\r]/.test(val)) {
-      warn(`Unsafe value for ${key} (contains newline). Skipping systemd.`);
-      return;
-    }
-  }
-
-  // Build ExecStart
-  let execStart: string;
-  if (psstBin) {
-    execStart = `${psstBin} run ${nodeBin} ${roundhouseBin} start`;
-  } else {
-    execStart = `${nodeBin} ${roundhouseBin} start`;
-  }
-
-  // Always include env file for non-secret config (AWS_PROFILE, etc)
-  // When using psst, ExecStart wraps with `psst run` to inject secrets
-  const unit = `[Unit]
-Description=Roundhouse Chat Gateway
-After=network.target
-
-[Service]
-Type=simple
-User=${user}
-WorkingDirectory=${homedir()}
-ExecStart=${execStart}
-Restart=on-failure
-RestartSec=5
-EnvironmentFile=-${ENV_PATH}
-Environment=ROUNDHOUSE_CONFIG=${CONFIG_PATH}
-Environment=NODE_ENV=production
-Environment=PATH=${nodeBinDir}:/usr/local/bin:/usr/bin:/bin
-Environment=HOME=${homedir()}
-
-[Install]
-WantedBy=multi-user.target
-`;
-
-  // Write to tmp, then sudo cp
-  const tmpPath = resolve(ROUNDHOUSE_DIR, `roundhouse.service.tmp.${randomBytes(4).toString("hex")}`);
-  const servicePath = `/etc/systemd/system/roundhouse.service`;
+  const psstBin = opts.psst ? whichSync("psst") : null;
+  const { execStart, nodeBinDir } = resolveExecStart({ psstBin });
+  const unit = generateUnit({ execStart, nodeBinDir, user });
 
   try {
-    await writeFile(tmpPath, unit, { mode: 0o600 });
-    execFileSync("sudo", ["-n", "cp", tmpPath, servicePath], { stdio: "pipe" });
-    await unlink(tmpPath);
-    execFileSync("sudo", ["-n", "systemctl", "daemon-reload"], { stdio: "pipe" });
-    execFileSync("sudo", ["-n", "systemctl", "enable", "roundhouse"], { stdio: "pipe" });
-    execFileSync("sudo", ["-n", "systemctl", "start", "roundhouse"], { stdio: "pipe" });
+    await writeServiceUnit(unit);
+    systemctl("enable");
+    systemctl("start");
     ok("roundhouse.service enabled and started");
   } catch (err: any) {
-    try { await unlink(tmpPath); } catch {}
     warn(`Systemd install failed: ${err.message}`);
     log("   Run manually: roundhouse start");
   }
@@ -794,9 +732,8 @@ async function stepPostflight(): Promise<void> {
   step("⑩", "Postflight checks...");
 
   if (platform() === "linux") {
-    const isActive = execSafe("systemctl", ["is-active", "roundhouse"], { silent: true });
-    if (isActive === "active") {
-      const pid = execSafe("systemctl", ["show", "-p", "MainPID", "--value", "roundhouse"], { silent: true });
+    if (isServiceActive()) {
+      const pid = systemctlShow("MainPID");
       ok(`Service active (PID ${pid})`);
     } else {
       warn("Service not active — check: roundhouse logs");
@@ -907,9 +844,9 @@ export async function cmdPair(argv: string[]): Promise<void> {
   // Try existing env file
   if (!token) {
     try {
-      const envContent = await readFile(ENV_PATH, "utf8");
-      const match = envContent.match(/TELEGRAM_BOT_TOKEN=["']?([^"'\n]+)["']?/);
-      if (match) token = match[1];
+      const entries = parseEnvFile(await readFile(ENV_PATH, "utf8"));
+      const raw = entries.get("TELEGRAM_BOT_TOKEN");
+      if (raw) token = raw.replace(/^["']|["']$/g, "");
     } catch {}
   }
 

package/src/cli/systemd.ts

@@ -0,0 +1,182 @@
+/**
+ * cli/systemd.ts — Shared systemd service management
+ *
+ * Generates unit files, resolves ExecStart, and installs/writes services.
+ * Used by both `roundhouse install` (cli.ts) and `roundhouse setup` (setup.ts).
+ */
+
+import { homedir } from "node:os";
+import { resolve, dirname } from "node:path";
+import { writeFile, unlink } from "node:fs/promises";
+import { execFileSync, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+import {
+  ROUNDHOUSE_DIR,
+  CONFIG_PATH,
+  ENV_FILE_PATH,
+  SERVICE_NAME,
+} from "../config";
+
+const __systemdDir = dirname(fileURLToPath(import.meta.url));
+
+export const SERVICE_PATH = `/etc/systemd/system/${SERVICE_NAME}.service`;
+
+// ── Shell helpers ───────────────────────────────────
+
+export function whichSync(cmd: string): string | null {
+  try {
+    return execFileSync("which", [cmd], { encoding: "utf8", stdio: "pipe" }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function execSilent(cmd: string, args: string[]): string {
+  try {
+    return execFileSync(cmd, args, { encoding: "utf8", stdio: "pipe" }).trim();
+  } catch {
+    return "";
+  }
+}
+
+export function runSudo(...args: string[]): void {
+  const result = spawnSync("sudo", ["-n", ...args], { stdio: "inherit" });
+  if (result.status !== 0) {
+    execFileSync("sudo", args, { stdio: "inherit" });
+  }
+}
+
+export function systemctl(verb: string, message?: string): void {
+  runSudo("systemctl", verb, SERVICE_NAME);
+  if (message) console.log(`  ✅ ${message}`);
+}
+
+export function hasSudoAccess(): boolean {
+  return spawnSync("sudo", ["-n", "true"], { stdio: "pipe" }).status === 0;
+}
+
+export function isServiceInstalled(): boolean {
+  return execSilent("systemctl", ["list-unit-files", `${SERVICE_NAME}.service`]).includes(SERVICE_NAME);
+}
+
+export function isServiceActive(): boolean {
+  return execSilent("systemctl", ["is-active", SERVICE_NAME]) === "active";
+}
+
+/**
+ * Query a systemd service property via `systemctl show`.
+ */
+export function systemctlShow(property: string): string {
+  return execSilent("systemctl", ["show", "-p", property, "--value", SERVICE_NAME]);
+}
+
+// ── ExecStart resolution ────────────────────────────
+
+export interface ExecStartOptions {
+  /** Path to psst binary (if using psst for secrets) */
+  psstBin?: string | null;
+}
+
+/**
+ * Resolve the ExecStart command for the systemd unit.
+ * Prefers the global `roundhouse` binary; falls back to tsx + cli.ts.
+ */
+export function resolveExecStart(opts: ExecStartOptions = {}): { execStart: string; nodeBinDir: string } {
+  const roundhouseBin = whichSync("roundhouse");
+  const nodeBin = whichSync("node") || process.execPath;
+  const nodeBinDir = dirname(nodeBin);
+
+  let execStart: string;
+  if (roundhouseBin) {
+    const base = `${nodeBin} ${roundhouseBin} run`;
+    execStart = opts.psstBin ? `${opts.psstBin} run ${base}` : base;
+  } else {
+    // No global install — run CLI via tsx with 'run' subcommand
+    const tsxBin = whichSync("tsx") || resolve(__systemdDir, "..", "..", "node_modules", ".bin", "tsx");
+    const cliPath = resolve(__systemdDir, "cli.ts");
+    const base = `${tsxBin} ${cliPath} run`;
+    execStart = opts.psstBin ? `${opts.psstBin} run ${base}` : base;
+  }
+
+  return { execStart, nodeBinDir };
+}
+
+// ── Unit file generation ────────────────────────────
+
+export interface UnitOptions {
+  execStart: string;
+  nodeBinDir: string;
+  user?: string;
+  envFilePath?: string;
+}
+
+/**
+ * Guard against newline injection in values interpolated into the unit template.
+ * A crafted $USER or path containing \n/\r could inject arbitrary systemd directives.
+ */
+function assertSafeForUnit(label: string, value: unknown): void {
+  if (typeof value !== "string") {
+    throw new Error(`Missing or non-string value for ${label} — cannot generate systemd unit`);
+  }
+  if (/[\n\r]/.test(value)) {
+    throw new Error(`Unsafe value for ${label} (contains newline) — cannot generate systemd unit`);
+  }
+}
+
+/**
+ * Generate a systemd unit file string.
+ */
+export function generateUnit(opts: UnitOptions): string {
+  const user = opts.user || process.env.USER || "root";
+  const envFilePath = opts.envFilePath || ENV_FILE_PATH;
+  const home = homedir();
+  const pathValue = `${opts.nodeBinDir}:/usr/local/bin:/usr/bin:/bin`;
+
+  // Validate all interpolated values before generating the unit
+  for (const [label, value] of Object.entries({
+    user, execStart: opts.execStart, nodeBinDir: opts.nodeBinDir,
+    envFilePath, home, configPath: CONFIG_PATH, pathValue,
+  })) {
+    assertSafeForUnit(label, value);
+  }
+
+  return `[Unit]
+Description=Roundhouse Chat Gateway
+After=network.target
+
+[Service]
+Type=simple
+User=${user}
+WorkingDirectory=${home}
+ExecStart=${opts.execStart}
+Restart=on-failure
+RestartSec=5
+EnvironmentFile=-${envFilePath}
+Environment=ROUNDHOUSE_CONFIG=${CONFIG_PATH}
+Environment=NODE_ENV=production
+Environment=PATH=${pathValue}
+Environment=HOME=${home}
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+// ── Install service ─────────────────────────────────
+
+/**
+ * Write a systemd unit file via sudo and reload the daemon.
+ * Uses atomic write-to-tmp + sudo cp pattern.
+ */
+export async function writeServiceUnit(unitContent: string): Promise<void> {
+  const tmpPath = resolve(ROUNDHOUSE_DIR, `roundhouse.service.tmp.${randomBytes(4).toString("hex")}`);
+  try {
+    await writeFile(tmpPath, unitContent, { mode: 0o600 });
+    execFileSync("sudo", ["-n", "cp", tmpPath, SERVICE_PATH], { stdio: "pipe" });
+  } finally {
+    try { await unlink(tmpPath); } catch {}
+  }
+  runSudo("systemctl", "daemon-reload");
+}