pi-crew 0.6.0 → 0.6.3

package/src/runtime/team-runner.ts

@@ -11,6 +11,7 @@ import { appendEvent, appendEventAsync, appendEventFireAndForget } from "../stat
 import type { TeamConfig } from "../teams/team-config.ts";
 import type { ArtifactDescriptor, PolicyDecision, TeamRunManifest, TaskAttemptState, TeamTaskState } from "../state/types.ts";
 import { loadRunManifestById, saveRunManifest, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/state-store.ts";
+import { withRunLock } from "../state/locks.ts";
 import { aggregateUsage, formatUsage } from "../state/usage.ts";
 import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
 import { evaluateCrewPolicy, summarizePolicyDecisions } from "./policy-engine.ts";
@@ -38,6 +39,19 @@ import { clearTrackedTaskUsage } from "./usage-tracker.ts";
 import { CrewCancellationError, buildSyntheticTerminalEvidence, cancellationReasonFromSignal } from "./cancellation.ts";
 import { effectivenessPolicyDecision, evaluateRunEffectiveness, formatRunEffectivenessLines } from "./effectiveness.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { PluginRegistry } from "../plugins/plugin-registry.ts";
+import { NextJsPlugin, VitestPlugin, VitePlugin } from "../plugins/plugins/index.ts";
+import { HealthStore } from "../state/health-store.ts";
+
+// Built-in plugin registry for framework awareness.
+// NOTE: This registry is registered here for future use. The integration
+// point (reading package.json deps, computing active plugin context, and
+// passing it into RunConfig / task-runner) is not yet implemented; see
+// `getPluginContext` in src/plugins/plugin-context.ts (planned).
+const builtInRegistry = new PluginRegistry();
+builtInRegistry.register(NextJsPlugin);
+builtInRegistry.register(VitestPlugin);
+builtInRegistry.register(VitePlugin);
 
 /**
  * Start a periodic heartbeat for the team-level run.
@@ -49,7 +63,7 @@ import { logInternalError } from "../utils/internal-error.ts";
  * executing. The team-runner has no periodic heartbeat today, so any
  * team run lasting >5min is at risk.
  */
-function startTeamRunHeartbeat(stateRoot: string, runId: string): () => void {
+function startTeamRunHeartbeat(stateRoot: string, runId: string, lastTaskUpdateAt?: string): () => void {
 	const heartbeatPath = path.join(stateRoot, "heartbeat.json");
 	const writeHeartbeat = (): void => {
 		try {
@@ -58,14 +72,18 @@ function startTeamRunHeartbeat(stateRoot: string, runId: string): () => void {
 				at: Date.now(),
 				runId,
 				kind: "team-runner",
-			}), "utf-8");
+				lastTaskUpdateAt,
+			}), { encoding: "utf-8", mode: 0o600 });
 		} catch {
 			// best-effort
 		}
 	};
 	writeHeartbeat();
+	// NOTE: This interval is deliberately NOT unref'd. Unlike background-runner's
+	// heartbeat and interrupt guard (both unref'd), the team heartbeat must keep
+	// the event loop alive so the stale reconciler does not cancel long-running
+	// team runs (>5 min) as "stale" while they are actively executing.
 	const interval = setInterval(writeHeartbeat, 30_000);
-	interval.unref();
 	return () => clearInterval(interval);
 }
 
@@ -120,18 +138,93 @@ function isNonTerminalTaskStatus(status: TeamTaskState["status"]): boolean {
 	return status === "queued" || status === "running" || status === "waiting";
 }
 
+/**
+ * Returns the finishedAt timestamp as a number, or Infinity for invalid/malformed dates.
+ * This makes comparison logic in shouldMergeTaskUpdate more readable by abstracting
+ * the NaN handling into a single well-named function.
+ */
+function safeFinishedAt(task: TeamTaskState): number {
+	if (!task.finishedAt) return -Infinity;
+	const ms = new Date(task.finishedAt).getTime();
+	return Number.isNaN(ms) ? Infinity : ms;
+}
+
+/**
+ * Returns true when the current task has a malformed finishedAt (NaN/Infinity)
+ * and the updated task has a valid finite finishedAt. Malformed finishedAt
+ * should be replaced rather than persisting corruption.
+ */
+function isMalformedFinishedAtReplacement(currentTime: number, updatedTime: number): boolean {
+	return !Number.isFinite(currentTime) && Number.isFinite(updatedTime);
+}
+
 function shouldMergeTaskUpdate(current: TeamTaskState, updated: TeamTaskState): boolean {
 	// Parallel workers receive the same input snapshot. A later result may still
 	// contain stale queued/running copies of tasks that another worker already
 	// completed. Never let those stale snapshots regress durable task state.
-	if (!isNonTerminalTaskStatus(current.status) && isNonTerminalTaskStatus(updated.status)) return false;
+	if (current.status === "waiting" && updated.status === "running") return false;
+	// Block terminal→non-terminal transitions (e.g. completed→running).
+	// A task that has reached a terminal state must not be resurrected.
+	const currentIsTerminal = !isNonTerminalTaskStatus(current.status);
+	const updatedIsNonTerminal = isNonTerminalTaskStatus(updated.status);
+	if (currentIsTerminal && updatedIsNonTerminal) return false;
+	// Explicitly block completed↔needs_attention terminal-to-terminal transitions.
+// Both are success terminal states used interchangeably; stale worker updates must
+// not cause a completed task to appear as needs_attention or vice versa.
+if (current.status === "completed" && updated.status === "needs_attention") return false;
+if (current.status === "needs_attention" && updated.status === "completed") return false;
+	// Explicitly block failed→completed resurrection. Both statuses are terminal,
+	// but completed is the success terminal state and should not be reachable from
+	// failed via a stale merge. The check above only guards non-terminal→terminal.
+	if (current.status === "failed" && updated.status === "completed") return false;
+	// Guard: when current is "running" but has resultArtifact (another worker already
+	// completed it), a stale updated with status="running" and no resultArtifact
+	// must not overwrite the actual completed state.
+	if (current.status === updated.status && updated.status === "running" && Boolean(current.resultArtifact) && !updated.resultArtifact) return false;
+	// Guard: when current is "completed" and has resultArtifact but updated is also
+	// "completed" without resultArtifact, block the stale update from overwriting
+	// a task that successfully produced output.
+	if (current.status === updated.status && current.status === "completed" && Boolean(current.resultArtifact) && !updated.resultArtifact) return false;
 	// Prevent a stale completed task from overwriting a fresher one.
-	if (current.finishedAt && updated.finishedAt) {
-		const currentFinished = new Date(current.finishedAt).getTime();
-		const updatedFinished = new Date(updated.finishedAt).getTime();
-		if (!Number.isNaN(currentFinished) && !Number.isNaN(updatedFinished) && updatedFinished < currentFinished) return false;
+	// Restructure to handle undefined current.finishedAt as a special case:
+	// - undefined current + valid updated: allow the update
+	// - valid current + undefined updated: block the update (don't lose completion time)
+	// - both undefined: finishedAt guard does not apply, fall through to heartbeat check
+	// - both valid: compare timestamps as before
+	if (current.finishedAt !== undefined && updated.finishedAt !== undefined) {
+		const currentTime = safeFinishedAt(current);
+		const updatedTime = safeFinishedAt(updated);
+		// Malformed finishedAt (NaN) is treated as Infinity — invalid state should be
+		// replaced rather than persisting corruption. Log warning for visibility.
+		if (!Number.isFinite(currentTime)) {
+			console.warn(`[team-runner] Task ${current.id} has malformed finishedAt: ${current.finishedAt}`);
+		}
+		if (isMalformedFinishedAtReplacement(currentTime, updatedTime)) {
+			return true;
+		}
+		if (updatedTime < currentTime) return false;
 	}
-	return updated.status !== current.status || updated.finishedAt !== current.finishedAt || updated.startedAt !== current.startedAt || Boolean(updated.resultArtifact) || Boolean(updated.error) || Boolean(updated.modelAttempts?.length) || Boolean(updated.usage) || Boolean(updated.attempts?.length);
+	// Block if updated is trying to establish a terminal status without a finishedAt
+	// timestamp. Heartbeat-only updates (status='running', no finishedAt) are
+	// allowed if heartbeat has changed (checked separately in hasMeaningfulUpdate).
+	if (!updated.finishedAt && !isNonTerminalTaskStatus(updated.status)) return false;
+	// Explicitly enumerate all fields that constitute a meaningful update so that
+// adding a new important field requires updating this list (rather than silently
+// losing data if a field is forgotten in the boolean OR chain below).
+const hasMeaningfulUpdate =
+  updated.status !== current.status ||
+  updated.finishedAt !== current.finishedAt ||
+  updated.startedAt !== current.startedAt ||
+  Boolean(updated.resultArtifact) !== Boolean(current.resultArtifact) ||
+  (Boolean(updated.resultArtifact) && updated.resultArtifact !== current.resultArtifact) ||
+  Boolean(updated.error) ||
+  Boolean(updated.modelAttempts?.length) ||
+  Boolean(updated.usage) ||
+  Boolean(updated.attempts?.length) ||
+  updated.heartbeat?.lastSeenAt !== current.heartbeat?.lastSeenAt ||
+  updated.jsonEvents !== current.jsonEvents ||
+  updated.agentProgress?.lastActivityAt !== current.agentProgress?.lastActivityAt;
+return hasMeaningfulUpdate;
 }
 
 // H4 fix: rename to descriptive name. Kept __test__ as alias for backward
@@ -141,7 +234,19 @@ export function mergeTaskUpdatesPreservingTerminal(base: TeamTaskState[], result
 	for (const result of results) {
 		for (const updated of result.tasks) {
 			const current = merged.find((task) => task.id === updated.id);
-			if (!current || !shouldMergeTaskUpdate(current, updated)) continue;
+			if (!current) continue;
+			if (!shouldMergeTaskUpdate(current, updated)) {
+				// Log skipped merges for visibility into rejected parallel updates.
+				// In distributed systems with parallel workers, rejected merges may
+				// indicate bugs (wrong status, timestamp corruption) if they accumulate.
+				console.debug("[team-runner] Skipping stale merge for task", updated.id, {
+					currentStatus: current.status,
+					updatedStatus: updated.status,
+					currentFinishedAt: current.finishedAt,
+					updatedFinishedAt: updated.finishedAt,
+				});
+				continue;
+			}
 			merged = merged.map((task) => task.id === updated.id ? updated : task);
 		}
 	}
@@ -189,7 +294,7 @@ function writeProgress(manifest: TeamRunManifest, tasks: TeamTaskState[], produc
 			"",
 		].join("\n"),
 	});
-	return { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts.filter((artifact) => !(artifact.kind === "progress" && artifact.path === progress.path)), progress] };
+	return { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts.filter((artifact) => !(artifact.kind === "progress" && artifact.path === progress.path)), progress].filter((artifact, index, self) => self.findIndex((a) => a.path === artifact.path) === index) };
 }
 
 function applyPolicy(manifest: TeamRunManifest, tasks: TeamTaskState[], limits?: CrewLimitsConfig): TeamRunManifest {
@@ -307,7 +412,7 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 	// (NO_PID_HEARTBEAT_STALE_MS). Previously only sub-task runners wrote
 	// heartbeats; the team-level run had no heartbeat, so any multi-phase
 	// workflow lasting >5min was marked stale and cancelled.
-	const stopTeamHeartbeat = startTeamRunHeartbeat(manifest.stateRoot, manifest.runId);
+	const stopTeamHeartbeat = startTeamRunHeartbeat(manifest.stateRoot, manifest.runId, manifest.updatedAt);
 
 	const cleanupUsage = (): void => {
 		for (const task of input.tasks) clearTrackedTaskUsage(task.id);
@@ -335,7 +440,14 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 	} catch (error) {
 		// P1: Catch unhandled errors — ensure manifest/tasks/agents are terminal so they don't stay "running" forever.
 		const message = error instanceof Error ? error.message : String(error);
-		const loaded = loadRunManifestById(input.manifest.cwd, input.manifest.runId);
+		// Reload manifest with lock to avoid stale data overwriting concurrent writes.
+		// If lock acquisition fails, use in-memory data rather than stale disk data.
+		let loaded;
+		try {
+			loaded = await withRunLock(input.manifest, async () => loadRunManifestById(input.manifest.cwd, input.manifest.runId));
+		} catch {
+			loaded = undefined; // best-effort: use in-memory data if lock fails
+		}
 		const freshManifest = loaded?.manifest ?? manifest;
 		const freshTasks = refreshTaskGraphQueues(loaded?.tasks ?? input.tasks);
 		const failedAt = new Date().toISOString();
@@ -364,7 +476,6 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		rejectRunPromise(manifest.runId, error instanceof Error ? error : new Error(message));
 		crewHooks.emit({ type: "run_failed", timestamp: new Date().toISOString(), runId: manifest.runId, data: { status: manifest.status, error: message } });
 		cleanupUsage();
-		stopTeamHeartbeat();
 		return result;
 	}
 }
@@ -543,6 +654,7 @@ async function executeTeamRunCore(
 						const startedAt = new Date().toISOString();
 						const inFlightAttempts: TaskAttemptState[] = [...attemptsSoFar, { attemptId: info.attemptId, startedAt }];
 						input.metricRegistry?.counter("crew.task.retry_attempt_total", "Retry attempts by run and task").inc({ runId: manifest.runId, taskId: task.id });
+						// NOTE: no withRunLock — best-effort only; concurrent writes may cause inconsistency
 						const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
 						const freshManifest = fresh?.manifest ?? manifest;
 						const freshTasks = fresh?.tasks ?? tasks;
@@ -580,6 +692,7 @@ async function executeTeamRunCore(
 				} catch (retryError) {
 					if (retryError instanceof CrewCancellationError || input.signal?.aborted) {
 						const reason = retryError instanceof CrewCancellationError ? retryError.reason : cancellationReasonFromSignal(input.signal);
+						// NOTE: no withRunLock — best-effort only; concurrent writes may cause inconsistency
 						const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
 						const freshManifest = fresh?.manifest ?? manifest;
 						const freshTasks = fresh?.tasks ?? tasks;
@@ -588,6 +701,7 @@ async function executeTeamRunCore(
 						return { manifest: updateRunStatus(freshManifest, "cancelled", reason.message), tasks: cancelledTasks };
 					}
 					if (lastFailed) return lastFailed;
+					// NOTE: no withRunLock — best-effort only; concurrent writes may cause inconsistency
 					const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
 					const freshManifest = fresh?.manifest ?? manifest;
 					const freshTasks = fresh?.tasks ?? tasks;
@@ -598,8 +712,43 @@ async function executeTeamRunCore(
 			},
 		);
 		if (results.length === 0) break;
-		manifest = { ...results.at(-1)!.manifest, artifacts: mergeArtifacts([manifest.artifacts, ...results.map((item) => item.manifest.artifacts)].flat()) };
-		tasks = mergeTaskUpdatesPreservingTerminal(tasks, results);
+		// FIX: Filter out undefined entries from partial results when error occurred
+		// during parallel execution. Other workers may have written partial results
+		// before one threw. Results may be partial - some tasks in-flight at error
+		// time will not have entries in the results array.
+		const validResults = results.filter((item): item is NonNullable<typeof item> => item !== undefined);
+		// Guard: if ALL parallel workers threw before returning, validResults is empty.
+		// at(-1)! would crash. Mark the run failed rather than crashing.
+		if (validResults.length === 0) {
+			manifest = updateRunStatus(manifest, "failed", "All parallel tasks failed catastrophically.");
+			return { manifest, tasks };
+		}
+		// Reconstruct manifest from the last worker's snapshot. The .artifacts field
+// is re-merged from both the team-runner's in-memory state and all workers'
+// snapshots, so artifact writes by task-runner (which individually save manifest
+// after writing artifacts) are safely persisted. The in-memory manifest is only
+// used for the next batch iteration's orchestration — actual persistence is safe.
+// Use updateRunStatus to recompute manifest status from merged tasks rather than
+// relying on the last result's manifest (which is arbitrary due to mapConcurrent
+// returning results in arbitrary order).
+// Use the in-memory manifest as base (not the last-completing worker's snapshot).
+// Recompute status from merged tasks so the manifest reflects actual task state,
+// not the arbitrary order in which mapConcurrent returned results.
+// Read committed manifest from disk inside the lock so artifact merge is based
+// on committed state, not in-memory state that may differ from disk.
+const mergeResult = await withRunLock(manifest, async () => {
+    const disk = loadRunManifestById(manifest.cwd, manifest.runId);
+    const diskManifest = disk?.manifest ?? manifest;
+    const diskArtifacts = diskManifest.artifacts;
+    const reconciledArtifacts = mergeArtifacts([...diskArtifacts, ...validResults.map((item) => item.manifest.artifacts)].flat());
+    const resultManifest = updateRunStatus({ ...diskManifest, artifacts: reconciledArtifacts }, "running", "Merged task updates from parallel batch.");
+    const resultTasks = mergeTaskUpdatesPreservingTerminal(tasks, validResults);
+    await saveRunManifestAsync(resultManifest);
+    await saveRunTasksAsync(resultManifest, resultTasks);
+    return { resultManifest, resultTasks };
+});
+manifest = mergeResult.resultManifest;
+tasks = mergeResult.resultTasks;
 
 		// Advance workflow phases whose tasks are all in terminal state
 		const terminalStatuses = new Set(["completed", "failed", "skipped", "cancelled", "needs_attention"]);
@@ -678,7 +827,7 @@ async function executeTeamRunCore(
 		}
 		await saveRunTasksAsync(manifest, tasks);
 		saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
-		const completedBatch = batchTasks.map((task) => tasks.find((item) => item.id === task.id) ?? task);
+		const completedBatch = tasks.filter((t) => batchTasks.some((bt) => bt.id === t.id));
 		const batchArtifact = writeArtifact(manifest.artifactsRoot, {
 			kind: "summary",
 			relativePath: `batches/${batchTasks.map((task) => task.id).join("+")}.md`,
@@ -744,8 +893,25 @@ async function executeTeamRunCore(
 			"",
 		].join("\n"),
 	});
-	manifest = { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts, summaryArtifact] };
-	await saveRunManifestAsync(manifest);
-	await saveRunTasksAsync(manifest, tasks);
+	// Build the complete manifest BEFORE acquiring the lock so the artifacts array
+	// is already incorporated into the manifest object that will be atomically written.
+	// This prevents crash-between-mutation-and-lock from leaving inconsistent state.
+	const finalManifest = { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts, summaryArtifact] };
+	// Joint atomic save: wrap manifest + tasks in a single run lock so they are
+	// written together or not at all. Crash between separate saveRunManifestAsync
+	// and saveRunTasksAsync calls could leave manifest/tasks.json out of sync.
+	await withRunLock(finalManifest, async () => {
+		await saveRunManifestAsync(finalManifest);
+		await saveRunTasksAsync(finalManifest, tasks);
+	});
+	manifest = finalManifest;
+	// Save health snapshot on run completion
+	const crewRoot = path.dirname(path.dirname(finalManifest.stateRoot));
+	const healthStore = new HealthStore(crewRoot);
+	healthStore.saveSnapshot({
+		runId: finalManifest.runId,
+		tasks: tasks.map((t) => ({ id: t.id, status: t.status })),
+		createdAt: finalManifest.createdAt,
+	});
 	return { manifest, tasks };
 }

package/src/runtime/usage-tracker.ts

@@ -16,7 +16,8 @@ export function addUsage(into: LifetimeUsage, delta: { input?: number; output?:
 	if (typeof delta.cacheWrite === "number") into.cacheWrite += delta.cacheWrite;
 }
 
-export function lifetimeUsageFromState(state: UsageState | undefined): LifetimeUsage {
+/** @internal */
+function lifetimeUsageFromState(state: UsageState | undefined): LifetimeUsage {
 	if (!state) return emptyLifetimeUsage();
 	return {
 		input: state.input ?? 0,
@@ -59,7 +60,8 @@ export const getTaskUsage = getTrackedTaskUsage;
 export const getRunUsage = getTrackedTaskUsage;
 export const clearAllTaskUsage = clearAllTrackedTaskUsage;
 
-export function aggregateTrackedUsageForRun(manifest: TeamRunManifest, tasks: TeamTaskState[]): UsageState {
+/** @internal */
+function aggregateTrackedUsageForRun(manifest: TeamRunManifest, tasks: TeamTaskState[]): UsageState {
 	const total = emptyLifetimeUsage();
 	for (const task of tasks) {
 		const tracked = getTrackedTaskUsage(task.id);

package/src/runtime/verification-gates.ts

@@ -38,35 +38,61 @@ export interface PhaseGateBundle {
  * Sequential enforcement: each phase must pass before proceeding.
  */
 export const NPM_TYPESCRIPT_GATES: Array<{ name: string; command: string; critical: boolean }> = [
-	{ name: "build", command: "npm run build 2>&1 || true", critical: true },
-	{ name: "typecheck", command: "npx tsc --noEmit 2>&1 || true", critical: true },
-	{ name: "lint", command: "npm run lint 2>&1 || true", critical: false },
-	{ name: "tests", command: "npm test 2>&1 || true", critical: true },
+	{ name: "build", command: "npm run build 2>&1", critical: true },
+	{ name: "typecheck", command: "npx tsc --noEmit 2>&1", critical: true },
+	{ name: "lint", command: "npm run lint 2>&1", critical: false },
+	{ name: "tests", command: "npm test 2>&1", critical: true },
 ];
 
 /**
  * Cargo/Rust project phase gates.
  */
 export const CARGO_RUST_GATES: Array<{ name: string; command: string; critical: boolean }> = [
-	{ name: "check", command: "cargo check 2>&1 || true", critical: true },
-	{ name: "test", command: "cargo test 2>&1 || true", critical: true },
-	{ name: "clippy", command: "cargo clippy 2>&1 || true", critical: false },
+	{ name: "check", command: "cargo check 2>&1", critical: true },
+	{ name: "test", command: "cargo test 2>&1", critical: true },
+	{ name: "clippy", command: "cargo clippy 2>&1", critical: false },
 ];
 
 /**
  * Execute a single command and capture output.
  */
+/** Characters/patterns that indicate dangerous shell metacharacters. */
+const DANGEROUS_SHELL_PATTERNS = /(?:;|&&|\|\||\$\(|`|\$\{|\b(eval|exec)\b|>>|<[^&])/;
+// Note: single `>` is NOT blocked here because `2>&1` is a safe redirect used by built-in gates.
+// `>>` (append) is still blocked. `<` without `&` (input redirect) is still blocked.
+
+/**
+ * Validate a verification gate command is safe to execute.
+ * Rejects commands with shell metacharacters that could enable injection.
+ * Allows: pipes (|), redirection of stderr (2>&1), and basic npm/cargo/npx commands.
+ */
+function validateGateCommand(command: string): void {
+	const normalized = command
+		.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')  // ANSI escape sequences
+		.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '')  // control chars
+		.replace(/\\\n/g, ' ')  // escaped newlines
+		.replace(/\s+/g, ' ')  // collapse whitespace
+		.trim();
+	if (DANGEROUS_SHELL_PATTERNS.test(normalized)) {
+		throw new Error(
+			`Security: verification gate command rejected (dangerous shell pattern): ${command}`,
+		);
+	}
+}
+
 async function executeCommand(
 	command: string,
 	cwd: string,
 	timeoutMs: number = 120000,
 ): Promise<{ exitCode: number | null; output: string; durationMs: number }> {
+	// SECURITY: Validate command before shell execution to prevent injection.
+	validateGateCommand(command);
+
 	const start = Date.now();
 	let output = "";
 	let exitCode: number | null = null;
 
 	return new Promise((resolve) => {
-		// Use shell to handle compound commands
 		const shell = spawn("sh", ["-c", command], {
 			cwd,
 			timeout: timeoutMs,
@@ -313,7 +339,8 @@ export function computeGreenLevelFromResults(
  * Create a verification gate report artifact.
  * Formatted for human review per ECC verification-loop pattern.
  */
-export function createVerificationGateReport(
+/** @internal */
+function createVerificationGateReport(
 	taskId: string,
 	contract: VerificationContract,
 	results: VerificationCommandResult[],

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

@@ -114,7 +114,10 @@ export const TeamToolParams = Type.Object({
 		}),
 	),
 	runId: Type.Optional(
-		Type.String({ description: "Run ID for status, cancel, or resume." }),
+		Type.String({
+			description: "Run ID for status, cancel, or resume.",
+			pattern: "^[A-Za-z0-9_-]+$",
+		}),
 	),
 	taskId: Type.Optional(
 		Type.String({ description: "Task ID for respond action." }),
@@ -197,39 +200,54 @@ export const TeamToolParams = Type.Object({
 		Type.Integer({ description: "Ms epoch deadline for a reply." }),
 	),
 	planPath: Type.Optional(
-		Type.String({ description: "Path to a markdown plan document for orchestration." }),
+		Type.String({
+			description: "Path to a markdown plan document for orchestration.",
+		}),
 	),
 	cron: Type.Optional(
-		Type.String({ description: "Cron expression for recurring scheduled runs (e.g., '0 9 * * MON')." }),
+		Type.String({
+			description:
+				"Cron expression for recurring scheduled runs (e.g., '0 9 * * MON').",
+		}),
 	),
 	interval: Type.Optional(
-		Type.Number({ description: "Interval in milliseconds between recurring scheduled runs." }),
+		Type.Number({
+			description:
+				"Interval in milliseconds between recurring scheduled runs.",
+		}),
 	),
 	once: Type.Optional(
-		Type.Union([Type.String(), Type.Number()], { description: "ISO timestamp or epoch ms for a one-time scheduled run." }),
+		Type.Union([Type.String(), Type.Number()], {
+			description:
+				"ISO timestamp or epoch ms for a one-time scheduled run.",
+		}),
 	),
 	excludeContextBash: Type.Optional(
 		Type.Boolean({
-			description: "Mark certain bash commands as excludeFromContext to reduce context tokens (default: false).",
+			description:
+				"Mark certain bash commands as excludeFromContext to reduce context tokens (default: false).",
 		}),
 	),
 	// Budget tracking options
 	budgetTotal: Type.Optional(
 		Type.Number({
-			description: "Total token budget for the run. When set, enables budget tracking with default 80% warning and 95% abort thresholds.",
+			description:
+				"Total token budget for the run. When set, enables budget tracking with default 80% warning and 95% abort thresholds.",
 			minimum: 1,
 		}),
 	),
 	budgetWarning: Type.Optional(
 		Type.Number({
-			description: "Budget warning threshold as a fraction (0-1). Default: 0.8 (80%). Emits warning event when this threshold is crossed.",
+			description:
+				"Budget warning threshold as a fraction (0-1). Default: 0.8 (80%). Emits warning event when this threshold is crossed.",
 			minimum: 0,
 			maximum: 1,
 		}),
 	),
 	budgetAbort: Type.Optional(
 		Type.Number({
-			description: "Budget abort threshold as a fraction (0-1). Default: 0.95 (95%). Aborts further execution when this threshold is crossed.",
+			description:
+				"Budget abort threshold as a fraction (0-1). Default: 0.95 (95%). Aborts further execution when this threshold is crossed.",
 			minimum: 0,
 			maximum: 1,
 		}),

package/src/skills/discover-skills.ts

@@ -54,10 +54,16 @@ export function discoverSkills(cwd: string): SkillDescriptor[] {
 				} catch { continue; }
 				let description = "";
 				try {
-					const realPath = resolveRealContainedPath(dir.root, skillMdRelative);
-					const content = fs.readFileSync(realPath, "utf-8");
+					let readPath = skillMdPath;
+					try {
+						readPath = resolveRealContainedPath(dir.root, skillMdRelative);
+						skillMdPath = readPath;
+					} catch {
+						// resolveRealContainedPath may fail for symlinked system paths
+						// (e.g. macOS /var → /private/var). Fall through with un-resolved path.
+					}
+					const content = fs.readFileSync(readPath, "utf-8");
 					description = frontmatterDescription(content) ?? "";
-					skillMdPath = realPath;
 				} catch (error) {
 					logInternalError("discoverSkills.readSkill", error, `skill=${entry.name}`);
 				}