fix(installer): keep a local checkout registered instead of replacing it

AGENTS.md

@@ -75,6 +75,8 @@ Package version: see `package.json` (`version` field).
 - Do not hardcode ports other than OAuth callback port `1455`; use existing constants/helpers.
 - Do not remove `store: false` or `reasoning.encrypted_content` from shipped config templates.
 - Do not treat `oc-chatgpt-multi-auth` as current except in migration/cleanup logic.
+- Do not identify a plugin entry by the spelling of its last path segment. Resolve what it points at; a path outside package-manager output - `node_modules`, and the versioned directories of the OpenCode package cache - belongs to whoever wrote it and is never rewritten or removed.
+- Do not run the installer to repair a developer machine's config. It writes that machine's real OpenCode config; `update` refreshes the package cache without touching either file.
 - Do not expose account emails, access tokens, refresh tokens, or raw prompt/response bodies in normal diagnostics.
 - Do not silently delete JSON credentials when keychain operations fail.
 - Do not document boolean env overrides as truthy for `"true"` or `"yes"`. Only `"1"` is truthy.
@@ -91,11 +93,22 @@ npm run test:watch       # vitest watch mode
 npm run lint             # eslint
 ```
 
+Installer, which writes the real `~/.config/opencode/opencode.json` and
+`tui.json` of whoever runs it:
+
+```bash
+npx -y oc-codex-multi-auth@latest          # register plugin entries only
+npx -y oc-codex-multi-auth@latest --full   # also install the explicit model catalog
+npx -y oc-codex-multi-auth@latest update   # refresh the package cache; never reads or writes config
+```
+
+A config that already registers this plugin keeps the entry it has, including
+one pointing at a working checkout of this repository. The published package
+name is added only when nothing in the config resolves to this plugin.
+
 Standalone CLI examples:
 
 ```bash
-npx -y oc-codex-multi-auth@latest
-npx -y oc-codex-multi-auth@latest --full
 oc-codex-multi-auth warm
 oc-codex-multi-auth status --json
 oc-codex-multi-auth doctor

README.md

@@ -128,7 +128,28 @@ opencode debug config
 opencode auth login
 ```
 
-The default installer only normalizes the plugin entry in `~/.config/opencode/opencode.json`, enables the TUI status plugin in `~/.config/opencode/tui.json`, and clears the cached plugin copy. Catalog modes also merge their selected `provider.openai` definitions. Changed config files are backed up before writing.
+The default installer only registers the plugin entry in `~/.config/opencode/opencode.json`, enables the TUI status plugin in `~/.config/opencode/tui.json`, and clears the cached plugin copy. Catalog modes also merge their selected `provider.openai` definitions. Changed config files are backed up before writing.
+
+### Running from a local checkout
+
+You can point OpenCode at a clone of this repository instead of the published
+package, which is how the project is developed:
+
+```json
+{ "plugin": ["file:///path/to/oc-codex-multi-auth"] }
+```
+
+The installer leaves that entry exactly as written. It identifies an entry by
+the package it resolves to rather than by how the path is spelled, so a clone
+is recognized under any directory name, whether it is referenced as a path, a
+`file://` URL, or its build output. `oc-codex-multi-auth` is appended only when
+no entry in the config resolves to this plugin, so the installer never replaces
+a checkout with the published package or registers both at once.
+
+Stale references the installer itself produced are still retired: the bare
+package name repeated, version-pinned entries, the former
+`oc-chatgpt-multi-auth` name, and paths into `node_modules` or the OpenCode
+package cache.
 
 ### Standalone CLI (no agent / no token cost)
 
@@ -504,7 +525,7 @@ opencode auth login
 <summary><b>Common symptoms</b></summary>
 
 - Plugin does not load: rerun `npx -y oc-codex-multi-auth@latest`, then restart OpenCode
-- Config looks wrong: run `opencode debug config` and confirm `"plugin": ["oc-codex-multi-auth"]`
+- Config looks wrong: run `opencode debug config` and confirm `"plugin": ["oc-codex-multi-auth"]`, or the path to your checkout when running one
 - OAuth callback fails: free port `1455`, then rerun `opencode auth login`
 - Browser launch is blocked: use the remote/headless login path from [docs/getting-started.md](docs/getting-started.md#remote-or-headless-login)
 - Wrong account is selected: run `codex-list`, then `codex-switch`

lib/auto-update-checker.ts

@@ -1,5 +1,5 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { createLogger } from "./logger.js";
 
@@ -118,12 +118,50 @@ function getManagedCachePaths(): string[] {
   ]);
 }
 
-export function clearManagedOpenCodePluginCache(paths = getManagedCachePaths()): boolean {
+function isInsideDirectory(candidate: string, directory: string): boolean {
+  const relativePath = relative(directory, candidate);
+  return relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath);
+}
+
+export interface EvictionScope {
+  cacheRoot?: string;
+  resolveRealPath?: (path: string) => string;
+}
+
+/**
+ * Cache eviction deletes recursively, so it must never act on a path that only
+ * looks like cache. Resolving symlinks before the containment check is the part
+ * that matters: a developer who links their working checkout into the cache
+ * would otherwise have it deleted on exit by a name match alone.
+ */
+export function isEvictableCachePath(cachePath: string, scope: EvictionScope = {}): boolean {
+  const { cacheRoot = OPENCODE_CACHE_DIR, resolveRealPath = realpathSync } = scope;
+  const absolutePath = resolve(cachePath);
+  const absoluteRoot = resolve(cacheRoot);
+  if (!isInsideDirectory(absolutePath, absoluteRoot)) return false;
+
+  try {
+    return isInsideDirectory(resolveRealPath(absolutePath), resolveRealPath(absoluteRoot));
+  } catch {
+    return false;
+  }
+}
+
+export function clearManagedOpenCodePluginCache(
+  paths = getManagedCachePaths(),
+  scope: EvictionScope = {},
+): boolean {
   let cleared = false;
 
   for (const cachePath of paths) {
     try {
       if (!existsSync(cachePath)) continue;
+      if (!isEvictableCachePath(cachePath, scope)) {
+        log.warn("Refused to clear a plugin cache path that resolves outside the OpenCode cache", {
+          path: cachePath,
+        });
+        continue;
+      }
       rmSync(cachePath, { recursive: true, force: true });
       cleared = true;
       log.info("Cleared OpenCode plugin cache for update", { path: cachePath });