@bybrawe/opencode-loop 0.5.32 → 0.5.34

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

@@ -0,0 +1,121 @@
+import path from "node:path"
+import { now as defaultNow } from "../core/args.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}`)
+  return value
+}
+
+export function createRunAdmissionRuntime(options = {}) {
+  const untilReached = requireFunction(options.untilReached, "untilReached")
+  const scheduleDueWork = requireFunction(options.scheduleDueWork, "scheduleDueWork")
+
+  const now = typeof options.now === "function" ? options.now : defaultNow
+  const pathExists = typeof options.pathExists === "function" ? options.pathExists : defaultPathExists
+  const writeState = typeof options.writeState === "function" ? options.writeState : defaultWriteState
+  const appendLoopLog = typeof options.appendLoopLog === "function" ? options.appendLoopLog : defaultAppendLoopLog
+  const runShellCommand = typeof options.runShellCommand === "function" ? options.runShellCommand : defaultRunShellCommand
+  const notifyJob = typeof options.notifyJob === "function" ? options.notifyJob : defaultNotifyJob
+  const toast = typeof options.toast === "function" ? options.toast : defaultToast
+  const dangerousShell = typeof options.dangerousShell === "function" ? options.dangerousShell : defaultDangerousShell
+
+  function dueJobs(state, force = false) {
+    return sharedDueJobs(state, now(), force)
+  }
+
+  async function reschedule(directory, client, sessionID) {
+    await scheduleDueWork(directory, client, sessionID)
+  }
+
+  async function stopAndRemove(directory, client, sessionID, state, job, reason, message, logEvent) {
+    state.jobs = (state.jobs || []).filter((candidate) => candidate.id !== job.id)
+    await writeState(directory, sessionID, state)
+    await notifyJob(directory, job, reason)
+    await toast(client, message, "success")
+    if (logEvent) await appendLoopLog(directory, logEvent, { sessionID, job: job.name || job.id })
+    await reschedule(directory, client, sessionID)
+    return { admitted: false, reason }
+  }
+
+  async function admitJob(directory, client, sessionID, state, job) {
+    const runNowRequested = Number(job.runNowRequestedAt || 0) > 0
+
+    if (job.maxRuntimeMs > 0 && now() - Date.parse(job.createdAt || new Date().toISOString()) >= job.maxRuntimeMs) {
+      return await stopAndRemove(
+        directory,
+        client,
+        sessionID,
+        state,
+        job,
+        "max_runtime_reached",
+        `Loop stopped by --max-runtime: ${job.name || job.id}`,
+        "max-runtime",
+      )
+    }
+
+    if (job.stopFile && await pathExists(path.resolve(directory, job.stopFile))) {
+      return await stopAndRemove(
+        directory,
+        client,
+        sessionID,
+        state,
+        job,
+        "stop_file",
+        "Loop stopped by --stop-file: " + job.stopFile,
+      )
+    }
+
+    if (await untilReached(directory, job)) {
+      return await stopAndRemove(
+        directory,
+        client,
+        sessionID,
+        state,
+        job,
+        "until_reached",
+        `Loop stopped by --until: ${job.until}`,
+      )
+    }
+
+    if (job.preflightCommand) {
+      if (job.safe && dangerousShell(job.preflightCommand)) {
+        if (runNowRequested) delete job.runNowRequestedAt
+        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(directory, client, sessionID)
+        return { admitted: false, reason: "preflight_blocked" }
+      }
+
+      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) {
+        if (runNowRequested) delete job.runNowRequestedAt
+        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(directory, client, sessionID)
+        return { admitted: false, reason: "preflight_failed" }
+      }
+    }
+
+    return { admitted: true, job, runNowRequested }
+  }
+
+  return { dueJobs, admitJob }
+}

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

@@ -0,0 +1,100 @@
+import { now as defaultNow } from "../core/args.js"
+import { isGoalJob } from "../core/jobs.js"
+import { 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 { writeGoalReport as defaultWriteGoalReport } from "./goal-runtime.js"
+import { dangerousShell as defaultDangerousShell } from "./job-workspace.js"
+
+function requireFunction(value, label) {
+  if (typeof value !== "function") throw new TypeError(`createRunFinalizationRuntime requires ${label}`)
+  return value
+}
+
+export function createRunFinalizationRuntime(options = {}) {
+  const runGoalChecks = requireFunction(options.runGoalChecks, "runGoalChecks")
+  const applyGoalNoProgressGuard = requireFunction(options.applyGoalNoProgressGuard, "applyGoalNoProgressGuard")
+  const createCheckpoint = requireFunction(options.createCheckpoint, "createCheckpoint")
+  const scheduleDueWork = requireFunction(options.scheduleDueWork, "scheduleDueWork")
+
+  const now = typeof options.now === "function" ? options.now : defaultNow
+  const writeState = typeof options.writeState === "function" ? options.writeState : defaultWriteState
+  const appendLoopLog = typeof options.appendLoopLog === "function" ? options.appendLoopLog : defaultAppendLoopLog
+  const runShellCommand = typeof options.runShellCommand === "function" ? options.runShellCommand : defaultRunShellCommand
+  const notifyJob = typeof options.notifyJob === "function" ? options.notifyJob : defaultNotifyJob
+  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
+
+  async function finalizeJob(directory, client, sessionID, state, job, previousJob) {
+    if (job.verifyCommand) {
+      const verify = await runShellCommand(job.verifyCommand, directory, job.timeoutMs || 300_000)
+      job.lastVerifyAt = now()
+      job.lastVerifyCode = verify.code
+      if (verify.code === 0) {
+        job.failureCount = 0
+        job.lastVerifyFailure = ""
+        await toast(client, "Loop verify passed: " + job.verifyCommand, "success")
+      } else {
+        job.failureCount = (job.failureCount || 0) + 1
+        job.lastVerifyFailure = (job.verifyCommand + "\nexit=" + verify.code + "\n" + verify.stdout + "\n" + verify.stderr).slice(0, 4000)
+        await toast(client, "Loop verify failed: " + job.verifyCommand, "warning")
+        if (job.pauseOnVerifyFail || (job.maxFailures > 0 && job.failureCount >= job.maxFailures)) {
+          job.paused = true
+          await notifyJob(directory, job, "verify_failed")
+        }
+      }
+      await appendLoopLog(directory, "verify", {
+        sessionID,
+        job: job.name || job.id,
+        command: job.verifyCommand,
+        code: verify.code,
+        failures: job.failureCount || 0,
+      })
+    }
+
+    if (job.postrunCommand) {
+      if (job.safe && dangerousShell(job.postrunCommand)) {
+        await appendLoopLog(directory, "postrun-blocked", {
+          sessionID,
+          job: job.name || job.id,
+          command: job.postrunCommand,
+        })
+      } else {
+        const postrun = await runShellCommand(job.postrunCommand, directory, job.timeoutMs || 300_000)
+        job.lastPostrunCode = postrun.code
+        job.lastPostrunAt = now()
+        if (postrun.code !== 0) {
+          job.failureCount = (job.failureCount || 0) + 1
+          job.lastPostrunFailure = (job.postrunCommand + "\nexit=" + postrun.code + "\n" + postrun.stdout + "\n" + postrun.stderr).slice(0, 4000)
+          if (job.maxFailures > 0 && job.failureCount >= job.maxFailures) {
+            job.paused = true
+            await notifyJob(directory, job, "postrun_failed")
+          }
+        }
+        await appendLoopLog(directory, "postrun", {
+          sessionID,
+          job: job.name || job.id,
+          command: job.postrunCommand,
+          code: postrun.code,
+        })
+      }
+    }
+
+    if (isGoalJob(job)) {
+      job = await runGoalChecks(directory, sessionID, job, client)
+      job = await applyGoalNoProgressGuard(directory, client, sessionID, job, previousJob)
+    }
+
+    state.jobs = (state.jobs || [])
+      .map((candidate) => candidate.id === job.id ? job : candidate)
+      .filter((candidate) => candidate.enabled !== false || isGoalJob(candidate))
+    await writeState(directory, sessionID, state)
+    if (isGoalJob(job)) await writeGoalReport(directory, sessionID, job)
+    await createCheckpoint(directory, sessionID, job, client)
+    await scheduleDueWork(directory, client, sessionID)
+    return job
+  }
+
+  return { finalizeJob }
+}

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

package/src/source/runtime/session-status.js

@@ -130,6 +130,24 @@ export function createSessionStatusRuntime(options = {}) {
     return cached === "idle" && seenAt > (active.startedAt || 0)
   }
 
+  async function recoverCompletedTailWithoutActiveRun(directory, client, sessionID, liveType, seenAt) {
+    if (activeRuns.has(sessionID)) return false
+    if (liveType !== "busy" && liveType !== "retry") return false
+    // Never override the first fresh busy observation. Waiting at least one cache
+    // window gives the host time to expose a new user/assistant turn if it is real.
+    if (!seenAt || now() - seenAt < sessionStatusCacheMs) return false
+    const completion = await activeRunCompletionFromMessages(directory, client, sessionID, { startedAt: 0 })
+    if (completion !== "completed") return false
+    markSessionStatus(sessionID, "idle")
+    await appendLoopLog(directory, "status-message-idle-recovery", {
+      sessionID,
+      staleStatus: liveType,
+      statusSeenAt: seenAt,
+      staleForMs: Math.max(0, now() - seenAt),
+    })
+    return true
+  }
+
   async function sessionStatusType(client, sessionID, directory, options = {}) {
     // OpenCode can briefly report an idle session while a long-running tool or
     // subtask is still executing. Tool lifecycle hooks are the more specific
@@ -152,10 +170,16 @@ export function createSessionStatusRuntime(options = {}) {
 
     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.
+      // Some OpenCode 1.15.x/1.18.x TUI builds can leave session.status at busy
+      // after a plugin command acknowledgement. If no Loop run exists yet, a
+      // completed assistant tail plus an already-stale busy observation is a
+      // stronger signal than the unchanged live status. A genuinely running turn
+      // has an unfinished assistant tail (or latest user message) and is never
+      // force-recovered by this path.
+      if (await recoverCompletedTailWithoutActiveRun(directory, client, sessionID, live.type, seenAt)) return "idle"
+
+      // When a Loop-owned turn exists, use its exact start boundary so an older
+      // completed assistant message can never finalize a newer active run.
       if ((live.type === "busy" || live.type === "retry") && options.recoverStaleActive !== false) {
         const active = activeRuns.get(sessionID)
         if (active) {