pi-crew 0.10.6 → 0.11.0

package/src/extension/team-tool/handle-schedule.ts

@@ -1,6 +1,11 @@
 import * as crypto from "node:crypto";
 import { humanizeSchedule, nextRunTime, parseSchedule } from "../../runtime/scheduling/scheduler.ts";
-import { type CrewSettings, updateCrewSettings } from "../../runtime/settings-store.ts";
+import {
+	type CrewSettings,
+	getScheduledJobsHiddenCount as computeScheduledJobsHiddenCount,
+	loadCrewSettingsTiers,
+	updateCrewSettings,
+} from "../../runtime/settings-store.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";
@@ -17,6 +22,8 @@ type SchedulerRef = {
 		id: string,
 		patch: Partial<import("../../runtime/scheduling/scheduler.ts").ScheduledJob>,
 	): import("../../runtime/scheduling/scheduler.ts").ScheduledJob | undefined;
+	/** Trigger a job immediately (force — bypasses the enabled gate). */
+	runNow(jobId: string): { ok: true } | { ok: false; error: string };
 };
 
 // Module-scoped scheduler instance — one per extension load (EXT-9).
@@ -31,9 +38,86 @@ export function registerCrewScheduler(scheduler: SchedulerRef): void {
 	crewSchedulerInstance = scheduler;
 }
 
+// Module-scoped hidden-count stash (P2-1, EXT-9 pattern): computed ONCE at
+// session_start registration from the SAME tiers read that drove registration
+// (no extra disk I/O), then served to paint-path consumers — the crew widget
+// line and the dashboard pane render ticks must never hit the settings store
+// (P0-6). undefined = never stashed (pre-registration / cleaned up / unit
+// tests with a fake scheduler) → consumers treat it as 0.
+let stashedScheduledJobsHiddenCount: number | undefined;
+
+/** @internal — lifecycle wiring: stash the registration-time hidden count. */
+export function stashScheduledJobsHiddenCount(count: number | undefined): void {
+	stashedScheduledJobsHiddenCount = count;
+}
+
+/** @internal — test seam: read the raw stash (undefined = never stashed). */
+export function getStashedScheduledJobsHiddenCount(): number | undefined {
+	return stashedScheduledJobsHiddenCount;
+}
+
 /** Remove the scheduler singleton. Call during session cleanup. */
 export function unregisterCrewScheduler(): void {
 	crewSchedulerInstance = undefined;
+	// P2-1: the hidden-count stash is registration-time state — clear it with
+	// the singleton so a later session can never paint a stale gate hint.
+	stashedScheduledJobsHiddenCount = undefined;
+}
+
+/**
+ * SINGLE SOURCE OF TRUTH for scheduled-job READS (G17). Every consumer —
+ * dashboard pane, /schedules command, crew widget — must read jobs through
+ * this provider; no module may keep its own defaults/settings copy.
+ *
+ * Reads the module-scoped scheduler singleton when registered (the live view
+ * the mutation handlers target); otherwise falls back to the SAME gated tiers
+ * view the session-start registration loop consumes (`effectiveScheduledJobs`:
+ * user-tier jobs always, project-tier only on explicit opt-in) so the fallback
+ * can never disagree with what would register on next session start.
+ */
+export function getScheduledJobs(
+	cwd: string = process.cwd(),
+	globalFile?: string,
+): import("../../runtime/scheduling/scheduler.ts").ScheduledJob[] {
+	const scheduler = getCrewScheduler();
+	if (scheduler) return scheduler.list();
+	try {
+		const tiers = loadCrewSettingsTiers(cwd, globalFile);
+		return tiers.effectiveScheduledJobs.filter(isScheduledJobLike);
+	} catch {
+		return [];
+	}
+}
+
+/** Shape guard for the settings fallback — mirrors settings-store's private
+ * `validateScheduledJob` (id + scheduleType + enabled) so invalid persisted
+ * entries are skipped instead of reaching renderers. */
+function isScheduledJobLike(job: unknown): job is import("../../runtime/scheduling/scheduler.ts").ScheduledJob {
+	if (!job || typeof job !== "object") return false;
+	const obj = job as Record<string, unknown>;
+	return typeof obj.id === "string" && obj.id.length > 0 && typeof obj.scheduleType === "string" && typeof obj.enabled === "boolean";
+}
+
+/**
+ * P2-1 companion read to getScheduledJobs(): how many project-tier
+ * scheduledJobs the B2 gate is hiding right now (for the "N project-tier jobs
+ * hidden" hint).
+ *
+ * With the scheduler singleton registered, serves the REGISTRATION-TIME stash
+ * (in-memory — paint-path safe, P0-6) computed from the exact tiers view the
+ * registration loop gated. Without a scheduler (pre-registration, headless
+ * command usage), computes from the same gated tiers view the provider
+ * fallback uses — user-initiated surfaces only (pane/command); the widget's
+ * default reader never reaches the compute branch because it gates on the
+ * scheduler singleton exactly like defaultScheduledJobsReader.
+ */
+export function getScheduledJobsHiddenCountView(cwd: string = process.cwd(), globalFile?: string): number {
+	if (getCrewScheduler()) return stashedScheduledJobsHiddenCount ?? 0;
+	try {
+		return computeScheduledJobsHiddenCount(cwd, globalFile);
+	} catch {
+		return 0;
+	}
 }
 
 interface ScheduleParams {
@@ -108,6 +192,9 @@ export function handleSchedule(params: TeamToolParamsValue, ctx: TeamContext): P
 	if (subAction === "disable" || subAction === "enable" || subAction === "update") {
 		return handleUpdateScheduled(params, ctx);
 	}
+	if (subAction === "run-now") {
+		return handleRunNowScheduled(params);
+	}
 
 	const team = params.team ?? "default";
 	const goal = params.goal ?? params.task ?? "";
@@ -348,3 +435,35 @@ export function handleUpdateScheduled(params: TeamToolParamsValue, ctx: TeamCont
 		{ action: "schedule", status: "ok", data: { jobId, enabled: updated.enabled, schedule: updated.schedule } },
 	);
 }
+
+/**
+ * Trigger a scheduled job immediately — the UI "run now" channel. Runs even
+ * when the job is disabled (explicit user action); completion tracking stays
+ * on the scheduler's async finalization path.
+ *
+ * Usage:
+ *   team action='schedule' subAction='run-now' jobId='<uuid>'
+ */
+export function handleRunNowScheduled(params: TeamToolParamsValue): PiTeamsToolResult {
+	const jobId = getJobIdParam(params);
+	if (!jobId) {
+		return result(
+			"subAction=run-now requires jobId. Usage: team action='schedule' subAction='run-now' jobId='<uuid>'",
+			{ action: "schedule", status: "error" },
+			true,
+		);
+	}
+	const scheduler = getCrewScheduler();
+	if (!scheduler) {
+		return result("Scheduler not running.", { action: "schedule", status: "error" }, true);
+	}
+	const outcome = scheduler.runNow(jobId);
+	if (!outcome.ok) {
+		return result(outcome.error, { action: "schedule", status: "error" }, true);
+	}
+	return result([`Scheduled job triggered.`, `  Job ID: ${jobId}`].join("\n"), {
+		action: "schedule",
+		status: "ok",
+		data: { jobId, triggered: true },
+	});
+}

package/src/runtime/scheduling/scheduler.ts

@@ -26,6 +26,15 @@ export type ScheduleChangeEvent =
 	| { type: "fired"; jobId: string; agentId: string; name: string }
 	| { type: "error"; jobId: string; error: string };
 
+export interface CrewSchedulerOptions {
+	/** Injectable clock for tests. Defaults to real time (`new Date()`). */
+	now?: () => Date;
+}
+
+/** Node clamps setTimeout delays > 2^31-1 ms to fire ~immediately; longer
+ * waits (e.g. a yearly cron) must be chained in hops below this ceiling. */
+const MAX_TIMER_DELAY_MS = 2_147_483_000;
+
 export class CrewScheduler {
 	private jobs = new Map<string, ScheduledJob>();
 	private timers = new Map<string, ReturnType<typeof setInterval | typeof setTimeout>>();
@@ -33,6 +42,16 @@ export class CrewScheduler {
 	private executor?: (job: ScheduledJob) => string;
 	private finalizer?: (jobId: string, agentId: string) => void;
 	private runCancelFn?: (runId: string) => void;
+	private nowFn: () => Date;
+
+	constructor(options: CrewSchedulerOptions = {}) {
+		this.nowFn = options.now ?? (() => new Date());
+	}
+
+	/** Scheduler clock. Injected in tests; real time in production. */
+	private now(): Date {
+		return this.nowFn();
+	}
 
 	start(options: {
 		emit: (event: ScheduleChangeEvent) => void;
@@ -107,6 +126,29 @@ export class CrewScheduler {
 		this.jobs.set(jobId, { ...job, spawnedRunIds });
 	}
 
+	/**
+	 * Trigger a job immediately (dashboard "run now" / subAction='run-now').
+	 * Bypasses the enabled gate — an explicit user action — but otherwise reuses
+	 * fire()'s exact path: marks lastStatus=running, invokes the SAME executor
+	 * callback, emits fired/error events, and calls the finalizer. Completion
+	 * (runCount/lastRun/lastStatus=persisted success) is handled by the same
+	 * async finalization the timer-driven path uses.
+	 *
+	 * Returns ok:false (no throw) when the job or the executor is missing.
+	 */
+	runNow(jobId: string): { ok: true } | { ok: false; error: string } {
+		const job = this.jobs.get(jobId);
+		if (!job) return { ok: false, error: `No scheduled job with id '${jobId}'.` };
+		if (!this.executor) return { ok: false, error: "Scheduler is not running." };
+		this.fire(jobId, true);
+		// A run-now on a scheduled ONCE job CONSUMES it: the timer-driven path
+		// self-disables after firing (arm()'s setTimeout callback), and without
+		// the same step here the still-armed timer would fire the job a SECOND
+		// time at its scheduled time — a one-shot executing twice.
+		if (job.scheduleType === "once") this.update(jobId, { enabled: false });
+		return { ok: true };
+	}
+
 	private arm(job: ScheduledJob): void {
 		if (this.timers.has(job.id)) return;
 		if (job.scheduleType === "interval" && job.intervalMs) {
@@ -115,7 +157,7 @@ export class CrewScheduler {
 			this.timers.set(job.id, t);
 		} else if (job.scheduleType === "once") {
 			const target = new Date(job.schedule).getTime();
-			const delay = target - Date.now();
+			const delay = target - this.now().getTime();
 			if (delay > 0) {
 				const t = setTimeout(() => {
 					this.fire(job.id);
@@ -131,7 +173,77 @@ export class CrewScheduler {
 					error: `Scheduled time ${job.schedule} is in the past`,
 				});
 			}
+		} else if (job.scheduleType === "cron") {
+			this.armCron(job);
+		}
+	}
+
+	/**
+	 * Arm a cron job: schedule a chained setTimeout at the next occurrence
+	 * (hops are clamped below the 2^31-1 ms setTimeout ceiling so yearly crons
+	 * cannot mis-fire), fire once on arrival, then let the existing
+	 * update() → disarm+arm lifecycle (triggered by fire()'s
+	 * lastStatus='running' update) re-arm the NEXT occurrence. fire() itself
+	 * stays persistence-blind; the post-fire nextRun advance happens in
+	 * advanceCronNextRun and persists via the usual `updated` event flow.
+	 */
+	private armCron(job: ScheduledJob): void {
+		const now = this.now();
+		const next = nextRunTime({ kind: "cron", spec: job.schedule }, now);
+		if (!(next instanceof Date) || next.getTime() <= now.getTime()) {
+			this.disableCronForUncomputableNext(job.id, next);
+			return;
+		}
+		this.setCronTimeout(job.id, next.getTime());
+	}
+
+	/** Chain a clamped timeout hop toward the target cron occurrence. */
+	private setCronTimeout(jobId: string, targetMs: number): void {
+		const delay = Math.max(targetMs - this.now().getTime(), 0);
+		const t = setTimeout(() => this.cronTick(jobId, targetMs), Math.min(delay, MAX_TIMER_DELAY_MS));
+		t.unref();
+		this.timers.set(jobId, t);
+	}
+
+	/** Timer callback for a cron hop/arrival. Fires at most once per occurrence. */
+	private cronTick(jobId: string, targetMs: number): void {
+		const job = this.jobs.get(jobId);
+		if (!job?.enabled) return; // disabled/removed mid-flight: hop must die
+		if (this.now().getTime() < targetMs) {
+			// Clamped hop landed early — chain again for the remaining time.
+			this.setCronTimeout(jobId, targetMs);
+			return;
+		}
+		// Occurrence reached. fire()'s internal update({lastStatus:'running'})
+		// runs disarm→arm, which re-arms the NEXT occurrence exactly once; the
+		// hop that just fired is dead, so no timer doubles up.
+		this.fire(jobId);
+		this.advanceCronNextRun(jobId);
+	}
+
+	/** After a cron fire, advance the persisted nextRun to the next occurrence
+	 * (or self-disable when no further occurrence is computable). */
+	private advanceCronNextRun(jobId: string): void {
+		const job = this.jobs.get(jobId);
+		if (!job?.enabled || job.scheduleType !== "cron") return;
+		const next = nextRunTime({ kind: "cron", spec: job.schedule }, this.now());
+		if (!(next instanceof Date)) {
+			this.disableCronForUncomputableNext(jobId, next);
+			return;
 		}
+		this.update(jobId, { nextRun: next.toISOString() });
+	}
+
+	/** No computable next occurrence (e.g. Feb-29 beyond the 366-day search
+	 * window): disable the job and record why. */
+	private disableCronForUncomputableNext(jobId: string, next: Date | { error: string }): void {
+		const reason = next && typeof next === "object" && "error" in next ? next.error : "next occurrence is not in the future";
+		this.update(jobId, { enabled: false, lastStatus: "error" });
+		this.emit?.({
+			type: "error",
+			jobId,
+			error: `Cron schedule cannot compute a next occurrence (${reason}); job disabled`,
+		});
 	}
 
 	private disarm(id: string): void {
@@ -139,18 +251,20 @@ export class CrewScheduler {
 		if (t) {
 			// Branch on timer type to use correct clear function
 			const job = this.jobs.get(id);
-			if (job?.scheduleType === "once") {
-				clearTimeout(t as ReturnType<typeof setTimeout>);
-			} else {
+			if (job?.scheduleType === "interval") {
 				clearInterval(t as ReturnType<typeof setInterval>);
+			} else {
+				// `once` and `cron` both arm setTimeout handles (cron chains hops).
+				clearTimeout(t as ReturnType<typeof setTimeout>);
 			}
 			this.timers.delete(id);
 		}
 	}
 
-	private fire(id: string): void {
+	private fire(id: string, force = false): void {
 		const job = this.jobs.get(id);
-		if (!job?.enabled || !this.executor) return;
+		if (!job || !this.executor) return;
+		if (!job.enabled && !force) return;
 		this.update(id, { lastStatus: "running" });
 		let agentId: string;
 		try {

package/src/runtime/settings-store.ts

@@ -114,9 +114,9 @@ function readSettingsFile(filePath: string): CrewSettings {
  * fixed P1 bypass (see docs/decisions/2026-08-15-schema-driven-sanitize.md
  * and the Wave 2B execution log in docs/refactor-plan.md).
  */
-export function loadCrewSettings(cwd: string = process.cwd()): CrewSettings {
+export function loadCrewSettings(cwd: string = process.cwd(), globalFile: string = globalPath()): CrewSettings {
 	return {
-		...readSettingsFile(globalPath()),
+		...readSettingsFile(globalFile),
 		...readSettingsFile(projectPath(cwd)),
 	};
 }
@@ -249,6 +249,32 @@ export function loadCrewSettingsTiers(cwd: string = process.cwd(), globalFile: s
 	return { user, project, merged: { ...user, ...project }, effectiveScheduledJobs, projectPath: projectFilePath };
 }
 
+/** P2-1 (B2 gate visibility): how many project-tier scheduledJobs the Wave B2
+ *  opt-in gate is currently hiding, derived from an ALREADY-LOADED tiers view
+ *  (no disk read — the lifecycle session_start stash reuses its single tiers
+ *  read through this helper). Mirrors what `effectiveScheduledJobs` would add
+ *  after opt-in: only shape-valid entries count (the same id + scheduleType +
+ *  enabled predicate the provider fallback and the scheduler apply), so the
+ *  hint never counts junk that would be skipped anyway. 0 whenever the user
+ *  tier opted in (nothing is hidden). */
+export function scheduledJobsHiddenCountOf(tiers: CrewSettingsTiers): number {
+	if (projectScheduledJobsOptIn(tiers.user)) return 0;
+	const jobs = tiers.project.scheduledJobs;
+	if (!Array.isArray(jobs)) return 0;
+	return jobs.filter(validateScheduledJob).length;
+}
+
+/** P2-1 companion getter: how many project-tier scheduledJobs the B2 gate is
+ *  filtering out of `effectiveScheduledJobs` (and therefore out of every
+ *  read surface). `getScheduledJobs()`'s signature is intentionally unchanged
+ *  — consumers that want the hidden count call this next to their existing
+ *  provider read. Reads the tiers (one disk read per call): user-initiated
+ *  surfaces only (pane render/command handlers); paint-path consumers use the
+ *  registration-time stash in handle-schedule.ts (P0-6). */
+export function getScheduledJobsHiddenCount(cwd: string = process.cwd(), globalFile: string = globalPath()): number {
+	return scheduledJobsHiddenCountOf(loadCrewSettingsTiers(cwd, globalFile));
+}
+
 /**
  * Apply crew settings to a config with correct trust tiering. Returns the
  * list of drop warnings (standard project-override format).

package/src/state/coordination/locks.ts

@@ -307,6 +307,21 @@ function releaseLock(filePath: string, token: string): void {
 	// (probably stale and overtaken). Do not touch it — the new holder owns it.
 }
 
+/**
+ * Error codes that mean "the lock file exists / is momentarily un-creatable
+ * because another process holds it" rather than "something is broken".
+ *
+ * EEXIST is the POSIX O_CREAT|O_EXCL loser signal. On Windows (libuv),
+ * CREATE_NEW against a file that another process has open mid-create can
+ * surface as EPERM (ERROR_ACCESS_DENIED) or EBUSY instead of EEXIST —
+ * observed on the windows-latest CI runner (ST-3 cross-process flock test).
+ * Retrying these is correct: the holder always closes/releases within the
+ * stale-deadline budget, and the deadline still bounds the wait.
+ */
+function isLockContention(code: string | undefined): boolean {
+	return code === "EEXIST" || code === "EPERM" || code === "EBUSY";
+}
+
 function acquireLockWithRetry(filePath: string, staleMs: number, kind: LockKind = "file"): string {
 	let attempt = 0;
 	const deadline = Date.now() + staleMs * 2;
@@ -317,7 +332,7 @@ function acquireLockWithRetry(filePath: string, staleMs: number, kind: LockKind
 			return token;
 		} catch (error) {
 			const code = (error as NodeJS.ErrnoException).code;
-			if (code !== "EEXIST") throw error;
+			if (!isLockContention(code)) throw error;
 			if (Date.now() > deadline) {
 				throw new Error(`Run '${path.basename(filePath)}' is locked by another operation.`);
 			}
@@ -355,7 +370,7 @@ async function acquireLockWithRetryAsync(filePath: string, staleMs: number, kind
 			return token;
 		} catch (error) {
 			const code = (error as NodeJS.ErrnoException).code;
-			if (code !== "EEXIST") throw error;
+			if (!isLockContention(code)) throw error;
 			if (Date.now() > deadline) {
 				throw new Error(`Run '${path.basename(filePath)}' is locked by another operation.`);
 			}