@jaybeeuu/agent-cortex 2.4.2 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 2.5.1
+
+### Patch Changes
+
+- e87b2d0: Align the code, verify, document, and fix REPORT templates on the authoritative
+  `run-pipeline-stage` contract. Each template now emits `STAGE_COMPLETED` with its stage name
+  (`code`, `verify`, `document`, `fix`) plus `COMMIT`, `PUSHED`, `PR`, and
+  `OUTCOME: SUCCESS|BLOCKED`, and lists blocked work under `BLOCKING_ISSUES`. The unparsed
+  `VERIFY_OUTCOME`/`VERIFY_FAILURES` keys are gone, so an orchestrator can route every stage's
+  report.
+- 83ed526: Stop `agent-cortex install claude` erasing Claude Code's `enabledPlugins` entry.
+
+  The settings merge now asserts only the `enabledPlugins` and `extraKnownMarketplaces` entries the
+  committed `claude/settings.json` template declares; entries it does not declare survive, so a
+  same-version re-run keeps the entry Claude Code writes when the plugin is enabled. Registration
+  also reports an installed-but-not-enabled plugin, naming `claude plugin enable <plugin>@<marketplace>`.
+
+- 34bcea7: Type-check the extensions against the pi version that is actually installed.
+
+  The extension workspaces pinned `@earendil-works/pi-coding-agent`, `pi-agent-core`, and `pi-ai` at
+  `^0.78.1` for `import type` only, while `pi --version` reported 1.5.2. `pnpm typecheck` therefore
+  validated against an API that no installed pi provides. The pins now follow the running CLI at
+  `^1.5.2`, and the `agent-modes` `ExtensionAPI` test double gains the members 1.5.x declares:
+  `registerMarkdownTransformer`, `registerEntryRenderer`, `registerToolRenderer`, `registerVirtualModel`,
+  `registerMcpServer`, `unregisterMcpServer`, `getMcpServers`, `unregisterVirtualModel`, and
+  `getSettings`, plus the unsubscribe return value of `on`.
+
+- fa84942: Move the composable agent-directory validator from
+  `skills/productivity/validate-agent-dir/scripts/` to `scripts/validate-agent-dir.mjs`. The
+  directory had no `SKILL.md`, so neither installer shipped it while it still looked like a shipped
+  skill, and the module validates this repository's own `agents/` layout — repo tooling, not a
+  portable skill. Its filesystem probes are now async (`validateAgentDir` returns a promise),
+  matching the no-`*Sync` rule for `scripts/`.
+
+  `agents/README.md` (Validation) and `test/validate-agent-dir.test.mjs` point at the new path. No
+  skill, agent, hook, or installer behaviour changes.
+
+## 2.5.0
+
+### Minor Changes
+
+- 8ca9462: New `cortex` and `ctx` commands: both run the same CLI as `agent-cortex`. The help text and the error hints now name the command that was invoked, so `ctx --help` prints `Usage: ctx <command>`; any other script name falls back to `agent-cortex`.
+- 45992c7: `create-chores.mjs` is now idempotent: a re-run adopts the stage chores and PR gate that already exist under the parent, creates only what is missing, and skips deps that are already wired. Re-running it after a failed chore expansion is now the recovery path, so ralph no longer refuses to re-dispatch an expansion.
+
+### Patch Changes
+
+- 2cab55e: Chunk the `migrate` v1 label rename: each `bd label add` and `bd label remove` call
+  now carries at most 20 bead ids. One call carrying every id in a large workspace
+  applied only part of the list and still reported success, so v1 never converged and a
+  workspace could report itself migrated with hundreds of legacy labels attached.
+- dd4e69c: Fail `agent-cortex install pi` when a skill sits outside `skills/<group>/<name>`.
+
+  pi advertises a skill by the absolute path of its `SKILL.md`, and the installer copies exactly
+  `skills/<group>/<name>`. A skill authored deeper was skipped without a trace, so no session was
+  ever told about it. The install now stops and names the offending path.
+
+  `docs/dev-loop.md` records the related limit that needs no code: a session lists its skills when
+  it starts, so a session already open across a re-stage holds the paths it was given.
+
 ## 2.4.2
 
 ### Patch Changes

package/README.md

@@ -151,6 +151,11 @@ long-lived credential in repository secrets to save one click per release.
 
 ## Installation
 
+The CLI installs under three names — `agent-cortex`, `cortex` and `ctx` — that run the
+same command, and the help and error text names the one you invoked. That naming is POSIX
+only: the npm and pnpm shims on Windows call `bin/agent-cortex.mjs` directly, so the text
+falls back to `agent-cortex` there.
+
 ### Pi package staging (`agent-cortex install pi`)
 
 `agent-cortex install pi` materialises agent-cortex as a self-contained pi
@@ -287,7 +292,8 @@ symlinks), `SessionStart` + `Notification` hooks, and 2 MCP servers — writes a
 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
 `~/.claude/settings.json`: the template supplies defaults, personal values win, and the
-installer owns exactly `enabledPlugins` + `extraKnownMarketplaces` — every other key
+installer owns exactly the `enabledPlugins` + `extraKnownMarketplaces` entries the template
+declares — entries it does not declare are left alone — while every other key
 (`permissions`, `hooks`, `env`, `statusLine`, unknown keys) is preserved. It also writes the
 managed section of `~/.claude/CLAUDE.md` — the reply-shape block the pi `output-style`
 extension appends, taken from the same source file — and leaves every other line of that
@@ -355,10 +361,15 @@ agent-cortex install claude --require-register       # register or fail the inst
 
 The install also merges the committed `claude/settings.json` template into
 `~/.claude/settings.json` (the settings file Claude Code reads at user scope). The template
-supplies defaults and personal values win; the installer owns exactly `enabledPlugins` +
-`extraKnownMarketplaces`, so `permissions`, `hooks`, `env`, `statusLine` and unknown keys are
-never touched. A legacy symlinked `settings.json` is replaced with a real file rather than
-written through, and `--output` leaves the user's Claude config alone.
+supplies defaults and personal values win; the installer owns exactly the `enabledPlugins` +
+`extraKnownMarketplaces` entries the template declares, so entries it does not declare (including
+the one Claude Code writes when you enable the plugin) survive, and `permissions`, `hooks`, `env`,
+`statusLine` and unknown keys are never touched. A legacy symlinked `settings.json` is replaced
+with a real file rather than written through, and `--output` leaves the user's Claude config
+alone. When registration finds the plugin installed but the settings do not enable it, the install
+warns and names `claude plugin enable <plugin>@<marketplace>` — a disabled plugin loads nothing.
+That check reads the user-scope file only, so a plugin enabled at project or local scope still
+warns; `claude plugin list` reports the effective state.
 
 It also writes the managed section of `~/.claude/CLAUDE.md` (Claude's user memory), delimited
 by `<!-- BEGIN agent-cortex:output-style -->` / `<!-- END agent-cortex:output-style -->`. The
@@ -480,7 +491,8 @@ is an empty legacy namespace, not just a clean live one (see
 A bare `agent-cortex migrate` is a **dry run** — it prints the per-bead plan and writes
 nothing. `--apply` runs every pending step in order and verifies each before moving on. It
 shells out to the `bd` CLI on `PATH` (`BD_PATH` overrides) and fails loudly, rather than
-half-applying, when `bd` is missing or a `bd` subcommand errors.
+half-applying, when `bd` is missing or a `bd` subcommand errors. Label writes carry at most 20
+ids per `bd` call, because `bd` can exit 0 having applied only part of a longer list.
 
 Detection reads `bd export --all` and cross-checks `bd label list-all`, never a
 label-filtered `bd list`: on bd 1.3.1 that query can omit closed beads, which once let a

package/agents/README.md

@@ -245,7 +245,9 @@ agents, token-substituted skills, extensions) at `~/.agent-cortex/pi`.
 
 ## Validation
 
-Use the `validate-agent-dir` script to validate agent directories:
+The composable layout is validated by the repo tooling at `scripts/validate-agent-dir.mjs` — a
+module, not a shipped skill, with no CLI. Import `validateAgentDir` to check a directory, or run
+its test suite:
 
 ```bash
 node --test test/validate-agent-dir.test.mjs

package/agents/ralph/agent.md

@@ -77,7 +77,7 @@ A feature carries `execution:hitl` by default, so this whole procedure only runs
 
 A ready `execution:afk` task bead with no `stage:*` chore children has nothing to dispatch, so it is not dispatched as work. Expand it first, then let the normal dispatch pick up the resulting `stage:code` chore:
 
-1. Confirm the bead is chore-less: `bd children <parent-id> --json | grep -c '"stage:'` prints `0` — add `|| true` under `set -e` or inside an `&&` chain, since `grep -c` exits `1` on a zero count and the printed number is the answer. A bead that already has stage chores is never expanded again.
+1. Confirm the bead is chore-less: `bd children <parent-id> --json | grep -c '"stage:'` prints `0` — add `|| true` under `set -e` or inside an `&&` chain, since `grep -c` exits `1` on a zero count and the printed number is the answer. A bead with a full chain — one `stage:*` chore per stage in `pipeline.json`, plus the `lifecycle:feature-pr` gate — never needs an expansion. This check only sees a count of zero, so a **partial** chain is not detected here and its missing stages never arrive: re-run step 2's command against that parent by hand, which is idempotent.
 2. Dispatch an **expansion worker** in the feature worktree (`.agent-cortex/worktrees/<parent-id>`, created per the branching model if it is missing) whose whole job is to run the pre-creator against the existing bead and report the JSON it printed:
 
    ```bash
@@ -86,6 +86,8 @@ A ready `execution:afk` task bead with no `stage:*` chore children has nothing t
    ```
 
    `<create-task-scripts>` is the absolute path to the `create-task` skill's `scripts/` directory, resolved from wherever the skill was loaded. `<parent-priority>` is the parent bead's own priority from `bd show <parent-id>`.
+
+   The command is idempotent: it adopts an existing child by its `stage:<id>` or `lifecycle:feature-pr` label, creates only what is missing, skips deps that are already wired, and prints the resolved mapping either way. Re-running it is the recovery path for a failed expansion.
 3. Record the worker in `inflight` as an **expansion** entry — it has no chore to key on, so `choreId` is `null`:
    ```json
    { "kind": "expand", "choreId": null, "parentId": "<parent-id>", "title": "<parent title>", "agentId": "<agent-id>", "logLine": 1 }
@@ -94,7 +96,7 @@ A ready `execution:afk` task bead with no `stage:*` chore children has nothing t
 4. The worker reports the returned mapping — `code`, `verify`, `review`, `document`, `featurePrReview` — and closes nothing. It emits **no** `---REPORT---` block and owns no bead, so there is nothing to parse and no close to confirm.
 5. Its completion means the parent now has a `stage:*` chain: the event loop's next `bd ready -l execution:afk` pass picks up the `stage:code` chore (event loop step 7).
 
-**Expansion completion contract.** An expansion worker is dispatched like a stage worker but is not one: no chore claim, no `---REPORT---`, no leaf-bead close. Handle its completion with the expansion branch in event-loop step 3, which confirms the chain exists (`bd children <parent-id> --json | grep -c '"stage:'` prints a non-zero count) and dispatches the ready `stage:code` chore. If the parent still has no `stage:*` children the expansion failed: surface the worker's output in chat, **never re-run `create-chores.mjs`** (it is not idempotent — a second run duplicates the chain), and record the parent for the shutdown summary. Either way, create nothing and close nothing.
+**Expansion completion contract.** An expansion worker is dispatched like a stage worker but is not one: no chore claim, no `---REPORT---`, no leaf-bead close. Handle its completion with the expansion branch in event-loop step 3, which confirms the chain exists (`bd children <parent-id> --json | grep -c '"stage:'` prints one match per stage chore — the gate carries `lifecycle:feature-pr` and is not counted) and dispatches the ready `stage:code` chore. A count below the stage total in `pipeline.json` is a partial chain, whose missing stages never arrive, so re-dispatch the expansion instead of dispatching on. If the parent still has no `stage:*` children the expansion failed: surface the worker's output in chat, record the parent for the shutdown summary, and re-dispatch the expansion — `create-chores.mjs` is idempotent, so a second run adopts the chores that exist, creates only the missing ones, and reports the whole mapping. Either way, create nothing and close nothing yourself.
 
 **Never expand an existing bead by running `create-task`** (or any other command that creates a bead). `create-task` creates a bead first and expands second, so running it for an existing bead leaves a **second parent** beside the original, which stays chore-less and never gets dispatched. `create-chores.mjs` expands a bead that already exists; it never creates parents.
 
@@ -165,8 +167,8 @@ After initialization, Ralph waits for background agents to complete. Completions
 1. **Flush** that bead's log using the procedure in the wake section to pick up any final lines for the chat summary (a mechanism that delivers the log with the completion needs no flush).
 2. **Read** the completed agent's full output the way the wake section describes.
 3. **Re-read** `.agent-cortex/ralph/state.json` to identify the entry for that agent ID, then branch on its `kind`:
-   - **`kind: "expand"` — expansion completion branch.** The worker claimed no chore, emits no `---REPORT---`, and owns no bead to confirm, so steps 4-6 **do not apply**: remove the entry from `inflight`, confirm the parent now has `stage:*` chore children (`bd children <parent-id> --json | grep -c '"stage:'`) and surface the reported mapping in chat, then go straight to step 7 — the new `stage:code` chore is ready to dispatch. If the parent still has no `stage:*` children the expansion failed: surface the worker's output, do **not** re-run `create-chores.mjs` (not idempotent), record the parent for the shutdown summary, remove the entry, and continue at step 7. Never create or close a bead for an expansion.
-   - **`kind: "decompose"` — decomposition completion branch.** Same shape as expansion: no chore, no `---REPORT---`, so steps 4-6 **do not apply**: remove the entry from `inflight`, confirm the feature now has children (`bd children <feature-id> --json` returns a non-empty list) and surface the created IDs in chat, then go straight to step 7. Nothing is dispatchable for that feature until a human closes the planning bead, so finding no ready work for it is the correct outcome — do **not** re-dispatch the decomposition (the bead creation it ran is not idempotent). If the feature still has no children, the worker failed: surface its output, record it for the shutdown summary, remove the entry, and continue at step 7. Never create or close a bead here.
+   - **`kind: "expand"` — expansion completion branch.** The worker claimed no chore, emits no `---REPORT---`, and owns no bead to confirm, so steps 4-6 **do not apply**: remove the entry from `inflight`, confirm the parent now has `stage:*` chore children (`bd children <parent-id> --json | grep -c '"stage:'`) and surface the reported mapping in chat, then go straight to step 7 — the new `stage:code` chore is ready to dispatch. If the count is `0` — or below the stage total, which is a partial chain whose later stages never arrive — the expansion failed: surface the worker's output, record the parent for the shutdown summary, remove the entry, and re-dispatch the expansion — re-running `create-chores.mjs` is idempotent and is the recovery path, so it repairs the tree instead of duplicating it. Never create or close a bead for an expansion.
+   - **`kind: "decompose"` — decomposition completion branch.** Same shape as expansion: no chore, no `---REPORT---`, so steps 4-6 **do not apply**: remove the entry from `inflight`, confirm the feature now has children (`bd children <feature-id> --json` returns a non-empty list) and surface the created IDs in chat, then go straight to step 7. Nothing is dispatchable for that feature until a human closes the planning bead, so finding no ready work for it is the correct outcome — do **not** re-dispatch the decomposition (the bead creation it ran is not idempotent; that hazard is `create-task`'s, not the expansion's). If the feature still has no children, the worker failed: surface its output, record it for the shutdown summary, remove the entry, and continue at step 7. Never create or close a bead here.
    - **`kind: "stage"`** — a stage worker: continue with steps 4-6.
 4. **Parse** the agent's `---REPORT---` block (see report format in the `run-pipeline-stage` skill).
 5. **Confirm** the worker closed its own leaf execution bead: `bd show <chore-id>` should read `closed`. If it is still open the worker died mid-stage — read its notes and re-dispatch. Never close it yourself.

package/bin/agent-cortex.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { parseArgs, buildHelpText, validateHarness } from "../lib/cli.mjs";
+import { parseArgs, buildHelpText, resolveProgramName, validateHarness } from "../lib/cli.mjs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
@@ -10,10 +10,12 @@ import { installPi, registerPi, sweepLegacyPiUserDirs } from "./installers/pi.mj
 /** @typedef {import("./installers/pi.mjs").RegisterPiResult} RegisterPiResult */
 
 const argv = process.argv.slice(2);
-const parsed = parseArgs(argv);
+// `agent-cortex`, `cortex` and `ctx` all run this file; the text names the one used.
+const programName = resolveProgramName(process.argv[1]);
+const parsed = parseArgs(argv, programName);
 
 if (parsed.command === "help") {
-  process.stdout.write(buildHelpText() + "\n");
+  process.stdout.write(buildHelpText(programName) + "\n");
   process.exit(0);
 }
 
@@ -53,7 +55,7 @@ if (parsed.command === "version") {
 }
 
 if (parsed.command === "unknown") {
-  process.stderr.write(`Unknown command: ${parsed.name}\nRun "agent-cortex --help" for usage.\n`);
+  process.stderr.write(`Unknown command: ${parsed.name}\nRun "${programName} --help" for usage.\n`);
   process.exit(1);
 }
 
@@ -65,7 +67,7 @@ if (parsed.command === "install") {
 
   const check = validateHarness(parsed.harness);
   if (!check.ok) {
-    process.stderr.write(`${check.error}\nRun "agent-cortex --help" for usage.\n`);
+    process.stderr.write(`${check.error}\nRun "${programName} --help" for usage.\n`);
     process.exit(1);
   }
 
@@ -118,8 +120,8 @@ if (parsed.command === "install") {
   // materialises the plugin into the home install root (~/.agent-cortex/claude)
   // with copied, token-substituted skills, writes the marketplace manifest at
   // ~/.agent-cortex/.claude-plugin/marketplace.json, merges the committed
-  // claude/settings.json template into ~/.claude/settings.json (owning only
-  // enabledPlugins + extraKnownMarketplaces), and registers it with Claude Code
+  // claude/settings.json template into ~/.claude/settings.json (asserting only
+  // the enabledPlugins + extraKnownMarketplaces entries the template declares), and registers it with Claude Code
   // (marketplace add → install → update); `--output <dir>` is the generate-only
   // form (tests/CI validation), and the generated claude/ plugin subtree is
   // never committed — only the settings template is.
@@ -145,6 +147,9 @@ if (parsed.command === "install") {
           root: /** @type {string} */ (result.marketplaceRoot),
           manifest: /** @type {object} */ (result.marketplaceManifest),
           pluginVersion: result.pluginVersion,
+          // The enablement check reads the same file this install just merged:
+          // a plugin Claude Code does not enable loads nothing.
+          ...(result.settings ? { settingsPath: result.settings.path } : {}),
           dryRun: parsed.dryRun ?? false,
           requireRegister: parsed.requireRegister ?? false,
         });

package/bin/installers/claude.mjs

@@ -85,13 +85,16 @@ const PACKAGE_ROOT = join(MODULE_DIR, "..", "..");
  */
 
 /**
- * Registration plan/outcome returned by registerClaude.
+ * Register plan/outcome returned by registerClaude.
  * @typedef {object} RegisterClaudeResult
  * @property {string} marketplace
  * @property {string} plugin
  * @property {string[][]} commands
  * @property {boolean} dryRun
  * @property {boolean} registered
+ * @property {boolean | null} enabled  Whether the user's settings enable the plugin;
+ *                                     null when the settings could not be read or
+ *                                     its state is unconfirmed.
  * @property {string[]} skipped
  */
 
@@ -400,9 +403,13 @@ async function buildHandAuthored(root) {
  *   - template keys fill in defaults the live file lacks; every value already
  *     present in the live file wins (deeply), and unknown keys are preserved,
  *     so personal config survives re-install;
- *   - `enabledPlugins` and `extraKnownMarketplaces` are CLI-owned: they are
- *     rewritten from the template outright. `permissions`, `hooks`, `env`,
- *     `statusLine` and every other key are never touched.
+ *   - `enabledPlugins` and `extraKnownMarketplaces` are CLI-owned in the other
+ *     direction: the entries the template declares are asserted (the template
+ *     value wins for those), and entries it does not declare are kept. A
+ *     template key that is empty or absent declares nothing and therefore owns
+ *     nothing — silence never deletes, so a re-install cannot erase the entry
+ *     Claude Code writes when the user enables the plugin. `permissions`,
+ *     `hooks`, `env`, `statusLine` and every other key are never touched.
  * @param {{ root: string, target: string, dryRun: boolean, warn: Warn }} options
  * @returns {Promise<ManagedFileResult | null>}
  */
@@ -410,16 +417,32 @@ async function installSettings({ root, target, dryRun, warn }) {
   const template = await readTemplateJson(join(root, SETTINGS_TEMPLATE), warn);
   if (template === null) return null;
 
-  const merged = mergeSettings(template, await readJsonObject(target, warn));
+  const existing = await readJsonObject(target, warn);
+  const merged = mergeSettings(template, existing);
   for (const key of SETTINGS_OWNED_KEYS) {
-    if (key in template) merged[key] = template[key];
-    else delete merged[key];
+    const value = mergeOwnedSetting(template[key], existing[key]);
+    if (value === undefined) delete merged[key];
+    else merged[key] = value;
   }
 
   const content = `${JSON.stringify(merged, null, 2)}\n`;
   return writeManagedFile({ target, content, dryRun });
 }
 
+/**
+ * Merge one CLI-owned settings key. The template asserts the entries it
+ * declares — its value wins for exactly those — and every entry it does not
+ * declare survives from the live file. An empty or absent template key declares
+ * nothing, so the live value passes through untouched: silence never deletes.
+ * @param {unknown} template
+ * @param {unknown} existing
+ * @returns {unknown}
+ */
+function mergeOwnedSetting(template, existing) {
+  if (!isPlainObject(template) || !isPlainObject(existing)) return existing === undefined ? template : existing;
+  return { ...existing, ...template };
+}
+
 /**
  * Merge the committed template over the live file. Template keys fill in
  * defaults, live values win (deeply), and keys the template does not know about
@@ -1045,6 +1068,11 @@ async function pluginLoadVerdict(claudeBin, pluginId) {
  * 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.
  *
+ * A loaded plugin that the user's settings do not enable loads nothing either:
+ * Claude Code reads `enabledPlugins` from that file, and registration skips the
+ * install as "already installed", so the run warns with the command that fixes
+ * it rather than reporting a working install.
+ *
  * @param {object} options
  * @param {string} [options.root]            Marketplace root carrying .claude-plugin/…
  *                                           (defaults to the repo containing this module)
@@ -1052,6 +1080,8 @@ async function pluginLoadVerdict(claudeBin, pluginId) {
  * @param {boolean} [options.dryRun]         Plan and report without running or writing
  * @param {object} [options.manifest]        Pre-parsed marketplace manifest (skips the file read)
  * @param {string} [options.pluginVersion]   Materialised plugin version (default: read from plugin.json)
+ * @param {string} [options.settingsPath]    Claude user settings the enablement check reads
+ *                                           (default ~/.claude/settings.json)
  * @param {boolean} [options.requireRegister] Exit non-zero when registration cannot run
  * @param {(msg: string) => void} [options.warn] Warning sink (default: console.warn)
  * @returns {Promise<RegisterClaudeResult>}
@@ -1062,6 +1092,7 @@ export async function registerClaude({
   dryRun = false,
   manifest,
   pluginVersion,
+  settingsPath = DEFAULT_SETTINGS_PATH,
   requireRegister = false,
   warn = DEFAULT_WARN,
 } = {}) {
@@ -1072,7 +1103,7 @@ export async function registerClaude({
   const version = pluginVersion ?? (await readMaterialisedPluginVersion(root, manifestObj));
   const home = resolve(root);
 
-  const summary = /** @type {RegisterClaudeResult} */ ({ marketplace, plugin, commands: [], dryRun, registered: true, skipped: [] });
+  const summary = /** @type {RegisterClaudeResult} */ ({ marketplace, plugin, commands: [], dryRun, registered: true, enabled: null, skipped: [] });
   console.log(`Registering plugin "${pluginId}" with Claude Code (via ${claudeBin})…`);
 
   const manualCommands = [
@@ -1156,9 +1187,22 @@ export async function registerClaude({
         `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).`,
-    );
+    // Installed but disabled is a plugin that loads nothing: Claude Code gates
+    // every skill and agent on the user's enabledPlugins entry, and the install
+    // path above skips a same-version re-install as "already installed", so
+    // this is the only place that state is reported.
+    const enabled = (await readJsonObject(settingsPath, warn)).enabledPlugins?.[pluginId] === true;
+    summary.enabled = enabled;
+    if (enabled) {
+      console.log(
+        `Installed and enabled — verify with "claude plugin list" / "claude plugin details ${plugin}" (restart Claude Code to apply).`,
+      );
+    } else {
+      warn(
+        `"${pluginId}" is installed but not enabled in ${settingsPath} — Claude Code loads nothing from a disabled plugin; ` +
+          `enable it with "${claudeBin} plugin enable ${pluginId}" and restart Claude Code`,
+      );
+    }
   }
   return summary;
 }

package/bin/installers/pi.mjs

@@ -395,7 +395,19 @@ async function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, wa
     const groupDir = join(skillsSrc, group);
     if (!(await isDirectory(groupDir))) continue;
     for (const name of (await readdir(groupDir)).sort()) {
-      if (!(await isFile(join(groupDir, name, "SKILL.md")))) continue;
+      if (!(await isFile(join(groupDir, name, "SKILL.md")))) {
+        // pi advertises a skill by the absolute path of its SKILL.md, and this
+        // installer carries exactly skills/<group>/<name>. A skill authored
+        // below that depth would be dropped without a trace, so fail instead.
+        const nested = await findSkillFiles(join(groupDir, name));
+        if (nested.length > 0) {
+          throw new Error(
+            `skill "${nested[0]}" is not at skills/<group>/<name>/SKILL.md — ` +
+              "the installer copies exactly that depth, so pi would never advertise this skill",
+          );
+        }
+        continue;
+      }
       skills += 1;
       const stats = await copyTree(join(groupDir, name), join(skillsDir, group, name), { dryRun, transform });
       md += stats.md;
@@ -405,6 +417,28 @@ async function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, wa
   return { skills, md, files, dir: skillsDir };
 }
 
+/**
+ * Every `SKILL.md` below `dir`, recursively — the skills pi would advertise if
+ * its discovery walked the repository tree instead of the staged one.
+ * @param {string} dir
+ * @returns {Promise<string[]>}
+ */
+async function findSkillFiles(dir) {
+  /** @type {string[]} */
+  const found = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) found.push(...(await findSkillFiles(join(dir, entry.name))));
+    else if (entry.isFile() && entry.name === "SKILL.md") found.push(join(dir, entry.name));
+  }
+  return found;
+}
+
 // ─── Extensions ──────────────────────────────────────────────────────────────
 
 /**

package/extensions/agent-guardrails/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/extensions/agent-modes/index.test.ts

@@ -64,6 +64,8 @@ function createFakePi(flagValues: Record<string, boolean | string> = {}): FakePi
       const list = handlers.get(event) ?? [];
       list.push(handler);
       handlers.set(event, list);
+      // `ExtensionAPI.on` returns an unsubscribe function.
+      return () => {};
     },
     registerFlag: (name, options) => {
       flags.push([name, options]);
@@ -77,8 +79,16 @@ function createFakePi(flagValues: Record<string, boolean | string> = {}): FakePi
     registerShortcut: () => {},
     registerTool: () => {},
     registerMessageRenderer: () => {},
+    registerMarkdownTransformer: () => {},
+    registerEntryRenderer: () => {},
+    registerToolRenderer: () => {},
     registerProvider: () => {},
     unregisterProvider: () => {},
+    registerMcpServer: () => {},
+    unregisterMcpServer: () => {},
+    unregisterVirtualModel: () => {},
+    registerVirtualModel: () => {},
+    getMcpServers: () => [],
     sendMessage: () => {},
     sendUserMessage: () => {},
     appendEntry: () => {},
@@ -89,6 +99,9 @@ function createFakePi(flagValues: Record<string, boolean | string> = {}): FakePi
       throw new Error("not implemented");
     },
     getAllTools: () => [],
+    getSettings: () => {
+      throw new Error("not implemented");
+    },
     getCommands: () => [],
     setModel: async () => false,
     getThinkingLevel: () => "off",

package/extensions/agent-modes/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/extensions/lib/tiny-model.ts

@@ -16,12 +16,13 @@
  * The model call itself is gone. It went through pi-ai's `complete()`, a value
  * import of pi's runtime, and that import stopped the extension loading outside
  * the agent-cortex checkout (see test/pi-extensions-load.test.mjs). The
- * ExtensionAPI promises no completion call. Newer hosts (pi 1.4.0) expose
- * `ModelRegistry.complete`, but the installed host (0.73.1) does not. Calling it
- * would need an untyped cast to a method that exists on one version only.
- * Extensions also make no internal LLM calls (AGENTS.md), so this feature stays
- * off. Both callers fall back to the truncation they already used when the model
- * failed. The `model` key is no longer read and is ignored if present.
+ * ExtensionAPI promises no completion call. The installed host (pi 1.5.2) does
+ * expose `ModelRegistry.complete` through `ExtensionContext.modelRegistry`, but
+ * calling it would make the extensions depend on a method that exists on later
+ * hosts only. Extensions also make no internal LLM calls (AGENTS.md), so this
+ * feature stays off. Both callers fall back to the truncation they already used
+ * when the model failed. The `model` key is no longer read and is ignored if
+ * present.
  */
 
 import { homedir } from "node:os";

package/extensions/output-style/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/extensions/session-start/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/extensions/skill-stats/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/extensions/subagent/package.json

@@ -8,9 +8,9 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.78.1",
-    "@earendil-works/pi-ai": "^0.78.1",
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-agent-core": "^1.5.2",
+    "@earendil-works/pi-ai": "^1.5.2",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typebox": "^1.1.38",

package/lib/cli.mjs

@@ -1,3 +1,5 @@
+import { basename } from "node:path";
+
 /**
  * Result of parsing the CLI argv. Every branch returns `command`; the rest are
  * populated only for the commands that accept them.
@@ -18,6 +20,24 @@
 
 const SUPPORTED_HARNESSES = ["claude", "pi"];
 
+// The published bin names. `package.json` maps all three onto bin/agent-cortex.mjs,
+// so the help and error text names whichever shim the user typed.
+const PROGRAM_NAMES = ["agent-cortex", "cortex", "ctx"];
+const DEFAULT_PROGRAM_NAME = "agent-cortex";
+
+/**
+ * Resolve the program name to print from the path the CLI was invoked as. Only
+ * the published command names are recognised; anything else (a bare `node
+ * bin/agent-cortex.mjs`, a renamed copy) falls back to `agent-cortex`, so the
+ * text always names a command that exists.
+ * @param {string | undefined} invokedPath `process.argv[1]`, or a bare name in tests
+ * @returns {string}
+ */
+export function resolveProgramName(invokedPath) {
+  const name = basename(invokedPath ?? "");
+  return PROGRAM_NAMES.includes(name) ? name : DEFAULT_PROGRAM_NAME;
+}
+
 // Options accepted by `install <harness>`. `--output`/`--dry-run` are shared by
 // the claude and pi installers; `--plugin-root` is pi-specific. Unknown or
 // malformed options surface as `optionError` on the parsed result; the CLI
@@ -33,9 +53,10 @@ const INSTALL_OPTIONS = {
 /**
  * Parse the CLI argv.
  * @param {string[]} argv
+ * @param {string} [programName] The resolved command name, for usage hints
  * @returns {ParsedArgs}
  */
-export function parseArgs(argv) {
+export function parseArgs(argv, programName = DEFAULT_PROGRAM_NAME) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     return { command: "help" };
   }
@@ -64,7 +85,7 @@ export function parseArgs(argv) {
       const inlineValue = arg.startsWith("--output=") ? arg.slice("--output=".length) : null;
       const spec = inlineValue !== null ? INSTALL_OPTIONS["--output"] : INSTALL_OPTIONS[arg];
       if (!spec) {
-        return { command: "install", harness, optionError: `Unknown option "${arg}". Run "agent-cortex --help" for usage.` };
+        return { command: "install", harness, optionError: `Unknown option "${arg}". Run "${programName} --help" for usage.` };
       }
       if (spec.boolean) {
         options[spec.key] = true;
@@ -76,7 +97,7 @@ export function parseArgs(argv) {
       }
       const value = rest[i + 1];
       if (value == null || value.startsWith("--")) {
-        return { command: "install", harness, optionError: `Missing value for "${arg}". Run "agent-cortex --help" for usage.` };
+        return { command: "install", harness, optionError: `Missing value for "${arg}". Run "${programName} --help" for usage.` };
       }
       options[spec.key] = value;
       i += 1;
@@ -116,13 +137,13 @@ export function parseArgs(argv) {
       if (arg === "--dir" || inlineDir !== null) {
         const value = rest[i + 1];
         if (inlineDir !== null || value == null || value.startsWith("--")) {
-          return { command: "migrate", optionError: `Missing value for "--dir". Run "agent-cortex --help" for usage.` };
+          return { command: "migrate", optionError: `Missing value for "--dir". Run "${programName} --help" for usage.` };
         }
         dir = value;
         i += 1;
         continue;
       }
-      return { command: "migrate", optionError: `Unknown option "${arg}". Run "agent-cortex --help" for usage.` };
+      return { command: "migrate", optionError: `Unknown option "${arg}". Run "${programName} --help" for usage.` };
     }
     if (sawApply && sawDryRun) {
       return { command: "migrate", optionError: '"--apply" and "--dry-run" are mutually exclusive.' };
@@ -134,10 +155,11 @@ export function parseArgs(argv) {
 }
 
 /**
+ * @param {string} [programName] The resolved command name, for the usage line
  * @returns {string}
  */
-export function buildHelpText() {
-  return `Usage: agent-cortex <command> [options]
+export function buildHelpText(programName = DEFAULT_PROGRAM_NAME) {
+  return `Usage: ${programName} <command> [options]
 
 Commands:
   install <harness>   Install agent-cortex for a harness