taskplane 0.10.2 → 0.12.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/dashboard/server.cjs

@@ -437,6 +437,10 @@ function loadTelemetryData(batchState) {
     for (const event of events) {
       switch (event.type) {
         case "message_end": {
+          // A successful message_end means any prior retry resolved.
+          // Clear retryActive to prevent stale retry badges from persisting
+          // across batches or after transient API errors recover.
+          acc.retryActive = false;
           const usage = event.message?.usage;
           if (usage) {
             acc.inputTokens += usage.input || 0;

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;