mirror-mind 0.33.2 → 0.33.3

package/docs/releases/index.md

@@ -12,6 +12,7 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [v0.33.3 — Mirror Finds Itself Under Any Path](v0.33.3.md) — patch release of one Change Request, CR140, carried by a contributor's PR #42: Mirror read its own install path from `URL.pathname`, so a checkout or package under a path with a space or a non-ASCII character read as `Install: unknown`, the welcome card showed no update, and `runtime update` refused. The path is now a filesystem path, a guard keeps the idiom out, and an `unknown` install names the path it looked up from. On Windows, npm's global layout is recognized and npm runs with no shell, verified on Windows in CI for the two files they touch; there is still no Windows product. Affected installs update once by hand. No migration.
 - [v0.33.2 — Git Runs Where Mirror Lives](v0.33.2.md) — patch release of one Change Request, CR138: on a clone install, `runtime status`, `version`, and `diagnose` describe the install from any directory, and `diagnose` grades Mirror's own tree. Git now runs only in the install's own checkout, so a checkout someone else made can no longer run a `core.fsmonitor` command through these commands; `version --start PATH` is the one explicit exception. Package installs were never exposed. No migration.
 - [v0.33.1 — The Install Answers For Itself](v0.33.1.md) — patch release of six RS010 Change Requests: the welcome card, the status line, and both `release-notes` readers answer for the install that is running, never for the cwd or the repository around the install. A package asks its own tree and the npm registry, a clone its own checkout and remote; `pending` says `unknown` when it cannot tell, and a `--ref` value can no longer run a command through git. No migration.
 - [v0.33.0 — One Plugin, Three Runtimes](v0.33.0.md) — minor release closing CV21.DS2: the one plugin works as it is on Claude Code, Codex, and Grok. Its MCP server starts on all three, the explicit Mirror form is recognized in every runtime's spelling, and each session is logged under its runtime with every reply beside its prompt. Also: a faster Pi session start, and notice that Gemini CLI is retired in favor of Antigravity.

package/docs/releases/v0.33.3.md

@@ -0,0 +1,158 @@
+---
+digest: >
+  v0.33.3 is a maintenance release of one Change Request, CR140, carried by a
+  contributor's pull request. Mirror read its own install path from
+  `URL.pathname`, which spells a space as `%20`, `Código` as `C%C3%B3digo`, and
+  `C:\` as `/C:/`. Under such a path a checkout or a package read as `Install:
+  unknown`, the welcome card showed no update, and `runtime update` refused for
+  a reason that was not true. The path is now a filesystem path, a guard keeps
+  the idiom out of the code, and an `unknown` install names the path it looked
+  up from. On Windows, npm's global layout is recognized and npm runs with no
+  shell, verified on Windows in CI for the two files they touch; there is still
+  no Windows product. People under such a path update once by hand; everyone
+  else as usual. No migration.
+---
+
+# v0.33.3 — Mirror Finds Itself Under Any Path
+
+**Date:** 2026-10-16
+
+## Highlights
+
+- **Mirror recognizes its own install under any path** (CR140, PR #42 by
+  @rodrigoimmaginario, with the macOS reproduction by @lgarciasbr). A checkout or a
+  package under `My Projects`, `Código`, or `C:\Users\John Doe` read as `Install:
+  unknown`; it reads as what it is.
+- **An `unknown` install names the path it looked up from.** `Install: unknown (<reason>;
+  looked up from <path>)`, with the path spelled as the detector saw it, so a wrong
+  spelling is wrong in the report instead of hidden behind `not a git checkout`.
+- **The idiom cannot come back.** A retired-surface row, `url-pathname-as-path`, sweeps
+  `ts/src/` and `ts/scripts/` for a URL's pathname read as a filesystem path. Widening it
+  to the scripts caught a second instance on the first run.
+- **On Windows, the install answers too.** npm's Windows global layout
+  (`<prefix>\node_modules\<name>` and a `<prefix>\<bin>.cmd` shim) is recognized, and npm
+  runs with no shell, as `node.exe` running `npm-cli.js`. Both run on Windows in CI, for
+  the two test files they touch. There is still no Windows product.
+- **People this release is for cannot take it the usual way.** Their `runtime update`
+  refuses them; see Upgrading.
+
+## Where We Started
+
+Every route that asks "how is this Mirror installed" hands the detector the front door's
+own path, and two of them computed it as `new URL("…/cli.ts", import.meta.url).pathname`.
+A URL's pathname is not a filesystem path: it percent-encodes every reserved or non-ASCII
+character, and on Windows it spells a drive as `/C:/`. None of those paths exist, so no
+`.git` was found above the front door, no manifest either, and the install was `unknown`
+with a reason that was false for a checkout whose branch the same command named a few
+lines down.
+
+Three surfaces failed together. `runtime status` printed `Install: unknown`, and since
+`v0.33.2` the repository rows went blank with it. The welcome card skips the remote update
+check for an `unknown` install, so nobody under such a path was told an update existed.
+And `runtime update` refused at its status gate, so the updater could not ship its own
+fix to the people it affected.
+
+It was reported twice within a day, independently: on Windows 11, where it first looked
+Windows-specific, and on macOS under `~/Documents/Código/mirror` at `0.32.1` and `0.33.2`.
+Review found the common case neither report named: a space. `/tmp/space only` read as
+`unknown` the same way, and on Windows that is most home directories.
+
+## What Changed
+
+**The path never enters URL form.** One `thisFrontDoorPath()` in
+`ts/src/runtime/installKind.ts` joins from `import.meta.dirname`, and every route hands
+the detector that. The first version of the fix converted out of the URL with
+`fileURLToPath`; the review asked for the form in which the class of bug is not possible,
+which is the idiom `ts/src/runtime/treeRoot.ts` already used.
+
+**A guard, not a memory.** The retired-surface table gained its first row that retires an
+idiom rather than a deleted file: `url-pathname-as-path`, with the code shapes as patterns
+so prose may still name `URL.pathname`. Its live-tree sweep runs in the suite. We checked
+the pin by putting `.pathname` back locally and watching it fail.
+
+**The `unknown` reason carries evidence.** It ends with `; looked up from <path>`. Had
+that line existed, the first report would have carried its own diagnosis.
+
+**Windows, honestly scoped.** The layout detector accepts npm's Windows shape, with the
+shim's own text as the evidence that the bin reaches into this package, since nothing
+resolves. npm is spawned as `npm.cmd` itself spawns it, `npm-cli.js` beside `node.exe`
+through the running node: no shell, so the welcome card's timeout kills npm itself rather
+than a shell above it (CVE-2024-27980 is why Node refuses `.cmd` without one). When no
+`npm-cli.js` sits beside the node, the answer is a named absence reported as "npm
+unavailable", not a module-not-found stack. One accepted difference from `npm.cmd`: it
+runs the npm bundled with the running node, not one the person upgraded under the
+prefix.
+
+A `windows-install-kind` job on `windows-latest` runs `installKind.test.ts` and
+`packageStrategy.test.ts`, about 25 seconds. On its first run on `main` it failed: on a
+test written on macOS the same day, by the reviewer who asked for the job, comparing a
+fixture against its POSIX spelling where Windows adds a drive. Fixed the way the PR had
+fixed six others.
+
+**Verified where it matters.** The install-from-nothing smoke, which packs this tree and
+installs it into a scratch prefix, was run under `/tmp/mirror pkg Código`: 76 checks, all
+passing, through `init`, `seed`, `status`, every runtime's hooks, and the MCP launcher.
+The smoke itself needed one fix first: its Gemini section split the work directory on
+the space, the same assumption this release removes from the product.
+
+### What you will notice
+
+- Under a path with a space or an accent, `runtime status` reads `Install: clone (…)` or
+  `Install: package (…)`, the welcome card checks for updates again, and `runtime update`
+  works, after the one manual update below.
+- Under any other path, nothing. The POSIX layout is checked first and is unchanged.
+- An install that is still `unknown` tells you where it looked.
+
+## Upgrading
+
+If your Mirror lives under a path with a space or a non-ASCII character anywhere above
+it, the version you have cannot update itself: `runtime update` refuses it. Once, by
+hand:
+
+```bash
+# a clone: in the checkout
+git pull --ff-only
+# a package
+npm install -g mirror-mind@latest
+```
+
+From then on `mirror runtime update` works as documented. Everyone else:
+
+```bash
+mirror runtime update          # or: npm install -g mirror-mind
+```
+
+There is no database migration and no runtime wiring change.
+
+## Conscious Exclusions
+
+- **A Windows product.** REFERENCE.md's platform envelope stands: POSIX. The Windows
+  changes here are correct where they run and verified on Windows for their two files;
+  the hook wrappers, the plugin's MCP entry, `init`'s wiring, and the suite as a whole
+  are not. The contributor describes a series toward that; its shape is not decided.
+- **The `frame-installer` guard row's `absentSuffixes`** (`.cmd`, `.ps1`) will meet that
+  series and is to be raised there, not here.
+- **The guard's `identifier.pathname` pattern** would also flag a legitimate
+  `request.pathname` if `ts/src` ever grows HTTP routing. The row's `exemptions` field is
+  for that day.
+- **Counting verdicts as front-door errors** (CR139), unchanged from `v0.33.2`.
+
+## What We Learned
+
+A diagnostic that names a conclusion is a diagnostic that lies when the conclusion is
+wrong. `not a git checkout` was false, and nothing in the line let anyone see why. A
+diagnostic that names evidence, the path it walked, is true even when the detector is
+wrong, and it turns a two-platform debugging session into one line read once.
+
+The strong form of a fix removes the class, not the instance. `fileURLToPath` fixed every
+path that exists; `import.meta.dirname` made the question of URL spelling unaskable, and
+the guard made the answer durable. The review asked for the second, and the contributor
+delivered it with a guard that found a second instance on its own.
+
+A CI job earns its place on its first catch, and this one's first catch was the person
+who asked for it.
+
+## Next Horizon
+
+CR139, the verdict loop, is the visible next step in RS010. The contributor's Windows
+series, if it comes, begins with the suite on `windows-latest`.

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.33.2",
+  "version": "0.33.3",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
   "author": {
     "name": "Mirror Mind"

package/ts/src/frontDoor/runtimeRoute.ts

@@ -42,7 +42,12 @@ import {
   unavailableUpdateCheck,
   upstreamFor,
 } from "#runtime/git.ts";
-import { detectInstallKind, type InstallKind, inspectionRootFor } from "#runtime/installKind.ts";
+import {
+  detectInstallKind,
+  type InstallKind,
+  inspectionRootFor,
+  thisFrontDoorPath,
+} from "#runtime/installKind.ts";
 import { MIGRATE_DECLINED_EXIT, renderMigrate, runMigrate } from "#runtime/migrate.ts";
 import {
   buildPendingReleaseNotes,
@@ -514,7 +519,7 @@ function runRuntimeUpdate(
   const install =
     io.install ??
     detectInstallKind({
-      frontDoorPath: frontDoorSelfPath(),
+      frontDoorPath: thisFrontDoorPath(),
       npmRootGlobal: npmRootGlobal(runningTreeRoot()),
     });
   const channel = channelFor(install, env, homedir(), channelOverride);
@@ -648,11 +653,6 @@ function spawner(env: NodeJS.ProcessEnv): UpdateSpawn {
   return frontDoorSpawner(join(runningTreeRoot(), "bin", "mirror.js"), env);
 }
 
-/** This front door's own path, which is also how the install kind is read. */
-function frontDoorSelfPath(): string {
-  return new URL("./cli.ts", import.meta.url).pathname;
-}
-
 /**
  * How THIS front door is installed, by what the filesystem shows and nothing
  * spawned: a checkout by its `.git`, a package by npm's global layout and the
@@ -660,7 +660,7 @@ function frontDoorSelfPath(): string {
  * lane, probes `npm root -g` itself.
  */
 function detectThisInstall(): InstallKind {
-  return detectInstallKind({ frontDoorPath: frontDoorSelfPath() });
+  return detectInstallKind({ frontDoorPath: thisFrontDoorPath() });
 }
 
 /**

package/ts/src/guards/retiredSurfaces.ts

@@ -460,6 +460,24 @@ export const RETIRED: readonly RetiredSurface[] = [
     // exploration's record is `docs/project/exploration/es-004-*.md`.
     exemptions: {},
   },
+  {
+    // Not a deleted surface: a retired IDIOM. A URL's pathname is not a
+    // filesystem path -- it percent-encodes `Código` and `John Doe`, and on
+    // Windows spells `C:\...` as `/C:/...` -- and read as one it made every
+    // install under such a directory `unknown` (PR #42, CR140). The fix is
+    // `import.meta.dirname` or `fileURLToPath`; this row keeps the idiom from
+    // coming back in code. Tests may spell the bug to pin it, so the scope is
+    // the product and its scripts.
+    surfaceId: "url-pathname-as-path",
+    story: "PR #42 (CR140)",
+    absentPaths: [],
+    // The code shapes: a property read off a call (`new URL(...).pathname`) or
+    // off a variable (`url.pathname`). Prose writes `URL.pathname`, capital U,
+    // which neither pattern matches, so a comment may still name the cause.
+    forbiddenPatterns: ["\\)\\.pathname\\b", "\\b[a-z_$][\\w$]*\\.pathname\\b"],
+    residueScope: ["ts/src/", "ts/scripts/"],
+    exemptions: {},
+  },
 ];
 
 export interface SurfaceProblem {

package/ts/src/runtime/installKind.ts

@@ -139,13 +139,19 @@ function packageUnderNpmRoot(
 
 /**
  * The installed package holding this front door, by its layout, with no
- * subprocess: the manifest sits at `<prefix>/lib/node_modules/<name>` -- the
- * global layout npm uses on every platform this core supports -- AND one of
- * the manifest's bins exists at `<prefix>/bin/<bin>` and resolves back into
- * the package. The bin is what makes a global install global; a project that
- * happens to live at `<x>/lib` has the first half and not the second.
- * (CV22.DS10.US3 plateau 4: the read-only routes run where npm may be off
- * the PATH and must still say what this is.)
+ * subprocess (CV22.DS10.US3 plateau 4: the read-only routes run where npm may
+ * be off the PATH and must still say what this is). npm has two global
+ * layouts, and in both the bin is what makes a global install global -- a
+ * project that happens to live at `<x>/lib` has the manifest half and not the
+ * bin half:
+ *
+ * - POSIX: the manifest at `<prefix>/lib/node_modules/<name>`, and one of its
+ *   bins at `<prefix>/bin/<bin>`, a symlink that resolves back into the
+ *   package.
+ * - Windows: the manifest at `<prefix>\node_modules\<name>`, and one of its
+ *   bins at `<prefix>\<bin>.cmd`, a shim file that runs
+ *   `%dp0%\node_modules\<name>\...`. Nothing resolves, so the shim's own
+ *   text is the evidence that the bin reaches into THIS package.
  */
 function packageByLayout(
   frontDoorPath: string,
@@ -156,15 +162,52 @@ function packageByLayout(
   const manifest = nearestManifest(frontDoorPath, null, exists, readFile);
   if (manifest === null) return null;
   const nodeModules = dirname(manifest.root);
+  if (basename(nodeModules) !== "node_modules") return null;
+  const linked =
+    binLinkedUnderPosixPrefix(manifest, nodeModules, exists, realpath) ||
+    binShimmedUnderWindowsPrefix(manifest, nodeModules, exists, readFile);
+  if (!linked) return null;
+  return { kind: "package", root: manifest.root, name: manifest.name, version: manifest.version };
+}
+
+function binLinkedUnderPosixPrefix(
+  manifest: Manifest,
+  nodeModules: string,
+  exists: (path: string) => boolean,
+  realpath: (path: string) => string,
+): boolean {
   const lib = dirname(nodeModules);
-  if (basename(nodeModules) !== "node_modules" || basename(lib) !== "lib") return null;
+  if (basename(lib) !== "lib") return false;
   const prefix = dirname(lib);
-  const linked = manifest.bins.some((bin) => {
+  return manifest.bins.some((bin) => {
     const link = join(prefix, "bin", bin);
     return exists(link) && isInside(manifest.root, realpath(link));
   });
-  if (!linked) return null;
-  return { kind: "package", root: manifest.root, name: manifest.name, version: manifest.version };
+}
+
+/**
+ * Not gated by platform, on purpose: the layout is evidence wherever it is
+ * found, and a Windows-only branch could be exercised only on Windows. Kept
+ * open, macOS and Linux run the Windows tests with fixture paths, and the
+ * `windows-latest` job runs the same tests on the real thing.
+ */
+function binShimmedUnderWindowsPrefix(
+  manifest: Manifest,
+  nodeModules: string,
+  exists: (path: string) => boolean,
+  readFile: (path: string) => string,
+): boolean {
+  const prefix = dirname(nodeModules);
+  const runsThisPackage = `node_modules/${manifest.name}/`;
+  return manifest.bins.some((bin) => {
+    const shim = join(prefix, `${bin}.cmd`);
+    if (!exists(shim)) return false;
+    try {
+      return readFile(shim).replace(/\\/g, "/").includes(runsThisPackage);
+    } catch {
+      return false;
+    }
+  });
 }
 
 /** `realpathSync`, except that a path that does not exist is returned as given. */
@@ -176,6 +219,21 @@ function safeRealpath(path: string): string {
   }
 }
 
+/**
+ * This front door's own path, as the filesystem spells it: what every route
+ * hands `detectInstallKind`. From `import.meta.dirname`, so the path never
+ * passes through URL form: a URL's pathname is not a filesystem path. It
+ * percent-encodes every reserved character -- a directory named `Código` or
+ * `John Doe` becomes `C%C3%B3digo`, `John%20Doe` -- and on Windows it spells
+ * `C:\...` as `/C:/...`. Read as a path, none of those exist, so no `.git`
+ * was found above the front door and every such install was `unknown`: the
+ * updater refused, and after CR138 the git rows went blank. The guard row
+ * `url-pathname-as-path` keeps the idiom out of `ts/src` and `ts/scripts`.
+ */
+export function thisFrontDoorPath(): string {
+  return join(import.meta.dirname, "..", "frontDoor", "cli.ts");
+}
+
 export function detectInstallKind(probe: InstallKindProbe): InstallKind {
   const exists = probe.exists ?? existsSync;
   const readFile = probe.readFile ?? ((path: string) => readFileSync(path, "utf8"));
@@ -190,15 +248,17 @@ export function detectInstallKind(probe: InstallKindProbe): InstallKind {
   const repository = cloneRootFor(dirname(frontDoorPath), exists);
   if (repository !== null) return { kind: "clone", repository };
 
-  return {
-    kind: "unknown",
-    reason:
-      probe.npmRootGlobal === null
-        ? "not a git checkout, and npm is unavailable to identify a package install"
-        : probe.npmRootGlobal === undefined
-          ? "not a git checkout, and not laid out as a global npm install"
-          : "not a git checkout, and not under the global npm root",
-  };
+  // The reason carries the path the walk started from, spelled as the detector
+  // saw it (CR140): a path that is wrong -- a URL's `%C3%B3` for `ó`, a `/C:/`
+  // for `C:\` -- is then wrong in the report, where `not a git checkout` alone
+  // sent two contributors on two platforms debugging what this line shows.
+  const because =
+    probe.npmRootGlobal === null
+      ? "not a git checkout, and npm is unavailable to identify a package install"
+      : probe.npmRootGlobal === undefined
+        ? "not a git checkout, and not laid out as a global npm install"
+        : "not a git checkout, and not under the global npm root";
+  return { kind: "unknown", reason: `${because}; looked up from ${frontDoorPath}` };
 }
 
 /**

package/ts/src/runtime/status.ts

@@ -40,6 +40,7 @@ import {
   type InstallKind,
   inspectionRootFor,
   renderInstallLines,
+  thisFrontDoorPath,
 } from "./installKind.ts";
 
 export interface CoreMigrationHealth {
@@ -390,9 +391,7 @@ function mirrorHomeForStatus(env: DbPathEnv): { home: string | null; error: stri
 /** Port of `build_runtime_status`. */
 export function buildRuntimeStatus(options: BuildStatusOptions = {}): RuntimeStatusReport {
   const env = options.env ?? process.env;
-  const install =
-    options.install ??
-    detectInstallKind({ frontDoorPath: new URL("../frontDoor/cli.ts", import.meta.url).pathname });
+  const install = options.install ?? detectInstallKind({ frontDoorPath: thisFrontDoorPath() });
   // The repository rows are the install's own, or the one `start` names; never
   // the cwd's (CR138). The git facts are a clone's: a package has no
   // repository, and grading the cwd as one read "not a git repository" as a git

package/ts/src/runtime/strategies/package.ts

@@ -11,7 +11,8 @@
 // the pipeline's decisions are testable without a registry.
 
 import { execFileSync } from "node:child_process";
-import { basename, join } from "node:path";
+import { existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { type ApplyStrategy, KNOWN_CHANNELS } from "#runtime/updatePipeline.ts";
 import { compareSemver, isPlainSemver } from "#util/semver.ts";
 
@@ -40,9 +41,44 @@ export type NpmRunner = (
   stderr: string;
 };
 
+/**
+ * How npm is spawned on this platform.
+ *
+ * Elsewhere `npm` is a file on the PATH, spawned directly. On Windows it is
+ * `npm.cmd`, which Node runs only through a shell (since CVE-2024-27980 it
+ * refuses otherwise) -- and a shell's timeout ends the shell, not the npm
+ * under it: an orphan that outlives the welcome card's budget and holds the
+ * directory it ran in. So on Windows Mirror runs npm the way `npm.cmd` itself
+ * does: the `npm-cli.js` every Windows distribution of Node ships beside
+ * `node.exe`, through the node already running. No shell, and the budget's
+ * kill reaches npm itself. Without this every probe answered "npm is
+ * unavailable" on a machine with npm on its PATH, and the update lane refused
+ * for a reason that was not true.
+ *
+ * One difference from `npm.cmd`, accepted: the shim prefers an npm the person
+ * upgraded under `<prefix>\node_modules\npm` when there is one; this runs the
+ * npm bundled with the node that is running. And when no `npm-cli.js` sits
+ * beside that node -- a node from a manager that ships npm elsewhere -- the
+ * answer is a named absence, so the status line can say "npm is unavailable"
+ * and where it looked, rather than a module-not-found stack.
+ */
+export function npmInvocation(
+  args: readonly string[],
+  platform: NodeJS.Platform,
+  execPath: string,
+  exists: (path: string) => boolean = existsSync,
+): { file: string; args: string[] } | { unavailable: string } {
+  if (platform !== "win32") return { file: "npm", args: [...args] };
+  const cli = join(dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js");
+  if (!exists(cli)) return { unavailable: `npm-cli.js not found beside node: ${cli}` };
+  return { file: execPath, args: [cli, ...args] };
+}
+
 export const defaultNpmRunner: NpmRunner = (args, call = {}) => {
+  const invocation = npmInvocation(args, process.platform, process.execPath);
+  if ("unavailable" in invocation) return { code: -1, stdout: "", stderr: invocation.unavailable };
   try {
-    const stdout = execFileSync("npm", [...args], {
+    const stdout = execFileSync(invocation.file, invocation.args, {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
       ...(call.cwd === undefined ? {} : { cwd: call.cwd }),