pi-crew 0.9.47 → 0.9.48

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 > **Note:** `atomic-write-v2.ts` / `AtomicWriter` mentioned in historical entries below was consolidated into `atomic-write.ts` as of v0.9.42. This changelog is preserved as historical record — the migration was completed (the v2 class was never adopted; v1 won on simplicity + symlink-safety + link+unlink atomicity). See `docs/migration/atomic-write-v2-migration.md` for the decision rationale.
 
 
+## [0.9.48] — Fix postinstall skill-collision regression (2026-07-24)
+
+Removes the `copySkills()` postinstall step introduced in v0.9.47. That step
+redundantly copied every `skills/<name>/` to `~/.pi/agent/skills/`, but **Pi
+already discovers skills natively from the npm package dir**
+(`~/.pi/agent/npm/node_modules/pi-crew/skills/`). The duplication caused 31
+"skill collision" warnings on every Pi startup (user-level copy shadowing the
+package version).
+
+- **`scripts/postinstall.mjs`**: `copySkills()` **removed**. Replaced with
+  `cleanupStaleSkillCopies()`, a one-time migration that removes the stale
+  copies created by v0.9.47's `copySkills()` — but **only byte-identical**
+  copies (a skill the user has customized is preserved). On upgrade, this
+  silently removes the 31 stale copies and clears the collisions. Verified:
+  31 identical→remove, `pi-fork-sync` (user-only) untouched.
+
+### Verification
+
+- `npm run test:critical` → 97/97 pass.
+- Cleanup dry-run: 31/31 stale copies identified as byte-identical → safe removal.
+- User-only skill (`pi-fork-sync`) correctly preserved.
+
+
 ## [0.9.47] — Broker Phase 4 gated ON (default-on flip) (2026-07-22)
 
 Flips `broker.enabled` from `false` to `true` as the new default on Linux
@@ -41,10 +64,10 @@ native Windows). Three independent kill switches remain available:
   sync → live TUI probing via tmux/pty → smoke team run). 659 lines, 26
   sections, 15 triggers. Bundled `scripts/pty_probe.py` (174-line hardened
   TUI probe with zombie reaping).
-- **`scripts/postinstall.mjs`**: new `copySkills()` step mirrors every
-  `skills/<name>/` dir to `~/.pi/agent/skills/` on install, so pi-crew's
-  skills are available globally (not just inside the pi-crew project).
-  Best-effort, never fails the install.
+- **`scripts/postinstall.mjs`**: ~~new `copySkills()` step mirrors every
+  `skills/<name>/` dir to `~/.pi/agent/skills/`~~ **(reverted in v0.9.48 —
+  Pi discovers skills natively from the npm package; copying only created
+  collision warnings).** See v0.9.48 below.
 
 ### Verification
 

package/README.md

@@ -291,7 +291,7 @@ The advisory is **informational only** — there is no `force:true` flag needed
 - **Broker default-on**: `broker.enabled` flipped `false` → `true` on Linux + macOS. The inter-pi broker lets concurrent Pi sessions exchange messages, steering notes, and task-status events over a Unix-domain socket. Three kill switches remain: config `broker.enabled: false`, env `PI_CREW_BROKER=0` (always wins), Windows auto-disable.
 - **Verifier-hang fix**: `npm run test:critical` — a curated 14-file / 97-test subset (~20s) replaces full `npm test` (>4 min) in verifier prompts. The full suite was exceeding the 300s `RESPONSE_TIMEOUT_MS`, killing workers with exit 143. Both plan-templates and all 4 workflow verifier prompts now specify the fast command.
 - **`real-test-pi-crew` skill** (659 lines): distills the 8-tier verification discipline used to ship this release (critical tests → 3-path kill-switch proof → typecheck/bundle → bundle md5 sync → live TUI probing via tmux/pty → smoke team run). Bundled `scripts/pty_probe.py`.
-- **Postinstall `copySkills()`**: `npx pi install .` now mirrors every `skills/<name>/` to `~/.pi/agent/skills/` for global availability.
+- **Postinstall skill-collision fix**: v0.9.47's `copySkills()` (which mirrored skills to `~/.pi/agent/skills/`) caused 31 "collision" warnings — Pi already discovers skills natively from the npm package. v0.9.48 removes `copySkills()` and adds a safe byte-identical cleanup (`cleanupStaleSkillCopies()`) that clears the stale copies on upgrade. User-customized skills are preserved.
 - See [CHANGELOG.md](CHANGELOG.md) §0.9.47 and [docs/decisions/2026-07-22-broker-phase4-gated-on.md](docs/decisions/2026-07-22-broker-phase4-gated-on.md).
 
 ### v0.9.45 – v0.9.46 (2026-07-20): security + perf remediation, UI stability

package/docs/publishing.md

@@ -71,8 +71,11 @@ pi install npm:pi-crew
 1. Builds the ESM bundle (`scripts/build-bundle.mjs`) — best-effort, falls
    back to strip-types loading if esbuild is missing.
 2. Installs the bundled `crew-vibes.ttf` font into the user fonts directory.
-3. Copies every `skills/<name>/` dir to `~/.pi/agent/skills/` so pi-crew's
-   skills are available globally (not just inside the pi-crew project).
+3. Runs `cleanupStaleSkillCopies()` — a one-time migration that removes
+   stale skill copies from `~/.pi/agent/skills/` left by v0.9.47's (now-removed)
+   `copySkills()` step. Only removes **byte-identical** copies; user-customized
+   skills are preserved. Pi discovers skills natively from the npm package's
+   own `skills/` dir, so copies are never needed.
 
 All three steps are best-effort and never fail the install.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.47",
+  "version": "0.9.48",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/scripts/postinstall.mjs

@@ -6,13 +6,17 @@
  *      let Pi fall back to strip-types loading).
  *   2. Install the bundled crew-vibes.ttf into the user fonts directory so
  *      the crew-vibes speed/capacity PUA glyphs render.
- *   3. Copy bundled skills to ~/.pi/agent/skills/ so they are available
- *      globally (not just inside the pi-crew project).
+ *   3. Remove stale skill copies from ~/.pi/agent/skills/ (migration from
+ *      the v0.9.47 copySkills() bug — see cleanupStaleSkillCopies()).
  *
  * Replaces the old `postinstall` shell chain so the font install runs on
  * every platform without relying on shell-specific chaining (`;`/`&&`).
+ *
+ * NOTE: skills are NOT copied here. Pi discovers skills natively from the
+ * npm package dir (`~/.pi/agent/npm/node_modules/pi-crew/skills/`); copying
+ * them to ~/.pi/agent/skills/ only creates duplicate "collision" warnings.
  */
-import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -29,32 +33,53 @@ function run(scriptRel) {
 }
 
 /**
- * Copy each skill directory from pi-crew/skills/ to ~/.pi/agent/skills/.
- * Best-effort: must never fail the install.
+ * Remove stale skill copies from ~/.pi/agent/skills/ that are byte-identical
+ * to the bundled skills/ — left over from the v0.9.47 copySkills() postinstall
+ * (which redundantly copied all skills, causing "collision" warnings).
+ *
+ * Pi discovers skills natively from the npm package dir, so these copies only
+ * create noise AND can shadow newer package versions on upgrade.
+ *
+ * SAFE: only removes EXACT (byte-identical) copies. A skill the user has
+ * customized (differs from the package) is preserved. Best-effort, never
+ * fails the install.
  */
-function copySkills() {
+function cleanupStaleSkillCopies() {
 	const srcSkillsDir = join(root, "skills");
 	if (!existsSync(srcSkillsDir)) return;
 
 	const destSkillsDir = join(homedir(), ".pi", "agent", "skills");
-	try {
-		mkdirSync(destSkillsDir, { recursive: true });
-	} catch {
-		return; // can't create dest — skip silently
-	}
+	if (!existsSync(destSkillsDir)) return;
 
+	let removed = 0;
+	let kept = 0;
 	for (const entry of readdirSync(srcSkillsDir, { withFileTypes: true })) {
 		if (!entry.isDirectory()) continue;
-		const skillMd = join(srcSkillsDir, entry.name, "SKILL.md");
-		if (!existsSync(skillMd)) continue;
+		const srcSkillMd = join(srcSkillsDir, entry.name, "SKILL.md");
+		if (!existsSync(srcSkillMd)) continue;
+		const destSkillDir = join(destSkillsDir, entry.name);
+		const destSkillMd = join(destSkillDir, "SKILL.md");
+		if (!existsSync(destSkillMd)) continue;
 		try {
-			cpSync(join(srcSkillsDir, entry.name), join(destSkillsDir, entry.name), {
-				recursive: true,
-			});
+			const srcContent = readFileSync(srcSkillMd, "utf8");
+			const destContent = readFileSync(destSkillMd, "utf8");
+			if (srcContent === destContent) {
+				rmSync(destSkillDir, { recursive: true, force: true });
+				removed++;
+			} else {
+				// User customized this skill — preserve it.
+				kept++;
+			}
 		} catch {
 			// best-effort: skip this skill on error
 		}
 	}
+	if (removed > 0) {
+		const note = kept > 0 ? ` (${kept} customized copy(ies) preserved)` : "";
+		console.warn(
+			`[pi-crew] postinstall: removed ${removed} stale skill cop${removed === 1 ? "y" : "ies"} from ~/.pi/agent/skills/${note}.`,
+		);
+	}
 }
 
 function main() {
@@ -74,8 +99,8 @@ function main() {
 		}
 		// Font install is best-effort and must never fail the install.
 		run("scripts/install-crew-vibes-font.mjs");
-		// Copy bundled skills to ~/.pi/agent/skills/ for global availability.
-		copySkills();
+		// Migration cleanup: remove stale skill copies from v0.9.47's copySkills().
+		cleanupStaleSkillCopies();
 	} catch (err) {
 		// Postinstall must NEVER fail the install (SEC-M2).
 		console.warn("[pi-crew] postinstall: best-effort step failed:", err instanceof Error ? err.message : err);