taskplane 0.10.2 → 0.12.0

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",
 };
 
 
@@ -1268,6 +1276,100 @@ export const MERGE_SPAWN_RETRY_MAX = 2;
  */
 export const MERGE_TIMEOUT_MAX_RETRIES = 2;
 
+// ── Merge Health Monitoring Constants (TP-056) ───────────────────────
+
+/**
+ * Polling interval for merge health monitor (ms).
+ * Independent of the merge result poll — runs on its own cadence.
+ * @since TP-056
+ */
+export const MERGE_HEALTH_POLL_INTERVAL_MS = 2 * 60 * 1000; // 2 minutes
+
+/**
+ * Threshold (ms) after which a merge session with no new output
+ * is classified as "possibly stalled" and a warning event is emitted.
+ * @since TP-056
+ */
+export const MERGE_HEALTH_WARNING_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Threshold (ms) after which a merge session with no new output
+ * is classified as "stuck" and a stuck event is emitted.
+ * @since TP-056
+ */
+export const MERGE_HEALTH_STUCK_THRESHOLD_MS = 20 * 60 * 1000; // 20 minutes
+
+/**
+ * Number of lines to capture from the bottom of a tmux pane
+ * for activity detection via snapshot comparison.
+ * @since TP-056
+ */
+export const MERGE_HEALTH_CAPTURE_LINES = 10;
+
+// ── Merge Health Event Types (TP-056) ────────────────────────────────
+
+/**
+ * Health classification for a merge session.
+ *
+ * - `healthy`:  Session alive, output changing
+ * - `warning`:  Session alive, no new output for MERGE_HEALTH_WARNING_THRESHOLD_MS
+ * - `dead`:     Session gone, no result file
+ * - `stuck`:    Session alive, no new output for MERGE_HEALTH_STUCK_THRESHOLD_MS
+ *
+ * @since TP-056
+ */
+export type MergeHealthStatus = "healthy" | "warning" | "dead" | "stuck";
+
+/**
+ * Engine event types for merge health monitoring.
+ *
+ * These extend the EngineEventType union and are emitted to the
+ * unified events.jsonl for supervisor consumption.
+ *
+ * @since TP-056
+ */
+export type MergeHealthEventType =
+	| "merge_health_warning"
+	| "merge_health_dead"
+	| "merge_health_stuck";
+
+/**
+ * Snapshot of a merge session's pane output at a point in time.
+ * Used for activity detection by comparing successive snapshots.
+ *
+ * @since TP-056
+ */
+export interface MergeSessionSnapshot {
+	/** Captured pane content (last N lines) */
+	content: string;
+	/** Epoch ms when the snapshot was taken */
+	capturedAt: number;
+}
+
+/**
+ * Per-session health tracking state.
+ *
+ * @since TP-056
+ */
+export interface MergeSessionHealthState {
+	/** TMUX session name */
+	sessionName: string;
+	/** Lane number this session belongs to */
+	laneNumber: number;
+	/** Last captured pane snapshot */
+	lastSnapshot: MergeSessionSnapshot | null;
+	/** Epoch ms when the last output change was detected */
+	lastActivityAt: number;
+	/** Current health classification */
+	status: MergeHealthStatus;
+	/** Whether a warning event has been emitted (prevent duplicates) */
+	warningEmitted: boolean;
+	/** Whether a stuck event has been emitted (prevent duplicates) */
+	stuckEmitted: boolean;
+	/** Whether a dead event has been emitted (prevent duplicates) */
+	deadEmitted: boolean;
+}
+
 
 // ── Merge Retry Policy Matrix (TP-033 Step 2) ───────────────────────
 
@@ -1384,7 +1486,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 +1501,7 @@ export type Tier0RecoveryPattern =
  */
 export const TIER0_RETRYABLE_CLASSIFICATIONS: ReadonlySet<string> = new Set([
 	"api_error",
+	"model_access_error",
 	"process_crash",
 	"session_vanished",
 ]);
@@ -1444,6 +1548,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 +1566,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
@@ -1541,6 +1651,9 @@ export type EngineEventType =
 	| "merge_start"
 	| "merge_success"
 	| "merge_failed"
+	| "merge_health_warning"
+	| "merge_health_dead"
+	| "merge_health_stuck"
 	| "batch_complete"
 	| "batch_paused";
 
@@ -1606,6 +1719,15 @@ export interface EngineEvent {
 	blockedTasks?: number;
 	/** Batch duration in milliseconds (for batch_complete) */
 	batchDurationMs?: number;
+
+	// ── Merge health monitoring fields (TP-056) ──────────────────
+
+	/** TMUX session name (for merge_health_* events) */
+	sessionName?: string;
+	/** Merge health status classification (for merge_health_* events) */
+	healthStatus?: MergeHealthStatus;
+	/** Minutes since last activity (for merge_health_warning, merge_health_stuck) */
+	stalledMinutes?: number;
 }
 
 /**

package/package.json

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