@kmmao/happy-agent 0.4.0 → 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.4.0";
+var version = "0.4.1";
 
 function loadConfig() {
   const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://happyserve.xycloud.info").replace(/\/+$/, "");
@@ -1846,9 +1846,24 @@ function untrackSession(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([
@@ -2044,130 +2059,139 @@ function buildSupervisorPrompt(data) {
   if (data.customRules) parts.push("", "## Custom Rules", data.customRules);
   return parts.join("\n");
 }
-async function handleWebhookTrigger(data, client, serverUrl, authToken) {
+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}`);
-  client.emitWebhookStatus({
-    webhookEventId: data.webhookEventId,
-    status: "dispatched"
-  });
-  try {
-    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") {
-      logger.debug(`[TRIGGER] Webhook session spawned: PID ${result.pid}`);
-    } else {
-      logger.debug(`[TRIGGER] Webhook spawn failed: ${result.type === "error" ? result.errorMessage : "needs approval"}`);
-      client.emitWebhookStatus({
-        webhookEventId: data.webhookEventId,
-        status: "failed",
-        errorMessage: result.type === "error" ? result.errorMessage : "Directory creation not approved"
+  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 };
     }
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    logger.debug(`[TRIGGER] Webhook error: ${msg}`);
-    client.emitWebhookStatus({
-      webhookEventId: data.webhookEventId,
-      status: "failed",
-      errorMessage: msg
-    });
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Webhook deduped: ${data.webhookEventId}`);
   }
 }
-async function handleSupervisorTrigger(data, client, serverUrl, authToken) {
+function handleSupervisorTrigger(data, client, serverUrl, authToken, scheduler) {
   logger.debug(`[TRIGGER] Supervisor: run ${data.runId} in ${data.repoPath}`);
-  client.emitSupervisorRunStatus({
-    runId: data.runId,
-    projectId: data.projectId,
-    status: "running"
-  });
-  try {
-    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") {
-      client.emitSupervisorRunStatus({
-        runId: data.runId,
-        projectId: data.projectId,
-        status: "failed",
-        errorMessage: result.type === "error" ? result.errorMessage : "Directory creation not approved"
+  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 };
     }
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    logger.debug(`[TRIGGER] Supervisor error: ${msg}`);
-    client.emitSupervisorRunStatus({
-      runId: data.runId,
-      projectId: data.projectId,
-      status: "failed",
-      errorMessage: msg
-    });
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Supervisor deduped: ${data.runId}`);
   }
 }
-async function handleTaskTrigger(data, serverUrl, _authToken) {
+function handleTaskTrigger(data, serverUrl, _authToken, scheduler) {
   logger.debug(`[TRIGGER] Task: ${data.taskId} in ${data.directory}`);
-  try {
-    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 { 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,
-      // Tasks always auto-approve directory
-      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
+      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");
       }
-    });
-    if (result.type !== "success") {
-      logger.debug(`[TRIGGER] Task spawn failed: ${result.type === "error" ? result.errorMessage : "needs approval"}`);
+      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 };
     }
-  } catch (error) {
-    logger.debug(`[TRIGGER] Task error: ${error instanceof Error ? error.message : String(error)}`);
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Task deduped: ${data.taskId}`);
   }
 }
 
@@ -2188,6 +2212,7 @@ class MachineClient {
   automationEnabled = false;
   automationServerUrl = "";
   automationAuthToken = "";
+  scheduler = null;
   constructor(opts) {
     this.token = opts.token;
     this.machine = opts.machine;
@@ -2410,37 +2435,41 @@ class MachineClient {
    * Enable automation handling — agent will process webhook, supervisor,
    * and task triggers from the server by spawning Happy CLI sessions.
    */
-  enableAutomation(serverUrl, authToken) {
+  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) return;
+    if (!this.automationEnabled || !this.scheduler) return;
     switch (event.type) {
       case "webhook-trigger":
-        void handleWebhookTrigger(
+        handleWebhookTrigger(
           event,
           this,
           this.automationServerUrl,
-          this.automationAuthToken
+          this.automationAuthToken,
+          this.scheduler
         );
         break;
       case "supervisor-trigger":
-        void handleSupervisorTrigger(
+        handleSupervisorTrigger(
           event,
           this,
           this.automationServerUrl,
-          this.automationAuthToken
+          this.automationAuthToken,
+          this.scheduler
         );
         break;
       case "task-trigger":
-        void handleTaskTrigger(
+        handleTaskTrigger(
           event,
           this.automationServerUrl,
-          this.automationAuthToken
+          this.automationAuthToken,
+          this.scheduler
         );
         break;
     }
@@ -2520,6 +2549,179 @@ 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");
 }
@@ -2587,8 +2789,9 @@ async function startDaemon(options) {
     agentVersion: version,
     workingDirectory: workDir
   });
+  const scheduler = new AutomationScheduler({ maxConcurrentJobs: 2 });
   client.setTailscaleInfo(fullTailscale);
-  client.enableAutomation(config.serverUrl, creds.token);
+  client.enableAutomation(config.serverUrl, creds.token, scheduler);
   client.connect();
   writePidFile(config.homeDir, process.pid);
   console.log(`Daemon started (PID ${process.pid})`);
@@ -2599,6 +2802,7 @@ async function startDaemon(options) {
     logger.debug(`[DAEMON] Received ${signal}, shutting down...`);
     console.log(`
 Received ${signal}, shutting down...`);
+    scheduler.shutdown();
     client.shutdown();
     removePidFile(config.homeDir);
     process.exit(0);

package/dist/index.d.cts

@@ -345,6 +345,90 @@ declare class TunnelManager {
     stopRefresh(): void;
 }
 
+/**
+ * AutomationScheduler — lightweight in-memory job queue for agent triggers.
+ *
+ * Features:
+ * - Priority queue (urgent > user > background)
+ * - dedupeKey deduplication (queued/dispatching/running)
+ * - Concurrency limit (maxConcurrentJobs)
+ * - Retry with incremental backoff (attempt * retryDelayMs)
+ * - Ring buffer for recent completions (observability)
+ */
+type JobPriority = "urgent" | "user" | "background";
+type JobStatus = "queued" | "dispatching" | "running" | "completed" | "failed";
+interface SchedulerJob {
+    readonly id: string;
+    readonly kind: "webhook" | "supervisor" | "task";
+    readonly dedupeKey: string;
+    readonly priority: JobPriority;
+    status: JobStatus;
+    attempt: number;
+    readonly maxAttempts: number;
+    readonly createdAt: number;
+    updatedAt: number;
+    nextRunAt: number;
+    errorMessage?: string;
+    pid?: number;
+    /** The thunk that performs the actual work (spawn session etc.) */
+    readonly run: (jobId: string) => Promise<{
+        pid: number;
+    }>;
+}
+interface EnqueueOptions {
+    kind: SchedulerJob["kind"];
+    dedupeKey: string;
+    priority: JobPriority;
+    run: (jobId: string) => Promise<{
+        pid: number;
+    }>;
+}
+interface EnqueueResult {
+    job: SchedulerJob;
+    deduped: boolean;
+}
+interface SchedulerStatus {
+    queueLength: number;
+    runningCount: number;
+    recentCompletions: Array<{
+        id: string;
+        kind: string;
+        dedupeKey: string;
+        status: "completed" | "failed";
+        completedAt: number;
+        errorMessage?: string;
+    }>;
+}
+interface SchedulerOptions {
+    maxConcurrentJobs?: number;
+    retryDelayMs?: number;
+    maxAttempts?: number;
+    maxRecentCompletions?: number;
+}
+declare class AutomationScheduler {
+    private readonly maxConcurrentJobs;
+    private readonly retryDelayMs;
+    private readonly defaultMaxAttempts;
+    private readonly maxRecentCompletions;
+    /** Active jobs indexed by id. */
+    private readonly jobs;
+    /** dedupeKey → jobId for fast dedup lookups. */
+    private readonly dedupeIndex;
+    /** Ring buffer for completed/failed jobs. */
+    private readonly recentCompletions;
+    private pumpTimer;
+    private pumping;
+    constructor(options?: SchedulerOptions);
+    enqueue(opts: EnqueueOptions): EnqueueResult;
+    markCompleted(jobId: string): void;
+    markFailed(jobId: string, error: string): void;
+    getStatus(): SchedulerStatus;
+    shutdown(): void;
+    private pump;
+    private dispatch;
+    private finalize;
+}
+
 /**
  * Machine WebSocket client — trimmed from CLI's ApiMachineClient.
  *
@@ -431,6 +515,7 @@ declare class MachineClient {
     private automationEnabled;
     private automationServerUrl;
     private automationAuthToken;
+    private scheduler;
     constructor(opts: MachineClientOptions);
     private registerMachineHandlers;
     connect(): void;
@@ -494,7 +579,7 @@ declare class MachineClient {
      * Enable automation handling — agent will process webhook, supervisor,
      * and task triggers from the server by spawning Happy CLI sessions.
      */
-    enableAutomation(serverUrl: string, authToken: string): void;
+    enableAutomation(serverUrl: string, authToken: string, scheduler: AutomationScheduler): void;
     /** Internal dispatch for ephemeral events that need automation handling. */
     private handleAutomationEvent;
     /** Seed initial Tailscale info detected before connect. */

package/dist/index.d.mts

@@ -345,6 +345,90 @@ declare class TunnelManager {
     stopRefresh(): void;
 }
 
+/**
+ * AutomationScheduler — lightweight in-memory job queue for agent triggers.
+ *
+ * Features:
+ * - Priority queue (urgent > user > background)
+ * - dedupeKey deduplication (queued/dispatching/running)
+ * - Concurrency limit (maxConcurrentJobs)
+ * - Retry with incremental backoff (attempt * retryDelayMs)
+ * - Ring buffer for recent completions (observability)
+ */
+type JobPriority = "urgent" | "user" | "background";
+type JobStatus = "queued" | "dispatching" | "running" | "completed" | "failed";
+interface SchedulerJob {
+    readonly id: string;
+    readonly kind: "webhook" | "supervisor" | "task";
+    readonly dedupeKey: string;
+    readonly priority: JobPriority;
+    status: JobStatus;
+    attempt: number;
+    readonly maxAttempts: number;
+    readonly createdAt: number;
+    updatedAt: number;
+    nextRunAt: number;
+    errorMessage?: string;
+    pid?: number;
+    /** The thunk that performs the actual work (spawn session etc.) */
+    readonly run: (jobId: string) => Promise<{
+        pid: number;
+    }>;
+}
+interface EnqueueOptions {
+    kind: SchedulerJob["kind"];
+    dedupeKey: string;
+    priority: JobPriority;
+    run: (jobId: string) => Promise<{
+        pid: number;
+    }>;
+}
+interface EnqueueResult {
+    job: SchedulerJob;
+    deduped: boolean;
+}
+interface SchedulerStatus {
+    queueLength: number;
+    runningCount: number;
+    recentCompletions: Array<{
+        id: string;
+        kind: string;
+        dedupeKey: string;
+        status: "completed" | "failed";
+        completedAt: number;
+        errorMessage?: string;
+    }>;
+}
+interface SchedulerOptions {
+    maxConcurrentJobs?: number;
+    retryDelayMs?: number;
+    maxAttempts?: number;
+    maxRecentCompletions?: number;
+}
+declare class AutomationScheduler {
+    private readonly maxConcurrentJobs;
+    private readonly retryDelayMs;
+    private readonly defaultMaxAttempts;
+    private readonly maxRecentCompletions;
+    /** Active jobs indexed by id. */
+    private readonly jobs;
+    /** dedupeKey → jobId for fast dedup lookups. */
+    private readonly dedupeIndex;
+    /** Ring buffer for completed/failed jobs. */
+    private readonly recentCompletions;
+    private pumpTimer;
+    private pumping;
+    constructor(options?: SchedulerOptions);
+    enqueue(opts: EnqueueOptions): EnqueueResult;
+    markCompleted(jobId: string): void;
+    markFailed(jobId: string, error: string): void;
+    getStatus(): SchedulerStatus;
+    shutdown(): void;
+    private pump;
+    private dispatch;
+    private finalize;
+}
+
 /**
  * Machine WebSocket client — trimmed from CLI's ApiMachineClient.
  *
@@ -431,6 +515,7 @@ declare class MachineClient {
     private automationEnabled;
     private automationServerUrl;
     private automationAuthToken;
+    private scheduler;
     constructor(opts: MachineClientOptions);
     private registerMachineHandlers;
     connect(): void;
@@ -494,7 +579,7 @@ declare class MachineClient {
      * Enable automation handling — agent will process webhook, supervisor,
      * and task triggers from the server by spawning Happy CLI sessions.
      */
-    enableAutomation(serverUrl: string, authToken: string): void;
+    enableAutomation(serverUrl: string, authToken: string, scheduler: AutomationScheduler): void;
     /** Internal dispatch for ephemeral events that need automation handling. */
     private handleAutomationEvent;
     /** Seed initial Tailscale info detected before connect. */

package/dist/index.mjs

@@ -11,12 +11,12 @@ import { io } from 'socket.io-client';
 import { exec, execFile, spawn } from 'child_process';
 import { promisify } from 'util';
 import { readFile, mkdir, writeFile, readdir, stat } from 'fs/promises';
-import { createHash as createHash$1 } from 'crypto';
+import { createHash as createHash$1, randomUUID } from 'crypto';
 import { join as join$1, resolve } from 'path';
 import { realpathSync } from 'fs';
 import { tmpdir } from 'os';
 
-var version = "0.4.0";
+var version = "0.4.1";
 
 function loadConfig() {
   const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://happyserve.xycloud.info").replace(/\/+$/, "");
@@ -1844,9 +1844,24 @@ function untrackSession(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 = promisify(execFile);
 const SERVER_INTERNAL_SECRETS = /* @__PURE__ */ new Set([
@@ -2042,130 +2057,139 @@ function buildSupervisorPrompt(data) {
   if (data.customRules) parts.push("", "## Custom Rules", data.customRules);
   return parts.join("\n");
 }
-async function handleWebhookTrigger(data, client, serverUrl, authToken) {
+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}`);
-  client.emitWebhookStatus({
-    webhookEventId: data.webhookEventId,
-    status: "dispatched"
-  });
-  try {
-    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") {
-      logger.debug(`[TRIGGER] Webhook session spawned: PID ${result.pid}`);
-    } else {
-      logger.debug(`[TRIGGER] Webhook spawn failed: ${result.type === "error" ? result.errorMessage : "needs approval"}`);
-      client.emitWebhookStatus({
-        webhookEventId: data.webhookEventId,
-        status: "failed",
-        errorMessage: result.type === "error" ? result.errorMessage : "Directory creation not approved"
+  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 };
     }
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    logger.debug(`[TRIGGER] Webhook error: ${msg}`);
-    client.emitWebhookStatus({
-      webhookEventId: data.webhookEventId,
-      status: "failed",
-      errorMessage: msg
-    });
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Webhook deduped: ${data.webhookEventId}`);
   }
 }
-async function handleSupervisorTrigger(data, client, serverUrl, authToken) {
+function handleSupervisorTrigger(data, client, serverUrl, authToken, scheduler) {
   logger.debug(`[TRIGGER] Supervisor: run ${data.runId} in ${data.repoPath}`);
-  client.emitSupervisorRunStatus({
-    runId: data.runId,
-    projectId: data.projectId,
-    status: "running"
-  });
-  try {
-    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") {
-      client.emitSupervisorRunStatus({
-        runId: data.runId,
-        projectId: data.projectId,
-        status: "failed",
-        errorMessage: result.type === "error" ? result.errorMessage : "Directory creation not approved"
+  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 };
     }
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    logger.debug(`[TRIGGER] Supervisor error: ${msg}`);
-    client.emitSupervisorRunStatus({
-      runId: data.runId,
-      projectId: data.projectId,
-      status: "failed",
-      errorMessage: msg
-    });
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Supervisor deduped: ${data.runId}`);
   }
 }
-async function handleTaskTrigger(data, serverUrl, _authToken) {
+function handleTaskTrigger(data, serverUrl, _authToken, scheduler) {
   logger.debug(`[TRIGGER] Task: ${data.taskId} in ${data.directory}`);
-  try {
-    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 { 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,
-      // Tasks always auto-approve directory
-      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
+      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");
       }
-    });
-    if (result.type !== "success") {
-      logger.debug(`[TRIGGER] Task spawn failed: ${result.type === "error" ? result.errorMessage : "needs approval"}`);
+      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 };
     }
-  } catch (error) {
-    logger.debug(`[TRIGGER] Task error: ${error instanceof Error ? error.message : String(error)}`);
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Task deduped: ${data.taskId}`);
   }
 }
 
@@ -2186,6 +2210,7 @@ class MachineClient {
   automationEnabled = false;
   automationServerUrl = "";
   automationAuthToken = "";
+  scheduler = null;
   constructor(opts) {
     this.token = opts.token;
     this.machine = opts.machine;
@@ -2408,37 +2433,41 @@ class MachineClient {
    * Enable automation handling — agent will process webhook, supervisor,
    * and task triggers from the server by spawning Happy CLI sessions.
    */
-  enableAutomation(serverUrl, authToken) {
+  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) return;
+    if (!this.automationEnabled || !this.scheduler) return;
     switch (event.type) {
       case "webhook-trigger":
-        void handleWebhookTrigger(
+        handleWebhookTrigger(
           event,
           this,
           this.automationServerUrl,
-          this.automationAuthToken
+          this.automationAuthToken,
+          this.scheduler
         );
         break;
       case "supervisor-trigger":
-        void handleSupervisorTrigger(
+        handleSupervisorTrigger(
           event,
           this,
           this.automationServerUrl,
-          this.automationAuthToken
+          this.automationAuthToken,
+          this.scheduler
         );
         break;
       case "task-trigger":
-        void handleTaskTrigger(
+        handleTaskTrigger(
           event,
           this.automationServerUrl,
-          this.automationAuthToken
+          this.automationAuthToken,
+          this.scheduler
         );
         break;
     }
@@ -2518,6 +2547,179 @@ 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: 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 join(homeDir, "agent-daemon.pid");
 }
@@ -2585,8 +2787,9 @@ async function startDaemon(options) {
     agentVersion: version,
     workingDirectory: workDir
   });
+  const scheduler = new AutomationScheduler({ maxConcurrentJobs: 2 });
   client.setTailscaleInfo(fullTailscale);
-  client.enableAutomation(config.serverUrl, creds.token);
+  client.enableAutomation(config.serverUrl, creds.token, scheduler);
   client.connect();
   writePidFile(config.homeDir, process.pid);
   console.log(`Daemon started (PID ${process.pid})`);
@@ -2597,6 +2800,7 @@ async function startDaemon(options) {
     logger.debug(`[DAEMON] Received ${signal}, shutting down...`);
     console.log(`
 Received ${signal}, shutting down...`);
+    scheduler.shutdown();
     client.shutdown();
     removePidFile(config.homeDir);
     process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kmmao/happy-agent",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "CLI client for controlling Happy Coder agents remotely",
   "author": "Kirill Dubovitskiy",
   "license": "MIT",