mirror-mind 0.0.1 → 0.32.1

package/docs/releases/v0.32.1.md

@@ -0,0 +1,59 @@
+---
+digest: >
+  v0.32.1 is the published CV22 release. v0.32.0 was tagged, and its
+  publication was refused by the project's own retired-surface tripwire:
+  one sentence in Getting Started named the retired Python invocation by
+  its literal form, which only the history and release notes may do. The
+  sentence is rephrased; nothing else changed. Everything v0.32.0's note
+  says is true of this version: install with `npm install -g mirror-mind`,
+  or upgrade a clone with the five lines, which include `npm link` and
+  `mirror runtime migrate`.
+---
+
+# v0.32.1 — The Release That Shipped
+
+**Date:** 2026-10-11
+
+## Highlights
+
+- **This is the CV22 release.** Read [v0.32.0 — One Language, One Install](v0.32.0.md)
+  for what it is; this note only says why the number ends in 1.
+- **One sentence changed**, in `docs/getting-started.md`: the paragraph telling a clone user
+  what the previous updater does no longer spells out the retired interpreter invocation.
+- **No code, no behavior, no schema** differs from `v0.32.0`.
+
+## Where We Started
+
+`v0.32.0` was tagged at `78dd5836` and `stable` moved there. The publish workflow, which
+stages the package from CI for a maintainer to approve, runs the retired-surface
+tripwire first, and it refused: `docs/getting-started.md:385 mentions \`uv run python\`,
+retired by CV22.DS10.TS5`. The sentence had been added after the upgrade rehearsal,
+committed as a docs-only change, and tagged without re-running the guard; the tests
+workflow skips docs-only pushes, so nothing ran it before the tag.
+
+## What Changed
+
+The project's rule is that a tag never moves and the doctor refuses a tag that is not at
+`HEAD`, so the fix is a patch: the sentence now reads "the old interpreter form of the
+command now fails with `No module named memory.__main__`", which says the same thing to
+the person it is for without naming the form the guard forbids. The guard was right: a
+Getting Started page is not the place to teach the retired invocation, even in the past
+tense.
+
+`v0.32.0` remains a tag in the repository and was never published to npm.
+
+## Conscious Exclusions
+
+- Moving the `v0.32.0` tag to the fix. It would have given a cleaner version list at the
+  cost of breaking, by hand, the rule the release tooling encodes, on the first release
+  made under it.
+
+## What We Learned
+
+A docs-only commit between the last green check and the tag is still a commit. The
+retired-surface guard belongs in the Docs workflow too, so a docs-only push cannot pass
+CI while carrying what the publish gate refuses; that is a Change Request, not this patch.
+
+## Next Horizon
+
+Publication through the staged route, then CV22 closes.

package/docs/releases/v0.8.0.md

@@ -0,0 +1,118 @@
+---
+digest: >
+  Mirror Mind v0.8.0 publishes the first stable self-update foundation. The
+  release turns update from an informal git pull into a visible runtime workflow:
+  status, diagnosis, backup, dry-run planning, fast-forward execution, updater
+  self-recovery, stable/main channels, welcome version visibility, and runtime
+  release-note access. It also establishes that `main` is integration while
+  `stable` is the user-facing update channel. This is not Mirror Mind 1.0 yet;
+  it is the operational base that makes future stable releases safe to receive.
+---
+
+# v0.8.0 — Stable Self-Update Foundation
+
+**Date:** 2026-05-22
+
+## Highlights
+
+- Runtime self-update now has a complete safe path: status, diagnosis, backup,
+  dry-run, update check, fast-forward execution, migrations, and post-update
+  health validation.
+- The updater can repair itself through a code-only recovery lane when stale
+  updater code crashes before normal update planning.
+- Mirror Mind now distinguishes `main` as the integration/dogfooding channel and
+  `stable` as the user-facing release channel.
+- The welcome card shows installed version and update channel, so users can see
+  what they are running before asking for help.
+- Runtime release notes can be read through `python -m memory runtime
+  release-notes` and natural-language Mirror requests such as "What's new in the
+  latest Mirror Mind release?"
+
+## Where We Started
+
+Mirror Mind already had a strong local-first runtime, but update was still a
+human memory problem. Production and development clones could be confused. A user
+could not ask the runtime whether it was healthy enough to update. Backup existed
+but was not part of a visible self-update route. Any push to `main` risked being
+interpreted as a user-facing update, even though Ariad's release model says a
+release is a closed, validated arc of work, not just a commit.
+
+The first self-update slices made the runtime inspectable. Later slices made it
+safe to mutate. The final pressure came from dogfooding: a stale updater crashed
+while trying to install its own fix. That proved the updater needed a recovery
+lane that did not require an end user to know git bootstrap commands.
+
+## What Changed
+
+The runtime now exposes a coherent operational surface:
+
+- `runtime status` reports version, repository state, mirror home, database,
+  migrations, extensions, clone role, update channel, Python version, and
+  environment.
+- `runtime diagnose` classifies drift and repair routes without mutating files or
+  the database.
+- `runtime backup` creates and structurally verifies database backups.
+- `runtime version` shows the installed version, clone role, and update channel.
+- `runtime update --check` checks the configured channel without mutating local
+  refs.
+- `runtime update --dry-run` plans from local refs without mutation.
+- `runtime update` performs a backup-first, fast-forward-only update and applies
+  migrations through a one-shot `MemoryClient` open.
+- `runtime update --repair-updater` provides a code-only recovery lane when the
+  full status gate cannot run because the updater itself is stale or broken.
+
+The production/development boundary is now explicit through `.mirror-clone-role`.
+The update target is explicit through `.mirror-update-channel`. Missing or invalid
+update channels default to `stable`.
+
+The welcome card now says what the runtime is:
+
+```text
+◇ Mirror · <user>
+Version 0.8.0 · channel stable
+...
+```
+
+Release notes are prospective from this release onward. Historical tags through
+`v0.7.0` remain valid history, but `v0.8.0` is the first release that carries the
+new release-management loop into the runtime itself.
+
+## Conscious Exclusions
+
+- This release does not complete CV9 or claim Mirror Mind 1.0 readiness.
+- Release-aware update notices still fall back to commit counts when they cannot
+  map an update to a release note; richer release-aware notices are planned next.
+- Stable promotion is still a controlled manual process, not a fully automated
+  command or Maestro workflow.
+- Full natural-language release-note parity across every runtime surface remains
+  follow-up work.
+- The local production checkout may still have git branch `main` while following
+  update channel `stable`; the channel, not the local branch name, controls the
+  update target.
+
+## What We Learned
+
+Self-update is not one command. It is a chain of trust: know the current state,
+refuse unsafe mutation, preserve recoverability, apply the smallest safe change,
+explain what happened, and leave a future session able to understand the result.
+
+The dogfooding incident where the updater could not install its own fix clarified
+an important product rule: recovery paths must be usable by non-experts. Manual
+git recovery is acceptable for development, but the product needs an updater
+self-repair lane.
+
+The release-channel split also clarified the relationship between Ariad and git.
+`main` is where integration happens. `stable` is where a release becomes a user
+promise.
+
+## Next Horizon
+
+The remaining Self-Update Done work is now clearer:
+
+- make update notices and post-install output speak in release terms when a
+  stable release note exists;
+- ensure release-note access works naturally across supported runtime surfaces;
+- add a repeatable release promotion checklist or doctor;
+- provide a controlled promotion path for `stable`;
+- validate a fresh clone updating from one stable release to the next without
+  manual git intervention.

package/docs/releases/v0.9.0.md

@@ -0,0 +1,98 @@
+---
+digest: >
+  Mirror Mind v0.9.0 closes the Self-Update Done release arc. The release turns
+  the v0.8.0 self-update foundation into a release-aware operating loop: stable
+  update notices speak in release terms, release notes are available across
+  runtime skill surfaces, promotion readiness is inspectable through a doctor,
+  stable promotion has a controlled execution path, and the fresh-user smoke
+  procedure proves the stable no-op path while identifying the release-state
+  boundary needed for update-hop validation. This is still not Mirror Mind 1.0;
+  it is the release-management layer that makes the path to 1.0 safer.
+---
+
+# v0.9.0 — Self-Update Done
+
+**Date:** 2026-05-23
+
+## Highlights
+
+- Stable update surfaces now prefer release language when local refs contain
+  newer release notes.
+- Release notes are available across Pi, Gemini/Codex shared skills, and Claude
+  Code.
+- `runtime release-doctor` provides a read-only promotion readiness checklist.
+- `runtime release-promote` provides a controlled stable promotion path with
+  dry-run, local promotion, and explicit push.
+- Fresh-user stable update smoke now has an isolated procedure and validated the
+  current stable no-op path without touching production data.
+
+## Where We Started
+
+`v0.8.0` made self-update safe enough to exist: status, diagnosis, backup,
+dry-run, execution, updater repair, release notes, and stable/main channels were
+in place. But the release layer around that mechanism was still thin. Stable
+updates could still look like commit movement. Release notes existed, but runtime
+skill access was uneven. Promotion relied on human git steps. And the user-shaped
+smoke test had not yet proven what a fresh clone would experience.
+
+The remaining question was not whether Mirror could update in principle. It was
+whether the release path around update was coherent enough to be repeated.
+
+## What Changed
+
+Release-aware update notices now connect stable updates with narrative release
+notes when the local upstream ref contains newer release metadata. `runtime
+update --check` remains conservative and non-mutating; it can report a remote
+commit without pretending to have fetched release-note details. Dry-run and
+successful stable updates can speak in terms of the release being installed.
+
+Release notes became available across runtime skill surfaces. Pi keeps
+`/mm-release-notes`, Gemini and Codex receive the shared `.agents` skill, and
+Claude Code has `/mm:release-notes`. The skill contract stays thin: call
+`python -m memory runtime release-notes` and show the output verbatim unless the
+user asks for a summary.
+
+Release promotion became inspectable and then executable. `runtime
+release-doctor` checks the repository, clean tree, package version, release note,
+release index, tag state, and stable ref relationship without mutation. `runtime
+release-promote` uses that doctor as a gate, creates or reuses the release tag,
+creates or fast-forwards the local stable branch only when safe, and publishes
+only when `--push` is explicit.
+
+The fresh-user smoke story then tested the stable update path in a temporary
+clone and temporary Mirror home. The smoke validated the current published stable
+state as a no-op update and revealed an important isolation rule for historical
+stable versions: set both `MIRROR_USER=` and `MIRROR_HOME=<temp-home>`, because
+`MEMORY_DIR` alone does not prevent older code from loading `MIRROR_USER` from
+`.env`.
+
+## Conscious Exclusions
+
+- This release does not close CV9 or claim Mirror Mind 1.0 readiness.
+- The fresh-user smoke could not prove a `v0.8.0 -> v0.9.0` hop before this
+  release was prepared and promoted; that hop is the post-promotion validation
+  target.
+- The release promotion path does not query GitHub Actions, wait for CI, force
+  push, rewrite tags, bump versions, or write release notes.
+- Production update validation remains a controlled operational step after
+  stable promotion.
+
+## What We Learned
+
+A self-updating runtime needs a release vocabulary, not only update mechanics.
+Users should see releases, not just commits. Maintainers should see readiness,
+not just git commands. And smoke tests should be shaped like real users, not like
+the developer's machine.
+
+The visualization experiment also clarified how Ariad work should be shown:
+Bird's-Eye maps locate work, Transition Views show movement, Release Intent
+shows the version arc being built, and checkpoint views should show only the
+components useful for that stage.
+
+## Next Horizon
+
+After `v0.9.0` is promoted to stable, the next validation is the real fresh-user
+update hop from `v0.8.0` to `v0.9.0`. Once that passes, CV9.E3's Self-Update Done
+track can close and the project can return to the remaining CV9 readiness work:
+boundary hardening and stabilization before the eventual Mirror Mind 1.0
+boundary.

package/docs/releases/v0.9.1.md

@@ -0,0 +1,83 @@
+---
+digest: >
+  Mirror Mind v0.9.1 adds the missing opening awareness around the v0.9.0
+  self-update path. The runtime can now surface stable release availability in
+  the welcome through a network-tolerant check and a small cache, while Pi gets
+  a compact status-bar signal that shows the active user and whether attention
+  is needed. This patch does not change the update executor; it makes the
+  existing stable update capability visible at the moment the user opens the
+  Mirror.
+---
+
+# v0.9.1 — Welcome Release Awareness
+
+**Date:** 2026-05-23
+
+## Highlights
+
+- Welcome can detect a newer stable release through a lightweight remote check
+  when its update cache is missing or stale.
+- Update awareness is cached under `<mirror-home>/runtime/update-check.json`.
+- Remote welcome checks fail softly and can be disabled with
+  `MIRROR_WELCOME_REMOTE_UPDATE_CHECK=off`.
+- `python -m memory welcome --status-line` renders a compact status signal for
+  runtime status bars.
+- Pi now uses the compact status signal instead of showing only conversation
+  logging status.
+
+## Where We Started
+
+After publishing `v0.9.0`, the self-update mechanism worked, but the opening
+experience did not yet reveal it. A user could run `runtime update --check` and
+see the new release, but simply opening Mirror showed version and channel only.
+The system was operationally capable but experientially quiet.
+
+That gap mattered because the desired user experience is natural: open Mirror,
+see that a release is available, ask what changed, and ask Mirror to update.
+
+## What Changed
+
+The welcome card now has network-tolerant release awareness. It can refresh a
+small update cache with a lightweight `git ls-remote` check when the cache is
+absent or older than six hours. It does not fetch, mutate refs, update files,
+run backups, run migrations, or block startup. If the remote is unavailable, the
+welcome still opens normally.
+
+When a stable update is known, the welcome can show:
+
+```text
+Update available: v0.9.1 — Welcome Release Awareness
+Ask: "what changed?" or "update my Mirror"
+```
+
+The compact status-line command gives runtimes a small signal:
+
+```text
+◇ alisson-vale · ✓
+◇ alisson-vale · ⬆ v0.9.1
+```
+
+Pi's `mirror-logger` extension now uses that status-line command for its footer
+status.
+
+## Conscious Exclusions
+
+- This patch does not auto-update the runtime.
+- The status bar reads cached state only; welcome owns remote refresh.
+- The release title is available when local release notes exist. Otherwise the
+  notice degrades to version-only or commit-level availability.
+- This patch does not add a full health dashboard.
+
+## What We Learned
+
+Mirror Mind should be local-first in state and network-tolerant in operation.
+The welcome should not depend on the network, but it can use the network as an
+antenna. The status bar should remain a signal; the welcome is where explanation
+and next action belong.
+
+## Next Horizon
+
+The next release-awareness improvements should come from dogfooding: whether the
+status signal is clear enough, whether the cache TTL feels right, and whether
+natural-language update requests should get a dedicated intent path beyond the
+existing runtime commands.

package/package.json

@@ -1,16 +1,112 @@
 {
   "name": "mirror-mind",
-  "version": "0.0.1",
-  "description": "Name reserved for Mirror Mind, a local-first memory and identity framework for agentic AI runtimes. This version installs nothing runnable; the first release is coming.",
+  "version": "0.32.1",
+  "description": "Mirror Mind: a local-first memory and identity framework for agentic AI runtimes (Pi, Claude Code, Gemini CLI, Codex)",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mirror-mind-ai/mirror.git"
   },
   "homepage": "https://github.com/mirror-mind-ai/mirror#readme",
-  "bugs": {
-    "url": "https://github.com/mirror-mind-ai/mirror/issues"
+  "keywords": [
+    "mirror-mind",
+    "memory",
+    "identity",
+    "agent",
+    "pi-package",
+    "claude-code",
+    "gemini-cli",
+    "codex",
+    "sqlite",
+    "local-first"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=24"
   },
-  "keywords": ["mirror-mind", "memory", "identity", "agent", "pi", "claude-code", "gemini-cli", "codex"],
-  "files": ["README.md", "LICENSE"]
+  "bin": {
+    "mirror": "bin/mirror.js",
+    "mirror-hook": "bin/mirror-hook.js"
+  },
+  "files": [
+    "bin",
+    "ts/src",
+    "templates",
+    "docs/releases",
+    ".pi/extensions",
+    ".pi/skills",
+    ".claude/hooks",
+    ".gemini/hooks",
+    "plugins/mirror-mind",
+    "scripts/codex-hooks",
+    "scripts/codex-mirror.sh",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./.pi/extensions/mirror-logger.ts"
+    ],
+    "skills": [
+      "./.pi/skills"
+    ]
+  },
+  "imports": {
+    "#backup/*": "./ts/src/backup/*",
+    "#builder/*": "./ts/src/builder/*",
+    "#consult/*": "./ts/src/consult/*",
+    "#conversation/*": "./ts/src/conversation/*",
+    "#cultivation/*": "./ts/src/cultivation/*",
+    "#db/*": "./ts/src/db/*",
+    "#descriptor/*": "./ts/src/descriptor/*",
+    "#docs/*": "./ts/src/docs/*",
+    "#evals/*": "./ts/evals/*",
+    "#explorer/*": "./ts/src/explorer/*",
+    "#extensions/*": "./ts/src/extensions/*",
+    "#extraction/*": "./ts/src/extraction/*",
+    "#fixtures/*": "./ts/test/fixtures/*",
+    "#frontDoor/*": "./ts/src/frontDoor/*",
+    "#goldens/*": "./ts/test/goldens/*",
+    "#guards/*": "./ts/src/guards/*",
+    "#helpers/*": "./ts/test/helpers/*",
+    "#hooks/*": "./ts/src/hooks/*",
+    "#identity/*": "./ts/src/identity/*",
+    "#init/*": "./ts/src/init/*",
+    "#journey/*": "./ts/src/journey/*",
+    "#mcp/*": "./ts/src/mcp/*",
+    "#memory/*": "./ts/src/memory/*",
+    "#mirror/*": "./ts/src/mirror/*",
+    "#mode/*": "./ts/src/mode/*",
+    "#observability/*": "./ts/src/observability/*",
+    "#persona/*": "./ts/src/persona/*",
+    "#planning/*": "./ts/src/planning/*",
+    "#providers/*": "./ts/src/providers/*",
+    "#repair/*": "./ts/src/repair/*",
+    "#runtime/*": "./ts/src/runtime/*",
+    "#search/*": "./ts/src/search/*",
+    "#seed/*": "./ts/src/seed/*",
+    "#smoke/*": "./ts/smoke/*",
+    "#soul/*": "./ts/src/soul/*",
+    "#tasks/*": "./ts/src/tasks/*",
+    "#util/*": "./ts/src/util/*",
+    "#welcome/*": "./ts/src/welcome/*"
+  },
+  "scripts": {
+    "release:doctor": "node ts/scripts/releaseDoctor.ts",
+    "release:promote": "node ts/scripts/releasePromote.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"ts/test/**/*.test.ts\"",
+    "eval": "node --env-file-if-exists=.env ts/evals/harness/cli.ts",
+    "lint": "biome check .",
+    "format": "biome format --write ."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.2.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.0"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  }
 }

package/plugins/mirror-mind/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "mirror-mind",
+  "version": "0.32.1",
+  "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
+  "author": {
+    "name": "Mirror Mind"
+  },
+  "mcpServers": {
+    "mirror-mind": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp/launch.sh"
+    }
+  }
+}

package/plugins/mirror-mind/hooks/hooks.json

@@ -0,0 +1,50 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
+            "timeout": 15000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/mirror-inject.sh",
+            "timeout": 30000
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/log-user-prompt.sh",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/log-session-end.sh",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/mirror-mind/hooks/log-session-end.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Mirror Mind hook wrapper — GENERATED by scripts/generate_hook_wrappers.sh.
+# Edit the generator, never this file: every wrapper shares these bytes and
+# differs only in the hook name and in how it finds the Mirror entry
+# (CV22.DS10.TS5 decision D4; CV22.DS10.US3 decision D5).
+set -uo pipefail
+HOOK="claude:session-end"
+
+# This wrapper is the Claude plugin's, and a plugin is copied into Claude
+# Code's own cache: no relative path from here reaches the Mirror tree. It
+# runs the installed `mirror-hook` bin instead, and reads no tree .env.
+REPO_ROOT=""
+
+# A hook never fails the user's turn, and never fails in silence: when it
+# cannot do its job it appends ONE line to <mirror home>/hooks.log and exits 0.
+# The home is found the way the core finds it -- MIRROR_HOME, else
+# MIRROR_USER -- from the environment when set there, else from the tree's
+# .env when the wrapper is in a tree, else from the user's config file
+# (~/.config/mirror/env), in the core's order (US3, D3). A GUI launch carries
+# neither variable, and the first wrappers then wrote to a home nobody reads.
+env_file_value() {
+  [ -f "$2" ] || return 0
+  sed -n -E "s/^[[:space:]]*(export[[:space:]]+)?$1[[:space:]]*=[[:space:]]*//p" "$2" \
+    | tail -n 1 | tr -d "\"'\r"
+}
+env_value() {
+  local value=""
+  if [ -n "${!1+set}" ]; then printf '%s' "${!1}"; return; fi
+  [ -z "$REPO_ROOT" ] || value="$(env_file_value "$1" "$REPO_ROOT/.env")"
+  [ -n "$value" ] || value="$(env_file_value "$1" "${XDG_CONFIG_HOME:-$HOME/.config}/mirror/env")"
+  printf '%s' "$value"
+}
+note() {
+  local home user
+  home="$(env_value MIRROR_HOME)"
+  user="$(env_value MIRROR_USER)"
+  if [ -n "$home" ]; then
+    home="${home/#\~/$HOME}"
+  elif [ -n "$user" ]; then
+    home="$HOME/.mirror-minds/$user"
+    [ -d "$home" ] || [ ! -d "$HOME/.mirror/$user" ] || home="$HOME/.mirror/$user"
+  else
+    return 0
+  fi
+  mkdir -p "$home" 2>/dev/null \
+    && printf '%s %s: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$HOOK" "$1" >> "$home/hooks.log" 2>/dev/null
+}
+
+# Find the bin. MIRROR_BIN names the directory holding `mirror` and
+# `mirror-hook` (`$(npm prefix -g)/bin`), the same trust class as MIRROR_NODE;
+# then the PATH; then the global bin directories a GUI launch leaves off it.
+ENTRY=""
+[ -n "${MIRROR_BIN:-}" ] && [ -x "$MIRROR_BIN/mirror-hook" ] && ENTRY="$MIRROR_BIN/mirror-hook"
+[ -n "$ENTRY" ] || ENTRY="$(command -v mirror-hook 2>/dev/null || true)"
+for candidate in "$HOME/.nvm/current/bin" /opt/homebrew/bin /usr/local/bin; do
+  [ -n "$ENTRY" ] && break
+  [ -x "$candidate/mirror-hook" ] && ENTRY="$candidate/mirror-hook"
+done
+
+if [ -z "$ENTRY" ]; then
+  note "mirror-hook not found on PATH; hook skipped. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory."
+  exit 0
+fi
+
+# Find Node. /usr/bin/python3 exists on every macOS; node usually lives under
+# nvm or Homebrew and is NOT on the PATH of a GUI-launched runtime. The Python
+# hooks could end in `|| true` because they always found their interpreter;
+# the same silence here would hide a new failure — no logging, no inject, no
+# close tail — that a user would meet weeks later as "Mirror stopped
+# remembering". So an unresolvable Node is RECORDED, never swallowed. The
+# directory the entry was found in is searched first: an npm global bin holds
+# the `node` that installed the package beside `mirror-hook`, while a system
+# `/usr/local/bin/node` can be years older (CI's Ubuntu runner has one).
+NODE="${MIRROR_NODE:-}"
+if [ -z "$NODE" ] || [ ! -x "$NODE" ]; then
+  NODE="$(command -v node 2>/dev/null || true)"
+fi
+for candidate in "$(dirname "$ENTRY")/node" "$HOME/.nvm/current/bin/node" /opt/homebrew/bin/node /usr/local/bin/node; do
+  [ -n "$NODE" ] && break
+  [ -x "$candidate" ] && NODE="$candidate"
+done
+
+if [ -z "$NODE" ]; then
+  note "node not found on PATH; hook skipped. Set MIRROR_NODE."
+  exit 0
+fi
+
+# Not `exec`: the entry exits 0 whatever happens inside it, so a non-zero exit
+# means Node itself could not run the hook -- too old for the loader shim, or
+# it crashed. That used to vanish into a stderr no runtime shows (TS5 handoff
+# review, finding N1). No flags: the entry reads configuration and silences
+# its own warnings (US3, D3).
+"$NODE" "$ENTRY" "$HOOK" "$@"
+status=$?
+if [ "$status" -ne 0 ]; then
+  note "node exited $status before the hook finished ($NODE, $("$NODE" --version 2>/dev/null || echo 'version unknown')); Mirror needs Node 24 or later. Set MIRROR_NODE."
+fi
+exit 0