@jaybeeuu/agent-cortex 1.42.0 → 1.43.0

package/test/release-gates.test.mjs

@@ -0,0 +1,190 @@
+// Behaviour tests for the release gates that keep `main` from re-publishing a
+// version: the inverted PR changeset gate and the no-publish release gate.
+// The decision logic is pure; the two CLI adapters are exercised through their
+// process boundary because that is the contract CI depends on.
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+  PUBLISH_COMMAND,
+  NO_PUBLISH_COMMAND,
+  evaluateChangesetGate,
+  parseNameStatus,
+  resolvePublishCommand,
+} from "../scripts/lib/release-gates.mjs";
+
+const CHECK_CHANGESET = fileURLToPath(new URL("../scripts/check-changeset.mjs", import.meta.url));
+const RESOLVE_PUBLISH = fileURLToPath(
+  new URL("../scripts/resolve-publish-command.mjs", import.meta.url),
+);
+
+function runScript(script, { args = [], env = {}, stdin = "" } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [script, ...args], {
+      env: { ...process.env, ...env },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+    child.stdin.end(stdin);
+  });
+}
+
+describe("parseNameStatus", () => {
+  it("parses added and modified paths from git diff --name-status output", () => {
+    const changes = parseNameStatus("M\tpackage.json\nA\t.changeset/fix-release.md\n");
+
+    assert.deepEqual(changes, [
+      { status: "M", path: "package.json" },
+      { status: "A", path: ".changeset/fix-release.md" },
+    ]);
+  });
+
+  it("uses the new path for a rename", () => {
+    const changes = parseNameStatus("R087\t.changeset/old.md\t.changeset/new.md\n");
+
+    assert.deepEqual(changes, [{ status: "R", path: ".changeset/new.md" }]);
+  });
+
+  it("returns no changes for empty output", () => {
+    assert.deepEqual(parseNameStatus(""), []);
+  });
+});
+
+describe("evaluateChangesetGate", () => {
+  it("passes a PR that adds a changeset", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "A", path: ".changeset/fix-release.md" }],
+      labels: [],
+      headRef: "fix/release-gate",
+      actor: "jaybeeuu",
+    });
+
+    assert.deepEqual(result, { ok: true, reason: "changeset-added" });
+  });
+
+  it("fails a CI-only change that adds no changeset", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "M", path: ".github/workflows/ci.yml" }],
+      labels: [],
+      headRef: "chore/bump-pnpm",
+      actor: "jaybeeuu",
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, "missing-changeset");
+  });
+
+  it("fails a PR that only modifies an existing changeset", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "M", path: ".changeset/pending.md" }],
+      labels: [],
+      headRef: "chore/edit-changeset",
+      actor: "jaybeeuu",
+    });
+
+    assert.equal(result.ok, false);
+  });
+
+  it("fails a PR that only adds the changeset README", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "A", path: ".changeset/README.md" }],
+      labels: [],
+      headRef: "docs/changesets",
+      actor: "jaybeeuu",
+    });
+
+    assert.equal(result.ok, false);
+  });
+
+  it("passes an unlabelled-change PR carrying the no-publish label", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "M", path: ".github/workflows/ci.yml" }],
+      labels: ["no-publish"],
+      headRef: "chore/bump-pnpm",
+      actor: "jaybeeuu",
+    });
+
+    assert.deepEqual(result, { ok: true, reason: "no-publish-label" });
+  });
+
+  it("passes the Version Packages PR by head branch", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "M", path: "package.json" }],
+      labels: [],
+      headRef: "changeset-release/main",
+      actor: "jaybeeuu",
+    });
+
+    assert.deepEqual(result, { ok: true, reason: "version-packages-pr" });
+  });
+
+  it("passes a PR opened by the GitHub Actions bot", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "M", path: "package.json" }],
+      labels: [],
+      headRef: "automation/some-branch",
+      actor: "github-actions[bot]",
+    });
+
+    assert.deepEqual(result, { ok: true, reason: "version-packages-pr" });
+  });
+});
+
+describe("resolvePublishCommand", () => {
+  it("publishes by default when the merged PR has no labels", () => {
+    assert.equal(resolvePublishCommand([]), PUBLISH_COMMAND);
+  });
+
+  it("publishes when the merged PR carries unrelated labels", () => {
+    assert.equal(resolvePublishCommand(["bug", "priority:p2"]), PUBLISH_COMMAND);
+  });
+
+  it("refuses to publish when the merged PR carries the no-publish label", () => {
+    assert.equal(resolvePublishCommand(["bug", "no-publish"]), NO_PUBLISH_COMMAND);
+  });
+
+  it("matches the label exactly, not as a substring", () => {
+    assert.equal(resolvePublishCommand(["no-publish-ci"]), PUBLISH_COMMAND);
+  });
+});
+
+describe("check-changeset CLI", () => {
+  it("exits 0 for a no-publish PR with no diff", async () => {
+    const { code } = await runScript(CHECK_CHANGESET, {
+      env: { PR_LABELS: '["no-publish"]', PR_HEAD_REF: "chore/bump-pnpm", PR_ACTOR: "jaybeeuu" },
+    });
+
+    assert.equal(code, 0);
+  });
+
+  it("exits 1 and explains the no-publish escape hatch for a changeset-less PR", async () => {
+    const { code, stderr } = await runScript(CHECK_CHANGESET, {
+      stdin: "M\tpackage.json\n",
+      env: { PR_LABELS: "[]", PR_HEAD_REF: "chore/bump-pnpm", PR_ACTOR: "jaybeeuu" },
+    });
+
+    assert.equal(code, 1);
+    assert.match(stderr, /no-publish/);
+  });
+});
+
+describe("resolve-publish-command CLI", () => {
+  it("prints the noop command for a no-publish label set", async () => {
+    const { code, stdout } = await runScript(RESOLVE_PUBLISH, {
+      args: ['["no-publish"]'],
+    });
+
+    assert.equal(code, 0);
+    assert.equal(stdout.trim(), NO_PUBLISH_COMMAND);
+  });
+});

package/test/verify-worker-tree.test.mjs

@@ -0,0 +1,120 @@
+// Integration tests for scripts/lib/verify-worker-tree.mjs. The module exists to
+// tell a worker that delivered from one that only said it did, so each case runs
+// a real git repository and asserts the verdict — no mocking of git, because git
+// is the thing whose state the verdict is about.
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { verifyWorkerTree } from "../scripts/lib/verify-worker-tree.mjs";
+
+const execFileAsync = promisify(execFile);
+
+/** Run a git command in `cwd`. */
+async function git(cwd, args) {
+  await execFileAsync("git", args, { cwd });
+}
+
+/** A repository with one base commit; returns its directory and that commit. */
+async function createRepo() {
+  const dir = await mkdtemp(join(tmpdir(), "verify-worker-tree-"));
+  await git(dir, ["init", "--quiet"]);
+  await git(dir, ["config", "user.email", "t@example.com"]);
+  await git(dir, ["config", "user.name", "T"]);
+  // A developer's global config may enable commit signing; the fixture must not
+  // depend on a secret key being present.
+  await git(dir, ["config", "commit.gpgsign", "false"]);
+  await writeFile(join(dir, "README.md"), "base\n");
+  await git(dir, ["add", "-A"]);
+  await git(dir, ["commit", "-m", "base"]);
+  const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: dir });
+  return { dir, base: stdout.trim() };
+}
+
+/** Commit a file in the repo, as a delivering worker would. */
+async function commitWork(dir) {
+  await writeFile(join(dir, "worker-output.txt"), "delivered\n");
+  await git(dir, ["add", "-A"]);
+  await git(dir, ["commit", "-m", "worker: deliver"]);
+}
+
+describe("verifyWorkerTree", () => {
+  it("passes a worker that committed and left a clean tree", async () => {
+    const { dir, base } = await createRepo();
+    try {
+      await commitWork(dir);
+
+      const verdict = await verifyWorkerTree({ worktree: dir, base });
+
+      assert.deepEqual(verdict, { ok: true, reasons: [], commitsAhead: 1 });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("fails a worker that reported success but left its work uncommitted", async () => {
+    const { dir, base } = await createRepo();
+    try {
+      await writeFile(join(dir, "left-behind.txt"), "uncommitted\n");
+
+      const verdict = await verifyWorkerTree({ worktree: dir, base });
+
+      assert.equal(verdict.ok, false);
+      assert.equal(verdict.reasons[0], "worktree is dirty: 1 uncommitted path(s)");
+      assert.equal(verdict.commitsAhead, 0);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("fails a worker that left a clean tree with nothing committed", async () => {
+    const { dir, base } = await createRepo();
+    try {
+      const verdict = await verifyWorkerTree({ worktree: dir, base });
+
+      assert.equal(verdict.ok, false);
+      assert.equal(verdict.reasons.length, 1);
+      assert.match(verdict.reasons[0], /^no commit ahead of base [0-9a-f]{7}$/);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("reports a dirty tree and a missing commit together", async () => {
+    const { dir, base } = await createRepo();
+    try {
+      await writeFile(join(dir, "partial.txt"), "half done\n");
+
+      const verdict = await verifyWorkerTree({ worktree: dir, base });
+
+      assert.equal(verdict.ok, false);
+      assert.equal(verdict.reasons.length, 2);
+      assert.equal(verdict.reasons[0], "worktree is dirty: 1 uncommitted path(s)");
+      assert.match(verdict.reasons[1], /^no commit ahead of base [0-9a-f]{7}$/);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("counts every commit the worker made, not just the last", async () => {
+    const { dir, base } = await createRepo();
+    try {
+      await commitWork(dir);
+      await writeFile(join(dir, "second.txt"), "more\n");
+      await git(dir, ["add", "-A"]);
+      await git(dir, ["commit", "-m", "worker: second"]);
+
+      const verdict = await verifyWorkerTree({ worktree: dir, base });
+
+      assert.equal(verdict.ok, true);
+      assert.equal(verdict.commitsAhead, 2);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/token-map.README.md

@@ -15,14 +15,14 @@ decisions behind the map.
 | id | Platform | Agent format | Plugin root |
 |---|---|---|---|
 | `copilot` | GitHub Copilot CLI | `agents/<name>/` composable dirs → generated `agents/*.agent.md` | `~/.copilot/installed-plugins/_direct/agent-cortex` |
-| `pi` | pi coding agent | `agents/<name>/` composable dirs (composed at runtime by agent-modes, or installed install-time by `agent-cortex install pi`) | `~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex` |
+| `pi` | pi coding agent | `agents/<name>/` composable dirs (composed at runtime by agent-modes, or rendered install-time by `agent-cortex install pi`) | `~/.agent-cortex/pi` |
 | `claude` | Claude Code | `~/.agent-cortex/claude/agents/*.md` (materialised home install) | `${CLAUDE_PLUGIN_ROOT}` (env var) |
 
 The harness ids match the values accepted by `agent-cortex install <harness>` in
-`lib/cli.mjs` (`SUPPORTED_HARNESSES`). The pi `plugin_root` row is the npm-layout
-literal that `agent-cortex install pi` uses by default; local checkout and symlinked
-installs pass `--plugin-root <dir>` to override it (see README "Pi harness agents &
-skills").
+`lib/cli.mjs` (`SUPPORTED_HARNESSES`). The pi `plugin_root` row is the staged package
+directory `agent-cortex install pi` materialises, which pi then loads by path; checkout
+and symlinked installs pass `--plugin-root <dir>` to override it (see README "Pi package
+staging (`agent-cortex install pi`)").
 
 ## Design decisions
 
@@ -49,7 +49,8 @@ rather than inventing a dotted form:
   column, consumed by `bin/installers/claude.mjs` (the install-time generator — PR #91, #92); the pi column is grounded
   in pi's documented built-in tool surface (`read`, `bash`, `edit`, `write`, `grep`, `find`,
   `ls`) plus `ask_questions` — added by the pi-questions package (mapped from
-  `ask_user`) — and `task` / `read_agent` / `wait_for_agents` subagent tools; `skill` maps
+  `ask_user`) — and `task` / `read_agent` / `wait_for_agents` subagent tools, the last three
+  supplied by this repo's own `extensions/subagent` rather than by pi; `skill` maps
   to `read` (skills load by reading the listed SKILL.md path).
 - **`paths`** — `plugin_root`, `agents_dir`, and `skills_dir`. These are the install-time
   variables that differ per harness. `plugin_root` is the anchor; the other two resolve

package/token-map.json

@@ -31,7 +31,7 @@
     "plugin_root": {
       "copilot": "~/.copilot/installed-plugins/_direct/agent-cortex",
       "claude": "${CLAUDE_PLUGIN_ROOT}",
-      "pi": "~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex"
+      "pi": "~/.agent-cortex/pi"
     },
     "agents_dir": {
       "copilot": { "base": "plugin_root", "relative": "agents" },
@@ -63,14 +63,15 @@
     "tools": {
       "rg": "Copilot alias for grep. Claude and pi collapse it onto their single search tool (Grep / grep) — same collapse rule as the build script.",
       "glob": "Claude has a dedicated Glob tool. pi's built-in pattern-search tool is find (hypa_find when the pi-hypa extension is installed).",
-      "ask_user": "Copilot (ask_user) and Claude (AskUserQuestion) prompt the user mid-run. pi's equivalent is ask_questions, provided by the pi-questions package (declared in the package manifest — package.json pi.packages — and provisioned by agent-cortex install pi; also declared in pi/settings.json for the symlinked checkout) — the genuine interactive-questioning tool, restoring grilling in plan/ralph-plan/strategy modes. Like fetch_content (pi-web-access), it is only present when its package is installed, so the mapping depends on that package (see the extension-manifests idea). pi still intentionally ships no permission popups; ask_questions is the interactive mid-run question tool, not a popup.",
-      "web_fetch": "pi's fetch_content comes from the pi-web-access package (declared in the package manifest — package.json pi.packages — and provisioned by agent-cortex install pi).",
+      "ask_user": "Copilot (ask_user) and Claude (AskUserQuestion) prompt the user mid-run. pi's equivalent is ask_questions, provided by the pi-questions package (an ordinary runtime dependency of this package that `agent-cortex install pi` bundles into the staged package's node_modules) — the genuine interactive-questioning tool, restoring grilling in plan/ralph-plan/strategy modes. Like fetch_content (pi-web-access), it is only present when its package is installed, so the mapping depends on that package (see the extension-manifests idea). pi still intentionally ships no permission popups; ask_questions is the interactive mid-run question tool, not a popup.",
+      "web_fetch": "pi's fetch_content comes from the pi-web-access package (an ordinary runtime dependency of this package that `agent-cortex install pi` bundles into the staged package's node_modules).",
       "skill": "Copilot (skill) and Claude (Skill) expose skills as a tool. pi has no dedicated skill tool — skills are surfaced in the always-present 'Available skills' context block and loaded by reading the listed SKILL.md path ({{PATH:<skill>/SKILL.md}}). The pi mapping is read, the tool used to load a skill's file; a dedicated skill tool is a follow-on design candidate if prompting proves insufficient.",
-      "read_agent": "Claude's Task returns results inline — there is no separate read step, so read_agent drops on claude (null). Copilot uses the task + read_agent poll loop; pi blocks on wait_for_agents and keeps read_agent as a fallback.",
+      "read_agent": "Claude's Task returns results inline — there is no separate read step, so read_agent drops on claude (null). Copilot uses the task + read_agent poll loop; pi exposes read_agent as a fallback to wait_for_agents.",
+      "task": "Copilot and Claude provide a subagent tool natively. On pi it is supplied by this repo's own extensions/subagent extension (which also registers read_agent and wait_for_agents), not by pi itself — a pi session started before that extension was installed has no dispatch tool at all. Skills must therefore stop and report a missing subagent tool rather than improvising a backgrounded CLI run, which has no completion signal.",
       "wait_for_agents": "PI-only blocking wait over background subagent runs (the task tool): returns the results of completed agents and STILL RUNNING for the rest. Copilot has no equivalent tool (its task + read_agent poll loop stays) and Claude's Task delivers results inline with no wait step — both null."
     },
     "paths": {
-      "pi": "plugin_root defaults to the npm-package install layout (~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex). Local-checkout installs (pi/settings.json packages entry referencing a local src path) or symlinked installs differ — installers must compute plugin_root from the actual resolution and can override it.",
+      "pi": "plugin_root is the staged package `agent-cortex install pi` materialises at ~/.agent-cortex/pi; pi loads that directory by path and the shipped extensions resolve their own resources relative to it (agent-modes computes plugin_root from its actual install location). A checkout or symlinked install differs — installers compute plugin_root from the actual resolution and can override it (--plugin-root).",
       "claude": "plugin_root stays ${CLAUDE_PLUGIN_ROOT} (env var) for the materialised plugin — never a literal ~/.agent-cortex/claude. Claude Code copies marketplace-installed plugins (including local directory sources like ~/.agent-cortex/claude) into its own cache and expands the env var per context, so a literal home path in substituted files would break under cache-copy; the installer passes the env form through verbatim."
     },
     "agents": {

package/extensions/session-start.ts

@@ -1,44 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadSessionContext } from "./lib/context-loader.js";
-
-/**
- * Session-start extension.
- *
- * Injects baseline context at the start of every PI session:
- * 1. Skill availability hints (so the agent knows they exist)
- * 2. Project context files (AGENTS.md, user-preferences.md)
- *
- * Context files are read dynamically from the project root (cwd).
- */
-export default function (pi: ExtensionAPI) {
-  pi.on("before_agent_start", async (_event, ctx) => {
-    const skillHints = [
-      "Available skills — invoke when relevant (not pre-loaded to save context):",
-      "",
-      "• /skill:using-agent-skills — meta-skill that routes to the right skill",
-      "  and enforces core agent behaviors. Check this first if unsure.",
-      "",
-      "• /skill:bd-tool — project context & task tracking with beads.",
-      "  Run `bd ready` to see available work.",
-      "",
-      "• /skill:git-workflow — git discipline: feature branches,",
-      "  worktrees for solo AFK work, PR workflow, and when to ask.",
-      "",
-      "Read the SKILL.md for full instructions when needed.",
-    ].join("\n");
-
-    const contextFiles = loadSessionContext(ctx.cwd);
-
-    const content = contextFiles
-      ? `${skillHints}\n\n---\n\n${contextFiles}`
-      : skillHints;
-
-    return {
-      message: {
-        customType: "session-start",
-        content,
-        display: false,
-      },
-    };
-  });
-}

package/lib/pi-packages.mjs

@@ -1,169 +0,0 @@
-// Pi third-party package provisioning.
-//
-// agent-cortex's pi harness needs tools that live in third-party pi packages:
-// ask_questions comes from pi-questions, fetch_content from pi-web-access (see
-// token-map.json notes and docs/ideas/extension-manifests.md). Those packages
-// are declared in the package manifest — package.json → pi.packages — and this
-// module makes them real: `agent-cortex install pi` reads the declaration and
-// installs any package the pi user scope is missing.
-//
-// Provisioning goes through the pi CLI (`pi install <source>`), which both
-// installs the package under ~/.pi/agent/npm and declares it in
-// ~/.pi/agent/settings.json — the same store pi loads packages from. It is
-// opt-in (installPi option `provisionPackages`) and idempotent: a package that
-// is already declared and installed is skipped. A failed install warns and the
-// rest continue, so an offline machine never breaks the agent install.
-
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-import { spawn } from "node:child_process";
-
-const DEFAULT_WARN = (msg) => console.warn(`[pi-packages] ${msg}`);
-
-/**
- * Read the pi package sources agent-cortex declares it needs.
- *
- * @param {string} root Package root containing package.json
- * @returns {Promise<string[]>} Declared sources, e.g. ["npm:pi-questions"]
- */
-export async function loadRequiredPackages(root) {
-  const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf-8"));
-  const packages = manifest?.pi?.packages;
-  return Array.isArray(packages) ? packages.filter((entry) => typeof entry === "string") : [];
-}
-
-/**
- * Extract the npm package name from a pi source string.
- *
- * @param {string} source e.g. "npm:pi-web-access@0.10.7", "npm:@scope/pkg"
- * @returns {string | null} The name, or null for sources we cannot inspect locally
- */
-export function npmSourceName(source) {
-  if (typeof source !== "string" || !source.startsWith("npm:")) return null;
-  const spec = source.slice("npm:".length);
-  const at = spec.lastIndexOf("@");
-  return at > 0 ? spec.slice(0, at) : spec;
-}
-
-/**
- * Decide which required packages still need installing.
- *
- * A package is satisfied only when it is both declared in settings (so pi loads
- * it) and present in the npm store (so it is installed) — otherwise it needs a
- * `pi install` to reconcile.
- *
- * @param {string[]} required
- * @param {{ declaredSources: string[], installedNames: string[] }} state
- * @returns {string[]} The sources still to install
- */
-export function planPackageInstalls(required, { declaredSources, installedNames }) {
-  const declared = new Set(declaredSources.map(npmSourceName).filter(Boolean));
-  const installed = new Set(installedNames);
-  return required.filter((source) => {
-    const name = npmSourceName(source);
-    return name === null || !declared.has(name) || !installed.has(name);
-  });
-}
-
-/**
- * Install every required package the pi user scope is missing.
- *
- * @param {object} options
- * @param {string[]} options.required        Declared pi sources (see loadRequiredPackages)
- * @param {string} options.piRoot            Pi user scope dir (default ~/.pi/agent)
- * @param {boolean} [options.dryRun]         Report the plan without installing
- * @param {(source: string) => Promise<{ok: boolean, error: string | null}>} [options.runInstall]
- * @param {(msg: string) => void} [options.warn]
- * @returns {Promise<{planned: string[], installed: string[], failed: {source: string, error: string}[]}>}
- */
-export async function provisionPiPackages({
-  required,
-  piRoot,
-  dryRun = false,
-  runInstall = runPiInstall,
-  warn = DEFAULT_WARN,
-}) {
-  const declaredSources = await readDeclaredSources(join(piRoot, "settings.json"));
-  const installedNames = await readInstalledNames(join(piRoot, "npm", "node_modules"));
-  const planned = planPackageInstalls(required, { declaredSources, installedNames });
-
-  if (dryRun) return { planned, installed: [], failed: [] };
-
-  const installed = [];
-  const failed = [];
-  for (const source of planned) {
-    const result = await runInstall(source);
-    if (result.ok) {
-      installed.push(source);
-    } else {
-      failed.push({ source, error: result.error });
-      warn(`could not install pi package ${source}: ${result.error}`);
-    }
-  }
-  return { planned, installed, failed };
-}
-
-/** Install one pi package source through the pi CLI. */
-export function runPiInstall(source) {
-  return new Promise((resolve) => {
-    const child = spawn("pi", ["install", source], { stdio: ["ignore", "pipe", "pipe"] });
-    let stderr = "";
-    child.stdout.resume(); // drain; only failures are interesting
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk;
-    });
-    child.on("error", (err) => {
-      resolve({
-        ok: false,
-        error: err.code === "ENOENT" ? "pi CLI not found on PATH" : err.message,
-      });
-    });
-    child.on("close", (code) => {
-      resolve({
-        ok: code === 0,
-        error: code === 0 ? null : stderr.trim() || `pi install exited with code ${code}`,
-      });
-    });
-  });
-}
-
-// ─── Pi user-scope inspection ────────────────────────────────────────────────
-
-/** Read the package sources declared in a pi settings.json (missing or unreadable → none). */
-async function readDeclaredSources(settingsPath) {
-  let settings;
-  try {
-    settings = JSON.parse(await readFile(settingsPath, "utf-8"));
-  } catch {
-    // Nothing declared yet, or a file pi itself owns and repairs. Provisioning is
-    // a non-essential step — it must never fail the agent install.
-    return [];
-  }
-  const packages = Array.isArray(settings?.packages) ? settings.packages : [];
-  return packages
-    .map((entry) => (typeof entry === "string" ? entry : entry?.source))
-    .filter((source) => typeof source === "string");
-}
-
-/** List installed package names in the pi npm store (missing dir → none). */
-async function readInstalledNames(nodeModulesDir) {
-  let entries;
-  try {
-    entries = await readdir(nodeModulesDir, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === "ENOENT") return [];
-    throw err;
-  }
-  const names = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    if (!entry.name.startsWith("@")) {
-      names.push(entry.name);
-      continue;
-    }
-    for (const scoped of await readdir(join(nodeModulesDir, entry.name), { withFileTypes: true })) {
-      if (scoped.isDirectory()) names.push(`${entry.name}/${scoped.name}`);
-    }
-  }
-  return names;
-}