opencode-goal-plugin 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.6.3 — 2026-07-11
+
+- Clarify the textual completion protocol so models keep evidence and completion on consecutive plain-text lines instead of wrapping markers in Markdown or separating them with blank lines.
+
+## 0.6.2 — 2026-07-11
+
+- Keep paused, blocked, and crash-recovered goals inert in model turns with a stopped-goal system guard, and enforce status/history/list/pause/clear control turns as read-only through the host's tool-execution hook so routed command text cannot mutate or resurrect work.
+- Add installed-package TypeScript and full tool-surface contracts, critical mutation testing, generated lifecycle-model testing, Linux/macOS/Windows filesystem CI, CodeQL, dependency updates, and a verified release workflow.
+- Preserve multi-goal creation order when a paused goal resumes; execution epochs rotate through `runId` while the public `goalId` remains stable.
+- Document the supported compatibility surface, release integrity process, and private vulnerability reporting path.
+
 ## 0.6.1 — 2026-07-10
 
 - Default-deny verifier tools except read/glob/grep, and fail closed unless the owned verifier agent registers successfully.
@@ -9,7 +20,7 @@
 - Prevent mutating SDK shape retries, validate child-session ancestry, and make auditor timeout independent of a hanging abort.
 - Move context-budget reset to the successful `session.compacted` event and prevent ordered goals from reusing a prior goal's completion message.
 - Drain accepted persistence writes before disposal, suppress late disposed-instance writes, and re-check goal identity after asynchronous audits/announcements.
-- Harden persistence recovery with bounded hostile-state parsing, cross-session-safe ledger identities, multi-goal snapshots, archive restoration, corrupt-state quarantine, stale malformed-lock recovery, symlink-safe ledger appends, and exclusive one-project legacy migration with preserved backups.
+- Improve persistence recovery with bounded hostile-state parsing, cross-session-safe ledger identities, multi-goal snapshots, archive restoration, corrupt-state quarantine, stale malformed-lock recovery, symlink-safe ledger appends, and exclusive one-project legacy migration with preserved backups.
 - Fail closed when neither terminal state nor ledger can be persisted; keep the goal paused instead of claiming archival.
 - Preserve paused time for queued/backgrounded goals, expose an opt-out for the tool-free heuristic, honor host `tokens.total`, and improve multi-step usage/cost availability accounting.
 - Add conditional TypeScript export mappings, an OpenCode engine range, honest auditor/visibility documentation, and cache-safe near-limit continuation warnings.
@@ -122,7 +133,7 @@
 
 ## 0.4.0 — 2026-06-21
 
-- **Expose agent-facing goal tools (`get_goal`, `get_goal_history`, `set_goal`, `update_goal`, `clear_goal`)** when the host provides `@opencode-ai/plugin` (a new *optional* peer dependency, loaded via a cached dynamic import so the zero-runtime-dependency posture is preserved). `set_goal` is constrained by its description to explicit user requests (so the agent does not set goals on its own); it accepts optional `maxTurns` / `maxTokens` / `maxDurationMs` overrides plus `successCriteria` / `constraints` / `mode`. `update_goal` supports objective edits and `complete` / `blocked` / `paused` / `resumed` transitions (with `evidence` / `blocker`). Tools create, replace, and clear goals through the **multi-goal registry** (the same `buildGoalState` → `registerSessionGoal` → `focusGoal` path the `/goal` command uses), so tool-created goals persist, appear in `/goal list`, and are driven by the idle handler; `complete` archives with evidence and auto-promotes the next goal in an ordered (sisyphus) sequence. Registration is skipped gracefully when the package is absent or with `registerTools: false`. New `buildAgentToolHandlers` / `buildAgentTools` / `agentToolSessionID` helpers. Implements megalist items 7.1 and 7.2. _(This is the work the 0.3.0 changelog mistakenly listed as already shipped; it is now actually implemented and adapted to the current multi-goal architecture.)_
+- **Expose agent-facing goal tools (`get_goal`, `get_goal_history`, `set_goal`, `update_goal`, `clear_goal`)** when the host provides `@opencode-ai/plugin` (a new *optional* peer dependency, loaded via a cached dynamic import so the zero-runtime-dependency posture is preserved). `set_goal` is constrained by its description to explicit user requests (so the agent does not set goals on its own); it accepts optional `maxTurns` / `maxTokens` / `maxDurationMs` overrides plus `successCriteria` / `constraints` / `mode`. `update_goal` supports objective edits and `complete` / `blocked` / `paused` / `resumed` transitions (with `evidence` / `blocker`). Tools create, replace, and clear goals through the **multi-goal registry** (the same `buildGoalState` → `registerSessionGoal` → `focusGoal` path the `/goal` command uses), so tool-created goals persist, appear in `/goal list`, and are driven by the idle handler; `complete` archives with evidence and auto-promotes the next goal in an ordered (sisyphus) sequence. Registration is skipped gracefully when the package is absent or with `registerTools: false`. New `buildAgentToolHandlers` / `buildAgentTools` / `agentToolSessionID` helpers. _(This is the work the 0.3.0 changelog mistakenly listed as already shipped; it is now actually implemented and adapted to the current multi-goal architecture.)_
 - **Fix a goal-registry leak when resuming.** `resetGoalBudget` rotates a goal's `goalId`, but the multi-goal registry is keyed by `goalId`, so resuming and then clearing/replacing left a stale entry behind (visible in `/goal list` and persisted). Both the `/goal resume` command path and the agent `update_goal {status:"resumed"}` path now re-key the registry to the new id (the focused pointer holds the same object). Regression test added for the command path.
 
 ## 0.3.0 — 2026-06-14
@@ -131,35 +142,35 @@
 
 ### Completion integrity & audit
 
-- **Require evidence to complete a goal and a concrete blocker to block one.** A `[goal:complete]` marker is now only honored when the assistant also supplies a non-empty `[goal:evidence] <summary>` line (on or before the completion marker); a `[goal:blocked]` is only honored when a concrete blocker is stated on the line before it. An unsubstantiated `[goal:complete]` or `[goal:blocked]` is rejected (not recorded / does not stop the goal) and the plugin sends a corrective continuation prompt demanding the missing evidence or blocker. The accepted evidence is stored on the result and shown in `/goal status` / `/goal history`. New `extractCompletionEvidence` helper, an `<evidence_required>` structural tag (added to the injection-escaping set), and continuation/system/compaction/creation prompts all updated to instruct the evidence requirement. Implements megalist item 2.1.
-- **Add an optional separate completion auditor that verifies before archival.** When a completion auditor is configured, a `[goal:complete]` (with evidence) is verified before the goal is archived: on approval it archives as achieved, on rejection the goal is *restored* (paused with stop reason `audit rejected` and the reason surfaced) rather than archived. Enable the built-in auditor — which spawns an independent OpenCode child session that replies `[audit:approved]`/`[audit:rejected]` — with `completionAudit: true`, or supply a custom `auditor({ goal, sessionID, latestText }) => { approved, reason }` (takes precedence). The built-in child-session auditor fails open if the session API is unavailable; a custom auditor that throws is treated as a rejection (fail closed). New `parseAuditVerdict` / `buildAuditPrompt` / `createChildSessionAuditor` helpers. Off by default. Implements megalist item 2.2.
-- **Announce completion/blocker audits with visible messages instead of silent background work.** When the assistant marks a goal complete or blocked, the plugin emits an audit-start and an audit-result message (e.g. "Auditing goal completion…" → "Audit result: completion accepted — goal archived"). Delivery defaults to OpenCode's structured log (`client.app.log`) and is pluggable via an `auditMessenger(sessionID, text)` option or disable-able with `auditMessages: false`. New `defaultAuditMessenger` helper. Implements megalist item 2.4.
+- **Require evidence to complete a goal and a concrete blocker to block one.** A `[goal:complete]` marker is now only honored when the assistant also supplies a non-empty `[goal:evidence] <summary>` line (on or before the completion marker); a `[goal:blocked]` is only honored when a concrete blocker is stated on the line before it. An unsubstantiated `[goal:complete]` or `[goal:blocked]` is rejected (not recorded / does not stop the goal) and the plugin sends a corrective continuation prompt demanding the missing evidence or blocker. The accepted evidence is stored on the result and shown in `/goal status` / `/goal history`. New `extractCompletionEvidence` helper, an `<evidence_required>` structural tag (added to the injection-escaping set), and continuation/system/compaction/creation prompts all updated to instruct the evidence requirement.
+- **Add an optional separate completion auditor that verifies before archival.** When a completion auditor is configured, a `[goal:complete]` (with evidence) is verified before the goal is archived: on approval it archives as achieved, on rejection the goal is *restored* (paused with stop reason `audit rejected` and the reason surfaced) rather than archived. Enable the built-in auditor — which spawns an independent OpenCode child session that replies `[audit:approved]`/`[audit:rejected]` — with `completionAudit: true`, or supply a custom `auditor({ goal, sessionID, latestText }) => { approved, reason }` (takes precedence). In this release, the built-in child-session auditor approved when the session API was unavailable; later releases changed operational failures to reject by default. A custom auditor that throws is treated as a rejection. New `parseAuditVerdict` / `buildAuditPrompt` / `createChildSessionAuditor` helpers. Off by default.
+- **Announce completion/blocker audits with visible messages instead of silent background work.** When the assistant marks a goal complete or blocked, the plugin emits an audit-start and an audit-result message (e.g. "Auditing goal completion…" → "Audit result: completion accepted — goal archived"). Delivery defaults to OpenCode's structured log (`client.app.log`) and is pluggable via an `auditMessenger(sessionID, text)` option or disable-able with `auditMessages: false`. New `defaultAuditMessenger` helper.
 
 ### Durability
 
-- **Add an append-only JSONL lifecycle ledger with state reconstruction, and fail-closed terminal-state persistence.** Every lifecycle event (`pushHistory`) is also appended as one JSON line to `<stateFile>.ledger.jsonl` (synchronous, owner-only `0600`). Because in-memory history is capped, the ledger is the durable record: when the main state file is missing on startup, the plugin reconstructs still-active (non-`completed`/`cleared`) goals from the ledger and reloads them paused (new `reconstructed` load status). Terminal events are written to the ledger before the main state write, so a goal's terminal outcome survives a failed state write (fail-closed); `persistState` now returns success/failure and a failed terminal persist is logged at error level. Tied to `persistState`. New `appendLedgerLine` / `readLedgerEntries` / `reconstructGoalsFromLedger` helpers. Implements megalist items 2.3 and 2.5.
-- **Build the compaction summary deterministically from the persisted goal record.** `buildCompactionContext` folds in a reproducible progress summary — recent checkpoints and lifecycle events — derived from the goal's persisted `checkpoints`/`history` (new `buildCompactionProgressSummary` helper) rather than chat memory, and labels it as such. Implements megalist item 6.3.
+- **Add an append-only JSONL lifecycle ledger with state reconstruction, and fail-closed terminal-state persistence.** Every lifecycle event (`pushHistory`) is also appended as one JSON line to `<stateFile>.ledger.jsonl` (synchronous, owner-only `0600`). Because in-memory history is capped, the ledger is the durable record: when the main state file is missing on startup, the plugin reconstructs still-active (non-`completed`/`cleared`) goals from the ledger and reloads them paused (new `reconstructed` load status). Terminal events are written to the ledger before the main state write, so a goal's terminal outcome survives a failed state write (fail-closed); `persistState` now returns success/failure and a failed terminal persist is logged at error level. Tied to `persistState`. New `appendLedgerLine` / `readLedgerEntries` / `reconstructGoalsFromLedger` helpers.
+- **Build the compaction summary deterministically from the persisted goal record.** `buildCompactionContext` folds in a reproducible progress summary — recent checkpoints and lifecycle events — derived from the goal's persisted `checkpoints`/`history` (new `buildCompactionProgressSummary` helper) rather than chat memory, and labels it as such.
 
 ### Auto-continue guardrails
 
-- **Pause auto-continue on repeated tool-free continuation turns (no-tool-call gate).** Complementing the low-output no-progress check, the plugin tracks continuation turns whose assistant message has no tool calls (OpenCode `tool` / `subtask` parts) and, after `noToolCallTurnsBeforePause` consecutive such turns (default `2`), pauses with stop reason `no tool calls` to guard against self-chat loops. A tool-using turn resets the counter. Configurable via the `noToolCallTurnsBeforePause` option and `--no-tool-turns <n>` flag. New `messageHasToolCall` helper. Implements megalist item 5.1.
-- **Pause auto-continue when a real user message arrives ("latest instruction wins").** The idle handler detects a genuine human message that arrived after the plugin's most recent continuation and pauses the goal (stop reason `user intervention`) instead of talking over the user; `/goal resume` hands control back. Plugin-generated continuation prompts (user-role messages framed in `<goal_continuation>`) are ignored, and detection requires `turnCount > 0` plus a visible plugin continuation so the first idle and scrolled-out sessions are never misread. New `isPluginContinuationMessage` / `userInterventionDetected` helpers. Implements megalist items 5.2 and 5.3.
+- **Pause auto-continue on repeated tool-free continuation turns (no-tool-call gate).** Complementing the low-output no-progress check, the plugin tracks continuation turns whose assistant message has no tool calls (OpenCode `tool` / `subtask` parts) and, after `noToolCallTurnsBeforePause` consecutive such turns (default `2`), pauses with stop reason `no tool calls` to guard against self-chat loops. A tool-using turn resets the counter. Configurable via the `noToolCallTurnsBeforePause` option and `--no-tool-turns <n>` flag. New `messageHasToolCall` helper.
+- **Pause auto-continue when a real user message arrives ("latest instruction wins").** The idle handler detects a genuine human message that arrived after the plugin's most recent continuation and pauses the goal (stop reason `user intervention`) instead of talking over the user; `/goal resume` hands control back. Plugin-generated continuation prompts (user-role messages framed in `<goal_continuation>`) are ignored, and detection requires `turnCount > 0` plus a visible plugin continuation so the first idle and scrolled-out sessions are never misread. New `isPluginContinuationMessage` / `userInterventionDetected` helpers.
 
 ### Multiple goals
 
-- **Support multiple goals per session with `/goal add`, `/goal list`, and `/goal focus`.** A session can hold several live goals via a new `sessionGoals` registry; `goalStates` continues to track the single *focused* goal the idle handler drives. `/goal <condition>` replaces the focused goal; `/goal add <condition>` backgrounds the current goal and focuses a new one (only the focused goal auto-continues). `/goal list` shows numbered live goals plus a per-session archive of completed/cleared goals, and `/goal focus <number|id>` switches the active goal (numeric refs are index-only). Focus is tracked per session and persisted (state files gain a per-goal `focused` flag and an `archives` array; older single-goal files load with their goal focused). New `buildGoalState` / `formatGoalList` / session-registry helpers. Implements megalist items 3.1, 3.2, and 3.3.
-- **Add `/goal sisyphus` ordered goal sequences.** `/goal sisyphus <obj 1>; <obj 2>; …` sets up a strict execution sequence: the first objective is focused and the rest queued, and when the focused goal completes the plugin auto-promotes the next until the sequence is exhausted. The ordered flag is tracked per session, shown in `/goal list`, persisted (`orderedSessions`), and cleared by `/goal clear`. New `promoteNextOrderedGoal` helper. Implements megalist item 3.4.
+- **Support multiple goals per session with `/goal add`, `/goal list`, and `/goal focus`.** A session can hold several live goals via a new `sessionGoals` registry; `goalStates` continues to track the single *focused* goal the idle handler drives. `/goal <condition>` replaces the focused goal; `/goal add <condition>` backgrounds the current goal and focuses a new one (only the focused goal auto-continues). `/goal list` shows numbered live goals plus a per-session archive of completed/cleared goals, and `/goal focus <number|id>` switches the active goal (numeric refs are index-only). Focus is tracked per session and persisted (state files gain a per-goal `focused` flag and an `archives` array; older single-goal files load with their goal focused). New `buildGoalState` / `formatGoalList` / session-registry helpers.
+- **Add `/goal sisyphus` ordered goal sequences.** `/goal sisyphus <obj 1>; <obj 2>; …` sets up a strict execution sequence: the first objective is focused and the rest queued, and when the focused goal completes the plugin auto-promotes the next until the sequence is exhausted. The ordered flag is tracked per session, shown in `/goal list`, persisted (`orderedSessions`), and cleared by `/goal clear`. New `promoteNextOrderedGoal` helper.
 
 ### Schema & command UX
 
-- **Add success-criteria, constraints/non-goals, and mode to the goal schema.** A goal can carry `successCriteria` (`--success`), `constraints` (`--constraints` / `--non-goals`), and a `mode` of `normal` or `ordered` (`--mode`, `sisyphus` alias). These thread through state, persistence, the injected goal block (escaped, new `success_criteria` / `constraints` structural tags), creation output, and `/goal status`. New `normalizeMode` helper. Implements megalist items 4.1, 4.2, and 4.3.
-- **Add an inline `--budget <n>` flag** on the create command — a shorthand for the context-token limit accepting a plain integer or `k`/`m` suffix (e.g. `--budget 100k`). New `parseTokenBudget` helper. Implements megalist item 8.1.
-- **Make the slash command configurable (`commandName`) and optional (`registerCommand`).** `commandName` (default `goal`, leading slash tolerated) lets the plugin own e.g. `/objective`, with all user-facing hints following the configured name; `registerCommand: false` skips installing the command hook entirely. New `normalizeCommandOptions` helper. Implements megalist item 8.2.
+- **Add success-criteria, constraints/non-goals, and mode to the goal schema.** A goal can carry `successCriteria` (`--success`), `constraints` (`--constraints` / `--non-goals`), and a `mode` of `normal` or `ordered` (`--mode`, `sisyphus` alias). These thread through state, persistence, the injected goal block (escaped, new `success_criteria` / `constraints` structural tags), creation output, and `/goal status`. New `normalizeMode` helper.
+- **Add an inline `--budget <n>` flag** on the create command — a shorthand for the context-token limit accepting a plain integer or `k`/`m` suffix (e.g. `--budget 100k`). New `parseTokenBudget` helper.
+- **Make the slash command configurable (`commandName`) and optional (`registerCommand`).** `commandName` (default `goal`, leading slash tolerated) lets the plugin own e.g. `/objective`, with all user-facing hints following the configured name; `registerCommand: false` skips installing the command hook entirely. New `normalizeCommandOptions` helper.
 
 ### Storage, tools & packaging
 
-- **Default goal state to a project-local path, with an env override and migration fallbacks.** State resolves as `stateFilePath` option → `OPENCODE_GOAL_STATE_PATH` env var → project-local `<cwd>/.opencode/goals/state.json` (previously `~/.opencode-goal-plugin/state.json`). When the default path is empty, the plugin migrates forward on first load from the legacy home path and the XDG path, then writes project-local. Explicit option/env paths are literal with no fallback; a present-but-corrupt primary is preserved. New `resolveStateFilePath` / `xdgStateFilePath` / `legacyStateFilePaths` helpers. Home-based fallback paths resolve from an injectable `env.HOME` (falling back to `os.homedir()`), making path resolution deterministic across platforms — `os.homedir()` ignores `$HOME` on macOS. Implements megalist items 6.1 and 6.2.
-- _**Correction (2026-06-21):** an earlier version of this entry claimed agent-facing goal tools shipped in 0.3.0. They did not — the work was on an unmerged branch (`wr/agent-tools`) and was never included in the 0.3.0 release. The feature now actually ships; see the **0.6.0** section above. Megalist items 7.1 and 7.2._
+- **Default goal state to a project-local path, with an env override and migration fallbacks.** State resolves as `stateFilePath` option → `OPENCODE_GOAL_STATE_PATH` env var → project-local `<cwd>/.opencode/goals/state.json` (previously `~/.opencode-goal-plugin/state.json`). When the default path is empty, the plugin migrates forward on first load from the legacy home path and the XDG path, then writes project-local. Explicit option/env paths are literal with no fallback; a present-but-corrupt primary is preserved. New `resolveStateFilePath` / `xdgStateFilePath` / `legacyStateFilePaths` helpers. Home-based fallback paths resolve from an injectable `env.HOME` (falling back to `os.homedir()`), making path resolution deterministic across platforms — `os.homedir()` ignores `$HOME` on macOS.
+- _**Correction (2026-06-21):** an earlier version of this entry claimed agent-facing goal tools shipped in 0.3.0. They did not — the work was on an unmerged branch (`wr/agent-tools`) and was never included in the 0.3.0 release. The feature now ships; see the **0.4.0** section above._
 - **Release automation note.** Development included a proposed npm Trusted Publishing workflow, but `.github/workflows/publish.yml` was not part of the final release history and is not present in the current repository. Releases therefore remain manual unless a separately reviewed publishing workflow is added. No package is published solely by the CI workflow documented in this repository.
 
 ## 0.2.0 — 2026-06-14

package/CONTRIBUTING.md

@@ -15,8 +15,11 @@ Run the local checks before submitting changes:
 ```sh
 npm test
 npm run test:coverage
+npm run type:check
+npm run test:mutation
 npm run smoke
 npm run smoke:packed-host
+npm run smoke:packed-tools
 npm run benchmark:behavior
 npm run verify
 npm run check
@@ -30,25 +33,19 @@ For behavior changes, add or update tests in `test/goal-plugin.test.js`.
 This plugin depends on OpenCode plugin hooks, including experimental hooks. When changing hook usage, command behavior, or system-prompt transforms:
 
 1. Check the current OpenCode plugin and command documentation.
-2. Run `npm run smoke` and `npm run smoke:packed-host` to verify the source and installed-tarball host contracts.
+2. Run `npm run smoke`, `npm run smoke:packed-host`, `npm run smoke:packed-tools`, and `npm run type:check` to verify the source and installed-tarball contracts.
 3. Test against a real OpenCode install when possible.
 4. Update the README compatibility snapshot if the tested surface changes.
 
-`npm run smoke` verifies the package export path and `/goal` command hook without invoking a model. `npm run smoke:packed-host` installs the packed artifact in an isolated directory and checks the public hook/tool contract. `npm run benchmark:behavior` covers deterministic autonomy and token-efficiency scenarios. None replaces a real OpenCode smoke test after hook, SDK, or command behavior changes.
+`npm run smoke` verifies the package export path and `/goal` command hook without invoking a model. The packed-host and packed-tool checks install the npm artifact in isolated consumer projects and verify the public hook and complete optional-peer tool contracts. `npm run type:check` compiles installed-package consumers with NodeNext and Bundler resolution. `npm run benchmark:behavior` covers deterministic autonomy and token-efficiency scenarios. None replaces a real OpenCode smoke test after hook, SDK, or command behavior changes.
 
 ## Release checklist
 
-Before publishing or tagging a release:
-
-- update `CHANGELOG.md`
-- run `npm test`
-- run `npm run test:coverage`
-- run `npm run smoke`
-- run `npm run smoke:packed-host`
-- run `npm run benchmark:behavior`
-- run `npm run verify`
-- run `npm run check`
-- run `npm run pack:check`
+Before publishing or tagging a release, follow [the release process](docs/releasing.md). The required automated gate is:
+
+- run `npm ci`
+- update `CHANGELOG.md` and both package-version files
+- run `npm run release:check`
 - perform at least one manual OpenCode smoke test if hook behavior changed
 - refresh compatibility notes if the tested OpenCode surface changed
 

package/README.md

@@ -3,10 +3,10 @@
 [![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-passing-brightgreen)](test/)
+[![CodeQL](https://github.com/willytop8/OpenCode-goal-plugin/actions/workflows/codeql.yml/badge.svg)](https://github.com/willytop8/OpenCode-goal-plugin/actions/workflows/codeql.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-An experimental session-scoped `/goal` command for [OpenCode](https://opencode.ai/).
+A session-scoped `/goal` workflow 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.
 
@@ -27,9 +27,13 @@ This project is independently implemented for OpenCode. Product names used elsew
 | Surface | Status |
 |---|---|
 | 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 |
+| Operating systems | Filesystem-sensitive lifecycle tests run on Linux, macOS, and Windows |
+| Package entrypoint | Installed-tarball contracts verify both export paths, consumer TypeScript resolution, hooks, and all 11 tools |
 | Provider/backend quirks | Strict-template backends require the goal block to merge into the primary `system` message; covered by regression tests |
 
+See the [compatibility policy](docs/compatibility.md) for the supported public
+surface and versioning expectations.
+
 ### 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:
@@ -380,7 +384,7 @@ The goal text is wrapped in `<goal_objective>` tags and labeled as user-provided
 
 The assistant still signals candidate outcomes with `[goal:complete]` or `[goal:blocked]`. Completion can additionally be checked by a custom `auditor` callback or the built-in child-session auditor before the goal becomes terminal. Marker quality therefore remains model-dependent when auditing is disabled, and audit quality depends on the configured verifier model and evidence available in the session. The built-in verifier performs static inspection with `read`, `glob`, and `grep`; it cannot execute shell commands.
 
-OpenCode's current `command.execute.before` hook does not fully intercept command text. The plugin can update in-memory goal state as a side effect, but the goal text may still be routed into the normal assistant conversation alongside the state update.
+OpenCode's current `command.execute.before` hook does not fully intercept command text. The plugin can update in-memory goal state as a side effect, but the goal text may still be routed into the normal assistant conversation alongside the state update. The plugin therefore guards `/goal status`, `/goal history`, `/goal list`, `/goal pause`, and `/goal clear` (including its aliases) with `tool.execute.before`: inspection tools remain available, while mutation-capable tools are rejected for that routed command turn. Paused goals also inject a system guard that omits the objective and requires an explicit resume before goal work continues.
 
 The plugin depends on `experimental.chat.system.transform` and other OpenCode plugin hooks that may change between OpenCode versions.
 
@@ -396,7 +400,7 @@ If a goal does not continue:
 2. Run `/goal resume` only after resolving the reported reason. Resume creates a fresh local budget window; it does not erase the objective or history.
 3. Check OpenCode's structured logs for persistence, SDK-shape, prompt, or auditor errors.
 4. Confirm the configured project directory and state-path precedence described under [Safety limits](#safety-limits). A daemon started elsewhere can otherwise make a manually configured relative path surprising.
-5. Run `npm run verify`, `npm run smoke`, and `npm run smoke:packed-host` against the installed source when diagnosing registration or packaging problems. `npm run benchmark:behavior` exercises completion, false-completion, loop, interruption, compaction, and restart behavior without a provider call.
+5. Run `npm run verify`, `npm run smoke`, and `npm run smoke:packed-host` against the installed source when diagnosing registration or packaging problems. Maintainers can run `npm run release:check` for the complete artifact and quality gate. `npm run benchmark:behavior` exercises completion, false-completion, loop, interruption, compaction, and restart behavior without a provider call.
 
 Do not paste `state.json`, its ledger, or verbose logs into a public issue without reviewing them first: they can contain goal text, assistant checkpoints, blockers, local paths, and command evidence. Prefer the bounded status/history output and redact project-specific content. There is intentionally no broad "dump diagnostics" tool: exposing process-wide session state or persistence paths to the model would add more privacy risk than troubleshooting value.
 
@@ -427,12 +431,16 @@ Keep test files outside OpenCode's auto-loaded plugin directory — OpenCode wil
 ```sh
 npm test                # run the test suite
 npm run test:coverage   # run tests with coverage
+npm run type:check      # compile installed-package consumers
+npm run test:mutation   # prove critical regressions are detected
 npm run smoke           # verify package export + command hook without a model call
 npm run smoke:packed-host # install the packed tarball and exercise the host contract
+npm run smoke:packed-tools # verify all tools from an installed tarball
 npm run benchmark:behavior # deterministic autonomy + token-efficiency scenarios
 npm run verify          # verify the installed plugin hook surface
 npm run check           # syntax check + tests
 npm run pack:check      # verify package contents before publishing
+npm run release:check   # run the complete release gate
 ```
 
 ## License

package/SECURITY.md

@@ -2,18 +2,16 @@
 
 ## Supported Versions
 
-This project is experimental. Security fixes are provided for the latest published version only.
+Security fixes are provided for the latest published version only. Users should
+upgrade to the newest patch release before reporting a vulnerability.
 
 ## Reporting a Vulnerability
 
-GitHub private vulnerability reporting may not always be enabled for this repository.
-
-Until a dedicated private reporting channel is documented here, do **not** open a public issue with exploit details, credentials, local paths, or reproduction steps that could expose user data or local system access.
-
-Instead:
-
-1. open a minimal public issue asking for a private contact path, or
-2. contact the maintainer through their GitHub profile and request a private handoff.
+Use [GitHub's private vulnerability report](https://github.com/willytop8/OpenCode-goal-plugin/security/advisories/new).
+Do **not** open a public issue with exploit details, credentials, local paths, or
+reproduction steps that could expose user data or local system access. If private
+reporting is temporarily unavailable, contact the maintainer through their GitHub
+profile and request a private handoff.
 
 ## Scope
 

package/docs/compatibility.md

@@ -0,0 +1,41 @@
+# Compatibility policy
+
+## Supported package surface
+
+The latest published release is the supported line. Public compatibility covers:
+
+- the package root and `opencode-goal-plugin/server` ESM exports
+- the declarations exported by `index.d.ts`
+- the documented `GoalPluginOptions` fields
+- the documented OpenCode hook names
+- the six canonical goal tools and five legacy tool aliases
+- persisted-state recovery from versions documented in the changelog
+
+The package requires Node.js 18 or newer and OpenCode 1.17.15 through the latest
+compatible 1.x release. CI runs the complete unit suite on Node 18, 20, 22, and
+24. Installed-package contracts compile TypeScript consumers using both NodeNext
+and Bundler resolution and load the npm tarball with and without the optional
+`@opencode-ai/plugin` peer.
+
+Filesystem-sensitive lifecycle tests run on Linux, macOS, and Windows. POSIX file
+mode and symbolic-link protections are applied where the operating system supports
+them; the plugin does not claim that Windows provides equivalent POSIX semantics.
+
+## OpenCode host compatibility
+
+OpenCode's experimental hooks and SDK request shapes may change within the 1.x
+line. Automated tests cover both current flattened session inputs and the legacy
+generated-client shape, but a real-host smoke test remains required when hook or
+SDK behavior changes. The current manual provider matrix is maintained in
+[providers.md](providers.md).
+
+## Versioning
+
+Semantic-versioning intent is:
+
+- patch: compatible fixes, documentation, and stronger verification
+- minor: backward-compatible options, hooks, commands, or tools
+- major: removal or incompatible change to a documented public surface
+
+`testInternals` is exported for diagnostics and the project's own tests; it is not
+part of the semantic-version compatibility guarantee.

package/docs/providers.md

@@ -20,9 +20,9 @@ vary by provider and model:
    See the [OpenCode version compatibility table](../README.md#opencode-version-compatibility)
    in the README for the current findings.
 
-All rows below were verified manually against the real OpenCode TUI (`tmux`
-+ live provider credentials, no mocks) on OpenCode 1.17.15, driving the
-plugin through `/goal status`, `/goal <condition> --max-turns N`, and
+All rows below were verified against real OpenCode processes with live
+provider credentials and no mocked plugin hooks on OpenCode 1.17.15, driving
+the plugin through `/goal status`, `/goal <condition> --max-turns N`, and
 inspecting the plugin's persisted state file to confirm state mutations
 (limit parsing, turn/stop accounting, evidence-gated completion detection)
 independent of what was rendered in the terminal.
@@ -31,10 +31,29 @@ independent of what was rendered in the terminal.
 
 | Provider | Model | Marker compliance | Notes |
 |---|---|---|---|
+| `opencode` | `deepseek-v4-flash-free` | ✅ Canonical tools | OpenCode 1.17.15, isolated HOME/XDG/project, loading the exact 0.6.2 branch source by file URL. In a real interactive PTY, the model fixed an intentionally failing two-test project, ran the tests to 2/2 passing, and completed through `goal_complete`. A second goal checkpointed after writing `step-1`; the plugin ledger then recorded `auto-continue 1/2`, after which the model wrote and verified `step-2` and completed. Sessions: `ses_0b021d93affeCsNvWkmJWwZzF2` and `ses_0b01f3767ffej4Mn6DMSWft0aX`. `/goal status` text was routed to the model by this host version, which then called `goal_status`; the persisted ledger remained authoritative. |
 | `opencode-go` | `qwen3.7-plus` | ✅ Self-corrects | First attempt emitted bare `[goal:complete]` with no evidence line and was correctly rejected by the plugin. On the very next turn it read the `<evidence_required>` re-prompt, added a `[goal:evidence]` line, and completed cleanly — a good demonstration of the evidence gate actually improving behavior rather than just failing closed. |
 | `opencode-go` | `glm-5.2` | ✅ Clean | Emitted a correct `[goal:evidence] ... [goal:complete]` pair on the first attempt. (An earlier plugin version without the evidence requirement showed GLM-5.2 sometimes trailing extra text after a bare marker — the more structured `<completion_audit>` prompt this plugin version sends appears to help.) |
 | `deepseek` | `deepseek-chat` | ✅ Clean | Emitted a correct `[goal:evidence] ... [goal:complete]` pair on the first attempt, both in a short synthetic goal and in the full [demo](../demo/) (autonomously located and fixed a real bug, then reported evidence-backed completion). Correctly parses per-goal flags (`--max-turns`, etc.) out of the condition text. |
 
+## OpenCode 1.17.15 lifecycle canaries
+
+The `opencode/deepseek-v4-flash-free` row was also exercised through an
+isolated project, HOME, and XDG directories while loading the exact 0.6.2
+source by `file://` URL. Persisted state, ledger entries, and file contents
+were checked independently of the model's prose.
+
+| Scenario | Result | Evidence |
+|---|---|---|
+| Normal completion | ✅ Pass | `ses_0b021d93affeCsNvWkmJWwZzF2`: fixed an intentionally failing project, reran 2/2 tests, and completed with structured evidence. |
+| Idle auto-continuation | ✅ Pass | `ses_0b01f3767ffej4Mn6DMSWft0aX`: checkpointed `step-1`, ledger recorded auto-continue 1/2, then verified `step-2` and completed. |
+| Pause and explicit resume across processes | ✅ Pass | `ses_0b01470c1ffeug0LX69fageiVm`: remained paused between OpenCode invocations; explicit resume released it and completion was archived. |
+| Concrete blocker and restart | ✅ Pass | `ses_0b013a903ffeg3I6tGbArE2b5E`: stopped with the missing approval-file reason and did not auto-continue after a fresh process loaded it. |
+| Hard process interruption and recovery | ✅ Pass | `ses_0b00b37a8ffeDrBshGDutFTqUm`: a running process was terminated during a shell wait; restart recovered paused, status blocked a stale `goal_resume`, the file stayed unchanged, and a later explicit resume completed. |
+| Real host compaction | ✅ Pass | `ses_0b00958e3ffekLLH5ztkkvHIPL`: the documented session summarize endpoint returned `true`; exported session data contained a real compaction part plus injected goal/checkpoint context, token accounting reset, and the paused goal resumed cleanly. |
+| Clear with stale conversation history | ✅ Pass | `ses_0affb9235ffeWl5LuZxXmvhSfM`: after command-side clearing, the routed model turn attempted `clear_goal` and `goal_resume`; the tool hook rejected all attempts, the file remained `before-clear`, and no goal survived in state. |
+| Interactive Esc during a running shell tool | ⚠️ Not established | Esc sent through the automated PTY did not interrupt OpenCode's shell tool. Hard-process recovery is verified above and host-abort hooks have deterministic tests, but this specific TUI input path is not claimed as passed. |
+
 Untested at time of writing: `deepseek-reasoner`, `mistral/*`, `openrouter/*`,
 and any `nvidia`/`google` provider — add rows here as they're verified. See
 [Testing a new model](#testing-a-new-model) below.

package/docs/releasing.md

@@ -0,0 +1,41 @@
+# Release process
+
+Releases are deliberately verified before they are published. GitHub Actions does
+not publish to npm automatically; the maintainer reviews and publishes the exact
+artifact after all checks pass.
+
+## Prepare
+
+1. Start from a clean branch based on `main`.
+2. Update the version in `package.json` and `package-lock.json` together.
+3. Move relevant entries from `Unreleased` into a dated changelog section.
+4. Run `npm ci` followed by `npm run release:check`.
+5. Inspect `npm pack --json` and the generated tarball before publishing.
+
+`release:check` runs the unit and coverage suites, consumer type compilation,
+critical mutation contract, behavior benchmark, source and installed-artifact
+smoke tests, full optional-peer tool registration, and package-content check.
+
+## Publish
+
+After the commit is reviewed and CI is green, create and push an annotated
+`vX.Y.Z` tag at the same commit. The release workflow rejects a tag whose version
+does not match `package.json`, reruns the complete release gate, and retains the
+verified npm tarball as a workflow artifact.
+
+Download that artifact, inspect it, and publish the tarball itself:
+
+```sh
+npm publish opencode-goal-plugin-X.Y.Z.tgz --access public
+```
+
+Confirm the registry digest and unpacked contents match the locally reviewed
+artifact before drafting the GitHub release notes. Never rebuild or edit an
+artifact after it has been published; prepare a new patch release instead.
+
+## Trusted publishing
+
+For a future fully automated publish, configure npm Trusted Publishing for this
+repository and a narrowly scoped GitHub Actions workflow, keep `id-token: write`
+only on the publish job, require the release environment, and publish with
+provenance. Do not add a long-lived npm token to repository secrets.

package/index.d.ts

@@ -17,10 +17,58 @@ export interface CompletionAuditVerdict {
   reason?: string
 }
 
+/** A timestamped lifecycle entry retained with an active or archived goal. */
+export interface GoalHistoryEntry {
+  type: string
+  detail: string
+  timestamp: number
+}
+
+/** A bounded progress checkpoint retained with a goal. */
+export interface GoalCheckpoint {
+  summary: string
+  timestamp: number
+}
+
+/** Normalized token and cost usage accumulated for the current goal run. */
+export interface GoalUsage {
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+  cost: number
+  costKnown: boolean
+}
+
+/** Read-only goal snapshot passed to custom completion auditors. */
+export interface GoalAuditSnapshot {
+  goalId: string
+  runId: string
+  condition: string
+  successCriteria: string
+  constraints: string
+  mode: "normal" | "sisyphus"
+  sessionID: string
+  turnCount: number
+  startedAt: number
+  pausedAt: number
+  totalTokens: number
+  usage: Readonly<GoalUsage>
+  options: Readonly<GoalPluginOptions>
+  lastStatus: string
+  blockedReason: string
+  stopped: boolean
+  stopReason: string
+  history: readonly Readonly<GoalHistoryEntry>[]
+  checkpoints: readonly Readonly<GoalCheckpoint>[]
+  lastCheckpoint: Readonly<GoalCheckpoint> | null
+}
+
 /** Arguments passed to a custom {@link GoalPluginOptions.auditor} function. */
 export interface CompletionAuditContext {
   /** The goal being audited (objective, budget usage, checkpoints, etc.). */
-  goal: unknown
+  goal: Readonly<GoalAuditSnapshot>
   /** The OpenCode session ID the goal belongs to. */
   sessionID: string
   /** The assistant's latest response text, containing the `[goal:evidence]`/`[goal:complete]` claim. */
@@ -283,10 +331,10 @@ export interface GoalPluginOptions {
 
   /**
    * 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.
+   * OpenCode's structured log (`client.app.log`) and TUI toast when those
+   * host APIs are available. Provide this to route audit messages elsewhere.
    */
-  auditMessenger?: (sessionID: string, text: string) => Promise<void>
+  auditMessenger?: (sessionID: string, text: string) => Promise<void> | void
 }
 
 /**
@@ -300,6 +348,8 @@ export interface GoalPluginHooks {
   config: (config: unknown) => Promise<void>
   /** Omitted entirely when {@link GoalPluginOptions.registerCommand} is `false`. */
   "command.execute.before"?: (input: unknown, output: unknown) => Promise<void>
+  /** Enforces read-only tool behavior when inspection, pause, or clear command text is routed to the model. */
+  "tool.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>
@@ -312,7 +362,6 @@ export interface GoalPluginHooks {
   tool?: Record<string, unknown>
   /** Cancels pending continuation work and releases this plugin instance. */
   dispose: () => Promise<void>
-  [hook: string]: unknown
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Durable, guarded goal workflows for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",
@@ -22,7 +22,7 @@
   },
   "files": [
     "src",
-    "scripts",
+    "scripts/verify.mjs",
     "examples",
     "demo",
     "docs",
@@ -36,13 +36,18 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
+    "test:model": "node --test test/lifecycle-model.test.js",
+    "test:mutation": "node scripts/mutation-contract.mjs",
     "test:coverage": "node --test --experimental-test-coverage test/*.test.js",
+    "type:check": "node scripts/type-contract.mjs",
     "smoke": "node scripts/smoke-command-hook.mjs",
     "smoke:packed-host": "node scripts/packed-host-contract.mjs",
+    "smoke:packed-tools": "node scripts/packed-tool-contract.mjs",
     "benchmark:behavior": "node scripts/behavior-benchmark.mjs",
     "verify": "node scripts/verify.mjs",
     "check": "node -c src/goal-plugin.js && npm test",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "release:check": "npm run check && npm run test:coverage && npm run type:check && npm run test:mutation && npm run benchmark:behavior && npm run smoke && npm run smoke:packed-host && npm run smoke:packed-tools && npm run verify && npm audit --omit=dev --audit-level=high && npm run pack:check"
   },
   "keywords": [
     "opencode",
@@ -73,5 +78,9 @@
   "homepage": "https://github.com/willytop8/OpenCode-goal-plugin#readme",
   "author": {
     "name": "willytop8"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.17.18",
+    "typescript": "5.9.3"
   }
 }

package/scripts/verify.mjs

@@ -9,6 +9,7 @@ import assert from "node:assert/strict"
 const REQUIRED_HOOKS = [
   "config",
   "command.execute.before",
+  "tool.execute.before",
   "event",
   "experimental.chat.system.transform",
   "experimental.compaction.autocontinue",