taskplane 0.10.2 → 0.11.0

package/README.md

@@ -129,7 +129,7 @@ For a single task with full worktree isolation, dashboard, and reviews:
 
 This uses the same orchestrator infrastructure as a full batch — isolated worktree, orch branch, supervisor, dashboard, inline reviews — but for just one task.
 
-> **Note:** The `/task` command still exists for direct single-task execution in the current branch, but `/orch` is recommended for all workflows. `/task` does not provide worktree isolation, dashboard, or inline reviews.
+> **Deprecated:** The `/task` command is deprecated and will be removed in a future major version. It does not provide worktree isolation, dashboard, or inline reviews. Use `/orch` for all workflows — including single-task execution.
 
 ## Commands
 
@@ -137,10 +137,10 @@ This uses the same orchestrator infrastructure as a full batch — isolated work
 
 | Command | Description |
 |---------|-------------|
-| `/task <path/to/PROMPT.md>` | Execute one task in the current branch/worktree |
-| `/task-status` | Show current task progress |
-| `/task-pause` | Pause after current worker iteration finishes |
-| `/task-resume` | Resume a paused task |
+| `/task <path/to/PROMPT.md>` | ⚠️ **Deprecated.** Execute one task in the current branch/worktree. Use `/orch` instead. |
+| `/task-status` | ⚠️ **Deprecated.** Show current task progress. Use `/orch-status` or dashboard. |
+| `/task-pause` | ⚠️ **Deprecated.** Pause after current worker iteration finishes. Use `/orch-pause`. |
+| `/task-resume` | ⚠️ **Deprecated.** Resume a paused task. Use `/orch-resume`. |
 | `/orch [<areas\|paths\|all>]` | No args: detect state & guide (onboarding, batch planning, etc.); with args: execute tasks via isolated worktrees |
 | `/orch-plan <areas\|paths\|all>` | Preview execution plan without running |
 | `/orch-status` | Show batch progress |

package/extensions/task-runner.ts

@@ -2098,9 +2098,13 @@ export default function (pi: ExtensionAPI) {
 
 				// Load reviewer agent definition
 				const reviewerDef = loadAgentDef(ctx.cwd, "task-reviewer");
-				const reviewerModel = config.reviewer.model
-					|| reviewerDef?.model
-					|| (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514");
+				// TP-055: model fallback — use session model when TASKPLANE_MODEL_FALLBACK=1
+				const reviewerModelFallback = process.env.TASKPLANE_MODEL_FALLBACK === "1";
+				const reviewerModel = reviewerModelFallback
+					? (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514")
+					: (config.reviewer.model
+						|| reviewerDef?.model
+						|| (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514"));
 				const reviewerPrompt = reviewerDef?.systemPrompt
 					|| "You are a code reviewer. Read the request and write your review to the specified output file.";
 				const systemPrompt = reviewerPrompt + "\n\n" + buildProjectContext(config, task.taskFolder);
@@ -2585,9 +2589,15 @@ export default function (pi: ExtensionAPI) {
 		const basePrompt = workerDef?.systemPrompt || "You are a task execution agent. Read STATUS.md first, find unchecked items, work on them, checkpoint after each.";
 		const systemPrompt = basePrompt + "\n\n" + buildProjectContext(config, task.taskFolder);
 
-		const model = config.worker.model
-			|| workerDef?.model
-			|| (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514");
+		// TP-055: When TASKPLANE_MODEL_FALLBACK=1 is set, skip configured model
+		// and fall back to the session model. This is set by the orchestrator's
+		// model fallback retry when the configured model becomes unavailable.
+		const modelFallbackActive = process.env.TASKPLANE_MODEL_FALLBACK === "1";
+		const model = modelFallbackActive
+			? (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514")
+			: (config.worker.model
+				|| workerDef?.model
+				|| (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514"));
 
 		const contextDocsList = task.contextDocs.length > 0
 			? "\n\nContext docs to read if needed:\n" + task.contextDocs.map(d => `- ${d}`).join("\n")
@@ -2904,7 +2914,11 @@ export default function (pi: ExtensionAPI) {
 		writeFileSync(requestPath, request);
 
 		const reviewerDef = loadAgentDef(ctx.cwd, "task-reviewer");
-		const reviewerModel = config.reviewer.model || reviewerDef?.model || (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514");
+		// TP-055: model fallback — use session model when TASKPLANE_MODEL_FALLBACK=1
+		const reviewerModelFallback2 = process.env.TASKPLANE_MODEL_FALLBACK === "1";
+		const reviewerModel = reviewerModelFallback2
+			? (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514")
+			: (config.reviewer.model || reviewerDef?.model || (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514"));
 		const reviewerPrompt = reviewerDef?.systemPrompt || "You are a code reviewer. Read the request and write your review to the specified output file.";
 		const systemPrompt = reviewerPrompt + "\n\n" + buildProjectContext(config, task.taskFolder);
 
@@ -3040,10 +3054,14 @@ export default function (pi: ExtensionAPI) {
 		// Determine review model with fallback chain:
 		// quality_gate.review_model → reviewer.model → agent def → default
 		const reviewerDef = loadAgentDef(ctx.cwd, "task-reviewer");
-		const reviewModel = config.quality_gate.review_model
-			|| config.reviewer.model
-			|| reviewerDef?.model
-			|| (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514");
+		// TP-055: model fallback — use session model when TASKPLANE_MODEL_FALLBACK=1
+		const qgModelFallback = process.env.TASKPLANE_MODEL_FALLBACK === "1";
+		const reviewModel = qgModelFallback
+			? (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514")
+			: (config.quality_gate.review_model
+				|| config.reviewer.model
+				|| reviewerDef?.model
+				|| (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514"));
 
 		const reviewerPrompt = reviewerDef?.systemPrompt
 			|| "You are a quality gate reviewer. Read the review request and write your JSON verdict to the specified file.";
@@ -3210,9 +3228,13 @@ export default function (pi: ExtensionAPI) {
 
 		// Use worker model and tools for fix agent (it needs to edit code)
 		const workerDef = loadAgentDef(ctx.cwd, "task-worker");
-		const fixModel = config.worker.model
-			|| workerDef?.model
-			|| "anthropic/claude-sonnet-4-20250514";
+		// TP-055: model fallback — use session model when TASKPLANE_MODEL_FALLBACK=1
+		const fixModelFallback = process.env.TASKPLANE_MODEL_FALLBACK === "1";
+		const fixModel = fixModelFallback
+			? (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "anthropic/claude-sonnet-4-20250514")
+			: (config.worker.model
+				|| workerDef?.model
+				|| "anthropic/claude-sonnet-4-20250514");
 
 		const basePrompt = workerDef?.systemPrompt
 			|| "You are a fix agent addressing quality gate findings. Read the feedback and make targeted code fixes.";
@@ -3405,9 +3427,15 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	pi.registerCommand("task", {
-		description: "Start executing a task: /task <path/to/PROMPT.md>",
+		description: "⚠️ [Deprecated] Start executing a task: /task <path/to/PROMPT.md>",
 		handler: async (args, ctx) => {
 			widgetCtx = ctx;
+			ctx.ui.notify(
+				"⚠️ /task is deprecated. Use /orch instead — it provides worktree isolation, " +
+				"dashboard, inline reviews, and supervisor monitoring. " +
+				"/task will be removed in a future major version.",
+				"warning",
+			);
 			const promptPath = args?.trim();
 			if (!promptPath) {
 				ctx.ui.notify("Usage: /task <path/to/PROMPT.md>", "error");
@@ -3425,9 +3453,13 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("task-status", {
-		description: "Show current task progress",
+		description: "⚠️ [Deprecated] Show current task progress",
 		handler: async (_args, ctx) => {
 			widgetCtx = ctx;
+			ctx.ui.notify(
+				"⚠️ /task-status is deprecated. Use the dashboard (`taskplane dashboard`) or `/orch-status` instead.",
+				"warning",
+			);
 			if (!state.task) {
 				ctx.ui.notify("No task loaded. Use /task <path/to/PROMPT.md>", "info");
 				return;
@@ -3459,9 +3491,13 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("task-pause", {
-		description: "Pause task after current worker finishes",
+		description: "⚠️ [Deprecated] Pause task after current worker finishes",
 		handler: async (_args, ctx) => {
 			widgetCtx = ctx;
+			ctx.ui.notify(
+				"⚠️ /task-pause is deprecated. Use `/orch-pause` instead.",
+				"warning",
+			);
 			if (state.phase !== "running") {
 				ctx.ui.notify("No task is running", "warning");
 				return;
@@ -3473,9 +3509,13 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("task-resume", {
-		description: "Resume a paused task",
+		description: "⚠️ [Deprecated] Resume a paused task",
 		handler: async (_args, ctx) => {
 			widgetCtx = ctx;
+			ctx.ui.notify(
+				"⚠️ /task-resume is deprecated. Use `/orch-resume` instead.",
+				"warning",
+			);
 			if (state.phase !== "paused") {
 				ctx.ui.notify("Task is not paused", "warning");
 				return;

package/extensions/taskplane/config-loader.ts

@@ -222,6 +222,9 @@ function mapTaskRunnerYaml(raw: any): Partial<TaskRunnerSection> {
 	// Quality gate (structural — all keys are schema-defined)
 	if (raw.quality_gate) result.qualityGate = convertStructuralKeys(raw.quality_gate);
 
+	// Model fallback (scalar — "inherit" or "fail")
+	if (raw.model_fallback) result.modelFallback = raw.model_fallback;
+
 	return result;
 }
 
@@ -814,6 +817,7 @@ export function toTaskRunnerConfig(config: TaskplaneConfig): import("./types.ts"
 		task_areas: taskAreas,
 		reference_docs: { ...config.taskRunner.referenceDocs },
 		...(hasTestingCommands ? { testing_commands: { ...testingCommands } } : {}),
+		model_fallback: config.taskRunner.modelFallback ?? "inherit",
 	};
 }
 

package/extensions/taskplane/config-schema.ts

@@ -170,6 +170,19 @@ export interface SelfDocTarget {
  */
 export type PassThreshold = "no_critical" | "no_important" | "all_clear";
 
+/**
+ * Model fallback behavior when a configured agent model becomes unavailable mid-batch.
+ *
+ * - `"inherit"`: Fall back to the session model and retry (default). The task is
+ *   retried without an explicit --model flag, so pi uses whatever model the
+ *   session is configured with.
+ * - `"fail"`: Fail immediately — the normal failure/retry path handles the error
+ *   without any model substitution.
+ *
+ * @since TP-055
+ */
+export type ModelFallbackMode = "inherit" | "fail";
+
 /** Quality gate configuration — opt-in post-completion review */
 export interface QualityGateConfig {
 	/** Enable quality gate review before .DONE creation (default: false) */
@@ -222,6 +235,16 @@ export interface TaskRunnerSection {
 	protectedDocs: string[];
 	/** Quality gate configuration — opt-in post-completion review */
 	qualityGate: QualityGateConfig;
+	/**
+	 * Model fallback behavior when a configured model becomes unavailable mid-batch.
+	 *
+	 * - `"inherit"` (default): Retry the task without an explicit model flag,
+	 *   falling back to the session model.
+	 * - `"fail"`: Fail immediately without model substitution.
+	 *
+	 * @since TP-055
+	 */
+	modelFallback: ModelFallbackMode;
 }
 
 
@@ -515,6 +538,7 @@ export const DEFAULT_TASK_RUNNER_SECTION: TaskRunnerSection = {
 		maxFixCycles: 1,
 		passThreshold: "no_critical",
 	},
+	modelFallback: "inherit",
 };
 
 /** Default orchestrator section values */

package/extensions/taskplane/diagnostics.ts

@@ -45,6 +45,7 @@ export interface SessionTokenCounts {
  * |----------------------|------------------------------------------------------|
  * | `completed`          | `.DONE` file found — task finished successfully      |
  * | `api_error`          | API returned error (auth, rate limit, overload)      |
+ * | `model_access_error` | Model unavailable (401/403/429, model not found)     |
  * | `context_overflow`   | Hit context window limit (compactions + high ctx %)  |
  * | `wall_clock_timeout` | Killed by task-runner's max_worker_minutes timer     |
  * | `process_crash`      | Non-zero exit code with no API error indicators      |
@@ -56,6 +57,7 @@ export interface SessionTokenCounts {
 export type ExitClassification =
 	| "completed"
 	| "api_error"
+	| "model_access_error"
 	| "context_overflow"
 	| "wall_clock_timeout"
 	| "process_crash"
@@ -70,6 +72,7 @@ export type ExitClassification =
 export const EXIT_CLASSIFICATIONS: readonly ExitClassification[] = [
 	"completed",
 	"api_error",
+	"model_access_error",
 	"context_overflow",
 	"wall_clock_timeout",
 	"process_crash",
@@ -223,6 +226,51 @@ export interface TaskExitDiagnostic {
  */
 export const CONTEXT_OVERFLOW_THRESHOLD_PCT = 90;
 
+/**
+ * Patterns that indicate a model access error (as opposed to a generic API error).
+ *
+ * These patterns match error messages from API providers when:
+ * - The model is not found or deprecated
+ * - Authentication/authorization fails (HTTP 401/403)
+ * - Rate limits are hit specifically for the model (HTTP 429)
+ * - API key is expired or invalid
+ *
+ * The patterns are case-insensitive and tested against the error string.
+ *
+ * @since TP-055
+ */
+export const MODEL_ACCESS_ERROR_PATTERNS: readonly RegExp[] = [
+	/\b(?:401|403)\b/,                          // HTTP auth/forbidden status codes
+	/\b429\b/,                                   // HTTP rate limit
+	/model[_ ]not[_ ]found/i,                    // Model not found
+	/model[_ ](?:is[_ ])?unavailable/i,          // Model unavailable
+	/model[_ ](?:has[_ ]been[_ ])?deprecated/i,  // Model deprecated
+	/api[_ ]key[_ ](?:expired|invalid|revoked)/i, // API key issues
+	/invalid[_ ]api[_ ]key/i,                     // Invalid API key (alternate phrasing)
+	/authentication[_ ](?:failed|error|required)/i, // Auth failures
+	/authorization[_ ](?:failed|error|denied)/i,    // Authz failures
+	/access[_ ]denied/i,                          // Generic access denied
+	/permission[_ ]denied/i,                      // Permission denied
+	/quota[_ ]exceeded/i,                         // Quota exceeded
+	/rate[_ ]limit/i,                             // Rate limit (phrase)
+	/insufficient[_ ]quota/i,                     // Insufficient quota
+];
+
+/**
+ * Test whether an error message indicates a model access error.
+ *
+ * Used by `classifyExit()` to distinguish model-specific failures from
+ * generic API errors, enabling targeted fallback to the session model.
+ *
+ * @param errorMessage - Error message to test
+ * @returns true if the error matches a model access pattern
+ * @since TP-055
+ */
+export function isModelAccessError(errorMessage: string): boolean {
+	if (!errorMessage) return false;
+	return MODEL_ACCESS_ERROR_PATTERNS.some(pattern => pattern.test(errorMessage));
+}
+
 /**
  * Classify a task session's exit into a deterministic category.
  *
@@ -232,22 +280,26 @@ export const CONTEXT_OVERFLOW_THRESHOLD_PCT = 90;
  *
  * **Classification precedence (highest → lowest):**
  *
- * | Priority | Condition                                            | Result              |
- * |----------|------------------------------------------------------|---------------------|
- * | 1        | `.DONE` file found                                   | `completed`         |
- * | 2        | Retries present with final retry failed               | `api_error`         |
- * | 3        | Compactions > 0 AND contextPct ≥ 90%                  | `context_overflow`  |
- * | 3b       | Task-runner explicitly context-killed                  | `context_overflow`  |
- * | 4        | Timer killed the session                              | `wall_clock_timeout`|
- * | 5        | Non-zero exit code, no API error                      | `process_crash`     |
- * | 6        | No exit summary file (session vanished)               | `session_vanished`  |
- * | 7        | Stall detected (no STATUS.md progress)                | `stall_timeout`     |
- * | 8        | User manually killed the session                      | `user_killed`       |
- * | 9        | None of the above                                    | `unknown`           |
+ * | Priority | Condition                                            | Result               |
+ * |----------|------------------------------------------------------|----------------------|
+ * | 1        | `.DONE` file found                                   | `completed`          |
+ * | 2a       | Retries with model-access error pattern               | `model_access_error` |
+ * | 2b       | Retries present with final retry failed               | `api_error`          |
+ * | 2c       | Error message has model-access pattern (no retries)   | `model_access_error` |
+ * | 3        | Compactions > 0 AND contextPct ≥ 90%                  | `context_overflow`   |
+ * | 3b       | Task-runner explicitly context-killed                  | `context_overflow`   |
+ * | 4        | Timer killed the session                              | `wall_clock_timeout` |
+ * | 5        | Non-zero exit code, no API error                      | `process_crash`      |
+ * | 6        | No exit summary file (session vanished)               | `session_vanished`   |
+ * | 7        | Stall detected (no STATUS.md progress)                | `stall_timeout`      |
+ * | 8        | User manually killed the session                      | `user_killed`        |
+ * | 9        | None of the above                                    | `unknown`            |
  *
  * **Tie-break rationale:**
  * - `.DONE` always wins because the task succeeded regardless of how messy
  *   the session was (retries, compactions, etc.).
+ * - `model_access_error` beats generic `api_error` because it's more specific
+ *   and enables targeted fallback (retry with session model).
  * - `api_error` beats `context_overflow` because API failures are more
  *   actionable (auth fix, rate limit backoff).
  * - `wall_clock_timeout` beats `process_crash` because the timer kill
@@ -269,14 +321,24 @@ export function classifyExit(input: ExitClassificationInput): ExitClassification
 		return "completed";
 	}
 
-	// 2. Retries present with final retry failed → api_error
+	// 2a. Retries present with model-access error pattern → model_access_error
+	// 2b. Retries present with final retry failed → api_error
 	if (exitSummary?.retries && exitSummary.retries.length > 0) {
 		const lastRetry = exitSummary.retries[exitSummary.retries.length - 1];
 		if (!lastRetry.succeeded) {
+			// Check if the retry error indicates a model access issue
+			if (isModelAccessError(lastRetry.error)) {
+				return "model_access_error";
+			}
 			return "api_error";
 		}
 	}
 
+	// 2c. Error message (no retries) indicates model access issue → model_access_error
+	if (exitSummary?.error && isModelAccessError(exitSummary.error)) {
+		return "model_access_error";
+	}
+
 	// 3. Compactions > 0 AND high context utilization → context_overflow
 	if (exitSummary && exitSummary.compactions > 0) {
 		const effectivePct = contextPct ?? 0;

package/extensions/taskplane/engine.ts

@@ -85,6 +85,7 @@ async function attemptWorkerCrashRetry(
 	allTaskOutcomes: LaneTaskOutcome[],
 	onNotify: (message: string, level: "info" | "warning" | "error") => void,
 	stateRoot: string,
+	runnerConfig?: TaskRunnerConfig,
 ): Promise<{ retriedCount: number; succeededRetries: string[]; failedRetries: string[] }> {
 	if (!batchState.resilience) {
 		batchState.resilience = defaultResilienceState();
@@ -134,6 +135,14 @@ async function attemptWorkerCrashRetry(
 			continue;
 		}
 
+		// model_access_error is handled by attemptModelFallbackRetry() — skip here
+		if (classification === "model_access_error") {
+			execLog("batch", batchState.batchId,
+				`tier0: task ${taskId} classified as model_access_error — deferring to model fallback handler`,
+			);
+			continue;
+		}
+
 		// Check retry budget
 		const scopeKey = tier0ScopeKey("worker_crash", taskId, waveIdx);
 		const currentCount = batchState.resilience.retryCountByScope[scopeKey] ?? 0;
@@ -333,6 +342,263 @@ async function attemptWorkerCrashRetry(
 	return { retriedCount, succeededRetries, failedRetries };
 }
 
+/**
+ * Attempt model fallback retry for tasks that failed with `model_access_error`.
+ *
+ * When a configured agent model becomes unavailable mid-batch (API key expired,
+ * rate limit, model deprecated, provider outage), this function retries the task
+ * with the session model by setting `TASKPLANE_MODEL_FALLBACK=1` env var. The
+ * task-runner reads this var and omits the explicit `--model` flag, causing pi
+ * to use the session's default model.
+ *
+ * Only runs when `runnerConfig.model_fallback === "inherit"` (the default). When
+ * set to `"fail"`, model access errors fall through to normal failure handling.
+ *
+ * Separate from `attemptWorkerCrashRetry()` because:
+ * - Uses a different recovery pattern (`model_fallback` vs `worker_crash`)
+ * - Requires env var injection to change the model behavior
+ * - Has its own retry budget
+ *
+ * @since TP-055
+ */
+async function attemptModelFallbackRetry(
+	waveResult: WaveExecutionResult,
+	waveIdx: number,
+	batchState: OrchBatchRuntimeState,
+	orchConfig: OrchestratorConfig,
+	repoRoot: string,
+	workspaceConfig: WorkspaceConfig | null | undefined,
+	allTaskOutcomes: LaneTaskOutcome[],
+	onNotify: (message: string, level: "info" | "warning" | "error") => void,
+	stateRoot: string,
+	runnerConfig?: TaskRunnerConfig,
+): Promise<{ retriedCount: number; succeededRetries: string[]; failedRetries: string[] }> {
+	// Short-circuit: if model fallback is disabled, skip entirely
+	const modelFallbackMode = runnerConfig?.model_fallback ?? "inherit";
+	if (modelFallbackMode !== "inherit") {
+		return { retriedCount: 0, succeededRetries: [], failedRetries: [] };
+	}
+
+	if (!batchState.resilience) {
+		batchState.resilience = defaultResilienceState();
+	}
+
+	const budget = TIER0_RETRY_BUDGETS.model_fallback;
+	const succeededRetries: string[] = [];
+	const failedRetries: string[] = [];
+	let retriedCount = 0;
+
+	// Build a map from taskId → lane for re-execution
+	const taskToLane = new Map<string, AllocatedLane>();
+	for (const lane of waveResult.allocatedLanes) {
+		for (const task of lane.tasks) {
+			taskToLane.set(task.taskId, lane);
+		}
+	}
+
+	// Process only model_access_error tasks
+	for (const taskId of [...waveResult.failedTaskIds]) {
+		const lane = taskToLane.get(taskId);
+		if (!lane) continue;
+
+		const outcome = allTaskOutcomes.find(o => o.taskId === taskId);
+		if (!outcome) continue;
+
+		const classification = outcome.exitDiagnostic?.classification;
+		if (classification !== "model_access_error") continue;
+
+		// Check retry budget
+		const scopeKey = tier0ScopeKey("model_fallback", taskId, waveIdx);
+		const currentCount = batchState.resilience.retryCountByScope[scopeKey] ?? 0;
+		if (currentCount >= budget.maxRetries) {
+			execLog("batch", batchState.batchId,
+				`tier0: task ${taskId} model fallback retry budget exhausted (${currentCount}/${budget.maxRetries})`,
+				{ scopeKey },
+			);
+			emitTier0Event(stateRoot, {
+				...buildTier0EventBase("tier0_recovery_exhausted", batchState.batchId, waveIdx, "model_fallback", currentCount, budget.maxRetries),
+				taskId,
+				laneNumber: lane.laneNumber,
+				repoId: lane.repoId ?? null,
+				classification,
+				error: `Model fallback retry budget exhausted for task ${taskId}`,
+				scopeKey,
+				affectedTaskIds: [taskId],
+				suggestion: `Task ${taskId} failed with model_access_error and model fallback retry exhausted. Check API key validity and model availability.`,
+			});
+			emitTier0Escalation(stateRoot, batchState.batchId, waveIdx, "model_fallback", currentCount, budget.maxRetries,
+				`Model fallback retry budget exhausted for task ${taskId}`, [taskId],
+				`Task ${taskId} failed with model_access_error and model fallback retry exhausted. Check API key validity and model availability.`,
+				{ taskId, laneNumber: lane.laneNumber, repoId: lane.repoId ?? null, classification, scopeKey },
+			);
+			continue;
+		}
+
+		// Increment retry counter
+		batchState.resilience.retryCountByScope[scopeKey] = currentCount + 1;
+		retriedCount++;
+
+		const failedModel = outcome.exitDiagnostic?.errorMessage || "configured model";
+		execLog("batch", batchState.batchId,
+			`tier0: model fallback — retrying task ${taskId} without explicit model (${failedModel} unavailable)`,
+			{ scopeKey, classification },
+		);
+		onNotify(
+			`🔄 Model fallback: Retrying task ${taskId} with session model (${failedModel} unavailable)`,
+			"info",
+		);
+
+		// Emit attempt event
+		emitTier0Event(stateRoot, {
+			...buildTier0EventBase("tier0_recovery_attempt", batchState.batchId, waveIdx, "model_fallback", currentCount + 1, budget.maxRetries),
+			taskId,
+			laneNumber: lane.laneNumber,
+			repoId: lane.repoId ?? null,
+			classification,
+			cooldownMs: budget.cooldownMs,
+			scopeKey,
+		});
+
+		// Cooldown before retry
+		if (budget.cooldownMs > 0) {
+			sleepSync(budget.cooldownMs);
+		}
+
+		// Find the specific AllocatedTask
+		const allocatedTask = lane.tasks.find(t => t.taskId === taskId);
+		if (!allocatedTask) continue;
+
+		// Re-execute with model fallback env var
+		const retryLane: AllocatedLane = {
+			...lane,
+			tasks: [allocatedTask],
+		};
+
+		const isWsMode = !!workspaceConfig;
+		const wsRoot = workspaceConfig
+			? resolve(workspaceConfig.configPath, "..", "..")
+			: undefined;
+
+		try {
+			const retryPauseSignal = { paused: false };
+			// Pass TASKPLANE_MODEL_FALLBACK=1 as extra env var to signal
+			// the task-runner to use the session model instead of configured model.
+			const modelFallbackEnv = { TASKPLANE_MODEL_FALLBACK: "1" };
+			const retryResult = await executeLane(
+				retryLane,
+				orchConfig,
+				repoRoot,
+				retryPauseSignal,
+				wsRoot,
+				isWsMode,
+				modelFallbackEnv,
+			);
+
+			const retryOutcome = retryResult.tasks[0];
+			if (retryOutcome && retryOutcome.status === "succeeded") {
+				succeededRetries.push(taskId);
+
+				// Update waveResult: move from failed to succeeded
+				const failIdx = waveResult.failedTaskIds.indexOf(taskId);
+				if (failIdx !== -1) waveResult.failedTaskIds.splice(failIdx, 1);
+				waveResult.succeededTaskIds.push(taskId);
+
+				// Update lane results
+				for (const lr of waveResult.laneResults) {
+					const taskIdx = lr.tasks.findIndex(t => t.taskId === taskId);
+					if (taskIdx !== -1) {
+						lr.tasks[taskIdx] = retryOutcome;
+						break;
+					}
+				}
+
+				upsertTaskOutcome(allTaskOutcomes, retryOutcome);
+
+				execLog("batch", batchState.batchId,
+					`tier0: task ${taskId} model fallback retry succeeded`,
+					{ scopeKey },
+				);
+				onNotify(
+					`✅ Model fallback: Task ${taskId} succeeded with session model`,
+					"info",
+				);
+
+				emitTier0Event(stateRoot, {
+					...buildTier0EventBase("tier0_recovery_success", batchState.batchId, waveIdx, "model_fallback", currentCount + 1, budget.maxRetries),
+					taskId,
+					laneNumber: lane.laneNumber,
+					repoId: lane.repoId ?? null,
+					classification,
+					resolution: `Task ${taskId} succeeded after falling back to session model`,
+					scopeKey,
+				});
+			} else {
+				failedRetries.push(taskId);
+				if (retryOutcome) {
+					upsertTaskOutcome(allTaskOutcomes, retryOutcome);
+				}
+				execLog("batch", batchState.batchId,
+					`tier0: task ${taskId} model fallback retry failed`,
+					{ scopeKey, exitReason: retryOutcome?.exitReason },
+				);
+
+				const retryFailError = retryOutcome?.exitReason ?? `Task ${taskId} model fallback retry failed`;
+				emitTier0Event(stateRoot, {
+					...buildTier0EventBase("tier0_recovery_exhausted", batchState.batchId, waveIdx, "model_fallback", currentCount + 1, budget.maxRetries),
+					taskId,
+					laneNumber: lane.laneNumber,
+					repoId: lane.repoId ?? null,
+					classification,
+					error: retryFailError,
+					scopeKey,
+					affectedTaskIds: [taskId],
+					suggestion: `Task ${taskId} failed even with session model fallback. Investigate task logs.`,
+				});
+				emitTier0Escalation(stateRoot, batchState.batchId, waveIdx, "model_fallback", currentCount + 1, budget.maxRetries,
+					retryFailError, [taskId],
+					`Task ${taskId} failed even with session model fallback. Investigate task logs.`,
+					{ taskId, laneNumber: lane.laneNumber, repoId: lane.repoId ?? null, classification, scopeKey },
+				);
+			}
+		} catch (err: unknown) {
+			failedRetries.push(taskId);
+			const errMsg = err instanceof Error ? err.message : String(err);
+			execLog("batch", batchState.batchId,
+				`tier0: task ${taskId} model fallback retry threw error: ${errMsg}`,
+				{ scopeKey },
+			);
+			emitTier0Event(stateRoot, {
+				...buildTier0EventBase("tier0_recovery_exhausted", batchState.batchId, waveIdx, "model_fallback", currentCount + 1, budget.maxRetries),
+				taskId,
+				laneNumber: lane.laneNumber,
+				repoId: lane.repoId ?? null,
+				classification,
+				error: errMsg,
+				scopeKey,
+				affectedTaskIds: [taskId],
+				suggestion: `Model fallback retry for task ${taskId} threw an exception: ${errMsg}`,
+			});
+			emitTier0Escalation(stateRoot, batchState.batchId, waveIdx, "model_fallback", currentCount + 1, budget.maxRetries,
+				errMsg, [taskId],
+				`Model fallback retry for task ${taskId} threw an exception: ${errMsg}`,
+				{ taskId, laneNumber: lane.laneNumber, repoId: lane.repoId ?? null, classification, scopeKey },
+			);
+		}
+	}
+
+	// Recalculate wave-level status if retries changed outcomes
+	if (succeededRetries.length > 0) {
+		if (waveResult.failedTaskIds.length === 0) {
+			waveResult.overallStatus = "succeeded";
+			waveResult.stoppedEarly = false;
+		} else if (waveResult.succeededTaskIds.length > 0) {
+			waveResult.overallStatus = "partial";
+		}
+	}
+
+	return { retriedCount, succeededRetries, failedRetries };
+}
+
 /**
  * Attempt stale worktree recovery when lane allocation fails with ALLOC_WORKTREE_FAILED.
  *
@@ -885,6 +1151,40 @@ export async function executeOrchBatch(
 			}
 		}
 
+		// ── TP-055: Tier 0 — Model fallback retry ───────────────
+		// Run model fallback BEFORE worker crash retry so that model_access_error
+		// tasks are retried with session model first. Worker crash retry skips
+		// model_access_error tasks (handled here instead).
+		if (waveResult.failedTaskIds.length > 0) {
+			const modelFallbackOutcome = await attemptModelFallbackRetry(
+				waveResult,
+				waveIdx,
+				batchState,
+				orchConfig,
+				repoRoot,
+				workspaceConfig,
+				allTaskOutcomes,
+				onNotify,
+				stateRoot,
+				runnerConfig,
+			);
+			if (modelFallbackOutcome.succeededRetries.length > 0) {
+				// Recompute blocked tasks after model fallback successes
+				if (waveResult.policyApplied === "skip-dependents" && waveResult.failedTaskIds.length > 0) {
+					const recomputed = computeTransitiveDependents(
+						new Set(waveResult.failedTaskIds),
+						depGraph,
+					);
+					waveResult.blockedTaskIds = [...recomputed].sort();
+				} else if (waveResult.failedTaskIds.length === 0) {
+					waveResult.blockedTaskIds = [];
+				}
+			}
+			if (modelFallbackOutcome.retriedCount > 0) {
+				persistRuntimeState("tier0-model-fallback", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discoveryRef, stateRoot);
+			}
+		}
+
 		// ── TP-039: Tier 0 — Worker crash retry ─────────────────
 		// Run retry BEFORE accumulating counts and blocked tasks so that
 		// successfully retried tasks don't inflate failedTasks count and

package/extensions/taskplane/execution.ts

@@ -683,6 +683,7 @@ export function spawnLaneSession(
 	config: OrchestratorConfig,
 	repoRoot: string,
 	workspaceRoot?: string,
+	extraEnvVars?: Record<string, string>,
 ): void {
 	const sessionName = lane.tmuxSessionName;
 	const laneId = lane.laneId;
@@ -706,6 +707,9 @@ export function spawnLaneSession(
 
 	// Build env vars
 	const envVars = buildLaneEnvVars(lane, task.task.promptPath, repoRoot, workspaceRoot);
+	if (extraEnvVars) {
+		Object.assign(envVars, extraEnvVars);
+	}
 
 	// Prepare per-task lane log path for post-mortem diagnostics
 	const laneLogPath = resolveLaneLogPath(lane, task);
@@ -1017,6 +1021,7 @@ export async function executeLane(
 	pauseSignal: { paused: boolean },
 	workspaceRoot?: string,
 	isWorkspaceMode?: boolean,
+	extraEnvVars?: Record<string, string>,
 ): Promise<LaneExecutionResult> {
 	const laneId = lane.laneId;
 	const laneStartTime = Date.now();
@@ -1053,7 +1058,7 @@ export async function executeLane(
 
 		try {
 			// Spawn TMUX session
-			spawnLaneSession(lane, task, config, repoRoot, workspaceRoot);
+			spawnLaneSession(lane, task, config, repoRoot, workspaceRoot, extraEnvVars);
 
 			// Poll until completion
 			const pollResult = await pollUntilTaskComplete(

package/extensions/taskplane/types.ts

@@ -134,6 +134,13 @@ export interface TaskRunnerConfig {
 	reference_docs: Record<string, string>;
 	/** Named testing/verification commands (e.g., { test: "npx vitest run" }). Used for baseline fingerprinting (TP-032). */
 	testing_commands?: Record<string, string>;
+	/**
+	 * Model fallback behavior when a configured model becomes unavailable mid-batch.
+	 * - `"inherit"` (default): Retry without explicit model (session model fallback).
+	 * - `"fail"`: No model substitution — normal failure path.
+	 * @since TP-055
+	 */
+	model_fallback?: "inherit" | "fail";
 }
 
 /** Result of a preflight check */
@@ -204,6 +211,7 @@ export const DEFAULT_ORCHESTRATOR_CONFIG: OrchestratorConfig = {
 export const DEFAULT_TASK_RUNNER_CONFIG: TaskRunnerConfig = {
 	task_areas: {},
 	reference_docs: {},
+	model_fallback: "inherit",
 };
 
 
@@ -1384,7 +1392,8 @@ export const MERGE_FAILURE_CLASSIFICATIONS: readonly MergeFailureClassification[
 export type Tier0RecoveryPattern =
 	| "worker_crash"
 	| "stale_worktree"
-	| "cleanup_gate";
+	| "cleanup_gate"
+	| "model_fallback";
 
 /**
  * Exit classifications that are eligible for automatic Tier 0 retry.
@@ -1398,6 +1407,7 @@ export type Tier0RecoveryPattern =
  */
 export const TIER0_RETRYABLE_CLASSIFICATIONS: ReadonlySet<string> = new Set([
 	"api_error",
+	"model_access_error",
 	"process_crash",
 	"session_vanished",
 ]);
@@ -1444,6 +1454,11 @@ export const TIER0_RETRY_BUDGETS: Readonly<Record<Tier0RecoveryPattern, Tier0Ret
 		cooldownMs: 2_000,
 		backoffMultiplier: 1.0,
 	},
+	model_fallback: {
+		maxRetries: 1,
+		cooldownMs: 3_000,
+		backoffMultiplier: 1.0,
+	},
 };
 
 /**
@@ -1457,6 +1472,7 @@ export const TIER0_RETRY_BUDGETS: Readonly<Record<Tier0RecoveryPattern, Tier0Ret
  * @since TP-039
  */
 export type Tier0EscalationPattern = Tier0RecoveryPattern | "merge_timeout";
+// Note: model_fallback is already included via Tier0RecoveryPattern
 
 /**
  * Context payload emitted when Tier 0 retries are exhausted and the

package/package.json

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