taskplane 0.11.0 → 0.13.0

package/extensions/taskplane/types.ts

@@ -1276,6 +1276,135 @@ 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;
+
+// ── Persistent Reviewer Constants (TP-057) ───────────────────────────
+
+/**
+ * Polling interval (ms) for the `wait_for_review` tool to check for signal files.
+ * Reviews take minutes; 3s latency is invisible to the user.
+ * @since TP-057
+ */
+export const REVIEWER_POLL_INTERVAL_MS = 3_000;
+
+/**
+ * Maximum time (ms) for the `wait_for_review` tool to wait for a review signal.
+ * 30 minutes — generous for long-running code reviews.
+ * @since TP-057
+ */
+export const REVIEWER_WAIT_TIMEOUT_MS = 30 * 60 * 1000;
+
+/**
+ * Grace period (ms) after writing shutdown signal before killing the reviewer session.
+ * Allows the reviewer to exit cleanly after receiving the shutdown signal.
+ * @since TP-057
+ */
+export const REVIEWER_SHUTDOWN_GRACE_MS = 10_000;
+
+/**
+ * Signal file prefix for review requests. Full name: `.review-signal-{NNN}`
+ * @since TP-057
+ */
+export const REVIEWER_SIGNAL_PREFIX = ".review-signal-";
+
+/**
+ * Shutdown signal filename written to .reviews/ when the task is complete.
+ * @since TP-057
+ */
+export const REVIEWER_SHUTDOWN_SIGNAL = ".review-shutdown";
+
+// ── 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) ───────────────────────
 
@@ -1557,6 +1686,9 @@ export type EngineEventType =
 	| "merge_start"
 	| "merge_success"
 	| "merge_failed"
+	| "merge_health_warning"
+	| "merge_health_dead"
+	| "merge_health_stuck"
 	| "batch_complete"
 	| "batch_paused";
 
@@ -1622,6 +1754,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.11.0",
+  "version": "0.13.0",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",
@@ -31,6 +31,7 @@
     "dashboard/",
     "extensions/task-runner.ts",
     "extensions/task-orchestrator.ts",
+    "extensions/reviewer-extension.ts",
     "extensions/taskplane/",
     "skills/",
     "templates/"

package/templates/agents/local/task-reviewer.md

@@ -16,6 +16,7 @@ name: task-reviewer
   - Verdict format (APPROVE / REVISE)
   - Review file output conventions
   - Plan granularity guidance
+  - Persistent reviewer mode (wait_for_review tool workflow)
 
   Add project-specific review criteria below. Common examples:
   - Required test coverage thresholds

package/templates/agents/task-reviewer.md

@@ -9,12 +9,38 @@ task implementations. You have full read access to the codebase and can run comm
 
 ## How You Work
 
+You operate in one of two modes depending on available tools:
+
+### Persistent Mode (when `wait_for_review` tool is available)
+
+You are a **persistent reviewer** that stays alive across all review requests for
+a task. This preserves your context — you remember what you reviewed in earlier
+steps and can reference previous findings.
+
+1. Call `wait_for_review()` to receive your first review request
+2. The request specifies an **output file path** — you MUST write your review there
+3. Use your tools to explore the codebase — read files, run `git diff`, check patterns
+4. **Use the `write` tool to create the output file with your review**
+5. Use the appropriate verdict: APPROVE, REVISE, or RETHINK
+6. Call `wait_for_review()` again to receive the next request
+7. Repeat until you receive a `SHUTDOWN` signal, then exit cleanly
+
+**Cross-step awareness:** When reviewing later steps, reference your earlier
+reviews when relevant. For example: "I flagged X in Step 2's plan review —
+checking if it was addressed in this code review."
+
+### Fresh Spawn Mode (when `wait_for_review` is NOT available)
+
+You handle a single review request and then exit.
+
 1. Read the review request provided to you carefully
 2. The request specifies an **output file path** — you MUST write your review there
 3. Use your tools to explore the codebase — read files, run `git diff`, check patterns
 4. **Use the `write` tool to create the output file with your review**
 5. Use the appropriate verdict: APPROVE, REVISE, or RETHINK
 
+### Critical Rule (Both Modes)
+
 **CRITICAL:** Your review MUST be written to disk using the `write` tool.
 Do NOT just respond with text — the orchestrator reads the OUTPUT FILE to get
 your verdict. If you don't write the file, your review is lost.