@jaybeeuu/agent-cortex 2.3.0 → 2.4.1

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 2.4.1
+
+### Patch Changes
+
+- 7a6288b: Align the review REPORT contract on the run-pipeline-stage playbook shape: the review template
+  and the `review-security` skill now emit `OUTCOME: SUCCESS|BLOCKED` with `BLOCKING_ISSUES`,
+  instead of the unparsed `REVIEW_OUTCOME`/`CHANGES_REQUESTED` keys.
+- 58d6627: Make the generated Claude plugin manifest valid: `repository` is always emitted as a string, normalising npm's object form to its `url` (falling back to `directory`, and omitted when neither exists) instead of copying the object through. An object there made Claude Code reject the whole plugin, hiding every skill and agent. The installer now also re-reads `claude plugin list --json` after registering and fails with Claude's validation error when the plugin reports failed to load, instead of reporting success. When that list cannot be read, or does not list the plugin, the installer warns that the load state is unconfirmed and omits its success message.
+- 00fbab3: Record the dev loop in `docs/dev-loop.md`: the three-command refresh of the installed runtime
+  (`pnpm add -g …@latest`, then `agent-cortex install pi` and `agent-cortex install claude`, with
+  `--dry-run` for the plan and a pi restart (or `/reload-plugins` in Claude Code) to apply), the
+  installed layout under `~/.agent-cortex`, and how to try uncommitted work without overwriting it —
+  stage the checkout with `install pi --output <scratch dir>` and load it with `pi -ne -e
+<scratch dir>`, which writes no settings and needs no undo. The page also states the boundary plainly: the checkout is what is
+  developed, `~/.agent-cortex` is what is run, and a path inside `~/src` is never a package source,
+  with the two historical violations named as anti-patterns. `README.md` links it from the pi
+  staging section and the Claude one-session section, and its Claude plugin section now states the
+  correct skill count (34, not 29).
+- dda3a31: `agent-cortex install pi` now reports the two ways a machine ends up in a mixed state, instead of
+  leaving them to surface later as missing tools or conflict errors.
+
+  A configured package source whose path no longer exists is named with the command that drops it.
+  Detection is an existence check, so it no longer depends on reading the source `package.json` —
+  which is exactly what failed on a pruned worktree path, letting the entry survive a whole install
+  and every `pi remove` afterwards. The report gives `pi remove <resolved path>`: pi matches a local
+  source by resolved path, and a relative argument resolves against the current directory rather
+  than the settings file, so the obvious `pi remove <as configured>` misses. The installer does not
+  remove the entry itself — a missing path may be temporarily absent.
+
+  A pi package the staged package bundles and the user also registers standalone is reported with
+  both copies, the copy that takes precedence (load order decides, and on pi 1.x the first-listed
+  source wins), and the `pi remove` command that resolves it. The staged package always ships its own copy, so the
+  standalone entry is the one to drop; the installer does not remove packages the user configured.
+
+  `LEGACY_ORPHAN_SKILLS` no longer lists `productivity/migration`: it ships again, so the package root
+  attributes its copy, and the entry now follows its own instruction to be dropped once that holds.
+
+## 2.4.0
+
+### Minor Changes
+
+- 0b72348: The extensions now load outside this checkout. `auto-name`, `notify`, `subagent` and `agent-modes`
+  value-imported `@earendil-works/pi-*`, which resolved only inside the repository, where pnpm had
+  installed each extension's own copy of pi's packages. The staged pi package carried no such
+  `node_modules`, so after `agent-cortex install pi` those four extensions failed to load for every
+  project outside this checkout — `subagent` included, which is the dispatcher ralph uses.
+
+  The runtime coupling is gone: frontmatter parsing, pi's user agent directory, the key helper and the
+  transcript components are now local, and the extensions declare no peer dependency on pi's packages. Two
+  callers lose their model-backed behaviour, since an extension has no completion API of its own:
+  `auto-name` names a session from its first prompt truncated (the fallback it already had) and
+  `notify` summarises with that same truncation. Subagent output renders as plain text instead of
+  markdown.
+
+  One bare runtime import remains: `typebox`. pi documents it as a host-provided module for
+  extensions and aliases it in its loader, so it resolves in the staged package. Everything imported
+  from `@earendil-works/*` is `import type`, which is erased. `test/pi-extensions-load.test.mjs`
+  stages the package and loads every extension from a temp directory with pi absent. A static scan in
+  the same file then rejects any value import from `@earendil-works/*` — including an unused one, which
+  tsx elides before the loader sees it.
+
 ## 2.3.0
 
 ### Minor Changes

package/README.md

@@ -75,7 +75,10 @@ temp-dir install plus structural checks:
 - **Manifests** are generated too: the plugin's `.claude-plugin/plugin.json` (its `version`
   tracks `package.json`, so it never goes stale) and `hooks.json` (copied from the canonical
   `hooks/claude/hooks.json` source), plus any support files under `hooks/claude/` bundled into
-  the plugin's `hooks/` so hook commands can reach them via `$CLAUDE_PLUGIN_ROOT`. Hand-authored
+  the plugin's `hooks/` so hook commands can reach them via `$CLAUDE_PLUGIN_ROOT`. Its
+  `repository` is always a string: `package.json`'s object form is reduced to its `url`, then
+  its `directory`, and dropped when neither exists. Claude rejects any other shape and drops
+  the whole plugin — every skill and agent in it — with that one field. Hand-authored
   extras — `.mcp.json` and `scripts/` — are copied into every install from the `claude-extras/`
   dir, which is their canonical store. See `docs/claude-hooks.md` for the
   extension→hook mapping and the rejections (auto-name, agent-guardrails, skill-stats, subagent, agent-modes).
@@ -201,7 +204,7 @@ The staged package contains:
 | `package.json` | pi manifest — `keywords: ["pi-package"]`, `pi.extensions` + `pi.skills`; the version tracks the package |
 | `agents/` | composed flat agents (ralph, plan, ralph-plan, strategy) with `{{TOOL:...}}` / `{{PATH:...}}` substituted — the shipped `agent-modes` extension resolves them from the package root |
 | `skills/` | token-substituted skill copies (real files, never symlinks) |
-| `extensions/` | copy of the repo `extensions/` tree |
+| `extensions/` | copy of the repo `extensions/` tree — imports nothing from pi's runtime except the host-aliased `typebox`, so pi loads it from any directory |
 | `token-map.json` | the token map `agent-modes` reads from the package root |
 | `node_modules/` | the required third-party pi packages and their transitive closure |
 
@@ -229,10 +232,19 @@ A superseded raw-repo source that `pi remove` cannot drop fails the install
 reporting success would leave the two-source state registration exists to
 prevent. Nothing is installed on that path — remove the source by hand and re-run.
 
+A source whose path no longer exists, and a package the staged bundle ships that
+you also registered standalone, are reported and left configured: the installer
+never removes an entry you added. Each report gives the `pi remove` command that
+resolves it, with the resolved path, because `pi remove` resolves a relative
+argument against the current directory.
+
 Re-run `agent-cortex install pi` after every `git pull` to refresh the staged
 package; registration is already in place, so that re-run changes nothing in
 pi's settings. Verify with `pi list` and `pi config` (restart pi to apply).
 
+Refreshing the installed runtime after a release, and trying uncommitted work without
+overwriting it, are recorded in [`docs/dev-loop.md`](docs/dev-loop.md).
+
 ### Desktop notifications
 
 Desktop notifications are handled by the local `extensions/notify/` extension
@@ -270,7 +282,7 @@ instructions file, leaving the rest of that file — and a `.bak` copy — intac
 
 A plain `agent-cortex install claude` **materialises** the plugin into the home install
 root `~/.agent-cortex/claude` — **4 agents** (`strategy`, `plan`, `ralph-plan`, `ralph`),
-**29 skills** (copied flat per skill, `{{TOOL:...}}` / `{{PATH:...}}` token-substituted — no
+**34 skills** (copied flat per skill, `{{TOOL:...}}` / `{{PATH:...}}` token-substituted — no
 symlinks), `SessionStart` + `Notification` hooks, and 2 MCP servers — writes a marketplace
 manifest at `~/.agent-cortex/.claude-plugin/marketplace.json` exposing `./claude`, and
 registers it with Claude Code, and merges the committed `claude/settings.json` template into
@@ -306,8 +318,11 @@ claude --plugin-dir /tmp/agent-cortex-claude
 claude --plugin-dir /tmp/agent-cortex-claude plugin details agent-cortex
 ```
 
-`SKILL.md` edits are picked up live in that session; agent, hook, and MCP changes need
-`/reload-plugins`.
+Edits to the generated copy of a `SKILL.md` are picked up live; re-run the generator after
+editing the checkout. Agent, hook, and MCP changes need `/reload-plugins`.
+
+Trying uncommitted work without overwriting the installed runtime is recorded in
+[`docs/dev-loop.md`](docs/dev-loop.md).
 
 #### Install persistently (recommended)
 
@@ -321,7 +336,11 @@ exit code: `claude plugin marketplace list --json` picks add-vs-update and
 `claude plugin list --json` picks install-vs-update against the materialised version. A
 fresh install adds the marketplace and installs the plugin; a re-run is the update path
 (`marketplace update`, plus `plugin update` only when a newer version is materialised); a
-repeat install at the same version is a true no-op. It requires the `claude` plugin CLI
+repeat install at the same version is a true no-op. Those commands exit 0 on a manifest Claude
+rejects, so the installer re-reads `claude plugin list --json` after they run. A plugin that
+list reports as failed to load fails the install with Claude's validation message. A list the
+installer cannot read, or one that omits the plugin, warns that the load state is unconfirmed
+and prints no success line. It requires the `claude` plugin CLI
 (Claude Code v2+): with a missing or pre-v2 CLI the installer warns and prints the manual
 commands below, exiting 0 — `--require-register` makes registration mandatory and fails
 non-zero when it can't run:

package/bin/installers/claude.mjs

@@ -52,7 +52,12 @@
 // re-run is the update path, and a repeat install at the same version is a
 // true no-op. If the `claude` CLI is missing or predates the plugin subcommand
 // (v2+), the installer warns and prints the manual registration commands,
-// exiting non-zero only with --require-register.
+// exiting non-zero only with --require-register. After the commands run,
+// `claude plugin list --json` is re-read: a plugin Claude Code reports as failed
+// to load fails the install with its validation error, because those commands
+// exit 0 on a manifest they reject. When that list cannot be read, or omits the
+// plugin, the load state is unconfirmed and the installer warns instead of
+// claiming success.
 //
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
@@ -253,6 +258,26 @@ async function copyTree(src, dest, transform, dryRun) {
   return { md, files };
 }
 
+/**
+ * Normalise package.json's `repository` field into the string Claude Code's
+ * plugin manifest requires. npm permits a string or an object
+ * (`{ type, url, directory }`); Claude rejects anything but a string, and one
+ * invalid manifest makes the whole plugin fail to load, so the object form must
+ * never be copied through. Prefer `url`, fall back to `directory`, and omit the
+ * field when neither is usable rather than emitting junk.
+ * @param {unknown} repository  parsed package.json `repository` value
+ * @returns {string | undefined}
+ */
+function normaliseRepository(repository) {
+  if (typeof repository === "string") return repository.trim() === "" ? undefined : repository;
+  if (repository === null || typeof repository !== "object") return undefined;
+  const { url, directory } = /** @type {{ url?: unknown, directory?: unknown }} */ (repository);
+  for (const candidate of [url, directory]) {
+    if (typeof candidate === "string" && candidate.trim() !== "") return candidate;
+  }
+  return undefined;
+}
+
 /**
  * plugin.json manifest; version tracks the package so it can never go stale.
  * @param {string} root
@@ -268,7 +293,9 @@ async function buildPluginJson(root) {
         description: "Personal Claude Code plugin with custom agents and skills",
         author: { name: "jaybeeuu" },
         license: pkg.license ?? "MIT",
-        repository: pkg.repository,
+        // JSON.stringify drops an undefined value, so an unusable repository
+        // is omitted instead of emitted as junk.
+        repository: normaliseRepository(pkg.repository),
         hooks: "./hooks.json",
       },
       null,
@@ -940,6 +967,50 @@ async function installedPluginVersion(claudeBin, pluginId) {
   }
 }
 
+/**
+ * Verdict of `claude plugin list --json` on whether `pluginId` actually loads.
+ * An entry carries `errors` when the materialised manifest could not be loaded
+ * (the CLI then also reports version "unknown") — a broken plugin that every
+ * install command still exits 0 on. Unreadable or unexpected output yields
+ * `unknown`, and a readable list that omits the plugin yields `not-listed`:
+ * both are no verdict, never a false failure.
+ * @typedef {{ verdict: "unknown" } | { verdict: "not-listed" } | { verdict: "loaded" } | { verdict: "failed", errors: string[] }} PluginLoadVerdict
+ */
+
+/**
+ * The string members of `values`, in order.
+ * @param {unknown[]} values
+ * @returns {string[]}
+ */
+function stringValues(values) {
+  /** @type {string[]} */
+  const strings = [];
+  for (const value of values) if (typeof value === "string") strings.push(value);
+  return strings;
+}
+
+/**
+ * @param {string} claudeBin
+ * @param {string} pluginId
+ * @returns {Promise<PluginLoadVerdict>}
+ */
+async function pluginLoadVerdict(claudeBin, pluginId) {
+  const out = await queryClaudeCommand(claudeBin, ["plugin", "list", "--json"]);
+  if (out == null) return { verdict: "unknown" };
+  /** @type {any} */
+  let entries;
+  try {
+    entries = JSON.parse(out.trim() || "[]");
+  } catch {
+    return { verdict: "unknown" };
+  }
+  if (!Array.isArray(entries)) return { verdict: "unknown" };
+  const entry = entries.find((/** @type {any} */ e) => e?.id === pluginId);
+  if (entry === undefined) return { verdict: "not-listed" };
+  const errors = Array.isArray(entry.errors) ? stringValues(/** @type {unknown[]} */ (entry.errors)) : [];
+  return errors.length > 0 ? { verdict: "failed", errors } : { verdict: "loaded" };
+}
+
 /**
  * Register the materialised plugin with Claude Code by driving the `claude
  * plugin` CLI against the home install root as the marketplace source.
@@ -967,6 +1038,13 @@ async function installedPluginVersion(claudeBin, pluginId) {
  * `requireRegister` is set — the default is warn-only because the plugin is
  * already materialised by then; the file side of the install succeeded.
  *
+ * A plugin that `claude plugin list --json` reports as failed to load is never
+ * reported as a success: the plugin commands exit 0 on an invalid manifest, so
+ * the run throws with Claude's validation error (which names the manifest)
+ * rather than leaving every skill and agent in the plugin silently unavailable.
+ * When that list cannot be read, or does not list the plugin, the load state is
+ * unconfirmed: the install warns and skips the success line.
+ *
  * @param {object} options
  * @param {string} [options.root]            Marketplace root carrying .claude-plugin/…
  *                                           (defaults to the repo containing this module)
@@ -1054,8 +1132,33 @@ export async function registerClaude({
     console.log(`  ${claudeBin} ${args.join(" ")}`);
     await runClaudeCommand(claudeBin, args);
   }
-  console.log(
-    `Installed — verify with "claude plugin list" / "claude plugin details ${plugin}" (restart Claude Code to apply).`,
-  );
+  // The commands exiting 0 does not mean the plugin loads: a manifest Claude
+  // rejects still installs and updates cleanly. Claiming success there would
+  // hide that every skill and agent in the plugin is unavailable.
+  const load = await pluginLoadVerdict(claudeBin, pluginId);
+  if (load.verdict === "failed") {
+    throw new Error(
+      `plugin "${pluginId}" is installed but Claude Code reports it as failed to load: ${load.errors.join("; ")} — ` +
+        `every skill and agent in the plugin stays unavailable until the manifest loads; fix it and re-run`,
+    );
+  }
+  // No verdict is not a success either: an unreadable list or a list that omits
+  // the plugin leaves its load state unconfirmed, so warn instead of claiming
+  // the plugin is installed and working.
+  if (load.verdict === "unknown") {
+    warn(
+      `could not read "${claudeBin} plugin list --json", so the plugin's load state is unconfirmed — ` +
+        `verify with "${claudeBin} plugin list" (restart Claude Code to apply)`,
+    );
+  } else if (load.verdict === "not-listed") {
+    warn(
+      `"${pluginId}" is not in "${claudeBin} plugin list --json" after registration, so it may not have registered — ` +
+        `verify with "${claudeBin} plugin list" (restart Claude Code to apply)`,
+    );
+  } else {
+    console.log(
+      `Installed — verify with "claude plugin list" / "claude plugin details ${plugin}" (restart Claude Code to apply).`,
+    );
+  }
   return summary;
 }

package/bin/installers/pi.mjs

@@ -59,8 +59,12 @@
 // pi's own user settings (settings.json, keybindings.json) are NOT written by
 // the installer: they are pi's config, not the package's, and `pi install` is
 // the command that owns them. They are READ (never written) to decide
-// install-vs-no-op and to find stale raw-repo sources; the committed pi/*.json
-// templates remain reference copies.
+// install-vs-no-op, to find stale raw-repo sources, and to report two states
+// the installer cannot resolve on its own: a configured source whose path no
+// longer exists (it cannot be identified, so only `pi remove <resolved path>`
+// can drop it), and a package the user also registers standalone that the
+// staged package bundles (both copies load, and their tools collide). The
+// committed pi/*.json templates remain reference copies.
 //
 // LEGACY SWEEP (sweepLegacyPiUserDirs): the pre-staged-model installer rendered
 // agents and skills into pi's own user directory (~/.pi/agent). Those copies are
@@ -198,13 +202,14 @@ const DEFAULT_WARN = (/** @type {string} */ msg) => console.warn(`[pi-installer]
 
 // Artifacts the pre-staged-model installer wrote into pi's own user directory
 // that the package root can no longer name on its own: the orphaned
-// `pipeline-worker` agent (an older render with no canonical source today) and
-// the `migration` skill (authored on a branch this epic does not carry).
+// `pipeline-worker` agent (an older render with no canonical source today).
 // Everything else is attributed from the package root — see
 // sweepLegacyPiUserDirs. Drop an entry once it is either shipped again (the
-// root-derived rules then cover it) or gone for good.
+// root-derived rules then cover it) or gone for good; `productivity/migration`
+// was dropped that way once the skill shipped again.
 const LEGACY_ORPHAN_AGENTS = ["pipeline-worker"];
-const LEGACY_ORPHAN_SKILLS = ["productivity/migration"];
+/** @type {string[]} Skills an older render shipped under a name the root no longer has. */
+const LEGACY_ORPHAN_SKILLS = [];
 
 // A path record some install flows leave in pi's user directory, listing the
 // copies they wrote there. It describes the same tree the sweep removes, so it
@@ -405,10 +410,13 @@ async function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, wa
 /**
  * Copy the repo's extensions/ tree into the staged package verbatim.
  *
- * The extensions import `@earendil-works/*`, which pi's loader supplies, so no
- * dependency tree is needed. `node_modules` (pnpm workspace links) and symlinks
- * are never copied: the staged package owns its dependencies and must contain
- * real files only.
+ * The extensions import nothing from pi's runtime — only `import type`, which is
+ * erased, and the one module pi documents as host-provided (`typebox`) — so no
+ * dependency tree of their own is needed. A value import of `@earendil-works/*`
+ * would only resolve where pnpm installed it and would break the staged package
+ * everywhere else, which test/pi-extensions-load.test.mjs guards. `node_modules`
+ * (pnpm workspace links) and symlinks are never copied: the staged package owns
+ * its dependencies and must contain real files only.
  * @param {{ root: string, output: string, dryRun: boolean }} options
  * @returns {Promise<{ files: number, dir: string }>}
  */
@@ -579,6 +587,11 @@ async function readDependencyNames(dir) {
  *     `git pull && agent-cortex install pi` is a true no-op)
  *   a source resolves to a raw agent-cortex checkout (this package's own name)
  *     → `pi remove` it first, so exactly one agent-cortex source stays
+ *   a local source whose path does not exist → reported with the command that
+ *     drops it (see reportDanglingSources)
+ *   a package the staged package bundles is also configured standalone →
+ *     reported with the copy that wins and the command that resolves it (see
+ *     reportBundledCollisions)
  *
  * A superseded source that survives its removal fails the run: pi would load
  * both sources side by side, so reporting success would leave the very state
@@ -612,7 +625,19 @@ export async function registerPi({
   const stagedPath = resolve(output);
   const rawPackageName = (await readJsonObject(join(root, "package.json")))?.name;
   const sources = await readConfiguredPackages(settingsPath);
-  const { registered, stale } = await classifySources({ sources, settingsPath, stagedPath, rawPackageName });
+  const { registered, stale, dangling } = await classifySources({ sources, settingsPath, stagedPath, rawPackageName });
+
+  // Both reports describe state this installer must not change on its own — a
+  // source it cannot identify, and a source the user configured deliberately —
+  // so they are reported on every path, including the no-op and dry-run ones.
+  reportDanglingSources(dangling, settingsPath, warn);
+  await reportBundledCollisions({
+    sources,
+    settingsPath,
+    stagedPath,
+    bundledPackages: await readBundledPackages(stagedPath),
+    warn,
+  });
 
   // The same sequence a human would run by hand, in the order the installer
   // runs it: drop the superseded sources, then register the staged package.
@@ -625,7 +650,7 @@ export async function registerPi({
   console.log(`Registering the staged pi package with pi (via ${piBin})…`);
 
   if (dryRun) {
-    console.log(`  would read: ${settingsPath} (install-vs-no-op and stale raw-repo sources)`);
+    console.log(`  would read: ${settingsPath} (install-vs-no-op, stale raw-repo sources, unusable sources)`);
     for (const { path } of stale) console.log(`  would run: ${piBin} remove ${path}`);
     if (registered) console.log(`  already configured: ${stagedPath}`);
     else console.log(`  would run: ${piBin} install ${stagedPath}`);
@@ -736,17 +761,23 @@ function resolveSourcePath(source, settingsDir) {
 
 /**
  * Split the configured local sources into "the staged package is already
- * registered" and "a raw agent-cortex checkout superseded by it". A source
- * whose directory is gone is left alone: a missing path cannot be told apart
- * from a temporarily absent one, and removing it could drop a package the user
- * still wants.
+ * registered", "a raw agent-cortex checkout superseded by it", and "a source
+ * whose path is not there".
+ *
+ * The third group is reported, never acted on: a missing path cannot be told
+ * apart from a temporarily absent one, and removing it could drop a package the
+ * user still wants. It also cannot be identified by name — reading the source
+ * package.json to recognise a raw agent-cortex checkout fails on a path that is
+ * not there — which is how such an entry survived a whole install unnoticed.
  * @param {{ sources: string[], settingsPath: string, stagedPath: string, rawPackageName: string | undefined }} options
- * @returns {Promise<{ registered: boolean, stale: { path: string }[] }>}
+ * @returns {Promise<{ registered: boolean, stale: { path: string }[], dangling: { source: string, path: string }[] }>}
  */
 async function classifySources({ sources, settingsPath, stagedPath, rawPackageName }) {
   const settingsDir = dirname(settingsPath);
   /** @type {{ path: string }[]} */
   const stale = [];
+  /** @type {{ source: string, path: string }[]} */
+  const dangling = [];
   let registered = false;
   for (const source of sources) {
     if (!isLocalSource(source)) continue;
@@ -755,10 +786,137 @@ async function classifySources({ sources, settingsPath, stagedPath, rawPackageNa
       registered = true;
       continue;
     }
+    // A local source may also be a single extension file, so absence means
+    // neither a directory nor a file is there.
+    if (!(await isDirectory(path)) && !(await isFile(path))) {
+      dangling.push({ source, path });
+      continue;
+    }
     if (rawPackageName === undefined) continue;
     if ((await readJsonObject(join(path, "package.json")))?.name === rawPackageName) stale.push({ path });
   }
-  return { registered, stale };
+  return { registered, stale, dangling };
+}
+
+/**
+ * Report a configured local source whose path does not exist, with the command
+ * that drops it.
+ *
+ * The source is named twice — as configured and as its resolved path — because
+ * pi matches a local source by its resolved path: a relative `pi remove`
+ * argument resolves against the CURRENT directory, not against the directory
+ * holding settings.json (pi 1.x, probed against 1.4.0), so the obvious
+ * `pi remove <as configured>` misses from anywhere else and leaves the entry
+ * stuck.
+ * @param {{ source: string, path: string }[]} dangling
+ * @param {string} settingsPath
+ * @param {Warn} warn
+ */
+function reportDanglingSources(dangling, settingsPath, warn) {
+  for (const { source, path } of dangling) {
+    warn(
+      `pi package source "${source}" cannot be identified: ${path} does not exist. ` +
+        `pi loads nothing from it and still lists it, so everything it was registered for is missing. ` +
+        `It is left configured in ${settingsPath} — a missing path may be temporarily absent. ` +
+        `Drop it with:\n  pi remove ${path}\n` +
+        `(pass the resolved path: pi 1.x resolves a relative remove argument against the current directory, not ${settingsPath})`,
+    );
+  }
+}
+
+/**
+ * Names of the third-party pi packages the staged package ships its own copy
+ * of, read from its generated manifest.
+ *
+ * Bundling stamps one `node_modules/<name>/…` resource path per package that
+ * ships pi resources (see resolvePiPackages), so the manifest names exactly the
+ * set that can load a second time beside a standalone registration. A package
+ * without a `pi` manifest key is only a module and cannot collide.
+ * @param {string} stagedPath
+ * @returns {Promise<string[]>}
+ */
+async function readBundledPackages(stagedPath) {
+  const manifest = await readJsonObject(join(stagedPath, "package.json"));
+  if (manifest === null) return [];
+  /** @type {Set<string>} */
+  const names = new Set();
+  for (const resource of [...asStringList(manifest.pi?.extensions), ...asStringList(manifest.pi?.skills)]) {
+    const match = /^node_modules\/((?:@[^/]+\/)?[^/]+)\//.exec(resource);
+    if (match !== null) names.add(match[1]);
+  }
+  return [...names];
+}
+
+/**
+ * Report every pi package the staged package bundles that the user also
+ * registers standalone.
+ *
+ * Staging copies each third-party pi package under the staged node_modules, so
+ * a standalone registration of the same package loads a second copy: pi keeps
+ * both — precedence follows load order on pi 1.x — and reports the overlap as
+ * tool-name, shortcut, and skill conflicts at startup, long after the install
+ * said it succeeded. The installer cannot drop the standalone entry (it is
+ * the user's configuration) and must not drop the bundle, so it says which
+ * copy wins and which command resolves it.
+ * @param {{ sources: string[], settingsPath: string, stagedPath: string,
+ *           bundledPackages: string[], warn: Warn }} options
+ * @returns {Promise<void>}
+ */
+async function reportBundledCollisions({ sources, settingsPath, stagedPath, bundledPackages, warn }) {
+  if (bundledPackages.length === 0) return;
+  const settingsDir = dirname(settingsPath);
+  const bundled = new Set(bundledPackages);
+  // pi 1.x loads configured sources in order, so the first one listed wins a
+  // shared tool name (probed against pi 1.4.0 — pi's behaviour, not a contract,
+  // so the message dates the claim); `-1` means the staged package is not
+  // configured at all, and `pi install` appends, so a standalone entry stays
+  // listed first.
+  const stagedIndex = sources.findIndex((source) => isLocalSource(source) && resolveSourcePath(source, settingsDir) === stagedPath);
+  for (const [index, source] of sources.entries()) {
+    const local = isLocalSource(source);
+    const path = local ? resolveSourcePath(source, settingsDir) : undefined;
+    if (path === stagedPath) continue;
+    const name = await configuredPackageName(source, settingsDir);
+    if (name === undefined || !bundled.has(name)) continue;
+
+    const bundledDir = join(stagedPath, "node_modules", name);
+    const standalone = path ?? source;
+    const winner =
+      stagedIndex === -1 || index < stagedIndex
+        ? `${standalone} takes precedence because it is listed first in ${settingsPath}`
+        : `the bundled copy at ${bundledDir} takes precedence because ${settingsPath} lists the staged package first`;
+    warn(
+      `pi loads "${name}" twice: standalone from ${standalone}, and bundled at ${bundledDir}. ` +
+        `The copies collide on tool names, extension shortcuts, and skills; on pi 1.x ${winner}. ` +
+        `The staged package always ships its own copy, so drop the standalone one with:\n` +
+        `  pi remove ${standalone}`,
+    );
+  }
+}
+
+/**
+ * The package name a configured source registers, or `undefined` when the
+ * installer cannot name it: an `npm:` spec by its name, a local source by the
+ * `name` in its package.json.
+ * @param {string} source
+ * @param {string} settingsDir
+ * @returns {Promise<string | undefined>}
+ */
+async function configuredPackageName(source, settingsDir) {
+  if (source.trim().startsWith("npm:")) return npmPackageName(source);
+  if (!isLocalSource(source)) return undefined;
+  return (await readJsonObject(join(resolveSourcePath(source, settingsDir), "package.json")))?.name;
+}
+
+/**
+ * `npm:@scope/name@^1.2.3` → `@scope/name`.
+ * @param {string} source
+ * @returns {string}
+ */
+function npmPackageName(source) {
+  const spec = source.trim().slice("npm:".length).trim();
+  const at = spec.indexOf("@", spec.startsWith("@") ? 1 : 0);
+  return at === -1 ? spec : spec.slice(0, at);
 }
 
 /**

package/extensions/agent-guardrails/package.json

@@ -12,8 +12,5 @@
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1"
   }
 }

package/extensions/agent-modes/index.ts

@@ -23,7 +23,6 @@
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Key } from "@earendil-works/pi-tui";
 import { discoverAgents, DEFAULT_TOOLS, type AgentDef } from "./discover.ts";
 import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 
@@ -196,8 +195,10 @@ export default function agentModesExtension(pi: ExtensionAPI): void {
       },
     });
 
-    // Ctrl+Shift+A to cycle agents (A = Agent)
-    pi.registerShortcut(Key.ctrlShift("a"), {
+    // Ctrl+Shift+A to cycle agents (A = Agent). Spelled out rather than built
+    // with pi-tui's Key helper: a value import of pi-tui stops the extension
+    // loading outside the agent-cortex checkout (test/pi-extensions-load.test.mjs).
+    pi.registerShortcut("ctrl+shift+a", {
       description: "Next agent mode",
       handler: async (ctx) => {
         const next = (activeAgentIndex + 1) % (agents.length + 1);

package/extensions/agent-modes/package.json

@@ -9,12 +9,8 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.78.1",
-    "@earendil-works/pi-tui": "^0.78.1",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1"
   }
-}
+}