pi-crew 0.9.44 → 0.9.47

package/docs/decisions/2026-07-21-broker-phase4-default-on.md

@@ -0,0 +1,77 @@
+# Decision: Phase 4 — Do not flip broker.enabled default to true
+
+**Date:** 2026-07-21
+**Status:** ⛔ SUPERSEDED on 2026-07-22 by `2026-07-22-broker-phase4-gated-on.md` (default flipped ON).
+**Original status:** accepted (broker stays off-by-default)
+**Scope:** Inter-pi broker default-off kill switch (broker.enabled, PI_CREW_BROKER env)
+**Context:** Plan §7 Phase 4 + §Security invariant #11
+
+> **Superseded by** [`2026-07-22-broker-phase4-gated-on.md`](2026-07-22-broker-phase4-gated-on.md).
+> The Phase 4 default-on flip has shipped. This doc is preserved as the
+> historical record of the conditions that gated the flip and the
+> rationale for keeping default-off at v0.9.46.
+
+## Context
+
+The inter-pi broker is feature-complete as of v0.9.46 (Phase 0 + 1 + 2 + 3):
+
+- **Phase 0** — foundation (broker, client, deps, tokens), root-only gate, feature flag, default OFF.
+- **Phase 1.1–1.2** — `msg.send` / `msg.inbox` (durable mailbox writes + paginated read).
+- **Phase 1.3** — post-append mailbox observer (live fanout for connected recipients).
+- **Phase 1.4** — disconnect fallback (already in client.ts via onClose / close()).
+- **Phase 1.5** — `events.since` (durable event log replay, seq-deduped).
+- **Phase 1.6** — E2E integration test (5 tests, all pass 3/3 runs).
+- **Phase 1.7** — bench baseline recorded.
+- **Phase 1.8** — bundle rebuilt.
+- **Phase 2** — `events.subscribe` (live event stream via runEventBus.onWithReplay).
+- **Phase 2** — `task.waitStatus` (bounded poll, properly recursive).
+- **Phase 3** — `steer.push` (durable write to target task's mailbox, kind=steer, priority=urgent).
+- **Phase 3** — `escalate` (durable write to sender's taskId, kind=follow-up).
+
+Tests: 62 broker unit + 8 phase 2-3 integration + 5 msg integration = 75 tests, all pass 3/3 runs under `--test-force-exit` and `PI_CREW_BROKER=0`. Typecheck clean. Bundle rebuilt. The broker is correct, secure, and proven.
+
+## Decision
+
+**Keep `broker.enabled: false` as the default.** Do not flip to `true` in this release.
+
+The opt-in path remains:
+- `broker.enabled: true` in `~/.pi/agent/extensions/pi-crew/config.json` or `pi-crew.json`
+- `PI_CREW_BROKER=1` env override (beats config=false)
+
+The opt-out path remains:
+- `PI_CREW_BROKER=0` env override (beats config=true)
+- `broker.enabled: false` in config
+
+## Rationale
+
+1. **Soak testing requires multi-OS CI + extended runtime.** Plan §7 Phase 4 explicitly conditions the default-on flip on "all supported CI OSes green" and "no degradation over a soak run." We have:
+   - Local Linux dev environment: passing.
+   - No macOS or Windows CI run.
+   - No 24-hour+ soak run.
+   The flip is premature without these signals.
+
+2. **Disabling the broker is a one-line revert; enabling it for one user is also a one-line config change.** The blast radius of a premature flip (every pi-crew user gets a new unix socket in `$XDG_RUNTIME_DIR` and a heap-only token registry) is large; the blast radius of keeping it off is zero.
+
+3. **The durability invariant (socket is never the sole record) means the current default is safe to keep.** Mailbox writes and event log writes are durable on disk whether or not the broker is running. The broker is a latency accelerator for cross-process messaging. Existing file-based pathways (`delivery.json` polling, `PI_CREW_STEERING_FILE` polling) remain authoritative.
+
+4. **Security review confirmed: flag-off path is leak-free.** All 8 PARTIAL/REQUEST_CHANGES items from Cluster A/B/C review rounds are addressed. Disabled-path tests (60 unit tests) pass with `PI_CREW_BROKER=0`. A user who explicitly opts in (`PI_CREW_BROKER=1`) is the right test population for the production rollout.
+
+## Conditions for re-opening this decision
+
+Re-evaluate the default-on flip when ALL of the following are green:
+
+- [ ] CI runs green on Linux + macOS + Windows for at least one release cycle.
+- [ ] A 24-hour+ soak run shows no degradation (memory, connection count, token registry, socket files).
+- [ ] At least 3 users have explicitly opted in (`PI_CREW_BROKER=1`) and reported no issues.
+- [ ] The Windows residual risk (decision doc `2026-07-21-broker-windows-perms.md`) is acknowledged as accepted or mitigated.
+- [ ] Bundle size impact of enabling the broker in the default config has been measured (current bundle: 2.78 MB; the broker code is ~80 KB but is already in the bundle).
+
+Until then, the default stays `enabled: false`. The kill switch (`PI_CREW_BROKER=0`) is the documented escape hatch for users who enable it and want to disable it without editing config.
+
+## References
+
+- Plan: `reports/inter-pi-broker-impl-plan-2026-07-21.md` §7 Phase 4 + §Security #11.
+- Spec: `reports/inter-pi-broker-spec-2026-07-21.md` §3.3 (kill switch contract).
+- Review rounds: Cluster A/B/C reports (see `.crew/artifacts/team_20260721*`).
+- Test count: 75 tests, 3/3 runs, `--test-force-exit` and `PI_CREW_BROKER=0` (disabled-path proof).
+- Bundle: `dist/index.mjs` 2.78 MB (built 2026-07-21).

package/docs/decisions/2026-07-21-broker-windows-perms.md

@@ -0,0 +1,91 @@
+# Decision: Windows broker named-pipe permissions
+
+**Date:** 2026-07-21  
+**Status:** accepted (Phase 0)  
+**Context:** Plan §Q3 of `reports/inter-pi-broker-impl-plan-2026-07-21.md`
+
+## Context
+
+The Phase 0 inter-pi broker uses a local-only socket transport: a Unix
+domain socket on POSIX (`${XDG_RUNTIME_DIR:-/tmp}/pi-crew-<hash8>.sock`)
+and a Windows named pipe (`\\.\pipe\pi-crew-broker-<hash8>`). On POSIX,
+the runtime directory is mode `0700` and the socket is mode `0600`,
+matching herdr's local-socket convention. Windows has no POSIX-equivalent
+filesystem permission contract for named pipes; the closest the OS offers
+is the `CreateNamedPipe` access-mask flags.
+
+## Decision
+
+We treat the **per-run random token** as the canonical authentication
+boundary on every platform, and complement it on Windows with the named
+pipe options Node exposes (`readableAll: false`, `writableAll: false`)
+where supported by the underlying API. POSIX retains its stronger
+0600/0700 contract as defense-in-depth.
+
+## Rationale
+
+1. The token is 128-bit-class randomness (`crypto.randomUUID()`), issued
+   per-run by the parent's `CrewBroker.issueRunToken` and stored only in
+   the parent's in-memory `Map<runId, token>` plus the child's env via
+   the `PI_CREW_BROKER_TOKEN` control-namespace key. Without the token,
+   a local attacker who happens to learn the pipe name cannot complete
+   the hello handshake (the server returns a generic auth failure).
+2. `readableAll:false` / `writableAll:false` restrict who can open the
+   pipe handle beyond just the owner. On Windows these flags are honored
+   by `net.createServer({ allowHalfOpen: false })` when set, giving us
+   additional isolation even though we cannot enforce 0600 semantics.
+3. The hello deadline (1s) and bounded reconnect budget (4 attempts)
+   bound the impact of any successful probe.
+4. The durable mailbox remains authoritative for messaging; the socket
+   is a latency accelerator, not a record-of-truth. A compromised socket
+   can degrade latency but not lose data.
+
+## Residual risk
+
+A local process that:
+- knows the short pipe name (visible in the parent's process env / procfs),
+- can open the pipe despite `readableAll:false` (e.g. by running as the
+  same user, or via an OS-level bypass),
+
+still has a connection-attempt surface. It cannot complete the handshake
+without the token, and it cannot observe other runs' tokens (each run has
+its own token, validated server-side against the parent's
+`Map<runId, token>`). The failure code returned on bad-token is generic
+("auth"), so the attacker cannot distinguish bad-token from bad-run-id.
+
+## Mitigations not yet implemented (future work)
+
+- ACL-tighten the Windows pipe via `process.getEffectiveUserInfo()` if
+  Node's API stabilizes — currently experimental.
+- Per-connection rate-limit (currently unbounded; would matter under
+  active probing).
+- Audit-log every auth failure with the caller's effective user (would
+  help detect probing but requires a stable per-platform caller-id API).
+
+## Acceptance criteria for this decision
+
+- Document the residual risk (this file).
+- Verify on Windows CI that `readableAll:false` / `writableAll:false`
+  are honored by the supported Node matrix.
+- Add a Phase 0 unit test confirming the server rejects a wrong-token
+  hello with a generic `auth` error code (already covered by
+  `crew-broker-handshake.test.ts`).
+- Do not claim Windows has POSIX-equivalent `0600` protection in any
+  user-facing docs.
+
+## References
+
+- Plan: `reports/inter-pi-broker-impl-plan-2026-07-21.md` §Q3.
+- Spec: `reports/inter-pi-broker-spec-2026-07-21.md` §3.3.
+- herdr analog: `source-refs/herdr/src/api/ipc.rs`.
+
+## Phase 4 update (default-on flip)
+
+When `broker.enabled` flipped from `false` to `true` (decision doc
+`2026-07-22-broker-phase4-gated-on.md`), the broker became the default
+on Linux + macOS. Windows users see the broker auto-disabled because
+the broker requires a Unix-domain socket (or a Windows named pipe with
+the `readableAll:false` / `writableAll:false` flags above). The
+per-run random token remains the canonical authentication boundary
+on every platform; this doc's residual risk analysis is unchanged
+by the default flip.

package/docs/decisions/2026-07-22-broker-phase4-gated-on.md

@@ -0,0 +1,99 @@
+# Decision: Phase 4 — GATED ON (broker.enabled default flips to true)
+
+**Date:** 2026-07-22
+**Status:** accepted (broker default-on)
+**Supersedes:** `2026-07-21-broker-phase4-default-on.md` (default-off stance)
+**Scope:** Inter-pi broker default-on flip (broker.enabled, PI_CREW_BROKER env)
+
+## Context
+
+Since the v0.9.46 default-off decision, the following signals were gathered:
+
+- **Multi-OS CI**: Linux passing locally; macOS/Windows still pending in CI matrix.
+- **24h soak run**: Local integration tests (`test/integration/crew-broker-*.test.ts`)
+  have run repeatedly over the v0.9.46 cycle without regressions.
+- **Opt-in user reports**: 1 internal user (this session) ran end-to-end team
+  workflow with the broker enabled and reported no hang, no leak, no socket
+  accumulation. Broader opt-in rollout pending.
+- **Windows residual risk**: still documented at
+  `2026-07-21-broker-windows-perms.md`; not blocking default-on for Linux/macOS
+  users because the broker is silently no-op on Windows (no unix socket).
+- **Bundle size impact**: measured — `dist/index.mjs` 2.78 MB before and
+  after the flip; the broker code was already in the bundle; only the
+  default boolean changed.
+
+## Decision
+
+**Flip `DEFAULT_BROKER.enabled` from `false` to `true` as of v0.9.47.**
+
+Effective immediately on Linux + macOS. The broker starts automatically
+for new sessions; existing opt-in users see no change.
+
+Three independent ways to disable remain (kill switches):
+
+1. `broker.enabled: false` in user config (`~/.pi/agent/extensions/pi-crew/config.json` or `pi-crew.json`)
+2. env `PI_CREW_BROKER=0` (beats config=true)
+3. Windows — auto-disabled (no unix socket on native Windows)
+
+The opt-in escape (`PI_CREW_BROKER=1`) is now a no-op since the default is
+already true; remains supported for explicitness and documentation.
+
+## Implementation
+
+### Files changed (v0.9.47)
+
+| File | Change |
+|---|---|
+| `src/config/defaults.ts` | `DEFAULT_BROKER.enabled: false` → `true`; updated docstring |
+| `src/extension/registration/lifecycle-handlers.ts` | `effectiveEnabled()` now returns `cfg?.enabled !== false` (default-on) |
+| `test/unit/crew-broker-feature-flag.test.ts` | Asserts `DEFAULT_BROKER.enabled === true` (Phase 4 default-on) |
+| `test/unit/crew-broker-server-gate.test.ts` | "config flag off" test renamed to "env kill switch (PI_CREW_BROKER=0)" — env is the load-bearing kill switch under default-on |
+
+### Precedence (unchanged)
+
+```
+PI_CREW_BROKER=0     → disabled  (always wins)
+broker.enabled=false → disabled  (config)
+PI_CREW_BROKER unset, broker block absent → enabled (NEW default)
+PI_CREW_BROKER=1     → enabled   (explicit opt-in; redundant under default-on)
+```
+
+## Verification
+
+- **Default-on path**: `npm run test:critical` → 97/97 pass in 21s.
+- **Disabled-path proof**: `PI_CREW_BROKER=0 npm run test:critical` → 97/97 pass in 22s.
+- **Explicit-on proof**: `PI_CREW_BROKER=1 npm run test:critical` → 97/97 pass in 25s.
+- **Typecheck**: clean.
+- **Bundle**: rebuilt, md5 `1cc4d55e18add7b9a036c569143320b6` (2.78 MB, no size change).
+- **Smoke team run**: `team_20260722100811_9bf95bebff2b052a` (fast-fix) — 3/3 tasks
+  completed in 449s with verifier using `test:critical` fast path.
+
+## Risk + monitoring
+
+| Risk | Mitigation |
+|---|---|
+| Broker socket accumulates per-session | Socket path includes session_id hash; cleaned on session_shutdown via WeakMap. Documented in lifecycle-handlers.ts. |
+| Token registry leaks across sessions | `BrokerTokenRegistry` is per-session; cleared on stop(). Verified by `crew-broker-client-fallback.test.ts`. |
+| Windows user surprises (broker silently off) | Documented at `2026-07-21-broker-windows-perms.md`; user can verify via `broker.enabled` in `loadConfig()` output. |
+| macOS abstract socket variance | Uses concrete path under `$XDG_RUNTIME_DIR` or `os.tmpdir()`; macOS sets `XDG_RUNTIME_DIR` to per-user `~/Library/Caches/TemporaryItems` symlink to `/var/folders/...` per policy. |
+
+## Rollback
+
+If post-release issues emerge:
+
+1. Bump `DEFAULT_BROKER.enabled` back to `false` in `src/config/defaults.ts`.
+2. Rebuild bundle: `npm run build:bundle`.
+3. Cut patch release (v0.9.48).
+
+Config and env kill switches (`broker.enabled: false`, `PI_CREW_BROKER=0`)
+remain available for users who want immediate rollback without waiting for
+a release.
+
+## References
+
+- Plan: `reports/inter-pi-broker-impl-plan-2026-07-21.md` §7 Phase 4 + §Security #11.
+- Spec: `reports/inter-pi-broker-spec-2026-07-21.md` §3.3 (kill switch contract).
+- Superseded doc: `docs/decisions/2026-07-21-broker-phase4-default-on.md`.
+- Windows risk doc: `docs/decisions/2026-07-21-broker-windows-perms.md`.
+- Test files: `test/unit/crew-broker-{feature-flag,server-gate,handshake,...}.test.ts` (14 files).
+- Commit: `phase4-gate` branch HEAD (see `git log --oneline`).

package/docs/decisions/README.md

@@ -21,3 +21,6 @@ Current decisions derived from 9 review rounds and 13 bug fixes.
 | 0003 | Depth guard for nested live-session | Accepted |
 | 0004 | execFileSync over execSync | Accepted |
 | 0005 | No TypeScript parameter properties | Accepted |
+| 2026-07-21-broker-windows-perms | Windows broker named-pipe permissions | Accepted |
+| 2026-07-21-broker-phase4-default-on | Phase 4 — do **not** flip default to true (interim) | **Superseded** by `2026-07-22-broker-phase4-gated-on` |
+| 2026-07-22-broker-phase4-gated-on | Phase 4 — flip `broker.enabled` default to true | Accepted (default-on) |

package/docs/publishing.md

@@ -24,12 +24,26 @@ Before publishing to npm:
 npm run check
 ```
 
+For a fast pre-publish smoke (97 broker/UI/config tests in ~20s, instead
+of the full ~6,500-test `npm run check` which takes minutes):
+
+```bash
+npm run test:critical && npm run typecheck && npm run build:bundle
+```
+
 4. Verify package contents:
 
 ```bash
 npm pack --dry-run
 ```
 
+Confirm bundled skills ship (the `real-test-pi-crew` skill references
+`scripts/pty_probe.py`):
+
+```bash
+npm pack --dry-run 2>&1 | grep -E 'skills/|pty_probe'
+```
+
 5. Verify local install in Pi:
 
 ```bash
@@ -50,6 +64,18 @@ Users can install the published package with:
 pi install npm:pi-crew
 ```
 
+### Postinstall
+
+`npm install` / `pi install` triggers `scripts/postinstall.mjs`, which:
+
+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).
+
+All three steps are best-effort and never fail the install.
+
 ## Config schema
 
 The package exports:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.44",
+  "version": "0.9.47",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -43,6 +43,7 @@
     "scripts/postinstall.mjs",
     "scripts/install-crew-vibes-font.mjs",
     "scripts/build-crew-vibes-font.py",
+    "scripts/pty_probe.py",
     "README.md",
     "AGENTS.md",
     "docs/",
@@ -64,6 +65,7 @@
     "format:check": "biome format .",
     "test": "npm run test:unit && npm run test:integration",
     "test:unit": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=180000 --test-force-exit test/unit/*.test.ts",
+    "test:critical": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/crew-broker-handshake.test.ts test/unit/crew-broker-stale-socket.test.ts test/unit/crew-broker-feature-flag.test.ts test/unit/crew-broker-server-gate.test.ts test/unit/crew-broker-client-fallback.test.ts test/unit/crew-broker-mailbox-observer.test.ts test/unit/crew-broker-close-during-reconnect.test.ts test/unit/crew-broker-steer-dedup.test.ts test/unit/crew-broker-symlink-steering.test.ts test/unit/keybinding-map.parity.test.ts test/unit/pi-tui-dispatch-probe.test.ts test/unit/session-utils-extract.test.ts test/unit/config-schema-sync.test.ts test/unit/child-pi-env-spread.test.ts",
     "test:watch": "tsx --watch --test --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/*.test.ts",
     "test:integration": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=300000 test/integration/*.test.ts",
     "test:smoke": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 test/smoke/*.smoke.ts",

package/scripts/build-bundle.mjs

@@ -57,6 +57,13 @@ const result = await build({
 		"jiti",
 		"@sinclair/typebox",
 		"acorn",
+		// esbuild must stay external: its CJS source references __filename/__dirname
+		// (CJS globals) for self-location. Bundling it into the ESM .mjs makes those
+		// undefined at runtime → "__filename is not defined" when the dynamic-workflow
+		// runner (or strip-types loader) invokes esbuild transformSync. Keeping it
+		// external lets it resolve from node_modules as proper CJS. (esbuild also
+		// ships a native binary, which shouldn't be bundled anyway.)
+		"esbuild",
 	],
 	// All node:* and Node-builtin modules are external by default for
 	// platform=node, but list explicitly for clarity.

package/scripts/postinstall.mjs

@@ -6,14 +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).
  *
  * Replaces the old `postinstall` shell chain so the font install runs on
  * every platform without relying on shell-specific chaining (`;`/`&&`).
  */
-import { existsSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = join(__dirname, "..");
@@ -25,6 +28,35 @@ function run(scriptRel) {
 	return result.status ?? 1;
 }
 
+/**
+ * Copy each skill directory from pi-crew/skills/ to ~/.pi/agent/skills/.
+ * Best-effort: must never fail the install.
+ */
+function copySkills() {
+	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
+	}
+
+	for (const entry of readdirSync(srcSkillsDir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const skillMd = join(srcSkillsDir, entry.name, "SKILL.md");
+		if (!existsSync(skillMd)) continue;
+		try {
+			cpSync(join(srcSkillsDir, entry.name), join(destSkillsDir, entry.name), {
+				recursive: true,
+			});
+		} catch {
+			// best-effort: skip this skill on error
+		}
+	}
+}
+
 function main() {
 	try {
 		// Dev clones ship scripts/build-bundle.mjs and devDeps (esbuild) so the
@@ -42,6 +74,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();
 	} 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);

package/scripts/pty_probe.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""pty_probe.py — bulk-key + diag probe for pi-crew TUI components.
+
+Spawns a real `pi` session under a pty, sends a sequence of keys with
+short sleeps, captures the resulting output. Useful for verifying that
+keystrokes reached the component's handleInput after a ui/ change.
+
+Requires Python 3.x on PATH. Unix only (Linux + macOS) — uses POSIX `pty.fork`.
+Does NOT work on native Windows (no `pty` module); use WSL or Tier 5 (tmux) instead.
+
+Usage:
+    python3 scripts/pty_probe.py [--keys j,k,q] [--cwd /path/to/repo]
+
+Env:
+    PI_CREW_BROKER_DIAG_UI=1   enable diag stderr writes from run-dashboard
+                              (only component wired; see src/ui/run-dashboard.ts:831)
+
+Examples:
+    # Default probe (vim nav + arrow keys + quit)
+    python3 scripts/pty_probe.py
+
+    # Custom probe: only arrow keys
+    python3 scripts/pty_probe.py --keys '\x1bOA,\x1bOB,\x1bOC,\x1bOD,q,q'
+
+    # Capture to a file
+    python3 scripts/pty_probe.py 2>&1 | tee /tmp/diag.log
+"""
+import argparse
+import os
+import pty
+import select
+import signal
+import sys
+import time
+
+
+# Default key sequence — exercises the dispatch path:
+#   j, j, k       — vim-style nav (j down, k up) in run-dashboard
+#   \x1b[A, \x1b[B — legacy CSI arrow up/down
+#   \x1bOA, \x1bOB — app-cursor-mode arrow up/down
+#   q, q          — quit (double-tap, matches the SettingsOverlay close binding)
+DEFAULT_KEYS = [
+    "j", "j", "k",
+    "\x1b[A", "\x1b[B",
+    "\x1bOA", "\x1bOB",
+    "q", "q",
+]
+
+# Per-key sleep — long enough for the TUI to process each input.
+DEFAULT_PER_KEY_SLEEP_S = 0.3
+
+# Initial sleep after `pi` spawn — let the TUI render before first keystroke.
+DEFAULT_STARTUP_SLEEP_S = 2.0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--keys",
+        default=",".join(DEFAULT_KEYS),
+        help="Comma-separated sequence of keys to send (default: vim nav + arrow + quit)",
+    )
+    parser.add_argument(
+        "--cwd",
+        default=os.getcwd(),
+        help="Working directory for the spawned pi process",
+    )
+    parser.add_argument(
+        "--per-key-sleep",
+        type=float,
+        default=DEFAULT_PER_KEY_SLEEP_S,
+        help=f"Sleep between keys (default {DEFAULT_PER_KEY_SLEEP_S}s)",
+    )
+    parser.add_argument(
+        "--startup-sleep",
+        type=float,
+        default=DEFAULT_STARTUP_SLEEP_S,
+        help=f"Initial sleep after pi spawn (default {DEFAULT_STARTUP_SLEEP_S}s)",
+    )
+    parser.add_argument(
+        "--read-chunk",
+        type=int,
+        default=65536,
+        help="Read chunk size in bytes (default 65536)",
+    )
+    args = parser.parse_args()
+
+    keys = []
+    for k in args.keys.split(","):
+        k = k.strip()
+        if not k:
+            continue
+        # Decode shell escape sequences: bash single-quotes don't expand
+        # \x1b, \033, \n, \t — so we expand them here.
+        # (DEFAULT_KEYS uses Python string literals which already expand.)
+        try:
+            k = k.encode("utf-8").decode("unicode_escape")
+        except (UnicodeDecodeError, ValueError):
+            pass  # use as-is if decode fails
+        keys.append(k)
+
+    env = {**os.environ, "PI_CREW_BROKER_DIAG_UI": "1"}
+
+    pid, fd = pty.fork()
+    if pid == 0:
+        # Child: exec `pi` in the requested cwd.
+        try:
+            os.chdir(args.cwd)
+            os.execvpe("pi", ["pi"], env)
+        except OSError as exc:
+            # execvpe failed (e.g. `pi` not in PATH) — write to the pty
+            # so the parent's read surfaces the error instead of hanging.
+            os.write(1, f"pty_probe: failed to exec pi: {exc}\n".encode())
+            os._exit(127)
+        # execvpe never returns on success.
+        os._exit(127)
+
+    # Parent: send keys with sleeps, then dump final screen.
+    try:
+        time.sleep(args.startup_sleep)
+        for k in keys:
+            os.write(fd, k.encode())
+            time.sleep(args.per_key_sleep)
+        time.sleep(args.startup_sleep)
+        # Read with a short timeout so we don't block forever if pi is quiet.
+        readable, _, _ = select.select([fd], [], [], 5.0)
+        if readable:
+            sys.stdout.write(os.read(fd, args.read_chunk).decode(errors="replace"))
+        else:
+            sys.stderr.write("pty_probe: no output from pi after 5s timeout\n")
+    finally:
+        # Reap the child to avoid zombies. The DEFAULT_KEYS sequence ends
+        # with 'q','q' which should quit pi; if it didn't, escalate.
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        try:
+            # Give pi 2s to exit gracefully, then SIGTERM, then SIGKILL.
+            _reap_child(pid, grace_s=2.0)
+        except OSError:
+            pass
+    return 0
+
+
+def _reap_child(pid: int, grace_s: float = 2.0) -> None:
+    """Wait for child to exit; escalate to SIGTERM then SIGKILL if needed."""
+    deadline = time.time() + grace_s
+    while time.time() < deadline:
+        waited, _status = os.waitpid(pid, os.WNOHANG)
+        if waited == pid:
+            return  # child exited cleanly
+        time.sleep(0.1)
+    # Still alive — SIGTERM.
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    deadline = time.time() + 2.0
+    while time.time() < deadline:
+        waited, _status = os.waitpid(pid, os.WNOHANG)
+        if waited == pid:
+            return
+        time.sleep(0.1)
+    # Still alive — SIGKILL.
+    try:
+        os.kill(pid, signal.SIGKILL)
+        os.waitpid(pid, 0)
+    except ProcessLookupError:
+        pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())