@kmmao/happy-agent 0.3.11 → 0.4.1

package/dist/index.cjs

@@ -18,7 +18,7 @@ var path = require('path');
 var fs = require('fs');
 var os = require('os');
 
-var version = "0.3.11";
+var version = "0.4.1";
 
 function loadConfig() {
   const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://happyserve.xycloud.info").replace(/\/+$/, "");
@@ -789,6 +789,7 @@ function createRpcHandlerManager(config) {
 }
 
 const execAsync = util.promisify(child_process.exec);
+const execFileAsync$1 = util.promisify(child_process.execFile);
 const UPLOAD_TEMP_DIR = path.join(os.tmpdir(), "happy", "uploads");
 const MAX_WRITE_SIZE = 10 * 1024 * 1024;
 function validatePath(targetPath, workingDirectory, additionalAllowedDirs) {
@@ -1048,6 +1049,367 @@ function registerAgentHandlers(rpcHandlerManager, workingDirectory, sessionId) {
     await promises.mkdir(uploadDir, { recursive: true });
     return { success: true, path: uploadDir };
   });
+  rpcHandlerManager.registerHandler("getDirectoryTree", async (data) => {
+    logger.debug("Get directory tree request:", data.path, "maxDepth:", data.maxDepth);
+    const validation = validatePath(data.path, workingDirectory);
+    if (!validation.valid) {
+      return { success: false, error: validation.error };
+    }
+    async function buildTree(dirPath, name, currentDepth) {
+      try {
+        const stats = await promises.stat(dirPath);
+        const node = {
+          name,
+          path: dirPath,
+          type: stats.isDirectory() ? "directory" : "file",
+          size: stats.size,
+          modified: stats.mtime.getTime()
+        };
+        if (stats.isDirectory() && currentDepth < data.maxDepth) {
+          const entries = await promises.readdir(dirPath, { withFileTypes: true });
+          const children = [];
+          await Promise.all(
+            entries.map(async (entry) => {
+              if (entry.isSymbolicLink()) return;
+              const childPath = path.join(dirPath, entry.name);
+              const childNode = await buildTree(childPath, entry.name, currentDepth + 1);
+              if (childNode) children.push(childNode);
+            })
+          );
+          children.sort((a, b) => {
+            if (a.type === "directory" && b.type !== "directory") return -1;
+            if (a.type !== "directory" && b.type === "directory") return 1;
+            return a.name.localeCompare(b.name);
+          });
+          node.children = children;
+        }
+        return node;
+      } catch (error) {
+        logger.debug(`Failed to process ${dirPath}:`, error instanceof Error ? error.message : String(error));
+        return null;
+      }
+    }
+    try {
+      if (data.maxDepth < 0) {
+        return { success: false, error: "maxDepth must be non-negative" };
+      }
+      const baseName = data.path === "/" ? "/" : data.path.split("/").pop() || data.path;
+      const tree = await buildTree(data.path, baseName, 0);
+      if (!tree) {
+        return { success: false, error: "Failed to access the specified path" };
+      }
+      return { success: true, tree };
+    } catch (error) {
+      logger.debug("Failed to get directory tree:", error);
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Failed to get directory tree"
+      };
+    }
+  });
+  rpcHandlerManager.registerHandler(
+    "ripgrep",
+    async (data) => {
+      const cwd = data.cwd || workingDirectory;
+      if (data.cwd) {
+        const validation = validatePath(data.cwd, workingDirectory);
+        if (!validation.valid) {
+          return { success: false, error: validation.error };
+        }
+      }
+      try {
+        const { stdout, stderr } = await execFileAsync$1("rg", data.args, {
+          cwd,
+          timeout: 3e4,
+          maxBuffer: 10 * 1024 * 1024
+        });
+        return { success: true, stdout: stdout?.toString() ?? "", stderr: stderr?.toString() ?? "", exitCode: 0 };
+      } catch (error) {
+        const e = error;
+        if (e.code === "ENOENT") {
+          return { success: false, error: "ripgrep (rg) is not installed on this machine" };
+        }
+        if (e.code === "1" || e.status === 1) {
+          return { success: true, stdout: e.stdout?.toString() ?? "", stderr: e.stderr?.toString() ?? "", exitCode: 1 };
+        }
+        return {
+          success: false,
+          stdout: e.stdout?.toString() ?? "",
+          stderr: e.stderr?.toString() ?? "",
+          exitCode: typeof e.code === "number" ? e.code : 1,
+          error: e.message ?? "ripgrep failed"
+        };
+      }
+    }
+  );
+  rpcHandlerManager.registerHandler(
+    "difftastic",
+    async (data) => {
+      const cwd = data.cwd || workingDirectory;
+      if (data.cwd) {
+        const validation = validatePath(data.cwd, workingDirectory);
+        if (!validation.valid) {
+          return { success: false, error: validation.error };
+        }
+      }
+      try {
+        const { stdout, stderr } = await execFileAsync$1("difft", data.args, {
+          cwd,
+          timeout: 3e4,
+          maxBuffer: 10 * 1024 * 1024
+        });
+        return { success: true, stdout: stdout?.toString() ?? "", stderr: stderr?.toString() ?? "", exitCode: 0 };
+      } catch (error) {
+        const e = error;
+        if (e.code === "ENOENT") {
+          return { success: false, error: "difftastic (difft) is not installed on this machine" };
+        }
+        return {
+          success: false,
+          stdout: e.stdout?.toString() ?? "",
+          stderr: e.stderr?.toString() ?? "",
+          exitCode: typeof e.code === "number" ? e.code : 1,
+          error: e.message ?? "difftastic failed"
+        };
+      }
+    }
+  );
+  rpcHandlerManager.registerHandler("listRemoteGitRepos", async (data) => {
+    const page = data.page ?? 1;
+    const perPage = data.perPage ?? 30;
+    const query = data.query?.trim() || "";
+    logger.debug("listRemoteGitRepos request:", { provider: data.provider, host: data.host, page, perPage, query });
+    if (!data.apiToken) return { success: false, error: "API token is required" };
+    if (!data.host?.trim()) return { success: false, error: "Host is required" };
+    try {
+      const baseUrl = buildGitApiBase(data.provider, data.host);
+      const headers = buildGitApiHeaders(data.apiToken);
+      let repos;
+      let hasMore;
+      if (data.provider === "github") {
+        const listUrl = `${baseUrl}/user/repos?per_page=${perPage}&page=${page}&sort=updated&affiliation=owner,collaborator,organization_member`;
+        const response = await fetch(listUrl, { headers });
+        if (!response.ok) {
+          const errorText = await response.text().catch(() => "");
+          throw new Error(`HTTP ${response.status}: ${errorText}`);
+        }
+        const items = await response.json();
+        repos = normalizeRemoteRepoEntries(items);
+        hasMore = items.length >= perPage;
+      } else {
+        const searchParams = new URLSearchParams({ sort: "updated", order: "desc", limit: String(perPage), page: String(page) });
+        if (query) searchParams.set("q", query);
+        const searchUrl = `${baseUrl}/repos/search?${searchParams.toString()}`;
+        const response = await fetch(searchUrl, { headers });
+        if (!response.ok) {
+          const errorText = await response.text().catch(() => "");
+          throw new Error(`HTTP ${response.status}: ${errorText}`);
+        }
+        const body = await response.json();
+        const items = Array.isArray(body) ? body : body.data || [];
+        repos = normalizeRemoteRepoEntries(items);
+        hasMore = items.length >= perPage;
+      }
+      return { success: true, repos, hasMore };
+    } catch (error) {
+      logger.debug("listRemoteGitRepos failed:", error);
+      return { success: false, error: error instanceof Error ? error.message : "Failed to load remote repositories" };
+    }
+  });
+  rpcHandlerManager.registerHandler(
+    "cloneGitRepo",
+    async (data) => {
+      logger.debug("cloneGitRepo request:", { repoUrl: data.repoUrl, targetDirectory: data.targetDirectory });
+      if (!data.repoUrl?.trim()) return { success: false, error: "Repository URL is required" };
+      if (!data.targetDirectory?.trim()) return { success: false, error: "Target directory is required" };
+      if (!data.targetDirectory.startsWith("/")) return { success: false, error: "Target directory must be an absolute path" };
+      const coords = parseCloneCoordinates(data.repoUrl);
+      if (!coords) return { success: false, error: "Invalid repository URL" };
+      const repoPath = path.join(path.resolve(data.targetDirectory), coords.repo);
+      try {
+        await promises.mkdir(path.resolve(data.targetDirectory), { recursive: true });
+        try {
+          const existing = await promises.stat(repoPath);
+          if (existing.isDirectory()) {
+            return { success: false, error: `Destination already exists: ${repoPath}` };
+          }
+        } catch {
+        }
+        const cloneUrl = resolveCloneUrl(data.repoUrl, data.host);
+        const options = {
+          cwd: path.resolve(data.targetDirectory),
+          timeout: 3e5,
+          maxBuffer: 4 * 1024 * 1024,
+          env: buildCloneAuthEnv(data.provider, data.apiToken)
+        };
+        const { stdout, stderr } = await execFileAsync$1("git", ["clone", cloneUrl, repoPath], options);
+        return { success: true, repoPath, stdout: stdout?.toString() ?? "", stderr: stderr?.toString() ?? "" };
+      } catch (error) {
+        const e = error;
+        logger.debug("cloneGitRepo failed:", { message: e.message, stderr: e.stderr });
+        return { success: false, repoPath, stdout: e.stdout || "", stderr: e.stderr || "", error: e.message || "Failed to clone repository" };
+      }
+    }
+  );
+  rpcHandlerManager.registerHandler("createRemoteWebhook", async (data) => {
+    logger.debug("createRemoteWebhook request:", { provider: data.provider, repoUrl: data.repoUrl });
+    try {
+      const parsed = parseRepoOwnerFromUrl(data.repoUrl);
+      if (!parsed) return { success: false, error: "Invalid repo URL" };
+      const { origin, owner, repo } = parsed;
+      const isGitHubCom = origin === "https://github.com" || origin === "http://github.com";
+      const baseUrl = data.provider === "github" && isGitHubCom ? "https://api.github.com" : data.provider === "github" ? `${origin}/api/v3` : `${origin}/api/v1`;
+      const headers = {
+        Authorization: `token ${data.apiToken}`,
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      };
+      const hooksEndpoint = `${baseUrl}/repos/${owner}/${repo}/hooks`;
+      const giteaEvents = [
+        "issues",
+        "issue_assign",
+        "issue_label",
+        "issue_milestone",
+        "issue_comment",
+        "pull_request",
+        "pull_request_assign",
+        "pull_request_label",
+        "pull_request_milestone",
+        "pull_request_comment",
+        "pull_request_review",
+        "pull_request_sync"
+      ];
+      const events = data.provider === "gitea" ? giteaEvents : data.events;
+      const listRes = await fetch(hooksEndpoint, { headers });
+      if (listRes.ok) {
+        const hooks = await listRes.json();
+        const existing = hooks.find((h) => h.config.url === data.webhookUrl);
+        if (existing) {
+          const patchRes = await fetch(`${hooksEndpoint}/${existing.id}`, {
+            method: "PATCH",
+            headers,
+            body: JSON.stringify({ config: { url: data.webhookUrl, content_type: "json", secret: data.webhookSecret }, events, active: true })
+          });
+          if (!patchRes.ok) {
+            const errText = await patchRes.text().catch(() => "");
+            return { success: false, error: `PATCH ${patchRes.status}: ${errText}` };
+          }
+          return { success: true, created: false, webhookId: existing.id };
+        }
+      }
+      const createBody = {
+        name: "web",
+        config: { url: data.webhookUrl, content_type: "json", secret: data.webhookSecret },
+        events,
+        active: true
+      };
+      if (data.provider === "gitea") createBody.type = "gitea";
+      const createRes = await fetch(hooksEndpoint, { method: "POST", headers, body: JSON.stringify(createBody) });
+      if (createRes.ok || createRes.status === 201) {
+        const body = await createRes.json().catch(() => ({}));
+        return { success: true, created: true, webhookId: body.id };
+      }
+      const errBody = await createRes.text().catch(() => "");
+      return { success: false, error: `HTTP ${createRes.status}: ${errBody}` };
+    } catch (error) {
+      logger.debug("createRemoteWebhook failed:", error);
+      return { success: false, error: error instanceof Error ? error.message : "Failed to create webhook" };
+    }
+  });
+  rpcHandlerManager.registerHandler("deleteRemoteWebhook", async (data) => {
+    logger.debug("deleteRemoteWebhook request:", { provider: data.provider, repoUrl: data.repoUrl });
+    try {
+      const parsed = parseRepoOwnerFromUrl(data.repoUrl);
+      if (!parsed) return { success: false, error: "Invalid repo URL" };
+      const { origin, owner, repo } = parsed;
+      const isGitHubCom = origin === "https://github.com" || origin === "http://github.com";
+      const baseUrl = data.provider === "github" && isGitHubCom ? "https://api.github.com" : data.provider === "github" ? `${origin}/api/v3` : `${origin}/api/v1`;
+      const headers = { Authorization: `token ${data.apiToken}`, Accept: "application/json" };
+      const hooksEndpoint = `${baseUrl}/repos/${owner}/${repo}/hooks`;
+      const listRes = await fetch(hooksEndpoint, { headers });
+      if (!listRes.ok) return { success: false, error: `List hooks failed: HTTP ${listRes.status}` };
+      const hooks = await listRes.json();
+      const existing = hooks.find((h) => h.config.url === data.webhookUrl);
+      if (!existing) return { success: true, deleted: false };
+      const deleteRes = await fetch(`${hooksEndpoint}/${existing.id}`, { method: "DELETE", headers });
+      if (deleteRes.ok || deleteRes.status === 204) return { success: true, deleted: true };
+      const errBody = await deleteRes.text().catch(() => "");
+      return { success: false, error: `DELETE ${deleteRes.status}: ${errBody}` };
+    } catch (error) {
+      logger.debug("deleteRemoteWebhook failed:", error);
+      return { success: false, error: error instanceof Error ? error.message : "Failed to delete webhook" };
+    }
+  });
+}
+function parseHostEntry(host) {
+  const match = host.match(/^(https?):\/\/(.+)/);
+  if (match) return { bare: match[2].replace(/\/$/, ""), protocol: match[1] };
+  return { bare: host.replace(/\/$/, ""), protocol: null };
+}
+function buildGitApiBase(provider, host) {
+  const { bare, protocol } = parseHostEntry(host);
+  const normalizedProtocol = protocol ?? "https";
+  const origin = `${normalizedProtocol}://${bare}`;
+  const isGitHubCom = bare === "github.com" || bare === "www.github.com";
+  if (provider === "github") {
+    return isGitHubCom ? "https://api.github.com" : `${origin}/api/v3`;
+  }
+  return `${origin}/api/v1`;
+}
+function buildGitApiHeaders(apiToken) {
+  return {
+    Authorization: `token ${apiToken}`,
+    Accept: "application/json",
+    "Content-Type": "application/json"
+  };
+}
+function normalizeRemoteRepoEntries(pageRepos) {
+  return pageRepos.filter((repo) => !!repo.name).map((repo) => {
+    const owner = repo.owner?.login || repo.owner?.username || "";
+    const fullName = repo.full_name || (owner ? `${owner}/${repo.name}` : repo.name || "");
+    const htmlUrl = repo.html_url || "";
+    const cloneUrl = repo.clone_url || (htmlUrl ? `${htmlUrl}.git` : "");
+    return { name: repo.name || fullName, fullName, cloneUrl, htmlUrl, private: !!repo.private, updatedAt: repo.updated_at ? Date.parse(repo.updated_at) : null };
+  }).filter((repo) => !!repo.cloneUrl);
+}
+function parseCloneCoordinates(repoUrl) {
+  const trimmed = repoUrl.trim();
+  const sshMatch = trimmed.match(/^git@([^:]+):([^/]+)\/([^/.]+?)(?:\.git)?$/);
+  if (sshMatch) return { host: sshMatch[1], owner: sshMatch[2], repo: sshMatch[3] };
+  const sshUrlMatch = trimmed.match(/^ssh:\/\/[^@]+@([^/]+)\/([^/]+)\/([^/.]+?)(?:\.git)?$/);
+  if (sshUrlMatch) return { host: sshUrlMatch[1], owner: sshUrlMatch[2], repo: sshUrlMatch[3] };
+  const httpsMatch = trimmed.match(/^https?:\/\/([^/]+)\/([^/]+)\/([^/.]+?)(?:\.git)?$/);
+  if (httpsMatch) return { host: httpsMatch[1], owner: httpsMatch[2], repo: httpsMatch[3] };
+  return null;
+}
+function resolveCloneUrl(repoUrl, configuredHost) {
+  if (/^https?:\/\//.test(repoUrl)) return repoUrl;
+  const coords = parseCloneCoordinates(repoUrl);
+  if (!coords) return repoUrl;
+  const hostEntry = configuredHost ? parseHostEntry(configuredHost) : null;
+  const protocol = hostEntry?.protocol ?? "https";
+  const bareHost = hostEntry?.bare ?? coords.host;
+  return `${protocol}://${bareHost}/${coords.owner}/${coords.repo}.git`;
+}
+function buildCloneAuthEnv(provider, apiToken) {
+  if (!apiToken) return void 0;
+  const username = provider === "github" ? "x-access-token" : "oauth2";
+  const authValue = Buffer.from(`${username}:${apiToken}`).toString("base64");
+  return {
+    ...process.env,
+    GIT_CONFIG_COUNT: "1",
+    GIT_CONFIG_KEY_0: "http.extraHeader",
+    GIT_CONFIG_VALUE_0: `Authorization: Basic ${authValue}`
+  };
+}
+function parseRepoOwnerFromUrl(repoUrl) {
+  try {
+    const url = new URL(repoUrl);
+    const parts = url.pathname.replace(/^\//, "").replace(/\.git$/, "").split("/");
+    if (parts.length >= 2) return { origin: url.origin, owner: parts[0], repo: parts[1] };
+  } catch {
+  }
+  return null;
 }
 
 class SessionClient extends node_events.EventEmitter {
@@ -1475,6 +1837,364 @@ function isNotFound(err) {
   return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
 }
 
+const pidToSession = /* @__PURE__ */ new Map();
+function trackSession(session) {
+  pidToSession.set(session.pid, session);
+}
+function untrackSession(pid) {
+  const session = pidToSession.get(pid);
+  pidToSession.delete(pid);
+  return session;
+}
+function getTrackedSession(pid) {
+  return pidToSession.get(pid);
+}
+function getAllTrackedSessions() {
+  return [...pidToSession.values()];
+}
+function getTrackedSessionCount() {
+  return pidToSession.size;
+}
+
+var trackedSessions = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  getAllTrackedSessions: getAllTrackedSessions,
+  getTrackedSession: getTrackedSession,
+  getTrackedSessionCount: getTrackedSessionCount,
+  trackSession: trackSession,
+  untrackSession: untrackSession
+});
+
+const execFileAsync = util.promisify(child_process.execFile);
+const SERVER_INTERNAL_SECRETS = /* @__PURE__ */ new Set([
+  "DATABASE_URL",
+  "REDIS_URL",
+  "JWT_SECRET",
+  "ENCRYPTION_KEY",
+  "GITHUB_CLIENT_SECRET",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SESSION_TOKEN",
+  "STRIPE_SECRET_KEY",
+  "SENDGRID_API_KEY",
+  "S3_ACCESS_KEY",
+  "S3_SECRET_KEY"
+]);
+function buildSpawnEnv(extra) {
+  const base = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!SERVER_INTERNAL_SECRETS.has(key) && key !== "CLAUDECODE") {
+      base[key] = value;
+    }
+  }
+  if (extra) {
+    for (const [key, value] of Object.entries(extra)) {
+      if (value !== void 0) {
+        base[key] = value;
+      }
+    }
+  }
+  return base;
+}
+let happyBinaryPath;
+async function findHappyBinary() {
+  if (happyBinaryPath !== void 0) return happyBinaryPath;
+  try {
+    const { stdout } = await execFileAsync("which", ["happy"]);
+    happyBinaryPath = stdout.trim() || null;
+  } catch {
+    happyBinaryPath = null;
+  }
+  return happyBinaryPath;
+}
+async function spawnSession(options) {
+  const {
+    directory,
+    agent = "claude",
+    approvedNewDirectoryCreation = false,
+    happySessionId,
+    automationContext,
+    environmentVariables
+  } = options;
+  const happyPath = await findHappyBinary();
+  if (!happyPath) {
+    return {
+      type: "error",
+      errorMessage: "happy CLI not found. Install with: npm install -g @kmmao/happy-coder"
+    };
+  }
+  try {
+    const dirStat = await promises.stat(directory);
+    if (!dirStat.isDirectory()) {
+      return { type: "error", errorMessage: `Path exists but is not a directory: ${directory}` };
+    }
+  } catch {
+    if (!approvedNewDirectoryCreation) {
+      return { type: "requestToApproveDirectoryCreation", directory };
+    }
+    try {
+      await promises.mkdir(directory, { recursive: true });
+      logger.debug(`[SPAWN] Created directory: ${directory}`);
+    } catch (mkdirError) {
+      return {
+        type: "error",
+        errorMessage: `Failed to create directory: ${mkdirError instanceof Error ? mkdirError.message : String(mkdirError)}`
+      };
+    }
+  }
+  const args = [
+    agent,
+    "--happy-starting-mode",
+    "remote",
+    "--started-by",
+    "daemon"
+  ];
+  if (happySessionId) {
+    args.push("--happy-session-id", happySessionId);
+  }
+  const spawnEnv = buildSpawnEnv(environmentVariables);
+  logger.debug(`[SPAWN] ${happyPath} ${args.join(" ")} in ${directory}`);
+  let happyProcess;
+  try {
+    happyProcess = child_process.spawn(happyPath, args, {
+      cwd: directory,
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: spawnEnv
+    });
+  } catch (spawnError) {
+    return {
+      type: "error",
+      errorMessage: `Failed to spawn: ${spawnError instanceof Error ? spawnError.message : String(spawnError)}`
+    };
+  }
+  const pid = happyProcess.pid;
+  if (!pid) {
+    return { type: "error", errorMessage: "Spawned process has no PID" };
+  }
+  const tracked = {
+    pid,
+    directory,
+    startedAt: Date.now(),
+    childProcess: happyProcess,
+    lastActivityAt: Date.now(),
+    automationContext
+  };
+  trackSession(tracked);
+  happyProcess.stdout?.on("data", () => {
+    tracked.lastActivityAt = Date.now();
+  });
+  happyProcess.stderr?.on("data", () => {
+    tracked.lastActivityAt = Date.now();
+  });
+  happyProcess.on("exit", (code, signal) => {
+    logger.debug(`[SPAWN] Process ${pid} exited: code=${code} signal=${signal}`);
+    const session = untrackSession(pid);
+    if (session) {
+      session.terminationReason = signal ? `signal:${signal}` : code !== 0 ? `exit:${code}` : "completed";
+    }
+  });
+  happyProcess.unref();
+  logger.debug(`[SPAWN] Spawned PID ${pid} in ${directory}`);
+  return { type: "success", pid, directory };
+}
+function stopSession(pid) {
+  const tracked = untrackSession(pid);
+  if (!tracked) {
+    try {
+      process.kill(pid, "SIGTERM");
+      return { stopped: true };
+    } catch {
+      return { stopped: false, error: `No tracked session with PID ${pid}` };
+    }
+  }
+  try {
+    if (tracked.childProcess && !tracked.childProcess.killed) {
+      tracked.childProcess.kill("SIGTERM");
+    } else {
+      process.kill(pid, "SIGTERM");
+    }
+    tracked.terminationReason = "user_stop";
+    logger.debug(`[SPAWN] Stopped session PID ${pid}`);
+    return { stopped: true };
+  } catch (error) {
+    return {
+      stopped: false,
+      error: error instanceof Error ? error.message : "Failed to stop session"
+    };
+  }
+}
+
+const PROMPT_DIR = path.join(os.tmpdir(), "happy", "agent-prompts");
+async function writePromptFile(prefix, content) {
+  await promises.mkdir(PROMPT_DIR, { recursive: true });
+  const filename = `${prefix}-${Date.now()}.md`;
+  const filepath = path.join(PROMPT_DIR, filename);
+  await promises.writeFile(filepath, content, "utf-8");
+  return filepath;
+}
+function buildWebhookPrompt(data) {
+  return [
+    `# Issue #${data.issueNumber}: ${data.issueTitle}`,
+    "",
+    `Author: ${data.issueAuthor}`,
+    `Labels: ${data.issueLabels.join(", ") || "none"}`,
+    `URL: ${data.issueUrl}`,
+    "",
+    data.issueBody
+  ].join("\n");
+}
+function buildSupervisorPrompt(data) {
+  const parts = [
+    `# Supervisor Run: ${data.runId}`,
+    "",
+    `Trigger: ${data.trigger}`,
+    `Project: ${data.projectId}`
+  ];
+  if (data.mode) parts.push(`Mode: ${data.mode}`);
+  if (data.dimensions?.length) parts.push(`Dimensions: ${data.dimensions.join(", ")}`);
+  if (data.changedFiles?.length) {
+    parts.push("", "## Changed Files", ...data.changedFiles.map((f) => `- ${f}`));
+  }
+  if (data.customRules) parts.push("", "## Custom Rules", data.customRules);
+  return parts.join("\n");
+}
+function mapTaskPriority(priority) {
+  if (priority === "urgent" || priority === "high") return "urgent";
+  if (priority === "background" || priority === "low") return "background";
+  return "user";
+}
+function handleWebhookTrigger(data, client, serverUrl, authToken, scheduler) {
+  logger.debug(`[TRIGGER] Webhook: issue #${data.issueNumber} in ${data.repoPath}`);
+  const { deduped } = scheduler.enqueue({
+    kind: "webhook",
+    dedupeKey: `webhook:${data.webhookEventId}`,
+    priority: "background",
+    run: async (jobId) => {
+      client.emitWebhookStatus({ webhookEventId: data.webhookEventId, status: "dispatched" });
+      const promptFile = await writePromptFile("webhook", buildWebhookPrompt(data));
+      const result = await spawnSession({
+        directory: data.repoPath,
+        approvedNewDirectoryCreation: false,
+        automationContext: { kind: "webhook", trigger: `issue#${data.issueNumber}` },
+        environmentVariables: {
+          HAPPY_INITIAL_PROMPT_FILE: promptFile,
+          HAPPY_WEBHOOK_EVENT_ID: data.webhookEventId,
+          HAPPY_WEBHOOK_ISSUE_URL: data.issueUrl,
+          HAPPY_SERVER_URL: serverUrl,
+          HAPPY_AUTH_TOKEN: authToken
+        }
+      });
+      if (result.type !== "success") {
+        const msg = result.type === "error" ? result.errorMessage : "Directory creation not approved";
+        client.emitWebhookStatus({ webhookEventId: data.webhookEventId, status: "failed", errorMessage: msg });
+        throw new Error(msg);
+      }
+      const tracked = (await Promise.resolve().then(function () { return trackedSessions; })).getTrackedSession(result.pid);
+      if (tracked?.childProcess) {
+        tracked.childProcess.on("exit", (code) => {
+          if (code === 0) scheduler.markCompleted(jobId);
+          else scheduler.markFailed(jobId, `exit code ${code}`);
+          client.emitWebhookStatus({ webhookEventId: data.webhookEventId, status: code === 0 ? "completed" : "failed" });
+        });
+      }
+      return { pid: result.pid };
+    }
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Webhook deduped: ${data.webhookEventId}`);
+  }
+}
+function handleSupervisorTrigger(data, client, serverUrl, authToken, scheduler) {
+  logger.debug(`[TRIGGER] Supervisor: run ${data.runId} in ${data.repoPath}`);
+  const { deduped } = scheduler.enqueue({
+    kind: "supervisor",
+    dedupeKey: `supervisor:${data.runId}`,
+    priority: "background",
+    run: async (jobId) => {
+      client.emitSupervisorRunStatus({ runId: data.runId, projectId: data.projectId, status: "running" });
+      const promptFile = await writePromptFile("supervisor", buildSupervisorPrompt(data));
+      const result = await spawnSession({
+        directory: data.repoPath,
+        approvedNewDirectoryCreation: false,
+        automationContext: { kind: "supervisor", trigger: data.trigger, projectId: data.projectId, runId: data.runId },
+        environmentVariables: {
+          HAPPY_INITIAL_PROMPT_FILE: promptFile,
+          HAPPY_SUPERVISOR_RUN_ID: data.runId,
+          HAPPY_SUPERVISOR_PROJECT_ID: data.projectId,
+          HAPPY_SUPERVISOR_SERVER_URL: serverUrl,
+          HAPPY_SUPERVISOR_AUTH_TOKEN: authToken
+        }
+      });
+      if (result.type !== "success") {
+        const msg = result.type === "error" ? result.errorMessage : "Directory creation not approved";
+        client.emitSupervisorRunStatus({ runId: data.runId, projectId: data.projectId, status: "failed", errorMessage: msg });
+        throw new Error(msg);
+      }
+      const tracked = (await Promise.resolve().then(function () { return trackedSessions; })).getTrackedSession(result.pid);
+      if (tracked?.childProcess) {
+        tracked.childProcess.on("exit", (code) => {
+          const status = code === 0 ? "completed" : "failed";
+          if (code === 0) scheduler.markCompleted(jobId);
+          else scheduler.markFailed(jobId, `exit code ${code}`);
+          client.emitSupervisorRunStatus({ runId: data.runId, projectId: data.projectId, status });
+        });
+      }
+      return { pid: result.pid };
+    }
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Supervisor deduped: ${data.runId}`);
+  }
+}
+function handleTaskTrigger(data, serverUrl, _authToken, scheduler) {
+  logger.debug(`[TRIGGER] Task: ${data.taskId} in ${data.directory}`);
+  const { deduped } = scheduler.enqueue({
+    kind: "task",
+    dedupeKey: `task:${data.taskId}`,
+    priority: mapTaskPriority(data.priority),
+    run: async (jobId) => {
+      const promptFile = await writePromptFile("task", data.prompt);
+      const skillEnv = {};
+      if (data.skillContents?.length) {
+        skillEnv.HAPPY_TASK_SKILL_COUNT = String(data.skillContents.length);
+        for (let i = 0; i < data.skillContents.length; i++) {
+          skillEnv[`HAPPY_TASK_SKILL_${i}_NAME`] = data.skillContents[i].name;
+          skillEnv[`HAPPY_TASK_SKILL_${i}_CONTENT`] = data.skillContents[i].content;
+        }
+      }
+      const result = await spawnSession({
+        directory: data.directory,
+        approvedNewDirectoryCreation: true,
+        automationContext: { kind: "task", trigger: "task-dispatch", projectId: data.projectId },
+        environmentVariables: {
+          HAPPY_INITIAL_PROMPT_FILE: promptFile,
+          HAPPY_TASK_ID: data.taskId,
+          HAPPY_TASK_PRIORITY: data.priority,
+          HAPPY_TASK_SERVER_URL: serverUrl,
+          HAPPY_TASK_RESULT_TOKEN: data.resultToken ?? "",
+          HAPPY_TASK_REPORT_URL: `${serverUrl}/v1/tasks/${data.taskId}/result`,
+          ...skillEnv
+        }
+      });
+      if (result.type !== "success") {
+        throw new Error(result.type === "error" ? result.errorMessage : "Directory creation not approved");
+      }
+      const tracked = (await Promise.resolve().then(function () { return trackedSessions; })).getTrackedSession(result.pid);
+      if (tracked?.childProcess) {
+        tracked.childProcess.on("exit", (code) => {
+          if (code === 0) scheduler.markCompleted(jobId);
+          else scheduler.markFailed(jobId, `exit code ${code}`);
+        });
+      }
+      return { pid: result.pid };
+    }
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Task deduped: ${data.taskId}`);
+  }
+}
+
 const TAILSCALE_REFRESH_MS = 5 * 60 * 1e3;
 class MachineClient {
   machine;
@@ -1486,11 +2206,18 @@ class MachineClient {
   tunnelManager = null;
   token;
   serverUrl;
+  agentVersion;
+  startTime = Date.now();
   onEphemeral;
+  automationEnabled = false;
+  automationServerUrl = "";
+  automationAuthToken = "";
+  scheduler = null;
   constructor(opts) {
     this.token = opts.token;
     this.machine = opts.machine;
     this.serverUrl = opts.serverUrl;
+    this.agentVersion = opts.agentVersion ?? "unknown";
     this.onEphemeral = opts.onEphemeral;
     this.rpcHandlerManager = new RpcHandlerManager({
       scopePrefix: opts.machine.id,
@@ -1500,6 +2227,32 @@ class MachineClient {
     });
     const workDir = opts.workingDirectory ?? process.cwd();
     registerAgentHandlers(this.rpcHandlerManager, workDir, opts.machine.id);
+    this.registerMachineHandlers();
+  }
+  // -----------------------------------------------------------------------
+  // Machine-scoped RPC handlers
+  // -----------------------------------------------------------------------
+  registerMachineHandlers() {
+    this.rpcHandlerManager.registerHandler(
+      "spawn-happy-session",
+      async (data) => {
+        logger.debug("[MACHINE] spawn-happy-session request:", data.directory);
+        return spawnSession(data);
+      }
+    );
+    this.rpcHandlerManager.registerHandler("stop-session", async (data) => {
+      logger.debug("[MACHINE] stop-session request:", data.pid);
+      return stopSession(data.pid);
+    });
+    this.rpcHandlerManager.registerHandler("list-tracked-sessions", async () => {
+      const sessions = getAllTrackedSessions().map((s) => ({
+        pid: s.pid,
+        directory: s.directory,
+        startedAt: s.startedAt,
+        happySessionId: s.happySessionId
+      }));
+      return { sessions };
+    });
   }
   // -----------------------------------------------------------------------
   // Connection
@@ -1526,6 +2279,8 @@ class MachineClient {
         status: "running",
         pid: process.pid,
         startedAt: Date.now(),
+        startTime: this.startTime,
+        startedWithCliVersion: this.agentVersion,
         tailscale: this.lastTailscaleInfo ?? state?.tailscale
       }));
       this.startKeepAlive();
@@ -1565,12 +2320,12 @@ class MachineClient {
         }
       }
     });
-    if (this.onEphemeral) {
-      this.socket.on("ephemeral", (data) => {
-        logger.debug("[MACHINE] Received ephemeral event:", data.type);
-        this.onEphemeral?.(data);
-      });
-    }
+    this.socket.on("ephemeral", (data) => {
+      const event = data;
+      logger.debug("[MACHINE] Received ephemeral event:", event.type);
+      this.onEphemeral?.(event);
+      this.handleAutomationEvent(event);
+    });
     this.socket.on("connect_error", (error) => {
       logger.debug(`[MACHINE] Connection error: ${error.message}`);
     });
@@ -1647,6 +2402,79 @@ class MachineClient {
     }, { maxRetries: 3, label: "updateDaemonState" });
   }
   // -----------------------------------------------------------------------
+  // Socket event emitters
+  // -----------------------------------------------------------------------
+  /** Emit a session lifecycle event. */
+  emitSessionEvent(sessionId, eventType, summary, detail) {
+    this.socket?.emit("session-event", { sessionId, eventType, summary, detail });
+  }
+  /** Report webhook processing status. */
+  emitWebhookStatus(data) {
+    this.socket?.emit("webhook-status", data);
+  }
+  /** Report supervisor run status. */
+  emitSupervisorRunStatus(data) {
+    this.socket?.emit("supervisor-run-status", data);
+  }
+  /** Submit a knowledge entry from a session. */
+  emitSubmitKnowledge(sid, entry) {
+    this.socket?.emit("submit-knowledge", { sid, entry });
+  }
+  /** Fetch knowledge for a session. */
+  emitFetchKnowledge(sid, mode, contextHints, callback) {
+    this.socket?.emit("fetch-knowledge", { sid, mode, contextHints }, callback);
+  }
+  /** Stream task log chunk. */
+  emitTaskLog(sid, taskId, outputFile, chunk, offset) {
+    this.socket?.emit("task-log", { sid, taskId, outputFile, chunk, offset });
+  }
+  // -----------------------------------------------------------------------
+  // Automation triggers
+  // -----------------------------------------------------------------------
+  /**
+   * Enable automation handling — agent will process webhook, supervisor,
+   * and task triggers from the server by spawning Happy CLI sessions.
+   */
+  enableAutomation(serverUrl, authToken, scheduler) {
+    this.automationEnabled = true;
+    this.automationServerUrl = serverUrl;
+    this.automationAuthToken = authToken;
+    this.scheduler = scheduler;
+    logger.debug("[MACHINE] Automation enabled");
+  }
+  /** Internal dispatch for ephemeral events that need automation handling. */
+  handleAutomationEvent(event) {
+    if (!this.automationEnabled || !this.scheduler) return;
+    switch (event.type) {
+      case "webhook-trigger":
+        handleWebhookTrigger(
+          event,
+          this,
+          this.automationServerUrl,
+          this.automationAuthToken,
+          this.scheduler
+        );
+        break;
+      case "supervisor-trigger":
+        handleSupervisorTrigger(
+          event,
+          this,
+          this.automationServerUrl,
+          this.automationAuthToken,
+          this.scheduler
+        );
+        break;
+      case "task-trigger":
+        handleTaskTrigger(
+          event,
+          this.automationServerUrl,
+          this.automationAuthToken,
+          this.scheduler
+        );
+        break;
+    }
+  }
+  // -----------------------------------------------------------------------
   // Lifecycle
   // -----------------------------------------------------------------------
   /** Seed initial Tailscale info detected before connect. */
@@ -1721,6 +2549,306 @@ function tailscaleChanged(prev, next) {
   return prev.status !== next.status || prev.ipv4 !== next.ipv4 || prev.ipv6 !== next.ipv6 || prev.hostname !== next.hostname || JSON.stringify(prev.serves) !== JSON.stringify(next.serves);
 }
 
+const PRIORITY_ORDER = {
+  urgent: 0,
+  user: 1,
+  background: 2
+};
+const ACTIVE_STATUSES = /* @__PURE__ */ new Set(["queued", "dispatching", "running"]);
+class AutomationScheduler {
+  maxConcurrentJobs;
+  retryDelayMs;
+  defaultMaxAttempts;
+  maxRecentCompletions;
+  /** Active jobs indexed by id. */
+  jobs = /* @__PURE__ */ new Map();
+  /** dedupeKey → jobId for fast dedup lookups. */
+  dedupeIndex = /* @__PURE__ */ new Map();
+  /** Ring buffer for completed/failed jobs. */
+  recentCompletions = [];
+  pumpTimer = null;
+  pumping = false;
+  constructor(options) {
+    this.maxConcurrentJobs = options?.maxConcurrentJobs ?? 2;
+    this.retryDelayMs = options?.retryDelayMs ?? 5e3;
+    this.defaultMaxAttempts = options?.maxAttempts ?? 3;
+    this.maxRecentCompletions = options?.maxRecentCompletions ?? 50;
+    this.pumpTimer = setInterval(() => this.pump(), 1e3);
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+  enqueue(opts) {
+    const existingId = this.dedupeIndex.get(opts.dedupeKey);
+    if (existingId) {
+      const existing = this.jobs.get(existingId);
+      if (existing && ACTIVE_STATUSES.has(existing.status)) {
+        logger.debug(`[SCHEDULER] Deduped: ${opts.dedupeKey} (job ${existingId} is ${existing.status})`);
+        return { job: existing, deduped: true };
+      }
+    }
+    const job = {
+      id: crypto.randomUUID(),
+      kind: opts.kind,
+      dedupeKey: opts.dedupeKey,
+      priority: opts.priority,
+      status: "queued",
+      attempt: 0,
+      maxAttempts: this.defaultMaxAttempts,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      nextRunAt: Date.now(),
+      run: opts.run
+    };
+    this.jobs.set(job.id, job);
+    this.dedupeIndex.set(job.dedupeKey, job.id);
+    logger.debug(`[SCHEDULER] Enqueued: ${job.kind} ${job.dedupeKey} (${job.priority}) id=${job.id}`);
+    this.pump();
+    return { job, deduped: false };
+  }
+  markCompleted(jobId) {
+    const job = this.jobs.get(jobId);
+    if (!job || job.status === "completed" || job.status === "failed") return;
+    job.status = "completed";
+    job.updatedAt = Date.now();
+    logger.debug(`[SCHEDULER] Completed: ${job.kind} ${job.dedupeKey} id=${jobId}`);
+    this.finalize(job);
+  }
+  markFailed(jobId, error) {
+    const job = this.jobs.get(jobId);
+    if (!job || job.status === "completed" || job.status === "failed") return;
+    job.errorMessage = error;
+    job.updatedAt = Date.now();
+    if (job.attempt < job.maxAttempts) {
+      job.status = "queued";
+      job.nextRunAt = Date.now() + job.attempt * this.retryDelayMs;
+      logger.debug(`[SCHEDULER] Retry queued: ${job.dedupeKey} attempt=${job.attempt}/${job.maxAttempts} nextRunAt=+${job.attempt * this.retryDelayMs}ms`);
+      this.pump();
+      return;
+    }
+    job.status = "failed";
+    logger.debug(`[SCHEDULER] Failed (exhausted): ${job.kind} ${job.dedupeKey} id=${jobId}: ${error}`);
+    this.finalize(job);
+  }
+  getStatus() {
+    let queueLength = 0;
+    let runningCount = 0;
+    for (const job of this.jobs.values()) {
+      if (job.status === "queued") queueLength++;
+      else if (job.status === "dispatching" || job.status === "running") runningCount++;
+    }
+    return {
+      queueLength,
+      runningCount,
+      recentCompletions: [...this.recentCompletions]
+    };
+  }
+  shutdown() {
+    if (this.pumpTimer) {
+      clearInterval(this.pumpTimer);
+      this.pumpTimer = null;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  pump() {
+    if (this.pumping) return;
+    this.pumping = true;
+    try {
+      const now = Date.now();
+      let runningCount = 0;
+      for (const job of this.jobs.values()) {
+        if (job.status === "dispatching" || job.status === "running") runningCount++;
+      }
+      if (runningCount >= this.maxConcurrentJobs) return;
+      const ready = [];
+      for (const job of this.jobs.values()) {
+        if (job.status === "queued" && job.nextRunAt <= now) {
+          ready.push(job);
+        }
+      }
+      ready.sort((a, b) => {
+        const pDiff = PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority];
+        if (pDiff !== 0) return pDiff;
+        return a.createdAt - b.createdAt;
+      });
+      const slotsAvailable = this.maxConcurrentJobs - runningCount;
+      const toDispatch = ready.slice(0, slotsAvailable);
+      for (const job of toDispatch) {
+        this.dispatch(job);
+      }
+    } finally {
+      this.pumping = false;
+    }
+  }
+  dispatch(job) {
+    job.status = "dispatching";
+    job.attempt++;
+    job.updatedAt = Date.now();
+    logger.debug(`[SCHEDULER] Dispatching: ${job.kind} ${job.dedupeKey} attempt=${job.attempt}`);
+    job.run(job.id).then(({ pid }) => {
+      if (job.status === "dispatching") {
+        job.status = "running";
+        job.pid = pid;
+        job.updatedAt = Date.now();
+        logger.debug(`[SCHEDULER] Running: ${job.dedupeKey} pid=${pid}`);
+      }
+    }).catch((error) => {
+      const msg = error instanceof Error ? error.message : String(error);
+      logger.debug(`[SCHEDULER] Dispatch failed: ${job.dedupeKey}: ${msg}`);
+      if (job.status === "dispatching") {
+        this.markFailed(job.id, msg);
+      }
+    });
+  }
+  finalize(job) {
+    this.jobs.delete(job.id);
+    if (this.dedupeIndex.get(job.dedupeKey) === job.id) {
+      this.dedupeIndex.delete(job.dedupeKey);
+    }
+    this.recentCompletions.push({
+      id: job.id,
+      kind: job.kind,
+      dedupeKey: job.dedupeKey,
+      status: job.status,
+      completedAt: job.updatedAt,
+      errorMessage: job.errorMessage
+    });
+    while (this.recentCompletions.length > this.maxRecentCompletions) {
+      this.recentCompletions.shift();
+    }
+    this.pump();
+  }
+}
+
+function pidFilePath(homeDir) {
+  return node_path.join(homeDir, "agent-daemon.pid");
+}
+function writePidFile(homeDir, pid) {
+  node_fs.mkdirSync(homeDir, { recursive: true });
+  node_fs.writeFileSync(pidFilePath(homeDir), String(pid), "utf-8");
+}
+function readPidFile(homeDir) {
+  try {
+    const raw = node_fs.readFileSync(pidFilePath(homeDir), "utf-8").trim();
+    const pid = parseInt(raw, 10);
+    return isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+function removePidFile(homeDir) {
+  try {
+    node_fs.unlinkSync(pidFilePath(homeDir));
+  } catch {
+  }
+}
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function startDaemon(options) {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const existingPid = readPidFile(config.homeDir);
+  if (existingPid && isProcessRunning(existingPid)) {
+    console.log(`Daemon already running (PID ${existingPid})`);
+    process.exitCode = 1;
+    return;
+  }
+  if (existingPid) {
+    removePidFile(config.homeDir);
+  }
+  const workDir = options.directory ?? process.cwd();
+  console.log(`Starting agent daemon in ${workDir}...`);
+  const metadata = {
+    host: node_os.hostname(),
+    platform: process.platform,
+    happyCliVersion: version,
+    homeDir: config.homeDir,
+    happyHomeDir: config.homeDir,
+    happyLibDir: config.homeDir
+  };
+  const machine = await getOrCreateMachine(config, creds, metadata);
+  console.log(`Machine: ${machine.id} (${machine.metadata.host})`);
+  const tailscaleInfo = await detectTailscale();
+  const serves = tailscaleInfo.status === "connected" ? await detectTailscaleServe() : [];
+  const fullTailscale = { ...tailscaleInfo, serves };
+  if (tailscaleInfo.status === "connected") {
+    console.log(`Tailscale: ${tailscaleInfo.hostname} (${tailscaleInfo.ipv4})`);
+  }
+  const client = new MachineClient({
+    token: creds.token,
+    machine,
+    serverUrl: config.serverUrl,
+    agentVersion: version,
+    workingDirectory: workDir
+  });
+  const scheduler = new AutomationScheduler({ maxConcurrentJobs: 2 });
+  client.setTailscaleInfo(fullTailscale);
+  client.enableAutomation(config.serverUrl, creds.token, scheduler);
+  client.connect();
+  writePidFile(config.homeDir, process.pid);
+  console.log(`Daemon started (PID ${process.pid})`);
+  let shuttingDown = false;
+  const shutdown = (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    logger.debug(`[DAEMON] Received ${signal}, shutting down...`);
+    console.log(`
+Received ${signal}, shutting down...`);
+    scheduler.shutdown();
+    client.shutdown();
+    removePidFile(config.homeDir);
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  await new Promise(() => {
+  });
+}
+function stopDaemon() {
+  const config = loadConfig();
+  const pid = readPidFile(config.homeDir);
+  if (!pid) {
+    console.log("No daemon PID file found.");
+    return;
+  }
+  if (!isProcessRunning(pid)) {
+    console.log(`Daemon PID ${pid} is not running (stale PID file). Cleaning up.`);
+    removePidFile(config.homeDir);
+    return;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+    console.log(`Sent SIGTERM to daemon (PID ${pid})`);
+    removePidFile(config.homeDir);
+  } catch (error) {
+    console.error(`Failed to stop daemon: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
+}
+function daemonStatus() {
+  const config = loadConfig();
+  const pid = readPidFile(config.homeDir);
+  if (!pid) {
+    console.log("Daemon is not running (no PID file).");
+    return;
+  }
+  if (isProcessRunning(pid)) {
+    console.log(`Daemon is running (PID ${pid})`);
+    console.log(`PID file: ${pidFilePath(config.homeDir)}`);
+  } else {
+    console.log(`Daemon PID ${pid} is not running (stale PID file).`);
+    console.log(`Run \`happy-agent daemon stop\` to clean up.`);
+  }
+}
+
 function formatTime(ts) {
   if (!ts) return "-";
   const date = new Date(ts);
@@ -2156,6 +3284,19 @@ program.command("machine").description("Manage machine identity").addCommand(
     }
   })
 );
+program.command("daemon").description("Run as a persistent background daemon").addCommand(
+  new commander.Command("start").description("Start the agent daemon (connects to server, handles triggers)").option("--directory <dir>", "Working directory for spawned sessions").option("--foreground", "Run in foreground (do not detach)").action(async (opts) => {
+    await startDaemon(opts);
+  })
+).addCommand(
+  new commander.Command("stop").description("Stop the running daemon").action(() => {
+    stopDaemon();
+  })
+).addCommand(
+  new commander.Command("status").description("Check daemon status").action(() => {
+    daemonStatus();
+  })
+);
 program.parseAsync(process.argv).catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));
   process.exitCode = 1;
@@ -2169,6 +3310,7 @@ exports.authLogout = authLogout;
 exports.authStatus = authStatus;
 exports.createRpcHandlerManager = createRpcHandlerManager;
 exports.createSession = createSession;
+exports.daemonStatus = daemonStatus;
 exports.deleteSession = deleteSession;
 exports.fetchMessagesAfterSeq = fetchMessagesAfterSeq;
 exports.getOrCreateMachine = getOrCreateMachine;
@@ -2181,3 +3323,5 @@ exports.readCredentials = readCredentials;
 exports.requireCredentials = requireCredentials;
 exports.resolveSessionEncryption = resolveSessionEncryption;
 exports.sendMessagesBatch = sendMessagesBatch;
+exports.startDaemon = startDaemon;
+exports.stopDaemon = stopDaemon;