pier-setup 0.2.7 → 0.3.0

package/README.md

@@ -26,11 +26,18 @@ pier ships as **two halves**, installed separately:
 - **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**: a `multi: true` question renders as an interactive toggle list (space toggles a row, `a` toggles all, enter confirms, esc declines, live selection count) with the free-text row pinned last; `allowOther: false` gives pure choice. The typed-index prompt remains the fallback 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.84.4 (`@earendil-works/pi-coding-agent`)
+- herdr ≥ 0.9.0 (macOS / Linux / Windows; Windows is preview beta)
 
 ### One-shot install (recommended)
 
@@ -147,16 +154,80 @@ 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
+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, 809 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, boot-config and the `PIER_*`/`PI_HERDR_*` env knobs) is also inspectable in-session:
+
+```text
+/pier-config            # 5-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 +241,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. Note that `packages/pier-workbench/scripts/boot-config.json` is machine-local (see the `.example.json` template), and `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,24 +1,24 @@
 #!/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] [--hmr-dev] [--force]   # Install (default command, 'install' can be omitted)
+ *   node install.mjs update   [--dev] [--hmr-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] [--purge]              # Uninstall; --purge deletes boot-config.json as well
+ *   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）。
+ *                   boot-config.json written to herdr plugin config-dir; extPath points to pi-installed
+ *                   pi-pier (~/.pi/agent/npm/...), not the repo path inside pier-setup package.
+ *   --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; update only rewrites boot-config).
+ * 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';
@@ -66,17 +66,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 +87,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,50 +141,50 @@ function npmLatest(name) {
   }
 }
 
-/** herdr 插件配置目录（用户模式 boot-config 落点；插件已注册才存在路径语义）。 */
+/** Herdr plugin config directory (boot-config destination in user mode; semantic path exists once plugin is registered). */
 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, 84, 4])) {
+    die(`pi ≥ 0.84.4 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 探测与写入 ──────────────────────────────────────── */
+/* ── boot-config detection and writing ────────────────────────────── */
 function probePiRuntime() {
   const piBin = which('pi');
-  // bin 是 node shim：realpath 落到 .../pi-coding-agent/dist/cli.js（npm 布局，win/posix 同构）
+  // bin is a node shim: realpath resolves to .../pi-coding-agent/dist/cli.js (npm layout, isomorphic win/posix)
   if (piBin) {
     try {
       const real = realpathSync(piBin);
       if (real.endsWith('cli.js') && existsSync(real)) {
         return { piCli: real, piNode: process.execPath };
       }
-    } catch { /* 落到兜底 */ }
+    } catch { /* fall back to fallback */ }
   }
-  // npm root -g 兜底：pi 不在 PATH（nvm shim 等）时按全局布局拼
+  // npm root -g fallback: when pi is not in PATH (e.g. nvm shim), construct from global npm layout
   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 不可用 */ }
+  } catch { /* npm unavailable */ }
   return null;
 }
 
@@ -192,9 +192,9 @@ 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 +203,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;
@@ -284,7 +284,7 @@ function writeBootConfig(hmrDev, force) {
   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 { /* 视为损坏 */ }
+    try { existing = JSON.parse(readFileSync(target, 'utf8')); } catch { /* treated as corrupted */ }
     if (existing) {
       log(`• ${target} exists, diff (existing → new):`);
       for (const k of Object.keys(config)) {
@@ -339,7 +339,7 @@ function collectStatus() {
   };
 }
 
-/* ── 命令 ────────────────────────────────────────────────────────── */
+/* ── Commands ─────────────────────────────────────────────────────── */
 function usage() {
   log(`pier-setup — install / update / inspect pier (pi-pier + pier.workbench)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pier-setup",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "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": [