mirror-mind 0.33.0 → 0.33.1

package/docs/releases/index.md

@@ -12,6 +12,7 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [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.
 - [v0.32.0 — One Language, One Install](v0.32.0.md) — minor release that closes CV22, the TypeScript Core Port. Mirror Mind is one TypeScript package run by Node.js 24, installed with `npm install -g mirror-mind` and wired to Pi, Claude Code, Gemini CLI, or Codex by one documented step each; no Python remains in the repository or the shipped artifact; every command answers as it did. Eleven surfaces are retired with cutoffs, recorded in [Pending Cutoffs](pending-cutoffs.md), which this note carries. A new home imports only the Pi sessions newer than itself.

package/docs/releases/v0.33.1.md

@@ -0,0 +1,174 @@
+---
+digest: >
+  v0.33.1 is a maintenance release: six Change Requests from RS010, closed
+  since v0.33.0, and no story or epic. Its subject is one defect in four
+  surfaces. The welcome card, the status line, and both release-notes readers
+  answered for the directory the person was in, or for the git repository
+  around the install, instead of for the install that was running. Each now
+  asks the install itself: a package its own tree and the npm registry, a
+  clone its own checkout and remote. `release-notes pending` says `unknown`
+  when it cannot tell, and a `--ref` value can no longer run a command through
+  git. Upgrade with `mirror runtime update`; there is no migration.
+---
+
+# v0.33.1 — The Install Answers For Itself
+
+**Date:** 2026-10-15
+
+## Highlights
+
+- **The welcome card and the status line announce the update the running install
+  has** (CR135). A package asks the registry for its channel's version, a clone its own
+  checkout and remote. Before, both asked the git repository of whatever directory the
+  session started in: another project's tag could be announced, a package was never told
+  of a release, and the status line kept a stale `⬆` after the update.
+- **npm runs in the install's own directory**, for the card and for `runtime update`, so
+  a project's `.npmrc` can no longer choose the registry the card reads and the update
+  installs from.
+- **`release-notes latest` and `vX.Y.Z` read the notes the package ships** (CR133). On a
+  Homebrew install on Apple Silicon, where `/opt/homebrew` is itself a git repository,
+  they answered `Release notes: not found`.
+- **`release-notes pending` answers for the install, never the cwd** (CR134). A clone
+  reads its own channel's ref in its own checkout. A package asks the registry which
+  version its channel holds and reads that version's notes from its tarball. When
+  nothing can answer it says `Pending releases: unknown` with a reason and exits 1, so
+  `none` always means a source answered.
+- **`--ref` can no longer run a command.** A value like `--upload-pack=<command>`
+  reached `git fetch` as an option, and git ran it. Refs beginning with `-` are refused,
+  and every git call takes `--end-of-options` before its operands.
+- **A clone's update fetch has git's network budget again** (CR132): 120 seconds, not
+  the 2 seconds a local git call gets.
+
+## Where We Started
+
+`v0.33.0` was installed onto a Homebrew package on 2026-10-14, and three surfaces
+answered wrongly the same day. `mirror runtime release-notes v0.33.0` said `not found`, with
+the note sitting in the package. `release-notes pending` said `none` from `/tmp` and,
+from inside an unrelated project, listed that project's releases after fetching from its
+remote. The welcome card asked the same wrong repository whether Mirror had an update.
+
+The three had one root. The readers were ported faithfully from a Python core that ran
+from a checkout, where the cwd, git's top level, and the install were usually one
+directory. Under npm distribution they are three: a skill runs in the person's project,
+and a global prefix can sit inside someone else's repository. CV22 had already moved the
+version and the welcome card's release note onto the running tree, and handed `latest`
+that tree. But the reader still climbed out of it to git's top level, and `pending` and
+the update check still began at the cwd.
+
+The promotion of `v0.33.0` itself had stumbled on the same day. Its push timed out at two
+seconds and was finished by hand (CR132), and npm's `latest` had needed a move nobody's
+route printed (CR125).
+
+## What Changed
+
+**Each install asks about itself.** The card, the status line, and `pending` detect the
+install from where the front door lives, as `runtime channel` does, with nothing spawned
+and no cwd involved. A package reads its channel's dist-tag through the same call `runtime
+update --check` makes. A clone runs its check, its tag lookup, and its "commits behind"
+count in its own checkout. The channel shown is the install's. On `stable` the card checks
+at every render; on `main` it never checks and shows the cached verdict.
+
+**npm's directory is a trust decision.** A four-lens review of CR135's plan found that npm
+reads the `.npmrc` of the directory it runs in. A cloned project that ships
+`registry=` could therefore choose what the card announced and what `runtime update`
+installed. Every npm call the product makes now runs in the install's own root, whose
+project config is the package's own.
+
+**One bound for the session start.** The card's remote reads share one 5-second deadline,
+and the registry read does not retry, so an unreachable registry costs at most that. A
+cached update the install already has is shown by neither surface, and a successful
+`runtime update` records `up_to_date`.
+
+**Release notes come from the install.** `latest` and `vX.Y.Z` read `docs/releases` under
+the running tree and ask git nothing. `pending` reads, for a clone, `origin/<channel>`
+(or `--ref`) in the clone's own repository, after fetching it there. For a package, it
+resolves the channel's dist-tag to a version, as `runtime update` does when it plans.
+When that version is newer, `npm pack --ignore-scripts` fetches that exact tarball into a
+private directory, and its notes are read in memory and the directory removed. When it is
+not newer, nothing is downloaded.
+
+Three choices shaped the package path:
+
+- the registry tarball, not the GitHub branch: the branch is a second authority that can
+  disagree with the dist-tag, as a half-promoted release does;
+- not version numbers alone, which would not answer "what's new in this update?";
+- a reader of its own over `node:zlib` rather than a spawned `tar`, which would take
+  archive-chosen names as arguments. It stops at 64 MB inflated. It refuses an archive
+  that ends before its end-of-archive block, so a cut tarball cannot pass for a whole one
+  missing its newest notes.
+
+**`unknown` is said.** A failed fetch, a ref or dist-tag that does not resolve, an
+unreachable registry, or an install that cannot be identified answers `Pending releases:
+unknown` with a `Reason:` line and exit 1. `--no-fetch` reads a clone's ref as last
+fetched; a package keeps no copy of its channel, so it cannot answer offline.
+
+**The ref is an operand.** `--ref` was split at its first slash into a remote and a
+branch for `git fetch`, so `--upload-pack=touch X/y`, or `origin/--upload-pack=touch X`,
+reached git as an option, and git ran the command. A test claimed this could not happen.
+It passed only because its marker path was absolute, which the split cuts at the leading
+`/`. The exposure was local: whoever can pass `--ref` can run commands anyway. Refs
+beginning with `-` are now refused, and `fetch`, `ls-tree`, and `show` take
+`--end-of-options`, which covers the half after the slash.
+
+### What you will notice
+
+- On a package, `release-notes pending` shows `Source: npm mirror-mind@stable (<version>)`.
+  On a clone it shows `Source: origin/<channel>`, so a clone on `main` now reads
+  `origin/main`, where it used to read `origin/stable`.
+- A package on `main` answers `unknown`: npm has no `main` dist-tag, as `runtime update
+  --check` already says.
+- A `⬆` that the status line kept after an update is no longer shown once the install
+  has that version.
+
+## 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, so this release's changes to it apply from the next update
+on: npm running in the install's root, and recording `up_to_date` when it succeeds. A
+Homebrew package on Apple Silicon reads its release notes again from the first command
+after the update.
+
+## Also In This Release
+
+- **For maintainers.** `release:promote` pushes with the network budget, and a failed push
+  shows git's message with a recovery that says what is where (CR132). A `stable` release
+  now ends, in both places the route is printed, with `npm dist-tag add
+  mirror-mind@<version> latest`. The publish workflow stages under `stable` or `next` and
+  nothing else (CR125).
+- **For contributors.** The updater smoke gives the same result on any machine, whatever
+  the shell exports (CR137). The npm package smoke installs into a prefix that is a git
+  repository, the Homebrew shape. Its `npm` is a stub after the install, so it never
+  reaches the live registry.
+
+## Conscious Exclusions
+
+- **`runtime status` and `runtime version` on a clone**, which still read the clone's
+  repository and channel from the cwd, so a healthy clone reads `attention needed` outside
+  its checkout. It is the same family, captured as CR138.
+- **The `release` environment's ref check.** It accepts a dispatch from any ref, so a
+  branch's own copy of the publish workflow could stage (CR136).
+- **A `--channel` option on `pending`**, which `update --check` and `version` have.
+- **The `mm-release-notes` skill's wording**, which still says "the current stable
+  release", true on the default channel.
+
+## What We Learned
+
+A faithful port inherits its oracle's idea of where it runs. Each of these readers matched
+the Python core's goldens, and each was wrong once the program stopped living in the
+directory it was asked about. The tests agreed with the oracle for the same reason: they
+ran from a clone's root, where the cwd, git, and the install coincide. The new tests for
+the card and for `pending` run every case from two places, outside any repository and
+inside an unrelated one, and the answer must not move.
+
+A validation route must say which install it tests. On a machine with both a package and
+a linked checkout, a bare `mirror` runs whichever comes first on the PATH, and both
+report the same version.
+
+## Next Horizon
+
+CR138, the same defect in `runtime status` and `runtime version`, is the visible next
+step. CR136 would harden the publish route. RS010's other hygiene requests follow.

package/package.json

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

package/ts/src/frontDoor/runtimeRoute.ts

@@ -46,13 +46,18 @@ import { detectInstallKind, type InstallKind } from "#runtime/installKind.ts";
 import { MIGRATE_DECLINED_EXIT, renderMigrate, runMigrate } from "#runtime/migrate.ts";
 import {
   buildPendingReleaseNotes,
+  buildPendingReleaseNotesFromRegistry,
+  type ReleaseNotesBundle,
   readReleaseNote,
   renderReleaseNote,
   renderReleaseNotesBundle,
+  unknownReleaseNotes,
 } from "#runtime/releaseNotes.ts";
 import { buildRuntimeStatus, renderRuntimeStatus, statusVerdict } from "#runtime/status.ts";
 import {
   checkPackageUpdateAvailability,
+  defaultNpmRunner,
+  type NpmRunner,
   npmRootGlobal,
   renderPackageUpdateAvailability,
 } from "#runtime/strategies/package.ts";
@@ -61,8 +66,9 @@ import { frontDoorSpawner, postUpdateHints, runUpdate, type UpdateSpawn } from "
 import { statusAllowsUpdatePreflight } from "#runtime/updateGate.ts";
 import { renderUpdateResult, updateLogDetail } from "#runtime/updatePipeline.ts";
 import { expandHome } from "#util/paths.ts";
-import { composeWelcome, welcomeDisabled } from "#welcome/card.ts";
+import { composeWelcome, type RemoteCheck, welcomeDisabled } from "#welcome/card.ts";
 import { composeStatusLine } from "#welcome/statusLine.ts";
+import { isoNow, recordUpToDate } from "#welcome/updateCache.ts";
 
 /** The `runtime` subcommands this story ports. */
 export const TS_RUNTIME_READ_SUBCOMMANDS = new Set([
@@ -165,18 +171,39 @@ function writeErr(io: RuntimeRouteIo, text: string): void {
   (io.stderr ?? ((value: string) => process.stderr.write(value)))(text);
 }
 
-/** Port of `welcome.main`. Always exits 0, like the oracle. */
-export function runWelcomeRoute(argv: readonly string[], io: RuntimeRouteIo = {}): number {
+/**
+ * The seams of the routes that answer for the running install, beyond the
+ * route's own: the install and its npm, for tests. The welcome (CR135) and
+ * `release-notes pending` (CR134) take them.
+ */
+export interface InstallRouteIo extends RuntimeRouteIo {
+  install?: InstallKind;
+  npm?: NpmRunner;
+  /** The OS home whose config directory holds a package's channel file. */
+  osHome?: string;
+}
+
+export type WelcomeRouteIo = InstallRouteIo;
+
+/**
+ * Port of `welcome.main`. Always exits 0, like the oracle.
+ *
+ * The card and the status line answer for the install that is running, never
+ * for the cwd (CR135): Pi renders both in the person's project.
+ */
+export function runWelcomeRoute(argv: readonly string[], io: WelcomeRouteIo = {}): number {
   const env = io.env ?? process.env;
-  const cwd = io.cwd ?? process.cwd();
   const args = argv.slice(1);
   if (welcomeDisabled(env)) return 0;
 
   const home = resolveWelcomeHome(optionValue(args, "--mirror-home"), env);
+  // The running tree's manifest: a file read, so the status line still spawns nothing.
+  const version = packageVersion(runningTreeRoot()) ?? "unknown";
 
   if (args.includes("--status-line")) {
     const line = composeStatusLine({
       mirrorHome: home,
+      installedVersion: version,
       sessionId: optionValue(args, "--session-id"),
       env,
     });
@@ -184,23 +211,37 @@ export function runWelcomeRoute(argv: readonly string[], io: RuntimeRouteIo = {}
     return 0;
   }
 
-  const version = packageVersion(runningTreeRoot()) ?? "unknown";
-  const card = composeWelcome({
+  const { card, check } = composeWelcome({
     mirrorHome: home,
-    cwd,
-    treeRoot: runningTreeRoot(),
+    install: io.install ?? detectThisInstall(),
     env,
     version,
-    updateChannel: inspectUpdateChannel(cwd, null),
+    ...(io.npm === undefined ? {} : { npm: io.npm }),
+    ...(io.osHome === undefined ? {} : { osHome: io.osHome }),
   });
   if (card) writeOut(io, `${card}\n`);
+  if (home !== null && check !== null) logWelcomeCheck(home, env, check);
   return 0;
 }
 
+/**
+ * One front-door line per remote check, so a slow session start can be
+ * explained later: what was asked, how it answered, how long it took. Never a
+ * path or a version.
+ */
+function logWelcomeCheck(home: string, env: NodeJS.ProcessEnv, check: RemoteCheck): void {
+  logFrontDoor(frontDoorLogPath(join(home, dbNameForEnv(env.MEMORY_ENV || "production"))), {
+    command: "welcome",
+    route: "ts",
+    exitCode: 0,
+    detail: `update-check source=${check.source} verdict=${check.verdict} ms=${check.ms}`,
+  });
+}
+
 /** Port of the read half of `cmd_runtime`. */
 export async function runRuntimeReadRoute(
   argv: readonly string[],
-  io: RuntimeRouteIo = {},
+  io: InstallRouteIo = {},
 ): Promise<number> {
   const env = io.env ?? process.env;
   const cwd = io.cwd ?? process.cwd();
@@ -280,19 +321,14 @@ export async function runRuntimeReadRoute(
   if (subcommand === "release-notes") {
     const target = firstPositional(args.slice(1)) ?? "latest";
     if (target === "pending") {
-      writeOut(
-        io,
-        renderReleaseNotesBundle(
-          buildPendingReleaseNotes({
-            // `--from` omitted falls back to the checkout's own version,
-            // exactly as the oracle does before normalizing.
-            currentVersion: optionValue(args, "--from") ?? version,
-            ref: optionValue(args, "--ref") ?? "origin/stable",
-            fetch: !args.includes("--no-fetch"),
-            start: cwd,
-          }),
-        ),
-      );
+      const pending = pendingReleaseNotes(args, io, env, version);
+      if ("usage" in pending) {
+        writeErr(io, pending.usage);
+        return 2;
+      }
+      writeOut(io, renderReleaseNotesBundle(pending.bundle));
+      // `unknown` exits 1, as `update --check` does on `unresolved` (CR134, decision 3).
+      return pending.bundle.unknown_reason === null ? 0 : 1;
     } else {
       // The notes ship in the package at the same path as in the checkout
       // (US3 D8), read from the tree that holds the running front door --
@@ -459,9 +495,13 @@ function runRuntimeUpdate(
   // The update lane asks npm, once, whether `-g` addresses this install: a
   // package outside npm's own global root is not the one `npm install -g`
   // would replace. The read routes do not pay for the probe.
+  //
+  // 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(),
+    npmRootGlobal: npmRootGlobal(runningTreeRoot()),
   });
   const start = install.kind === "clone" ? install.repository : cwd;
   const channel = channelFor(install, env, homedir(), channelOverride);
@@ -548,6 +588,16 @@ function runRuntimeUpdate(
   });
 
   writeOut(io, renderUpdateResult(result));
+  // The install now holds its channel's version: say so where the welcome card
+  // and the status line read it, or they keep announcing what was just
+  // installed (CR135).
+  if (result.success && !args.includes("--dry-run")) {
+    recordUpToDate(mirrorHome, {
+      channel: channel.value,
+      commit: install.kind === "clone" ? result.newRef : null,
+      checkedAt: isoNow(),
+    });
+  }
   if (repair && result.success) {
     // After the stages, not before them: the instruction is what to do NEXT,
     // and it reads as a caption on a result the operator has already seen.
@@ -596,6 +646,74 @@ function detectThisInstall(): InstallKind {
   return detectInstallKind({ frontDoorPath: frontDoorSelfPath() });
 }
 
+/**
+ * `release-notes pending` for the install that is running, never for the cwd
+ * (CR134), which for a skill is the person's project. A clone reads its own
+ * channel's ref -- or `--ref` -- in its own repository; a package asks the
+ * registry what its channel holds; an install that cannot be identified has no
+ * source, and says so.
+ */
+function pendingReleaseNotes(
+  args: readonly string[],
+  io: InstallRouteIo,
+  env: NodeJS.ProcessEnv,
+  version: string,
+): { bundle: ReleaseNotesBundle } | { usage: string } {
+  const install = io.install ?? detectThisInstall();
+  const osHome = io.osHome ?? homedir();
+  const ref = optionValue(args, "--ref");
+  const fetch = !args.includes("--no-fetch");
+
+  if (install.kind === "clone") {
+    return {
+      bundle: buildPendingReleaseNotes({
+        // `--from` omitted falls back to the running tree's own version.
+        currentVersion: optionValue(args, "--from") ?? version,
+        ref: ref ?? upstreamFor(channelFor(install, env, osHome)),
+        repository: install.repository,
+        fetch,
+      }),
+    };
+  }
+
+  if (install.kind === "package") {
+    if (ref !== null) {
+      return {
+        usage:
+          `release-notes pending: --ref names a git ref, and this install is a package ` +
+          `(${install.name}@${install.version}), which reads its channel from the npm registry\n`,
+      };
+    }
+    const currentVersion = optionValue(args, "--from") ?? install.version;
+    const channel = channelFor(install, env, osHome).value;
+    if (!fetch) {
+      return {
+        bundle: unknownReleaseNotes(
+          currentVersion,
+          `npm ${install.name}@${channel}`,
+          "a package keeps no copy of its channel to read offline; run without --no-fetch",
+        ),
+      };
+    }
+    return {
+      bundle: buildPendingReleaseNotesFromRegistry({
+        currentVersion,
+        install,
+        channel,
+        npm: io.npm ?? defaultNpmRunner,
+      }),
+    };
+  }
+
+  return {
+    bundle: unknownReleaseNotes(
+      optionValue(args, "--from") ?? version,
+      null,
+      `install kind unknown (${install.reason})`,
+    ),
+  };
+}
+
 /**
  * argparse's positional for `release-notes`: the first bare token that is not
  * consumed as the VALUE of `--from` or `--ref`. Walking the list is the only

package/ts/src/runtime/git.ts

@@ -13,7 +13,9 @@
 // Timeouts follow the oracle's two budgets, and for the reason recorded there:
 // local inspections are near-instant, while a single shared 2 s budget once
 // made a network operation report failure after it had already succeeded
-// (the v0.30.1 release incident). Network reads get 120 s.
+// (the v0.30.1 release incident). Network reads get 120 s, except where a
+// caller holds a tighter budget of its own: the welcome card's update check
+// runs inside the session start and passes what is left of its 5 s (CR135).
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
@@ -260,11 +262,15 @@ function availability(
  * Is the channel's remote branch ahead of HEAD? The remote query is the only
  * authority: remote-tracking refs are only as fresh as the last fetch, and
  * trusting them is how a clone two releases behind gets told it is ahead.
+ *
+ * `networkTimeoutMs` bounds that query; `runtime update --check` keeps the
+ * network budget, and the welcome card passes what is left of its own.
  */
 export function checkUpdateAvailability(
   start: string,
   channel: string | null,
   version: string,
+  networkTimeoutMs: number = GIT_NETWORK_TIMEOUT_MS,
 ): UpdateAvailability {
   const startPath = resolve(start);
   const git = inspectGit(startPath);
@@ -303,7 +309,7 @@ export function checkUpdateAvailability(
   const lsRemote = runGit(
     ["ls-remote", remote, `refs/heads/${branch}`],
     git.repository,
-    GIT_NETWORK_TIMEOUT_MS,
+    networkTimeoutMs,
   );
   if (lsRemote.code !== 0 || !lsRemote.stdout) {
     return availability(version, updateChannel, {