@bybrawe/opencode-loop 0.5.28 → 0.5.29

package/src/source/runtime/executor.js

@@ -0,0 +1,558 @@
+import path from "node:path"
+import { now as defaultNow, splitFirst } from "../core/args.js"
+import { actionKind, isGoalJob } from "../core/jobs.js"
+import { pathExists as defaultPathExists, readState as defaultReadState, writeState as defaultWriteState } from "../core/state.js"
+import { appendLoopLog as defaultAppendLoopLog, runShellCommand as defaultRunShellCommand, notifyJob as defaultNotifyJob } from "../core/process.js"
+import { sdkErrorMessage as defaultErrorMessage, sdkCall as defaultSdkCall } from "../opencode/sdk.js"
+import { normalizedModelRef as defaultNormalizedModelRef } from "../opencode/session-context.js"
+import { fireSdk as defaultFireSdk, compactTuiCommandName as defaultCompactTuiCommandName, log as defaultLog, toast as defaultToast } from "../opencode/host.js"
+import { guardLoopOwnedUserMessage as defaultGuardLoopOwnedUserMessage } from "../opencode/messages.js"
+import { writeGoalReport as defaultWriteGoalReport } from "./goal-runtime.js"
+import { dangerousShell as defaultDangerousShell } from "./job-workspace.js"
+import { createSessionStatusRuntime } from "./session-status.js"
+import { createCompactionRuntime } from "./compaction.js"
+
+const DEFAULT_ACTIVE_GUARD_MS = 45_000
+const DEFAULT_BUSY_RETRY_MS = 5_000
+
+function requireFunction(value, label) {
+  if (typeof value !== "function") throw new TypeError(`createLoopExecutor requires ${label}`)
+  return value
+}
+
+export function createLoopExecutor(options = {}) {
+  const workspace = options.workspace || {}
+  const goalPolicy = options.goalPolicy || {}
+  const scheduler = options.scheduler || {}
+
+  const buildPrompt = requireFunction(workspace.buildPrompt, "workspace.buildPrompt")
+  const ensureBranch = requireFunction(workspace.ensureBranch, "workspace.ensureBranch")
+  const watchChanged = requireFunction(workspace.watchChanged, "workspace.watchChanged")
+  const untilReached = requireFunction(workspace.untilReached, "workspace.untilReached")
+  const createCheckpoint = requireFunction(workspace.createCheckpoint, "workspace.createCheckpoint")
+  const runGoalChecks = requireFunction(goalPolicy.runGoalChecks, "goalPolicy.runGoalChecks")
+  const applyGoalNoProgressGuard = requireFunction(goalPolicy.applyGoalNoProgressGuard, "goalPolicy.applyGoalNoProgressGuard")
+  const rememberSession = requireFunction(scheduler.rememberSession, "scheduler.rememberSession")
+  const scheduleDueWork = requireFunction(scheduler.scheduleDueWork, "scheduler.scheduleDueWork")
+
+  const now = typeof options.now === "function" ? options.now : defaultNow
+  const readState = typeof options.readState === "function" ? options.readState : defaultReadState
+  const writeState = typeof options.writeState === "function" ? options.writeState : defaultWriteState
+  const pathExists = typeof options.pathExists === "function" ? options.pathExists : defaultPathExists
+  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 errorMessage = typeof options.errorMessage === "function" ? options.errorMessage : defaultErrorMessage
+  const sdkCall = typeof options.sdkCall === "function" ? options.sdkCall : defaultSdkCall
+  const normalizedModelRef = typeof options.normalizedModelRef === "function" ? options.normalizedModelRef : defaultNormalizedModelRef
+  const fireSdk = typeof options.fireSdk === "function" ? options.fireSdk : defaultFireSdk
+  const compactTuiCommandName = typeof options.compactTuiCommandName === "function" ? options.compactTuiCommandName : defaultCompactTuiCommandName
+  const log = typeof options.log === "function" ? options.log : defaultLog
+  const toast = typeof options.toast === "function" ? options.toast : defaultToast
+  const guardLoopOwnedUserMessage = typeof options.guardLoopOwnedUserMessage === "function"
+    ? options.guardLoopOwnedUserMessage
+    : defaultGuardLoopOwnedUserMessage
+  const writeGoalReport = typeof options.writeGoalReport === "function" ? options.writeGoalReport : defaultWriteGoalReport
+  const dangerousShell = typeof options.dangerousShell === "function" ? options.dangerousShell : defaultDangerousShell
+  const activeGuardMs = Number.isFinite(Number(options.activeGuardMs)) && Number(options.activeGuardMs) > 0
+    ? Number(options.activeGuardMs)
+    : DEFAULT_ACTIVE_GUARD_MS
+  const busyRetryMs = Number.isFinite(Number(options.busyRetryMs)) && Number(options.busyRetryMs) > 0
+    ? Number(options.busyRetryMs)
+    : DEFAULT_BUSY_RETRY_MS
+
+  const activeRuns = new Map()
+  const runLocks = new Map()
+
+  const statusRuntime = createSessionStatusRuntime({
+    activeRuns,
+    appendLoopLog,
+    now,
+    activeRunCompletionFromMessages: options.activeRunCompletionFromMessages,
+    staleActiveRecoveryMs: options.staleActiveRecoveryMs,
+    sessionStatusCacheMs: options.sessionStatusCacheMs,
+  })
+  const {
+    updateSessionStatusFromEvent,
+    staleActiveRun,
+    canFinalizeActiveRun,
+    sessionIsIdle,
+    markSessionStatus,
+    clearSessionStatus,
+  } = statusRuntime
+
+  const compactionRuntime = createCompactionRuntime({
+    activeRuns,
+    finalizeActiveRun,
+    appendLoopLog,
+    compactSession: options.compactSession,
+    log,
+    errorMessage,
+    now,
+  })
+
+  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))
+  }
+
+  function clearActiveRun(sessionID) {
+    const active = activeRuns.get(sessionID)
+    if (active?.timer) clearTimeout(active.timer)
+    compactionRuntime.clearForActiveRun(sessionID, active)
+    activeRuns.delete(sessionID)
+  }
+
+  function disposeSession(sessionID) {
+    clearActiveRun(sessionID)
+    runLocks.delete(sessionID)
+    compactionRuntime.clear(sessionID)
+    clearSessionStatus(sessionID)
+  }
+
+  async function recoverActiveDispatchFailure(directory, client, sessionID, jobId, runToken, error) {
+    const active = activeRuns.get(sessionID)
+    if (!active || active.jobId !== jobId || active.runToken !== runToken) return false
+
+    clearActiveRun(sessionID)
+    clearSessionStatus(sessionID)
+
+    const message = errorMessage(error)
+    const state = await readState(directory, sessionID)
+    const job = (state.jobs || []).find((candidate) => candidate.id === jobId)
+    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")
+      }
+      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)
+    return true
+  }
+
+  async function finalizeActiveRun(directory, client, sessionID, finalizeOptions = {}) {
+    const active = activeRuns.get(sessionID)
+    if (!active) return
+    if (!await canFinalizeActiveRun(directory, client, sessionID, active, finalizeOptions)) return false
+    const recoveredStale = staleActiveRun(sessionID)
+    if (active.compactionOnly) {
+      const pending = compactionRuntime.getPending(sessionID)
+      clearActiveRun(sessionID)
+      clearSessionStatus(sessionID)
+      await appendLoopLog(directory, pending?.completedAt ? "compact-finished" : "compact-idle-fallback", {
+        sessionID,
+        job: active.job?.name || active.jobId,
+        startedAt: active.startedAt,
+        nativeEvent: Boolean(pending?.completedAt),
+      })
+      await scheduleDueWork(directory, client, sessionID)
+      return true
+    }
+
+    clearActiveRun(sessionID)
+    const state = await readState(directory, sessionID)
+    let job = (state.jobs || []).find((candidate) => candidate.id === active.jobId)
+    if (!job) return
+    job.lastFinishedAt = now()
+    if (recoveredStale) {
+      await appendLoopLog(directory, "active-stale-recovery", {
+        sessionID,
+        job: job.name || job.id,
+        startedAt: active.startedAt,
+      })
+    }
+
+    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, active.job)
+    }
+    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 true
+  }
+
+  async function fireAction(directory, client, sessionID, job) {
+    const action = String(job.action || "").trim()
+    const kind = actionKind(action, job)
+    const agent = job.agent || "build"
+    const model = normalizedModelRef(job.model)
+
+    if (kind === "compact") {
+      const ok = await compactionRuntime.start(directory, client, sessionID, job.id, model, false)
+      return { startsAssistantTurn: ok, pause: !ok, reason: "compact_failed", compaction: ok }
+    }
+
+    if (kind === "command") {
+      const normalized = action.startsWith("/") ? action.slice(1) : action
+      const [command, argumentsText] = splitFirst(normalized)
+      if (!command) {
+        await toast(client, "Loop command action is empty. Example: /loop-command 200m /compact", "warning")
+        return { startsAssistantTurn: false, pause: true, reason: "empty_command" }
+      }
+      const tuiCommand = compactTuiCommandName(command)
+      if (tuiCommand) {
+        guardLoopOwnedUserMessage(sessionID)
+        const ok = await compactionRuntime.start(directory, client, sessionID, job.id, model, false)
+        return { startsAssistantTurn: ok, pause: !ok, reason: "compact_failed", compaction: ok }
+      }
+      guardLoopOwnedUserMessage(sessionID)
+      const commandBody = { command, arguments: argumentsText, agent }
+      if (model) commandBody.model = `${model.providerID}/${model.modelID}`
+      await sdkCall(
+        client.session.command.bind(client.session),
+        { path: { id: sessionID }, body: commandBody },
+        { path: { sessionID }, body: commandBody },
+        { sessionID, ...commandBody },
+      )
+      return { startsAssistantTurn: true }
+    }
+
+    if (kind === "shell") {
+      const command = action.replace(/^[!$]\s*/, "").trim()
+      if (job.safe && dangerousShell(command)) {
+        await toast(client, `Blocked dangerous shell command in safe mode: ${command}`, "error")
+        await appendLoopLog(directory, "blocked", { sessionID, job: job.name || job.id, command })
+        return { startsAssistantTurn: false, pause: true, reason: "safe_shell_blocked" }
+      }
+      guardLoopOwnedUserMessage(sessionID)
+      const shellBody = { command, agent }
+      if (model) shellBody.model = model
+      const dispatch = fireSdk(
+        client,
+        "session.shell",
+        client.session.shell.bind(client.session),
+        { path: { id: sessionID }, body: shellBody },
+        { path: { sessionID }, body: shellBody },
+        { sessionID, ...shellBody },
+      )
+      return { startsAssistantTurn: true, dispatch }
+    }
+
+    const prompt = await buildPrompt(directory, job)
+    const prefix = kind === "goal"
+      ? "EXPERIMENTAL GOAL MODE CONTINUATION. Continue pursuing the active goal. Do not explain the /loop-goal command. Use the goal tools only when progress/completion/block state is real."
+      : "AUTONOMOUS OPENCODE LOOP ITERATION. Continue the configured task now. Do not explain the /loop command. Do not search for documentation about this plugin. Do not create scheduler files. Do not ask questions. Make reasonable assumptions and work directly."
+    const promptText = `${prefix}\n\n${prompt}`
+    guardLoopOwnedUserMessage(sessionID)
+    const promptBody = { agent, parts: [{ type: "text", text: promptText }] }
+    if (model) promptBody.model = model
+    const dispatch = fireSdk(
+      client,
+      "session.prompt",
+      client.session.prompt.bind(client.session),
+      { path: { id: sessionID }, body: promptBody },
+      { path: { sessionID }, body: promptBody },
+      { sessionID, ...promptBody },
+    )
+    return { startsAssistantTurn: true, dispatch }
+  }
+
+  async function maybeRunDueJobs(directory, client, sessionID, runOptions = {}) {
+    rememberSession(directory, client, sessionID)
+    const reschedule = async (minDelayMs = 0) => {
+      await scheduleDueWork(directory, client, sessionID, minDelayMs)
+    }
+
+    if (runLocks.has(sessionID)) {
+      await reschedule(busyRetryMs)
+      return
+    }
+    runLocks.set(sessionID, now())
+    let job
+    try {
+      await finalizeActiveRun(directory, client, sessionID, { requireIdle: true, forceStale: true })
+      if (!await sessionIsIdle(client, sessionID, directory)) {
+        if (runOptions.force) await toast(client, "Loop queued: session is busy; it will run on the next idle check.", "info")
+        await reschedule(busyRetryMs)
+        return
+      }
+
+      const active = activeRuns.get(sessionID)
+      const activeAge = active ? now() - (active.startedAt || 0) : 0
+      const activeGuard = active?.job?.timeoutMs || active?.job?.activeRecoveryMs || activeGuardMs
+      if (active && active.job?.noOverlap !== false && activeAge < activeGuard) {
+        await reschedule(busyRetryMs)
+        return
+      }
+      if (active && activeAge >= activeGuard) clearActiveRun(sessionID)
+
+      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.watchTriggered = true
+        }
+      }
+      const due = dueJobs(state, Boolean(runOptions.force))
+      if (!due.length) {
+        await writeState(directory, sessionID, state)
+        await reschedule()
+        return
+      }
+      job = due[0]
+      const runNowRequested = Number(job.runNowRequestedAt || 0) > 0
+
+      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
+      }
+
+      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()
+          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) {
+          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()
+          return
+        }
+      }
+
+      job = await ensureBranch(directory, job, client, sessionID)
+      const compactResult = await compactionRuntime.maybeCompact(directory, client, sessionID, job)
+      job = compactResult.job
+      if (compactResult.started) {
+        state.jobs = (state.jobs || []).map((candidate) => candidate.id === job.id ? job : candidate)
+        await writeState(directory, sessionID, state)
+        let timer
+        if (job.timeoutMs > 0) {
+          timer = setTimeout(() => {
+            fireSdk(
+              client,
+              "session.abort",
+              client.session.abort.bind(client.session),
+              { path: { id: sessionID }, body: {} },
+              { path: { sessionID }, body: {} },
+              { sessionID },
+            )
+            toast(client, `Loop compact timeout fired: ${job.name || job.id}`, "warning").catch(() => {})
+          }, job.timeoutMs)
+        }
+        const runToken = `${job.id}:compact:${now().toString(36)}:${Math.random().toString(16).slice(2)}`
+        activeRuns.set(sessionID, { jobId: job.id, job, startedAt: now(), timer, runToken, compactionOnly: true })
+        if (compactionRuntime.isCompleted(sessionID, job.id)) {
+          await compactionRuntime.finalize(directory, client, sessionID)
+          return
+        }
+        markSessionStatus(sessionID, "busy")
+        await reschedule(busyRetryMs)
+        return
+      }
+
+      if (runNowRequested) delete job.runNowRequestedAt
+      job.watchTriggered = false
+      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)
+          if (result.pause) {
+            fresh.jobs = (fresh.jobs || []).map((candidate) => candidate.id === job.id ? {
+              ...candidate,
+              paused: true,
+              failureCount: (candidate.failureCount || 0) + 1,
+              lastFailureReason: result.reason || "action_did_not_start",
+            } : candidate)
+          }
+          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),
+              { path: { id: sessionID }, body: {} },
+              { path: { sessionID }, body: {} },
+              { sessionID },
+            )
+            toast(client, `Loop timeout fired: ${job.name || job.id}`, "warning").catch(() => {})
+          }, job.timeoutMs)
+        }
+        const runToken = `${job.id}:${now().toString(36)}:${Math.random().toString(16).slice(2)}`
+        activeRuns.set(sessionID, {
+          jobId: job.id,
+          job,
+          startedAt: now(),
+          timer,
+          runToken,
+          compactionAction: result.compaction === true,
+        })
+        if (result.compaction && compactionRuntime.isCompleted(sessionID, job.id)) {
+          await compactionRuntime.finalize(directory, client, sessionID)
+          return
+        }
+        if (result.dispatch) {
+          void result.dispatch.catch((error) => {
+            recoverActiveDispatchFailure(directory, client, sessionID, job.id, runToken, error)
+              .catch((recoveryError) => log(client, "error", "dispatch recovery failed", { error: errorMessage(recoveryError) }))
+          })
+        }
+        markSessionStatus(sessionID, "busy")
+        await reschedule(busyRetryMs)
+      } 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(busyRetryMs)
+      }
+    } finally {
+      runLocks.delete(sessionID)
+    }
+  }
+
+  return {
+    dueJobs,
+    clearActiveRun,
+    disposeSession,
+    recoverActiveDispatchFailure,
+    finalizeActiveRun,
+    fireAction,
+    maybeRunDueJobs,
+    sessionIsIdle,
+    updateSessionStatusFromEvent,
+    markSessionStatus,
+    clearSessionStatus,
+    noteLoopCompactionStarted: compactionRuntime.noteStarted,
+    noteLoopCompactionCompleted: compactionRuntime.noteCompleted,
+    getActiveRun: (sessionID) => activeRuns.get(sessionID),
+    isRunLocked: (sessionID) => runLocks.has(sessionID),
+  }
+}

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

@@ -0,0 +1,77 @@
+import { DEFAULT_GOAL_MAX_NO_PROGRESS, now as defaultNow } from "../core/args.js"
+import { isGoalJob } from "../core/jobs.js"
+import { appendLoopLog as defaultAppendLoopLog } from "../core/process.js"
+import { goalMadeMeaningfulProgress } from "./goal-runtime.js"
+
+function requireFunction(value, name) {
+  if (typeof value !== "function") throw new TypeError(`createGoalExecutionPolicy requires ${name}`)
+  return value
+}
+
+export function createGoalExecutionPolicy(options = {}) {
+  const runShellCommand = requireFunction(options.runShellCommand, "runShellCommand")
+  const dangerousShell = requireFunction(options.dangerousShell, "dangerousShell")
+  const toast = requireFunction(options.toast, "toast")
+  const now = typeof options.now === "function" ? options.now : defaultNow
+  const appendLoopLog = typeof options.appendLoopLog === "function" ? options.appendLoopLog : defaultAppendLoopLog
+
+  async function applyGoalNoProgressGuard(directory, client, sessionID, job, beforeJob) {
+    if (!isGoalJob(job) || ["completed", "blocked"].includes(job.goalStatus) || job.paused || job.enabled === false) return job
+    const limit = Number(job.maxNoProgress ?? DEFAULT_GOAL_MAX_NO_PROGRESS)
+    if (!Number.isFinite(limit) || limit <= 0) return job
+    if (goalMadeMeaningfulProgress(beforeJob, job)) {
+      job.noProgressCount = 0
+      job.lastProgressAt = now()
+      return job
+    }
+    job.noProgressCount = (job.noProgressCount || 0) + 1
+    job.lastNoProgressAt = now()
+    await appendLoopLog(directory, "goal-no-progress", { sessionID, job: job.name || job.id, count: job.noProgressCount, limit })
+    if (job.noProgressCount >= limit) {
+      job.paused = true
+      job.goalNoProgressPausedAt = now()
+      job.goalNoProgressReason = `Paused after ${job.noProgressCount} turn(s) without recorded progress. Resume with /loop-goal-resume after adjusting the goal or evidence.`
+      await toast(client, job.goalNoProgressReason, "warning")
+      await appendLoopLog(directory, "goal-no-progress-paused", { sessionID, job: job.name || job.id, count: job.noProgressCount, limit })
+    }
+    return job
+  }
+
+  async function runGoalChecks(directory, sessionID, job, client) {
+    if (!isGoalJob(job) || !job.goalChecks?.length || ["completed", "blocked"].includes(job.goalStatus)) return job
+    const results = []
+    for (const command of job.goalChecks) {
+      if (job.safe && dangerousShell(command)) {
+        results.push({ command, code: -1, output: "Blocked dangerous command in safe mode." })
+        continue
+      }
+      const result = await runShellCommand(command, directory, job.timeoutMs || 300_000)
+      results.push({ command, code: result.code, output: (result.stdout + "\n" + result.stderr).slice(0, 1200) })
+    }
+    job.lastGoalCheckAt = now()
+    job.lastGoalChecks = results
+    const allPassed = results.length > 0 && results.every((item) => item.code === 0)
+    if (allPassed) {
+      job.goalChecksPassedAt = now()
+      job.failureCount = 0
+      await toast(client, "Goal checks passed.", "success")
+      if (job.goalCompleteWhenChecksPass) {
+        job.goalStatus = "completed"
+        job.enabled = false
+        job.paused = true
+        job.goalCompletedAt = now()
+        job.goalSummary = job.goalSummary || "All configured goal checks passed."
+        job.goalEvidence = results.map((item) => `${item.command}: exit ${item.code}`).join("\n")
+        await appendLoopLog(directory, "goal-auto-complete", { sessionID, job: job.name || job.id })
+      }
+    } else {
+      job.failureCount = (job.failureCount || 0) + 1
+      job.lastVerifyFailure = results.map((item) => `${item.command}\nexit=${item.code}\n${item.output}`).join("\n\n").slice(0, 4000)
+      await toast(client, "Goal checks still failing; goal will continue on next idle turn.", "warning")
+    }
+    await appendLoopLog(directory, "goal-checks", { sessionID, job: job.name || job.id, results: results.map((item) => ({ command: item.command, code: item.code })) })
+    return job
+  }
+
+  return { runGoalChecks, applyGoalNoProgressGuard }
+}