mirror-mind 0.39.0 → 0.39.2

package/.pi/extensions/mirror-logger.ts

@@ -43,6 +43,14 @@
  * it supplies the Operating Instructions (`AGENTS.md`) itself (D13), and says
  * so once when `mirror` is not on the PATH.
  *
+ * The `node` it runs the core on is resolved as the hook wrappers resolve
+ * theirs (CR191): `MIRROR_NODE`, the PATH, the Node that installed the
+ * package, then nvm, Homebrew, and `/usr/local`. A GUI-launched Pi, or one from
+ * a window older than the Node install, has none on its PATH. When nothing
+ * resolves the session says so once, names the fix, and writes one line to
+ * `<mirror home>/hooks.log`, where `runtime diagnose` reads it; it spawns
+ * nothing, and Pi stays up.
+ *
  * External skill prep note:
  * Pi reads installed external skills from
  *   ~/.mirror-minds/<user>/runtime/skills/pi/extensions.json
@@ -52,7 +60,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { accessSync, appendFileSync, closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { delimiter, dirname, join } from "node:path";
+import { delimiter, dirname, join, posix, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -180,6 +188,95 @@ function _mirrorOnPath(): string | null {
 	return null;
 }
 
+/**
+ * Where a hook wrapper looks for Node after `MIRROR_NODE`, the PATH, and the
+ * Node beside the entry it runs (CR191). The same list as the core's
+ * `HOOK_NODE_CANDIDATES` (`ts/src/runtime/diagnose.ts`), which this file
+ * cannot import: it is a thin dispatcher and duplicates the contracts it
+ * needs, as it does the homes-root names above. `mirrorLoggerExtension.test.ts`
+ * fails if the two lists differ, as `hooks.test.ts` does for the wrappers.
+ */
+export const NODE_CANDIDATES: readonly string[] = [
+	"$HOME/.nvm/current/bin/node",
+	"/opt/homebrew/bin/node",
+	"/usr/local/bin/node",
+];
+
+/** What `resolveNode` found at a path it probed. */
+export type PathKind = "executable" | "directory" | "not executable" | "missing";
+
+/** An executable FILE: a directory passes `X_OK` on its own. */
+function pathKind(path: string): PathKind {
+	try {
+		if (statSync(path).isDirectory()) return "directory";
+	} catch {
+		return "missing";
+	}
+	try {
+		accessSync(path, constants.X_OK);
+		return "executable";
+	} catch {
+		return "not executable";
+	}
+}
+
+export interface NodeResolution {
+	/** The Node to run the core on, by its path; null when none resolves. */
+	node: string | null;
+	/** A `MIRROR_NODE` the search would not use, and why: the caller says so once. */
+	rejected: { value: string; reason: string } | null;
+}
+
+/**
+ * The Node the core runs on, in the hook wrappers' order (CR191): `MIRROR_NODE`
+ * when it is an absolute path to an executable file; `node` on the PATH; the
+ * Node beside the tree this file ships in, which for a global install is the
+ * `<prefix>/bin/node` that installed the package (and nothing for a checkout);
+ * then `NODE_CANDIDATES`. Not `process.execPath`: Pi may run on a Node older
+ * than the core needs. On Windows the PATH is the last place looked.
+ *
+ * A relative `MIRROR_NODE` is refused here, though the wrappers accept one: it
+ * would resolve against whatever project Pi was opened in.
+ *
+ * The absolute candidates make "nothing anywhere" a fact about the host, so
+ * under `MEMORY_ENV=test` only, `MIRROR_TEST_NODE_SEARCH_ROOT` re-roots them
+ * and the prefix candidate. A production session never reads it.
+ */
+export function resolveNode(
+	env: Record<string, string | undefined>,
+	treeRoot: string,
+	kindOf: (path: string) => PathKind = pathKind,
+	platform: NodeJS.Platform = process.platform,
+): NodeResolution {
+	const paths = platform === "win32" ? win32 : posix;
+	let rejected: NodeResolution["rejected"] = null;
+	const explicit = (env.MIRROR_NODE ?? "").trim();
+	if (explicit !== "") {
+		if (!paths.isAbsolute(explicit)) rejected = { value: explicit, reason: "relative" };
+		else {
+			const kind = kindOf(explicit);
+			if (kind === "executable") return { node: explicit, rejected: null };
+			rejected = { value: explicit, reason: kind === "directory" ? "a directory" : kind };
+		}
+	}
+	const name = platform === "win32" ? "node.exe" : "node";
+	for (const dir of (env.PATH ?? "").split(paths.delimiter).filter(Boolean)) {
+		const candidate = paths.join(dir, name);
+		if (kindOf(candidate) === "executable") return { node: candidate, rejected };
+	}
+	if (platform === "win32") return { node: null, rejected };
+	const searchRoot = env.MEMORY_ENV === "test" ? (env.MIRROR_TEST_NODE_SEARCH_ROOT ?? "") : "";
+	const home = env.HOME ?? homedir();
+	const candidates = [
+		paths.resolve(treeRoot, "..", "..", "..", "bin", "node"),
+		...NODE_CANDIDATES.map((candidate) => candidate.replace("$HOME", home)),
+	].map((candidate) => (searchRoot ? paths.join(searchRoot, candidate) : candidate));
+	for (const candidate of candidates) {
+		if (kindOf(candidate) === "executable") return { node: candidate, rejected };
+	}
+	return { node: null, rejected };
+}
+
 /** True when `path` is the same file as this tree's AGENTS.md (symlinks resolved). */
 function _isOurAgentsFile(path: string): boolean {
 	try {
@@ -277,6 +374,41 @@ export default function (pi: ExtensionAPI) {
 	 */
 	const FRONT_DOOR_ARGV = [MIRROR_BIN];
 
+	/**
+	 * The Node every front-door process runs on (CR191), or null when none
+	 * resolves: the caller spawns nothing and logs why. A `MIRROR_NODE` the search
+	 * refused is said once per registration, with the reason, so the log is
+	 * enough to fix it; the search went on without it, as the wrappers' does.
+	 */
+	let mirrorNodeWarned = false;
+	function nodeFor(): string | null {
+		const found = resolveNode(process.env, TREE_ROOT);
+		if (found.rejected && !mirrorNodeWarned) {
+			mirrorNodeWarned = true;
+			log("WARN", `MIRROR_NODE=${found.rejected.value} is ${found.rejected.reason}; searching the PATH and the usual places instead`);
+		}
+		return found.node;
+	}
+
+	/** The line said once at session start when no Node resolves; also the log's and, in short, hooks.log's. */
+	const NO_NODE_NOTICE =
+		"Mirror: `node` is not on the PATH Pi inherited, nor in the usual places — set MIRROR_NODE=/path/to/node (Node 24 or later) where Pi is launched. Mirror will not log this session.";
+
+	/**
+	 * One line in `<mirror home>/hooks.log`, in the format the wrappers write and
+	 * `hookFailureFindings` parses (`<stamp> <runtime>:<hook>: <reason>`), so
+	 * `runtime diagnose` reports it for seven days. Same directory as this log,
+	 * mode 0600 as `noteHookFailure` writes it.
+	 */
+	function noteHookFailure(hook: string, reason: string): void {
+		try {
+			mkdirSync(MIRROR_DIR, { recursive: true });
+			appendFileSync(join(MIRROR_DIR, "hooks.log"), `${new Date().toISOString()} pi:${hook}: ${reason}\n`, { mode: 0o600 });
+		} catch {
+			// A hook cannot report that it could not report.
+		}
+	}
+
 	function log(level: string, msg: string): void {
 		try {
 			const ts = new Date().toISOString();
@@ -288,11 +420,16 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	function runMirrorBackground(args: string[], label: string): void {
+		const node = nodeFor();
+		if (node === null) {
+			log("ERROR", `${label} skipped: no node (see the session's notice)`);
+			return;
+		}
 		let logFd: number | undefined;
 		try {
 			mkdirSync(MIRROR_DIR, { recursive: true });
 			logFd = openSync(LOG_FILE, "a");
-			const child = spawn("node", [...FRONT_DOOR_ARGV, ...args], {
+			const child = spawn(node, [...FRONT_DOOR_ARGV, ...args], {
 				cwd: process.cwd(),
 				stdio: ["ignore", logFd, logFd],
 				// Windows: a detached console child materializes as a visible
@@ -303,8 +440,24 @@ export default function (pi: ExtensionAPI) {
 				detached: process.platform !== "win32",
 				windowsHide: true,
 			});
+			// A child that cannot start reports through 'error', not by throwing,
+			// so the catch below never sees it; without a listener the event is an
+			// uncaught exception and Pi exits ("pi exiting due to uncaughtException:
+			// Error: spawn node ENOENT", PR #47). The path was an executable file a
+			// moment ago (`resolveNode`), so this is the record of one that vanished
+			// in between, or of any other start failure. A logging failure must never
+			// break anything: log it and move on.
+			child.on("error", (error) => {
+				log("ERROR", `${label} failed to start: ${error.message.slice(0, 500)}`);
+			});
+			// Its stdout and stderr are in this log already; the exit code says
+			// whether to read them (a Node too old for the core exits before it runs).
+			child.on("exit", (code, signal) => {
+				if (code !== 0) log("ERROR", `${label} exited ${code ?? `on ${signal}`}`);
+			});
 			child.unref();
-			log("INFO", `${label} started in detached background process ${child.pid ?? "(unknown pid)"}`);
+			// No pid, no process: the 'error' above is on its way.
+			if (child.pid !== undefined) log("INFO", `${label} started in detached background process ${child.pid}`);
 		} catch (err: unknown) {
 			const message = err instanceof Error ? err.message : String(err);
 			log("ERROR", `${label} failed: ${message.slice(0, 500)}`);
@@ -331,10 +484,15 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	async function runMirror(args: string[]): Promise<string> {
+		const node = nodeFor();
+		if (node === null) {
+			log("ERROR", `runMirror skipped [${args.slice(0, 2).join(" ")}]: no node (see the session's notice)`);
+			return "";
+		}
 		try {
 			const delay = testFrontDoorDelayMs();
 			if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay));
-			const result = await pi.exec("node", [...FRONT_DOOR_ARGV, ...args], {
+			const result = await pi.exec(node, [...FRONT_DOOR_ARGV, ...args], {
 				timeout: 30_000,
 			});
 			const stderr = (result?.stderr ?? "").trim();
@@ -682,6 +840,14 @@ export default function (pi: ExtensionAPI) {
 			log("WARN", line);
 			if (ctx.hasUI) ctx.ui.notify(line, "warning");
 		}
+		// Likewise when no Node resolves (CR191): once, visibly, naming the fix,
+		// and one line where `runtime diagnose` reads. The calls below then skip
+		// themselves; a later one that finds nothing logs only.
+		if (nodeFor() === null) {
+			log("WARN", NO_NODE_NOTICE);
+			if (ctx.hasUI) ctx.ui.notify(NO_NODE_NOTICE, "warning");
+			noteHookFailure("session-start", "node not found on PATH or in the usual places; Mirror is off for this session. Set MIRROR_NODE.");
+		}
 		const sessionId = ctx.sessionManager.getSessionFile() ?? null;
 		const openArgs = ["conversation-logger", "session-start", "--fast", "--welcome", "--format", "json"];
 		if (sessionId) openArgs.push("--session-id", sessionId);

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/docs/releases/index.md

@@ -12,6 +12,8 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [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.
 - [v0.38.0 — The Model Behind the Memories, Chosen by Measurement](v0.38.0.md) — minor release closing CV9.DS9: the model behind memories, tasks, titles, summaries, tags, reception, journal, shadow, and consolidation is Claude Haiku 5.5 at reasoning off, chosen on the eval suite with reasoning on and off and on 24 of the owner's own conversations ranked blind, where it came first on 16 of 26 surfaces. Every extraction-pin call can carry a reasoning effort, and a pin carries its own default. With CR180, summaries open with their subject, every lifecycle prompt sees the owner's name, and a framed opening is written once more. Release gate 70 of 70 probes. Rollback is one env line. No migration.

package/docs/releases/v0.39.0.md

@@ -32,6 +32,8 @@ digest: >
 - **Breaking for deep imports only.** The package now declares `exports` with `./desktop` and
   `./package.json`. Any other `import "mirror-mind/…"` path that resolved before no longer does.
   The `mirror` and `mirror-hook` bins are unaffected.
+- **A Windows package install can update itself** (PR #46 by @rodrigoimmaginario, CR189;
+  *added on 2026-10-31*). An earlier version needs one manual install to get here; see Upgrading.
 - No migration, and no model or prompt change, so the model-behavior release gate does not apply.
 
 ## Where We Started
@@ -87,6 +89,32 @@ Existing code changed only where the entry needed it: the loader, three exported
 required), and `package.json`. No existing test changed. The npm smoke installs the package and
 imports the entry from a host project for DS1 to DS5.
 
+*Added on 2026-10-31:* this release also carries one change outside CV24, merged to `main` the
+day before and missing from this note when it was published, so the paragraph above covers CV24
+only. PR #46 (CR189, by @rodrigoimmaginario) runs the package update's `npm install -g` from the
+parent of `node_modules` instead of from inside the package. npm renames the package's directory
+aside before it lays down the new version, and Windows refuses to rename a directory a process is
+running in, so on Windows `runtime update` failed at apply with `EBUSY` every time. Nothing
+changes on macOS or Linux. See Upgrading.
+
+## Upgrading
+
+*Added on 2026-10-31.* Everyone updates as usual:
+
+```bash
+mirror runtime update          # or: npm install -g mirror-mind
+```
+
+On Windows, a package install of an earlier version cannot install this one itself: its
+`runtime update` fails at apply with `EBUSY`. Once, by hand, from any directory other than the
+package's own:
+
+```bash
+npm install -g mirror-mind@latest
+```
+
+From then on `mirror runtime update` works.
+
 ## Conscious Exclusions
 
 - **Renaming a Journey's slug.** The slug keys Conversations, memories and tasks; renaming it is a

package/docs/releases/v0.39.1.md

@@ -0,0 +1,109 @@
+---
+digest: >
+  v0.39.1 is a patch release about one failure: a Pi opened where `node` is not on the
+  PATH, which a desktop launch or a window older than the Node install gives it. Through
+  v0.39.0 that Pi exited at startup with `spawn node ENOENT`. PR #47 (Rodrigo Immaginario)
+  keeps it up, and CR191 makes the Pi extension find Node where the hook wrappers already
+  look, so a machine with a global install needs nothing configured; when no Node resolves,
+  the session says so once, with the fix, and `runtime diagnose` can see it. No migration,
+  and no model or prompt change.
+---
+
+# v0.39.1 — Pi Finds Its Node, or Says So
+
+**Date:** 2026-11-02
+
+## Highlights
+
+- **A Pi opened without `node` on its PATH no longer exits**
+  ([PR #47](https://github.com/mirror-mind-ai/mirror/pull/47), by @rodrigoimmaginario). The
+  extension's detached maintenance process had no `'error'` listener, so a `node` that
+  could not start was an uncaught exception and Pi went down with it. It is now logged.
+- **The Pi extension resolves Node the way the hook wrappers do**
+  ([CR191](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr191-the-pi-extension-cannot-find-node-where-the-hook-wrappers-can.md)):
+  `MIRROR_NODE`, the PATH, the Node that installed the package (`<prefix>/bin/node`), then
+  `~/.nvm/current/bin`, `/opt/homebrew/bin`, `/usr/local/bin`. On a machine with a global
+  install this needs no configuration: the session that used to crash opens as usual.
+- **When no Node resolves, the failure reaches someone.** Pi stays up, shows one warning at
+  session start that names the fix (`MIRROR_NODE=/path/to/node`, Node 24 or later), and
+  writes one line to `<mirror home>/hooks.log`, where `mirror runtime diagnose` reports it
+  for seven days as `hook_failures_recorded`, as it does for the other runtimes' hooks.
+- **A `MIRROR_NODE` the extension will not use is warned once, with the reason**: missing, a
+  directory, not executable, or relative. The search goes on without it.
+- No migration, and no model or prompt change.
+
+## Where We Started
+
+On 2026-10-16 a Pi opened from a terminal window whose PATH predated the Node install
+exited at once:
+
+```text
+pi exiting due to uncaughtException:
+Error: spawn node ENOENT
+  spawnargs: [ '…/node_modules/mirror-mind/bin/mirror.js', 'conversation-logger', 'session-maintenance' ]
+```
+
+The same happens wherever `node` is not on the PATH Pi inherited, and `runtime diagnose`
+had long named that the usual case for a runtime launched from the desktop: `node` lives
+under nvm or Homebrew, not where a GUI looks. The hook wrappers the other runtimes use
+were built for exactly this. They search the usual places and record a failure in
+`hooks.log`. The Pi extension, which runs no wrapper, knew only the bare name `node`.
+
+Rodrigo Immaginario's PR #47 fixed the crash: the listener, and `MIRROR_NODE` honored by
+the extension as the wrappers honor it. Reviewed through four lenses on 2026-11-01, it was
+merged as it was. The review also showed what it left: without `MIRROR_NODE`, that Pi now
+ran with Mirror silently absent, no welcome card, no logging, no context, and a line in a
+file no one is pointed at. That is the failure the wrappers' silence-is-forbidden rule was
+written against, and CR191 is its answer for Pi.
+
+## What Changed
+
+**One resolver, the wrappers' order (CR191).** The extension resolves Node itself, in the
+same order the wrappers use, taking only an executable file: `MIRROR_NODE`, then `node` on
+each PATH entry, then the `bin/` of the prefix the package is installed under, three
+directories up from the tree the extension ships in, which is the Node that installed the
+package, then nvm, Homebrew, `/usr/local`. The candidate list is the core's
+`HOOK_NODE_CANDIDATES`, duplicated in the extension because it imports no core module, and a
+test fails if the two ever differ, as one already did for the wrappers. On Windows the
+search stops after the PATH, as before.
+
+**Nothing found: no spawn, one notice, one line.** When no Node resolves, no front-door
+process is attempted: each call logs that it was skipped. At session start, the extension
+says so once, the way it already says `mirror` is not on the PATH:
+
+```text
+Mirror: `node` is not on the PATH Pi inherited, nor in the usual places — set MIRROR_NODE=/path/to/node (Node 24 or later) where Pi is launched. Mirror will not log this session.
+```
+
+and writes one line to `hooks.log` in the wrappers' format, `pi:session-start: node not
+found on PATH or in the usual places; …`, which `runtime diagnose` counts.
+
+**The log tells one story.** A child that did not start is not logged as started; one that
+exits non-zero leaves its code beside its own output. PR #47's listener stays as the record
+of a file that vanished between the check and the spawn.
+
+Validated against Pi 1.5.0 with `PATH=/usr/bin:/bin`, the incident's configuration: the
+session opened through `/opt/homebrew/bin/node` with nothing configured; a bad
+`MIRROR_NODE` was warned once; with no Node anywhere, Pi stayed up, the warning was on
+screen, and `runtime diagnose` reported the `hooks.log` line.
+
+## Conscious Exclusions
+
+- The hook wrappers and the MCP locator still accept a relative `MIRROR_NODE`; the Pi
+  extension refuses one, since it would resolve against whatever project Pi was opened in.
+  Whether the family follows is a separate decision.
+- A "Node too old" message with the version, as the wrappers print: the exit code and the
+  loader's own output are in the log.
+- Windows candidates beyond `MIRROR_NODE` and the PATH.
+
+## Upgrading
+
+```bash
+mirror runtime update
+```
+
+A Pi session running the previous extension keeps it until Pi restarts.
+
+## Next Horizon
+
+CR190, captured this week, and the open RS010 backlog. CV24 continues on its branch.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.39.0",
+  "version": "0.39.2",
   "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.0",
+  "version": "0.39.2",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
   "author": {
     "name": "Mirror Mind"

package/plugins/mirror-mind/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mirror-mind",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
-  "version": "0.39.0",
+  "version": "0.39.2",
   "mcpServers": {
     "mirror-mind": {
       "command": "/bin/sh",

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";
@@ -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(

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/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 [
     {