gsd-pi 2.37.0 → 2.37.1-dev.49503be

package/src/resources/extensions/gsd/auto-loop.ts

@@ -15,6 +15,7 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import type { AutoSession } from "./auto/session.js";
 import { NEW_SESSION_TIMEOUT_MS } from "./auto/session.js";
 import type { GSDPreferences } from "./preferences.js";
+import type { SessionLockStatus } from "./session-lock.js";
 import type { GSDState } from "./types.js";
 import type { CloseoutOptions } from "./auto-unit-closeout.js";
 import type { PostUnitContext } from "./auto-post-unit.js";
@@ -307,7 +308,7 @@ export interface LoopDeps {
   checkResourcesStale: (version: string | null) => string | null;
 
   // Session lock
-  validateSessionLock: (basePath: string) => boolean;
+  validateSessionLock: (basePath: string) => SessionLockStatus;
   updateSessionLock: (
     basePath: string,
     unitType: string,
@@ -315,7 +316,10 @@ export interface LoopDeps {
     completedUnits: number,
     sessionFile?: string,
   ) => void;
-  handleLostSessionLock: (ctx?: ExtensionContext) => void;
+  handleLostSessionLock: (
+    ctx?: ExtensionContext,
+    lockStatus?: SessionLockStatus,
+  ) => void;
 
   // Milestone transition functions
   sendDesktopNotification: (
@@ -559,10 +563,24 @@ export async function autoLoop(
     try {
       // ── Blanket try/catch: one bad iteration must not kill the session
 
-      if (deps.lockBase() && !deps.validateSessionLock(deps.lockBase())) {
-        deps.handleLostSessionLock(ctx);
-        debugLog("autoLoop", { phase: "exit", reason: "session-lock-lost" });
-        break;
+      const sessionLockBase = deps.lockBase();
+      if (sessionLockBase) {
+        const lockStatus = deps.validateSessionLock(sessionLockBase);
+        if (!lockStatus.valid) {
+          debugLog("autoLoop", {
+            phase: "session-lock-invalid",
+            reason: lockStatus.failureReason ?? "unknown",
+            existingPid: lockStatus.existingPid,
+            expectedPid: lockStatus.expectedPid,
+          });
+          deps.handleLostSessionLock(ctx, lockStatus);
+          debugLog("autoLoop", {
+            phase: "exit",
+            reason: "session-lock-lost",
+            detail: lockStatus.failureReason ?? "unknown",
+          });
+          break;
+        }
       }
 
       // ── Phase 1: Pre-dispatch ───────────────────────────────────────────

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -217,6 +217,20 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
       }
     }
 
+    // Reactive state cleanup on slice completion
+    if (s.currentUnit.type === "complete-slice") {
+      try {
+        const parts = s.currentUnit.id.split("/");
+        const [mid, sid] = parts;
+        if (mid && sid) {
+          const { clearReactiveState } = await import("./reactive-graph.js");
+          clearReactiveState(s.basePath, mid, sid);
+        }
+      } catch {
+        // Non-fatal
+      }
+    }
+
     // Post-triage: execute actionable resolutions
     if (s.currentUnit.type === "triage-captures") {
       try {

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -1234,6 +1234,74 @@ export async function buildReassessRoadmapPrompt(
   });
 }
 
+// ─── Reactive Execute Prompt ──────────────────────────────────────────────
+
+export async function buildReactiveExecutePrompt(
+  mid: string, midTitle: string, sid: string, sTitle: string,
+  readyTaskIds: string[], base: string,
+): Promise<string> {
+  const { loadSliceTaskIO, deriveTaskGraph, graphMetrics } = await import("./reactive-graph.js");
+
+  // Build graph for context
+  const taskIO = await loadSliceTaskIO(base, mid, sid);
+  const graph = deriveTaskGraph(taskIO);
+  const metrics = graphMetrics(graph);
+
+  // Build graph context section
+  const graphLines: string[] = [];
+  for (const node of graph) {
+    const status = node.done ? "✅ done" : readyTaskIds.includes(node.id) ? "🟢 ready" : "⏳ waiting";
+    const deps = node.dependsOn.length > 0 ? ` (depends on: ${node.dependsOn.join(", ")})` : "";
+    graphLines.push(`- **${node.id}: ${node.title}** — ${status}${deps}`);
+    if (node.outputFiles.length > 0) {
+      graphLines.push(`  - Outputs: ${node.outputFiles.map(f => `\`${f}\``).join(", ")}`);
+    }
+  }
+  const graphContext = [
+    `Tasks: ${metrics.taskCount}, Edges: ${metrics.edgeCount}, Ready: ${metrics.readySetSize}`,
+    "",
+    ...graphLines,
+  ].join("\n");
+
+  // Build individual subagent prompts for each ready task
+  const subagentSections: string[] = [];
+  const readyTaskListLines: string[] = [];
+
+  for (const tid of readyTaskIds) {
+    const node = graph.find((n) => n.id === tid);
+    const tTitle = node?.title ?? tid;
+    readyTaskListLines.push(`- **${tid}: ${tTitle}**`);
+
+    // Build a full execute-task prompt for this task (reuse existing builder)
+    const taskPrompt = await buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base);
+
+    subagentSections.push([
+      `### ${tid}: ${tTitle}`,
+      "",
+      "Use this as the prompt for a `subagent` call:",
+      "",
+      "```",
+      taskPrompt,
+      "```",
+    ].join("\n"));
+  }
+
+  const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
+
+  return loadPrompt("reactive-execute", {
+    workingDirectory: base,
+    milestoneId: mid,
+    milestoneTitle: midTitle,
+    sliceId: sid,
+    sliceTitle: sTitle,
+    graphContext,
+    readyTaskCount: String(readyTaskIds.length),
+    readyTaskList: readyTaskListLines.join("\n"),
+    subagentPrompts: subagentSections.join("\n\n---\n\n"),
+    inlinedTemplates,
+  });
+}
+
 export async function buildRewriteDocsPrompt(
   mid: string, midTitle: string,
   activeSlice: { id: string; title: string } | null,

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -26,6 +26,7 @@ import {
   resolveSlicePath,
   resolveSliceFile,
   resolveTasksDir,
+  resolveTaskFiles,
   relMilestoneFile,
   relSliceFile,
   relSlicePath,
@@ -110,6 +111,9 @@ export function resolveExpectedArtifactPath(
     }
     case "rewrite-docs":
       return null;
+    case "reactive-execute":
+      // Reactive execute produces multiple task summaries — verified separately
+      return null;
     default:
       return null;
   }
@@ -148,6 +152,20 @@ export function verifyExpectedArtifact(
     return !content.includes("**Scope:** active");
   }
 
+  // Reactive-execute: verify that at least one new task summary was written.
+  // The unitId is "{mid}/{sid}/reactive" — extract mid and sid to check.
+  if (unitType === "reactive-execute") {
+    const parts = unitId.split("/");
+    const mid = parts[0];
+    const sid = parts[1];
+    if (!mid || !sid) return false;
+    const tDir = resolveTasksDir(base, mid, sid);
+    if (!tDir) return false;
+    const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
+    // At least one summary file should exist
+    return summaryFiles.length > 0;
+  }
+
   const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
   // For unit types with no verifiable artifact (null path), the parent directory
   // is missing on disk — treat as stale completion state so the key gets evicted (#313).

package/src/resources/extensions/gsd/auto.ts

@@ -47,10 +47,11 @@ import {
 } from "./crash-recovery.js";
 import {
   acquireSessionLock,
-  validateSessionLock,
+  getSessionLockStatus,
   releaseSessionLock,
   updateSessionLock,
 } from "./session-lock.js";
+import type { SessionLockStatus } from "./session-lock.js";
 import {
   clearUnitRuntimeRecord,
   inspectExecuteTaskDurability,
@@ -417,6 +418,38 @@ export function stopAutoRemote(projectRoot: string): {
   }
 }
 
+/**
+ * Check if a remote auto-mode session is running (from a different process).
+ * Reads the crash lock, checks PID liveness, and returns session details.
+ * Used by the guard in commands.ts to prevent bare /gsd, /gsd next, and
+ * /gsd auto from stealing the session lock.
+ */
+export function checkRemoteAutoSession(projectRoot: string): {
+  running: boolean;
+  pid?: number;
+  unitType?: string;
+  unitId?: string;
+  startedAt?: string;
+  completedUnits?: number;
+} {
+  const lock = readCrashLock(projectRoot);
+  if (!lock) return { running: false };
+
+  if (!isLockProcessAlive(lock)) {
+    // Stale lock from a dead process — not a live remote session
+    return { running: false };
+  }
+
+  return {
+    running: true,
+    pid: lock.pid,
+    unitType: lock.unitType,
+    unitId: lock.unitId,
+    startedAt: lock.startedAt,
+    completedUnits: lock.completedUnits,
+  };
+}
+
 export function isStepMode(): boolean {
   return s.stepMode;
 }
@@ -461,15 +494,33 @@ function buildSnapshotOpts(
   };
 }
 
-function handleLostSessionLock(ctx?: ExtensionContext): void {
-  debugLog("session-lock-lost", { lockBase: lockBase() });
+function handleLostSessionLock(
+  ctx?: ExtensionContext,
+  lockStatus?: SessionLockStatus,
+): void {
+  debugLog("session-lock-lost", {
+    lockBase: lockBase(),
+    reason: lockStatus?.failureReason,
+    existingPid: lockStatus?.existingPid,
+    expectedPid: lockStatus?.expectedPid,
+  });
   s.active = false;
   s.paused = false;
   clearUnitTimeout();
   deregisterSigtermHandler();
   clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
+  const message =
+    lockStatus?.failureReason === "pid-mismatch"
+      ? lockStatus.existingPid
+        ? `Session lock moved to PID ${lockStatus.existingPid} — another GSD process appears to have taken over. Stopping gracefully.`
+        : "Session lock moved to a different process — another GSD process appears to have taken over. Stopping gracefully."
+      : lockStatus?.failureReason === "missing-metadata"
+        ? "Session lock metadata disappeared, so ownership could not be confirmed. Stopping gracefully."
+        : lockStatus?.failureReason === "compromised"
+          ? "Session lock was compromised or invalidated during heartbeat checks; takeover was not confirmed. Stopping gracefully."
+          : "Session lock lost. Stopping gracefully.";
   ctx?.ui.notify(
-    "Session lock lost — another GSD process appears to have taken over. Stopping gracefully.",
+    message,
     "error",
   );
   ctx?.ui.setStatus("gsd-auto", undefined);
@@ -736,7 +787,7 @@ function buildLoopDeps(): LoopDeps {
     checkResourcesStale,
 
     // Session lock
-    validateSessionLock,
+    validateSessionLock: getSessionLockStatus,
     updateSessionLock,
     handleLostSessionLock,
 

package/src/resources/extensions/gsd/commands.ts

@@ -15,7 +15,7 @@ import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
 import { GSDVisualizerOverlay } from "./visualizer-overlay.js";
 import { showQueue, showDiscuss, showHeadlessMilestoneCreation } from "./guided-flow.js";
-import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote } from "./auto.js";
+import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote, checkRemoteAutoSession } from "./auto.js";
 import { dispatchDirectPhase } from "./auto-direct-dispatch.js";
 import { resolveProjectRoot } from "./worktree.js";
 import { assertSafeDirectory } from "./validate-directory.js";
@@ -50,6 +50,7 @@ import { handleLogs } from "./commands-logs.js";
 import { handleStart, handleTemplates, getTemplateCompletions } from "./commands-workflow-templates.js";
 import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
 import { handleCmux } from "./commands-cmux.js";
+import { showNextAction } from "../shared/mod.js";
 
 
 /** Resolve the effective project root, accounting for worktree paths. */
@@ -72,36 +73,88 @@ export function projectRoot(): string {
 }
 
 /**
- * Check if another process holds the auto-mode session lock.
- * Returns the lock data if a remote session is alive, null otherwise.
+ * Guard against starting auto-mode when a remote session is already running.
+ * Returns true if the caller should proceed with startAuto, false if handled.
  */
-function getRemoteAutoSession(basePath: string): { pid: number } | null {
-  const lockData = readSessionLockData(basePath);
-  if (!lockData) return null;
-  if (lockData.pid === process.pid) return null;
-  if (!isSessionLockProcessAlive(lockData)) return null;
-  return { pid: lockData.pid };
-}
+async function guardRemoteSession(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<boolean> {
+  // Local session already active — proceed (startAuto handles re-entrant calls)
+  if (isAutoActive() || isAutoPaused()) return true;
+
+  const remote = checkRemoteAutoSession(projectRoot());
+  if (!remote.running || !remote.pid) return true;
+
+  const unitLabel = remote.unitType && remote.unitId
+    ? `${remote.unitType} (${remote.unitId})`
+    : "unknown unit";
+  const unitsMsg = remote.completedUnits != null
+    ? `${remote.completedUnits} units completed`
+    : "";
+
+  const choice = await showNextAction(ctx, {
+    title: `Auto-mode is running in another terminal (PID ${remote.pid})`,
+    summary: [
+      `Currently executing: ${unitLabel}`,
+      ...(unitsMsg ? [unitsMsg] : []),
+      ...(remote.startedAt ? [`Started: ${remote.startedAt}`] : []),
+    ],
+    actions: [
+      {
+        id: "status",
+        label: "View status",
+        description: "Show the current GSD progress dashboard.",
+        recommended: true,
+      },
+      {
+        id: "steer",
+        label: "Steer the session",
+        description: "Use /gsd steer <instruction> to redirect the running session.",
+      },
+      {
+        id: "stop",
+        label: "Stop remote session",
+        description: `Send SIGTERM to PID ${remote.pid} to stop it gracefully.`,
+      },
+      {
+        id: "force",
+        label: "Force start (steal lock)",
+        description: "Start a new session, terminating the existing one.",
+      },
+    ],
+    notYetMessage: "Run /gsd when ready.",
+  });
 
-/**
- * Show a steering menu when auto-mode is running in another process.
- * Returns true if a remote session was detected (caller should return early).
- */
-function notifyRemoteAutoActive(ctx: ExtensionCommandContext, basePath: string): boolean {
-  const remote = getRemoteAutoSession(basePath);
-  if (!remote) return false;
-  ctx.ui.notify(
-    `Auto-mode is running in another process (PID ${remote.pid}).\n` +
-    `Use these commands to interact with it:\n` +
-    `  /gsd status   — check progress\n` +
-    `  /gsd discuss  — discuss architecture decisions\n` +
-    `  /gsd queue    — queue the next milestone\n` +
-    `  /gsd steer    — apply an override to active work\n` +
-    `  /gsd capture  — fire-and-forget thought\n` +
-    `  /gsd stop     — stop auto-mode`,
-    "warning",
-  );
-  return true;
+  if (choice === "status") {
+    await handleStatus(ctx);
+    return false;
+  }
+  if (choice === "steer") {
+    ctx.ui.notify(
+      "Use /gsd steer <instruction> to redirect the running auto-mode session.\n" +
+      "Example: /gsd steer Use Postgres instead of SQLite",
+      "info",
+    );
+    return false;
+  }
+  if (choice === "stop") {
+    const result = stopAutoRemote(projectRoot());
+    if (result.found) {
+      ctx.ui.notify(`Sent stop signal to auto-mode session (PID ${result.pid}). It will shut down gracefully.`, "info");
+    } else if (result.error) {
+      ctx.ui.notify(`Failed to stop remote auto-mode: ${result.error}`, "error");
+    } else {
+      ctx.ui.notify("Remote session is no longer running.", "info");
+    }
+    return false;
+  }
+  if (choice === "force") {
+    return true; // Proceed — startAuto will steal the lock
+  }
+
+  // "not_yet" or escape
+  return false;
 }
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
@@ -598,10 +651,10 @@ export async function handleGSDCommand(
           await handleDryRun(ctx, projectRoot());
           return;
         }
-        if (notifyRemoteAutoActive(ctx, projectRoot())) return;
         const verboseMode = trimmed.includes("--verbose");
         const debugMode = trimmed.includes("--debug");
         if (debugMode) enableDebug(projectRoot());
+        if (!(await guardRemoteSession(ctx, pi))) return;
         await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
         return;
       }
@@ -610,6 +663,7 @@ export async function handleGSDCommand(
         const verboseMode = trimmed.includes("--verbose");
         const debugMode = trimmed.includes("--debug");
         if (debugMode) enableDebug(projectRoot());
+        if (!(await guardRemoteSession(ctx, pi))) return;
         await startAuto(ctx, pi, projectRoot(), verboseMode);
         return;
       }
@@ -993,7 +1047,7 @@ Examples:
       }
 
       if (trimmed === "") {
-        if (notifyRemoteAutoActive(ctx, projectRoot())) return;
+        if (!(await guardRemoteSession(ctx, pi))) return;
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
         return;
       }

package/src/resources/extensions/gsd/files.ts

@@ -15,6 +15,7 @@ import type {
   Summary, SummaryFrontmatter, SummaryRequires, FileModified,
   Continue, ContinueFrontmatter, ContinueStatus,
   RequirementCounts,
+  TaskIO,
   SecretsManifest, SecretsManifestEntry, SecretsManifestEntryStatus,
   ManifestStatus,
 } from './types.js';
@@ -724,6 +725,50 @@ export function countMustHavesMentionedInSummary(
   return count;
 }
 
+// ─── Task Plan IO Extractor ────────────────────────────────────────────────
+
+/**
+ * Extract input and output file paths from a task plan's `## Inputs` and
+ * `## Expected Output` sections. Looks for backtick-wrapped file paths on
+ * each line (e.g. `` `src/foo.ts` ``).
+ *
+ * Returns empty arrays for missing/empty sections — callers should treat
+ * tasks with no IO as ambiguous (sequential fallback trigger).
+ */
+export function parseTaskPlanIO(content: string): { inputFiles: string[]; outputFiles: string[] } {
+  const backtickPathRegex = /`([^`]+)`/g;
+
+  function extractPaths(sectionText: string | null): string[] {
+    if (!sectionText) return [];
+    const paths: string[] = [];
+    for (const line of sectionText.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      let match: RegExpExecArray | null;
+      backtickPathRegex.lastIndex = 0;
+      while ((match = backtickPathRegex.exec(trimmed)) !== null) {
+        const candidate = match[1];
+        // Filter out things that look like code tokens rather than file paths
+        // (e.g. `true`, `false`, `npm run test`). A file path has at least one
+        // dot or slash.
+        if (candidate.includes("/") || candidate.includes(".")) {
+          paths.push(candidate);
+        }
+      }
+    }
+    return paths;
+  }
+
+  const [, body] = splitFrontmatter(content);
+  const inputSection = extractSection(body, "Inputs");
+  const outputSection = extractSection(body, "Expected Output");
+
+  return {
+    inputFiles: extractPaths(inputSection),
+    outputFiles: extractPaths(outputSection),
+  };
+}
+
 // ─── UAT Type Extractor ────────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/git-service.ts

@@ -479,9 +479,20 @@ export class GitServiceImpl {
 
     const wtName = detectWorktreeName(this.basePath);
     if (wtName) {
+      // Auto-mode worktrees use milestone/<MID> branches (wtName = milestone ID)
+      const milestoneBranch = `milestone/${wtName}`;
+      const currentBranch = nativeGetCurrentBranch(this.basePath);
+
+      // If we're on a milestone/<MID> branch, use it (auto-mode case)
+      if (currentBranch.startsWith("milestone/")) {
+        return currentBranch;
+      }
+
+      // Otherwise check for manual worktree branch (worktree/<name>)
       const wtBranch = `worktree/${wtName}`;
       if (nativeBranchExists(this.basePath, wtBranch)) return wtBranch;
-      return nativeGetCurrentBranch(this.basePath);
+
+      return currentBranch;
     }
 
     // Repo-level default detection: origin/HEAD → main → master → current branch.

package/src/resources/extensions/gsd/history.ts

@@ -2,7 +2,8 @@
 // Human-readable display of past auto-mode unit executions.
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { formatDuration, padRight, truncateWithEllipsis } from "../shared/format-utils.js";
+import { formatDuration, truncateWithEllipsis } from "../shared/format-utils.js";
+import { padRight } from "../shared/layout-utils.js";
 import {
   getLedger, getProjectTotals, formatCost, formatTokenCount,
   aggregateBySlice, aggregateByPhase, aggregateByModel, loadLedgerFromDisk,

package/src/resources/extensions/gsd/metrics.ts

@@ -20,8 +20,10 @@ import { getAndClearSkills } from "./skill-telemetry.js";
 import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 import { parseUnitId } from "./unit-id.js";
 
-// Re-export from shared — canonical implementation lives in format-utils.
-export { formatTokenCount } from "../shared/mod.js";
+// Re-export from shared — import directly from format-utils to avoid pulling
+// in the full barrel (mod.js → ui.js → @gsd/pi-tui) which breaks when loaded
+// outside jiti's alias resolution (e.g. dynamic import in auto-loop reports).
+export { formatTokenCount } from "../shared/format-utils.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 

package/src/resources/extensions/gsd/preferences-types.ts

@@ -18,6 +18,7 @@ import type {
   ParallelConfig,
   CompressionStrategy,
   ContextSelectionMode,
+  ReactiveExecutionConfig,
 } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 
@@ -86,12 +87,13 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "compression_strategy",
   "context_selection",
   "widget_mode",
+  "reactive_execution",
 ]);
 
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [
   "research-milestone", "plan-milestone", "research-slice", "plan-slice",
-  "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
+  "execute-task", "reactive-execute", "complete-slice", "replan-slice", "reassess-roadmap",
   "run-uat", "complete-milestone",
 ] as const;
 export type UnitType = (typeof KNOWN_UNIT_TYPES)[number];
@@ -215,6 +217,8 @@ export interface GSDPreferences {
   context_selection?: ContextSelectionMode;
   /** Default widget display mode for auto-mode dashboard. "full" | "small" | "min" | "off". Default: "full". */
   widget_mode?: "full" | "small" | "min" | "off";
+  /** Reactive (graph-derived parallel) task execution within slices. Disabled by default. */
+  reactive_execution?: ReactiveExecutionConfig;
 }
 
 export interface LoadedGSDPreferences {

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -496,6 +496,47 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Reactive Execution ─────────────────────────────────────────────────
+  if (preferences.reactive_execution !== undefined) {
+    if (typeof preferences.reactive_execution === "object" && preferences.reactive_execution !== null) {
+      const re = preferences.reactive_execution as unknown as Record<string, unknown>;
+      const validRe: Record<string, unknown> = {};
+
+      if (re.enabled !== undefined) {
+        if (typeof re.enabled === "boolean") validRe.enabled = re.enabled;
+        else errors.push("reactive_execution.enabled must be a boolean");
+      }
+      if (re.max_parallel !== undefined) {
+        const mp = typeof re.max_parallel === "number" ? re.max_parallel : Number(re.max_parallel);
+        if (Number.isFinite(mp) && mp >= 1 && mp <= 8) {
+          validRe.max_parallel = Math.floor(mp);
+        } else {
+          errors.push("reactive_execution.max_parallel must be a number between 1 and 8");
+        }
+      }
+      if (re.isolation_mode !== undefined) {
+        if (re.isolation_mode === "same-tree") {
+          validRe.isolation_mode = "same-tree";
+        } else {
+          errors.push('reactive_execution.isolation_mode must be "same-tree"');
+        }
+      }
+
+      const knownReKeys = new Set(["enabled", "max_parallel", "isolation_mode"]);
+      for (const key of Object.keys(re)) {
+        if (!knownReKeys.has(key)) {
+          warnings.push(`unknown reactive_execution key "${key}" — ignored`);
+        }
+      }
+
+      if (Object.keys(validRe).length > 0) {
+        validated.reactive_execution = validRe as unknown as import("./types.js").ReactiveExecutionConfig;
+      }
+    } else {
+      errors.push("reactive_execution must be an object");
+    }
+  }
+
   // ─── Verification Preferences ───────────────────────────────────────────
   if (preferences.verification_commands !== undefined) {
     if (Array.isArray(preferences.verification_commands)) {