pi-crew 0.9.68 → 0.10.1

package/docs/README.md

@@ -30,6 +30,8 @@ stay at the root of this directory; historical/retired docs live in
 | [`COVERAGE-ASSESSMENT-2026-08-01.md`](./COVERAGE-ASSESSMENT-2026-08-01.md) | v0.9.56 coverage assessment + source-reorg history |
 | [`AUDIT-2026-07-30.md`](./AUDIT-2026-07-30.md) | v0.9.56 comprehensive audit (6 parallel streams) |
 | [`REMEDIATION-PLAN-2026-07-30.md`](./REMEDIATION-PLAN-2026-07-30.md) | v0.9.56 remediation plan |
+| [`refactor-plan.md`](./refactor-plan.md) | Maintainability refactor plan (phased, v0.9.68) |
+| [`refactor-plan.review.md`](./refactor-plan.review.md) | Verification sweep 3 (vòng 4) audit trail — 3 large-file baselines CONFIRMED, 6 corrections, Phase 4 reframe |
 
 ## Subdirectories
 

package/docs/actions-reference.md

@@ -2,6 +2,23 @@
 
 The `team` tool is the primary tool that pi-crew registers with Pi. All operations go through `action`.
 
+### `plans` — Inspect and decide a run's plan record (T2/R4)
+
+Reads the versioned `PlanRecord` list at `<stateRoot>/plans/plans.json` (ADR-4). Pre-v2 runs without a record degrade gracefully with the manifest-gate info.
+
+```json
+{ "action": "plans", "runId": "team_..." }
+{ "action": "plans", "runId": "team_...", "config": { "subAction": "get", "rev": 2 } }
+{ "action": "plans", "runId": "team_...", "config": { "subAction": "list" } }
+{ "action": "plans", "runId": "team_...", "config": { "subAction": "diff", "a": 1, "b": 2 } }
+{ "action": "plans", "runId": "team_...", "config": { "subAction": "approve" } }
+```
+
+- `get` (default) renders the current (or pinned `rev`) revision with derived per-item progress (done/failed/running from linked `taskIds`).
+- `list` renders the revision history.
+- `diff` reports item-level changes between two revisions (added / removed / dropped / status changes / retitles).
+- `approve` / `reject` delegate to the api `approve-plan` / `cancel-plan` ops (dual-write: manifest keeps its vocabulary — `cancelled` on deny — the record side uses `rejected`).
+
 ## Quick Reference
 
 | Action | Purpose | When to use |
@@ -10,6 +27,7 @@ The `team` tool is the primary tool that pi-crew registers with Pi. All operatio
 | `run` | Create a run and execute a workflow | Main operation |
 | `parallel` | Fan out independent tasks as concurrent runs | When you need N truly concurrent agents |
 | `plan` | Preview a workflow without running tasks | Dry-run planning |
+| `plans` | Inspect/decide the versioned plan record of a run | Plan revisions, diff, approve/reject |
 | `orchestrate` | Execute from a plan document | Automate a plan |
 | `schedule` | Schedule recurring runs | Periodic automation |
 | `scheduled` | List scheduled jobs | View schedules |
@@ -800,6 +818,19 @@ Returns `status: "error"` when the run finished as `failed`.
 > ⚠️ **Internal / experimental.** Queues a steering message that is delivered to
 > a task's worker session on its next turn. The message is appended to
 > `pendingSteers` and also written to a live steering file for immediate delivery.
+>
+> **Updated (T1/WP-1, 2026-08-17, v0.10.1):** the agent-level tools
+> `steer_subagent` / `crew_agent_steer` are now **implemented** — they resolve the
+> subagent record via the unified ownership map (`src/state/stores/ownership-map.ts`,
+> task ⇄ subagent ⇄ pid ⇄ artifacts) to the run's steering file and append a
+> `{type:"steer", message, ts}` line that the worker polls every 500ms and picks
+> up at its next turn boundary. Terminal-task refusal + size-cap parity with
+> `team action=steer`; the steering file is truncated at each worker spawn so
+> lines are scoped to one worker incarnation. The record's `taskId` is linked at
+> dispatch time (onRunStarted), so mid-run steering of a live one-shot agent
+> works. See ADR `docs/decisions/2026-08-14-agent-steer-tools-planned-not-implemented.md`
+> (status: CLOSED). `team action=steer` (runId + taskId + message) remains the
+> run-level path.
 
 ```json
 {

package/docs/commands-reference.md

@@ -8,21 +8,22 @@ Slash commands are manual actions triggered from the Pi chat. Autonomous tool us
 |---------|-------|
 | `/teams` | List teams, agents, workflows, and recent runs |
 | `/team-run [options] <goal>` | Run a team workflow |
-| `/team-orchestrate <planPath>` | Execute from a plan document |
-| `/team-schedule [options]` | Schedule a recurring run |
-| `/team-scheduled` | List scheduled jobs |
 | `/team-cancel <runId>` | Cancel a run |
 | `/team-status <runId>` | View status |
 | `/team-summary <runId>` | View or write a summary |
 | `/team-resume <runId>` | Resume a stopped run |
-| `/team-search <query>` | BM25-ranked discovery |
-| `/team-graph <runId>` | Load, save, or list run graphs |
+| `/team-retry <runId>` | Retry a failed run |
+| `/team-result <runId>` | Show a task result artifact |
+| `/team-respond <taskId> <message>` | Respond to a waiting worker task |
+| `/team-follow-up [options]` | Manage follow-up notifications |
 | `/team-events <runId>` | View the event log |
 | `/team-artifacts <runId>` | View artifacts |
+| `/team-transcript <runId>` | Open the transcript viewer |
 | `/team-worktrees <runId>` | View worktree metadata |
-| `/team-cleanup <runId>` | Remove worktrees |
+| `/team-cleanup <runId>` | Remove worktrees (interactive menu: `/team-cleanup-menu`) |
 | `/team-forget <runId>` | Fully delete a run |
 | `/team-prune` | Delete multiple old runs |
+| `/team-invalidate [scope]` | Invalidate caches |
 | `/team-export <runId>` | Export a run bundle |
 | `/team-import <path>` | Import a run bundle |
 | `/team-imports` | List imported bundles |
@@ -37,9 +38,16 @@ Slash commands are manual actions triggered from the Pi chat. Autonomous tool us
 | `/team-validate` | Validate resources |
 | `/team-help` | Help text |
 | `/team-doctor` | Diagnose the environment |
+| `/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`) |
 
+**Removed (v0.10.1 docs hygiene):** `/team-orchestrate`, `/team-schedule`,
+`/team-scheduled`, `/team-search`, `/team-graph` — phantom entries; none of
+these slash commands is registered. Their functionality is reachable via the
+`team` tool actions (`action: "orchestrate" | "schedule" | "scheduled" |
+"search" | "graph"`) instead.
+
 ---
 
 ## `/team-run` — Details
@@ -296,6 +304,9 @@ Creates directories:
 | `u` | View summary |
 | `i` | API read-manifest |
 | `q` or `Esc` | Close |
+| `1`–`7` | Pane: agents / progress / mailbox / output / health / metrics / **plan** (v0.10.1, `PI_CREW_PLAN_UI=1`) |
+| `A` / `n` | Plan approval approve/deny (progress + plan panes, while pending) |
+| `X` | Plan revision diff (plan pane) |
 
 ---
 

package/docs/resource-formats.md

@@ -107,6 +107,8 @@ Format:
 ---
 name: default
 description: Explore, plan, execute, verify
+maxConcurrency: 3
+specStrict: false
 ---
 
 ## explore
@@ -122,6 +124,15 @@ output: plan.md
 Create a plan for: {goal}
 ```
 
+Frontmatter fields:
+
+| Field | Meaning |
+| --- | --- |
+| `maxConcurrency` | Max parallel tasks for the run |
+| `topology` | Explicit topology classification |
+| `coalesceMicroTasks` | Coalesce micro-tasks sharing role+cwd into one worker prompt |
+| `specStrict` | T4/R6 (ADR-6): strict spec mode — coverage AND machine-check; requires a `verifier` role step (reject-start) |
+
 Step fields:
 
 | Field | Meaning |
@@ -136,5 +147,7 @@ Step fields:
 | `progress` | `true`/`false` |
 | `worktree` | `true`/`false` metadata |
 | `verify` | `true`/`false` verification marker |
+| `specRefs` | T4/R6 (ADR-6): workspace SpecRecord ids this step is held to (frozen into the packet at dispatch) |
+| `specStrict` | Per-step strict override (`true`/`1`) |
 
 Each step starts with `## step-id` followed by recognized step metadata such as `role:` before the blank line. Level-2 headings inside task bodies are preserved unless they look like a step section with recognized metadata; use `###` or lower for maximum compatibility.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.68",
+  "version": "0.10.1",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -30,6 +30,7 @@
   ],
   "files": [
     "src/",
+    "!src/benchmark",
     "dist/index.mjs",
     "index.ts",
     "install.mjs",
@@ -67,13 +68,14 @@
   ],
   "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: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:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm test && 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",
     "check:bundle-size": "node scripts/check-bundle-size.mjs",
     "check:conflict-markers": "node scripts/check-conflict-markers.mjs",
     "check:decision-drift": "node scripts/check-decision-drift.mjs",
+    "check:env-vars": "node scripts/check-env-vars.mjs",
     "check:event-types": "node scripts/check-event-types-registry.mjs",
     "typecheck": "tsc --noEmit && node --experimental-strip-types -e \"await import('./index.ts'); console.log('strip-types import ok')\"",
     "lint": "biome check --linter-enabled=true --formatter-enabled=false --max-diagnostics=50 .",

package/schema.json

@@ -256,7 +256,21 @@
         "enabled": { "type": "boolean" },
         "pathHashLen": { "type": "integer", "minimum": 4, "maximum": 32 },
         "maxFrameBytes": { "type": "integer", "minimum": 1024, "maximum": 1048576 },
-        "outboundQueueCap": { "type": "integer", "minimum": 32, "maximum": 4096 }
+        "outboundQueueCap": { "type": "integer", "minimum": 32, "maximum": 4096 },
+        "waitMethodsEnabled": {
+          "type": "boolean",
+          "description": "WP-2/R2 (ADR-0 2026-08-17-waiting-producer-ask item 7): gate for the broker wait.* methods. Default false - fail-closed."
+        }
+      }
+    },
+    "nesting": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Governed nesting (ADR-5 docs/decisions/2026-08-17-governed-nesting.md). Worker-to-grandchild delegation via the delegate tool. Default false - fail-closed until WP-5 completes.",
+      "properties": {
+        "enabled": { "type": "boolean", "sensitive": true, "description": "Master switch. Privilege-raising: user config only; project-level nesting.enabled is ignored." },
+        "maxSlots": { "type": "integer", "minimum": 1, "maximum": 64, "description": "Nested-slot budget override. Default max(1, floor(globalSem/2))." },
+        "maxDepth": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Max crew depth for delegate-driven nesting. Default 2 (mirrors PI_CREW_MAX_DEPTH clamp)." }
       }
     }
   }

package/scripts/resource-sampler.mjs

@@ -147,9 +147,16 @@ function readProcStatus(pid) {
 
 // ---------- fallback via ps (non-Linux) ----------
 function readPs(pid) {
-	const res = spawnSync("ps", ["-o", "rss=,pcpu=", "-p", String(pid)], { encoding: "utf8" });
+	// state= makes zombie detection possible on BSD ps (macOS): a dead child
+	// stays listed by ps until reaped — without the state check, watch-parent
+	// (R4) never sees the watched PID die and live-warn (proc_died) never fires
+	// (CI incident: resource-sampler-audit.test.ts on macos-latest). Linux ps
+	// also supports state=. Z/X (and empty) = dead.
+	const res = spawnSync("ps", ["-o", "rss=,pcpu=,state=", "-p", String(pid)], { encoding: "utf8" });
 	if (res.status !== 0 || !res.stdout.trim()) return null;
 	const parts = res.stdout.trim().split(/\s+/);
+	const state = parts.length >= 3 ? parts[2] : "";
+	if (state.startsWith("Z") || state.startsWith("X")) return null;
 	return {
 		pid,
 		ppid: 0,
@@ -163,7 +170,34 @@ function readPs(pid) {
 // ---------- child discovery ----------
 function findDescendants(rootPid) {
 	// BFS over /proc to find all PIDs whose ppid chain leads to rootPid.
-	if (!existsSync("/proc")) return [rootPid];
+	// Non-Linux (macOS/BSD): no /proc — build the ppid map from `ps -eo pid=,ppid=`
+	// instead (R3 on macos-latest CI: /proc-less platforms previously returned
+	// [rootPid] only, so descendants were never sampled).
+	if (!existsSync("/proc")) {
+		try {
+			const res = spawnSync("ps", ["-eo", "pid=,ppid="], { encoding: "utf8" });
+			if (res.status !== 0 || !res.stdout.trim()) return [rootPid];
+			const ppidOf = new Map();
+			for (const line of res.stdout.trim().split("\n")) {
+				const parts = line.trim().split(/\s+/);
+				if (parts.length >= 2) ppidOf.set(Number.parseInt(parts[0], 10), Number.parseInt(parts[1], 10));
+			}
+			const result = new Set([rootPid]);
+			let grew = true;
+			while (grew) {
+				grew = false;
+				for (const [pid, ppid] of ppidOf) {
+					if (result.has(ppid) && !result.has(pid)) {
+						result.add(pid);
+						grew = true;
+					}
+				}
+			}
+			return [...result];
+		} catch {
+				return [rootPid];
+			}
+	}
 	const all = [];
 	try {
 		for (const name of readdirSync("/proc")) {

package/skills/requirements-to-task-packet/SKILL.md

@@ -62,6 +62,32 @@ Use observable checks:
 - compatibility requirements such as Windows paths or Pi CLI flags;
 - rollback notes.
 
+## Spec Pairs (pi-crew v0.10.1+, ADR-6)
+
+When the target runs pi-crew, author the **SpecRecord + TaskPacket pair** instead of prose-only acceptance:
+
+1. **SpecRecord** (workspace `state/specs/<id>.json`): `requirements[]` with
+   `must|should|could` priority + stable ids; `acceptance[]` entries each tied to
+   a `requirementId`. Machine-checkable acceptances carry `command`,
+   `expectedDigest` (sha-256 hex of stdout) or `expectedExitCode`, and
+   `idempotent: true` — only idempotent commands are ever re-run.
+2. **PROVENANCE — critical**: specs you (an agent/skill path) write are persisted
+   `generated` and NEVER re-executed by the orchestrator. `manual`+`trusted`
+   (the only specs strict mode re-runs) are minted exclusively by USER-facing
+   import actions — a worker cannot author a command the root re-executes.
+3. **Wire the workflow**: add `specRefs: [<spec ids>]` to steps held to the spec;
+   `specStrict: true` in frontmatter opts the whole workflow into strict mode
+   (requires a `verifier` role step — the run rejects at start otherwise).
+4. **Executor footer contract**: workers must END results with
+
+   ```text
+   SPEC-EVIDENCE:
+   <acceptanceId>: <one-line evidence>
+   ```
+
+   Non-strict = mechanical coverage only (`unverified` badge on gaps, never
+   blocks). Strict = coverage AND machine-check; failures fail the run.
+
 ## Enforcement — Requirements to Task Packet Gate
 
 **Before dispatching workers, verify task packet has:**

package/skills/widget-rendering/SKILL.md

@@ -32,16 +32,16 @@ In-memory map from `live-agent-manager.ts`. Provides:
 
 **When NOT used:** After `evictStaleLiveAgentHandles()` removes a handle, widget falls back to agent records on disk.
 
-### 2. Snapshot cache (500ms TTL)
+### 2. Snapshot cache (1500ms TTL)
 
-`RunSnapshotCache` from `run-snapshot-cache.ts` caches parsed manifests and agents for 500ms. Reduces disk reads during rapid refresh.
+`RunSnapshotCache` from `run-snapshot-cache.ts` caches parsed manifests and agents for 1500ms. Reduces disk reads during rapid refresh.
 
 **When used:** As the fallback when no live handle exists. Prevents excessive disk reads on every render tick.
 
 **Invalidation:** Cache is invalidated when:
 - `invalidate()` is called on a specific run
 - An empty result is returned (forces refresh on next tick)
-- TTL expires (500ms)
+- TTL expires (1500ms)
 
 ### 3. `agents.json` on disk (durables, lowest priority)
 
@@ -156,7 +156,7 @@ Every render cycle (`renderTick` / `requestAnimationFrame`) must complete in <16
 
 ### TTL interactions
 
-- Snapshot cache TTL = 500ms
+- Snapshot cache TTL = 1500ms
 - Preload interval must be < TTL to avoid render-time gaps
 - If preload interval ≥ TTL, the cache always has fresh data for render
 
@@ -248,7 +248,7 @@ If ANY answer is NO → Stop. Fix widget rendering issues before proceeding.
 ## Anti-patterns
 
 - **Blocking render with fs calls**: Every `readFileSync`, `readdirSync`, `fs.statSync` in the render path causes frame drops. Preload everything async.
-- **Stale cache in hot path**: If snapshot cache TTL is too long, widget shows outdated state. Keep TTL at 500ms or less.
+- **Stale cache in hot path**: If snapshot cache TTL is too long, widget shows outdated state. Keep TTL at 1500ms or less (the code default; lower only with cause).
 - **No invalidation on empty**: When `readCrewAgents` returns `[]` (no agents yet), the cache must be invalidated on next tick to prevent showing empty for too long.
 - **Expired handles accumulating**: Without `evictStaleLiveAgentHandles`, the Map grows indefinitely. Call it on every refresh.
 - **Widget showing stale health warnings**: Completed/cancelled/failed runs should not show health warnings. Filter by status.
@@ -258,7 +258,7 @@ If ANY answer is NO → Stop. Fix widget rendering issues before proceeding.
 ## Source patterns
 
 - `src/ui/crew-widget.ts` — render, refresh, activeWidgetRuns, evictStaleLiveAgentHandles, agentActivity, describeLiveActivity
-- `src/ui/run-snapshot-cache.ts` — SnapshotCache, get, refreshIfStale, TTL=500ms
+- `src/ui/run-snapshot-cache.ts` — SnapshotCache, get, refreshIfStale, TTL=1500ms
 - `src/runtime/crew-agent-records.ts` — readCrewAgents, agents.json
 - `src/runtime/process-status.ts` — hasStaleAsyncProcess, isDisplayActiveRun
 - `src/runtime/background-runner.ts` — active run filtering with async PID check
@@ -275,7 +275,7 @@ Render-path performance for the widget is non-negotiable. Treat every `render(wi
 - **Prefer `snapshotCache.get(runId)`** on render paths. If a synchronous fallback is genuinely unavoidable, classify it as first-load/rare and document why it can't be preloaded.
 - **Keep panes pure.** Dashboard panes must accept a snapshot/model and format strings only. Never call `fs.readFileSync`, `fs.readdirSync`, `fs.statSync`, network APIs, or large JSON parsing from pane render methods.
 - **Stay non-blocking at 60fps.** Each render cycle must complete in under ~16ms. Anything that can't finish synchronously (reads, fetches, directory scans) belongs in the async preload path, not `renderTick()`.
-- **Respect the snapshot-cache TTL of ≤500ms.** Keep the `RunSnapshotCache` TTL at 500ms or less so the widget never shows stale state. Watch TTL interactions: the preload interval must be shorter than the cache TTL, otherwise render-time refresh gaps appear.
+- **Respect the snapshot-cache TTL of ≤1500ms.** Keep the `RunSnapshotCache` TTL at 1500ms or less (the code default; lower only with cause) so the widget never shows stale state. Watch TTL interactions: the preload interval must be shorter than the cache TTL, otherwise render-time refresh gaps appear.
 - **Guard session switches.** On a session switch, cancel timers and ensure in-flight async preloads cannot update a now-stale session's UI.
 - **Filter stale warnings by terminal status.** Do not surface health warnings for completed/failed/cancelled runs.
 

package/src/agents/agent-config.ts

@@ -1,3 +1,4 @@
+import { getCrewEnv } from "../config/env-vars.ts";
 import type { RoleToolConfig } from "../config/role-tools.ts";
 import { getToolConfig, isScratchpadEnabledForRole } from "../config/role-tools.ts";
 
@@ -196,7 +197,7 @@ export function resolveToolPolicy(agent: AgentConfig, role?: string): ResolvedTo
  * live-session filterActiveTools) via the unified policy.
  */
 function shouldDemoteBashForScratchpad(role: string | undefined, agent: AgentConfig): boolean {
-	if (process.env.PI_CREW_SCRATCHPAD_DEMOTE_BASH !== "1") return false;
+	if (getCrewEnv("PI_CREW_SCRATCHPAD_DEMOTE_BASH") !== "1") return false;
 	if (!role) return false;
 	return isScratchpadEnabledForRole(role, { scratchpad: agent.scratchpad });
 }

package/src/agents/discover-agents.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { type LoadedPiTeamsConfig, loadConfig } from "../config/config.ts";
+import { getCrewEnv } from "../config/env-vars.ts";
 import { discoverProviderExtensionPaths } from "../runtime/model/provider-extensions.ts";
 import { parseCsv, parseFrontmatter } from "../utils/frontmatter.ts";
 import { logInternalError } from "../utils/internal-error.ts";
@@ -136,19 +137,13 @@ function logSecurityEvent(event: SecurityEvent): void {
 }
 
 /**
- * Get recent security events (for debugging/testing).
+ * Get recent security events. Production reader: the team doctor report
+ * surfaces a compact summary (R7-13); tests assert on the full list.
  */
 export function getSecurityEventLog(): readonly SecurityEvent[] {
 	return securityEventLog;
 }
 
-/**
- * Clear security event log (for testing).
- */
-export function clearSecurityEventLog(): void {
-	securityEventLog.length = 0;
-}
-
 /**
  * Security check: throws if the agent name is protected.
  *
@@ -373,7 +368,11 @@ export function sanitizeAgentSystemPrompt(content: string, source: ResourceSourc
  * emitted the `contextMode: fork` warn-only notice. Avoids spam when
  * the discovery cache reloads or the same agent is parsed multiple
  * times in a session. Exported for test reset.
+ * R5-L5: FIFO cap so the set stays bounded in long-lived sessions
+ * (Set preserves insertion order; bounded naturally <50, cap is a
+ * safety net).
  */
+const MAX_WARNED_FORK_AGENTS = 128;
 const warnedForkAgents = new Set<string>();
 export function __test_resetForkWarnings(): void {
 	warnedForkAgents.clear();
@@ -406,14 +405,19 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 		// so the agent will behave as `fresh` regardless of the setting.
 		// We warn (not throw) so existing configs that predate live-session
 		// keep working. Deduped per-filePath so we don't spam on cache
-		// reload. Use console.warn (no logger hook here yet; a future
-		// refactor could pipe through the same log channel as
-		// logInternalError below).
+		// reload. User-facing config notice (kept on console.warn deliberately
+		// so the user sees it in the interactive session; internal failures
+		// below use logInternalError).
 		if (contextMode === "fork" && !warnedForkAgents.has(filePath)) {
 			console.warn(
 				"contextMode: 'fork' is only effective in live-session runtime; current default child-process will behave as 'fresh'. See docs/runtime-flow.md.",
 			);
 			warnedForkAgents.add(filePath);
+			// R5-L5: FIFO eviction — drop the oldest entry past the cap.
+			if (warnedForkAgents.size > MAX_WARNED_FORK_AGENTS) {
+				const oldest = warnedForkAgents.values().next().value;
+				if (oldest !== undefined) warnedForkAgents.delete(oldest);
+			}
 		}
 
 		return {
@@ -442,7 +446,7 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 			// code. Bypass only when PI_CREW_TRUST_PROJECT_AGENT_EXTENSIONS=1 is
 			// explicitly set. buildPiWorkerArgs also enforces this as
 			// defense-in-depth.
-			...((source === "project" || source === "project-pi") && process.env.PI_CREW_TRUST_PROJECT_AGENT_EXTENSIONS !== "1"
+			...((source === "project" || source === "project-pi") && getCrewEnv("PI_CREW_TRUST_PROJECT_AGENT_EXTENSIONS") !== "1"
 				? { extensions: [], excludeExtensions: [] }
 				: {
 						extensions: frontmatter.extensions === "" ? [] : parseCsv(frontmatter.extensions),
@@ -494,7 +498,12 @@ function readAgentDir(dir: string, source: ResourceSource): AgentConfig[] {
 			try {
 				const stat = fs.statSync(fullPath);
 				if (stat.size > MAX_AGENT_FILE_BYTES) {
-					console.warn(`[pi-crew] Skipping oversized agent file (${stat.size} > ${MAX_AGENT_FILE_BYTES} bytes): ${fullPath}`);
+					logInternalError(
+						"discover-agents",
+						new Error(`Skipping oversized agent file (${stat.size} > ${MAX_AGENT_FILE_BYTES} bytes): ${fullPath}`),
+						undefined,
+						"warn",
+					);
 					return undefined;
 				}
 			} catch {
@@ -536,7 +545,7 @@ function applyAgentOverrides(agents: AgentConfig[], cwd: string, loadedConfig?:
 	// user-trusted config knob (provider extensions like pi-commandcode-provider)
 	// and applies to builtin / user agents only.
 	const isUntrustedProject = (agent: AgentConfig) =>
-		(agent.source === "project" || agent.source === "project-pi") && process.env.PI_CREW_TRUST_PROJECT_AGENT_EXTENSIONS !== "1";
+		(agent.source === "project" || agent.source === "project-pi") && getCrewEnv("PI_CREW_TRUST_PROJECT_AGENT_EXTENSIONS") !== "1";
 	const withGlobalExtensions = (agent: AgentConfig): AgentConfig => {
 		if (isUntrustedProject(agent)) return agent;
 		return deduped.length > 0 || agent.extensions !== undefined

package/src/config/config-merge.ts

@@ -0,0 +1,183 @@
+import { DANGEROUS_OBJECT_KEYS } from "./config-validation.ts";
+import type { AgentOverrideConfig, PiTeamsConfig } from "./types.ts";
+
+function withoutUndefined<T extends Record<string, unknown>>(value: T): Partial<T> {
+	return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as Partial<T>;
+}
+
+export function mergeConfig(base: PiTeamsConfig, override: PiTeamsConfig): PiTeamsConfig {
+	const warnings: string[] = [];
+	const merged: PiTeamsConfig = {
+		...base,
+		...withoutUndefined(override as Record<string, unknown>),
+	};
+	if (base.autonomous || override.autonomous) {
+		merged.autonomous = {
+			...(base.autonomous ?? {}),
+			...withoutUndefined((override.autonomous ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.broker || override.broker) {
+		// WP-2/R2 fix (B1 battery 2026-08-18): `broker` was previously merged by
+		// the top-level spread only — a user-side broker object (defaults or a
+		// user config file with ANY broker block) replaced the project config's
+		// block WHOLESALE, silently dropping keys like waitMethodsEnabled that
+		// the user side did not set (enabled:true survived only because it
+		// matched DEFAULT_BROKER). Per-key user-wins, same as runtime/ui/….
+		merged.broker = {
+			...(base.broker ?? {}),
+			...withoutUndefined((override.broker ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.nesting || override.nesting) {
+		// ADR-5: per-key user-wins deep merge — a partial user-side nesting block
+		// (e.g. just maxSlots) must not erase DEFAULT_NESTING.enabled=false.
+		merged.nesting = {
+			...(base.nesting ?? {}),
+			...withoutUndefined((override.nesting ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.limits || override.limits) {
+		merged.limits = {
+			...(base.limits ?? {}),
+			...withoutUndefined((override.limits ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.runtime || override.runtime) {
+		merged.runtime = {
+			...(base.runtime ?? {}),
+			...withoutUndefined((override.runtime ?? {}) as Record<string, unknown>),
+		};
+		// F19-1 (Round 19 parity): deep-merge modelFallback like
+		// reliability.retryPolicy so a partial override cannot erase base fields
+		// (user-wins precedence per key). Assigned only when a side defines it —
+		// unlike retryPolicy we avoid a stray `modelFallback: undefined` key so
+		// the merged runtime shape stays byte-identical for configs without it.
+		if (base.runtime?.modelFallback || override.runtime?.modelFallback) {
+			merged.runtime.modelFallback = {
+				...(base.runtime?.modelFallback ?? {}),
+				...withoutUndefined((override.runtime?.modelFallback ?? {}) as Record<string, unknown>),
+			};
+		}
+	}
+	if (base.control || override.control) {
+		merged.control = {
+			...(base.control ?? {}),
+			...withoutUndefined((override.control ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.worktree || override.worktree) {
+		merged.worktree = {
+			...(base.worktree ?? {}),
+			...withoutUndefined((override.worktree ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.ui || override.ui) {
+		merged.ui = {
+			...(base.ui ?? {}),
+			...withoutUndefined((override.ui ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.agents || override.agents) {
+		merged.agents = {
+			...(base.agents ?? {}),
+			...withoutUndefined((override.agents ?? {}) as Record<string, unknown>),
+			overrides: {
+				...(base.agents?.overrides ?? {}),
+				...(withoutUndefined((override.agents?.overrides ?? {}) as Record<string, unknown>) as Record<string, AgentOverrideConfig>),
+			},
+		};
+	}
+	if (base.tools || override.tools) {
+		merged.tools = {
+			...(base.tools ?? {}),
+			...withoutUndefined((override.tools ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.telemetry || override.telemetry) {
+		merged.telemetry = {
+			...(base.telemetry ?? {}),
+			...withoutUndefined((override.telemetry ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.policy || override.policy) {
+		merged.policy = {
+			...(base.policy ?? {}),
+			...withoutUndefined((override.policy ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.notifications || override.notifications) {
+		merged.notifications = {
+			...(base.notifications ?? {}),
+			...withoutUndefined((override.notifications ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.observability || override.observability) {
+		merged.observability = {
+			...(base.observability ?? {}),
+			...withoutUndefined((override.observability ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.reliability || override.reliability) {
+		merged.reliability = {
+			...(base.reliability ?? {}),
+			...withoutUndefined((override.reliability ?? {}) as Record<string, unknown>),
+			retryPolicy:
+				base.reliability?.retryPolicy || override.reliability?.retryPolicy
+					? {
+							...(base.reliability?.retryPolicy ?? {}),
+							...withoutUndefined((override.reliability?.retryPolicy ?? {}) as Record<string, unknown>),
+						}
+					: undefined,
+		};
+	}
+	if (base.otlp || override.otlp) {
+		merged.otlp = {
+			...(base.otlp ?? {}),
+			...withoutUndefined((override.otlp ?? {}) as Record<string, unknown>),
+			headers: {
+				...(base.otlp?.headers ?? {}),
+				...(override.otlp?.headers ?? {}),
+			},
+		};
+		if (Object.keys(merged.otlp.headers ?? {}).length === 0) 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) 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)
+			const checkKey = (key: string): boolean => {
+				const lowerKey = key.toLowerCase();
+				if (DANGEROUS_OBJECT_KEYS.has(lowerKey)) return true;
+				return false;
+			};
+			if (checkKey(k)) {
+				invalidHeaders.push(k);
+				continue;
+			}
+			// 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\x0a-\x1f]/.test(valStr)) {
+				invalidHeaders.push(k);
+			}
+		}
+		if (invalidHeaders.length > 0) {
+			delete merged.otlp.headers;
+			warnings.push(`OTLP headers blocked due to invalid characters: ${invalidHeaders.join(", ")}`);
+		}
+	}
+	if (merged.agents?.overrides && Object.keys(merged.agents.overrides).length === 0) delete merged.agents.overrides;
+	return merged;
+}
+
+/** @internal — direct-test seam for Phase 2.2 extraction target (refactor-plan step 1.9c). */
+export const __test__mergeConfig = mergeConfig;