mirror-mind 0.39.1 → 0.39.2

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,7 @@ 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.

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.1",
+  "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.1",
+  "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.1",
+  "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 [
     {