@bybrawe/opencode-loop 0.5.33 → 0.5.35

package/src/source/runtime/executor.js

@@ -10,9 +10,12 @@ import { createCompactionRuntime } from "./compaction.js"
 import { createActionDispatcher } from "./action-dispatch.js"
 import { createRunFinalizationRuntime } from "./run-finalization.js"
 import { createRunAdmissionRuntime } from "./run-admission.js"
+import { isTransientNetworkError, networkRetryDelayMs, refundInfrastructureRun } from "./network-recovery.js"
 
 const DEFAULT_ACTIVE_GUARD_MS = 45_000
 const DEFAULT_BUSY_RETRY_MS = 5_000
+const DEFAULT_PROVIDER_RETRY_WATCHDOG_MS = 2 * 60_000
+const DEFAULT_NETWORK_RETRY_MAX_MS = 60_000
 
 function requireFunction(value, label) {
   if (typeof value !== "function") throw new TypeError(`createLoopExecutor requires ${label}`)
@@ -51,9 +54,16 @@ export function createLoopExecutor(options = {}) {
   const busyRetryMs = Number.isFinite(Number(options.busyRetryMs)) && Number(options.busyRetryMs) > 0
     ? Number(options.busyRetryMs)
     : DEFAULT_BUSY_RETRY_MS
+  const providerRetryWatchdogMs = Number.isFinite(Number(options.providerRetryWatchdogMs)) && Number(options.providerRetryWatchdogMs) > 0
+    ? Number(options.providerRetryWatchdogMs)
+    : DEFAULT_PROVIDER_RETRY_WATCHDOG_MS
+  const networkRetryMaxMs = Number.isFinite(Number(options.networkRetryMaxMs)) && Number(options.networkRetryMaxMs) > 0
+    ? Number(options.networkRetryMaxMs)
+    : DEFAULT_NETWORK_RETRY_MAX_MS
 
   const activeRuns = new Map()
   const runLocks = new Map()
+  const retryRuns = new Map()
 
   const statusRuntime = createSessionStatusRuntime({
     activeRuns,
@@ -67,6 +77,7 @@ export function createLoopExecutor(options = {}) {
     updateSessionStatusFromEvent,
     staleActiveRun,
     canFinalizeActiveRun,
+    sessionStatusType,
     sessionIsIdle,
     markSessionStatus,
     clearSessionStatus,
@@ -129,6 +140,7 @@ export function createLoopExecutor(options = {}) {
     if (active?.timer) clearTimeout(active.timer)
     compactionRuntime.clearForActiveRun(sessionID, active)
     activeRuns.delete(sessionID)
+    retryRuns.delete(sessionID)
   }
 
   function disposeSession(sessionID) {
@@ -138,32 +150,116 @@ export function createLoopExecutor(options = {}) {
     clearSessionStatus(sessionID)
   }
 
+  async function persistInfrastructureRefund(directory, sessionID, active, input = {}) {
+    const state = await readState(directory, sessionID)
+    const job = (state.jobs || []).find((candidate) => candidate.id === active.jobId)
+    if (!job) return { job: undefined, delayMs: busyRetryMs }
+    refundInfrastructureRun(job, {
+      runCount: active.job?.runCount,
+      previousLastRunAt: active.previousLastRunAt,
+      disabledByMaxRuns: active.disabledByMaxRuns,
+    }, {
+      reason: input.reason,
+      error: input.error,
+      now: now(),
+    })
+    state.jobs = (state.jobs || []).map((candidate) => candidate.id === job.id ? job : candidate)
+    await writeState(directory, sessionID, state)
+    const delayMs = networkRetryDelayMs(job.infrastructureFailureCount || 1, busyRetryMs, networkRetryMaxMs)
+    return { job, delayMs }
+  }
+
   async function recoverActiveDispatchFailure(directory, client, sessionID, jobId, runToken, error) {
     const active = activeRuns.get(sessionID)
     if (!active || active.jobId !== jobId || active.runToken !== runToken) return false
 
+    const transient = isTransientNetworkError(error)
+    const snapshot = active
     clearActiveRun(sessionID)
     clearSessionStatus(sessionID)
 
     const message = errorMessage(error)
-    const state = await readState(directory, sessionID)
-    const job = (state.jobs || []).find((candidate) => candidate.id === jobId)
+    let state = await readState(directory, sessionID)
+    let job = (state.jobs || []).find((candidate) => candidate.id === jobId)
+    let retryDelay = busyRetryMs
     if (job) {
-      job.failureCount = (job.failureCount || 0) + 1
-      job.lastFailureReason = "dispatch_failed"
-      job.lastDispatchFailure = message.slice(0, 4000)
-      job.lastDispatchFailureAt = now()
-      if (job.maxFailures > 0 && job.failureCount >= job.maxFailures) {
-        job.paused = true
-        await notifyJob(directory, job, "dispatch_failed")
+      if (transient) {
+        const refunded = await persistInfrastructureRefund(directory, sessionID, snapshot, {
+          reason: "dispatch_failed_transient",
+          error,
+        })
+        job = refunded.job
+        retryDelay = refunded.delayMs
+        state = await readState(directory, sessionID)
+      } else {
+        job.failureCount = (job.failureCount || 0) + 1
+        job.lastFailureReason = "dispatch_failed"
+        job.lastDispatchFailure = message.slice(0, 4000)
+        job.lastDispatchFailureAt = now()
+        if (job.maxFailures > 0 && job.failureCount >= job.maxFailures) {
+          job.paused = true
+          await notifyJob(directory, job, "dispatch_failed")
+        }
+        state.jobs = (state.jobs || []).map((candidate) => candidate.id === job.id ? job : candidate)
+        await writeState(directory, sessionID, state)
       }
-      state.jobs = (state.jobs || []).map((candidate) => candidate.id === job.id ? job : candidate)
-      await writeState(directory, sessionID, state)
     }
 
-    await appendLoopLog(directory, "dispatch-error", { sessionID, job: job?.name || jobId, error: message })
-    await toast(client, `Loop dispatch failed${job?.paused ? " and paused" : ""}: ${message}`, job?.paused ? "error" : "warning")
-    await scheduleDueWork(directory, client, sessionID, busyRetryMs)
+    await appendLoopLog(directory, transient ? "network-dispatch-error" : "dispatch-error", {
+      sessionID,
+      job: job?.name || jobId,
+      error: message,
+      ...(transient ? { retryInMs: retryDelay } : {}),
+    })
+    if (transient) {
+      await toast(client, `Loop network dispatch failed; retrying when the session recovers: ${message}`, "warning")
+    } else {
+      await toast(client, `Loop dispatch failed${job?.paused ? " and paused" : ""}: ${message}`, job?.paused ? "error" : "warning")
+    }
+    await scheduleDueWork(directory, client, sessionID, retryDelay)
+    return true
+  }
+
+  async function recoverStuckProviderRetry(directory, client, sessionID) {
+    const active = activeRuns.get(sessionID)
+    if (!active || active.compactionOnly) {
+      retryRuns.delete(sessionID)
+      return false
+    }
+    const current = retryRuns.get(sessionID)
+    if (!current || current.runToken !== active.runToken) {
+      retryRuns.set(sessionID, { runToken: active.runToken, since: now() })
+      return false
+    }
+    if (now() - current.since < providerRetryWatchdogMs) return false
+
+    const snapshot = active
+    try {
+      if (client?.session?.abort) {
+        await fireSdk(
+          client,
+          "session.abort provider retry watchdog",
+          client.session.abort.bind(client.session),
+          { path: { id: sessionID }, body: {} },
+          { path: { sessionID }, body: {} },
+          { sessionID },
+        )
+      }
+    } catch {}
+    clearActiveRun(sessionID)
+    clearSessionStatus(sessionID)
+    const refunded = await persistInfrastructureRefund(directory, sessionID, snapshot, {
+      reason: "provider_retry_watchdog",
+      error: `OpenCode session.status stayed retry for ${providerRetryWatchdogMs}ms`,
+    })
+    await appendLoopLog(directory, "provider-retry-recovery", {
+      sessionID,
+      job: refunded.job?.name || snapshot.jobId,
+      retryForMs: now() - current.since,
+      retryInMs: refunded.delayMs,
+    })
+    await toast(client, "Loop provider retry exceeded the watchdog; the Loop-owned turn was released and will retry with backoff.", "warning")
+    await scheduleDueWork(directory, client, sessionID, refunded.delayMs)
     return true
   }
 
@@ -217,13 +313,22 @@ export function createLoopExecutor(options = {}) {
     }
     runLocks.set(sessionID, now())
     let job
+    let previousLastRunAt = 0
+    let disabledByMaxRuns = false
     try {
       await finalizeActiveRun(directory, client, sessionID, { requireIdle: true, forceStale: true })
-      if (!await sessionIsIdle(client, sessionID, directory)) {
+      const statusType = await sessionStatusType(client, sessionID, directory)
+      if (statusType !== "idle") {
+        if (statusType === "retry") {
+          if (await recoverStuckProviderRetry(directory, client, sessionID)) return
+        } else {
+          retryRuns.delete(sessionID)
+        }
         if (runOptions.force) await toast(client, "Loop queued: session is busy; it will run on the next idle check.", "info")
         await reschedule(busyRetryMs)
         return
       }
+      retryRuns.delete(sessionID)
 
       const active = activeRuns.get(sessionID)
       const activeAge = active ? now() - (active.startedAt || 0) : 0
@@ -286,9 +391,11 @@ export function createLoopExecutor(options = {}) {
 
       if (runNowRequested) delete job.runNowRequestedAt
       job.watchTriggered = false
+      previousLastRunAt = Number(job.lastRunAt || 0)
       job.lastRunAt = now()
       job.runCount = (job.runCount || 0) + 1
-      if (job.maxRuns > 0 && job.runCount >= job.maxRuns) {
+      disabledByMaxRuns = job.maxRuns > 0 && job.runCount >= job.maxRuns
+      if (disabledByMaxRuns) {
         job.enabled = false
         await notifyJob(directory, job, "max_runs_reached")
       }
@@ -337,6 +444,8 @@ export function createLoopExecutor(options = {}) {
           timer,
           runToken,
           compactionAction: result.compaction === true,
+          previousLastRunAt,
+          disabledByMaxRuns,
         })
         if (result.compaction && compactionRuntime.isCompleted(sessionID, job.id)) {
           await compactionRuntime.finalize(directory, client, sessionID)
@@ -352,6 +461,24 @@ export function createLoopExecutor(options = {}) {
         await reschedule(busyRetryMs)
       } catch (error) {
         clearActiveRun(sessionID)
+        if (isTransientNetworkError(error) && job) {
+          const stateAfterFailure = await readState(directory, sessionID)
+          const persisted = (stateAfterFailure.jobs || []).find((candidate) => candidate.id === job.id)
+          if (persisted) {
+            refundInfrastructureRun(persisted, {
+              runCount: job.runCount,
+              previousLastRunAt,
+              disabledByMaxRuns,
+            }, { reason: "action_dispatch_transient", error, now: now() })
+            stateAfterFailure.jobs = (stateAfterFailure.jobs || []).map((candidate) => candidate.id === persisted.id ? persisted : candidate)
+            await writeState(directory, sessionID, stateAfterFailure)
+            const delayMs = networkRetryDelayMs(persisted.infrastructureFailureCount || 1, busyRetryMs, networkRetryMaxMs)
+            await appendLoopLog(directory, "network-action-error", { sessionID, job: persisted.name || persisted.id, error: errorMessage(error), retryInMs: delayMs })
+            await toast(client, "Loop action hit a transient network failure; the logical run was refunded and will retry.", "warning")
+            await reschedule(delayMs)
+            return
+          }
+        }
         await toast(client, `Loop job failed: ${error instanceof Error ? error.message : String(error)}`, "error")
         await appendLoopLog(directory, "error", {
           sessionID,
@@ -370,9 +497,11 @@ export function createLoopExecutor(options = {}) {
     clearActiveRun,
     disposeSession,
     recoverActiveDispatchFailure,
+    recoverStuckProviderRetry,
     finalizeActiveRun,
     fireAction,
     maybeRunDueJobs,
+    sessionStatusType,
     sessionIsIdle,
     updateSessionStatusFromEvent,
     markSessionStatus,

package/src/source/runtime/loop-diagnostics.js

@@ -0,0 +1,45 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { stateDir } from "../core/state.js"
+import { scheduleDescription, scheduleState } from "./schedule-policy.js"
+
+export function describeJobScheduling(job, current = Date.now()) {
+  return {
+    schedule: scheduleDescription(job),
+    state: scheduleState(job, current),
+  }
+}
+
+export async function listPersistedLoopSessions(directory, currentSessionID) {
+  const root = stateDir(directory)
+  let names
+  try {
+    names = await fs.readdir(root)
+  } catch (error) {
+    if (error?.code === "ENOENT") return []
+    return []
+  }
+
+  const sessions = []
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue
+    const sessionID = name.slice(0, -5)
+    try {
+      const parsed = JSON.parse(await fs.readFile(path.join(root, name), "utf8"))
+      const jobs = Array.isArray(parsed?.jobs) ? parsed.jobs : []
+      const enabled = jobs.filter((job) => job?.enabled !== false && !job?.paused).length
+      const neverRan = jobs.filter((job) => Number(job?.runCount || 0) === 0).length
+      sessions.push({
+        sessionID,
+        current: sessionID === currentSessionID,
+        jobs: jobs.length,
+        enabled,
+        neverRan,
+      })
+    } catch {
+      sessions.push({ sessionID, current: sessionID === currentSessionID, jobs: 0, enabled: 0, neverRan: 0, corrupt: true })
+    }
+  }
+
+  return sessions.sort((a, b) => Number(b.current) - Number(a.current) || b.enabled - a.enabled || a.sessionID.localeCompare(b.sessionID))
+}

package/src/source/runtime/network-recovery.js

@@ -0,0 +1,40 @@
+const TRANSIENT_NETWORK_PATTERNS = [
+  /\b(?:408|425|429|500|502|503|504|524)\b/i,
+  /rate[\s_-]?limit|too many requests|overloaded|service[\s_-]?unavailable|provider[_ -]?unavailable/i,
+  /terminated|fetch failed|failed to fetch|network[\s_-]?error|network connection lost/i,
+  /connection (?:error|refused|lost)|socket (?:hang up|connection was closed)|reset before headers/i,
+  /\b(?:enotfound|eai_again|econnrefused|econnreset|etimedout|ehostunreach|enetunreach|epipe)\b/i,
+  /\b(?:request|response|connection|network|stream|read) (?:timeout|timed out|time out)\b/i,
+  /\btimeout(?:error)?\b/i,
+]
+
+function errorText(value) {
+  if (value instanceof Error) return `${value.name}: ${value.message}`
+  if (typeof value === "string") return value
+  try { return JSON.stringify(value) } catch { return String(value) }
+}
+
+export function isTransientNetworkError(value) {
+  const text = errorText(value)
+  return TRANSIENT_NETWORK_PATTERNS.some((pattern) => pattern.test(text))
+}
+
+export function networkRetryDelayMs(attempt, baseMs = 5_000, maxMs = 60_000) {
+  const safeAttempt = Math.max(1, Math.floor(Number(attempt) || 1))
+  const safeBase = Math.max(1, Math.floor(Number(baseMs) || 5_000))
+  const safeMax = Math.max(safeBase, Math.floor(Number(maxMs) || 60_000))
+  return Math.min(safeMax, safeBase * (2 ** Math.min(8, safeAttempt - 1)))
+}
+
+export function refundInfrastructureRun(job, snapshot = {}, input = {}) {
+  const chargedCount = Number(snapshot.runCount ?? job.runCount ?? 0)
+  const currentCount = Number(job.runCount || 0)
+  if (chargedCount > 0 && currentCount >= chargedCount) job.runCount = Math.max(0, currentCount - 1)
+  if (Number.isFinite(Number(snapshot.previousLastRunAt))) job.lastRunAt = Number(snapshot.previousLastRunAt)
+  if (snapshot.disabledByMaxRuns && job.maxRuns > 0 && job.runCount < job.maxRuns) job.enabled = true
+  job.infrastructureFailureCount = (job.infrastructureFailureCount || 0) + 1
+  job.lastInfrastructureFailure = String(input.reason || "transient_network_failure").slice(0, 120)
+  job.lastInfrastructureError = errorText(input.error).slice(0, 4000)
+  job.lastInfrastructureFailureAt = Number(input.now || Date.now())
+  return job
+}

package/src/source/runtime/run-admission.js

@@ -1,10 +1,10 @@
 import path from "node:path"
 import { now as defaultNow } from "../core/args.js"
-import { isGoalJob } from "../core/jobs.js"
 import { pathExists as defaultPathExists, writeState as defaultWriteState } from "../core/state.js"
 import { appendLoopLog as defaultAppendLoopLog, runShellCommand as defaultRunShellCommand, notifyJob as defaultNotifyJob } from "../core/process.js"
 import { toast as defaultToast } from "../opencode/host.js"
 import { dangerousShell as defaultDangerousShell } from "./job-workspace.js"
+import { dueJobs as sharedDueJobs } from "./schedule-policy.js"
 
 function requireFunction(value, label) {
   if (typeof value !== "function") throw new TypeError(`createRunAdmissionRuntime requires ${label}`)
@@ -25,18 +25,7 @@ export function createRunAdmissionRuntime(options = {}) {
   const dangerousShell = typeof options.dangerousShell === "function" ? options.dangerousShell : defaultDangerousShell
 
   function dueJobs(state, force = false) {
-    const current = now()
-    const due = (state.jobs || []).filter((job) => {
-      if (isGoalJob(job) && ["completed", "blocked", "cleared"].includes(job.goalStatus)) return false
-      if (!job.enabled || job.paused) return false
-      if (job.maxRuns > 0 && (job.runCount || 0) >= job.maxRuns) return false
-      if (job.maxRuntimeMs > 0 && current - Date.parse(job.createdAt || new Date().toISOString()) >= job.maxRuntimeMs) return true
-      if (Number(job.runNowRequestedAt || 0) > 0) return true
-      if (force) return true
-      if (job.watchPaths?.length) return job.watchTriggered === true
-      return job.intervalMs === 0 || !job.lastRunAt || current - job.lastRunAt >= job.intervalMs
-    })
-    return due.sort((a, b) => Number(Number(b.runNowRequestedAt || 0) > 0) - Number(Number(a.runNowRequestedAt || 0) > 0))
+    return sharedDueJobs(state, now(), force)
   }
 
   async function reschedule(directory, client, sessionID) {

package/src/source/runtime/run-finalization.js

@@ -5,6 +5,7 @@ import { appendLoopLog as defaultAppendLoopLog, runShellCommand as defaultRunShe
 import { toast as defaultToast } from "../opencode/host.js"
 import { writeGoalReport as defaultWriteGoalReport } from "./goal-runtime.js"
 import { dangerousShell as defaultDangerousShell } from "./job-workspace.js"
+import { applyTerminalContinuationGuard as defaultApplyTerminalContinuationGuard } from "./terminal-guard.js"
 
 function requireFunction(value, label) {
   if (typeof value !== "function") throw new TypeError(`createRunFinalizationRuntime requires ${label}`)
@@ -25,8 +26,22 @@ export function createRunFinalizationRuntime(options = {}) {
   const toast = typeof options.toast === "function" ? options.toast : defaultToast
   const writeGoalReport = typeof options.writeGoalReport === "function" ? options.writeGoalReport : defaultWriteGoalReport
   const dangerousShell = typeof options.dangerousShell === "function" ? options.dangerousShell : defaultDangerousShell
+  const applyTerminalContinuationGuard = typeof options.applyTerminalContinuationGuard === "function"
+    ? options.applyTerminalContinuationGuard
+    : defaultApplyTerminalContinuationGuard
 
   async function finalizeJob(directory, client, sessionID, state, job, previousJob) {
+    // Infrastructure backoff is consecutive, not lifetime. Reaching normal
+    // finalization proves a real Loop-owned turn completed, so the next future
+    // outage should restart from the shortest backoff rather than inheriting an
+    // old 60s cap from unrelated historical network failures.
+    if (job.infrastructureFailureCount) {
+      job.infrastructureFailureCount = 0
+      job.lastInfrastructureFailure = ""
+      job.lastInfrastructureError = ""
+      job.lastInfrastructureFailureAt = 0
+    }
+
     if (job.verifyCommand) {
       const verify = await runShellCommand(job.verifyCommand, directory, job.timeoutMs || 300_000)
       job.lastVerifyAt = now()
@@ -86,6 +101,19 @@ export function createRunFinalizationRuntime(options = {}) {
       job = await applyGoalNoProgressGuard(directory, client, sessionID, job, previousJob)
     }
 
+    const terminal = await applyTerminalContinuationGuard(directory, client, sessionID, job)
+    job = terminal.job
+    if (terminal.pausedNow) {
+      await appendLoopLog(directory, "terminal-no-work", {
+        sessionID,
+        job: job.name || job.id,
+        count: job.terminalNoWorkCount,
+        summary: String(terminal.text || "").slice(0, 1000),
+      })
+      await notifyJob(directory, job, "terminal_no_work")
+      await toast(client, "Loop paused: completion-bounded task reported complete with no work remaining twice.", "success")
+    }
+
     state.jobs = (state.jobs || [])
       .map((candidate) => candidate.id === job.id ? job : candidate)
       .filter((candidate) => candidate.enabled !== false || isGoalJob(candidate))

package/src/source/runtime/schedule-policy.js

@@ -0,0 +1,80 @@
+import { durationToText } from "../core/args.js"
+import { isGoalJob } from "../core/jobs.js"
+
+const TERMINAL_GOAL_STATUSES = new Set(["completed", "blocked", "cleared"])
+
+export function inferredScheduleMode(job) {
+  const explicit = String(job?.scheduleMode || "").toLowerCase()
+  if (["idle", "interval", "once", "watch"].includes(explicit)) return explicit
+  if (job?.watchPaths?.length) return "watch"
+  if (Number(job?.maxRuns || 0) === 1 && job?.immediate === false && Number(job?.intervalMs || 0) > 0) return "once"
+  return Number(job?.intervalMs || 0) === 0 ? "idle" : "interval"
+}
+
+export function jobRunnable(job) {
+  if (!job) return false
+  if (isGoalJob(job) && TERMINAL_GOAL_STATUSES.has(job.goalStatus)) return false
+  if (!job.enabled || job.paused) return false
+  if (Number(job.maxRuns || 0) > 0 && Number(job.runCount || 0) >= Number(job.maxRuns || 0)) return false
+  return true
+}
+
+export function jobDueAt(job, current = Date.now()) {
+  if (!jobRunnable(job)) return Infinity
+  if (Number(job.runNowRequestedAt || 0) > 0) return current
+
+  const created = Date.parse(job.createdAt || "")
+  if (Number(job.maxRuntimeMs || 0) > 0 && Number.isFinite(created) && current - created >= Number(job.maxRuntimeMs || 0)) return current
+
+  if (job.watchPaths?.length) return job.watchTriggered === true ? current : Infinity
+
+  const intervalMs = Number(job.intervalMs || 0)
+  if (intervalMs === 0) return current
+
+  const lastRunAt = Number(job.lastRunAt || 0)
+  if (!lastRunAt) {
+    if (job.immediate === false) return (Number.isFinite(created) ? created : current) + intervalMs
+    return current
+  }
+  return lastRunAt + intervalMs
+}
+
+export function jobIsDue(job, current = Date.now(), force = false) {
+  if (!jobRunnable(job)) return false
+  if (force) return true
+  return jobDueAt(job, current) <= current
+}
+
+export function dueJobs(state, current = Date.now(), force = false) {
+  return (state?.jobs || [])
+    .filter((job) => jobIsDue(job, current, force))
+    .sort((a, b) => Number(Number(b.runNowRequestedAt || 0) > 0) - Number(Number(a.runNowRequestedAt || 0) > 0))
+}
+
+export function nextDueDelay(state, current = Date.now()) {
+  let soonest = Infinity
+  for (const job of state?.jobs || []) soonest = Math.min(soonest, jobDueAt(job, current))
+  if (!Number.isFinite(soonest)) return Infinity
+  return Math.max(0, soonest - current)
+}
+
+export function scheduleDescription(job) {
+  const mode = inferredScheduleMode(job)
+  const intervalMs = Number(job?.intervalMs || 0)
+  if (mode === "idle") return "every idle"
+  if (mode === "watch") return `on watch: ${(job.watchPaths || []).join(", ")}`
+  if (mode === "once") return intervalMs > 0 ? `once after ${durationToText(intervalMs)}` : "once on next idle"
+  if (job?.immediate === false) return `every ${durationToText(intervalMs)}, first after ${durationToText(intervalMs)}`
+  return `every ${durationToText(intervalMs)}, starts on next idle`
+}
+
+export function scheduleState(job, current = Date.now()) {
+  if (!job?.enabled) return "stopped"
+  if (job?.paused) return "paused"
+  if (Number(job?.runNowRequestedAt || 0) > 0) return "due now; waiting for idle"
+  const mode = inferredScheduleMode(job)
+  const dueAt = jobDueAt(job, current)
+  if (!Number.isFinite(dueAt)) return mode === "watch" ? "waiting for watched change" : "not scheduled"
+  if (dueAt <= current) return mode === "idle" ? "waiting for idle" : "due; waiting for idle"
+  return `due in ${durationToText(dueAt - current)}`
+}

package/src/source/runtime/scheduler-diagnostics.js

@@ -0,0 +1,30 @@
+const DEFAULT_DEFERRAL_LOG_THROTTLE_MS = 30_000
+
+export function createSchedulerDiagnostics(options = {}) {
+  const now = typeof options.now === "function" ? options.now : Date.now
+  const appendLoopLog = typeof options.appendLoopLog === "function" ? options.appendLoopLog : async () => {}
+  const configured = Number(options.throttleMs)
+  const throttleMs = Number.isFinite(configured) && configured >= 0 ? configured : DEFAULT_DEFERRAL_LOG_THROTTLE_MS
+  const lastLogged = new Map()
+
+  async function logDeferral(directory, sessionID, reason, extra = {}) {
+    const key = `${sessionID || "unknown"}:${reason || "deferred"}:${extra.source || "runtime"}`
+    const current = now()
+    const previous = Number(lastLogged.get(key) || 0)
+    if (previous > 0 && current - previous < throttleMs) return false
+    lastLogged.set(key, current)
+    await appendLoopLog(directory, "deferred", {
+      sessionID,
+      reason,
+      ...extra,
+    })
+    return true
+  }
+
+  function clearSession(sessionID) {
+    const prefix = `${sessionID || "unknown"}:`
+    for (const key of lastLogged.keys()) if (key.startsWith(prefix)) lastLogged.delete(key)
+  }
+
+  return { logDeferral, clearSession }
+}

package/src/source/runtime/scheduler.js

@@ -1,6 +1,10 @@
 import { now } from "../core/args.js"
 import { isGoalJob } from "../core/jobs.js"
 import { readState } from "../core/state.js"
+import { createSchedulerDiagnostics } from "./scheduler-diagnostics.js"
+import { jobDueAt, nextDueDelay } from "./schedule-policy.js"
+
+export { jobDueAt, nextDueDelay }
 
 const DEFAULT_IDLE_DEBOUNCE_MS = 1_200
 const DEFAULT_BUSY_RETRY_MS = 5_000
@@ -9,29 +13,6 @@ const DEFAULT_MAX_DUE_TIMER_MS = 2_147_000_000
 const DEFAULT_HEARTBEAT_MS = 2_500
 const DEFAULT_SESSION_TTL_MS = 12 * 60 * 60 * 1000
 
-export function jobDueAt(job, current = now()) {
-  if (isGoalJob(job) && ["completed", "blocked", "cleared"].includes(job.goalStatus)) return Infinity
-  if (!job.enabled || job.paused) return Infinity
-  if (job.maxRuns > 0 && (job.runCount || 0) >= job.maxRuns) return Infinity
-  if (Number(job.runNowRequestedAt || 0) > 0) return current
-  if (job.watchPaths?.length) return Infinity
-  const created = Date.parse(job.createdAt || "")
-  if (job.maxRuntimeMs > 0 && Number.isFinite(created) && current - created >= job.maxRuntimeMs) return current
-  if (job.intervalMs === 0) return current
-  if (!job.lastRunAt) {
-    if (job.immediate === false) return (Number.isFinite(created) ? created : current) + (job.intervalMs || 0)
-    return current
-  }
-  return job.lastRunAt + (job.intervalMs || 0)
-}
-
-export function nextDueDelay(state, current = now()) {
-  let soonest = Infinity
-  for (const job of state.jobs || []) soonest = Math.min(soonest, jobDueAt(job, current))
-  if (!Number.isFinite(soonest)) return Infinity
-  return Math.max(0, soonest - current)
-}
-
 export function createSchedulerRuntime(options = {}) {
   const idleTimers = new Map()
   const dueTimers = new Map()
@@ -55,6 +36,7 @@ export function createSchedulerRuntime(options = {}) {
   const errorMessage = (error) => options.errorMessage ? options.errorMessage(error) : (error instanceof Error ? error.message : String(error || "unknown error"))
   const appendLog = async (directory, event, extra) => { if (options.appendLoopLog) await options.appendLoopLog(directory, event, extra) }
   const toast = async (client, message, level) => { if (options.toast) await options.toast(client, message, level) }
+  const diagnostics = createSchedulerDiagnostics({ appendLoopLog: appendLog, now: clock, throttleMs: options.deferralLogThrottleMs })
 
   function stopHeartbeatIfIdle() {
     if (!knownSessions.size && heartbeatTimer) {
@@ -107,11 +89,13 @@ export function createSchedulerRuntime(options = {}) {
       Promise.resolve()
         .then(async () => {
           if (!await options.sessionIsIdle?.(client, sessionID, directory)) {
+            await diagnostics.logDeferral(directory, sessionID, "session-busy", { source: "idle", retryMs: busyRetryMs })
             await scheduleDueWork(directory, client, sessionID, busyRetryMs)
             return
           }
           await options.finalizeActiveRun?.(directory, client, sessionID)
           if (!await options.sessionIsIdle?.(client, sessionID, directory)) {
+            await diagnostics.logDeferral(directory, sessionID, "session-busy-after-finalize", { source: "idle", retryMs: busyRetryMs })
             await scheduleDueWork(directory, client, sessionID, busyRetryMs)
             return
           }
@@ -164,11 +148,13 @@ export function createSchedulerRuntime(options = {}) {
       Promise.resolve()
         .then(async () => {
           if (!await options.sessionIsIdle?.(client, sessionID, directory)) {
+            await diagnostics.logDeferral(directory, sessionID, "session-busy", { source: "due", retryMs: busyRetryMs })
             await scheduleDueWork(directory, client, sessionID, busyRetryMs)
             return
           }
           await options.finalizeActiveRun?.(directory, client, sessionID)
           if (!await options.sessionIsIdle?.(client, sessionID, directory)) {
+            await diagnostics.logDeferral(directory, sessionID, "session-busy-after-finalize", { source: "due", retryMs: busyRetryMs })
             await scheduleDueWork(directory, client, sessionID, busyRetryMs)
             return
           }
@@ -193,6 +179,7 @@ export function createSchedulerRuntime(options = {}) {
     cancelIdleWork(sessionID)
     cancelDueWork(sessionID)
     stopWatchdog(sessionID)
+    diagnostics.clearSession(sessionID)
     knownSessions.delete(sessionID)
     stopHeartbeatIfIdle()
   }