pi-crew 0.1.45 → 0.1.46

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: systematic-debugging
+description: Use when encountering a bug, test failure, blocked run, provider error, stale state, crash, or unexpected behavior before proposing fixes.
+---
+
+# systematic-debugging
+
+Core principle: no fixes without root-cause investigation first. Symptom patches create new bugs and hide the real failure.
+
+Distilled from detailed reads of systematic-debugging, root-cause tracing, TDD, and error-analysis skill patterns.
+
+## Four Phases
+
+### 1. Root Cause Investigation
+
+Before any fix:
+
+- read error messages, stack traces, failing assertions, task status, and logs completely;
+- reproduce narrowly and record the exact command/steps;
+- check recent diffs, commits, config changes, dependency changes, and environment differences;
+- trace data/control flow across component boundaries;
+- add temporary diagnostics only when they answer a specific question.
+
+For pi-crew, trace:
+
+```text
+user/tool params → config resolution → team/workflow/agent discovery → model/runtime routing → child args/env → state/events/artifacts → status/UI
+```
+
+### 2. Pattern Analysis
+
+- Find a similar working path in the codebase.
+- Compare working vs broken behavior field-by-field.
+- Identify dependencies: config home, project root markers, env vars, locks, stale caches, provider model capabilities.
+- Do not assume small differences are irrelevant.
+
+### 3. Hypothesis and Test
+
+- State one hypothesis: “I think X is the root cause because Y.”
+- Test one variable at a time with the smallest read-only probe or targeted test.
+- If wrong, discard the hypothesis instead of piling on fixes.
+- After three failed fixes, question architecture or assumptions before continuing.
+
+### 4. Implementation
+
+- Add or identify a failing regression test when practical.
+- Fix the root cause, not the symptom.
+- Avoid “while I’m here” refactors.
+- Verify targeted behavior, then broader gates.
+
+## Evidence to Collect
+
+- failing command and exit code;
+- relevant manifest/tasks/events/mailbox files;
+- effective config paths and redacted config;
+- child Pi args/env after redaction;
+- git diff and recent commits;
+- provider/model/thinking resolution;
+- async timing/race indicators.
+
+## Anti-patterns
+
+- Fixing before reproducing.
+- Assuming real user global config cannot pollute tests.
+- Treating provider errors as only transient network failures.
+- Removing guards because they reveal a blocked state.
+- Editing unrelated layers before checking the hypothesis.

package/skills/ui-render-performance/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: ui-render-performance
+description: Non-blocking Pi TUI render workflow. Use when changing widgets, powerbar/statusbar segments, dashboard panes, overlays, snapshot caches, or live UI refresh behavior.
+---
+
+# ui-render-performance
+
+Use this skill for Pi/pi-crew TUI work.
+
+## Source patterns distilled
+
+- Pi TUI is synchronous immediate-mode/string rendering: `source/pi-mono/packages/coding-agent/src/modes/interactive/interactive-mode.ts`
+- Pi extension examples use event-driven state updates, not render-time loading.
+- pi-crew UI: `src/extension/register.ts`, `src/ui/run-dashboard.ts`, `src/ui/run-snapshot-cache.ts`, `src/ui/crew-widget.ts`, `src/ui/powerbar-publisher.ts`, `src/ui/render-scheduler.ts`
+
+## Rules
+
+- Treat every `render(width)` and widget/powerbar update as a hot synchronous path.
+- Render from in-memory snapshots only. Preload config, manifests, snapshots, agents, and mailbox counts asynchronously.
+- Use `RenderScheduler.schedule()` to coalesce renders; avoid direct repeated rendering.
+- Prefer `snapshotCache.get(runId)` in render paths. If a sync fallback is unavoidable, classify it as first-load/rare and document why.
+- Keep dashboard panes pure: accept a snapshot/model and format strings; do not call `fs.readFileSync`, `fs.readdirSync`, `fs.statSync`, or network APIs from pane render methods.
+- On session switch, cancel timers and ensure in-flight async preloads cannot update stale session UI.
+- Watch TTL interactions: a preload interval shorter than cache TTL prevents render-time refresh gaps.
+
+## Anti-patterns
+
+- Do not call `loadConfig()`, `manifestCache.list()`, or `refreshIfStale()` repeatedly inside `renderTick()` unless backed by preloaded frame data.
+- Do not do large JSON parsing or directory scans inside widget render/update functions.
+- Do not show stale health warnings for completed/cancelled/failed runs.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/run-snapshot-cache.test.ts test/unit/crew-widget.test.ts test/unit/powerbar-publisher.test.ts test/unit/run-dashboard.test.ts
+npm test
+```

package/skills/verification-before-done/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: verification-before-done
+description: Use when about to claim work is complete, fixed, passing, reviewed, committed, or ready to hand off.
+---
+
+# verification-before-done
+
+Core principle: evidence before claims. A worker report, green-looking log, or previous run is not fresh verification.
+
+Distilled from detailed reads of agent-skill patterns for verification-before-completion, TDD, review reception, and QA workflows.
+
+## Gate Function
+
+Before any completion claim:
+
+1. Identify the command or inspection that proves the claim.
+2. Run the full command fresh, or explicitly state why a command cannot be run.
+3. Read the output, including exit code and failure counts.
+4. Compare the output to the claim.
+5. Report the claim only with the evidence.
+
+## Claim-to-Evidence Table
+
+| Claim | Requires | Not sufficient |
+|---|---|---|
+| Tests pass | Fresh test output with zero failures | Prior run, “should pass” |
+| Typecheck passes | Typecheck command exit 0 | Lint or targeted tests only |
+| Bug fixed | Original symptom/regression test passes | Code changed |
+| Requirements met | Checklist against request/plan | Generic test success |
+| Agent completed | Worker output plus artifact/diff/state inspection | Worker says DONE |
+| Safe to commit | Relevant checks pass and status reviewed | Partial local confidence |
+
+## Verification Ladder
+
+Choose the smallest reliable gate, then escalate when risk requires it:
+
+1. Read-only inspection for plans/reviews.
+2. Targeted unit test for touched behavior.
+3. Typecheck for TypeScript/schema/API changes.
+4. Integration test for runtime, subprocess, state, filesystem, UI, config, or session behavior.
+5. Full suite before commit/release or broad changes.
+6. Real Pi smoke only when safe and needed.
+
+## Done Report
+
+Include:
+
+- changed files or read-only status;
+- commands run and pass/fail result;
+- artifacts, run IDs, logs, or state paths inspected;
+- behavior actually verified;
+- skipped checks and why;
+- risks and rollback notes.
+
+## Red Flags
+
+Stop before saying done if you are using words like “should”, “probably”, “looks”, “seems”, “I think”, or if you are trusting an agent report without checking evidence.

package/skills/worktree-isolation/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: worktree-isolation
+description: Conflict-safe git worktree workflow. Use when running parallel implementation workers, isolating risky edits, or cleaning up task worktrees.
+---
+
+# worktree-isolation
+
+Use this skill for worktree-based execution or cleanup.
+
+## Source patterns distilled
+
+- pi-subagents worktree runner and cleanup patterns
+- pi-crew worktrees: `src/worktree/worktree-manager.ts`, `src/worktree/cleanup.ts`, `src/worktree/branch-freshness.ts`
+- Team runner workspace mode: `src/runtime/team-runner.ts`, workflow/team resource fields
+
+## Rules
+
+- Use worktree mode for parallel or risky code-changing tasks when the repository is clean enough and merge ownership is clear.
+- Assign one owner per file/symbol/migration path to avoid conflict-heavy merges.
+- Name branches/worktrees deterministically from run/task IDs; avoid user-controlled path fragments without sanitization.
+- Before cleanup, check dirty state. Preserve dirty worktrees unless `force` is explicitly set.
+- Record worktree paths and branch metadata in artifacts/events so the operator can inspect or recover.
+- Do not run destructive git operations without explicit confirmation and evidence of target path containment.
+
+## Anti-patterns
+
+- Parallel editing the same file in multiple worktrees without a merge plan.
+- Force-removing dirty worktrees by default.
+- Reusing stale worktrees after the base branch has moved without freshness checks.
+- Storing worktrees outside the intended contained workspace root.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/integration/worktree-mode.test.ts test/unit/run-index.test.ts
+npm test
+```

package/src/agents/agent-serializer.ts

@@ -1,34 +1,34 @@
-import type { AgentConfig } from "./agent-config.ts";
-
-function line(key: string, value: string | boolean | string[] | undefined): string | undefined {
-	if (value === undefined) return undefined;
-	if (Array.isArray(value)) return `${key}: ${value.join(", ")}`;
-	return `${key}: ${String(value)}`;
-}
-
-export function serializeAgent(agent: AgentConfig): string {
-	const lines = [
-		"---",
-		`name: ${agent.name}`,
-		`description: ${agent.description}`,
-		line("model", agent.model),
-		line("fallbackModels", agent.fallbackModels),
-		line("thinking", agent.thinking),
-		line("tools", agent.tools),
-		agent.extensions !== undefined ? line("extensions", agent.extensions) ?? "extensions:" : undefined,
-		line("skills", agent.skills),
-		line("systemPromptMode", agent.systemPromptMode),
-		line("inheritProjectContext", agent.inheritProjectContext),
-		line("inheritSkills", agent.inheritSkills),
-		line("triggers", agent.routing?.triggers),
-		line("useWhen", agent.routing?.useWhen),
-		line("avoidWhen", agent.routing?.avoidWhen),
-		line("cost", agent.routing?.cost),
-		line("category", agent.routing?.category),
-		"---",
-		"",
-		agent.systemPrompt.trim(),
-		"",
-	].filter((entry): entry is string => entry !== undefined);
-	return lines.join("\n");
-}
+import type { AgentConfig } from "./agent-config.ts";
+
+function line(key: string, value: string | boolean | string[] | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	if (Array.isArray(value)) return `${key}: ${value.join(", ")}`;
+	return `${key}: ${String(value)}`;
+}
+
+export function serializeAgent(agent: AgentConfig): string {
+	const lines = [
+		"---",
+		`name: ${agent.name}`,
+		`description: ${agent.description}`,
+		line("model", agent.model),
+		line("fallbackModels", agent.fallbackModels),
+		line("thinking", agent.thinking),
+		line("tools", agent.tools),
+		agent.extensions !== undefined ? line("extensions", agent.extensions) ?? "extensions:" : undefined,
+		line("skills", agent.skills),
+		line("systemPromptMode", agent.systemPromptMode),
+		line("inheritProjectContext", agent.inheritProjectContext),
+		line("inheritSkills", agent.inheritSkills),
+		line("triggers", agent.routing?.triggers),
+		line("useWhen", agent.routing?.useWhen),
+		line("avoidWhen", agent.routing?.avoidWhen),
+		line("cost", agent.routing?.cost),
+		line("category", agent.routing?.category),
+		"---",
+		"",
+		agent.systemPrompt.trim(),
+		"",
+	].filter((entry): entry is string => entry !== undefined);
+	return lines.join("\n");
+}

package/src/agents/discover-agents.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentConfig, ResourceSource } from "./agent-config.ts";
-import { loadConfig } from "../config/config.ts";
+import { loadConfig, type LoadedPiTeamsConfig } from "../config/config.ts";
 import { parseCsv, parseFrontmatter } from "../utils/frontmatter.ts";
 import { packageRoot, projectCrewRoot, userPiRoot } from "../utils/paths.ts";
 
@@ -36,9 +36,9 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 			source,
 			filePath,
 			systemPrompt: body.trim(),
-			model: frontmatter.model || undefined,
+			model: frontmatter.model === "false" ? undefined : frontmatter.model || undefined,
 			fallbackModels: parseCsv(frontmatter.fallbackModels),
-			thinking: frontmatter.thinking || undefined,
+			thinking: frontmatter.thinking === "false" ? undefined : frontmatter.thinking || undefined,
 			tools: parseCsv(frontmatter.tools),
 			extensions: frontmatter.extensions === "" ? [] : parseCsv(frontmatter.extensions),
 			skills: parseCsv(frontmatter.skills ?? frontmatter.skill),
@@ -63,12 +63,12 @@ function readAgentDir(dir: string, source: ResourceSource): AgentConfig[] {
 		.sort((a, b) => a.name.localeCompare(b.name));
 }
 
-function applyAgentOverrides(agents: AgentConfig[], cwd: string): AgentConfig[] {
-	const loaded = loadConfig(cwd);
-	const config = loaded.config.agents;
-	const overrides = config?.overrides ?? {};
+function applyAgentOverrides(agents: AgentConfig[], cwd: string, loadedConfig?: LoadedPiTeamsConfig): AgentConfig[] {
+	const loaded = loadedConfig ?? loadConfig(cwd);
+	const agentsConfig = loaded.config.agents;
+	const overrides = agentsConfig?.overrides ?? {};
 	return agents
-		.filter((agent) => !(config?.disableBuiltins && agent.source === "builtin"))
+		.filter((agent) => !(agentsConfig?.disableBuiltins && agent.source === "builtin"))
 		.map((agent) => {
 			const overrideEntry = Object.entries(overrides).find(([name]) => name.toLowerCase() === agent.name.toLowerCase());
 			if (!overrideEntry) return agent;
@@ -87,10 +87,11 @@ function applyAgentOverrides(agents: AgentConfig[], cwd: string): AgentConfig[]
 }
 
 export function discoverAgents(cwd: string): AgentDiscoveryResult {
+	const loaded = loadConfig(cwd);
 	return {
-		builtin: applyAgentOverrides(readAgentDir(path.join(packageRoot(), "agents"), "builtin"), cwd),
-		user: applyAgentOverrides(readAgentDir(path.join(userPiRoot(), "agents"), "user"), cwd),
-		project: applyAgentOverrides(readAgentDir(path.join(projectCrewRoot(cwd), "agents"), "project"), cwd),
+		builtin: applyAgentOverrides(readAgentDir(path.join(packageRoot(), "agents"), "builtin"), cwd, loaded),
+		user: applyAgentOverrides(readAgentDir(path.join(userPiRoot(), "agents"), "user"), cwd, loaded),
+		project: applyAgentOverrides(readAgentDir(path.join(projectCrewRoot(cwd), "agents"), "project"), cwd, loaded),
 	};
 }
 

package/src/config/config.ts

@@ -4,7 +4,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { PiTeamsAutonomyProfileSchema, PiTeamsConfigSchema } from "../schema/config-schema.ts";
-import { projectCrewRoot } from "../utils/paths.ts";
+import { projectCrewRoot, projectPiRoot } from "../utils/paths.ts";
 
 export type PiTeamsAutonomyProfile = "manual" | "suggested" | "assisted" | "aggressive";
 
@@ -31,6 +31,7 @@ export interface CrewLimitsConfig {
 export type CrewRuntimeMode = "auto" | "scaffold" | "child-process" | "live-session";
 
 export type CompletionMutationGuardMode = "off" | "warn" | "fail";
+export type EffectivenessGuardMode = "off" | "warn" | "block" | "fail";
 
 export interface CrewRuntimeConfig {
 	mode?: CrewRuntimeMode;
@@ -44,6 +45,7 @@ export interface CrewRuntimeConfig {
 	groupJoinAckTimeoutMs?: number;
 	requirePlanApproval?: boolean;
 	completionMutationGuard?: CompletionMutationGuardMode;
+	effectivenessGuard?: EffectivenessGuardMode;
 }
 
 export interface CrewControlConfig {
@@ -182,6 +184,11 @@ export interface UpdateConfigOptions {
 }
 
 export function configPath(): string {
+	const home = process.env.PI_TEAMS_HOME?.trim() || os.homedir();
+	return path.join(home, ".pi", "agent", "pi-crew.json");
+}
+
+export function legacyConfigPath(): string {
 	const home = process.env.PI_TEAMS_HOME?.trim() || os.homedir();
 	return path.join(home, ".pi", "agent", "extensions", "pi-crew", "config.json");
 }
@@ -195,7 +202,7 @@ export function projectConfigPath(cwd: string): string {
  * This is a convenience path alongside the standard `config.json` in crewRoot.
  */
 export function projectPiCrewJsonPath(cwd: string): string {
-	return path.join(cwd, ".pi", "pi-crew.json");
+	return path.join(projectPiRoot(cwd), "pi-crew.json");
 }
 
 function withoutUndefined<T extends Record<string, unknown>>(value: T): Partial<T> {
@@ -509,6 +516,7 @@ function parseRuntimeConfig(value: unknown): CrewRuntimeConfig | undefined {
 		groupJoinAckTimeoutMs: parsePositiveInteger(obj.groupJoinAckTimeoutMs, 86_400_000),
 		requirePlanApproval: parseWithSchema(Type.Boolean(), obj.requirePlanApproval),
 		completionMutationGuard: parseWithSchema(Type.Union([Type.Literal("off"), Type.Literal("warn"), Type.Literal("fail")]), obj.completionMutationGuard),
+		effectivenessGuard: parseWithSchema(Type.Union([Type.Literal("off"), Type.Literal("warn"), Type.Literal("block"), Type.Literal("fail")]), obj.effectivenessGuard),
 	};
 	return Object.values(runtime).some((entry) => entry !== undefined) ? runtime : undefined;
 }
@@ -727,35 +735,51 @@ function readConfigRecord(filePath: string): Record<string, unknown> {
 	return raw as Record<string, unknown>;
 }
 
+function readOptionalConfig(filePath: string): { exists: boolean; config: PiTeamsConfig; warnings: string[] } {
+	if (!fs.existsSync(filePath)) return { exists: false, config: {}, warnings: [] };
+	try {
+		const raw = readConfigRecord(filePath);
+		const parsed = parseConfigWithWarnings(raw);
+		return { exists: true, config: parsed.config, warnings: parsed.warnings.map((warning) => `${filePath}: ${warning}`) };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { exists: true, config: {}, warnings: [`${filePath}: invalid config ignored: ${message}`] };
+	}
+}
+
 export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 	const filePath = configPath();
+	const legacyPath = legacyConfigPath();
 	const paths = cwd ? [filePath, projectConfigPath(cwd)] : [filePath];
-	try {
-		const userRaw = readConfigRecord(filePath);
-		const userConfig = parseConfigWithWarnings(userRaw);
-		let config = userConfig.config;
-		const warnings: string[] = userConfig.warnings.map((warning) => `${filePath}: ${warning}`);
-		if (cwd) {
-			const projectPath = projectConfigPath(cwd);
-			const projectConfig = parseConfigWithWarnings(readConfigRecord(projectPath));
+	const warnings: string[] = [];
+	const legacyConfig = readOptionalConfig(legacyPath);
+	if (legacyConfig.exists && legacyPath !== filePath) {
+		warnings.push(...legacyConfig.warnings);
+		paths.unshift(legacyPath);
+	}
+	const userConfig = readOptionalConfig(filePath);
+	warnings.push(...userConfig.warnings);
+	let config = mergeConfig(legacyConfig.exists && legacyPath !== filePath ? legacyConfig.config : {}, userConfig.config);
+	if (cwd) {
+		const projectPath = projectConfigPath(cwd);
+		const projectConfig = readOptionalConfig(projectPath);
+		if (projectConfig.exists) {
 			const projectSafeConfig = sanitizeProjectConfig(projectPath, config, projectConfig.config);
-			warnings.push(...projectConfig.warnings.map((warning) => `${projectPath}: ${warning}`), ...projectSafeConfig.warnings);
+			warnings.push(...projectConfig.warnings, ...projectSafeConfig.warnings);
 			config = mergeConfig(config, projectSafeConfig.config);
-			// Also load .pi/pi-crew.json from project root if it exists
-			const piCrewJsonPath = projectPiCrewJsonPath(cwd);
-			if (fs.existsSync(piCrewJsonPath)) {
-				const piCrewJsonConfig = parseConfigWithWarnings(readConfigRecord(piCrewJsonPath));
-				const piCrewJsonSafeConfig = sanitizeProjectConfig(piCrewJsonPath, config, piCrewJsonConfig.config);
-				warnings.push(...piCrewJsonConfig.warnings.map((warning) => `${piCrewJsonPath}: ${warning}`), ...piCrewJsonSafeConfig.warnings);
-				config = mergeConfig(config, piCrewJsonSafeConfig.config);
-				paths.push(piCrewJsonPath);
-			}
 		}
-		return { path: filePath, paths, config, warnings: warnings.length > 0 ? warnings : undefined };
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		return { path: filePath, paths, config: {}, error: message };
+		// `.pi/pi-crew.json` is the project-owned override file. If present and valid,
+		// it may override all pi-crew config fields, including agents.overrides.
+		// If missing or invalid, it is ignored and defaults/user config remain effective.
+		const piCrewJsonPath = projectPiCrewJsonPath(cwd);
+		const piCrewJsonConfig = readOptionalConfig(piCrewJsonPath);
+		if (piCrewJsonConfig.exists) {
+			warnings.push(...piCrewJsonConfig.warnings);
+			config = mergeConfig(config, piCrewJsonConfig.config);
+			paths.push(piCrewJsonPath);
+		}
 	}
+	return { path: filePath, paths, config, warnings: warnings.length > 0 ? warnings : undefined };
 }
 
 export function updateConfig(patch: PiTeamsConfig, options: UpdateConfigOptions = {}): SavedPiTeamsConfig {

package/src/config/defaults.ts

@@ -53,6 +53,20 @@ export const DEFAULT_UI = {
 	refreshMs: 1000,
 	notifierIntervalMs: 5000,
 	widgetDefaultFrameMs: 1000,
+	widgetPlacement: "aboveEditor" as const,
+	widgetMaxLines: 8,
+	powerbar: true,
+	dashboardPlacement: "center" as const,
+	dashboardWidth: 72,
+	dashboardLiveRefreshMs: 1000,
+	autoOpenDashboard: false,
+	autoOpenDashboardForForegroundRuns: false,
+	showModel: true,
+	showTokens: true,
+	showTools: true,
+	transcriptTailBytes: 1024 * 1024,
+	mascotStyle: "cat" as const,
+	mascotEffect: "random" as const,
 };
 
 export const DEFAULT_NOTIFICATIONS = {

package/src/extension/cross-extension-rpc.ts

@@ -1,82 +1,82 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";
-import { handleTeamTool } from "./team-tool.ts";
-import { parseLiveControlRealtimeMessage, publishLiveControlRealtime } from "../runtime/live-control-realtime.ts";
-
-export interface EventBusLike {
-	on(event: string, handler: (data: unknown) => void): (() => void) | void;
-	emit(event: string, data: unknown): void;
-}
-
-export type RpcReply<T = unknown> = { success: true; data?: T } | { success: false; error: string };
-export const PI_CREW_RPC_VERSION = 1;
-
-export interface PiCrewRpcHandle {
-	unsubscribe(): void;
-}
-
-function requestId(raw: unknown): string | undefined {
-	return raw && typeof raw === "object" && !Array.isArray(raw) && typeof (raw as { requestId?: unknown }).requestId === "string" ? (raw as { requestId: string }).requestId : undefined;
-}
-
-function reply(events: EventBusLike, channel: string, id: string | undefined, payload: RpcReply): void {
-	if (!id) return;
-	events.emit(`${channel}:reply:${id}`, payload);
-}
-
-function textOf(result: Awaited<ReturnType<typeof handleTeamTool>>): string {
-	return result.content?.map((item) => item.type === "text" ? item.text : "").join("\n") ?? "";
-}
-
-function on(events: EventBusLike, channel: string, handler: (raw: unknown) => void): () => void {
-	const unsub = events.on(channel, handler);
-	return typeof unsub === "function" ? unsub : () => {};
-}
-
-export function registerPiCrewRpc(events: EventBusLike | undefined, getCtx: () => ExtensionContext | undefined): PiCrewRpcHandle | undefined {
-	if (!events) return undefined;
-	const unsubs = [
-		on(events, "pi-crew:rpc:ping", (raw) => reply(events, "pi-crew:rpc:ping", requestId(raw), { success: true, data: { version: PI_CREW_RPC_VERSION } })),
-		on(events, "pi-crew:rpc:run", async (raw) => {
-			const id = requestId(raw);
-			try {
-				const ctx = getCtx();
-				if (!ctx) throw new Error("No active pi-crew session context.");
-				const params: TeamToolParamsValue = raw && typeof raw === "object" && !Array.isArray(raw) ? { ...(raw as object), action: "run" } as TeamToolParamsValue : { action: "run" };
-				const result = await handleTeamTool(params, ctx);
-				reply(events, "pi-crew:rpc:run", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: result.details });
-			} catch (error) {
-				reply(events, "pi-crew:rpc:run", id, { success: false, error: error instanceof Error ? error.message : String(error) });
-			}
-		}),
-		on(events, "pi-crew:rpc:status", async (raw) => {
-			const id = requestId(raw);
-			try {
-				const ctx = getCtx();
-				if (!ctx) throw new Error("No active pi-crew session context.");
-				const runId = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as { runId?: string }).runId : undefined;
-				const result = await handleTeamTool({ action: "status", runId }, ctx);
-				reply(events, "pi-crew:rpc:status", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: { text: textOf(result), details: result.details } });
-			} catch (error) {
-				reply(events, "pi-crew:rpc:status", id, { success: false, error: error instanceof Error ? error.message : String(error) });
-			}
-		}),
-		on(events, "pi-crew:live-control", (raw) => {
-			const request = parseLiveControlRealtimeMessage(raw);
-			if (request) publishLiveControlRealtime(request);
-		}),
-		on(events, "pi-crew:rpc:live-control", async (raw) => {
-			const id = requestId(raw);
-			try {
-				const ctx = getCtx();
-				if (!ctx) throw new Error("No active pi-crew session context.");
-				const obj = raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
-				const result = await handleTeamTool({ action: "api", runId: typeof obj.runId === "string" ? obj.runId : undefined, config: { operation: typeof obj.operation === "string" ? obj.operation : "steer-agent", agentId: obj.agentId, message: obj.message, prompt: obj.prompt } }, ctx);
-				reply(events, "pi-crew:rpc:live-control", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: { text: textOf(result), details: result.details } });
-			} catch (error) {
-				reply(events, "pi-crew:rpc:live-control", id, { success: false, error: error instanceof Error ? error.message : String(error) });
-			}
-		}),
-	];
-	return { unsubscribe: () => unsubs.forEach((unsub) => unsub()) };
-}
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";
+import { handleTeamTool } from "./team-tool.ts";
+import { parseLiveControlRealtimeMessage, publishLiveControlRealtime } from "../runtime/live-control-realtime.ts";
+
+export interface EventBusLike {
+	on(event: string, handler: (data: unknown) => void): (() => void) | void;
+	emit(event: string, data: unknown): void;
+}
+
+export type RpcReply<T = unknown> = { success: true; data?: T } | { success: false; error: string };
+export const PI_CREW_RPC_VERSION = 1;
+
+export interface PiCrewRpcHandle {
+	unsubscribe(): void;
+}
+
+function requestId(raw: unknown): string | undefined {
+	return raw && typeof raw === "object" && !Array.isArray(raw) && typeof (raw as { requestId?: unknown }).requestId === "string" ? (raw as { requestId: string }).requestId : undefined;
+}
+
+function reply(events: EventBusLike, channel: string, id: string | undefined, payload: RpcReply): void {
+	if (!id) return;
+	events.emit(`${channel}:reply:${id}`, payload);
+}
+
+function textOf(result: Awaited<ReturnType<typeof handleTeamTool>>): string {
+	return result.content?.map((item) => item.type === "text" ? item.text : "").join("\n") ?? "";
+}
+
+function on(events: EventBusLike, channel: string, handler: (raw: unknown) => void): () => void {
+	const unsub = events.on(channel, handler);
+	return typeof unsub === "function" ? unsub : () => {};
+}
+
+export function registerPiCrewRpc(events: EventBusLike | undefined, getCtx: () => ExtensionContext | undefined): PiCrewRpcHandle | undefined {
+	if (!events) return undefined;
+	const unsubs = [
+		on(events, "pi-crew:rpc:ping", (raw) => reply(events, "pi-crew:rpc:ping", requestId(raw), { success: true, data: { version: PI_CREW_RPC_VERSION } })),
+		on(events, "pi-crew:rpc:run", async (raw) => {
+			const id = requestId(raw);
+			try {
+				const ctx = getCtx();
+				if (!ctx) throw new Error("No active pi-crew session context.");
+				const params: TeamToolParamsValue = raw && typeof raw === "object" && !Array.isArray(raw) ? { ...(raw as object), action: "run" } as TeamToolParamsValue : { action: "run" };
+				const result = await handleTeamTool(params, ctx);
+				reply(events, "pi-crew:rpc:run", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: result.details });
+			} catch (error) {
+				reply(events, "pi-crew:rpc:run", id, { success: false, error: error instanceof Error ? error.message : String(error) });
+			}
+		}),
+		on(events, "pi-crew:rpc:status", async (raw) => {
+			const id = requestId(raw);
+			try {
+				const ctx = getCtx();
+				if (!ctx) throw new Error("No active pi-crew session context.");
+				const runId = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as { runId?: string }).runId : undefined;
+				const result = await handleTeamTool({ action: "status", runId }, ctx);
+				reply(events, "pi-crew:rpc:status", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: { text: textOf(result), details: result.details } });
+			} catch (error) {
+				reply(events, "pi-crew:rpc:status", id, { success: false, error: error instanceof Error ? error.message : String(error) });
+			}
+		}),
+		on(events, "pi-crew:live-control", (raw) => {
+			const request = parseLiveControlRealtimeMessage(raw);
+			if (request) publishLiveControlRealtime(request);
+		}),
+		on(events, "pi-crew:rpc:live-control", async (raw) => {
+			const id = requestId(raw);
+			try {
+				const ctx = getCtx();
+				if (!ctx) throw new Error("No active pi-crew session context.");
+				const obj = raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
+				const result = await handleTeamTool({ action: "api", runId: typeof obj.runId === "string" ? obj.runId : undefined, config: { operation: typeof obj.operation === "string" ? obj.operation : "steer-agent", agentId: obj.agentId, message: obj.message, prompt: obj.prompt } }, ctx);
+				reply(events, "pi-crew:rpc:live-control", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: { text: textOf(result), details: result.details } });
+			} catch (error) {
+				reply(events, "pi-crew:rpc:live-control", id, { success: false, error: error instanceof Error ? error.message : String(error) });
+			}
+		}),
+	];
+	return { unsubscribe: () => unsubs.forEach((unsub) => unsub()) };
+}