@bybrawe/opencode-loop 0.5.28 → 0.5.30

package/src/source/opencode/command-router.js

@@ -0,0 +1,103 @@
+import { presetDefaults } from "../core/jobs.js"
+import { captureSessionExecutionContext as defaultCaptureSessionExecutionContext } from "./session-context.js"
+import { guardLoopOwnedUserMessage as defaultGuardLoopOwnedUserMessage } from "./messages.js"
+import {
+  markHandled,
+  consumeHandled,
+  hasHandledCommandEvent,
+  markHandledCommandEvent,
+  forgetHandledCommandEvent,
+  commandName,
+  isPreset,
+  isLoopCommandName,
+  commandArgsText,
+} from "./commands.js"
+
+const HANDLER_NAMES = [
+  "addGoal",
+  "statusGoal",
+  "pauseGoal",
+  "resumeGoal",
+  "clearGoal",
+  "completeGoalCommand",
+  "blockGoalCommand",
+  "addLoop",
+  "stopLoop",
+  "statusLoop",
+  "logsLoop",
+  "helpLoop",
+  "runNow",
+  "updateJobState",
+  "doctorLoop",
+  "initLoop",
+  "exportLoop",
+]
+
+function requireFunction(value, name) {
+  if (typeof value !== "function") throw new TypeError(`createCommandRouter requires ${name}`)
+  return value
+}
+
+export function createCommandRouter(options = {}) {
+  const rememberSession = requireFunction(options.rememberSession, "rememberSession")
+  const captureSessionExecutionContext = typeof options.captureSessionExecutionContext === "function"
+    ? options.captureSessionExecutionContext
+    : defaultCaptureSessionExecutionContext
+  const guardLoopOwnedUserMessage = typeof options.guardLoopOwnedUserMessage === "function"
+    ? options.guardLoopOwnedUserMessage
+    : defaultGuardLoopOwnedUserMessage
+  const handlers = {}
+  for (const name of HANDLER_NAMES) handlers[name] = requireFunction(options.handlers?.[name], `handlers.${name}`)
+
+  return async function handleCommand(directory, client, input, fallbackName, fallbackArgs, output, source = "before") {
+    const name = commandName(input?.command ?? input?.name ?? fallbackName)
+    const sessionID = input?.sessionID
+    const args = commandArgsText(input?.arguments ?? fallbackArgs ?? "")
+    if (!sessionID || !name) return false
+    rememberSession(directory, client, sessionID)
+    if (isLoopCommandName(name)) await captureSessionExecutionContext(client, sessionID)
+    if (source === "event") {
+      if (consumeHandled(sessionID, name, args)) return true
+      if (hasHandledCommandEvent(sessionID, input?.messageID)) return true
+      markHandledCommandEvent(sessionID, input?.messageID)
+    } else {
+      // Every before-hook invocation is an intentional command. Keep a pending
+      // count only so the matching command.executed compatibility event can be
+      // consumed without suppressing a genuine repeated command.
+      markHandled(sessionID, name, args)
+    }
+    if (isLoopCommandName(name)) guardLoopOwnedUserMessage(sessionID)
+
+    const handled = () => {
+      // OpenCode 1.18.x ignores unknown hook output fields, while proposed/newer
+      // hosts can honor noReply to skip the otherwise unavoidable model turn.
+      // Keep acknowledgement parts intact as the compatibility fallback.
+      if (output && typeof output === "object") output.noReply = true
+      return true
+    }
+
+    if (name === "loop-goal") return await handlers.addGoal(directory, client, sessionID, args), handled()
+    if (name === "loop-goal-status") return await handlers.statusGoal(directory, client, sessionID), handled()
+    if (name === "loop-goal-pause") return await handlers.pauseGoal(directory, client, sessionID, args), handled()
+    if (name === "loop-goal-resume") return await handlers.resumeGoal(directory, client, sessionID, args), handled()
+    if (name === "loop-goal-clear") return await handlers.clearGoal(directory, client, sessionID, args), handled()
+    if (name === "loop-goal-done" || name === "loop-goal-complete") return await handlers.completeGoalCommand(directory, client, sessionID, args), handled()
+    if (name === "loop-goal-blocked") return await handlers.blockGoalCommand(directory, client, sessionID, args), handled()
+    if (name === "loop") return await handlers.addLoop(directory, client, sessionID, args), handled()
+    if (isPreset(name)) return await handlers.addLoop(directory, client, sessionID, args, presetDefaults(name, args)), handled()
+    if (name === "loop-stop" || name === "loop-remove") return await handlers.stopLoop(directory, client, sessionID, args), handled()
+    if (name === "loop-clear") return await handlers.stopLoop(directory, client, sessionID, "all"), handled()
+    if (name === "loop-status") return await handlers.statusLoop(directory, client, sessionID), handled()
+    if (name === "loop-logs") return await handlers.logsLoop(directory, client, sessionID), handled()
+    if (name === "loop-help") return await handlers.helpLoop(client, sessionID), handled()
+    if (name === "loop-now") return await handlers.runNow(directory, client, sessionID, args), handled()
+    if (name === "loop-pause") return await handlers.updateJobState(directory, client, sessionID, args, (job) => ({ ...job, paused: true }), "Paused"), handled()
+    if (name === "loop-resume") return await handlers.updateJobState(directory, client, sessionID, args, (job) => ({ ...job, paused: false, lastRunAt: 0 }), "Resumed"), handled()
+    if (name === "loop-doctor") return await handlers.doctorLoop(directory, client, sessionID), handled()
+    if (name === "loop-init") return await handlers.initLoop(directory, client, sessionID, args), handled()
+    if (name === "loop-export") return await handlers.exportLoop(directory, client, sessionID), handled()
+    if (source === "event") forgetHandledCommandEvent(sessionID, input?.messageID)
+    else consumeHandled(sessionID, name, args)
+    return false
+  }
+}

package/src/source/opencode/commands.js

@@ -0,0 +1,83 @@
+import { now } from "../core/args.js"
+
+const COMMAND_DEDUPE_MS = 30_000
+const handledCommands = new Map()
+const handledCommandEvents = new Map()
+
+function normalizeArgsForKey(args) {
+  if (args === undefined || args === null) return ""
+  if (typeof args === "string") return args.trim().replace(/\s+/g, " ")
+  if (Array.isArray(args)) return args.map(normalizeArgsForKey).join(" ").trim().replace(/\s+/g, " ")
+  try { return JSON.stringify(args) } catch { return String(args) }
+}
+
+function commandKey(sessionID, name, args) {
+  return `${sessionID || "no-session"}:${name || ""}:${normalizeArgsForKey(args)}`
+}
+
+function commandEventKey(sessionID, messageID) {
+  return `${sessionID || "no-session"}:event:${messageID || "no-message"}`
+}
+
+export function markHandled(sessionID, name, args) {
+  const key = commandKey(sessionID, name, args)
+  const previous = handledCommands.get(key)
+  const pending = previous && now() - previous.time < COMMAND_DEDUPE_MS ? previous.pending + 1 : 1
+  handledCommands.set(key, { time: now(), pending })
+  for (const [entryKey, entry] of handledCommands.entries()) if (now() - entry.time > COMMAND_DEDUPE_MS) handledCommands.delete(entryKey)
+  for (const [entryKey, time] of handledCommandEvents.entries()) if (now() - time > COMMAND_DEDUPE_MS) handledCommandEvents.delete(entryKey)
+}
+
+export function consumeHandled(sessionID, name, args) {
+  const key = commandKey(sessionID, name, args)
+  const entry = handledCommands.get(key)
+  if (!entry || now() - entry.time >= COMMAND_DEDUPE_MS) {
+    handledCommands.delete(key)
+    return false
+  }
+  if (entry.pending <= 1) handledCommands.delete(key)
+  else handledCommands.set(key, { time: entry.time, pending: entry.pending - 1 })
+  return true
+}
+
+export function hasHandledCommandEvent(sessionID, messageID) {
+  return handledCommandEvents.has(commandEventKey(sessionID, messageID))
+}
+
+export function markHandledCommandEvent(sessionID, messageID) {
+  handledCommandEvents.set(commandEventKey(sessionID, messageID), now())
+}
+
+export function forgetHandledCommandEvent(sessionID, messageID) {
+  handledCommandEvents.delete(commandEventKey(sessionID, messageID))
+}
+
+export function clearCommandLifecycle(sessionID) {
+  const prefix = `${sessionID}:`
+  for (const key of handledCommands.keys()) if (key.startsWith(prefix)) handledCommands.delete(key)
+  for (const key of handledCommandEvents.keys()) if (key.startsWith(prefix)) handledCommandEvents.delete(key)
+}
+
+export function commandName(name) {
+  return String(name || "")
+}
+
+export function isPreset(name) {
+  return ["loop-dev", "loop-testfix", "loop-compact", "loop-progress", "loop-safe-dev", "loop-command", "loop-cmd", "loop-prompt", "loop-ask", "loop-shell"].includes(name)
+}
+
+export function isLoopCommandName(name) {
+  return name === "loop" || name === "loop-stop" || name === "loop-remove" || name === "loop-clear" || name === "loop-status" || name === "loop-logs" || name === "loop-help" || name === "loop-now" || name === "loop-pause" || name === "loop-resume" || name === "loop-doctor" || name === "loop-init" || name === "loop-export" || name === "loop-goal" || name === "loop-goal-status" || name === "loop-goal-pause" || name === "loop-goal-resume" || name === "loop-goal-clear" || name === "loop-goal-done" || name === "loop-goal-complete" || name === "loop-goal-blocked" || isPreset(name)
+}
+
+export function commandArgsText(args) {
+  if (args === undefined || args === null) return ""
+  if (typeof args === "string") return args
+  if (Array.isArray(args)) return args.map(commandArgsText).join(" ")
+  if (typeof args === "object") {
+    for (const key of ["arguments", "args", "message", "text", "value"]) {
+      if (args[key] !== undefined) return commandArgsText(args[key])
+    }
+  }
+  return String(args)
+}

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

@@ -0,0 +1,107 @@
+import { DEFAULT_GOAL_MAX_NO_PROGRESS, splitFirst } from "../core/args.js"
+import { isGoalJob, matchJob, goalStatusText } from "../core/jobs.js"
+import { readState as defaultReadState, writeState as defaultWriteState } from "../core/state.js"
+import { setGoalComplete as defaultSetGoalComplete, setGoalBlocked as defaultSetGoalBlocked } from "../runtime/goal-runtime.js"
+
+function requireFunction(value, name) {
+  if (typeof value !== "function") throw new TypeError(`createGoalCommandHandlers requires ${name}`)
+  return value
+}
+
+export function createGoalCommandHandlers(options = {}) {
+  const addLoop = requireFunction(options.addLoop, "addLoop")
+  const scheduleDueWork = requireFunction(options.scheduleDueWork, "scheduleDueWork")
+  const scheduleIdleWork = requireFunction(options.scheduleIdleWork, "scheduleIdleWork")
+  const toast = requireFunction(options.toast, "toast")
+  const say = requireFunction(options.say, "say")
+  const readState = typeof options.readState === "function" ? options.readState : defaultReadState
+  const writeState = typeof options.writeState === "function" ? options.writeState : defaultWriteState
+  const setGoalComplete = typeof options.setGoalComplete === "function" ? options.setGoalComplete : defaultSetGoalComplete
+  const setGoalBlocked = typeof options.setGoalBlocked === "function" ? options.setGoalBlocked : defaultSetGoalBlocked
+
+  async function statusGoal(directory, client, sessionID) {
+    const state = await readState(directory, sessionID)
+    const goals = (state.jobs || []).filter(isGoalJob)
+    const lines = goals.length ? goals.map((job, index) => {
+      const status = goalStatusText(job)
+      const checks = job.goalChecks?.length ? ` | checks=${job.goalChecks.length}` : ""
+      const acceptance = job.goalAcceptance?.length ? ` | acceptance=${job.goalAcceptance.length}` : ""
+      const progress = job.goalProgress?.length ? ` | progress=${job.goalProgress.length}` : ""
+      const noProgress = (job.maxNoProgress ?? DEFAULT_GOAL_MAX_NO_PROGRESS) > 0 ? ` | no-progress=${job.noProgressCount || 0}/${job.maxNoProgress ?? DEFAULT_GOAL_MAX_NO_PROGRESS}` : ""
+      const rejected = job.goalCompletionRejectedReason ? " | completion-rejected" : ""
+      return `${index + 1}. ${job.id}${job.name ? ` (${job.name})` : ""}: ${status} | turns=${job.runCount || 0} | objective=${String(job.action || job.goalFile || "").slice(0, 220)}${checks}${acceptance}${progress}${noProgress}${rejected}`
+    }) : ["No experimental goal jobs."]
+    await toast(client, goals.length ? `${goals.length} experimental goal(s).` : "No experimental goal jobs.", goals.length ? "info" : "warning")
+    await say(client, sessionID, "OpenCode Loop experimental goal status:\n" + lines.join("\n"))
+  }
+
+  async function pauseGoal(directory, client, sessionID, args) {
+    const target = String(args || "").trim() || "goal"
+    const state = await readState(directory, sessionID)
+    let count = 0
+    state.jobs = (state.jobs || []).map((job, index) => isGoalJob(job) && matchJob(job, target, index) ? (count++, { ...job, paused: true }) : job)
+    await writeState(directory, sessionID, state)
+    await scheduleDueWork(directory, client, sessionID)
+    await toast(client, `Paused ${count} experimental goal(s).`, count ? "success" : "warning")
+  }
+
+  async function resumeGoal(directory, client, sessionID, args) {
+    const target = String(args || "").trim() || "goal"
+    const state = await readState(directory, sessionID)
+    let count = 0
+    state.jobs = (state.jobs || []).map((job, index) => {
+      if (!isGoalJob(job) || !matchJob(job, target, index)) return job
+      count++
+      return { ...job, paused: false, enabled: true, goalStatus: job.goalStatus === "blocked" ? "active" : (job.goalStatus || "active"), lastRunAt: 0, noProgressCount: 0, goalNoProgressReason: "", goalInterruptedReason: "" }
+    })
+    await writeState(directory, sessionID, state)
+    await toast(client, `Resumed ${count} experimental goal(s).`, count ? "success" : "warning")
+    if (count) {
+      await scheduleDueWork(directory, client, sessionID)
+      scheduleIdleWork(directory, client, sessionID)
+    }
+  }
+
+  async function clearGoal(directory, client, sessionID, args) {
+    const target = String(args || "").trim()
+    const state = await readState(directory, sessionID)
+    const before = state.jobs.length
+    state.jobs = (state.jobs || []).filter((job, index) => !isGoalJob(job) || (target && !matchJob(job, target, index)))
+    await writeState(directory, sessionID, state)
+    await scheduleDueWork(directory, client, sessionID)
+    await toast(client, `Cleared ${before - state.jobs.length} experimental goal(s).`, before !== state.jobs.length ? "success" : "warning")
+  }
+
+  async function completeGoalCommand(directory, client, sessionID, args) {
+    const result = await setGoalComplete(directory, sessionID, { summary: String(args || "").trim() || "Goal manually marked complete.", evidence: "Marked complete by /loop-goal-done.", manual: true })
+    await toast(client, result.message, result.ok ? "success" : "warning")
+  }
+
+  async function blockGoalCommand(directory, client, sessionID, args) {
+    const result = await setGoalBlocked(directory, sessionID, { reason: String(args || "").trim() || "Goal manually marked blocked.", needed: "User input or manual intervention." })
+    await toast(client, result.message, "warning")
+  }
+
+  async function addGoal(directory, client, sessionID, args) {
+    const text = String(args || "").trim()
+    const [maybeCommand, rest] = splitFirst(text)
+    const sub = maybeCommand.toLowerCase()
+    if (!text || sub === "status") return await statusGoal(directory, client, sessionID)
+    if (sub === "pause") return await pauseGoal(directory, client, sessionID, rest)
+    if (sub === "resume") return await resumeGoal(directory, client, sessionID, rest)
+    if (["clear", "remove", "stop"].includes(sub)) return await clearGoal(directory, client, sessionID, rest)
+    if (["done", "complete", "completed"].includes(sub)) return await completeGoalCommand(directory, client, sessionID, rest)
+    if (["blocked", "block"].includes(sub)) return await blockGoalCommand(directory, client, sessionID, rest)
+    return await addLoop(directory, client, sessionID, text, { intervalMs: 0, kind: "goal", name: "goal", immediate: true, safe: true, askNever: true, noOverlap: true, goalStatus: "active" })
+  }
+
+  return {
+    addGoal,
+    statusGoal,
+    pauseGoal,
+    resumeGoal,
+    clearGoal,
+    completeGoalCommand,
+    blockGoalCommand,
+  }
+}

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

@@ -0,0 +1,195 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { now as defaultNow, durationToText } 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"
+
+const SERVICE = "opencode-loop"
+const DEFAULT_PROGRESS_MD = `# Progress
+
+## Current Goal
+Describe the current project goal here.
+
+## Agent Rules
+- Do not ask questions unless truly blocked.
+- Make reasonable assumptions and continue.
+- Work on unfinished TODOs in order.
+- Mark completed TODOs with [x].
+- Add new bugs, ideas, and follow-up work as TODOs.
+- Run tests, lint, or build when available.
+- Do not run destructive commands, force pushes, production deploys, or database resets.
+
+## Active TODO
+- [ ] Review the project structure and pick the next safe improvement.
+
+## Completed
+- [x] Created progress.md.
+
+## Backlog Ideas
+- [ ] Add more project-specific tasks here.
+
+## Blocked
+- None.
+`
+
+function requireFunction(value, name) {
+  if (typeof value !== "function") throw new TypeError(`createLoopCommandHandlers requires ${name}`)
+  return value
+}
+
+export function createLoopCommandHandlers(options = {}) {
+  const clearActiveRun = requireFunction(options.clearActiveRun, "clearActiveRun")
+  const cancelDueWork = requireFunction(options.cancelDueWork, "cancelDueWork")
+  const stopWatchdog = requireFunction(options.stopWatchdog, "stopWatchdog")
+  const scheduleDueWork = requireFunction(options.scheduleDueWork, "scheduleDueWork")
+  const maybeRunDueJobs = requireFunction(options.maybeRunDueJobs, "maybeRunDueJobs")
+  const toast = requireFunction(options.toast, "toast")
+  const say = requireFunction(options.say, "say")
+  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 removeState = typeof options.removeState === "function" ? options.removeState : defaultRemoveState
+  const pathExists = typeof options.pathExists === "function" ? options.pathExists : defaultPathExists
+  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 runtimeVersion = options.runtimeVersion || process.version
+  const runtimePlatform = options.runtimePlatform || process.platform
+
+  async function stopLoop(directory, client, sessionID, args) {
+    const target = String(args || "").trim()
+    if (!target || target.toLowerCase() === "all") {
+      await removeState(directory, sessionID)
+      clearActiveRun(sessionID)
+      cancelDueWork(sessionID)
+      stopWatchdog(sessionID)
+      await toast(client, "All loops stopped for this session.", "success")
+      return
+    }
+    const state = await readState(directory, sessionID)
+    const before = state.jobs.length
+    state.jobs = state.jobs.filter((job, index) => !matchJob(job, target, index))
+    await writeState(directory, sessionID, state)
+    await scheduleDueWork(directory, client, sessionID)
+    await toast(client, `Stopped ${before - state.jobs.length} loop(s).`, "success")
+  }
+
+  async function updateJobState(directory, client, sessionID, args, updater, message) {
+    const target = String(args || "").trim() || "all"
+    const state = await readState(directory, sessionID)
+    let count = 0
+    state.jobs = (state.jobs || []).map((job, index) => matchJob(job, target, index) ? (count++, updater(job)) : job)
+    await writeState(directory, sessionID, state)
+    await scheduleDueWork(directory, client, sessionID)
+    await toast(client, `${message}: ${count} loop(s).`, count ? "success" : "warning")
+  }
+
+  async function statusLoop(directory, client, sessionID) {
+    const state = await readState(directory, sessionID)
+    const jobs = state.jobs || []
+    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 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}`
+    }) : ["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"))
+  }
+
+  async function logsLoop(directory, client, sessionID) {
+    let text = "No loop log found."
+    try { text = (await readFile(path.join(stateDir(directory), "loop.log"), "utf8")).trim().split(/\r?\n/).slice(-80).join("\n") || text } catch {}
+    await say(client, sessionID, "OpenCode loop logs:\n" + text)
+  }
+
+  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-doctor | /loop-init | /loop-export",
+    ].join("\n"))
+  }
+
+  async function runNow(directory, client, sessionID, args) {
+    const target = String(args || "").trim() || "all"
+    const state = await readState(directory, sessionID)
+    const requestedAt = Math.max(1, Number(now()) || Date.now())
+    let count = 0
+    for (const [index, job] of (state.jobs || []).entries()) {
+      if (!matchJob(job, target, index)) continue
+      job.lastRunAt = 0
+      job.paused = false
+      job.runNowRequestedAt = requestedAt
+      count += 1
+    }
+    await writeState(directory, sessionID, state)
+    await toast(client, `Marked ${count} loop job(s) due now.`, count ? "success" : "warning")
+    // /loop-now is handled in command.execute.before. Do not start a model turn re-entrantly
+    // inside that hook; schedule the persisted request and let the idle-safe timer dispatch it.
+    if (count) await scheduleDueWork(directory, client, sessionID)
+  }
+
+  async function doctorLoop(directory, client, sessionID) {
+    const state = await readState(directory, sessionID)
+    await say(client, sessionID, [
+      "OpenCode Loop doctor:",
+      `- plugin: ${SERVICE}`,
+      `- project directory: ${directory}`,
+      `- state directory: ${stateDir(directory)}`,
+      `- active jobs: ${(state.jobs || []).length}`,
+      `- node: ${runtimeVersion}`,
+      `- platform: ${runtimePlatform}`,
+      "- smoke test: /loop 0s --max-runs 1 --dry-run continue from progress.md",
+      "- experimental goal smoke test: /loop-goal --dry-run finish the current task and verify it",
+    ].join("\n"))
+  }
+
+  async function initLoop(directory, client, sessionID, args) {
+    const target = String(args || "").trim() || "progress.md"
+    const full = path.resolve(directory, target)
+    if (await pathExists(full)) { await toast(client, `${target} already exists.`, "warning"); return }
+    await writeFile(full, DEFAULT_PROGRESS_MD, "utf8")
+    await toast(client, `Created ${target}.`, "success")
+    await appendLoopLog(directory, "init", { sessionID, file: target })
+  }
+
+  async function exportLoop(directory, client, sessionID) {
+    const state = await readState(directory, sessionID)
+    await say(client, sessionID, "OpenCode loop state export:\n```json\n" + JSON.stringify(state, null, 2) + "\n```")
+  }
+
+  return {
+    stopLoop,
+    updateJobState,
+    statusLoop,
+    logsLoop,
+    helpLoop,
+    runNow,
+    doctorLoop,
+    initLoop,
+    exportLoop,
+  }
+}

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

@@ -0,0 +1,100 @@
+import { parseLoopArgs as defaultParseLoopArgs } from "../core/args.js"
+import { jobLabel, isGoalJob } from "../core/jobs.js"
+import { readState as defaultReadState, writeState as defaultWriteState } from "../core/state.js"
+import { appendLoopLog as defaultAppendLoopLog } from "../core/process.js"
+import { normalizedModelRef as defaultNormalizedModelRef, getSessionExecutionContext as defaultGetSessionExecutionContext } from "./session-context.js"
+
+const DEFAULT_GOAL_ACTIVE_RECOVERY_MS = 180_000
+const FALLBACK_ACTIVE_GUARD_MS = 45_000
+
+function requireFunction(value, name) {
+  if (typeof value !== "function") throw new TypeError(`createLoopRegistration requires ${name}`)
+  return value
+}
+
+export function normalizeActionForCompare(value) {
+  return String(value || "").replace(/\s+/g, " ").trim()
+}
+
+export function sameLoopDefinition(a, b) {
+  if (!a || !b) return false
+  return (a.name || "") === (b.name || "") &&
+    Number(a.intervalMs || 0) === Number(b.intervalMs || 0) &&
+    normalizeActionForCompare(a.action) === normalizeActionForCompare(b.action) &&
+    normalizeActionForCompare(a.kind) === normalizeActionForCompare(b.kind) &&
+    normalizeActionForCompare(a.promptFile) === normalizeActionForCompare(b.promptFile)
+}
+
+export function createLoopRegistration(options = {}) {
+  const snapshotPaths = requireFunction(options.snapshotPaths, "snapshotPaths")
+  const scheduleDueWork = requireFunction(options.scheduleDueWork, "scheduleDueWork")
+  const scheduleIdleWork = requireFunction(options.scheduleIdleWork, "scheduleIdleWork")
+  const toast = requireFunction(options.toast, "toast")
+  const say = requireFunction(options.say, "say")
+  const parseLoopArgs = typeof options.parseLoopArgs === "function" ? options.parseLoopArgs : defaultParseLoopArgs
+  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 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)
+    if (!parsed.ok) { await toast(client, parsed.error, "warning"); return }
+    const executionContext = getSessionExecutionContext(sessionID) || { agent: "build" }
+    parsed.job.agent = defaults.agent || executionContext.agent || "build"
+    parsed.job.model = normalizedModelRef(defaults.model) || executionContext.model
+    if (defaults.testfixPreset) {
+      const defaultCommand = String(defaults.verifyCommand || "npm test")
+      const parsedAction = String(parsed.job.action || "").trim()
+      const usedDefaultAction = parsedAction === String(defaults.action || "").trim()
+      if (!usedDefaultAction && parsed.job.verifyCommand === defaults.verifyCommand) {
+        parsed.job.verifyCommand = parsedAction
+        parsed.job.action = `Run the project tests. Fix failures. Re-run the tests. Test command hint: ${parsedAction}`
+      } else if (usedDefaultAction && parsed.job.verifyCommand !== defaults.verifyCommand) {
+        parsed.job.action = `Run the project tests. Fix failures. Re-run the tests. Test command hint: ${parsed.job.verifyCommand || defaultCommand}`
+      }
+    }
+    if (parsed.job.watchPaths.length) parsed.job.watchSnapshot = await snapshotPaths(directory, parsed.job.watchPaths)
+    if (!parsed.job.activeRecoveryMs) {
+      parsed.job.activeRecoveryMs = isGoalJob(parsed.job)
+        ? DEFAULT_GOAL_ACTIVE_RECOVERY_MS
+        : Math.max(defaultActiveGuardMs, Math.min(90_000, (parsed.job.intervalMs || 0) + 10_000))
+    }
+    if (parsed.job.dryRun) {
+      await toast(client, `Loop dry run: ${jobLabel(parsed.job)}`, "info")
+      await say(client, sessionID, "OpenCode loop dry run:\n```json\n" + JSON.stringify(parsed.job, null, 2) + "\n```")
+      return
+    }
+    const state = await readState(directory, sessionID)
+    const jobs = Array.isArray(state.jobs) ? state.jobs : []
+
+    // Default behavior is replace/upsert, not append forever. This prevents duplicate
+    // loops when OpenCode emits both command.execute.before and command.executed,
+    // and it matches the common expectation that /loop configures the current loop.
+    let replaced = false
+    if (!parsed.job.multi) {
+      const targetName = parsed.job.name || "default"
+      parsed.job.name = targetName
+      state.jobs = jobs.filter((existing) => {
+        const existingName = existing.name || "default"
+        const shouldReplace = existingName === targetName || sameLoopDefinition(existing, parsed.job)
+        if (shouldReplace) replaced = true
+        return !shouldReplace
+      })
+    } else {
+      state.jobs = jobs
+    }
+
+    state.jobs.push(parsed.job)
+    await writeState(directory, sessionID, state)
+    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) })
+  }
+
+  return { addLoop }
+}

package/src/source/opencode/messages.js

@@ -0,0 +1,55 @@
+import { now } from "../core/args.js"
+import { sdkCall } from "./sdk.js"
+
+const LOOP_OWNED_USER_MESSAGE_GUARD_MS = 10_000
+const LOOP_OWNED_USER_MESSAGE_RETENTION_MS = 10 * 60_000
+const loopOwnedUserMessageGuards = new Map()
+
+export function guardLoopOwnedUserMessage(sessionID) {
+  if (!sessionID) return
+  const current = loopOwnedUserMessageGuards.get(sessionID) || { pending: 0, until: 0, messageIDs: new Map() }
+  current.pending += 1
+  current.until = Math.max(current.until || 0, now() + LOOP_OWNED_USER_MESSAGE_GUARD_MS)
+  for (const [messageID, expiresAt] of current.messageIDs.entries()) if (expiresAt < now()) current.messageIDs.delete(messageID)
+  loopOwnedUserMessageGuards.set(sessionID, current)
+  for (const [key, entry] of loopOwnedUserMessageGuards.entries()) {
+    for (const [messageID, expiresAt] of entry.messageIDs.entries()) if (expiresAt < now()) entry.messageIDs.delete(messageID)
+    if ((entry.pending || 0) <= 0 && entry.messageIDs.size === 0 && (entry.until || 0) < now()) loopOwnedUserMessageGuards.delete(key)
+  }
+}
+
+export function loopOwnedUserMessageGuardActive(sessionID, messageID) {
+  const entry = loopOwnedUserMessageGuards.get(sessionID)
+  if (!entry || typeof entry !== "object") return false
+  for (const [id, expiresAt] of entry.messageIDs.entries()) if (expiresAt < now()) entry.messageIDs.delete(id)
+  const id = typeof messageID === "string" ? messageID : ""
+  if (id && entry.messageIDs.has(id)) return true
+  if ((entry.pending || 0) > 0 && (entry.until || 0) >= now()) {
+    // chat.message can fire before OpenCode assigns the synthetic user message
+    // an ID. Treat that pre-dispatch hook as Loop-owned without consuming the
+    // pending guard; message.updated will later bind and retain the real ID.
+    if (!id) return true
+    entry.pending -= 1
+    entry.messageIDs.set(id, now() + LOOP_OWNED_USER_MESSAGE_RETENTION_MS)
+    loopOwnedUserMessageGuards.set(sessionID, entry)
+    return true
+  }
+  if ((entry.pending || 0) <= 0 && entry.messageIDs.size === 0) loopOwnedUserMessageGuards.delete(sessionID)
+  return false
+}
+
+export async function say(client, sessionID, text) {
+  guardLoopOwnedUserMessage(sessionID)
+  try {
+    await sdkCall(
+      client.session.prompt.bind(client.session),
+      { path: { id: sessionID }, body: { noReply: true, parts: [{ type: "text", text }] } },
+      { path: { sessionID }, body: { noReply: true, parts: [{ type: "text", text }] } },
+      { sessionID, noReply: true, parts: [{ type: "text", text }] },
+    )
+  } catch {}
+}
+
+export function clearLoopOwnedUserMessageGuard(sessionID) {
+  loopOwnedUserMessageGuards.delete(sessionID)
+}