opencode-goal-plugin 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 ## Unreleased
 
+## 0.5.0 — 2026-07-08
+
+- Replace the single-line "Compatibility snapshot" in the README with an OpenCode version compatibility table, manually verified via `tmux` + the OpenCode TUI against the persisted state file for each provider/model combination.
+- Add `docs/providers.md`, a provider/model compatibility guide covering evidence-gated marker-compliance behavior for `opencode-go/qwen3.7-plus`, `opencode-go/glm-5.2`, and `deepseek/deepseek-chat` (manually verified via the OpenCode TUI against real provider credentials on OpenCode 1.17.15), plus a step-by-step guide for testing new models.
+- Add a reproducible `demo/` directory: a minimal Node project with a deliberately buggy `add()` function, a test that catches it, and an `opencode.json` wired to the local plugin source. Verified end-to-end via the OpenCode TUI.
+- Scope `npm test`/`npm run test:coverage` to `test/*.test.js` explicitly, since Node's test runner otherwise recursively discovers `demo/test/*.test.js` too, which would fail the root suite whenever the demo's deliberate bug is (correctly) unfixed.
+- **Fix project-local state persistence to actually use the active session's directory.** `GoalPlugin` previously ignored the `directory` field OpenCode passes in its `PluginInput`, so the default `.opencode/goals/state.json` path resolved against the Node process's own `process.cwd()` instead. This works fine for a one-shot CLI invocation, but silently breaks when OpenCode runs as a persistent server/daemon serving multiple projects: `process.cwd()` stays wherever the server booted, not the active session's project. Confirmed live via the OpenCode TUI — a goal set in a project directory never persisted to disk at all. `GoalPlugin` now reads `directory` from its `PluginInput` and uses it as the default `cwd` for state-path resolution (an explicit `cwd` plugin option, mainly for tests, still takes precedence).
+- Add Node 24 to the CI matrix, a weekly scheduled CI run (Mondays 08:00 UTC) to catch upstream drift, a `test:coverage` step, and npm/CI/tests/license badges to the README.
+- Add GitHub issue templates for bug reports (OpenCode version, provider/model, Node version, relevant plugin options, repro steps) and feature requests (problem solved, scope fit against the current multi-goal/audit feature set).
+- Add an Examples section to the README with copy-pasteable `/goal` commands: common workflows, success criteria/constraints/budget shorthand, and an ordered (sisyphus) sequence.
+- Add a Comparison section to the README benchmarking `/goal` support, auto-continue, per-goal overrides, no-progress/no-tool-call detection, safety limits, history, persistence, multi-goal/sisyphus sequences, evidence-gated completion, the optional completion auditor, budget wrap-up, and license against Claude Code and Codex.
+- Add `npm run verify` / `npx opencode-goal-plugin` installation verification command (`scripts/verify.mjs`). Checks Node >= 18, the plugin module shape, that all 4 hooks (`command.execute.before`, `event`, `experimental.chat.system.transform`, `experimental.compaction.autocontinue`) register, and that `/goal status`/`/goal set` work — entirely via mock clients, with zero model calls.
+- Add TypeScript declarations (`index.d.ts`) covering the full current `GoalPluginOptions` surface — budgets, persistence/ledger paths, `commandName`/`registerCommand`/`registerTools`, and the completion-audit options (`completionAudit`, `auditor`, `auditorOptions`, `auditMessages`, `auditMessenger`) — plus the plugin's hook map and default export. `package.json`'s `types` field points at it.
+- Warn when `/goal <condition>` replaces the focused goal instead of silently discarding it. The response now leads with `⚠️ Replacing active goal: "<old condition>"` and points at `/goal add <condition>` as the non-destructive alternative that backgrounds the current goal instead.
+
+## 0.4.7 — 2026-06-29
+
+### Bug fixes (low-severity cleanups)
+
+- **Dead `if (goal.goalId !== previousGoalId)` conditional removed from both resume paths.** `resetGoalBudget` always rotates `goalId` via `randomUUID()`, so the conditional was always `true`. The misleading branch could never be taken, masking the intent (unconditional registry re-key on resume). Both the agent-tool `updateGoal {status: "resumed"}` path and the `/goal resume` command path are now unconditional.
+- **`noToolCallTurns` no longer stales on null-assistant idles.** When `messages()` returns no assistant message (only a user turn), `latestAssistant` is `null` and `latestHasToolCall` is `false`. Previously the counter incremented unconditionally; a user-only idle turn could push the goal toward a no-tool-call pause even though the model hadn't spoken. The reset condition now includes `|| !latestAssistant`, matching the intent of the stall detector.
+- **`noProgressTurns` no longer stales on null-assistant idles.** Same scenario as above: when `latestOutputTokens === null` and there is no assistant message, the counter now resets instead of incrementing, consistent with the gate's purpose of detecting stalled model output.
+- **Updated ledger-durability comment near `pushHistory("completed")`.** The previous comment implied the ledger was the primary recovery mechanism. The corrected comment clarifies that ledger write failures are silent (bare `catch`), and that a present state file always takes precedence over the ledger — making the ledger relevant only when the state file is absent.
+- **`buildAgentToolHandlers` accepts a `persistTerminalState` option.** Terminal state transitions (`status='complete'` and `clearGoal`) now call `persistTerminalState` if provided, falling back to the regular `persist` function. The `GoalPlugin` factory passes its own `persistTerminalState` closure through, so agent-triggered completions and clears get the same durable flush semantics as the event-handler paths.
+
+## 0.4.6 — 2026-06-29
+
+### Bug fixes (counters, compaction, and auditor)
+
+- **`noToolCallTurns` is now independent of `noProgressTurns`.** On a turn that qualifies for the noProgress stall gate (low output, no tool call, stalled text), the noToolCall counter no longer also increments. Without this guard, the effective grace window was `min(noProgress, noToolCall)` rather than two independent limits — a configured higher `noProgressTurnsBeforePause` threshold was silently overridden by the lower `noToolCallTurnsBeforePause`.
+- **`formatFailures` is now incremented when the stall gate fires and returns early.** Stall detection previously returned before the format-failure accumulator could run. A model that repeatedly emitted bare `[goal:complete]` with low output triggered the stall gate rather than accumulating toward the `maxPromptFailures` cap; the cap was permanently unreachable because `/goal resume` reset `formatFailures` to zero each time. The counter now increments inside the stall-gate early-return path when `completionUnverified` or `blockerUnstated` is true.
+- **Budget-wrapup state is persisted before the wrapup prompt is sent.** Previously `budgetWrapupSent = true` and `stopped = true` were set in memory but not persisted before `promptAsync`. A crash during the prompt would result in `budgetWrapupSent: false` in the state file and a duplicate wrapup on the next resume cycle. The fix adds `pushHistory("budget-wrapup")` + `persist()` before the prompt call, mirroring the hard-limit path.
+- **`TOOL_PART_TYPES` now covers raw provider part type names.** Some OpenCode adapters forward the provider's original message part shape without normalizing to `"tool"`. Added `"tool_use"`, `"function_call"`, and `"tool-call"` to the set so `messageHasToolCall` (and both stall gates) correctly recognize tool-using turns from non-normalized adapters.
+- **Approved completion that is lost while the auditor is in flight now produces an announcement.** If the goal is cleared or replaced while a completion auditor runs, and the auditor returns `approved: true`, the plugin now announces "completion was approved but the goal was modified while the audit ran — completion not recorded." Previously the approved result was silently discarded with no visible trace.
+- **`buildCompactionContext` is now deterministic.** The function previously called `Date.now()` to compute elapsed seconds, so two calls during the same compaction event produced different strings, busting the prefix cache from that byte position. The elapsed time is now derived from `goal.lastContinueAt` (set during each persist cycle), making the output stable and matching the function's own claim of being "reconstructed deterministically from the plugin's persisted goal record."
+
+## 0.4.5 — 2026-06-29
+
+### Bug fixes (input validation + counter correctness)
+
+- **`set_goal` now validates budget arguments and mode.** Previously `set_goal({maxTurns: 0})` silently used the global default; a typo in `mode` silently became `"normal"`. Both now return explicit errors, matching the `/goal` command's validation behavior.
+- **`update_goal` cannot combine an objective update with `status='complete'` in the same call.** The completion would be archived under a condition that was never executed, falsifying the audit trail. The tool now requires two separate calls: first update the objective, then mark complete after the revised work is done.
+- **`update_goal {status: 'resumed'}` on a running goal returns an error.** The slash-command path rejected this; the agent tool path silently reset all budget counters — turnCount, totalTokens, startedAt, etc. — on a goal that never stopped, enabling indefinite budget circumvention. The agent tool now rejects the call when the goal is not stopped.
+- **`/goal edit` and `update_goal` objective updates now reset `formatFailures` to 0.** The edit paths already reset `noProgressTurns` and `noToolCallTurns` but omitted `formatFailures`. A goal with accumulated format-failure violations had less tolerance than a freshly-resumed goal after an objective change.
+- **`/goal <condition>` replace command now clears `sessionOrdered`.** The agent `setGoal` path called `sessionOrdered.delete()` on replacement, but the slash-command path did not. A user replacing a sisyphus sequence with a standalone goal would get unexpected auto-promotion of the sequence's remaining goals after the replacement completed.
+- **`set_goal` and `update_goal` tool result strings now escape XML metacharacters.** The `goal.condition` is stored raw (for use by `buildGoalBlock`/`buildContinueMessage`), but the tool result returned to the model now calls `escapeGoalText` to prevent XML metacharacters from breaking tool-result boundaries in XML-serialized formats.
+- **`promptFailures` decrements by 1 on a successful prompt instead of resetting to 0.** This mirrors the `formatFailures` fix: an alternating error/success pattern previously bypassed the circuit-breaker cap indefinitely. Decrementing allows gradual recovery while still accumulating toward the cap over time.
+
+## 0.4.4 — 2026-06-29
+
+### Bug fixes (state machine + injection prevention)
+
+- **`escapeGoalText` now neutralizes role-like tag openings.** The previous `STRUCTURAL_TAGS` set only covered plugin-defined tags. Tags like `<system>`, `<assistant>`, `<human>`, `<anthropic>`, `<claude>`, `<context>`, `<instructions>`, and `<prompt>` could survive unescaped in compacted system messages, creating second-order injection opportunities where model output captured by `recordCheckpoint` re-appeared as an elevated-privilege block after compaction.
+- **`update_goal` objective update no longer un-stops a stopped goal.** Calling `update_goal({objective: "…"})` previously cleared `goal.stopped` and `goal.stopReason`, silently resurrecting a goal that was audit-rejected, user-paused, or blocked for any reason. Objective updates now preserve the stopped state; only an explicit `status: "resumed"` call resets it.
+- **`/goal clear` and agent `clearGoal` now delete all backgrounded goals.** Previously only the focused goal was removed from the session registry (`cleanupGoal` → `removeSessionGoal`). Background goals added via `/goal add` remained alive and would promote themselves to focused on restart. Both clear paths now call `sessionGoals.delete(sessionID)` first, wiping the entire per-session goal map.
+- **`formatFailures` decrements by 1 on a clean turn instead of resetting to 0.** A reset-to-zero on every non-violation turn allowed an alternating bad/good/bad pattern to bypass the consecutive-failure cap indefinitely. Decrementing by 1 means repeated violations accumulate toward the cap even when interspersed with good turns.
+- **`update_goal {status: "blocked"}` requires a non-empty `blocker` argument.** The event-handler path already rejects a `[goal:blocked]` marker with no concrete blocker, but the agent tool path accepted an empty `blocker` (recording an empty `blockedReason`). The agent tool now returns an error when `blocker` is missing or whitespace-only, consistent with the auto-continue guard.
+
+## 0.4.3 — 2026-06-29
+
+### Bug fixes (concurrency + persistence)
+
+- **`activeContinues` Set → Map with per-handler UUID token.** `cleanupGoal` removes the session from the Map (allowing new handlers to start), but the idle handler's `finally` block only deletes if its token still matches — preventing it from clobbering a new handler's guard. With a plain `Set`, the old `finally` unconditionally deleted the new handler's entry, creating a race window where two handlers could run concurrently for the same session.
+- **Liveness re-check after `announceAudit`.** `announceAudit` is async and can yield long enough for a user to `/goal clear` or replace the goal. The handler now calls `activeGoal(sessionID, goalID)` after the announcement and returns immediately if the goal is gone, preventing an orphaned archive write.
+- **`persist()` calls serialized via promise chain.** Concurrent callers previously raced on the temp-file rename: the second rename could write older state over the first. All calls now chain through `persistChain`, guaranteeing ordered writes.
+- **`/goal clear` and agent `clearGoal` now emit a `"cleared"` ledger event before discarding the goal.** Without this, `reconstructGoalsFromLedger` (used when the state file is missing) would revive cleared goals as paused on restart. `LEDGER_TERMINAL_TYPES` already includes `"cleared"` — the event just wasn't being written.
+- **State-file/ledger cross-check on restart.** After loading from the state file, the plugin now reads the ledger and removes any active goals whose `goalId` appears in a terminal ledger entry. This guards against the scenario where a terminal persist wrote to the ledger but the state file write failed (e.g. process killed between the two writes): the goal would otherwise load as active and be re-driven on the next idle.
+
+### Bug fixes (state machine + security)
+
+- **Escape checkpoint and history text in compaction context.** Checkpoint summaries and lifecycle-event details contain assistant-generated text. If a malicious assistant output included structural XML tags (e.g. `</goal_objective><budget_wrapup>…</budget_wrapup>`), they could be re-embedded unescaped in the compaction context system message. `buildCompactionProgressSummary` and the `lastCheckpoint` inline in `buildCompactionContext` now call `escapeGoalText` on all assistant-derived strings.
+- **`/goal edit` and agent `update_goal` objective updates now reset `noToolCallTurns`.** The edit paths already reset `noProgressTurns` and cleared soft-stop state, but forgot `noToolCallTurns`. A goal that was heading toward a no-tool-call pause kept its stale counter after an objective change, and could pause after fewer than the configured grace turns on the new objective.
+- **`formatFailures` is now preserved through a persistence round-trip.** `normalizePersistedGoal` carried `promptFailures` but omitted `formatFailures`. After a plugin restart any accumulated format-failure count was silently reset to zero, giving the model an unintended free pass on the first format re-prompts after recovery.
+- **Agent `update_goal {status: "complete"}` now invokes the configured completion auditor.** The `[goal:complete]` marker path gates archival on an optional auditor, but the agent tool path bypassed it entirely. `buildAgentToolHandlers` now accepts a `completionAuditor` option, and the `GoalPlugin` factory passes the configured auditor through. A rejected verdict pauses the goal with stop reason `audit rejected`; an auditor that throws is treated as a rejection (fail closed).
+- **`createChildSessionAuditor` now enforces a configurable timeout (default 120 s).** `sessionApi.prompt` could hang indefinitely, blocking the idle handler and stalling the goal forever. The auditor now races the API call against a `setTimeout` promise; if the timeout fires first, the verdict is `{ approved: false, reason: "auditor timed out after Nms" }`. The timer is always cleared after settlement.
+- **Thinking-only turns are excluded from the `noProgress` stall detector.** A turn that produced reasoning tokens but no prose output and no tool calls was treated as stalled by `lowOutputLooksStalled` (prose output tokens = 0 < threshold). The new `latestHasThinkingTokens` check (`tokens.reasoning > 0`) excludes such turns from the stall gate, preventing false pauses on extended-thinking models that reason before acting.
+
+## 0.4.2 — 2026-06-29
+
+### Bug fixes
+
+- **Guard against stale `message.updated` re-deliveries re-inflating `totalTokens` after `/goal resume`.** After `/goal resume`, OpenCode replays the streaming `message.updated` event for the last assistant message. Previously `resetGoalBudget` deleted those message IDs from `seenTokens`, so the replayed event looked new and added its tokens to the freshly-zeroed counter — incorrectly inflating the resumed goal's token total from the first turn. Fix: `resetGoalBudget` no longer deletes IDs from `seenTokens`. The `message.updated` handler now skips any message whose ID is already in `seenTokens` but is absent from the current `goal.messageIDs` (i.e. belongs to a prior budget epoch), so stale re-deliveries are silently ignored.
+- **Guard against stale `message.updated` re-deliveries inflating a replacement goal's `totalTokens`.** When a goal is replaced via `/goal <new>`, the old goal's `cleanupGoal` path previously deleted its message IDs from `seenTokens`. If OpenCode then re-delivered a streaming event for one of those old IDs (e.g. a buffered duplicate), the new goal object had no record of it, so the guard could not fire and the event inflated the new goal's counter. Fix: `cleanupGoal` also leaves `seenTokens` entries in place. Entries accumulate across the process lifetime (O(turns × messages_per_turn)) and are cleared in bulk by `clearRuntimeState` on teardown.
+- **Reset `totalTokens` to zero after session compaction.** `totalTokens` is tracked with `Math.max` semantics (peak context size), so it never decreases on its own. A goal that crossed the 80 % budget-wrapup threshold before compaction would permanently remain above it even after the context shrank to a fraction of its prior size. Fix: the `experimental.session.compacting` hook now resets `totalTokens = 0` and rotates `messageIDs` into `priorMessageIDs` after injecting the compaction context, then calls `persist()`. Post-compaction turns re-establish the token baseline from scratch.
+
 ## 0.4.1 — 2026-06-29
 
 ### Bug fixes

package/README.md

@@ -1,20 +1,57 @@
 # opencode-goal-plugin
 
+[![npm version](https://img.shields.io/npm/v/opencode-goal-plugin)](https://www.npmjs.com/package/opencode-goal-plugin)
+[![npm downloads](https://img.shields.io/npm/dm/opencode-goal-plugin)](https://www.npmjs.com/package/opencode-goal-plugin)
+[![CI](https://github.com/willytop8/OpenCode-goal-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/willytop8/OpenCode-goal-plugin/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-185%20passing-brightgreen)](test/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
 An experimental session-scoped `/goal` command for [OpenCode](https://opencode.ai/).
 
 Set a goal and the plugin keeps it in context, auto-continues the session whenever the assistant goes idle, and stops when the goal is marked complete, a blocker is reported, or a safety limit is reached.
 
 Compatibility: this plugin relies on experimental OpenCode hooks. Re-test against the exact OpenCode build and provider/backend stack you plan to use for unattended work.
 
+## Comparison
+
+| Feature | Claude Code | Codex | opencode-goal-plugin |
+|---|---|---|---|
+| `/goal` command | ✅ Native | ✅ Native | ✅ Plugin |
+| Auto-continue | ✅ | ✅ | ✅ |
+| Per-goal flag overrides | ❌ | ❌ | ✅ |
+| No-progress / no-tool-call detection | ❌ | ❌ | ✅ Both |
+| Configurable safety limits | Limited | Limited | ✅ All tunable |
+| Goal history | ✅ | ❌ | ✅ `/goal history` |
+| Goal persistence | ❌ | ❌ | ✅ Survives restart, ledger-backed |
+| Multiple concurrent goals | ❌ | ❌ | ✅ `/goal add` / `/goal focus` |
+| Ordered goal sequences | ❌ | ❌ | ✅ `/goal sisyphus` |
+| Evidence-gated completion | ❌ | ❌ | ✅ `[goal:evidence]` required |
+| Independent completion audit | ✅ | ❌ | ✅ Optional child-session auditor |
+| Budget wrap-up prompts | ❌ | ❌ | ✅ 80% threshold |
+| Open source | ❌ | ❌ | ✅ MIT |
+
 ## Compatibility snapshot
 
 | Surface | Status |
 |---|---|
-| Node.js | Declared support: `>=18`; CI covers Node 18, 20, and 22 |
+| Node.js | Declared support: `>=18`; CI covers Node 18, 20, 22, and 24 |
 | Package entrypoint | `npm run smoke` verifies the package export path plus `/goal` command-hook behavior from a local install without invoking a model |
-| OpenCode host | Manually smoke-tested against OpenCode 1.15.10 using the `opencode-go` provider (`qwen3.7-plus`) on this repo's local hardening branch; re-test your own version/provider stack before relying on unattended runs |
 | Provider/backend quirks | Strict-template backends require the goal block to merge into the primary `system` message; covered by regression tests |
 
+### OpenCode version compatibility
+
+Manually tested via the OpenCode TUI (`tmux` + real provider credentials, no mocks), verified against the plugin's own persisted state rather than terminal display alone:
+
+| OpenCode Version | Provider Tested | `/goal status` | Auto-continue | Evidence-gated completion | Hook Output Display |
+|---|---|---|---|---|---|
+| 1.17.15 | opencode-go (`qwen3.7-plus`) | ✅ | ✅ | ✅ Self-corrected after one rejection (bare `[goal:complete]` with no evidence), then completed cleanly | ⚠️ Not displayed |
+| 1.17.15 | opencode-go (`glm-5.2`) | ✅ | ✅ | ✅ Clean `[goal:evidence]` + `[goal:complete]` on the first attempt | ⚠️ Not displayed |
+| 1.17.15 | deepseek (`deepseek-chat`) | ✅ | ✅ | ✅ Clean `[goal:evidence]` + `[goal:complete]` on the first attempt; also verified end-to-end via the [demo](demo/) — autonomously fixed a real bug and reported evidence-backed completion | ⚠️ Not displayed |
+
+`/goal status` and auto-continue are graded on **state correctness** (verified directly against the plugin's persisted state file: correct limits parsed, correct turn/stop accounting, correct completion detection) — not on what's rendered in the terminal, since that's tracked separately as Hook Output Display.
+
+**Note:** Hook output display depends on OpenCode version — on 1.17.15, `command.execute.before`'s `output.parts` text is not rendered in the TUI for any provider tested; the raw command argument is instead routed to the model as a normal chat turn (see [Limitations](#limitations)). State mutations always work regardless of display: goal creation, flag parsing, auto-continue, limit enforcement, and evidence-gated completion detection were all verified correct via the persisted state file in every combination above. Re-test against your own OpenCode build before relying on unattended runs, and see [`docs/providers.md`](docs/providers.md) for the full per-model marker-compliance notes.
+
 ## Install
 
 ```sh
@@ -122,6 +159,29 @@ A session can hold more than one goal. `/goal <condition>` replaces the focused
 
 The first goal is focused and the rest are queued. `/goal list` marks the session as ordered. Auto-promotion stops when the sequence is exhausted; `/goal clear` ends the sequence.
 
+## Examples
+
+Copy-pasteable goals for common workflows:
+
+```
+/goal "fix the failing tests" --max-turns 10
+/goal "refactor auth to use new API" --max-minutes 30
+/goal "audit for security issues" --max-turns 3
+/goal "migrate class components to functional" --max-minutes 60 --max-tokens 400000
+```
+
+With success criteria, constraints, and a token budget shorthand:
+
+```
+/goal "ship the release" --success "tests pass and changelog updated" --constraints "do not touch the public API" --budget 150k
+```
+
+An ordered sequence, run as a strict pipeline:
+
+```
+/goal sisyphus build the parser; write the tests; ship the release
+```
+
 ## How it works
 
 1. When you set a goal, the plugin stores it in session memory and injects it into the system prompt so the assistant keeps it in view on every turn.
@@ -290,6 +350,19 @@ By default a `[goal:complete]` is accepted on the assistant's word. You can requ
 
 On **approval** the goal is archived as achieved. On **rejection** the goal is *not* archived — it is paused with stop reason `audit rejected` and the reason in its status, so you can address the gap and `/goal resume`. The built-in child-session auditor fails *open* (auto-approves) if the session API is unavailable, while a custom auditor that throws is treated as a rejection (fail closed). The audit is off unless one of these options is set.
 
+Pass `auditorOptions` to tune the built-in auditor:
+
+```js
+GoalPlugin({
+  completionAudit: true,
+  auditorOptions: {
+    timeoutMs: 60_000,  // default 120 000 ms; set lower for faster CI feedback
+  },
+})
+```
+
+`timeoutMs` caps how long the built-in child-session auditor waits for a verdict. If the session doesn't reply within the timeout the auditor auto-approves (fail open) so the goal can still be archived. `auditorOptions` is ignored when a custom `auditor` function is supplied.
+
 ## 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.

package/index.d.ts

@@ -0,0 +1,299 @@
+/**
+ * Type declarations for opencode-goal-plugin.
+ *
+ * These describe the plugin-level configuration object accepted in
+ * `opencode.json` under `plugin: [["opencode-goal-plugin", { ... }]]`,
+ * and the shape of the module's exports.
+ */
+
+/**
+ * Verdict returned by a completion auditor (built-in or custom). See
+ * {@link GoalPluginOptions.auditor} and {@link GoalPluginOptions.completionAudit}.
+ */
+export interface CompletionAuditVerdict {
+  /** `true` to archive the goal as achieved; `false` to reject the completion. */
+  approved: boolean
+  /** Human-readable reason, surfaced in the goal's status when rejected. */
+  reason?: string
+}
+
+/** Arguments passed to a custom {@link GoalPluginOptions.auditor} function. */
+export interface CompletionAuditContext {
+  /** The goal being audited (objective, budget usage, checkpoints, etc.). */
+  goal: unknown
+  /** The OpenCode session ID the goal belongs to. */
+  sessionID: string
+  /** The assistant's latest response text, containing the `[goal:evidence]`/`[goal:complete]` claim. */
+  latestText: string
+}
+
+/** Options for the built-in child-session completion auditor (`completionAudit: true`). */
+export interface CompletionAuditorOptions {
+  /**
+   * How long, in milliseconds, the built-in auditor waits for a verdict from
+   * its child OpenCode session before failing open (auto-approving).
+   * @default 120000
+   */
+  timeoutMs?: number
+}
+
+/**
+ * Configuration options for opencode-goal-plugin. All fields are optional;
+ * unset fields fall back to the plugin's built-in defaults. These act as
+ * the default limits for every goal set in a session, and most of the
+ * budget/behavior fields can be overridden per-goal via `/goal` command
+ * flags (e.g. `--max-turns`, `--success`, `--mode`).
+ */
+export interface GoalPluginOptions {
+  /**
+   * Maximum number of auto-continue turns sent toward a goal before it is
+   * stopped for exceeding limits. Overridable per-goal with `--max-turns`.
+   * @default 10
+   */
+  maxTurns?: number
+
+  /**
+   * Maximum wall-clock duration, in milliseconds, a goal may run before it
+   * is stopped for exceeding limits. Overridable per-goal with
+   * `--max-duration-ms` or `--max-minutes`.
+   * @default 900000
+   */
+  maxDurationMs?: number
+
+  /**
+   * Maximum context token budget a goal may consume before it is stopped
+   * for exceeding limits. Overridable per-goal with `--max-tokens` or the
+   * `--budget` shorthand (accepts a `k`/`m` suffix, e.g. `100k`, `1.5m`).
+   * @default 200000
+   */
+  maxTokens?: number
+
+  /**
+   * Minimum delay, in milliseconds, enforced between consecutive
+   * auto-continue prompts. Overridable per-goal with `--cooldown-ms`.
+   * @default 1500
+   */
+  minDelayMs?: number
+
+  /**
+   * 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.
+   * @default 50
+   */
+  maxRecentMessages?: number
+
+  /**
+   * Output token floor below which a turn is considered "low-output" for
+   * no-progress detection. Overridable per-goal with
+   * `--no-progress-threshold`.
+   * @default 50
+   */
+  noProgressTokenThreshold?: number
+
+  /**
+   * Grace window for low-output stalls: the goal is paused only after this
+   * many consecutive stalled low-output turns, rather than on the first
+   * one. Overridable per-goal with `--no-progress-turns`.
+   * @default 2
+   */
+  noProgressTurnsBeforePause?: number
+
+  /**
+   * Grace window for tool-free continuation turns (a "talk only" turn that
+   * calls no tool). Complements the no-progress check by catching
+   * self-chat loops that still produce output. Overridable per-goal with
+   * `--no-tool-turns`.
+   * @default 2
+   */
+  noToolCallTurnsBeforePause?: number
+
+  /**
+   * Fraction (between 0 and 1, exclusive) of any budget (turns, duration,
+   * or tokens) at which the plugin sends a one-time "wrap up" prompt
+   * nudging the model to finish before the hard limit is hit.
+   * @default 0.8
+   */
+  budgetWrapupRatio?: number
+
+  /**
+   * Number of remaining auto-continue turns at which a limit-approaching
+   * warning is included in status output.
+   * @default 3
+   */
+  warnTurnsRemaining?: number
+
+  /**
+   * Remaining duration, in milliseconds, at which a limit-approaching
+   * warning is included in status output.
+   * @default 60000
+   */
+  warnDurationMsRemaining?: number
+
+  /**
+   * Remaining context tokens at which a limit-approaching warning is
+   * included in status output.
+   * @default 25000
+   */
+  warnTokensRemaining?: number
+
+  /**
+   * Maximum number of consecutive prompt failures (e.g. transport errors
+   * sending the auto-continue prompt, or repeated missing-evidence /
+   * missing-blocker format violations) tolerated before the goal is
+   * stopped.
+   * @default 3
+   */
+  maxPromptFailures?: number
+
+  /**
+   * Whether to persist active/backgrounded goals and recent goal results
+   * to disk so they survive a restart. Recovered active goals are loaded
+   * in a paused state. Set to `false` for purely in-memory behavior (this
+   * also disables the lifecycle ledger).
+   * @default true
+   */
+  persistState?: boolean
+
+  /**
+   * Filesystem path where persisted goal state is written when
+   * `persistState` is enabled. Overrides both the project-local default
+   * and the `OPENCODE_GOAL_STATE_PATH` environment variable.
+   * @default "<cwd>/.opencode/goals/state.json"
+   */
+  stateFilePath?: string
+
+  /**
+   * Filesystem path for the append-only lifecycle ledger
+   * (`<event> per line`, used to reconstruct active goals if the main
+   * state file is missing or corrupted).
+   * @default "<stateFilePath>.ledger.jsonl"
+   */
+  ledgerFilePath?: string
+
+  /**
+   * How long, in milliseconds, a completed goal's summary remains
+   * available through `/goal status` after the goal leaves active memory.
+   * @default 604800000
+   */
+  resultRetentionMs?: number
+
+  /**
+   * Maximum number of completed-goal summaries retained in process memory
+   * before the oldest ones are evicted.
+   * @default 200
+   */
+  maxStoredResults?: number
+
+  /**
+   * The slash command the plugin owns. Set to e.g. `"objective"` to drive
+   * the workflow with `/objective` instead of `/goal`; a leading slash is
+   * tolerated and stripped. Remember to register the matching command
+   * name in your OpenCode `command` config.
+   * @default "goal"
+   */
+  commandName?: string
+
+  /**
+   * Whether the plugin installs its `command.execute.before` hook at all.
+   * Set to `false` if you only want the auto-continue/persistence
+   * behavior driven programmatically (e.g. via {@link registerTools})
+   * and don't want the plugin to own a slash command.
+   * @default true
+   */
+  registerCommand?: boolean
+
+  /**
+   * Whether the plugin registers the agent-facing goal tools
+   * (`get_goal`, `get_goal_history`, `set_goal`, `update_goal`,
+   * `clear_goal`). Requires the optional `@opencode-ai/plugin` peer
+   * dependency; when it is absent, tool registration is silently skipped
+   * and the command/event hooks still work.
+   * @default true
+   */
+  registerTools?: boolean
+
+  /**
+   * Enables the built-in child-session completion auditor: before a
+   * `[goal:complete]` is archived, the plugin spawns an independent
+   * OpenCode session to verify the completion against the goal and
+   * workspace. Ignored if {@link auditor} is also set (the custom
+   * auditor takes precedence). Tune the built-in auditor with
+   * {@link auditorOptions}.
+   * @default false
+   */
+  completionAudit?: boolean
+
+  /**
+   * Supply a custom completion auditor instead of the built-in
+   * child-session one. Takes precedence over `completionAudit: true`.
+   * A verdict of `{ approved: false }` pauses the goal (stop reason
+   * `"audit rejected"`) instead of archiving it. A thrown error is
+   * treated as a rejection (fail closed).
+   */
+  auditor?: (context: CompletionAuditContext) => Promise<CompletionAuditVerdict>
+
+  /**
+   * Tuning options for the built-in child-session auditor. Ignored when
+   * a custom {@link auditor} is supplied.
+   */
+  auditorOptions?: CompletionAuditorOptions
+
+  /**
+   * Whether the plugin announces completion/blocked audits (an
+   * audit-start and an audit-result message) instead of running silently.
+   * @default true
+   */
+  auditMessages?: boolean
+
+  /**
+   * Custom sink for audit announcements. Defaults to routing through
+   * OpenCode's structured log (`client.app.log`). Provide this to route
+   * audit messages elsewhere, e.g. into the live conversation.
+   */
+  auditMessenger?: (sessionID: string, text: string) => Promise<void>
+}
+
+/**
+ * OpenCode plugin hook map returned by the plugin's `server` factory.
+ * Matches OpenCode's plugin hook contract; kept loose (`unknown`
+ * input/output) since hook payload shapes are defined by OpenCode itself,
+ * not by this package.
+ */
+export interface GoalPluginHooks {
+  /** Omitted entirely when {@link GoalPluginOptions.registerCommand} is `false`. */
+  "command.execute.before"?: (input: unknown, output: unknown) => Promise<void>
+  event: (input: unknown) => Promise<void>
+  "experimental.chat.system.transform": (input: unknown, output: unknown) => Promise<void>
+  "experimental.compaction.autocontinue": (input: unknown, output: unknown) => Promise<void>
+  /**
+   * Agent-facing tool definitions, present only when
+   * {@link GoalPluginOptions.registerTools} is enabled (default) and the
+   * optional `@opencode-ai/plugin` peer dependency is installed.
+   */
+  tool?: Record<string, unknown>
+  [hook: string]: unknown
+}
+
+/**
+ * The plugin's `server` factory. OpenCode calls this with a client bound
+ * to the running session and the resolved plugin options from
+ * `opencode.json`.
+ */
+export function GoalPlugin(
+  context: { client: unknown },
+  options?: GoalPluginOptions,
+): Promise<GoalPluginHooks>
+
+/**
+ * Default export consumed by OpenCode's plugin loader:
+ * `{ "opencode-goal-plugin": { ... } }` in `opencode.json` resolves `id`
+ * and calls `server` to obtain the plugin's hooks.
+ */
+declare const goalPlugin: {
+  id: "opencode-goal-plugin"
+  server: typeof GoalPlugin
+}
+
+export default goalPlugin

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Session-scoped /goal workflow for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",
+  "types": "./index.d.ts",
   "exports": {
     ".": "./src/goal-plugin.js",
     "./server": "./src/goal-plugin.js"
   },
+  "bin": {
+    "opencode-goal-plugin": "./scripts/verify.mjs"
+  },
   "files": [
     "src",
     "scripts",
     "examples",
+    "index.d.ts",
     "README.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
@@ -20,9 +25,10 @@
     ".nvmrc"
   ],
   "scripts": {
-    "test": "node --test",
-    "test:coverage": "node --test --experimental-test-coverage",
+    "test": "node --test test/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage test/*.test.js",
     "smoke": "node scripts/smoke-command-hook.mjs",
+    "verify": "node scripts/verify.mjs",
     "check": "node -c src/goal-plugin.js && npm test",
     "pack:check": "npm pack --dry-run"
   },