@bybrawe/opencode-loop 0.5.9 → 0.5.11

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.5.11
+
+- Added a watchdog loop in addition to one-shot due timers, so recurring jobs keep checking due work even if OpenCode misses an idle event or a due timeout gets effectively stuck behind a stale busy state.
+- Added stronger stale-active-run recovery. If a plugin-injected run is still marked active after the recovery window, the scheduler treats it as finished, finalizes it, and continues without waiting for another manual command such as `/loop-status`.
+- Refreshed session status with workspace-aware calls before trusting cached busy/retry state.
+- Kept `/compact` routing from v0.5.9: `session_compact` first, then `session.compact`, then summarize fallback.
+- This targets the observed case where `/loop 1m ...` only continued after manually running `/loop-status`.
+
 ## 0.5.9
 
 - Fixed stale-busy recovery for TUI sessions. Cached `busy` / `retry` status is now short-lived, so due jobs no longer get stuck at `due in every idle` after `/loop-status` or other short custom-command turns.

package/README.md

@@ -9,9 +9,14 @@ It is useful for long coding sessions, `progress.md` workflows, TODO automation,
 Repository: **ByBrawe/opencode-loop**  
 NPM package name: **@bybrawe/opencode-loop**
 
+### Scheduler heartbeat note
+
+v0.5.11 includes a referenced heartbeat scheduler. This is important in OpenCode TUI because local command hooks are event-driven: a normal `/loop-status` command can wake the plugin, but a timer-only loop should not depend on a user typing another command. The heartbeat periodically checks active loop jobs, clears stale completed runs, and starts due work only when the session appears idle.
+
+
 ## Current status
 
-**v0.5.9 is a reliability hotfix for stale-busy status and `/compact` routing.** It keeps the real due timer from v0.5.8, but no longer trusts a cached `busy` / `retry` session status forever. This fixes the case where `/loop-status` or another short custom-command turn could leave a loop showing `due in every idle` without firing. It also routes scheduled `/compact` through OpenCode's current TUI alias first, with fallback paths for older builds.
+**v0.5.11 is a reliability hotfix for recurring timers that only continued after manual activity.** It keeps the real due timer from v0.5.8 and the stale-busy recovery from v0.5.9, then adds a watchdog checker and stronger stale-active-run recovery. This targets the case where `/loop 1m ...` reaches its due time but does not fire until you run `/loop-status` or type another command. Scheduled `/compact` still routes through OpenCode's current TUI alias first, with fallback paths for older builds.
 
 The known update-related symptoms from older builds are fixed:
 
@@ -27,7 +32,7 @@ The known update-related symptoms from older builds are fixed:
 
 The TUI loop is still intentionally session-bound: it runs while OpenCode is open and the current session emits status/idle events. For long-running background work after closing the terminal or OpenCode, use `opencode-loopd`.
 
-## v0.5.9 quick behavior guide
+## v0.5.11 quick behavior guide
 
 OpenCode Loop has two triggers now:
 
@@ -74,7 +79,7 @@ Run a shell command every 10 minutes when idle.
 
 Experimental persistent goal mode: keep working until the goal is complete, blocked, paused, cleared, or a safety limit is reached.
 
-> Note: OpenCode custom command markdown still creates a tiny assistant turn for slash commands. v0.5.9 keeps these command templates short and asks the model to reply `OK`. The actual loop scheduling is handled locally by the plugin. If that short turn briefly makes OpenCode look busy, the loop now recovers by refreshing stale busy status on the next due retry.
+> Note: OpenCode custom command markdown still creates a tiny assistant turn for slash commands. v0.5.11 keeps these command templates short and asks the model to reply `OK`. The actual loop scheduling is handled locally by the plugin. If that short turn briefly makes OpenCode look busy, the loop now recovers with fresh status checks, stale-active-run recovery, and a watchdog that does not require another manual command.
 
 ## Why this exists
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bybrawe/opencode-loop",
-  "version": "0.5.9",
-  "description": "Claude Code/Codex style /loop and experimental goal mode for OpenCode: reliable timers, stale-busy recovery, idle-safe loops, scheduled commands, compact scheduling, verification, checkpoints, and persistent coding goals.",
+  "version": "0.5.11",
+  "description": "Claude Code/Codex style /loop and experimental goal mode for OpenCode: heartbeat scheduler, idle-safe loops, scheduled commands, compact scheduling, verification, checkpoints, and persistent coding goals.",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/index.js

@@ -4,12 +4,14 @@ import { spawn } from "node:child_process"
 
 const SERVICE = "opencode-loop"
 const STATE_DIR = ".opencode/opencode-loop"
-const DEFAULT_ACTIVE_GUARD_MS = 60_000
+const DEFAULT_ACTIVE_GUARD_MS = 45_000
+const STALE_ACTIVE_RECOVERY_MS = 45_000
 const IDLE_DEBOUNCE_MS = 1_200
 const BUSY_RETRY_MS = 5_000
 const SESSION_STATUS_CACHE_MS = 1_500
 const MIN_DUE_TIMER_MS = 250
 const MAX_DUE_TIMER_MS = 2_147_000_000
+const HEARTBEAT_MS = 2_500
 const MAX_SCAN_FILES = 200
 const MAX_SCAN_BYTES = 2_000_000
 const GOAL_REPORT_DIR = "goals"
@@ -19,6 +21,10 @@ const activeRuns = new Map()
 const handledCommands = new Map()
 const idleTimers = new Map()
 const dueTimers = new Map()
+const watchdogTimers = new Map()
+const runLocks = new Map()
+const knownSessions = new Map()
+let heartbeatTimer
 const sessionStatuses = new Map()
 const sessionStatusSeenAt = new Map()
 
@@ -442,7 +448,7 @@ async function say(client, sessionID, text) {
   } catch {}
 }
 
-function commandKey(sessionID, name, args) { return `${sessionID || "no-session"}:${name || ""}:${args || ""}` }
+function commandKey(sessionID, name, args) { return `${sessionID || "no-session"}:${name || ""}:${normalizeArgsForKey(args)}` }
 function markHandled(sessionID, name, args) {
   handledCommands.set(commandKey(sessionID, name, args), now())
   for (const [key, time] of handledCommands.entries()) if (now() - time > 30_000) handledCommands.delete(key)
@@ -454,6 +460,41 @@ function wasHandled(sessionID, name, args) {
 
 function commandName(name) { return String(name || "") }
 function isPreset(name) { return ["loop-dev", "loop-testfix", "loop-compact", "loop-progress", "loop-safe-dev", "loop-command", "loop-cmd", "loop-prompt", "loop-ask", "loop-shell"].includes(name) }
+
+function normalizeArgsForKey(args) {
+  if (args === undefined || args === null) return ""
+  if (typeof args === "string") return args.trim().replace(/\s+/g, " ")
+  if (Array.isArray(args)) return args.map(normalizeArgsForKey).join(" ").trim().replace(/\s+/g, " ")
+  try { return JSON.stringify(args) } catch { return String(args) }
+}
+
+function rememberSession(directory, client, sessionID) {
+  if (!sessionID) return
+  knownSessions.set(sessionID, { directory, client, seenAt: now() })
+  startHeartbeat()
+}
+
+function startHeartbeat() {
+  if (heartbeatTimer) return
+  heartbeatTimer = setInterval(() => {
+    for (const [sessionID, info] of [...knownSessions.entries()]) {
+      if (!info || now() - (info.seenAt || 0) > 12 * 60 * 60 * 1000) {
+        knownSessions.delete(sessionID)
+        continue
+      }
+      Promise.resolve()
+        .then(async () => {
+          await finalizeActiveRun(info.directory, info.client, sessionID, { forceStale: true })
+          await maybeRunDueJobs(info.directory, info.client, sessionID, { heartbeat: true })
+        })
+        .catch((error) => appendLoopLog(info.directory, "heartbeat-error", { sessionID, error: sdkErrorMessage(error) }).catch(() => {}))
+    }
+    if (!knownSessions.size && heartbeatTimer) {
+      clearInterval(heartbeatTimer)
+      heartbeatTimer = undefined
+    }
+  }, HEARTBEAT_MS)
+}
 function presetDefaults(name, args) {
   const [maybeDuration, rest] = splitFirst(args)
   const parsed = parseDuration(maybeDuration)
@@ -757,7 +798,34 @@ function updateSessionStatusFromEvent(event) {
   return undefined
 }
 
-async function sessionStatusType(client, sessionID) {
+function staleActiveRun(sessionID) {
+  const active = activeRuns.get(sessionID)
+  if (!active) return false
+  const age = now() - (active.startedAt || 0)
+  const configured = Number(active.job?.staleActiveRecoveryMs || active.job?.activeRecoveryMs || 0)
+  const threshold = Number.isFinite(configured) && configured > 0 ? configured : STALE_ACTIVE_RECOVERY_MS
+  return age >= threshold
+}
+
+async function readLiveSessionStatus(client, sessionID, directory) {
+  const argsList = []
+  if (directory) argsList.push({ workspace: directory }, { directory })
+  argsList.push({})
+  for (const args of argsList) {
+    try {
+      const result = await client.session.status(args)
+      const error = sdkError(result)
+      if (error) continue
+      const data = sdkData(result)
+      const status = data?.[sessionID]
+      const type = status && typeof status === "object" ? status.type : undefined
+      if (typeof type === "string") return { type, source: "sdk" }
+    } catch {}
+  }
+  return undefined
+}
+
+async function sessionStatusType(client, sessionID, directory, options = {}) {
   const cached = sessionStatuses.get(sessionID)
   const seenAt = sessionStatusSeenAt.get(sessionID) || 0
 
@@ -769,25 +837,30 @@ async function sessionStatusType(client, sessionID) {
   if (cached === "idle") return cached
   if (cached && now() - seenAt < SESSION_STATUS_CACHE_MS) return cached
 
-  try {
-    const data = await sdkCall(client.session.status.bind(client.session), {}, undefined)
-    const status = data?.[sessionID]
-    const type = status && typeof status === "object" ? status.type : undefined
-    if (typeof type === "string") {
-      sessionStatuses.set(sessionID, type)
+  const live = await readLiveSessionStatus(client, sessionID, directory)
+  if (live?.type) {
+    // Some OpenCode 1.15.x TUI builds can leave session.status at busy after a
+    // plugin-injected turn until the next user command touches the session.
+    // When the only reason we still think the session is busy is our own stale
+    // active-run guard, recover instead of waiting for another manual command.
+    if ((live.type === "busy" || live.type === "retry") && options.recoverStaleActive !== false && staleActiveRun(sessionID)) {
+      sessionStatuses.set(sessionID, "idle")
       sessionStatusSeenAt.set(sessionID, now())
-      return type
+      return "idle"
     }
-  } catch {}
+    sessionStatuses.set(sessionID, live.type)
+    sessionStatusSeenAt.set(sessionID, now())
+    return live.type
+  }
 
-  const fallback = activeRuns.has(sessionID) ? "busy" : "idle"
+  const fallback = activeRuns.has(sessionID) && !staleActiveRun(sessionID) ? "busy" : "idle"
   sessionStatuses.set(sessionID, fallback)
   sessionStatusSeenAt.set(sessionID, now())
   return fallback
 }
 
-async function sessionIsIdle(client, sessionID) {
-  return await sessionStatusType(client, sessionID) === "idle"
+async function sessionIsIdle(client, sessionID, directory, options = {}) {
+  return await sessionStatusType(client, sessionID, directory, options) === "idle"
 }
 
 function scheduleIdleWork(directory, client, sessionID) {
@@ -797,12 +870,12 @@ function scheduleIdleWork(directory, client, sessionID) {
     idleTimers.delete(sessionID)
     Promise.resolve()
       .then(async () => {
-        if (!await sessionIsIdle(client, sessionID)) {
+        if (!await sessionIsIdle(client, sessionID, directory)) {
           await scheduleDueWork(directory, client, sessionID, BUSY_RETRY_MS)
           return
         }
         await finalizeActiveRun(directory, client, sessionID)
-        if (!await sessionIsIdle(client, sessionID)) {
+        if (!await sessionIsIdle(client, sessionID, directory)) {
           await scheduleDueWork(directory, client, sessionID, BUSY_RETRY_MS)
           return
         }
@@ -836,6 +909,37 @@ function nextDueDelay(state) {
   return Math.max(0, soonest - current)
 }
 
+async function startWatchdog(directory, client, sessionID) {
+  if (watchdogTimers.has(sessionID)) return
+  const timer = setInterval(() => {
+    Promise.resolve()
+      .then(async () => {
+        const state = await readState(directory, sessionID)
+        const delay = nextDueDelay(state)
+        const hasJobs = (state.jobs || []).some((job) => job.enabled !== false && !job.paused && (!isGoalJob(job) || !["completed", "blocked", "cleared"].includes(job.goalStatus)))
+        if (!hasJobs || !Number.isFinite(delay)) {
+          const existing = watchdogTimers.get(sessionID)
+          if (existing) clearInterval(existing)
+          watchdogTimers.delete(sessionID)
+          return
+        }
+        if (delay <= 0) await maybeRunDueJobs(directory, client, sessionID)
+        else await scheduleDueWork(directory, client, sessionID)
+      })
+      .catch((error) => appendLoopLog(directory, "watchdog-error", { sessionID, error: sdkErrorMessage(error) }).catch(() => {}))
+  }, Math.max(1_000, BUSY_RETRY_MS))
+  // Keep this interval referenced. In current OpenCode TUI builds, plugin hooks
+  // are event-driven; a referenced watchdog helps scheduled loops wake up even
+  // when no manual /loop-status command is typed.
+  watchdogTimers.set(sessionID, timer)
+}
+
+function stopWatchdog(sessionID) {
+  const timer = watchdogTimers.get(sessionID)
+  if (timer) clearInterval(timer)
+  watchdogTimers.delete(sessionID)
+}
+
 async function scheduleDueWork(directory, client, sessionID, minDelayMs = 0) {
   const previous = dueTimers.get(sessionID)
   if (previous) clearTimeout(previous)
@@ -852,12 +956,12 @@ async function scheduleDueWork(directory, client, sessionID, minDelayMs = 0) {
     dueTimers.delete(sessionID)
     Promise.resolve()
       .then(async () => {
-        if (!await sessionIsIdle(client, sessionID)) {
+        if (!await sessionIsIdle(client, sessionID, directory)) {
           await scheduleDueWork(directory, client, sessionID, BUSY_RETRY_MS)
           return
         }
         await finalizeActiveRun(directory, client, sessionID)
-        if (!await sessionIsIdle(client, sessionID)) {
+        if (!await sessionIsIdle(client, sessionID, directory)) {
           await scheduleDueWork(directory, client, sessionID, BUSY_RETRY_MS)
           return
         }
@@ -869,6 +973,7 @@ async function scheduleDueWork(directory, client, sessionID, minDelayMs = 0) {
       })
   }, wait)
   dueTimers.set(sessionID, timer)
+  await startWatchdog(directory, client, sessionID)
 }
 
 function dueJobs(state, force = false) {
@@ -1130,112 +1235,128 @@ ${prompt}` }] } })
 }
 
 async function maybeRunDueJobs(directory, client, sessionID, options = {}) {
+  rememberSession(directory, client, sessionID)
   const reschedule = async (minDelayMs = 0) => { await scheduleDueWork(directory, client, sessionID, minDelayMs) }
 
-  if (!await sessionIsIdle(client, sessionID)) {
-    if (options.force) await toast(client, "Loop queued: session is busy; it will run on the next idle check.", "info")
-    await reschedule(BUSY_RETRY_MS)
-    return
-  }
-  const active = activeRuns.get(sessionID)
-  if (active && active.job?.noOverlap !== false && now() - active.startedAt < (active.job?.timeoutMs || DEFAULT_ACTIVE_GUARD_MS)) {
+  if (runLocks.has(sessionID)) {
     await reschedule(BUSY_RETRY_MS)
     return
   }
+  runLocks.set(sessionID, now())
+  let job
+  try {
+    await finalizeActiveRun(directory, client, sessionID, { forceStale: true })
+    if (!await sessionIsIdle(client, sessionID, directory)) {
+      if (options.force) await toast(client, "Loop queued: session is busy; it will run on the next idle check.", "info")
+      await reschedule(BUSY_RETRY_MS)
+      return
+    }
 
-  const state = await readState(directory, sessionID)
-  for (const job of state.jobs || []) {
-    if (job.watchPaths?.length && !job.paused && job.enabled && await watchChanged(directory, job)) job.lastRunAt = 0
-  }
-  let due = dueJobs(state, options.force)
-  if (!due.length) {
-    await writeState(directory, sessionID, state)
-    await reschedule()
-    return
-  }
-  let job = due[0]
+    const active = activeRuns.get(sessionID)
+    const activeAge = active ? now() - (active.startedAt || 0) : 0
+    const activeGuard = active?.job?.timeoutMs || active?.job?.activeRecoveryMs || DEFAULT_ACTIVE_GUARD_MS
+    if (active && active.job?.noOverlap !== false && activeAge < activeGuard) {
+      await reschedule(BUSY_RETRY_MS)
+      return
+    }
+    if (active && activeAge >= activeGuard) clearActiveRun(sessionID)
 
-  if (job.maxRuntimeMs > 0 && now() - Date.parse(job.createdAt || new Date().toISOString()) >= job.maxRuntimeMs) {
-    state.jobs = (state.jobs || []).filter((candidate) => candidate.id !== job.id)
-    await writeState(directory, sessionID, state)
-    await notifyJob(directory, job, "max_runtime_reached")
-    await toast(client, `Loop stopped by --max-runtime: ${job.name || job.id}`, "success")
-    await appendLoopLog(directory, "max-runtime", { sessionID, job: job.name || job.id })
-    await reschedule()
-    return
-  }
-  if (job.stopFile && await pathExists(path.resolve(directory, job.stopFile))) {
-    state.jobs = (state.jobs || []).filter((candidate) => candidate.id !== job.id)
-    await writeState(directory, sessionID, state)
-    await notifyJob(directory, job, "stop_file")
-    await toast(client, "Loop stopped by --stop-file: " + job.stopFile, "success")
-    await reschedule()
-    return
-  }
-  if (await untilReached(directory, job)) {
-    state.jobs = (state.jobs || []).filter((candidate) => candidate.id !== job.id)
-    await writeState(directory, sessionID, state)
-    await notifyJob(directory, job, "until_reached")
-    await toast(client, `Loop stopped by --until: ${job.until}`, "success")
-    await reschedule()
-    return
-  }
+    const state = await readState(directory, sessionID)
+    for (const candidate of state.jobs || []) {
+      if (candidate.watchPaths?.length && !candidate.paused && candidate.enabled && await watchChanged(directory, candidate)) candidate.lastRunAt = 0
+    }
+    const due = dueJobs(state, options.force)
+    if (!due.length) {
+      await writeState(directory, sessionID, state)
+      await reschedule()
+      return
+    }
+    job = due[0]
 
-  if (job.preflightCommand) {
-    if (job.safe && dangerousShell(job.preflightCommand)) {
-      job.paused = true
+    if (job.maxRuntimeMs > 0 && now() - Date.parse(job.createdAt || new Date().toISOString()) >= job.maxRuntimeMs) {
+      state.jobs = (state.jobs || []).filter((candidate) => candidate.id !== job.id)
       await writeState(directory, sessionID, state)
-      await notifyJob(directory, job, "preflight_blocked")
-      await toast(client, "Preflight blocked in safe mode and loop paused: " + job.preflightCommand, "error")
+      await notifyJob(directory, job, "max_runtime_reached")
+      await toast(client, `Loop stopped by --max-runtime: ${job.name || job.id}`, "success")
+      await appendLoopLog(directory, "max-runtime", { sessionID, job: job.name || job.id })
       await reschedule()
       return
     }
-    const preflight = await runShellCommand(job.preflightCommand, directory, job.timeoutMs || 300_000)
-    await appendLoopLog(directory, "preflight", { sessionID, job: job.name || job.id, command: job.preflightCommand, code: preflight.code })
-    if (preflight.code !== 0) {
-      job.paused = true
-      job.failureCount = (job.failureCount || 0) + 1
-      job.lastPreflightFailure = (job.preflightCommand + "\nexit=" + preflight.code + "\n" + preflight.stdout + "\n" + preflight.stderr).slice(0, 4000)
-      state.jobs = (state.jobs || []).map((candidate) => candidate.id === job.id ? job : candidate)
+    if (job.stopFile && await pathExists(path.resolve(directory, job.stopFile))) {
+      state.jobs = (state.jobs || []).filter((candidate) => candidate.id !== job.id)
       await writeState(directory, sessionID, state)
-      await notifyJob(directory, job, "preflight_failed")
-      await toast(client, "Preflight failed and loop paused: " + job.preflightCommand, "warning")
+      await notifyJob(directory, job, "stop_file")
+      await toast(client, "Loop stopped by --stop-file: " + job.stopFile, "success")
       await reschedule()
       return
     }
-  }
-
-  job = await ensureBranch(directory, job, client, sessionID)
-  job = await maybeCompact(client, sessionID, job)
-  job.lastRunAt = now()
-  job.runCount = (job.runCount || 0) + 1
-  if (job.maxRuns > 0 && job.runCount >= job.maxRuns) {
-    job.enabled = false
-    await notifyJob(directory, job, "max_runs_reached")
-  }
-  state.jobs = (state.jobs || []).map((candidate) => candidate.id === job.id ? job : candidate)
-  await writeState(directory, sessionID, state)
-  await appendLoopLog(directory, "run", { sessionID, job: job.name || job.id, runCount: job.runCount })
-  await toast(client, `Loop running: ${job.name || job.id}`, "info")
-
-  try {
-    const result = await fireAction(directory, client, sessionID, job)
-    if (!result.startsAssistantTurn) {
-      const fresh = await readState(directory, sessionID)
-      fresh.jobs = (fresh.jobs || []).filter((candidate) => candidate.enabled !== false || isGoalJob(candidate))
-      await writeState(directory, sessionID, fresh)
+    if (await untilReached(directory, job)) {
+      state.jobs = (state.jobs || []).filter((candidate) => candidate.id !== job.id)
+      await writeState(directory, sessionID, state)
+      await notifyJob(directory, job, "until_reached")
+      await toast(client, `Loop stopped by --until: ${job.until}`, "success")
       await reschedule()
       return
     }
-    let timer
-    if (job.timeoutMs > 0) timer = setTimeout(() => { fireSdk(client, "session.abort", client.session.abort.bind(client.session), { sessionID }, { path: { id: sessionID }, body: {} }); toast(client, `Loop timeout fired: ${job.name || job.id}`, "warning").catch(() => {}) }, job.timeoutMs)
-    activeRuns.set(sessionID, { jobId: job.id, job, startedAt: now(), timer })
-    await reschedule(BUSY_RETRY_MS)
-  } catch (error) {
-    clearActiveRun(sessionID)
-    await toast(client, `Loop job failed: ${error instanceof Error ? error.message : String(error)}`, "error")
-    await appendLoopLog(directory, "error", { sessionID, job: job.name || job.id, error: error instanceof Error ? error.message : String(error) })
-    await reschedule(BUSY_RETRY_MS)
+
+    if (job.preflightCommand) {
+      if (job.safe && dangerousShell(job.preflightCommand)) {
+        job.paused = true
+        await writeState(directory, sessionID, state)
+        await notifyJob(directory, job, "preflight_blocked")
+        await toast(client, "Preflight blocked in safe mode and loop paused: " + job.preflightCommand, "error")
+        await reschedule()
+        return
+      }
+      const preflight = await runShellCommand(job.preflightCommand, directory, job.timeoutMs || 300_000)
+      await appendLoopLog(directory, "preflight", { sessionID, job: job.name || job.id, command: job.preflightCommand, code: preflight.code })
+      if (preflight.code !== 0) {
+        job.paused = true
+        job.failureCount = (job.failureCount || 0) + 1
+        job.lastPreflightFailure = (job.preflightCommand + "\nexit=" + preflight.code + "\n" + preflight.stdout + "\n" + preflight.stderr).slice(0, 4000)
+        state.jobs = (state.jobs || []).map((candidate) => candidate.id === job.id ? job : candidate)
+        await writeState(directory, sessionID, state)
+        await notifyJob(directory, job, "preflight_failed")
+        await toast(client, "Preflight failed and loop paused: " + job.preflightCommand, "warning")
+        await reschedule()
+        return
+      }
+    }
+
+    job = await ensureBranch(directory, job, client, sessionID)
+    job = await maybeCompact(client, sessionID, job)
+    job.lastRunAt = now()
+    job.runCount = (job.runCount || 0) + 1
+    if (job.maxRuns > 0 && job.runCount >= job.maxRuns) {
+      job.enabled = false
+      await notifyJob(directory, job, "max_runs_reached")
+    }
+    state.jobs = (state.jobs || []).map((candidate) => candidate.id === job.id ? job : candidate)
+    await writeState(directory, sessionID, state)
+    await appendLoopLog(directory, "run", { sessionID, job: job.name || job.id, runCount: job.runCount })
+    await toast(client, `Loop running: ${job.name || job.id}`, "info")
+
+    try {
+      const result = await fireAction(directory, client, sessionID, job)
+      if (!result.startsAssistantTurn) {
+        const fresh = await readState(directory, sessionID)
+        fresh.jobs = (fresh.jobs || []).filter((candidate) => candidate.enabled !== false || isGoalJob(candidate))
+        await writeState(directory, sessionID, fresh)
+        await reschedule()
+        return
+      }
+      let timer
+      if (job.timeoutMs > 0) timer = setTimeout(() => { fireSdk(client, "session.abort", client.session.abort.bind(client.session), { sessionID }, { path: { id: sessionID }, body: {} }); toast(client, `Loop timeout fired: ${job.name || job.id}`, "warning").catch(() => {}) }, job.timeoutMs)
+      activeRuns.set(sessionID, { jobId: job.id, job, startedAt: now(), timer })
+      await reschedule(BUSY_RETRY_MS)
+    } catch (error) {
+      clearActiveRun(sessionID)
+      await toast(client, `Loop job failed: ${error instanceof Error ? error.message : String(error)}`, "error")
+      await appendLoopLog(directory, "error", { sessionID, job: job?.name || job?.id, error: error instanceof Error ? error.message : String(error) })
+      await reschedule(BUSY_RETRY_MS)
+    }
+  } finally {
+    runLocks.delete(sessionID)
   }
 }
 
@@ -1256,6 +1377,7 @@ async function addLoop(directory, client, sessionID, args, defaults = {}) {
   const parsed = parseLoopArgs(args, defaults)
   if (!parsed.ok) { await toast(client, parsed.error, "warning"); return }
   if (parsed.job.watchPaths.length) parsed.job.watchSnapshot = await snapshotPaths(directory, parsed.job.watchPaths)
+  if (!parsed.job.activeRecoveryMs) parsed.job.activeRecoveryMs = Math.max(20_000, Math.min(90_000, (parsed.job.intervalMs || 0) + 10_000))
   if (parsed.job.dryRun) { await toast(client, `Loop dry run: ${jobLabel(parsed.job)}`, "info"); await say(client, sessionID, "OpenCode loop dry run:\n```json\n" + JSON.stringify(parsed.job, null, 2) + "\n```"); return }
   const state = await readState(directory, sessionID)
   const jobs = Array.isArray(state.jobs) ? state.jobs : []
@@ -1291,6 +1413,7 @@ async function stopLoop(directory, client, sessionID, args) {
     await removeState(directory, sessionID)
     clearActiveRun(sessionID)
     const due = dueTimers.get(sessionID); if (due) clearTimeout(due); dueTimers.delete(sessionID)
+    stopWatchdog(sessionID)
     await toast(client, "All loops stopped for this session.", "success")
     return
   }
@@ -1467,6 +1590,7 @@ async function handleCommand(directory, client, input, fallbackName, fallbackArg
   const sessionID = input?.sessionID
   const args = input?.arguments ?? fallbackArgs ?? ""
   if (!sessionID || !name) return false
+  rememberSession(directory, client, sessionID)
   if (wasHandled(sessionID, name, args)) return true
   markHandled(sessionID, name, args)
 
@@ -1551,6 +1675,7 @@ export const OpenCodeLoopPlugin = async ({ client, directory }) => {
         await handleCommand(directory, client, props, props.name, props.arguments)
       }
       const statusUpdate = updateSessionStatusFromEvent(event)
+      if (statusUpdate?.sessionID) rememberSession(directory, client, statusUpdate.sessionID)
       if (statusUpdate?.idle) scheduleIdleWork(directory, client, statusUpdate.sessionID)
     },
   }