mellos-mapping 0.24.0 → 0.26.0

package/docs/map-api.md

@@ -64,20 +64,35 @@ a group does not silently move members: include their intended node moves in
 the same update or transaction. Normal single-field changes keep the old graph
 constraints; use a batch for changes that require a coordinated final graph.
 
-Every graph writer in the current MCP, HTTP viewer and watcher uses a cooperative
-cross-process project lock. MCP expectedRevision is compared inside that lock
-before loading the proposed changes into the saved map. `CONFLICT` requires a
-fresh read and reconsideration of the edit. `BUSY` means another transaction is
-active; retry after it completes. There is no background lock polling. Locks are
-released on normal completion/error; a confirmed dead PID can be recovered.
-An incomplete owner file after an abrupt crash is refused for manual inspection,
-not guessed stale from its age.
+Every graph writer in the current MCP, HTTP viewer and watcher uses the same
+`withStoreLock` boundary. It takes a non-blocking OS exclusive lock on one fixed
+regular file, `.mellos/.write-lock`; named pages and the default page share it.
+That file is separate from the map JSON files and is never removed or renamed
+as part of locking. The read, revision check, change and save happen while the
+lock is held.
+Contention returns `BUSY`; retry after the other operation completes. There is
+no background lock polling. `LOCK_MIGRATION_REQUIRED` means the lock path is
+still a directory from the old protocol; `LOCK_UNAVAILABLE` means the required
+native binding or supported platform is unavailable. Neither error permits an
+unlocked write. Normal completion/error releases the lock, and the OS also
+releases it when the owning process exits or crashes. A leftover lock
+file is expected and does not indicate a live or stale owner.
+
+MCP `expectedRevision` is optional. When supplied, it is compared inside the
+lock; `CONFLICT` requires a fresh read and reconsideration of the edit. Omitting
+it still serializes the operation against other writers, but does not check
+whether its inputs came from an older read. A later update can overwrite the
+same field or replace an entire `context` or `sources` value. Pass the revision
+from the page read whenever an edit depends on that read.
 
 Low-level library saveMapFile, hand edits, and older running processes do not
-participate in this contract. Restart MCP processes and native watchers after
-upgrading. Opening a Web surface upgrades services that lack format-2 support;
-existing tabs must reconnect with the newly returned URL. Atomic file
-replacement alone does not make a caller's stale read/modify/write safe.
+participate in this contract. Atomic file replacement alone does not make a
+caller's stale read/modify/write safe. Stop all old MCP, HTTP viewer and watcher
+processes for the project before upgrading; restart the HTTP service as well
+as reopening its tabs. A leftover old lock directory requires the manual
+[migration steps](locking.md#upgrade-from-directory-locks). There is no hot
+upgrade of the lock protocol, and supporting map format 2 alone does not
+establish that all writers use the new lock.
 
 Legacy `mmap_remove {pages:[...]}` remains a separately documented batch of file
 deletions, with explicit partial success and historical reference behavior. It
@@ -106,7 +121,8 @@ and the page is saved once; a refusal preserves the original file bytes.
 ```
 
 Machine-readable error codes include NOT_FOUND, INVALID_STORE, REFUSED,
-CONFLICT, BUSY, INVALID_CURSOR, INVALID_ARGUMENT, REFERENCED and SAVE_FAILED.
+CONFLICT, BUSY, LOCK_MIGRATION_REQUIRED, LOCK_UNAVAILABLE, INVALID_CURSOR,
+INVALID_ARGUMENT, REFERENCED and SAVE_FAILED.
 Malformed schema inputs remain MCP invalid-argument errors. Read calls do not
 open panels or create page files.
 

package/lib/store/migration.js

@@ -1,7 +1,8 @@
-import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import { existsSync, renameSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { PAGES_DIR_NAME } from './pages.js';
 import { configFilePath } from './policy.js';
+import { withStoreLock } from './transaction.js';
 // ---------------------------------------------------------------------------
 // legacy migration — stores written under the old host-coupled location
 // ---------------------------------------------------------------------------
@@ -29,18 +30,24 @@ export function migrateLegacyStore(defaultFile) {
     const legacyDefault = join(projectRoot, LEGACY_STATE_FILE_RELATIVE_PATH);
     const legacyPages = join(dirname(legacyDefault), LEGACY_PAGES_DIR_NAME);
     const legacyConfig = join(dirname(legacyDefault), LEGACY_CONFIG_FILE_NAME);
-    const hasLegacy = existsSync(legacyDefault) || existsSync(legacyPages) || existsSync(legacyConfig);
-    const hasCurrent = existsSync(defaultFile)
+    const hasLegacy = () => existsSync(legacyDefault) || existsSync(legacyPages) || existsSync(legacyConfig);
+    const hasCurrent = () => existsSync(defaultFile)
         || existsSync(join(dirname(defaultFile), PAGES_DIR_NAME))
         || existsSync(configFilePath(defaultFile));
-    if (!hasLegacy || hasCurrent)
+    if (!hasLegacy() || hasCurrent())
         return false;
-    mkdirSync(dirname(defaultFile), { recursive: true });
-    if (existsSync(legacyDefault))
-        renameSync(legacyDefault, defaultFile);
-    if (existsSync(legacyPages))
-        renameSync(legacyPages, join(dirname(defaultFile), PAGES_DIR_NAME));
-    if (existsSync(legacyConfig))
-        renameSync(legacyConfig, configFilePath(defaultFile));
-    return true;
+    return withStoreLock(defaultFile, () => {
+        // A writer or another startup may have committed after the fast checks.
+        // Recheck under the same lock used by all current project mutations;
+        // rename is allowed to replace its destination on every supported OS.
+        if (!hasLegacy() || hasCurrent())
+            return false;
+        if (existsSync(legacyDefault))
+            renameSync(legacyDefault, defaultFile);
+        if (existsSync(legacyPages))
+            renameSync(legacyPages, join(dirname(defaultFile), PAGES_DIR_NAME));
+        if (existsSync(legacyConfig))
+            renameSync(legacyConfig, configFilePath(defaultFile));
+        return true;
+    });
 }

package/lib/store/native-lock.d.ts

@@ -0,0 +1,5 @@
+export interface NativeLock {
+    tryLock(fd: number): boolean;
+    unlock(fd: number): void;
+}
+export declare function nativeLock(): NativeLock;

package/lib/store/native-lock.js

@@ -0,0 +1,27 @@
+/** Load the shipped N-API implementation without a runtime npm dependency. */
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+let loaded;
+export function nativeLock() {
+    if (loaded)
+        return loaded;
+    if (Number(process.versions.napi ?? 0) < 9) {
+        throw new Error('Project locks require Node-API 9 (Node 18.17+ or 20.3+).');
+    }
+    // Bundled entry points live in dist/; source and npm library modules live
+    // two directories below the package root. Never resolve from the user's cwd.
+    const candidates = [
+        new URL('./native-lock.cjs', import.meta.url),
+        new URL('../../dist/native-lock.cjs', import.meta.url),
+    ];
+    const entry = candidates.find(candidate => existsSync(candidate));
+    if (!entry)
+        throw new Error('The installed package is missing dist/native-lock.cjs; reinstall the complete package.');
+    const backend = createRequire(import.meta.url)(fileURLToPath(entry));
+    if (typeof backend.tryLock !== 'function' || typeof backend.unlock !== 'function') {
+        throw new Error('The installed native lock backend is invalid.');
+    }
+    loaded = backend;
+    return backend;
+}

package/lib/store/transaction.d.ts

@@ -1,4 +1,6 @@
 import type { MellosMap } from '../domain/types.js';
+/** Viewer health must identify the writer protocol before a new client reuses it. */
+export declare const STORE_LOCK_PROTOCOL = "os-file-v1";
 export declare class LedgerError extends Error {
     readonly code: string;
     readonly details: Record<string, unknown>;
@@ -8,5 +10,10 @@ export declare const revisionOf: (map: MellosMap) => string;
 export declare function assertRevision(actual: string, expected?: string): void;
 /** A named page and the default page share the same project lock. */
 export declare function storeDirectory(file: string): string;
-/** No timed polling: contention is an explicit retryable BUSY result. Never steal a live lock. */
-export declare function withStoreLock<T>(file: string, action: () => T): T;
+/**
+ * A synchronous transaction on a permanent, independent OS lock file.
+ * The action must finish synchronously; all cooperating writers use this entry.
+ * Never unlink/rename this file: another opener must reach the same lock object.
+ * Contention is BUSY immediately, with no timer, stale lease or PID recovery.
+ */
+export declare function withStoreLock<T>(file: string, action: () => T & (T extends PromiseLike<unknown> ? never : unknown)): T;

package/lib/store/transaction.js

@@ -1,8 +1,11 @@
 /** Cooperative, cross-process transactions for MCP and HTTP writers. */
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { randomUUID, createHash } from 'node:crypto';
+import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, realpathSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
 import { serializeMap } from './format.js';
+import { nativeLock } from './native-lock.js';
+/** Viewer health must identify the writer protocol before a new client reuses it. */
+export const STORE_LOCK_PROTOCOL = 'os-file-v1';
 export class LedgerError extends Error {
     code;
     details;
@@ -20,72 +23,98 @@ export function assertRevision(actual, expected) {
 /** A named page and the default page share the same project lock. */
 export function storeDirectory(file) {
     const dir = dirname(file);
-    return dir.endsWith('/pages') || dir.endsWith('\\pages') ? dirname(dir) : dir;
-}
-function deadOwner(lock) {
+    // Keep a configured pages directory tied to its project even when that
+    // directory itself is a symlink. Case variants must share the lock on
+    // Windows and case-insensitive macOS volumes (and are harmless elsewhere).
+    if (basename(dir).toLowerCase() === 'pages')
+        return dirname(dir);
+    let canonical = dir;
     try {
-        const owner = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
-        if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0)
-            return false;
-        try {
-            process.kill(owner.pid, 0);
-            return false;
-        }
-        catch (e) {
-            return e.code === 'ESRCH';
-        }
+        canonical = realpathSync.native(dir);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
     }
-    catch {
-        return false;
+    // An explicit --file may reach pages through a differently named alias.
+    return basename(canonical).toLowerCase() === 'pages' ? dirname(canonical) : canonical;
+}
+function checkLockPath(lock) {
+    const entry = lstatSync(lock, { throwIfNoEntry: false });
+    if (entry?.isDirectory()) {
+        throw new LedgerError('LOCK_MIGRATION_REQUIRED', `Legacy directory lock at ${lock}. Stop all old MCP servers, viewers and watchers for this project, then move that directory aside for inspection and retry. Never remove the new regular lock file.`, { path: lock });
+    }
+    if (entry && !entry.isFile()) {
+        throw new LedgerError('LOCK_UNAVAILABLE', `Project lock must be a regular file, not a symlink or special file: ${lock}`, { path: lock });
     }
 }
-/** No timed polling: contention is an explicit retryable BUSY result. Never steal a live lock. */
+/**
+ * A synchronous transaction on a permanent, independent OS lock file.
+ * The action must finish synchronously; all cooperating writers use this entry.
+ * Never unlink/rename this file: another opener must reach the same lock object.
+ * Contention is BUSY immediately, with no timer, stale lease or PID recovery.
+ */
 export function withStoreLock(file, action) {
+    let backend;
+    try {
+        backend = nativeLock();
+    }
+    catch (error) {
+        throw new LedgerError('LOCK_UNAVAILABLE', `Cannot load the operating-system lock backend: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const dir = storeDirectory(file);
     mkdirSync(dir, { recursive: true });
     const lock = join(dir, '.write-lock');
-    const owner = join(lock, 'owner.json');
-    const token = randomUUID();
+    checkLockPath(lock);
+    let fd;
+    // a+ atomically opens/creates without truncation. At a legacy/new startup
+    // race, either old mkdir wins (we refuse its directory), or our file wins
+    // (old mkdir gets EEXIST and cannot find owner.json, so refuses to write).
     try {
-        mkdirSync(lock);
+        fd = openSync(lock, 'a+', 0o600);
     }
     catch (error) {
-        if (error.code !== 'EEXIST')
-            throw error;
-        // Reapers serialize inside the old directory and recheck its owner after acquiring.
-        // Missing/invalid owners are deliberately not reclaimed on an age heuristic.
-        if (!deadOwner(lock))
-            throw new LedgerError('BUSY', `Another writer owns ${lock}; retry after it completes. An orphan without owner metadata needs manual inspection.`);
+        checkLockPath(lock);
+        throw new LedgerError('LOCK_UNAVAILABLE', `Cannot open project lock ${lock}: ${error instanceof Error ? error.message : String(error)}`, { path: lock });
+    }
+    let acquired = false;
+    try {
+        checkLockPath(lock);
+        if (!fstatSync(fd).isFile())
+            throw new LedgerError('LOCK_UNAVAILABLE', `Project lock is not a regular file: ${lock}`);
         try {
-            mkdirSync(join(lock, '.reap'));
-        }
-        catch {
-            throw new LedgerError('BUSY', 'Another process is recovering the writer lock.');
+            acquired = backend.tryLock(fd);
         }
-        if (!deadOwner(lock)) {
-            rmSync(join(lock, '.reap'), { recursive: true, force: true });
-            throw new LedgerError('BUSY', 'Writer ownership changed.');
+        catch (error) {
+            throw new LedgerError('LOCK_UNAVAILABLE', `Cannot acquire project lock ${lock}: ${error instanceof Error ? error.message : String(error)}`, { path: lock });
         }
-        rmSync(lock, { recursive: true });
+        if (!acquired)
+            throw new LedgerError('BUSY', `Another writer owns ${lock}; retry after it completes.`);
+        return action();
+    }
+    finally {
+        // Closing also releases this descriptor's lock if explicit unlock fails.
+        // Cleanup must not misreport an already committed map as unsaved.
         try {
-            mkdirSync(lock);
+            if (acquired)
+                backend.unlock(fd);
         }
         catch {
-            throw new LedgerError('BUSY', 'Another writer acquired the recovered lock.');
+            warnLockCleanup(`Could not explicitly unlock ${lock}; closing its file handle.`);
+        }
+        finally {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                warnLockCleanup(`Could not close the project lock handle for ${lock}; restart this process before retrying writes.`);
+            }
         }
     }
-    let initialized = false;
+}
+function warnLockCleanup(message) {
     try {
-        writeFileSync(owner, JSON.stringify({ pid: process.pid, token }), { flag: 'wx' });
-        initialized = true;
-        return action();
-    }
-    finally {
-        // Only remove the directory still owned by this invocation.
-        try {
-            if (!initialized || JSON.parse(readFileSync(owner, 'utf8')).token === token)
-                rmSync(lock, { recursive: true });
-        }
-        catch { /* A cleanup error must not misreport a successfully committed map as unsaved. */ }
+        process.stderr.write(`mellos-mapping: ${message}\n`);
     }
+    catch { /* Preserve the action's result. */ }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "mcpName": "io.github.GuangminJu/mellos-mapping",
   "description": "A live layered dependency map for bottom-up development — MCP server + terminal pane. Ghost the design first, then light nodes up from the bottom as they are built and verified.",
   "type": "module",
@@ -65,12 +65,18 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
+  "omp": {
+    "extensions": [
+      "./dist/omp-extension.mjs"
+    ]
+  },
   "files": [
     "dist",
     "lib",
     "README.zh-CN.md",
     "docs/codex.md",
     "docs/map-api.md",
+    "docs/locking.md",
     "scripts/codex-register.mjs",
     "scripts/codex-cli.mjs",
     "scripts/install-mmap-command.mjs",
@@ -82,7 +88,7 @@
     "scripts/watcher-command.mjs"
   ],
   "engines": {
-    "node": ">=18"
+    "node": "^18.17.0 || >=20.3.0"
   },
   "scripts": {
     "test": "vitest run",
@@ -94,9 +100,10 @@
     "check:package": "node scripts/check-package-surface.mjs",
     "check:codex": "node scripts/check-codex-package.mjs",
     "check:reuse": "node scripts/check-reuse.mjs",
+    "check:locks": "node scripts/check-store-lock.mjs",
     "benchmark:render": "node scripts/benchmark-render.mjs",
     "prepack": "npm run build",
-    "verify": "npm run typecheck && npm run test && npm run build && npm run check:reuse && npm run check:package && npm run check:codex && npm run check:release"
+    "verify": "npm run typecheck && npm run test && npm run build && npm run check:locks && npm run check:reuse && npm run check:package && npm run check:codex && npm run check:release"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
@@ -105,6 +112,7 @@
     "@xterm/addon-fit": "0.11.0",
     "@xterm/xterm": "6.0.0",
     "esbuild": "^0.25.0",
+    "fs-native-extensions": "1.5.1",
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
     "ws": "8.21.3",

package/scripts/install-mmap-command.mjs

@@ -37,7 +37,7 @@
  * point, so importing this file is inert.
  */
 import { spawnSync } from 'node:child_process';
-import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { launchedAsEntry, pluginRootOf } from './pane-core.mjs';
@@ -56,9 +56,36 @@ export function binDirIn(localAppData) {
   return join(localAppData, 'mellos-mapping', 'bin');
 }
 
+/**
+ * Per-user command directories that are USUALLY already on the PATH, in the
+ * order they should be tried, given a `%LOCALAPPDATA%` and a home directory.
+ *
+ * These exist for one case: `setx` refuses to write a user PATH this script
+ * will not carry safely (see setxRefusal), and the canonical `bin` directory is
+ * therefore unreachable for good. A machine with a long PATH — conda, five
+ * Pythons, several toolchains — then has no way to run `mmap` at all, which is
+ * the opposite of what the command is for. Dropping the same two shims into a
+ * directory the PATH already names fixes that without editing anything:
+ *
+ *   - `WindowsApps` is Windows' own per-user command directory (the one App
+ *     Execution Aliases live in) and is on the PATH of every interactive user;
+ *   - `~/.local/bin` is the same idea as the rest of the world spells it.
+ *
+ * Only ever consulted when the PATH route is refused, and only if the directory
+ * exists, is reachable on the CURRENT PATH, and accepts a write.
+ */
+export function linkDirCandidates(localAppData, home) {
+  return [join(localAppData, 'Microsoft', 'WindowsApps'), join(home, '.local', 'bin')];
+}
+
+/** The candidates this PATH can already reach, in the order they were given. */
+export function reachableDirs(candidates, rawPath, exists) {
+  return candidates.filter((dir) => exists(dir) && pathContains(rawPath, dir));
+}
+
 /** The cmd/PowerShell shim: forwards every argument, prints nothing of its own. */
 export function cmdShim(mmapPath) {
-  return ['@echo off', `node "${mmapPath}" %*`, ''].join('\r\n');
+  return ['@echo off', `rem ${SHIM_MARKER}`, `node "${mmapPath}" %*`, ''].join('\r\n');
 }
 
 /**
@@ -67,7 +94,7 @@ export function cmdShim(mmapPath) {
  * `C:\Users` is one escape away from being someone else's bug.
  */
 export function shShim(mmapPath) {
-  return ['#!/bin/sh', `exec node "${mmapPath.replaceAll('\\', '/')}" "$@"`, ''].join('\n');
+  return ['#!/bin/sh', `# ${SHIM_MARKER}`, `exec node "${mmapPath.replaceAll('\\', '/')}" "$@"`, ''].join('\n');
 }
 
 /** PATH entries as written, empties dropped — the unit every rule below works on. */
@@ -175,6 +202,68 @@ function applyPath(raw, wanted) {
   }
 }
 
+/** The command name this plugin installs, and the script it must point at. */
+export const SHIM_COMMAND = 'mmap';
+export const SHIM_SCRIPT = 'mmap.mjs';
+
+/**
+ * Written into both shim shapes. The path alone says nothing reliable about
+ * who wrote a file in a shared directory — the same plugin may be installed
+ * under any checkout name — so ownership gets its own line, and old shims are
+ * still recognized by their target.
+ */
+export const SHIM_MARKER = 'mellos-mapping mmap shim';
+
+/**
+ * The `mmap.mjs` bundle a shim launches, normalized to forward slashes, or
+ * undefined when the text quotes no such path. One reader for every question
+ * about ownership: the cmd shape writes the Windows path, the git-bash shape
+ * the forward-slash one, and a rule that knew only one form would answer
+ * differently about a shim's two files.
+ */
+export function shimTarget(content) {
+  const quoted = /"([^"]*mmap\.mjs)"/.exec(content)?.[1];
+  return quoted === undefined ? undefined : quoted.replaceAll('\\', '/');
+}
+
+/**
+ * Is this shim file one of ours — a `mmap` command that launches a
+ * `dist/mmap.mjs` of this plugin family?
+ *
+ * The fallback directory is SHARED (`WindowsApps`, `~/.local/bin`): a file
+ * called `mmap` there may belong to somebody else, and a plugin that overwrites
+ * a stranger's command on its way in has no standing to be careful on the way
+ * out. Ownership is read from the file's own text. Every shim written since the
+ * marker exists carries it — an install under ANY directory name owns its
+ * copies — and shims written before it are recognized by their target, whose
+ * path named the plugin.
+ */
+export function shimIsOurs(content) {
+  if (content.includes(SHIM_MARKER)) return true;
+  const target = shimTarget(content);
+  return target !== undefined && /mellos-mapping/i.test(target);
+}
+
+/**
+ * Does this shim launch exactly `mmapPath`? Both shapes write the path their
+ * own way, so the comparison happens on the normalized form — the rule every
+ * removal in this file uses, or a git-bash copy would outlive the uninstall
+ * that removed its cmd sibling.
+ */
+export function shimLaunches(content, mmapPath) {
+  const target = shimTarget(content);
+  return target !== undefined && target === mmapPath.replaceAll('\\', '/');
+}
+
+/** Read a file's text, or undefined when it is absent or unreadable. */
+function readIfPresent(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * The install itself, with the narration stripped out: write the shims, bring
  * the PATH in line, report what happened as data. This outcome object IS the
@@ -183,13 +272,16 @@ function applyPath(raw, wanted) {
  *
  * @returns one of
  *   {kind: 'not-built', missing}  — dist/mmap.mjs absent, nothing written;
- *   {kind: 'installed', binDir, cmdPath, shPath, path, wanted, reason?} —
+ *   {kind: 'installed', binDir, cmdPath, shPath, path, wanted, reason?, alias?} —
  *     shims written; `path` says what happened to the USER PATH:
  *       'unchanged' — the entry was already there,
  *       'updated'   — the entry was appended,
  *       'refused'   — setx would damage this PATH (`reason` says how); the
  *                     entry in `wanted` must be added by hand,
  *       'error'     — setx itself failed (`reason` is its message).
+ *     `alias` is the second copy in a directory the PATH already names, written
+ *     only when the PATH route came up short OR when one is already there and
+ *     needs to keep pointing at this install.
  */
 export function install(localAppData, pluginRoot) {
   const mmapPath = join(pluginRoot, 'dist', 'mmap.mjs');
@@ -211,14 +303,56 @@ export function install(localAppData, pluginRoot) {
   const raw = readUserPath();
   const wanted = pathWith(raw, binDir);
   const plan = planPath(raw, wanted);
-  if (plan.action === 'unchanged') return { kind: 'installed', binDir, cmdPath, shPath, path: 'unchanged', wanted };
+  /**
+   * When the PATH cannot be brought to the shim, bring the shim to the PATH:
+   * same two files, dropped into a directory this machine already searches.
+   *
+   * Two rules keep that from becoming a second install nobody owns. A
+   * candidate is skipped when its `mmap` belongs to somebody else — a shared
+   * directory is not ours to overwrite. And a copy that IS ours is refreshed
+   * on every install, not only when the PATH route fails: the shim embeds the
+   * absolute path of one plugin copy, and an untouched copy from an earlier
+   * install would keep launching a directory the next upgrade deletes.
+   *
+   * @param force - create the copy even when none exists yet (the PATH route
+   *   came up short, so this is the only runnable command).
+   * @returns `{dir, cmdPath, shPath, refreshed}` for the copy, or undefined.
+   */
+  const alias = (force) => {
+    const home = process.env['USERPROFILE'] ?? process.env['HOME'];
+    if (home === undefined || home === '') return undefined;
+    // every candidate gets its own try: a directory that exists and is on the
+    // PATH can still refuse the write, and that is a reason to try the next
+    // one, not to give up on having a runnable command
+    for (const dir of reachableDirs(linkDirCandidates(localAppData, home), process.env['PATH'] ?? '', existsSync)) {
+      const linkedCmd = join(dir, 'mmap.cmd');
+      const linkedSh = join(dir, 'mmap');
+      const existing = [readIfPresent(linkedCmd), readIfPresent(linkedSh)].filter((text) => text !== undefined);
+      const foreign = existing.some((text) => !shimIsOurs(text));
+      if (foreign) continue; // somebody else's command: not ours to touch
+      const refreshed = existing.length > 0;
+      if (!refreshed && !force) continue; // nothing there and nothing to fix
+      try {
+        writeFileSync(linkedCmd, cmdShim(mmapPath));
+        writeFileSync(linkedSh, shShim(mmapPath));
+        return { dir, cmdPath: linkedCmd, shPath: linkedSh, refreshed };
+      } catch {
+        continue;
+      }
+    }
+    return undefined;
+  };
   if (plan.action === 'refused') {
-    return { kind: 'installed', binDir, cmdPath, shPath, path: 'refused', wanted, reason: plan.reason };
+    // refused means setx would damage this PATH: the alias is the whole answer
+    return { kind: 'installed', binDir, cmdPath, shPath, path: 'refused', wanted, reason: plan.reason, alias: alias(true) };
+  }
+  if (plan.action === 'unchanged') {
+    return { kind: 'installed', binDir, cmdPath, shPath, path: 'unchanged', wanted, alias: alias(false) };
   }
   const written = writeUserPath(wanted);
   return written.ok
-    ? { kind: 'installed', binDir, cmdPath, shPath, path: 'updated', wanted }
-    : { kind: 'installed', binDir, cmdPath, shPath, path: 'error', wanted, reason: written.error };
+    ? { kind: 'installed', binDir, cmdPath, shPath, path: 'updated', wanted, alias: alias(false) }
+    : { kind: 'installed', binDir, cmdPath, shPath, path: 'error', wanted, reason: written.error, alias: alias(true) };
 }
 
 function main() {
@@ -247,11 +381,37 @@ function main() {
   if (uninstall) {
     const binDir = binDirIn(localAppData);
     const raw = readUserPath();
+    const mine = join(pluginRootOf(import.meta.url), 'dist', 'mmap.mjs');
+    // Remove only what launches THIS install. The canonical pair is shared
+    // with every other host running this plugin (one file per shape, last
+    // installer wins), so when a file belongs to another install — or to a
+    // stranger — it stays, and with it the directory and its PATH entry: the
+    // command those files leave behind is theirs, not this uninstall's to take.
+    let stillInUse = false;
     for (const path of [join(binDir, 'mmap.cmd'), join(binDir, 'mmap')]) {
-      rmSync(path, { force: true });
-      console.log(`removed ${path}`);
+      const content = readIfPresent(path);
+      if (content === undefined) continue;
+      if (shimLaunches(content, mine)) {
+        rmSync(path, { force: true });
+        console.log(`removed ${path}`);
+      } else stillInUse = true;
+    }
+    // The fallback copies — the route a refused PATH leaves — obey the same
+    // rule, per file, in every candidate directory.
+    const home = process.env['USERPROFILE'] ?? process.env['HOME'] ?? '';
+    for (const dir of home === '' ? [] : linkDirCandidates(localAppData, home)) {
+      for (const candidate of [join(dir, 'mmap.cmd'), join(dir, 'mmap')]) {
+        const content = readIfPresent(candidate);
+        if (content === undefined || !shimLaunches(content, mine)) continue;
+        rmSync(candidate, { force: true });
+        console.log(`removed ${candidate}`);
+      }
+    }
+    if (stillInUse) {
+      console.log(`kept ${binDir} and its PATH entry: another install of this plugin still launches from there.`);
+    } else {
+      applyPath(raw, pathWithout(raw, binDir));
     }
-    applyPath(raw, pathWithout(raw, binDir));
     console.log('Close your terminal app entirely and reopen it for the change to take effect — a new tab keeps the old PATH.');
     return;
   }
@@ -277,8 +437,14 @@ function main() {
       break;
     case 'refused':
       console.log(`NOT touching your user PATH: ${outcome.reason}.`);
-      console.log('Add this entry yourself, in Settings > "Edit environment variables for your account":');
-      console.log(`  ${outcome.binDir}`);
+      if (outcome.alias !== undefined) {
+        console.log(`The command works anyway: both shims were also written to ${outcome.alias.dir},`);
+        console.log('which is already on your PATH — open a new terminal and type `mmap`.');
+        console.log(`(${outcome.binDir} stays the canonical home; add it in Settings if you prefer one place.)`);
+      } else {
+        console.log('Add this entry yourself, in Settings > "Edit environment variables for your account":');
+        console.log(`  ${outcome.binDir}`);
+      }
       break;
     case 'error':
       console.error(`setx refused: ${outcome.reason}`);