pi-crew 0.1.41 → 0.1.43

package/src/extension/registration/subagent-tools.ts

@@ -7,6 +7,7 @@ import { readPersistedSubagentRecord, savePersistedSubagentRecord, type Subagent
 import { loadConfig } from "../../config/config.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { __test__subagentSpawnParams, formatSubagentRecord, readSubagentRunResult, refreshPersistedSubagentRecord, subagentToolResult } from "./subagent-helpers.ts";
+import { t } from "../../i18n.ts";
 
 export interface SubagentToolRegistrationOptions {
 	ownerSessionGeneration?: () => number;
@@ -37,7 +38,7 @@ export function registerSubagentTools(pi: ExtensionAPI, subagentManager: Subagen
 			if (!permission.allowed) return subagentToolResult(permission.reason ?? "Current role cannot spawn subagents.", { role: currentRole, mode: permission.mode }, true);
 			const spawnOptions = __test__subagentSpawnParams(params as Record<string, unknown>, ctx);
 			spawnOptions.ownerSessionGeneration = options.ownerSessionGeneration?.();
-			if (!spawnOptions.prompt.trim()) return subagentToolResult("Agent requires prompt.", {}, true);
+			if (!spawnOptions.prompt.trim()) return subagentToolResult(t("agent.requiresPrompt"), {}, true);
 			const runner = async (currentOptions: SubagentSpawnOptions, childSignal?: AbortSignal) => handleTeamTool({ action: "run", agent: currentOptions.type, goal: currentOptions.prompt, model: currentOptions.model, async: currentOptions.background, config: currentOptions.maxTurns ? { runtime: { maxTurns: currentOptions.maxTurns } } : undefined } as TeamToolParamsValue, currentOptions.background ? { ...ctx, signal: childSignal } : { ...ctx, signal: childSignal });
 			const record = subagentManager.spawn(spawnOptions, runner, spawnOptions.background ? undefined : signal);
 			if (spawnOptions.background || record.status === "queued") {
@@ -45,11 +46,11 @@ export function registerSubagentTools(pi: ExtensionAPI, subagentManager: Subagen
 				// Phase 1.6: Record was terminated for telemetry.
 				record.terminated = true;
 				savePersistedSubagentRecord(ctx.cwd, record);
-				return { ...subagentToolResult([`Agent ${record.status === "queued" ? "queued" : "started"}.`, `Agent ID: ${record.id}`, `Type: ${record.type}`, `Description: ${record.description}`, "Use get_subagent_result to retrieve output. Do not duplicate this agent's work."].join("\n"), { agentId: record.id, status: record.status }), terminate: true };
+				return { ...subagentToolResult([t("agent.started", { state: record.status === "queued" ? "queued" : "started" }), t("agent.id", { id: record.id }), t("agent.type", { type: record.type }), t("agent.description", { description: record.description }), t("agent.retrieveHint")].join("\n"), { agentId: record.id, status: record.status }), terminate: true };
 			}
 			await record.promise;
-			const output = readSubagentRunResult(ctx, record) ?? record.result ?? "No output.";
-			const foregroundResult = subagentToolResult([`Agent ${record.id} ${record.status}.`, "", output].join("\n"), { agentId: record.id, runId: record.runId, status: record.status }, record.status === "failed" || record.status === "error");
+			const output = readSubagentRunResult(ctx, record) ?? record.result ?? t("agent.noOutput");
+			const foregroundResult = subagentToolResult([t("agent.foregroundStatus", { id: record.id, status: record.status }), "", output].join("\n"), { agentId: record.id, runId: record.runId, status: record.status }, record.status === "failed" || record.status === "error");
 			if (loadConfig(ctx.cwd).config.tools?.terminateOnForeground === true) {
 				record.terminated = true;
 				savePersistedSubagentRecord(ctx.cwd, record);
@@ -66,14 +67,14 @@ export function registerSubagentTools(pi: ExtensionAPI, subagentManager: Subagen
 		parameters: Type.Object({ agent_id: Type.String({ description: "Agent ID returned by Agent." }), wait: Type.Optional(Type.Boolean({ description: "Wait for completion before returning." })), verbose: Type.Optional(Type.Boolean({ description: "Include status metadata before output." })) }) as never,
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			const p = params as { agent_id?: string; wait?: boolean; verbose?: boolean };
-			if (!p.agent_id) return subagentToolResult("get_subagent_result requires agent_id.", {}, true);
+			if (!p.agent_id) return subagentToolResult(t("result.requiresAgentId"), {}, true);
 			const inMemory = subagentManager.getRecord(p.agent_id);
 			const record = inMemory ?? readPersistedSubagentRecord(ctx.cwd, p.agent_id);
-			if (!record) return subagentToolResult(`Agent not found: ${p.agent_id}`, {}, true);
+			if (!record) return subagentToolResult(t("result.notFound", { id: p.agent_id }), {}, true);
 			let current = refreshPersistedSubagentRecord(ctx, record);
 			if (inMemory && current !== inMemory) Object.assign(inMemory, current);
 			if (!inMemory && !current.runId && (current.status === "running" || current.status === "queued")) {
-				current = { ...current, status: "error", error: "Subagent was interrupted before its durable run id was recorded; it cannot be recovered after restart.", completedAt: current.completedAt ?? Date.now() };
+				current = { ...current, status: "error", error: t("result.unrecoverable"), completedAt: current.completedAt ?? Date.now() };
 				savePersistedSubagentRecord(ctx.cwd, current);
 			}
 			if (p.wait && (current.status === "running" || current.status === "queued")) {
@@ -83,16 +84,24 @@ export function registerSubagentTools(pi: ExtensionAPI, subagentManager: Subagen
 					current.resultConsumed = false;
 					if (inMemory) inMemory.resultConsumed = false;
 					savePersistedSubagentRecord(ctx.cwd, current);
-				}
-				else while (current.status === "running" || current.status === "queued") {
-					if (signal?.aborted) {
-						current = { ...current, status: "error", error: "Waiting for subagent result was aborted.", completedAt: Date.now() };
-						savePersistedSubagentRecord(ctx.cwd, current);
-						break;
+				} else {
+					const waitStartMs = Date.now();
+					const maxWaitMs = 300_000; // 5 minutes
+					while (current.status === "running" || current.status === "queued") {
+						if (signal?.aborted) {
+							current = { ...current, status: "error", error: t("result.waitAborted"), completedAt: Date.now() };
+							savePersistedSubagentRecord(ctx.cwd, current);
+							break;
+						}
+						if (Date.now() - waitStartMs > maxWaitMs) {
+							current = { ...current, status: "error", error: t("result.waitTimeout"), completedAt: Date.now() };
+							savePersistedSubagentRecord(ctx.cwd, current);
+							break;
+						}
+						await new Promise((resolve) => setTimeout(resolve, 1000));
+						current = refreshPersistedSubagentRecord(ctx, current);
+						if (!current.runId) break;
 					}
-					await new Promise((resolve) => setTimeout(resolve, 1000));
-					current = refreshPersistedSubagentRecord(ctx, current);
-					if (!current.runId) break;
 				}
 			}
 			const output = readSubagentRunResult(ctx, current);
@@ -101,7 +110,7 @@ export function registerSubagentTools(pi: ExtensionAPI, subagentManager: Subagen
 				if (inMemory) inMemory.resultConsumed = true;
 				savePersistedSubagentRecord(ctx.cwd, current);
 			}
-			const text = [p.verbose ? formatSubagentRecord(current) : undefined, output ? `${p.verbose ? "\n" : ""}${output}` : current.status === "running" || current.status === "queued" ? "Agent is still running. Use wait=true or check again later." : current.error ?? "No output."].filter((line): line is string => Boolean(line)).join("\n");
+			const text = [p.verbose ? formatSubagentRecord(current) : undefined, output ? `${p.verbose ? "\n" : ""}${output}` : current.status === "running" || current.status === "queued" ? t("result.stillRunning") : current.error ?? t("agent.noOutput")].filter((line): line is string => Boolean(line)).join("\n");
 			return subagentToolResult(text, { agentId: current.id, runId: current.runId, status: current.status }, current.status === "failed" || current.status === "error");
 		},
 	};
@@ -114,8 +123,8 @@ export function registerSubagentTools(pi: ExtensionAPI, subagentManager: Subagen
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const p = params as { agent_id?: string; message?: string };
 			const record = p.agent_id ? subagentManager.getRecord(p.agent_id) ?? readPersistedSubagentRecord(ctx.cwd, p.agent_id) : undefined;
-			if (!record) return subagentToolResult(`Agent not found: ${p.agent_id ?? ""}`, {}, true);
-			return subagentToolResult([`Steering request noted for ${record.id}.`, "Current default pi-crew backend is child-process, so mid-turn session.steer is not available yet.", record.runId ? `Use team cancel runId=${record.runId} if the agent must be interrupted.` : undefined].filter((line): line is string => Boolean(line)).join("\n"), { agentId: record.id, runId: record.runId, status: record.status });
+			if (!record) return subagentToolResult(t("result.notFound", { id: p.agent_id ?? "" }), {}, true);
+			return subagentToolResult([t("steer.noted", { id: record.id }), t("steer.unavailable"), record.runId ? t("steer.cancelHint", { runId: record.runId }) : undefined].filter((line): line is string => Boolean(line)).join("\n"), { agentId: record.id, runId: record.runId, status: record.status });
 		},
 	};
 

package/src/extension/result-watcher.ts

@@ -61,7 +61,7 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 			coalescer.schedule(file, RESULT_WATCHER_POLL_MS);
 			return;
 		}
-		const key = buildCompletionKey(payload as Record<string, unknown>, `file:${file}`);
+		const key = buildCompletionKey(payload && typeof payload === "object" && !Array.isArray(payload) ? payload as Record<string, unknown> : {}, `file:${file}`);
 		if (!markSeenWithTtl(seen, key, Date.now(), completionTtlMs)) {
 			events.emit(eventName, payload);
 		}
@@ -78,7 +78,7 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 	const startPolling = () => {
 		if (pollTimer) return;
 		pollTimer = setInterval(poll, RESULT_WATCHER_POLL_MS);
-		pollTimer.unref?.();
+		pollTimer.unref();
 		poll();
 	};
 	const stopPolling = () => {
@@ -98,7 +98,7 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 				logInternalError("result-watcher.restart", error, `resultsDir=${resultsDir}`);
 			}
 		}, RESULT_WATCHER_RESTART_MS);
-		restartTimer.unref?.();
+		restartTimer.unref();
 	};
 	const handle: ResultWatcherHandle = {
 		start() {
@@ -110,7 +110,7 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 				coalescer.schedule(fileName.toString());
 			}, scheduleRestart);
 			if (watcher) stopPolling();
-			watcher?.unref?.();
+			watcher?.unref();
 		},
 		prime() {
 			poll();

package/src/extension/run-bundle-schema.ts

@@ -17,12 +17,13 @@ function validateArtifact(value: unknown, index: number, errors: string[]): valu
 		errors.push(`manifest.artifacts[${index}] must be an object.`);
 		return false;
 	}
+	const before = errors.length;
 	if (typeof value.kind !== "string") errors.push(`manifest.artifacts[${index}].kind must be a string.`);
 	if (typeof value.path !== "string") errors.push(`manifest.artifacts[${index}].path must be a string.`);
 	if (typeof value.createdAt !== "string") errors.push(`manifest.artifacts[${index}].createdAt must be a string.`);
 	if (typeof value.producer !== "string") errors.push(`manifest.artifacts[${index}].producer must be a string.`);
 	if (value.retention !== "run" && value.retention !== "project" && value.retention !== "temporary") errors.push(`manifest.artifacts[${index}].retention is invalid.`);
-	return true;
+	return errors.length === before;
 }
 
 function validateManifest(value: unknown, errors: string[]): value is TeamRunManifest {
@@ -30,6 +31,7 @@ function validateManifest(value: unknown, errors: string[]): value is TeamRunMan
 		errors.push("manifest must be an object.");
 		return false;
 	}
+	const before = errors.length;
 	if (value.schemaVersion !== 1) errors.push("manifest.schemaVersion must be 1.");
 	for (const field of ["runId", "team", "goal", "createdAt", "updatedAt", "cwd", "stateRoot", "artifactsRoot", "tasksPath", "eventsPath"] as const) {
 		if (typeof value[field] !== "string") errors.push(`manifest.${field} must be a string.`);
@@ -38,7 +40,7 @@ function validateManifest(value: unknown, errors: string[]): value is TeamRunMan
 	if (value.workspaceMode !== "single" && value.workspaceMode !== "worktree") errors.push("manifest.workspaceMode must be single or worktree.");
 	if (!Array.isArray(value.artifacts)) errors.push("manifest.artifacts must be an array.");
 	else value.artifacts.forEach((artifact, index) => validateArtifact(artifact, index, errors));
-	return true;
+	return errors.length === before;
 }
 
 function validateTask(value: unknown, index: number, errors: string[]): value is TeamTaskState {
@@ -46,12 +48,13 @@ function validateTask(value: unknown, index: number, errors: string[]): value is
 		errors.push(`tasks[${index}] must be an object.`);
 		return false;
 	}
+	const before = errors.length;
 	for (const field of ["id", "runId", "role", "agent", "title", "cwd"] as const) {
 		if (typeof value[field] !== "string") errors.push(`tasks[${index}].${field} must be a string.`);
 	}
 	if (!isTeamTaskStatus(value.status)) errors.push(`tasks[${index}].status is invalid.`);
 	if (!Array.isArray(value.dependsOn)) errors.push(`tasks[${index}].dependsOn must be an array.`);
-	return true;
+	return errors.length === before;
 }
 
 function validateEvent(value: unknown, index: number, errors: string[]): value is TeamEvent {
@@ -59,10 +62,11 @@ function validateEvent(value: unknown, index: number, errors: string[]): value i
 		errors.push(`events[${index}] must be an object.`);
 		return false;
 	}
+	const before = errors.length;
 	for (const field of ["time", "type", "runId"] as const) {
 		if (typeof value[field] !== "string") errors.push(`events[${index}].${field} must be a string.`);
 	}
-	return true;
+	return errors.length === before;
 }
 
 export function validateRunBundle(value: unknown): BundleValidationResult {

package/src/extension/run-import.ts

@@ -29,6 +29,10 @@ export function importRunBundle(cwd: string, bundlePath: string, scope: "project
 	resolveRealContainedPath(path.dirname(importsRoot), path.basename(importsRoot));
 	const root = resolveContainedRelativePath(importsRoot, runId, "runId");
 	fs.mkdirSync(root, { recursive: true });
+	// TOCTOU note: mkdirSync would throw EEXIST if a symlink already existed.
+	// The lstatSync check catches a symlink swapped in between mkdirSync and the check
+	// (theoretically possible but requires local attacker with exact timing).
+	// resolveRealContainedPath provides an additional real-path containment barrier.
 	if (fs.lstatSync(root).isSymbolicLink()) throw new Error(`Invalid import directory: ${root}`);
 	resolveRealContainedPath(importsRoot, runId);
 	const targetJson = path.join(root, "run-export.json");

package/src/extension/run-index.ts

@@ -40,7 +40,10 @@ function mergeRuns(runSets: TeamRunManifest[][], max?: number): TeamRunManifest[
 }
 
 function scopedRunRoots(cwd: string): string[] {
-	return [findRepoRoot(cwd) ? projectCrewRoot(cwd) : userCrewRoot()];
+	const roots: string[] = [userCrewRoot()];
+	const projectRoot = findRepoRoot(cwd);
+	if (projectRoot) roots.unshift(projectCrewRoot(cwd));
+	return roots;
 }
 
 export function listRuns(cwd: string): TeamRunManifest[] {

package/src/extension/run-maintenance.ts

@@ -1,24 +1,43 @@
-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 { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { projectCrewRoot } from "../utils/paths.ts";
+import { listRuns } from "./run-index.ts";
+import { logInternalError } from "../utils/internal-error.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";
+}
+
+function isSafeToPrune(cwd: string, run: TeamRunManifest): boolean {
+	try {
+		const crewRoot = projectCrewRoot(cwd);
+		resolveRealContainedPath(crewRoot, run.stateRoot);
+		resolveRealContainedPath(crewRoot, run.artifactsRoot);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function pruneFinishedRuns(cwd: string, keep: number): PruneRunsResult {
+	const crewRoot = projectCrewRoot(cwd);
+	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)) {
+		if (!isSafeToPrune(cwd, run)) {
+			logInternalError("prune.path-unsafe", new Error(`Skipping unsafe prune: stateRoot=${run.stateRoot}, artifactsRoot=${run.artifactsRoot}`), `runId=${run.runId}`);
+			continue;
+		}
+		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

@@ -22,7 +22,7 @@ import type { PiTeamsToolResult } from "../tool-result.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
 
 function globMatch(value: string, pattern: string): boolean {
-	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\?/g, "\\?").replace(/\*/g, ".*");
 	return new RegExp(`^${escaped}$`).test(value);
 }
 

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 });
+	});
+}

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

@@ -52,7 +52,14 @@ function checkWritableDir(dir: string): { ok: boolean; detail: string } {
 	try {
 		if (!fs.existsSync(dir)) return { ok: false, detail: `${dir}: missing` };
 		if (!fs.statSync(dir).isDirectory()) return { ok: false, detail: `${dir}: not a directory` };
-		fs.accessSync(dir, fs.constants.W_OK);
+		// fs.accessSync(W_OK) is unreliable on Windows; verify by writing a temp file.
+		const probePath = `${dir}/.pi-crew-write-test`;
+		try {
+			fs.writeFileSync(probePath, "ok", "utf-8");
+			fs.rmSync(probePath, { force: true });
+		} catch {
+			return { ok: false, detail: `${dir}: not writable (write test failed)` };
+		}
 		return { ok: true, detail: dir };
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);

package/src/extension/team-tool/handle-settings.ts

@@ -0,0 +1,188 @@
+import type { TeamContext } from "../team-tool/context.ts";
+import { loadConfig, updateConfig } from "../../config/config.ts";
+import { configPatchFromConfig } from "../team-tool/config-patch.ts";
+import { result } from "../team-tool/context.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function setNested(obj: Record<string, unknown>, path: string, value: unknown): void {
+	const keys = path.split(".");
+	let target: Record<string, unknown> = obj;
+	for (let i = 0; i < keys.length - 1; i++) {
+		if (!target[keys[i]] || typeof target[keys[i]] !== "object") {
+			target[keys[i]] = {};
+		}
+		target = target[keys[i]] as Record<string, unknown>;
+	}
+	target[keys[keys.length - 1]] = value;
+}
+
+function getNested(obj: Record<string, unknown>, path: string): unknown {
+	const keys = path.split(".");
+	let current: unknown = obj;
+	for (const key of keys) {
+		if (!current || typeof current !== "object") return undefined;
+		current = (current as Record<string, unknown>)[key];
+	}
+	return current;
+}
+
+function formatValue(value: unknown): string {
+	if (value === undefined) return "<not set>";
+	if (typeof value === "object") return JSON.stringify(value);
+	return String(value);
+}
+
+function parseValue(raw: string): unknown {
+	// JSON handles strings (quoted), numbers, booleans, null, arrays, objects.
+	try { return JSON.parse(raw); } catch { /* keep as string */ }
+	return raw;
+}
+
+// ---------------------------------------------------------------------------
+// Known config keys — mirrors config-schema.ts + config.ts.
+// When adding new config fields, add the dotted path here so team-settings
+// can discover and display them.
+// ---------------------------------------------------------------------------
+
+const KNOWN_KEYS = new Set([
+	// top-level
+	"asyncByDefault",
+	"executeWorkers",
+	"notifierIntervalMs",
+	"requireCleanWorktreeLeader",
+	// runtime
+	"runtime.mode",
+	"runtime.preferLiveSession",
+	"runtime.allowChildProcessFallback",
+	"runtime.maxTurns",
+	"runtime.graceTurns",
+	"runtime.inheritContext",
+	"runtime.promptMode",
+	"runtime.groupJoin",
+	"runtime.groupJoinAckTimeoutMs",
+	"runtime.requirePlanApproval",
+	"runtime.completionMutationGuard",
+	// limits
+	"limits.maxConcurrentWorkers",
+	"limits.allowUnboundedConcurrency",
+	"limits.maxTaskDepth",
+	"limits.maxChildrenPerTask",
+	"limits.maxRunMinutes",
+	"limits.maxRetriesPerTask",
+	"limits.maxTasksPerRun",
+	"limits.heartbeatStaleMs",
+	// control
+	"control.enabled",
+	"control.needsAttentionAfterMs",
+	// autonomous
+	"autonomous.profile",
+	"autonomous.enabled",
+	"autonomous.injectPolicy",
+	"autonomous.preferAsyncForLongTasks",
+	"autonomous.allowWorktreeSuggestion",
+	// tools
+	"tools.enableClaudeStyleAliases",
+	"tools.enableSteer",
+	"tools.terminateOnForeground",
+	// agents
+	"agents.disableBuiltins",
+	// observability
+	"observability.prometheus.enabled",
+	"observability.otlp.enabled",
+	// worktree
+	"worktree.enabled",
+]);
+
+const KNOWN_SORTED = [...KNOWN_KEYS].sort();
+
+// ---------------------------------------------------------------------------
+// Detail objects – all require { action, status } from TeamToolDetails.
+// Extras (count, key, value, path) are passed as never to bypass the narrow
+// TeamToolDetails interface (consistent with the rest of the codebase).
+// ---------------------------------------------------------------------------
+
+const OK = { action: "settings", status: "ok" as const };
+const ERR = { action: "settings", status: "error" as const };
+
+// ---------------------------------------------------------------------------
+// Main handler
+// ---------------------------------------------------------------------------
+
+export function handleSettings(params: { config?: Record<string, unknown> }, ctx: TeamContext): PiTeamsToolResult {
+	const cfg = (params.config ?? {}) as Record<string, unknown>;
+	const args = typeof cfg.args === "string" ? cfg.args.trim() : "";
+	const scope = cfg.scope === "project" ? "project" : "user";
+	const loaded = loadConfig(ctx.cwd);
+	const effective = loaded.config as Record<string, unknown>;
+
+	// team-settings list
+	if (!args || args === "list") {
+		const lines = ["pi-crew settings:", `Path: ${loaded.path}`, ""];
+		for (const key of KNOWN_SORTED) {
+			const value = getNested(effective, key);
+			lines.push(`  ${key} = ${formatValue(value)}`);
+		}
+		lines.push("", "Usage: team-settings [list|get <key>|set <key> <value>|unset <key>|path|scope]");
+		return result(lines.join("\n"), { ...OK, count: KNOWN_KEYS.size } as never);
+	}
+
+	// team-settings path
+	if (args === "path") {
+		return result(`pi-crew config path: ${loaded.path}`, { ...OK, path: loaded.path } as never);
+	}
+
+	// team-settings scope
+	if (args === "scope") {
+		return result(`Current scope: ${scope}\nConfig at: ${loaded.path}`, { ...OK, scope } as never);
+	}
+
+	// team-settings get <key>
+	if (args.startsWith("get ")) {
+		const key = args.slice(4).trim();
+		if (!key) return result("Usage: team-settings get <key>", { ...ERR }, true);
+		const value = getNested(effective, key);
+		const note = KNOWN_KEYS.has(key) ? "" : " (unknown key — may not take effect)";
+		return result(`${key} = ${formatValue(value)}${note}`, { ...OK, key, value } as never);
+	}
+
+	// team-settings unset <key>
+	if (args.startsWith("unset ")) {
+		const key = args.slice(6).trim();
+		if (!key) return result("Usage: team-settings unset <key>", { ...ERR }, true);
+		try {
+			const saved = updateConfig({}, { cwd: ctx.cwd, scope, unsetPaths: [key] });
+			return result(`Unset ${key}\nPath: ${saved.path}`, { ...OK, key } as never);
+		} catch (error) {
+			return result(error instanceof Error ? error.message : String(error), { ...ERR }, true);
+		}
+	}
+
+	// team-settings set <key> <value>
+	if (args.startsWith("set ")) {
+		const rest = args.slice(4).trim();
+		const spaceIdx = rest.indexOf(" ");
+		if (spaceIdx === -1) return result("Usage: team-settings set <key> <value>", { ...ERR }, true);
+		const key = rest.slice(0, spaceIdx);
+		const rawValue = rest.slice(spaceIdx + 1).trim();
+		if (!key) return result("Usage: team-settings set <key> <value>", { ...ERR }, true);
+
+		const value = parseValue(rawValue);
+		const patch = {};
+		setNested(patch as Record<string, unknown>, key, value);
+
+		try {
+			const converted = configPatchFromConfig({ config: patch as Record<string, unknown> });
+			const saved = updateConfig(converted, { cwd: ctx.cwd, scope });
+			const warning = KNOWN_KEYS.has(key) ? "" : "\nWarning: unknown key — verify it exists in config schema.";
+			return result(`Set ${key} = ${formatValue(value)}\nPath: ${saved.path}${warning}`, { ...OK, key, value } as never);
+		} catch (error) {
+			return result(error instanceof Error ? error.message : String(error), { ...ERR }, true);
+		}
+	}
+
+	return result("Unknown subcommand. Usage: team-settings [list|get <key>|set <key> <value>|unset <key>|path|scope]", { ...ERR }, true);
+}