taskplane 0.22.4 → 0.22.6

package/dashboard/server.cjs

@@ -792,7 +792,17 @@ function computeBatchTotalCost(laneStates, telemetry) {
 function buildDashboardState() {
   const state = loadBatchState();
   const tmuxSessions = getTmuxSessions();
-  const laneStates = loadLaneStates();
+  const rawLaneStates = loadLaneStates();
+  // Filter stale lane states from previous batches.
+  // Lane state files persist across batches (same filename), so without
+  // filtering the dashboard shows telemetry from old runs.
+  const currentBatchId = state?.batchId || null;
+  const laneStates = {};
+  for (const [key, ls] of Object.entries(rawLaneStates)) {
+    if (!currentBatchId || !ls.batchId || ls.batchId === currentBatchId) {
+      laneStates[key] = ls;
+    }
+  }
   const telemetry = loadTelemetryData(state);
   const batchTotalCost = computeBatchTotalCost(laneStates, telemetry);
   const supervisor = loadSupervisorData(state);

package/extensions/task-runner.ts

@@ -447,6 +447,7 @@ function writeLaneState(state: TaskState): void {
 			reviewerOutputTokens: state.reviewerOutputTokens || 0,
 			reviewerCacheReadTokens: state.reviewerCacheReadTokens || 0,
 			reviewerCacheWriteTokens: state.reviewerCacheWriteTokens || 0,
+			batchId: process.env.ORCH_BATCH_ID || null,
 			timestamp: Date.now(),
 		};
 		writeFileSync(filePath, JSON.stringify(data) + "\n");
@@ -2554,7 +2555,22 @@ export default function (pi: ExtensionAPI) {
 						reviewContent, statusPath, num, reviewType, stepNum, state.reviewCounter,
 					);
 
-					// Set reviewer to idle (NOT clear — persistent session stays alive)
+					// After code review: kill the persistent reviewer to free context.
+					// The reviewer persists through a plan+code pair for one step,
+					// then gets a fresh session for the next step.
+					if (reviewType === "code") {
+						console.error(`[task-runner] code review complete for step ${stepNum} — killing reviewer for fresh context on next step`);
+						logExecution(statusPath, `Reviewer R${num}`,
+							`code review complete — killing persistent reviewer (step ${stepNum} cycle done)`);
+						if (state.persistentReviewerKill) {
+							try { state.persistentReviewerKill(); } catch {}
+						}
+						state.persistentReviewerSession = null;
+						state.persistentReviewerKill = null;
+						state.persistentReviewerSignalNum = 0;
+						state.reviewerRespawnCount = 0;
+					}
+
 					state.reviewerStatus = "idle";
 					state.reviewerType = "";
 					state.reviewerStep = 0;
@@ -2642,6 +2658,9 @@ export default function (pi: ExtensionAPI) {
 							fallbackContent, statusPath, num, reviewType, stepNum, state.reviewCounter, "fallback",
 						);
 
+						// Reset respawn counter on successful fallback review
+						state.reviewerRespawnCount = 0;
+
 						clearReviewerState();
 						writeLaneState(state);
 						updateWidgets();

package/extensions/taskplane/config-loader.ts

@@ -43,6 +43,7 @@ import type {
 	TaskplaneConfig,
 	TaskRunnerSection,
 	OrchestratorSection,
+	WorkspaceSectionConfig,
 	UserPreferences,
 } from "./config-schema.ts";
 
@@ -270,6 +271,71 @@ function mapOrchestratorYaml(raw: any): Partial<OrchestratorSection> {
 	return result;
 }
 
+/**
+ * Normalize a workspace section loaded from JSON/YAML into camelCase shape.
+ *
+ * Compatibility: if `routing.taskPacketRepo` is missing, defaults to
+ * `routing.defaultRepo` and emits a warning message.
+ */
+function normalizeWorkspaceSection(
+	rawWorkspace: any,
+	sourcePath: string,
+): WorkspaceSectionConfig | undefined {
+	if (!rawWorkspace || typeof rawWorkspace !== "object" || Array.isArray(rawWorkspace)) {
+		return undefined;
+	}
+
+	const rawRepos = rawWorkspace.repos;
+	if (!rawRepos || typeof rawRepos !== "object" || Array.isArray(rawRepos)) {
+		return undefined;
+	}
+
+	const rawRouting = rawWorkspace.routing;
+	if (!rawRouting || typeof rawRouting !== "object" || Array.isArray(rawRouting)) {
+		return undefined;
+	}
+
+	const repos: WorkspaceSectionConfig["repos"] = {};
+	for (const [repoId, repoVal] of Object.entries(rawRepos as Record<string, any>)) {
+		if (!repoVal || typeof repoVal !== "object" || Array.isArray(repoVal)) continue;
+		const repoObj = repoVal as Record<string, any>;
+		if (typeof repoObj.path !== "string" || repoObj.path.trim() === "") continue;
+		repos[repoId] = {
+			path: repoObj.path,
+			...(typeof repoObj.defaultBranch === "string" && repoObj.defaultBranch.trim()
+				? { defaultBranch: repoObj.defaultBranch }
+				: {}),
+		};
+	}
+
+	const defaultRepo = typeof rawRouting.defaultRepo === "string" ? rawRouting.defaultRepo.trim() : "";
+	const tasksRoot = typeof rawRouting.tasksRoot === "string" ? rawRouting.tasksRoot.trim() : "";
+	let taskPacketRepo = typeof rawRouting.taskPacketRepo === "string" ? rawRouting.taskPacketRepo.trim() : "";
+
+	if (!taskPacketRepo && defaultRepo) {
+		taskPacketRepo = defaultRepo;
+		console.error(
+			`[taskplane] config compatibility: workspace.routing.taskPacketRepo is missing in ${sourcePath}; defaulting to workspace.routing.defaultRepo ('${defaultRepo}'). Add workspace.routing.taskPacketRepo explicitly.`,
+		);
+	}
+
+	if (!tasksRoot || !defaultRepo || !taskPacketRepo) {
+		return undefined;
+	}
+
+	const strict = rawRouting.strict === true;
+
+	return {
+		repos,
+		routing: {
+			tasksRoot,
+			defaultRepo,
+			taskPacketRepo,
+			...(strict ? { strict: true } : {}),
+		},
+	};
+}
+
 
 // ── Config File Path Resolution ──────────────────────────────────────
 
@@ -354,6 +420,12 @@ function loadJsonConfig(configRoot: string): TaskplaneConfig | null {
 	if (parsed.orchestrator) {
 		deepMerge(config.orchestrator, parsed.orchestrator);
 	}
+	if (parsed.workspace) {
+		const normalizedWorkspace = normalizeWorkspaceSection(parsed.workspace, jsonPath);
+		if (normalizedWorkspace) {
+			config.workspace = normalizedWorkspace;
+		}
+	}
 
 	return config;
 }
@@ -438,6 +510,29 @@ function loadOrchestratorYaml(configRoot: string): OrchestratorSection {
 	}
 }
 
+/**
+ * Load optional workspace routing config from legacy `taskplane-workspace.yaml`.
+ *
+ * This file is fallback-only for workspace metadata when JSON `workspace`
+ * section is not present. Malformed files are ignored here — strict validation
+ * still happens in workspace runtime loading (`workspace.ts`).
+ */
+function loadWorkspaceYaml(configRoot: string): WorkspaceSectionConfig | undefined {
+	const yamlPath = resolveConfigFilePath(configRoot, "taskplane-workspace.yaml");
+	if (!existsSync(yamlPath)) return undefined;
+
+	try {
+		const raw = readFileSync(yamlPath, "utf-8");
+		const loaded = yamlParse(raw) as any;
+		if (!loaded || typeof loaded !== "object") return undefined;
+
+		const converted = convertStructuralKeys(loaded);
+		return normalizeWorkspaceSection(converted, yamlPath);
+	} catch {
+		return undefined;
+	}
+}
+
 
 // ── User Preferences (Layer 2) ───────────────────────────────────────
 
@@ -586,9 +681,17 @@ export function applyUserPreferences(config: TaskplaneConfig, prefs: UserPrefere
  * in either location. This allows pointer-resolved roots (e.g.,
  * `<configRepo>/.taskplane/`) where files are scaffolded directly
  * without a `.pi/` subdirectory.
+ *
+ * Includes optional workspace YAML (`taskplane-workspace.yaml`) so
+ * workspace-only roots participate in config-root resolution.
  */
 export function hasConfigFiles(root: string): boolean {
-	const files = [PROJECT_CONFIG_FILENAME, "task-runner.yaml", "task-orchestrator.yaml"];
+	const files = [
+		PROJECT_CONFIG_FILENAME,
+		"task-runner.yaml",
+		"task-orchestrator.yaml",
+		"taskplane-workspace.yaml",
+	];
 	for (const f of files) {
 		if (existsSync(join(root, ".pi", f)) || existsSync(join(root, f))) return true;
 	}
@@ -637,6 +740,7 @@ export function resolveConfigRoot(cwd: string, pointerConfigRoot?: string): stri
  *   Layer 1 — Project config:
  *     1. `.pi/taskplane-config.json` — JSON-first (new format)
  *     2. `.pi/task-runner.yaml` + `.pi/task-orchestrator.yaml` — YAML fallback
+ *        (+ optional `.pi/taskplane-workspace.yaml` workspace section mapping)
  *     3. Defaults — if no config files exist
  *
  *   Layer 2 — User preferences (applied on top of Layer 1):
@@ -671,10 +775,12 @@ export function loadProjectConfig(cwd: string, pointerConfigRoot?: string): Task
 		// Fall back to YAML
 		const taskRunner = loadTaskRunnerYaml(configRoot);
 		const orchestrator = loadOrchestratorYaml(configRoot);
+		const workspace = loadWorkspaceYaml(configRoot);
 		config = {
 			configVersion: CONFIG_VERSION,
 			taskRunner,
 			orchestrator,
+			...(workspace ? { workspace } : {}),
 		};
 	}
 
@@ -710,10 +816,12 @@ export function loadLayer1Config(cwd: string, pointerConfigRoot?: string): Taskp
 	// Fall back to YAML
 	const taskRunner = loadTaskRunnerYaml(configRoot);
 	const orchestrator = loadOrchestratorYaml(configRoot);
+	const workspace = loadWorkspaceYaml(configRoot);
 	return {
 		configVersion: CONFIG_VERSION,
 		taskRunner,
 		orchestrator,
+		...(workspace ? { workspace } : {}),
 	};
 }
 

package/extensions/taskplane/config-schema.ts

@@ -415,6 +415,37 @@ export interface OrchestratorSection {
 }
 
 
+// ── Workspace Section Interfaces ─────────────────────────────────────
+
+/** Workspace repo definition (JSON config shape). */
+export interface WorkspaceRepoSectionConfig {
+	/** Repo root path (relative to workspace root or absolute). */
+	path: string;
+	/** Optional default branch override. */
+	defaultBranch?: string;
+}
+
+/** Workspace routing definition (JSON config shape). */
+export interface WorkspaceRoutingSectionConfig {
+	/** Shared task packet root directory. */
+	tasksRoot: string;
+	/** Default repo for unqualified operations. */
+	defaultRepo: string;
+	/** Packet-home repo owning PROMPT/STATUS/.DONE. */
+	taskPacketRepo: string;
+	/** Strict repo routing mode. */
+	strict?: boolean;
+}
+
+/** Optional workspace section in taskplane-config.json. */
+export interface WorkspaceSectionConfig {
+	/** Repo map keyed by repo ID. */
+	repos: Record<string, WorkspaceRepoSectionConfig>;
+	/** Routing contract for workspace mode. */
+	routing: WorkspaceRoutingSectionConfig;
+}
+
+
 // ── Unified Config ───────────────────────────────────────────────────
 
 /**
@@ -442,6 +473,8 @@ export interface TaskplaneConfig {
 	taskRunner: TaskRunnerSection;
 	/** Orchestrator settings */
 	orchestrator: OrchestratorSection;
+	/** Optional workspace config (JSON-first; legacy YAML fallback supported). */
+	workspace?: WorkspaceSectionConfig;
 }
 
 

package/extensions/taskplane/execution.ts

@@ -475,7 +475,7 @@ export function buildLaneEnvVars(
 
 	const vars: Record<string, string> = {
 		TASK_AUTOSTART: relativePath,
-		TASK_RUNNER_SPAWN_MODE: "subprocess",
+		TASK_RUNNER_SPAWN_MODE: "tmux",
 		TASK_RUNNER_TMUX_PREFIX: lane.tmuxSessionName,
 		ORCH_SIDECAR_DIR: join(workspaceRoot || repoRoot, ".pi"),
 		NODE_PATH: nodePath,
@@ -915,6 +915,10 @@ export function spawnLaneSession(
 
 	// Build env vars
 	const envVars = buildLaneEnvVars(lane, task.task.promptPath, repoRoot, workspaceRoot);
+	// Pass batch ID so task-runner can include it in lane state for dashboard filtering
+	if (config.orchestrator?.batchId) {
+		envVars.ORCH_BATCH_ID = config.orchestrator.batchId;
+	}
 	if (extraEnvVars) {
 		Object.assign(envVars, extraEnvVars);
 	}

package/extensions/taskplane/extension.ts

@@ -1457,6 +1457,8 @@ export default function (pi: ExtensionAPI) {
 	 * and return early with a user-facing error when null.
 	 */
 	let execCtx: ExecutionContext | null = null;
+	/** Last startup error message to surface consistently through command guards. */
+	let execCtxInitError: string | null = null;
 
 	// ── Widget Rendering ─────────────────────────────────────────────
 
@@ -1477,17 +1479,18 @@ export default function (pi: ExtensionAPI) {
 
 	// ── Command Guard ────────────────────────────────────────────────
 
+	function getExecCtxInitErrorMessage(): string {
+		return execCtxInitError ??
+			"❌ Orchestrator not initialized. Startup failed before execution context was created.\nRestart the session after fixing configuration/setup issues.";
+	}
+
 	/**
 	 * Guard: returns true if execution context is initialized, false otherwise.
 	 * Emits a user-facing error notification when the context is missing.
 	 */
 	function requireExecCtx(ctx: ExtensionContext): boolean {
 		if (execCtx) return true;
-		ctx.ui.notify(
-			"❌ Orchestrator not initialized. Workspace configuration failed at startup.\n" +
-			"Fix the workspace config or remove it to use repo mode, then restart.",
-			"error",
-		);
+		ctx.ui.notify(getExecCtxInitErrorMessage(), "error");
 		return false;
 	}
 
@@ -1720,7 +1723,7 @@ export default function (pi: ExtensionAPI) {
 
 		if (!execCtx) {
 			return {
-				message: "❌ Orchestrator not initialized. Workspace configuration failed at startup.\nFix the workspace config or remove it to use repo mode, then restart.",
+				message: getExecCtxInitErrorMessage(),
 				error: true,
 			};
 		}
@@ -2050,7 +2053,7 @@ export default function (pi: ExtensionAPI) {
 	function doOrchResume(force: boolean, ctx: ExtensionContext): { message: string; error?: boolean } {
 		if (!execCtx) {
 			return {
-				message: "❌ Orchestrator not initialized. Workspace configuration failed at startup.\nFix the workspace config or remove it to use repo mode, then restart.",
+				message: getExecCtxInitErrorMessage(),
 				error: true,
 			};
 		}
@@ -2786,7 +2789,7 @@ export default function (pi: ExtensionAPI) {
 	): Promise<{ message: string; error?: boolean; level?: "info" | "warning" | "error" }> {
 		if (!execCtx) {
 			return {
-				message: "❌ Orchestrator not initialized. Workspace configuration failed at startup.\nFix the workspace config or remove it to use repo mode, then restart.",
+				message: getExecCtxInitErrorMessage(),
 				error: true,
 			};
 		}
@@ -3653,24 +3656,35 @@ export default function (pi: ExtensionAPI) {
 		orchWidgetCtx = ctx;
 
 		// ── Build execution context (config + workspace mode detection) ──
-		// Reset execCtx before loading to prevent stale state on re-init
+		// Reset startup state before loading to prevent stale errors on re-init.
 		execCtx = null;
+		execCtxInitError = null;
 		try {
 			execCtx = buildExecutionContext(ctx.cwd, loadOrchestratorConfig, loadTaskRunnerConfig);
 		} catch (err: unknown) {
 			if (err instanceof WorkspaceConfigError) {
-				// Workspace config is present but invalid — fatal startup error.
-				// Leave execCtx null; command guard will block all commands except abort.
-				ctx.ui.notify(
-					`❌ Workspace configuration error [${err.code}]\n\n` +
-					`${err.message}\n\n` +
-					`Fix the workspace config at .pi/taskplane-workspace.yaml or remove it to use repo mode.\n` +
-					`Orchestrator commands are disabled until this is resolved.`,
-					"error",
-				);
+				// Startup is fatal when workspace config is invalid OR repo-mode setup
+				// requirements are not met (non-git cwd without workspace config).
+				const setupError = err.code === "WORKSPACE_SETUP_REQUIRED";
+				execCtxInitError = setupError
+					? (
+						`❌ Orchestrator startup blocked [${err.code}]\n\n` +
+						`${err.message}\n\n` +
+						`Orchestrator commands are disabled until this setup issue is resolved.`
+					)
+					: (
+						`❌ Workspace configuration error [${err.code}]\n\n` +
+						`${err.message}\n\n` +
+						`Fix the workspace config at .pi/taskplane-workspace.yaml (or taskplane-config.json workspace section), then restart.\n` +
+						`Orchestrator commands are disabled until this is resolved.`
+					);
+
+				ctx.ui.notify(execCtxInitError, "error");
 				ctx.ui.setStatus(
 					"task-orchestrator",
-					"🔀 Orchestrator · ❌ startup failed (workspace config error)",
+					setupError
+						? "🔀 Orchestrator · ❌ startup failed (setup required)"
+						: "🔀 Orchestrator · ❌ startup failed (workspace config error)",
 				);
 				return;
 			}

package/extensions/taskplane/types.ts

@@ -2832,10 +2832,11 @@ export const BATCH_HISTORY_MAX_ENTRIES = 100;
  *   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
+ * 1. 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.
+ * 2. Workspace config file present + valid → workspace mode.
+ * 3. No workspace config + cwd is a git repo → repo mode.
+ * 4. No workspace config + cwd is not a git repo → `WORKSPACE_SETUP_REQUIRED`.
  */
 export type WorkspaceMode = "repo" | "workspace";
 
@@ -2872,6 +2873,15 @@ export interface WorkspaceRoutingConfig {
 	 * Must reference a valid key in `WorkspaceConfig.repos`.
 	 */
 	defaultRepo: string;
+	/**
+	 * Repo ID that owns task packet files (PROMPT.md/STATUS.md/.DONE/.reviews).
+	 *
+	 * Required at runtime. Legacy workspace YAML without this field is
+	 * compatibility-mapped to `defaultRepo` during load with a warning.
+	 *
+	 * Invariant: `tasksRoot` must resolve inside `repos[taskPacketRepo].path`.
+	 */
+	taskPacketRepo: string;
 	/**
 	 * When true, every task MUST declare an explicit execution target
 	 * (via `## Execution Target` section or inline `**Repo:**` in PROMPT.md).
@@ -2964,6 +2974,10 @@ export interface ExecutionContext {
  * - 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_TASK_PACKET_REPO_NOT_FOUND: `routing.task_packet_repo` references a repo ID not in the repos map
+ * - WORKSPACE_TASKS_ROOT_OUTSIDE_PACKET_REPO: `routing.tasks_root` resolves outside `repos[routing.task_packet_repo].path`
+ * - WORKSPACE_TASK_AREA_OUTSIDE_TASKS_ROOT: A configured task-area path resolves outside `routing.tasks_root`
+ * - WORKSPACE_SETUP_REQUIRED: No workspace config and cwd is not a git repository
  * - 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
  */
@@ -2978,10 +2992,12 @@ export type WorkspaceConfigErrorCode =
 	| "WORKSPACE_TASKS_ROOT_NOT_FOUND"
 	| "WORKSPACE_MISSING_DEFAULT_REPO"
 	| "WORKSPACE_DEFAULT_REPO_NOT_FOUND"
+	| "WORKSPACE_TASK_PACKET_REPO_NOT_FOUND"
+	| "WORKSPACE_TASKS_ROOT_OUTSIDE_PACKET_REPO"
+	| "WORKSPACE_TASK_AREA_OUTSIDE_TASKS_ROOT"
+	| "WORKSPACE_SETUP_REQUIRED"
 	| "WORKSPACE_DUPLICATE_REPO_PATH"
-	| "WORKSPACE_SCHEMA_INVALID";
-
-/**
+	| "WORKSPACE_SCHEMA_INVALID";/**
  * Typed error class for workspace configuration failures.
  *
  * Thrown during workspace config loading/validation when the config file

package/extensions/taskplane/workspace.ts

@@ -2,8 +2,9 @@
  * Workspace configuration loading and validation.
  *
  * Detects workspace mode by checking for `.pi/taskplane-workspace.yaml`.
- * When the file is absent, the orchestrator runs in repo mode (default).
  * 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)
@@ -20,6 +21,8 @@
  * 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.
@@ -95,6 +98,16 @@ function resolveAbsolutePath(p: string, base: string): string {
 	}
 }
 
+/**
+ * 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 ───────────────────────────────────────────────
 
@@ -498,7 +511,50 @@ export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | nu
 		);
 	}
 
-	// ── 12. routing.strict (optional boolean, default false) ─────
+	// 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(
+			`[taskplane] 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
@@ -518,6 +574,7 @@ export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | nu
 	const routing: WorkspaceRoutingConfig = {
 		tasksRoot: tasksRootAbsolute,
 		defaultRepo: defaultRepoId,
+		taskPacketRepo: taskPacketRepoId,
 		...(strict ? { strict: true } : {}),
 	};
 
@@ -531,6 +588,39 @@ export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | nu
 }
 
 
+// ── 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 ────────────────────────────────────────
 
 /**
@@ -543,8 +633,14 @@ export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | nu
  * @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
+ * @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,
@@ -553,6 +649,19 @@ export function buildExecutionContext(
 	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 Taskplane from a git repository, or create ${wsConfigFile} (taskplane 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);
@@ -580,6 +689,9 @@ export function buildExecutionContext(
 	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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.22.4",
+  "version": "0.22.6",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",

package/templates/agents/task-worker.md

@@ -289,33 +289,35 @@ checkpoints protect against regressions even when intermediate steps use targete
 2. The merge agent (before merging to the orchestrator branch)
 3. CI (before merging to main)
 
-## File Reading Strategy (Context Budget)
+## File Reading Strategy (Context Budget) — CRITICAL
 
-Your context window is finite. Reading large files whole wastes budget and risks
-triggering the context-pressure safety net (85% → wrap-up, 95% → kill).
-Use targeted reads instead:
+Your context window is finite. **Reading large files without offset/limit is the
+#1 cause of context exhaustion** — one full read of a 3000-line file consumes
+~5% of a 1M context window. Three such reads = 15% gone before you've done
+anything.
+
+### HARD RULES
+
+1. **NEVER read a file > 500 lines without offset/limit.** Always grep first.
+2. **NEVER read the same file twice in full.** Re-read only the changed region.
+3. **ALWAYS check file size before reading:** `wc -l <file>` or `ls -la <file>`
 
 ### Pattern: grep-first, read-with-offset
 
-1. **Locate** the relevant section with `grep` or `find`:
-   ```
-   grep -n "function buildPrompt" extensions/task-runner.ts
-   ```
-2. **Read** just that region with `offset` and `limit`:
-   ```
-   read extensions/task-runner.ts (offset: 1773, limit: 50)
-   ```
-3. **Edit** surgically with exact `oldText → newText`
+1. **Check size:** `wc -l extensions/task-runner.ts` → 4100 lines (DO NOT read fully)
+2. **Locate** the relevant section: `grep -n "function buildPrompt" extensions/task-runner.ts`
+3. **Read** just that region: `read extensions/task-runner.ts (offset: 1773, limit: 50)`
+4. **Edit** surgically with exact `oldText → newText`
 
 ### When to read a full file
 
 - Files under ~500 lines — read the whole thing, it's fine
-- Config files, test files, templates — usually small enough to read fully
+- Config files, small test files, templates — usually small enough
 - New files you're creating — read after writing to verify
 
 ### When NOT to read a full file
 
-- Source files over ~1000 lines — grep first, read the relevant region
+- Source files over ~500 lines — grep first, read with offset/limit
 - Generated files, lock files, large data files — almost never need full reads
 - Files you've already read this session — re-read only the changed region