@jaybeeuu/agent-cortex 1.42.0 → 1.43.0

package/README.md

@@ -105,6 +105,13 @@ does its own checkout and `pnpm install` rather than sharing build artifacts fro
 the `setup` job — pnpm workspace symlinks don't survive artifact upload/download,
 so artifact sharing would break the workspace resolution that the build depends on.
 
+The root `pnpm-workspace.yaml` carries a strict `allowBuilds` map: on pnpm 12 (what CI
+pins) any dependency with install or build scripts that is not named there aborts
+`pnpm install` with `ERR_PNPM_IGNORED_BUILDS`. pnpm 10 only warns, so a newly pulled-in
+native dependency surfaces as a red `Setup` job before it surfaces locally. Adding one
+therefore means deciding its build policy in that map — `false` unless it genuinely
+needs to compile, with a comment saying why.
+
 The repo commits no generated `claude/` plugin output, so the `claude-plugin-check` job
 validates the Claude plugin **materialiser** instead of diffing a committed mirror:
 it runs `node bin/agent-cortex.mjs install claude --output <tmp dir>` and checks the
@@ -114,10 +121,14 @@ and no symlinks leak into the copied tree. The Copilot drift check
 (`pnpm build:copilot` + `git diff --exit-code -- 'agents/*.agent.md'`) still guards the
 committed flat agent files.
 
-A separate `changeset-check` job runs only on pull requests and fails any PR that
-touches a versioned path (`extensions/`, `skills/`, `agents/`, `package.json`, or
-`plugin.json`) without a changeset in `.changeset/`. Add one with `pnpm changeset` —
-the `style-versioning` skill documents the format.
+A separate `changeset-check` job runs on every pull request and fails it unless the
+PR adds a `.changeset/*.md` file. **Publishing is the default and `no-publish` is the
+only opt-out**, so shipping nothing has to be a deliberate, reviewable act rather
+than an accident. Two exemptions: the changesets bot's Version Packages PR (it
+consumes changesets and adds none) and PRs labelled `no-publish`. The `no-publish`
+label must exist in the repository's label settings — a one-off repo-settings step
+that no PR can ship. The `style-versioning` skill documents the format of a
+changeset.
 
 On pushes to `main`, a `release` job (gated on `lint`, `test`, and
 `claude-plugin-check`) runs changesets to open a `chore: version packages` PR when
@@ -125,90 +136,131 @@ changesets are pending, then publishes to npm once it lands. The version step ru
 `pnpm version-packages` — bumping `package.json`, syncing `plugin.json`, and
 regenerating the committed Copilot agent files (the Claude plugin is materialised at
 install time with the package version, so it has no committed output to regenerate)
-so the drift gates stay green; the
-publish step runs `pnpm publish-package` (pack + provenance publish). Publish
-authenticates via npm Trusted Publishing (OIDC) — no npm token or GitHub
-secret is needed, only the one-time npm-side setup on npmjs.com (package →
+so the drift gates stay green; the publish step runs `pnpm publish-package` (pack +
+provenance publish), or
+`pnpm publish-noop` when the merged PR carried `no-publish`. Labels are invisible on
+a push event, so the job resolves the PR merged for the pushed commit through the
+GitHub API and reads its labels — no extra secret or scope, since the job already
+holds `GITHUB_TOKEN` and `pull-requests: write`. A direct push with no merged PR
+resolves to no labels and therefore publishes, so attempting to publish an
+already-published version still fails loudly; there is deliberately no idempotency
+guard. Publishing authenticates via npm Trusted Publishing (OIDC) — no npm token or
+GitHub secret is needed, only the one-time npm-side setup on npmjs.com (package →
 Access → Trusted Publishing for the `jaybeeuu/agent-cortex` repo). Releases
 are sourced entirely from `main`.
 
-## Installation
-
-### Pi config files (`settings.json` + `keybindings.json`)
-
-`agent-cortex install pi` materialises `~/.pi/agent/settings.json` and
-`~/.pi/agent/keybindings.json` as real CLI-managed files — the legacy symlinks
-into this repo's `pi/` directory are gone. `pi/settings.json` and
-`pi/keybindings.json` are the committed **templates**; the live files exist only
-on the machine, so re-run the installer after pulling changes.
-
-`settings.json` is merged. The template supplies defaults for keys the live file
-lacks, every value already present in the live file wins, and keys the template
-does not know about are preserved — so personal config (and anything pi itself
-wrote) survives re-install. The one key the CLI owns outright is `packages`: it
-is rebuilt from the template with the repo path entry resolved against the live
-settings file.
-
-Two consequences follow from that precedence:
-
-- **Template changes to non-`packages` keys never reach an existing install.**
-  Because the live value always wins, editing a default in `pi/settings.json`
-  only affects a fresh install (or a manually deleted live file) — edit the live
-  file to adopt a new default.
-- **`pi install npm:<pkg>` entries do not survive re-install.** `packages` is
-  rebuilt from the template, so any `npm:` package pi added to the live file is
-  dropped on the next `agent-cortex install pi`. Declare long-lived packages in
-  the repo template instead.
-
-An unparseable live `settings.json` is warned about and overwritten.
-`keybindings.json` follows a checksum rule: written from the template, refreshed
-when the template changes, and left untouched once you edit it by hand (delete
-it to re-adopt the template).
-
-### Pi package dependencies
-
-These packages are declared in the package manifest (`package.json` → `pi.packages`) and
-provisioned by `agent-cortex install pi`, so a clean `~/.pi` gets the tools they provide
-without a manual `pi install`. They are also declared in the template `pi/settings.json`,
-so the materialised `settings.json` registers them with pi.
-
-| Package | Version | Purpose |
-|---|---|---|
-| [`pi-web-access`](https://www.npmjs.com/package/pi-web-access) | 0.10.7 | Web search, URL fetching, GitHub repo access, PDF/YouTube/video analysis (`fetch_content`) |
-| [`pi-questions`](https://www.npmjs.com/package/pi-questions) | latest | Structured interactive questions (`ask_questions`) |
-
-Pass `--no-provision` to skip the package install step (e.g. offline machines); a
-missing `pi` CLI or failed install warns and leaves the rest of the install intact.
+Merge the version PR whenever its plan and diff look right, but approve its CI
+first: `changesets/action` pushes that branch with `GITHUB_TOKEN`, so GitHub parks
+the CI run the push creates behind **“Approve workflows to run”** — a run with no
+jobs, which reports nothing, so the merge box shows `BLOCKED` with an empty check
+list even though no gate has run or failed. Approving it from the merge box (or
+`gh api -X POST repos/{owner}/{repo}/actions/runs/<run-id>/approve`) starts the five
+required checks. Do it after the last merge to `main`, not once at the start of a
+release: every subsequent merge force-updates the version branch, and a new head
+brings a new parked run. This stays manual by design — letting the bot's push
+trigger CI on its own means a personal access token or GitHub App token, a
+long-lived credential in repository secrets to save one click per release.
 
-Desktop notifications are handled by the local `extensions/notify/` extension
-(replaces the former `pi-notify` dependency). It sends an OSC desktop
-notification on multi-turn tasks, labelled with the tmux session:window.pane
-if available, or the project directory name otherwise.
+## Installation
 
-### Pi harness agents & skills (`agent-cortex install pi`)
+### Pi package staging (`agent-cortex install pi`)
 
-The agents are already available to pi through the package (`pi.skills` + the
-`agent-modes` extension compose them at runtime), but the raw package files carry
-literal `{{TOOL:...}}` / `{{PATH:...}}` tokens. Run the pi installer to materialise
-composed agents and token-substituted skills into pi's user scope:
+`agent-cortex install pi` materialises agent-cortex as a self-contained pi
+package in `~/.agent-cortex/pi` — the pi analogue of `~/.agent-cortex/claude` —
+and registers that directory with pi through pi's own `pi install`. Nothing is
+generated into pi's own directories (`~/.pi/agent/…`): pi owns its settings
+file, so the installer only reads it to decide the plan and lets the `pi` CLI
+write it. Once the staged package is registered, the artifacts an older
+installer rendered there are swept (see below).
 
 ```sh
-agent-cortex install pi
-# → ~/.pi/agent/agents/<name>.agent.md (ralph, plan, ralph-plan, strategy)
-# → ~/.pi/agent/skills/  (token-substituted skill tree)
-# → ~/.pi/agent/settings.json + keybindings.json (merged from the repo templates)
+agent-cortex install pi          # stage ~/.agent-cortex/pi + register it with pi
 ```
 
-Flags:
+Registration is idempotent by state: the staged path is registered once (a
+re-run is a true no-op — a local package source is read from disk on every pi
+start, so nothing needs refreshing), and a source pointing at a raw agent-cortex
+checkout is removed first, so exactly one agent-cortex source stays configured.
+The installer decides that plan by reading pi's settings at
+`~/.pi/agent/settings.json`, so a pi agent dir relocated with
+`PI_CODING_AGENT_DIR` is not inspected — a superseded raw-repo source configured
+there has to be removed by hand with `pi remove <path>`.
+
+Under the old model the same installer rendered agents and skills into
+`~/.pi/agent/{agents,skills}`. Those copies are a second source of the same
+resource — the skill-collision diagnostics the staged model exists to remove —
+so once registration succeeds the installer removes the ones it can attribute to
+agent-cortex: `agents/<name>.agent.md` and `skills/<group>/<name>` for agents and
+skills this package ships or once shipped, and a `.agent-cortex-install.json`
+path record left there listing those copies. It is a one-time migration:
+attribution is by name, which cannot tell a rendered copy from a file you wrote
+under the same name, so once it has finished it records that in
+`~/.agent-cortex/legacy-sweep.json` — keyed by the pi user directory, never
+inside it — and never removes anything there again. A completed migration
+leaves `~/.pi/agent` with no agent-cortex file in it. Only a migration that
+removed every copy it attributed, from directories it could read, is recorded:
+a copy that could not be deleted (permissions, `EBUSY`) or a directory that
+could not be listed is warned about and retried on the next install, and a
+record that cannot be written is a warning, not a failed install. Anything
+whose name this package does not ship is left alone, and
+`~/.pi/agent/extensions` is never touched at all — no
+installer has written there, so its contents are yours. `--output <dir>` and
+`--dry-run` sweep nothing.
+The sweep follows the settings file the installer reads (`~/.pi/agent`): a pi
+agent dir relocated with `PI_CODING_AGENT_DIR` keeps its copies.
+
+The staged package contains:
+
+| Path | Contents |
+| --- | --- |
+| `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 |
+| `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 |
+
+The third-party packages supply the tools the agents need — `pi-questions`
+(`ask_questions`) and `pi-web-access` (`fetch_content`). They are ordinary
+runtime dependencies of this package and travel inside the staged tree, so pi
+loads them from a local directory without any npm resolution of its own. An
+unresolvable dependency fails the install rather than staging a package that
+cannot provide those tools. Re-staging clears the children the installer owns, so
+a re-run never accumulates stale copies.
 
 | Flag | Meaning |
 | --- | --- |
-| `--dry-run` | Show what would be installed without writing anything |
-| `--output <dir>` | Install into `<dir>/agents`, `<dir>/skills` and the config files (default `~/.pi/agent`) |
+| `--dry-run` | Show what would be staged and registered without writing or spawning anything |
+| `--output <dir>` | Stage into `<dir>` only — no registration (tests/CI) |
 | `--plugin-root <dir>` | Override the plugin root used for `{{PATH:...}}` tokens (default: token-map.json's pi value — use it for checkout or symlinked installs) |
-| `--no-provision` | Skip provisioning the third-party pi packages declared in `package.json` `pi.packages` (default: install them via the `pi` CLI) |
+| `--require-register` | Fail the install when the `pi` CLI cannot drive registration; by default a missing CLI warns and prints the commands to run |
+
+If the `pi` CLI is not on `PATH`, the staged package is correct but unregistered:
+the installer warns and prints the exact commands (`pi install
+~/.agent-cortex/pi`, plus a `pi remove` for any superseded raw-repo source).
+
+A superseded raw-repo source that `pi remove` cannot drop fails the install
+(non-zero, naming the source still configured): pi would load both sources, so
+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.
+
+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).
+
+### Desktop notifications
+
+Desktop notifications are handled by the local `extensions/notify/` extension
+(replaces the former `pi-notify` dependency). It sends an OSC desktop
+notification on multi-turn tasks, labelled with the tmux session:window.pane
+if available, or the project directory name otherwise.
+
+### Pi config files
 
-Re-run whenever you pull changes (`git pull` + reinstall, or after `pnpm build:copilot`).
+`pi/settings.json` and `pi/keybindings.json` are committed **reference
+templates** for your own pi configuration. They are not installer output: pi's
+`settings.json` and `keybindings.json` are pi's own user config, so
+`agent-cortex install pi` leaves them alone.
 
 ### Copilot plugin (separate)
 

package/agents/README.md

@@ -153,6 +153,16 @@ composes agent prompts on the fly from `agent.md` + `pi/frontmatter.json`, subst
 tokens against `token-map.json`'s pi column with no install step. See
 `extensions/agent-modes/README.md`.
 
+### Rendered tool lists are comma-separated
+
+pi's `parseFrontmatter` returns the `tools` scalar as one string, and its consumers split
+that string on commas — the subagent extension forwards it straight to `pi --tools`, whose
+parser is comma-separated too. Generated pi agents therefore render
+`tools: "bash, read, task"`; a space-separated list collapses to a single bogus name and
+leaves the agent with an allowlist matching no tool. Both parsers
+(`extensions/subagent/agents.ts`, `extensions/agent-modes/discover.ts`) accept whitespace
+as well, so either form round-trips safely.
+
 ## Composition Rules
 
 ### For Harnesses with Sections
@@ -216,8 +226,11 @@ flat `agents/*.agent.md` files are built from them:
   from `agents-native/ralph.md`, copied verbatim).
 - The pi harness delivers two ways: the `agent-modes` extension composes `agent.md` +
   `pi/frontmatter.json` at runtime against `token-map.json`, and `agent-cortex install pi`
-  materialises composed agents + token-substituted skills into `~/.pi/agent` at install
-  time (see README "Pi harness agents & skills").
+  renders flat pi agents + token-substituted skills into a self-contained package at
+  `~/.agent-cortex/pi`, which pi loads once registered (see README "Pi package staging
+  (`agent-cortex install pi`)"). `agent-modes` and the `subagent` extension both read agents
+  beside themselves,
+  so the staged package needs no `~/.pi/agent` writes.
 
 Never edit the generated flat materialised files by hand — edit the composable directory.
 Generation is install-time: `claude` ships
@@ -229,8 +242,8 @@ in `claude-extras/`), and CI validates the materialiser with structural checks o
 install; `copilot` ships via
 `bin/installers/copilot.mjs`, the shared code path behind both `agent-cortex install
 copilot` and `scripts/build-copilot-agents.mjs`; `pi` ships via
-`bin/installers/pi.mjs`, which materialises composed agents + token-substituted skills
-into `~/.pi/agent`.
+`bin/installers/pi.mjs`, which stages a self-contained pi package (manifest, rendered
+agents, token-substituted skills, extensions) at `~/.agent-cortex/pi`.
 
 ## Validation
 

package/bin/agent-cortex.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 import { parseArgs, buildHelpText, validateHarness } from "../lib/cli.mjs";
-import { installPi } from "./installers/pi.mjs";
+import { join, dirname } from "node:path";
+import { installPi, registerPi, sweepLegacyPiUserDirs } from "./installers/pi.mjs";
 
 const argv = process.argv.slice(2);
 const parsed = parseArgs(argv);
@@ -29,18 +30,41 @@ if (parsed.command === "install") {
   }
 
   if (parsed.harness === "pi") {
+    // A plain `agent-cortex install pi` stages the package into the home
+    // install root (~/.agent-cortex/pi) and registers that directory with pi
+    // through pi's own `pi install` (idempotent by state: a re-run is a no-op
+    // update); `--output <dir>` is the stage-only form (tests/CI) and prints
+    // the registration command instead.
     try {
       const result = await installPi({
         dryRun: parsed.dryRun ?? false,
-        // Third-party pi packages are only provisioned for a real install:
-        // --output is the generate-only form, --no-provision opts an offline
-        // machine out explicitly.
-        provisionPackages: parsed.output === undefined && !parsed.noProvision,
         warn: () => {}, // warnings surface once in the printed summary
         ...(parsed.output ? { output: parsed.output } : {}),
         ...(parsed.pluginRoot ? { pluginRoot: parsed.pluginRoot } : {}),
       });
       printPiInstall(result);
+      if (parsed.output === undefined) {
+        const registration = await registerPi({
+          output: result.output,
+          dryRun: parsed.dryRun ?? false,
+          requireRegister: parsed.requireRegister ?? false,
+          warn: (msg) => process.stdout.write(`  ⚠ ${msg}\n`),
+        });
+        // The old installer's rendered copies are only stale once the staged
+        // package is what pi loads — and nothing is deleted on a dry run. The
+        // flag is passed through as well, so the sweep's own guarantee does not
+        // depend on this guard staying in place.
+        if (registration.registered && !(parsed.dryRun ?? false)) {
+          printPiSweep(
+            await sweepLegacyPiUserDirs({
+              piUserDir: dirname(registration.settingsPath),
+              dryRun: parsed.dryRun ?? false,
+            }),
+          );
+        }
+      } else {
+        process.stdout.write(`  → register it with pi: pi install ${result.output}\n`);
+      }
     } catch (err) {
       process.stderr.write(`Install failed: ${err.message}\n`);
       process.exit(1);
@@ -106,20 +130,32 @@ if (parsed.command === "install") {
   process.exit(0);
 }
 
+function printPiSweep({ removed }) {
+  if (removed.length === 0) return;
+  process.stdout.write(
+    `  ✓ Removed ${removed.length} artifact(s) the pre-staged-model installer rendered into pi's user directory (one-time migration — the staged package is the source from now on)\n`,
+  );
+  for (const path of removed) {
+    process.stdout.write(`    - ${path}\n`);
+  }
+}
+
 function printPiInstall(result) {
   process.stdout.write(`Installing agent-cortex for "pi" harness…\n`);
+  process.stdout.write(`  ✓ Staged pi package → ${result.output}\n`);
   for (const agent of result.agents) {
     process.stdout.write(`  ✓ ${agent.name}.agent.md → ${agent.filePath}\n`);
   }
   process.stdout.write(`  ✓ Substituted ${result.skills.md} markdown file(s) across ${result.skills.skills} skill(s) → ${result.skills.dir}\n`);
-  printManagedConfig("settings.json", result.settings);
-  printManagedConfig("keybindings.json", result.keybindings);
-  // A dry run installs nothing, so report the plan — otherwise the documented
-  // "show what would be installed" contract prints no packages at all.
-  const packages = result.packages ?? { planned: [], installed: [] };
-  for (const source of result.dryRun ? packages.planned : packages.installed) {
-    process.stdout.write(`  ✓ ${result.dryRun ? "Would install" : "Installed"} pi package ${source}\n`);
+  process.stdout.write(`  ✓ Copied ${result.extensions.files} extension file(s) → ${result.extensions.dir}\n`);
+  for (const name of result.packages.bundled) {
+    process.stdout.write(`  ✓ Bundled pi package ${name} → ${join(result.packages.dir, name)}\n`);
+  }
+  const transitive = result.packages.staged.length - result.packages.bundled.length;
+  if (transitive > 0) {
+    process.stdout.write(`  ✓ Copied ${transitive} transitive dependency tree(s) → ${result.packages.dir}\n`);
   }
+  process.stdout.write(`  ✓ ${result.dryRun ? "Would write" : "Wrote"} ${result.manifest.path} (version ${result.manifest.manifest.version})\n`);
   for (const warning of result.warnings) {
     process.stdout.write(`  ⚠ ${warning}\n`);
   }
@@ -127,21 +163,3 @@ function printPiInstall(result) {
     process.stdout.write("(dry-run — nothing written)\n");
   }
 }
-
-/** Report one managed pi config file (settings.json / keybindings.json). */
-function printManagedConfig(label, info) {
-  if (!info) return;
-  if (info.action === "would-remove-symlink") {
-    process.stdout.write(`  → would remove symlink ${info.path} and write ${label}\n`);
-  } else if (info.action === "would-write") {
-    process.stdout.write(`  → would write ${label} → ${info.path}\n`);
-  } else if (info.action === "unchanged") {
-    process.stdout.write(`  · ${label} → ${info.path} (unchanged)\n`);
-  } else if (info.action === "skipped") {
-    process.stdout.write(`  ⚠ ${label} modified after install — left untouched → ${info.path}\n`);
-  } else if (info.action === "removed-symlink") {
-    process.stdout.write(`  ✓ ${label} → ${info.path} (removed legacy symlink)\n`);
-  } else {
-    process.stdout.write(`  ✓ ${label} → ${info.path}\n`);
-  }
-}