---
digest: >
  v0.40.1 is a patch release of one Change Request, CR197. The plugin's hook wrappers and
  MCP entry now use `MIRROR_BIN` only when it is an absolute path to a directory holding the
  bin they need, the rule `MIRROR_NODE` follows since v0.39.5. A relative value could make
  a plugin hook run a JavaScript file from the project the runtime was opened in, and a
  value that no longer held `mirror-hook` was dropped without a word. Now neither is used,
  and the refused value is named with its reason. The forward-slash drive form Windows
  machines set for the Claude Code forwarders counts as absolute, proven in CI under Git
  Bash. No schema change, no migration, and no model or prompt change.
---

# v0.40.1 — The Bins You Named, or Why Not

**Date:** 2026-11-07

## Highlights

- **A relative `MIRROR_BIN` is never used**
  ([CR197](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr197-the-hook-wrappers-and-the-mcp-locator-accept-a-relative-mirror-bin.md)).
  `MIRROR_BIN` names the directory holding `mirror` and `mirror-hook`, for the plugin's
  hook wrappers and MCP entry, which a runtime copies into its own cache. A runtime starts
  them from the project it was opened in, and both readers took any value that passed
  `[ -x ]` there: with `MIRROR_BIN=bin`, Node ran the project's `bin/mirror-hook` as
  JavaScript on every plugin hook, and its `bin/mirror` at every MCP server start. Both
  readers now use the value only as an absolute path to a directory holding the bin they
  need as an executable file.
- **A value that is not used is named, with its reason.** A value that no longer held the
  bin, such as a prefix left behind by a Node switch, used to be dropped without a word.
  Now the hook wrappers write
  `MIRROR_BIN=bin is relative; searching the PATH and the usual places instead` to
  `<mirror home>/hooks.log`, once a UTC day for the same value, and the MCP entry writes
  the same message to its stderr. The reasons are `relative`, `missing`,
  `not a directory`, and `a directory without an executable mirror-hook` (or `mirror`).
  The search then goes on through the PATH and the usual places, as before.
- **The Windows form counts as absolute.** The rule uses `MIRROR_NODE`'s pattern, so
  `C:/Users/<you>/.mirror/bin`, the forward-slash form Windows machines set for the Claude
  Code forwarders, is absolute, and a drive-relative `C:bin` is refused as `relative`. The
  Windows CI job runs a plugin wrapper with that form under Git Bash.
- No schema change, no migration, and no model or prompt change.

## Where We Started

v0.39.5 gave `MIRROR_NODE` its rule
([CR192](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr192-the-hook-wrappers-and-the-mcp-locator-accept-a-relative-mirror-node.md)),
and its review found the same exposure one variable over: with `MIRROR_BIN=bin`, the
plugin's prompt hook made Node run the project's `bin/mirror-hook`, probed on 2026-11-04.
It was captured as CR197 and left out of v0.39.5 on purpose. On 2026-11-07 the CV9
re-baseline decided to ship it as a patch ahead of the 1.0 gate.

## What Changed

**One rule, two variables.** The plugin's bin and agy wrappers, generated by
`scripts/generate_hook_wrappers.sh`, and the MCP locator in
`ts/src/guards/claudePlugin.ts` test `MIRROR_BIN` with `ABSOLUTE_PATH_CASE`, the pattern
`MIRROR_NODE` uses, and a test fails if the copies drift. The bin search now carries the
pattern's backslashes, so the generator splices it by the text around its placeholder, as
it does the other shared fragments. The eight plugin wrappers are regenerated; the five
tree-form wrappers under `.claude/hooks/` read no `MIRROR_BIN` and are unchanged.

**A refusal that cannot forge a line.** Line breaks are removed from the value before it is
logged, as for `MIRROR_NODE`. The locator reads `$MIRROR_BIN` once, where it read it three
times, because Grok pastes a set variable's value into the MCP arguments it loads.

**Tests and CI.** The new tests ran the project's planted `bin/mirror-hook` and
`bin/mirror` before the fix. They cover each reason, the daily rule, a forged line break,
both variables refused in one run, the agy form, and a valid value that outranks the PATH.
The Windows job's Git Bash step runs a plugin wrapper over a prefix shaped like npm's on
Windows, with `MIRROR_BIN` in the forward-slash drive form.

**Docs.** The rule is stated once, in full, in the
[configuration reference](../reference/configuration.md#hook-bin-resolution), and
`REFERENCE.md` points there. Troubleshooting shows the refusal line and the fix, and no
longer says `MIRROR_BIN` is honored as given. Getting Started says the directory is given
as an absolute path.

Validated by the Navigator in a scratch home: two runs of the plugin's prompt hook with
`MIRROR_BIN=bin` wrote one line,

```text
2026-11-07T19:11:56Z claude:user-prompt: MIRROR_BIN=bin is relative; searching the PATH and the usual places instead
```

the MCP entry printed the same refusal and answered `initialize`, the project's planted
bins never ran, the prompt was logged, and `/opt/homebrew/bin`, the value his own Claude
settings set, was used with no refusal.

**Also in this release.** CV9's re-baseline
([CV9.DS10](../project/roadmap/cv9-mirror-1-0/cv9-ds10-the-1-0-done-condition-describes-the-system-that-exists/index.md)),
which changes documents only: the 1.0 done condition is now a table of claims, each with
the story that owns it.

## Conscious Exclusions

- `runtime diagnose` does not name a refused `MIRROR_BIN`. It counts the hooks' line as
  `hook_failures_recorded`, and the value and its reason are in `hooks.log`. Deferred to
  [CR198](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr198-runtime-diagnose-does-not-name-a-refused-mirror-node.md),
  which now covers both variables.
- A relative entry in your own `PATH`, such as `.`: `command -v` finds a project's file
  through it for every command you run, not only Mirror's.
- An absolute value is trusted wherever it points: whoever sets it chooses what runs.
- Rodrigo Immaginario's installer run against `main` was asked for and does not gate this
  tag; the Windows CI job is this release's Windows evidence.

## Upgrading

```bash
mirror runtime update
```

If you set `MIRROR_BIN` by hand, make it the absolute path of the directory holding
`mirror-hook`, `$(npm prefix -g)/bin`: a relative one is now refused, with one line a day
in `hooks.log`. A plugin copied into a runtime's cache keeps the old wrappers until the
runtime takes the update; `runtime diagnose` reports a copy that is behind.

## Next Horizon

CR198, so that `runtime diagnose` names a refused `MIRROR_NODE` or `MIRROR_BIN`; CV9.DS11,
journeys that can be reshaped without losing a record; and the rest of the way to 1.0 in
the [CV9 index](../project/roadmap/cv9-mirror-1-0/index.md).
