taskplane 0.1.15 → 0.1.16

package/extensions/taskplane/index.ts

@@ -1,22 +1,23 @@
-/**
- * Task Orchestrator — barrel re-export
- *
- * Provides a single import point for all orchestrator modules.
- * Usage: import { executeOrchBatch, ... } from "./taskplane/index.ts";
- */
-
-export * from "./types.ts";
-export * from "./config.ts";
-export * from "./git.ts";
-export * from "./worktree.ts";
-export * from "./discovery.ts";
-export * from "./waves.ts";
-export * from "./formatting.ts";
-export * from "./execution.ts";
-export * from "./merge.ts";
-export * from "./messages.ts";
-export * from "./sessions.ts";
-export * from "./persistence.ts";
-export * from "./engine.ts";
-export * from "./resume.ts";
-export * from "./abort.ts";
+/**
+ * Task Orchestrator — barrel re-export
+ *
+ * Provides a single import point for all orchestrator modules.
+ * Usage: import { executeOrchBatch, ... } from "./taskplane/index.ts";
+ */
+
+export * from "./types.ts";
+export * from "./config.ts";
+export * from "./git.ts";
+export * from "./worktree.ts";
+export * from "./discovery.ts";
+export * from "./waves.ts";
+export * from "./formatting.ts";
+export * from "./execution.ts";
+export * from "./merge.ts";
+export * from "./messages.ts";
+export * from "./sessions.ts";
+export * from "./persistence.ts";
+export * from "./engine.ts";
+export * from "./resume.ts";
+export * from "./abort.ts";
+export * from "./workspace.ts";

package/extensions/taskplane/messages.ts

@@ -1,134 +1,146 @@
-/**
- * User-facing message templates (ORCH_MESSAGES)
- * @module orch/messages
- */
-import type { AbortMode } from "./types.ts";
-
-// ── Message Templates ────────────────────────────────────────────────
-
-/**
- * Deterministic message templates for user-facing /orch commands.
- * Ensures consistent UX across invocations.
- */
-export const ORCH_MESSAGES = {
-	// /orch
-	orchStarting: (batchId: string, waves: number, tasks: number) =>
-		`🚀 Starting batch ${batchId}: ${waves} wave(s), ${tasks} task(s)`,
-	orchWaveStart: (waveNum: number, totalWaves: number, tasks: number, lanes: number) =>
-		`\n🌊 Wave ${waveNum}/${totalWaves}: ${tasks} task(s) across ${lanes} lane(s)`,
-	orchWaveComplete: (waveNum: number, succeeded: number, failed: number, skipped: number, elapsedSec: number) =>
-		`✅ Wave ${waveNum} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped (${elapsedSec}s)`,
-	orchMergeStart: (waveNum: number, laneCount: number) =>
-		`🔀 [Wave ${waveNum}] Merging ${laneCount} lane(s) into develop...`,
-	orchMergeLaneSuccess: (laneNum: number, commit: string, durationSec: number) =>
-		`  ✅ Lane ${laneNum} merged (${commit.slice(0, 8)}, ${durationSec}s)`,
-	orchMergeLaneConflictResolved: (laneNum: number, conflictCount: number, durationSec: number) =>
-		`  ⚡ Lane ${laneNum} merged with ${conflictCount} auto-resolved conflict(s) (${durationSec}s)`,
-	orchMergeLaneFailed: (laneNum: number, reason: string) =>
-		`  ❌ Lane ${laneNum} merge failed: ${reason}`,
-	orchMergeComplete: (waveNum: number, mergedCount: number, totalSec: number) =>
-		`🔀 [Wave ${waveNum}] Merge complete: ${mergedCount} lane(s) merged (${totalSec}s)`,
-	orchMergeFailed: (waveNum: number, laneNum: number, reason: string) =>
-		`❌ [Wave ${waveNum}] Merge failed at lane ${laneNum}: ${reason}`,
-	orchMergeSkipped: (waveNum: number) =>
-		`📝 [Wave ${waveNum}] No successful lanes to merge`,
-	orchMergePlaceholder: (waveNum: number) =>
-		`🔀 [Wave ${waveNum}] Merge: placeholder — Step 3 (TS-008) will replace with mergeWave()`,
-	orchWorktreeReset: (waveNum: number, lanes: number) =>
-		`🔄 Resetting ${lanes} worktree(s) to develop HEAD after wave ${waveNum}`,
-	orchBatchComplete: (batchId: string, succeeded: number, failed: number, skipped: number, blocked: number, elapsedSec: number) =>
-		`\n🏁 Batch ${batchId} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped, ${blocked} blocked (${elapsedSec}s)`,
-	orchBatchFailed: (batchId: string, reason: string) =>
-		`\n❌ Batch ${batchId} failed: ${reason}`,
-	orchBatchStopped: (batchId: string, policy: string) =>
-		`\n⛔ Batch ${batchId} stopped by ${policy} policy`,
-
-	// /orch-pause
-	pauseNoBatch: () => "No active batch is running. Use /orch <areas|all> to start.",
-	pauseAlreadyPaused: (batchId: string) => `Batch ${batchId} is already paused.`,
-	pauseActivated: (batchId: string) =>
-		`⏸️  Pausing batch ${batchId}... lanes will stop after their current tasks complete.`,
-
-	// /orch-sessions
-	sessionsNone: () => "No orchestrator TMUX sessions found.",
-	sessionsHeader: (count: number) => `🖥️  ${count} orchestrator session(s):`,
-
-	// /orch orphan detection
-	orphanDetectionResume: (batchId: string, sessionCount: number) =>
-		`🔄 Found ${sessionCount} running orchestrator session(s) from batch ${batchId}.\n` +
-		`   Use /orch-resume to continue, or /orch-abort to clean up.`,
-	orphanDetectionAbort: (sessionCount: number) =>
-		`⚠️ Found ${sessionCount} orphan orchestrator session(s) without usable state.\n` +
-		`   Use /orch-abort to clean up before starting a new batch.`,
-	orphanDetectionCleanup: () =>
-		`🧹 Cleaned up stale batch state file. Starting fresh.`,
-
-	// /orch-resume
-	resumeStarting: (batchId: string, phase: string) =>
-		`🔄 Resuming batch ${batchId} (was: ${phase})...`,
-	resumeReconciled: (batchId: string, completed: number, pending: number, failed: number, reconnecting: number, reExecuting: number = 0) =>
-		`📊 Batch ${batchId} reconciliation: ${completed} completed, ${pending} pending, ${failed} failed, ${reconnecting} reconnecting` +
-		(reExecuting > 0 ? `, ${reExecuting} re-executing` : ""),
-	resumeSkippedWaves: (skippedCount: number) =>
-		`⏭️  Skipping ${skippedCount} completed wave(s)`,
-	resumeReconnecting: (sessionCount: number) =>
-		`🔗 Reconnecting to ${sessionCount} alive session(s)...`,
-	resumeNoState: () =>
-		`❌ No batch to resume. No batch-state.json file found.\n` +
-		`   Use /orch <areas|all> to start a new batch.`,
-	resumeInvalidState: (error: string) =>
-		`❌ Cannot resume: batch state file is invalid.\n` +
-		`   Error: ${error}\n` +
-		`   Delete .pi/batch-state.json and start a new batch.`,
-	resumePhaseNotResumable: (batchId: string, phase: string, reason: string) =>
-		`❌ Cannot resume batch ${batchId} (phase: ${phase}).\n` +
-		`   ${reason}`,
-	resumeComplete: (batchId: string, succeeded: number, failed: number, skipped: number, blocked: number, elapsedSec: number) =>
-		`\n🏁 Resumed batch ${batchId} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped, ${blocked} blocked (${elapsedSec}s total)`,
-
-	// /orch-abort
-	abortGracefulStarting: (batchId: string, sessionCount: number) =>
-		`⏳ Graceful abort of batch ${batchId}: signaling ${sessionCount} session(s) to checkpoint and exit...`,
-	abortGracefulWaiting: (batchId: string, graceSec: number) =>
-		`⏳ Waiting up to ${graceSec}s for sessions to checkpoint and exit...`,
-	abortGracefulForceKill: (count: number) =>
-		`⚠️ Force-killing ${count} session(s) that did not exit within timeout`,
-	abortGracefulComplete: (batchId: string, graceful: number, forceKilled: number, durationSec: number) =>
-		`✅ Graceful abort complete for batch ${batchId}: ${graceful} exited gracefully, ${forceKilled} force-killed (${durationSec}s)`,
-	abortHardStarting: (batchId: string, sessionCount: number) =>
-		`⚡ Hard abort of batch ${batchId}: killing ${sessionCount} session(s) immediately...`,
-	abortHardComplete: (batchId: string, killed: number, durationSec: number) =>
-		`✅ Hard abort complete for batch ${batchId}: ${killed} session(s) killed (${durationSec}s)`,
-	abortPartialFailure: (failureCount: number) =>
-		`⚠️ ${failureCount} error(s) during abort (see details above)`,
-	abortNoBatch: () =>
-		`No active batch to abort. Use /orch <areas|all> to start a batch.`,
-	abortComplete: (mode: AbortMode, sessionsKilled: number) =>
-		`🏁 Abort (${mode}) complete: ${sessionsKilled} session(s) terminated. Worktrees and branches preserved.`,
-} as const;
-
-
-// ── Resume ORCH_MESSAGES ─────────────────────────────────────────────
-
-// Note: These are added via extension to the ORCH_MESSAGES object below.
-
-// ── Resume Orchestration ─────────────────────────────────────────────
-
-/**
- * Resume an interrupted batch from persisted state.
- *
- * Flow:
- * 1. Load and validate batch-state.json
- * 2. Check phase eligibility (paused/executing/merging only)
- * 3. Check for alive TMUX sessions and .DONE files
- * 4. Reconcile persisted state against live signals
- * 5. Compute resume point (which wave to start from)
- * 6. Reconstruct runtime state and continue execution
- *
- * @param orchConfig     - Orchestrator configuration
- * @param runnerConfig   - Task runner configuration
- * @param cwd            - Repository root
- * @param batchState     - Mutable batch state (will be populated from persisted state)
- * @param onNotify       - Callback for user-facing messages
- * @param onMonitorUpdate - Optional callback for dashboard updates
- */
+/**
+ * User-facing message templates (ORCH_MESSAGES)
+ * @module orch/messages
+ */
+import type { AbortMode } from "./types.ts";
+
+// ── Message Templates ────────────────────────────────────────────────
+
+/**
+ * Deterministic message templates for user-facing /orch commands.
+ * Ensures consistent UX across invocations.
+ */
+export const ORCH_MESSAGES = {
+	// /orch
+	orchStarting: (batchId: string, waves: number, tasks: number) =>
+		`🚀 Starting batch ${batchId}: ${waves} wave(s), ${tasks} task(s)`,
+	orchWaveStart: (waveNum: number, totalWaves: number, tasks: number, lanes: number) =>
+		`\n🌊 Wave ${waveNum}/${totalWaves}: ${tasks} task(s) across ${lanes} lane(s)`,
+	orchWaveComplete: (waveNum: number, succeeded: number, failed: number, skipped: number, elapsedSec: number) =>
+		`✅ Wave ${waveNum} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped (${elapsedSec}s)`,
+	orchMergeStart: (waveNum: number, laneCount: number) =>
+		`🔀 [Wave ${waveNum}] Merging ${laneCount} lane(s) into develop...`,
+	orchMergeLaneSuccess: (laneNum: number, commit: string, durationSec: number) =>
+		`  ✅ Lane ${laneNum} merged (${commit.slice(0, 8)}, ${durationSec}s)`,
+	orchMergeLaneConflictResolved: (laneNum: number, conflictCount: number, durationSec: number) =>
+		`  ⚡ Lane ${laneNum} merged with ${conflictCount} auto-resolved conflict(s) (${durationSec}s)`,
+	orchMergeLaneFailed: (laneNum: number, reason: string) =>
+		`  ❌ Lane ${laneNum} merge failed: ${reason}`,
+	orchMergeComplete: (waveNum: number, mergedCount: number, totalSec: number) =>
+		`🔀 [Wave ${waveNum}] Merge complete: ${mergedCount} lane(s) merged (${totalSec}s)`,
+	orchMergeFailed: (waveNum: number, laneNum: number, reason: string) =>
+		`❌ [Wave ${waveNum}] Merge failed at lane ${laneNum}: ${reason}`,
+	orchMergeSkipped: (waveNum: number) =>
+		`📝 [Wave ${waveNum}] No successful lanes to merge`,
+	orchMergePlaceholder: (waveNum: number) =>
+		`🔀 [Wave ${waveNum}] Merge: placeholder — Step 3 (TS-008) will replace with mergeWave()`,
+	orchWorktreeReset: (waveNum: number, lanes: number) =>
+		`🔄 Resetting ${lanes} worktree(s) to develop HEAD after wave ${waveNum}`,
+	orchBatchComplete: (batchId: string, succeeded: number, failed: number, skipped: number, blocked: number, elapsedSec: number) => {
+		const lines = [`\n🏁 Batch ${batchId} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped, ${blocked} blocked (${elapsedSec}s)`];
+		if (failed > 0 || blocked > 0) {
+			lines.push("");
+			if (blocked > 0) {
+				lines.push(`   ${blocked} task(s) were blocked because upstream tasks failed.`);
+			}
+			lines.push("   Next steps:");
+			lines.push("   • /orch-status     — review what failed and why");
+			lines.push("   • /orch-resume     — retry from the failed wave");
+			lines.push("   • /orch-abort      — clean up and start fresh");
+		}
+		return lines.join("\n");
+	},
+	orchBatchFailed: (batchId: string, reason: string) =>
+		`\n❌ Batch ${batchId} failed: ${reason}`,
+	orchBatchStopped: (batchId: string, policy: string) =>
+		`\n⛔ Batch ${batchId} stopped by ${policy} policy`,
+
+	// /orch-pause
+	pauseNoBatch: () => "No active batch is running. Use /orch <areas|all> to start.",
+	pauseAlreadyPaused: (batchId: string) => `Batch ${batchId} is already paused.`,
+	pauseActivated: (batchId: string) =>
+		`⏸️  Pausing batch ${batchId}... lanes will stop after their current tasks complete.`,
+
+	// /orch-sessions
+	sessionsNone: () => "No orchestrator TMUX sessions found.",
+	sessionsHeader: (count: number) => `🖥️  ${count} orchestrator session(s):`,
+
+	// /orch orphan detection
+	orphanDetectionResume: (batchId: string, sessionCount: number) =>
+		`🔄 Found ${sessionCount} running orchestrator session(s) from batch ${batchId}.\n` +
+		`   Use /orch-resume to continue, or /orch-abort to clean up.`,
+	orphanDetectionAbort: (sessionCount: number) =>
+		`⚠️ Found ${sessionCount} orphan orchestrator session(s) without usable state.\n` +
+		`   Use /orch-abort to clean up before starting a new batch.`,
+	orphanDetectionCleanup: () =>
+		`🧹 Cleaned up stale batch state file. Starting fresh.`,
+
+	// /orch-resume
+	resumeStarting: (batchId: string, phase: string) =>
+		`🔄 Resuming batch ${batchId} (was: ${phase})...`,
+	resumeReconciled: (batchId: string, completed: number, pending: number, failed: number, reconnecting: number, reExecuting: number = 0) =>
+		`📊 Batch ${batchId} reconciliation: ${completed} completed, ${pending} pending, ${failed} failed, ${reconnecting} reconnecting` +
+		(reExecuting > 0 ? `, ${reExecuting} re-executing` : ""),
+	resumeSkippedWaves: (skippedCount: number) =>
+		`⏭️  Skipping ${skippedCount} completed wave(s)`,
+	resumeReconnecting: (sessionCount: number) =>
+		`🔗 Reconnecting to ${sessionCount} alive session(s)...`,
+	resumeNoState: () =>
+		`❌ No batch to resume. No batch-state.json file found.\n` +
+		`   Use /orch <areas|all> to start a new batch.`,
+	resumeInvalidState: (error: string) =>
+		`❌ Cannot resume: batch state file is invalid.\n` +
+		`   Error: ${error}\n` +
+		`   Delete .pi/batch-state.json and start a new batch.`,
+	resumePhaseNotResumable: (batchId: string, phase: string, reason: string) =>
+		`❌ Cannot resume batch ${batchId} (phase: ${phase}).\n` +
+		`   ${reason}`,
+	resumeComplete: (batchId: string, succeeded: number, failed: number, skipped: number, blocked: number, elapsedSec: number) =>
+		`\n🏁 Resumed batch ${batchId} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped, ${blocked} blocked (${elapsedSec}s total)`,
+
+	// /orch-abort
+	abortGracefulStarting: (batchId: string, sessionCount: number) =>
+		`⏳ Graceful abort of batch ${batchId}: signaling ${sessionCount} session(s) to checkpoint and exit...`,
+	abortGracefulWaiting: (batchId: string, graceSec: number) =>
+		`⏳ Waiting up to ${graceSec}s for sessions to checkpoint and exit...`,
+	abortGracefulForceKill: (count: number) =>
+		`⚠️ Force-killing ${count} session(s) that did not exit within timeout`,
+	abortGracefulComplete: (batchId: string, graceful: number, forceKilled: number, durationSec: number) =>
+		`✅ Graceful abort complete for batch ${batchId}: ${graceful} exited gracefully, ${forceKilled} force-killed (${durationSec}s)`,
+	abortHardStarting: (batchId: string, sessionCount: number) =>
+		`⚡ Hard abort of batch ${batchId}: killing ${sessionCount} session(s) immediately...`,
+	abortHardComplete: (batchId: string, killed: number, durationSec: number) =>
+		`✅ Hard abort complete for batch ${batchId}: ${killed} session(s) killed (${durationSec}s)`,
+	abortPartialFailure: (failureCount: number) =>
+		`⚠️ ${failureCount} error(s) during abort (see details above)`,
+	abortNoBatch: () =>
+		`No active batch to abort. Use /orch <areas|all> to start a batch.`,
+	abortComplete: (mode: AbortMode, sessionsKilled: number) =>
+		`🏁 Abort (${mode}) complete: ${sessionsKilled} session(s) terminated. Worktrees and branches preserved.`,
+} as const;
+
+
+// ── Resume ORCH_MESSAGES ─────────────────────────────────────────────
+
+// Note: These are added via extension to the ORCH_MESSAGES object below.
+
+// ── Resume Orchestration ─────────────────────────────────────────────
+
+/**
+ * Resume an interrupted batch from persisted state.
+ *
+ * Flow:
+ * 1. Load and validate batch-state.json
+ * 2. Check phase eligibility (paused/executing/merging only)
+ * 3. Check for alive TMUX sessions and .DONE files
+ * 4. Reconcile persisted state against live signals
+ * 5. Compute resume point (which wave to start from)
+ * 6. Reconstruct runtime state and continue execution
+ *
+ * @param orchConfig     - Orchestrator configuration
+ * @param runnerConfig   - Task runner configuration
+ * @param cwd            - Repository root
+ * @param batchState     - Mutable batch state (will be populated from persisted state)
+ * @param onNotify       - Callback for user-facing messages
+ * @param onMonitorUpdate - Optional callback for dashboard updates
+ */

package/extensions/taskplane/resume.ts

@@ -14,9 +14,9 @@ import { mergeWave } from "./merge.ts";
 import { ORCH_MESSAGES } from "./messages.ts";
 import { deleteBatchState, hasTaskDoneMarker, loadBatchState, persistRuntimeState, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
 import { StateFileError } from "./types.ts";
-import type { AllocatedLane, AllocatedTask, LaneExecutionResult, LaneTaskOutcome, LaneTaskStatus, MergeWaveResult, OrchBatchPhase, OrchBatchRuntimeState, OrchestratorConfig, ParsedTask, PersistedBatchState, ReconciledTaskState, ResumeEligibility, ResumePoint, TaskRunnerConfig, WaveExecutionResult } from "./types.ts";
+import type { AllocatedLane, AllocatedTask, LaneExecutionResult, LaneTaskOutcome, LaneTaskStatus, MergeWaveResult, OrchBatchPhase, OrchBatchRuntimeState, OrchestratorConfig, ParsedTask, PersistedBatchState, ReconciledTaskState, ResumeEligibility, ResumePoint, TaskRunnerConfig, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
 import { buildDependencyGraph } from "./waves.ts";
-import { deleteBranchBestEffort, listWorktrees, removeAllWorktrees, removeWorktree, safeResetWorktree } from "./worktree.ts";
+import { deleteBranchBestEffort, forceCleanupWorktree, listWorktrees, removeAllWorktrees, removeWorktree, safeResetWorktree } from "./worktree.ts";
 
 // ── Resume Pure Functions ────────────────────────────────────────────
 
@@ -335,6 +335,7 @@ export async function resumeOrchBatch(
 	batchState: OrchBatchRuntimeState,
 	onNotify: (message: string, level: "info" | "warning" | "error") => void,
 	onMonitorUpdate?: MonitorUpdateCallback,
+	workspaceConfig?: WorkspaceConfig | null,
 ): Promise<void> {
 	const repoRoot = cwd;
 	const prefix = orchConfig.orchestrator.tmux_prefix;
@@ -464,6 +465,7 @@ export async function resumeOrchBatch(
 		refreshDependencies: false,
 		dependencySource: orchConfig.dependencies.source,
 		useDependencyCache: orchConfig.dependencies.cache,
+		workspaceConfig: workspaceConfig ?? null,
 	});
 
 	// Build dependency graph for skip-dependents policy
@@ -1041,7 +1043,11 @@ export async function resumeOrchBatch(
 				for (const wt of existingWorktrees) {
 					const resetResult = safeResetWorktree(wt, targetBranch, repoRoot);
 					if (!resetResult.success) {
-						try { removeWorktree(wt, repoRoot); } catch { /* best effort */ }
+						try {
+							removeWorktree(wt, repoRoot);
+						} catch {
+							forceCleanupWorktree(wt, repoRoot, batchState.batchId);
+						}
 					}
 				}
 			}

package/extensions/taskplane/types.ts

@@ -59,6 +59,10 @@ export interface ParsedTask {
 	promptPath: string;
 	areaName: string;
 	status: "pending" | "complete";
+	/** Repo ID declared in the PROMPT metadata (e.g., "api", "frontend"). Undefined if not declared. */
+	promptRepoId?: string;
+	/** Resolved repo ID after routing precedence (workspace mode only). Undefined in repo mode. */
+	resolvedRepoId?: string;
 }
 
 /** A wave: a group of tasks whose dependencies are all satisfied */
@@ -105,6 +109,8 @@ export interface TaskArea {
 	path: string;
 	prefix: string;
 	context: string;
+	/** Optional repo ID for routing tasks in this area (workspace mode only). */
+	repoId?: string;
 }
 
 /** Subset of task-runner.yaml that the orchestrator needs */
@@ -359,12 +365,31 @@ export interface DiscoveryError {
 		| "DEP_UNRESOLVED"
 		| "DEP_PENDING"
 		| "DEP_AMBIGUOUS"
-		| "DEP_SOURCE_FALLBACK";
+		| "DEP_SOURCE_FALLBACK"
+		| "TASK_REPO_UNRESOLVED"
+		| "TASK_REPO_UNKNOWN";
 	message: string;
 	taskPath?: string;
 	taskId?: string;
 }
 
+/**
+ * Discovery error codes that are fatal (block planning/execution).
+ *
+ * Used by formatDiscoveryResults, extension.ts, and engine.ts for
+ * consistent fatal-error classification. Keep in sync with the
+ * DiscoveryError.code union above.
+ */
+export const FATAL_DISCOVERY_CODES: ReadonlyArray<DiscoveryError["code"]> = [
+	"DUPLICATE_ID",
+	"DEP_UNRESOLVED",
+	"DEP_PENDING",
+	"DEP_AMBIGUOUS",
+	"PARSE_MISSING_ID",
+	"TASK_REPO_UNRESOLVED",
+	"TASK_REPO_UNKNOWN",
+] as const;
+
 /** Result of the full discovery pipeline */
 export interface DiscoveryResult {
 	pending: Map<string, ParsedTask>;
@@ -1519,3 +1544,215 @@ export interface BatchHistorySummary {
 /** Max number of batch history entries to retain. */
 export const BATCH_HISTORY_MAX_ENTRIES = 100;
 
+
+// ── Workspace Mode Types ─────────────────────────────────────────────
+
+/**
+ * Workspace execution mode.
+ *
+ * Mode behavior contract:
+ * - **"repo"** (default): No workspace config file present. The orchestrator
+ *   treats `cwd` as both the workspace root and the single repo root.
+ *   All existing monorepo behavior is preserved unchanged.
+ * - **"workspace"**: A `.pi/taskplane-workspace.yaml` file is present and
+ *   valid. The orchestrator runs from a non-git workspace root that
+ *   coordinates multiple repos and a shared task root.
+ *
+ * Mode determination rules:
+ * 1. No workspace config file → repo mode (non-fatal default, silent).
+ * 2. Workspace config file present + invalid → fatal error with actionable
+ *    `WorkspaceConfigError` (never silently falls back to repo mode).
+ * 3. Workspace config file present + valid → workspace mode.
+ */
+export type WorkspaceMode = "repo" | "workspace";
+
+/**
+ * Configuration for a single repository within a workspace.
+ *
+ * Each repo is identified by a stable ID (e.g., "api", "frontend")
+ * that is used for routing tasks to repos and for display purposes.
+ */
+export interface WorkspaceRepoConfig {
+	/** Stable identifier for this repo (e.g., "api", "frontend") */
+	id: string;
+	/** Absolute filesystem path to the repo root (must be a git repo) */
+	path: string;
+	/** Optional default branch override (e.g., "develop", "main"). Falls back to repo HEAD. */
+	defaultBranch?: string;
+}
+
+/**
+ * Routing configuration for workspace mode.
+ *
+ * Controls where tasks are discovered and which repo receives
+ * unqualified operations.
+ */
+export interface WorkspaceRoutingConfig {
+	/**
+	 * Absolute path to the shared tasks root directory.
+	 * All task areas are resolved relative to this path.
+	 * Must exist on disk.
+	 */
+	tasksRoot: string;
+	/**
+	 * Default repo ID for operations that don't specify a repo.
+	 * Must reference a valid key in `WorkspaceConfig.repos`.
+	 */
+	defaultRepo: string;
+}
+
+/**
+ * Top-level workspace configuration.
+ *
+ * Loaded from `.pi/taskplane-workspace.yaml` when present.
+ * Immutable after initial validation — never mutated at runtime.
+ */
+export interface WorkspaceConfig {
+	/** Active workspace mode */
+	mode: WorkspaceMode;
+	/** Map of repo ID → repo configuration. At least one repo required in workspace mode. */
+	repos: Map<string, WorkspaceRepoConfig>;
+	/** Routing configuration (tasks root, default repo) */
+	routing: WorkspaceRoutingConfig;
+	/** Absolute path to the workspace config file that was loaded */
+	configPath: string;
+}
+
+/**
+ * Canonical execution context for the orchestrator.
+ *
+ * This is the primary runtime context threaded through orchestrator
+ * entry points. It replaces the previous pattern of passing raw `cwd`
+ * as the sole repo root.
+ *
+ * In repo mode, `workspaceRoot` and `repoRoot` are the same directory.
+ * In workspace mode, `workspaceRoot` is the non-git coordination root
+ * and `repoRoot` is the default repo from the workspace config.
+ *
+ * Design rationale:
+ * - Step 2 (wire orchestrator startup) will construct this from config
+ *   loading results and thread it into `executeOrchBatch()` and friends.
+ * - `repoRoot` is always a git repository, preserving the invariant
+ *   that git operations (worktree, branch, merge) have a valid target.
+ * - `workspaceConfig` is null in repo mode (no workspace file loaded).
+ */
+export interface ExecutionContext {
+	/** Absolute path to the workspace root (cwd in repo mode, workspace dir in workspace mode) */
+	workspaceRoot: string;
+	/** Absolute path to the default/primary git repo root */
+	repoRoot: string;
+	/** Active workspace mode */
+	mode: WorkspaceMode;
+	/** Workspace configuration (null in repo mode) */
+	workspaceConfig: WorkspaceConfig | null;
+	/** Loaded task runner configuration */
+	taskRunnerConfig: TaskRunnerConfig;
+	/** Loaded orchestrator configuration */
+	orchestratorConfig: OrchestratorConfig;
+}
+
+
+// ── Workspace Validation Error Types ─────────────────────────────────
+
+/**
+ * Error codes for workspace configuration validation failures.
+ *
+ * Each code maps to a deterministic validation rule from the workspace
+ * config loading pipeline. Codes are stable and machine-branchable.
+ *
+ * - WORKSPACE_FILE_READ_ERROR: Config file exists but cannot be read (permissions, encoding)
+ * - WORKSPACE_FILE_PARSE_ERROR: Config file contains invalid YAML
+ * - WORKSPACE_MISSING_REPOS: No repos defined in workspace config (at least one required)
+ * - WORKSPACE_REPO_PATH_MISSING: A repo entry has no `path` field
+ * - WORKSPACE_REPO_PATH_NOT_FOUND: A repo's `path` does not exist on disk
+ * - WORKSPACE_REPO_NOT_GIT: A repo's `path` exists but is not a git repository
+ * - WORKSPACE_MISSING_TASKS_ROOT: `routing.tasks_root` is missing or empty
+ * - WORKSPACE_TASKS_ROOT_NOT_FOUND: `routing.tasks_root` path does not exist on disk
+ * - WORKSPACE_MISSING_DEFAULT_REPO: `routing.default_repo` is missing or empty
+ * - WORKSPACE_DEFAULT_REPO_NOT_FOUND: `routing.default_repo` references a repo ID not in the repos map
+ * - WORKSPACE_DUPLICATE_REPO_PATH: Two or more repos share the same filesystem path
+ * - WORKSPACE_SCHEMA_INVALID: Config file has valid YAML but missing/invalid top-level structure
+ */
+export type WorkspaceConfigErrorCode =
+	| "WORKSPACE_FILE_READ_ERROR"
+	| "WORKSPACE_FILE_PARSE_ERROR"
+	| "WORKSPACE_MISSING_REPOS"
+	| "WORKSPACE_REPO_PATH_MISSING"
+	| "WORKSPACE_REPO_PATH_NOT_FOUND"
+	| "WORKSPACE_REPO_NOT_GIT"
+	| "WORKSPACE_MISSING_TASKS_ROOT"
+	| "WORKSPACE_TASKS_ROOT_NOT_FOUND"
+	| "WORKSPACE_MISSING_DEFAULT_REPO"
+	| "WORKSPACE_DEFAULT_REPO_NOT_FOUND"
+	| "WORKSPACE_DUPLICATE_REPO_PATH"
+	| "WORKSPACE_SCHEMA_INVALID";
+
+/**
+ * Typed error class for workspace configuration failures.
+ *
+ * Thrown during workspace config loading/validation when the config file
+ * is present but invalid. Never thrown when no config file exists (that
+ * case silently falls back to repo mode).
+ *
+ * Follows the established pattern of typed error classes in this module
+ * (WorktreeError, ExecutionError, MergeError, StateFileError, ResumeError).
+ */
+export class WorkspaceConfigError extends Error {
+	code: WorkspaceConfigErrorCode;
+	/** Optional repo ID that triggered the error (for repo-specific validation failures) */
+	repoId?: string;
+	/** Optional filesystem path related to the error */
+	relatedPath?: string;
+
+	constructor(code: WorkspaceConfigErrorCode, message: string, repoId?: string, relatedPath?: string) {
+		super(message);
+		this.name = "WorkspaceConfigError";
+		this.code = code;
+		this.repoId = repoId;
+		this.relatedPath = relatedPath;
+	}
+}
+
+
+// ── Workspace Defaults ───────────────────────────────────────────────
+
+/**
+ * Canonical filename for workspace configuration.
+ * Resolved relative to workspace root: `.pi/taskplane-workspace.yaml`
+ */
+export const WORKSPACE_CONFIG_FILENAME = "taskplane-workspace.yaml";
+
+/**
+ * Resolve the absolute path to the workspace config file.
+ * @param workspaceRoot - Absolute path to the workspace root
+ */
+export function workspaceConfigPath(workspaceRoot: string): string {
+	return join(workspaceRoot, ".pi", WORKSPACE_CONFIG_FILENAME);
+}
+
+/**
+ * Create a default ExecutionContext for repo mode.
+ *
+ * Used when no workspace config file is present. The workspace root
+ * and repo root are the same directory (cwd), preserving existing
+ * monorepo behavior exactly.
+ *
+ * @param cwd - Current working directory (treated as both workspace and repo root)
+ * @param taskRunnerConfig - Loaded task runner config (or defaults)
+ * @param orchestratorConfig - Loaded orchestrator config (or defaults)
+ */
+export function createRepoModeContext(
+	cwd: string,
+	taskRunnerConfig: TaskRunnerConfig,
+	orchestratorConfig: OrchestratorConfig,
+): ExecutionContext {
+	return {
+		workspaceRoot: cwd,
+		repoRoot: cwd,
+		mode: "repo",
+		workspaceConfig: null,
+		taskRunnerConfig,
+		orchestratorConfig,
+	};
+}
+