@bybrawe/opencode-loop 0.5.27 → 0.5.29

package/src/source/legacy-v1.js

@@ -0,0 +1,252 @@
+import { tool } from "@opencode-ai/plugin/tool"
+import { now } from "./core/args.js"
+import { appendLoopLog, runShellCommand } from "./core/process.js"
+import { sdkErrorMessage } from "./opencode/sdk.js"
+import { updateSessionExecutionContext } from "./opencode/session-context.js"
+import { log, toast } from "./opencode/host.js"
+import { loopOwnedUserMessageGuardActive, say, clearLoopOwnedUserMessageGuard } from "./opencode/messages.js"
+import { clearCommandLifecycle } from "./opencode/commands.js"
+import { createCommandRouter } from "./opencode/command-router.js"
+import { createGoalCommandHandlers } from "./opencode/goal-commands.js"
+import { createLoopCommandHandlers } from "./opencode/loop-commands.js"
+import { createLoopRegistration } from "./opencode/loop-registration.js"
+import { markToolCallActive, markToolCallFinished, updateSessionRelationshipFromEvent, refreshSessionRelationships, updateToolActivityFromEvent, clearSessionActivity } from "./runtime/session-activity.js"
+import { createSchedulerRuntime } from "./runtime/scheduler.js"
+import { setGoalComplete, setGoalBlocked, setGoalProgress } from "./runtime/goal-runtime.js"
+import { createGoalExecutionPolicy } from "./runtime/goal-policy.js"
+import { createJobWorkspaceRuntime, dangerousShell } from "./runtime/job-workspace.js"
+import { createLoopExecutor } from "./runtime/executor.js"
+import { createGoalSteeringRuntime } from "./runtime/goal-steering.js"
+
+const DEFAULT_ACTIVE_GUARD_MS = 45_000
+
+const workspaceRuntime = createJobWorkspaceRuntime({ toast })
+const { snapshotPaths } = workspaceRuntime
+const goalPolicy = createGoalExecutionPolicy({ runShellCommand, dangerousShell, toast, appendLoopLog, now })
+
+let schedulerRuntime
+let goalSteeringRuntime
+const schedulerBridge = {
+  rememberSession: (...args) => schedulerRuntime.rememberSession(...args),
+  scheduleDueWork: (...args) => schedulerRuntime.scheduleDueWork(...args),
+}
+const executorRuntime = createLoopExecutor({
+  workspace: workspaceRuntime,
+  goalPolicy,
+  scheduler: schedulerBridge,
+  toast,
+  log,
+  appendLoopLog,
+  errorMessage: sdkErrorMessage,
+  now,
+})
+const {
+  clearActiveRun,
+  finalizeActiveRun,
+  maybeRunDueJobs: runDueJobs,
+  sessionIsIdle,
+  updateSessionStatusFromEvent,
+  noteLoopCompactionStarted,
+  noteLoopCompactionCompleted,
+} = executorRuntime
+
+async function maybeRunDueJobs(directory, client, sessionID, runOptions) {
+  if (goalSteeringRuntime?.shouldSuppressIdle(sessionID)) return
+  return await runDueJobs(directory, client, sessionID, runOptions)
+}
+
+schedulerRuntime = createSchedulerRuntime({
+  sessionIsIdle,
+  finalizeActiveRun,
+  maybeRunDueJobs,
+  appendLoopLog,
+  toast,
+  errorMessage: sdkErrorMessage,
+})
+const { rememberSession, scheduleIdleWork, scheduleDueWork, stopWatchdog, cancelDueWork } = schedulerRuntime
+
+goalSteeringRuntime = createGoalSteeringRuntime({
+  getActiveRun: executorRuntime.getActiveRun,
+  clearActiveRun,
+  isLoopOwnedUserMessage: loopOwnedUserMessageGuardActive,
+  appendLoopLog,
+  now,
+})
+
+const { addLoop } = createLoopRegistration({
+  snapshotPaths,
+  scheduleDueWork,
+  scheduleIdleWork,
+  toast,
+  say,
+  defaultActiveGuardMs: DEFAULT_ACTIVE_GUARD_MS,
+})
+
+const {
+  addGoal,
+  statusGoal,
+  pauseGoal,
+  resumeGoal,
+  clearGoal,
+  completeGoalCommand,
+  blockGoalCommand,
+} = createGoalCommandHandlers({
+  addLoop,
+  scheduleDueWork,
+  scheduleIdleWork,
+  toast,
+  say,
+})
+
+const {
+  stopLoop,
+  updateJobState,
+  statusLoop,
+  logsLoop,
+  helpLoop,
+  runNow,
+  doctorLoop,
+  initLoop,
+  exportLoop,
+} = createLoopCommandHandlers({
+  clearActiveRun,
+  cancelDueWork,
+  stopWatchdog,
+  scheduleDueWork,
+  maybeRunDueJobs,
+  toast,
+  say,
+  now,
+})
+
+const handleCommand = createCommandRouter({
+  rememberSession,
+  handlers: {
+    addGoal,
+    statusGoal,
+    pauseGoal,
+    resumeGoal,
+    clearGoal,
+    completeGoalCommand,
+    blockGoalCommand,
+    addLoop,
+    stopLoop,
+    statusLoop,
+    logsLoop,
+    helpLoop,
+    runNow,
+    updateJobState,
+    doctorLoop,
+    initLoop,
+    exportLoop,
+  },
+})
+
+function disposeRuntime(directory, client) {
+  const sessions = schedulerRuntime.sessionIDsForHost(directory, client)
+  for (const sessionID of sessions) {
+    executorRuntime.disposeSession(sessionID)
+    schedulerRuntime.clearSessionScheduling(sessionID)
+    goalSteeringRuntime.clearSession(sessionID)
+    clearLoopOwnedUserMessageGuard(sessionID)
+    clearSessionActivity(sessionID)
+    clearCommandLifecycle(sessionID)
+  }
+}
+
+function steeringToolRejection(sessionID) {
+  if (!goalSteeringRuntime.hasPendingSteering(sessionID)) return undefined
+  return {
+    title: "Goal steering pending",
+    output: "Goal lifecycle update deferred because queued user steering is pending. The experimental Goal remains active and unchanged.",
+  }
+}
+
+function goalTools(defaultDirectory) {
+  return {
+    opencode_loop_goal_complete: tool({
+      description: "Mark the current OpenCode Loop experimental goal as completed. Use only after acceptance criteria are satisfied and you have evidence from tests, typecheck, build, or code inspection.",
+      args: {
+        summary: tool.schema.string().describe("Short human-readable summary of what was completed."),
+        evidence: tool.schema.string().describe("Concrete evidence that the goal is complete, such as commands run, passing checks, files changed, and important results."),
+      },
+      execute: async (args, context) => {
+        const steering = steeringToolRejection(context.sessionID)
+        if (steering) return steering
+        const result = await setGoalComplete(context.directory || defaultDirectory, context.sessionID, args)
+        return { title: result.ok ? "Goal completed" : result.rejected ? "Goal completion rejected" : "Goal not found", output: result.message }
+      },
+    }),
+    opencode_loop_goal_blocked: tool({
+      description: "Mark the current OpenCode Loop experimental goal as blocked when user input or manual intervention is required.",
+      args: {
+        reason: tool.schema.string().describe("Why the goal is blocked."),
+        needed: tool.schema.string().describe("What user input, credential, decision, or manual action is needed to continue."),
+      },
+      execute: async (args, context) => {
+        const steering = steeringToolRejection(context.sessionID)
+        if (steering) return steering
+        const result = await setGoalBlocked(context.directory || defaultDirectory, context.sessionID, args)
+        return { title: result.ok ? "Goal blocked" : "Goal not found", output: result.message }
+      },
+    }),
+    opencode_loop_goal_progress: tool({
+      description: "Record meaningful progress on the current OpenCode Loop experimental goal without completing it.",
+      args: {
+        summary: tool.schema.string().describe("What useful progress was made."),
+        next: tool.schema.string().describe("The next step toward completing the goal."),
+      },
+      execute: async (args, context) => {
+        const steering = steeringToolRejection(context.sessionID)
+        if (steering) return steering
+        const result = await setGoalProgress(context.directory || defaultDirectory, context.sessionID, args)
+        return { title: result.ok ? "Goal progress" : "Goal not found", output: result.message }
+      },
+    }),
+  }
+}
+
+export const OpenCodeLoopPlugin = async ({ client, directory }) => {
+  // OpenCode's local SDK can be slow or unavailable while a project instance
+  // is still waiting for its plugins to return their hooks. Defer bootstrap
+  // calls so headless/server sessions cannot deadlock during plugin loading.
+  const bootstrap = setTimeout(() => {
+    log(client, "info", "Plugin initialized", { directory }).catch(() => {})
+    refreshSessionRelationships(client, directory).catch(() => {})
+  }, 0)
+  bootstrap.unref?.()
+  return {
+    dispose: async () => { disposeRuntime(directory, client) },
+    tool: goalTools(directory),
+    "command.execute.before": async (input, output) => { await handleCommand(directory, client, input, undefined, undefined, output) },
+    "chat.message": async (input) => {
+      const steering = await goalSteeringRuntime.handleUserMessage(directory, client, {
+        sessionID: input?.sessionID,
+        messageID: input?.messageID,
+      })
+      if (steering?.handled && steering.sessionID) rememberSession(directory, client, steering.sessionID)
+    },
+    "tool.execute.before": async (input) => { markToolCallActive(input) },
+    "tool.execute.after": async (input) => { markToolCallFinished(input) },
+    "experimental.session.compacting": async (input) => { await noteLoopCompactionStarted(directory, input?.sessionID) },
+    event: async ({ event }) => {
+      if (event.type === "session.compacted") await noteLoopCompactionCompleted(directory, client, event?.properties?.sessionID)
+      updateSessionRelationshipFromEvent(event)
+      if (event.type === "message.updated") updateSessionExecutionContext(event?.properties?.info)
+      updateToolActivityFromEvent(event)
+      if (event.type === "command.executed") {
+        const props = event.properties || {}
+        await handleCommand(directory, client, props, props.name, props.arguments, undefined, "event")
+      }
+      const steering = await goalSteeringRuntime.handleEvent(directory, client, event)
+      if (steering?.handled && steering.sessionID) rememberSession(directory, client, steering.sessionID)
+      const statusUpdate = updateSessionStatusFromEvent(event)
+      if (statusUpdate?.sessionID) rememberSession(directory, client, statusUpdate.sessionID)
+      if (statusUpdate?.idle && !goalSteeringRuntime.shouldSuppressIdle(statusUpdate.sessionID)) {
+        scheduleIdleWork(directory, client, statusUpdate.sessionID)
+      }
+    },
+  }
+}
+
+export default OpenCodeLoopPlugin

package/src/source/opencode/adapter.js

@@ -0,0 +1,21 @@
+import {
+  activeRunCompletionFromMessages,
+  compactSession,
+  executeTuiCommand,
+  log,
+  readRecentSessionMessages,
+  resolveCompactionModel,
+  toast,
+} from "./host.js"
+
+export function createOpenCodeHostAdapter(client, directory) {
+  return Object.freeze({
+    executeTuiCommand: (command) => executeTuiCommand(client, command),
+    readRecentMessages: (sessionID, limit = 12) => readRecentSessionMessages(client, sessionID, directory, limit),
+    activeRunCompletion: (sessionID, active) => activeRunCompletionFromMessages(directory, client, sessionID, active),
+    resolveCompactionModel: (sessionID, preferredModel) => resolveCompactionModel(directory, client, sessionID, preferredModel),
+    compactSession: (sessionID, preferredModel) => compactSession(directory, client, sessionID, preferredModel),
+    log: (level, message, extra) => log(client, level, message, extra),
+    toast: (message, variant) => toast(client, message, variant),
+  })
+}

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,
+  }
+}