pi-crew 0.6.4 → 0.7.2

package/src/runtime/resilient-edit.ts

@@ -0,0 +1,166 @@
+/**
+ * Resilient edit wrapper — uses the cascading replace() engine as a fallback
+ * when the native edit tool fails with "old_string not found".
+ *
+ * Multi-agent runs (crew workers) often provide slightly-wrong oldText:
+ *   - indentation drift (tabs vs spaces)
+ *   - trailing whitespace differences
+ *   - line-ending normalization (\r\n vs \n)
+ *
+ * The native edit tool is exact-match only and fails hard on these. This
+ * wrapper catches that failure and retries with the cascading engine, which
+ * tries (in order): exact → escape-normalized → line-trimmed → block-anchor →
+ * whitespace-normalized → trimmed-boundary.
+ *
+ * CONFLICT AWARENESS: pi-diff (`@heyhuynhgiabuu/pi-diff`) also overrides the
+ * edit tool with its own replace() integration. To avoid double-wrapping,
+ * this module is OPT-IN via the `CREW_RESILIENT_EDIT=1` env var, and
+ * auto-disables if pi-diff is detected in the loaded extensions.
+ *
+ * Usage (in register.ts, guarded):
+ *   if (process.env.CREW_RESILIENT_EDIT === "1") {
+ *       wrapEditWithResilientReplace(pi);
+ *   }
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { replace, type ReplaceResult } from "../runtime/replace.ts";
+
+interface ToolLike {
+	name: string;
+	description: string;
+	parameters: unknown;
+	execute: (toolCallId: string, params: any, signal: any, onUpdate: any) => Promise<unknown>;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	[key: string]: any;
+}
+
+interface EditParams {
+	path?: string;
+	filePath?: string;
+	oldString?: string;
+	old_string?: string;
+	newString?: string;
+	new_string?: string;
+	replaceAll?: boolean;
+	replace_all?: boolean;
+}
+
+interface EditResult {
+	content?: unknown[];
+	[key: string]: unknown;
+}
+
+const NOT_FOUND_PATTERNS = [
+	/old_string not found/i,
+	/oldstring not found/i,
+	/no match/i,
+	/could not find/i,
+	/string not found/i,
+];
+
+function isNotFoundResult(result: unknown): boolean {
+	if (!result || typeof result !== "object") return false;
+	const r = result as EditResult;
+	const text = JSON.stringify(r.content ?? r);
+	return NOT_FOUND_PATTERNS.some((re) => re.test(text));
+}
+
+/** Detect whether pi-diff is loaded (to avoid double-wrapping edit). */
+function isPiDiffLoaded(pi: ExtensionAPI): boolean {
+	try {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const piAny = pi as any;
+		const extensions = piAny?.extensions ?? piAny?._extensions ?? [];
+		const names = Array.isArray(extensions)
+			? extensions.map((e: unknown) => (typeof e === "string" ? e : (e as { name?: string })?.name ?? ""))
+			: Object.keys(extensions);
+		return names.some((n: string) => typeof n === "string" && n.includes("pi-diff"));
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Wrap the native `edit` tool so that on "old_string not found" failures, it
+ * retries using the cascading replace() engine (lenient matching).
+ *
+ * @param pi      the Pi extension API
+ * @param tools   optional injected tool registry (for testing)
+ * @returns true if the wrapper was applied, false if skipped
+ */
+export function wrapEditWithResilientReplace(pi: ExtensionAPI, tools?: { edit: ToolLike }): boolean {
+	// Auto-disable if pi-diff is present (it has its own replace integration).
+	if (isPiDiffLoaded(pi)) {
+		return false;
+	}
+
+	const t = tools ?? ((pi as unknown as { tools?: { edit?: ToolLike } }).tools);
+	if (!t?.edit?.execute) return false;
+
+	const nativeExecute = t.edit.execute.bind(t.edit);
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	t.edit.execute = async function resilientExecute(toolCallId: string, params: any, signal: any, onUpdate: any): Promise<unknown> {
+		try {
+			const result = await nativeExecute(toolCallId, params, signal, onUpdate);
+			if (!isNotFoundResult(result)) return result;
+			// Fall through to resilient retry.
+			return await retryWithReplace(params, toolCallId, signal, onUpdate);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			if (NOT_FOUND_PATTERNS.some((re) => re.test(msg))) {
+				return await retryWithReplace(params, toolCallId, signal, onUpdate);
+			}
+			throw err;
+		}
+	};
+
+	return true;
+
+	async function retryWithReplace(
+		params: EditParams,
+		toolCallId: string,
+		signal: any,
+		onUpdate: any,
+	): Promise<unknown> {
+		const filePath = params.path ?? params.filePath;
+		const oldStr = params.oldString ?? params.old_string;
+		const newStr = params.newString ?? params.new_string;
+		const replaceAll = params.replaceAll ?? params.replace_all ?? false;
+
+		if (!filePath || typeof oldStr !== "string" || typeof newStr !== "string") {
+			// Can't retry — rethrow a not-found style error.
+			throw new Error("old_string not found (and resilient retry skipped: missing path/old/new)");
+		}
+
+		const fs = await import("node:fs/promises");
+		let content: string;
+		try {
+			content = await fs.readFile(filePath, "utf8");
+		} catch (readErr) {
+			throw new Error(
+				`resilient edit: could not read ${filePath}: ${
+					readErr instanceof Error ? readErr.message : String(readErr)
+				}`,
+			);
+		}
+
+		const result: ReplaceResult = replace(content, oldStr, newStr, { replaceAll });
+		if (!result.changed) {
+			throw new Error(
+				`old_string not found (resilient cascade exhausted, strategy=${result.strategy})`,
+			);
+		}
+
+		await fs.writeFile(filePath, result.content, "utf8");
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Edited ${filePath} via resilient cascade (strategy: ${result.strategy}).`,
+				},
+			],
+			_replaceStrategy: result.strategy,
+		};
+	}
+}

package/src/runtime/single-agent-compose.ts

@@ -0,0 +1,87 @@
+/**
+ * single-agent-compose.ts — Cliff hedge v0 (roadmap Phase 0 / T0.5).
+ *
+ * PURPOSE (Round 6 §5, Round 7 Pillar 3 "Cliff-Resilient Value"):
+ * If by ~2027 single models with 1M+ tokens outperform multi-agent teams for
+ * most coding tasks, pi-crew must still deliver value. This module composes a
+ * workflow into ONE sequential prompt that a single agent can execute — proving
+ * pi-crew's mission (reliable orchestration) survives even if the multi-agent
+ * MECHANISM is obsoleted.
+ *
+ * This is the CHEAP v0 (prompt composition only, ~100 LOC). The full
+ * single-agent runtime mode is Phase 2 (T2.2).
+ *
+ * What survives the cliff (cliff-resilient value):
+ *   - Workflow-as-data (the Markdown workflow definitions)
+ *   - Sequential phase structure + dependencies
+ *   - Artifact naming + output contracts
+ *   - The agent just executes phases in order instead of N agents in parallel.
+ */
+import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
+
+export interface SingleAgentPrompt {
+	prompt: string;
+	stepCount: number;
+}
+
+/** Topologically order steps by dependsOn (stable for already-ordered input). */
+function orderSteps(steps: WorkflowStep[]): WorkflowStep[] {
+	const byId = new Map(steps.map((s) => [s.id, s]));
+	const ordered: WorkflowStep[] = [];
+	const seen = new Set<string>();
+	const visit = (step: WorkflowStep): void => {
+		if (seen.has(step.id)) return;
+		if (step.dependsOn) {
+			for (const dep of step.dependsOn) {
+				const d = byId.get(dep);
+				if (d) visit(d);
+			}
+		}
+		seen.add(step.id);
+		ordered.push(step);
+	};
+	for (const s of steps) visit(s);
+	return ordered;
+}
+
+/**
+ * Compose a workflow into a single sequential execution prompt.
+ * The agent executes each phase in dependency order, writing outputs to the
+ * named artifacts, mimicking what the multi-agent team would produce.
+ */
+export function composeSingleAgentPrompt(
+	workflow: WorkflowConfig,
+	goal: string,
+): SingleAgentPrompt {
+	const ordered = orderSteps(workflow.steps);
+	const lines: string[] = [];
+	lines.push(`# Single-agent workflow execution: ${workflow.name}`);
+	lines.push(`Workflow: ${workflow.name} — ${workflow.description}`);
+	lines.push("");
+	lines.push(`## Goal`);
+	lines.push(goal);
+	lines.push("");
+	lines.push("## Execution plan");
+	lines.push(
+		"Execute the following phases in order. Each phase has a role, a task, and an optional output artifact.",
+		"Complete each phase fully before moving to the next. After all phases, summarize results.",
+	);
+	lines.push("");
+	ordered.forEach((step, i) => {
+		const deps = step.dependsOn?.length ? ` (after: ${step.dependsOn.join(", ")})` : "";
+		lines.push(`### Phase ${i + 1}: ${step.id}${deps}`);
+		lines.push(`Role: ${step.role}`);
+		lines.push(`Task: ${step.task}`);
+		if (step.output) {
+			lines.push(`Output: write your result to \`${step.output}\``);
+		}
+		if (step.reads && step.reads.length) {
+			lines.push(`Read first: ${step.reads.join(", ")}`);
+		}
+		lines.push("");
+	});
+	lines.push("## After all phases");
+	lines.push("Write a brief summary of what you accomplished, referencing each output artifact.");
+	const prompt = lines.join("\n");
+	return { prompt, stepCount: ordered.length };
+}

package/src/runtime/task-runner/prompt-builder.ts

@@ -5,6 +5,7 @@ import { buildMemoryBlock } from "../agent-memory.ts";
 import { permissionForRole } from "../role-permission.ts";
 import { renderTaskPacket, HANDOFF_TEMPLATE } from "../task-packet.ts";
 import { buildWorkspaceTree } from "../workspace-tree.ts";
+import { buildKnowledgeFragment } from "../../extension/knowledge-injection.ts";
 
 /**
  * When loadMode is "lean", emit a tool guidance block that tells the worker
@@ -114,6 +115,11 @@ export async function renderTaskPrompt(manifest: TeamRunManifest, step: Workflow
 		treeBlock,
 		"",
 		toolGuidanceBlock(agent),
+		"",
+		// O4: project knowledge (.crew/knowledge.md) — workers don't load the
+		// pi-crew extension (spawned with --no-extensions), so before_agent_start
+		// never fires for them. Inject here so every worker sees project knowledge.
+		buildKnowledgeFragment(task.cwd),
 	].filter(Boolean).join("\n");
 
 	// Dynamic suffix: goal, step, skills, task packet, dependency context, memory — changes per task

package/src/runtime/team-runner.ts

@@ -342,8 +342,11 @@ function failedTaskFrom(result: { tasks: TeamTaskState[] }, taskId: string): Tea
 	return result.tasks.find((item) => item.id === taskId && item.status === "failed");
 }
 
-function requiresPlanApproval(workflow: WorkflowConfig, runtimeConfig: CrewRuntimeConfig | undefined): boolean {
-	return workflow.name === "implementation" && runtimeConfig?.requirePlanApproval === true;
+function requiresPlanApproval(_workflow: WorkflowConfig, runtimeConfig: CrewRuntimeConfig | undefined): boolean {
+	// ROADMAP T1.2: plan-level HITL applies to ANY workflow when
+	// config.runtime.requirePlanApproval === true (not just 'implementation').
+	// The gate fires at the read-only → mutating (plan → execute) boundary.
+	return runtimeConfig?.requirePlanApproval === true;
 }
 
 function isPlanApprovalPending(manifest: TeamRunManifest): boolean {
@@ -357,6 +360,9 @@ function isMutatingTask(task: TeamTaskState): boolean {
 function ensurePlanApprovalRequested(manifest: TeamRunManifest, tasks: TeamTaskState[]): TeamRunManifest {
 	if (manifest.planApproval) return manifest;
 	const assessTask = tasks.find((task) => task.stepId === "assess" && task.status === "completed");
+	// ROADMAP T1.2: for non-adaptive workflows, fall back to the most recent
+	// completed read-only (planning) task as the plan reference.
+	const planTask = assessTask ?? [...tasks].reverse().find((t) => t.status === "completed" && !isMutatingTask(t));
 	const now = new Date().toISOString();
 	const updated: TeamRunManifest = {
 		...manifest,
@@ -366,12 +372,12 @@ function ensurePlanApprovalRequested(manifest: TeamRunManifest, tasks: TeamTaskS
 			status: "pending",
 			requestedAt: now,
 			updatedAt: now,
-			planTaskId: assessTask?.id,
-			planArtifactPath: assessTask?.resultArtifact?.path,
+			planTaskId: planTask?.id,
+			planArtifactPath: planTask?.resultArtifact?.path,
 		},
 	};
 	saveRunManifest(updated);
-	appendEvent(updated.eventsPath, { type: "plan.approval_required", runId: updated.runId, taskId: assessTask?.id, message: "Adaptive implementation plan requires explicit approval before mutating tasks run.", data: { planArtifactPath: assessTask?.resultArtifact?.path } });
+	appendEvent(updated.eventsPath, { type: "plan.approval_required", runId: updated.runId, taskId: planTask?.id, message: "Plan requires explicit approval before mutating tasks run. Use: team api op=approve-plan runId=...", data: { planArtifactPath: planTask?.resultArtifact?.path } });
 	return updated;
 }
 
@@ -383,6 +389,17 @@ function hasPendingMutatingAdaptiveTask(tasks: TeamTaskState[]): boolean {
 	return tasks.some((task) => task.status === "queued" && task.adaptive && isMutatingTask(task));
 }
 
+/**
+ * ROADMAP T1.2: gate detection for ANY workflow (not just adaptive).
+ * Fires when there are pending mutating tasks whose prerequisites (read-only
+ * tasks) have completed — i.e. the plan→execute boundary.
+ */
+export function hasPendingMutatingTaskAtBoundary(tasks: TeamTaskState[]): boolean {
+	const hasCompletedReadOnly = tasks.some((t) => t.status === "completed" && !isMutatingTask(t));
+	const hasPendingMutating = tasks.some((t) => t.status === "queued" && isMutatingTask(t));
+	return hasCompletedReadOnly && hasPendingMutating;
+}
+
 /**
  * Check whether any task uses explicit `dependsOn` that would benefit from DAG-based
  * execution planning. If so, build an execution plan and use `getDagReadyTasks`
@@ -516,7 +533,7 @@ async function executeTeamRunCore(
 	if (initialAdaptive.injected) {
 		manifest = requiresPlanApproval(workflow, input.runtimeConfig) ? ensurePlanApprovalRequested(manifest, tasks) : manifest;
 		queueIndex = buildTaskGraphIndex(tasks);
-	} else if (requiresPlanApproval(workflow, input.runtimeConfig) && hasPendingMutatingAdaptiveTask(tasks)) {
+	} else if (requiresPlanApproval(workflow, input.runtimeConfig) && (hasPendingMutatingAdaptiveTask(tasks) || hasPendingMutatingTaskAtBoundary(tasks))) {
 		manifest = ensurePlanApprovalRequested(manifest, tasks);
 	}
 	if (manifest.planApproval?.status === "cancelled") {
@@ -815,7 +832,7 @@ tasks = mergeResult.resultTasks;
 		if (injectedAfterBatch.injected) {
 			manifest = requiresPlanApproval(workflow, input.runtimeConfig) ? ensurePlanApprovalRequested(manifest, tasks) : manifest;
 			queueIndex = buildTaskGraphIndex(tasks);
-		} else if (requiresPlanApproval(workflow, input.runtimeConfig) && hasPendingMutatingAdaptiveTask(tasks)) {
+		} else if (requiresPlanApproval(workflow, input.runtimeConfig) && (hasPendingMutatingAdaptiveTask(tasks) || hasPendingMutatingTaskAtBoundary(tasks))) {
 			manifest = ensurePlanApprovalRequested(manifest, tasks);
 		}
 		if (manifest.planApproval?.status === "cancelled") {

package/src/schema/team-tool-schema.ts

@@ -113,6 +113,11 @@ export const TeamToolParams = Type.Object({
 			description: "Concrete task text for direct role/agent execution.",
 		}),
 	),
+	singleAgent: Type.Optional(
+		Type.Boolean({
+			description: "When true (with action=plan), compose a single-agent sequential prompt for the workflow instead of a multi-agent plan. Cliff-resilient mode.",
+		}),
+	),
 	runId: Type.Optional(
 		Type.String({
 			description: "Run ID for status, cancel, or resume.",
@@ -308,6 +313,7 @@ export interface TeamToolParamsValue {
 	agent?: string;
 	goal?: string;
 	task?: string;
+	singleAgent?: boolean;
 	runId?: string;
 	taskId?: string;
 	message?: string;

package/src/state/usage.ts

@@ -47,3 +47,76 @@ export function formatUsage(usage: UsageState | undefined): string {
 	if (usage.turns !== undefined) parts.push(`turns=${usage.turns}`);
 	return parts.join(", ") || "(none)";
 }
+
+/** Human-readable compact token count (12345 -> "12.3k"). */
+export function formatTokens(n: number): string {
+	if (n < 1000) return `${n}`;
+	if (n < 1_000_000) return n < 10_000 ? `${(n / 1000).toFixed(1)}k` : `${Math.round(n / 1000)}k`;
+	return `${(n / 1_000_000).toFixed(2)}M`;
+}
+
+/** Human-readable cost ($0.001234 -> "$0.001234", $1.5 -> "$1.50"). */
+export function formatCost(cost: number | undefined): string {
+	if (cost === undefined || !Number.isFinite(cost)) return "$0.00";
+	if (cost === 0) return "$0.00";
+	if (cost < 0.01) return `$${cost.toFixed(6)}`;
+	return `$${cost.toFixed(cost < 1 ? 4 : 2)}`;
+}
+
+export interface RoleUsage {
+	role: string;
+	input: number;
+	output: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+	taskCount: number;
+}
+
+/** Aggregate usage per-role (and per-task) for cost attribution. */
+export function aggregateUsageByRole(tasks: TeamTaskState[]): RoleUsage[] {
+	const byRole = new Map<string, RoleUsage>();
+	for (const task of tasks) {
+		const role = task.role || "unknown";
+		let bucket = byRole.get(role);
+		if (!bucket) {
+			bucket = { role, input: 0, output: 0, cacheWrite: 0, cost: 0, turns: 0, taskCount: 0 };
+			byRole.set(role, bucket);
+		}
+		bucket.taskCount++;
+		if (!task.usage) continue;
+		bucket.input += task.usage.input ?? 0;
+		bucket.output += task.usage.output ?? 0;
+		bucket.cacheWrite += task.usage.cacheWrite ?? 0;
+		bucket.cost += task.usage.cost ?? 0;
+		bucket.turns += task.usage.turns ?? 0;
+	}
+	return [...byRole.values()].sort((a, b) => b.cost - a.cost);
+}
+
+/**
+ * Build a multi-line cost report with per-role attribution.
+ * Used by the `summary` action for cost visibility (roadmap T1.1).
+ */
+export function formatCostReport(tasks: TeamTaskState[]): string {
+	const usage = aggregateUsage(tasks);
+	if (!usage) return "Cost: (no usage data recorded)";
+	const byRole = aggregateUsageByRole(tasks);
+	const totalTokens = (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheWrite ?? 0);
+	const lines: string[] = [];
+	lines.push("═══ Cost Report ═══");
+	lines.push(`Tokens: ${formatTokens(totalTokens)} (in ${formatTokens(usage.input ?? 0)}, out ${formatTokens(usage.output ?? 0)}, cache-write ${formatTokens(usage.cacheWrite ?? 0)})`);
+	lines.push(`Cost: ${formatCost(usage.cost)}${usage.turns ? ` across ${usage.turns} turn(s)` : ""}`);
+	if (byRole.length > 1) {
+		lines.push("");
+		lines.push("By role:");
+		for (const r of byRole) {
+			const pct = usage.cost && usage.cost > 0 ? Math.round((r.cost / usage.cost) * 100) : 0;
+			const tok = r.input + r.output + r.cacheWrite;
+			lines.push(`  ${r.role} (${r.taskCount} task${r.taskCount === 1 ? "" : "s"}): ${formatCost(r.cost)}${pct ? ` — ${pct}%` : ""}, ${formatTokens(tok)} tok, ${r.turns} turns`);
+		}
+	}
+	lines.push("");
+	lines.push("Track budget via budgetTotal/budgetWarning/budgetAbort on team run.");
+	return lines.join("\n");
+}

package/src/ui/card-colors.ts

@@ -0,0 +1,126 @@
+/**
+ * Color utilities for pi-crew UI — background tinting and ANSI parsing.
+ *
+ * Ported from pi-diff's mixBg() / autoDeriveBgFromTheme() technique:
+ * derive subtle status-tinted backgrounds from the theme's foreground colors
+ * so crew cards stay readable across light/dark themes without hardcoding RGB.
+ *
+ * mixBg(base, accent, intensity) does a LINEAR interpolation:
+ *   result = base + (accent - base) * intensity
+ *
+ * Intensity tiers (per pi-diff research):
+ *   10-12% — subtle gutter/hint
+ *   15-18% — line background (visible but not loud)
+ *   30-35% — word-level emphasis (prominent)
+ */
+import type { CrewTheme } from "./theme-adapter.ts";
+
+// ── ANSI parsing ────────────────────────────────────────────────────────
+
+interface Rgb { r: number; g: number; b: number; }
+
+const ANSI_RGB_FG_RE = /^\x1b?\[?38;2;(\d+);(\d+);(\d+)m?$/;
+const ANSI_RGB_BG_RE = /^\x1b?\[?48;2;(\d+);(\d+);(\d+)m?$/;
+
+/** Parse a truecolor ANSI SGR sequence (e.g. "\x1b[38;2;255;100;50m") to RGB. */
+export function parseAnsiRgb(ansi: string | undefined | null): Rgb | null {
+	if (!ansi) return null;
+	const stripped = ansi.replace(/^\x1b?\[?/, "").replace(/m?$/, "");
+	const fgMatch = stripped.match(/^38;2;(\d+);(\d+);(\d+)$/);
+	const bgMatch = stripped.match(/^48;2;(\d+);(\d+);(\d+)$/);
+	const m = fgMatch ?? bgMatch;
+	if (!m) return null;
+	const r = Number(m[1]);
+	const g = Number(m[2]);
+	const b = Number(m[3]);
+	if (![r, g, b].every(Number.isFinite)) return null;
+	return { r, g, b };
+}
+
+// ── Color mixing ────────────────────────────────────────────────────────
+
+/** Linear-interpolate two RGB colors and emit a 48;2 (truecolor bg) SGR code. */
+export function mixBg(base: Rgb, accent: Rgb, intensity: number): string {
+	const r = Math.round(base.r + (accent.r - base.r) * intensity);
+	const g = Math.round(base.g + (accent.g - base.g) * intensity);
+	const b = Math.round(base.b + (accent.b - base.b) * intensity);
+	return `\x1b[48;2;${r};${g};${b}m`;
+}
+
+const BLACK: Rgb = { r: 0, g: 0, b: 0 };
+
+// ── Theme → background derivation ───────────────────────────────────────
+
+/**
+ * Resolve a subtle status-tinted background for a crew card interior.
+ *
+ * Reads the theme's fg color for the given status slot (success/error/border),
+ * mixes it into a dark base at low intensity (default 8%), and returns a bg SGR
+ * sequence. Returns "" if the theme exposes no fg ANSI (graceful — caller
+ * renders without background).
+ *
+ * @param theme       pi-crew theme adapter
+ * @param statusSlot  which status color to tint with ("success" | "error" | "borderAccent" | "border")
+ * @param intensity   0-1, how strong the tint is (default 0.08 = very subtle)
+ */
+export function deriveCardBackground(
+	theme: CrewTheme,
+	statusSlot: "success" | "error" | "borderAccent" | "border",
+	intensity = 0.08,
+): string {
+	// Prefer the theme's bg color as base (matches the card's surroundings).
+	let base = BLACK;
+	const themeAny = theme as unknown as {
+		getBgAnsi?: (slot: string) => string | undefined;
+		getFgAnsi?: (slot: string) => string | undefined;
+	};
+	if (themeAny.getBgAnsi) {
+		try {
+			const bg = themeAny.getBgAnsi("background");
+			const parsed = parseAnsiRgb(bg);
+			if (parsed) base = parsed;
+		} catch { /* fall back to black */ }
+	}
+
+	// Get the accent from the theme's fg for the requested slot.
+	let accentRgb: Rgb | null = null;
+	if (themeAny.getFgAnsi) {
+		try {
+			accentRgb = parseAnsiRgb(themeAny.getFgAnsi(statusSlot));
+		} catch { /* accent stays null */ }
+	}
+	if (!accentRgb) return ""; // can't derive — render without bg tint
+
+	return mixBg(base, accentRgb, intensity);
+}
+
+// ── Helpers for padding lines with a background ─────────────────────────
+
+const ANSI_SGR_RE = /\x1b\[[0-9;]*m/g;
+const RESET = "\x1b[0m";
+
+/** Strip ANSI SGR codes to get visible character count. */
+export function visibleWidth(text: string): number {
+	return text.replace(ANSI_SGR_RE, "").length;
+}
+
+/**
+ * Pad a line to `targetWidth` and apply `bgAnsi` as the background for the
+ * full visible width (including any trailing padding spaces).
+ *
+ * `bgAnsi` should be a 48;2 (truecolor bg) SGR sequence from mixBg().
+ * The function inserts the bg code after any existing leading SGR, fills the
+ * content, pads to width, then resets. This ensures the entire row's background
+ * is tinted — not just the characters.
+ */
+export function padWithBackground(line: string, targetWidth: number, bgAnsi: string): string {
+	if (!bgAnsi) {
+		// No background — just space-pad (preserving any existing styling).
+		const width = visibleWidth(line);
+		return width >= targetWidth ? line : line + " ".repeat(targetWidth - width);
+	}
+	const width = visibleWidth(line);
+	const pad = width >= targetWidth ? "" : " ".repeat(targetWidth - width);
+	// Re-apply bg after a leading reset if present, otherwise prepend.
+	return `${bgAnsi}${line}${pad}${RESET}`;
+}

package/src/ui/deploy-bundled-themes.ts

@@ -0,0 +1,71 @@
+/**
+ * Deploy pi-crew's bundled themes to ~/.pi/agent/themes/ so Pi's theme
+ * loader discovers them (Pi scans that directory for custom themes).
+ *
+ * Best-effort and idempotent: compares content to avoid unnecessary writes,
+ * logs errors but never crashes registration.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { packageRoot, userPiRoot } from "../utils/paths.ts";
+
+/** Directory containing pi-crew's bundled theme JSON files. */
+function bundledThemesDir(): string {
+	return path.join(packageRoot(), "themes");
+}
+
+/** Target directory: ~/.pi/agent/themes/ (where Pi loads custom themes from). */
+function customThemesDir(): string {
+	return path.join(userPiRoot(), "themes");
+}
+
+function readIfExists(filePath: string): string | undefined {
+	try {
+		return fs.readFileSync(filePath, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Copy bundled themes to ~/.pi/agent/themes/, skipping files whose content
+ * already matches (idempotent). Returns the number of themes deployed/updated.
+ *
+ * Safe to call on every registration. Never throws.
+ */
+export function deployBundledThemes(): number {
+	try {
+		const srcDir = bundledThemesDir();
+		const dstDir = customThemesDir();
+
+		if (!fs.existsSync(srcDir)) return 0;
+
+		const files = (fs.readdirSync(srcDir) as string[]).filter((f) => f.endsWith(".json"));
+		if (files.length === 0) return 0;
+
+		// Ensure target directory exists
+		fs.mkdirSync(dstDir, { recursive: true });
+
+		let deployed = 0;
+		for (const file of files) {
+			const srcPath = path.join(srcDir, file);
+			const dstPath = path.join(dstDir, file);
+			const srcContent = fs.readFileSync(srcPath, "utf8");
+			const dstContent = readIfExists(dstPath);
+
+			// Skip if content matches exactly (idempotent — no churn)
+			if (dstContent !== undefined && dstContent === srcContent) continue;
+
+			try {
+				fs.writeFileSync(dstPath, srcContent, "utf8");
+				deployed++;
+			} catch {
+				// Individual file write failure — skip but continue
+			}
+		}
+
+		return deployed;
+	} catch {
+		return 0;
+	}
+}