mirror-mind 0.39.1 → 0.39.3

package/.pi/skills/mm-identity/SKILL.md

@@ -59,9 +59,15 @@ Update identity content directly in the database.
 
 ```bash
 mirror identity set <layer> <key> --content "..." [--mirror-home PATH]
+mirror identity set <layer> <key> --file <path>  [--mirror-home PATH]
 ```
 
-If `--content` is omitted, content is read from stdin.
+If neither `--content` nor `--file` is given, content is read from stdin.
+
+For anything longer than a line, write the text to a file and pass `--file`:
+Mirror reads it as bytes, so the shell never splits, substitutes, or re-encodes
+it. On Windows PowerShell 5.1 it is the only safe route: the pipe is ASCII by
+default and turns every accented letter into `?`. The pipe stays for one-liners.
 
 A new `journey` or `persona` key must be kebab-case: lowercase letters, digits,
 and single hyphens, up to 80 characters, such as `product-launch`. Agents put
@@ -70,7 +76,8 @@ one that would work. A key created before this rule keeps working.
 
 **Examples:**
 - `mirror identity set ego behavior --content "Be direct."`
-- `cat new-soul.md | mirror identity set self soul`
+- `mirror identity set self soul --file new-soul.md`
+- `echo "Be direct." | mirror identity set ego behavior` (a one-liner; not on PowerShell 5.1)
 
 ---
 

package/.pi/skills/mm-journey/SKILL.md

@@ -16,7 +16,9 @@ When receiving `/mm-journey update <slug> <content>`: answered by the TS core (C
 
 ```bash
 mirror journey update <slug> "<content>"
-# or pipe via stdin:
+# longer than a line: write it to a file, read as bytes, untouched by the shell
+mirror journey update <slug> --file <path>
+# a one-liner through stdin (not on Windows PowerShell 5.1, whose pipe is ASCII):
 echo "<content>" | mirror journey update <slug> -
 ```
 

package/README.md

@@ -76,6 +76,9 @@ in your machine, not a server.
 - [Node.js 24+](https://nodejs.org/) — runs Mirror Mind's core
   (`node --version` must be ≥ v24; POSIX/macOS/Linux supported). Nothing
   else to install: there is no Python and no build step
+- On Windows: [Mirror Mind for Windows](https://github.com/mirror-mind-ai/mirror-installer),
+  a separate per-user installer that brings Node, Git Bash, Pi and Mirror in
+  one pass. It lives in its own repository, outside this package and its CI
 - [OpenRouter](https://openrouter.ai) account with at least $5 in credits —
   embeddings, memory extraction, and multi-LLM
 - An AI runtime subscription:

package/docs/releases/index.md

@@ -12,6 +12,8 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [v0.39.3 — Windows Gets Its Hooks](v0.39.3.md) — patch release of PR #53, PR #50, and PR #54 (@rodrigoimmaginario): the plugin's hook wrappers and MCP locator run the package's own bin when npm's global entry is a shell shim, so Claude Code hooks and the MCP server work on a Windows package install; `runtime diagnose` no longer counts its own verdict as a front-door error (CR139); the docs point a Windows reader to the installer in its own repository. No migration.
+- [v0.39.2 — Input, Read the Platform's Way](v0.39.2.md) — patch release of PR #49 and PR #48 (@rodrigoimmaginario), CR194, and CR193: `runtime diagnose` stops warning every Windows install about Node; a PowerShell byte-order mark is not stored; stdin is decoded by its mark, UTF-8 or UTF-16, and `identity set` and `journey update` gain `--file`, the route around PowerShell 5.1's ASCII pipe; `package-lock.json` names the package at its version, and the release doctor checks it. No migration.
 - [v0.39.1 — Pi Finds Its Node, or Says So](v0.39.1.md) — patch release of PR #47 (@rodrigoimmaginario) and CR191: a Pi opened where `node` is not on the PATH no longer exits; the Pi extension resolves Node where the hook wrappers look, so a global install needs nothing configured; when no Node resolves, one warning names the fix and `runtime diagnose` reports the `hooks.log` line. No migration.
 - [v0.39.0 — The Core as a Library](v0.39.0.md) — minor release of CV24's first eight Delivery Stories: `mirror-mind/desktop`, a library entry through which a host such as Mirror Desktop 0.3 embeds this core; calls for a home's migration state, Conversations, sidebar reads, home creation, migration on request, Mirror's context, learning from open Conversations, and Journey administration, each with an explicit path and no environment. The new `exports` field closes every other deep import. No migration.
 - [v0.38.1 — The Refusal Names the Way Out](v0.38.1.md) — patch release of three Change Requests, CR185, CR186, and CR187: a package with no home configured names the homes it finds and the `mirror init <name>` that selects one, and `init` adopts a home that already exists; a missing or refused OpenRouter key is one line that names the file, before anything is touched; a `stable` clone ahead only by `main`'s commits is told that `stable` is behind it, not to push or reset. No migration.

package/docs/releases/v0.39.2.md

@@ -0,0 +1,113 @@
+---
+digest: >
+  v0.39.2 is a patch release about input read the platform's way, most of it on Windows.
+  `runtime diagnose` stops warning every Windows install that Node is unresolvable, and a
+  PowerShell byte-order mark is no longer stored as identity content (PR #49, Rodrigo
+  Immaginario). From that review, CR194: text on stdin is decoded by its mark, UTF-8 or
+  UTF-16, and `identity set` and `journey update` gain `--file`, the route for any text
+  longer than a line and the only safe one on Windows PowerShell 5.1, whose pipe is ASCII.
+  `package-lock.json` names the package at its version after nine releases that left it
+  behind (PR #48), and the release doctor now checks it (CR193). No migration, and no model
+  or prompt change.
+---
+
+# v0.39.2 — Input, Read the Platform's Way
+
+**Date:** 2026-11-03
+
+## Highlights
+
+- **`runtime diagnose` no longer warns every Windows install that Node is unresolvable**
+  ([PR #49](https://github.com/mirror-mind-ai/mirror/pull/49), by @rodrigoimmaginario).
+  It split the `PATH` on `:` and looked for `node`; on Windows that is `;` and `node.exe`,
+  so nothing ever matched. It now looks the platform's way, and the test proves the Windows
+  branch on every host.
+- **A PowerShell byte-order mark is not content** (PR #49). `identity set` and
+  `journey update -` drop the one at the head of stdin instead of storing it as the first
+  character of an entry.
+- **Text on stdin is decoded by its mark, and `--file` reads a file as bytes**
+  ([CR194](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr194-powershell-stdin-reaches-identity-set-as-utf-16-or-ascii.md)).
+  UTF-16, as Windows PowerShell 5.1's `>` writes it, is read as UTF-16. The pipe's ASCII
+  default, which turns every accented letter into `?`, cannot be detected, so
+  `identity set <layer> <key> --file <path>` and `journey update <slug> --file <path>` read
+  the file themselves: the route for anything longer than a line on every platform, and
+  the only safe one on PowerShell 5.1. The troubleshooting page names the three PowerShell
+  behaviors and the way around each.
+- **`package-lock.json` names `mirror-mind` at the package's version**
+  ([PR #48](https://github.com/mirror-mind-ai/mirror/pull/48), by @rodrigoimmaginario),
+  with a test that keeps it so. Its root had said `mirror-core 0.0.0` through nine releases,
+  and the first `npm install` on any clone left the tree dirty.
+- **The release doctor fails on a lock left behind**
+  ([CR193](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr193-the-release-doctor-does-not-check-the-lockfile.md)),
+  before anything is tagged, naming the command that levels it. This is the first release it
+  checked.
+- No migration, and no model or prompt change.
+
+## Where We Started
+
+Rodrigo Immaginario's PRs #48 and #49 had waited since 2026-10-19 and 2026-10-21. One
+described a lockfile that nine releases in a row had left behind, each rebase of the PR
+proving it again, the last of them v0.39.1 the afternoon before it merged. The other
+described two inputs misread on Windows: a `PATH` split as if it were POSIX, so `runtime
+diagnose` prescribed `MIRROR_NODE` to every healthy Windows install, and a byte-order mark
+stored as the first character of an identity entry, repaired by hand on 2026-10-17.
+
+Both were merged as written, each with one maintainer commit: the lock brought to the
+current version so the PR's own test was green at merge, and `hookNodeFindings` given the
+platform as a parameter so the branch the PR exists for is proved on macOS and Ubuntu,
+where CI runs the suite, and not only on a Windows machine.
+
+The review of PR #49 found the two hazards the BOM fix sat beside. In Windows PowerShell
+5.1, `>` writes UTF-16LE, and the pipe to a native command goes through `$OutputEncoding`,
+whose default is ASCII: Portuguese text arrives with every accent as `?`, and Mirror stored
+what arrived. The second is not detectable — a `?` is a character — which is what shaped
+CR194.
+
+## What Changed
+
+**One decoder for human text** (`ts/src/frontDoor/textInput.ts`). A UTF-8 or UTF-16 mark
+at the head of the bytes chooses the decoding and is dropped; nothing else about the text
+is touched. UTF-16 without a mark is not guessed at. `identity set` and `journey update -`
+read stdin through it.
+
+**`--file`, the route around the pipe.** Mirror reads the file as bytes, so the shell never
+splits, substitutes, or re-encodes the text. `--file` beside `--content`, or beside `-`, is
+refused in one line; a path that cannot be read is refused naming the path and nothing from
+the error; nothing is written in either case. The skills present `--file` for anything
+longer than a line, and keep the pipe for one-liners.
+
+**`runtime diagnose` on Windows** looks for `node.exe` on a `;`-separated `PATH`, and only
+`node.exe`: on Windows the executable check is an existence check, and an extensionless
+`node` is nothing the system would run.
+
+**The lockfile.** Regenerated once with `npm install --package-lock-only --ignore-scripts`;
+`packageLock.test.ts` fails CI when its root and `package.json` disagree; the release doctor
+makes the same four comparisons before the tag exists, and the versioning page names the
+lock among what a release commit changes.
+
+Validated on 2026-11-03 against a scratch copy of the maintainer's database: UTF-8, UTF-8
+with a mark, and UTF-16LE as PowerShell 5.1 writes it, through `--file` and through stdin;
+the refusals writing nothing; the one-liner pipe unchanged.
+
+## Conscious Exclusions
+
+- Windows PowerShell 5.1 itself was not run: there is no Windows machine on the maintainer's
+  side. The decoder's cases are pinned byte for byte; a measurement on the OS is asked of
+  the reporter.
+- Detecting text the ASCII pipe damaged: not possible without guessing.
+- The hook wrappers and the MCP locator still accept a relative `MIRROR_NODE`
+  ([CR192](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr192-the-hook-wrappers-and-the-mcp-locator-accept-a-relative-mirror-node.md),
+  captured).
+- The JSON stdin readers (`conversations append`, the hooks' payloads) are unchanged: their
+  input comes from runtimes, which write UTF-8 without a mark.
+
+## Upgrading
+
+```bash
+mirror runtime update
+```
+
+## Next Horizon
+
+Rodrigo Immaginario's PRs #50, #53, and #54, all Windows and packaging; CR190 and CR192 in
+RS010's backlog. CV24 continues on its branch.

package/docs/releases/v0.39.3.md

@@ -0,0 +1,94 @@
+---
+digest: >
+  v0.39.3 is a patch release of three pull requests by Rodrigo Immaginario. On a Windows
+  package install, npm's global `mirror` and `mirror-hook` are shell shims, and the plugin's
+  hook wrappers and MCP locator handed them to Node: no Claude Code conversation was ever
+  logged there, and the MCP server died on arrival. They now run the package's own bin
+  (PR #53). `runtime diagnose` no longer counts its own "attention needed" exit as a
+  front-door error, so the finding stops feeding itself (PR #50, CR139). The docs point a
+  Windows reader to the installer that now lives in its own repository (PR #54). No
+  migration, and no model or prompt change.
+---
+
+# v0.39.3 — Windows Gets Its Hooks
+
+**Date:** 2026-11-03
+
+## Highlights
+
+- **Claude Code hooks and the MCP server work on a Windows package install**
+  ([PR #53](https://github.com/mirror-mind-ai/mirror/pull/53), by @rodrigoimmaginario). On
+  Windows npm writes no symlink: its global `mirror-hook` and `mirror` are POSIX shell
+  shims with `node_modules/` beside them. Handed to Node, the shim ran as JavaScript:
+  every hook ended `node exited 1` in `hooks.log`, and the MCP server died with a
+  `SyntaxError` from the shim's second line. The wrappers and the locator now run the bin
+  the shim wraps, one fixed path away, when it is there. A POSIX prefix is unchanged.
+- **`runtime diagnose` no longer counts its own verdict as a front-door error**
+  ([PR #50](https://github.com/mirror-mind-ai/mirror/pull/50), by @rodrigoimmaginario;
+  [CR139](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr139-a-verdict-that-exits-1-is-logged-as-a-front-door-error.md)).
+  Its exit 1 means "attention needed", a contract with scripts, and the front door logged
+  it as `ERROR`, which `front_door_errors` then counted: one more error per run, a finding
+  that could never clear. The exit is now logged at `INFO` as a verdict; a real failure of
+  the same command stays `ERROR`.
+- **A Windows reader is pointed to the installer**
+  ([PR #54](https://github.com/mirror-mind-ai/mirror/pull/54), by @rodrigoimmaginario):
+  [mirror-mind-ai/mirror-installer](https://github.com/mirror-mind-ai/mirror-installer), a
+  per-user installer in its own repository, from README, Getting Started, and REFERENCE's
+  platform envelope. The envelope itself is unchanged: this repository ships no Windows
+  product, and POSIX is what is supported.
+- No migration, and no model or prompt change.
+
+## Where We Started
+
+v0.39.2 shipped the morning's Windows fixes: `runtime diagnose` reading the PATH the
+platform's way, and PowerShell's marks and encodings on stdin. Three of Rodrigo's PRs
+remained, and the largest of them was the one that mattered most: on a Windows package
+install, Mirror's Claude Code integration had never worked, and nothing said so but
+`hooks.log`.
+
+The diagnose loop in PR #50 had been in the backlog three times over, CR127, CR139, and
+CR176, the last two captured without finding the first. The PR implements CR139's first
+option as written, arrived at independently. CR139 is done with Rodrigo as its Driver;
+CR127 and CR176 are closed as its duplicates.
+
+## What Changed
+
+**The shim rule, in the two generators.** `scripts/generate_hook_wrappers.sh` and
+`MCP_LOCATOR` in `ts/src/guards/claudePlugin.ts` each gain one rule: when
+`<dir of the entry>/node_modules/mirror-mind/bin/<entry>.js` exists, that is the entry.
+The twelve wrappers and manifests are regenerated from it, and regenerating on the merge
+leaves the tree unchanged. A hook test models the Windows prefix on POSIX with a fake
+Node that records the entry it was handed; a maintainer commit added the locator's
+run-as-written case, which fails on the previous locator.
+
+**The verdict, beside the command.** `isRuntimeVerdict` in `runtimeRoute.ts` says which
+exit is an answer; the dispatcher asks it. A maintainer commit moved the rule there from
+the dispatcher, and made the end-to-end test's finding sure on purpose (`loose_permissions`
+by `chmod`), since v0.39.1's Node search no longer guarantees the one the test had relied
+on.
+
+## Conscious Exclusions
+
+- Windows is not a supported platform of this repository: CI runs the suite on macOS and
+  Ubuntu, and the Windows job runs two files. The installer repository pins the core it
+  tests against. Whether that changes is a later decision.
+- The front-door log's `route=usage` lines still count as errors (CR139's second option,
+  not taken). On the maintainer's home every such line comes from the test suite:
+  [CR195](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr195-the-test-suite-writes-four-lines-into-the-real-home-s-front-door-log.md),
+  captured.
+- One macOS CI run on PR #54 failed in the updater smoke's package lane with a bare exit
+  1 and passed on re-run. Noted; not yet understood.
+
+## Upgrading
+
+```bash
+mirror runtime update
+```
+
+On Windows, the installer at mirror-mind-ai/mirror-installer pins the core version it
+ships; this release is the one its Claude Code hooks need.
+
+## Next Horizon
+
+Alan Nascimento's PR #51 (the stop hook losing a reply) and Moacir Moda's PR #27; CR190,
+CR192, and CR195 in RS010's backlog. CV24 continues on its branch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.39.1",
+  "version": "0.39.3",
   "description": "Mirror Mind: a local-first memory and identity framework for agentic AI runtimes (Pi, Claude Code, Codex, Antigravity)",
   "license": "MIT",
   "repository": {

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

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.39.1",
+  "version": "0.39.3",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
   "author": {
     "name": "Mirror Mind"
@@ -10,7 +10,7 @@
       "command": "/bin/sh",
       "args": [
         "-c",
-        "mmbin=\"\"; [ -n \"$MIRROR_BIN\" ] && [ -x \"$MIRROR_BIN/mirror\" ] && mmbin=\"$MIRROR_BIN/mirror\"; [ -n \"$mmbin\" ] || mmbin=\"$(command -v mirror 2>/dev/null)\"; for mmdir in \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmbin\" ] && break; [ -x \"$mmdir/mirror\" ] && mmbin=\"$mmdir/mirror\"; done; [ -n \"$mmbin\" ] || { echo \"mirror-mind: mirror not found on PATH; the MCP server cannot start. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory.\" >&2; exit 1; }; mmnode=\"$MIRROR_NODE\"; [ -n \"$mmnode\" ] && [ -x \"$mmnode\" ] || mmnode=\"$(command -v node 2>/dev/null)\"; for mmdir in \"$(dirname \"$mmbin\")\" \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmnode\" ] && break; [ -x \"$mmdir/node\" ] && mmnode=\"$mmdir/node\"; done; [ -n \"$mmnode\" ] || { echo \"mirror-mind: node not found on PATH; the MCP server cannot start. Set MIRROR_NODE.\" >&2; exit 1; }; exec \"$mmnode\" \"$mmbin\" mcp"
+        "mmbin=\"\"; [ -n \"$MIRROR_BIN\" ] && [ -x \"$MIRROR_BIN/mirror\" ] && mmbin=\"$MIRROR_BIN/mirror\"; [ -n \"$mmbin\" ] || mmbin=\"$(command -v mirror 2>/dev/null)\"; for mmdir in \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmbin\" ] && break; [ -x \"$mmdir/mirror\" ] && mmbin=\"$mmdir/mirror\"; done; [ -n \"$mmbin\" ] || { echo \"mirror-mind: mirror not found on PATH; the MCP server cannot start. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory.\" >&2; exit 1; }; mmjs=\"$(dirname \"$mmbin\")/node_modules/mirror-mind/bin/mirror.js\"; [ -f \"$mmjs\" ] && mmbin=\"$mmjs\"; mmnode=\"$MIRROR_NODE\"; [ -n \"$mmnode\" ] && [ -x \"$mmnode\" ] || mmnode=\"$(command -v node 2>/dev/null)\"; for mmdir in \"$(dirname \"$mmbin\")\" \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmnode\" ] && break; [ -x \"$mmdir/node\" ] && mmnode=\"$mmdir/node\"; done; [ -n \"$mmnode\" ] || { echo \"mirror-mind: node not found on PATH; the MCP server cannot start. Set MIRROR_NODE.\" >&2; exit 1; }; exec \"$mmnode\" \"$mmbin\" mcp"
       ]
     }
   }

package/plugins/mirror-mind/agy/pre-invocation.sh

@@ -61,6 +61,14 @@ 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
+# On Windows npm writes no symlink: the `mirror-hook` in its global prefix is
+# a POSIX shell shim, and `node_modules/` sits beside it. Node cannot run the
+# shim ("node exited 1" in hooks.log on every hook); the entry it wraps is the
+# package's own bin, so that is the entry when it is there. A POSIX prefix
+# keeps node_modules under lib/ and its bin is already the .js: no change.
+shim_entry=""
+[ -n "$ENTRY" ] && shim_entry="$(dirname "$ENTRY")/node_modules/mirror-mind/bin/mirror-hook.js"
+[ -n "$shim_entry" ] && [ -f "$shim_entry" ] && ENTRY="$shim_entry"
 
 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."

package/plugins/mirror-mind/agy/session-start.sh

@@ -61,6 +61,14 @@ 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
+# On Windows npm writes no symlink: the `mirror-hook` in its global prefix is
+# a POSIX shell shim, and `node_modules/` sits beside it. Node cannot run the
+# shim ("node exited 1" in hooks.log on every hook); the entry it wraps is the
+# package's own bin, so that is the entry when it is there. A POSIX prefix
+# keeps node_modules under lib/ and its bin is already the .js: no change.
+shim_entry=""
+[ -n "$ENTRY" ] && shim_entry="$(dirname "$ENTRY")/node_modules/mirror-mind/bin/mirror-hook.js"
+[ -n "$shim_entry" ] && [ -f "$shim_entry" ] && ENTRY="$shim_entry"
 
 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."

package/plugins/mirror-mind/agy/stop.sh

@@ -61,6 +61,14 @@ 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
+# On Windows npm writes no symlink: the `mirror-hook` in its global prefix is
+# a POSIX shell shim, and `node_modules/` sits beside it. Node cannot run the
+# shim ("node exited 1" in hooks.log on every hook); the entry it wraps is the
+# package's own bin, so that is the entry when it is there. A POSIX prefix
+# keeps node_modules under lib/ and its bin is already the .js: no change.
+shim_entry=""
+[ -n "$ENTRY" ] && shim_entry="$(dirname "$ENTRY")/node_modules/mirror-mind/bin/mirror-hook.js"
+[ -n "$shim_entry" ] && [ -f "$shim_entry" ] && ENTRY="$shim_entry"
 
 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."

package/plugins/mirror-mind/hooks/log-assistant-reply.sh

@@ -56,6 +56,14 @@ 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
+# On Windows npm writes no symlink: the `mirror-hook` in its global prefix is
+# a POSIX shell shim, and `node_modules/` sits beside it. Node cannot run the
+# shim ("node exited 1" in hooks.log on every hook); the entry it wraps is the
+# package's own bin, so that is the entry when it is there. A POSIX prefix
+# keeps node_modules under lib/ and its bin is already the .js: no change.
+shim_entry=""
+[ -n "$ENTRY" ] && shim_entry="$(dirname "$ENTRY")/node_modules/mirror-mind/bin/mirror-hook.js"
+[ -n "$shim_entry" ] && [ -f "$shim_entry" ] && ENTRY="$shim_entry"
 
 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."

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

@@ -56,6 +56,14 @@ 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
+# On Windows npm writes no symlink: the `mirror-hook` in its global prefix is
+# a POSIX shell shim, and `node_modules/` sits beside it. Node cannot run the
+# shim ("node exited 1" in hooks.log on every hook); the entry it wraps is the
+# package's own bin, so that is the entry when it is there. A POSIX prefix
+# keeps node_modules under lib/ and its bin is already the .js: no change.
+shim_entry=""
+[ -n "$ENTRY" ] && shim_entry="$(dirname "$ENTRY")/node_modules/mirror-mind/bin/mirror-hook.js"
+[ -n "$shim_entry" ] && [ -f "$shim_entry" ] && ENTRY="$shim_entry"
 
 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."

package/plugins/mirror-mind/hooks/log-user-prompt.sh

@@ -56,6 +56,14 @@ 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
+# On Windows npm writes no symlink: the `mirror-hook` in its global prefix is
+# a POSIX shell shim, and `node_modules/` sits beside it. Node cannot run the
+# shim ("node exited 1" in hooks.log on every hook); the entry it wraps is the
+# package's own bin, so that is the entry when it is there. A POSIX prefix
+# keeps node_modules under lib/ and its bin is already the .js: no change.
+shim_entry=""
+[ -n "$ENTRY" ] && shim_entry="$(dirname "$ENTRY")/node_modules/mirror-mind/bin/mirror-hook.js"
+[ -n "$shim_entry" ] && [ -f "$shim_entry" ] && ENTRY="$shim_entry"
 
 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."

package/plugins/mirror-mind/hooks/mirror-inject.sh

@@ -56,6 +56,14 @@ 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
+# On Windows npm writes no symlink: the `mirror-hook` in its global prefix is
+# a POSIX shell shim, and `node_modules/` sits beside it. Node cannot run the
+# shim ("node exited 1" in hooks.log on every hook); the entry it wraps is the
+# package's own bin, so that is the entry when it is there. A POSIX prefix
+# keeps node_modules under lib/ and its bin is already the .js: no change.
+shim_entry=""
+[ -n "$ENTRY" ] && shim_entry="$(dirname "$ENTRY")/node_modules/mirror-mind/bin/mirror-hook.js"
+[ -n "$shim_entry" ] && [ -f "$shim_entry" ] && ENTRY="$shim_entry"
 
 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."

package/plugins/mirror-mind/hooks/session-start.sh

@@ -56,6 +56,14 @@ 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
+# On Windows npm writes no symlink: the `mirror-hook` in its global prefix is
+# a POSIX shell shim, and `node_modules/` sits beside it. Node cannot run the
+# shim ("node exited 1" in hooks.log on every hook); the entry it wraps is the
+# package's own bin, so that is the entry when it is there. A POSIX prefix
+# keeps node_modules under lib/ and its bin is already the .js: no change.
+shim_entry=""
+[ -n "$ENTRY" ] && shim_entry="$(dirname "$ENTRY")/node_modules/mirror-mind/bin/mirror-hook.js"
+[ -n "$shim_entry" ] && [ -f "$shim_entry" ] && ENTRY="$shim_entry"
 
 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."

package/plugins/mirror-mind/mcp_config.json

@@ -4,7 +4,7 @@
       "command": "/bin/sh",
       "args": [
         "-c",
-        "mmbin=\"\"; [ -n \"$MIRROR_BIN\" ] && [ -x \"$MIRROR_BIN/mirror\" ] && mmbin=\"$MIRROR_BIN/mirror\"; [ -n \"$mmbin\" ] || mmbin=\"$(command -v mirror 2>/dev/null)\"; for mmdir in \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmbin\" ] && break; [ -x \"$mmdir/mirror\" ] && mmbin=\"$mmdir/mirror\"; done; [ -n \"$mmbin\" ] || { echo \"mirror-mind: mirror not found on PATH; the MCP server cannot start. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory.\" >&2; exit 1; }; mmnode=\"$MIRROR_NODE\"; [ -n \"$mmnode\" ] && [ -x \"$mmnode\" ] || mmnode=\"$(command -v node 2>/dev/null)\"; for mmdir in \"$(dirname \"$mmbin\")\" \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmnode\" ] && break; [ -x \"$mmdir/node\" ] && mmnode=\"$mmdir/node\"; done; [ -n \"$mmnode\" ] || { echo \"mirror-mind: node not found on PATH; the MCP server cannot start. Set MIRROR_NODE.\" >&2; exit 1; }; exec \"$mmnode\" \"$mmbin\" mcp"
+        "mmbin=\"\"; [ -n \"$MIRROR_BIN\" ] && [ -x \"$MIRROR_BIN/mirror\" ] && mmbin=\"$MIRROR_BIN/mirror\"; [ -n \"$mmbin\" ] || mmbin=\"$(command -v mirror 2>/dev/null)\"; for mmdir in \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmbin\" ] && break; [ -x \"$mmdir/mirror\" ] && mmbin=\"$mmdir/mirror\"; done; [ -n \"$mmbin\" ] || { echo \"mirror-mind: mirror not found on PATH; the MCP server cannot start. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory.\" >&2; exit 1; }; mmjs=\"$(dirname \"$mmbin\")/node_modules/mirror-mind/bin/mirror.js\"; [ -f \"$mmjs\" ] && mmbin=\"$mmjs\"; mmnode=\"$MIRROR_NODE\"; [ -n \"$mmnode\" ] && [ -x \"$mmnode\" ] || mmnode=\"$(command -v node 2>/dev/null)\"; for mmdir in \"$(dirname \"$mmbin\")\" \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmnode\" ] && break; [ -x \"$mmdir/node\" ] && mmnode=\"$mmdir/node\"; done; [ -n \"$mmnode\" ] || { echo \"mirror-mind: node not found on PATH; the MCP server cannot start. Set MIRROR_NODE.\" >&2; exit 1; }; exec \"$mmnode\" \"$mmbin\" mcp"
       ]
     }
   }

package/plugins/mirror-mind/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "mirror-mind",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
-  "version": "0.39.1",
+  "version": "0.39.3",
   "mcpServers": {
     "mirror-mind": {
       "command": "/bin/sh",
       "args": [
         "-c",
-        "mmbin=\"\"; [ -n \"$MIRROR_BIN\" ] && [ -x \"$MIRROR_BIN/mirror\" ] && mmbin=\"$MIRROR_BIN/mirror\"; [ -n \"$mmbin\" ] || mmbin=\"$(command -v mirror 2>/dev/null)\"; for mmdir in \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmbin\" ] && break; [ -x \"$mmdir/mirror\" ] && mmbin=\"$mmdir/mirror\"; done; [ -n \"$mmbin\" ] || { echo \"mirror-mind: mirror not found on PATH; the MCP server cannot start. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory.\" >&2; exit 1; }; mmnode=\"$MIRROR_NODE\"; [ -n \"$mmnode\" ] && [ -x \"$mmnode\" ] || mmnode=\"$(command -v node 2>/dev/null)\"; for mmdir in \"$(dirname \"$mmbin\")\" \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmnode\" ] && break; [ -x \"$mmdir/node\" ] && mmnode=\"$mmdir/node\"; done; [ -n \"$mmnode\" ] || { echo \"mirror-mind: node not found on PATH; the MCP server cannot start. Set MIRROR_NODE.\" >&2; exit 1; }; exec \"$mmnode\" \"$mmbin\" mcp"
+        "mmbin=\"\"; [ -n \"$MIRROR_BIN\" ] && [ -x \"$MIRROR_BIN/mirror\" ] && mmbin=\"$MIRROR_BIN/mirror\"; [ -n \"$mmbin\" ] || mmbin=\"$(command -v mirror 2>/dev/null)\"; for mmdir in \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmbin\" ] && break; [ -x \"$mmdir/mirror\" ] && mmbin=\"$mmdir/mirror\"; done; [ -n \"$mmbin\" ] || { echo \"mirror-mind: mirror not found on PATH; the MCP server cannot start. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory.\" >&2; exit 1; }; mmjs=\"$(dirname \"$mmbin\")/node_modules/mirror-mind/bin/mirror.js\"; [ -f \"$mmjs\" ] && mmbin=\"$mmjs\"; mmnode=\"$MIRROR_NODE\"; [ -n \"$mmnode\" ] && [ -x \"$mmnode\" ] || mmnode=\"$(command -v node 2>/dev/null)\"; for mmdir in \"$(dirname \"$mmbin\")\" \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; do [ -n \"$mmnode\" ] && break; [ -x \"$mmdir/node\" ] && mmnode=\"$mmdir/node\"; done; [ -n \"$mmnode\" ] || { echo \"mirror-mind: node not found on PATH; the MCP server cannot start. Set MIRROR_NODE.\" >&2; exit 1; }; exec \"$mmnode\" \"$mmbin\" mcp"
       ]
     }
   }

package/plugins/mirror-mind/skills/mm-identity/SKILL.md

@@ -59,9 +59,15 @@ Update identity content directly in the database.
 
 ```bash
 mirror identity set <layer> <key> --content "..." [--mirror-home PATH]
+mirror identity set <layer> <key> --file <path>  [--mirror-home PATH]
 ```
 
-If `--content` is omitted, content is read from stdin.
+If neither `--content` nor `--file` is given, content is read from stdin.
+
+For anything longer than a line, write the text to a file and pass `--file`:
+Mirror reads it as bytes, so the shell never splits, substitutes, or re-encodes
+it. On Windows PowerShell 5.1 it is the only safe route: the pipe is ASCII by
+default and turns every accented letter into `?`. The pipe stays for one-liners.
 
 A new `journey` or `persona` key must be kebab-case: lowercase letters, digits,
 and single hyphens, up to 80 characters, such as `product-launch`. Agents put
@@ -70,7 +76,8 @@ one that would work. A key created before this rule keeps working.
 
 **Examples:**
 - `mirror identity set ego behavior --content "Be direct."`
-- `cat new-soul.md | mirror identity set self soul`
+- `mirror identity set self soul --file new-soul.md`
+- `echo "Be direct." | mirror identity set ego behavior` (a one-liner; not on PowerShell 5.1)
 
 ---
 

package/plugins/mirror-mind/skills/mm-journey/SKILL.md

@@ -30,7 +30,15 @@ If the journey path appears outdated relative to recent conversations and memori
 mirror journey update JOURNEY "UPDATED_CONTENT"
 ```
 
-For long content, use stdin:
+For anything longer than a line, write it to a file and pass `--file`: Mirror
+reads it as bytes, untouched by the shell (on Windows PowerShell 5.1 the pipe
+is ASCII by default, and this is the only safe route):
+
+```bash
+mirror journey update JOURNEY --file PATH
+```
+
+A one-liner can go through stdin:
 
 ```bash
 echo "CONTENT" | mirror journey update JOURNEY -

package/ts/src/frontDoor/cli.ts

@@ -80,6 +80,7 @@ import { configFilePath, loadConfiguration, silenceExperimentalWarnings } from "
 import { runSeed } from "#seed/seed.ts";
 import { getTasksForWeek, listTasks } from "#tasks/taskStore.ts";
 import { computeWeekRange } from "#tasks/weekView.ts";
+import { expandHome } from "#util/paths.ts";
 import { PROGRAM } from "#util/program.ts";
 import { newId, nowIso } from "#util/pyGenerators.ts";
 import { hasOption, optionValue, stripOptionWithValue } from "./args.ts";
@@ -169,7 +170,7 @@ import {
 } from "./render/tasksImportSync.ts";
 import { renderWeekView } from "./render/week.ts";
 import { retiredRefusal, routeMemoryCommand } from "./routing.ts";
-import { runRuntimeReadRoute, runWelcomeRoute } from "./runtimeRoute.ts";
+import { isRuntimeVerdict, runRuntimeReadRoute, runWelcomeRoute } from "./runtimeRoute.ts";
 import { runMemorySearchRoute } from "./searchRoute.ts";
 import { resolveSeedPaths } from "./seedPaths.ts";
 import { isSessionStartWelcome, runSessionStartWelcomeRoute } from "./sessionStartWelcomeRoute.ts";
@@ -187,6 +188,7 @@ import {
   applyTasksStatusChange,
   type TaskStatusTarget,
 } from "./tasksWriteRoute.ts";
+import { readStdinText, readTextFile } from "./textInput.ts";
 import { answerUsage } from "./usage.ts";
 
 /**
@@ -522,12 +524,19 @@ function runShadowRead(db: Database, args: readonly string[]): number {
   return 0;
 }
 
+/** Stdin as human text, decoded by its mark (PR #49, CR194: `textInput.ts`). */
 function readStdinContent(): string {
-  try {
-    return readFileSync(0, "utf8");
-  } catch {
-    return "";
-  }
+  return readStdinText();
+}
+
+/**
+ * CR194: `--file <path>`, the text read by Mirror as bytes, so the shell's pipe
+ * never touches it (PowerShell 5.1's pipe is ASCII by default, and its `>` is
+ * UTF-16LE). `~` expands as it does for `--mirror-home`; a relative path is
+ * the cwd's. The refusal names the path and nothing from the error.
+ */
+function readFileContent(path: string): { text: string } | { error: string } {
+  return readTextFile(expandHome(path));
 }
 
 /** `conversations append` (CV22.DS7.US10 slice B′). */
@@ -840,7 +849,10 @@ function refusedNewIdentityKey(args: readonly string[], layer: string, key: stri
 function runIdentityWrite(argv: readonly string[]): number {
   const args = argv.slice(2);
   const positionals = stripOptionWithValue(
-    stripOptionWithValue(stripOptionWithValue(args, "--content"), "--db-path"),
+    stripOptionWithValue(
+      stripOptionWithValue(stripOptionWithValue(args, "--content"), "--file"),
+      "--db-path",
+    ),
     "--mirror-home",
   );
   const layer = positionals[0];
@@ -854,7 +866,23 @@ function runIdentityWrite(argv: readonly string[]): number {
     console.error(`Error: ${refused}`);
     return 1;
   }
-  const content = optionValue(args, "--content") ?? readStdinContent();
+  const inlineContent = optionValue(args, "--content");
+  const filePath = optionValue(args, "--file");
+  if (inlineContent !== null && filePath !== null) {
+    console.error("Error: --file and --content name two sources for one content; pass one.");
+    return 1;
+  }
+  let content: string;
+  if (filePath !== null) {
+    const read = readFileContent(filePath);
+    if ("error" in read) {
+      console.error(`Error: ${read.error}`);
+      return 1;
+    }
+    content = read.text;
+  } else {
+    content = inlineContent ?? readStdinContent();
+  }
   if (!content.trim()) {
     console.error("Error: content is empty.");
     return 1;
@@ -1007,22 +1035,36 @@ function runJourneyWrite(argv: readonly string[]): number {
  */
 const JOURNEY_UPDATE_USAGE =
   `Usage: ${PROGRAM} journey update <slug> <content>\n` +
-  "       Pass '-' as <content> to read it from stdin.";
+  "       Pass '-' as <content> to read it from stdin, or --file <path> to read a file.";
 const FLAG_SHAPED_CONTENT = /^--?[A-Za-z]/;
 
 function runJourneyUpdateWrite(argv: readonly string[]): number {
   const args = argv.slice(2);
   const positionals = stripOptionWithValue(
-    stripOptionWithValue(args, "--db-path"),
+    stripOptionWithValue(stripOptionWithValue(args, "--file"), "--db-path"),
     "--mirror-home",
   );
   const slug = positionals[0];
   let content = positionals[1];
-  if (!slug || content === undefined) {
+  const filePath = optionValue(args, "--file");
+  if (!slug || (content === undefined && filePath === null)) {
     console.error(JOURNEY_UPDATE_USAGE);
     return 1;
   }
-  if (content === "-") {
+  if (filePath !== null) {
+    if (content !== undefined) {
+      console.error(
+        `Error: --file and ${content === "-" ? "'-'" : "<content>"} name two sources for one content; pass one.`,
+      );
+      return 1;
+    }
+    const read = readFileContent(filePath);
+    if ("error" in read) {
+      console.error(`Error: ${read.error}`);
+      return 1;
+    }
+    content = read.text;
+  } else if (content === "-") {
     content = readStdinContent();
   } else if (FLAG_SHAPED_CONTENT.test(content)) {
     console.error(
@@ -1669,6 +1711,8 @@ interface DispatchOutcome {
   exitCode: number;
   /** Content-free route metadata for the durable front-door log. */
   detail?: string;
+  /** The non-zero exit is the command's answer, not a failure (`frontDoorLog.ts`). */
+  verdict?: boolean;
 }
 
 async function dispatch(argv: readonly string[]): Promise<DispatchOutcome> {
@@ -1777,7 +1821,13 @@ async function dispatchTs(argv: readonly string[]): Promise<number | DispatchOut
   // database, when at all, through a read-only handle -- no bootstrap, no
   // migrate-on-open, and for `welcome --status-line` no subprocess whatsoever.
   if (argv[0] === "welcome") return runWelcomeRoute(argv);
-  if (argv[0] === "runtime") return runRuntimeReadRoute(argv);
+  if (argv[0] === "runtime") {
+    const exitCode = await runRuntimeReadRoute(argv);
+    // A verdict, not a failure: `isRuntimeVerdict` says which (CR139).
+    return isRuntimeVerdict(argv, exitCode)
+      ? { exitCode, detail: "verdict=attention", verdict: true }
+      : exitCode;
+  }
   if (argv[0] === "mcp") return runMcpServer();
   if (isMemorySearch(argv)) return runMemorySearch(argv);
   if (isConsult(argv)) {
@@ -1853,6 +1903,7 @@ export async function main(rawArgv = process.argv.slice(2)): Promise<number> {
       route: decision.engine,
       exitCode: outcome.exitCode,
       ...(outcome.detail ? { detail: outcome.detail } : {}),
+      ...(outcome.verdict ? { verdict: true } : {}),
     });
     return outcome.exitCode;
   } catch (error) {

package/ts/src/frontDoor/frontDoorLog.ts

@@ -29,6 +29,13 @@ export interface FrontDoorLogEntry {
   exitCode: number;
   /** A short, content-free note or error category. Never argument values. */
   detail?: string;
+  /**
+   * The non-zero exit is the command's answer, not a failure: `runtime
+   * diagnose` exits 1 to say "attention needed". Logged at INFO, so the line
+   * does not count as a front-door error -- which `front_door_errors` reads,
+   * and which each diagnose with findings then fed, one line per run.
+   */
+  verdict?: boolean;
 }
 
 /** The log path for a resolved database path (sibling of the DB). */
@@ -40,7 +47,7 @@ export function frontDoorLogPath(dbPath: string): string {
 export function logFrontDoor(logPath: string | null, entry: FrontDoorLogEntry): void {
   if (!logPath) return;
   try {
-    const level = entry.exitCode === 0 ? "INFO" : "ERROR";
+    const level = entry.exitCode === 0 || entry.verdict ? "INFO" : "ERROR";
     const detail = entry.detail ? entry.detail.replace(/[\r\n\t]+/g, " ") : "";
     const line = [
       new Date().toISOString(),

package/ts/src/frontDoor/runtimeRoute.ts

@@ -254,6 +254,17 @@ function logWelcomeCheck(home: string, env: NodeJS.ProcessEnv, check: RemoteChec
 }
 
 /** Port of the read half of `cmd_runtime`. */
+/**
+ * `runtime diagnose` exits 1 to say "attention needed": its contract with
+ * scripts, not a failure. The front door logs that exit as a verdict (PR #50,
+ * CR139), at INFO, so `front_door_errors` does not count the diagnose that
+ * reported it -- every diagnose with findings used to feed the finding, one
+ * line per run. The rule lives here, beside the command whose contract it is.
+ */
+export function isRuntimeVerdict(argv: readonly string[], exitCode: number): boolean {
+  return argv[0] === "runtime" && argv[1] === "diagnose" && exitCode === 1;
+}
+
 export async function runRuntimeReadRoute(
   argv: readonly string[],
   io: InstallRouteIo = {},

package/ts/src/frontDoor/textInput.ts

@@ -0,0 +1,55 @@
+// Human text that reaches the front door as bytes: stdin behind `identity set`
+// and `journey update -`, and the file behind `--file` (CR194).
+//
+// The bytes carry no encoding but what their first bytes say. PowerShell 5.1
+// writes a UTF-8 mark at the head of what it pipes (PR #49) and UTF-16LE from
+// `>`; an editor writes UTF-8 with or without a mark. The mark is an encoding's
+// signature, not content: it chooses the decoding and is dropped. UTF-16
+// without a mark is not detectable and is not attempted: a guess about bytes
+// would be wrong about some file, silently.
+//
+// What the ASCII pipe does to a text (`$OutputEncoding` in PowerShell 5.1
+// turns every accented letter into `?`) is not detectable either: a `?` is a
+// character. `--file` is the route that never meets the pipe.
+
+import { readFileSync } from "node:fs";
+
+/** The text the bytes carry, by their mark; the mark itself is never returned. */
+export function decodeTextInput(bytes: Buffer): string {
+  if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) {
+    return bytes.subarray(2).toString("utf16le");
+  }
+  if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+    const payload = Buffer.from(bytes.subarray(2));
+    // An odd trailing byte is not a code unit; `swap16` refuses it.
+    return (payload.length % 2 === 0 ? payload : payload.subarray(0, payload.length - 1))
+      .swap16()
+      .toString("utf16le");
+  }
+  if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+    return bytes.subarray(3).toString("utf8");
+  }
+  return bytes.toString("utf8");
+}
+
+/** Stdin to its end, decoded; "" when there is none. */
+export function readStdinText(): string {
+  try {
+    return decodeTextInput(readFileSync(0));
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The file behind `--file`, decoded; or the one-line refusal. The line names
+ * the path and nothing from the error: a directory, a missing file, and a
+ * permission refused all read the same to the person, and `errno` is noise.
+ */
+export function readTextFile(path: string): { text: string } | { error: string } {
+  try {
+    return { text: decodeTextInput(readFileSync(path)) };
+  } catch {
+    return { error: `cannot read ${path}` };
+  }
+}

package/ts/src/guards/claudePlugin.ts

@@ -111,6 +111,11 @@ export const MCP_LOCATOR = [
   '[ -n "$mmbin" ] || mmbin="$(command -v mirror 2>/dev/null)"',
   `for mmdir in ${GLOBAL_BIN_DIRS.join(" ")}; do [ -n "$mmbin" ] && break; [ -x "$mmdir/mirror" ] && mmbin="$mmdir/mirror"; done`,
   '[ -n "$mmbin" ] || { echo "mirror-mind: mirror not found on PATH; the MCP server cannot start. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory." >&2; exit 1; }',
+  // On Windows npm's global `mirror` is a POSIX shell shim with node_modules/
+  // beside it, and Node cannot run the shim; the package's own bin is the
+  // entry when it is there (a POSIX prefix keeps node_modules under lib/).
+  'mmjs="$(dirname "$mmbin")/node_modules/mirror-mind/bin/mirror.js"',
+  '[ -f "$mmjs" ] && mmbin="$mmjs"',
   'mmnode="$MIRROR_NODE"',
   '[ -n "$mmnode" ] && [ -x "$mmnode" ] || mmnode="$(command -v node 2>/dev/null)"',
   `for mmdir in "$(dirname "$mmbin")" ${GLOBAL_BIN_DIRS.join(" ")}; do [ -n "$mmnode" ] && break; [ -x "$mmdir/node" ] && mmnode="$mmdir/node"; done`,

package/ts/src/runtime/diagnose.ts

@@ -25,7 +25,7 @@
 // inconclusive without a key; the live fetch belongs to DS8.
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, posix, win32 } from "node:path";
 import { openDatabaseReadOnly } from "#db/database.ts";
 import {
   type ExtensionPluginReport,
@@ -913,16 +913,24 @@ export function hookFailureFindings(
 export function hookNodeFindings(
   env: NodeJS.ProcessEnv,
   isExecutable: (path: string) => boolean,
+  platform: NodeJS.Platform = process.platform,
 ): DriftFinding[] {
   const explicit = env.MIRROR_NODE ?? "";
   if (explicit && isExecutable(explicit)) return [];
   const candidates = HOOK_NODE_CANDIDATES.map((candidate) =>
     candidate.replace("$HOME", env.HOME ?? ""),
   );
+  // The platform's PATH separator and its executable name: `;` and `node.exe`
+  // on Windows, where splitting on `:` cut `C:\Program Files\nodejs` into `C`
+  // and a path and the finding fired on every install that had Node (PR #49).
+  // `platform` is a parameter so the test runs both branches on every host:
+  // CI's Windows job runs two files and this one is not among them.
+  const paths = platform === "win32" ? win32 : posix;
+  const name = platform === "win32" ? "node.exe" : "node";
   const onPath = (env.PATH ?? "")
-    .split(":")
+    .split(paths.delimiter)
     .filter(Boolean)
-    .some((entry) => isExecutable(`${entry}/node`));
+    .some((entry) => isExecutable(paths.join(entry, name)));
   if (onPath || candidates.some((candidate) => isExecutable(candidate))) return [];
   return [
     {