@femtomc/mu-server 26.2.56 → 26.2.57

package/dist/heartbeat_programs.js

@@ -34,6 +34,13 @@ function normalizeTarget(input) {
     }
     return null;
 }
+function normalizeWakeMode(value) {
+    if (typeof value !== "string") {
+        return "immediate";
+    }
+    const normalized = value.trim().toLowerCase().replaceAll("-", "_");
+    return normalized === "next_heartbeat" ? "next_heartbeat" : "immediate";
+}
 function sanitizeMetadata(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return {};
@@ -52,9 +59,7 @@ function normalizeProgram(row) {
         return null;
     }
     const everyMsRaw = record.every_ms;
-    const everyMs = typeof everyMsRaw === "number" && Number.isFinite(everyMsRaw)
-        ? Math.max(0, Math.trunc(everyMsRaw))
-        : 0;
+    const everyMs = typeof everyMsRaw === "number" && Number.isFinite(everyMsRaw) ? Math.max(0, Math.trunc(everyMsRaw)) : 0;
     const createdAt = typeof record.created_at_ms === "number" && Number.isFinite(record.created_at_ms)
         ? Math.trunc(record.created_at_ms)
         : defaultNowMs();
@@ -72,6 +77,7 @@ function normalizeProgram(row) {
         ? lastResultRaw
         : null;
     const reason = typeof record.reason === "string" && record.reason.trim().length > 0 ? record.reason.trim() : "scheduled";
+    const wakeMode = normalizeWakeMode(record.wake_mode);
     return {
         v: 1,
         program_id: programId,
@@ -79,6 +85,7 @@ function normalizeProgram(row) {
         enabled: record.enabled !== false,
         every_ms: everyMs,
         reason,
+        wake_mode: wakeMode,
         target,
         metadata: sanitizeMetadata(record.metadata),
         created_at_ms: createdAt,
@@ -180,12 +187,17 @@ export class HeartbeatProgramRegistry {
         const nowMs = Math.trunc(this.#nowMs());
         program.last_triggered_at_ms = nowMs;
         program.updated_at_ms = nowMs;
+        let heartbeatResult;
+        let eventStatus = "ok";
+        let eventReason = heartbeatReason;
+        let eventMessage = `heartbeat program tick: ${program.title}`;
         try {
             const result = program.target.kind === "run"
                 ? await this.#runHeartbeat({
                     jobId: program.target.job_id,
                     rootIssueId: program.target.root_issue_id,
                     reason: heartbeatReason,
+                    wakeMode: program.wake_mode,
                 })
                 : await this.#activityHeartbeat({
                     activityId: program.target.activity_id,
@@ -194,92 +206,69 @@ export class HeartbeatProgramRegistry {
             if (result.ok) {
                 program.last_result = "ok";
                 program.last_error = null;
-                void this.#persist().catch(() => {
-                    // Best effort persistence on background ticks.
-                });
-                void this.#emitTickEvent({
-                    ts_ms: nowMs,
-                    program_id: program.program_id,
-                    message: `heartbeat program tick: ${program.title}`,
-                    status: "ok",
-                    reason: heartbeatReason,
-                    program: this.#snapshot(program),
-                }).catch(() => {
-                    // best effort only
-                });
-                return { status: "ran" };
+                heartbeatResult = { status: "ran" };
             }
-            if (result.reason === "not_running") {
+            else if (result.reason === "not_running") {
                 program.last_result = "not_running";
                 program.last_error = null;
-                void this.#persist().catch(() => {
-                    // Best effort persistence on background ticks.
-                });
-                void this.#emitTickEvent({
-                    ts_ms: nowMs,
-                    program_id: program.program_id,
-                    message: `heartbeat program skipped (not running): ${program.title}`,
-                    status: "not_running",
-                    reason: result.reason,
-                    program: this.#snapshot(program),
-                }).catch(() => {
-                    // best effort only
-                });
-                return { status: "skipped", reason: "not_running" };
+                eventStatus = "not_running";
+                eventReason = result.reason;
+                eventMessage = `heartbeat program skipped (not running): ${program.title}`;
+                heartbeatResult = { status: "skipped", reason: "not_running" };
             }
-            if (result.reason === "not_found") {
+            else if (result.reason === "not_found") {
                 program.last_result = "not_found";
                 program.last_error = null;
-                void this.#persist().catch(() => {
-                    // Best effort persistence on background ticks.
-                });
-                void this.#emitTickEvent({
-                    ts_ms: nowMs,
-                    program_id: program.program_id,
-                    message: `heartbeat program skipped (not found): ${program.title}`,
-                    status: "not_found",
-                    reason: result.reason,
-                    program: this.#snapshot(program),
-                }).catch(() => {
-                    // best effort only
-                });
-                return { status: "skipped", reason: "not_found" };
+                eventStatus = "not_found";
+                eventReason = result.reason;
+                eventMessage = `heartbeat program skipped (not found): ${program.title}`;
+                heartbeatResult = { status: "skipped", reason: "not_found" };
+            }
+            else {
+                program.last_result = "failed";
+                program.last_error = result.reason ?? "heartbeat_program_tick_failed";
+                eventStatus = "failed";
+                eventReason = program.last_error;
+                eventMessage = `heartbeat program failed: ${program.title}`;
+                heartbeatResult = { status: "failed", reason: program.last_error };
             }
-            program.last_result = "failed";
-            program.last_error = result.reason ?? "heartbeat_program_tick_failed";
-            void this.#persist().catch(() => {
-                // Best effort persistence on background ticks.
-            });
-            void this.#emitTickEvent({
-                ts_ms: nowMs,
-                program_id: program.program_id,
-                message: `heartbeat program failed: ${program.title}`,
-                status: "failed",
-                reason: program.last_error,
-                program: this.#snapshot(program),
-            }).catch(() => {
-                // best effort only
-            });
-            return { status: "failed", reason: program.last_error };
         }
         catch (err) {
             program.last_result = "failed";
             program.last_error = err instanceof Error ? err.message : String(err);
-            void this.#persist().catch(() => {
-                // Best effort persistence on background ticks.
-            });
-            void this.#emitTickEvent({
-                ts_ms: nowMs,
-                program_id: program.program_id,
-                message: `heartbeat program failed: ${program.title}`,
-                status: "failed",
-                reason: program.last_error,
-                program: this.#snapshot(program),
-            }).catch(() => {
-                // best effort only
-            });
-            return { status: "failed", reason: program.last_error };
+            eventStatus = "failed";
+            eventReason = program.last_error;
+            eventMessage = `heartbeat program failed: ${program.title}`;
+            heartbeatResult = { status: "failed", reason: program.last_error };
+        }
+        const shouldAutoDisableOnTerminal = program.target.kind === "run" &&
+            program.metadata.auto_disable_on_terminal === true &&
+            heartbeatResult.status === "skipped" &&
+            (heartbeatResult.reason === "not_running" || heartbeatResult.reason === "not_found");
+        if (shouldAutoDisableOnTerminal) {
+            program.enabled = false;
+            program.every_ms = 0;
+            program.updated_at_ms = Math.trunc(this.#nowMs());
+            program.metadata = {
+                ...program.metadata,
+                auto_disabled_at_ms: Math.trunc(this.#nowMs()),
+                auto_disabled_reason: heartbeatResult.status === "skipped" ? (heartbeatResult.reason ?? null) : null,
+            };
+            this.#heartbeatScheduler.unregister(this.#scheduleId(program.program_id));
+            eventMessage = `${eventMessage} (auto-disabled)`;
         }
+        await this.#persist();
+        await this.#emitTickEvent({
+            ts_ms: nowMs,
+            program_id: program.program_id,
+            message: eventMessage,
+            status: eventStatus,
+            reason: eventReason,
+            program: this.#snapshot(program),
+        }).catch(() => {
+            // best effort only
+        });
+        return heartbeatResult;
     }
     async list(opts = {}) {
         await this.#ensureLoaded();
@@ -322,6 +311,7 @@ export class HeartbeatProgramRegistry {
                 ? Math.max(0, Math.trunc(opts.everyMs))
                 : 15_000,
             reason: opts.reason?.trim() || "scheduled",
+            wake_mode: normalizeWakeMode(opts.wakeMode),
             target,
             metadata: sanitizeMetadata(opts.metadata),
             created_at_ms: nowMs,
@@ -354,6 +344,9 @@ export class HeartbeatProgramRegistry {
         if (typeof opts.reason === "string") {
             program.reason = opts.reason.trim() || "scheduled";
         }
+        if (typeof opts.wakeMode === "string") {
+            program.wake_mode = normalizeWakeMode(opts.wakeMode);
+        }
         if (typeof opts.enabled === "boolean") {
             program.enabled = opts.enabled;
         }

package/dist/heartbeat_scheduler.js

@@ -49,37 +49,61 @@ function toMs(value, fallback, min) {
     }
     return Math.max(min, Math.trunc(value));
 }
+function shouldRetry(result) {
+    if (result.status === "failed") {
+        return true;
+    }
+    return result.status === "skipped" && result.reason === "requests-in-flight";
+}
 export class ActivityHeartbeatScheduler {
     #states = new Map();
     #nowMs;
     #defaultCoalesceMs;
     #retryMs;
     #minIntervalMs;
+    #wakeTimerToken = 0;
     constructor(opts = {}) {
         this.#nowMs = opts.nowMs ?? defaultNowMs;
         this.#defaultCoalesceMs = Math.max(0, Math.trunc(opts.defaultCoalesceMs ?? DEFAULT_COALESCE_MS));
         this.#retryMs = Math.max(100, Math.trunc(opts.retryMs ?? DEFAULT_RETRY_MS));
         this.#minIntervalMs = Math.max(100, Math.trunc(opts.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS));
     }
+    #isCurrentState(state) {
+        if (state.disposed) {
+            return false;
+        }
+        return this.#states.get(state.activityId) === state;
+    }
+    #normalizeDelayMs(coalesceMs) {
+        if (!Number.isFinite(coalesceMs)) {
+            return this.#defaultCoalesceMs;
+        }
+        return Math.max(0, Math.trunc(coalesceMs));
+    }
     #clearWakeTimer(state) {
         if (state.wakeTimer) {
-            clearTimeout(state.wakeTimer);
-            state.wakeTimer = null;
+            clearTimeout(state.wakeTimer.handle);
         }
-        state.wakeDueAt = null;
-        state.wakeKind = null;
+        state.wakeTimer = null;
     }
     #disposeState(state) {
+        if (state.disposed) {
+            return;
+        }
+        state.disposed = true;
         if (state.intervalTimer) {
             clearInterval(state.intervalTimer);
             state.intervalTimer = null;
         }
         this.#clearWakeTimer(state);
         state.pendingWake = null;
-        state.running = false;
         state.scheduled = false;
+        state.running = false;
     }
     #queuePendingWakeReason(state, reason) {
+        if (!this.#isCurrentState(state)) {
+            return;
+        }
         const normalized = normalizeReason(reason);
         const next = {
             reason: normalized,
@@ -98,73 +122,90 @@ export class ActivityHeartbeatScheduler {
             state.pendingWake = next;
         }
     }
-    #schedule(state, coalesceMs, kind = "normal") {
-        const delay = Math.max(0, Math.trunc(Number.isFinite(coalesceMs) ? coalesceMs : this.#defaultCoalesceMs));
+    #scheduleWake(state, coalesceMs, kind = "normal") {
+        if (!this.#isCurrentState(state)) {
+            return;
+        }
+        const delay = this.#normalizeDelayMs(coalesceMs);
         const dueAt = this.#nowMs() + delay;
-        if (state.wakeTimer) {
+        const activeTimer = state.wakeTimer;
+        if (activeTimer) {
             // Retry cooldown should remain in force.
-            if (state.wakeKind === "retry") {
+            if (activeTimer.kind === "retry") {
                 return;
             }
-            if (typeof state.wakeDueAt === "number" && state.wakeDueAt <= dueAt) {
+            if (activeTimer.dueAt <= dueAt) {
                 return;
             }
             this.#clearWakeTimer(state);
         }
-        state.wakeDueAt = dueAt;
-        state.wakeKind = kind;
-        state.wakeTimer = setTimeout(() => {
-            void this.#flush(state.activityId, delay, kind);
+        const timerToken = ++this.#wakeTimerToken;
+        const handle = setTimeout(() => {
+            void this.#flushWake(state, {
+                timerToken,
+                delay,
+                kind,
+            });
         }, delay);
-        state.wakeTimer.unref?.();
+        handle.unref?.();
+        state.wakeTimer = {
+            handle,
+            dueAt,
+            kind,
+            token: timerToken,
+        };
     }
-    async #flush(activityId, delay, kind) {
-        const state = this.#states.get(activityId);
-        if (!state) {
-            return;
-        }
-        this.#clearWakeTimer(state);
-        state.scheduled = false;
-        if (state.running) {
-            state.scheduled = true;
-            this.#schedule(state, delay, kind);
-            return;
-        }
-        const reason = state.pendingWake?.reason;
-        state.pendingWake = null;
-        state.running = true;
-        let result;
+    async #invokeHandler(state, reason) {
         const startedAt = this.#nowMs();
         try {
-            result = await state.handler({ activityId, reason: reason ?? undefined });
+            const result = await state.handler({
+                activityId: state.activityId,
+                reason,
+            });
             if (result.status === "ran" && result.durationMs == null) {
-                result = {
+                return {
                     status: "ran",
                     durationMs: Math.max(0, Math.trunc(this.#nowMs() - startedAt)),
                 };
             }
+            return result;
         }
         catch (err) {
-            result = {
+            return {
                 status: "failed",
                 reason: err instanceof Error ? err.message : String(err),
             };
         }
-        state.running = false;
-        // If the activity was removed while the handler was running, bail out quietly.
-        if (this.#states.get(activityId) !== state) {
+    }
+    async #flushWake(state, params) {
+        if (!this.#isCurrentState(state)) {
             return;
         }
-        if (result.status === "failed") {
-            this.#queuePendingWakeReason(state, reason ?? "retry");
-            this.#schedule(state, this.#retryMs, "retry");
+        const activeTimer = state.wakeTimer;
+        if (!activeTimer || activeTimer.token !== params.timerToken) {
+            return;
+        }
+        this.#clearWakeTimer(state);
+        state.scheduled = false;
+        if (state.running) {
+            state.scheduled = true;
+            this.#scheduleWake(state, params.delay, params.kind);
+            return;
+        }
+        const reason = state.pendingWake?.reason;
+        state.pendingWake = null;
+        state.running = true;
+        const result = await this.#invokeHandler(state, reason ?? undefined);
+        state.running = false;
+        if (!this.#isCurrentState(state)) {
+            return;
         }
-        else if (result.status === "skipped" && result.reason === "requests-in-flight") {
+        if (shouldRetry(result)) {
             this.#queuePendingWakeReason(state, reason ?? "retry");
-            this.#schedule(state, this.#retryMs, "retry");
+            this.#scheduleWake(state, this.#retryMs, "retry");
         }
         if (state.pendingWake || state.scheduled) {
-            this.#schedule(state, state.coalesceMs, "normal");
+            this.#scheduleWake(state, state.coalesceMs, "normal");
         }
     }
     register(opts) {
@@ -174,9 +215,10 @@ export class ActivityHeartbeatScheduler {
             this.#disposeState(existing);
             this.#states.delete(activityId);
         }
+        const hasInterval = Number.isFinite(opts.everyMs) && Math.trunc(opts.everyMs) > 0;
         const state = {
             activityId,
-            everyMs: toMs(opts.everyMs, this.#minIntervalMs, this.#minIntervalMs),
+            everyMs: hasInterval ? toMs(opts.everyMs, this.#minIntervalMs, this.#minIntervalMs) : 0,
             coalesceMs: Math.max(0, Math.trunc(opts.coalesceMs ?? this.#defaultCoalesceMs)),
             handler: opts.handler,
             pendingWake: null,
@@ -184,13 +226,14 @@ export class ActivityHeartbeatScheduler {
             running: false,
             intervalTimer: null,
             wakeTimer: null,
-            wakeDueAt: null,
-            wakeKind: null,
+            disposed: false,
         };
-        state.intervalTimer = setInterval(() => {
-            this.requestNow(activityId, { reason: "interval", coalesceMs: 0 });
-        }, state.everyMs);
-        state.intervalTimer.unref?.();
+        if (state.everyMs > 0) {
+            state.intervalTimer = setInterval(() => {
+                this.requestNow(activityId, { reason: "interval", coalesceMs: 0 });
+            }, state.everyMs);
+            state.intervalTimer.unref?.();
+        }
         this.#states.set(activityId, state);
     }
     requestNow(activityIdRaw, opts) {
@@ -203,7 +246,7 @@ export class ActivityHeartbeatScheduler {
             return false;
         }
         this.#queuePendingWakeReason(state, opts?.reason);
-        this.#schedule(state, opts?.coalesceMs ?? state.coalesceMs, "normal");
+        this.#scheduleWake(state, opts?.coalesceMs ?? state.coalesceMs, "normal");
         return true;
     }
     unregister(activityIdRaw) {

package/dist/index.d.ts

@@ -1,12 +1,18 @@
-export type { MuConfig, MuConfigPatch, MuConfigPresence } from "./config.js";
-export { applyMuConfigPatch, DEFAULT_MU_CONFIG, getMuConfigPath, muConfigPresence, normalizeMuConfig, readMuConfigFile, redactMuConfigSecrets, writeMuConfigFile, } from "./config.js";
 export type { ControlPlaneActivityEvent, ControlPlaneActivityEventKind, ControlPlaneActivityMutationResult, ControlPlaneActivitySnapshot, ControlPlaneActivityStatus, ControlPlaneActivitySupervisorOpts, } from "./activity_supervisor.js";
 export { ControlPlaneActivitySupervisor } from "./activity_supervisor.js";
-export type { HeartbeatProgramOperationResult, HeartbeatProgramRegistryOpts, HeartbeatProgramSnapshot, HeartbeatProgramTarget, HeartbeatProgramTickEvent, } from "./heartbeat_programs.js";
-export { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
+export type { MuConfig, MuConfigPatch, MuConfigPresence } from "./config.js";
+export { applyMuConfigPatch, DEFAULT_MU_CONFIG, getMuConfigPath, muConfigPresence, normalizeMuConfig, readMuConfigFile, redactMuConfigSecrets, writeMuConfigFile, } from "./config.js";
 export type { ActiveAdapter, ControlPlaneConfig, ControlPlaneHandle } from "./control_plane.js";
 export { bootstrapControlPlane, detectAdapters } from "./control_plane.js";
-export type { HeartbeatRunResult, HeartbeatTickHandler, ActivityHeartbeatSchedulerOpts } from "./heartbeat_scheduler.js";
+export type { CronProgramLifecycleAction, CronProgramLifecycleEvent, CronProgramOperationResult, CronProgramRegistryOpts, CronProgramSnapshot, CronProgramStatusSnapshot, CronProgramTarget, CronProgramTickEvent, CronProgramWakeMode, } from "./cron_programs.js";
+export { CronProgramRegistry } from "./cron_programs.js";
+export type { CronProgramSchedule as CronSchedule, CronProgramSchedule } from "./cron_schedule.js";
+export { computeNextScheduleRunAtMs, normalizeCronSchedule } from "./cron_schedule.js";
+export type { CronTimerRegistryOpts, CronTimerSnapshot } from "./cron_timer.js";
+export { CronTimerRegistry } from "./cron_timer.js";
+export type { HeartbeatProgramOperationResult, HeartbeatProgramRegistryOpts, HeartbeatProgramSnapshot, HeartbeatProgramTarget, HeartbeatProgramTickEvent, HeartbeatProgramWakeMode, } from "./heartbeat_programs.js";
+export { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
+export type { ActivityHeartbeatSchedulerOpts, HeartbeatRunResult, HeartbeatTickHandler, } from "./heartbeat_scheduler.js";
 export { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
 export type { ServerContext, ServerOptions, ServerWithControlPlane } from "./server.js";
 export { createContext, createServer, createServerAsync } from "./server.js";

package/dist/index.js

@@ -1,6 +1,9 @@
-export { applyMuConfigPatch, DEFAULT_MU_CONFIG, getMuConfigPath, muConfigPresence, normalizeMuConfig, readMuConfigFile, redactMuConfigSecrets, writeMuConfigFile, } from "./config.js";
 export { ControlPlaneActivitySupervisor } from "./activity_supervisor.js";
-export { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
+export { applyMuConfigPatch, DEFAULT_MU_CONFIG, getMuConfigPath, muConfigPresence, normalizeMuConfig, readMuConfigFile, redactMuConfigSecrets, writeMuConfigFile, } from "./config.js";
 export { bootstrapControlPlane, detectAdapters } from "./control_plane.js";
+export { CronProgramRegistry } from "./cron_programs.js";
+export { computeNextScheduleRunAtMs, normalizeCronSchedule } from "./cron_schedule.js";
+export { CronTimerRegistry } from "./cron_timer.js";
+export { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
 export { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
 export { createContext, createServer, createServerAsync } from "./server.js";

package/dist/run_supervisor.d.ts

@@ -2,6 +2,7 @@ import type { CommandRecord } from "@femtomc/mu-control-plane";
 import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
 export type ControlPlaneRunMode = "run_start" | "run_resume";
 export type ControlPlaneRunStatus = "running" | "completed" | "failed" | "cancelled";
+export type ControlPlaneRunWakeMode = "immediate" | "next_heartbeat";
 export type ControlPlaneRunSnapshot = {
     job_id: string;
     mode: ControlPlaneRunMode;
@@ -95,6 +96,7 @@ export declare class ControlPlaneRunSupervisor {
         jobId?: string | null;
         rootIssueId?: string | null;
         reason?: string | null;
+        wakeMode?: string | null;
     }): ControlPlaneRunHeartbeatResult;
     startFromCommand(command: CommandRecord): Promise<ControlPlaneRunSnapshot | null>;
     stop(): Promise<void>;

package/dist/run_supervisor.js

@@ -45,6 +45,13 @@ function normalizeIssueId(value) {
     }
     return trimmed.toLowerCase();
 }
+function normalizeWakeMode(value) {
+    if (typeof value !== "string") {
+        return "immediate";
+    }
+    const normalized = value.trim().toLowerCase().replaceAll("-", "_");
+    return normalized === "next_heartbeat" ? "next_heartbeat" : "immediate";
+}
 function pushBounded(lines, line, maxLines) {
     lines.push(line);
     if (lines.length <= maxLines) {
@@ -232,6 +239,7 @@ export class ControlPlaneRunSupervisor {
             stderr_lines: [],
             log_hints: new Set(),
             interrupt_requested: false,
+            next_heartbeat_reason: null,
             hard_kill_timer: null,
         };
         this.#jobsById.set(snapshot.job_id, job);
@@ -242,14 +250,22 @@ export class ControlPlaneRunSupervisor {
         this.#heartbeatScheduler.register({
             activityId: snapshot.job_id,
             everyMs: this.#heartbeatIntervalMs,
-            handler: async () => {
+            handler: async ({ reason }) => {
                 if (job.snapshot.status !== "running") {
                     return { status: "skipped", reason: "not_running" };
                 }
+                const normalizedReason = reason?.trim();
+                const heartbeatReason = normalizedReason && normalizedReason.length > 0 && normalizedReason !== "interval"
+                    ? normalizedReason
+                    : job.next_heartbeat_reason;
+                if (heartbeatReason) {
+                    job.next_heartbeat_reason = null;
+                }
                 const elapsedSec = Math.max(0, Math.trunc((this.#nowMs() - job.snapshot.started_at_ms) / 1_000));
                 const root = job.snapshot.root_issue_id ?? job.snapshot.job_id;
                 const progress = job.snapshot.last_progress ? ` · ${job.snapshot.last_progress}` : "";
-                this.#emit("run_heartbeat", job, `⏱ ${root} running for ${elapsedSec}s${progress}`);
+                const reasonSuffix = heartbeatReason ? ` · wake=${heartbeatReason}` : "";
+                this.#emit("run_heartbeat", job, `⏱ ${root} running for ${elapsedSec}s${progress}${reasonSuffix}`);
                 return { status: "ran" };
             },
         });
@@ -288,7 +304,7 @@ export class ControlPlaneRunSupervisor {
             throw new Error("run_start_prompt_required");
         }
         const maxSteps = toPositiveInt(opts.maxSteps, DEFAULT_MAX_STEPS);
-        const argv = ["mu", "run", prompt, "--max-steps", String(maxSteps), "--raw-stream"];
+        const argv = ["mu", "_run-direct", prompt, "--max-steps", String(maxSteps), "--raw-stream"];
         return await this.#launch({
             mode: "run_start",
             prompt,
@@ -424,6 +440,15 @@ export class ControlPlaneRunSupervisor {
             return { ok: false, reason: "not_running", run: this.#snapshot(job) };
         }
         const reason = opts.reason?.trim() || "manual";
+        const wakeMode = normalizeWakeMode(opts.wakeMode);
+        if (wakeMode === "next_heartbeat") {
+            job.next_heartbeat_reason = reason;
+            this.#touch(job);
+            return { ok: true, reason: null, run: this.#snapshot(job) };
+        }
+        if (reason !== "interval") {
+            job.next_heartbeat_reason = null;
+        }
         this.#heartbeatScheduler.requestNow(job.snapshot.job_id, {
             reason,
             coalesceMs: 0,

package/dist/server.d.ts

@@ -6,6 +6,7 @@ import { IssueStore } from "@femtomc/mu-issue";
 import { ControlPlaneActivitySupervisor } from "./activity_supervisor.js";
 import { type MuConfig } from "./config.js";
 import { type ControlPlaneConfig, type ControlPlaneHandle } from "./control_plane.js";
+import { CronProgramRegistry } from "./cron_programs.js";
 import { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
 import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
 type ControlPlaneReloader = (opts: {
@@ -24,6 +25,8 @@ export type ServerOptions = {
     activitySupervisor?: ControlPlaneActivitySupervisor;
     controlPlaneReloader?: ControlPlaneReloader;
     generationTelemetry?: GenerationTelemetryRecorder;
+    operatorWakeCoalesceMs?: number;
+    autoRunHeartbeatEveryMs?: number;
     config?: MuConfig;
     configReader?: ConfigReader;
     configWriter?: ConfigWriter;
@@ -43,6 +46,7 @@ export declare function createServer(options?: ServerOptions): {
     controlPlane: ControlPlaneHandle;
     activitySupervisor: ControlPlaneActivitySupervisor;
     heartbeatPrograms: HeartbeatProgramRegistry;
+    cronPrograms: CronProgramRegistry;
 };
 export type ServerWithControlPlane = {
     serverConfig: ReturnType<typeof createServer>;