@bybrawe/opencode-loop 0.5.33 → 0.5.34

package/src/source/core/continuation.js

@@ -0,0 +1,20 @@
+const CONTINUATION_SHORTHANDS = new Set([
+  "continue",
+  "continue.",
+  "continue working",
+  "keep going",
+  "go on",
+  "devam",
+  "devam et",
+  "devam et.",
+  "devam et bakalım",
+])
+
+export function isContinuationShorthand(value) {
+  return CONTINUATION_SHORTHANDS.has(String(value || "").trim().toLowerCase().replace(/\s+/g, " "))
+}
+
+export function continuationProjectInstruction(value) {
+  if (!isContinuationShorthand(value)) return ""
+  return "Treat this as continuation of the current project and conversation, not a fresh task. Inspect the repository state, relevant files, TODO/progress notes, recent changes, and git status as needed to identify the next unfinished step. Continue from existing work, do not redo completed work, and verify meaningful changes when practical."
+}

package/src/source/core/jobs.js

@@ -1,4 +1,5 @@
 import { DEFAULT_GOAL_MAX_NO_PROGRESS, parseDuration, durationToText } from "./args.js"
+import { continuationProjectInstruction } from "./continuation.js"
 
 export function presetDefaults(name) {
   // parseLoopArgs owns duration/flag/action parsing. Presets only provide real
@@ -54,6 +55,8 @@ export function actionKind(action, job = {}) {
 
 export function decoratePrompt(job) {
   const additions = []
+  const continuation = continuationProjectInstruction(job.action)
+  if (continuation) additions.push(continuation)
   if (job.progressFile) additions.push(`Use ${job.progressFile} as the main progress/TODO state file. Read it before choosing the next task and update it after work.`)
   if (job.lastVerifyFailure) additions.push("Previous verify command failed. Fix this before moving on. Failure summary: " + String(job.lastVerifyFailure).slice(0, 1200))
   if (job.askNever) additions.push("Do not ask the user questions. Make reasonable assumptions and continue. Only write a short BLOCKED note if truly blocked.")

package/src/source/core/schedule-syntax.js

@@ -0,0 +1,93 @@
+import { parseDuration } from "./args.js"
+
+function removeBooleanFlag(input, flag) {
+  const pattern = new RegExp(`(^|\\s)${flag.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&")}(?=\\s|$)`, "i")
+  const found = pattern.test(input)
+  return {
+    found,
+    value: String(input || "").replace(pattern, " ").replace(/\s+/g, " ").trim(),
+  }
+}
+
+function firstToken(input) {
+  const match = String(input || "").trim().match(/^(\S+)(?:\s+([\s\S]*))?$/)
+  return match ? { token: match[1], rest: String(match[2] || "").trim() } : { token: "", rest: "" }
+}
+
+function inferredMode(intervalMs, maxRuns) {
+  if (Number(maxRuns || 0) === 1 && Number(intervalMs || 0) > 0) return "once"
+  return Number(intervalMs || 0) === 0 ? "idle" : "interval"
+}
+
+/**
+ * Normalize the human-facing /loop schedule grammar before the legacy flag parser.
+ *
+ * Supported forms:
+ *   /loop <prompt>                 -> every idle, unlimited
+ *   /loop idle <prompt>            -> every idle, unlimited
+ *   /loop every 5m <prompt>        -> recurring, first run after 5m
+ *   /loop after 5m <prompt>        -> one shot after 5m
+ *   /loop in 5m <prompt>           -> alias for `after`
+ *   /loop 5m <prompt>              -> legacy compact form (starts now unless --no-now)
+ */
+export function normalizeLoopScheduleArgs(raw, defaults = {}) {
+  const overlap = removeBooleanFlag(String(raw || "").trim(), "--allow-goal-overlap")
+  let input = overlap.value
+  const nextDefaults = { ...defaults }
+  let scheduleMode = defaults.scheduleMode
+  let scheduleSyntax = "legacy"
+
+  const first = firstToken(input)
+  const keyword = first.token.toLowerCase()
+
+  if (keyword === "idle") {
+    nextDefaults.intervalMs = 0
+    nextDefaults.immediate = true
+    scheduleMode = "idle"
+    scheduleSyntax = "idle"
+    input = first.rest
+  } else if (keyword === "every" || keyword === "after" || keyword === "in") {
+    const duration = firstToken(first.rest)
+    const intervalMs = parseDuration(duration.token)
+    if (intervalMs === null) {
+      return {
+        ok: false,
+        error: `Invalid ${keyword} schedule. Example: /loop ${keyword === "every" ? "every" : "after"} 5m continue the project`,
+      }
+    }
+    nextDefaults.intervalMs = intervalMs
+    nextDefaults.immediate = false
+    input = duration.rest
+    if (keyword === "every") {
+      scheduleMode = intervalMs === 0 ? "idle" : "interval"
+      scheduleSyntax = "every"
+    } else {
+      nextDefaults.maxRuns = 1
+      scheduleMode = "once"
+      scheduleSyntax = "after"
+    }
+  } else {
+    const duration = parseDuration(first.token)
+    if (duration !== null) {
+      scheduleMode = duration === 0 ? "idle" : "interval"
+    } else if (nextDefaults.intervalMs === undefined || nextDefaults.intervalMs === null) {
+      // Plain /loop text is the ergonomic auto-continue form. Flags at the front
+      // are also accepted because the lower-level parser now receives an idle default.
+      nextDefaults.intervalMs = 0
+      nextDefaults.immediate = nextDefaults.immediate ?? true
+      scheduleMode = "idle"
+      scheduleSyntax = "idle-shorthand"
+    } else {
+      scheduleMode = scheduleMode || inferredMode(nextDefaults.intervalMs, nextDefaults.maxRuns)
+    }
+  }
+
+  return {
+    ok: true,
+    args: input,
+    defaults: nextDefaults,
+    scheduleMode: scheduleMode || inferredMode(nextDefaults.intervalMs, nextDefaults.maxRuns),
+    scheduleSyntax,
+    allowGoalOverlap: overlap.found || defaults.allowGoalOverlap === true,
+  }
+}

package/src/source/opencode/loop-commands.js

@@ -1,9 +1,11 @@
 import { promises as fs } from "node:fs"
 import path from "node:path"
-import { now as defaultNow, durationToText } from "../core/args.js"
+import { now as defaultNow } from "../core/args.js"
 import { jobLabel, matchJob, isGoalJob, goalStatusText } from "../core/jobs.js"
 import { stateDir, pathExists as defaultPathExists, readState as defaultReadState, writeState as defaultWriteState, removeState as defaultRemoveState } from "../core/state.js"
 import { appendLoopLog as defaultAppendLoopLog } from "../core/process.js"
+import { dedicatedGoalSummary, findDedicatedGoalForSession as defaultFindDedicatedGoalForSession } from "../runtime/companion-goal.js"
+import { describeJobScheduling, listPersistedLoopSessions as defaultListPersistedLoopSessions } from "../runtime/loop-diagnostics.js"
 
 const SERVICE = "opencode-loop"
 const DEFAULT_PROGRESS_MD = `# Progress
@@ -54,6 +56,8 @@ export function createLoopCommandHandlers(options = {}) {
   const appendLoopLog = typeof options.appendLoopLog === "function" ? options.appendLoopLog : defaultAppendLoopLog
   const readFile = typeof options.readFile === "function" ? options.readFile : (...args) => fs.readFile(...args)
   const writeFile = typeof options.writeFile === "function" ? options.writeFile : (...args) => fs.writeFile(...args)
+  const listPersistedLoopSessions = typeof options.listPersistedLoopSessions === "function" ? options.listPersistedLoopSessions : defaultListPersistedLoopSessions
+  const findDedicatedGoalForSession = typeof options.findDedicatedGoalForSession === "function" ? options.findDedicatedGoalForSession : defaultFindDedicatedGoalForSession
   const runtimeVersion = options.runtimeVersion || process.version
   const runtimePlatform = options.runtimePlatform || process.platform
 
@@ -88,21 +92,11 @@ export function createLoopCommandHandlers(options = {}) {
   async function statusLoop(directory, client, sessionID) {
     const state = await readState(directory, sessionID)
     const jobs = state.jobs || []
+    const current = now()
     const lines = jobs.length ? jobs.map((job, index) => {
-      const current = now()
-      const intervalMs = Number(job.intervalMs || 0)
-      const lastRunAt = Number(job.lastRunAt || 0)
-      const createdAt = Date.parse(job.createdAt || "")
-      const dueAt = Number(job.runNowRequestedAt || 0) > 0
-        ? current
-        : lastRunAt > 0
-          ? lastRunAt + intervalMs
-          : job.immediate === false && Number.isFinite(createdAt)
-            ? createdAt + intervalMs
-            : current
-      const dueIn = Math.max(0, dueAt - current)
+      const scheduling = describeJobScheduling(job, current)
       const flags = [isGoalJob(job) ? `goal:${goalStatusText(job)}` : undefined, job.paused ? "paused" : "active", Number(job.runNowRequestedAt || 0) > 0 ? "run-now" : undefined, job.safe ? "safe" : undefined, job.askNever ? "ask-never" : undefined, job.noOverlap ? "no-overlap" : undefined, job.checkpointOnly ? "checkpoint-only" : undefined, job.gitCheckpoint ? "git-checkpoint" : undefined].filter(Boolean).join(",")
-      return `${index + 1}. ${job.id}${job.name ? ` (${job.name})` : ""}: ${jobLabel(job)} | runs=${job.runCount || 0} | failures=${job.failureCount || 0} | due in ${durationToText(dueIn)} | ${flags}`
+      return `${index + 1}. ${job.id}${job.name ? ` (${job.name})` : ""}: ${jobLabel(job)} | schedule=${scheduling.schedule} | state=${scheduling.state} | runs=${job.runCount || 0} | failures=${job.failureCount || 0} | ${flags}`
     }) : ["No active loop jobs."]
     await toast(client, jobs.length ? `${jobs.length} loop job(s).` : "No active loop jobs.", jobs.length ? "info" : "warning")
     await say(client, sessionID, "OpenCode loop status:\n" + lines.join("\n"))
@@ -117,18 +111,20 @@ export function createLoopCommandHandlers(options = {}) {
   async function helpLoop(client, sessionID) {
     await say(client, sessionID, [
       "OpenCode Loop help:",
-      "/loop 0s <prompt>                                Claude Code style auto-continue",
-      "/loop 5m --ask-never --safe <prompt>              interval autonomous prompt loop",
-      "/loop-command 200m /compact                       OpenCode slash-command loop, waits for idle",
-      "/loop-ask 1h did you run tests and tsc --noEmit?   scheduled question/check prompt",
-      "/loop-shell 10m npm test                           shell loop, waits for idle",
-      "/loop-goal finish the feature and keep tests green  experimental persistent goal mode",
-      "/loop-goal --check \"npm run build\" --check \"npm test\" --complete-when-checks-pass ship it",
-      "/loop-goal status | pause | resume | clear          manage experimental goals",
-      "/loop 200m --command /compact                     same as command loop",
-      "/loop 0s --verify \"npm test\" <prompt>            verify after each assistant turn",
-      "/loop 0s --prompt-file loop-prompt.md             load prompt from a file",
-      "/loop 0s --max-runtime 6h --max-failures 3 <task> stop safely after limits",
+      "/loop continue the project                           auto-continue forever whenever the session becomes idle",
+      "/loop idle continue the project                      explicit form of the same idle loop",
+      "/loop every 5m continue the project                  recurring timer; first run after 5m, always waits for idle",
+      "/loop after 5m continue the project                  one-shot delayed prompt; runs once when 5m has passed and session is idle",
+      "/loop 5m continue the project                        legacy compact form: starts on next idle, then every 5m",
+      "/loop 5m --no-now continue the project               legacy recurring form with first run delayed 5m",
+      "/loop-command 200m /compact                          OpenCode slash-command loop, waits for idle",
+      "/loop-ask 1h did you run tests and tsc --noEmit?      scheduled question/check prompt",
+      "/loop-shell 10m npm test                              shell loop, waits for idle",
+      "/loop-goal finish the feature and keep tests green    experimental persistent goal mode",
+      "/loop 0s --verify \"npm test\" <prompt>               verify after each assistant turn",
+      "/loop --prompt-file loop-prompt.md                    idle loop loading its prompt from a file",
+      "/loop 0s --max-runtime 6h --max-failures 3 <task>     stop safely after limits",
+      "Prompt-producing /loop jobs are blocked while dedicated /goal owns the same session; use another session or --allow-goal-overlap only intentionally.",
       "/loop-doctor | /loop-init | /loop-export",
     ].join("\n"))
   }
@@ -154,17 +150,30 @@ export function createLoopCommandHandlers(options = {}) {
 
   async function doctorLoop(directory, client, sessionID) {
     const state = await readState(directory, sessionID)
-    await say(client, sessionID, [
+    const persisted = await listPersistedLoopSessions(directory, sessionID)
+    const otherSessions = persisted.filter((entry) => !entry.current && entry.enabled > 0)
+    const dedicatedGoal = await findDedicatedGoalForSession(directory, sessionID)
+    const lines = [
       "OpenCode Loop doctor:",
       `- plugin: ${SERVICE}`,
       `- project directory: ${directory}`,
       `- state directory: ${stateDir(directory)}`,
-      `- active jobs: ${(state.jobs || []).length}`,
+      `- current session: ${sessionID}`,
+      `- current-session jobs: ${(state.jobs || []).length}`,
+      `- dedicated /goal: ${dedicatedGoalSummary(dedicatedGoal)}`,
+      `- other persisted sessions with enabled jobs: ${otherSessions.length}`,
       `- node: ${runtimeVersion}`,
       `- platform: ${runtimePlatform}`,
-      "- smoke test: /loop 0s --max-runs 1 --dry-run continue from progress.md",
+      "- smoke test: /loop --max-runs 1 --dry-run continue from progress.md",
+      "- delayed smoke test: /loop after 5m --dry-run continue from progress.md",
+      "- recurring smoke test: /loop every 5m --dry-run continue from progress.md",
       "- experimental goal smoke test: /loop-goal --dry-run finish the current task and verify it",
-    ].join("\n"))
+    ]
+    for (const entry of otherSessions.slice(0, 8)) {
+      lines.push(`- other session ${entry.sessionID}: jobs=${entry.jobs}, enabled=${entry.enabled}, never-ran=${entry.neverRan}`)
+    }
+    if (otherSessions.length > 8) lines.push(`- ... ${otherSessions.length - 8} more persisted session(s)`)
+    await say(client, sessionID, lines.join("\n"))
   }
 
   async function initLoop(directory, client, sessionID, args) {

package/src/source/opencode/loop-registration.js

@@ -1,7 +1,9 @@
 import { parseLoopArgs as defaultParseLoopArgs } from "../core/args.js"
-import { jobLabel, isGoalJob } from "../core/jobs.js"
+import { actionKind, jobLabel, isGoalJob } from "../core/jobs.js"
+import { normalizeLoopScheduleArgs as defaultNormalizeLoopScheduleArgs } from "../core/schedule-syntax.js"
 import { readState as defaultReadState, writeState as defaultWriteState } from "../core/state.js"
 import { appendLoopLog as defaultAppendLoopLog } from "../core/process.js"
+import { dedicatedGoalOwnsContinuation, findDedicatedGoalForSession as defaultFindDedicatedGoalForSession } from "../runtime/companion-goal.js"
 import { normalizedModelRef as defaultNormalizedModelRef, getSessionExecutionContext as defaultGetSessionExecutionContext } from "./session-context.js"
 
 const DEFAULT_GOAL_ACTIVE_RECOVERY_MS = 180_000
@@ -32,17 +34,31 @@ export function createLoopRegistration(options = {}) {
   const toast = requireFunction(options.toast, "toast")
   const say = requireFunction(options.say, "say")
   const parseLoopArgs = typeof options.parseLoopArgs === "function" ? options.parseLoopArgs : defaultParseLoopArgs
+  const normalizeLoopScheduleArgs = typeof options.normalizeLoopScheduleArgs === "function" ? options.normalizeLoopScheduleArgs : defaultNormalizeLoopScheduleArgs
   const readState = typeof options.readState === "function" ? options.readState : defaultReadState
   const writeState = typeof options.writeState === "function" ? options.writeState : defaultWriteState
   const appendLoopLog = typeof options.appendLoopLog === "function" ? options.appendLoopLog : defaultAppendLoopLog
   const normalizedModelRef = typeof options.normalizedModelRef === "function" ? options.normalizedModelRef : defaultNormalizedModelRef
   const getSessionExecutionContext = typeof options.getSessionExecutionContext === "function" ? options.getSessionExecutionContext : defaultGetSessionExecutionContext
+  const findDedicatedGoalForSession = typeof options.findDedicatedGoalForSession === "function" ? options.findDedicatedGoalForSession : defaultFindDedicatedGoalForSession
   const configuredGuard = Number(options.defaultActiveGuardMs)
   const defaultActiveGuardMs = Number.isFinite(configuredGuard) && configuredGuard > 0 ? configuredGuard : FALLBACK_ACTIVE_GUARD_MS
 
   async function addLoop(directory, client, sessionID, args, defaults = {}) {
-    const parsed = parseLoopArgs(args, defaults)
+    const normalized = normalizeLoopScheduleArgs(args, defaults)
+    if (!normalized.ok) { await toast(client, normalized.error, "warning"); return }
+
+    const parsed = parseLoopArgs(normalized.args, normalized.defaults)
     if (!parsed.ok) { await toast(client, parsed.error, "warning"); return }
+    parsed.job.scheduleMode = normalized.scheduleMode
+    parsed.job.scheduleSyntax = normalized.scheduleSyntax
+    parsed.job.allowGoalOverlap = normalized.allowGoalOverlap === true
+    if (normalized.scheduleSyntax === "after") {
+      parsed.job.immediate = false
+      parsed.job.maxRuns = 1
+      parsed.job.lastRunAt = Date.parse(parsed.job.createdAt || "") || Date.now()
+    }
+
     const executionContext = getSessionExecutionContext(sessionID) || { agent: "build" }
     parsed.job.agent = defaults.agent || executionContext.agent || "build"
     parsed.job.model = normalizedModelRef(defaults.model) || executionContext.model
@@ -63,6 +79,21 @@ export function createLoopRegistration(options = {}) {
         ? DEFAULT_GOAL_ACTIVE_RECOVERY_MS
         : Math.max(defaultActiveGuardMs, Math.min(90_000, (parsed.job.intervalMs || 0) + 10_000))
     }
+
+    const promptProducing = actionKind(parsed.job.action, parsed.job) === "prompt"
+    if (promptProducing && !parsed.job.allowGoalOverlap) {
+      const dedicatedGoal = await findDedicatedGoalForSession(directory, sessionID)
+      if (dedicatedGoalOwnsContinuation(dedicatedGoal)) {
+        await appendLoopLog(directory, "goal-overlap-blocked", {
+          sessionID,
+          job: parsed.job.name || parsed.job.id,
+          goal: dedicatedGoal.id,
+        })
+        await toast(client, "Prompt loop not added: dedicated /goal already owns continuation in this session. Pause/finish the Goal, use another session, or pass --allow-goal-overlap intentionally.", "warning")
+        return
+      }
+    }
+
     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```")
@@ -93,7 +124,13 @@ export function createLoopRegistration(options = {}) {
     await scheduleDueWork(directory, client, sessionID)
     if (parsed.job.immediate) scheduleIdleWork(directory, client, sessionID)
     await toast(client, `${replaced ? "Loop replaced" : "Loop added"}: ${jobLabel(parsed.job)}`, "success")
-    await appendLoopLog(directory, replaced ? "replace" : "add", { sessionID, job: parsed.job.name || parsed.job.id, label: jobLabel(parsed.job) })
+    await appendLoopLog(directory, replaced ? "replace" : "add", {
+      sessionID,
+      job: parsed.job.name || parsed.job.id,
+      label: jobLabel(parsed.job),
+      scheduleMode: parsed.job.scheduleMode,
+      scheduleSyntax: parsed.job.scheduleSyntax,
+    })
   }
 
   return { addLoop }

package/src/source/runtime/companion-goal.js

@@ -0,0 +1,37 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+
+function goalRoot(directory) {
+  return path.join(directory, ".opencode", "goals")
+}
+
+export async function findDedicatedGoalForSession(directory, sessionID) {
+  if (!directory || !sessionID) return undefined
+  let names
+  try {
+    names = await fs.readdir(goalRoot(directory))
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined
+    return undefined
+  }
+
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue
+    try {
+      const value = JSON.parse(await fs.readFile(path.join(goalRoot(directory), name), "utf8"))
+      if (value?.sessionID === sessionID) return value
+    } catch {}
+  }
+  return undefined
+}
+
+export function dedicatedGoalOwnsContinuation(goal) {
+  return goal?.status === "active"
+}
+
+export function dedicatedGoalSummary(goal) {
+  if (!goal) return "not detected"
+  const id = String(goal.id || "unknown").slice(0, 12)
+  const status = String(goal.status || "unknown")
+  return `${status} (${id})`
+}

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/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/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()
   }