pi-crew 0.6.1 → 0.6.4

package/docs/ui-optimization-plan.md

@@ -0,0 +1,447 @@
+# pi-crew UI Optimization & Beautification Plan
+
+> Based on deep analysis of oh-my-pi patterns + pi-crew current UI state.
+> Date: 2026-06-12
+> Status: Draft — awaiting approval
+
+## Current State
+
+### pi-crew UI (~7,800 lines across 45 files)
+
+| Component | Lines | Status |
+|---|---|---|
+| `run-snapshot-cache.ts` | 827 | Complex, over-engineered |
+| `settings-overlay.ts` | 723 | Functional |
+| `crew-widget.ts` | 544 | **High complexity, hard to read** |
+| `run-dashboard.ts` | 536 | Dense, many responsibilities |
+| `mascot.ts` | 444 | Cute but bloated |
+| `tool-render.ts` | 380 | **Needs pattern overhaul** |
+| `theme-adapter.ts` | 190 | Defensive but verbose |
+
+### Key Problems
+
+1. **No theme color consistency** — `CrewThemeColor` has ~22 slots vs oh-my-pi's 40+
+2. **Tool rendering reimplements logic** — pi-brief's delegate-execute pattern is cleaner
+3. **Widget is monolithic** — 544 lines doing state management, rendering, caching, and formatting
+4. **No structured interaction** — `respond` action is free-text only; no `ask_user`-style schema
+5. **Raw ANSI codes in places** — mixing `theme.fg()` with `\x1b[38;5;2m`
+6. **No brief/compact mode** — all output is verbose, no toggle for condensed display
+7. **Checkpoint display is text-heavy** — run history shows full text vs compact stats
+
+---
+
+## Phase 1: Theme System Upgrade
+
+**Priority**: HIGH — foundation for all other UI work
+**Effort**: 2-3 days
+**Risk**: LOW (additive changes, no breaking API)
+
+### 1.1 Expand Theme Color Slots
+
+**Current** (`src/ui/theme-adapter.ts`):
+```typescript
+export type CrewThemeColor =
+  | "accent" | "border" | "borderAccent" | "borderMuted"
+  | "success" | "error" | "warning" | "muted" | "dim" | "text"
+  | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext"
+  | "syntaxKeyword" | "syntaxString" | "syntaxNumber"
+  | "syntaxComment" | "syntaxFunction" | "syntaxVariable"
+  | "syntaxType" | "syntaxOperator" | "syntaxPunctuation"
+  | "mdCodeBlock";
+```
+
+**Target** — add from oh-my-pi's 40+ slots:
+```typescript
+export type CrewThemeColor =
+  // Existing (keep)
+  | "accent" | "border" | "borderAccent" | "borderMuted"
+  | "success" | "error" | "warning" | "muted" | "dim" | "text"
+  | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext"
+  | "syntaxKeyword" | "syntaxString" | "syntaxNumber"
+  | "syntaxComment" | "syntaxFunction" | "syntaxVariable"
+  | "syntaxType" | "syntaxOperator" | "syntaxPunctuation"
+  | "mdCodeBlock"
+  // NEW — message display
+  | "userMessageText" | "customMessageLabel"
+  // NEW — tool rendering
+  | "toolTitle"       // already used in tool-render.ts but missing from type
+  | "toolOutput"
+  | "toolPending" | "toolSuccess" | "toolError"
+  // NEW — markdown
+  | "mdHeading" | "mdLink" | "mdCode" | "mdQuote" | "mdHr" | "mdListBullet"
+  // NEW — thinking gradient (6 levels)
+  | "thinkingOff" | "thinkingMinimal" | "thinkingLow"
+  | "thinkingMedium" | "thinkingHigh" | "thinkingXhigh"
+  // NEW — special
+  | "bashMode" | "thinkingText";
+
+export type CrewThemeBg =
+  // Existing
+  | "selectedBg" | "userMessageBg" | "toolPendingBg" | "toolSuccessBg" | "toolErrorBg"
+  // NEW
+  | "customMessageBg";
+```
+
+**Files to change**: `src/ui/theme-adapter.ts`
+
+### 1.2 Theme Color Fallback Map
+
+Add default ANSI values for all new slots so widgets work even with minimal themes:
+
+```typescript
+const THEME_FALLBACKS: Record<CrewThemeColor, string> = {
+  toolTitle: "\x1b[36m",     // cyan
+  toolOutput: "\x1b[38;5;245m", // gray
+  toolPending: "\x1b[38;5;240m",
+  toolSuccess: "\x1b[32m",
+  toolError: "\x1b[31m",
+  mdHeading: "\x1b[33m",     // yellow
+  mdLink: "\x1b[35m",        // indigo
+  mdCode: "\x1b[32m",        // green
+  // ... all new slots
+};
+```
+
+### 1.3 Remove Raw ANSI from Business Logic
+
+Find and replace all raw `\x1b[38;5;XXXm` in non-UI files with `theme.fg("slot", text)` calls.
+
+**Files to audit**:
+- `src/ui/tool-render.ts` — check for raw ANSI
+- `src/extension/registration/commands.ts` — status line rendering
+- `src/runtime/task-display.ts` — display formatting
+
+---
+
+## Phase 2: Tool Rendering Overhaul
+
+**Priority**: HIGH — visible improvement to every tool call display
+**Effort**: 2-3 days
+**Risk**: MEDIUM (changes how tool calls look)
+
+### 2.1 Adopt Rendering-Only Override Pattern
+
+**From oh-my-pi's pi-brief**: Register tool rendering that delegates execution to original.
+
+**Current pi-crew approach** (`src/ui/tool-render.ts`):
+- 380 lines of monolithic rendering functions
+- Separate `renderTeamToolCall`, `renderAgentToolCall`, `renderTeamToolResult`, `renderAgentToolResult`
+- Each function handles both collapsed and expanded mode internally
+
+**Target**: Split into focused renderers using a registry pattern:
+
+```typescript
+// src/ui/tool-renderers/index.ts
+export interface ToolRenderer {
+  renderCall(args: unknown, theme: CrewTheme, expanded: boolean): Component;
+  renderResult(result: unknown, theme: CrewTheme, expanded: boolean): Component;
+}
+
+// src/ui/tool-renderers/team-renderer.ts
+export const teamToolRenderer: ToolRenderer = {
+  renderCall(args, theme, expanded) { ... },
+  renderResult(result, theme, expanded) { ... },
+};
+
+// src/ui/tool-renderers/agent-renderer.ts
+export const agentToolRenderer: ToolRenderer = { ... };
+```
+
+### 2.2 Compact Brief Mode for Tool Output
+
+**From pi-brief**: Add a configurable "brief" toggle that shows one-line summaries.
+
+```typescript
+// New: src/ui/tool-renderers/brief-mode.ts
+export function briefResult(result: ToolResult, theme: CrewTheme): string {
+  // read → "→ 142 lines"
+  // bash → "→ done" or "→ 12 lines"
+  // edit → "→ edited +3 -1"
+  // write → "→ written"
+  // team → "→ 3/3 tasks · 1.2m · 45k tok"
+  // agent → "✓ explorer · 8 tools · 23.4s"
+}
+```
+
+Add `/crew-brief on|off` command and persist state via `pi.appendEntry()`.
+
+### 2.3 Team Tool Result — Compact Stats Display
+
+**From pi-rewind's checkpoint display**: Show goal + task stats in one line.
+
+**Current**:
+```
+team action='run' (implementation) · status=completed · runId=team_2026... · goal="Investigate failing..."
+```
+
+**Target** (compact):
+```
+✓ team/implementation · 3/3 tasks · 1.2m · ↑45k ↓12k · $0.042
+```
+
+With expanded (Ctrl+O):
+```
+✓ team/implementation · 3/3 tasks · 1.2m · ↑45k ↓12k · $0.042
+├─ ✓ explorer · 8 tools · 23.4s · ↑12k ↓4k
+├─ ✓ executor · 15 tools · 41.2s · ↑22k ↓6k
+└─ ✓ verifier · 5 tools · 12.1s · ↑11k ↓2k
+```
+
+---
+
+## Phase 3: Widget Refactor
+
+**Priority**: MEDIUM — internal cleanup, same visual output
+**Effort**: 3-4 days
+**Risk**: MEDIUM (core display component)
+
+### 3.1 Split crew-widget.ts into Modules
+
+**Current**: 544 lines monolith doing everything.
+
+**Target structure**:
+```
+src/ui/widget/
+├── index.ts              # Public API: updateCrewWidget, stopCrewWidget
+├── widget-component.ts   # CrewWidgetComponent class (~100 lines)
+├── widget-model.ts       # Data fetching + caching (~100 lines)
+├── widget-renderer.ts    # Line building + colorizing (~150 lines)
+├── widget-formatters.ts  # formatTokens, formatDuration, agentStats (~100 lines)
+└── widget-types.ts       # Shared types
+```
+
+### 3.2 Adopt SessionStateMap Pattern
+
+**From oh-my-pi**: Generic session-scoped state container instead of scattered maps.
+
+```typescript
+// src/state/session-state-map.ts (new)
+export class SessionStateMap<T> {
+  private map = new Map<string, T>();
+  getOrUndefined(sessionId: string): T | undefined { ... }
+  set(sessionId: string, value: T): void { ... }
+  delete(sessionId: string): void { ... }
+}
+```
+
+Use this in widget, dashboard, and live-agent-manager instead of separate `Map<string, ...>` instances.
+
+### 3.3 Render Coalescing Optimization
+
+The widget currently rebuilds signature strings on every render call. Optimize:
+- Pre-compute signatures when data changes, not on render
+- Use a simple counter-based invalidation instead of string concatenation
+- Eliminate `this.cacheSignature` string comparison in hot path
+
+---
+
+## Phase 4: Dashboard Polish
+
+**Priority**: MEDIUM
+**Effort**: 3-4 days
+**Risk**: LOW
+
+### 4.1 Run History — Compact Checkpoint Style
+
+**From pi-rewind**: Show runs with file-change statistics.
+
+**Current** (status command output):
+```
+Run: team_20260612100313...
+Status: completed
+Team: implementation
+Goal: Fix failing tests
+Tasks: 3/3
+Duration: 5m23s
+Tokens: 45.2k
+```
+
+**Target** (compact):
+```
+✓ team_...3d7f  implementation · Fix failing tests
+   3/3 tasks · 5m23s · ↑45k ↓12k
+   14 files +342 -87
+```
+
+### 4.2 Agent Progress — Thinking Level Visualization
+
+**From oh-my-pi's thinking gradient**: Show thinking intensity with color gradient.
+
+```typescript
+function thinkingColor(level: number, theme: CrewTheme): CrewThemeColor {
+  // level 0-5 → off, minimal, low, medium, high, xhigh
+  return ["thinkingOff", "thinkingMinimal", "thinkingLow",
+          "thinkingMedium", "thinkingHigh", "thinkingXhigh"][level];
+}
+```
+
+Apply to agent activity line when agent is "thinking..." (no tool call, just LLM processing).
+
+### 4.3 Dashboard Pane Improvements
+
+**Agents pane**: Add compact/expanded toggle per agent
+**Progress pane**: Use brief mode rendering from Phase 2
+**Mailbox pane**: Add structured response schema option
+**Health pane**: Color-code issues by severity
+
+---
+
+## Phase 5: Structured Interaction
+
+**Priority**: MEDIUM
+**Effort**: 4-5 days
+**Risk**: MEDIUM (new feature)
+
+### 5.1 Structured Respond Action
+
+**From pi-clarify**: Add schema validation to `respond` action.
+
+```typescript
+// In team-tool/respond.ts
+interface RespondOptions {
+  message: string;
+  // NEW: structured answer option
+  answer?: {
+    type: "select" | "text" | "confirm";
+    value: string | boolean;
+    label?: string;
+  };
+}
+```
+
+### 5.2 Secret Rejection in Tool Inputs
+
+**From pi-clarify's SECRET_WORDS**: Add to all tool inputs that accept user text.
+
+```typescript
+const SECRET_PATTERNS = [
+  "api key", "apikey", "auth token", "cookie", "credential",
+  "password", "private key", "secret", "token",
+];
+```
+
+Already partially done in `env-filter.ts`, but should extend to `goal`, `message`, `task` parameters.
+
+---
+
+## Phase 6: Code Quality from oh-my-pi
+
+**Priority**: LOW-MEDIUM (foundation for long-term)
+**Effort**: 2-3 days
+**Risk**: LOW
+
+### 6.1 Type Guard Library
+
+**From runtime-core**: Create `src/utils/guards.ts` with systematic type guards.
+
+```typescript
+// src/utils/guards.ts
+export function isRecord(value: unknown): value is Record<string, unknown> { ... }
+export function isString(value: unknown): value is string { ... }
+export function isNumber(value: unknown): value is number { ... }
+export function isNonEmptyString(value: unknown): value is string { ... }
+export function isArrayOf<T>(guard: (v: unknown) => v is T): (v: unknown) => v is readonly T[] { ... }
+export function getStringField(value: unknown, key: string): string | undefined { ... }
+export function getNumberField(value: unknown, key: number): number | undefined { ... }
+export function errorMessage(err: unknown): string { ... }
+```
+
+Replace scattered `typeof x === "string"` checks across codebase.
+
+### 6.2 No-Any Lint Rule
+
+Add ESLint rule to enforce `unknown` over `any`:
+
+```javascript
+// .eslintrc
+{
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/no-unsafe-assignment": "error",
+    "@typescript-eslint/no-unsafe-call": "error"
+  }
+}
+```
+
+### 6.3 mkdir-Based Locking (Optional)
+
+**From pi-checkpoint**: Replace JSON token-based locks with `mkdir` atomic locks.
+
+This is a bigger change — could be Phase 7 if needed.
+
+---
+
+## Implementation Order & Timeline
+
+| Phase | Duration | Depends On | Impact |
+|---|---|---|---|
+| **Phase 1**: Theme System | 2-3 days | Nothing | Foundation for all UI |
+| **Phase 2**: Tool Rendering | 2-3 days | Phase 1 | Every tool call looks better |
+| **Phase 3**: Widget Refactor | 3-4 days | Phase 1 | Internal cleanup |
+| **Phase 4**: Dashboard Polish | 3-4 days | Phase 1, 2 | Visible improvement |
+| **Phase 5**: Structured Interaction | 4-5 days | Phase 2 | New feature |
+| **Phase 6**: Code Quality | 2-3 days | Nothing | Long-term maintainability |
+
+**Total estimated**: 16-22 days (can parallelize Phase 1+6, Phase 2+3)
+
+### Recommended Execution
+
+```
+Week 1: Phase 1 (Theme) + Phase 6 (Code Quality)  [parallel]
+Week 2: Phase 2 (Tool Rendering)
+Week 3: Phase 3 (Widget) + Phase 4 (Dashboard)  [sequential]
+Week 4: Phase 5 (Structured Interaction) + polish
+```
+
+---
+
+## Success Metrics
+
+| Metric | Current | Target |
+|---|---|---|
+| Theme color slots | 22 | 40+ |
+| Raw ANSI in business logic | ~15 instances | 0 |
+| Widget lines of code | 544 | ~150 (per module) |
+| Tool result compact display | N/A | All 7 tool types |
+| Structured respond | Free text only | Schema-validated |
+| `any` in production code | ~40 instances | 0 |
+| Type guard reuse | Scattered | Centralized in guards.ts |
+
+---
+
+## Risks & Mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Theme slot additions break existing themes | All new slots have fallback ANSI values |
+| Widget refactor breaks live updates | Keep same public API, refactor internals only |
+| Brief mode confuses users | Default OFF, toggle via `/crew-brief on` |
+| Structured respond breaks existing workflows | `message` field still accepts free text; `answer` is optional |
+| No-any lint produces too many errors | Incremental: start with new files, then expand |
+
+---
+
+## Files to Create/Modify
+
+### New Files
+- `src/ui/tool-renderers/index.ts`
+- `src/ui/tool-renderers/team-renderer.ts`
+- `src/ui/tool-renderers/agent-renderer.ts`
+- `src/ui/tool-renderers/brief-mode.ts`
+- `src/ui/widget/index.ts`
+- `src/ui/widget/widget-component.ts`
+- `src/ui/widget/widget-model.ts`
+- `src/ui/widget/widget-renderer.ts`
+- `src/ui/widget/widget-formatters.ts`
+- `src/ui/widget/widget-types.ts`
+- `src/state/session-state-map.ts`
+- `src/utils/guards.ts`
+
+### Modified Files
+- `src/ui/theme-adapter.ts` — expand color types + fallbacks
+- `src/ui/tool-render.ts` — slim down, delegate to renderers
+- `src/ui/crew-widget.ts` — split into widget/ modules
+- `src/ui/run-dashboard.ts` — compact display + thinking gradient
+- `src/ui/status-colors.ts` — add new status colors
+- `src/extension/team-tool/respond.ts` — structured response option
+- `src/extension/registration/commands.ts` — add `/crew-brief` command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.6.1",
+  "version": "0.6.4",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -84,7 +84,7 @@
     "ajv": "^8.20.0",
     "cli-highlight": "^2.1.11",
     "diff": "^5.2.0",
-    "jiti": "^2.6.1",
+    "jiti": "^2.7.0",
     "typebox": "^1.1.38"
   },
   "devDependencies": {

package/src/config/config.ts

@@ -8,6 +8,7 @@ import {
 	PiTeamsConfigSchema,
 } from "../schema/config-schema.ts";
 import { withFileLockSync } from "../state/locks.ts";
+import { atomicWriteFile } from "../state/atomic-write.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { projectCrewRoot, projectPiRoot } from "../utils/paths.ts";
 import { suggestConfigKey } from "./suggestions.ts";
@@ -79,7 +80,17 @@ function resolveHomeDir(): string {
 	// directory (e.g. withIsolatedHome) set PI_TEAMS_HOME to a tmp dir
 	// under /tmp; we skip the check in test environments (NODE_ENV=test)
 	// so existing tests don't break.
-	if (process.env.NODE_ENV === "test" || process.env.PI_CREW_SKIP_HOME_CHECK === "1") {
+	if (process.env.PI_CREW_SKIP_HOME_CHECK === "1") {
+		return envValue;
+	}
+	// NOTE: NODE_ENV=test bypass is intentional for test isolation only.
+	// It allows tests to use isolated temporary directories (e.g. withIsolatedHome
+	// sets PI_TEAMS_HOME to /tmp). This is NOT a security boundary — tests that
+	// need the validation skipped should set PI_CREW_SKIP_HOME_CHECK=1 explicitly.
+	// WARNING: Tests must NOT rely on PI_TEAMS_HOME for security boundaries in
+	// test environments. Any test verifying path-restriction behavior should set
+	// PI_CREW_SKIP_HOME_CHECK=1 and validate the path directly.
+	if (process.env.NODE_ENV === "test") {
 		return envValue;
 	}
 	try {
@@ -481,10 +492,22 @@ function mergeConfig(
 		};
 		if (Object.keys(merged.otlp.headers ?? {}).length === 0)
 			delete merged.otlp.headers;
-		// Validate OTLP headers for injection attacks (newlines, CR, null bytes)
+		// 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.
 		const invalidHeaders: string[] = [];
 		for (const [k, v] of Object.entries(merged.otlp.headers ?? {})) {
-			if (/[\r\n\x00]/.test(String(v))) { invalidHeaders.push(k); }
+			// 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
+			const valStr = String(v);
+			if (/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(valStr)) { invalidHeaders.push(k); }
 		}
 		if (invalidHeaders.length > 0) {
 			delete merged.otlp.headers;
@@ -511,10 +534,57 @@ const LIMIT_CEILINGS = {
 	runtimeGraceTurns: 1_000,
 } as const;
 
-function asRecord(value: unknown): Record<string, unknown> | undefined {
+/**
+ * Keys that could allow prototype pollution if merged into plain objects.
+ * NOTE: This set is comprehensive for ES2023 and earlier. When upgrading JavaScript
+ * versions, verify whether new dangerous Object.prototype properties have been added
+ * that could enable prototype pollution attacks.
+ */
+const DANGEROUS_OBJECT_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype",
+	"hasOwnProperty",
+	"toString",
+	"valueOf",
+	"isPrototypeOf",
+	"propertyIsEnumerable",
+	"toLocaleString",
+	"__defineGetter__",
+	"__defineSetter__",
+	"__lookupGetter__",
+	"__lookupSetter__",
+]);
+
+/**
+ * Strips dangerous Object.prototype keys from an object.
+ * Returns a new object built with Object.create(null) to prevent
+ * prototype pollution attacks.
+ */
+function sanitizeObject(obj: Record<string, unknown>): Record<string, unknown> {
+	const sanitized: Record<string, unknown> = Object.create(null);
+	for (const [key, value] of Object.entries(obj)) {
+		// Case-insensitive check to catch __Proto__, CONSTRUCTOR, etc.
+		const lowerKey = key.toLowerCase();
+		if (DANGEROUS_OBJECT_KEYS.has(lowerKey)) continue;
+		if (value && typeof value === "object" && !Array.isArray(value)) {
+			sanitized[key] = sanitizeObject(value as Record<string, unknown>);
+		} else {
+			sanitized[key] = value;
+		}
+	}
+	return sanitized;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
 	if (!value || typeof value !== "object" || Array.isArray(value))
 		return undefined;
-	return value as Record<string, unknown>;
+	// Defensive: create a sanitized copy to prevent prototype pollution.
+	// Uses Object.create(null) so the result has no prototype chain.
+	// WARNING: The returned object has no prototype methods (no hasOwnProperty,
+	// toString, etc.). Use Object.hasOwn(obj, key) or
+	// Object.prototype.hasOwnProperty.call(obj, key) for property checks.
+	return sanitizeObject(value as Record<string, unknown>);
 }
 
 function parseWithSchema<T extends TSchema>(
@@ -1190,7 +1260,29 @@ function unsetPath(record: Record<string, unknown>, dottedPath: string): void {
 
 function readConfigRecord(filePath: string): Record<string, unknown> {
 	if (!fs.existsSync(filePath)) return {};
-	const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+	// Defense-in-depth: reject config files larger than 10 MB before parsing.
+	// This prevents memory exhaustion and blocks deeply nested JSON that could
+	// cause stack overflow during parsing.
+	const MAX_CONFIG_SIZE = 10 * 1024 * 1024;
+	const stat = fs.statSync(filePath);
+	if (stat.size > MAX_CONFIG_SIZE) {
+		logInternalError(
+			"config.file-too-large",
+			new Error(`config file exceeds ${MAX_CONFIG_SIZE} bytes`),
+			`path=${filePath}; size=${stat.size}`,
+		);
+		return {};
+	}
+	// Parse with depth limit to prevent stack overflow from deeply nested JSON.
+	// Nesting beyond 100 levels is almost certainly an attack or malformed file.
+	const MAX_JSON_DEPTH = 100;
+	let depth = 0;
+	const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"), (_key, value) => {
+		if (++depth > MAX_JSON_DEPTH) {
+			throw new Error(`config JSON exceeds max depth ${MAX_JSON_DEPTH}`);
+		}
+		return value;
+	}) as unknown;
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
 	return raw as Record<string, unknown>;
 }
@@ -1244,7 +1336,7 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 		const projectPath = projectConfigPath(cwd);
 		const projectConfig = readOptionalConfig(projectPath);
 		// SECURITY FIX: Merge project config FIRST, then user config on top.
-		// This ensures user preferences always take precedence over project settings.
+		// Precedence formula: merge(projectConfig, userConfig) = userConfig wins.
 		// Sensitive fields have already been sanitized by sanitizeProjectConfig.
 		let effectiveConfig = {};
 		if (projectConfig.exists) {
@@ -1257,6 +1349,7 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 				...projectConfig.warnings,
 				...projectSafeConfig.warnings,
 			);
+			// merge(base=projectConfig, override=userConfig) → override wins
 			effectiveConfig = mergeConfig(effectiveConfig, projectSafeConfig.config);
 		}
 		// User config always takes precedence over project config
@@ -1265,19 +1358,20 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 
 
 		// `.pi/pi-crew.json` is the project-owned config file.
-		// SECURITY FIX: User config takes precedence over project-level `.pi/pi-crew.json`.
-		// This prevents malicious project configs from overriding user preferences.
+		// Merge project config FIRST (base), then user config on top (override).
+		// This ensures user preferences always take precedence over project settings.
+		// Sensitive fields have already been sanitized by sanitizeProjectConfig.
 		const piCrewJsonPath = projectPiCrewJsonPath(cwd);
 		const piCrewJsonConfig = readOptionalConfig(piCrewJsonPath);
 		if (piCrewJsonConfig.exists) {
 			warnings.push(...piCrewJsonConfig.warnings);
-			// Merge project config first, then user config on top
 			const projectPart = sanitizeProjectConfig(
 				piCrewJsonPath,
 				config,
 				piCrewJsonConfig.config,
 			);
 			warnings.push(...projectPart.warnings);
+			// base=project config, override=user config → user wins
 			const mergedProject = mergeConfig(projectPart.config, config);
 			config = mergedProject;
 			paths.push(piCrewJsonPath);
@@ -1319,10 +1413,9 @@ export function updateConfig(
 			merged = parseConfig(raw);
 		}
 		fs.mkdirSync(path.dirname(filePath), { recursive: true });
-		fs.writeFileSync(
+		atomicWriteFile(
 			filePath,
 			`${JSON.stringify(merged, null, 2)}\n`,
-			"utf-8",
 		);
 		return { path: filePath, config: merged };
 	});
@@ -1349,11 +1442,9 @@ export function updateAutonomousConfig(
 				? (current.autonomous as Record<string, unknown>)
 				: {};
 		current.autonomous = { ...currentAutonomous, ...patch };
-		fs.mkdirSync(path.dirname(filePath), { recursive: true });
-		fs.writeFileSync(
+		atomicWriteFile(
 			filePath,
 			`${JSON.stringify(current, null, 2)}\n`,
-			"utf-8",
 		);
 		return { path: filePath, config: parseConfig(current) };
 	});