pi-crew 0.1.37 → 0.1.39

package/src/extension/result-watcher.ts

@@ -1,98 +1,98 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "../utils/completion-dedupe.ts";
-import { closeWatcher, watchWithErrorHandler } from "../utils/fs-watch.ts";
-import { createFileCoalescer } from "../utils/file-coalescer.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-
-export interface ResultWatcherEvents {
-	emit(event: string, data: unknown): void;
-}
-
-export interface ResultWatcherHandle {
-	start(): void;
-	prime(): void;
-	stop(): void;
-}
-
-interface ResultWatcherDependencies {
-	watch?: typeof watchWithErrorHandler;
-}
-
-export interface ResultWatcherOptions extends ResultWatcherDependencies {
-	eventName?: string;
-	completionTtlMs?: number;
-}
-
-const RESULT_WATCHER_RESTART_MS = 3000;
-
-function readJson(filePath: string): unknown | undefined {
-	try {
-		return JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
-	} catch (error) {
-		logInternalError("result-watcher.parse", error, `filePath=${filePath}`);
-		return undefined;
-	}
-}
-
-export function createResultWatcher(events: ResultWatcherEvents, resultsDir: string, eventNameOrOptions: string | ResultWatcherOptions = "pi-crew:run-result"): ResultWatcherHandle {
-	const options: ResultWatcherOptions = typeof eventNameOrOptions === "string" ? { eventName: eventNameOrOptions } : eventNameOrOptions;
-	const eventName = options.eventName ?? "pi-crew:run-result";
-	const completionTtlMs = options.completionTtlMs ?? 5 * 60_000;
-	const watch = options.watch ?? watchWithErrorHandler;
-	const seen = getGlobalSeenMap("pi-crew.result-watcher");
-	let watcher: fs.FSWatcher | null | undefined;
-	let restartTimer: ReturnType<typeof setTimeout> | undefined;
-	const coalescer = createFileCoalescer((file) => {
-		const filePath = path.join(resultsDir, file);
-		if (!file.endsWith(".json") || !fs.existsSync(filePath)) return;
-		const payload = readJson(filePath);
-		if (payload !== undefined) {
-			const key = buildCompletionKey(payload as Record<string, unknown>, `file:${file}`);
-			if (!markSeenWithTtl(seen, key, Date.now(), completionTtlMs)) {
-				events.emit(eventName, payload);
-			}
-		}
-		try {
-			fs.unlinkSync(filePath);
-		} catch (error) {
-			logInternalError("result-watcher.unlink", error, `filePath=${filePath}`);
-		}
-	}, 50);
-	const scheduleRestart = () => {
-		if (restartTimer) clearTimeout(restartTimer);
-		restartTimer = setTimeout(() => {
-			restartTimer = undefined;
-			try {
-				fs.mkdirSync(resultsDir, { recursive: true });
-				handle.start();
-			} catch (error) {
-				logInternalError("result-watcher.restart", error, `resultsDir=${resultsDir}`);
-			}
-		}, RESULT_WATCHER_RESTART_MS);
-		restartTimer.unref?.();
-	};
-	const handle: ResultWatcherHandle = {
-		start() {
-			fs.mkdirSync(resultsDir, { recursive: true });
-			if (watcher) closeWatcher(watcher);
-			watcher = watch(resultsDir, (event, fileName) => {
-				if (event !== "rename" || !fileName) return;
-				coalescer.schedule(fileName.toString());
-			}, scheduleRestart);
-			watcher?.unref?.();
-		},
-		prime() {
-			if (!fs.existsSync(resultsDir)) return;
-			for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
-		},
-		stop() {
-			if (restartTimer) clearTimeout(restartTimer);
-			restartTimer = undefined;
-			closeWatcher(watcher);
-			watcher = undefined;
-			coalescer.clear();
-		},
-	};
-	return handle;
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "../utils/completion-dedupe.ts";
+import { closeWatcher, watchWithErrorHandler } from "../utils/fs-watch.ts";
+import { createFileCoalescer } from "../utils/file-coalescer.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface ResultWatcherEvents {
+	emit(event: string, data: unknown): void;
+}
+
+export interface ResultWatcherHandle {
+	start(): void;
+	prime(): void;
+	stop(): void;
+}
+
+interface ResultWatcherDependencies {
+	watch?: typeof watchWithErrorHandler;
+}
+
+export interface ResultWatcherOptions extends ResultWatcherDependencies {
+	eventName?: string;
+	completionTtlMs?: number;
+}
+
+const RESULT_WATCHER_RESTART_MS = 3000;
+
+function readJson(filePath: string): unknown | undefined {
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+	} catch (error) {
+		logInternalError("result-watcher.parse", error, `filePath=${filePath}`);
+		return undefined;
+	}
+}
+
+export function createResultWatcher(events: ResultWatcherEvents, resultsDir: string, eventNameOrOptions: string | ResultWatcherOptions = "pi-crew:run-result"): ResultWatcherHandle {
+	const options: ResultWatcherOptions = typeof eventNameOrOptions === "string" ? { eventName: eventNameOrOptions } : eventNameOrOptions;
+	const eventName = options.eventName ?? "pi-crew:run-result";
+	const completionTtlMs = options.completionTtlMs ?? 5 * 60_000;
+	const watch = options.watch ?? watchWithErrorHandler;
+	const seen = getGlobalSeenMap("pi-crew.result-watcher");
+	let watcher: fs.FSWatcher | null | undefined;
+	let restartTimer: ReturnType<typeof setTimeout> | undefined;
+	const coalescer = createFileCoalescer((file) => {
+		const filePath = path.join(resultsDir, file);
+		if (!file.endsWith(".json") || !fs.existsSync(filePath)) return;
+		const payload = readJson(filePath);
+		if (payload !== undefined) {
+			const key = buildCompletionKey(payload as Record<string, unknown>, `file:${file}`);
+			if (!markSeenWithTtl(seen, key, Date.now(), completionTtlMs)) {
+				events.emit(eventName, payload);
+			}
+		}
+		try {
+			fs.unlinkSync(filePath);
+		} catch (error) {
+			logInternalError("result-watcher.unlink", error, `filePath=${filePath}`);
+		}
+	}, 50);
+	const scheduleRestart = () => {
+		if (restartTimer) clearTimeout(restartTimer);
+		restartTimer = setTimeout(() => {
+			restartTimer = undefined;
+			try {
+				fs.mkdirSync(resultsDir, { recursive: true });
+				handle.start();
+			} catch (error) {
+				logInternalError("result-watcher.restart", error, `resultsDir=${resultsDir}`);
+			}
+		}, RESULT_WATCHER_RESTART_MS);
+		restartTimer.unref?.();
+	};
+	const handle: ResultWatcherHandle = {
+		start() {
+			fs.mkdirSync(resultsDir, { recursive: true });
+			if (watcher) closeWatcher(watcher);
+			watcher = watch(resultsDir, (event, fileName) => {
+				if (event !== "rename" || !fileName) return;
+				coalescer.schedule(fileName.toString());
+			}, scheduleRestart);
+			watcher?.unref?.();
+		},
+		prime() {
+			if (!fs.existsSync(resultsDir)) return;
+			for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
+		},
+		stop() {
+			if (restartTimer) clearTimeout(restartTimer);
+			restartTimer = undefined;
+			closeWatcher(watcher);
+			watcher = undefined;
+			coalescer.clear();
+		},
+	};
+	return handle;
+}

package/src/extension/run-import.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { assertRunBundle } from "./run-bundle-schema.ts";
 import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
 import { DEFAULT_PATHS } from "../config/defaults.ts";
+import { assertSafePathId, resolveContainedRelativePath, resolveRealContainedPath } from "../utils/safe-paths.ts";
 
 export interface ImportedRunBundleInfo {
 	runId: string;
@@ -20,12 +21,21 @@ export function importRunBundle(cwd: string, bundlePath: string, scope: "project
 	const resolvedPath = path.isAbsolute(bundlePath) ? bundlePath : path.resolve(cwd, bundlePath);
 	const raw = JSON.parse(fs.readFileSync(resolvedPath, "utf-8")) as unknown;
 	assertRunBundle(raw);
-	const runId = raw.manifest.runId;
+	const runId = assertSafePathId("runId", raw.manifest.runId);
 	const importedAt = new Date().toISOString();
-	const root = path.join(importRoot(cwd, scope), runId);
+	const importsRoot = importRoot(cwd, scope);
+	fs.mkdirSync(importsRoot, { recursive: true });
+	if (fs.lstatSync(importsRoot).isSymbolicLink()) throw new Error(`Invalid import root: ${importsRoot}`);
+	resolveRealContainedPath(path.dirname(importsRoot), path.basename(importsRoot));
+	const root = resolveContainedRelativePath(importsRoot, runId, "runId");
 	fs.mkdirSync(root, { recursive: true });
+	if (fs.lstatSync(root).isSymbolicLink()) throw new Error(`Invalid import directory: ${root}`);
+	resolveRealContainedPath(importsRoot, runId);
 	const targetJson = path.join(root, "run-export.json");
 	const targetSummary = path.join(root, "README.md");
+	for (const target of [targetJson, targetSummary]) {
+		if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) throw new Error(`Invalid import target: ${target}`);
+	}
 	fs.writeFileSync(targetJson, `${JSON.stringify({ ...raw, importedAt, importedFrom: resolvedPath }, null, 2)}\n`, "utf-8");
 	fs.writeFileSync(targetSummary, [
 		`# Imported pi-crew run ${runId}`,

package/src/extension/run-index.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import type { TeamRunManifest } from "../state/types.ts";
 import { DEFAULT_PATHS } from "../config/defaults.ts";
 import { findRepoRoot, projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
+import { isSafePathId, resolveRealContainedPath } from "../utils/safe-paths.ts";
 
 function readManifest(filePath: string): TeamRunManifest | undefined {
 	try {
@@ -15,10 +16,19 @@ function readManifest(filePath: string): TeamRunManifest | undefined {
 function collectRuns(root: string, maxEntries?: number): TeamRunManifest[] {
 	const runsRoot = path.join(root, DEFAULT_PATHS.state.runsSubdir);
 	if (!fs.existsSync(runsRoot)) return [];
-	const entries = fs.readdirSync(runsRoot).sort((a, b) => b.localeCompare(a));
+	const entries = fs.readdirSync(runsRoot, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory() && isSafePathId(entry.name))
+		.map((entry) => entry.name)
+		.sort((a, b) => b.localeCompare(a));
 	const selected = maxEntries !== undefined ? entries.slice(0, Math.max(0, maxEntries)) : entries;
 	return selected
-		.map((entry) => readManifest(path.join(runsRoot, entry, DEFAULT_PATHS.state.manifestFile)))
+		.map((entry) => {
+			try {
+				return readManifest(path.join(resolveRealContainedPath(runsRoot, entry), DEFAULT_PATHS.state.manifestFile));
+			} catch {
+				return undefined;
+			}
+		})
 		.filter((manifest): manifest is TeamRunManifest => manifest !== undefined);
 }
 

package/src/extension/run-maintenance.ts

@@ -1,24 +1,24 @@
-import * as fs from "node:fs";
-import type { TeamRunManifest } from "../state/types.ts";
-import { listRuns } from "./run-index.ts";
-
-export interface PruneRunsResult {
-	kept: string[];
-	removed: string[];
-}
-
-function isFinished(run: TeamRunManifest): boolean {
-	return run.status === "completed" || run.status === "failed" || run.status === "cancelled" || run.status === "blocked";
-}
-
-export function pruneFinishedRuns(cwd: string, keep: number): PruneRunsResult {
-	const finished = listRuns(cwd).filter((run) => run.cwd === cwd && isFinished(run)).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
-	const kept = finished.slice(0, keep).map((run) => run.runId);
-	const removed: string[] = [];
-	for (const run of finished.slice(keep)) {
-		fs.rmSync(run.stateRoot, { recursive: true, force: true });
-		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
-		removed.push(run.runId);
-	}
-	return { kept, removed };
-}
+import * as fs from "node:fs";
+import type { TeamRunManifest } from "../state/types.ts";
+import { listRuns } from "./run-index.ts";
+
+export interface PruneRunsResult {
+	kept: string[];
+	removed: string[];
+}
+
+function isFinished(run: TeamRunManifest): boolean {
+	return run.status === "completed" || run.status === "failed" || run.status === "cancelled" || run.status === "blocked";
+}
+
+export function pruneFinishedRuns(cwd: string, keep: number): PruneRunsResult {
+	const finished = listRuns(cwd).filter((run) => run.cwd === cwd && isFinished(run)).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+	const kept = finished.slice(0, keep).map((run) => run.runId);
+	const removed: string[] = [];
+	for (const run of finished.slice(keep)) {
+		fs.rmSync(run.stateRoot, { recursive: true, force: true });
+		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
+		removed.push(run.runId);
+	}
+	return { kept, removed };
+}

package/src/extension/team-tool/api.ts

@@ -10,12 +10,13 @@ import { appendEvent, readEvents, readEventsCursor } from "../../state/event-log
 import { resolveCrewRuntime } from "../../runtime/runtime-resolver.ts";
 import { probeLiveSessionRuntime } from "../../subagents/live/session-runtime.ts";
 import { touchWorkerHeartbeat } from "../../runtime/worker-heartbeat.ts";
-import { agentEventsPath, agentOutputPath, readCrewAgentEvents, readCrewAgentEventsCursor, readCrewAgentStatus, readCrewAgents } from "../../runtime/crew-agent-records.ts";
+import { agentOutputPath, readCrewAgentEventsCursor, readCrewAgentStatus, readCrewAgents } from "../../runtime/crew-agent-records.ts";
 import { buildAgentDashboard, readAgentOutput } from "../../runtime/agent-observability.ts";
 import { readForegroundControlStatus, writeForegroundInterruptRequest } from "../../runtime/foreground-control.ts";
-import { listLiveAgents, resumeLiveAgent, steerLiveAgent, stopLiveAgent } from "../../subagents/live/manager.ts";
+import { getLiveAgent, listLiveAgents, resumeLiveAgent, steerLiveAgent, stopLiveAgent } from "../../subagents/live/manager.ts";
 import { appendLiveAgentControlRequest } from "../../subagents/live/control.ts";
 import { liveControlRealtimeMessage, publishLiveControlRealtime } from "../../subagents/live/realtime.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
 
@@ -24,6 +25,26 @@ function globMatch(value: string, pattern: string): boolean {
 	return new RegExp(`^${escaped}$`).test(value);
 }
 
+function safeReadContainedFile(baseDir: string, filePath: string | undefined): string | undefined {
+	if (!filePath) return undefined;
+	let safePath: string;
+	try {
+		safePath = resolveRealContainedPath(baseDir, filePath);
+	} catch {
+		return undefined;
+	}
+	return fs.existsSync(safePath) ? fs.readFileSync(safePath, "utf-8") : undefined;
+}
+
+function safeContainedPath(baseDir: string, filePath: string | undefined): string | undefined {
+	if (!filePath) return undefined;
+	try {
+		return resolveRealContainedPath(baseDir, filePath);
+	} catch {
+		return undefined;
+	}
+}
+
 function snapshotHasRunId(snapshot: { values?: unknown }, runId: string): boolean {
 	const values = Array.isArray(snapshot.values) ? snapshot.values : [];
 	return values.some((value) => {
@@ -85,7 +106,7 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
 		if (!agent) return result("API get-agent-result requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		const task = loaded.tasks.find((item) => item.id === agent.taskId);
-		const text = task?.resultArtifact && fs.existsSync(task.resultArtifact.path) ? fs.readFileSync(task.resultArtifact.path, "utf-8") : JSON.stringify(agent, null, 2);
+		const text = safeReadContainedFile(loaded.manifest.artifactsRoot, task?.resultArtifact?.path) ?? JSON.stringify(agent, null, 2);
 		return result(text, { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
 	if (operation === "read-agent-status") {
@@ -102,9 +123,8 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		if (!agent) return result("API read-agent-events requires config.agentId matching an agent id or task id, or at least one agent in the run.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		const sinceSeq = typeof cfg.sinceSeq === "number" ? cfg.sinceSeq : undefined;
 		const limit = typeof cfg.limit === "number" ? cfg.limit : undefined;
-		const payload = sinceSeq !== undefined || limit !== undefined
-			? readCrewAgentEventsCursor(loaded.manifest, agent.taskId, { sinceSeq, limit })
-			: { path: agentEventsPath(loaded.manifest, agent.taskId), events: readCrewAgentEvents(loaded.manifest, agent.taskId) };
+		const cursorPayload = readCrewAgentEventsCursor(loaded.manifest, agent.taskId, { sinceSeq, limit });
+		const payload = sinceSeq !== undefined || limit !== undefined ? cursorPayload : { path: cursorPayload.path, events: cursorPayload.events };
 		return result(JSON.stringify(payload, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
 	if (operation === "read-agent-transcript") {
@@ -112,8 +132,12 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		const agents = readCrewAgents(loaded.manifest);
 		const agent = agentId ? agents.find((item) => item.id === agentId || item.taskId === agentId) : agents[0];
 		if (!agent) return result("API read-agent-transcript requires config.agentId matching an agent id or task id, or at least one agent in the run.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
-		const transcriptPath = agent.transcriptPath && fs.existsSync(agent.transcriptPath) ? agent.transcriptPath : agentOutputPath(loaded.manifest, agent.taskId);
-		const text = fs.existsSync(transcriptPath) ? fs.readFileSync(transcriptPath, "utf-8") : "";
+		const artifactTranscriptPath = safeContainedPath(loaded.manifest.artifactsRoot, agent.transcriptPath);
+		const fallbackPath = agentOutputPath(loaded.manifest, agent.taskId);
+		const artifactText = artifactTranscriptPath ? safeReadContainedFile(loaded.manifest.artifactsRoot, artifactTranscriptPath) ?? "" : "";
+		const fallbackText = artifactText ? "" : safeReadContainedFile(loaded.manifest.stateRoot, fallbackPath) ?? "";
+		const transcriptPath = artifactText ? artifactTranscriptPath : fallbackPath;
+		const text = artifactText || fallbackText;
 		return result(text || `(no transcript at ${transcriptPath})`, { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
 	if (operation === "read-agent-output") {
@@ -153,6 +177,8 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		const message = typeof cfg.message === "string" && cfg.message.trim() ? cfg.message.trim() : undefined;
 		const prompt = typeof cfg.prompt === "string" && cfg.prompt.trim() ? cfg.prompt.trim() : message;
 		try {
+			const live = getLiveAgent(agentId);
+			if (live && live.runId !== loaded.manifest.runId) return result(`Live agent '${agentId}' does not belong to run ${loaded.manifest.runId}.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 			if (operation === "steer-agent") return result(JSON.stringify(await steerLiveAgent(agentId, message ?? "Please report current status and wrap up if possible."), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 			if (operation === "resume-agent") {
 				if (!prompt) return result("API resume-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
@@ -165,18 +191,31 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 				const err = error instanceof Error ? error.message : String(error);
 				return result(err, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 			}
+			const task = loaded.tasks.find((item) => item.id === agent.taskId);
+			if (!task) return result(`API ${operation} agent '${agentId}' does not match a run task.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 			if (operation === "resume-agent" && !prompt) return result("API resume-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
-			const request = appendLiveAgentControlRequest(loaded.manifest, { taskId: agent.taskId, agentId: agent.id, operation: operation === "resume-agent" ? "resume" : operation === "steer-agent" ? "steer" : "stop", message: operation === "resume-agent" ? prompt : message });
-			publishLiveControlRealtime(request);
-			ctx.events?.emit?.("pi-crew:live-control", liveControlRealtimeMessage(request));
-			appendEvent(loaded.manifest.eventsPath, { type: "agent.control.queued", runId: loaded.manifest.runId, taskId: agent.taskId, message: `Queued ${request.operation} control request for live agent.`, data: { request, realtime: true } });
-			return result(JSON.stringify({ queued: true, request }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			try {
+				const request = appendLiveAgentControlRequest(loaded.manifest, { taskId: task.id, agentId: agent.id, operation: operation === "resume-agent" ? "resume" : operation === "steer-agent" ? "steer" : "stop", message: operation === "resume-agent" ? prompt : message });
+				publishLiveControlRealtime(request);
+				ctx.events?.emit?.("pi-crew:live-control", liveControlRealtimeMessage(request));
+				appendEvent(loaded.manifest.eventsPath, { type: "agent.control.queued", runId: loaded.manifest.runId, taskId: agent.taskId, message: `Queued ${request.operation} control request for live agent.`, data: { request, realtime: true } });
+				return result(JSON.stringify({ queued: true, request }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			} catch (queueError) {
+				const message = queueError instanceof Error ? queueError.message : String(queueError);
+				return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+			}
 		}
 	}
 	if (operation === "read-mailbox") {
 		const direction = cfg.direction === "inbox" || cfg.direction === "outbox" ? cfg.direction as MailboxDirection : undefined;
 		const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
-		return result(JSON.stringify(readMailbox(loaded.manifest, direction, taskId), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+		if (taskId && !loaded.tasks.some((task) => task.id === taskId)) return result(`API read-mailbox taskId '${taskId}' does not match a run task.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		try {
+			return result(JSON.stringify(readMailbox(loaded.manifest, direction, taskId), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		}
 	}
 	if (operation === "validate-mailbox") {
 		const report = validateMailbox(loaded.manifest, { repair: cfg.repair === true });
@@ -192,6 +231,7 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		const body = typeof cfg.body === "string" && cfg.body.trim() ? cfg.body : undefined;
 		const taskId = typeof cfg.taskId === "string" && cfg.taskId.trim() ? cfg.taskId.trim() : undefined;
 		if (!body) return result("API send-message requires config.body.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		if (taskId && !loaded.tasks.some((task) => task.id === taskId)) return result(`API send-message taskId '${taskId}' does not match a run task.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		try {
 			return withRunLockSync(loaded.manifest, () => {
 				const message = appendMailboxMessage(loaded.manifest, { direction, from, to, body, taskId });

package/src/extension/team-tool/cancel.ts

@@ -1,31 +1,31 @@
-import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { withRunLockSync } from "../../state/locks.ts";
-import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/state-store.ts";
-import { saveCrewAgents, recordFromTask } from "../../runtime/crew-agent-records.ts";
-import { writeForegroundInterruptRequest } from "../../runtime/foreground-control.ts";
-import { logInternalError } from "../../utils/internal-error.ts";
-import type { PiTeamsToolResult } from "../tool-result.ts";
-import { result, type TeamContext } from "./context.ts";
-
-export function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
-	if (!params.runId) return result("Cancel requires runId.", { action: "cancel", status: "error" }, true);
-	const loaded = loadRunManifestById(ctx.cwd, params.runId);
-	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "cancel", status: "error" }, true);
-	return withRunLockSync(loaded.manifest, () => {
-		if (loaded.manifest.status === "completed" && !params.force) return result(`Run ${loaded.manifest.runId} is already completed; nothing to cancel. Use force: true to mark it cancelled anyway.`, { action: "cancel", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
-		const tasks = loaded.tasks.map((task) => task.status === "queued" || task.status === "running" ? { ...task, status: "cancelled" as const, finishedAt: new Date().toISOString(), error: "Run cancelled by user request." } : task);
-		saveRunTasks(loaded.manifest, tasks);
-		try {
-			saveCrewAgents(loaded.manifest, tasks.map((task) => recordFromTask(loaded.manifest, task, "child-process")));
-		} catch (error) {
-			logInternalError("team-tool.handleCancel.crewAgents", error, `runId=${loaded.manifest.runId}`);
-		}
-		try {
-			writeForegroundInterruptRequest(loaded.manifest, "Run cancelled by user request.");
-		} catch (error) {
-			logInternalError("team-tool.handleCancel.interruptRequest", error, `runId=${loaded.manifest.runId}`);
-		}
-		const updated = updateRunStatus(loaded.manifest, "cancelled", "Run cancelled by user request. Already-finished worker processes are not retroactively changed.");
-		return result(`Cancelled run ${updated.runId}.`, { action: "cancel", status: "ok", runId: updated.runId, artifactsRoot: updated.artifactsRoot });
-	});
-}
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { withRunLockSync } from "../../state/locks.ts";
+import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/state-store.ts";
+import { saveCrewAgents, recordFromTask } from "../../runtime/crew-agent-records.ts";
+import { writeForegroundInterruptRequest } from "../../runtime/foreground-control.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { result, type TeamContext } from "./context.ts";
+
+export function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	if (!params.runId) return result("Cancel requires runId.", { action: "cancel", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "cancel", status: "error" }, true);
+	return withRunLockSync(loaded.manifest, () => {
+		if (loaded.manifest.status === "completed" && !params.force) return result(`Run ${loaded.manifest.runId} is already completed; nothing to cancel. Use force: true to mark it cancelled anyway.`, { action: "cancel", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+		const tasks = loaded.tasks.map((task) => task.status === "queued" || task.status === "running" ? { ...task, status: "cancelled" as const, finishedAt: new Date().toISOString(), error: "Run cancelled by user request." } : task);
+		saveRunTasks(loaded.manifest, tasks);
+		try {
+			saveCrewAgents(loaded.manifest, tasks.map((task) => recordFromTask(loaded.manifest, task, "child-process")));
+		} catch (error) {
+			logInternalError("team-tool.handleCancel.crewAgents", error, `runId=${loaded.manifest.runId}`);
+		}
+		try {
+			writeForegroundInterruptRequest(loaded.manifest, "Run cancelled by user request.");
+		} catch (error) {
+			logInternalError("team-tool.handleCancel.interruptRequest", error, `runId=${loaded.manifest.runId}`);
+		}
+		const updated = updateRunStatus(loaded.manifest, "cancelled", "Run cancelled by user request. Already-finished worker processes are not retroactively changed.");
+		return result(`Cancelled run ${updated.runId}.`, { action: "cancel", status: "ok", runId: updated.runId, artifactsRoot: updated.artifactsRoot });
+	});
+}