taskplane 0.6.0 → 0.7.0

package/dashboard/server.cjs

@@ -507,6 +507,222 @@ function loadTelemetryData(batchState) {
   return result;
 }
 
+// ─── Supervisor Data Loading ────────────────────────────────────────────────
+
+/**
+ * Module-level tail state for supervisor JSONL files (actions.jsonl, events.jsonl).
+ * Reuses the same incremental tailing pattern as telemetry.
+ * Key: absolute file path → { offset, partial, entries }
+ */
+const supervisorTailStates = {
+  actions: { offset: 0, partial: "", entries: [] },
+  events: { offset: 0, partial: "", entries: [] },
+  conversation: { offset: 0, partial: "", entries: [] },
+};
+
+/**
+ * The last known batchId — used to detect batch changes and reset accumulators.
+ */
+let supervisorLastBatchId = "";
+
+/**
+ * Incrementally tail a JSONL file, accumulating parsed entries.
+ * Filters entries by batchId when provided.
+ *
+ * @param {string} filePath - Absolute path to the JSONL file
+ * @param {object} tailState - Mutable tail state { offset, partial, entries }
+ * @param {string} batchId - Batch ID to filter by (empty = no filter)
+ * @returns {object[]} The accumulated entries array (same reference as tailState.entries)
+ */
+function tailSupervisorJsonl(filePath, tailState, batchId) {
+  // Check file size
+  let fileSize;
+  try {
+    fileSize = fs.statSync(filePath).size;
+  } catch {
+    return tailState.entries; // File doesn't exist yet — return accumulated
+  }
+
+  // Handle file truncation/recreation
+  if (fileSize < tailState.offset) {
+    tailState.offset = 0;
+    tailState.partial = "";
+    tailState.entries = [];
+  }
+
+  if (fileSize <= tailState.offset) {
+    return tailState.entries; // No new data
+  }
+
+  // Read new bytes from offset
+  const bytesToRead = fileSize - tailState.offset;
+  const buf = Buffer.alloc(bytesToRead);
+  let fd;
+  try {
+    fd = fs.openSync(filePath, "r");
+  } catch {
+    return tailState.entries;
+  }
+  try {
+    fs.readSync(fd, buf, 0, bytesToRead, tailState.offset);
+  } catch {
+    fs.closeSync(fd);
+    return tailState.entries;
+  }
+  fs.closeSync(fd);
+  tailState.offset = fileSize;
+
+  // Split into lines, preserving partial trailing line
+  const chunk = tailState.partial + buf.toString("utf-8");
+  const lines = chunk.split("\n");
+  tailState.partial = lines.pop() || "";
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const entry = JSON.parse(trimmed);
+      // Filter by batchId if provided
+      if (batchId && entry.batchId && entry.batchId !== batchId) continue;
+      tailState.entries.push(entry);
+    } catch {
+      // Malformed JSON — skip
+    }
+  }
+
+  // Cap accumulated entries to prevent unbounded growth (keep last 500)
+  if (tailState.entries.length > 500) {
+    tailState.entries = tailState.entries.slice(-500);
+  }
+
+  return tailState.entries;
+}
+
+/**
+ * Read supervisor autonomy level from project config.
+ *
+ * Checks `.pi/taskplane-config.json` for `orchestrator.supervisor.autonomy`.
+ * Falls back to "supervised" (the default) if config is missing or malformed.
+ * This is needed because the lockfile does not contain the autonomy level.
+ *
+ * @returns {string} Autonomy level: "interactive" | "supervised" | "autonomous"
+ */
+function loadSupervisorAutonomy() {
+  try {
+    const configPath = path.join(REPO_ROOT, ".pi", "taskplane-config.json");
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const config = JSON.parse(raw);
+    const autonomy = config?.orchestrator?.supervisor?.autonomy;
+    if (autonomy === "interactive" || autonomy === "supervised" || autonomy === "autonomous") {
+      return autonomy;
+    }
+  } catch {
+    // Config missing or malformed — use default
+  }
+  return "supervised"; // Default per DEFAULT_SUPERVISOR_CONFIG
+}
+
+/**
+ * Load supervisor data for the dashboard.
+ *
+ * Reads (all from .pi/supervisor/):
+ * - lock.json: supervisor active/stale status, heartbeat, autonomy (from config)
+ * - actions.jsonl: recovery action audit trail (batch-scoped, incremental)
+ * - events.jsonl: engine + tier 0 events (batch-scoped, incremental)
+ * - conversation.jsonl: operator ↔ supervisor interaction log (spec §9.1)
+ * - summary.md: human-readable batch summary (generated on completion)
+ *
+ * Returns null when no supervisor files exist (pre-supervisor batches).
+ *
+ * @param {object|null} batchState - The batch state from batch-state.json
+ * @returns {object|null} Supervisor data object or null
+ */
+function loadSupervisorData(batchState) {
+  const supervisorDir = path.join(REPO_ROOT, ".pi", "supervisor");
+  const batchId = batchState ? (batchState.batchId || "") : "";
+
+  // Detect batch change — reset tail state accumulators
+  if (batchId && batchId !== supervisorLastBatchId) {
+    supervisorLastBatchId = batchId;
+    supervisorTailStates.actions = { offset: 0, partial: "", entries: [] };
+    supervisorTailStates.events = { offset: 0, partial: "", entries: [] };
+    supervisorTailStates.conversation = { offset: 0, partial: "", entries: [] };
+  }
+
+  // ── Lockfile: supervisor status ──
+  // The lockfile contains pid, sessionId, batchId, startedAt, heartbeat.
+  // It does NOT contain autonomy — that comes from project config.
+  let lock = null;
+  try {
+    const lockPath = path.join(supervisorDir, "lock.json");
+    const raw = fs.readFileSync(lockPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && parsed.pid && parsed.sessionId) {
+      // Determine if lock is stale (heartbeat older than 90s)
+      const heartbeatAge = parsed.heartbeat
+        ? Date.now() - new Date(parsed.heartbeat).getTime()
+        : Infinity;
+      const isStale = heartbeatAge > 90_000;
+
+      lock = {
+        active: !isStale,
+        pid: parsed.pid,
+        sessionId: parsed.sessionId,
+        batchId: parsed.batchId || "",
+        startedAt: parsed.startedAt || "",
+        heartbeat: parsed.heartbeat || "",
+        // Autonomy is NOT in the lockfile — derive from project config
+        autonomy: loadSupervisorAutonomy(),
+      };
+    }
+  } catch {
+    // No lockfile or malformed — supervisor is inactive
+  }
+
+  // ── Actions JSONL: recovery audit trail (batch-scoped, incremental) ──
+  const actionsPath = path.join(supervisorDir, "actions.jsonl");
+  const actions = tailSupervisorJsonl(actionsPath, supervisorTailStates.actions, batchId);
+
+  // ── Events JSONL: engine events (batch-scoped, incremental) ──
+  const eventsPath = path.join(supervisorDir, "events.jsonl");
+  const events = tailSupervisorJsonl(eventsPath, supervisorTailStates.events, batchId);
+
+  // ── Conversation JSONL: operator interaction log (spec §9.1) ──
+  // The supervisor writes operator↔supervisor messages to conversation.jsonl.
+  // Not yet implemented in all supervisor versions — degrade gracefully.
+  const conversationPath = path.join(supervisorDir, "conversation.jsonl");
+  const conversation = tailSupervisorJsonl(conversationPath, supervisorTailStates.conversation, batchId);
+
+  // ── Summary: human-readable batch summary (generated on completion) ──
+  // Per spec §9.1, the supervisor writes .pi/supervisor/summary.md when the
+  // batch completes or is abandoned. Read the file if it exists.
+  let summary = null;
+  try {
+    const summaryPath = path.join(supervisorDir, "summary.md");
+    summary = fs.readFileSync(summaryPath, "utf-8");
+  } catch {
+    // No summary yet — batch may still be running, or pre-supervisor batch
+  }
+
+  // If nothing exists at all, return null (pre-supervisor batch)
+  if (!lock && actions.length === 0 && events.length === 0 && conversation.length === 0 && !summary) {
+    // Check if the supervisor directory even exists
+    try {
+      fs.statSync(supervisorDir);
+    } catch {
+      return null; // No supervisor dir → pre-supervisor batch
+    }
+  }
+
+  return {
+    lock,
+    actions,
+    events,
+    conversation,
+    summary,
+  };
+}
+
 /**
  * Compute batch total cost from lane states (primary) and telemetry (supplementary).
  * Lane states are authoritative — telemetry provides additional data only for lanes
@@ -541,9 +757,10 @@ function buildDashboardState() {
   const laneStates = loadLaneStates();
   const telemetry = loadTelemetryData(state);
   const batchTotalCost = computeBatchTotalCost(laneStates, telemetry);
+  const supervisor = loadSupervisorData(state);
 
   if (!state) {
-    return { batch: null, tmuxSessions, laneStates: {}, telemetry: {}, batchTotalCost: 0, timestamp: Date.now() };
+    return { batch: null, tmuxSessions, laneStates: {}, telemetry: {}, batchTotalCost: 0, supervisor: null, timestamp: Date.now() };
   }
 
   const tasks = (state.tasks || []).map((task) => {
@@ -562,6 +779,7 @@ function buildDashboardState() {
     laneStates,
     telemetry,
     batchTotalCost,
+    supervisor,
     batch: {
       batchId: state.batchId,
       phase: state.phase,

package/extensions/task-runner.ts

@@ -1406,6 +1406,20 @@ export const _readExitSummary = readExitSummary;
 export const _buildExitDiagnostic = buildExitDiagnostic;
 export type { BuildExitDiagnosticInput };
 
+/**
+ * Determine whether a step is "low-risk" and should skip reviews.
+ * Low-risk steps: Step 0 (Preflight) and the final step (Delivery/Docs).
+ *
+ * @param stepNumber  The 0-based step number being evaluated
+ * @param totalSteps  Total number of steps in the task
+ * @returns true if the step should skip plan and code reviews
+ */
+export function isLowRiskStep(stepNumber: number, totalSteps: number): boolean {
+	if (totalSteps <= 0) return false;
+	const lastStepIndex = totalSteps - 1;
+	return stepNumber === 0 || stepNumber === lastStepIndex;
+}
+
 // ── TMUX Agent Spawner ───────────────────────────────────────────────
 
 /**
@@ -2081,11 +2095,20 @@ export default function (pi: ExtensionAPI) {
 		logExecution(statusPath, `Step ${step.number} started`, step.name);
 		updateWidgets();
 
+		// Skip reviews for low-risk steps (Step 0 / Preflight and final step / Delivery)
+		const _isLowRiskStep = isLowRiskStep(step.number, task.steps.length);
+
 		// Plan review (level ≥ 1)
 		if (task.reviewLevel >= 1) {
-			const verdict = await doReview("plan", step, ctx, stepBaselineCommit);
-			if (verdict === "RETHINK") {
-				ctx.ui.notify(`Reviewer: RETHINK on Step ${step.number} plan. Proceeding with caution.`, "warning");
+			if (_isLowRiskStep) {
+				const label = step.number === 0 ? "Preflight" : "final step";
+				logExecution(statusPath, `Skip plan review`, `Step ${step.number} (${label}) — low-risk`);
+				ctx.ui.notify(`⏭️ Skipping plan review for Step ${step.number} (${label})`, "info");
+			} else {
+				const verdict = await doReview("plan", step, ctx, stepBaselineCommit);
+				if (verdict === "RETHINK") {
+					ctx.ui.notify(`Reviewer: RETHINK on Step ${step.number} plan. Proceeding with caution.`, "warning");
+				}
 			}
 		}
 
@@ -2135,10 +2158,16 @@ export default function (pi: ExtensionAPI) {
 
 		// Code review (level ≥ 2)
 		if (task.reviewLevel >= 2 && state.phase === "running") {
-			const verdict = await doReview("code", step, ctx, stepBaselineCommit);
-			if (verdict === "REVISE") {
-				ctx.ui.notify(`Reviewer: REVISE on Step ${step.number}. Running worker to fix...`, "warning");
-				await runWorker(step, ctx); // One more pass to address issues
+			if (_isLowRiskStep) {
+				const label = step.number === 0 ? "Preflight" : "final step";
+				logExecution(statusPath, `Skip code review`, `Step ${step.number} (${label}) — low-risk`);
+				ctx.ui.notify(`⏭️ Skipping code review for Step ${step.number} (${label})`, "info");
+			} else {
+				const verdict = await doReview("code", step, ctx, stepBaselineCommit);
+				if (verdict === "REVISE") {
+					ctx.ui.notify(`Reviewer: REVISE on Step ${step.number}. Running worker to fix...`, "warning");
+					await runWorker(step, ctx); // One more pass to address issues
+				}
 			}
 		}
 

package/extensions/taskplane/config-loader.ts

@@ -261,6 +261,9 @@ function mapOrchestratorYaml(raw: any): Partial<OrchestratorSection> {
 	// verification: all keys are structural (TP-032)
 	if (raw.verification) result.verification = convertStructuralKeys(raw.verification);
 
+	// supervisor: all keys are structural (TP-041)
+	if (raw.supervisor) result.supervisor = convertStructuralKeys(raw.supervisor);
+
 	return result;
 }
 
@@ -515,6 +518,7 @@ function extractAllowlistedPreferences(raw: Record<string, any>): UserPreference
 	if (typeof raw.workerModel === "string") prefs.workerModel = raw.workerModel;
 	if (typeof raw.reviewerModel === "string") prefs.reviewerModel = raw.reviewerModel;
 	if (typeof raw.mergeModel === "string") prefs.mergeModel = raw.mergeModel;
+	if (typeof raw.supervisorModel === "string") prefs.supervisorModel = raw.supervisorModel;
 	if (typeof raw.dashboardPort === "number" && Number.isFinite(raw.dashboardPort)) {
 		prefs.dashboardPort = raw.dashboardPort;
 	}
@@ -541,6 +545,7 @@ function extractAllowlistedPreferences(raw: Record<string, any>): UserPreference
  *   prefs.workerModel   → config.taskRunner.worker.model
  *   prefs.reviewerModel → config.taskRunner.reviewer.model
  *   prefs.mergeModel    → config.orchestrator.merge.model
+ *   prefs.supervisorModel → config.orchestrator.supervisor.model
  *   prefs.dashboardPort → (no config target yet — stored only)
  */
 export function applyUserPreferences(config: TaskplaneConfig, prefs: UserPreferences): TaskplaneConfig {
@@ -554,6 +559,7 @@ export function applyUserPreferences(config: TaskplaneConfig, prefs: UserPrefere
 	applyStr(prefs.workerModel, (v) => { config.taskRunner.worker.model = v; });
 	applyStr(prefs.reviewerModel, (v) => { config.taskRunner.reviewer.model = v; });
 	applyStr(prefs.mergeModel, (v) => { config.orchestrator.merge.model = v; });
+	applyStr(prefs.supervisorModel, (v) => { config.orchestrator.supervisor.model = v; });
 
 	// spawnMode: enum — apply if defined (not a string-empty check)
 	if (prefs.spawnMode !== undefined) {
@@ -578,7 +584,7 @@ export function applyUserPreferences(config: TaskplaneConfig, prefs: UserPrefere
  * `<configRepo>/.taskplane/`) where files are scaffolded directly
  * without a `.pi/` subdirectory.
  */
-function hasConfigFiles(root: string): boolean {
+export function hasConfigFiles(root: string): boolean {
 	const files = [PROJECT_CONFIG_FILENAME, "task-runner.yaml", "task-orchestrator.yaml"];
 	for (const f of files) {
 		if (existsSync(join(root, ".pi", f)) || existsSync(join(root, f))) return true;

package/extensions/taskplane/config-schema.ts

@@ -241,8 +241,8 @@ export interface OrchestratorCoreConfig {
 	tmuxPrefix: string;
 	/** Operator identifier. Auto-detected from OS username if empty */
 	operatorId: string;
-	/** How completed batches are integrated. manual = user runs /orch-integrate. auto = fast-forward on completion. */
-	integration: "manual" | "auto";
+	/** How completed batches are integrated. manual = user runs /orch-integrate. supervised = supervisor proposes plan, asks confirmation. auto = supervisor executes without asking. */
+	integration: "manual" | "supervised" | "auto";
 }
 
 /** Dependency resolution settings */
@@ -360,6 +360,14 @@ export interface VerificationConfig {
 /**
  * All orchestrator settings, previously from `.pi/task-orchestrator.yaml`.
  */
+/** Supervisor agent settings (TP-041). */
+export interface SupervisorSectionConfig {
+	/** Supervisor model (empty = inherit active session model) */
+	model: string;
+	/** Autonomy level for recovery actions */
+	autonomy: "interactive" | "supervised" | "autonomous";
+}
+
 export interface OrchestratorSection {
 	/** Core orchestrator settings */
 	orchestrator: OrchestratorCoreConfig;
@@ -377,6 +385,8 @@ export interface OrchestratorSection {
 	monitoring: MonitoringConfig;
 	/** Verification baseline fingerprinting (TP-032) */
 	verification: VerificationConfig;
+	/** Supervisor agent (TP-041) */
+	supervisor: SupervisorSectionConfig;
 }
 
 
@@ -435,6 +445,7 @@ export interface TaskplaneConfig {
  * | workerModel        | taskRunner.worker.model              | string  |
  * | reviewerModel      | taskRunner.reviewer.model            | string  |
  * | mergeModel         | orchestrator.merge.model             | string  |
+ * | supervisorModel    | orchestrator.supervisor.model        | string  |
  * | dashboardPort      | (preferences-only; not yet in schema)| number  |
  */
 export interface UserPreferences {
@@ -450,6 +461,8 @@ export interface UserPreferences {
 	reviewerModel?: string;
 	/** Merge model override (overrides orchestrator.merge.model) */
 	mergeModel?: string;
+	/** Supervisor model override (overrides orchestrator.supervisor.model) (TP-041) */
+	supervisorModel?: string;
 	/** Dashboard port (preferences-only; not yet wired into config schema) */
 	dashboardPort?: number;
 }
@@ -549,6 +562,10 @@ export const DEFAULT_ORCHESTRATOR_SECTION: OrchestratorSection = {
 		mode: "permissive",
 		flakyReruns: 1,
 	},
+	supervisor: {
+		model: "",
+		autonomy: "supervised",
+	},
 };
 
 /** Default unified config */

package/extensions/taskplane/config.ts

@@ -11,8 +11,11 @@
  * @module orch/config
  */
 
-import { loadProjectConfig, toOrchestratorConfig, toTaskRunnerConfig } from "./config-loader.ts";
+import { loadProjectConfig, toOrchestratorConfig, toTaskRunnerConfig, hasConfigFiles } from "./config-loader.ts";
+export { hasConfigFiles } from "./config-loader.ts";
 import type { OrchestratorConfig, TaskRunnerConfig } from "./types.ts";
+import type { SupervisorConfig } from "./supervisor.ts";
+import { DEFAULT_SUPERVISOR_CONFIG } from "./supervisor.ts";
 
 // ── Config Loading ───────────────────────────────────────────────────
 
@@ -49,3 +52,22 @@ export function loadTaskRunnerConfig(cwd: string, pointerConfigRoot?: string): T
 	const unified = loadProjectConfig(cwd, pointerConfigRoot);
 	return toTaskRunnerConfig(unified);
 }
+
+/**
+ * Load supervisor config from unified project config.
+ *
+ * Extracts the `orchestrator.supervisor` section from the unified config.
+ * Falls back to defaults if the section is missing (backward compatibility
+ * with configs created before TP-041).
+ *
+ * @since TP-041
+ */
+export function loadSupervisorConfig(cwd: string, pointerConfigRoot?: string): SupervisorConfig {
+	const unified = loadProjectConfig(cwd, pointerConfigRoot);
+	const section = unified.orchestrator.supervisor;
+	if (!section) return { ...DEFAULT_SUPERVISOR_CONFIG };
+	return {
+		model: section.model ?? DEFAULT_SUPERVISOR_CONFIG.model,
+		autonomy: section.autonomy ?? DEFAULT_SUPERVISOR_CONFIG.autonomy,
+	};
+}