projectstore-claude 0.28.0-rc.3 → 0.28.1

package/node_modules/projectstore/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "projectstore",
       "displayName": "projectstore",
       "description": "📚 Your agent runs the project through a verified loop: task → artifact (ADR · spec · epic · story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in an Obsidian-friendly vault, every write approved by you — and any model can pick the project up tomorrow.",
-      "version": "0.28.0-rc.3",
+      "version": "0.28.1",
       "author": {
         "name": "Evgenii Konev",
         "email": "ekonev@smartandpoint.com",

package/node_modules/projectstore/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "projectstore",
   "displayName": "projectstore",
-  "version": "0.28.0-rc.3",
+  "version": "0.28.1",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "author": {
     "name": "Evgenii Konev @ SmartAndPoint",

package/node_modules/projectstore/README.md

@@ -4,7 +4,7 @@
 
 [![release](https://img.shields.io/github/v/release/SmartAndPoint/ProjectStore?label=release)](https://github.com/SmartAndPoint/ProjectStore/releases) [![license](https://img.shields.io/github/license/SmartAndPoint/ProjectStore?label=license)](./LICENSE) [![Star on GitHub](https://img.shields.io/badge/%E2%AD%90-star_us-yellow?logo=github)](https://github.com/SmartAndPoint/ProjectStore/stargazers)
 
-A project workflow plugin for [Claude Code](https://claude.com/claude-code) and [OpenAI Codex](https://developers.openai.com/codex/) (experimental).
+A project workflow plugin for [Claude Code](https://claude.com/claude-code) and [OpenAI Codex](https://developers.openai.com/codex/) (experimental). Both are released together at one version, and each installs with one command.
 
 ---
 
@@ -66,6 +66,14 @@ Open Claude Code in your project and say:
 
 That's the whole setup. Claude adds the marketplace, installs the plugin, and walks you through binding a vault, scaffolding it and wiring the status line — every step previewed, nothing written without your Yes.
 
+**On Codex**, run one command from a terminal in your project:
+
+```
+npx projectstore-codex install --project "$PWD"
+```
+
+Then restart Codex, approve the ProjectStore hooks when it asks, and run `$projectstore-bind ~/Documents/my-project-vault`. Codex support is newer and still labelled experimental: [`docs/harnesses.md`](./docs/harnesses.md#codex) says what has been verified and what has not. A project can be worked from both agents: they share the binding in `.projectstore/`, and each keeps its own overlay and session state beside it ([running both over one project](./docs/harnesses.md#running-both-over-one-project)).
+
 <details>
 <summary>Prefer to type it yourself?</summary>
 
@@ -88,28 +96,26 @@ npx projectstore-claude install --project "$PWD"
 
 The same tree is published to npm as [`projectstore`](https://www.npmjs.com/package/projectstore) — one source package carrying every harness's manifest — and `projectstore-claude` is its Claude Code shell: the core pinned at the same version and bundled inside, the harness fixed, so the one command has the same shape on every harness. It registers the plugin with Claude Code: it writes a small local marketplace of its own under your Claude home, then drives `claude plugin marketplace add` / `plugin install` **at local scope**, so the registration lands in this checkout's `.claude/settings.local.json` and nowhere else. Every host command is printed before it runs; naming the harness is the confirmation. Restart Claude Code afterwards. A git-marketplace copy already enabled for the checkout is silenced there (not globally) so the plugin does not load twice; `uninstall` turns it back on. Pin or upgrade with `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run. The core's low-level form, `npx projectstore <verb> --harness claude-code …`, is exactly what the shell runs. bun works the same on the packed bin.
 
-**Codex uses its own rendered plugin root and the same one-command shape.**
-Codex support is **experimental** (see [`docs/harnesses.md`](./docs/harnesses.md)
-for what has been measured and what has not), and its shell is not published
-yet. From this checkout, exercise the exact npx path against the built tarball:
+**Codex has its own shell with the same one-command shape:**
+`npx projectstore-codex install --project "$PWD"`. It carries a canonical
+portable manifest, namespaced workflow and role skills, lifecycle hooks, and
+the exact bundled core. It stages a stable marketplace under `CODEX_HOME`,
+drives `codex plugin marketplace add` and `codex plugin add`, then reads the
+installation back and verifies its version and payload digest. Restart Codex,
+approve the hooks, and run `$projectstore-bind <vault-path>`. For later
+releases, `npx projectstore-codex@<version> upgrade --project "$PWD"`. Because
+Codex's plugin registry is user-global, ordinary uninstall removes only the
+project's agents block; `uninstall --global` is the explicit machine-wide
+removal. Codex is **experimental** until a live session has exercised every
+surface it installs; [`docs/harnesses.md`](./docs/harnesses.md) says what has
+been measured and what has not. From a checkout, the same npx path runs against
+a built tarball:
 
 ```sh
 npm run shells:build -- --only projectstore-codex --dev --out dist
 npx --package "./dist/projectstore-codex-$(node -p 'require("./package.json").version').tgz" projectstore-codex install --project "$PWD"
 ```
 
-The Codex shell carries a canonical portable manifest, namespaced workflow and
-role skills, lifecycle hooks, and the exact bundled core. It stages a stable
-marketplace under `CODEX_HOME`, drives `codex plugin marketplace add` and
-`codex plugin add`, then reads the installation back and verifies its version
-and payload digest. Restart Codex, approve the hooks, and run
-`$projectstore-bind <vault-path>`. After the first explicit npm publication,
-the shorter command is
-`npx projectstore-codex@<version> install --project "$PWD"`; use its `upgrade`
-verb for later releases. Because Codex's
-plugin registry is user-global, ordinary uninstall removes only the project's
-agents block; `uninstall --global` is the explicit machine-wide removal.
-
 The package also carries a `bin`. Without a session — in CI, or in a shell — the same core answers token-free, with a `--json` envelope on every verb:
 
 ```
@@ -141,7 +147,7 @@ npx projectstore bind ~/vaults/my-project
 npx projectstore init ~/vaults/new-project --language ru
 ```
 
-`projectstore-claude`, `projectstore-codex` and `projectstore-opencode` are this package's per-harness shells — the core pinned and bundled, the harness fixed. Codex's shell is experimental and stays private until a live run has exercised every surface it installs, from an installed release ([`docs/harnesses.md`](./docs/harnesses.md)). The opencode shell publishes after its plugin root is rendered. The other `projectstore-*` names are reserved placeholders pointing back here. One source package, one version, N tarballs.
+`projectstore-claude`, `projectstore-codex` and `projectstore-opencode` are this package's per-harness shells — the core pinned and bundled, the harness fixed. The Claude Code and Codex shells are published at the core's version; Codex stays labelled experimental until a live run has exercised every surface it installs ([`docs/harnesses.md`](./docs/harnesses.md)). The opencode shell publishes after its plugin root is rendered. The other `projectstore-*` names are reserved placeholders pointing back here. One source package, one version, N tarballs.
 </details>
 
 ## Upgrading
@@ -168,9 +174,14 @@ bound before 0.28. What an existing project sees afterwards, and why:
   `npx projectstore-claude upgrade` on a git-marketplace install does more: it
   also registers the plugin from npm for this checkout and turns the
   git-marketplace copy off here, so `/plugin update` stops reaching the
-  checkout. If that already happened,
+  checkout. The 0.28.0-rc.1 and rc.2 startup lines named that shell form
+  (`npx projectstore-claude@<version> upgrade`, without `--no-register`), so on
+  those, update first and run what the new startup line names. If it already
+  happened,
   `npx projectstore-claude@<version> uninstall --surface plugin --project "$PWD"`
-  turns the git-marketplace copy back on. Restart, then run
+  (0.28.0 or later) turns the git-marketplace copy back on. That copy must be 0.28 or later — an
+  older one reads a moved project as unbound — so update it first if it is not.
+  Restart, then run
   `/projectstore:doctor --fix` in the new session, which re-stamps the status
   line against that copy.
 - **The status line keeps rendering.** A launcher written by an earlier version
@@ -197,6 +208,15 @@ bound before 0.28. What an existing project sees afterwards, and why:
   (`projectstore-decision-detector`, `projectstore-peer-reviewer`,
   `projectstore-story-completion`, `projectstore-vault-communication`). Nothing
   in a project names them; only a skill listing shows the new names.
+- **Rolling back** to 0.27.x before the move: everything keeps working, since
+  0.27.x still reads the old layout. It rewrites the status-line launcher in its
+  own form, as it always did; coming forward again, the startup line names the
+  move once more, and the move re-stamps the launcher. If a session already
+  re-stamped the status line or re-registered the agents block before the move
+  (rc.2's `/projectstore:doctor --fix` did both), 0.27.x reports a foreign
+  status line and a v4 block and leaves both alone — unless you run its
+  `/projectstore:agents register`, which rewrites the block; the status line
+  still renders, and the move settles both.
 - **Rolling back** to 0.27.x after the move: 0.27.x looks for its binding under
   `.claude/`, finds none and offers `bind`. Do not accept. A re-bind writes
   `.claude/projectstore.json` again, and 0.28's `install` and `upgrade` refuse

package/node_modules/projectstore/commands/agents.md

@@ -28,7 +28,13 @@ subcommand (`.projectstore/projectstore.json`; else point to `/projectstore:bind
    prose byte-identical.
 3. A non-zero exit is a refusal — a duplicated or unclosed block, a missing
    template — relay it and stop. Never write the block with the Write or Edit
-   tool: the verb is the only writer (install spec, contract 6).
+   tool: the verb is the only writer (install spec, contract 6). One exception,
+   read from the output, not assumed: when it shows the block applied and the
+   `layout` item skipped as deferred to a terminal outside the session, the
+   exit 1 is that deferral. The block is registered — say so, and for the move
+   relay the command the startup line or `/projectstore:doctor`'s
+   `layout-legacy` finding names; never compose one. Any other non-zero exit
+   is a refusal.
 
 ## `unregister` — remove what register added
 

package/node_modules/projectstore/commands/doctor.md

@@ -25,6 +25,8 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
    is in the report, it goes first and its command is the one repair** for a
    stale-launcher `surface`, a v3 `agents-block` and `agents-in-binding` as
    well: relay it and run nothing in-session for those (see its bullet below).
+   The report already shows the v3 block, and a block Claude Code cannot see,
+   as info that points at the move.
    - `worktree-unbound` → this checkout is a git worktree of a bound one. Offer
      `/projectstore:bind --inherit`, and say what it does: copies the parent's
      binding, leaves the vault shared and unchanged, carries no session state.
@@ -35,7 +37,10 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
    - `agents-block` duplicate or stale → show the finding, then (after approval)
      run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" install --harness claude-code --surface agents_block --project "${CLAUDE_PROJECT_DIR}"`
      and print its output: it removes the copy in the non-preferred file and
-     keeps the preferred one current. Never Edit or Write the block yourself —
+     keeps the preferred one current. A block Claude Code cannot see — in
+     `AGENTS.md`, with no `@AGENTS.md` line in `CLAUDE.md` — is the same repair:
+     the verb adds the import. For another harness the finding names its own
+     `--harness`; relay that command. Never Edit or Write the block yourself —
      the verb is its only writer (install spec, contract 6).
    - `statusline` issues → offer running `/projectstore:statusline on|off`,
      which installs or removes the entry and the launcher behind a preview
@@ -74,8 +79,10 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
      git-marketplace install or a checkout, the `projectstore-claude` shell for
      the npm registration. Relay the finding's command verbatim and never
      substitute the other form — the shell, run for a git-marketplace install,
-     would also move this checkout to the npm channel. Never move the files
-     yourself. While this finding is in the report, its command is also the one
+     would also move this checkout to the npm channel. When the finding carries
+     advice instead of a command — the installed copy predates the move, or
+     predates `--no-register` — relay the advice and never compose a command
+     yourself. Never move the files yourself. While this finding is in the report, its command is also the one
      repair for a stale-launcher `surface`, a v3 `agents-block` and
      `agents-in-binding`: do not run the in-session `install` or `upgrade` for
      those — the deferred move makes that run stop part-way.

package/node_modules/projectstore/docs/harnesses.md

@@ -23,8 +23,10 @@ and the measurements in the manifest came from that run.
 **experimental** means `verified` is `null`. Every field that was not measured
 is absent or `null` rather than guessed. It is enough to run on; it is not enough
 to promise. An experimental harness is never the source layout. A generated
-adapter may exist while it is experimental, but its distribution shell stays
-private until the complete built artifact passes the live gate.
+adapter may exist while it is experimental. Its distribution shell may
+publish before the live run that sets `verified`, but only by the maintainer's
+decision (Codex's does, from 0.28.1); the label stays experimental until that
+run.
 
 The label is not prose. It is derived from the manifest, and
 `tests/portability.test.mjs` fails if this table and `verified` disagree.
@@ -45,38 +47,50 @@ model names and those are harness-specific — is
 
 Experimental, measured on `codex-cli 0.153.4`. The initial spike captured 759
 hook firings. The 2026-09-30 gate then built the npm shell from a packed core,
-passed the Codex plugin validator, installed and upgraded it through an isolated
+passed Codex's plugin validator, installed and upgraded it through an isolated
 `CODEX_HOME`, verified the materialised cache by version and digest, and loaded
-`$projectstore-status` in a fresh Codex session.
+the `projectstore-status` skill in a fresh Codex session. The validator (the
+plugin-creator skill's `validate_plugin.py`) reads only
+`.codex-plugin/plugin.json`. The canonical root `plugin.json` was validated
+separately on 2026-10-04, against the schema it declares (Agent Plugins 1.0.0).
 
 That run exercised one skill, not every installed surface, so `verified` stays
 `null`. The hooks are the reason it matters. On 2026-10-03 the first real
-install's cached hooks could not load the vault in any session. They were run by
-hand through `zsh -lc`: that machine's default shell, started the way Codex's
-command runner starts a hook on its main branch (`<default shell> -lc`). That
-0.153.4 does the same is not confirmed. In the first session
-the failure sat in the model's context under the welcome, which was all the user
-saw. The core had taken the shell's root for its own. That is fixed, and the
-suite now runs every rendered hook from the built shell. A live Codex session
-firing them from an installed release is still owed.
-
-The shell is not published. Build it and install the tarball through npx from
-this checkout:
+install's cached hooks could not load the vault in any session. They were run
+by hand through `zsh -lc`; the failure did not depend on the shell form. In the
+first session the failure sat in the model's context under the welcome, which
+was all the user saw. The core had taken the shell's root for its own. That is
+fixed, and the suite now runs every rendered hook from the built shell. A live
+Codex session firing them from an installed release is still owed.
+
+How 0.153.4 starts a hook was read from its source, not measured: under the
+session's shell as `<shell> -c`, with the environment the Codex process had when
+it built the session's hooks. `$SHELL -lc` (or `/bin/sh -lc`) is the fallback
+when the hooks are built without exactly one ready local environment. So a hook
+finds `node` on the Codex process's own `PATH`, plus whatever `.zshenv` adds:
+zsh reads `.zshenv` for a `-c` command, not `.zprofile` or `.zshrc`, so a Codex
+not started from a terminal can miss a `node` that only `.zprofile` puts on
+`PATH`.
+
+The shell is published as `projectstore-codex` from 0.28.1, ahead of that live
+run, by the maintainer's decision:
+
+```sh
+npx projectstore-codex install --project "$PWD"
+```
+
+For later releases, `npx projectstore-codex@<version> upgrade --project "$PWD"`.
+Installation is user-global because Codex stores marketplace registrations and
+plugin caches in `CODEX_HOME`; the agents block in `AGENTS.md` remains
+project-local. Ordinary uninstall leaves the global plugin in place; add
+`--global` only when you mean to remove it for every project. From this
+checkout, the same flow runs against a built tarball:
 
 ```sh
 npm run shells:build -- --only projectstore-codex --dev --out dist
 npx --package "./dist/projectstore-codex-$(node -p 'require("./package.json").version').tgz" projectstore-codex install --project "$PWD"
 ```
 
-The shell package is release-gated until its first npm publication. From this
-repository, the same flow is exercised against the packed tarball. Installation
-is user-global because Codex stores marketplace registrations and plugin caches
-in `CODEX_HOME`; the agents block in `AGENTS.md` remains project-local. After
-the first explicit npm publication, the shorter registry form is
-`npx projectstore-codex@<version> install --project "$PWD"` (or `upgrade`). Ordinary
-uninstall leaves the global plugin in place; add `--global` only when you mean
-to remove it for every project.
-
 What is known, and how:
 
 - **Hooks are rendered; their live firing from an installed release is not

package/node_modules/projectstore/harnesses/claude-code.json

@@ -472,7 +472,7 @@
     "",
     "Without it, you would run `/plugin marketplace update SmartAndPoint` manually. See https://github.com/SmartAndPoint/ProjectStore#upgrading for details.",
     "",
-    "**Upgrading from 0.27.x to 0.28**: restart after the update, then move the project's files to `.projectstore/` with the one command the first session names, run from a terminal outside the session: for a git-marketplace install, the installed copy's own `bin/projectstore.mjs upgrade --harness claude-code --no-register --project <dir>`, which leaves the registration as it is; for the npm registration, `npx projectstore-claude@<version> upgrade --no-register --project <dir>`. The same run re-stamps the status-line launcher, and until then every reader falls back to the old paths. `status` and `search` answer from artifact facts; `doctor` gains surface, version-drift and mcp lines and exits 1 on findings; the plugin registers an MCP server the host may ask you to approve once. After the move, 0.27.x reads the project as unbound."
+    "**Upgrading from 0.27.x to 0.28**: restart after the update, then move the project's files to `.projectstore/` with the one command the first session names, run from a terminal outside the session: for a git-marketplace install, the installed copy's own `bin/projectstore.mjs upgrade --harness claude-code --no-register --project <dir>`, which leaves the registration as it is; for the npm registration, `npx projectstore-claude@<version> upgrade --no-register --project <dir>`. The same run re-stamps the status-line launcher, and until then every reader falls back to the old paths. `status` and `search` answer from artifact facts; `doctor` gains surface, version-drift and mcp lines and exits 1 on findings; the plugin registers an MCP server the host may ask you to approve once. On 0.28.0-rc.1 or rc.2, update first: their startup line named the shell form without `--no-register` (`npx projectstore-claude@<version> upgrade`), which also switches a git-marketplace install to npm for the checkout (the README's Upgrading section has the way back). Before the move, a rollback to 0.27.x keeps working and the move is the way forward again; after the move, 0.27.x reads the project as unbound."
   ],
   "agent_translation": {
     "carries_model": true,

package/node_modules/projectstore/harnesses/codex.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Harness capability manifest — Codex. The committed adapters/codex tree renders the source commands, roles, passive skills and hooks into Codex vocabulary. Measurements began with 759 captured hook firings on 2026-09-07/08; the complete built shell, isolated marketplace install, upgrade, validator and fresh-session skill load passed on codex-cli 0.153.4 on 2026-09-30.",
+  "_comment": "Harness capability manifest — Codex. The committed adapters/codex tree renders the source commands, roles, passive skills and hooks into Codex vocabulary. Measurements began with 759 captured hook firings on 2026-09-07/08; the complete built shell, isolated marketplace install, upgrade, validator and fresh-session skill load passed on codex-cli 0.153.4 on 2026-09-30. The validator reads only .codex-plugin/plugin.json; the canonical root plugin.json was validated separately on 2026-10-04 against the schema it declares (Agent Plugins 1.0.0).",
   "id": "codex",
   "display_name": "Codex",
   "emit": true,
@@ -7,7 +7,7 @@
   "output_dir": "adapters/codex",
   "docs": "https://developers.openai.com/codex/",
   "verified": null,
-  "verified_reason": "Null, restored 2026-10-03. docs/harnesses.md calls a harness supported only when every installed surface has been exercised end to end, and contract 16 of the generation spec (Generated harness surfaces: manifests, the generator and the three invariants) derives that label from this field. The 2026-09-30 run (session 01a0f079-7ecd-7331-95a9-2471def3cb22) exercised one surface: a fresh `codex exec` session loaded projectstore-status from the materialised cache. The hooks were not exercised, and the first real install showed why that matters. Its cached hooks, run by hand through `zsh -lc` (that machine's default shell, started as Codex's runner on its main branch starts a hook, `<default shell> -lc`; unconfirmed on 0.153.4), could not load the vault in any session; in the first, the failure sat beneath the welcome. The core had taken the shell's root for its own. That is fixed and pinned by a test that runs every rendered hook from the built shell. This block is set by a live run that exercises every installed surface: the hooks once registration has settled, including PreCompact, and the skill flows.",
+  "verified_reason": "Null, restored 2026-10-03. docs/harnesses.md calls a harness supported only when every installed surface has been exercised end to end, and contract 16 of the generation spec (Generated harness surfaces: manifests, the generator and the three invariants) derives that label from this field. The 2026-09-30 run (session 01a0f079-7ecd-7331-95a9-2471def3cb22) exercised one surface: a fresh `codex exec` session loaded projectstore-status from the materialised cache. The hooks were not exercised, and the first real install showed why that matters. Its cached hooks, run by hand through `zsh -lc` (a form the failure did not depend on: read from source, 0.153.4 runs a hook as `<session shell> -c` with the Codex process's environment, and `$SHELL -lc` only as a fallback), could not load the vault in any session; in the first, the failure sat beneath the welcome. The core had taken the shell's root for its own. That is fixed and pinned by a test that runs every rendered hook from the built shell. This block is set by a live run that exercises every installed surface: the hooks once registration has settled, including PreCompact, and the skill flows. The shell is published from 0.28.1, ahead of that run, by the maintainer's decision of 2026-10-04; publication does not set this block.",
   "runtime": {
     "detect_env": [
       "PLUGIN_ROOT",
@@ -290,7 +290,8 @@
   "rewrites": [],
   "install": {
     "mechanism": "the package's portable plugin root, registered through its distribution shell and Codex's own marketplace CLI",
-    "shell_reason": "The built `projectstore-codex` shell carries the rendered Codex skills and hooks plus an exact bundled core, fixes --harness codex, stages a stable marketplace under CODEX_HOME, and asks Codex itself to install it. The `shell` key is deliberately absent until its first npm publication, so generated guidance cannot send users to the reserved placeholder package.",
+    "shell": "projectstore-codex",
+    "shell_reason": "The built `projectstore-codex` shell carries the rendered Codex skills and hooks plus an exact bundled core, fixes --harness codex, stages a stable marketplace under CODEX_HOME, and asks Codex itself to install it. It is published from 0.28.1, by the maintainer's decision of 2026-10-04. Until then this key was absent, so generated guidance could not send users to the reserved 0.0.1 placeholder; the core alone is not Codex's plugin root and cannot register it.",
     "why_not_scripted": "The shell does not edit Codex's registry or cache. It atomically stages the plugin source, previews the host commands, then runs `codex plugin marketplace add` and `codex plugin add`; a read-back verifies the installed version and payload digest. The global plugin survives ordinary project uninstall; `uninstall --global` is the explicit destructive form.",
     "steps": [
       "npx projectstore-codex install --project \"$PWD\"",

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.28.0-rc.3",
+  "version": "0.28.1",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "keywords": [
     "project-management",

package/node_modules/projectstore/scripts/doctor.mjs

@@ -60,6 +60,7 @@ import {
   lastVaultActivityMs,
   ENTRY_IGNORE,
   AGENTS_BLOCK_OPEN_SRC,
+  AGENTS_BLOCK_CLOSE,
   agentsBlockVersion,
   findAgentsBlock,
   statusLineLauncherPath,
@@ -75,8 +76,11 @@ import {
   hostSettingsPath,
   readOverlayAt, layoutRoster,
   installChannel,
+  cmpPrecedence,
+  cmpVersion,
+  blockVisibleTo,
 } from "./lib.mjs";
-import { agentOverrides, childEnv, sourceHarness, runtimeEnvNames, loadHarness, detectHarnesses, configPath as harnessConfigPath, packageCommand } from "./harness.mjs";
+import { agentOverrides, childEnv, sourceHarness, runtimeEnvNames, loadHarness, detectHarnesses, identifiedHarnessId, configPath as harnessConfigPath, packageCommand } from "./harness.mjs";
 
 // A remedy used to interpolate the surface's harness variable here. It cannot:
 // measured 2026-09-06, NO harness gives its Bash tool that variable, and a
@@ -387,9 +391,14 @@ export function checkPendingUpgrade(proj, home = homedir(), root = pluginRoot())
     relative(proj, lp))];
 }
 
-export function checkAgentsBlock(proj) {
+// The two findings the layout move itself repairs carry what they say without
+// their remedy, so a pending move can name itself instead (foldIntoMove).
+const moveRepairs = (f, fact) => ({ ...f, byMove: fact });
+
+export function checkAgentsBlock(proj, { env = process.env, root = pluginRoot() } = {}) {
   const out = [];
   const AGENT_BLOCK_VERSION = agentsBlockVersion();
+  const texts = {};
   // One parser for every reader (findAgentsBlock): its count is the loose one,
   // so a good block plus a re-wrapped marker in one file is "more than once"
   // here exactly as install and uninstall see it (both refuse), never a quiet
@@ -397,6 +406,7 @@ export function checkAgentsBlock(proj) {
   // registered" is the reading that makes install append a second block.
   let blocks = 0;
   let wrappedFiles = 0;
+  let unclosedFiles = 0;
   const perFile = {};
   const staleVersions = [];
   for (const name of ["CLAUDE.md", "AGENTS.md"]) {
@@ -404,6 +414,7 @@ export function checkAgentsBlock(proj) {
     if (!existsSync(p)) continue;
     let text;
     try { text = readFileSync(p, "utf8"); } catch { continue; }
+    texts[name] = text;
     const f = findAgentsBlock(text);
     if (!f) continue;
     perFile[name] = f.count;
@@ -414,6 +425,13 @@ export function checkAgentsBlock(proj) {
         `${name}:${f.line}: the projectstore:agents open marker does not close on its own line — put \`-->\` back on the marker's line, then run /projectstore:agents register (install and uninstall refuse until it does).`, name));
       continue;
     }
+    if (f.unclosed) {
+      // Named here as the wrapped marker is, so the startup count carries it:
+      // the agents-block plan refuses it, and the layout move with it.
+      unclosedFiles++;
+      out.push(finding("install", "issue", "agents-block",
+        `${name}: the projectstore:agents block opens and never closes — close it with \`${AGENTS_BLOCK_CLOSE}\` or delete the half block, then run /projectstore:agents register (install and uninstall refuse until then).`, name));
+    }
     for (const m of text.matchAll(AGENT_BLOCK_MARKER)) {
       const v = parseInt(m[1], 10);
       if (v !== AGENT_BLOCK_VERSION) staleVersions.push({ file: name, v });
@@ -427,25 +445,75 @@ export function checkAgentsBlock(proj) {
     // One block in each file is a state install resolves (it keeps the
     // preferred file's); two in one file is not, and stays an issue — and a
     // wrapped marker anywhere means install refuses, so the "both files"
-    // advice is withheld while one is wrapped.
+    // advice is withheld while one is wrapped or never closes.
     const twiceInOne = Object.entries(perFile).find(([, n]) => n > 1);
     if (twiceInOne) {
       out.push(finding("install", "issue", "agents-block",
         `${twiceInOne[0]} carries the projectstore:agents block ${twiceInOne[1]} times — keep exactly one; install refuses until it does.`, twiceInOne[0]));
-    } else if (wrappedFiles) {
+    } else if (wrappedFiles || unclosedFiles) {
       // already named above, file by file
     } else {
       out.push(finding("install", "warn", "agents-block",
         `The projectstore:agents block is in both CLAUDE.md and AGENTS.md — run /projectstore:agents register: install keeps the one in ${(sourceHarness()?.surfaces?.agents_block?.files || ["AGENTS.md"])[0]} and removes the other.`));
     }
   }
+  // A state the agents-block plan refuses — a wrapped marker, a block that
+  // never closes, a block twice in one file — refuses the move with it, so
+  // nothing here is the move's to repair while one stands.
+  const refuses = wrappedFiles > 0 || unclosedFiles > 0 || Object.values(perFile).some((n) => n > 1);
   for (const s of staleVersions) {
-    out.push(finding("install", "issue", "agents-block",
-      `Agents block in ${s.file} is v${s.v}, expected v${AGENT_BLOCK_VERSION} — re-run /projectstore:agents register.`, s.file));
+    const fact = `Agents block in ${s.file} is v${s.v}, expected v${AGENT_BLOCK_VERSION}`;
+    const f = finding("install", "issue", "agents-block", `${fact} — re-run /projectstore:agents register.`, s.file);
+    out.push(refuses ? f : moveRepairs(f, fact));
+  }
+  // Placement, held to the predicate install plans from (the install spec,
+  // contract 6 as amended after the rc.3 tag): one well-formed block, seen by
+  // every harness the project uses. rc.1 and rc.2 left a block in an
+  // AGENTS.md-only project with no CLAUDE.md, so Claude Code saw nothing, and
+  // nothing said so. Used means detected by directory, or identified from the
+  // environment — never the source harness a terminal run falls back to, so a
+  // Codex-only project hears nothing about CLAUDE.md (contract 16). An issue
+  // for the harness that identified itself, a warning for one only detected.
+  const blockFile = blocks === 1 && !refuses ? Object.keys(perFile)[0] : null;
+  if (blockFile) {
+    const identified = identifiedHarnessId(env);
+    const used = new Set([...detectHarnesses(proj).map((d) => d.id), ...(identified ? [identified] : [])]);
+    for (const id of used) {
+      const m = loadHarness(id);
+      if (!m || blockVisibleTo(m, blockFile, texts)) continue;
+      const ab = m.surfaces.agents_block;
+      const why = (ab.files || []).includes(blockFile)
+        ? `${ab.reads_natively} does not import it (\`@${blockFile}\`)`
+        : `it reads ${(ab.files || []).join(" and ")} only`;
+      const fact = `The projectstore:agents block is in ${blockFile}, which ${m.display_name} does not see: ${why}`;
+      // The resolved-root form the surface remedy uses: the running copy's own bin.
+      const remedy = `install the block for ${m.display_name}: node "${join(root, "bin", "projectstore.mjs")}" install --harness ${id} --surface agents_block --project "${proj}"`;
+      const f = finding("install", id === identified ? "issue" : "warn", "agents-block", `${fact} — ${remedy}.`, blockFile);
+      // The layout's harness is the one the move's command installs for, so the
+      // move plans this import; another harness's is not the move's to repair.
+      out.push(id === sourceHarness()?.id ? moveRepairs(f, fact) : f);
+    }
   }
   return out;
 }
 
+// While the layout move is pending, the findings the move itself repairs fold
+// into it instead of being counted beside it (the layout spec, contract 7 as
+// amended after the rc.3 tag; the upgrade story's O1): the stale block, which
+// the move re-registers, and the block's invisibility to the layout's
+// harness, whose import the move plans. Nothing else folds — a block twice in
+// one file, one that never closes or a wrapped marker makes the agents-block
+// plan refuse, which blocks the move itself. The message points at the layout
+// finding rather than computing its command again. The tag is internal: no
+// finding leaves here carrying it.
+export function foldIntoMove(findings) {
+  const layout = findings.find((f) => f.check === "layout-legacy" || f.check === "layout-two-configs");
+  const step = layout && (layout.check === "layout-two-configs"
+    ? "delete the binding the layout-two-configs finding names, then run the layout move, which repairs this"
+    : "the layout move repairs this: run what the layout-legacy finding names");
+  return findings.map(({ byMove, ...f }) => (byMove && layout ? { ...f, level: "info", message: `${byMove} — ${step}.` } : f));
+}
+
 // Both scopes are walked. The original reason ("project > user > plugin, so a
 // copy in either scope shadows the bundle") turned out to be wrong — a copy
 // shadows NOTHING, because plugin agents register under a scoped id and copies
@@ -509,8 +577,10 @@ export async function checkHarnessSurfaces(_cfg, proj, { home = homedir(), root
       }
     } else if (s.surface === "agents_block") {
       // Version drift and duplicates are checkAgentsBlock's; what only the
-      // state knows is content that differs at the same version, and a block
-      // that never closes.
+      // state knows is content that differs at the same version. A block that
+      // never closes is named by both: checkAgentsBlock carries it to the
+      // startup line, and the state names it with the file's own reason, as a
+      // wrapped marker already was.
       if (s.state === "unparseable") {
         out.push(finding("install", "issue", "surface", `${where} — ${s.reason}`, where));
       } else if (s.state === "ours-stale" && /content differs|migrates/.test(s.reason || "")) {
@@ -590,13 +660,38 @@ export function checkOverlays(cfg, proj, { root = pluginRoot(), home = homedir()
 // itself); a competing copy enabled beside ours → an issue (two enabled copies
 // of one plugin); a competitor alone → an info naming the npm path; foreign →
 // never repairable; the host CLI missing → an info.
-export function checkPluginRegistration(proj, states = []) {
+export function checkPluginRegistration(proj, states = [], { home = homedir() } = {}) {
   const out = [];
   for (const s of states.filter((x) => x.kind === "registration")) {
     // The shell form when the manifest names a shell (contract 12): the
     // command a user can paste, built in one place.
     const h = loadHarness(s.harness) || { id: s.harness };
     const refresh = packageCommand(h, "upgrade", { version: s.pkg || "latest", args: `--surface ${s.surface} --project "${proj}"` });
+    // A copy this registration silenced for the checkout and the checkout
+    // still holds off, one per key (the install spec, contract 13 as amended
+    // after the rc.3 tag): rc.1 and rc.2's startup offer left exactly this on
+    // git-marketplace projects, and nothing said so. Only for a registration
+    // this checkout holds; the record lives in our directory, so a directory
+    // removed by hand takes it along and leaves nothing to name.
+    if ((s.silenced || []).length && (s.state === "current" || s.state === "stale")) {
+      // The row this checkout loads: its own local-scope row first, then a
+      // user-scope one — never another checkout's (layoutRemedy's rule).
+      const real = (x) => { try { return realpathSync.native(x); } catch { return resolve(x); } };
+      const here = real(proj);
+      const rows = installedPluginEntries(home, proj).filter((e) => e.present && (!e.projectPath || real(e.projectPath) === here));
+      for (const key of s.silenced) {
+        const row = rows.filter((e) => e.key === key).sort((a, b) => Number(Boolean(b.projectPath)) - Number(Boolean(a.projectPath)))[0];
+        if (!row) {
+          out.push(finding("install", "info", "plugin-registration", `${key} is held off in this checkout's local settings, where the npm registration turned it off — and that copy is no longer installed, so the entry is stale.`, s.path));
+          continue;
+        }
+        // The release line, not the build: a 0.28 release candidate reads a
+        // moved project; 0.27.x reads it as unbound. No version reads as old.
+        const old = !row.version || cmpVersion(row.version, "0.28.0") < 0;
+        out.push(finding("install", "info", "plugin-registration",
+          `${key} (${row.version || "no version recorded"}) is off for this checkout: the npm registration turned it off when it registered, so the checkout no longer loads that copy and a /plugin update no longer reaches the project. ${old ? "Update that copy first — 0.27.x reads a moved project as unbound. " : ""}To go back to it: from a terminal outside the session, ${packageCommand(h, "uninstall", { version: s.pkg || "latest", args: `--surface ${s.surface} --project "${proj}"` })}, restart, then /projectstore:doctor --fix. If moving to npm was meant, ignore this.`, s.path));
+      }
+    }
     const others = (s.others || []).map((o) => `${o.key} (${o.version || "?"})`).join(", ");
     if (s.state === "foreign") {
       out.push(finding("install", "issue", "plugin-registration-foreign", `${s.reason} — install, uninstall and upgrade refuse it; nothing repairs it.`, s.path));
@@ -770,6 +865,21 @@ export function checkLayout(proj, harness = sourceHarness(), { level = "warn", r
 // the move never needs the registration, so a misread channel can cost a
 // launcher stamp but never a channel switch. A copy that predates the move
 // (no bin/projectstore.mjs — 0.27.x) cannot run it: update that copy first.
+// Nor can one whose CLI predates --no-register (takesNoRegister).
+//
+// Whether a registry copy can run the command named for it. `--no-register`
+// arrived in 0.28.0-rc.3, and rc.1 and rc.2 parse strictly, so the command
+// exits 2 on the flag and writes nothing (the layout spec, contract 12 as
+// amended after the rc.3 tag). Read from the copy's own parse table, never
+// from its version: a never-published 0.28.0 build ranks above rc.3 and lacks
+// the flag, while a copy labelled rc.2 taken from main at 418448e has it. A
+// file read, because this runs in the SessionStart subset: never an import()
+// of the copy, never a spawn. Add files to the read, never drop cli.mjs:
+// released copies keep their parse there.
+export function takesNoRegister(copy) {
+  try { return readFileSync(join(copy, "scripts", "cli.mjs"), "utf8").includes('"no-register"'); } catch { return false; }
+}
+
 export function layoutRemedy(proj, { root = pluginRoot(), home = homedir(), harness = sourceHarness(), env = process.env } = {}) {
   // A session under a relocated host home hands it on: a terminal without it
   // would classify the copy as a checkout, render no launcher and never clear
@@ -790,10 +900,22 @@ export function layoutRemedy(proj, { root = pluginRoot(), home = homedir(), harn
     .filter((e) => e.present && e.enabled && (!e.projectPath || mine(e)))
     .sort((a, b) => (Number(mine(b)) - Number(mine(a))) || (b.at - a.at))[0];
   if (copy) {
+    const v = copy.version ? ` (${copy.version})` : "";
     if (!existsSync(join(copy.path, "bin", "projectstore.mjs"))) {
-      return { advice: `This project's projectstore plugin${copy.version ? ` (${copy.version})` : ""} predates the move and cannot run it: update it first (in Claude Code: /plugin marketplace update, then /plugin update, then restart), and the startup line names the command` };
+      return { advice: `This project's projectstore plugin${v} predates the move and cannot run it: update it first (in Claude Code: /plugin marketplace update, then /plugin update, then restart), and the startup line names the command` };
+    }
+    // Chosen first, gated after: the copy is what the project runs, so an
+    // incapable one gets advice even beside a capable user-scope copy.
+    const viaRegistration = installChannel(copy.path, { home, harness }) === "registration";
+    if (!takesNoRegister(copy.path)) {
+      return { advice: viaRegistration
+        // Its channel's ordinary refresh, at the running version: the plain
+        // upgrade re-registers from npm — not a switch for an npm project — and
+        // moves the project in the same run.
+        ? `This project's projectstore plugin${v} is the npm registration's copy and predates --no-register, so it cannot run the move as named: refresh that registration, which moves the project too, from a terminal outside the session: ${prefix}${packageCommand(harness, "upgrade", { version: pluginVersion(root) || "latest", args: `--project "${proj}"` })}`
+        : `This project's projectstore plugin${v} predates --no-register and cannot run the move as named: update it first (in Claude Code: /plugin marketplace update, then /plugin update, then restart), and the startup line names the command` };
     }
-    return installChannel(copy.path, { home, harness }) === "registration" ? shell(copy.version) : own(copy.path);
+    return viaRegistration ? shell(copy.version) : own(copy.path);
   }
   return channel === "package" ? shell(pluginVersion(root)) : own(root);
 }
@@ -865,16 +987,6 @@ export function checkVaultGit(cfg) {
     "Vault is not a git repository — the knowledge has no history/blame/review. Consider `git init` (doctor --fix offers it).")];
 }
 
-function versionNewer(a, b) {
-  const pa = String(a).split(".").map(Number);
-  const pb = String(b).split(".").map(Number);
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const x = pa[i] || 0, y = pb[i] || 0;
-    if (x !== y) return x > y;
-  }
-  return false;
-}
-
 // Marketplace auto-update (maintainer request 2026-07-03): third-party
 // marketplaces do NOT auto-update by default, so a stale plugin looks like
 // "the feature is broken". Read the real registries and, when the flag is
@@ -948,7 +1060,8 @@ export function checkAutoUpdate(home = homedir()) {
     const latest = (catalog.plugins || []).find((p) => p.name === name)?.version;
     const running = (named && named.version)
       || JSON.parse(readFileSync(join(root, ".claude-plugin", "plugin.json"), "utf8")).version;
-    if (latest && running && versionNewer(latest, running)) {
+    // Precedence, not the triple: a session on 0.28.0-rc.3 hears that 0.28.0 is out.
+    if (latest && running && cmpPrecedence(latest, running) > 0) {
       out.push(finding("install", "warn", "auto-update",
         `A newer ${name} is available: v${latest} (running v${running}) — run /plugin marketplace update ${marketplace}, then /reload-plugins.`));
     }
@@ -1852,7 +1965,7 @@ export async function runInstallChecks(cfg, proj, opts = {}) {
     ...checkLayoutTemplates(cfg),
     ...checkHooksAlive(cfg),
     ...checkStatusline(cfg, proj),
-    ...checkAgentsBlock(proj),
+    ...checkAgentsBlock(proj, { env: opts.env, root: opts.root }),
     ...checkOverrideCopies(proj),
     ...checkEnvModel(),
     ...checkEnvEffort(),
@@ -1867,9 +1980,9 @@ export async function runInstallChecks(cfg, proj, opts = {}) {
   let read = null;
   try { read = await readSurfaceStates(proj, opts); } catch {} // reported as a warn by checkHarnessSurfaces
   out.push(...await checkHarnessSurfaces(cfg, proj, { ...opts, read }));
-  if (read) out.push(...checkPluginRegistration(proj, read.result.states));
+  if (read) out.push(...checkPluginRegistration(proj, read.result.states, { home: opts.home }));
   if (read) out.push(...checkVersionDrift(opts.home, read.result.states, proj));
-  return out;
+  return foldIntoMove(out);
 }
 
 export function runVaultChecks(cfg) {
@@ -1932,24 +2045,26 @@ export function runStartupChecks(cfg, proj, budgetMs = 150) {
   ];
   const findings = [];
   for (const step of steps) {
-    if (Date.now() - started > budgetMs) return { skipped: true, count: 0, findings };
+    if (Date.now() - started > budgetMs) return { skipped: true, count: 0, findings: foldIntoMove(findings) };
     try { findings.push(...step()); } catch {}
   }
+  // The findings the move repairs are not counted beside it (foldIntoMove).
+  const settled = foldIntoMove(findings);
   // While the move is pending, the re-stamp is not a step of its own: the move
   // re-stamps the launcher at its new path (the layout spec, contract 7 as
   // amended 2026-10-03), and an in-session `doctor --fix` would write that
   // launcher and then stop at the deferred move with exit 1. So the line names
   // one step, and says what it covers when the dropped offer would have fired.
-  const movePending = findings.some((f) => f.check === "layout-legacy" || f.check === "layout-two-configs");
-  const restamp = findings.some((f) => f.level === "info" && f.check === "upgrade");
-  const offers = findings
+  const movePending = settled.some((f) => f.check === "layout-legacy" || f.check === "layout-two-configs");
+  const restamp = settled.some((f) => f.level === "info" && f.check === "upgrade");
+  const offers = settled
     .filter((f) => f.level === "info" && OFFER_CHECKS.has(f.check) && !(movePending && f.check === "upgrade"))
     .map((f) => (movePending && restamp && f.check === "layout-legacy" ? `${f.message} The same run re-stamps the status line launcher.` : f.message));
   return {
     skipped: false,
-    count: findings.filter((f) => f.level === "issue").length,
+    count: settled.filter((f) => f.level === "issue").length,
     offers,
-    findings,
+    findings: settled,
   };
 }
 

package/node_modules/projectstore/scripts/harness.mjs

@@ -120,7 +120,49 @@ export function detectHarnessId(env = process.env, dir = MANIFEST_DIR) {
 function detect(env, dir) {
   const forced = env.PROJECTSTORE_HARNESS;
   if (forced && loadHarnesses(dir).has(forced)) return forced;
+  const best = ranked(env, dir);
+  // A strong signal is the harness identifying itself, and it decides.
+  if (best && best.strong) return best.id;
 
+  // Only weak signals. That is not enough to switch harness: the project
+  // itself carries better evidence — whichever harness directory is present
+  // in it is the harness this project is used from. (Until 2026-09-06 the
+  // evidence was "which harness directory holds our config"; the binding is
+  // harness-neutral now and carries no such signal.)
+  const cwd = process.cwd();
+  for (const m of loadHarnesses(dir).values()) {
+    const d = m.runtime?.harness_dir;
+    if (d && existsSync(join(cwd, d))) return m.id;
+  }
+  if (best) return best.id;
+  const src = sourceHarness(dir);
+  return src ? src.id : null;
+}
+
+// The harness that identifies ITSELF from the environment, or null: a strong
+// signal (its own plugin-root or project-dir variable, not one another
+// harness shares), or its session marker — runtime.session_env, which a Bash
+// tool inside a session carries while the variables a hook receives are
+// absent (measured 2026-09-05). Never the weak ranking, never the cwd's
+// directory, never the source harness detectHarnessId falls back to. A
+// finding that must not fire for a harness the project only might use asks
+// this (the install spec, contract 6 as amended after the rc.3 tag).
+export const IDENTIFIED_ENV = "PROJECTSTORE_IDENTIFIED";
+export function identifiedHarnessId(env = process.env, dir = MANIFEST_DIR) {
+  const forced = env.PROJECTSTORE_HARNESS;
+  if (forced && loadHarnesses(dir).has(forced)) return forced;
+  // A parent of ours decided before it named the project in the harness's own
+  // vocabulary (childEnv), so its answer stands — an empty one included.
+  if (env[IDENTIFIED_ENV] !== undefined) return loadHarnesses(dir).has(env[IDENTIFIED_ENV]) ? env[IDENTIFIED_ENV] : null;
+  const best = ranked(env, dir);
+  if (best && best.strong) return best.id;
+  for (const m of loadHarnesses(dir).values()) {
+    if ((m.runtime?.session_env || []).some((k) => env[k])) return m.id;
+  }
+  return null;
+}
+
+function ranked(env, dir) {
   // Explicit plugin-root/home variables beat merely-present ones: a shell that
   // exports CODEX_HOME globally should not make a Claude Code session read as
   // Codex when Claude Code also handed us CLAUDE_PLUGIN_ROOT.
@@ -168,22 +210,7 @@ function detect(env, dir) {
     const rank = (strongHits > 0 ? 1e6 : 0) + strongHits * 1e3 + weakHits;
     if (!best || rank > best.rank) best = { id: m.id, rank, strong: strongHits > 0 };
   }
-  // A strong signal is the harness identifying itself, and it decides.
-  if (best && best.strong) return best.id;
-
-  // Only weak signals. That is not enough to switch harness: the project
-  // itself carries better evidence — whichever harness directory is present
-  // in it is the harness this project is used from. (Until 2026-09-06 the
-  // evidence was "which harness directory holds our config"; the binding is
-  // harness-neutral now and carries no such signal.)
-  const cwd = process.cwd();
-  for (const m of loadHarnesses(dir).values()) {
-    const d = m.runtime?.harness_dir;
-    if (d && existsSync(join(cwd, d))) return m.id;
-  }
-  if (best) return best.id;
-  const src = sourceHarness(dir);
-  return src ? src.id : null;
+  return best;
 }
 
 // Test seam: the detected id is memoised for the process; a test that changes
@@ -474,6 +501,11 @@ export function configPath(projectDir, env = process.env) {
 export function childEnv(base = process.env, { projectRoot: root, pluginRoot: plugin } = {}) {
   const out = { ...base };
   const r = activeHarness(base)?.runtime || {};
+  // Who called is decided here, before the project is named below: a
+  // project-dir variable we write would otherwise read, in the child, as the
+  // harness identifying itself — a terminal `doctor` took Claude Code for the
+  // session's own harness (the review of the post-rc.3 fixes, 2026-10-04).
+  if (base[IDENTIFIED_ENV] === undefined) out[IDENTIFIED_ENV] = identifiedHarnessId(base) || "";
   if (r.project_dir_env && root) out[r.project_dir_env] = root;
   // A caller that runs its own copy of the core (the npm bin) names it, so a
   // child never resolves templates or its version from a sibling install.

package/node_modules/projectstore/scripts/install-harness.mjs

@@ -67,7 +67,7 @@ import { loadHarness, loadHarnesses, harnessIds, sourceHarness, detectHarnesses,
 import { FOREIGN_TEXT, GRAMMAR_VERSION } from "./provenance.mjs";
 import { analyseBlock, analyseJsonEntry, analyseStampedFile, analyseRegistration, analysePortableRegistration, analyseLayout, isOurFile, readText } from "./surfaces.mjs";
 import { payloadFiles, renderPortableCatalog } from "./portable-registration.mjs";
-import { pluginRoot, writeFileAtomic, writeExclusiveMetadata, ensureStateDir, ensureRuntimeDir, removeAgentsBlock, replaceAgentsBlock, readConfigAt, isPluginCacheRoot, isEphemeralRoot, statusLineIsOurWiring, claudeHome, packageDigest, writeOwnTree, removeOwnTree, cmpVersion, whichOnPath as whichOnPathFromLib, moveStateDir, mergeEntryLog, movePath, removeInside, statusLineScriptPath, layoutPaths, stagePortableMarketplace, finishPortableMarketplace, rollbackPortableMarketplace, removeTreeUnder } from "./lib.mjs";
+import { pluginRoot, writeFileAtomic, writeExclusiveMetadata, ensureStateDir, ensureRuntimeDir, removeAgentsBlock, replaceAgentsBlock, readConfigAt, isPluginCacheRoot, isEphemeralRoot, statusLineIsOurWiring, claudeHome, packageDigest, writeOwnTree, removeOwnTree, cmpPrecedence, importsLine, whichOnPath as whichOnPathFromLib, moveStateDir, mergeEntryLog, movePath, removeInside, statusLineScriptPath, layoutPaths, stagePortableMarketplace, finishPortableMarketplace, rollbackPortableMarketplace, removeTreeUnder } from "./lib.mjs";
 
 import { GENERATOR } from "./surfaces.mjs";
 export { GENERATOR };
@@ -112,7 +112,7 @@ function planAgentsBlock(ctx, key, s) {
   const items = [];
   if (a.refusal) return [{ surface: key, kind: "shared", path: a.files[0].path, entry: "projectstore:agents", state: "refused", action: "refuse", reason: a.refusal }];
 
-  const hasImport = (text) => String(text ?? "").split("\n").some((l) => l.trim() === importLine);
+  const hasImport = (text) => importsLine(text, importLine);
   // A CLAUDE.md that is nothing but the import registration added is ours to
   // delete when the block goes (ADR-002 decision 4); anything else stays.
   const onlyImport = (text) => String(text ?? "").split("\n").every((l) => !l.trim() || l.trim() === importLine);
@@ -256,7 +256,7 @@ function planAgentsBlock(ctx, key, s) {
     const rewrite = items.find((i) => i.action === "remove" && i.path === e.path);
     // An absent native file is empty text, not a reason to skip: it is created.
     const text = rewrite ? rewrite.after : (e.present ? e.text : "");
-    if (typeof text !== "string" || text.split("\n").some((l) => l.trim() === line)) continue;
+    if (typeof text !== "string" || importsLine(text, line)) continue;
     const after = line + "\n" + (text.startsWith("\n") || !text.trim() ? "" : "\n") + text;
     if (rewrite) { rewrite.after = after; rewrite.deleteIfEmpty = false; rewrite.reason += `; ${line} import added`; }
     else items.push({ surface: `${key}_import`, kind: "shared", path: e.path, entry: line, state: "ours-absent", action: e.present ? "add" : "create",
@@ -271,14 +271,17 @@ function planAgentsBlock(ctx, key, s) {
 // One host command as a plan step: the verbatim argv (the manifest's
 // subcommand with its placeholders filled), why it runs, and the host-owned
 // files it is known to touch (measured 2026-09-05 — the manifest's cli.verified).
+// A portable registration keeps its marketplace and enablement stanzas in one
+// global config (registry.global_config; Codex's config.toml, measured
+// 2026-09-07), so the preview names that file wherever a step rewrites it.
 function hostStep(a, s, name, fill, why) {
   const template = s.cli.commands[name];
   if (!Array.isArray(template) || !template.length) throw new Error(`${s.format}: host operation ${name} is not declared`);
   const argv = template.map((t) => t.replace(/\{(\w+)\}/g, (_, k) => fill[k] ?? `{${k}}`));
   const p = a.paths;
   const touches = {
-    validate: [], marketplace_add: [p.marketplaces, p.projectSettings], marketplace_update: [p.marketplaces], marketplace_remove: [p.marketplaces, p.projectSettings],
-    install: [p.installed, p.projectSettings, p.cacheDir], update: [p.installed, p.cacheDir], uninstall: [p.installed, p.projectSettings], disable: [p.projectSettings], enable: [p.projectSettings],
+    validate: [], marketplace_add: [p.marketplaces, p.globalConfig, p.projectSettings], marketplace_update: [p.marketplaces], marketplace_remove: [p.marketplaces, p.globalConfig, p.projectSettings],
+    install: [p.installed, p.globalConfig, p.projectSettings, p.cacheDir], update: [p.installed, p.cacheDir], uninstall: [p.installed, p.globalConfig, p.projectSettings], disable: [p.projectSettings], enable: [p.projectSettings],
   }[name] || [];
   return { kind: "host", name, bin: s.cli.bin, argv, why, touches: touches.filter(Boolean) };
 }
@@ -455,7 +458,7 @@ function planRegistration(ctx, key, s) {
     // pack → install → fix → pack loop never bumps it. The host will not
     // re-copy at an equal version (measured), so that refresh is uninstall + install.
     const sameVersionDiffers = a.contentDiffers === true;
-    const rewrite = !a.dir.present || (cmpVersion(a.dir.pkg, a.pkg) < 0) || a.dir.digestOk === false || sameVersionDiffers;
+    const rewrite = !a.dir.present || (cmpPrecedence(a.dir.pkg, a.pkg) < 0) || a.dir.digestOk === false || sameVersionDiffers;
     const disabled = [...new Set([...a.dir.disabled, ...a.others.map((o) => o.key)])];
     const digest = rewrite ? packageDigest(root) : (a.dir.prov?.digest || null);
     const files = digest ? digest.count : 0;
@@ -596,7 +599,7 @@ export function plan(projectDir, { harnesses = [], mode = "install", env = proce
   // once whatever --surface names — planned first, so every surface below is
   // planned against the new paths; its cleanup is planned last (below).
   const layoutHarness = loadHarness(ids.find((id) => { const p = layoutPaths(projectDir, { harnessDir: loadHarness(id).runtime?.harness_dir || null }); return existsSync(p.legacy.binding) || existsSync(p.legacy.runtime); }) || ids[0]);
-  const layoutCtx = { projectDir, mode, env, home, root, harness: layoutHarness, incomplete: false };
+  const layoutCtx = { projectDir, mode, env, home, root, harness: layoutHarness, incomplete: false, surfaces };
   const layout = planLayout(layoutCtx);
   for (const item of layout.first) out.items.push({ harness: layoutHarness.id, ...item });
   if (layoutCtx.incomplete) out.incomplete = true;
@@ -691,7 +694,12 @@ function planLayout(ctx) {
   const base = { surface: "layout", kind: "layout", path: P.legacy.binding, entry: null, state: a.state, reason: null };
   if (mode === "uninstall") {
     // Disowning: the legacy runtime directory goes with the new one when it is
-    // ours (its header); the legacy binding is bind's, never uninstall's.
+    // ours (its header); the legacy binding is bind's, never uninstall's. A
+    // narrowed uninstall leaves it alone: the way back from an npm switch is
+    // `uninstall --surface plugin`, and it deleted a not-yet-moved project's
+    // sessions, log and the launcher its status line still ran (the critic's
+    // fourth pass, 2026-10-04). `surfaces` is null when nothing was named.
+    if (ctx.surfaces) return none;
     if (!a.legacy.runtime || !a.legacy.runtimeOurs) return none;
     return { first: [], last: [{ ...base, surface: "layout_cleanup", path: P.legacy.runtime, state: "legacy", action: "remove", reason: "the legacy runtime directory is ours (its .gitignore header) and goes with the state", steps: [
       { kind: "remove-legacy-runtime", path: P.legacy.runtime, why: "the pre-0.28 state directory, removed whole" },
@@ -714,7 +722,7 @@ function planLayout(ctx) {
   const last = [];
   if (a.legacy.launcher || a.legacy.runtime) {
     const cleanup = [];
-    if (a.legacy.launcher) cleanup.push({ kind: "remove-legacy-launcher", path: P.legacy.launcher, why: "removed once the new launcher is written and the settings entry names it — or at once when the status-line slot is not ours (foreign, or empty because the status line is off); kept if anything still points at it" });
+    if (a.legacy.launcher) cleanup.push({ kind: "remove-legacy-launcher", path: P.legacy.launcher, why: "removed once the new launcher is written and the settings entry names it — or at once when the status-line slot is not ours (foreign, or empty because the status line is off); kept while a settings file the host reads (this project's local or committed settings, or the user's) still runs it as the status line — a script that calls it indirectly is not seen" });
     if (a.legacy.runtime) cleanup.push({ kind: "rmdir-legacy", path: P.legacy.runtime, why: "the emptied pre-0.28 runtime directory" });
     last.push({ ...base, surface: "layout_cleanup", path: P.legacy.runtime, state: "legacy", action: "cleanup", reason: null, steps: cleanup });
   }
@@ -767,7 +775,7 @@ function applyLayout(p, i, { failed, home = homedir() }) {
         if (text === null) out.steps.push({ kind: st.kind, ok: true, removed: false });
         else if (!moved && slotOurs) out.steps.push({ kind: st.kind, ok: true, removed: false, reason: "no launcher at the new path yet (this root does not produce one) — left in place" });
         else if (!isOurFile(text)) out.steps.push({ kind: st.kind, ok: true, removed: false, reason: "not ours — left in place" });
-        else if (named) out.steps.push({ kind: st.kind, ok: true, removed: false, reason: "the settings entry still names it — left in place" });
+        else if (named) out.steps.push({ kind: st.kind, ok: true, removed: false, reason: "a settings file the host reads still runs it as the status line — left in place" });
         else out.steps.push({ kind: st.kind, ok: true, removed: removeInside(st.path, within) });
       }
       else if (st.kind === "rmdir-legacy") {

package/node_modules/projectstore/scripts/lib.mjs

@@ -318,6 +318,9 @@ export function claudeHome(home = homedir()) {
   return harnessAgentHome(process.env, home);
 }
 
+// The release triple only: 0.28.0-rc.2 and 0.28.0 compare equal. Right for
+// "which release line" (the layout window's sunset); wrong for "which build is
+// newer" — that is cmpPrecedence.
 export function cmpVersion(a, b) {
   const A = String(a || "0").split(".").map((n) => parseInt(n, 10) || 0);
   const B = String(b || "0").split(".").map((n) => parseInt(n, 10) || 0);
@@ -325,6 +328,33 @@ export function cmpVersion(a, b) {
   return 0;
 }
 
+// Semver 2.0 precedence: 0.28.0-rc.2 < 0.28.0-rc.3 < 0.28.0. A registration
+// made at a release candidate read as current against the release while the
+// comparison stopped at the triple, so `upgrade` never refreshed it (the
+// critic's probe, 2026-10-03). Build metadata (`+…`) never ranks.
+export function cmpPrecedence(a, b) {
+  const parse = (v) => {
+    const s = String(v || "0").split("+")[0];
+    const dash = s.indexOf("-");
+    return { core: (dash < 0 ? s : s.slice(0, dash)).split(".").map((n) => parseInt(n, 10) || 0), pre: dash < 0 ? [] : s.slice(dash + 1).split(".") };
+  };
+  const A = parse(a), B = parse(b);
+  for (let i = 0; i < 3; i++) if ((A.core[i] || 0) !== (B.core[i] || 0)) return (A.core[i] || 0) - (B.core[i] || 0);
+  // A release outranks every candidate for it.
+  if (!A.pre.length || !B.pre.length) return B.pre.length - A.pre.length;
+  for (let i = 0; i < Math.max(A.pre.length, B.pre.length); i++) {
+    if (i >= A.pre.length) return -1;
+    if (i >= B.pre.length) return 1;
+    const x = A.pre[i], y = B.pre[i];
+    const nx = /^\d+$/.test(x), ny = /^\d+$/.test(y);
+    if (nx && ny) { if (Number(x) !== Number(y)) return Number(x) - Number(y); continue; }
+    // A numeric identifier ranks below an alphanumeric one.
+    if (nx !== ny) return nx ? -1 : 1;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
 // Where the CURRENTLY installed projectstore lives, per Claude Code's own
 // plugin registry. The cache path carries the version
 // (…/plugins/cache/<marketplace>/projectstore/<version>), so anything that
@@ -863,6 +893,30 @@ export function findAgentsBlock(text) {
   return { present: true, v: Number(m[1]), start: m.index, end, unclosed: false, count, block: text.slice(m.index, end) };
 }
 
+// Whether `text` holds `line` as a line of its own, trimmed and exact — the
+// installer's match for the `@<file>` import, so `@./AGENTS.md` reads as
+// absent to install and doctor alike.
+export function importsLine(text, line) {
+  return String(text ?? "").split("\n").some((l) => l.trim() === line);
+}
+
+// Whether a harness sees the one agents block where it stands — the predicate
+// doctor reports by (the install spec, contract 6 as amended after the rc.3
+// tag). Install's placement rules agree with it: it moves a block whose file
+// is not among the harness's files and bridges one that is, through the same
+// import match (importsLine); a test holds the two to one answer. Visible when
+// the block's file is among the harness's agents_block.files and is either the
+// file it reads by itself or imported from that file. A harness with no agents
+// block has nothing to see it with. `texts` maps a file name to its text; an
+// absent file is undefined.
+export function blockVisibleTo(manifest, file, texts = {}) {
+  const ab = manifest?.surfaces?.agents_block;
+  if (!ab || ab.supported === false) return true;
+  if (!(ab.files || []).includes(file)) return false;
+  const native = ab.reads_natively;
+  return !native || native === file || importsLine(texts[native], `@${file}`);
+}
+
 // Replace the block in place, else append it after the user's own content.
 export function replaceAgentsBlock(text, block) {
   const base = String(text ?? "");

package/node_modules/projectstore/scripts/surfaces.mjs

@@ -47,7 +47,7 @@ import {
   pluginEnabled,
   treeDigest,
   packageDigest,
-  cmpVersion,
+  cmpPrecedence,
   layoutPaths,
   RUNTIME_GITIGNORE_HEADER,
   LAUNCHER_HEADER,
@@ -284,7 +284,7 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
     if (e.projectPath && !samePath(e.projectPath, projectDir)) continue;
     seen.add(e.key); a.others.push({ key: e.key, path: e.path, version: e.version });
   }
-  a.newer = Boolean(a.dir.pkg) && cmpVersion(a.dir.pkg, pkg) > 0;
+  a.newer = Boolean(a.dir.pkg) && cmpPrecedence(a.dir.pkg, pkg) > 0;
   // Same version, different payload: the directory's recorded digest against
   // this package's — contract 4's rung 3 (source changed) for a directory.
   a.contentDiffers = null;
@@ -307,7 +307,7 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
   // The directory is shared by every checkout on the machine; a project that never registered is absent, whatever the directory holds.
   if (nothingOfOursHere) return { ...a, state: "absent", reason: a.dir.present ? `the marketplace directory is present${a.writtenBy ? ` (written from ${a.writtenBy})` : ""}; this checkout is not registered` : null };
   if (!a.dir.present) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + " (the directory is gone)" };
-  if (cmpVersion(a.dir.pkg, pkg) < 0) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (directory at ${a.dir.pkg}, package at ${pkg})` };
+  if (cmpPrecedence(a.dir.pkg, pkg) < 0) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (directory at ${a.dir.pkg}, package at ${pkg})` };
   if (a.dir.digestOk === false) return { ...a, state: "stale", reason: "edited by hand or half-written (the payload does not match the digest its manifest carries)" };
   if (a.contentDiffers === true) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (same version ${pkg}, different content — the directory's digest is not this package's)` };
   if (!a.known || !a.registeredHere) return { ...a, state: "stale", reason: STALE_TEXT[STALE.CONFIG] + (a.known ? " (this checkout does not declare the marketplace)" : " (the host does not know the marketplace)") };
@@ -397,6 +397,9 @@ export function surfaceStates(projectDir, { home = homedir(), root = pluginRoot(
         writtenBy: a.writtenBy || null,
         newer: Boolean(a.newer),
         bin: a.bin,
+        // What this registration silenced for the checkout and the checkout
+        // still holds off: exactly the set uninstall re-enables (contract 13).
+        silenced: (a.dir?.disabled || []).filter((k) => (a.disabledHere || []).includes(k)),
       });
       states.push(row);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore-claude",
-  "version": "0.28.0-rc.3",
+  "version": "0.28.1",
   "description": "Installs projectstore for Claude Code from npm: the core pinned and bundled, the harness fixed — npx projectstore-claude install --project \"$PWD\".",
   "keywords": [
     "projectstore",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "projectstore": "=0.28.0-rc.3"
+    "projectstore": "=0.28.1"
   },
   "bundleDependencies": [
     "projectstore"