pi-crew 0.7.5 → 0.7.7

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [0.7.7] — Windows spawn fix + plan-approval crash-recovery fix + CI flake fixes (2026-06-16)
+
+A focused patch release driven by two community reports (Issue #33 and PR #32) plus the CI flake surfaced while validating them. CI green on Windows / Ubuntu / macOS (run 27599121797). 4965 tests pass / 0 fail.
+
+### Bug Fixes
+
+- **`#33` — Windows `spawn pi ENOENT`** (commit `afc23b4`): when pi is installed outside `%APPDATA%\npm` (nvm-windows / Volta / fnm put the global `node_modules` elsewhere), the static `%APPDATA%\npm` paths in `resolvePiCliScript()` all miss, and the fallback `spawn("pi")` fails with `ENOENT` because `child_process.spawn` does NOT do PATHEXT resolution on Windows (only `exec`/`execSync` via `cmd.exe` do). **Fix**: pi-crew now discovers the real npm global `node_modules` dir at runtime via `npm root -g` (run through `execSync`, which DOES resolve `npm.cmd` via PATHEXT), then derives the `@earendil-works` / `@mariozechner` package dirs from it and checks them BEFORE the static `%APPDATA%\npm` paths and the cwd fallback. Covers standard installs **and** nvm-windows / Volta / fnm uniformly. Memoized once per process (one-time ~200ms cost). Injection-safe — no `shell: true` on the real worker spawn. +6 tests.
+- **Plan-approval-blocked runs crash-recovery fix** (commit `421b76d`, adapts PR #32 change #1 by @gustavo-pelissaro): crash recovery and stale reconciliation both treated `status === "blocked"` runs as repair candidates, so a run legitimately blocked on **human** plan approval (`requirePlanApproval`, `status="pending"`) was marked failed and/or orphan-cancelled when its owning session died or its async PID was no longer live — destroying an in-flight HITL checkpoint. **Fix**: new `isPlanApprovalPending(manifest)` guard (status=blocked AND `planApproval.required=true` AND `planApproval.status=pending`). Guarded in `reconcileStaleRun` (new `blocked_awaiting_approval` verdict, `repaired=false` — which automatically covers `reconcileAllStaleRuns`), `detectInterruptedRuns` (skip), `cancelOrphanedRuns` (push to `skipped`), and a belt-and-suspenders re-check under the lock in `reconcileAllStaleRuns`. The guard is intentionally narrow: a plain `blocked` run (no planApproval, or already approved/cancelled) is still a recovery candidate, so existing orphaned-blocked-run handling is unchanged. +6 tests.
+
+### Tests (CI reliability)
+
+- **`run-watcher-registry` macOS cancellation** (commit `dccb5e7`): the two fs.watch-dependent tests used unbounded `done()` callbacks that hung the whole test file on macOS CI runners (fs.watch events are slow/dropped under `/var/folders` + VM-runner FS load). Fixed with bounded async waits (1.5s deadline) consistent with production semantics, where fs.watch is best-effort and the preload poll loop is the source of truth.
+- **`operator-experience` ubuntu redaction flake** (commit `2da1a1b`): the redaction test seeded a secret literally named `abc` and asserted `/abc/` does not leak, but the runId hash (`randomBytes(8).toString("hex")`) occasionally spells `...abc...` (e.g. `team_..._9791deabc2f52485`) → false failure, even though redaction worked perfectly. Fixed by switching to a `ZZ_LEAK_CANARY` marker — uppercase letters never appear in a lowercase-hex hash, so the marker is collision-proof.
+
+### Community
+
+- Thanks to **@YrFnS** for the textbook-quality Issue #33 report and diagnosis (PATHEXT, spawn vs execSync matrix) that pinpointed the fix.
+- Thanks to **@gustavo-pelissaro** for PR #32 — change #1 (plan-approval preservation) landed here; changes #2/#3 (child exit-143 normalization, symlinked temp base) were closed for heavy conflicts but will be revisited.
+- PR #34 (closed) overlapped the existing `%APPDATA%\npm` resolution; superseded by the runtime `npm root -g` probe.
+
+## [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.7",
   "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`);