EremesNG · EremesNG · Aug 2, 2026 · Aug 2, 2026
diff --git a/README.md b/README.md
@@ -56,6 +56,11 @@ npx thoth-agents@latest install --agent=opencode --dry-run
 npx thoth-agents@latest install --agent=opencode
 ```
 
+Here, `@latest` selects which CLI release runs. That CLI writes the exact
+executing release to OpenCode configuration, for example
+`plugin: ["thoth-agents@0.4.8"]`; it never writes a `latest` plugin entry or
+falls back to one when package identity cannot be verified.
+
 Restart OpenCode and initialize the current repository:
 
 ```text
@@ -393,9 +398,31 @@ npx thoth-agents@latest list
 npx thoth-agents@latest install --agent=opencode
 npx thoth-agents@latest install --agent=codex
 npx thoth-agents@latest install --agent=claude
+npx thoth-agents@latest update --harness=opencode
+npx thoth-agents@latest update --harness=opencode --apply
 npx thoth-agents@latest model --harness=codex --role=deep --model=gpt-5.6-sol
 ```
 
+`update` previews by default. Applying it performs the same complete refresh as
+installation for the selected harness: OpenCode refreshes its exact plugin pin,
+managed configuration, owned skills, external skills, and provider setup;
+Codex runs native plugin setup before its global agent pack, external skills,
+and provider setup; Claude refreshes its native plugin before external skills
+and provider setup. Any required failure makes the operation fail rather than
+claiming a complete update.
+
+After every required step succeeds, the CLI records that harness's executing
+version in
+`${XDG_CONFIG_HOME:-~/.config}/thoth-agents/install-state.json`. `status` shows
+the executing CLI version and this last complete CLI-managed version. The three
+harness records are independent: native Codex or Claude marketplace updates do
+not advance them and do not prove that CLI-managed agents, skills,
+configuration, or provider setup are current.
+
+OpenCode's runtime release check is notification-only. It does not rewrite the
+exact plugin pin, invalidate package state, or run a package manager. Follow the
+notification by rerunning the latest CLI installer or applying CLI Update.
+
 In the interactive `Configure models` flow, `Apply` is always available. When
 no role is dirty, it reapplies every currently displayed role value; after an
 edit, preview and apply remain limited to the dirty roles. In OpenCode, both

diff --git a/docs/agent/cli-installation.md b/docs/agent/cli-installation.md
@@ -9,6 +9,10 @@ phase execution does not.
 ## Invariants
 
 - OpenCode is the default CLI harness.
+- `@latest` is valid for selecting the CLI package to execute, but every
+  OpenCode config mutation uses the executing package's exact semantic version.
+  Package identity is resolved before managed writes and failure never falls
+  back to a `latest` plugin entry.
 - OpenCode installation synchronizes all five packaged thoth-owned skills into
   `~/.config/opencode/skills/`; status, install, and sync share that inventory.
   `/thoth-init` owns only project `openspec/` governance.
@@ -20,17 +24,36 @@ phase execution does not.
 - Provider diagnostics, manual actions, and receipt are surfaced. Consumer
   reset never becomes provider `--force`, rollback, removal, or file repair.
 - Browser and QA executables remain project-owned.
-- Dry-run writes nothing; reset touches only bounded managed targets.
+- Install and applied Update share the complete selected-harness orchestration:
+  OpenCode refreshes exact plugin/config plus owned skills; Codex performs
+  native plugin setup before its global pack; Claude performs native plugin
+  refresh. Every harness then installs required external skills, requires
+  provider-complete evidence, and records CLI completion last.
+- Update previews by default. Preview and dry-run write nothing; any required
+  apply failure returns failure and does not claim or record completion. Reset
+  touches only bounded managed targets.
+- `${XDG_CONFIG_HOME:-~/.config}/thoth-agents/install-state.json` is the
+  schema-versioned CLI-owned ledger. Its `opencode`, `codex`, and `claude`
+  records advance independently and atomically only after complete success.
+  Missing state remains missing; malformed state is backed up and repaired only
+  when a successful operation is ready to commit its selected harness.
+- Status treats each ledger record as the official last complete CLI-managed
+  version, exposes it beside the executing CLI version, and never infers or
+  advances it from OpenCode package state or native marketplace state.
 - Codex and Claude marketplace trust, snapshots, and caches remain
   manager-owned; installers may invoke their official native manager commands
-  but never edit those files directly.
+  but never edit those files directly. Native plugin updates do not prove that
+  CLI-managed agents, skills, configuration, or provider setup are aligned.
 - Codex CLI installation is mandatory for global agents, root instructions,
   feature configuration, external global skills, and native plugin setup. It
   fails closed before global writes when Codex manager inspection or plugin
   verification fails. `$thoth-init` creates project SDD governance only.
 - Claude requires native marketplace add/install before its plugin surfaces
   exist; then the CLI installs external skills and requests provider setup
   without editing Claude's cache.
+- OpenCode runtime update checks are notification-only. They do not rewrite
+  config, invalidate package state, or run package installation; operators must
+  rerun the latest CLI installer or apply Update explicitly.
 - CLI changes require parser/help/tests and public docs in the same change.
 
 ## Verification

diff --git a/docs/installation.md b/docs/installation.md
@@ -1,8 +1,8 @@
 # Installation
 
-thoth-agents 0.3.0 supports OpenCode, Codex, and Claude Code. The distributions
-share one seven-role and Spec Kit-compatible SDD contract. Installation uses the
-CLI for every harness, while Codex additionally requires a CLI-managed global
+thoth-agents supports OpenCode, Codex, and Claude Code. The distributions share
+one seven-role and Spec Kit-compatible SDD contract. Installation uses the CLI
+for every harness, while Codex additionally requires a CLI-managed global
 orchestration layer that its plugin manifest cannot provide.
 
 ## Requirements
@@ -51,16 +51,22 @@ npx thoth-agents@latest install --agent=opencode --dry-run
 npx thoth-agents@latest install --agent=opencode
 ```
 
-The CLI adds `thoth-agents@latest` to OpenCode configuration, writes the
-seven-role OpenAI preset, synchronizes all five packaged thoth-owned skills into
-`~/.config/opencode/skills/`, and installs all four external skills with `npx
-skills add`. Status and repair verify the resulting global discovery targets.
-It then requires provider-owned thoth-mem setup to complete. Restart OpenCode
-and invoke `/thoth-init`; it only preflights and synchronizes the minimum
-`openspec/` governance structure while preserving existing constitutions. SDD
-phases resolve templates directly from the globally installed `thoth-sdd` skill;
-init leaves any legacy `openspec/templates/` tree untouched. No Kimi, Copilot,
-ZAI/GLM, or mixed-provider preset is generated.
+`@latest` selects the CLI release to execute. The CLI resolves that package's
+version before any managed write and puts the exact version in OpenCode
+configuration, for example `thoth-agents@0.4.8`. It replaces bare, tagged, or
+older thoth-agents entries with one exact entry while preserving unrelated
+plugins. If package identity or version cannot be verified, installation fails
+before changing configuration and never substitutes `latest`.
+
+The CLI also writes the seven-role OpenAI preset, synchronizes all five packaged
+thoth-owned skills into `~/.config/opencode/skills/`, and installs all four
+external skills with `npx skills add`. Status and repair verify the resulting
+global discovery targets. It then requires provider-owned thoth-mem setup to
+complete. Restart OpenCode and invoke `/thoth-init`; it only preflights and
+synchronizes the minimum `openspec/` governance structure while preserving
+existing constitutions. SDD phases resolve templates directly from the globally
+installed `thoth-sdd` skill; init leaves any legacy `openspec/templates/` tree
+untouched. No Kimi, Copilot, ZAI/GLM, or mixed-provider preset is generated.
 
 ## Codex
 
@@ -186,11 +192,65 @@ mirrored into thoth-mem.
 No distribution bundles thoth-mem or project QA executables. thoth-mem remains
 an independently owned provider/plugin installed through its own public setup.
 
-## Status and repair
+## Updates and authoritative install state
+
+Rerunning the latest installer and applying Update are the two supported update
+paths. Update previews by default; add `--apply` only after reviewing the plan:
+
+```bash
+npx thoth-agents@latest update --harness=opencode
+npx thoth-agents@latest update --harness=opencode --apply
+npx thoth-agents@latest update --harness=codex --apply
+npx thoth-agents@latest update --harness=claude --apply
+```
+
+Applied Update is installation-equivalent for the selected harness:
+
+| Harness | Complete refresh order |
+| --- | --- |
+| OpenCode | Exact plugin pin and managed configuration, global thoth-owned skills, required external skills, provider setup, then the CLI record |
+| Codex | Native plugin-manager setup, global agent pack/configuration, required external skills, provider setup, then the CLI record |
+| Claude Code | Native marketplace/plugin refresh, required external skills, provider setup, then the CLI record |
+
+The versioned CLI-owned ledger is located at
+`${XDG_CONFIG_HOME:-~/.config}/thoth-agents/install-state.json`. It keeps
+independent `opencode`, `codex`, and `claude` records. Each record is the version
+of the CLI release that most recently completed every required step for that
+harness; it is not a native plugin version.
+
+For existing installations, a missing ledger is expected until each harness
+first completes installation or applied Update under this contract. Status
+reports that harness's record as missing rather than inferring it from OpenCode
+package state or a Codex/Claude marketplace. Rerun the latest installer or apply
+Update once per harness to establish its record.
+
+The CLI commits the selected harness record last using temporary-file
+replacement. A preview, dry-run, cancellation, or failed native, managed,
+required-skill, provider, or ledger step does not advance the record; the
+previous completed version remains authoritative. A malformed ledger also
+remains untouched after earlier failures. Once a complete operation is ready to
+record success, the CLI preserves the malformed file as `install-state.json.bak`
+and replaces it with valid schema-v1 state.
+
+Codex and Claude marketplace managers continue to own native plugin versions,
+trust, snapshots, and caches. A native marketplace update neither changes this
+ledger nor proves that the CLI-managed global agents, skills, configuration, or
+provider setup were refreshed. Use `status` to compare the executing CLI version
+with the recorded complete-install version.
+
+OpenCode runtime checks only notify when a newer release exists. They do not
+rewrite the exact plugin entry, invalidate package state, or install packages in
+the background. Follow the notification by rerunning
+`npx thoth-agents@latest install --agent=opencode` or applying interactive or
+command-line Update.
+
+## Status, update, and repair
 
 ```bash
 npx thoth-agents@latest status
 npx thoth-agents@latest status --harness=codex
+npx thoth-agents@latest update --harness=codex
+npx thoth-agents@latest update --harness=codex --apply
 npx thoth-agents@latest sync --harness=codex --apply
 npx thoth-agents@latest model --harness=codex --role=deep --model=gpt-5.6-sol
 ```

diff --git a/docs/quick-reference.md b/docs/quick-reference.md
@@ -96,9 +96,28 @@ repositories.
 ```bash
 npx thoth-agents@latest status
 npx thoth-agents@latest list
+npx thoth-agents@latest update --harness=opencode
+npx thoth-agents@latest update --harness=opencode --apply
+npx thoth-agents@latest update --harness=codex --apply
+npx thoth-agents@latest update --harness=claude --apply
 npx thoth-agents@latest model --harness=codex --role=deep --model=gpt-5.6-sol
 ```
 
+`@latest` selects the CLI release. OpenCode is configured with that release's
+exact version, never a `latest` plugin entry. `update` previews by default;
+`--apply` performs the complete selected-harness installation refresh, including
+native setup where applicable, managed surfaces, required skills, and provider
+setup. Rerunning `install --agent=<harness>` is the equivalent explicit update
+path.
+
+The CLI records each harness's last fully completed version independently in
+`${XDG_CONFIG_HOME:-~/.config}/thoth-agents/install-state.json`. Dry-runs and
+failures do not advance it. Codex and Claude native marketplace updates do not
+advance it either; `status` reports the executing and recorded CLI versions.
+
+OpenCode runtime update checks only notify. They never rewrite the plugin pin,
+invalidate package state, or install the newer release.
+
 ## Boundaries
 
 - OpenCode ships only the OpenAI built-in preset.
@@ -109,6 +128,8 @@ npx thoth-agents@latest model --harness=codex --role=deep --model=gpt-5.6-sol
   config; `$thoth-init` creates project SDD governance only.
 - Claude requires both native marketplace commands before its namespaced skill
   exists.
+- Codex and Claude native managers own plugin versions and caches; the CLI
+  ledger is the authority only for the separate complete CLI-managed setup.
 - thoth-mem owns its hooks, MCP, skill, lifecycle, persistence, receipts, and
   recovery. thoth-agents only invokes its public setup during installation.
 - Runtime memory authorization is `none`, `recall`, or `observe` and does not

diff --git a/...nges/archive/2026-07-26-pin-opencode-plugin-and-unify-updates/archive-report.md b/...nges/archive/2026-07-26-pin-opencode-plugin-and-unify-updates/archive-report.md
@@ -0,0 +1,32 @@
+# Archive Report: Pin OpenCode Plugin and Unify Harness Updates
+
+**Status**: ARCHIVED<br>
+**Oracle verdict**: PASS<br>
+**Archive path**: `openspec/changes/archive/2026-07-26-pin-opencode-plugin-and-unify-updates/`
+
+## Completed scope
+
+- US1 / FR-001-FR-002 / SC-001-SC-002: OpenCode installation and applied Update pin exactly the executing package release, replace prior managed forms, and fail before mutation when package identity is invalid.
+- US2 / FR-003-FR-005 / SC-003-SC-005: Interactive and command Update paths perform the complete selected-harness refresh with truthful previews, ordered native/managed/skill/provider/ledger effects, and failing outcomes for incomplete required steps.
+- US3 / FR-006-FR-007 / SC-006-SC-007: A versioned global ledger records the last complete CLI-managed release independently for OpenCode, Codex, and Claude and remains independent of native marketplace versions.
+- US4 / FR-008-FR-009 / SC-008-SC-009: The OpenCode runtime only notifies about newer releases, while CLI/TUI/public documentation consistently identifies the CLI as the official complete update path.
+
+## Verification lineage
+
+- `verify-report.md` records independent oracle PASS with `pnpm run check:ci`, `pnpm run typecheck`, `pnpm run build`, `pnpm run integration:verify`, and `pnpm test` all passing; the full suite completed 939/939 tests.
+- Oracle mapped every FR-001 through FR-009 and buildable SC-001 through SC-009 to implementation evidence and executed checks, with no critical issue.
+
+## Canonical specification sync
+
+- Updated: `cli-installation`.
+## Deviations and residual warnings
+
+- No scope deviation. A stale provider-boundary source-layout assertion was updated to follow the accepted shared finalization seam without weakening provider ownership.
+- W-001: The TUI preview renders five item details and summarizes remaining planned stages as a count; the underlying plan and CLI preview enumerate every required stage.
+- R-001: Native manager, external skill, and provider effects were verified through isolated/mocked seams; live external mutation was intentionally not invoked.
+- R-002: Ledger replacement is atomic, but already completed external effects are not rolled back if the final ledger commit fails; retry is the documented recovery path.
+- R-003: Existing nonfatal Codex enforcement-gap notices remain truthful capability disclosures.
+
+## Follow-up
+
+- None.
diff --git a/.../changes/archive/2026-07-26-pin-opencode-plugin-and-unify-updates/data-model.md b/.../changes/archive/2026-07-26-pin-opencode-plugin-and-unify-updates/data-model.md
@@ -0,0 +1,61 @@
+# Data Model: CLI-Managed Installation Ledger
+
+## Location and ownership
+
+The CLI owns one global state file:
+
+```text
+${XDG_CONFIG_HOME:-~/.config}/thoth-agents/install-state.json
+```
+
+The path is independent of OpenCode, Codex, Claude Code, and thoth-mem native state. Test and embedded callers may inject the home/config root, but harness-specific environment variables do not relocate this cross-harness ledger.
+
+## Schema v1
+
+```json
+{
+  "schemaVersion": 1,
+  "harnesses": {
+    "opencode": { "version": "0.4.8" },
+    "codex": { "version": "0.4.8" },
+    "claude": { "version": "0.4.8" }
+  }
+}
+```
+
+Rules:
+
+- `schemaVersion` is exactly `1`.
+- Harness keys are limited to `opencode`, `codex`, and `claude`.
+- Each record contains only the exact package version that most recently completed the full CLI installation contract for that harness.
+- A harness key may be absent when that harness has never completed installation through a ledger-aware CLI.
+- No native marketplace version, provider state, receipt, secret, timestamp, or inferred cache version is stored.
+
+## State transitions
+
+| Existing state | Operation outcome | Result |
+| --- | --- | --- |
+| Missing ledger | Full non-dry-run success for harness H at version V | Create schema v1 with `H.version = V`. |
+| Valid ledger | Full non-dry-run success for harness H at version V | Preserve every other harness record and atomically replace `H.version`. |
+| Valid ledger | Preview, dry-run, cancellation, or any failed required step | Preserve the file byte-for-byte. |
+| Malformed/unsupported ledger | Status | Report CLI-managed version as unknown and do not infer a replacement. |
+| Malformed/unsupported ledger | Full non-dry-run success | Back up the invalid CLI-owned file, initialize schema v1, and commit only the newly proven harness record. |
+| Any state | Native Codex/Claude marketplace update outside the CLI | No ledger transition. |
+
+## Atomicity and failure semantics
+
+1. Resolve and validate the executing package identity and version before any harness mutation.
+2. Complete native-manager, CLI-managed surface, required-skill, and provider setup steps.
+3. Serialize the next ledger to a sibling temporary file.
+4. Preserve an invalid prior ledger as a backup when repair is required.
+5. Rename the temporary file into place.
+6. Report overall installation failure if the ledger cannot be committed; retain the previous authoritative record and make retry the recovery path.
+
+The transaction is atomic only for the ledger file. External manager, filesystem, skill, and provider effects are not rolled back after they have independently succeeded.
+
+## Status interpretation
+
+- **Recorded equals executing version**: the last complete CLI refresh used this CLI release; ordinary managed-surface checks still determine drift.
+- **Recorded differs from executing version**: show both values and offer a complete update. Do not silently classify marketplace state as the recorded value.
+- **Record missing or invalid**: show the CLI-managed version as unknown/missing and recommend a complete CLI update.
+- A Codex or Claude marketplace plugin may be newer or older than the ledger without changing this interpretation.