pstack-claude-mirror 0.9.133 → 0.9.134

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "pstack",
       "source": "./plugins/pstack",
       "description": "If you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence. Original pstack by Lauren Tan (poteto).",
-      "version": "0.9.133"
+      "version": "0.9.134"
     }
   ]
 }

package/CHANGES.md

@@ -2,6 +2,14 @@
 
 This file is the release changelog, with one `## <version> - <title>` entry per release, newest first. The Cursor-to-Claude rewrite rules live in [`tools/substitutions.json`](tools/substitutions.json), and the [sync boundary](CONTRIBUTING.md#the-sync-boundary) in `CONTRIBUTING.md` defines how a change to upstream's skill content is declared.
 
+## 0.9.134 - Fable 5.2 on Pi, Pi 1.5.1 as the oldest supported Pi
+
+On Pi, the `anthropic` provider's `fable` role runs `claude-fable-5-2`, where it ran `claude-fable-5-1`. A session on a provider that has no table of its own uses the `anthropic` table, so its `fable` role changes too. Claude Code sessions need no change, because Claude Code 2.1.321 moved its own `fable` alias to Fable 5.2. The model first appears in Pi 1.5.1's catalog. Pi 1.5.0 does not have it. It warns `Model "claude-fable-5-2" not found for provider "anthropic". Using custom model id.` and runs that ID with the context window, pricing, and thinking settings of the provider's default model. To stay on Fable 5.1, add the line `pi models: fable=anthropic/claude-fable-5-1` to the override sheet.
+
+Pi 1.5.1 is now the oldest Pi that the port supports. CI typechecks the Pi extension against Pi 1.5.1, where it used Pi 1.1.0, and checks the model catalog, child startup, and slash expansion against it. `CONTRIBUTING.md` asks for the local Pi checks on Pi 1.5.1. No CI job runs on Pi 1.1.0 through 1.5.0 any longer. The copy of Pi that the tests load the extension against moves from 1.5.0 to 1.5.2.
+
+Pi 1.5.1 changed how it splits the arguments of a prompt template, and the extension's copy of that code in `pi/slash.ts` now does the same. The extension uses the copy when a wake-up prompt that the agent scheduled names a prompt template. A quote opens only at the start of an argument, so `--title="fix bug"` gives the template `--title="fix` and `bug"`, where it gave `--title=fix bug`. Inside a quoted argument, a backslash before the same kind of quote keeps the quote as text. A quote that never closes is text, and the words after it split at each space, so `open "quote here` gives `open`, `"quote`, and `here`, where it gave `open` and `quote here`. On Pi 1.5.0 and older, Pi itself still splits such arguments the old way. A local `bun test tests/` reads the installed Pi, so against Pi 1.5.0 or older `tests/pi/slash.test.mjs` and `tests/pi/catalog.test.mjs` each fail one test. Set `PI_PACKAGE_DIR` to a Pi 1.5.1 package to run them.
+
 ## 0.9.133 - worktree audit ref and PR fixes, setup-pstack runtime notes
 
 `worktree-audit.mjs` now checks a worktree's ancestry against `refs/remotes/origin/<trunk>`. git resolves the shorthand `origin/<trunk>` to a tag or local branch of that name before the remote-tracking ref. Such a ref pointing at unmerged work made the audit report the worktree merged and safe. The REMOTE column's ahead count reads `refs/remotes/origin/<branch>` for the same reason. @EthanYoQ found and fixed the trunk case in [#423](https://github.com/michael-denyer/pstack-claude/pull/423).

package/README.md

@@ -3,21 +3,28 @@
 > **This is an unofficial mirror, not the official package.**
 > It is an unmodified copy of the GitHub repository [michael-denyer/pstack-claude](https://github.com/michael-denyer/pstack-claude), republished on npm for networks that can reach an npm registry mirror but not GitHub.
 > It is **not** published by or affiliated with the upstream author (Michael Denyer), or with the original pstack author (Lauren Tan / Cursor).
-> Report bugs and feature requests [upstream](https://github.com/michael-denyer/pstack-claude/issues), not to this mirror.
+> Report plugin bugs and feature requests [upstream](https://github.com/michael-denyer/pstack-claude/issues). Report mirror installation and packaging problems in the mirror repository linked by this package's `repository` field.
 
 **What the mirror changes:** nothing in the upstream files. It only adds `bin/` (the installer), this `README.md` (upstream's README is kept as `UPSTREAM-README.md`), `LICENSE-mirror`, and its own `package.json`.
 
 | | |
 |---|---|
-| Package version | `0.9.133` (same as upstream `VERSION`) |
-| Upstream ref | `v0.9.133` |
-| Upstream commit | `8074b9fda33293b51844fbfc50e615df3729350b` (2026-11-07T21:17:57Z) |
+| Package version | `0.9.134` |
+| Upstream plugin version | `0.9.134` |
+| Upstream ref | `v0.9.134` |
+| Upstream commit | `a691bd30341289b9c7eae8e5b4da28a400ea2423` (2026-11-10T17:42:12Z) |
 | Marketplace / plugin | `pstack@pstack-claude` |
 
 The package contains the upstream marketplace exactly as published (`.claude-plugin/marketplace.json` + `plugins/pstack/`) plus a small installer. No install scripts run on `npm install`.
 
+Mirror-only corrections can add a `-mirror.N` suffix to the npm package version while upstream plugin versions stay unchanged. Install `@latest` to receive the current mirror revision. Stable SemVer ranges do not automatically select prerelease suffixes.
+
+The installer depends on `cross-spawn@7.0.6` for Windows command shims. npm installs its dependencies through your configured registry. Keep those packages available in an intranet registry or local npm cache when installing without internet access.
+
 ## Install (OMP and/or Claude Code)
 
+Use Node.js 18 or later and an installed `omp` or `claude` CLI.
+
 ```shell
 npm install -g pstack-claude-mirror          # registry = your intranet npm mirror
 pstack-claude-mirror install                 # every CLI found on PATH
@@ -39,6 +46,10 @@ claude plugin install pstack@pstack-claude --scope user
 
 Restart OMP / start a new Claude Code session afterwards. Use `--dry-run` to see the commands, `--scope project` for a project-scoped install.
 
+Choose a new directory, an empty directory, or a directory already managed by this package. The installer checks its `.pstack-mirror.json` ownership marker and every selected CLI's marketplace source before replacing files. It refuses unowned nonempty directories and symbolic-link destinations. An owned directory is disposable mirror state. Do not store your own files there.
+
+`--dry-run` reads CLI state and reports conflicts, but does not stage files or change plugin registrations.
+
 ## Update
 
 ```shell
@@ -52,10 +63,13 @@ pstack-claude-mirror update
 
 ```shell
 pstack-claude-mirror uninstall
-rm -rf ~/.pstack-claude-mirror
 npm uninstall -g pstack-claude-mirror
 ```
 
+Uninstall leaves the marketplace files on disk. Delete `~/.pstack-claude-mirror` only after no other CLI or project uses it. The installer retains a marketplace registration when another installation uses it. It also retains Claude registrations when the CLI does not report their declaration scope. To remove a retained registration, check the scope you used to add it, then run `claude plugin marketplace remove pstack-claude --scope user` or `--scope project` as appropriate.
+
+External CLI failures return a nonzero exit status. A failed plugin removal does not trigger marketplace removal.
+
 ## Other harnesses
 
 - **Pi** (untested): `pi install npm:pstack-claude-mirror` (the package keeps upstream's `pi` manifest).
@@ -68,7 +82,7 @@ npm uninstall -g pstack-claude-mirror
 
 ## License
 
-Everything except the mirror's own files is redistributed unchanged under the upstream MIT licenses, with every upstream copyright and permission notice kept as it is:
+Mirrored upstream content is redistributed unchanged under its MIT licenses, with every upstream copyright and permission notice kept as it is:
 
 | Component | Copyright | License file |
 |---|---|---|
@@ -78,8 +92,10 @@ Everything except the mirror's own files is redistributed unchanged under the up
 | `thermos`, `thermo-nuclear-*` skills and agents | © 2026 Cursor | `LICENSE-thermos` |
 | Mirror additions only: `bin/`, this `README.md`, `package.json` | © 2026 The pstack-claude-mirror maintainers | `LICENSE-mirror` |
 
+The separately installed `cross-spawn` dependency is MIT-licensed. Its transitive dependencies retain their own MIT or ISC licenses in their npm packages.
+
 The full per-directory provenance is in `NOTICE.md` (it links to `CHANGES.md`, `tools/substitutions.json`, `tools/forks.json`, `tools/upstream.json` and `docs/reference.md`, all included). A copy of the license files also ships inside the plugin at `plugins/pstack/skills/poteto-mode/references/licenses/`, so it reaches the OMP / Claude Code plugin cache.
 
-Each mirror build stops if any upstream license file, `NOTICE.md` row, or skill `license:` field is no longer MIT, so a component under another license is never republished without review.
+Each build checks upstream license metadata before packaging. A failed check stops automatic publication for review. This check is not a security audit or a substitute for reviewing license changes.
 
 The software is provided "as is", without warranty of any kind (see the license files). The mirror does not imply any endorsement by the upstream authors.

package/UPSTREAM-README.md

@@ -217,6 +217,8 @@ Use poteto-mode to fix the search filter resetting when I change pages.
 
 For a bug, it reproduces the failure, uses `how` and `why` to investigate, delegates the fix, then reruns the failing case. If the fix crosses a function boundary, it brings in `architect` before implementation. You receive the fix and the failing and passing evidence.
 
+A localized bug with a demonstrated cause can use the [focused-fix exception](plugins/pstack/skills/poteto-mode/playbooks/bug-fix.md#focused-fix-exception). One delegate investigates and implements the correction when it preserves existing interfaces and state semantics and has a focused regression check. Reproduction, verification, and required independent review still apply; a small patch alone does not qualify.
+
 [Other playbooks](plugins/pstack/skills/poteto-mode/SKILL.md#playbooks) cover planning, features, refactoring, performance issues, investigations, prototypes, PR maintenance, shipping, and longer projects.
 
 ![poteto-mode on Claude Code, Codex, and Pi turns a request into verified work. Choose a playbook, plan and delegate with architect, arena, or swarm, then review and verify with interrogate, tests, and measurements. Project playbooks customize the workflow, and setup-pstack configures the model and reasoning effort per role. Supporting skills include how, why, and unslop.](assets/pstack-overview.png)
@@ -232,6 +234,10 @@ For a bug, it reproduces the failure, uses `how` and `why` to investigate, deleg
 
 pstack has no server or telemetry. Anything its skills ask your agent to read, including session transcripts, goes to your model provider. Scripts run locally, and PR tools use your GitHub CLI login.
 
+This port has no automatic agent-diary reporting or diary opt-in setting. For a local decision trail, ask for [`show-me-your-work`](plugins/pstack/skills/show-me-your-work/SKILL.md). Longer or unattended workflows also invoke it. The trail stays uncommitted by default. If the trail is committed and pushed to a shared PR, anyone with access to the PR can read it.
+
+To share feedback, submit a short, manually reviewed report through [GitHub issues](https://github.com/michael-denyer/pstack-claude/issues). Include the pstack version, runtime, relevant workflow, and observed result. Remove credentials, customer data, private repository links, and sensitive log or configuration values before posting; share a summary instead of raw transcripts.
+
 ## Contributing
 
 Thanks for helping make this port better. Bug reports, documentation fixes, and runtime improvements are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks and where your change belongs. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).

package/bin/pstack-claude.mjs

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
-// Installs the pstack marketplace shipped in this npm package into OMP and/or Claude Code,
-// without any GitHub access. See README.md.
 import { spawnSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { stripVTControlCharacters } from "node:util";
 import { fileURLToPath } from "node:url";
 
-const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const pkgRoot = realpathSync(resolve(dirname(fileURLToPath(import.meta.url)), ".."));
 const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"));
 const { marketplace: MKT, plugin: PLUGIN } = pkg.pstackMirror;
 const ID = `${PLUGIN}@${MKT}`;
 const isWin = process.platform === "win32";
+const spawn = isWin ? createRequire(import.meta.url)("cross-spawn").sync : spawnSync;
 
 const HELP = `${pkg.name} ${pkg.version}: unofficial GitHub mirror of ${pkg.pstackMirror.upstream}\n(upstream ${pkg.pstackMirror.ref} ${pkg.pstackMirror.commit.slice(0, 12)}; not affiliated with the upstream author)
 
@@ -29,155 +30,302 @@ Targets default to every CLI found on PATH (omp, claude).
 Options:
   --dir <path>        marketplace directory (default: $PSTACK_CLAUDE_HOME or ~/.pstack-claude-mirror/marketplace)
   --scope <scope>     plugin scope: user (default) or project
-  --dry-run           print the commands without running them
+  --dry-run           check current state and print changes without applying them
 `;
 
-const argv = process.argv.slice(2);
-const opts = { scope: "user", dryRun: false, dir: process.env.PSTACK_CLAUDE_HOME ? join(process.env.PSTACK_CLAUDE_HOME, "marketplace") : join(homedir(), ".pstack-claude-mirror", "marketplace") };
-const pos = [];
-for (let i = 0; i < argv.length; i++) {
-  const a = argv[i];
-  if (a === "--dir") opts.dir = resolve(argv[++i]);
-  else if (a === "--scope") opts.scope = argv[++i];
-  else if (a === "--dry-run") opts.dryRun = true;
-  else if (a === "-h" || a === "--help") pos.unshift("help");
-  else if (a === "-v" || a === "--version") pos.unshift("version");
-  else pos.push(a);
-}
-const [cmd = "help", ...targetArgs] = pos;
+const opts = { scope: "user", dryRun: false, dir: join(process.env.PSTACK_CLAUDE_HOME || join(homedir(), ".pstack-claude-mirror"), "marketplace") };
 
 function has(bin) {
-  const r = spawnSync(isWin ? "where" : "sh", isWin ? [bin] : ["-c", `command -v ${bin}`], { stdio: "ignore" });
+  const r = spawn(isWin ? "where" : "sh", isWin ? [bin] : ["-c", `command -v ${bin}`], { stdio: "ignore", shell: false });
   return r.status === 0;
 }
 
-function targets() {
-  const t = targetArgs.length && !targetArgs.includes("all") ? targetArgs : ["omp", "claude"];
-  for (const x of t) if (!["omp", "claude"].includes(x)) die(`unknown target "${x}" (expected omp, claude or all)`);
-  const found = t.filter(has);
-  const missing = t.filter((x) => !found.includes(x));
-  if (targetArgs.length && !targetArgs.includes("all") && missing.length) die(`not found on PATH: ${missing.join(", ")}`);
+function targets(args) {
+  for (const x of args) if (!["omp", "claude", "all"].includes(x)) die(`unknown target "${x}" (expected omp, claude or all)`);
+  const requested = args.length && !args.includes("all") ? [...new Set(args)] : ["omp", "claude"];
+  const found = requested.filter(has);
+  const missing = requested.filter((x) => !found.includes(x));
+  if (args.length && !args.includes("all") && missing.length) die(`not found on PATH: ${missing.join(", ")}`);
   if (!found.length) die("neither omp nor claude was found on PATH");
   for (const m of missing) console.log(`- ${m} not found on PATH, skipping`);
   return found;
 }
 
-function die(msg) {
-  console.error(`error: ${msg}`);
-  process.exit(1);
+function die(message) {
+  throw new Error(message);
 }
 
-function run(bin, args, { allowFail = false, capture = false } = {}) {
-  console.log(`$ ${bin} ${args.join(" ")}`);
-  if (opts.dryRun) return { status: 0, out: "" };
-  const r = spawnSync(bin, args, { encoding: "utf8", shell: isWin, stdio: capture ? ["ignore", "pipe", "pipe"] : ["ignore", "pipe", "pipe"] });
-  const out = `${r.stdout || ""}${r.stderr || ""}`;
-  if (!capture && out.trim()) process.stdout.write(out.replace(/^/gm, "  ").replace(/\s*$/, "\n"));
-  if (r.status !== 0 && !allowFail) die(`${bin} ${args[0]} ${args[1] || ""} failed (exit ${r.status})`);
-  return { status: r.status, out };
+function run(bin, args, { query = false } = {}) {
+  console.log(`$ ${bin} ${args.map((arg) => /\s/.test(arg) ? JSON.stringify(arg) : arg).join(" ")}`);
+  if (opts.dryRun && !query) return "";
+  const r = spawn(bin, args, { encoding: "utf8", shell: false, stdio: ["ignore", "pipe", "pipe"] });
+  if (r.stderr) process.stderr.write(r.stderr);
+  if (r.stdout && (!query || r.status !== 0)) process.stdout.write(r.stdout);
+  if (r.error) die(`could not run ${bin}: ${r.error.message}`);
+  if (r.status !== 0) die(`${bin} ${args.join(" ")} failed (${r.signal ? `signal ${r.signal}` : `exit ${r.status}`})`);
+  return r.stdout || "";
 }
 
-// Copy the marketplace out of node_modules / the npx cache into a directory that survives
-// `npm uninstall` and cache cleaning: Claude Code reads the plugin in place from it.
-function stage() {
-  const dir = opts.dir;
-  console.log(`staging ${pkg.name}@${pkg.version} -> ${dir}`);
-  if (opts.dryRun) return dir;
-  mkdirSync(dirname(dir), { recursive: true });
-  const tmp = `${dir}.new-${process.pid}`;
-  const old = `${dir}.old-${process.pid}`;
-  rmSync(tmp, { recursive: true, force: true });
-  mkdirSync(tmp, { recursive: true });
-  for (const f of [".claude-plugin", "plugins", "LICENSE", "NOTICE.md", "NOTICE-skills.md", "LICENSE-cursor-team-kit", "LICENSE-thermos", "CHANGES.md"]) {
-    if (existsSync(join(pkgRoot, f))) cpSync(join(pkgRoot, f), join(tmp, f), { recursive: true });
+function statIfPresent(path) {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function canonicalPath(path, rejectFinalSymlink = true) {
+  const absolute = resolve(path);
+  const stat = statIfPresent(absolute);
+  if (stat) {
+    if (rejectFinalSymlink && stat.isSymbolicLink()) die(`refusing symlink: ${absolute}`);
+    return realpathSync(absolute);
+  }
+  const parent = dirname(absolute);
+  if (parent === absolute) die(`cannot resolve filesystem root: ${absolute}`);
+  return join(canonicalPath(parent, false), basename(absolute));
+}
+
+function contains(parent, child) {
+  const path = relative(parent, child);
+  return path === "" || (!isAbsolute(path) && path !== ".." && !path.startsWith(`..${sep}`));
+}
+
+function inspectDirectory(path) {
+  path = canonicalPath(path);
+  if (contains(pkgRoot, path) || contains(path, pkgRoot)) die(`marketplace directory overlaps this package: ${path}`);
+  const stat = statIfPresent(path);
+  if (!stat) return { kind: "absent", path, stat };
+  if (!stat.isDirectory()) die(`marketplace path is not a directory: ${path}`);
+  if (!readdirSync(path).length) return { kind: "empty", path, stat };
+  const markerPath = join(path, ".pstack-mirror.json");
+  const markerStat = statIfPresent(markerPath);
+  if (!markerStat || !markerStat.isFile() || markerStat.isSymbolicLink()) die(`refusing nonempty directory without a regular ownership marker: ${path}`);
+  let marker;
+  try {
+    marker = JSON.parse(readFileSync(markerPath, "utf8"));
+  } catch (error) {
+    die(`cannot read ownership marker ${markerPath}: ${error.message}`);
+  }
+  const owner = { package: pkg.name, upstream: pkg.pstackMirror.upstream, marketplace: MKT, plugin: PLUGIN };
+  if (!isRecord(marker) || Object.entries(owner).some(([key, value]) => marker[key] !== value)) die(`ownership marker does not match this mirror: ${markerPath}`);
+  return { kind: "owned", path, stat };
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function text(value) {
+  return typeof value === "string" && value.trim().length > 0 && !/[\x00-\x1f\x7f]/.test(value);
+}
+
+function jsonQuery(bin, args) {
+  const output = run(bin, args, { query: true });
+  try {
+    return JSON.parse(output);
+  } catch {
+    die(`invalid JSON from ${bin} ${args.join(" ")}`);
+  }
+}
+
+function sameSource(target, source) {
+  if (!text(source) || !isAbsolute(source) || canonicalPath(source) !== opts.dir) {
+    die(`${target} already has marketplace "${MKT}" from another source: ${source}`);
   }
-  writeFileSync(join(tmp, ".pstack-mirror.json"), JSON.stringify({ package: pkg.name, version: pkg.version, ...pkg.pstackMirror }, null, 2) + "\n");
-  if (existsSync(dir)) renameSync(dir, old);
-  renameSync(tmp, dir);
-  rmSync(old, { recursive: true, force: true });
-  return dir;
-}
-
-function installOmp(dir) {
-  console.log("\n== OMP");
-  const list = run("omp", ["plugin", "marketplace", "list"], { capture: true, allowFail: true }).out;
-  const line = list.split("\n").find((l) => l.trim().split(/\s+/)[0] === MKT);
-  if (!line) {
-    run("omp", ["plugin", "marketplace", "add", dir]);
+}
+
+function inspectOmp() {
+  const output = stripVTControlCharacters(run("omp", ["plugin", "marketplace", "list"], { query: true }));
+  const lines = output.split(/\r?\n/).filter((line) => line.trim());
+  const marketplaces = new Map();
+  if (lines[0] === "No marketplaces configured") {
+    if (lines.length > 2 || (lines.length === 2 && lines[1] !== "Add one with: omp plugin marketplace add <source>")) die("unrecognized OMP marketplace listing");
   } else {
-    if (!opts.dryRun && !line.includes(dir)) {
-      die(`OMP already has a marketplace "${MKT}" from another source:\n  ${line.trim()}\nRemove it first: omp plugin marketplace remove ${MKT}`);
+    if (lines[0] !== "Configured Marketplaces:" || lines.length < 2) die("unrecognized OMP marketplace listing");
+    for (const line of lines.slice(1)) {
+      const row = /^\s{2}([\w.-]+)[ \t]{2,}(.+)$/.exec(line);
+      if (!row || !text(row[2]) || marketplaces.has(row[1])) die("invalid or duplicate OMP marketplace row");
+      marketplaces.set(row[1], row[2]);
     }
-    run("omp", ["plugin", "marketplace", "update", MKT]);
   }
-  const installed = run("omp", ["plugin", "list", "--json"], { capture: true, allowFail: true }).out;
-  let present = false;
-  try {
-    present = JSON.parse(installed).marketplace.some((p) => p.id === ID && p.entries.some((e) => e.scope === opts.scope));
-  } catch {}
-  if (present) run("omp", ["plugin", "upgrade", `--scope=${opts.scope}`, ID]);
-  else run("omp", ["plugin", "install", `--scope=${opts.scope}`, ID]);
-  console.log("Restart OMP to load pstack.");
+  if (marketplaces.has(MKT)) sameSource("OMP", marketplaces.get(MKT));
+  const plugins = jsonQuery("omp", ["plugin", "list", "--json"]);
+  if (!isRecord(plugins) || !Array.isArray(plugins.npm) || !Array.isArray(plugins.marketplace)) die("invalid OMP plugin listing");
+  const installed = [];
+  const seen = new Set();
+  for (const plugin of plugins.marketplace) {
+    if (!isRecord(plugin) || !text(plugin.id) || !/^[^@\s]+@[^@\s]+$/.test(plugin.id) || !["user", "project"].includes(plugin.scope) || !Array.isArray(plugin.entries)) die("invalid OMP marketplace plugin");
+    const key = `${plugin.id}:${plugin.scope}`;
+    if (seen.has(key)) die("duplicate OMP marketplace plugin");
+    seen.add(key);
+    for (const entry of plugin.entries) {
+      if (!isRecord(entry) || entry.scope !== plugin.scope) die("invalid OMP plugin entry");
+      installed.push({ id: plugin.id, scope: entry.scope });
+    }
+  }
+  return {
+    target: "omp",
+    marketplace: marketplaces.has(MKT),
+    present: installed.some((p) => p.id === ID && p.scope === opts.scope),
+    retain: installed.some((p) => p.id.endsWith(`@${MKT}`) && (p.id !== ID || p.scope !== opts.scope)),
+  };
+}
+
+function inspectClaude() {
+  const marketplaces = jsonQuery("claude", ["plugin", "marketplace", "list", "--json"]);
+  if (!Array.isArray(marketplaces)) die("invalid Claude Code marketplace listing");
+  const seen = new Set();
+  for (const marketplace of marketplaces) {
+    if (!isRecord(marketplace) || !text(marketplace.name) || seen.has(marketplace.name)) die("invalid or duplicate Claude Code marketplace");
+    seen.add(marketplace.name);
+    const sourceField = { directory: "path", file: "path", github: "repo", git: "url", url: "url", claudeai: "marketplaceId" }[marketplace.source];
+    if (!text(marketplace.source) || typeof sourceField !== "string" || !text(marketplace[sourceField])) die("invalid Claude Code marketplace source");
+    if (["directory", "file"].includes(marketplace.source) && !isAbsolute(marketplace.path)) die("invalid Claude Code local marketplace path");
+    if (marketplace.scope !== undefined && !["user", "project", "local", "managed"].includes(marketplace.scope)) die("invalid Claude Code marketplace scope");
+  }
+  const marketplace = marketplaces.find((m) => m.name === MKT);
+  if (marketplace) {
+    if (marketplace.source !== "directory") die(`Claude Code already has marketplace "${MKT}" from another source: ${marketplace.source}`);
+    sameSource("Claude Code", marketplace.path);
+  }
+  const plugins = jsonQuery("claude", ["plugin", "list", "--json"]);
+  if (!Array.isArray(plugins)) die("invalid Claude Code plugin listing");
+  const project = canonicalPath(process.cwd(), false);
+  const installed = [];
+  seen.clear();
+  for (const plugin of plugins) {
+    if (!isRecord(plugin) || !text(plugin.id) || !/^[^@\s]+@[^@\s]+$/.test(plugin.id) || !["user", "project", "local", "managed", "session", "synced"].includes(plugin.scope)) die("invalid Claude Code plugin");
+    const scopedProject = plugin.scope === "project" || plugin.scope === "local";
+    if (scopedProject && (!text(plugin.projectPath) || !isAbsolute(plugin.projectPath))) die("invalid Claude Code plugin project path");
+    const projectPath = scopedProject ? canonicalPath(plugin.projectPath, false) : null;
+    const key = JSON.stringify([plugin.id, plugin.scope, projectPath]);
+    if (seen.has(key)) die("duplicate Claude Code plugin installation");
+    seen.add(key);
+    installed.push({ id: plugin.id, requested: plugin.scope === opts.scope && (!scopedProject || projectPath === project) });
+  }
+  return {
+    target: "claude",
+    marketplace: Boolean(marketplace),
+    present: installed.some((p) => p.id === ID && p.requested),
+    retain: Boolean(marketplace && marketplace.scope !== opts.scope) || installed.some((p) => p.id.endsWith(`@${MKT}`) && (p.id !== ID || !p.requested)),
+  };
 }
 
-function installClaude(dir) {
-  console.log("\n== Claude Code");
-  const list = run("claude", ["plugin", "marketplace", "list", "--json"], { capture: true, allowFail: true }).out;
-  let existing;
+// Claude reads local marketplace content in place, so keep it outside the npm cache.
+function stage(directory) {
+  const dir = directory.path;
+  console.log(`staging ${pkg.name}@${pkg.version} -> ${dir}`);
+  if (opts.dryRun) return;
+  mkdirSync(dirname(dir), { recursive: true });
+  const workspace = mkdtempSync(join(dirname(dir), `.${basename(dir)}.pstack-`));
+  const next = join(workspace, "next");
+  const backup = join(workspace, "previous");
+  let preserveBackup = false;
   try {
-    existing = JSON.parse(list.slice(list.indexOf("["))).find((m) => m.name === MKT);
-  } catch {}
-  if (existing && !opts.dryRun && resolve(existing.path || existing.installLocation || "") !== dir) {
-    die(`Claude Code already has a marketplace "${MKT}" from another source (${existing.source} ${existing.path || existing.repo || existing.url || ""}).\nRemove it first: claude plugin marketplace remove ${MKT}`);
+    mkdirSync(next);
+    for (const name of [".claude-plugin", "plugins"]) cpSync(join(pkgRoot, name), join(next, name), { recursive: true });
+    for (const name of readdirSync(pkgRoot)) {
+      if ([".claude-plugin", "plugins", "bin", "package.json", "README.md", "node_modules", ".git", ".pstack-mirror.json"].includes(name)) continue;
+      cpSync(join(pkgRoot, name), join(next, name), { recursive: true });
+    }
+    writeFileSync(join(next, ".pstack-mirror.json"), JSON.stringify({ package: pkg.name, version: pkg.version, ...pkg.pstackMirror }, null, 2) + "\n");
+    const current = inspectDirectory(dir);
+    if (current.path !== dir || current.kind !== directory.kind || current.stat?.dev !== directory.stat?.dev || current.stat?.ino !== directory.stat?.ino) die(`marketplace directory changed during preflight: ${dir}`);
+    if (directory.kind !== "absent") renameSync(dir, backup);
+    try {
+      renameSync(next, dir);
+    } catch (error) {
+      if (directory.kind !== "absent") {
+        try {
+          if (statIfPresent(dir)) die(`destination is occupied: ${dir}`);
+          renameSync(backup, dir);
+        } catch (restoreError) {
+          preserveBackup = true;
+          die(`staging failed: ${error.message}; restore failed: ${restoreError.message}; previous installation remains at ${backup}`);
+        }
+      }
+      throw error;
+    }
+  } finally {
+    if (!preserveBackup) rmSync(workspace, { recursive: true, force: true });
   }
-  if (!existing) run("claude", ["plugin", "marketplace", "add", dir, "--scope", opts.scope === "project" ? "project" : "user"]);
-  else run("claude", ["plugin", "marketplace", "update", MKT]);
-  run("claude", ["plugin", "install", ID, "--scope", opts.scope]);
-  console.log("Start a new Claude Code session (or run /reload-plugins) to load pstack.");
-}
-
-function uninstallOmp() {
-  console.log("\n== OMP");
-  run("omp", ["plugin", "uninstall", `--scope=${opts.scope}`, ID], { allowFail: true });
-  run("omp", ["plugin", "marketplace", "remove", MKT], { allowFail: true });
-}
-
-function uninstallClaude() {
-  console.log("\n== Claude Code");
-  run("claude", ["plugin", "uninstall", ID, "--scope", opts.scope], { allowFail: true });
-  run("claude", ["plugin", "marketplace", "remove", MKT], { allowFail: true });
-}
-
-switch (cmd) {
-  case "help":
-    console.log(HELP);
-    break;
-  case "version":
-    console.log(pkg.version);
-    break;
-  case "path":
-    console.log(opts.dir);
-    break;
-  case "info":
-    console.log(JSON.stringify({ package: pkg.name, version: pkg.version, root: pkgRoot, marketplaceDir: opts.dir, ...pkg.pstackMirror }, null, 2));
-    break;
-  case "install":
-  case "update": {
-    if (!["user", "project"].includes(opts.scope)) die(`--scope must be user or project`);
-    const t = targets();
-    const dir = stage();
-    if (t.includes("omp")) installOmp(dir);
-    if (t.includes("claude")) installClaude(dir);
-    console.log(`\nDone: ${ID} ${pkg.version}`);
-    break;
+}
+
+function install(state) {
+  const { target, marketplace, present } = state;
+  console.log(`\n== ${target === "omp" ? "OMP" : "Claude Code"}`);
+  if (marketplace) run(target, ["plugin", "marketplace", "update", MKT]);
+  else run(target, ["plugin", "marketplace", "add", opts.dir, ...(target === "claude" ? ["--scope", opts.scope] : [])]);
+  if (target === "omp") {
+    run(target, ["plugin", present ? "upgrade" : "install", `--scope=${opts.scope}`, ID]);
+    console.log("Restart OMP to load pstack.");
+  } else {
+    run(target, ["plugin", "install", ID, "--scope", opts.scope]);
+    console.log("Start a new Claude Code session (or run /reload-plugins) to load pstack.");
   }
-  case "uninstall": {
-    const t = targets();
-    if (t.includes("omp")) uninstallOmp();
-    if (t.includes("claude")) uninstallClaude();
-    console.log(`\nThe marketplace files remain in ${opts.dir}; delete that directory if no other tool uses it.`);
-    break;
+}
+
+function uninstall(state) {
+  const { target, present, marketplace, retain } = state;
+  console.log(`\n== ${target === "omp" ? "OMP" : "Claude Code"}`);
+  if (present) run(target, ["plugin", "uninstall", ...(target === "omp" ? [`--scope=${opts.scope}`, ID] : [ID, "--scope", opts.scope])]);
+  if (marketplace && !retain) run(target, ["plugin", "marketplace", "remove", MKT, ...(target === "claude" ? ["--scope", opts.scope] : [])]);
+  if (marketplace && retain) console.log(`Keeping marketplace "${MKT}" for other installations or scopes.`);
+}
+
+try {
+  const argv = process.argv.slice(2);
+  const pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--dir" || arg === "--scope") {
+      const value = argv[++i];
+      if (!value || value.startsWith("-")) die(`${arg} requires a value`);
+      opts[arg === "--dir" ? "dir" : "scope"] = value;
+    } else if (arg === "--dry-run") opts.dryRun = true;
+    else if (arg === "-h" || arg === "--help") pos.unshift("help");
+    else if (arg === "-v" || arg === "--version") pos.unshift("version");
+    else if (arg.startsWith("-")) die(`unknown option "${arg}"`);
+    else pos.push(arg);
+  }
+  if (!["user", "project"].includes(opts.scope)) die("--scope must be user or project");
+  opts.dir = canonicalPath(opts.dir);
+  const [cmd = "help", ...targetArgs] = pos;
+  switch (cmd) {
+    case "help":
+      console.log(HELP);
+      break;
+    case "version":
+      console.log(pkg.version);
+      break;
+    case "path":
+      console.log(opts.dir);
+      break;
+    case "info":
+      console.log(JSON.stringify({ package: pkg.name, version: pkg.version, root: pkgRoot, marketplaceDir: opts.dir, ...pkg.pstackMirror }, null, 2));
+      break;
+    case "install":
+    case "update":
+    case "uninstall": {
+      const selected = targets(targetArgs);
+      const directory = inspectDirectory(opts.dir);
+      const states = selected.map((target) => target === "omp" ? inspectOmp() : inspectClaude());
+      if (cmd === "uninstall") {
+        for (const state of states) uninstall(state);
+        console.log(`\nThe marketplace files remain in ${opts.dir}; delete that directory if no other tool uses it.`);
+      } else {
+        stage(directory);
+        for (const state of states) install(state);
+        console.log(`\nDone: ${ID} ${pkg.version}`);
+      }
+      break;
+    }
+    default:
+      die(`unknown command "${cmd}"\n\n${HELP}`);
   }
-  default:
-    die(`unknown command "${cmd}"\n\n${HELP}`);
+} catch (error) {
+  console.error(`error: ${error.message}`);
+  process.exitCode = 1;
 }