feat: add cycle timeout/watchdog mechanism

- Add cycleTimeoutMinutes config option (default: 60 minutes, 0 = disabled)
- Track cycleStartTime in state for timeout calculation
- Force cycle completion when timeout exceeded:
  - Plan phase: start new cycle
  - Build phase: skip to evaluation
- Add isCycleTimedOut() and getCycleElapsedTime() helpers
- Support via config file, env var OPENCODER_CYCLE_TIMEOUT_MINUTES
- Add comprehensive tests for timeout functionality
- Update documentation with new config option

Signed-off-by: leocavalcante <[email protected]>

Author: leocavalcante

AGENTS.md

@@ -270,6 +270,7 @@ OPENCODER_TASK_PAUSE_SECONDS=2
 OPENCODER_AUTO_COMMIT=true
 OPENCODER_AUTO_PUSH=true
 OPENCODER_COMMIT_SIGNOFF=false
+OPENCODER_CYCLE_TIMEOUT_MINUTES=60
 ```
 
 ### Config File (.opencode/opencoder/config.json)
@@ -283,7 +284,8 @@ OPENCODER_COMMIT_SIGNOFF=false
   "taskPauseSeconds": 2,
   "autoCommit": true,
   "autoPush": true,
-  "commitSignoff": false
+  "commitSignoff": false,
+  "cycleTimeoutMinutes": 60
 }
 ```
 

src/config.ts

@@ -23,6 +23,7 @@ const DEFAULTS: Omit<Config, "planModel" | "buildModel" | "projectDir"> = {
 	autoCommit: true,
 	autoPush: true,
 	commitSignoff: false,
+	cycleTimeoutMinutes: 60,
 }
 
 /** Environment variable prefix */
@@ -111,6 +112,7 @@ async function loadConfigFile(projectDir: string): Promise<Partial<Config>> {
 			autoCommit: parsed.autoCommit,
 			autoPush: parsed.autoPush,
 			commitSignoff: parsed.commitSignoff,
+			cycleTimeoutMinutes: parsed.cycleTimeoutMinutes,
 		})
 	} catch (err) {
 		console.warn(`Warning: Failed to parse config.json: ${err}`)
@@ -166,6 +168,12 @@ function loadEnvConfig(): Partial<Config> {
 	const commitSignoff = process.env[`${ENV_PREFIX}COMMIT_SIGNOFF`]
 	if (commitSignoff) config.commitSignoff = commitSignoff === "true" || commitSignoff === "1"
 
+	const cycleTimeout = process.env[`${ENV_PREFIX}CYCLE_TIMEOUT_MINUTES`]
+	if (cycleTimeout) {
+		const parsed = Number.parseInt(cycleTimeout, 10)
+		if (!Number.isNaN(parsed)) config.cycleTimeoutMinutes = parsed
+	}
+
 	return config
 }
 

src/loop.ts

@@ -79,6 +79,38 @@ export async function runLoop(config: Config): Promise<void> {
 		while (!shutdownRequested) {
 			logger.setCycleLog(state.cycle)
 
+			// Start cycle timer if not already set
+			if (!state.cycleStartTime) {
+				state.cycleStartTime = getISOTimestamp()
+				logger.logVerbose(`Cycle ${state.cycle} started at ${state.cycleStartTime}`)
+			}
+
+			// Check for cycle timeout
+			if (isCycleTimedOut(state, config)) {
+				const elapsed = getCycleElapsedTime(state)
+				logger.alert(
+					`TIMEOUT: Cycle ${state.cycle} exceeded ${config.cycleTimeoutMinutes} minute limit (elapsed: ${elapsed})`,
+				)
+				logger.warn("Forcing cycle completion due to timeout...")
+
+				// Force transition to evaluation to complete the cycle
+				if (state.phase === "plan") {
+					// Can't complete without a plan, start new cycle
+					logger.warn("Timeout during planning, starting new cycle...")
+					state.cycle++
+					state.phase = "plan"
+					state.cycleStartTime = undefined
+					state.currentIdeaPath = undefined
+					state.currentIdeaFilename = undefined
+					builder.clearSession()
+				} else if (state.phase === "build") {
+					// Skip remaining tasks and move to evaluation
+					logger.warn("Timeout during build, skipping to evaluation...")
+					state.phase = "evaluation"
+				}
+				// If already in evaluation, it will complete normally
+			}
+
 			try {
 				switch (state.phase) {
 					case "init":
@@ -466,6 +498,7 @@ async function runEvaluationPhase(
 		state.currentTaskDesc = ""
 		state.currentIdeaPath = undefined
 		state.currentIdeaFilename = undefined
+		state.cycleStartTime = undefined // Reset for new cycle
 
 		// Clear session for new cycle
 		builder.clearSession()
@@ -572,6 +605,50 @@ function escapeRegExp(str: string): string {
 	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 }
 
+/**
+ * Check if the current cycle has exceeded the timeout.
+ * @param state - Runtime state with cycle start time
+ * @param config - Configuration with timeout setting
+ * @returns True if cycle has timed out, false otherwise
+ */
+export function isCycleTimedOut(state: RuntimeState, config: Config): boolean {
+	if (config.cycleTimeoutMinutes <= 0) {
+		return false // Timeout disabled
+	}
+
+	if (!state.cycleStartTime) {
+		return false // No start time recorded
+	}
+
+	const startTime = new Date(state.cycleStartTime).getTime()
+	const elapsed = Date.now() - startTime
+	const timeoutMs = config.cycleTimeoutMinutes * 60 * 1000
+
+	return elapsed >= timeoutMs
+}
+
+/**
+ * Get elapsed time in the current cycle as a human-readable string.
+ * @param state - Runtime state with cycle start time
+ * @returns Formatted elapsed time (e.g., "45m 30s") or empty string if no start time
+ */
+export function getCycleElapsedTime(state: RuntimeState): string {
+	if (!state.cycleStartTime) {
+		return ""
+	}
+
+	const startTime = new Date(state.cycleStartTime).getTime()
+	const elapsed = Date.now() - startTime
+
+	const minutes = Math.floor(elapsed / 60000)
+	const seconds = Math.floor((elapsed % 60000) / 1000)
+
+	if (minutes > 0) {
+		return `${minutes}m ${seconds}s`
+	}
+	return `${seconds}s`
+}
+
 /**
  * Check if shutdown has been requested.
  * Exported for testing and external shutdown checks.

src/state.ts

@@ -15,6 +15,7 @@ const DEFAULT_STATE: State = {
 	currentIdeaFilename: undefined,
 	retryCount: 0,
 	lastErrorTime: undefined,
+	cycleStartTime: undefined,
 }
 
 /**
@@ -78,6 +79,7 @@ export async function loadState(stateFile: string): Promise<RuntimeState> {
 			currentIdeaFilename: parsed.currentIdeaFilename,
 			retryCount: parsed.retryCount ?? DEFAULT_STATE.retryCount,
 			lastErrorTime: parsed.lastErrorTime,
+			cycleStartTime: parsed.cycleStartTime,
 		}
 
 		return toRuntimeState(state)
@@ -114,6 +116,7 @@ export async function saveState(stateFile: string, state: RuntimeState): Promise
 		currentIdeaFilename: state.currentIdeaFilename,
 		retryCount: state.retryCount,
 		lastErrorTime: state.lastErrorTime,
+		cycleStartTime: state.cycleStartTime,
 	}
 
 	const content = JSON.stringify(persistedState, null, 2)
@@ -172,5 +175,6 @@ export function newCycleState(currentCycle: number): Partial<RuntimeState> {
 		currentIdeaFilename: undefined,
 		retryCount: 0,
 		lastErrorTime: undefined,
+		cycleStartTime: undefined,
 	}
 }

src/types.ts

@@ -31,6 +31,8 @@ export interface Config {
 	autoPush: boolean
 	/** Add signoff flag (-s) to commits */
 	commitSignoff: boolean
+	/** Maximum minutes per cycle before timeout (0 = no limit) */
+	cycleTimeoutMinutes: number
 }
 
 /** Persisted state */
@@ -53,6 +55,8 @@ export interface State {
 	retryCount: number
 	/** ISO timestamp of last error (for backoff calculation) */
 	lastErrorTime?: string
+	/** ISO timestamp when current cycle started */
+	cycleStartTime?: string
 }
 
 /** Runtime state with additional non-persisted fields */
@@ -137,6 +141,7 @@ export interface ConfigFile {
 	autoCommit?: boolean
 	autoPush?: boolean
 	commitSignoff?: boolean
+	cycleTimeoutMinutes?: number
 }
 
 /** CLI options from argument parsing */

tests/loop.test.ts

@@ -9,13 +9,15 @@ import { Logger } from "../src/logger.ts"
 import {
 	archivePlan,
 	calculateBackoff,
+	getCycleElapsedTime,
+	isCycleTimedOut,
 	isShutdownRequested,
 	logStartupInfo,
 	requestShutdown,
 	resetShutdownFlags,
 	sleep,
 } from "../src/loop.ts"
-import type { Config, Paths } from "../src/types.ts"
+import type { Config, Paths, RuntimeState } from "../src/types.ts"
 
 const TEST_DIR = "/tmp/opencoder-test-loop"
 
@@ -30,6 +32,7 @@ function createTestPaths(): Paths {
 		alertsFile: join(TEST_DIR, "alerts.log"),
 		historyDir: join(TEST_DIR, "history"),
 		ideasDir: join(TEST_DIR, "ideas"),
+		ideasHistoryDir: join(TEST_DIR, "ideas", "history"),
 		configFile: join(TEST_DIR, "config.json"),
 	}
 }
@@ -48,6 +51,22 @@ function createTestConfig(overrides?: Partial<Config>): Config {
 		autoCommit: true,
 		autoPush: true,
 		commitSignoff: false,
+		cycleTimeoutMinutes: 60,
+		...overrides,
+	}
+}
+
+/** Create a test RuntimeState object */
+function createTestState(overrides?: Partial<RuntimeState>): RuntimeState {
+	return {
+		cycle: 1,
+		phase: "plan",
+		taskIndex: 0,
+		lastUpdate: new Date().toISOString(),
+		retryCount: 0,
+		totalTasks: 0,
+		currentTaskNum: 0,
+		currentTaskDesc: "",
 		...overrides,
 	}
 }
@@ -458,4 +477,93 @@ Some notes with Unicode: 日本語 🎉`
 			expect(archivedContent).toBe(planContent)
 		})
 	})
+
+	describe("isCycleTimedOut", () => {
+		test("returns false when timeout is disabled (0)", () => {
+			const state = createTestState({
+				cycleStartTime: new Date(Date.now() - 120 * 60 * 1000).toISOString(), // 2 hours ago
+			})
+			const config = createTestConfig({ cycleTimeoutMinutes: 0 })
+
+			expect(isCycleTimedOut(state, config)).toBe(false)
+		})
+
+		test("returns false when no start time is set", () => {
+			const state = createTestState({ cycleStartTime: undefined })
+			const config = createTestConfig({ cycleTimeoutMinutes: 60 })
+
+			expect(isCycleTimedOut(state, config)).toBe(false)
+		})
+
+		test("returns false when within timeout", () => {
+			const state = createTestState({
+				cycleStartTime: new Date(Date.now() - 30 * 60 * 1000).toISOString(), // 30 minutes ago
+			})
+			const config = createTestConfig({ cycleTimeoutMinutes: 60 })
+
+			expect(isCycleTimedOut(state, config)).toBe(false)
+		})
+
+		test("returns true when timeout exceeded", () => {
+			const state = createTestState({
+				cycleStartTime: new Date(Date.now() - 65 * 60 * 1000).toISOString(), // 65 minutes ago
+			})
+			const config = createTestConfig({ cycleTimeoutMinutes: 60 })
+
+			expect(isCycleTimedOut(state, config)).toBe(true)
+		})
+
+		test("returns true exactly at timeout", () => {
+			const state = createTestState({
+				cycleStartTime: new Date(Date.now() - 60 * 60 * 1000).toISOString(), // Exactly 60 minutes ago
+			})
+			const config = createTestConfig({ cycleTimeoutMinutes: 60 })
+
+			expect(isCycleTimedOut(state, config)).toBe(true)
+		})
+
+		test("works with short timeout values", () => {
+			const state = createTestState({
+				cycleStartTime: new Date(Date.now() - 2 * 60 * 1000).toISOString(), // 2 minutes ago
+			})
+			const config = createTestConfig({ cycleTimeoutMinutes: 1 })
+
+			expect(isCycleTimedOut(state, config)).toBe(true)
+		})
+	})
+
+	describe("getCycleElapsedTime", () => {
+		test("returns empty string when no start time", () => {
+			const state = createTestState({ cycleStartTime: undefined })
+
+			expect(getCycleElapsedTime(state)).toBe("")
+		})
+
+		test("returns seconds only for short durations", () => {
+			const state = createTestState({
+				cycleStartTime: new Date(Date.now() - 30 * 1000).toISOString(), // 30 seconds ago
+			})
+
+			const elapsed = getCycleElapsedTime(state)
+			expect(elapsed).toMatch(/^\d+s$/)
+		})
+
+		test("returns minutes and seconds for longer durations", () => {
+			const state = createTestState({
+				cycleStartTime: new Date(Date.now() - (5 * 60 + 30) * 1000).toISOString(), // 5m 30s ago
+			})
+
+			const elapsed = getCycleElapsedTime(state)
+			expect(elapsed).toMatch(/^\d+m \d+s$/)
+		})
+
+		test("handles hours worth of minutes", () => {
+			const state = createTestState({
+				cycleStartTime: new Date(Date.now() - 90 * 60 * 1000).toISOString(), // 90 minutes ago
+			})
+
+			const elapsed = getCycleElapsedTime(state)
+			expect(elapsed).toContain("90m")
+		})
+	})
 })

tests/state.test.ts

@@ -114,6 +114,7 @@ describe("state", () => {
 				currentTaskNum: 1,
 				currentTaskDesc: "Test task",
 				lastUpdate: "",
+				retryCount: 0,
 			}
 
 			await saveState(stateFile, state)
@@ -126,6 +127,29 @@ describe("state", () => {
 			expect(saved.taskIndex).toBe(1)
 			expect(saved.lastUpdate).toBeTruthy()
 		})
+
+		test("saves cycleStartTime when present", async () => {
+			const stateFile = join(TEST_DIR, "save-cycle-time.json")
+			const startTime = new Date().toISOString()
+			const state = {
+				cycle: 1,
+				phase: "build" as const,
+				taskIndex: 0,
+				totalTasks: 3,
+				currentTaskNum: 1,
+				currentTaskDesc: "Task",
+				lastUpdate: "",
+				retryCount: 0,
+				cycleStartTime: startTime,
+			}
+
+			await saveState(stateFile, state)
+
+			const content = await Bun.file(stateFile).text()
+			const saved = JSON.parse(content)
+
+			expect(saved.cycleStartTime).toBe(startTime)
+		})
 	})
 
 	describe("resetState", () => {