pi-crew 0.10.6 → 0.11.1

package/src/extension/registration/terminal-status-wiring.ts

@@ -0,0 +1,172 @@
+/**
+ * M3-1 (UI-AUDIT P0-2/P1-1): wire the terminal-status controller (tab title +
+ * Ghostty OSC 9;4 progress) to the runEventBus.
+ *
+ * History: `src/ui/terminal-status.ts` shipped in v0.8.3 (819d71ad) with unit
+ * tests but NO construction site — `ctx.terminalStatus` was never assigned, so
+ * the feature never ran. This module is the missing wire, installed once from
+ * `register.ts` in place of the old no-op cleanup handler.
+ *
+ * Design:
+ *   - Subscribe to `runEventBus.onAny` and debounce evaluation (250ms) so a
+ *     burst of task events collapses into one state transition.
+ *   - State is derived from `listLiveAgents()`: >0 live → active; 0 → idle.
+ *     `ctx.terminalStatusActive` (already in RegistrationContext) is the single
+ *     source of truth for the current phase, so `runtime-cleanup.ts` resetting
+ *     it also resets this state machine on the next event.
+ *   - On the idle transition, `onRunCompleted()` fires the green Ghostty flash
+ *     and `onIdle()` runs COMPLETE_FLASH_MS later (title restore + re-assert
+ *     loop), so the flash is visible before the bar clears.
+ *   - The `TerminalStatusUi` adapter reads `ctx.currentCtx` dynamically (getter
+ *     + call-time lookup), so a session swap never leaves the controller
+ *     holding a stale session's `ui.setTitle` (the P1-10 class of bug).
+ *   - Everything is best-effort and guarded by `hasUI`: headless / subagent
+ *     contexts evaluate to a no-op and write nothing.
+ *   - All timers are `unref()`-ed; dispose unsubscribes, clears timers and
+ *     disposes the controller (registered via `registerCleanupHandler`, which
+ *     replaces the old no-op `disposeTerminalStatus` handler in register.ts).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { listLiveAgents } from "../../runtime/live-session/live-agent-manager.ts";
+import { runEventBus } from "../../ui/run-event-bus.ts";
+import {
+	buildCrewTitleSegment,
+	COMPLETE_FLASH_MS,
+	createTerminalStatusController,
+	setTerminalTitle,
+	type TerminalStatusController,
+	type TerminalStatusUi,
+} from "../../ui/terminal-status.ts";
+import { registerCleanupHandler } from "../crew-cleanup.ts";
+
+/**
+ * Structural subset of RegistrationContext this module needs. Declared
+ * locally (not imported) so tests can pass a 3-field fake without building
+ * the full context, while `register.ts` passes the real context unchanged.
+ */
+export interface TerminalStatusWiringDeps {
+	currentCtx: { hasUI: boolean; ui: { setTitle(title: string): void } } | undefined;
+	terminalStatus: TerminalStatusController | undefined;
+	terminalStatusActive: boolean;
+}
+
+/** Debounce window that collapses an event burst into one evaluation. */
+const EVAL_DEBOUNCE_MS = 250;
+
+/**
+ * Live-agent probe (dependency inversion for tests). Production reads the real
+ * registry; tests inject a deterministic count source.
+ */
+let liveAgentProbe: () => number = () => listLiveAgents().length;
+
+/** @internal Re-subscribe guard: unsubscribe fn from a previous registration. */
+let currentUnsubscribe: (() => void) | undefined;
+/** @internal Latest install's full dispose (unsubscribe + timers + controller). */
+let currentDispose: (() => void) | undefined;
+
+/** Test seam: override the live-agent source (restore with `() => default`). */
+export function __test__setLiveAgentProbe(probe: () => number): void {
+	liveAgentProbe = probe;
+}
+
+/** Test seam: fully dispose any wiring left by a previous install in this process. */
+export function __test__resetTerminalStatusWiring(): void {
+	currentDispose?.();
+	currentDispose = undefined;
+	currentUnsubscribe = undefined;
+}
+
+export function installTerminalStatus(pi: ExtensionAPI, deps: TerminalStatusWiringDeps): void {
+	// A previous registration in this process must not leave a second
+	// subscription behind (registerCleanupHandler only keeps the latest
+	// dispose fn, so an older subscription would leak otherwise).
+	currentUnsubscribe?.();
+
+	// Dynamic adapter: resolves the CURRENT session's UI at call time, so the
+	// controller never captures a session-scoped reference.
+	const adapter: TerminalStatusUi = {
+		get hasUI(): boolean {
+			return deps.currentCtx?.hasUI ?? false;
+		},
+		ui: {
+			setTitle(title: string): void {
+				deps.currentCtx?.ui.setTitle(title);
+			},
+		},
+	};
+
+	let evalTimer: ReturnType<typeof setTimeout> | undefined;
+	let idleTimer: ReturnType<typeof setTimeout> | undefined;
+	let lastSegment = "";
+
+	const clearTimers = (): void => {
+		if (evalTimer) {
+			clearTimeout(evalTimer);
+			evalTimer = undefined;
+		}
+		if (idleTimer) {
+			clearTimeout(idleTimer);
+			idleTimer = undefined;
+		}
+	};
+
+	const evaluate = (): void => {
+		evalTimer = undefined;
+		if (!adapter.hasUI) return;
+		if (!deps.terminalStatus) deps.terminalStatus = createTerminalStatusController(adapter);
+		const controller = deps.terminalStatus;
+
+		if (liveAgentProbe() > 0) {
+			// Active: cancel any pending idle transition, then (re)assert.
+			if (idleTimer) {
+				clearTimeout(idleTimer);
+				idleTimer = undefined;
+			}
+			if (!deps.terminalStatusActive) {
+				deps.terminalStatusActive = true;
+				controller.onRunsActive(); // title (best-effort) + Ghostty INDETERMINATE
+				lastSegment = buildCrewTitleSegment();
+				return;
+			}
+			// Still active: refresh the title only when the role summary changed
+			// (never re-emit the OSC sequence — state 3 persists on its own).
+			const segment = buildCrewTitleSegment();
+			if (segment && segment !== lastSegment) {
+				lastSegment = segment;
+				setTerminalTitle(adapter, segment);
+			}
+			return;
+		}
+
+		if (deps.terminalStatusActive) {
+			deps.terminalStatusActive = false;
+			lastSegment = "";
+			controller.onRunCompleted(); // green flash, self-re-evaluates after COMPLETE_FLASH_MS
+			idleTimer = setTimeout(() => {
+				idleTimer = undefined;
+				controller.onIdle(); // title restore + idle re-assert loop + Ghostty CLEAR
+			}, COMPLETE_FLASH_MS);
+			idleTimer.unref?.();
+		}
+	};
+
+	const unsubscribe = runEventBus.onAny(() => {
+		if (evalTimer) return;
+		evalTimer = setTimeout(evaluate, EVAL_DEBOUNCE_MS);
+		evalTimer.unref?.();
+	});
+	currentUnsubscribe = unsubscribe;
+	const dispose = (): void => {
+		unsubscribe();
+		currentUnsubscribe = undefined;
+		currentDispose = undefined;
+		clearTimers();
+		deps.terminalStatus?.dispose();
+		deps.terminalStatus = undefined;
+		deps.terminalStatusActive = false;
+	};
+	currentDispose = dispose;
+
+	registerCleanupHandler(pi, { disposeTerminalStatus: dispose });
+}

package/src/extension/registration/viewers.ts

@@ -1,9 +1,12 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey } from "@earendil-works/pi-tui";
 import { loadConfig } from "../../config/config.ts";
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
 import { listLiveAgents } from "../../runtime/live-session/live-agent-manager.ts";
 import { loadRunManifestById } from "../../state/stores/state-store.ts";
+import { AgentsJobsBrowser } from "../../ui/agents-jobs-browser.ts";
 import { LiveConversationOverlay } from "../../ui/live-conversation-overlay.ts";
+import { requestRenderTarget } from "../../ui/pi-ui-compat.ts";
 import { asCrewTheme } from "../../ui/theme-adapter.ts";
 // Lazy-loaded: DurableTranscriptViewer is 658ms — only needed for /crew transcript command
 import type { DurableTranscriptViewer as DurableTranscriptViewerType } from "../../ui/transcript-viewer.ts";
@@ -87,10 +90,16 @@ export async function openLiveConversation(
 					return overlay.render(width);
 				},
 				handleInput(data: string) {
-					if (data === "\x1b" || data === "q") {
+					// Close keys stay exactly as they were: close the overlay and
+					// resolve the custom() promise.
+					if (matchesKey(data, "escape") || matchesKey(data, "q")) {
 						overlay.close();
 						done(undefined);
+						return;
 					}
+					// Everything else scrolls the live transcript (P1-3):
+					// j/k, ↓/↑, g/G, PgUp/PgDn and the `a` auto-scroll toggle.
+					overlay.handleInput(data);
 				},
 				invalidate() {
 					/* overlay polls */
@@ -111,3 +120,65 @@ export async function openLiveConversation(
 	);
 	return true;
 }
+
+/**
+ * feat/agents-browser: open the unified Agents & Jobs browser overlay.
+ *
+ * Full-view component (the SAME custom() precedent as openLiveConversation —
+ * pi's overlay-anchor option was evaluated and set aside: overlays float over
+ * chat with different key routing; the modal form matches every existing
+ * pi-crew viewer, so users get one consistent interaction model). Opened from the run
+ * dashboard with ONE keypress (`b`); lists ALL live agents + scheduled jobs
+ * via the G17 providers — independent of any single run. Headless sessions
+ * (`ctx.hasUI === false`) are a silent no-op returning false.
+ */
+export async function openAgentsJobsBrowser(
+	ctx: Pick<ExtensionCommandContext, "hasUI" | "cwd" | "ui" | "sessionManager">,
+): Promise<boolean> {
+	if (!ctx.hasUI) return false;
+	const theme = asCrewTheme({});
+	const workspaceId = ctx.sessionManager?.getSessionId?.();
+	await ctx.ui.custom<undefined>(
+		(tui, _theme, _keybindings, done) => {
+			const columns = tui?.terminal?.columns ?? 80;
+			const rows = tui?.terminal?.rows ?? 24;
+			const browser = new AgentsJobsBrowser({
+				cwd: ctx.cwd,
+				workspaceId,
+				theme,
+				columns,
+				rows,
+				requestRender: () => requestRenderTarget(tui),
+				// Enter on an agent opens the full transcript overlay — the
+				// `/crew transcript` experience ("chi tiết như subagent cũ").
+				onOpenTranscript: ({ runId, taskId }) => {
+					void openTranscriptViewer(ctx as ExtensionCommandContext, runId, taskId);
+				},
+			});
+			return {
+				render(width: number) {
+					return browser.render(width);
+				},
+				handleInput(data: string) {
+					browser.handleInput(data);
+					if (browser.isClosed) done(undefined);
+				},
+				invalidate() {
+					browser.refreshData(true);
+				},
+				dispose() {
+					browser.dispose();
+				},
+			};
+		},
+		{
+			overlay: true,
+			overlayOptions: {
+				width: "92%",
+				maxHeight: "70%",
+				anchor: "center",
+			},
+		},
+	);
+	return true;
+}

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/extension/team-tool/handle-settings.ts

@@ -245,11 +245,19 @@ const KNOWN_KEYS = new Set([
 	// ui
 	"ui.widgetPlacement",
 	"ui.widgetMaxLines",
+	// M1-9/P1-8: inlinePanel is a schema key (config-schema.ts
+	// PiTeamsUiConfigSchema) and ui.autoCloseDashboardMs is parsed by
+	// parseUiConfig — keep this list mirroring the schema's ui block so
+	// `team-settings schema` lists what the schema actually accepts.
+	// (ui.widgetRowStyle was REMOVED 2026-09-16: the RAIL dock renders one
+	// layout; the key no longer has any reader.)
+	"ui.inlinePanel",
 	"ui.dashboardPlacement",
 	"ui.dashboardWidth",
 	"ui.dashboardLiveRefreshMs",
 	"ui.autoOpenDashboard",
 	"ui.autoOpenDashboardForForegroundRuns",
+	"ui.autoCloseDashboardMs",
 	"ui.showModel",
 	"ui.showTokens",
 	"ui.showTools",
@@ -440,9 +448,13 @@ export function handleSettings(params: { config?: Record<string, unknown> }, ctx
 		const key = args.slice(4).trim();
 		if (!key) return result("Usage: team-settings get <key>\nUse 'team-settings schema' to see all known keys.", { ...ERR }, true);
 		const value = getNested(effective, key);
-		// Try to provide helpful note for unknown keys
+		// Try to provide helpful note for unknown keys.
+		// M1-9/P1-8: `ui.*` is exempt exactly like the `set` path below (:497) —
+		// every ui.* key is accepted by the schema's ui block, so `get
+		// ui.<key>` must not answer "(unknown key — may not take
+		// effect)" for a key the config layer actually honours.
 		let note = "";
-		if (!KNOWN_KEYS.has(key) && !key.startsWith("agents.overrides.")) {
+		if (!KNOWN_KEYS.has(key) && !key.startsWith("agents.overrides.") && !key.startsWith("ui.")) {
 			const suggestion = suggestConfigKey(key, KNOWN_SORTED);
 			if (suggestion) note = `\n(did you mean '${suggestion}'?)`;
 			else note = "\n(unknown key — may not take effect)";

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).