pier-setup 0.2.5 → 0.2.6

package/README.md

@@ -90,12 +90,39 @@ herdr plugin link ./packages/pier-workbench                        # development
 
 The extension degrades gracefully outside a herdr environment (see Scope below).
 
-### Scope (only the herdr × pi intersection is affected)
+### Scope (what the pi extension mutates)
+
+`pi-pier` is not dormant outside herdr. After install it is live in every pi session:
+
+| Surface | Bare `pi` | Inside herdr |
+|---|---|---|
+| `todo_write`, `/todos`, widget, anti-freeze, stop reminder | live | live |
+| `ask_user_question` | live | live + blocked marker |
+| Hidden inject (`before_agent_start` todo-read; settle reminder) | live | live |
+| `subagent`, `terminal` | **not registered** | live |
+| `/locks`, write-lock, slim-frame, pane title, pipe | off | live |
+| `setActiveTools` role visible layer | off | on (herdr master) |
+
+Session JSONL custom types (`pi-herdr.todo-edit`, `.subs`, `.terminals`, `.todo-read`, `.todo-reminder`, …) persist across `/resume` even without herdr.
+
+### Plugin conflicts
+
+pi overwrites tools/commands by name; event listeners stack. Two todo or subagent plugins will silently replace each other.
+
+**Do not install alongside** (same-name overwrite → wrong handler, split JSONL):
+
+- [`@nguyenquangthai/pi-todo`](https://pi.dev/packages/@nguyenquangthai/pi-todo) — `todo_write` + overlay
+- [`@josephyoung/pi-ask-user-question`](https://pi.dev/packages/@josephyoung/pi-ask-user-question) — `ask_user_question`
+- [`pi-herdr-subagents`](https://pi.dev/packages/pi-herdr-subagents) — `subagent` + herdr panes
+
+**Soft conflict** (two orchestrators / two injectors — the agent “talks to itself”):
+
+- [`@tintinweb/pi-subagents`](https://pi.dev/packages/@tintinweb/pi-subagents) (`Agent`)
+- [`@minhduydev/pi-subagents`](https://pi.dev/packages/@minhduydev/pi-subagents) (`task`)
+- any other extension that calls `setActiveTools`, `ui.custom` overlay, `before_agent_start`, or `sendUserMessage`/`sendMessage` followUp
+
+**Designed coexistence:** herdr’s official `herdr:pi` reporter. Keep it. pier emits `herdr:blocked` so that plugin remains lifecycle authority.
 
-- **pi outside herdr**: the extension degrades — reporting is free, workbench tools
-  (`subagent`, terminal family) return a clear "requires a herdr-managed pane" error;
-  `todo_write` / `ask_user_question` stay available (session JSONL is the authority,
-  no herdr dependency).
 - **other agents inside herdr (claude code / codex etc.)**: tabs without a pi pane
   are excluded from heat reflow; blocked notifications are pi-only; master-tab
   auto-bootstrap can be disabled with `autoBootstrap: false` in boot-config.

package/install.mjs

@@ -86,8 +86,17 @@ function which(bin) {
   }
 }
 
-function run(cmd, args) {
-  return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+function run(cmd, args, opts = {}) {
+  // win32: npm 全局 bin 是 .cmd shim，无 shell 直接 spawn 会 ENOENT/EINVAL，须走 cmd.exe；
+  // 且 shell:true 时 Node 把 args 按空格裸拼接（不加引号），含空格的路径参数会被拆碎，故预拼接并加引号。
+  // POSIX 走原生分支，保持 execFileSync(cmd, args) 原语义。
+  if (IS_WIN) {
+    const cmdline = [cmd, ...args]
+      .map((a) => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a))
+      .join(' ');
+    return execFileSync(cmdline, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], shell: true, ...opts }).trim();
+  }
+  return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts }).trim();
 }
 
 function tryRun(cmd, args) {
@@ -126,9 +135,7 @@ function readPkgVersion(dir) {
 
 function npmLatest(name) {
   try {
-    return execFileSync('npm', ['view', name, 'version'], {
-      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15000,
-    }).trim();
+    return run('npm', ['view', name, 'version'], { timeout: 15000 });
   } catch {
     return null;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pier-setup",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "One-shot installer for pier: install / update / version / uninstall for pi-pier + pier.workbench",
   "license": "MIT",
   "type": "module",