diff --git a/CHANGELOG.md b/CHANGELOG.md index ec4833d4e0b..8bcd871cc89 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ Docs: https://docs.openclaw.ai - Agents/sessions: preserve terminal lifecycle state when final run metadata persists from a stale in-memory snapshot, preventing `main` sessions from staying stuck as running after completed or timed-out turns. - Gateway/CLI: make `openclaw gateway start` repair stale managed service definitions that point at old OpenClaw versions, missing binaries, or temporary installer paths before starting. +- Heartbeat/scheduler: make heartbeat phase scheduling active-hours-aware so the scheduler seeks forward to the first in-window phase slot instead of arming timers for quiet-hours slots and relying solely on the runtime guard. Non-UTC `activeHours.timezone` values (e.g. `Asia/Shanghai`) now correctly influence when the next heartbeat timer fires, avoiding wasted quiet-hours ticks and long dormant gaps after gateway restarts. Fixes #75487. Thanks @amknight. - Status: show the `openai-codex` OAuth profile for `openai/gpt-*` sessions running through the native Codex runtime instead of reporting auth as unknown. (#76197) Thanks @mbelinky. - Plugins/externalization: keep diagnostics ClawHub packages and persisted bundled-plugin relocation on npm-first install metadata for launch, and omit Discord from the core package now that its external package is published. Thanks @vincentkoc. - Plugins/Codex: allow the official npm Codex plugin to install without the unsafe-install override, keep `/codex` command ownership, and cover the real npm Docker live path through managed `.openclaw/npm` dependencies plus uninstall failure proof. diff --git a/src/infra/heartbeat-active-hours.ts b/src/infra/heartbeat-active-hours.ts index aedf04dd61c..9215ce30675 100644 --- a/src/infra/heartbeat-active-hours.ts +++ b/src/infra/heartbeat-active-hours.ts @@ -6,7 +6,7 @@ type HeartbeatConfig = AgentDefaultsConfig["heartbeat"]; const ACTIVE_HOURS_TIME_PATTERN = /^(?:([01]\d|2[0-3]):([0-5]\d)|24:00)$/; -function resolveActiveHoursTimezone(cfg: OpenClawConfig, raw?: string): string { +export function resolveActiveHoursTimezone(cfg: OpenClawConfig, raw?: string): string { const trimmed = raw?.trim(); if (!trimmed || trimmed === "user") { return resolveUserTimezone(cfg.agents?.defaults?.userTimezone); diff --git a/src/infra/heartbeat-runner.active-hours-schedule.e2e.test.ts b/src/infra/heartbeat-runner.active-hours-schedule.e2e.test.ts new file mode 100644 index 00000000000..d69179f6980 --- /dev/null +++ b/src/infra/heartbeat-runner.active-hours-schedule.e2e.test.ts @@ -0,0 +1,288 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import type { OpenClawConfig } from "../config/config.js"; +import { startHeartbeatRunner } from "./heartbeat-runner.js"; +import { computeNextHeartbeatPhaseDueMs, resolveHeartbeatPhaseMs } from "./heartbeat-schedule.js"; +import { resetHeartbeatWakeStateForTests } from "./heartbeat-wake.js"; + +/** Verifies that the scheduler seeks to in-window phase slots (#75487). */ +describe("heartbeat scheduler: activeHours-aware scheduling (#75487)", () => { + type RunOnce = Parameters[0]["runOnce"]; + const TEST_SCHEDULER_SEED = "heartbeat-ah-schedule-test-seed"; + + function useFakeHeartbeatTime(startMs: number) { + vi.useFakeTimers(); + vi.setSystemTime(new Date(startMs)); + } + + function heartbeatConfig(overrides?: { + every?: string; + activeHours?: { start: string; end: string; timezone?: string }; + userTimezone?: string; + }): OpenClawConfig { + return { + agents: { + defaults: { + heartbeat: { + every: overrides?.every ?? "4h", + ...(overrides?.activeHours ? { activeHours: overrides.activeHours } : {}), + }, + ...(overrides?.userTimezone ? { userTimezone: overrides.userTimezone } : {}), + }, + }, + }; + } + + function resolveDueFromNow(nowMs: number, intervalMs: number, agentId: string) { + return computeNextHeartbeatPhaseDueMs({ + nowMs, + intervalMs, + phaseMs: resolveHeartbeatPhaseMs({ + schedulerSeed: TEST_SCHEDULER_SEED, + agentId, + intervalMs, + }), + }); + } + + afterEach(() => { + resetHeartbeatWakeStateForTests(); + vi.useRealTimers(); + vi.restoreAllMocks(); + }); + + it("skips quiet-hours slots and fires at the first in-window phase slot", async () => { + // 09:00–17:00 UTC, 4h interval. Start at 16:30 — raw due is after 17:00. + const startMs = Date.parse("2026-06-15T16:30:00.000Z"); + useFakeHeartbeatTime(startMs); + + const intervalMs = 4 * 60 * 60_000; + const callTimes: number[] = []; + const runSpy: RunOnce = vi.fn().mockImplementation(async () => { + callTimes.push(Date.now()); + return { status: "ran", durationMs: 1 }; + }); + + const runner = startHeartbeatRunner({ + cfg: heartbeatConfig({ + every: "4h", + activeHours: { start: "09:00", end: "17:00", timezone: "UTC" }, + }), + runOnce: runSpy, + stableSchedulerSeed: TEST_SCHEDULER_SEED, + }); + + const rawDueMs = resolveDueFromNow(startMs, intervalMs, "main"); + + // Advance past the raw due — should NOT fire (quiet hours). + await vi.advanceTimersByTimeAsync(rawDueMs - startMs + 1); + + // Advance to end of next day's window — should fire within 09:00–17:00. + const safeEndOfWindow = Date.parse("2026-06-16T17:00:00.000Z"); + await vi.advanceTimersByTimeAsync(safeEndOfWindow - Date.now()); + + expect(runSpy).toHaveBeenCalled(); + const firstCallHourUTC = new Date(callTimes[0]).getUTCHours(); + expect(firstCallHourUTC).toBeGreaterThanOrEqual(9); + expect(firstCallHourUTC).toBeLessThan(17); + + runner.stop(); + }); + + it("fires immediately when the first phase slot is already within active hours", async () => { + const startMs = Date.parse("2026-06-15T10:00:00.000Z"); + useFakeHeartbeatTime(startMs); + + const intervalMs = 4 * 60 * 60_000; + const runSpy: RunOnce = vi.fn().mockResolvedValue({ status: "ran", durationMs: 1 }); + + const runner = startHeartbeatRunner({ + cfg: heartbeatConfig({ + every: "4h", + activeHours: { start: "08:00", end: "20:00", timezone: "UTC" }, + }), + runOnce: runSpy, + stableSchedulerSeed: TEST_SCHEDULER_SEED, + }); + + const rawDueMs = resolveDueFromNow(startMs, intervalMs, "main"); + await vi.advanceTimersByTimeAsync(rawDueMs - startMs + 1); + + expect(runSpy).toHaveBeenCalledTimes(1); + runner.stop(); + }); + + it("seeks forward correctly with a non-UTC timezone (e.g. America/New_York)", async () => { + // 09:00–17:00 ET (EDT = UTC-4 in June) → 13:00–21:00 UTC. + // Start at 21:30 UTC (17:30 ET = outside window). + const startMs = Date.parse("2026-06-15T21:30:00.000Z"); + useFakeHeartbeatTime(startMs); + + const callTimes: number[] = []; + const runSpy: RunOnce = vi.fn().mockImplementation(async () => { + callTimes.push(Date.now()); + return { status: "ran", durationMs: 1 }; + }); + + const runner = startHeartbeatRunner({ + cfg: heartbeatConfig({ + every: "4h", + activeHours: { start: "09:00", end: "17:00", timezone: "America/New_York" }, + }), + runOnce: runSpy, + stableSchedulerSeed: TEST_SCHEDULER_SEED, + }); + + await vi.advanceTimersByTimeAsync(48 * 60 * 60_000); + + expect(runSpy).toHaveBeenCalled(); + const firstCallHourUTC = new Date(callTimes[0]).getUTCHours(); + expect(firstCallHourUTC).toBeGreaterThanOrEqual(13); + expect(firstCallHourUTC).toBeLessThan(21); + + runner.stop(); + }); + + it("advances to in-window slot after a quiet-hours skip during interval runs", async () => { + // 09:00–17:00 UTC, 4h interval. Verify ALL fires over 48h stay in-window. + const startMs = Date.parse("2026-06-15T09:00:00.000Z"); + useFakeHeartbeatTime(startMs); + + const callTimes: number[] = []; + const runSpy: RunOnce = vi.fn().mockImplementation(async () => { + callTimes.push(Date.now()); + return { status: "ran", durationMs: 1 }; + }); + + const runner = startHeartbeatRunner({ + cfg: heartbeatConfig({ + every: "4h", + activeHours: { start: "09:00", end: "17:00", timezone: "UTC" }, + }), + runOnce: runSpy, + stableSchedulerSeed: TEST_SCHEDULER_SEED, + }); + + await vi.advanceTimersByTimeAsync(48 * 60 * 60_000); + + expect(callTimes.length).toBeGreaterThan(0); + for (const t of callTimes) { + const hour = new Date(t).getUTCHours(); + expect( + hour, + `fire at ${new Date(t).toISOString()} is outside active window`, + ).toBeGreaterThanOrEqual(9); + expect(hour, `fire at ${new Date(t).toISOString()} is outside active window`).toBeLessThan( + 17, + ); + } + + runner.stop(); + }); + + it("does not loop indefinitely when activeHours window is zero-width", async () => { + // start === end → never-active; seek falls back, runtime guard skips. + const startMs = Date.parse("2026-06-15T10:00:00.000Z"); + useFakeHeartbeatTime(startMs); + + const runSpy: RunOnce = vi.fn().mockResolvedValue({ status: "skipped", reason: "quiet-hours" }); + + const runner = startHeartbeatRunner({ + cfg: heartbeatConfig({ + every: "30m", + activeHours: { start: "12:00", end: "12:00", timezone: "UTC" }, + }), + runOnce: runSpy, + stableSchedulerSeed: TEST_SCHEDULER_SEED, + }); + + await vi.advanceTimersByTimeAsync(2 * 60 * 60_000); + + expect(runSpy).toHaveBeenCalled(); + runner.stop(); + }); + + it("recomputes schedule when activeHours config changes via hot reload", async () => { + // Narrow window pushes nextDueMs to tomorrow; widening via updateConfig + // must recompute from `now` so the timer fires today. + const startMs = Date.parse("2026-06-15T14:00:00.000Z"); + useFakeHeartbeatTime(startMs); + + const callTimes: number[] = []; + const runSpy: RunOnce = vi.fn().mockImplementation(async () => { + callTimes.push(Date.now()); + return { status: "ran", durationMs: 1 }; + }); + + const runner = startHeartbeatRunner({ + cfg: heartbeatConfig({ + every: "4h", + activeHours: { start: "09:00", end: "10:00", timezone: "UTC" }, + }), + runOnce: runSpy, + stableSchedulerSeed: TEST_SCHEDULER_SEED, + }); + + await vi.advanceTimersByTimeAsync(60 * 60_000); + expect(runSpy).not.toHaveBeenCalled(); + + // Widen window — scheduler must recompute, not keep stale tomorrow slot. + runner.updateConfig( + heartbeatConfig({ + every: "4h", + activeHours: { start: "08:00", end: "20:00", timezone: "UTC" }, + }), + ); + + await vi.advanceTimersByTimeAsync(8 * 60 * 60_000); + expect(runSpy).toHaveBeenCalled(); + const firstCallHour = new Date(callTimes[0]).getUTCHours(); + expect(firstCallHour).toBeGreaterThanOrEqual(8); + expect(firstCallHour).toBeLessThan(20); + expect(new Date(callTimes[0]).getUTCDate()).toBe(15); // today, not tomorrow + + runner.stop(); + }); + + it("recomputes schedule when activeHours effective timezone changes via hot reload", async () => { + const startMs = Date.parse("2026-06-15T14:00:00.000Z"); + useFakeHeartbeatTime(startMs); + + const callTimes: number[] = []; + const runSpy: RunOnce = vi.fn().mockImplementation(async () => { + callTimes.push(Date.now()); + return { status: "ran", durationMs: 1 }; + }); + + const activeHours = { start: "16:00", end: "17:00" }; + const runner = startHeartbeatRunner({ + cfg: heartbeatConfig({ + every: "4h", + activeHours, + userTimezone: "America/New_York", + }), + runOnce: runSpy, + stableSchedulerSeed: TEST_SCHEDULER_SEED, + }); + + await vi.advanceTimersByTimeAsync(60 * 60_000); + expect(runSpy).not.toHaveBeenCalled(); + + runner.updateConfig( + heartbeatConfig({ + every: "4h", + activeHours, + userTimezone: "UTC", + }), + ); + + const endOfUtcWindow = Date.parse("2026-06-15T17:00:00.000Z"); + await vi.advanceTimersByTimeAsync(endOfUtcWindow - Date.now()); + + expect(runSpy).toHaveBeenCalled(); + const firstCall = new Date(callTimes[0]); + expect(firstCall.getUTCHours()).toBe(16); + expect(firstCall.getUTCDate()).toBe(15); + + runner.stop(); + }); +}); diff --git a/src/infra/heartbeat-runner.ts b/src/infra/heartbeat-runner.ts index b23d704f194..9699cc9de9e 100644 --- a/src/infra/heartbeat-runner.ts +++ b/src/infra/heartbeat-runner.ts @@ -83,7 +83,7 @@ import { escapeRegExp } from "../utils.js"; import { MAX_SAFE_TIMEOUT_DELAY_MS, resolveSafeTimeoutDelayMs } from "../utils/timer-delay.js"; import { loadOrCreateDeviceIdentity } from "./device-identity.js"; import { formatErrorMessage, hasErrnoCode } from "./errors.js"; -import { isWithinActiveHours } from "./heartbeat-active-hours.js"; +import { isWithinActiveHours, resolveActiveHoursTimezone } from "./heartbeat-active-hours.js"; import { recordRunStart, shouldDeferWake, type DeferDecision } from "./heartbeat-cooldown.js"; import { buildCronEventPrompt, @@ -97,6 +97,7 @@ import { computeNextHeartbeatPhaseDueMs, resolveHeartbeatPhaseMs, resolveNextHeartbeatDueMs, + seekNextActivePhaseDueMs, } from "./heartbeat-schedule.js"; import { isHeartbeatEnabledForAgent, @@ -212,6 +213,7 @@ function canHeartbeatDeliverCommitments(heartbeat?: HeartbeatConfig): boolean { type HeartbeatAgentState = { agentId: string; heartbeat?: HeartbeatConfig; + activeHoursSchedule?: ActiveHoursSchedule; intervalMs: number; phaseMs: number; nextDueMs: number; @@ -223,6 +225,37 @@ type HeartbeatAgentState = { floodLoggedSinceLastRun: boolean; }; +type ActiveHoursSchedule = { + start?: string; + end?: string; + timezone: string; +}; + +function resolveActiveHoursSchedule( + cfg: OpenClawConfig, + heartbeat?: HeartbeatConfig, +): ActiveHoursSchedule | undefined { + const activeHours = heartbeat?.activeHours; + if (!activeHours) { + return undefined; + } + return { + start: activeHours.start, + end: activeHours.end, + timezone: resolveActiveHoursTimezone(cfg, activeHours.timezone), + }; +} + +function activeHoursConfigMatch(a?: ActiveHoursSchedule, b?: ActiveHoursSchedule): boolean { + if (a === b) { + return true; + } + if (!a || !b) { + return false; + } + return a.start === b.start && a.end === b.end && a.timezone === b.timezone; +} + export type HeartbeatRunner = { stop: () => void; updateConfig: (cfg: OpenClawConfig) => void; @@ -1779,8 +1812,16 @@ export function startHeartbeatRunner(opts: { : undefined, }); + const seekActiveSlotForAgent = (agent: HeartbeatAgentState, rawDueMs: number) => + seekNextActivePhaseDueMs({ + startMs: rawDueMs, + intervalMs: agent.intervalMs, + phaseMs: agent.phaseMs, + isActive: (ms) => isWithinActiveHours(state.cfg, agent.heartbeat, ms), + }); + const advanceAgentSchedule = (agent: HeartbeatAgentState, now: number, reason?: string) => { - agent.nextDueMs = + const rawDueMs = reason === "interval" ? computeNextHeartbeatPhaseDueMs({ nowMs: now, @@ -1790,6 +1831,7 @@ export function startHeartbeatRunner(opts: { : // Targeted and action-driven wakes still count as a fresh heartbeat run // for cooldown purposes, so keep the existing now + interval behavior. now + agent.intervalMs; + agent.nextDueMs = seekActiveSlotForAgent(agent, rawDueMs); }; // Centralized cooldown gate. Both targeted and broadcast dispatch branches @@ -1894,10 +1936,27 @@ export function startHeartbeatRunner(opts: { }); intervals.push(intervalMs); const prevState = prevAgents.get(agent.agentId); - const nextDueMs = resolveNextDue(now, intervalMs, phaseMs, prevState); + const activeHoursSchedule = resolveActiveHoursSchedule(cfg, agent.heartbeat); + // resolveNextDue only compares intervalMs/phaseMs, so discard + // prevState when the effective activeHours window changed to avoid a stale far-future slot. + const ahChanged = + prevState && !activeHoursConfigMatch(prevState.activeHoursSchedule, activeHoursSchedule); + const rawNextDueMs = resolveNextDue( + now, + intervalMs, + phaseMs, + ahChanged ? undefined : prevState, + ); + const nextDueMs = seekNextActivePhaseDueMs({ + startMs: rawNextDueMs, + intervalMs, + phaseMs, + isActive: (ms) => isWithinActiveHours(cfg, agent.heartbeat, ms), + }); nextAgents.set(agent.agentId, { agentId: agent.agentId, heartbeat: agent.heartbeat, + activeHoursSchedule, intervalMs, phaseMs, nextDueMs, diff --git a/src/infra/heartbeat-schedule.test.ts b/src/infra/heartbeat-schedule.test.ts index c4d848f0fdf..9f01e459c25 100644 --- a/src/infra/heartbeat-schedule.test.ts +++ b/src/infra/heartbeat-schedule.test.ts @@ -3,6 +3,7 @@ import { computeNextHeartbeatPhaseDueMs, resolveHeartbeatPhaseMs, resolveNextHeartbeatDueMs, + seekNextActivePhaseDueMs, } from "./heartbeat-schedule.js"; describe("heartbeat schedule helpers", () => { @@ -61,3 +62,168 @@ describe("heartbeat schedule helpers", () => { ).toBe(nextDueMs); }); }); + +describe("seekNextActivePhaseDueMs", () => { + const HOUR = 60 * 60_000; + + it("returns startMs immediately when no isActive predicate is provided", () => { + const startMs = Date.parse("2026-01-01T03:00:00.000Z"); + expect( + seekNextActivePhaseDueMs({ + startMs, + intervalMs: 4 * HOUR, + phaseMs: 0, + }), + ).toBe(startMs); + }); + + it("returns startMs when the first slot is already within active hours", () => { + const startMs = Date.parse("2026-01-01T10:00:00.000Z"); + expect( + seekNextActivePhaseDueMs({ + startMs, + intervalMs: 4 * HOUR, + phaseMs: 0, + isActive: () => true, + }), + ).toBe(startMs); + }); + + it("skips quiet-hours slots and returns the first in-window slot", () => { + // 08:00–17:00 UTC, 4h interval, start at 19:00 (quiet). + const startMs = Date.parse("2026-01-01T19:00:00.000Z"); + const intervalMs = 4 * HOUR; + const isActive = (ms: number) => { + const hour = new Date(ms).getUTCHours(); + return hour >= 8 && hour < 17; + }; + + const result = seekNextActivePhaseDueMs({ + startMs, + intervalMs, + phaseMs: 0, + isActive, + }); + + expect(result).toBe(Date.parse("2026-01-02T11:00:00.000Z")); + }); + + it("handles overnight active windows correctly", () => { + // 22:00–06:00 UTC (overnight), 4h interval, start at 10:00 (quiet). + const startMs = Date.parse("2026-01-01T10:00:00.000Z"); + const intervalMs = 4 * HOUR; + const isActive = (ms: number) => { + const hour = new Date(ms).getUTCHours(); + return hour >= 22 || hour < 6; + }; + + const result = seekNextActivePhaseDueMs({ + startMs, + intervalMs, + phaseMs: 0, + isActive, + }); + + expect(result).toBe(Date.parse("2026-01-01T22:00:00.000Z")); + }); + + it("falls back to startMs when no slot is active within the seek horizon", () => { + const startMs = Date.parse("2026-01-01T10:00:00.000Z"); + const result = seekNextActivePhaseDueMs({ + startMs, + intervalMs: 4 * HOUR, + phaseMs: 0, + isActive: () => false, + }); + + expect(result).toBe(startMs); + }); + + it("seeks across timezone-aware active hours using isWithinActiveHours semantics", () => { + // Asia/Shanghai (UTC+8): active 08:00–23:00 local. + const startMs = Date.parse("2026-01-01T15:21:00.000Z"); + const intervalMs = 4 * HOUR; + const shanghaiOffsetMs = 8 * HOUR; + + const isActive = (ms: number) => { + const shanghaiMs = ms + shanghaiOffsetMs; + const shanghaiHour = new Date(shanghaiMs).getUTCHours(); + return shanghaiHour >= 8 && shanghaiHour < 23; + }; + + const result = seekNextActivePhaseDueMs({ + startMs, + intervalMs, + phaseMs: 0, + isActive, + }); + + expect(result).toBe(Date.parse("2026-01-02T03:21:00.000Z")); + }); + + it("handles very short intervals efficiently", () => { + // 30m interval, 09:00–17:00. Start at 17:00 (quiet) → 09:00 next day. + const startMs = Date.parse("2026-01-01T17:00:00.000Z"); + const intervalMs = 30 * 60_000; + const isActive = (ms: number) => { + const hour = new Date(ms).getUTCHours(); + return hour >= 9 && hour < 17; + }; + + const result = seekNextActivePhaseDueMs({ + startMs, + intervalMs, + phaseMs: 0, + isActive, + }); + + expect(result).toBe(Date.parse("2026-01-02T09:00:00.000Z")); + }); + + it("caps iterations for pathological sub-second intervals", () => { + const startMs = Date.parse("2026-01-01T12:00:00.000Z"); + const t0 = performance.now(); + const result = seekNextActivePhaseDueMs({ + startMs, + intervalMs: 1, // 1ms — pathological + phaseMs: 0, + isActive: () => false, + }); + const elapsedMs = performance.now() - t0; + + expect(result).toBe(startMs); + expect(elapsedMs).toBeLessThan(500); + }); + + it("handles intervalMs larger than the seek horizon", () => { + const startMs = Date.parse("2026-01-01T03:00:00.000Z"); + const eightDays = 8 * 24 * HOUR; + const result = seekNextActivePhaseDueMs({ + startMs, + intervalMs: eightDays, + phaseMs: 0, + isActive: (ms) => { + const hour = new Date(ms).getUTCHours(); + return hour >= 9 && hour < 17; + }, + }); + + expect(result).toBe(startMs); + }); + + it("returns startMs when intervalMs larger than horizon and startMs is active", () => { + const startMs = Date.parse("2026-01-01T12:00:00.000Z"); // 12:00 — active + const eightDays = 8 * 24 * HOUR; + const result = seekNextActivePhaseDueMs({ + startMs, + intervalMs: eightDays, + phaseMs: 0, + isActive: (ms) => { + const hour = new Date(ms).getUTCHours(); + return hour >= 9 && hour < 17; + }, + }); + + expect(result).toBe(startMs); + }); +}); diff --git a/src/infra/heartbeat-schedule.ts b/src/infra/heartbeat-schedule.ts index 65b2fc4cd0e..6df73e1e0f0 100644 --- a/src/infra/heartbeat-schedule.ts +++ b/src/infra/heartbeat-schedule.ts @@ -57,3 +57,41 @@ export function resolveNextHeartbeatDueMs(params: { phaseMs, }); } + +/** + * Seek forward through phase-aligned slots until one falls within the active + * hours window. Falls back to the raw next slot when no predicate is provided + * or no in-window slot is found within the seek horizon. + * + * The caller binds config/heartbeat into `isActive` so this module stays + * config-agnostic. `phaseMs` is unused — alignment is preserved because + * `startMs` is already phase-aligned and `intervalMs` addition maintains it. + */ +const MAX_SEEK_HORIZON_MS = 7 * 24 * 60 * 60_000; +// Prevent pathological sub-minute intervals from blocking the event loop. +const MAX_SEEK_ITERATIONS = 10_080; // 7 days at 1-minute steps + +export function seekNextActivePhaseDueMs(params: { + startMs: number; + intervalMs: number; + phaseMs: number; + isActive?: (ms: number) => boolean; +}): number { + const isActive = params.isActive; + if (!isActive) { + return params.startMs; + } + const intervalMs = Math.max(1, Math.floor(params.intervalMs)); + const horizonMs = params.startMs + MAX_SEEK_HORIZON_MS; + let candidateMs = params.startMs; + let iterations = 0; + while (candidateMs <= horizonMs && iterations < MAX_SEEK_ITERATIONS) { + if (isActive(candidateMs)) { + return candidateMs; + } + candidateMs += intervalMs; + iterations++; + } + // No in-window slot found; fall back so the runtime guard can gate it. + return params.startMs; +}