pi-crew 0.9.26 → 0.9.27

package/scripts/watch-bundle.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * Auto-rebuild bundle watcher — dev-loop ergonomics for v0.9.17+.
+ *
+ * Watches `src/`, `index.bundle.ts` for changes and rebuilds
+ * `dist/index.mjs` after a 300ms debounce. Solves the "edit src/foo.ts,
+ * forget to rebuild, run stale bundle" race that motivated check:
+ * bundle-staleness as a CI gate.
+ *
+ * Usage:
+ *   node scripts/watch-bundle.mjs                # default: watch src/ + index.bundle.ts
+ *   node scripts/watch-bundle.mjs --once         # build once and exit (CI prep)
+ *   node scripts/watch-bundle.mjs --debounce 500 # custom debounce ms
+ *
+ * Why native fs.watch (not chokidar):
+ *   - Adds zero deps (chokidar would add ~50 transitive deps)
+ *   - Node 22 + Linux/macOS support recursive watching (fs.watch recursive)
+ *
+ * Why not in-process (bundled into build:bundle):
+ *   - Watch is a separate dev concern; doesn't belong in the build script
+ *   - Keeps the build script one-shot (CI-friendly, deterministic)
+ */
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { readdir, watch } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+let onceMode = false;
+let debounceMs = 300;
+for (let i = 0; i < args.length; i += 1) {
+	if (args[i] === "--once") {
+		onceMode = true;
+	} else if (args[i] === "--debounce" && args[i + 1]) {
+		debounceMs = Number(args[i + 1]);
+		i += 1;
+	}
+}
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, "..");
+
+const WATCH_PATHS = ["src", "index.bundle.ts"];
+const EXTENSIONS_TO_WATCH = new Set([".ts", ".mts", ".cts", ".js", ".mjs"]);
+const IGNORE_DIRS = new Set(["node_modules", "dist", ".git"]);
+
+let pending = null;
+let lastBuildReason = null;
+
+function scheduleRebuild(reason, file) {
+	lastBuildReason = `${reason} ${path.relative(root, file ?? "")}`;
+	if (pending) clearTimeout(pending);
+	pending = setTimeout(() => {
+		pending = null;
+		runBuild().catch((err) => console.error("[watch-bundle] build crashed:", err));
+	}, debounceMs);
+}
+
+function runBuild() {
+	return new Promise((resolve, reject) => {
+		const startMs = Date.now();
+		const child = spawn(process.execPath, [path.join(root, "scripts/build-bundle.mjs")], {
+			stdio: ["ignore", "pipe", "pipe"],
+			cwd: root,
+			env: { ...process.env, FORCE_COLOR: "0" },
+		});
+		let stderr = "";
+		child.stdout.on("data", (chunk) => {
+			const text = String(chunk);
+			if (text.includes("[build-bundle] dist/index.mjs")) {
+				process.stdout.write(`[watch-bundle] ${text}`);
+			}
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += String(chunk);
+			process.stderr.write(`[watch-bundle] ${chunk}`);
+		});
+		child.on("exit", (code) => {
+			const ms = Date.now() - startMs;
+			if (code === 0) {
+				console.log(`[watch-bundle] ok in ${ms}ms (${lastBuildReason ?? "initial"})`);
+				resolve();
+			} else {
+				reject(new Error(`build exited with code ${code}: ${stderr.trim().split("\n").slice(-3).join(" / ")}`));
+			}
+		});
+		child.on("error", reject);
+	});
+}
+
+async function listFiles(dir) {
+	const out = [];
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const entry of entries) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (IGNORE_DIRS.has(entry.name)) continue;
+			out.push(...(await listFiles(full)));
+		} else if (entry.isFile()) {
+			const ext = path.extname(entry.name).toLowerCase();
+			if (EXTENSIONS_TO_WATCH.has(ext)) out.push(full);
+		}
+	}
+	return out;
+}
+
+async function watchDir(dir) {
+	// Linux inotify (used by fs.watch {recursive: true} on modern Node)
+	// sometimes misses events on deep trees. Walk the tree once and
+	// spawn a per-directory watcher for robustness. Cost: O(2N) FDs
+	// where N = number of source dirs (~5 for a typical pi-crew tree).
+	// Each watcher is independent and yields events as its dir changes.
+	const watcherJobs = [];
+	try {
+		// Watch the dir itself (catches direct children changes)
+		const rootWatcher = await watch(dir, { persistent: true });
+		watcherJobs.push(
+			(async () => {
+				for await (const e of rootWatcher) {
+					if (e.filename) handleEvent(dir, e.filename);
+				}
+			})(),
+		);
+	} catch (err) {
+		console.warn(`[watch-bundle] cannot watch ${dir}:`, err?.code ?? err?.message ?? err);
+	}
+	// Recurse into subdirectories (skip ignored) — each gets its own watcher
+	try {
+		const entries = await readdir(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			if (IGNORE_DIRS.has(entry.name)) continue;
+			const sub = path.join(dir, entry.name);
+			watcherJobs.push(
+				(async () => {
+					try {
+						const subWatcher = await watch(sub, { persistent: true });
+						for await (const e of subWatcher) {
+							if (e.filename) handleEvent(sub, e.filename);
+						}
+					} catch (err) {
+						console.warn(
+							`[watch-bundle] cannot watch ${sub}:`,
+							err?.code ?? err?.message ?? err,
+						);
+					}
+				})(),
+			);
+		}
+	} catch {
+		// ignore readdir errors
+	}
+	// Block until any watcher completes (they shouldn't, they're persistent)
+	await Promise.race(watcherJobs);
+}
+
+function handleEvent(watchedDir, filename) {
+	const fullPath = path.resolve(watchedDir, filename);
+	const ext = path.extname(fullPath).toLowerCase();
+	if (!EXTENSIONS_TO_WATCH.has(ext)) return;
+	if (fullPath.includes(`${path.sep}dist${path.sep}`)) return;
+	scheduleRebuild("change", fullPath);
+}
+
+async function watchFile(file) {
+	if (!existsSync(file)) return;
+	const dir = path.dirname(file);
+	const watcher = watch(dir, { persistent: true });
+	for await (const event of watcher) {
+		if (!event.filename) continue;
+		const changed = path.resolve(dir, event.filename);
+		if (changed === file) scheduleRebuild("change", changed);
+	}
+}
+
+async function main() {
+	const watchables = WATCH_PATHS.map((p) => path.join(root, p)).filter((p) => {
+		try {
+			return existsSync(p);
+		} catch {
+			return false;
+		}
+	});
+	if (watchables.length === 0) {
+		console.error("[watch-bundle] no watchable paths found (run from repo root)");
+		process.exit(1);
+	}
+
+	console.log("[watch-bundle] initial build...");
+	let initialOk = true;
+	try {
+		await runBuild();
+	} catch (err) {
+		console.error("[watch-bundle] initial build failed:", err.message);
+		initialOk = false;
+	}
+
+	if (onceMode) {
+		process.exit(initialOk ? 0 : 2);
+	}
+
+	if (!initialOk) {
+		console.warn("[watch-bundle] initial build failed; watching anyway");
+	}
+
+	let seedCount = 0;
+	for (const p of watchables) {
+		try {
+			const stat = statSync(p);
+			if (stat.isDirectory()) {
+				seedCount += (await listFiles(p)).length;
+			} else if (stat.isFile()) {
+				seedCount += 1;
+			}
+		} catch {
+			// skip
+		}
+	}
+	console.log(`[watch-bundle] seeded with ${seedCount} source files`);
+
+	const watchJobs = [];
+	for (const p of watchables) {
+		try {
+			const stat = statSync(p);
+			watchJobs.push(stat.isDirectory() ? watchDir(p) : watchFile(p));
+		} catch (err) {
+			console.warn(`[watch-bundle] cannot watch ${p}:`, err?.code ?? err?.message ?? err);
+		}
+	}
+
+	console.log(`[watch-bundle] watching ${watchables.length} paths; debounce=${debounceMs}ms; Ctrl+C to stop`);
+
+	let shutting = false;
+	const stop = () => {
+		if (shutting) return;
+		shutting = true;
+		console.log("\n[watch-bundle] shutting down...");
+		if (pending) {
+			clearTimeout(pending);
+			pending = null;
+		}
+		setTimeout(() => process.exit(0), 200);
+	};
+	process.on("SIGINT", stop);
+	process.on("SIGTERM", stop);
+
+	await Promise.race(watchJobs);
+}
+
+main().catch((err) => {
+	console.error("[watch-bundle] fatal:", err);
+	process.exit(1);
+});

package/scripts/watchdog-harness.ts

@@ -0,0 +1,119 @@
+/**
+ * Watchdog harness — a minimal script that mimics the background-runner's
+ * watchdog + keepAlive mechanism WITHOUT needing a real team/run manifest.
+ *
+ * This is used by test/integration/background-runner-watchdog-e2e.test.ts to
+ * verify the watchdog fires and force-exits a hung process.
+ *
+ * Usage:
+ *   node --experimental-strip-types scripts/watchdog-harness.ts
+ *
+ * Env vars:
+ *   PI_CREW_MAX_RUN_MS          — watchdog timeout (ms). Default: 2h.
+ *   PI_CREW_PARENT_PID          — parent guard PID. If parent dies, exit 124.
+ *   PI_CREW_HARD_KILL_GRACE_MS  — grace period before force-exit. Default: 15000.
+ *
+ * The script:
+ *   1. Starts the parent guard (self-terminates if parent dies)
+ *   2. Starts a keepAlive interval (prevents event-loop exit)
+ *   3. Starts a watchdog timer (fires after MAX_RUN_MS, schedules force-exit)
+ *   4. NEVER resolves — simulating a hung team run
+ *
+ * Expected behaviour: process exits via watchdog force-exit within
+ *   PI_CREW_MAX_RUN_MS + PI_CREW_HARD_KILL_GRACE_MS milliseconds.
+ */
+
+// ─── Config (from env — mirrors background-runner.ts) ─────────────────────────
+const MAX_BACKGROUND_RUN_MS = (() => {
+	const env = Number.parseInt(process.env.PI_CREW_MAX_RUN_MS ?? "", 10);
+	return Number.isFinite(env) && env > 0 ? env : 2 * 60 * 60 * 1000; // 2h default
+})();
+
+const HARD_KILL_GRACE_MS = Number.parseInt(process.env.PI_CREW_HARD_KILL_GRACE_MS ?? "", 10) || 15_000;
+
+// ─── Global error handlers (mirror background-runner.ts patterns) ─────────────
+// These prevent unhandled exceptions/rejections from crashing the process
+// before the watchdog can fire. The harness deliberately hangs, so these are
+// the only way to keep the process alive long enough for the watchdog to trigger.
+process.on("uncaughtException", (err) => {
+	console.error(`[watchdog-harness] uncaughtException: ${err.message}`);
+});
+
+process.on("unhandledRejection", (reason) => {
+	const msg = reason instanceof Error ? reason.message : String(reason);
+	console.error(`[watchdog-harness] unhandledRejection: ${msg}`);
+});
+
+// ─── Parent Guard ──────────────────────────────────────────────────────────────
+const parentPid = Number(process.env.PI_CREW_PARENT_PID);
+if (parentPid > 0) {
+	const POLL_INTERVAL_MS = 500;
+
+	function isPidAlive(pid: number): boolean {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	const guard = setInterval(() => {
+		// Wrap in try/catch: if isPidAlive throws unexpectedly (e.g. EPERM on
+		// some platforms), we don't want the interval itself to crash and prevent
+		// the watchdog from ever firing.
+		try {
+			if (!isPidAlive(parentPid)) {
+				clearInterval(guard);
+				process.exit(124); // 124 = "parent died" exit code
+			}
+		} catch (err) {
+			// Unexpected error in parent guard — log and continue polling.
+			console.error(`[watchdog-harness] parent-guard error: ${err}`);
+		}
+	}, POLL_INTERVAL_MS);
+	// NOTE: intentionally NOT unref'd — must keep event loop alive while parent is alive.
+}
+
+// ─── KeepAlive (same interval as background-runner.ts) ─────────────────────────
+const keepAlive = setInterval(() => {}, 5000);
+// NOTE: intentionally NOT unref'd — must hold the event loop open while the
+// process is alive. The event loop MUST stay alive so the forceExit setTimeout
+// below can fire. If keepAlive is cleared too early, the event loop drains
+// and all pending setTimeouts are silently cancelled before they fire.
+
+// ─── Watchdog ─────────────────────────────────────────────────────────────────
+// Track whether abort+force-exit has already been triggered (prevents double-fire).
+let watchdogFired = false;
+
+const watchdogTimer = setTimeout(() => {
+	if (watchdogFired) return;
+	watchdogFired = true;
+
+	console.error(
+		`[watchdog-harness] WATCHDOG: run exceeded ${MAX_BACKGROUND_RUN_MS}ms — scheduling force-exit in ${HARD_KILL_GRACE_MS}ms (zombie prevention)`,
+	);
+
+	// Hard-exit safety net: if the abort does not propagate within grace period,
+	// force-kill so the process cannot linger. Matches background-runner.ts logic.
+	// NOTE: keepAlive is NOT cleared here — it keeps the event loop alive so
+	// the forceExit setTimeout below can fire. If keepAlive is cleared, the
+	// event loop drains and forceExit is silently cancelled (observed: process
+	// exits via module-level finally/runCleanup with the last exit code instead).
+	const forceExit = setTimeout(() => {
+		// Clear keepAlive only at the very end, right before force-exit.
+		clearInterval(keepAlive);
+		clearTimeout(watchdogTimer);
+		process.exit(1);
+	}, HARD_KILL_GRACE_MS);
+	// NOTE: intentionally NOT unref'd — this timer MUST fire to force-exit.
+}, MAX_BACKGROUND_RUN_MS);
+
+// ─── Hung run simulation ──────────────────────────────────────────────────────
+// NEVER resolve this promise — simulates a team run that hangs forever.
+// The watchdog setTimeout above fires and force-exits the process first.
+await new Promise<void>((resolve) => {
+	// Intentionally never resolved. The unhandledRejection handler above keeps
+	// the process alive until the watchdog fires and calls process.exit().
+	void resolve;
+});

package/src/agents/discover-agents.ts

@@ -490,7 +490,12 @@ function applyAgentOverrides(agents: AgentConfig[], cwd: string, loadedConfig?:
 // SEC-005 Fix: Uses version-based cache for atomic invalidation.
 // ═══════════════════════════════════════════════════════════════════════════
 
-const DISCOVERY_CACHE_TTL_MS = 500;
+// F15: raised from 500 ms -> 5 s. The cache-version stamp (SEC-005) plus
+// explicit `invalidateAgentDiscoveryCache()` calls from management actions
+// (create/update/delete) cover correctness on edit; 5 s TTL is plenty for the
+// powerbar / scheduler hot path (~5 Hz when a run is active) and matches the
+// TTL we use for workflow / team discovery caches.
+const DISCOVERY_CACHE_TTL_MS = 5000;
 interface CachedDiscoveryEntry {
 	result: AgentDiscoveryResult;
 	expiresAt: number;

package/src/config/defaults.ts

@@ -1,6 +1,11 @@
 export const DEFAULT_CHILD_PI: Readonly<{
 	postExitStdioGuardMs: number;
 	finalDrainMs: number;
+	/** F12: early-exit the drain if stdout goes silent for ≥ this many ms after
+	 *  the final assistant event AND the assistant already emitted
+	 *  message_end with stopReason=stop. Lets well-behaved workers finish in
+	 *  ~800 ms instead of the full 5 s ceiling. Set to >= finalDrainMs to disable. */
+	finalDrainQuietMs: number;
 	hardKillMs: number;
 	responseTimeoutMs: number;
 	maxCaptureBytes: number;
@@ -11,6 +16,7 @@ export const DEFAULT_CHILD_PI: Readonly<{
 }> = {
 	postExitStdioGuardMs: 3000,
 	finalDrainMs: 5000,
+	finalDrainQuietMs: 800,
 	hardKillMs: 3000,
 	// Child workers can spend more than a few seconds in provider calls or long-running tools without emitting stdout.
 	// Keep this as a coarse stuck-worker guard rather than a short per-message latency budget.

package/src/extension/crew-vibes/cat-frames.ts

@@ -0,0 +1,18 @@
+/**
+ * ANSI art cat animation frames extracted from runner-spritesheet.png.
+ * Used when PUA font glyphs are not available (web terminals like gotty).
+ * Each frame is an array of strings (one per line).
+ */
+export const CAT_FRAMES: readonly string[][] = [
+	// Frame 0 — standing
+	["▄▄ ███▄ ", "▀▀█████▄", "  ██▀██ ", "  ▀▀  ▀▀"],
+	// Frame 1 — step 1
+	["  ████  ", "  █████▄", "▄██████▀", "  ██ ▀█▄"],
+	// Frame 2 — step 2
+	[" ▄██████", " █████▀ ", "███████ ", "▀██████ "],
+	// Frame 3 — step 3
+	["  ████  ", "▄█████▄ ", "▀██████▄", "▄█▀  ██ "],
+] as const;
+
+/** Number of animation frames. */
+export const CAT_FRAME_COUNT = CAT_FRAMES.length;

package/src/extension/crew-vibes/config.ts

@@ -0,0 +1,195 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { hasCrewFontFile, isWebTerminal } from "./font-detect.ts";
+
+/**
+ * Self-contained config for the crew-vibes module (speed + capacity meters).
+ * Stored in its own JSON file so it never touches the strict typebox schema
+ * used by the rest of pi-crew.
+ */
+
+export const SPEED_STATUS_ID = "pi-crew-speed";
+export const CAPACITY_STATUS_ID = "pi-crew-bar";
+export const PROVIDER_STATUS_ID = "pi-crew-bar";
+
+function resolveHome(): string {
+	return process.env.PI_TEAMS_HOME?.trim() || process.env.HOME || process.env.USERPROFILE || "";
+}
+
+export function configPath(): string {
+	return join(resolveHome(), ".pi", "agent", "pi-crew-vibes.json");
+}
+
+export type TokenDisplay = "off" | "tokens" | "percentage";
+
+export interface SpeedConfig {
+	enabled: boolean;
+	footer: boolean;
+	indicator: boolean;
+	label: string;
+	renderIntervalMs: number;
+	slidingWindowMs: number;
+	minReliableDurationMs: number;
+	maxDisplayTokS: number;
+	defaultIntervalMs: number;
+	minIntervalMs: number;
+	maxIntervalMs: number;
+	scale: number;
+}
+
+export interface CapacityConfig {
+	enabled: boolean;
+	tokenDisplay: TokenDisplay;
+	showLabel: boolean;
+	refreshIntervalMs: number;
+	labels: [string, string, string, string, string, string];
+	icons: [string, string, string, string, string, string];
+	providerUsage: boolean;
+	providerRefreshMs: number;
+}
+
+export interface CrewVibesConfig {
+	enabled: boolean;
+	speed: SpeedConfig;
+	capacity: CapacityConfig;
+}
+
+export const DEFAULT_CONFIG: CrewVibesConfig = {
+	enabled: true,
+	speed: {
+		enabled: true,
+		footer: false,
+		indicator: true,
+		label: "tok/s",
+		renderIntervalMs: 250,
+		slidingWindowMs: 1000,
+		minReliableDurationMs: 1000,
+		maxDisplayTokS: 500,
+		defaultIntervalMs: 167,
+		minIntervalMs: 50,
+		maxIntervalMs: 250,
+		scale: 6000,
+	},
+	capacity: {
+		enabled: true,
+		tokenDisplay: "tokens",
+		showLabel: true,
+		refreshIntervalMs: 2000,
+		labels: ["Orbit", "Cruise", "Warp", "Black Hole", "Supernova", "Big Bang"],
+		icons: ["", "", "", "", "", ""],
+		providerUsage: true,
+		providerRefreshMs: 300000,
+	},
+};
+
+// Fallback capacity icons using standard Unicode characters that render
+// on any terminal without the crew-vibes PUA font.
+const FALLBACK_CAPACITY_ICONS: [string, string, string, string, string, string] = [
+	"\u25CB ", // ○ empty circle (lean)
+	"\u25D4 ", // ◔ circle with dot (chonking)
+	"\u25D1 ", // ◑ circle half filled (chonky)
+	"\u25CF ", // ● filled circle (big chonk)
+	"\u2B24 ", // ⬤ large filled circle (mega chonk)
+	"\u2B22 ", // ⬢ filled hexagon (oh lawd)
+];
+
+/** Return capacity icons: standard Unicode glyphs that render on any terminal.
+ * PUA glyphs (U+E710..U+E715) require crew-vibes.ttf AND terminal PUA
+ * support — many terminals cannot render them even with the font installed. */
+export function capacityIcons(): [string, string, string, string, string, string] {
+	// Web terminals cannot render PUA glyphs — use fallback.
+	if (isWebTerminal()) return FALLBACK_CAPACITY_ICONS;
+	return hasCrewFontFile() ? DEFAULT_CONFIG.capacity.icons : FALLBACK_CAPACITY_ICONS;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function boolFrom(raw: unknown, fallback: boolean): boolean {
+	return typeof raw === "boolean" ? raw : fallback;
+}
+
+function stringFrom(raw: unknown, fallback: string): string {
+	return typeof raw === "string" ? raw : fallback;
+}
+
+function positiveFrom(raw: unknown, fallback: number): number {
+	return typeof raw === "number" && Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+
+function sextet(
+	raw: unknown,
+	fallback: [string, string, string, string, string, string],
+): [string, string, string, string, string, string] {
+	if (Array.isArray(raw) && raw.length === 6 && raw.every((entry) => typeof entry === "string")) {
+		return raw as [string, string, string, string, string, string];
+	}
+	return fallback;
+}
+
+function tokenDisplayFrom(raw: unknown, fallback: TokenDisplay): TokenDisplay {
+	return raw === "off" || raw === "tokens" || raw === "percentage" ? raw : fallback;
+}
+
+function normalizeSpeed(raw: unknown): SpeedConfig {
+	const input = asRecord(raw);
+	const speed: SpeedConfig = {
+		enabled: boolFrom(input.enabled, DEFAULT_CONFIG.speed.enabled),
+		footer: boolFrom(input.footer, DEFAULT_CONFIG.speed.footer),
+		indicator: boolFrom(input.indicator, DEFAULT_CONFIG.speed.indicator),
+		label: stringFrom(input.label, DEFAULT_CONFIG.speed.label),
+		renderIntervalMs: positiveFrom(input.renderIntervalMs, DEFAULT_CONFIG.speed.renderIntervalMs),
+		slidingWindowMs: positiveFrom(input.slidingWindowMs, DEFAULT_CONFIG.speed.slidingWindowMs),
+		minReliableDurationMs: positiveFrom(input.minReliableDurationMs, DEFAULT_CONFIG.speed.minReliableDurationMs),
+		maxDisplayTokS: positiveFrom(input.maxDisplayTokS, DEFAULT_CONFIG.speed.maxDisplayTokS),
+		defaultIntervalMs: positiveFrom(input.defaultIntervalMs, DEFAULT_CONFIG.speed.defaultIntervalMs),
+		minIntervalMs: positiveFrom(input.minIntervalMs, DEFAULT_CONFIG.speed.minIntervalMs),
+		maxIntervalMs: positiveFrom(input.maxIntervalMs, DEFAULT_CONFIG.speed.maxIntervalMs),
+		scale: positiveFrom(input.scale, DEFAULT_CONFIG.speed.scale),
+	};
+	if (speed.minIntervalMs > speed.maxIntervalMs) {
+		speed.minIntervalMs = DEFAULT_CONFIG.speed.minIntervalMs;
+		speed.maxIntervalMs = DEFAULT_CONFIG.speed.maxIntervalMs;
+	}
+	return speed;
+}
+
+function normalizeCapacity(raw: unknown): CapacityConfig {
+	const input = asRecord(raw);
+	return {
+		enabled: boolFrom(input.enabled, DEFAULT_CONFIG.capacity.enabled),
+		tokenDisplay: tokenDisplayFrom(input.tokenDisplay, DEFAULT_CONFIG.capacity.tokenDisplay),
+		showLabel: boolFrom(input.showLabel, DEFAULT_CONFIG.capacity.showLabel),
+		refreshIntervalMs: positiveFrom(input.refreshIntervalMs, DEFAULT_CONFIG.capacity.refreshIntervalMs),
+		labels: sextet(input.labels, DEFAULT_CONFIG.capacity.labels),
+		icons: sextet(input.icons, DEFAULT_CONFIG.capacity.icons),
+		providerUsage: boolFrom(input.providerUsage, DEFAULT_CONFIG.capacity.providerUsage),
+		providerRefreshMs: positiveFrom(input.providerRefreshMs, DEFAULT_CONFIG.capacity.providerRefreshMs),
+	};
+}
+
+export function normalizeConfig(raw: unknown): CrewVibesConfig {
+	const input = asRecord(raw);
+	return {
+		enabled: boolFrom(input.enabled, DEFAULT_CONFIG.enabled),
+		speed: normalizeSpeed(input.speed),
+		capacity: normalizeCapacity(input.capacity),
+	};
+}
+
+export function loadConfig(): CrewVibesConfig {
+	try {
+		const path = configPath();
+		if (!existsSync(path)) return normalizeConfig(undefined);
+		return normalizeConfig(JSON.parse(readFileSync(path, "utf8")));
+	} catch {
+		return normalizeConfig(undefined);
+	}
+}
+
+export function saveConfig(config: CrewVibesConfig): void {
+	const path = configPath();
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(normalizeConfig(config), null, 2)}\n`);
+}