pi-crew 0.7.4 → 0.7.6

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # 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.
+
+### Features
+
+- **Ambient crew-status injection (GAP-2)** — registers Pi's `context` event handler so the parent agent stays continuously aware of in-flight crew runs on every LLM call, without calling the `team` tool. Injects a compact status note (runId/team/status/goal, capped at 3 inline) before the last message. **Transient and safe**: Pi uses the result only for that call (`agent-loop.ts:283-289`) — it never mutates persistent `state.messages`, so there's no accumulation or history corruption. No-op when zero runs are active. Toggle: `reliability.ambientStatusInjection`.
+
+### Performance (Round 15 audit)
+
+- **P1 (CRITICAL): throttle `persistSingleTaskUpdate` in `onJsonEvent`** — previously every child JSON event did a full locked read-parse-write of `tasks.json`; a 200-event task produced 200 such cycles. Now throttled to 500ms (in-memory progress stays fresh every event; final state force-flushed on completion).
+- **P4: `buildWorkspaceTree` TTL cache (30s)** — workers in a run share a cwd, so the recursive walk was repeated once per task.
+- **P5: `readKnowledge` mtime+size cache** — fired on every agent start (main + every worker), re-reading the same file N×/run.
+
+### Error experience (Round 15 audit)
+
+- **E1: extended CrewError taxonomy E007–E012** — the taxonomy previously covered only file I/O and discovery. The most common *runtime* failures (child timeout, model exhaustion, pre-step failure, event-log lock timeout, depth limit, stale run) now throw structured `CrewError`s with a machine-readable code, a default actionable help hint, and context. Wired into all six throw sites (`task-runner.ts`, `event-log.ts`, `pipeline-runner.ts`, `stale-reconciler.ts`).
+- **E2: model fallback exhaustion surfaces the full chain tried** ("All N candidates exhausted (tried: a → b → c). Last failure: …") instead of only the last attempt's raw error.
+- **E3: stale-reconcile error explains the heartbeat mechanism + remediation** instead of the bare "Stale run reconciled: <reason>".
+
+### Tests
+
+- +20 tests (context-status-injection: 11, errors E007–E012: 9). 4800+ pass / 0 fail.
+
+### Research
+
+This release was driven by the Round 11 Pi-API gap audit and the Round 15 performance/cost + error-experience audit, documented in `research-findings/`.
+
 ## [0.7.4] — Editor autocomplete + settings shortcut (2026-06-15)
 
 Round 13 UX quick wins round-out: the remaining two Pi extension API integrations plus a hard-won CI reliability fix after the state-store test flake re-emerged on Windows and macOS.

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.4",
+  "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/config/types.ts

@@ -178,6 +178,8 @@ export interface CrewReliabilityConfig {
 	autoRepairIntervalMs?: number;
 	/** Remove /tmp/pi-crew-* directories after their orphaned runs are reconciled. Default: true. */
 	cleanupOrphanedTempDirs?: boolean;
+	/** Inject a compact ambient crew-status note into the agent's context on every LLM call while crew runs are in-flight, so the agent stays continuously aware of active runs without calling the `team` tool. No-op when no runs are active. Default: true. */
+	ambientStatusInjection?: boolean;
 }
 
 export interface CrewOtlpConfig {

package/src/errors.ts

@@ -30,6 +30,14 @@ export const ErrorCode = {
   InvalidStatusTransition: "E004",  // Run/task status cannot legally transition
   ConfigError: "E005",              // Malformed config or missing required field
   ResourceNotFound: "E006",         // Agent/team/workflow not found in discovery paths
+  // E1 (Round 15): runtime failure categories that previously threw raw Error
+  // with no code, no help hint, and no context. Surfaces actionable guidance.
+  ChildTimeout: "E007",             // Child Pi worker became unresponsive and was killed
+  ModelExhausted: "E008",           // All model candidates in the fallback chain failed
+  PreStepFailed: "E009",            // A pre-step hook script returned a non-zero exit
+  EventLogLockTimeout: "E010",      // Could not acquire the event-log file lock
+  DepthLimitExceeded: "E011",       // Pipeline/chain recursion depth limit hit (circular dep)
+  RunStale: "E012",                 // Run reconciled as stale/zombie (heartbeat expired)
 } as const;
 
 export type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
@@ -41,6 +49,13 @@ const DEFAULT_HELP: Record<ErrorCode, string | undefined> = {
   [ErrorCode.InvalidStatusTransition]: "Verify the run status using `team status` before retrying.",
   [ErrorCode.ConfigError]: "Check the configuration file for syntax errors or missing required fields.",
   [ErrorCode.ResourceNotFound]: "Use `team list` to see available agents, teams, and workflows.",
+  // E1 (Round 15): help hints for the new runtime categories.
+  [ErrorCode.ChildTimeout]: "The child Pi worker produced no output for too long and was terminated. Re-run the team; if it recurs, raise the response timeout in config or reduce the task scope.",
+  [ErrorCode.ModelExhausted]: "Every model in the fallback chain failed. Check your API key/quota and the per-attempt errors, then retry or swap the model in config.",
+  [ErrorCode.PreStepFailed]: "The pre-step hook script exited non-zero. Inspect its stderr, or mark it optional in the workflow step (preStepOptional).",
+  [ErrorCode.EventLogLockTimeout]: "Another process holds the event-log lock. Check for orphaned `.lock` files or stale pi-crew processes, then retry.",
+  [ErrorCode.DepthLimitExceeded]: "A pipeline/chain exceeded the recursion depth limit, which usually indicates a circular stage dependency. Review step `dependsOn` chains.",
+  [ErrorCode.RunStale]: "The worker stopped heartbeating and was treated as a zombie. Re-run the team (resume or fresh); if it recurs, check `runtime.executeWorkers` / system load.",
 };
 
 /**
@@ -122,4 +137,55 @@ export const errors = {
       `${type} '${name}' not found in any discovery path`,
     );
   },
+
+  // E1 (Round 15): runtime failure constructors. These wrap the raw-throw
+  // sites identified in the Round 15 error-experience audit so failures carry
+  // a machine-readable code, a help hint, and structured context.
+  childTimeout(detail: { timeoutMs?: number; taskId?: string; stderr?: string }): CrewError {
+    const tail = detail.stderr ? ` Stderr tail: ${detail.stderr.slice(-400)}` : "";
+    const dur = detail.timeoutMs ? ` after ${detail.timeoutMs}ms of no output` : "";
+    return new CrewError(
+      ErrorCode.ChildTimeout,
+      `Child Pi worker became unresponsive${dur} and was terminated.${tail}`,
+    ).withContext(`worker execution${detail.taskId ? ` (task ${detail.taskId})` : ""}`);
+  },
+
+  modelExhausted(chain: string[], lastFailure?: string): CrewError {
+    const tried = chain.join(" → ");
+    const last = lastFailure ? ` Last failure: ${lastFailure}` : "";
+    return new CrewError(
+      ErrorCode.ModelExhausted,
+      `All ${chain.length} model candidates exhausted (tried: ${tried}).${last}`,
+    ).withContext("model fallback chain");
+  },
+
+  preStepFailed(script: string, exitCode: number | undefined, stderr?: string): CrewError {
+    const tail = stderr ? ` Stderr: ${stderr.slice(-400)}` : "";
+    return new CrewError(
+      ErrorCode.PreStepFailed,
+      `preStepScript '${script}' exited ${exitCode ?? "non-zero"}.${tail}`,
+    ).withContext("pre-step hook execution");
+  },
+
+  eventLogLockTimeout(eventsPath: string, timeoutMs: number): CrewError {
+    return new CrewError(
+      ErrorCode.EventLogLockTimeout,
+      `Event log lock timeout for ${eventsPath}: could not acquire lock within ${timeoutMs}ms`,
+    ).withContext("event-log append");
+  },
+
+  depthLimitExceeded(depth: number, kind = "pipeline"): CrewError {
+    return new CrewError(
+      ErrorCode.DepthLimitExceeded,
+      `${kind[0].toUpperCase() + kind.slice(1)} recursion depth limit exceeded (${depth}). Possible circular dependency.`,
+    ).withContext(`${kind} execution`);
+  },
+
+  runStale(reason: string, heartbeatAgeSeconds?: number): CrewError {
+    const age = heartbeatAgeSeconds !== undefined ? ` Last heartbeat was ${heartbeatAgeSeconds}s ago.` : "";
+    return new CrewError(
+      ErrorCode.RunStale,
+      `Stale run reconciled (reason=${reason}).${age} The worker stopped heartbeating and was treated as dead/zombie.`,
+    ).withContext("stale-run reconciliation");
+  },
 } as const;

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.`;
+}