feat(cron): enhance one-shot job behavior and CLI options

- Default one-shot jobs to delete after success, improving job management.
- Introduced `--keep-after-run` CLI option to allow users to retain one-shot jobs post-execution.
- Updated documentation to clarify default behaviors and new options for one-shot jobs.
- Adjusted cron job creation logic to ensure consistent handling of delete options.
- Enhanced tests to validate new behaviors and ensure reliability.

This update streamlines the handling of one-shot jobs, providing users with more control over job persistence and execution outcomes.

src/cron/normalize.test.ts

@@ -111,6 +111,22 @@ describe("normalizeCronJobCreate", () => {
     expect(schedule.atMs).toBe(Date.parse("2026-01-12T18:00:00Z"));
   });
 
+  it("defaults deleteAfterRun for one-shot schedules", () => {
+    const normalized = normalizeCronJobCreate({
+      name: "default delete",
+      enabled: true,
+      schedule: { at: "2026-01-12T18:00:00Z" },
+      sessionTarget: "main",
+      wakeMode: "next-heartbeat",
+      payload: {
+        kind: "systemEvent",
+        text: "hi",
+      },
+    }) as unknown as Record<string, unknown>;
+
+    expect(normalized.deleteAfterRun).toBe(true);
+  });
+
   it("normalizes delivery mode and channel", () => {
     const normalized = normalizeCronJobCreate({
       name: "delivery",

src/cron/normalize.ts

@@ -172,6 +172,14 @@ export function normalizeCronJobInput(
         next.sessionTarget = "isolated";
       }
     }
+    if (
+      "schedule" in next &&
+      isRecord(next.schedule) &&
+      next.schedule.kind === "at" &&
+      !("deleteAfterRun" in next)
+    ) {
+      next.deleteAfterRun = true;
+    }
     const hasDelivery = "delivery" in next && next.delivery !== undefined;
     const payload = isRecord(next.payload) ? next.payload : null;
     const payloadKind = payload && typeof payload.kind === "string" ? payload.kind : "";

src/cron/service.runs-one-shot-main-job-disables-it.test.ts

@@ -36,7 +36,7 @@ describe("CronService", () => {
     vi.useRealTimers();
   });
 
-  it("runs a one-shot main job and disables it after success", async () => {
+  it("runs a one-shot main job and disables it after success when requested", async () => {
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
@@ -55,6 +55,7 @@ describe("CronService", () => {
     const job = await cron.add({
       name: "one-shot hello",
       enabled: true,
+      deleteAfterRun: false,
       schedule: { kind: "at", atMs },
       sessionTarget: "main",
       wakeMode: "now",
@@ -79,7 +80,7 @@ describe("CronService", () => {
     await store.cleanup();
   });
 
-  it("runs a one-shot job and deletes it after success when requested", async () => {
+  it("runs a one-shot job and deletes it after success by default", async () => {
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
@@ -98,7 +99,6 @@ describe("CronService", () => {
     const job = await cron.add({
       name: "one-shot delete",
       enabled: true,
-      deleteAfterRun: true,
       schedule: { kind: "at", atMs },
       sessionTarget: "main",
       wakeMode: "now",

src/cron/service/jobs.ts

@@ -97,13 +97,19 @@ export function nextWakeAtMs(state: CronServiceState) {
 export function createJob(state: CronServiceState, input: CronJobCreate): CronJob {
   const now = state.deps.nowMs();
   const id = crypto.randomUUID();
+  const deleteAfterRun =
+    typeof input.deleteAfterRun === "boolean"
+      ? input.deleteAfterRun
+      : input.schedule.kind === "at"
+        ? true
+        : undefined;
   const job: CronJob = {
     id,
     agentId: normalizeOptionalAgentId(input.agentId),
     name: normalizeRequiredName(input.name),
     description: normalizeOptionalText(input.description),
     enabled: input.enabled,
-    deleteAfterRun: input.deleteAfterRun,
+    deleteAfterRun,
     createdAtMs: now,
     updatedAtMs: now,
     schedule: input.schedule,