Clarify shiv package resolution and freshness across global vs mise installs

[ikma-ricon]

Problem

We keep losing time to one question:

What version of this shiv-managed tool am I actually running, and why?

There are now two overlapping installation paths:

1. Global shiv installs — command shims in the user's PATH, backed by shiv's global registry / package directory.
2. Repo-scoped mise installs — mise.toml entries like:

   [tools]
   "shiv:modules" = "latest"
   "shiv:sessions" = "0.3.0"

   resolved through vfox-shiv and mise shims.

When these disagree, users and agents get confused about which package wins. Worse, if a repo says "shiv:<pkg>" = "latest", it is unclear when that value is re-resolved and whether the installed copy is fresh.

This has already shown up in real work:

• A prior non-interactive-shell bug caused agents to run global shiv shims instead of per-project mise pins (bug: vfox-shiv packages not on PATH in non-interactive shells #90, closed).
• During a modules investigation, shiv which modules said modules was not shiv-managed even though the current repo had "shiv:modules" = "latest" and mise which modules resolved a shiv package (which: resolve or explain mise-scoped shiv packages #100).
• We routinely need to know whether a pinned/latest shiv:* entry in mise.toml is stale (Bump shiv dependency versions in consumer mise.toml files #87, Version management: upgrade, downgrade, version check #53, feat: shiv outdated — detect stale package versions #79).

Desired user-facing outcome

There should be one obvious command that answers, for a command/package name:

• What executable will run from here?
• Is that executable a global shiv shim, a mise shim, or something else?
• If it is a shiv package, where is the package checkout?
• If this repo's mise.toml declares shiv:<pkg>, what version/ref is declared?
• What version/ref is installed/resolved right now?
• If the declared version is latest, when was it resolved and is it stale?
• If both global and mise-scoped installs exist, which one wins and why?

Possible command names:

shiv resolve modules
shiv doctor modules
shiv which --explain modules

Example output shape:

modules
  command on PATH: /Users/.../.local/share/mise/shims/modules
  provider:        mise tool shiv:modules
  declared in:     /Users/rikonor/agents/or/home/mise.toml
  declared ref:    latest
  installed shim:  /Users/.../.local/share/mise/installs/shiv-modules/0.9.0/bin/modules
  package root:    /Users/.../.local/share/mise/installs/shiv-modules/0.9.0/packages/modules
  package ref:     v0.9.0 / abc1234
  freshness:       latest available is v0.9.1 (stale)

  global shiv install also exists:
    /Users/.../.local/share/shiv/packages/modules
    not winning because mise shims precede ~/.local/bin on PATH

Semantics to define

Precedence

Document and test the intended precedence between:

• mise shims for repo-scoped shiv:<pkg> tools
• global shiv shims in ~/.local/bin
• direct binaries elsewhere on PATH

The #90 class should have regression coverage so a global shiv install cannot silently win in non-interactive shells when a repo declares a mise-scoped package.

latest

Define what "shiv:<pkg>" = "latest" means in practice:

• When does mise/vfox-shiv re-resolve latest?
• Does mise install update it?
• Does mise upgrade update it?
• Should shiv update know about repo-scoped shiv:* entries?
• How can a user tell whether the current latest install is stale?

If latest is effectively cached until an explicit update command, diagnostics should say that plainly.

Related issues

• bug: vfox-shiv packages not on PATH in non-interactive shells #90 — non-interactive shells fell back to global shiv shims instead of per-project mise pins (closed, needs regression coverage)
• which: resolve or explain mise-scoped shiv packages #100 — shiv which should resolve or explain mise-scoped shiv packages
• Bump shiv dependency versions in consumer mise.toml files #87 — bump shiv dependency versions in consumer mise.toml files
• Version management: upgrade, downgrade, version check #53 — version management: upgrade, downgrade, version check
• Shim should intercept --version to show package version info #85 — shims should intercept --version to show package version info
• feat: shiv outdated — detect stale package versions #79 — shiv outdated for stale package detection (closed; verify whether it handles mise-scoped shiv:* entries)
• mise plugin for shiv: versioned dependencies and safe interface migrations #59 — mise plugin for shiv packages
• mise plugin: support command aliases for shiv packages #101 — command aliases for mise-scoped shiv packages

Why this is high priority

This is not just polish. When agents or humans run the wrong version of a tool, they make incorrect diagnoses and sometimes file/fix the wrong thing. The ecosystem now relies heavily on repo-scoped shiv packages in mise.toml, so resolution/freshness ambiguity is a correctness issue.

The north star: from any repo, one command should make the active shiv package, its source, its version, and its freshness obvious.

[junior-ricon]

Split the concrete PATH-ordering enforcement work into #106. #102 should remain the broader resolution/freshness/explainability umbrella; #106 is the focused fix for ensuring mise shims actually precede global shiv shims even when PATH already contains both dirs in the wrong order.