@bybrawe/opencode-loop 0.6.8 → 0.6.9

package/src/source/core/args.js

@@ -135,6 +135,7 @@ export function parseLoopArgs(raw, defaults = {}) {
     until: defaults.until,
     stopFile: defaults.stopFile,
     progressFile: defaults.progressFile,
+    untilChecklistComplete: defaults.untilChecklistComplete ?? false,
     promptFile: defaults.promptFile,
     includeFiles: Array.isArray(defaults.includeFiles) ? [...defaults.includeFiles] : [],
     watchPaths: Array.isArray(defaults.watchPaths) ? [...defaults.watchPaths] : [],
@@ -197,6 +198,7 @@ export function parseLoopArgs(raw, defaults = {}) {
   ;[found, rest] = takeFlag(rest, "--git-checkpoint"); if (found) job.gitCheckpoint = true
   ;[found, rest] = takeFlag(rest, "--checkpoint-only"); if (found) job.checkpointOnly = true
   ;[found, rest] = takeFlag(rest, "--pause-on-verify-fail"); if (found) job.pauseOnVerifyFail = true
+  ;[found, rest] = takeFlag(rest, "--until-checklist-complete"); if (found) job.untilChecklistComplete = true
   ;[found, rest] = takeFlag(rest, "--dry-run"); if (found) job.dryRun = true
   ;[found, rest] = takeFlag(rest, "--multi"); if (found) job.multi = true
   ;[found, rest] = takeFlag(rest, "--replace"); if (found) job.multi = false
@@ -276,6 +278,7 @@ export function parseLoopArgs(raw, defaults = {}) {
   }
   job.lastRunAt = job.immediate ? 0 : now()
 
+  if (job.untilChecklistComplete && !job.progressFile) return { ok: false, error: "--until-checklist-complete requires --progress-file <project.md>" }
   if (!job.action && !job.promptFile && !job.goalFile) return { ok: false, error: "Missing action. Example: /loop 0s continue from progress.md, /loop-goal ship the feature, or /loop 0s --prompt-file loop-prompt.md" }
   return { ok: true, job }
 }

package/src/source/core/jobs.js

@@ -58,6 +58,7 @@ export function decoratePrompt(job) {
   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.untilChecklistComplete) additions.push("When all actual Markdown tasks in the configured progress file are checked, stop creating new work and report results. Loop will make the stopping decision itself from the project file at a safe host boundary; do not attempt to invoke /loop-clear as assistant text.")
   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.")
   if (job.safe) additions.push("Safety rules: do not run destructive commands such as git reset, git clean, rm -rf, del /s, rmdir /s, force push, production deploys, production migrations, terraform destroy, or deleting user data. If such an action seems needed, write a BLOCKED note instead.")

package/src/source/opencode2/native-plugin.js

@@ -13,6 +13,7 @@ const HELP = `OpenCode Loop: native OpenCode 2 runtime
 /loop 5m <task> --verify "npm test" --pause-on-verify-fail
 /loop --watch progress.md <task>
 /loop 0s <task> --prompt-file instructions.md --include-file progress.md
+/loop 0s <task> --progress-file TASK.md --until-checklist-complete --verify "npm test"
 /loop 0s <task> --compact-every 3
 /loop 5m --shell npm test
 /loop 15m --compact /compact
@@ -20,6 +21,8 @@ Presets: /loop-dev, /loop-testfix, /loop-progress, /loop-safe-dev, /loop-ask, /l
 /loop-init [progress.md] creates a missing project-local progress file without overwriting existing data.
 Controls: /loop-now, /loop-pause, /loop-resume, /loop-stop, /loop-remove, /loop-clear, /loop-status, /loop-export.
 Preflight, postrun, notifications, stop files, completion markers, runtime/failure/run limits, branches and checkpoints are supported.
+--progress-file alone is context, not a stop condition. --until-checklist-complete is an explicit host-verified stop condition; missing/unsafe/no-task files pause for review, and --verify must have passed before stopping.
+Invoke /loop-stop or /loop-clear as native USER commands. Having an assistant print the slash command does not execute it.
 Scheduled shell commands run as bounded local child processes managed by Loop; OpenCode 2's ctx.shell surface is a hook API, not a shell-execution method.
 Manual /loop-compact, --compact and --compact-every use public session.compact when the V2 host exposes it. Loop matches the admitted manual compaction inputID and waits for host completion; older hosts without this capability reject the job before creation. Automatic compaction stays host-owned.
 An unfinished dedicated Goal reserves its session; Loop will not override it.

package/src/source/opencode2/native-policy.js

@@ -2,6 +2,7 @@ import { stat } from "node:fs/promises"
 import path from "node:path"
 import { runShellCommand, appendLoopLog } from "../core/process.js"
 import { createJobWorkspaceRuntime, dangerousShell } from "../runtime/job-workspace.js"
+import { inspectTaskChecklist } from "../runtime/checklist-completion.js"
 
 export function createNativeJobPolicy(options = {}) {
   const now = options.now || Date.now
@@ -44,6 +45,20 @@ export function createNativeJobPolicy(options = {}) {
       job.enabled = false
       return pause(job, "until-reached")
     }
+    if (job.untilChecklistComplete) {
+      const checklist = await inspectTaskChecklist(scope.directory, job.progressFile)
+      job.checklistStatus = { status: checklist.status, total: checklist.total, pending: checklist.pending }
+      if (checklist.status === "unavailable") {
+        job.lastChecklistError = checklist.reason
+        return pause(job, "checklist-unavailable")
+      }
+      delete job.lastChecklistError
+      if (checklist.status === "complete" && (!job.verifyCommand || (job.lastVerifyAt > 0 && job.lastVerifyCode === 0 && job.lastVerifyChecklistDigest === checklist.digest))) {
+        job.enabled = false
+        job.checklistCompletedAt = now()
+        return pause(job, "checklist-complete")
+      }
+    }
     return true
   }
 
@@ -71,11 +86,17 @@ export function createNativeJobPolicy(options = {}) {
       job.lastVerifyAt = now()
       job.lastVerifyOutput = `${result.stdout || ""}\n${result.stderr || ""}`.trim().slice(-8000)
       if (result.code !== 0) {
+        delete job.lastVerifyChecklistDigest
         job.failureCount = (job.failureCount || 0) + 1
         if (result.blocked || job.pauseOnVerifyFail || (job.maxFailures > 0 && job.failureCount >= job.maxFailures)) pause(job, "verification-failed")
         return
       }
       job.failureCount = 0
+      if (job.untilChecklistComplete) {
+        const verified = await inspectTaskChecklist(scope.directory, job.progressFile)
+        if (verified.status !== "unavailable") job.lastVerifyChecklistDigest = verified.digest
+        else delete job.lastVerifyChecklistDigest
+      }
     }
     if (!isCurrent()) return
     if (job.postrunCommand) {

package/src/source/opencode2/native-runtime.js

@@ -81,6 +81,7 @@ export function createNativeLoopRuntime(options = {}) {
     for (const job of state.jobs || []) {
       if (!eligible(job) || job.v2Run || blocked(job).length) continue
       if (job.watchPaths?.length || job.stopFile || job.until) delay = Math.min(delay, 1000)
+      if (job.untilChecklistComplete) delay = Math.min(delay, 5000)
       const due = dueAt(job)
       if (due > now()) delay = Math.min(delay, due - now())
       // A zero-delay deferred preset still needs a first idle-safe wake after

package/src/source/opencode2/status.js

@@ -28,6 +28,10 @@ export function formatOpenCode2LoopStatus(state, current = Date.now()) {
           job.noOverlap ? "no-overlap" : undefined,
           job.checkpointOnly ? "checkpoint-only" : undefined,
           job.gitCheckpoint ? "git-checkpoint" : undefined,
+          job.untilChecklistComplete ? "checklist-stop:" + (job.progressFile || "missing-file") : undefined,
+          job.pauseReason ? "reason:" + job.pauseReason : undefined,
+          job.lastChecklistError ? "checklist-error:" + job.lastChecklistError : undefined,
+          !job.maxRuns && !job.maxRuntimeMs && !job.until && !job.stopFile && !job.untilChecklistComplete ? "unlimited" : 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}`
       })
@@ -35,6 +39,6 @@ export function formatOpenCode2LoopStatus(state, current = Date.now()) {
 
   return Object.freeze({
     jobs,
-    text: `OpenCode loop status:\n${lines.join("\n")}`,
+    text: `OpenCode loop status:\n${lines.join("\n")}${jobs.length ? "\nHost controls: run /loop-stop <name-or-id> or /loop-clear to stop jobs; asking the model to print those commands does not execute them." : ""}`,
   })
 }

package/src/source/runtime/checklist-completion.js

@@ -0,0 +1,113 @@
+import { promises as fs, constants } from "node:fs"
+import path from "node:path"
+import { createHash } from "node:crypto"
+
+const MAX_CHECKLIST_BYTES = 256_000
+const EXCLUDED_PROJECT_DIRS = new Set([".opencode", ".git", "node_modules"])
+
+function unavailable(reason) {
+  return { status: "unavailable", reason, total: 0, pending: 0 }
+}
+
+export function summarizeTaskChecklist(markdown) {
+  let total = 0
+  let pending = 0
+  let fence = null
+  let comment = false
+
+  for (const original of String(markdown || "").replace(/^\uFEFF/, "").split(/\r?\n/)) {
+    // Only project tasks count, never examples in HTML comments or fenced code.
+    let line = ""
+    let offset = 0
+    while (offset < original.length) {
+      if (comment) {
+        const end = original.indexOf("-->", offset)
+        if (end < 0) break
+        comment = false
+        offset = end + 3
+      } else {
+        const start = original.indexOf("<!--", offset)
+        if (start < 0) {
+          line += original.slice(offset)
+          break
+        }
+        line += original.slice(offset, start)
+        comment = true
+        offset = start + 4
+      }
+    }
+
+    const trimmed = line.trimStart()
+    const indentation = line.length - trimmed.length
+    const marker = trimmed.charAt(0)
+    let markerSize = 0
+    if (marker === "~" || marker.charCodeAt(0) === 96) {
+      while (trimmed.charAt(markerSize) === marker) markerSize++
+    }
+    if (fence) {
+      if (indentation <= 3 && markerSize >= fence.length && marker === fence.marker && !trimmed.slice(markerSize).trim()) fence = null
+      continue
+    }
+    if (indentation <= 3 && markerSize >= 3) {
+      fence = { marker, length: markerSize }
+      continue
+    }
+    // A quoted example must not be mistaken for an actionable checkbox.
+    if (/^\s*>/.test(line)) continue
+    const match = line.match(/^\s{0,24}[-+*]\s+\[([ xX])\](?:\s|$)/)
+    if (!match) continue
+    total++
+    if (match[1] === " ") pending++
+  }
+
+  return { status: total === 0 ? "unavailable" : pending === 0 ? "complete" : "pending",
+    reason: total === 0 ? "no-task-checkboxes" : "",
+    total, pending }
+}
+
+export async function inspectTaskChecklist(directory, progressFile) {
+  const name = String(progressFile || "").trim()
+  if (!name || name.includes("\u0000")) return unavailable("missing-progress-file")
+  if (path.isAbsolute(name) || path.win32.isAbsolute(name)) return unavailable("absolute-path")
+  const root = path.resolve(directory)
+  const target = path.resolve(root, name)
+  const relative = path.relative(root, target)
+  if (!relative || relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) {
+    return unavailable("outside-project")
+  }
+  const parts = relative.split(path.sep)
+  if (parts.some((part) => EXCLUDED_PROJECT_DIRS.has(part.toLowerCase()))) return unavailable("control-plane-path")
+
+  try {
+    const rootInfo = await fs.lstat(root)
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()) return unavailable("unsafe-project-root")
+    let current = root
+    for (let index = 0; index < parts.length; index++) {
+      current = path.join(current, parts[index])
+      const info = await fs.lstat(current)
+      if (info.isSymbolicLink()) return unavailable("symlink-path")
+      if (index < parts.length - 1 && !info.isDirectory()) return unavailable("invalid-parent")
+      if (index === parts.length - 1 && (!info.isFile() || info.size > MAX_CHECKLIST_BYTES)) {
+        return unavailable(!info.isFile() ? "not-regular-file" : "file-too-large")
+      }
+    }
+    // Do not follow a last-component symlink introduced between lstat and open.
+    const handle = await fs.open(target, constants.O_RDONLY | (constants.O_NOFOLLOW || 0))
+    try {
+      const info = await handle.stat()
+      if (!info.isFile() || info.size > MAX_CHECKLIST_BYTES) {
+        return unavailable(!info.isFile() ? "not-regular-file" : "file-too-large")
+      }
+      const content = await handle.readFile({ encoding: "utf8" })
+      const after = await fs.lstat(target)
+      if (!after.isFile() || after.isSymbolicLink() || after.dev !== info.dev || after.ino !== info.ino) {
+        return unavailable("file-changed-during-read")
+      }
+      return { ...summarizeTaskChecklist(content), digest: createHash("sha256").update(content).digest("hex") }
+    } finally {
+      await handle.close()
+    }
+  } catch (error) {
+    return unavailable(error?.code === "ENOENT" ? "file-missing" : error?.code === "ELOOP" ? "symlink-path" : "file-unreadable")
+  }
+}

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

@@ -4,6 +4,7 @@ import { pathExists as defaultPathExists, writeState as defaultWriteState } from
 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 { inspectTaskChecklist } from "./checklist-completion.js"
 import { dueJobs as sharedDueJobs } from "./schedule-policy.js"
 
 function requireFunction(value, label) {
@@ -82,6 +83,30 @@ export function createRunAdmissionRuntime(options = {}) {
       )
     }
 
+    if (job.untilChecklistComplete) {
+      const checklist = await inspectTaskChecklist(directory, job.progressFile)
+      job.checklistStatus = { status: checklist.status, total: checklist.total, pending: checklist.pending }
+      if (checklist.status === "unavailable") {
+        job.paused = true
+        job.pauseReason = "checklist-unavailable"
+        job.lastChecklistError = checklist.reason
+        await writeState(directory, sessionID, state)
+        await notifyJob(directory, job, "checklist_unavailable")
+        await toast(client, "Loop paused: checklist " + job.progressFile + " could not be validated (" + checklist.reason + ").", "warning")
+        await reschedule(directory, client, sessionID)
+        return { admitted: false, reason: "checklist_unavailable" }
+      }
+      delete job.lastChecklistError
+      if (checklist.status === "complete" && (!job.verifyCommand || (job.lastVerifyAt > 0 && job.lastVerifyCode === 0 && job.lastVerifyChecklistDigest === checklist.digest))) {
+        return await stopAndRemove(
+          directory, client, sessionID, state, job,
+          "checklist_complete",
+          "Loop stopped: " + job.progressFile + " checklist completed.",
+          "checklist-complete",
+        )
+      }
+    }
+
     if (job.preflightCommand) {
       if (job.safe && dangerousShell(job.preflightCommand)) {
         if (runNowRequested) delete job.runNowRequestedAt

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

@@ -6,6 +6,7 @@ import { toast as defaultToast } from "../opencode/host.js"
 import { writeGoalReport as defaultWriteGoalReport } from "./goal-runtime.js"
 import { dangerousShell as defaultDangerousShell } from "./job-workspace.js"
 import { applyTerminalContinuationGuard as defaultApplyTerminalContinuationGuard } from "./terminal-guard.js"
+import { inspectTaskChecklist } from "./checklist-completion.js"
 
 function requireFunction(value, label) {
   if (typeof value !== "function") throw new TypeError(`createRunFinalizationRuntime requires ${label}`)
@@ -49,8 +50,14 @@ export function createRunFinalizationRuntime(options = {}) {
       if (verify.code === 0) {
         job.failureCount = 0
         job.lastVerifyFailure = ""
+        if (job.untilChecklistComplete) {
+          const inspected = await inspectTaskChecklist(directory, job.progressFile)
+          if (inspected.status !== "unavailable") job.lastVerifyChecklistDigest = inspected.digest
+          else delete job.lastVerifyChecklistDigest
+        }
         await toast(client, "Loop verify passed: " + job.verifyCommand, "success")
       } else {
+        delete job.lastVerifyChecklistDigest
         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")