pi-crew 0.10.2 → 0.10.4

package/docs/architecture.md

@@ -2,7 +2,7 @@
 
 `pi-crew` is a Pi package for coordinated multi-agent work. It is intentionally durable-first: every run is represented on disk, every task has a state record, and child workers stream progress into JSONL/status files so foreground sessions, background jobs, dashboards, and later restarts all read the same source of truth.
 
-**Current version:** v0.9.0 — 100+ rounds of code review hardening (see [CHANGELOG.md](../CHANGELOG.md)).
+**Current version:** v0.10.3 — 100+ rounds of code review hardening (see [CHANGELOG.md](../CHANGELOG.md)).
 
 ## Layers
 
@@ -79,11 +79,11 @@ The extension layer should remain thin: user input is normalized into tool param
 
 ### Task runner
 
-`src/runtime/task-runner.ts` executes one task. It prepares workspace/worktree context, renders a task prompt, chooses model candidates from Pi configuration, launches a child Pi process by default, and writes result artifacts. Scaffold mode is explicit dry-run only.
+`src/runtime/task-runner.ts` (thin entry, ~230 lines) executes one task; branch bodies live in `src/runtime/task-runner/` modules (`pre-execution.ts`, `child-executor.ts`, `post-execution.ts`, `live-executor.ts`, `scaffold-executor.ts`, …). It prepares workspace/worktree context, renders a task prompt, chooses model candidates from Pi configuration, launches a child Pi process by default, and writes result artifacts. Scaffold mode is explicit dry-run only.
 
 ### Child Pi runtime
 
-`src/runtime/child-pi.ts` is the default worker runtime. It:
+`src/runtime/child-pi/child-pi.ts` is the default worker runtime (split into the `src/runtime/child-pi/` module — `child-pi-spawn.ts`, `child-pi-streams.ts`, `child-pi-kill.ts`, `child-pi-steering.ts`, `child-pi-timers.ts`, `child-pi-transcript.ts`, `child-pi-constants.ts`). It:
 
 - launches real `pi` child processes,
 - hides Windows console windows with `windowsHide: true`,
@@ -98,7 +98,7 @@ The extension layer should remain thin: user input is normalized into tool param
 
 ### Concurrency and policy
 
-`src/runtime/concurrency.ts` picks batch size from explicit limits, team settings, workflow settings, or built-in defaults. User-provided `limits.maxConcurrentWorkers` is hard-capped by default to prevent local DoS; `limits.allowUnboundedConcurrency=true` is an explicit opt-out and emits an observability event.
+`src/runtime/scheduling/concurrency.ts` picks batch size from explicit limits, team settings, workflow settings, or built-in defaults. User-provided `limits.maxConcurrentWorkers` is hard-capped by default to prevent local DoS; `limits.allowUnboundedConcurrency=true` is an explicit opt-out and emits an observability event.
 
 `src/runtime/policy-engine.ts` applies closeout and safety policy decisions such as limit exceeded, failed task blocking, stale workers, and green-contract failures.
 

package/docs/commands-reference.md

@@ -41,6 +41,9 @@ Slash commands are manual actions triggered from the Pi chat. Autonomous tool us
 | `/team-mascot` | Toggle the mascot overlay |
 | **`/team-goal`** | **v0.9.0** Start autonomous goal loop (sub-actions: `start/status/pause/resume/stop/step/clear`) |
 | **`/workflows`** | **v0.9.0** List static + dynamic workflows (`.dwf.ts`) |
+| `/crew-view <runId> <taskId>` | Open an agent's live full-screen transcript view (thin alias for the inline-panel pane wiring; never switches sessions) |
+| `/crew-back` | Close the agent transcript view and return to the main conversation |
+| `/team-vibes [on\|off\|speed on\|off\|capacity on\|off]` | Toggle crew-vibes speed + context meters (on/off, speed, capacity) |
 
 **Removed (v0.10.1 docs hygiene):** `/team-orchestrate`, `/team-schedule`,
 `/team-scheduled`, `/team-search`, `/team-graph` — phantom entries; none of

package/docs/publishing.md

@@ -31,7 +31,19 @@ of the full ~6,500-test `npm run check` which takes minutes):
 npm run test:critical && npm run typecheck && npm run build:bundle
 ```
 
-4. Verify package contents:
+4. Verify dist is clean and current ("dist clean check", WI-1.3):
+
+```bash
+git status --short dist/                          # must print NOTHING (clean)
+node scripts/check-bundle-staleness.mjs --committed-hash   # must exit 0
+```
+
+A dirty or stale committed dist silently ships old code (the v0.9.x
+stale-bundle incident class). If either check fails: `npm run build:bundle`,
+then commit the bundle — `git add -f dist/ && git commit -- dist`
+(dist/ is gitignored, so `-f` is required).
+
+5. Verify package contents:
 
 ```bash
 npm pack --dry-run
@@ -44,7 +56,7 @@ Confirm bundled skills ship (the `real-test-pi-crew` skill references
 npm pack --dry-run 2>&1 | grep -E 'skills/|pty_probe'
 ```
 
-5. Verify local install in Pi:
+6. Verify local install in Pi:
 
 ```bash
 pi install ./pi-crew
@@ -52,7 +64,7 @@ pi install ./pi-crew
 /team-validate
 ```
 
-6. Publish when ready:
+7. Publish when ready:
 
 ```bash
 npm publish --access public

package/install.mjs

@@ -2,13 +2,32 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { pathToFileURL } from "node:url";
 
 const home = process.env.PI_TEAMS_HOME?.trim() || os.homedir();
 const agentDir = path.join(home, ".pi", "agent");
 const configPath = path.join(agentDir, "pi-crew.json");
 const legacyConfigPath = path.join(agentDir, "extensions", "pi-crew", "config.json");
-const defaultConfig = {
-  // Keep generated config non-invasive: runtime/limits use pi-crew internal defaults.
+
+/**
+ * Default config written to `~/.pi/agent/pi-crew.json` on fresh installs.
+ *
+ * WI-1b.2 (G17): this object is intentionally an embedded literal — install.mjs
+ * runs under bare `node` as the `pi-crew` bin (engines floor is >=22.0.0; .ts
+ * imports would require >=22.18 or `--experimental-strip-types`, which the npm
+ * bin shim cannot pass). Runtime jiti/esbuild loading was rejected as a
+ * postinstall failure surface; build-time codegen would need package.json /
+ * prepack wiring. Instead, drift is enforced by
+ * `test/unit/install-defaults-sync.test.ts`, which derives the source of truth
+ * from `src/config/defaults.ts` (DEFAULT_UI) and
+ * `src/config/config-validation.ts` (effectiveAutonomousConfig) and goes red
+ * the moment this literal diverges (mutation-demo verified).
+ *
+ * Keys mirror the curated subset in `src/extension/project-init.ts`
+ * (DEFAULT_PI_CREW_CONFIG) — deliberately non-invasive: runtime/limits use
+ * pi-crew internal defaults and are not pinned here.
+ */
+export const defaultConfig = {
   autonomous: {
     enabled: true,
     injectPolicy: true,
@@ -30,7 +49,9 @@ const defaultConfig = {
     }
   },
   ui: {
-    widgetPlacement: "aboveEditor",
+    // G17 drift fix (2026-09): was "aboveEditor" while DEFAULT_UI.widgetPlacement
+    // is "bottom" — fresh installs were pinning a stale default into user config.
+    widgetPlacement: "bottom",
     widgetMaxLines: 8,
     powerbar: true,
     dashboardPlacement: "center",
@@ -44,44 +65,74 @@ const defaultConfig = {
   }
 };
 
-fs.mkdirSync(agentDir, { recursive: true });
-if (!fs.existsSync(configPath)) {
-  if (fs.existsSync(legacyConfigPath)) {
-    fs.copyFileSync(legacyConfigPath, configPath);
-    console.log(`Migrated pi-crew global config to: ${configPath}`);
+/**
+ * Postinstall / bin behavior: create the agent dir, migrate or write the
+ * default global config, and print install + uninstall guidance.
+ * Kept side-effect-for-side-effect identical to the pre-refactor top-level
+ * script (WI-1b.2 refactor only moved it behind a main-guard).
+ */
+export function main() {
+  fs.mkdirSync(agentDir, { recursive: true });
+  if (!fs.existsSync(configPath)) {
+    if (fs.existsSync(legacyConfigPath)) {
+      fs.copyFileSync(legacyConfigPath, configPath);
+      console.log(`Migrated pi-crew global config to: ${configPath}`);
+    } else {
+      fs.writeFileSync(configPath, `${JSON.stringify(defaultConfig, null, 2)}\n`, "utf-8");
+      console.log(`Created default pi-crew global config: ${configPath}`);
+    }
   } else {
-    fs.writeFileSync(configPath, `${JSON.stringify(defaultConfig, null, 2)}\n`, "utf-8");
-    console.log(`Created default pi-crew global config: ${configPath}`);
+    console.log(`pi-crew global config already exists: ${configPath}`);
   }
-} else {
-  console.log(`pi-crew global config already exists: ${configPath}`);
+
+  console.log("\nInstall the published package in Pi with:");
+  console.log("  pi install npm:pi-crew");
+  console.log("\nFor local development from a cloned repo:");
+  console.log("  pi install .");
+  console.log("\nChild workers are enabled by default. For dry runs, set runtime.mode=scaffold or executeWorkers=false.");
+  console.log("To force-disable or force-enable workers in a shell, use PI_TEAMS_EXECUTE_WORKERS=0/1.");
+
+  // Side-effects warning (Issue #35): be upfront about what pi-crew writes and
+  // how to fully uninstall it. Nothing runs on install/registration itself; the
+  // writes below only happen when you explicitly invoke `team action=init`.
+  console.log("\n--- What pi-crew writes (and how to undo it) ---");
+  console.log("pi-crew itself writes nothing on install. The following only happens when you");
+  console.log("explicitly run `team action=init` in a project:");
+  console.log("  - A `.crew/` runtime state dir is created in the project (run history + artifacts).");
+  console.log("  - With --copy-builtins: bundled agents/teams/workflows are copied into the project.");
+  console.log("This install also created the global config above (`~/.pi/agent/pi-crew.json`).");
+  console.log("Note: pi-crew v0.8.14+ no longer injects a guidance block into AGENTS.md on init");
+  console.log("      (it was redundant — the `team` tool self-describes via tool registration).");
+  console.log("      Versions <0.8.14 did inject one; `team action=cleanup` removes it.");
+  console.log("\nFull uninstall (in order):");
+  console.log("  team action=cleanup dryRun=true       # preview what would be removed (project)");
+  console.log("  team action=cleanup                    # remove the AGENTS.md guidance block");
+  console.log("  team action=cleanup force=true         # also remove the .crew/ project state dir");
+  console.log("  team action=cleanup scope=user         # remove pi-crew user-scope junk");
+  console.log("                                          #   (~/.pi/agent/extensions/pi-crew/ + test .bak files)");
+  console.log("  team action=cleanup scope=user force=true  # also remove ~/.pi/agent/pi-crew.json");
+  console.log("  pi uninstall npm:pi-crew               # remove the package itself");
+  console.log("See the README 'Uninstall' section for details.");
 }
 
-console.log("\nInstall the published package in Pi with:");
-console.log("  pi install npm:pi-crew");
-console.log("\nFor local development from a cloned repo:");
-console.log("  pi install .");
-console.log("\nChild workers are enabled by default. For dry runs, set runtime.mode=scaffold or executeWorkers=false.");
-console.log("To force-disable or force-enable workers in a shell, use PI_TEAMS_EXECUTE_WORKERS=0/1.");
+/**
+ * Main-guard: run main() only when this file is executed directly
+ * (`node install.mjs` or via the npm `pi-crew` bin shim), never when imported
+ * as a module (e.g. by test/unit/install-defaults-sync.test.ts).
+ * realpathSync both sides: import.meta.url is the realpath (Node resolves
+ * symlinks by default), while argv[1] may be a symlinked bin path — e.g. the
+ * dev-install layout where node_modules/pi-crew symlinks into a source clone.
+ */
+function invokedDirectly() {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return import.meta.url === pathToFileURL(fs.realpathSync(invoked)).href;
+  } catch {
+    return false;
+  }
+}
 
-// Side-effects warning (Issue #35): be upfront about what pi-crew writes and
-// how to fully uninstall it. Nothing runs on install/registration itself; the
-// writes below only happen when you explicitly invoke `team action=init`.
-console.log("\n--- What pi-crew writes (and how to undo it) ---");
-console.log("pi-crew itself writes nothing on install. The following only happens when you");
-console.log("explicitly run `team action=init` in a project:");
-console.log("  - A `.crew/` runtime state dir is created in the project (run history + artifacts).");
-console.log("  - With --copy-builtins: bundled agents/teams/workflows are copied into the project.");
-console.log("This install also created the global config above (`~/.pi/agent/pi-crew.json`).");
-console.log("Note: pi-crew v0.8.14+ no longer injects a guidance block into AGENTS.md on init");
-console.log("      (it was redundant — the `team` tool self-describes via tool registration).");
-console.log("      Versions <0.8.14 did inject one; `team action=cleanup` removes it.");
-console.log("\nFull uninstall (in order):");
-console.log("  team action=cleanup dryRun=true       # preview what would be removed (project)");
-console.log("  team action=cleanup                    # remove the AGENTS.md guidance block");
-console.log("  team action=cleanup force=true         # also remove the .crew/ project state dir");
-console.log("  team action=cleanup scope=user         # remove pi-crew user-scope junk");
-console.log("                                          #   (~/.pi/agent/extensions/pi-crew/ + test .bak files)");
-console.log("  team action=cleanup scope=user force=true  # also remove ~/.pi/agent/pi-crew.json");
-console.log("  pi uninstall npm:pi-crew               # remove the package itself");
-console.log("See the README 'Uninstall' section for details.");
+if (invokedDirectly()) {
+  main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -68,7 +68,8 @@
   ],
   "scripts": {
     "check": "npm run ci",
-    "ci": "npm run check:lockfile-sync && npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:env-vars && npm run check:event-types && npm run check:lazy-imports && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm test && npm pack --dry-run",
+    "ci": "npm run check:lockfile-sync && npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:env-vars && npm run check:event-types && npm run check:lazy-imports && npm run check:wc-gate && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm test && npm pack --dry-run",
+    "ci:fast": "npm run check:lockfile-sync && npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:env-vars && npm run check:event-types && npm run check:lazy-imports && npm run check:wc-gate && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm run test:critical && npm pack --dry-run",
     "check:lockfile-sync": "node scripts/check-lockfile-sync.mjs",
     "check:lazy-imports": "node scripts/check-lazy-imports.mjs",
     "check:bundle-staleness": "node scripts/check-bundle-staleness.mjs",
@@ -81,10 +82,13 @@
     "lint": "biome check --linter-enabled=true --formatter-enabled=false --max-diagnostics=50 .",
     "format:check": "biome format .",
     "test": "npm run test:unit && npm run test:integration",
+    "test:full": "npm run test:unit && npm run test:integration && npm run test:integration:slow",
     "test:unit": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=180000 --test-force-exit 'test/unit/**/*.test.ts'",
     "test:critical": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/runtime/broker/crew-broker-handshake.test.ts test/unit/runtime/broker/crew-broker-stale-socket.test.ts test/unit/runtime/broker/crew-broker-feature-flag.test.ts test/unit/runtime/broker/crew-broker-server-gate.test.ts test/unit/runtime/broker/crew-broker-client-fallback.test.ts test/unit/runtime/broker/crew-broker-mailbox-observer.test.ts test/unit/runtime/broker/crew-broker-close-during-reconnect.test.ts test/unit/runtime/broker/crew-broker-steer-dedup.test.ts test/unit/runtime/broker/crew-broker-symlink-steering.test.ts test/unit/ui/keybinding-map.parity.test.ts test/unit/ui/pi-tui-dispatch-probe.test.ts test/unit/utils/session-utils-extract.test.ts test/unit/config/config-schema-sync.test.ts test/unit/runtime/child-pi/child-pi-env-spread.test.ts",
     "test:watch": "node scripts/test-runner.mjs --watch --test-concurrency=4 --test-timeout=30000 'test/unit/**/*.test.ts'",
     "test:integration": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=300000 test/integration/*.test.ts",
+    "test:integration:slow": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=600000 test/integration/slow/*.test.ts",
+    "test:system": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 --test-force-exit test/system/*.e2e.test.ts",
     "test:smoke": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 test/smoke/*.smoke.ts",
     "test:spike": "node scripts/test-runner.mjs --test-concurrency=2 --test-timeout=120000 --test-force-exit test/runtime/scratchpad/*.test.ts",
     "test:functional": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=120000 test/functional/pi-crew-functional.test.ts",
@@ -105,7 +109,9 @@
     "profile:startup": "node scripts/profile-startup.mjs",
     "smoke:pi": "pi install .",
     "smoke:release": "node scripts/release-smoke.mjs",
-    "prepack": "node scripts/clean-strip-types.mjs"
+    "prepack": "node scripts/clean-strip-types.mjs",
+    "test:fast": "npm run test:critical && npm run test:bundle",
+    "check:wc-gate": "node scripts/wc-gate.mjs"
   },
   "exports": {
     "./schema.json": "./schema.json",

package/schema.json

@@ -670,6 +670,17 @@
           "description": "Max crew depth for delegate-driven nesting. Default 2 (mirrors PI_CREW_MAX_DEPTH clamp)."
         }
       }
+    },
+    "persistence": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "State-layer persistence knobs (perf round 2, Task 3). Opt-in only.",
+      "properties": {
+        "skipTasksFsync": {
+          "type": "boolean",
+          "description": "Opt-in (default false): write non-terminal tasks checkpoints best-effort (no fsync; the 50ms coalesced write grouping is kept — only durability is skipped, tasks.json stays reconstructible from the fsync'd event log). Terminal transitions stay full-durability. Env PI_CREW_PERSISTENCE_SKIP_TASKS_FSYNC beats this."
+        }
+      }
     }
   }
 }

package/scripts/README.md

@@ -1,6 +1,7 @@
 # Scripts
 
-> **Note:** Many scripts in this directory are one-off fix scripts (e.g.,
-> `fix-*.cjs`, `patch-*.cjs`) that were used for specific migrations or
-> bugfixes and could be archived. Only `postinstall.mjs`, `build-bundle.mjs`,
+> **Note:** Some scripts in this directory are one-off fix/patch scripts
+> (e.g., `patch-*.cjs`) that were used for specific migrations or bugfixes
+> and could be archived. The 14 `fix-*.cjs` one-offs were removed in the
+> 2026-09 M1 hygiene sweep. Only `postinstall.mjs`, `build-bundle.mjs`,
 > and `watch-bundle.mjs` are actively used by the project.

package/skills/real-test-pi-crew/REPORT-TEMPLATE.md

@@ -27,12 +27,17 @@ This artifact exists so past runs are verifiable (see SKILL.md "Output report").
 | 6 pty probe | ✅/❌/⏭️ | `<keys reached handleInput / diag lines>` |
 | 7 smoke team run | ✅/❌/⏭️ | runId `<id>`, `<n>/<n>` tasks, verifier `<dur>` (<300s) |
 | 8 final md5 sync | ✅/❌/⏭️ | disk = session = `<md5>` |
-| 9a read-only battery | ✅/❌/⏭️ | list/recommend/health/doctor/status/events/summary/get/explain/worktrees — `<n>/10` |
-| 9b spawn paths | ✅/❌/⏭️ | sync / async / chain / Agent / crew_agent — `<n>/5` |
+| 9a read-only battery | ✅/❌/⏭️ | list/recommend/health/doctor/status/events/summary/get/explain/worktrees/graph/search/settings — `<n>/13` |
+| 9b spawn paths | ✅/❌/⏭️ | sync / async / chain / orchestrate-plan / Agent / crew_agent / steer_subagent — `<n>/7` |
+| 9b-W worker tools | ✅/❌/⏭️ | ask round-trip / message notify / message DM-group / delegate nesting — which ran + evidence (reply in transcript, wake event, depth-cap reject) |
 | 9c lifecycle | ✅/❌/⏭️ | status-details/cache/checkpoint/steer/retry/resume + live cancel — which ran |
 | 9d destructive | ✅/❌/⏭️ | forget/cleanup/prune — which ran (note data-protection skips) |
 | 9e admin | ✅/❌/⏭️ | team/workflow CRUD round-trip |
 | 9f background | ✅/❌/⏭️ | auto-summarize/anchor/schedule register+remove |
+| 10a surface E2E | ✅/❌/⏭️ | tmux 3/3 (spawn+self-close / kill-pane→degrade / doctor orphan) + herdr 3/3 — or skip reason per backend (no `$TMUX`/CI/no socket/in tmux for herdr) |
+| 10b live surface run | ✅/❌/⏭️ | `visibleAgents='<set>'`, pane ids+titles during run, `worker.surface_spawned`/`worker.surface_closed` events (+ no `surface.degraded`), panes auto-closed. NOTE: `manifest.surface.panes` is `{}` at run END even on success (released on pane close) — engage-evidence is the EVENTS + `manifest.surface.provider`/`workerPids` |
+| 10c herdr path | ✅/❌/⏭️ | ran in herdr pane / skipped (not in herdr pane) |
+| 11 remediation regression | ✅/❌/⏭️ | sub-checks run + evidence: 11a buffered-site census `<n>` files (full test:unit `<pass>/<tests>` if run) · 11b wc-gate max `<n>`/2000 + in `ci` · 11c validator warn `<key>` → severity · 11d slow tier 3 files disjoint · 11e nightly SMOKE not-set · 11f reject format sites · 11g widgetPlacement bottom · 11h twins 3× green · 11i dead-export 0 + MUST_INCLUDE 5 · 11j committed-hash OK |
 
 Legend: ✅ pass with evidence · ❌ fail (root cause below) · ⏭️ skipped (justify why)