opencode-goal-plugin 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.9 — 2026-05-18
+
+> This release makes the goal plugin much more reliable for real unattended use. Goals now persist across restarts, recover in a safe paused state, expose better status/history visibility, and use smarter no-progress detection to avoid premature stalls. It also hardens persistence with atomic writes, stricter file permissions, and regression tests around corrupt or missing state.
+
+- Persist active goals and recent results to `~/.opencode-goal-plugin/state.json` by default, with recovered goals loaded in a paused state.
+- Add `/goal history` plus richer `/goal status` output with recent checkpoint and suggested-next-action hints.
+- Replace one-shot low-output pausing with a configurable consecutive-stall grace window via `noProgressTurnsBeforePause` / `--no-progress-turns`.
+- Expand tests to cover history output, persistence recovery, repeated-stall pausing, and changing short assistant updates.
+
+## 0.1.8 — 2026-05-18
+
+- Harden `--max-minutes` fallback arithmetic when mixed with millisecond duration overrides.
+- Clarify plugin-default config merging and goal-text trust guidance.
+
 ## 0.1.7 — 2026-05-18
 
 - Accept bare final-line `goal:complete` and `goal:blocked` markers in addition to canonical bracketed markers, matching observed model output during smoke testing.

package/README.md

@@ -41,12 +41,20 @@ Override limits for a single goal:
 /goal fix the failing tests --max-turns 20 --max-minutes 30 --max-tokens 400000
 ```
 
+Flags accept either `--flag value` or `--flag=value`. If a flag is unknown, missing a value, or given a non-positive integer, the plugin rejects the command with a helpful error instead of silently folding the bad flag into the goal text.
+
 Check status:
 
 ```
 /goal status
 ```
 
+View lifecycle history and the latest checkpoint:
+
+```
+/goal history
+```
+
 Resume a paused or stopped goal:
 
 ```
@@ -95,7 +103,7 @@ Markers must appear on their own final line. The bracketed form is canonical, bu
 | Max duration | 15 minutes |
 | Tracked tokens | 200,000 |
 | Min delay between continues | 1.5 seconds |
-| No-progress pause | < 50 output tokens on a turn |
+| No-progress pause | < 50 output tokens on a stalled turn (after a 2-turn grace window) |
 | Budget wrap-up threshold | 80% of tracked token budget |
 | Auto-continue failure pause | 3 consecutive prompt failures |
 
@@ -103,11 +111,17 @@ Markers must appear on their own final line. The bracketed form is canonical, bu
 
 **Token budget.** The plugin tracks `input + output + reasoning` tokens across all session messages. In high-context sessions (large codebases, long conversation history), input overhead per turn can be substantial and the budget may be exhausted before the turn limit is reached. Treat it as a safety brake, not precise billing accounting.
 
+**No-progress heuristic.** A low-output turn does not pause immediately anymore. The plugin pauses only after `noProgressTurnsBeforePause` consecutive *stalled* low-output turns — repeated turns with very little output and no meaningful change in the latest assistant checkpoint.
+
 **Wrap-up vs. hard stop.** When a limit is reached, the plugin sends one final prompt asking the assistant to summarize what is done, what remains, and the next concrete step — rather than stopping silently. Use `/goal resume` to continue after any stop, including limit stops and no-progress pauses.
 
-Goal state is process-memory only. It is not persisted across OpenCode restarts, plugin reloads, or config reloads.
+Goal state is persisted by default to `~/.opencode-goal-plugin/state.json`, but only as a local workflow checkpoint. It is not synchronized across machines or OpenCode instances.
+
+The state directory is created with owner-only permissions, and the JSON state file is written as `0600` because it may contain goal text, assistant checkpoints, and workflow history.
 
-`/goal resume` continues the same in-memory objective with a fresh local budget window. This lets you continue after pause, blocker, no-progress pause, rate-limit failures, or a limit stop without retyping the objective.
+Recovered active goals are loaded in a **paused** state with a recovery note, so unattended auto-continue does not resume blindly after a restart. Set `"persistState": false` to keep purely in-memory behavior.
+
+`/goal resume` continues the same objective with a fresh local budget window. This lets you continue after pause, blocker, no-progress pause, rate-limit failures, or a limit stop without retyping the objective.
 
 ### Per-goal flags
 
@@ -121,10 +135,19 @@ Override any limit for a single goal:
 | `--max-tokens <n>` | Tracked token limit |
 | `--cooldown-ms <n>` | Minimum delay between continues |
 | `--no-progress-threshold <n>` | Output token floor before pausing |
+| `--no-progress-turns <n>` | Consecutive stalled low-output turns before pausing |
+
+Examples:
+
+```sh
+/goal fix tests --max-turns 20 --max-tokens 400000
+/goal fix tests --max-turns=20 --max-tokens=400000
+/goal fix tests --no-progress-threshold 50 --no-progress-turns 2
+```
 
 ### Plugin-level defaults
 
-Pass options when registering the plugin to change the defaults for all goals:
+Pass options when registering the plugin to change the defaults for all goals. To combine with the `goal` command, merge this plugin entry into the config shown above.
 
 ```json
 {
@@ -136,15 +159,30 @@ Pass options when registering the plugin to change the defaults for all goals:
         "maxDurationMs": 900000,
         "maxTokens": 200000,
         "minDelayMs": 1500,
+        "maxRecentMessages": 50,
         "noProgressTokenThreshold": 50,
+        "noProgressTurnsBeforePause": 2,
         "budgetWrapupRatio": 0.8,
-        "maxPromptFailures": 3
+        "maxPromptFailures": 3,
+        "persistState": true,
+        "stateFilePath": "/home/you/.opencode-goal-plugin/state.json",
+        "resultRetentionMs": 604800000,
+        "maxStoredResults": 200
       }
     ]
   ]
 }
 ```
 
+Additional plugin-level options:
+
+- `maxRecentMessages` — how many recent session messages to scan when looking for the latest assistant turn before auto-continuing. Higher values make long, tool-heavy sessions less likely to lose the most recent assistant response.
+- `noProgressTurnsBeforePause` — grace window for low-output stalls. The plugin pauses only after this many consecutive stalled low-output turns rather than on the first one.
+- `persistState` — whether to persist active goals and recent goal results to disk.
+- `stateFilePath` — where the persisted state JSON is written. Useful if you want per-project or ephemeral storage.
+- `resultRetentionMs` — how long a completed goal summary remains available through `/goal status` after the goal leaves active memory.
+- `maxStoredResults` — maximum number of completed-goal summaries retained in process memory before the oldest ones are evicted.
+
 ## Prompt safety
 
 The goal text is wrapped in `<goal_objective>` tags and labeled as user-provided task data. The assistant is told to treat it as a task description, not as elevated instructions that can override system, developer, tool, or repository policies.
@@ -180,8 +218,9 @@ Keep test files outside OpenCode's auto-loaded plugin directory — OpenCode wil
 ## Development
 
 ```sh
-npm test          # run the test suite
-npm run check     # syntax check + tests
+npm test            # run the test suite
+npm run test:coverage  # run tests with coverage
+npm run check       # syntax check + tests
 npm run pack:check  # verify package contents before publishing
 ```
 

package/SECURITY.md

@@ -21,4 +21,4 @@ Relevant security-sensitive areas include:
 - incorrect command or hook handling across OpenCode versions
 - leakage of goal text through logs or status output
 
-The goal text is wrapped in `<goal_objective>` tags and the closing tag is escaped before insertion. Other structural tags used in continuation prompts (`<goal_continuation>`, `<progress_budget>`, etc.) are not escaped. Crafted goal text containing those literal strings would close the tag early in the plaintext prompt; the model treats it as text rather than structure, so the practical risk for a local single-user tool is negligible.
+The goal text is wrapped in `<goal_objective>` tags and the closing tag is escaped before insertion. Other structural tags used in continuation prompts (`<goal_continuation>`, `<progress_budget>`, etc.) are not escaped. Crafted goal text containing those literal strings would close the tag early in the plaintext prompt; the model treats it as text rather than structure, so the practical risk for a local single-user tool is negligible. Do not paste untrusted third-party text into a goal; treat goal text as if you typed it directly into the assistant.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Session-scoped /goal workflow for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",
@@ -19,6 +19,7 @@
   ],
   "scripts": {
     "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage",
     "check": "node -c src/goal-plugin.js && npm test",
     "pack:check": "npm pack --dry-run"
   },

package/src/goal-plugin.js

@@ -1,16 +1,29 @@
 import { randomUUID } from "node:crypto"
+import { promises as fs } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+
+const STATE_FILE_VERSION = 1
+const DEFAULT_STATE_FILE_PATH = join(homedir(), ".opencode-goal-plugin", "state.json")
+const MAX_HISTORY_ENTRIES = 20
+const MAX_CHECKPOINTS = 5
+const CHECKPOINT_CHAR_LIMIT = 280
 
 const DEFAULT_OPTIONS = {
   maxTurns: 10,
   maxDurationMs: 15 * 60 * 1000,
   maxTokens: 200000,
   minDelayMs: 1500,
+  maxRecentMessages: 50,
   noProgressTokenThreshold: 50,
+  noProgressTurnsBeforePause: 2,
   budgetWrapupRatio: 0.8,
   warnTurnsRemaining: 3,
   warnDurationMsRemaining: 60 * 1000,
   warnTokensRemaining: 25000,
   maxPromptFailures: 3,
+  resultRetentionMs: 7 * 24 * 60 * 60 * 1000,
+  maxStoredResults: 200,
 }
 
 const goalStates = new Map()
@@ -20,6 +33,39 @@ const seenOutputTokens = new Map()
 const activeContinues = new Set()
 const CLEAR_COMMANDS = new Set(["clear", "stop", "off", "reset", "none", "cancel"])
 const PAUSE_COMMANDS = new Set(["pause"])
+const GOAL_FLAG_SPECS = {
+  "--max-turns": {
+    optionKey: "maxTurns",
+    parse: (value, options) => toPositiveInteger(value, options.maxTurns),
+  },
+  "--max-duration-ms": {
+    optionKey: "maxDurationMs",
+    parse: (value, options) => toPositiveInteger(value, options.maxDurationMs),
+  },
+  "--max-minutes": {
+    optionKey: "maxDurationMs",
+    parse: (value, options) =>
+      toPositiveInteger(value, Math.ceil(options.maxDurationMs / 60000)) * 60000,
+  },
+  "--max-tokens": {
+    optionKey: "maxTokens",
+    parse: (value, options) => toPositiveInteger(value, options.maxTokens),
+  },
+  "--cooldown-ms": {
+    optionKey: "minDelayMs",
+    parse: (value, options) => toPositiveInteger(value, options.minDelayMs),
+  },
+  "--no-progress-threshold": {
+    optionKey: "noProgressTokenThreshold",
+    parse: (value, options) =>
+      toPositiveInteger(value, options.noProgressTokenThreshold),
+  },
+  "--no-progress-turns": {
+    optionKey: "noProgressTurnsBeforePause",
+    parse: (value, options) =>
+      toPositiveInteger(value, options.noProgressTurnsBeforePause),
+  },
+}
 
 function getText(parts) {
   return (parts || [])
@@ -44,12 +90,55 @@ function isIdleEvent(event) {
   )
 }
 
+function summarizeText(text, limit = CHECKPOINT_CHAR_LIMIT) {
+  const normalized = String(text || "").replace(/\s+/g, " ").trim()
+  if (!normalized) return ""
+  return normalized.length > limit ? `${normalized.slice(0, limit - 1)}…` : normalized
+}
+
+function formatTimestamp(timestamp) {
+  if (!timestamp) return "unknown"
+  return new Date(timestamp).toISOString()
+}
+
+function formatAge(timestamp) {
+  if (!timestamp) return "unknown"
+  return `${Math.round((Date.now() - timestamp) / 1000)}s ago`
+}
+
+function makeHistoryEntry(type, detail, timestamp = Date.now()) {
+  return {
+    type,
+    detail: summarizeText(detail, 400),
+    timestamp,
+  }
+}
+
+function pushHistory(goal, type, detail, timestamp = Date.now()) {
+  goal.history = [...(goal.history || []), makeHistoryEntry(type, detail, timestamp)].slice(
+    -MAX_HISTORY_ENTRIES,
+  )
+}
+
+function recordCheckpoint(goal, text, timestamp = Date.now()) {
+  const summary = summarizeText(text)
+  if (!summary) return
+  if (goal.lastCheckpoint?.summary === summary) return
+
+  const checkpoint = { summary, timestamp }
+  goal.lastCheckpoint = checkpoint
+  goal.checkpoints = [...(goal.checkpoints || []), checkpoint].slice(-MAX_CHECKPOINTS)
+}
+
 function formatStatus(goal) {
   const elapsed = Math.round((Date.now() - goal.startedAt) / 1000)
   const lastProgress =
     goal.lastProgressAt > 0
       ? `${Math.round((Date.now() - goal.lastProgressAt) / 1000)}s ago`
       : "none yet"
+  const lastCheckpoint = goal.lastCheckpoint
+    ? `${goal.lastCheckpoint.summary} (${formatAge(goal.lastCheckpoint.timestamp)})`
+    : "none yet"
   const lines = [
     `Active goal: ${goal.condition}`,
     `Auto-continues sent: ${goal.turnCount}/${goal.options.maxTurns}`,
@@ -57,21 +146,31 @@ function formatStatus(goal) {
     `Elapsed: ${elapsed}s/${Math.round(goal.options.maxDurationMs / 1000)}s`,
     `Last progress: ${lastProgress}`,
     `No-progress turns: ${goal.noProgressTurns}`,
+    `Recent checkpoint: ${lastCheckpoint}`,
     `Last status: ${goal.lastStatus || "No assistant turn recorded yet."}`,
   ]
   if (goal.stopped) lines.push(`Stopped: ${goal.stopReason || "unknown"}`)
   if (goal.blockedReason) lines.push(`Blocked reason: ${goal.blockedReason}`)
+  if (goal.stopped) {
+    lines.push(
+      `Suggested action: ${goal.stopReason === "blocked" ? "address the blocker, then run /goal resume" : "run /goal resume to continue, or /goal clear to discard"}`,
+    )
+  }
   return lines.join("\n")
 }
 
 function formatGoalResult(result) {
   const elapsed = Math.round((result.finishedAt - result.startedAt) / 1000)
+  const lastCheckpoint = result.lastCheckpoint
+    ? `${result.lastCheckpoint.summary} (${formatTimestamp(result.lastCheckpoint.timestamp)})`
+    : "none recorded"
   const lines = [
     `Last goal: ${result.condition}`,
     `State: ${result.state}`,
     `Auto-continues sent: ${result.turnCount}`,
     `Tokens: ${result.totalTokens.toLocaleString()}`,
     `Elapsed: ${elapsed}s`,
+    `Last checkpoint: ${lastCheckpoint}`,
     `Last status: ${result.lastStatus || "No status recorded."}`,
   ]
   if (result.reason) lines.push(`Reason: ${result.reason}`)
@@ -79,6 +178,13 @@ function formatGoalResult(result) {
   return lines.join("\n")
 }
 
+function formatHistory(history = []) {
+  if (!history.length) return "No goal history recorded yet."
+  return history
+    .map((entry) => `- [${formatTimestamp(entry.timestamp)}] ${entry.type}: ${entry.detail}`)
+    .join("\n")
+}
+
 function goalIsComplete(text) {
   return /(^|\n)\s*(?:\[goal:complete\]|goal:complete)\s*$/i.test(text.trimEnd())
 }
@@ -108,7 +214,34 @@ function cleanupGoal(sessionID) {
   activeContinues.delete(sessionID)
 }
 
+function clearRuntimeState() {
+  goalStates.clear()
+  lastGoalResults.clear()
+  seenTokens.clear()
+  seenOutputTokens.clear()
+  activeContinues.clear()
+}
+
+function pruneGoalResults(options) {
+  const retentionMs = options?.resultRetentionMs ?? DEFAULT_OPTIONS.resultRetentionMs
+  const maxStoredResults = options?.maxStoredResults ?? DEFAULT_OPTIONS.maxStoredResults
+  const now = Date.now()
+
+  for (const [sessionID, result] of lastGoalResults.entries()) {
+    if (!result?.finishedAt || now - result.finishedAt > retentionMs) {
+      lastGoalResults.delete(sessionID)
+    }
+  }
+
+  while (lastGoalResults.size > maxStoredResults) {
+    const oldestSessionID = lastGoalResults.keys().next().value
+    if (oldestSessionID === undefined) break
+    lastGoalResults.delete(oldestSessionID)
+  }
+}
+
 function rememberGoalResult(sessionID, goal, state, reason = "") {
+  lastGoalResults.delete(sessionID)
   lastGoalResults.set(sessionID, {
     condition: goal.condition,
     state,
@@ -119,7 +252,11 @@ function rememberGoalResult(sessionID, goal, state, reason = "") {
     startedAt: goal.startedAt,
     finishedAt: Date.now(),
     lastStatus: goal.lastStatus,
+    lastCheckpoint: goal.lastCheckpoint || null,
+    checkpoints: [...(goal.checkpoints || [])],
+    history: [...(goal.history || [])],
   })
+  pruneGoalResults(goal.options)
 }
 
 function resetGoalBudget(goal) {
@@ -137,6 +274,8 @@ function resetGoalBudget(goal) {
   goal.budgetWrapupSent = false
   goal.messageIDs = new Set()
   goal.promptFailures = 0
+  goal.lastAssistantMessageID = ""
+  goal.history = [...(goal.history || [])].slice(-MAX_HISTORY_ENTRIES)
 }
 
 function currentGoal(sessionID, goalID) {
@@ -151,16 +290,33 @@ function toPositiveInteger(value, fallback) {
   return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
 }
 
+function parsePositiveIntegerStrict(value) {
+  const parsed = Number(value)
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null
+}
+
+function stripWrappingQuotes(value) {
+  return value.replace(/^["']|["']$/g, "")
+}
+
 function normalizeOptions(options = {}) {
   return {
     maxTurns: toPositiveInteger(options.maxTurns, DEFAULT_OPTIONS.maxTurns),
     maxDurationMs: toPositiveInteger(options.maxDurationMs, DEFAULT_OPTIONS.maxDurationMs),
     maxTokens: toPositiveInteger(options.maxTokens, DEFAULT_OPTIONS.maxTokens),
     minDelayMs: toPositiveInteger(options.minDelayMs, DEFAULT_OPTIONS.minDelayMs),
+    maxRecentMessages: toPositiveInteger(
+      options.maxRecentMessages,
+      DEFAULT_OPTIONS.maxRecentMessages,
+    ),
     noProgressTokenThreshold: toPositiveInteger(
       options.noProgressTokenThreshold,
       DEFAULT_OPTIONS.noProgressTokenThreshold,
     ),
+    noProgressTurnsBeforePause: toPositiveInteger(
+      options.noProgressTurnsBeforePause,
+      DEFAULT_OPTIONS.noProgressTurnsBeforePause,
+    ),
     budgetWrapupRatio:
       Number(options.budgetWrapupRatio) > 0 && Number(options.budgetWrapupRatio) < 1
         ? Number(options.budgetWrapupRatio)
@@ -181,6 +337,121 @@ function normalizeOptions(options = {}) {
       options.maxPromptFailures,
       DEFAULT_OPTIONS.maxPromptFailures,
     ),
+    resultRetentionMs: toPositiveInteger(
+      options.resultRetentionMs,
+      DEFAULT_OPTIONS.resultRetentionMs,
+    ),
+    maxStoredResults: toPositiveInteger(
+      options.maxStoredResults,
+      DEFAULT_OPTIONS.maxStoredResults,
+    ),
+  }
+}
+
+function normalizePersistenceOptions(options = {}) {
+  return {
+    persistState: options.persistState !== false,
+    stateFilePath:
+      typeof options.stateFilePath === "string" && options.stateFilePath.trim()
+        ? options.stateFilePath.trim()
+        : DEFAULT_STATE_FILE_PATH,
+  }
+}
+
+function serializeGoal(goal) {
+  return {
+    ...goal,
+    messageIDs: [...(goal.messageIDs || [])],
+    history: [...(goal.history || [])],
+    checkpoints: [...(goal.checkpoints || [])],
+    lastCheckpoint: goal.lastCheckpoint || null,
+  }
+}
+
+function deserializeGoal(goal) {
+  const hydrated = {
+    ...goal,
+    messageIDs: new Set(goal?.messageIDs || []),
+    history: Array.isArray(goal?.history) ? goal.history : [],
+    checkpoints: Array.isArray(goal?.checkpoints) ? goal.checkpoints : [],
+    lastCheckpoint: goal?.lastCheckpoint || null,
+  }
+
+  if (!hydrated.stopped) {
+    hydrated.stopped = true
+    hydrated.stopReason = "recovered after restart"
+    hydrated.lastStatus = "Recovered persisted goal state. Review /goal status and run /goal resume when ready."
+    pushHistory(
+      hydrated,
+      "recovered",
+      "Recovered persisted goal state after plugin restart; auto-continue remains paused until you resume.",
+    )
+  }
+
+  return hydrated
+}
+
+async function loadPersistedState(persistenceOptions, client) {
+  if (!persistenceOptions.persistState) return "disabled"
+
+  try {
+    const raw = await fs.readFile(persistenceOptions.stateFilePath, "utf8")
+    const parsed = JSON.parse(raw)
+    if (parsed?.version !== STATE_FILE_VERSION) {
+      await logPluginError(
+        client,
+        `Skipped persisted goal state: unsupported version ${parsed?.version ?? "unknown"}.`,
+      )
+      return "invalid"
+    }
+
+    clearRuntimeState()
+
+    for (const goal of parsed.goals || []) {
+      goalStates.set(goal.sessionID, deserializeGoal(goal))
+    }
+
+    for (const result of parsed.results || []) {
+      lastGoalResults.set(result.sessionID, result)
+    }
+
+    return "loaded"
+  } catch (error) {
+    if (error?.code === "ENOENT") return "missing"
+    await logPluginError(client, "Failed to load persisted goal state", error)
+    return "invalid"
+  }
+}
+
+async function persistState(persistenceOptions, client) {
+  if (!persistenceOptions.persistState) return
+
+  try {
+    await fs.mkdir(dirname(persistenceOptions.stateFilePath), { recursive: true, mode: 0o700 })
+    const tmpPath = `${persistenceOptions.stateFilePath}.${process.pid}.${randomUUID()}.tmp`
+    await fs.writeFile(
+      tmpPath,
+      JSON.stringify(
+        {
+          version: STATE_FILE_VERSION,
+          goals: [...goalStates.values()].map(serializeGoal),
+          results: [...lastGoalResults.entries()].map(([sessionID, result]) => ({
+            ...result,
+            sessionID,
+            history: [...(result.history || [])],
+            checkpoints: [...(result.checkpoints || [])],
+            lastCheckpoint: result.lastCheckpoint || null,
+          })),
+        },
+        null,
+        2,
+      ),
+      { encoding: "utf8", mode: 0o600 },
+    )
+    await fs.rename(tmpPath, persistenceOptions.stateFilePath)
+    await fs.chmod(persistenceOptions.stateFilePath, 0o600)
+  } catch (error) {
+    await logPluginError(client, "Failed to persist goal state", error)
   }
 }
 
@@ -204,43 +475,48 @@ function parseGoalArguments(args, defaults) {
   const parts = args.match(/"[^"]*"|'[^']*'|\S+/g) || []
   const condition = []
   const options = { ...defaults }
+  const errors = []
 
   for (let i = 0; i < parts.length; i += 1) {
     const part = parts[i]
-    const next = parts[i + 1]
-    const nextIsValue = next !== undefined && !next.startsWith("--")
 
-    if (part === "--max-turns") {
-      if (nextIsValue) { options.maxTurns = toPositiveInteger(next, options.maxTurns); i += 1 }
-      continue
-    }
-    if (part === "--max-duration-ms") {
-      if (nextIsValue) { options.maxDurationMs = toPositiveInteger(next, options.maxDurationMs); i += 1 }
-      continue
-    }
-    if (part === "--max-minutes") {
-      if (nextIsValue) { options.maxDurationMs = toPositiveInteger(next, options.maxDurationMs / 60000) * 60000; i += 1 }
-      continue
-    }
-    if (part === "--max-tokens") {
-      if (nextIsValue) { options.maxTokens = toPositiveInteger(next, options.maxTokens); i += 1 }
-      continue
-    }
-    if (part === "--cooldown-ms") {
-      if (nextIsValue) { options.minDelayMs = toPositiveInteger(next, options.minDelayMs); i += 1 }
-      continue
-    }
-    if (part === "--no-progress-threshold") {
-      if (nextIsValue) { options.noProgressTokenThreshold = toPositiveInteger(next, options.noProgressTokenThreshold); i += 1 }
+    if (part.startsWith("--")) {
+      const [flagName, inlineValue] = part.split(/=(.*)/s, 2)
+      const flagSpec = GOAL_FLAG_SPECS[flagName]
+
+      if (!flagSpec) {
+        const next = parts[i + 1]
+        if (inlineValue === undefined && next !== undefined && !next.startsWith("--")) i += 1
+        errors.push(`Unsupported flag: ${flagName}`)
+        continue
+      }
+
+      const next = parts[i + 1]
+      const value = inlineValue ?? (next !== undefined && !next.startsWith("--") ? next : undefined)
+      if (inlineValue === undefined && value !== undefined) i += 1
+
+      if (value === undefined) {
+        errors.push(`Missing value for ${flagName}`)
+        continue
+      }
+
+      const parsedValue = parsePositiveIntegerStrict(stripWrappingQuotes(value))
+      if (parsedValue === null) {
+        errors.push(`Invalid positive integer for ${flagName}: ${value}`)
+        continue
+      }
+
+      options[flagSpec.optionKey] = flagSpec.parse(parsedValue, options)
       continue
     }
 
-    condition.push(part.replace(/^["']|["']$/g, ""))
+    condition.push(stripWrappingQuotes(part))
   }
 
   return {
     condition: condition.join(" ").trim(),
     options,
+    errors,
   }
 }
 
@@ -348,6 +624,20 @@ function extractBlockedReason(text) {
     .find((line) => line.trim())?.trim() || ""
 }
 
+function formatArgumentErrors(errors) {
+  return [
+    "Goal flags could not be parsed.",
+    ...errors.map((error) => `- ${error}`),
+    "",
+    "Supported flags: --max-turns, --max-minutes, --max-duration-ms, --max-tokens, --cooldown-ms, --no-progress-threshold, --no-progress-turns.",
+    "You can pass them as `--flag value` or `--flag=value`.",
+  ].join("\n")
+}
+
+function findLatestAssistantMessage(messages) {
+  return [...(messages || [])].reverse().find((message) => message.info?.role === "assistant") || null
+}
+
 function outputTokensForMessage(message) {
   return message?.info?.tokens?.output || 0
 }
@@ -361,6 +651,15 @@ function budgetWrapupNeeded(goal) {
 
 export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
   const defaultGoalOptions = normalizeOptions(pluginOptions)
+  const persistenceOptions = normalizePersistenceOptions(pluginOptions)
+  const persist = async () => persistState(persistenceOptions, client)
+
+  clearRuntimeState()
+  const persistedStateStatus = await loadPersistedState(persistenceOptions, client)
+  pruneGoalResults(defaultGoalOptions)
+  if (persistedStateStatus === "loaded" || persistedStateStatus === "missing") {
+    await persist()
+  }
 
   return {
     "command.execute.before": async (input, output) => {
@@ -368,6 +667,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
 
       const args = (input.arguments || "").trim()
       const sessionID = input.sessionID
+      pruneGoalResults(defaultGoalOptions)
 
       if (!args || args === "status") {
         const goal = goalStates.get(sessionID)
@@ -384,9 +684,37 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
         return
       }
 
+      if (args === "history") {
+        const goal = goalStates.get(sessionID)
+        const lastResult = lastGoalResults.get(sessionID)
+        output.parts = [
+          makeTextPart(
+            goal
+              ? [
+                  `Goal history for: ${goal.condition}`,
+                  "",
+                  `Latest checkpoint: ${goal.lastCheckpoint?.summary || "none yet"}`,
+                  "",
+                  formatHistory(goal.history),
+                ].join("\n")
+              : lastResult
+                ? [
+                    `Last goal history for: ${lastResult.condition}`,
+                    "",
+                    `Latest checkpoint: ${lastResult.lastCheckpoint?.summary || "none recorded"}`,
+                    "",
+                    formatHistory(lastResult.history),
+                  ].join("\n")
+                : "No goal history recorded yet. Set a goal with `/goal <condition>`.",
+          ),
+        ]
+        return
+      }
+
       if (CLEAR_COMMANDS.has(args)) {
         cleanupGoal(sessionID)
         lastGoalResults.delete(sessionID)
+        await persist()
         output.parts = [makeTextPart("Goal cleared.")]
         return
       }
@@ -400,6 +728,8 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
         goal.stopped = true
         goal.stopReason = "paused"
         goal.lastStatus = "Goal paused."
+        pushHistory(goal, "paused", "User paused the active goal.")
+        await persist()
         output.parts = [makeTextPart(`Goal paused: ${goal.condition}`)]
         return
       }
@@ -420,11 +750,17 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
         goal.stopReason = ""
         goal.blockedReason = ""
         goal.lastStatus = "Goal resumed with a fresh local budget."
+        pushHistory(goal, "resumed", "User resumed the goal with a fresh local budget window.")
+        await persist()
         output.parts = [makeTextPart(`Goal resumed with fresh limits: ${goal.condition}`)]
         return
       }
 
       const parsed = parseGoalArguments(args, defaultGoalOptions)
+      if (parsed.errors.length > 0) {
+        output.parts = [makeTextPart(formatArgumentErrors(parsed.errors))]
+        return
+      }
       if (!parsed.condition) {
         output.parts = [makeTextPart("No goal provided. Set one with `/goal <condition>`.")]
         return
@@ -440,6 +776,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
         options: parsed.options,
         lastStatus: "Goal set.",
         lastAssistantText: "",
+        lastAssistantMessageID: "",
         lastContinueAt: 0,
         lastProgressAt: 0,
         noProgressTurns: 0,
@@ -449,11 +786,21 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
         stopReason: "",
         promptFailures: 0,
         messageIDs: new Set(),
+        history: [],
+        checkpoints: [],
+        lastCheckpoint: null,
       }
 
+      pushHistory(
+        goal,
+        "set",
+        `Goal created with limits: ${goal.options.maxTurns} auto-continues, ${Math.round(goal.options.maxDurationMs / 1000)}s, ${goal.options.maxTokens.toLocaleString()} tracked tokens.`,
+      )
+
       cleanupGoal(sessionID)
       lastGoalResults.delete(sessionID)
       goalStates.set(sessionID, goal)
+      await persist()
       output.parts = [
         makeTextPart(
           [
@@ -462,6 +809,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
             "Start working toward this goal now.",
             "When the goal is fully satisfied, end your response with `[goal:complete]`.",
             "If you are truly blocked and need the user, end with `[goal:blocked]`.",
+            "Use `/goal history` to inspect recent lifecycle events and checkpoints.",
             "",
             `Limits: ${goal.options.maxTurns} auto-continues, ${Math.round(
               goal.options.maxDurationMs / 1000,
@@ -479,6 +827,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
         const goal = goalStates.get(message.sessionID)
         if (!goal) return
 
+        let changed = false
         const currentOutputTokens = message.tokens?.output || 0
         const previousOutputTokens = seenOutputTokens.get(message.id) || 0
         const currentTokens =
@@ -490,17 +839,21 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
           goal.totalTokens += currentTokens - previousTokens
           seenTokens.set(message.id, currentTokens)
           goal.messageIDs.add(message.id)
+          changed = true
         }
 
         if (currentOutputTokens > previousOutputTokens) {
           seenOutputTokens.set(message.id, currentOutputTokens)
           goal.messageIDs.add(message.id)
+          changed = true
         }
 
         if (message.role === "assistant" && currentOutputTokens > previousOutputTokens) {
           goal.lastProgressAt = Date.now()
-          goal.noProgressTurns = 0
+          changed = true
         }
+
+        if (changed) await persist()
         return
       }
 
@@ -515,23 +868,32 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
       try {
         const messages = await client.session.messages({
           path: { id: sessionID },
-          query: { limit: 12 },
+          query: { limit: goal.options.maxRecentMessages },
         })
         const activeGoalAfterMessages = currentGoal(sessionID, goalID)
         if (!activeGoalAfterMessages) return
 
-        const latestAssistant = [...(messages.data || [])]
-          .reverse()
-          .find((message) => message.info?.role === "assistant")
+        const latestAssistant = findLatestAssistantMessage(messages.data)
+        const latestAssistantID = latestAssistant?.info?.id || ""
         const latestText = getText(latestAssistant?.parts)
-        const latestOutputTokens = outputTokensForMessage(latestAssistant)
-
+        const latestOutputTokens = latestAssistant ? outputTokensForMessage(latestAssistant) : null
+        const previousAssistantText = activeGoalAfterMessages.lastAssistantText
+        const assistantChanged = summarizeText(latestText) !== summarizeText(previousAssistantText)
+        const assistantRepeated =
+          latestAssistantID && latestAssistantID === activeGoalAfterMessages.lastAssistantMessageID
+
+        if (latestText && (!assistantRepeated || assistantChanged)) {
+          recordCheckpoint(activeGoalAfterMessages, latestText)
+        }
         activeGoalAfterMessages.lastAssistantText = latestText
+        activeGoalAfterMessages.lastAssistantMessageID = latestAssistantID
 
         if (goalIsComplete(latestText)) {
           activeGoalAfterMessages.lastStatus = "Goal completed."
+          pushHistory(activeGoalAfterMessages, "completed", "Assistant marked the goal complete.")
           rememberGoalResult(sessionID, activeGoalAfterMessages, "achieved")
           cleanupGoal(sessionID)
+          await persist()
           return
         }
 
@@ -540,6 +902,12 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
           activeGoalAfterMessages.lastStatus = "Assistant reported blocked."
           activeGoalAfterMessages.stopped = true
           activeGoalAfterMessages.stopReason = "blocked"
+          pushHistory(
+            activeGoalAfterMessages,
+            "blocked",
+            activeGoalAfterMessages.blockedReason || "Assistant reported blocked and requested user input.",
+          )
+          await persist()
           return
         }
 
@@ -550,6 +918,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
             activeGoalAfterMessages.stopped = true
             activeGoalAfterMessages.stopReason = limitReason
             activeGoalAfterMessages.lastStatus = `${limitReason}; requested final handoff.`
+            pushHistory(activeGoalAfterMessages, "limit", `${limitReason}; requested a final handoff.`)
             await client.session.promptAsync({
               path: { id: sessionID },
               body: { parts: [makeTextPart(buildContinueMessage(activeGoalAfterMessages, { budgetWrapup: true }))] },
@@ -558,19 +927,44 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
             activeGoalAfterMessages.stopped = true
             activeGoalAfterMessages.stopReason = limitReason
             activeGoalAfterMessages.lastStatus = limitReason
+            pushHistory(activeGoalAfterMessages, "limit", limitReason)
           }
+          await persist()
           return
         }
 
-        if (
+        const lowOutputTurn =
           activeGoalAfterMessages.turnCount > 0 &&
+          latestOutputTokens !== null &&
           latestOutputTokens < activeGoalAfterMessages.options.noProgressTokenThreshold
-        ) {
+        const lowOutputLooksStalled =
+          lowOutputTurn && (assistantRepeated || !latestText || !assistantChanged)
+        if (lowOutputLooksStalled) {
           activeGoalAfterMessages.noProgressTurns += 1
-          activeGoalAfterMessages.stopped = true
-          activeGoalAfterMessages.stopReason = "no progress"
-          activeGoalAfterMessages.lastStatus = `Goal auto-continue paused: last turn produced ${latestOutputTokens} output token(s). Run /goal resume to continue.`
-          return
+          if (
+            activeGoalAfterMessages.noProgressTurns >=
+            activeGoalAfterMessages.options.noProgressTurnsBeforePause
+          ) {
+            activeGoalAfterMessages.stopped = true
+            activeGoalAfterMessages.stopReason = "no progress"
+            activeGoalAfterMessages.lastStatus = `Goal auto-continue paused after ${activeGoalAfterMessages.noProgressTurns} low-progress turn(s); the latest turn produced ${latestOutputTokens} output token(s). Run /goal resume to continue.`
+            pushHistory(
+              activeGoalAfterMessages,
+              "paused",
+              `Paused after ${activeGoalAfterMessages.noProgressTurns} low-progress turn(s) below ${activeGoalAfterMessages.options.noProgressTokenThreshold} output tokens.`,
+            )
+            await persist()
+            return
+          }
+
+          activeGoalAfterMessages.lastStatus = `Low-progress turn detected (${activeGoalAfterMessages.noProgressTurns}/${activeGoalAfterMessages.options.noProgressTurnsBeforePause}); monitoring for another stalled turn before pausing.`
+          pushHistory(
+            activeGoalAfterMessages,
+            "warning",
+            `Observed a low-progress turn below ${activeGoalAfterMessages.options.noProgressTokenThreshold} output tokens; grace count ${activeGoalAfterMessages.noProgressTurns}/${activeGoalAfterMessages.options.noProgressTurnsBeforePause}.`,
+          )
+        } else if (latestOutputTokens !== null || assistantChanged) {
+          activeGoalAfterMessages.noProgressTurns = 0
         }
 
         const elapsedSinceLastContinue = Date.now() - activeGoalAfterMessages.lastContinueAt
@@ -615,6 +1009,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
           if (activeGoalAfterPrompt) {
             activeGoalAfterPrompt.promptFailures += 1
             activeGoalAfterPrompt.lastStatus = message
+            pushHistory(activeGoalAfterPrompt, "error", message)
             if (activeGoalAfterPrompt.promptFailures >= activeGoalAfterPrompt.options.maxPromptFailures) {
               activeGoalAfterPrompt.stopped = true
               activeGoalAfterPrompt.stopReason = "auto-continue failures"
@@ -624,19 +1019,31 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
           await logPluginError(client, message, response.error)
         } else {
           const activeGoalAfterPrompt = currentGoal(sessionID, goalID)
-          if (activeGoalAfterPrompt) activeGoalAfterPrompt.promptFailures = 0
+          if (activeGoalAfterPrompt) {
+            activeGoalAfterPrompt.promptFailures = 0
+            pushHistory(
+              activeGoalAfterPrompt,
+              budgetWrapup ? "budget-wrapup" : "auto-continue",
+              budgetWrapup
+                ? "Sent a final handoff request near the tracked token budget."
+                : `Sent auto-continue prompt ${activeGoalAfterPrompt.turnCount}/${activeGoalAfterPrompt.options.maxTurns}.`,
+            )
+          }
         }
+        await persist()
       } catch (error) {
         const activeGoalAfterError = currentGoal(sessionID, goalID)
         if (activeGoalAfterError) {
           activeGoalAfterError.promptFailures += 1
           const message = `Auto-continue failed: ${error?.message || error}`
           activeGoalAfterError.lastStatus = message
+          pushHistory(activeGoalAfterError, "error", message)
           if (activeGoalAfterError.promptFailures >= activeGoalAfterError.options.maxPromptFailures) {
             activeGoalAfterError.stopped = true
             activeGoalAfterError.stopReason = "auto-continue failures"
             activeGoalAfterError.lastStatus = `${message}; paused after ${activeGoalAfterError.promptFailures} failure(s). Run /goal resume to retry.`
           }
+          await persist()
         }
         await logPluginError(client, "Auto-continue failed", error)
       } finally {
@@ -679,6 +1086,8 @@ export const testInternals = {
   currentGoal,
   escapeGoalText,
   extractBlockedReason,
+  findLatestAssistantMessage,
+  formatArgumentErrors,
   formatStatus,
   getSessionID,
   goalIsBlocked,
@@ -687,5 +1096,7 @@ export const testInternals = {
   normalizeOptions,
   outputTokensForMessage,
   parseGoalArguments,
+  parsePositiveIntegerStrict,
+  pruneGoalResults,
   stopReason,
 }