@pi-agents/orchid 0.1.0-beta.0

package/src/orchestrator/workspace.ts

@@ -0,0 +1,707 @@
+/**
+ * Workspace configuration loading and validation.
+ *
+ * Detects workspace mode by checking for `.pi/orchid-workspace.yaml`.
+ * When the file is present, it must be valid — invalid files are fatal.
+ * When absent, `loadWorkspaceConfig()` returns null and `buildExecutionContext()`
+ * decides repo-mode eligibility (cwd must be a git repository).
+ *
+ * Validation order (deterministic, fail-fast):
+ * 1. File existence check → absent = repo mode (return null)
+ * 2. File read → WORKSPACE_FILE_READ_ERROR
+ * 3. YAML parse → WORKSPACE_FILE_PARSE_ERROR
+ * 4. Top-level schema → WORKSPACE_SCHEMA_INVALID
+ * 5. repos map non-empty → WORKSPACE_MISSING_REPOS
+ * 6. Per-repo validation (sorted key order):
+ *    a. path present → WORKSPACE_REPO_PATH_MISSING
+ *    b. path exists on disk → WORKSPACE_REPO_PATH_NOT_FOUND
+ *    c. path is git repo → WORKSPACE_REPO_NOT_GIT
+ * 7. Duplicate repo paths → WORKSPACE_DUPLICATE_REPO_PATH
+ * 8. routing.tasks_root present → WORKSPACE_MISSING_TASKS_ROOT
+ * 9. routing.tasks_root exists → WORKSPACE_TASKS_ROOT_NOT_FOUND
+ * 10. routing.default_repo present → WORKSPACE_MISSING_DEFAULT_REPO
+ * 11. routing.default_repo valid → WORKSPACE_DEFAULT_REPO_NOT_FOUND
+ * 12. routing.task_packet_repo valid (or compat fallback) → WORKSPACE_TASK_PACKET_REPO_NOT_FOUND
+ * 13. routing.tasks_root inside packet-home repo → WORKSPACE_TASKS_ROOT_OUTSIDE_PACKET_REPO
+ *
+ * Path normalization rules:
+ * - Relative paths are resolved against workspaceRoot.
+ * - Existing paths are canonicalized via `fs.realpathSync.native()` to
+ *   expand Windows 8.3 short names and resolve symlinks.
+ * - All paths are forward-slash normalized and lowercased for comparison.
+ * - This matches the precedent in `worktree.ts:normalizePath()`.
+ *
+ * Git repo validation:
+ * - Uses `git rev-parse --git-dir` run inside the repo path.
+ * - The path must be the repo root (not a subdirectory).
+ *   We verify by checking that `git rev-parse --show-toplevel` matches
+ *   the canonicalized path.
+ *
+ * @module orch/workspace
+ */
+import { readFileSync, existsSync, realpathSync } from "fs";
+import { resolve, relative, isAbsolute } from "path";
+import { parse as yamlParse } from "yaml";
+
+import { runGit } from "./git.ts";
+import {
+	WorkspaceConfigError,
+	workspaceConfigPath,
+	pointerFilePath,
+	type WorkspaceConfig,
+	type WorkspaceRepoConfig,
+	type WorkspaceRoutingConfig,
+	type PointerResolution,
+} from "./types.ts";
+
+// ── Path Canonicalization ────────────────────────────────────────────
+
+/**
+ * Canonicalize a filesystem path for comparison and storage.
+ *
+ * Reuses the normalization pattern from `worktree.ts:normalizePath()`:
+ * - `realpathSync.native()` expands Windows 8.3 short names when the path exists.
+ * - Falls back to `resolve()` for non-existent paths.
+ * - Forward-slash normalized and lowercased for platform-safe comparison.
+ *
+ * @param p - Path to canonicalize (absolute or relative)
+ * @param base - Base directory for resolving relative paths
+ * @returns Canonical absolute path (forward-slash, lowercased)
+ */
+export function canonicalizePath(p: string, base: string): string {
+	const resolved = resolve(base, p);
+	let expanded: string;
+	try {
+		expanded = realpathSync.native(resolved);
+	} catch {
+		// Path doesn't exist yet — fall back to resolve()
+		expanded = resolved;
+	}
+	return expanded.replace(/\\/g, "/").toLowerCase();
+}
+
+/**
+ * Canonicalize a path for storage (absolute, native separators, resolved symlinks).
+ * Unlike canonicalizePath(), this preserves original case for display/config output.
+ *
+ * @param p - Path to resolve (absolute or relative)
+ * @param base - Base directory for resolving relative paths
+ * @returns Absolute resolved path (native separators preserved)
+ */
+function resolveAbsolutePath(p: string, base: string): string {
+	const resolved = resolve(base, p);
+	try {
+		return realpathSync.native(resolved);
+	} catch {
+		return resolved;
+	}
+}
+
+/**
+ * True when `childPath` is the same path as `parentPath` or contained within it.
+ * Uses canonicalized paths for cross-platform, case-insensitive comparison.
+ */
+function isPathWithinContainer(childPath: string, parentPath: string): boolean {
+	const child = canonicalizePath(childPath, "");
+	const parent = canonicalizePath(parentPath, "");
+	return child === parent || child.startsWith(`${parent}/`);
+}
+
+// ── Pointer Resolution ───────────────────────────────────────────────
+
+/**
+ * Resolve the workspace pointer file to find config and agent roots.
+ *
+ * The pointer file (`<workspace-root>/.pi/orchid-pointer.json`) tells
+ * OrchID where to find project config and agent overrides in workspace
+ * (polyrepo) mode. It's created by `orchid init` and is local-only
+ * (not committed to git).
+ *
+ * **Repo mode:** Returns null. The pointer is workspace-only — in repo
+ * mode it is never read, even if a file happens to exist on disk.
+ *
+ * **Workspace mode:** Reads and validates the pointer, then resolves
+ * config and agent roots. All failures are non-fatal:
+ * - Missing pointer file → warn + fallback
+ * - Malformed JSON → warn + fallback
+ * - Missing required fields → warn + fallback
+ * - Unknown config_repo (not in WorkspaceConfig.repos) → warn + fallback
+ * - Path traversal in config_path → warn + fallback
+ *
+ * Fallback paths: `<workspace-root>/.pi/` for config,
+ * `<workspace-root>/.pi/agents/` for agents.
+ *
+ * State/sidecar paths are NOT affected by the pointer and are not
+ * included in the return value — they always live at
+ * `<workspace-root>/.pi/` regardless.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory
+ * @param workspaceConfig - Loaded workspace config (null = repo mode → returns null)
+ * @returns PointerResolution with resolved paths, or null in repo mode
+ */
+export function resolvePointer(
+	workspaceRoot: string,
+	workspaceConfig: WorkspaceConfig | null,
+): PointerResolution | null {
+	// ── Repo mode: pointer is ignored entirely ───────────────────
+	if (workspaceConfig === null) {
+		return null;
+	}
+
+	const fallbackConfigRoot = resolve(workspaceRoot, ".pi");
+	const fallbackAgentRoot = resolve(workspaceRoot, ".pi", "agents");
+
+	const filePath = pointerFilePath(workspaceRoot);
+
+	// ── 1. File existence ────────────────────────────────────────
+	if (!existsSync(filePath)) {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file not found: ${filePath}. Run 'orchid init' to create it.`,
+		};
+	}
+
+	// ── 2. Read file ─────────────────────────────────────────────
+	let rawContent: string;
+	try {
+		rawContent = readFileSync(filePath, "utf-8");
+	} catch (err: unknown) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Cannot read pointer file ${filePath}: ${msg}`,
+		};
+	}
+
+	// ── 3. Parse JSON ────────────────────────────────────────────
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(rawContent);
+	} catch {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} contains invalid JSON.`,
+		};
+	}
+
+	// ── 4. Validate shape ────────────────────────────────────────
+	if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} must be a JSON object.`,
+		};
+	}
+
+	const doc = parsed as Record<string, unknown>;
+	const configRepo = doc.config_repo;
+	const configPath = doc.config_path;
+
+	if (!configRepo || typeof configRepo !== "string" || configRepo.trim() === "") {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} is missing required field 'config_repo'.`,
+		};
+	}
+
+	if (!configPath || typeof configPath !== "string" || configPath.trim() === "") {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} is missing required field 'config_path'.`,
+		};
+	}
+
+	// ── 5. Guard path traversal ──────────────────────────────────
+	const normalizedConfigPath = configPath.trim().replace(/\\/g, "/");
+
+	// Reject absolute paths (POSIX `/...` and Windows `C:/...`, `\\...`)
+	if (isAbsolute(normalizedConfigPath) || isAbsolute(configPath.trim())) {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} has invalid config_path '${configPath}' (absolute paths not allowed).`,
+		};
+	}
+
+	// Reject traversal sequences
+	if (
+		normalizedConfigPath.startsWith("..") ||
+		normalizedConfigPath.includes("/../") ||
+		normalizedConfigPath.endsWith("/..")
+	) {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} has invalid config_path '${configPath}' (path traversal not allowed).`,
+		};
+	}
+
+	// ── 6. Resolve config_repo against workspace repos map ──────
+	const repoId = configRepo.trim();
+	const repoConfig = workspaceConfig.repos.get(repoId);
+	if (!repoConfig) {
+		const available = Array.from(workspaceConfig.repos.keys()).join(", ");
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath}: config_repo '${repoId}' not found in workspace repos. Available repos: ${available}`,
+		};
+	}
+
+	// ── 7. Build resolved paths + containment check ──────────────
+	const resolvedConfigRoot = resolve(repoConfig.path, normalizedConfigPath);
+
+	// Verify the resolved path is within the repo root (defense-in-depth)
+	const rel = relative(repoConfig.path, resolvedConfigRoot);
+	if (rel.startsWith("..") || isAbsolute(rel)) {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} has invalid config_path '${configPath}' (resolved path escapes config repo root).`,
+		};
+	}
+
+	const resolvedAgentRoot = resolve(resolvedConfigRoot, "agents");
+
+	return {
+		used: true,
+		configRoot: resolvedConfigRoot,
+		agentRoot: resolvedAgentRoot,
+	};
+}
+
+// ── Workspace Config Loading ─────────────────────────────────────────
+
+/**
+ * Load and validate workspace configuration from `.pi/orchid-workspace.yaml`.
+ *
+ * Mode determination rules:
+ * 1. No config file → return null (repo mode, non-fatal, silent).
+ * 2. Config file present + invalid → throw WorkspaceConfigError (fatal).
+ * 3. Config file present + valid → return WorkspaceConfig (workspace mode).
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory
+ * @returns WorkspaceConfig if workspace mode, null if repo mode
+ * @throws WorkspaceConfigError when config file is present but invalid
+ */
+export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | null {
+	const configFile = workspaceConfigPath(workspaceRoot);
+
+	// ── 1. File existence check ──────────────────────────────────
+	if (!existsSync(configFile)) {
+		return null;
+	}
+
+	// ── 2. File read ─────────────────────────────────────────────
+	let rawContent: string;
+	try {
+		rawContent = readFileSync(configFile, "utf-8");
+	} catch (err: unknown) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new WorkspaceConfigError(
+			"WORKSPACE_FILE_READ_ERROR",
+			`Cannot read workspace config file: ${msg}`,
+			undefined,
+			configFile,
+		);
+	}
+
+	// ── 3. YAML parse ────────────────────────────────────────────
+	let parsed: unknown;
+	try {
+		parsed = yamlParse(rawContent);
+	} catch (err: unknown) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new WorkspaceConfigError(
+			"WORKSPACE_FILE_PARSE_ERROR",
+			`Invalid YAML in workspace config: ${msg}`,
+			undefined,
+			configFile,
+		);
+	}
+
+	// ── 4. Top-level schema validation ───────────────────────────
+	if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_SCHEMA_INVALID",
+			"Workspace config must be a YAML mapping (object), not a scalar or sequence.",
+			undefined,
+			configFile,
+		);
+	}
+	const doc = parsed as Record<string, unknown>;
+
+	if (!doc.repos || typeof doc.repos !== "object" || Array.isArray(doc.repos)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_SCHEMA_INVALID",
+			"Workspace config must contain a 'repos' mapping.",
+			undefined,
+			configFile,
+		);
+	}
+	if (!doc.routing || typeof doc.routing !== "object" || Array.isArray(doc.routing)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_SCHEMA_INVALID",
+			"Workspace config must contain a 'routing' mapping.",
+			undefined,
+			configFile,
+		);
+	}
+
+	// ── 5. Repos map non-empty ───────────────────────────────────
+	const rawRepos = doc.repos as Record<string, unknown>;
+	const repoKeys = Object.keys(rawRepos).sort(); // deterministic order
+	if (repoKeys.length === 0) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_MISSING_REPOS",
+			"Workspace config must define at least one repo under 'repos'.",
+			undefined,
+			configFile,
+		);
+	}
+
+	// ── 6. Per-repo validation ───────────────────────────────────
+	const repos = new Map<string, WorkspaceRepoConfig>();
+	const normalizedPaths = new Map<string, string>(); // normalized → repoId (for duplicate detection)
+
+	for (const repoId of repoKeys) {
+		const rawRepo = rawRepos[repoId];
+		if (rawRepo == null || typeof rawRepo !== "object" || Array.isArray(rawRepo)) {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_SCHEMA_INVALID",
+				`Repo '${repoId}' must be a YAML mapping with at least a 'path' field.`,
+				repoId,
+				configFile,
+			);
+		}
+		const repoEntry = rawRepo as Record<string, unknown>;
+
+		// 6a. path present and non-empty
+		const rawPath = repoEntry.path;
+		if (!rawPath || typeof rawPath !== "string" || rawPath.trim() === "") {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_REPO_PATH_MISSING",
+				`Repo '${repoId}' is missing a 'path' field.`,
+				repoId,
+				configFile,
+			);
+		}
+
+		// 6b. path exists on disk
+		const absolutePath = resolveAbsolutePath(rawPath.trim(), workspaceRoot);
+		const normalizedPath = canonicalizePath(rawPath.trim(), workspaceRoot);
+		if (!existsSync(absolutePath)) {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_REPO_PATH_NOT_FOUND",
+				`Repo '${repoId}' path does not exist: ${absolutePath}`,
+				repoId,
+				absolutePath,
+			);
+		}
+
+		// 6c. path is a git repo root
+		const gitDirCheck = runGit(["rev-parse", "--git-dir"], absolutePath);
+		if (!gitDirCheck.ok) {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_REPO_NOT_GIT",
+				`Repo '${repoId}' path is not a git repository: ${absolutePath}`,
+				repoId,
+				absolutePath,
+			);
+		}
+		// Verify we're at the root, not a subdirectory
+		const toplevelCheck = runGit(["rev-parse", "--show-toplevel"], absolutePath);
+		if (toplevelCheck.ok) {
+			const toplevelNormalized = canonicalizePath(toplevelCheck.stdout.trim(), "");
+			if (toplevelNormalized !== normalizedPath) {
+				throw new WorkspaceConfigError(
+					"WORKSPACE_REPO_NOT_GIT",
+					`Repo '${repoId}' path is a subdirectory of a git repo, not the repo root. Expected root: ${toplevelCheck.stdout.trim()}, got: ${absolutePath}`,
+					repoId,
+					absolutePath,
+				);
+			}
+		}
+
+		// 7. Collect for duplicate detection (checked after loop)
+		if (normalizedPaths.has(normalizedPath)) {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_DUPLICATE_REPO_PATH",
+				`Repos '${normalizedPaths.get(normalizedPath)}' and '${repoId}' share the same path: ${absolutePath}`,
+				repoId,
+				absolutePath,
+			);
+		}
+		normalizedPaths.set(normalizedPath, repoId);
+
+		// Build repo config
+		const defaultBranch =
+			typeof repoEntry.default_branch === "string" && repoEntry.default_branch.trim()
+				? repoEntry.default_branch.trim()
+				: undefined;
+
+		repos.set(repoId, {
+			id: repoId,
+			path: absolutePath,
+			defaultBranch,
+		});
+	}
+
+	// ── 8–11. Routing validation ─────────────────────────────────
+	const rawRouting = doc.routing as Record<string, unknown>;
+
+	// 8. routing.tasks_root present
+	const rawTasksRoot = rawRouting.tasks_root;
+	if (!rawTasksRoot || typeof rawTasksRoot !== "string" || rawTasksRoot.trim() === "") {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_MISSING_TASKS_ROOT",
+			"Workspace config 'routing.tasks_root' is missing or empty.",
+			undefined,
+			configFile,
+		);
+	}
+
+	// 9. routing.tasks_root exists on disk
+	const tasksRootAbsolute = resolveAbsolutePath(rawTasksRoot.trim(), workspaceRoot);
+	if (!existsSync(tasksRootAbsolute)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_TASKS_ROOT_NOT_FOUND",
+			`routing.tasks_root path does not exist: ${tasksRootAbsolute}`,
+			undefined,
+			tasksRootAbsolute,
+		);
+	}
+
+	// 10. routing.default_repo present
+	const rawDefaultRepo = rawRouting.default_repo;
+	if (!rawDefaultRepo || typeof rawDefaultRepo !== "string" || rawDefaultRepo.trim() === "") {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_MISSING_DEFAULT_REPO",
+			"Workspace config 'routing.default_repo' is missing or empty.",
+			undefined,
+			configFile,
+		);
+	}
+
+	// 11. routing.default_repo references a valid repo ID
+	const defaultRepoId = rawDefaultRepo.trim();
+	if (!repos.has(defaultRepoId)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_DEFAULT_REPO_NOT_FOUND",
+			`routing.default_repo '${defaultRepoId}' does not match any repo ID. Available repos: ${Array.from(repos.keys()).join(", ")}`,
+			undefined,
+			configFile,
+		);
+	}
+
+	// 12. routing.task_packet_repo (required by v1 contract)
+	// Compatibility policy: if omitted, default to routing.default_repo and
+	// emit a warning so legacy configs remain deterministic.
+	const hasTaskPacketRepo = Object.prototype.hasOwnProperty.call(rawRouting, "task_packet_repo");
+	const rawTaskPacketRepo = rawRouting.task_packet_repo;
+	let taskPacketRepoId = defaultRepoId;
+
+	if (hasTaskPacketRepo) {
+		if (typeof rawTaskPacketRepo !== "string" || rawTaskPacketRepo.trim() === "") {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_SCHEMA_INVALID",
+				"Workspace config 'routing.task_packet_repo' must be a non-empty string when provided.",
+				undefined,
+				configFile,
+			);
+		}
+		taskPacketRepoId = rawTaskPacketRepo.trim();
+	} else {
+		console.error(
+			`[orchid] workspace compatibility: 'routing.task_packet_repo' is missing in ${configFile}; defaulting to routing.default_repo ('${defaultRepoId}'). Add 'routing.task_packet_repo' explicitly.`,
+		);
+	}
+
+	if (!repos.has(taskPacketRepoId)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_TASK_PACKET_REPO_NOT_FOUND",
+			`routing.task_packet_repo '${taskPacketRepoId}' does not match any repo ID. Available repos: ${Array.from(repos.keys()).join(", ")}`,
+			undefined,
+			configFile,
+		);
+	}
+
+	// 13. tasks_root must be inside repos[task_packet_repo].path
+	const packetRepoPath = repos.get(taskPacketRepoId)!.path;
+	if (!isPathWithinContainer(tasksRootAbsolute, packetRepoPath)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_TASKS_ROOT_OUTSIDE_PACKET_REPO",
+			`routing.tasks_root '${tasksRootAbsolute}' must be inside packet-home repo '${taskPacketRepoId}' (${packetRepoPath}). Update routing.tasks_root or routing.task_packet_repo.`,
+			undefined,
+			tasksRootAbsolute,
+		);
+	}
+
+	// ── 14. routing.strict (optional boolean, default false) ─────
+	const rawStrict = rawRouting.strict;
+	if (rawStrict !== undefined) {
+		// null (from bare `strict:` or `strict: null` in YAML) is rejected
+		// to prevent fail-open: governance controls must be explicit.
+		if (rawStrict === null || typeof rawStrict !== "boolean") {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_SCHEMA_INVALID",
+				`routing.strict must be a boolean (true/false)${rawStrict === null ? ", got null (use true or false explicitly)" : `, got ${typeof rawStrict}: ${JSON.stringify(rawStrict)}`}`,
+				undefined,
+				configFile,
+			);
+		}
+	}
+	const strict = rawStrict === true;
+
+	// ── Build routing config ─────────────────────────────────────
+	const routing: WorkspaceRoutingConfig = {
+		tasksRoot: tasksRootAbsolute,
+		defaultRepo: defaultRepoId,
+		taskPacketRepo: taskPacketRepoId,
+		...(strict ? { strict: true } : {}),
+	};
+
+	// ── Build and return WorkspaceConfig ─────────────────────────
+	return {
+		mode: "workspace",
+		repos,
+		routing,
+		configPath: configFile,
+	};
+}
+
+// ── Cross-Config Validation ─────────────────────────────────────────
+
+/**
+ * Enforce that every configured task area resolves inside workspace routing.tasksRoot.
+ *
+ * This is a cross-config invariant and therefore runs after both workspace and
+ * task-runner configs are loaded.
+ */
+export function validateTaskAreasWithinTasksRoot(
+	workspaceRoot: string,
+	workspaceConfig: WorkspaceConfig,
+	taskRunnerConfig: import("./types.ts").TaskRunnerConfig,
+): void {
+	const tasksRoot = workspaceConfig.routing.tasksRoot;
+	const areaEntries = Object.entries(taskRunnerConfig.task_areas ?? {}).sort((a, b) =>
+		a[0].localeCompare(b[0]),
+	);
+
+	for (const [areaName, area] of areaEntries) {
+		const areaPathRaw = (area?.path ?? "").trim();
+		const areaAbsolute = resolveAbsolutePath(areaPathRaw, workspaceRoot);
+		if (!isPathWithinContainer(areaAbsolute, tasksRoot)) {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_TASK_AREA_OUTSIDE_TASKS_ROOT",
+				`Task area '${areaName}' path '${areaAbsolute}' must be inside routing.tasks_root '${tasksRoot}'. Move the area under tasks_root or update task_areas.${areaName}.path.`,
+				undefined,
+				areaAbsolute,
+			);
+		}
+	}
+}
+
+// ── Execution Context Builder ────────────────────────────────────────
+
+/**
+ * Build an ExecutionContext from the current working directory.
+ *
+ * This is the top-level entry point for Step 2 (wire orchestrator startup).
+ * It loads all configs, detects workspace mode, and returns a unified context.
+ *
+ * @param cwd - Current working directory
+ * @param loadOrchConfig - Orchestrator config loader (for testability)
+ * @param loadTaskConfig - Task runner config loader (for testability)
+ * @returns ExecutionContext ready for orchestrator consumption
+ * @throws WorkspaceConfigError if workspace config is present but invalid,
+ *   or when no workspace config exists and `cwd` is not a git repository.
+ */
+function isInsideGitRepo(cwd: string): boolean {
+	const probe = runGit(["rev-parse", "--is-inside-work-tree"], cwd);
+	return probe.ok && probe.stdout.trim() === "true";
+}
+
+export function buildExecutionContext(
+	cwd: string,
+	loadOrchConfig: (
+		root: string,
+		pointerConfigRoot?: string,
+	) => import("./types.ts").OrchestratorConfig,
+	loadTaskConfig: (
+		root: string,
+		pointerConfigRoot?: string,
+	) => import("./types.ts").TaskRunnerConfig,
+): import("./types.ts").ExecutionContext {
+	const workspaceConfig = loadWorkspaceConfig(cwd);
+
+	if (workspaceConfig === null) {
+		// Deterministic mode guard: without workspace config, repo mode is only
+		// valid when cwd is a git repository.
+		if (!isInsideGitRepo(cwd)) {
+			const wsConfigFile = workspaceConfigPath(cwd);
+			throw new WorkspaceConfigError(
+				"WORKSPACE_SETUP_REQUIRED",
+				`No workspace config found at ${wsConfigFile}, and current directory is not a git repository: ${cwd}. ` +
+					`Run OrchID from a git repository, or create ${wsConfigFile} (orchid init) to use workspace mode.`,
+				undefined,
+				cwd,
+			);
+		}
+
+		// Repo mode: pointer is ignored entirely. Config loads from cwd.
+		const orchestratorConfig = loadOrchConfig(cwd);
+		const taskRunnerConfig = loadTaskConfig(cwd);
+
+		return {
+			workspaceRoot: cwd,
+			repoRoot: cwd,
+			mode: "repo",
+			workspaceConfig: null,
+			orchestratorConfig,
+			taskRunnerConfig,
+			pointer: null,
+		};
+	}
+
+	// Workspace mode: resolve pointer once, pass configRoot to config loaders.
+	const pointer = resolvePointer(cwd, workspaceConfig);
+
+	// Log pointer warning once at startup (non-fatal).
+	if (pointer && pointer.warning) {
+		console.error(`[orchid] pointer warning: ${pointer.warning}`);
+	}
+
+	const pointerConfigRoot = pointer?.configRoot;
+	const orchestratorConfig = loadOrchConfig(cwd, pointerConfigRoot);
+	const taskRunnerConfig = loadTaskConfig(cwd, pointerConfigRoot);
+
+	// Cross-config invariant: every task-area path must live under routing.tasks_root.
+	validateTaskAreasWithinTasksRoot(cwd, workspaceConfig, taskRunnerConfig);
+
+	const defaultRepo = workspaceConfig.repos.get(workspaceConfig.routing.defaultRepo)!;
+	return {
+		workspaceRoot: cwd,
+		repoRoot: defaultRepo.path,
+		mode: "workspace",
+		workspaceConfig,
+		orchestratorConfig,
+		taskRunnerConfig,
+		pointer,
+	};
+}