mirror-mind 0.33.1 → 0.33.3

package/docs/releases/index.md

@@ -12,6 +12,8 @@ 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.
 - [v0.32.1 — The Release That Shipped](v0.32.1.md) — patch release that is the published CV22 release: `v0.32.0` was tagged and its publication refused by the retired-surface tripwire over one sentence in Getting Started, now rephrased. No code, behavior, or schema differs from `v0.32.0`; read that note for the release itself.

package/docs/releases/v0.33.2.md

@@ -0,0 +1,124 @@
+---
+digest: >
+  v0.33.2 is a maintenance release of one Change Request, CR138, which closes
+  the family v0.33.1 began. For a clone install, `runtime status`, `version`,
+  and `diagnose` described the repository the person was standing in, not the
+  install: a healthy clone read `attention needed` outside its checkout, and
+  `diagnose` reported another project's uncommitted files as Mirror drift.
+  Because git reads a repository's own config, running these commands inside a
+  checkout someone else made could also run a command that checkout chose. Git
+  now runs only in the install's own checkout, and `version --start PATH` is
+  the one explicit exception. Package installs, the default, were never
+  exposed. Upgrade with `mirror runtime update`; there is no migration.
+---
+
+# v0.33.2 — Git Runs Where Mirror Lives
+
+**Date:** 2026-10-15
+
+## Highlights
+
+- **On a clone install, `runtime status`, `version`, and `diagnose` describe the install
+  from any directory** (CR138). A healthy clone is `ready` everywhere. The channel row is
+  what `runtime channel` reports, and the clone role is the checkout's own.
+- **`diagnose` grades Mirror's own tree.** Run inside another project, it reported that
+  project's uncommitted files as Mirror drift and advised committing, stashing, or
+  discarding them. It no longer looks there.
+- **A checkout you did not make can no longer run a command through these commands.**
+  Git reads a repository's `.git/config`, where `core.fsmonitor` names a command git runs
+  on `status`. Run inside such a checkout, `runtime status`, `version`, and `diagnose` ran
+  it. They now run git only in the install's own checkout. `version --start PATH` is the
+  one documented way to inspect another repository.
+- **Package installs were never exposed.** A package inspects no repository; its
+  clone-role row now reads `none (package install)`.
+- **An install that cannot be identified inspects no repository**, and says why;
+  `update --check` answers `unknown` with the reason.
+
+## Where We Started
+
+`v0.33.1` made the welcome card, the status line, and both release-notes readers answer
+for the install instead of the cwd. CR138, captured during that work, named the same
+defect in `runtime status` and `runtime version` for a clone: both named the install on
+their first line, then reported the repository, git state, and channel of whatever
+directory they were run in. REFERENCE.md's recommended update flow begins with `runtime
+status`, so a clone user who ran it from a project was told `attention needed` about a
+healthy install.
+
+Selection found more than the capture said. The clone-role row read the cwd too.
+`runtime diagnose` built the same report, so from inside another project it listed that
+project's uncommitted files as Mirror's and recommended discarding work in a repository
+that was not Mirror's. The plan's review then measured the third face. Git runs a
+repository's own `core.fsmonitor` command on `status`, so these commands, run inside a
+checkout someone else made, ran what that checkout chose. No skill runs these commands,
+so it took a person running them there. The exposure was clone installs, and installs
+that cannot be identified; a package never inspected a repository.
+
+## What Changed
+
+**One rule says where the repository rows come from.** `inspectionRootFor(install,
+start)`: `--start` when given, else a clone's own checkout, else nowhere. The report
+builder and `runtime version` both use it. The builder no longer defaults to the cwd, and
+`status`, `diagnose`, and the update gate pass none.
+
+**The rows are the install's.** The channel row is the answer `runtime channel` gives,
+and the clone role is the checkout's marker. `diagnose`'s worktree findings come from the
+install's tree, so a dirty Mirror checkout is still reported and another project's work
+never is.
+
+**`--start` is the one explicit exception.** `runtime version --start PATH` keeps its
+documented meaning, to inspect the repository at PATH, and is now named as the one way
+these commands run git in a repository the install does not own.
+
+**An install that cannot be identified asks nothing.** Its git rows say `install kind
+unknown: <reason>`, and its verdict is `attention needed`, which is true: `runtime
+update` refuses such an install. `update --check` answers `unknown` with the same reason
+instead of asking the cwd's git.
+
+The tests run every command from a directory in no repository and from a hostile project:
+uncommitted work, its own channel and role markers, and a `core.fsmonitor` that creates a
+marker file. The answers are byte-identical, and the marker never appears, except through
+`--start`, which asks for it. No golden changed.
+
+### What you will notice
+
+- On a clone, `runtime status` gives the same answer from any directory as from the
+  checkout, and `runtime version`'s `Update channel:` matches `runtime channel`.
+- On a package, `Clone role: none (package install)`.
+- `runtime diagnose` may still report `front_door_errors`. Every command that exits 1 to
+  report a verdict, `diagnose` included, is logged as an error and counted. That is
+  CR139, captured and not in this release.
+
+## Upgrading
+
+```bash
+mirror runtime update          # or: npm install -g mirror-mind
+```
+
+There is no database migration, and no runtime wiring changes. The update itself is run
+by the version you have now; the fix applies from the first command after it.
+
+## Conscious Exclusions
+
+- **Counting verdicts as front-door errors** (CR139). `runtime status`'s `attention
+  needed`, `diagnose`'s findings, and `release-notes pending`'s `unknown` exit 1, and the
+  front door logs every non-zero exit as an error that `diagnose` counts. This release
+  removes the false verdicts that fed it, not the loop.
+- **The `release` environment's ref check** (CR136).
+- **Retiring `version --start`.** It was kept, as the explicit override it always was.
+
+## What We Learned
+
+In CR133 to CR135, "never the cwd" was a correctness rule: the person's project is not
+Mirror, so it cannot answer Mirror's questions. CR138 showed it is also a trust boundary.
+The cwd's repository configures the very git that inspects it, so a wrong answer and an
+executed command had the same cause and the same fix, which is where a command decides to
+look.
+
+A test can pin a defect as faithfully as it pins a feature. One CLI test asserted, with a
+comment saying so: "Git inspection still describes the cwd." It was right about the
+oracle and wrong about the product, and it now pins the fix.
+
+## Next Horizon
+
+CR139, the verdict loop, is the visible next step in RS010. CR136 would harden the
+publish route.

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

@@ -21,7 +21,7 @@ import {
   renderRuntimeBackupCreated,
   verifyBackupArchive,
 } from "#runtime/backup.ts";
-import { channelFor, renderChannel, setChannel } from "#runtime/channel.ts";
+import { channelFor, channelForReport, renderChannel, setChannel } from "#runtime/channel.ts";
 import {
   diagnoseRuntime,
   hookFailureFindings,
@@ -33,16 +33,21 @@ import {
 } from "#runtime/diagnose.ts";
 import {
   checkUpdateAvailability,
-  inspectCloneRole,
+  cloneRoleFor,
   inspectGitFor,
   inspectGitWorktree,
-  inspectUpdateChannel,
   packageVersion,
   renderRuntimeUpdateAvailability,
   renderRuntimeVersion,
+  unavailableUpdateCheck,
   upstreamFor,
 } from "#runtime/git.ts";
-import { detectInstallKind, type InstallKind } 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,
@@ -156,6 +161,11 @@ function resolveWelcomeHome(explicit: string | null, env: NodeJS.ProcessEnv): st
 }
 
 export interface RuntimeRouteIo {
+  /**
+   * Where the command was run. No `runtime` read route consults it: since
+   * CR134 and CR138 they answer for the install, wherever they run. Tests pass
+   * it to show that it does not matter.
+   */
   cwd?: string;
   env?: NodeJS.ProcessEnv;
   stdout?: (text: string) => void;
@@ -244,7 +254,6 @@ export async function runRuntimeReadRoute(
   io: InstallRouteIo = {},
 ): Promise<number> {
   const env = io.env ?? process.env;
-  const cwd = io.cwd ?? process.cwd();
   const args = argv.slice(1);
   const subcommand = args[0] ?? "";
   // The version is the running tree's, never the cwd's: for a skill the cwd
@@ -254,19 +263,24 @@ export async function runRuntimeReadRoute(
 
   if (subcommand === "version") {
     const startArg = optionValue(args, "--start");
-    const start = startArg ? expandHome(startArg) : cwd;
-    const install = detectThisInstall();
+    const install = io.install ?? detectThisInstall();
+    // The install's own repository, or the one `--start` names: the one
+    // explicit way these commands run git outside the install (CR138).
+    const root = inspectionRootFor(install, startArg ? expandHome(startArg) : null);
     writeOut(
       io,
       renderRuntimeVersion({
         version,
         install,
-        git: inspectGitFor(install, start),
-        cloneRole: inspectCloneRole(start),
-        updateChannel:
-          install.kind === "package"
-            ? channelFor(install, env, homedir(), optionValue(args, "--channel"))
-            : inspectUpdateChannel(start, optionValue(args, "--channel")),
+        git: inspectGitFor(install, root),
+        cloneRole: cloneRoleFor(install, root),
+        updateChannel: channelForReport(
+          install,
+          root,
+          env,
+          io.osHome ?? homedir(),
+          optionValue(args, "--channel"),
+        ),
       }),
     );
     return 0;
@@ -274,24 +288,24 @@ export async function runRuntimeReadRoute(
 
   if (subcommand === "status") {
     const report = buildRuntimeStatus({
-      start: cwd,
       mirrorHome: optionValue(args, "--mirror-home"),
       channel: optionValue(args, "--channel"),
       env,
       version,
-      install: detectThisInstall(),
+      install: io.install ?? detectThisInstall(),
     });
     writeOut(io, renderRuntimeStatus(report, env));
     return statusVerdict(report) === "ready" ? 0 : 1;
   }
 
   if (subcommand === "diagnose") {
+    // The install's own tree, so its worktree findings are Mirror's and never
+    // the cwd project's (CR138).
     const report = buildRuntimeStatus({
-      start: cwd,
       mirrorHome: optionValue(args, "--mirror-home"),
       env,
       version,
-      install: detectThisInstall(),
+      install: io.install ?? detectThisInstall(),
     });
     const findings = [
       ...diagnoseRuntime(report, inspectGitWorktree(report.git.repository)),
@@ -340,7 +354,7 @@ export async function runRuntimeReadRoute(
 
   if (subcommand === "backup") return runRuntimeBackup(args.slice(1), io, env);
   if (subcommand === "migrate") return runRuntimeMigrate(args.slice(1), io, env);
-  if (subcommand === "update") return runRuntimeUpdate(args.slice(1), io, env, cwd);
+  if (subcommand === "update") return runRuntimeUpdate(args.slice(1), io, env);
   if (subcommand === "channel") return runRuntimeChannel(args.slice(1), io, env);
 
   // Routing answers every name it does not recognize before dispatch (the
@@ -486,9 +500,8 @@ function runRuntimeChannel(
  */
 function runRuntimeUpdate(
   args: readonly string[],
-  io: RuntimeRouteIo,
+  io: InstallRouteIo,
   env: NodeJS.ProcessEnv,
-  cwd: string,
 ): number {
   const version = packageVersion(runningTreeRoot()) ?? "unknown";
   const channelOverride = optionValue(args, "--channel");
@@ -499,11 +512,16 @@ function runRuntimeUpdate(
   // npm runs in the tree the front door runs from -- for a package, the
   // install's own root -- and never in the cwd, whose `.npmrc` could name
   // another registry or prefix (CR135). The strategy's own calls do the same.
-  const install = detectInstallKind({
-    frontDoorPath: frontDoorSelfPath(),
-    npmRootGlobal: npmRootGlobal(runningTreeRoot()),
-  });
-  const start = install.kind === "clone" ? install.repository : cwd;
+  //
+  // Git runs in the clone's own checkout and nowhere else: the gate's report
+  // and `--check` name no cwd (CR138), whose `.git/config` could name a
+  // command for git to run.
+  const install =
+    io.install ??
+    detectInstallKind({
+      frontDoorPath: thisFrontDoorPath(),
+      npmRootGlobal: npmRootGlobal(runningTreeRoot()),
+    });
   const channel = channelFor(install, env, homedir(), channelOverride);
 
   if (args.includes("--check")) {
@@ -517,7 +535,12 @@ function runRuntimeUpdate(
         ? 0
         : 1;
     }
-    const availability = checkUpdateAvailability(start, channelOverride, version);
+    // An install that cannot be identified has no checkout to ask, and the
+    // cwd is not one (CR138, decision 2). `runtime update` refuses it too.
+    const availability =
+      install.kind === "clone"
+        ? checkUpdateAvailability(install.repository, channelOverride, version)
+        : unavailableUpdateCheck(version, channel, `install kind unknown: ${install.reason}`);
     writeOut(io, renderRuntimeUpdateAvailability(availability));
     return availability.status === "up_to_date" || availability.status === "update_available"
       ? 0
@@ -541,7 +564,6 @@ function runRuntimeUpdate(
 
   const gate = (): { ready: boolean; allowed: boolean; detail: string } => {
     const report = buildRuntimeStatus({
-      start,
       mirrorHome,
       channel: channelOverride,
       env,
@@ -631,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
@@ -643,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/channel.ts

@@ -82,6 +82,24 @@ export function channelFor(
   return { value: DEFAULT_CHANNEL, source: null, note: "install kind unknown" };
 }
 
+/**
+ * The channel row of `status` and `version` (CR138). A package's is its
+ * config file's. A clone's is the marker in the repository the rows come from
+ * (`inspectionRootFor`): its own checkout, or `version --start PATH`, the
+ * flag's documented meaning. With no root, the install's own answer, which for
+ * a clone without `--start` is the same marker, read the same way.
+ */
+export function channelForReport(
+  install: InstallKind,
+  root: string | null,
+  env: ConfigEnv = process.env,
+  home: string = homedir(),
+  override: string | null = null,
+): MarkerValue {
+  if (install.kind === "package" || root === null) return channelFor(install, env, home, override);
+  return inspectUpdateChannel(root, override);
+}
+
 export type ChannelWrite =
   | { ok: true; path: string; value: string; previous: string }
   | { ok: false; reason: string; exitCode: 1 | 2 };

package/ts/src/runtime/git.ts

@@ -436,12 +436,52 @@ export const NO_REPOSITORY: GitStatus = {
 };
 
 /**
- * The git facts of `start`, for the install's kind: a clone's are inspected,
- * a package's are `NO_REPOSITORY` (CV22.DS10.US3 plateau 4). Grading the cwd
- * of a package install as a tree read "not a git repository" as a git error.
+ * The git facts of the install's `root` (`inspectionRootFor`): a package's
+ * are `NO_REPOSITORY` (CV22.DS10.US3 plateau 4), since grading the cwd of a
+ * package install as a tree read "not a git repository" as a git error. With
+ * no root -- an install that cannot be identified, and no `--start` -- no
+ * repository is inspected at all, and the rows say why (CR138, decision 2).
  */
-export function inspectGitFor(install: InstallKind, start: string): GitStatus {
-  return install.kind === "package" ? NO_REPOSITORY : inspectGit(start);
+export function inspectGitFor(install: InstallKind, root: string | null): GitStatus {
+  if (install.kind === "package") return NO_REPOSITORY;
+  if (root === null) {
+    const reason =
+      install.kind === "unknown" ? `install kind unknown: ${install.reason}` : "no repository";
+    return { ...NO_REPOSITORY, error: reason };
+  }
+  return inspectGit(root);
+}
+
+/**
+ * The clone role the install's checkout declares (CR138). A package has none
+ * to declare. With no root, nothing is read, and the oracle's answer for no
+ * repository stands: the default, with the note that says why.
+ */
+export function cloneRoleFor(install: InstallKind, root: string | null): MarkerValue {
+  if (install.kind === "package") return { value: "none", source: null, note: "package install" };
+  if (root === null) return { value: DEFAULT_CLONE_ROLE, source: null, note: "no repository" };
+  return inspectCloneRole(root);
+}
+
+/** The clone-role rows of `status` and `version`, one renderer for both (CR138). */
+export function renderCloneRoleLines(install: InstallKind, role: MarkerValue): string[] {
+  if (install.kind === "package") return ["Clone role: none (package install)"];
+  const lines = [`Clone role: ${role.value}`];
+  if (role.note) lines.push(`Clone role note: ${role.note}`);
+  return lines;
+}
+
+/**
+ * `update --check` for an install whose repository is not asked: the same
+ * shape as the check's own `unknown`, with the reason (CR138). An install that
+ * cannot be identified has no checkout to ask, and the cwd is not one.
+ */
+export function unavailableUpdateCheck(
+  version: string,
+  updateChannel: MarkerValue,
+  note: string,
+): UpdateAvailability {
+  return availability(version, updateChannel, { note });
 }
 
 /**
@@ -470,8 +510,7 @@ export function renderRuntimeVersion(report: RuntimeVersionReport): string {
   lines.push(`Version: ${report.version}`);
   lines.push(...renderInstallLines(report.install));
   lines.push(...renderRepositoryLines(report.install, report.git, false));
-  lines.push(`Clone role: ${report.cloneRole.value}`);
-  if (report.cloneRole.note) lines.push(`Clone role note: ${report.cloneRole.note}`);
+  lines.push(...renderCloneRoleLines(report.install, report.cloneRole));
   lines.push(`Update channel: ${report.updateChannel.value}`);
   if (report.updateChannel.note) lines.push(`Update channel note: ${report.updateChannel.note}`);
   return `${lines.join("\n")}\n`;

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,32 @@ 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}` };
+}
+
+/**
+ * Where the repository rows of `status`, `version`, and `diagnose` come from
+ * (CR138): `start` when one is given -- `version --start PATH`, or a test --
+ * else a clone's own checkout, else nowhere. Never the cwd. For a skill the
+ * cwd is the person's project, and git run there reads that project's config,
+ * where `core.fsmonitor` names a command git runs on `status`.
+ */
+export function inspectionRootFor(
+  install: InstallKind,
+  start: string | null | undefined,
+): string | null {
+  if (start !== null && start !== undefined) return resolve(start);
+  return install.kind === "clone" ? install.repository : null;
 }
 
 /** One line for a render or a log entry. */

package/ts/src/runtime/status.ts

@@ -26,16 +26,22 @@ import { inspectMigrationFiles } from "#extensions/migrations.ts";
 import { type DbPathEnv, dbNameForEnv, resolveMirrorHome } from "#frontDoor/dbPath.ts";
 import { DEFAULT_EMBEDDING_MODEL, DEFAULT_EXTRACTION_MODEL } from "#providers/config.ts";
 import { sortByCodePoint } from "#util/pythonText.ts";
-import { channelFor } from "./channel.ts";
+import { channelForReport } from "./channel.ts";
 import type { MarkerValue } from "./git.ts";
 import {
+  cloneRoleFor,
   type GitStatus,
-  inspectCloneRole,
   inspectGitFor,
-  inspectUpdateChannel,
+  renderCloneRoleLines,
   renderRepositoryLines,
 } from "./git.ts";
-import { detectInstallKind, type InstallKind, renderInstallLines } from "./installKind.ts";
+import {
+  detectInstallKind,
+  type InstallKind,
+  inspectionRootFor,
+  renderInstallLines,
+  thisFrontDoorPath,
+} from "./installKind.ts";
 
 export interface CoreMigrationHealth {
   ready: boolean;
@@ -339,6 +345,11 @@ export function detectNodeVersion(): string | null {
 }
 
 export interface BuildStatusOptions {
+  /**
+   * An explicit repository to inspect. Absent, the install's own: a clone's
+   * checkout, and for anything else none (CR138). It used to default to the
+   * cwd, which for a skill is the person's project.
+   */
   start?: string;
   mirrorHome?: string | null;
   channel?: string | null;
@@ -354,21 +365,6 @@ export interface BuildStatusOptions {
   install?: InstallKind;
 }
 
-/**
- * The channel the report shows. A clone is inspected at `start`, as the
- * oracle did and `version --start PATH` still means; a package has no tree at
- * `start` and keeps its channel in the user's config file (US3 D9).
- */
-function channelForStatus(
-  install: InstallKind,
-  startPath: string,
-  override: string | null,
-  env: NodeJS.ProcessEnv,
-): MarkerValue {
-  if (install.kind === "package") return channelFor(install, env, undefined, override);
-  return inspectUpdateChannel(startPath, override);
-}
-
 /**
  * Python's `resolve_mirror_home` raises `ValueError`, and
  * `build_runtime_status` prints `str(exc)` as `Mirror home note:`. The front
@@ -394,16 +390,15 @@ function mirrorHomeForStatus(env: DbPathEnv): { home: string | null; error: stri
 
 /** Port of `build_runtime_status`. */
 export function buildRuntimeStatus(options: BuildStatusOptions = {}): RuntimeStatusReport {
-  const startPath = resolve(options.start ?? process.cwd());
   const env = options.env ?? process.env;
-  const install =
-    options.install ??
-    detectInstallKind({ frontDoorPath: new URL("../frontDoor/cli.ts", import.meta.url).pathname });
-  // 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 error, said `attention
-  // needed`, and so refused every package update at the gate (CV22.DS10.US3
-  // plateau 4, found by the package lane of the update smoke).
-  const git = inspectGitFor(install, startPath);
+  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
+  // error, said `attention needed`, and so refused every package update at the
+  // gate (CV22.DS10.US3 plateau 4, found by the package lane of the update smoke).
+  const root = inspectionRootFor(install, options.start);
+  const git = inspectGitFor(install, root);
 
   let mirrorHome: string | null;
   let mirrorHomeError: string | null;
@@ -430,9 +425,9 @@ export function buildRuntimeStatus(options: BuildStatusOptions = {}): RuntimeSta
     core_migrations: inspectCoreMigrations(dbPath, dbExists),
     extensions: listInstalledExtensions(mirrorHome),
     extension_health: inspectExtensionHealth(mirrorHome, dbPath, dbExists),
-    clone_role: inspectCloneRole(startPath),
+    clone_role: cloneRoleFor(install, root),
     memory_env: memoryEnv,
-    update_channel: channelForStatus(install, startPath, options.channel ?? null, env),
+    update_channel: channelForReport(install, root, env, undefined, options.channel ?? null),
     node_version: options.nodeVersion === undefined ? detectNodeVersion() : options.nodeVersion,
   };
 }
@@ -533,8 +528,7 @@ export function renderRuntimeStatus(
     lines.push("Installed extensions: 0");
   }
   lines.push(...renderExtensionHealth(report.extension_health));
-  lines.push(`Clone role: ${report.clone_role.value}`);
-  if (report.clone_role.note) lines.push(`Clone role note: ${report.clone_role.note}`);
+  lines.push(...renderCloneRoleLines(report.install, report.clone_role));
   lines.push(`Update channel: ${report.update_channel.value}`);
   if (report.update_channel.note) lines.push(`Update channel note: ${report.update_channel.note}`);
   lines.push(`Node: ${report.node_version || "not found (TS front door requires Node >= 24)"}`);

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 }),