pier-setup 0.2.7 → 0.3.1

package/README.md

@@ -19,18 +19,25 @@ pier ships as **two halves**, installed separately:
 | Half | Package | Role |
 |---|---|---|
 | **pi extension** | `packages/pier-ext` (npm: [`pi-pier`](https://www.npmjs.com/package/pi-pier), [pi.dev gallery](https://pi.dev/packages/pi-pier)) | Injects `todo_write` / `subagent` / `terminal` / `ask_user_question` tools into a pi session, and reports pane state over the herdr socket API |
-| **herdr plugin** | `packages/pier-workbench` (`pier.workbench`) | Workspace bootstrap, blocked human-gate notifications, focus heat layout (focused pane grows in place) |
+| **herdr plugin** | `packages/pier-workbench` (`pier.workbench`) | Blocked human-gate notifications, focus heat layout (focused pane grows in place), ops dashboard + sidebar agent view |
 
 ### Highlights
 
 - **Todo loop**: `todo_write` with full-replace semantics, session JSONL as source of truth, correct branch rollback; live pane-title projection `▶i ○p ■b ✓c (N/M) · current task`; TUI widget is an activity-anchored window (the in_progress entry and its surrounding context stay visible as work moves down the list); `/todos` command (including unblock)
 - **Todo anti-freeze**: an all-completed list unchanged for ≥6 turns flips the read hook from recitation to a rewrite warning; after ≥1h it archives — first offering one rewrite window with old entries as reference, then (if ignored) a final notice that clears the list (rm persisted to JSONL; the empty guard takes over — multi-step work must re-track); `/todos` still shows history, session JSONL untouched
 - **Interactive subagents**: every subagent = an isolated pi session in its own pane (separate context window); **a human can enter that pane and talk to it directly** (fix bugs, take over, answer ask_user_question)
-- **Soft write-locks**: per-pane lock tokens on write paths; cross-pane conflicts warn or block
+- **Subagent output preview**: `subagent(action: "output", agentId)` returns what a running background subagent has printed since the previous call — an in-memory per-pane cursor computes the delta (`agent.read`, falling back to `pane.read` on older herdr), and the result carries status, revision, truncation and a `restart` flag for scrolled/cleared buffers, so the master can notice a stuck worker instead of waiting for settlement
+- **Soft write-locks**: per-pane lock beacons on `write`/`edit` paths; cross-pane conflicts warn (default) or block (`PI_HERDR_WRITE_LOCK=1`). The warning lists every holder; `/locks` is the human view of the same table (`herdr agent list` exposes the raw tokens to agents)
 - **Role profiles**: built-in `master` / `worker-default`; custom roles as `.pi-herdr/roles/<name>.json`; toolset converges per role (deny rules are not bypassable)
 - **Human gate**: subagent `ask_user_question` → sidebar blocked marker + notification; manual takeover (ESC-interrupt then typing) is heuristically detected so the master pauses/returns management automatically
+- **Ask picker**: every choice question renders through one pier-owned picker in the TUI — single-select (arrows + enter/space pick the highlighted row) and `multi: true` toggle list (checkboxes: space toggles, `a` toggles all, live selection count) share the same framed chrome, `recommended` seeds the cursor (and pre-checks in multi), and the free-text row stays last; `allowOther: false` gives pure choice. The host select dialog and typed-index prompts remain the fallbacks for RPC mode and older pi
+- **Blocking dialogs mark the pane**: pi's `ui_prompt_start` / `ui_prompt_end` events cover the inherently blocking `ctx.ui` dialogs (`select` / `confirm` / `input` / `editor`), so a dialog from *any* extension marks the pane blocked and emits the `herdr:blocked` edge; nested gates coalesce, and the ask tool no longer needs its 5s refresh heartbeat. `custom` is deliberately excluded — pi routes resident overlays through it too (pier's own slim-frame overlay never calls `done()`), which used to leave a working pane marked blocked for the whole session
+- **Role gate stops early**: a denied worker tool call returns `terminate`, so a batch whose results are all terminating ends without another model round trip
+- **Transcript cards**: pier's own session entries (todo edits, subagent/terminal registries, role manifests, soft approvals) and its reminder messages render as compact cards instead of raw JSON — entry/message renderers, no pi-tui dependency
 - **Isolated worktree subagents (`isolate`)**: heavy parallel writers get a fresh git worktree (branch `pier/<slug>` from your HEAD under `~/.herdr/worktrees/<repo>/`) with commit discipline in the prompt; settlement carries a diff summary (commits since base, files changed, uncommitted count); merge with `git merge --no-ff` and the worktree auto-removes once merged and clean — the branch stays for audit
-- **Long-task lifecycle (01a03c0d review)**: observation timeout is now an inactivity budget (working slices renew it — healthy >10min tasks are no longer killed); follow_up messages deliver via steer at tool-call gaps (supplementary contracts arrive in seconds, not after the whole run); GC waits for the settlement notice to be delivered before closing panes; takeover detection attributes recent machine injections first; ledger rows carry a `via` tag, closed rows inherit their outcome, zombie running rows are swept on startup; SUBS snapshots are hash-gated. Tunables: `PI_HERDR_SUBAGENT_TIMEOUT_MS` (inactivity seconds), `PI_HERDR_INJECT_GRACE_MS`, `PI_HERDR_OBSERVE_MS`
+- **Worktree collection is ownership-scoped**: only worktrees this session registered are collected, and the running process's own directory is never a candidate — the earlier prefix match on `refs/heads/pier/` could delete a parallel session's worktree out from under it. Sweeping branches the session never registered is opt-in (`PIER_ISOLATE_SWEEP_ORPHANS=1`)
+- **Ops dashboard + sidebar view (herdr 0.9)**: `herdr plugin pane open --plugin pier.workbench --entrypoint dashboard` opens a live pane/tab/agent board (roles, states, todo progress); the plugin also registers a `Pier` sidebar agent view that lists every detected agent (no harness filter) with attention-first ordering
+- **Long-task lifecycle (01a03c0d review)**: observation timeout is now an inactivity budget (working slices renew it — healthy >10min tasks are no longer killed); follow_up messages deliver via steer at tool-call gaps (supplementary contracts arrive in seconds, not after the whole run); GC waits for the settlement notice to be delivered before closing panes; takeover detection attributes recent machine injections first; ledger rows carry a `via` tag, closed rows inherit their outcome, zombie running rows are swept on startup; SUBS snapshots are hash-gated. Tunables: `PIER_SUBAGENT_TIMEOUT_MS` (inactivity ms), `PIER_SETTLEMENT_WINDOW_MS` (ms), `PIER_OBSERVATION_WINDOW_MS` (ms)
 - **Settlement notice folding**: subagent settlements no longer flood back when a long main run ends — they inject at turn gaps, up to 3 shown, the rest folded with pointers
 
 ## Installation
@@ -38,8 +45,8 @@ pier ships as **two halves**, installed separately:
 ### Requirements
 
 - Node ≥ 22
-- pi ≥ 0.84 (`@earendil-works/pi-coding-agent`)
-- herdr ≥ 0.8.0 (macOS / Linux / Windows; Windows is preview beta)
+- pi ≥ 0.86.0 (`@earendil-works/pi-coding-agent`) — dynamic toolset (transcript-backed `setActiveTools` deltas) and role switching require it
+- herdr ≥ 0.9.0 (macOS / Linux / Windows; Windows is preview beta)
 
 ### One-shot install (recommended)
 
@@ -49,7 +56,7 @@ No clone needed — run the npm package directly:
 npx pier-setup@latest            # user mode: pi install npm:pi-pier + herdr plugin install
 npx pier-setup@latest version    # local vs npm latest (installer / pi-pier / herdr plugin)
 npx pier-setup@latest update     # refresh both halves in place (does not uninstall first)
-npx pier-setup@latest uninstall  # --purge also drops boot-config.json
+npx pier-setup@latest uninstall
 
 npm i -g pier-setup              # or install globally, then: pier-setup / version / update
 ```
@@ -63,15 +70,13 @@ Dev mode still requires cloning the repo:
 git clone https://github.com/July24/pier && cd pier
 node install.mjs install --dev   # local-path pi install + herdr plugin link; code changes are live
 node install.mjs version --dev
-node install.mjs update --dev    # rewrite boot-config only; pull the repo yourself
+node install.mjs update --dev    # re-check env + versions; pull the repo yourself
 ```
 
-The script verifies the environment (node / pi / herdr versions), probes pi's node
-and cli.js absolute paths, generates boot-config.json (user mode stores it in the
-herdr plugin config dir, so reinstalls don't lose it), and registers both halves.
+The script verifies the environment (node / pi / herdr versions) and registers both halves.
 
 `update` re-runs `pi update npm:pi-pier` (falls back to `pi install`) and
-`herdr plugin install … --yes`, then rewrites boot-config. Override sources with
+`herdr plugin install … --yes`. Override sources with
 `--pi-spec=` / `--herdr-spec=` (npm publishing or forks). `pier-setup --help`
 lists every command.
 
@@ -124,15 +129,7 @@ pi overwrites tools/commands by name; event listeners stack. Two todo or subagen
 **Designed coexistence:** herdr’s official `herdr:pi` reporter. Keep it. pier emits `herdr:blocked` so that plugin remains lifecycle authority.
 
 - **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.
-
-### Bootstrap config (workbench half)
-
-Master-tab bootstrap needs local node / pi paths: `pier-setup` generates
-them automatically; manually, copy `packages/pier-workbench/scripts/boot-config.example.json`
-(placeholders for both macOS and Windows). User mode reads it from
-`herdr plugin config-dir pier.workbench`; dev mode from `packages/pier-workbench/scripts/boot-config.json`.
+  are excluded from heat reflow; blocked notifications are pi-only.
 
 ### Usage
 
@@ -146,17 +143,81 @@ them automatically; manually, copy `packages/pier-workbench/scripts/boot-config.
 ```
 packages/
   pier-ext/        # pi extension (npm: pi-pier): todo/subagent tools, herdr client, vocab authority, skill
-  pier-workbench/  # herdr plugin (pier.workbench): workspace bootstrap + blocked notify + heat layout
-docs/              # install guide, role profile docs, sidebar role config
+  pier-workbench/  # herdr plugin (pier.workbench): blocked notify + heat layout + ops dashboard
+docs/              # install guide, configuration overview, role profile docs, sidebar role config
 ```
 
 ## Testing
 
 ```sh
 npm install --ignore-scripts
-npm test          # node --test, 278 unit tests (planner / todo replay / anti-freeze staleness / session tail / GC / lifecycle)
+npm test          # node --test, 733 unit tests (planner / todo replay / anti-freeze staleness / session tail / GC / lifecycle / renderers / ask picker / subagent output / jev decision layer: diagnostic gate, notice ranking, excerpt windows)
 ```
 
+## Configuration
+
+Runtime policies and operational limits are centralized in `runtime-policy.ts` (with terminal read limits in `terminal.ts`). All timeouts use millisecond units unless specified otherwise:
+
+| Variable | Default | Unit | Purpose |
+|---|---|---|---|
+| `PIER_SUBAGENT_TIMEOUT_MS` | `600000` | ms | Subagent inactivity budget / overall timeout before forced termination |
+| `PIER_SETTLEMENT_WINDOW_MS` | `60000` | ms | Settlement notice window, machine injection grace period, and takeover idle threshold |
+| `PIER_OBSERVATION_WINDOW_MS` | `30000` | ms | Post-settle observation window before auto-consuming finished subagents |
+| `PIER_FOREGROUND_PATIENCE_MS` | `300000` | ms | Foreground execution patience before auto-demoting a subagent to background |
+| `PIER_GC_TICK_MS` | `30000` | ms | Subagent garbage collection ticker interval |
+| `PIER_POLL_INTERVAL_MS` | `30000` | ms | State observation polling interval for subagent state transitions |
+| `PIER_READY_TIMEOUT_MS` | `90000` | ms | Subagent pane pipe readiness wait (exponential backoff; a pane that exited fails immediately with its last output attached) |
+| `PIER_SESSION_TTL_SECONDS` | `600` | s | Session retention TTL after subagent exit before GC cleanup |
+| `PIER_GIT_TIMEOUT_MS` | `10000` | ms | Execution timeout for git operations (worktree creation, diff summary, cleanup) |
+| `PIER_FOCUS_POLL_MS` | `1500` / `0` | ms | Focus sampling for heat layout (`0` disables). Default 1500ms on Herdr <0.9.1; 0 (event-first) on 0.9.1+ |
+| `PIER_TERM_READ_MAX` | `8000` | chars | Maximum terminal buffer characters read per operation |
+| `PIER_TERM_IDLE_MS` | `1800000` | ms | Idle time before pier nudges about an open terminal |
+| `PIER_TODO_GRACE_MS` | `30000` | ms | Settle grace before the unfinished-todo reminder |
+| `PIER_TRACE` | – | flag | Write diagnostics (tool renderers, swallowed errors) to stderr |
+| `PIER_JEV_ENABLE` | `0` | flag | Jev decision layer (TypeSafe System One classification) master switch; every call site fails open — see `docs/rfc-jev-integration.md` |
+| `PIER_JEV_LOG` | `0` | flag | Write `efficiency-logs/jev.jsonl` (metadata + hashes only, never bodies) |
+| `PIER_JEV_API_KEY` | – | – | API key; precedence env > config `jev.apiKey` > `TYPESAFE_API_KEY` |
+| `PIER_JEV_MODEL` | `jev-1.13.0` | – | Pinned versioned model id (aliases drift silently and skew tuned thresholds) |
+| `PIER_JEV_TIMEOUT_MS` | `2000` | ms | Total per-call budget (AbortController hard kill) |
+| `PIER_JEV_MIN_CONFIDENCE` | `0.6` | – | Minimum Choice/Score confidence to adopt an answer |
+| `PIER_JEV_BASE_URL` | – | – | API root override (relay/gateway) |
+
+**Naming:** `PIER_*` is the canonical namespace for pier options; the historical `PI_HERDR_*` spelling
+of the same knob is still read as an alias (an empty value counts as unset). Names handed to child
+processes stay as they are (`PI_HERDR_SUBAGENT`, `PI_HERDR_ROLE_MANIFEST`, `PI_HERDR_TUI`,
+`PI_HERDR_META_KEY`), because renaming them would split a running worker from its parent.
+`/pier-config doctor` lists every option with its effective value and where it came from, plus the
+errors pier deliberately swallowed this session.
+
+**Focus heat:** Herdr 0.9.0 resolved mouse focus in the client and did not deliver `pane.focused`
+to plugins, so each pane sampled `layout.export → focused_pane_id` and replayed the workbench
+event. Herdr 0.9.1+ delivers `pane.focused` natively, so the poller defaults off. Override with
+`PIER_FOCUS_POLL_MS`; `PIER_WORKBENCH_ROOT` points at a relocated plugin checkout.
+
+### Efficiency mechanisms (D100–D103, opt-in)
+
+Three token-saving mechanisms ship **disabled by default** and are safe to try one at a time:
+
+- **ObservationPack** — large tool outputs are projected as placeholders after the first `fullSends` requests, with paged retrieval via `obs_recall` (session JSONL stays untouched).
+- **EPR** — long diagnostic (`bash` test/build) logs are reduced in-process to a byte-verified evidence receipt; the raw log is archived first and stays readable.
+- **OCC** — `todo_write` boundaries drive pi's native compaction under a KV-cache cost model, carrying unfinished tasks across the compaction.
+
+```bash
+PI_HERDR_OBS_PACK_ENABLE=1 PI_HERDR_OBS_PACK_LOG=1 pi   # start here
+```
+
+Full quick start, what to watch in `efficiency-logs/*.jsonl`, rollback steps and a feedback template: **[docs/efficiency-trial.md](docs/efficiency-trial.md)**.
+
+Everything above (plus roles, pi settings and the `PIER_*`/`PI_HERDR_*` env knobs) is also inspectable in-session:
+
+```text
+/pier-config            # 4-plane index; hands a guided change to the agent
+/pier-config show all   # effective value + source (env > workspace > user > default) per key
+/pier-config check      # validation across planes   ·   /pier-config doc → written report
+```
+
+Read-only by design — see **[docs/configuration.md](docs/configuration.md)** for the plane map and the "which plane do I edit?" table.
+
 ## Design principles
 
 - **Session JSONL is the single source of truth**: todos, delegations, and registries replay from session branches — restart and branch switches stay correct
@@ -170,6 +231,6 @@ MIT
 
 ---
 
-> 💡 **For contributors**: `.gitignore` is deliberately **not committed** to this repository (ignore rules are per-environment). Maintain your own rules based on `README.md` / `README_ZH.md`; `packages/pier-workbench/scripts/boot-config.json` is also machine-local (see the `.example.json` template).
+> 💡 **For contributors**: `.gitignore` is tracked in the repository. `docs/research/` contains local research notes ignored by `.gitignore`.
 >
 > **Naming convention**: the brand is **pier** (repo/packages/plugin); runtime protocol identifiers keep the **`pi-herdr`** prefix (`.pi-herdr/roles/` dir, `pi-herdr.subs` session custom entries, `~/.pi/agent/herdr-pi/roles/` user dir) — they persist with user sessions/config files, renaming would break existing data, so they are the compatibility layer.

package/install.mjs

@@ -1,27 +1,25 @@
 #!/usr/bin/env node
 /**
- * pier 一键安装/卸载/更新/查版本（跨平台：macOS / Linux / Windows）。
+ * pier one-shot installer / uninstaller / updater / version inspector (cross-platform: macOS / Linux / Windows).
  *
- * 用法：
- *   node install.mjs install  [--dev] [--hmr-dev] [--force]   # 安装（默认命令，可省略 install）
- *   node install.mjs update   [--dev] [--hmr-dev]             # 原地刷新两半区到最新发行（不先卸载）
- *   node install.mjs version  [--json]                        # 本地 vs npm latest
- *   node install.mjs uninstall [--dev] [--purge]              # 卸载；--purge 连 boot-config.json 一起删
- *   node install.mjs --prepare                                # npm prepare：hooksPath + 仓库根 bin 链接
+ * Usage:
+ *   node install.mjs install  [--dev]                        # Install (default command, 'install' can be omitted)
+ *   node install.mjs update   [--dev]                        # Refresh both halves in place to latest release (no prior uninstall)
+ *   node install.mjs version  [--json]                       # Local vs npm latest
+ *   node install.mjs uninstall [--dev]                       # Uninstall both halves
+ *   node install.mjs --prepare                                # npm prepare: hooksPath + repo root bin link
  *   node install.mjs --help
  *
- * 模式：
- *   用户模式（默认）：pi install npm:pi-pier
+ * Modes:
+ *   User mode (default): pi install npm:pi-pier
  *                   + herdr plugin install July24/pier/packages/pier-workbench --yes
- *                   boot-config.json 写 herdr plugin config-dir；extPath 指向 pi 已安装的
- *                   pi-pier（~/.pi/agent/npm/...），不是 pier-setup 包内的仓库路径。
- *   --dev 开发模式：pi install <repo>/packages/pier-ext + herdr plugin link <repo>/packages/pier-workbench
- *                   （link 目录是活的，改码即生效；update 只重写 boot-config）。
- * 发行规格可用 --pi-spec= / --herdr-spec= 覆盖（npm 发布或 fork 场景）。
- * 失败语义：每步给出手动等价命令；步骤失败不阻断报告（exitCode=1）。
+ *   --dev Development mode: pi install <repo>/packages/pier-ext + herdr plugin link <repo>/packages/pier-workbench
+ *                   (linked directory is live; code edits take effect immediately).
+ * Distribution specs can be overridden via --pi-spec= / --herdr-spec= (for npm publish or fork scenarios).
+ * Failure semantics: Each step provides manual equivalent command; step failure does not abort reporting (exitCode=1).
  */
 import { execFileSync } from 'node:child_process';
-import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -29,7 +27,6 @@ import { fileURLToPath } from 'node:url';
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)));
 const EXT_DIR = join(ROOT, 'packages', 'pier-ext');
 const WB_DIR = join(ROOT, 'packages', 'pier-workbench');
-const DEV_BOOT_CONFIG = join(WB_DIR, 'scripts', 'boot-config.json');
 const EXT_PATH = join(EXT_DIR, 'src', 'index.ts');
 const IS_WIN = process.platform === 'win32';
 const COMMANDS = ['install', 'uninstall', 'update', 'version', 'help'];
@@ -66,17 +63,17 @@ const command = COMMANDS.includes(argv[0]) ? argv.shift() : null;
 const flags = new Set(argv.filter((a) => (a.startsWith('--') && !a.includes('=')) || a === '-h' || a === '-v'));
 const optValue = (name) => argv.find((a) => a.startsWith(`--${name}=`))?.split('=').slice(1).join('=') ?? null;
 const dev = flags.has('--dev');
-const PI_SPEC = optValue('pi-spec') ?? 'npm:pi-pier';   // 用户模式默认 npm 发行版；--pi-spec=git:github.com/July24/pier 可跟随仓库 main
+const PI_SPEC = optValue('pi-spec') ?? 'npm:pi-pier';   // User mode defaults to npm release; --pi-spec=git:github.com/July24/pier tracks repo main
 const HERDR_SPEC = optValue('herdr-spec') ?? 'July24/pier/packages/pier-workbench';
 
 const log = (m) => console.log(m);
 const die = (m) => { console.error(`✗ ${m}`); process.exit(1); };
 
-/* ── 工具函数 ────────────────────────────────────────────────────── */
+/* ── Utility functions ────────────────────────────────────────────── */
 function which(bin) {
   try {
     const out = execFileSync(IS_WIN ? 'where' : 'which', [bin], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-    // where 可能多行（PATH 逐条命中），取第一条存在的
+    // 'where' may return multiple lines (one per PATH hit); pick the first existing line
     for (const line of out.split('\n').map((l) => l.trim()).filter(Boolean)) {
       if (existsSync(line)) return line;
     }
@@ -87,9 +84,9 @@ function which(bin) {
 }
 
 function run(cmd, args, opts = {}) {
-  // win32: npm 全局 bin 是 .cmd shim，无 shell 直接 spawn 会 ENOENT/EINVAL，须走 cmd.exe；
-  // 且 shell:true 时 Node 把 args 按空格裸拼接（不加引号），含空格的路径参数会被拆碎，故预拼接并加引号。
-  // POSIX 走原生分支，保持 execFileSync(cmd, args) 原语义。
+  // win32: npm global bin is a .cmd shim; spawning directly without shell triggers ENOENT/EINVAL, must run via cmd.exe;
+  // also when shell:true, Node concatenates args with bare spaces (unquoted), breaking path args with spaces, so pre-join and quote.
+  // POSIX uses native branch, preserving execFileSync(cmd, args) semantics.
   if (IS_WIN) {
     const cmdline = [cmd, ...args]
       .map((a) => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a))
@@ -141,60 +138,36 @@ function npmLatest(name) {
   }
 }
 
-/** herdr 插件配置目录（用户模式 boot-config 落点；插件已注册才存在路径语义）。 */
-function herdrConfigDir() {
-  try { return run('herdr', ['plugin', 'config-dir', 'pier.workbench']); } catch { return null; }
-}
 
-/* ── 环境校验（install 前置） ────────────────────────────────────── */
+/* ── Environment check (pre-install) ────────────────────────────────── */
 function checkEnv() {
   const [major] = process.versions.node.split('.').map(Number);
   if (major < 22) die(`node ≥ 22 required, found ${process.versions.node}`);
   log(`✓ node ${process.versions.node}`);
   const piVersion = (() => { try { return parseVersion(run('pi', ['--version'])); } catch { return null; } })();
-  if (!piVersion || !geVersion(piVersion, [0, 84, 0])) {
-    die(`pi ≥ 0.84 required${piVersion ? `, found ${piVersion.join('.')}` : ' (pi not found or not runnable)'}. Install: npm i -g @earendil-works/pi-coding-agent`);
+  if (!piVersion || !geVersion(piVersion, [0, 86, 0])) {
+    die(`pi ≥ 0.86.0 required${piVersion ? `, found ${piVersion.join('.')}` : ' (pi not found or not runnable)'}. Install: npm i -g @earendil-works/pi-coding-agent`);
   }
   log(`✓ pi ${piVersion.join('.')}`);
   const herdrVersion = (() => { try { return parseVersion(run('herdr', ['--version'])); } catch { return null; } })();
-  if (!herdrVersion || !geVersion(herdrVersion, [0, 8, 0])) {
-    die(`herdr ≥ 0.8.0 required${herdrVersion ? `, found ${herdrVersion.join('.')}` : ' (herdr not found)'}. Install: https://herdr.dev/`);
+  if (!herdrVersion || !geVersion(herdrVersion, [0, 9, 0])) {
+    die(`herdr ≥ 0.9.0 required${herdrVersion ? `, found ${herdrVersion.join('.')}` : ' (herdr not found)'}. Install: https://herdr.dev/`);
   }
   log(`✓ herdr ${herdrVersion.join('.')}`);
   return { piVersion, herdrVersion };
 }
 
-/** pi 半区源：用户模式 git 规格，dev 模式本地目录。 */
+/** pi extension source: user mode uses git/npm spec, dev mode uses local directory. */
 const piSource = () => (dev ? EXT_DIR : PI_SPEC);
 
-/* ── boot-config 探测与写入 ──────────────────────────────────────── */
-function probePiRuntime() {
-  const piBin = which('pi');
-  // bin 是 node shim：realpath 落到 .../pi-coding-agent/dist/cli.js（npm 布局，win/posix 同构）
-  if (piBin) {
-    try {
-      const real = realpathSync(piBin);
-      if (real.endsWith('cli.js') && existsSync(real)) {
-        return { piCli: real, piNode: process.execPath };
-      }
-    } catch { /* 落到兜底 */ }
-  }
-  // npm root -g 兜底：pi 不在 PATH（nvm shim 等）时按全局布局拼
-  try {
-    const gRoot = run('npm', ['root', '-g']);
-    const cand = join(gRoot, '@earendil-works', 'pi-coding-agent', 'dist', 'cli.js');
-    if (existsSync(cand)) return { piCli: cand, piNode: process.execPath };
-  } catch { /* npm 不可用 */ }
-  return null;
-}
 
 function piAgentDir() {
   return process.env.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent');
 }
 
-/* ── 旧版 git 模式注册迁移 ──────────────────────────────────────── */
-// 早期 `pi install git:github.com/July24/pier` 的遗留注册与 npm:pi-pier 并存时，
-// 两份扩展会注册同名工具（todo_write / ask_user_question…），pi 启动即报 conflict。
+/* ── Legacy git-mode registration migration ────────────────────────── */
+// When legacy `pi install git:github.com/July24/pier` coexists with npm:pi-pier,
+// both extensions register identical tools (todo_write / ask_user_question...), causing conflict at pi launch.
 const LEGACY_GIT_SPEC = 'git:github.com/July24/pier';
 
 function registeredPiPackages() {
@@ -203,7 +176,7 @@ function registeredPiPackages() {
   } catch { return []; }
 }
 
-/** install/update 前清理旧 git 模式注册；--pi-spec 显式指定该 git 源时视为目标源，不动。 */
+/** Clean up legacy git-mode registration before install/update; if --pi-spec explicitly specifies that git source, treat it as target and keep it. */
 function removeLegacyGitRegistration() {
   if (piSource() === LEGACY_GIT_SPEC) return;
   if (!registeredPiPackages().includes(LEGACY_GIT_SPEC)) return;
@@ -260,47 +233,6 @@ function resolveUserExtPath() {
   return extPathFromPiList();
 }
 
-function writeBootConfig(hmrDev, force) {
-  const probed = probePiRuntime();
-  if (!probed) die('cannot locate pi cli.js (tried: pi shim realpath, npm root -g). Fill boot-config.json manually.');
-  let extPath;
-  if (dev) {
-    if (!existsSync(EXT_PATH)) die(`pier-ext entry missing: ${EXT_PATH} (repo layout broken?)`);
-    extPath = EXT_PATH;
-  } else {
-    extPath = resolveUserExtPath();
-    if (!extPath) die(`cannot locate installed pier-ext (npm:pi-pier / git clone). Did \`pi install ${piSource()}\` succeed?`);
-  }
-
-  const config = {
-    mainTabLabel: 'main',
-    piNode: probed.piNode,
-    piCli: probed.piCli,
-    extPath,
-    workbenchPluginId: 'pier.workbench',
-    hmrDev,
-  };
-
-  const target = dev ? DEV_BOOT_CONFIG : join(herdrConfigDir() ?? die('cannot resolve herdr plugin config-dir (is pier.workbench installed?)'), 'boot-config.json');
-  if (existsSync(target) && !force) {
-    let existing = null;
-    try { existing = JSON.parse(readFileSync(target, 'utf8')); } catch { /* 视为损坏 */ }
-    if (existing) {
-      log(`• ${target} exists, diff (existing → new):`);
-      for (const k of Object.keys(config)) {
-        if (existing[k] !== config[k]) log(`    ${k}: ${JSON.stringify(existing[k])} → ${JSON.stringify(config[k])}`);
-      }
-      log('  kept existing (use --force to overwrite)');
-      return;
-    }
-  }
-  mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, JSON.stringify(config, null, 2) + '\n');
-  log(`✓ boot-config.json ${force ? 'overwritten (--force)' : 'written'} → ${target}`);
-  log(`  piNode = ${config.piNode}`);
-  log(`  piCli  = ${config.piCli}`);
-  log(`  extPath = ${config.extPath}`);
-}
 
 function pkgDirFromExtPath(extPath) {
   let d = dirname(extPath);
@@ -339,22 +271,22 @@ function collectStatus() {
   };
 }
 
-/* ── 命令 ────────────────────────────────────────────────────────── */
+/* ── Commands ─────────────────────────────────────────────────────── */
 function usage() {
   log(`pier-setup — install / update / inspect pier (pi-pier + pier.workbench)
 
 Usage:
-  pier-setup [install] [--dev] [--hmr-dev] [--force]
-  pier-setup update    [--dev] [--hmr-dev]
+  pier-setup [install] [--dev]
+  pier-setup update    [--dev]
   pier-setup version   [--json]
-  pier-setup uninstall [--dev] [--purge]
+  pier-setup uninstall [--dev]
 
   npx pier-setup@latest          # recommended user install
   npx pier-setup@latest update   # refresh both halves to newest release
   npx pier-setup@latest version  # local vs npm latest
 
   --pi-spec= / --herdr-spec= override distribution sources
-  --dev  local link (clone); update only rewrites boot-config`);
+  --dev  local link (clone); the linked directories are live`);
 }
 
 function version() {
@@ -390,25 +322,20 @@ function update() {
   if (latestSetup && me && cmpSemver(me, latestSetup) < 0) {
     log(`⚠ installer ${me} < latest ${latestSetup} — re-run: npx pier-setup@latest update`);
   }
-  const hmrDev = flags.has('--hmr-dev');
   if (dev) {
-    log('dev mode: local link is live; pull the repo yourself. Refreshing boot-config only.');
-    writeBootConfig(hmrDev, true);
+    log('dev mode: local link is live; pull the repo yourself (no installer-managed files to refresh).');
   } else {
     if (tryRun('pi', ['update', piSource()])) log(`✓ pi extension updated (${piSource()})`);
     else if (tryRun('pi', ['install', piSource()])) log(`✓ pi extension installed (${piSource()})`);
     else { console.error('✗ pi update/install failed'); log(`  manual: pi update ${piSource()}`); process.exitCode = 1; }
     if (tryRun('herdr', ['plugin', 'install', HERDR_SPEC, '--yes'])) log(`✓ herdr plugin updated (${HERDR_SPEC})`);
     else { console.error('✗ herdr plugin update failed'); log(`  manual: herdr plugin install ${HERDR_SPEC} --yes`); process.exitCode = 1; }
-    writeBootConfig(hmrDev, true);
   }
   log('');
   version();
 }
 
 function install() {
-  const hmrDev = flags.has('--hmr-dev');
-  const force = flags.has('--force');
   checkEnv();
   removeLegacyGitRegistration();
 
@@ -417,40 +344,31 @@ function install() {
     else { console.error('✗ pi install failed'); log(`  manual: pi install ${EXT_DIR}`); process.exitCode = 1; }
     if (tryRun('herdr', ['plugin', 'link', WB_DIR])) log('✓ herdr plugin linked (packages/pier-workbench, local)');
     else { console.error('✗ herdr plugin link failed'); log(`  manual: herdr plugin link ${WB_DIR}`); process.exitCode = 1; }
-    writeBootConfig(hmrDev, force);
   } else {
     if (tryRun('pi', ['install', piSource()])) log(`✓ pi extension installed (${PI_SPEC})`);
     else { console.error('✗ pi install failed'); log(`  manual: pi install ${PI_SPEC}`); process.exitCode = 1; }
     if (tryRun('herdr', ['plugin', 'install', HERDR_SPEC, '--yes'])) log(`✓ herdr plugin installed (${HERDR_SPEC})`);
     else { console.error('✗ herdr plugin install failed'); log(`  manual: herdr plugin install ${HERDR_SPEC}`); process.exitCode = 1; }
-    writeBootConfig(hmrDev, force);
   }
 
   log(`
 pier installed (${dev ? 'dev mode: local paths, code changes are live' : 'user mode: managed checkouts'}). Next:
-  1. start herdr, open/create a workspace — the main tab auto-bootstraps a pi session
+  1. start herdr, open/create a workspace and run \`pi\` inside a pane
   2. inside pi, ask the model to use todo_write / subagent tools`);
 }
 
 function uninstall() {
-  const purge = flags.has('--purge');
   if (tryRun('pi', ['remove', piSource()])) log('✓ pi extension removed');
   else { console.error('✗ pi remove failed'); log(`  manual: pi remove ${piSource()}`); process.exitCode = 1; }
 
   if (dev) {
     if (tryRun('herdr', ['plugin', 'unlink', 'pier.workbench'])) log('✓ herdr plugin unlinked (files kept)');
     else { console.error('✗ herdr plugin unlink failed'); log('  manual: herdr plugin unlink pier.workbench'); process.exitCode = 1; }
-    if (purge && existsSync(DEV_BOOT_CONFIG)) { rmSync(DEV_BOOT_CONFIG); log('✓ dev boot-config.json purged'); }
   } else {
     if (tryRun('herdr', ['plugin', 'uninstall', 'pier.workbench'])) log('✓ herdr plugin uninstalled (managed checkout removed)');
     else { console.error('✗ herdr plugin uninstall failed'); log('  manual: herdr plugin uninstall pier.workbench'); process.exitCode = 1; }
-    if (purge) {
-      const dir = herdrConfigDir();
-      const f = dir ? join(dir, 'boot-config.json') : null;
-      if (f && existsSync(f)) { rmSync(f); log('✓ boot-config.json purged'); }
-    }
   }
-  log(`\npier uninstalled.${purge ? '' : ' (boot-config.json kept; use --purge to remove)'}`);
+  log('\npier uninstalled.');
 }
 
 if (command === 'help' || flags.has('--help') || flags.has('-h')) usage();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pier-setup",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "One-shot installer for pier: install / update / version / uninstall for pi-pier + pier.workbench",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,8 @@
     "packages/*"
   ],
   "scripts": {
-    "test": "node --test \"packages/*/test/*.test.ts\"",
+    "typecheck": "tsc --noEmit -p packages/pier-ext/tsconfig.json",
+    "test": "npm run typecheck && node --test \"packages/*/test/*.test.ts\"",
     "test:mutation": "stryker run",
     "prepare": "node ./install.mjs --prepare"
   },
@@ -41,7 +42,8 @@
     "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
     "@deepseek-ai/cordis-plugin-timer": "^1.1.3",
     "@stryker-mutator/core": "^10.0.0",
-    "@stryker-mutator/typescript-checker": "^10.0.0"
+    "@stryker-mutator/typescript-checker": "^10.0.0",
+    "typescript": "~5.9.3"
   },
   "pi": {
     "extensions": [