@jl1990/pi-scheduler 0.2.4 → 0.3.1

package/README.md

@@ -223,7 +223,19 @@ Pi Scheduler currently uses **in-process timers**:
 
 - If Pi is running, tasks fire at the scheduled time.
 - If Pi is closed, tasks do not fire while Pi is closed.
-- Pending/missed tasks are loaded again when the relevant Pi session starts, and due tasks fire then.
+- Overdue one-shot and interval tasks fire when the relevant Pi session starts again.
+- For each overdue cron task, Pi Scheduler catches up its most recent missed occurrence when that occurrence is inside the configured catch-up window. Catch-up is newest-first and bounded per startup.
+
+Cron catch-up can be configured with environment variables:
+
+| Variable | Default | Description |
+| --- | ---: | --- |
+| `PI_SCHEDULER_CATCHUP_WINDOW_H` | `24` | Maximum age, in hours, of the most recent missed cron occurrence. |
+| `PI_SCHEDULER_CATCHUP_MAX` | `5` | Maximum number of missed cron tasks fired per session start. Set to `0` to disable cron catch-up. |
+
+Invalid, negative, or non-finite values fall back to the defaults; `PI_SCHEDULER_CATCHUP_MAX` must also be a whole number. If Pi stopped while a task was already running, the interrupted attempt is recorded as failed rather than retried blindly: one-shot tasks remain failed, while recurring tasks are rescheduled from startup time.
+
+Task state is shared but not cross-process locked. Running multiple Pi processes against the same `cwd` or `global` tasks can race, so use those scopes from one active Pi process at a time.
 
 This is enough for live agent workflows like CI polling while a Pi session is open. A future version could add OS-level `cron`, `at`, launchd, systemd, or a small daemon for exact wakeups while Pi is not running.
 

package/extensions/scheduler/index.ts

@@ -2,6 +2,7 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Cron } from "croner";
+import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -9,6 +10,7 @@ import { Type } from "typebox";
 
 // Keep the scheduler logic testable from plain node --test.
 const core = require("./scheduler-core.cjs");
+const lifecycle = require("./scheduler-lifecycle.cjs");
 
 const ACTIONS = ["notify", "prompt", "shell", "message"] as const;
 const TYPES = ["once", "interval", "cron"] as const;
@@ -40,12 +42,19 @@ function currentSessionFile(ctx: ExtensionContext): string | undefined {
 }
 
 function taskBelongsToSession(task: ScheduledTask, ctx: ExtensionContext): boolean {
-	const scope = task.scope ?? "session";
-	if (scope === "global") return true;
-	if (scope === "cwd") return !task.cwd || task.cwd === ctx.cwd;
+	return core.taskMatchesScope(task, { cwd: ctx.cwd, sessionFile: currentSessionFile(ctx) });
+}
 
-	const sessionFile = currentSessionFile(ctx);
-	return !task.sessionFile || !sessionFile || task.sessionFile === sessionFile;
+function isRunOwnerActive(owner: Record<string, any> | undefined): boolean {
+	const pid = Number(owner?.pid);
+	if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+	if (pid === process.pid) return true;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error: any) {
+		return error?.code === "EPERM";
+	}
 }
 
 function sendAgentPrompt(pi: ExtensionAPI, ctx: ExtensionContext, prompt: string): void {
@@ -109,10 +118,15 @@ export default function schedulerExtension(pi: ExtensionAPI) {
 	let tasks: ScheduledTask[] = [];
 	let handles = new Map<string, TimerHandle>();
 	let activeCtx: ExtensionContext | undefined;
+	let sessionGeneration = 0;
 	let saveQueue: Promise<void> = Promise.resolve();
 	let widgetEnabled = true;
 	const firing = new Set<string>();
 
+	function isSessionActive(ctx: ExtensionContext, generation = sessionGeneration): boolean {
+		return lifecycle.isSessionContextActive(activeCtx, ctx, sessionGeneration, generation);
+	}
+
 	async function loadTasks(): Promise<void> {
 		try {
 			const raw = await readFile(STATE_FILE, "utf8");
@@ -186,7 +200,8 @@ export default function schedulerExtension(pi: ExtensionAPI) {
 		updateWidget(ctx);
 	}
 
-	function scheduleTaskHandle(task: ScheduledTask, ctx: ExtensionContext): void {
+	function scheduleTaskHandle(task: ScheduledTask, ctx: ExtensionContext, generation = sessionGeneration): void {
+		if (!isSessionActive(ctx, generation)) return;
 		if (task.enabled === false || task.status !== "pending") return;
 		if (!taskBelongsToSession(task, ctx)) return;
 		clearHandle(task.id);
@@ -194,7 +209,7 @@ export default function schedulerExtension(pi: ExtensionAPI) {
 		if (task.type === "cron") {
 			try {
 				const cron = new Cron(task.schedule, () => {
-					void fireTask(task.id, ctx);
+					void fireTask(task.id, ctx, generation);
 				});
 				handles.set(task.id, { kind: "cron", handle: cron });
 			} catch (error: any) {
@@ -214,22 +229,48 @@ export default function schedulerExtension(pi: ExtensionAPI) {
 
 		const timer = setTimeout(() => {
 			handles.delete(task.id);
+			if (!isSessionActive(ctx, generation)) return;
 			if (Date.now() < dueAt) {
-				scheduleTaskHandle(task, ctx);
+				scheduleTaskHandle(task, ctx, generation);
 				return;
 			}
-			void fireTask(task.id, ctx);
+			void fireTask(task.id, ctx, generation);
 		}, timerDelay);
 		handles.set(task.id, { kind: "timeout", handle: timer });
 	}
 
-	function rescheduleAll(ctx = activeCtx): void {
-		if (!ctx) return;
+	function rescheduleAll(ctx = activeCtx, generation = sessionGeneration): void {
+		if (!ctx || !isSessionActive(ctx, generation)) return;
 		clearTimers();
-		for (const task of core.pendingTasks(tasks)) scheduleTaskHandle(task, ctx);
+		for (const task of core.pendingTasks(tasks)) scheduleTaskHandle(task, ctx, generation);
 		updateStatus(ctx);
 	}
 
+	async function catchUpOverdueCronTasks(
+		ctx: ExtensionContext,
+		generation: number,
+		options: { windowHours: number; maxFire: number },
+	): Promise<void> {
+		const overdue = core.selectCatchUpCronTasks(visibleTasks(ctx), new Date(), options);
+		if (overdue.length === 0 || !isSessionActive(ctx, generation)) return;
+
+		if (ctx.hasUI) {
+			ctx.ui.notify(
+				`Catching up ${overdue.length} missed cron task(s) (window ${options.windowHours}h, limit ${options.maxFire})`,
+				"info",
+			);
+		}
+
+		for (const { task, missedAt } of overdue) {
+			if (!isSessionActive(ctx, generation)) return;
+			// Record the most recent missed occurrence so prompts and persisted state
+			// describe the run being caught up, not the first occurrence missed.
+			task.nextRun = missedAt.toISOString();
+			task.dueAt = task.nextRun;
+			await fireTask(task.id, ctx, generation);
+		}
+	}
+
 	function recordMessage(content: string, details?: Record<string, any>, triggerTurn = false): void {
 		pi.sendMessage(
 			{
@@ -242,7 +283,11 @@ export default function schedulerExtension(pi: ExtensionAPI) {
 		);
 	}
 
-	async function executeTask(task: ScheduledTask, ctx: ExtensionContext): Promise<Record<string, any>> {
+	async function executeTask(
+		task: ScheduledTask,
+		ctx: ExtensionContext,
+		isActive: () => boolean,
+	): Promise<Record<string, any>> {
 		if (task.action === "notify") {
 			const message = task.message ?? "Scheduled reminder";
 			if (ctx.hasUI) ctx.ui.notify(message, "info");
@@ -279,6 +324,8 @@ export default function schedulerExtension(pi: ExtensionAPI) {
 				stderr: truncateMiddle(result.stderr ?? "", MAX_STORED_OUTPUT_CHARS),
 			};
 
+			if (!isActive()) return { ...shellResult, outputSuppressed: true };
+
 			recordMessage(
 				`🖥️ Scheduled command ${task.id} finished with exit code ${result.code}: ${task.command}`,
 				{ task, result: shellResult },
@@ -296,40 +343,67 @@ export default function schedulerExtension(pi: ExtensionAPI) {
 		throw new Error(`Unsupported scheduled action: ${task.action}`);
 	}
 
-	async function fireTask(taskId: string, ctx: ExtensionContext): Promise<void> {
+	async function fireTask(taskId: string, ctx: ExtensionContext, generation = sessionGeneration): Promise<void> {
+		if (!isSessionActive(ctx, generation)) return;
 		const task = tasks.find((candidate) => candidate.id === taskId);
 		if (!task || task.enabled === false || task.status !== "pending" || firing.has(task.id)) return;
 		if (!taskBelongsToSession(task, ctx)) return;
 
 		firing.add(task.id);
+		const attemptId = randomUUID();
 		try {
-			core.markScheduledTaskRunning(tasks, task.id, new Date());
+			core.markScheduledTaskRunning(tasks, task.id, new Date(), {
+				runOwner: { pid: process.pid, attemptId, sessionFile: currentSessionFile(ctx) },
+			});
 			await saveTasks();
+			if (!isSessionActive(ctx, generation)) {
+				const currentTask = tasks.find((candidate) => candidate.id === task.id);
+				if (currentTask?.runOwner?.attemptId === attemptId) {
+					currentTask.status = "pending";
+					currentTask.lastStatus = "error";
+					currentTask.lastError = "Scheduled task start was cancelled because the Pi session changed";
+					delete currentTask.runOwner;
+					delete currentTask.startedAt;
+					await saveTasks();
+				}
+				return;
+			}
 			updateStatus(ctx);
-			const result = await executeTask(task, ctx);
-			core.markScheduledTaskCompleted(tasks, task.id, new Date(), result, { ok: result.ok !== false });
+			const result = await executeTask(task, ctx, () => isSessionActive(ctx, generation));
+			const currentTask = tasks.find((candidate) => candidate.id === task.id);
+			if (currentTask?.runOwner?.attemptId !== attemptId) return;
+			core.markScheduledTaskCompleted(tasks, currentTask.id, new Date(), result, { ok: result.ok !== false });
 			await saveTasks();
 		} catch (error: any) {
-			core.markScheduledTaskFailed(tasks, task.id, new Date(), error);
+			const currentTask = tasks.find((candidate) => candidate.id === task.id);
+			if (currentTask?.runOwner?.attemptId !== attemptId) return;
+			core.markScheduledTaskFailed(tasks, currentTask.id, new Date(), error);
 			await saveTasks();
-			const message = `Scheduled task ${task.id} failed: ${error?.message ?? String(error)}`;
-			if (ctx.hasUI) ctx.ui.notify(message, "error");
-			recordMessage(`⚠️ ${message}`, { task, error: error?.message ?? String(error) }, false);
+			if (isSessionActive(ctx, generation)) {
+				const message = `Scheduled task ${currentTask.id} failed: ${error?.message ?? String(error)}`;
+				if (ctx.hasUI) ctx.ui.notify(message, "error");
+				recordMessage(`⚠️ ${message}`, { task: currentTask, error: error?.message ?? String(error) }, false);
+			}
 		} finally {
 			firing.delete(task.id);
-			rescheduleAll(ctx);
+			if (isSessionActive(ctx, generation)) rescheduleAll(ctx, generation);
+			else if (activeCtx) rescheduleAll(activeCtx, sessionGeneration);
 		}
 	}
 
 	async function createAndSchedule(input: Record<string, any>, ctx: ExtensionContext): Promise<ScheduledTask> {
 		const scope = input.scope ?? "session";
+		const sessionFile = scope === "session" ? currentSessionFile(ctx) : undefined;
+		if (scope === "session" && !sessionFile) {
+			throw new Error("Session-scoped tasks require a persisted Pi session; use scope 'cwd' or 'global' instead");
+		}
 		const task = core.createScheduledTask(
 			{
 				...input,
 				schedule: input.schedule ?? input.when ?? input.whenText,
 				cwd: input.cwd ?? ctx.cwd,
 				scope,
-				sessionFile: scope === "session" ? currentSessionFile(ctx) : undefined,
+				sessionFile,
 			},
 			new Date(),
 		);
@@ -385,11 +459,34 @@ export default function schedulerExtension(pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		activeCtx = ctx;
+		const generation = ++sessionGeneration;
 		await loadTasks();
-		rescheduleAll(ctx);
+		if (!isSessionActive(ctx, generation)) return;
+
+		const interrupted = core.recoverInterruptedTasks(tasks, new Date(), { isOwnerActive: isRunOwnerActive });
+		if (interrupted.length > 0) {
+			await saveTasks();
+			if (!isSessionActive(ctx, generation)) return;
+			if (ctx.hasUI) {
+				ctx.ui.notify(
+					`Recovered ${interrupted.length} task(s) interrupted before completion; recurring tasks were rescheduled`,
+					"warning",
+				);
+			}
+		}
+
+		rescheduleAll(ctx, generation);
+		const catchUpOptions = core.parseCatchUpOptions(process.env);
+		void catchUpOverdueCronTasks(ctx, generation, catchUpOptions).catch((error: any) => {
+			if (isSessionActive(ctx, generation) && ctx.hasUI) {
+				ctx.ui.notify(`Failed to catch up missed cron tasks: ${error?.message ?? String(error)}`, "error");
+			}
+		});
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
+		if (!isSessionActive(ctx)) return;
+		++sessionGeneration;
 		clearTimers();
 		if (ctx.hasUI) {
 			ctx.ui.setStatus("scheduler", undefined);
@@ -689,9 +786,17 @@ export default function schedulerExtension(pi: ExtensionAPI) {
 				task = core.removeScheduledTask(tasks, visibleRemoved.id);
 				clearHandle(task.id);
 			} else {
-				const updates = { ...params };
+				const updates: Record<string, any> = { ...params };
 				delete updates.action;
 				delete updates.id;
+				if (updates.scope === "session") {
+					updates.sessionFile = currentSessionFile(ctx);
+					if (!updates.sessionFile) {
+						throw new Error("Session-scoped tasks require a persisted Pi session");
+					}
+				} else if (updates.scope !== undefined) {
+					updates.sessionFile = null;
+				}
 				task = core.updateScheduledTask(visibleTasks(ctx), params.id, updates, new Date());
 			}
 

package/extensions/scheduler/scheduler-core.cjs

@@ -29,6 +29,8 @@ const MINUTE = 60 * SECOND;
 const HOUR = 60 * MINUTE;
 const DAY = 24 * HOUR;
 const WEEK = 7 * DAY;
+const DEFAULT_CATCHUP_WINDOW_HOURS = 24;
+const DEFAULT_CATCHUP_MAX_FIRE = 5;
 
 function asDate(value) {
 	const date = value instanceof Date ? new Date(value.getTime()) : new Date(value);
@@ -397,7 +399,7 @@ function normalizeTask(task, nowValue = new Date()) {
 	const migrated = { ...task, action, type, schedule, status };
 	migrated.enabled = task.enabled === undefined ? !isTerminal(migrated) : Boolean(task.enabled);
 	migrated.runCount = Number.isInteger(task.runCount) && task.runCount >= 0 ? task.runCount : 0;
-	migrated.scope = VALID_SCOPES.has(task.scope) ? task.scope : "session";
+	migrated.scope = VALID_SCOPES.has(task.scope) ? task.scope : task.sessionFile ? "session" : task.cwd ? "cwd" : "global";
 	migrated.whenText = compactSpaces(task.whenText ?? task.when ?? schedule);
 	migrated.createdAt = Number.isNaN(Date.parse(task.createdAt)) ? asDate(nowValue).toISOString() : task.createdAt;
 	if (task.maxRuns !== undefined) migrated.maxRuns = normalizeMaxRuns(task.maxRuns);
@@ -449,6 +451,13 @@ function sortByNextRun(a, b) {
 	return (Number.isFinite(aTime) ? aTime : Number.POSITIVE_INFINITY) - (Number.isFinite(bTime) ? bTime : Number.POSITIVE_INFINITY);
 }
 
+function taskMatchesScope(task, context = {}) {
+	const scope = task.scope ?? "session";
+	if (scope === "global") return true;
+	if (scope === "cwd") return Boolean(task.cwd && context.cwd && task.cwd === context.cwd);
+	return Boolean(task.sessionFile && context.sessionFile && task.sessionFile === context.sessionFile);
+}
+
 function pendingTasks(tasks) {
 	return tasks
 		.filter((task) => task.enabled !== false && !isTerminal(task))
@@ -461,6 +470,56 @@ function dueTasks(tasks, nowValue = new Date()) {
 	return pendingTasks(tasks).filter((task) => task.status === "pending" && Date.parse(task.nextRun ?? task.dueAt) <= now);
 }
 
+function parseCatchUpOptions(env = {}) {
+	const rawWindow = typeof env.PI_SCHEDULER_CATCHUP_WINDOW_H === "string"
+		? env.PI_SCHEDULER_CATCHUP_WINDOW_H.trim()
+		: env.PI_SCHEDULER_CATCHUP_WINDOW_H;
+	const parsedWindow = rawWindow === undefined || rawWindow === "" ? Number.NaN : Number(rawWindow);
+	const windowHours = Number.isFinite(parsedWindow) && parsedWindow >= 0 && Number.isFinite(parsedWindow * HOUR)
+		? parsedWindow
+		: DEFAULT_CATCHUP_WINDOW_HOURS;
+
+	const rawMax = typeof env.PI_SCHEDULER_CATCHUP_MAX === "string"
+		? env.PI_SCHEDULER_CATCHUP_MAX.trim()
+		: env.PI_SCHEDULER_CATCHUP_MAX;
+	const parsedMax = rawMax === undefined || rawMax === "" ? Number.NaN : Number(rawMax);
+	const maxFire = Number.isSafeInteger(parsedMax) && parsedMax >= 0 ? parsedMax : DEFAULT_CATCHUP_MAX_FIRE;
+	return { windowHours, maxFire };
+}
+
+function latestMissedCronRun(task, now) {
+	const persistedNext = Date.parse(task.nextRun ?? task.dueAt ?? "");
+	if (!Number.isFinite(persistedNext) || persistedNext > now.getTime()) return undefined;
+
+	let cron;
+	try {
+		cron = new Cron(task.schedule, { paused: true }, () => {});
+		const [latest] = cron.previousRuns(1, now);
+		if (latest && latest.getTime() >= persistedNext && latest.getTime() <= now.getTime()) return latest;
+	} catch {
+		return undefined;
+	} finally {
+		cron?.stop();
+	}
+	return new Date(persistedNext);
+}
+
+function selectCatchUpCronTasks(tasks, nowValue = new Date(), options = {}) {
+	const now = asDate(nowValue);
+	const windowHours = Number(options.windowHours);
+	const maxFire = Number(options.maxFire);
+	if (!Number.isFinite(windowHours) || windowHours < 0 || !Number.isSafeInteger(maxFire) || maxFire <= 0) return [];
+	const windowMs = windowHours * HOUR;
+	if (!Number.isFinite(windowMs)) return [];
+
+	return tasks
+		.filter((task) => task.type === "cron" && task.enabled !== false && task.status === "pending")
+		.map((task) => ({ task, missedAt: latestMissedCronRun(task, now) }))
+		.filter((entry) => entry.missedAt && now.getTime() - entry.missedAt.getTime() <= windowMs)
+		.sort((a, b) => b.missedAt.getTime() - a.missedAt.getTime())
+		.slice(0, maxFire);
+}
+
 function findTask(tasks, idOrPrefix) {
 	const id = compactSpaces(idOrPrefix);
 	return tasks.find((task) => task.id === id || task.id.startsWith(id));
@@ -524,7 +583,8 @@ function updateScheduledTask(tasks, idOrPrefix, updates = {}, nowValue = new Dat
 	if (updates.description !== undefined) task.description = compactSpaces(updates.description);
 	if (updates.maxRuns !== undefined) task.maxRuns = normalizeMaxRuns(updates.maxRuns);
 	if (updates.cwd !== undefined) task.cwd = String(updates.cwd);
-	if (updates.sessionFile !== undefined) task.sessionFile = String(updates.sessionFile);
+	if (updates.sessionFile === null) delete task.sessionFile;
+	else if (updates.sessionFile !== undefined) task.sessionFile = String(updates.sessionFile);
 	if (updates.timeoutMs !== undefined) task.timeoutMs = validateTimeoutMs(updates.timeoutMs);
 	if (updates.followUpPrompt !== undefined) task.followUpPrompt = compactSpaces(updates.followUpPrompt) || undefined;
 	if (updates.successPrompt !== undefined) task.successPrompt = compactSpaces(updates.successPrompt) || undefined;
@@ -555,7 +615,7 @@ function updateScheduledTask(tasks, idOrPrefix, updates = {}, nowValue = new Dat
 	return task;
 }
 
-function markScheduledTaskRunning(tasks, idOrPrefix, nowValue = new Date()) {
+function markScheduledTaskRunning(tasks, idOrPrefix, nowValue = new Date(), options = {}) {
 	const now = asDate(nowValue);
 	const task = findTask(tasks, idOrPrefix);
 	if (!task) throw new Error(`Scheduled task not found: ${idOrPrefix}`);
@@ -563,10 +623,12 @@ function markScheduledTaskRunning(tasks, idOrPrefix, nowValue = new Date()) {
 	task.status = "running";
 	task.lastStatus = "running";
 	task.startedAt = now.toISOString();
+	if (options.runOwner) task.runOwner = { ...options.runOwner, startedAt: now.toISOString() };
 	return task;
 }
 
 function finishTaskAfterRun(task, now, ok, result) {
+	delete task.runOwner;
 	task.runCount = (Number.isInteger(task.runCount) ? task.runCount : 0) + 1;
 	task.lastRun = now.toISOString();
 	task.lastStatus = ok ? "success" : "error";
@@ -617,6 +679,17 @@ function markScheduledTaskFailed(tasks, idOrPrefix, nowValue = new Date(), error
 	return finishTaskAfterRun(task, asDate(nowValue), false, undefined);
 }
 
+function recoverInterruptedTasks(tasks, nowValue = new Date(), options = {}) {
+	const now = asDate(nowValue);
+	const interrupted = tasks.filter(
+		(task) => task.enabled !== false && task.status === "running" && !options.isOwnerActive?.(task.runOwner),
+	);
+	for (const task of interrupted) {
+		markScheduledTaskFailed(tasks, task.id, now, new Error("Scheduled task was interrupted before completion"));
+	}
+	return interrupted;
+}
+
 function shellResultOk(result) {
 	if (typeof result?.ok === "boolean") return result.ok;
 	if (typeof result?.code === "number") return result.code === 0 && result.killed !== true;
@@ -731,8 +804,12 @@ module.exports = {
 	createScheduledTask,
 	normalizeTask,
 	sanitizeTasks,
+	taskMatchesScope,
 	pendingTasks,
 	dueTasks,
+	parseCatchUpOptions,
+	selectCatchUpCronTasks,
+	recoverInterruptedTasks,
 	cancelScheduledTask,
 	disableScheduledTask,
 	enableScheduledTask,

package/extensions/scheduler/scheduler-lifecycle.cjs

@@ -0,0 +1,16 @@
+"use strict";
+
+function isSessionContextActive(activeCtx, candidateCtx, currentGeneration, expectedGeneration) {
+	if (!activeCtx || currentGeneration !== expectedGeneration) return false;
+	try {
+		// Pi creates distinct context wrappers for events, commands, and tool calls.
+		// Probe both wrappers for staleness instead of comparing object identity.
+		activeCtx.isIdle();
+		candidateCtx.isIdle();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+module.exports = { isSessionContextActive };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jl1990/pi-scheduler",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Give Pi coding agents a clock: schedule reminders, shell commands, and self-waking prompts for CI polling and autonomous follow-ups.",
   "author": "jl1990",
   "license": "MIT",