@jaybeeuu/agent-cortex 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 2.4.2
+
+### Patch Changes
+
+- 015ede5: Stop the Claude install from dropping `{{TOOL:read_agent}}` and `{{TOOL:wait_for_agents}}`
+  into dangling prose. Both tokens are null on the claude column (Claude reports a subagent's
+  result inline, so there is no separate read or wait step), so the installer replaced them with
+  an empty string and warned three times — leaving `Read the completed agent's output with  and
+parse…` and two similar broken sentences in the installed `ralph` and `design-an-interface`
+  skills. Those sentences are now harness-neutral, so both installs read correctly and the
+  installer emits no null-mapping warning. A regression guard fails the installer test if a
+  shipped skill names a tool the claude column cannot map.
+- 199cefe: Point the shipped pi settings at models that still exist. `tinyModel.model` was
+  `opencode/mimo-v2.5-free`, which the provider catalogue has dropped, so the
+  setting resolved to nothing and pi fell back to another free model. That fallback
+  returns `429 FreeUsageLimitError` once the free quota is spent, and the 429 JSON
+  became the entire output of the background call that runs auto-naming and
+  notifications — so a subagent run died at session start while the agent itself was
+  on a paid model. `tinyModel.model` is now `opencode-go/deepseek-v4.1-flash`.
+  `enabledModels` also drops three ids that do not resolve — `opencode-go/deepseek-v4-flash`,
+  `opencode/deepseek-v4-flash` and `opencode/mimo-v2.5-free` — which made pi print a
+  `No models match pattern` warning on every startup.
+- 6b6080b: Stop the test suite from leaking temp workspaces into `/tmp`. Each test file that
+  creates workspaces under the system temp dir now shares one temp root that a
+  file-level `after()` hook removes, so the removal happens whether the tests
+  passed, failed, or threw before reaching their own cleanup — previously a single
+  green run of `test/installer.test.mjs` left 21 workspaces behind (7.4 MB apparent,
+  13 MB on disk: each is a materialised plugin tree of skills, agents and hooks),
+  plus one from `test/cli.test.mjs`'s `install claude --output` case. Repeated runs
+  could fill a small tmpfs and make unrelated tests fail with ENOSPC. A regression
+  guard runs a deliberately failing test file and asserts the run leaves nothing
+  behind.
+
+## 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

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).
@@ -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
@@ -582,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
@@ -615,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.
@@ -628,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}`);
@@ -739,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;
@@ -758,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"

package/skills/engineering/design-an-interface/SKILL.md

@@ -55,7 +55,7 @@ description: "Generate multiple radically different interface designs for a modu
    4. Trade-offs of this approach
    ```
 
-   Collect each agent's output with {{TOOL:read_agent}} when it finishes.
+   Collect each agent's output as it finishes.
 
 3. **Present designs.** Show each design sequentially — signature, usage examples, what it hides — so the user absorbs each approach before any comparison happens.
 

package/skills/planning/create-task/templates/review.md

@@ -16,21 +16,26 @@ Log stage start, security scan result, review outcome, and stage complete (see P
 
 ## Instructions
 **First**, invoke the `review-security` skill and run the scan against the changes. If the
-verdict is FAIL, set `REVIEW_OUTCOME: CHANGES_REQUESTED` immediately and list each finding
-as a required change — do not proceed with the quality review.
+verdict is FAIL, set `OUTCOME: BLOCKED` immediately and list each finding under
+`BLOCKING_ISSUES` — do not proceed with the quality review.
 
 **Then**, review the implementation for correctness, quality, and alignment with the task
 description and project conventions. Only flag genuine correctness issues or clear deviations
 from stated requirements — not stylistic preferences.
 
-End your response with a ---REPORT--- block:
+End your response with a ---REPORT--- block. The `run-pipeline-stage` skill's
+`prompts/stage-runner.md` holds the authoritative REPORT contract — if this block and that
+prompt differ, follow the prompt and correct this template.
 ---REPORT---
 BEAD_ID: <id>
-STAGE_COMPLETED: reviewing
+STAGE_COMPLETED: review
 SUMMARY: <2–3 sentence summary of what you reviewed>
 FILES_CHANGED: none
-REVIEW_OUTCOME: <APPROVED|CHANGES_REQUESTED>
-CHANGES_REQUESTED:       ← include only if REVIEW_OUTCOME is CHANGES_REQUESTED
-1. <required change>
-2. <required change>
+COMMIT: <sha, or "none" if this stage added no commit>
+PUSHED: <yes|no>
+PR: none
+OUTCOME: <SUCCESS|BLOCKED>
+BLOCKING_ISSUES:         ← include only if OUTCOME is BLOCKED; one numbered line per finding
+1. <path:line — what is wrong and what to fix>
+2. <path:line — what is wrong and what to fix>
 ---

package/skills/review/review-security/SKILL.md

@@ -54,7 +54,10 @@ bash "$(find ~ -path '*/agent-cortex/skills/review-security/scripts/install-gitl
 
 If the verdict is FAIL, report each finding as a required change. Do not proceed until secrets are removed.
 
-When running within a ralph review pipeline, the outcome is communicated through the `---REPORT---` block that ralph parses — set `REVIEW_OUTCOME: CHANGES_REQUESTED` in that block and list each finding under `CHANGES_REQUESTED` (see the review template at `skills/create-task/templates/review.md`).
+When running within a ralph review pipeline, the outcome is communicated through the
+`---REPORT---` block that ralph parses — set `OUTCOME: BLOCKED` in that block and list each
+finding under `BLOCKING_ISSUES` with its file and line (see the review template in the
+`create-task` skill's `templates/review.md`).
 
 ## Red Flags
 

package/skills/workflow/ralph/SKILL.md

@@ -41,7 +41,7 @@ State model: task state lives in beads (ready/in_progress via `bd`); the only lo
    - **Bead that already has its children** (a decomposed feature, an expanded task parent): skip it — it is not dispatchable itself, and its `stage:*` chore is dispatched on its own.
    `execution:hitl` beads are not in this query and are not ralph's to touch: record them for the Pending Human Action summary. That includes every feature still at its default `execution:hitl` label.
 7. Dispatch each unit from its parent's worktree, up to 5 in flight: a stage chore via the event loop, a childless feature via a decomposition worker (_Feature decomposition_), a chore-less task via an expansion worker (_Expansion guard_). Create branches and worktrees first (REFERENCE.md, _Feature Branches and Worktrees_).
-8. Hand over to your harness's completion-detection mechanism: PI keeps a {{TOOL:wait_for_agents}} call outstanding over every in-flight agent ID, and Claude re-invokes you as each worker completes. If no **agent work** was dispatched — `state.json`'s `inflight` holds no entries, so no stage, decomposition or expansion worker is running — and `skills/workflow/ralph/scripts/pending-gates.mjs` reports a non-empty `pendingHumanAction` (an unblocked `lifecycle:feature-pr` gate, or an epic tagged `awaiting-epic-pr-merge`), go straight to HITL Pause (REFERENCE.md). A decomposition- or expansion-only init is in flight, not idle: keep the completion mechanism running and continue at the event loop.
+8. Hand over to your harness's completion-detection mechanism: PI keeps a blocking wait outstanding over every in-flight agent ID, and Claude re-invokes you as each worker completes. If no **agent work** was dispatched — `state.json`'s `inflight` holds no entries, so no stage, decomposition or expansion worker is running — and `skills/workflow/ralph/scripts/pending-gates.mjs` reports a non-empty `pendingHumanAction` (an unblocked `lifecycle:feature-pr` gate, or an epic tagged `awaiting-epic-pr-merge`), go straight to HITL Pause (REFERENCE.md). A decomposition- or expansion-only init is in flight, not idle: keep the completion mechanism running and continue at the event loop.
 
 ### 2. Expansion guard (stage chores are pre-created)
 
@@ -60,7 +60,7 @@ A feature carries `execution:hitl` by default, so this only runs when a human ha
 On each completion notification (a background agent finished):
 
 1. Poll that parent's log for new lines — `tail -n +<nextLine> .agent-cortex/ralph/ralph-<parent-id>.log` (logs are keyed by parent bead ID, so every stage of a feature shares one file) — and post only new key events (stage transitions, test/lint results), never empty updates.
-2. Read the completed agent's output with {{TOOL:read_agent}} and parse its `---REPORT---` block for `BEAD_ID`, `STAGE_COMPLETED`, and the outcome. A **decomposition** (`kind: "decompose"`) or **expansion** (`kind: "expand"`) worker has no REPORT and no leaf bead to confirm. An **expansion worker** owns no bead — confirm the parent now has `stage:*` chores (`bd children <parent-id> --json | grep -c '"stage:'`) and skip to step 5 to dispatch its ready `stage:code` chore. A **decomposition worker** — confirm the feature now has children (`bd children <feature-id> --json` returns a non-empty list), record that nothing is dispatchable for it until a human closes the planning bead, and skip to step 5; never re-decompose. If either confirmation comes back empty, the worker failed: surface its output, record the parent for the shutdown summary, and do not re-dispatch.
+2. Read the completed agent's output and parse its `---REPORT---` block for `BEAD_ID`, `STAGE_COMPLETED`, and the outcome. A **decomposition** (`kind: "decompose"`) or **expansion** (`kind: "expand"`) worker has no REPORT and no leaf bead to confirm. An **expansion worker** owns no bead — confirm the parent now has `stage:*` chores (`bd children <parent-id> --json | grep -c '"stage:'`) and skip to step 5 to dispatch its ready `stage:code` chore. A **decomposition worker** — confirm the feature now has children (`bd children <feature-id> --json` returns a non-empty list), record that nothing is dispatchable for it until a human closes the planning bead, and skip to step 5; never re-decompose. If either confirmation comes back empty, the worker failed: surface its output, record the parent for the shutdown summary, and do not re-dispatch.
 3. Confirm the stage worker closed its chore bead: `bd show <bead-id>` should read `closed` with the outcome in its close reason. If it is still open the worker died mid-stage — read its notes and re-dispatch; never close it yourself.
 4. Route the parent per the dispatch table — nothing is created here: the pre-created chain already encodes the order, and the worker owns any remediation it needs.