pi-crew 0.7.5 → 0.7.6

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [0.7.6] — DX, observability, and a critical interactive-session hang fix (2026-06-16)
+
+This release bundles Rounds 16–28: a developer-experience pass, an observability pass, and eight correctness/security audits — culminating in the **fix for the pts/2 interactive-session busy-loop hang** (two separate Pi sessions had hung at 71.5% CPU with 339 inotify watches). All 24 commits passed CI on Windows, Ubuntu, and macOS.
+
+### 🚨 Critical — interactive-session hang (Round 28 + pts/2 investigation)
+
+Report: `/home/bom/pts2-hang-investigation-2026-06-16.md`. Three root causes, all fixed:
+
+- **BUG C (CRITICAL): recursive watcher busy-loop** — `watchCrewState` used `fs.watch(<crewRoot>/state, {recursive:true})`. On Linux, Node implements "recursive" as ONE inotify watch PER SUBDIRECTORY, so with many historical runs under `.crew/state/runs/` this ballooned to hundreds of watches (109→339 observed) and caused a permanent busy-loop even with no active work. **Fix**: new `src/utils/run-watcher-registry.ts` (`RunWatcherRegistry`) — one non-recursive watcher on the `runs/` root (for new-run detection, since `crew.run.created` is never emitted) + one non-recursive watcher per **active** run, reconciled each preload tick against `running`/`queued`/`planning` status. Total inotify cost is now O(active runs) — typically 1–5 — not O(total history). Completed runs leave the active set and their watcher closes within one tick. The dead `createRecursiveWatcher` / `watchCrewState` / `runIdFromStateRelativePath` primitives were deleted from `fs-watch.ts`.
+- **BUG A (MEDIUM): health double-join path** — `HEALTH_DIR = ".crew/state/health"` was joined with a `crewRoot` computed only 2 `dirname`s up, writing to `.crew/state/.crew/state/health` — a path **no code ever reads**. It produced a growing ghost subtree that the recursive watcher then walked. **Fix**: `crewRoot` = 3 `dirname`s up; `HEALTH_DIR` = `"state/health"`.
+- **BUG B (MEDIUM): OTLP CRLF injection** — header-value validation left CR (0x0D) and LF (0x0A) unblocked, enabling header-splitting / log-injection via crafted values. **Fix**: regex now `/[\x00-\x08\x0a-\x1f]/`.
+
+Cleanup: 246 orphaned health snapshots (~1 MB) across 4 bogus `.crew/state/.crew/state/` subtrees were removed.
+
+### Correctness audits (Rounds 22–27)
+
+- **Round 27 — resource leaks**: (1) orphaned heartbeat timer in the team-runner catch block (`stopTeamHeartbeat()` never called on the error path; non-unref'd 30s interval kept the event loop alive → foreground pi hung); (2) FD leak in background-runner (`fs.openSync` without `closeSync`); (3) pipe FD leak + potential deadlock in async-runner (piped stdout/stderr never drained → >64 KB blocks forever); (4) AbortSignal listener leak in child-pi + live-session-runtime (anonymous `{once:true}` listeners never removed on normal completion).
+- **Round 26 — cross-process file-locking** (5 bugs): TOCTOU split-read in `acquireLockWithRetry` (single-snapshot read closes the window); racy pre-acquisition target cleanup in `withFileLockSync` (removed); crash-between-mkdir-and-pidFile wedge (mtime-based stale check); PID-recycling wedge (mtime checked first for all holders); non-token-guarded release (PID-guarded removal).
+- **Round 25 — security**: deleted two vulnerable dead modules — `sandbox.ts` (CRITICAL VM sandbox escape) and `dynamic-script-runner.ts` (HIGH `skip-validateScript`) — totalling −1701 LOC across 2 source + 5 test files. Plus closed verification-gate newline + `$VARNAME` injection (DANGEROUS_SHELL_PATTERNS extended).
+- **Round 24 — event-log deadlock**: `appendEventInsideLock` (already inside `withEventLogLockSync`) called the public `compactEventLog`/`rotateEventLog` which re-acquired the same non-reentrant mkdir lock → 5 s timeout → compaction never ran → unbounded log growth → events silently dropped past 50 MB. Fix: extracted `prepareCompaction` / `applyCompactionUnlocked` / `rotateEventLogUnlocked` into `event-log-rotation.ts`.
+- **Round 23 — UI correctness**: negative live duration in `agents-pane.ts` (shared `src/ui/live-duration.ts`); Unicode width/truncation bugs in `card-colors.ts`, `tool-renderers/index.ts`, `tool-render.ts`.
+- **Round 22 — reliability**: checkpoint `.tmp.checkpoint` was reused across concurrent saves (cross-process data corruption → now unique per save); chain-parser had no recursion-depth limit (now `MAX_CHAIN_NESTING=100`).
+
+### Developer experience (Round 16)
+
+- **F1 "Did you mean?"** suggestions on unknown team actions.
+- **F2 recovery hint** on all "Run not found" errors.
+- **F3 compact status mode** (`details=false`) for low-noise polling.
+- **F4 config errors surfaced** on the run path.
+- **F5 pipeline dead-end redirect** — unsupported `action=pipeline` now points at a working workflow.
+- **F6 troubleshooting guide** added at `docs/troubleshooting.md`; usage.md config path fixed.
+
+### Observability (Round 17)
+
+- **Progress % + ETA** in `status`; run age in the ambient context note.
+- **Per-agent cost** in the dashboard + status output.
+- **Aggregate failure patterns** in the run summary.
+
+### Features
+
+- **Round 21 (E4): `preStepOptional`** — advisory pre-step hooks that don't fail the run. Opt-in (`preStepOptional: true` on a `WorkflowStep`); fail-fast remains the default.
+- **Round 18 (defense-in-depth)**: capped `suggestAction` input length.
+
+### Tests
+
+- +60+ tests across Rounds 16–28 (run-watcher-registry: 12, event-log deadlock: 5, injection guards: 6, file/event-log locks: 8, plus UI, DX, observability, and test-isolation coverage). 4955 pass / 0 fail. Test health pass restored the false-confidence security suite.
+
+### Documentation
+
+- Round 20 documentation-accuracy audit fixed 8 defects across README, CHANGELOG, and `docs/`.
+
 ## [0.7.5] — Ambient context status + perf hardening + error taxonomy (2026-06-15)
 
 Three workstreams from the Round 11 API-gap and Round 15 perf/error audits: a new `context`-event feature, three performance fixes, and a full error-taxonomy expansion.

package/README.md

@@ -231,20 +231,19 @@ If preconditions are not met, a friendly error message is returned instead of cr
 
 | Scope | Path |
 |-------|------|
-| User | `~/.pi/agent/extensions/pi-crew/config.json` |
-| Project (new) | `.crew/config.json` |
-| Project (legacy) | `.pi/teams/config.json` |
+| User (primary) | `~/.pi/agent/pi-crew.json` |
+| User (legacy, still read for migration) | `~/.pi/agent/extensions/pi-crew/config.json` |
+| Project (crewRoot) | `.crew/config.json` (or `.pi/teams/config.json` legacy) |
+| Project (alt) | `.pi/pi-crew.json` |
 
 ### Quick Config
 
 ```text
 /team-config                           # view all settings
-/team-config get runtime.mode            # read one key
-/team-config set runtime.mode=scaffold  # scaffold mode
-/team-config set asyncByDefault=true    # async by default
-/team-config unset runtime.mode          # reset to default
-/team-config --project                  # project scope
-/team-settings path                     # show config file path
+/team-config runtime.mode=scaffold    # set a key (--project for project scope)
+/team-config --unset=runtime.mode     # reset a key to default
+/team-config --project runtime.mode   # project-scoped view
+/team-settings path                   # show config file path
 ```
 
 ### Key Settings
@@ -262,8 +261,8 @@ If preconditions are not met, a friendly error message is returned instead of cr
 | **UI** | `widgetPlacement`, `dashboardPlacement` | compact widget |
 | | `showModel`, `showTokens` | display controls |
 | **Reliability** | `autoRetry`, `autoRecover`, `deadletterThreshold` | opt-in |
-| **Observability** | `prometheus.enabled`, `otlp.enabled`, `heartbeatStaleMs` | opt-in |
-| **Worktree** | `worktree.enabled` | disabled by default |
+| **Observability** | `observability.enabled`, `observability.pollIntervalMs`, `otlp.enabled`/`otlp.endpoint` | opt-in |
+| **Worktree** | `worktree.setupHook`, `worktree.linkNodeModules`, `worktree.seedPaths` (mode is set via `workspaceMode: "worktree"` at run time) | disabled by default |
 
 > ⚠️ **Trust boundary**: project config cannot override sensitive execution controls (workers, runtime mode, autonomy, agent overrides). Set those in **user config** only.
 
@@ -515,6 +514,7 @@ Stats: **366 source files** (70K lines) · **506 test files** (66K lines) · **4
 | [docs/commands-reference.md](docs/commands-reference.md) | Slash commands + `/team-api` |
 | [docs/resource-formats.md](docs/resource-formats.md) | Agent/team/workflow file formats |
 | [docs/usage.md](docs/usage.md) | Usage patterns + config examples |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Common errors, recovery, and error-code reference (E001–E012) |
 | [docs/architecture.md](docs/architecture.md) | Internal architecture + run flow |
 | [docs/runtime-flow.md](docs/runtime-flow.md) | Runtime execution details |
 | [docs/live-mailbox-runtime.md](docs/live-mailbox-runtime.md) | Mailbox + live-session runtime |

package/docs/commands-reference.md

@@ -188,13 +188,13 @@ Giữ lại 20 runs gần nhất, xóa phần còn lại.
 | `runtime.groupJoinAckTimeoutMs` | number | `300000` | Group join ack timeout (ms) |
 | `runtime.requirePlanApproval` | boolean | `false` | Yêu cầu approve plan trước execute |
 | `runtime.completionMutationGuard` | string | `"warn"` | `off`, `warn`, `fail` |
-| `limits.maxConcurrentWorkers` | number | — | Max workers chạy song song |
-| `limits.maxTaskDepth` | number | `2` | Max task tree depth |
-| `limits.maxChildrenPerTask` | number | `5` | Max children per task |
-| `limits.maxRunMinutes` | number | `60` | Max run duration (phút) |
-| `limits.maxRetriesPerTask` | number | `1` | Max retries per task |
-| `limits.maxTasksPerRun` | number | — | Max tasks per run |
-| `limits.heartbeatStaleMs` | number | `60000` | Heartbeat stale threshold |
+| `limits.maxConcurrentWorkers` | number | `1024` | Max workers chạy song song |
+| `limits.maxTaskDepth` | number | `100` | Max task tree depth |
+| `limits.maxChildrenPerTask` | number | — | Max children per task |
+| `limits.maxRunMinutes` | number | `1440` | Max run duration (phút) |
+| `limits.maxRetriesPerTask` | number | `100` | Max retries per task |
+| `limits.maxTasksPerRun` | number | `10000` | Max tasks per run |
+| `limits.heartbeatStaleMs` | number | `86400000` | Heartbeat stale threshold |
 | `control.enabled` | boolean | — | Enable agent control-plane |
 | `control.needsAttentionAfterMs` | number | — | Attention timeout |
 | `autonomous.profile` | string | `"suggested"` | `manual`, `suggested`, `assisted`, `aggressive` |
@@ -205,9 +205,13 @@ Giữ lại 20 runs gần nhất, xóa phần còn lại.
 | `tools.enableSteer` | boolean | `true` | Enable steer tool |
 | `tools.terminateOnForeground` | boolean | `false` | Return terminate từ foreground Agent |
 | `agents.disableBuiltins` | boolean | `false` | Disable builtin agents |
-| `observability.prometheus.enabled` | boolean | `false` | Enable Prometheus exporter |
-| `observability.otlp.enabled` | boolean | `false` | Enable OTLP exporter |
-| `worktree.enabled` | boolean | — | Enable worktree isolation |
+| `observability.enabled` | boolean | `false` | Enable metrics collection |
+| `observability.pollIntervalMs` | number | — | Metrics poll interval |
+| `otlp.enabled` | boolean | `false` | Enable OTLP exporter |
+| `otlp.endpoint` | string | — | OTLP endpoint URL |
+| `worktree.setupHook` | string | — | Worktree setup hook command |
+| `worktree.linkNodeModules` | boolean | — | Symlink node_modules into worktree |
+| `worktree.seedPaths` | array | — | Extra paths to seed into worktree |
 
 ---
 

package/docs/troubleshooting.md

@@ -0,0 +1,131 @@
+# Troubleshooting
+
+Common problems and their fixes. If you hit an error code (E001–E012), see the
+[Error codes](#error-codes) table below.
+
+## Quick health check
+
+```text
+team action='doctor'
+team action='health'
+```
+
+`doctor` validates your config, runtime, and worker setup. `health` shows live
+run/process status. Start here.
+
+## Runs won't start / workers are "blocked"
+
+**Symptom:** `team action='run'` returns a `blocked` status with a message like
+"Child worker execution is disabled".
+
+**Cause:** Worker execution is off. pi-crew refuses to create no-op scaffold
+subagents by default until you opt in.
+
+**Fix — pick one:**
+- Set in your config (`~/.pi/agent/pi-crew.json`): `"executeWorkers": true`
+- Or set the env var: `PI_CREW_EXECUTE_WORKERS=1`
+- Or pass at run time: `team action='run' config={runtime:{mode:'live-session'}}`
+
+The blocked-run message lists the exact config + env vars in play — read it.
+
+## "Run not found" / I lost my run ID
+
+Run IDs are long (`team_20260615180014_a1b2c3d4e5f60718`). To recover:
+
+```text
+team action='list'              # recent runs + IDs
+team action='status'            # status of in-flight runs in this project
+team action='artifacts' runId=… # if you only have a partial ID
+```
+
+Every "Run not found" error now appends a `Tip: run action='list'` hint.
+
+## "Unknown action: X"
+
+You typo'd an action. The error now suggests the closest match
+(`Did you mean 'status'?`). To see all valid actions:
+
+```text
+team action='help'
+team action='list' resource='workflow'
+```
+
+## Worktree runs fail ("not a git repo" / "tree is dirty")
+
+Worktree mode (`workspaceMode: 'worktree'`) requires:
+1. The target directory is a **git repository** (`git rev-parse` succeeds).
+2. The working tree is **clean** (no uncommitted changes) unless you pass
+   `force: true`.
+
+If you don't need isolation, use single mode instead:
+`team action='run' workspaceMode='single'`.
+
+## Stale async process / run stuck in "running"
+
+A background run whose process died (crash, Ctrl+C, reboot) can appear stuck
+in `running`. The stale-reconciler eventually marks it `failed`, but you can
+force recovery:
+
+```text
+team action='status' runId=…    # check the async liveness line
+team action='cleanup' runId=…   # repair stuck state
+team action='cancel' runId=…    # cancel a truly-dead run
+```
+
+The error message explains the heartbeat mechanism + remediation.
+
+## Model fallback exhausted
+
+**Symptom:** `All N candidates exhausted (tried: a → b → c)`.
+
+**Cause:** Every model in your fallback chain failed (rate limit, auth, quota).
+
+**Fix:** Check your provider config / API keys. The error now lists the full
+chain tried and the last failure reason.
+
+## Config is malformed / ignored
+
+If your `pi-crew.json` has a syntax or type error, `team action='run'` emits a
+`config.warning` event (visible via `team action='events'`) and proceeds with
+defaults — it does **not** hard-fail. To validate explicitly:
+
+```text
+team action='config'            # show loaded config + any warnings
+team action='doctor'            # full validation
+```
+
+## Compact vs full status
+
+`team action='status'` defaults to full output (~40 lines). For a quick check:
+
+```text
+team action='status' details=false   # compact: status, progress, goal, issues only
+```
+
+## Error codes
+
+pi-crew uses a structured error taxonomy (E001–E012). Each error renders its
+code + a help hint inline. Common ones:
+
+| Code | Name | Meaning | First check |
+|------|------|---------|-------------|
+| E001 | FileReadError | a required file couldn't be read | check the file exists + read perms; may need `cleanup` |
+| E002 | FileWriteError | an atomic write failed | check disk space + dir write perms |
+| E003 | TaskNotFound | a referenced task id doesn't exist | `team status` to verify the run's tasks |
+| E004 | InvalidStatusTransition | illegal run/task status change | verify status via `team status` before retrying |
+| E005 | ConfigError | config has a syntax/type error | `team config` shows the offending field |
+| E006 | ResourceNotFound | agent/team/workflow not found | `team list` to see available resources |
+| E007 | ChildTimeout | a worker Pi didn't finish in time | raise `runtime.responseTimeoutMs` or simplify the task |
+| E008 | ModelExhausted | all fallback models failed | see "Model fallback exhausted" above |
+| E009 | PreStepFailed | a workflow pre-step hook failed | check the hook stderr in events; set `preStepOptional: true` on the step to make it advisory (non-fatal) |
+| E010 | EventLogLockTimeout | event log locked under contention | transient; retry, or lower concurrency |
+| E011 | DepthLimitExceeded | crew nesting too deep | raise `crew.maxDepth` or flatten the call |
+| E012 | RunStale | run reconciled as stale | see "Stale async process" above |
+
+## Still stuck
+
+- `team action='explain' runId=…` — structured per-task analysis (why, files,
+  complexity).
+- `team action='summary' runId=…` — includes common failure-pattern detection
+  ("4 of 5 failures share 2 root causes").
+- `team action='events' runId=…` — full event timeline for forensics.

package/docs/usage.md

@@ -5,9 +5,14 @@
 Optional config path:
 
 ```text
-~/.pi/agent/extensions/pi-crew/config.json
+~/.pi/agent/pi-crew.json
 ```
 
+A **legacy** path `~/.pi/agent/extensions/pi-crew/config.json` is also read for
+backward-compatibility migration — values there are merged but the new path
+above is preferred. A project-local config may also live at `.pi/pi-crew.json`
+in your repo root (project values are merged under the user config).
+
 Create a default config:
 
 ```bash
@@ -58,9 +63,9 @@ Supported fields:
     "deadletterThreshold": 3,
     "retryPolicy": {
       "maxAttempts": 3,
-      "initialDelayMs": 1000,
-      "backoffMultiplier": 2,
-      "maxDelayMs": 30000
+      "backoffMs": 1000,
+      "jitterRatio": 0.3,
+      "exponentialFactor": 2
     }
   }
 }

package/package.json

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

package/src/config/config.ts

@@ -494,8 +494,14 @@ function mergeConfig(
 			delete merged.otlp.headers;
 		// Validate OTLP headers for injection attacks:
 		// - Check top-level keys for dangerous prototype pollution patterns
-		// - Block all control characters (except tab=0x09, newline=0x0A) to prevent
-		//   header injection via CR/LF/zero-byte/etc.
+		// - Block ALL control characters except tab (0x09) to prevent header
+		//   injection via CR/LF/zero-byte/etc.
+		// BUG (Round 28, CRLF injection): the previous range
+		//   /[\x00-\x08\x0b\x0c\x0e-\x1f]/ left THREE chars unblocked: tab (0x09,
+		//   intentionally allowed), LF (0x0A) AND CR (0x0D). The comment claimed to
+		//   "prevent header injection via CR/LF" but CR was never matched, and LF
+		//   was explicitly allowed — both are CRLF injection vectors that can split
+		//   HTTP headers. Fix: block 0x00-0x08 and 0x0A-0x1F, allowing only tab.
 		const invalidHeaders: string[] = [];
 		for (const [k, v] of Object.entries(merged.otlp.headers ?? {})) {
 			// Check top-level key for dangerous names (only top-level keys are checked)
@@ -505,9 +511,10 @@ function mergeConfig(
 				return false;
 			};
 			if (checkKey(k)) { invalidHeaders.push(k); continue; }
-			// Block any control characters except tab (0x09) in values
+			// Block any control characters except tab (0x09) in values.
+			// Round 28 fix: /[\x00-\x08\x0a-\x1f]/ blocks LF (0x0A) and CR (0x0D) too.
 			const valStr = String(v);
-			if (/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(valStr)) { invalidHeaders.push(k); }
+			if (/[\x00-\x08\x0a-\x1f]/.test(valStr)) { invalidHeaders.push(k); }
 		}
 		if (invalidHeaders.length > 0) {
 			delete merged.otlp.headers;

package/src/extension/action-suggestions.ts

@@ -0,0 +1,71 @@
+/**
+ * action-suggestions.ts — "Did you mean?" suggestions for team actions (DX: F1).
+ *
+ * Round 16 DX audit found that a typo'd action (`action: 'stat'`,
+ * `action: 'summery'`) hits a dead-end "Unknown action: stat" with no path
+ * forward. pi-crew already ships a Levenshtein fuzzy-matcher
+ * (`src/config/suggestions.ts → suggestConfigKey`); this module applies it to
+ * the known set of team actions.
+ *
+ * The known-action list mirrors the `action` enum in
+ * `src/schema/team-tool-schema.ts`. Kept as a hand-maintained constant (not
+ * derived from the TypeBox schema at runtime) so it is trivially testable and
+ * avoids pulling the schema into low-level error paths.
+ */
+
+import { findClosestKey } from "../config/suggestions.ts";
+
+/**
+ * The complete set of valid top-level `team` actions (mirrors the action enum
+ * in `src/schema/team-tool-schema.ts`). Exported so callers and tests can use
+ * the single source of truth.
+ */
+export const KNOWN_TEAM_ACTIONS = [
+	"run", "parallel", "plan", "status", "wait", "list", "get",
+	"cancel", "retry", "resume", "respond", "create", "update", "delete",
+	"doctor", "cleanup", "events", "artifacts", "worktrees", "forget",
+	"summary", "prune", "export", "import", "imports", "help", "validate",
+	"config", "init", "recommend", "autonomy", "api", "settings", "steer",
+	"invalidate", "health", "graph", "onboard", "explain", "cache",
+	"checkpoint", "search", "orchestrate", "schedule", "scheduled", "anchor",
+	"auto-summarize", "auto_boomerang",
+] as const;
+
+/**
+ * Suggest the closest known team action for a (likely typo'd) input.
+ * Returns `null` when no action is close enough — callers should then omit
+ * the "Did you mean …?" hint rather than suggesting a poor match.
+ *
+ * Uses a tighter edit-distance budget than the generic config-key suggester
+ * (2 instead of 3): team actions are short command words, so distance-3
+ * matches against a short input (e.g. "" → "run") produce low-quality hints.
+ * Empty/whitespace input always returns null.
+ *
+ * Exported for unit testing.
+ */
+export function suggestAction(input: string): string | null {
+	const trimmed = input.trim();
+	if (!trimmed) return null;
+	// Defense-in-depth (Round 18 security F1): levenshtein is O(n×m). A hostile
+	// very-long input would waste cycles. The action is enum-validated upstream
+	// so this is unreachable in practice, but cap input length cheaply.
+	if (trimmed.length > 64) return null;
+	return findClosestKey(trimmed, KNOWN_TEAM_ACTIONS, 2);
+}
+
+/**
+ * Build a "Did you mean?" suffix for an unknown-action error message.
+ * Returns "" when there is no good suggestion (so the caller can just append
+ * it unconditionally). Keeps error formatting centralized.
+ *
+ * Exported for unit testing + use in the dispatch default-case.
+ *
+ * Example:
+ *   formatActionSuggestion("stat")    // "\n\nDid you mean 'status'? Use action='status'."
+ *   formatActionSuggestion("xyzzy")   // ""
+ */
+export function formatActionSuggestion(input: string): string {
+	const suggestion = suggestAction(input);
+	if (!suggestion || suggestion === input) return "";
+	return `\n\nDid you mean '${suggestion}'? Use action='${suggestion}'. Run action='help' to see all actions.`;
+}

package/src/extension/context-status-injection.ts

@@ -45,6 +45,36 @@ const MAX_INLINE_RUNS = 3;
 /** Truncate long goals so one run can't dominate the context window. */
 const MAX_GOAL_LEN = 80;
 
+/**
+ * Cheap human-readable run age from manifest timestamps (no extra I/O).
+ * Returns "running 12m" / "updated 3m ago" style, or "" if timestamps are
+ * missing/invalid. Keeps the ambient note informative without reading
+ * tasks.json on every LLM call.
+ */
+function runAge(createdAt?: string, updatedAt?: string): string {
+	try {
+		const updated = updatedAt ? Date.parse(updatedAt) : NaN;
+		const created = createdAt ? Date.parse(createdAt) : NaN;
+		if (Number.isFinite(updated)) {
+			const sinceUpdate = Date.now() - updated;
+			if (sinceUpdate < 60_000) return `, updated just now`;
+			return `, updated ${humanizeMs(sinceUpdate)} ago`;
+		}
+		if (Number.isFinite(created)) {
+			return `, running ${humanizeMs(Date.now() - created)}`;
+		}
+	} catch { /* ignore malformed timestamps */ }
+	return "";
+}
+
+function humanizeMs(ms: number): string {
+	if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+	const m = Math.floor(ms / 60_000);
+	if (m < 60) return `${m}m`;
+	const h = Math.floor(m / 60);
+	return h < 24 ? `${h}h${m % 60}m` : `${Math.floor(h / 24)}d`;
+}
+
 /**
  * Build a compact, human+LLM-readable ambient status string for the given
  * in-flight runs. Returns "" for an empty list (caller treats as no-op).
@@ -62,7 +92,8 @@ export function formatAmbientStatus(runs: TeamRunManifest[]): string {
 	const shown = runs.slice(0, MAX_INLINE_RUNS);
 	for (const run of shown) {
 		const wf = run.workflow ? `, ${run.workflow}` : "";
-		lines.push(`• ${run.runId} (${run.status}, ${run.team}${wf}): ${truncate(run.goal ?? "(no goal)", MAX_GOAL_LEN)}`);
+		const age = runAge(run.createdAt, run.updatedAt);
+		lines.push(`• ${run.runId} (${run.status}, ${run.team}${wf})${age}: ${truncate(run.goal ?? "(no goal)", MAX_GOAL_LEN)}`);
 	}
 	if (runs.length > MAX_INLINE_RUNS) {
 		lines.push(`• …and ${runs.length - MAX_INLINE_RUNS} more`);

package/src/extension/register.ts

@@ -82,7 +82,8 @@ import {
 import { RenderScheduler } from "../ui/render-scheduler.ts";
 import { runEventBus } from "../ui/run-event-bus.ts";
 import { createRunSnapshotCache } from "../ui/run-snapshot-cache.ts";
-import { closeWatcher, watchCrewState } from "../utils/fs-watch.ts";
+import { closeWatcher } from "../utils/fs-watch.ts";
+import { RunWatcherRegistry } from "../utils/run-watcher-registry.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import {
 	clearProjectRootCache,
@@ -725,8 +726,13 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	// Linux), file changes (manifest/tasks/events/agents) trigger an
 	// immediate cache invalidate via renderScheduler.schedule. Falls back to
 	// poll-only behavior on systems where fs.watch errors.
-	let crewWatcher: import("node:fs").FSWatcher | undefined;
-	let userCrewWatcher: import("node:fs").FSWatcher | undefined;
+	// pts/2 hang fix (2026-06-16): the previous RECURSIVE fs.watch(<state>, {recursive:true})
+	// exploded to O(total run history) inotify watches on Linux (109→339 observed) and
+	// caused a permanent busy-loop. Replaced with bounded per-active-run watchers via
+	// RunWatcherRegistry (root watcher on runs/ for new-run detection + one non-recursive
+	// watcher per active run, reconciled each preload tick in buildFrame).
+	let crewRunWatchers: RunWatcherRegistry | undefined;
+	let userCrewWatchers: RunWatcherRegistry | undefined;
 	// Separate map for foreground team-run AbortControllers (distinct from subagent controllers).
 	// P0 fix: stopSessionBoundSubagents must NOT abort foreground team runs on session switch.
 	// Foreground team runs run in the same process as the session; they naturally clean up
@@ -1116,10 +1122,10 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 			clearTimeout(preloadTimer);
 			preloadTimer = undefined;
 		}
-		closeWatcher(crewWatcher);
-		crewWatcher = undefined;
-		closeWatcher(userCrewWatcher);
-		userCrewWatcher = undefined;
+		crewRunWatchers?.closeAll();
+		crewRunWatchers = undefined;
+		userCrewWatchers?.closeAll();
+		userCrewWatchers = undefined;
 		stopSessionBoundSubagents();
 		// P0 fix: also abort foreground team runs on session shutdown (not on session switch).
 		// This is the only place where foreground team run controllers should be aborted.
@@ -1590,6 +1596,25 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 			lastFrameSnapshotCache = getRunSnapshotCache(currentCtx.cwd);
 			const manifests = lastFrameManifestCache.list(20);
 			lastPreloadedManifests = manifests;
+			// pts/2 hang fix: reconcile per-run watchers against the ACTIVE set only.
+			// This bounds inotify cost to O(active runs) — completed runs stop being
+			// watched as soon as they leave running/queued/planning status, instead of
+			// the recursive watcher watching the entire run history forever.
+			{
+				const onRunChange = (runId: string): void => {
+					if (cleanedUp || sessionGeneration !== ownerGeneration) return;
+					getRunSnapshotCache(currentCtx?.cwd ?? process.cwd()).invalidate(runId);
+					renderScheduler?.schedule({ runId });
+				};
+				const onWatchErr = (error: unknown): void => {
+					logInternalError("register.runWatcher.change", error);
+				};
+				const active = manifests
+					.filter((r) => r.status === "running" || r.status === "queued" || r.status === "planning")
+					.map((r) => ({ runId: r.runId, runDir: r.stateRoot }));
+				crewRunWatchers?.reconcile(active, onRunChange, onWatchErr);
+				userCrewWatchers?.reconcile(active, onRunChange, onWatchErr);
+			}
 			const runIds = manifests.map((r) => r.runId);
 			await lastFrameSnapshotCache.preloadAllStale(runIds);
 			return true;
@@ -1815,72 +1840,53 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		renderSchedulerUnsubscribers.push(unsubscribeRunEvents);
 		// Start async preload loop — refreshes snapshot cache in background
 		startPreloadLoop(fallbackMs, effectiveRefreshMs);
-		// 1.3: native FS watcher on `<crewRoot>/state`. Triggers an immediate
-		// renderScheduler.schedule({runId}) when files inside any run change so
-		// the snapshot cache invalidates well before the 1s preload tick. Falls
-		// back silently to poll-only behavior on systems where recursive
-		// fs.watch is not supported.
+		// 1.3: BOUNDED run watcher (pts/2 hang fix 2026-06-16). Previously this was
+		// a RECURSIVE fs.watch(<state>, {recursive:true}) which on Linux expands to
+		// ONE inotify watch PER SUBDIR — with many historical runs under
+		// .crew/state/runs/ this ballooned to hundreds of watches (109→339 observed)
+		// and the event volume caused a permanent busy-loop (71% CPU, 400KB/s read).
+		// Now: a single non-recursive watcher on the runs/ ROOT (to detect new run
+		// dirs appearing — crew.run.created is never emitted) plus per-active-run
+		// watchers reconciled each preload tick in buildFrame. Total inotify cost is
+		// O(active runs), not O(total history). Falls back to poll-only (the preload
+		// loop already polls every effectiveRefreshMs) on systems where fs.watch
+		// errors or the runs dir is absent.
+		const crewRunWatcherOnChange = (runId: string): void => {
+			if (cleanedUp || sessionGeneration !== ownerGeneration) return;
+			getRunSnapshotCache(currentCtx?.cwd ?? process.cwd()).invalidate(runId);
+			renderScheduler?.schedule({ runId });
+		};
+		const crewRunWatcherOnError = (error: unknown): void => {
+			logInternalError("register.crewRunWatchers.error", error);
+		};
 		try {
-			closeWatcher(crewWatcher);
-			crewWatcher = undefined;
-			const stateDir = path.join(projectCrewRoot(ctx.cwd), "state");
-			const watcher = watchCrewState(
-				stateDir,
-				(runId) => {
-					if (cleanedUp || sessionGeneration !== ownerGeneration)
-						return;
-					// Invalidate snapshot cache so the next renderTick reads fresh state from disk.
-					// Without this, renderTick re-renders from stale lastPreloadedManifests and
-					// shows ghost "running" entries for runs that already completed on disk.
-					const sc = getRunSnapshotCache(
-						currentCtx?.cwd ?? process.cwd(),
-					);
-					sc.invalidate(runId);
-					renderScheduler?.schedule({ runId });
-				},
-				(error) => {
-					logInternalError("register.crewWatcher.error", error);
-					closeWatcher(crewWatcher);
-					crewWatcher = undefined;
-				},
-			);
-			if (watcher) crewWatcher = watcher;
+			crewRunWatchers?.closeAll();
+			crewRunWatchers = undefined;
+			const crewRunsDir = path.join(projectCrewRoot(ctx.cwd), "state", "runs");
+			if (fs.existsSync(crewRunsDir)) {
+				crewRunWatchers = new RunWatcherRegistry();
+				crewRunWatchers.setRootWatcher(crewRunsDir, crewRunWatcherOnChange, crewRunWatcherOnError);
+			}
 		} catch (error) {
-			logInternalError("register.crewWatcher.start", error);
+			logInternalError("register.crewRunWatchers.start", error);
 		}
-		// Also watch user-level state dir — fast-fix and other user-scoped runs
-		// write manifests there. Without this watcher, runs completing in user-level
+		// Also watch user-level runs dir — fast-fix and other user-scoped runs
+		// write manifests there. Without this, runs completing in user-level
 		// state never trigger cache invalidation, causing ghost "running" entries.
 		try {
-			closeWatcher(userCrewWatcher);
-			userCrewWatcher = undefined;
-			const userStateDir = path.join(userCrewRoot(), "state");
-			if (fs.existsSync(userStateDir)) {
-				const userWatcher = watchCrewState(
-					userStateDir,
-					(runId) => {
-						if (cleanedUp || sessionGeneration !== ownerGeneration)
-							return;
-						const sc = getRunSnapshotCache(
-							currentCtx?.cwd ?? process.cwd(),
-						);
-						sc.invalidate(runId);
-						renderScheduler?.schedule({ runId });
-					},
-					(error) => {
-						logInternalError(
-							"register.userCrewWatcher.error",
-							error,
-						);
-						closeWatcher(userCrewWatcher);
-						userCrewWatcher = undefined;
-					},
-				);
-				if (userWatcher) userCrewWatcher = userWatcher;
+			userCrewWatchers?.closeAll();
+			userCrewWatchers = undefined;
+			const userRunsDir = path.join(userCrewRoot(), "state", "runs");
+			if (fs.existsSync(userRunsDir)) {
+				userCrewWatchers = new RunWatcherRegistry();
+				userCrewWatchers.setRootWatcher(userRunsDir, crewRunWatcherOnChange, crewRunWatcherOnError);
 			}
 		} catch (error) {
-			logInternalError("register.userCrewWatcher.start", error);
+			logInternalError("register.userCrewWatchers.start", error);
 		}
+		// Kick an immediate preload so the first buildFrame reconciles per-run
+		// watchers for any runs that are already active on session start.
+		backgroundPreload();
 	});
 	pi.on("session_before_switch", () => {
 		sessionGeneration++;