pi-crew 0.9.68 → 0.10.2

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;