smithers-orchestrator 0.8.4 → 0.9.0

package/README.md

@@ -11,6 +11,7 @@
 * Re-renders the workflow after each step
 * Resumes exactly where it left off after crashes
 * Supports subscriptions
+* Hot-reloads workflow code on file save (prompts, config, components) without restarting
 
 There is no hidden in-memory state. Every task result is stored as:
 
@@ -226,6 +227,36 @@ smithers list workflow.tsx
 smithers approve workflow.tsx --run-id abc123 --node-id review
 ```
 
+## Hot Module Replacement
+
+Edit your workflow files while a run is executing. Smithers watches your source tree and hot-reloads changes on save — prompts, config, agent settings, and component structure — without restarting the process or losing run state.
+
+```bash
+smithers run workflow.tsx --hot
+```
+
+In-flight tasks continue with their original code. Only newly scheduled tasks pick up the changes.
+
+```
+[00:05:12] ⟳ File change detected: 1 file(s)
+[00:05:12] ⟳ Workflow reloaded (generation 1)
+[00:05:13] → implement-cat-12 (attempt 1, iteration 0)
+```
+
+**What you can change live:**
+
+* Prompt strings and `.md`/`.mdx` prompt files
+* Focus lists, config values, concurrency settings
+* Agent models, timeouts, system prompts
+* JSX tree structure (add/remove/reorder tasks)
+
+**What requires a restart:**
+
+* Output schema changes (Zod shapes)
+* Database path changes
+
+See the [Hot Reload Guide](/guides/hot-reload) for details.
+
 ---
 
 ## Built-in Tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smithers-orchestrator",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "AI workflow orchestration with JSX",
   "author": "William Cory",
   "license": "MIT",

package/src/RunOptions.ts

@@ -1,5 +1,18 @@
 import type { SmithersEvent } from "./SmithersEvent";
 
+export type HotReloadOptions = {
+  /** Root directory to watch for changes (default: auto-detect from workflow entry) */
+  rootDir?: string;
+  /** Directory for generation overlays (default: .smithers/hmr/<runId>) */
+  outDir?: string;
+  /** Max overlay generations to keep (default: 3) */
+  maxGenerations?: number;
+  /** Whether to cancel tasks that become unmounted after hot reload (default: false) */
+  cancelUnmounted?: boolean;
+  /** Debounce interval in ms for file change events (default: 100) */
+  debounceMs?: number;
+};
+
 export type RunOptions = {
   runId?: string;
   input: Record<string, unknown>;
@@ -13,4 +26,5 @@ export type RunOptions = {
   allowNetwork?: boolean;
   maxOutputBytes?: number;
   toolTimeoutMs?: number;
+  hot?: boolean | HotReloadOptions;
 };

package/src/SmithersEvent.ts

@@ -152,4 +152,31 @@ export type SmithersEvent =
       success: boolean;
       error?: string;
       timestampMs: number;
+    }
+  | {
+      type: "WorkflowReloadDetected";
+      runId: string;
+      changedFiles: string[];
+      timestampMs: number;
+    }
+  | {
+      type: "WorkflowReloaded";
+      runId: string;
+      generation: number;
+      changedFiles: string[];
+      timestampMs: number;
+    }
+  | {
+      type: "WorkflowReloadFailed";
+      runId: string;
+      error: unknown;
+      changedFiles: string[];
+      timestampMs: number;
+    }
+  | {
+      type: "WorkflowReloadUnsafe";
+      runId: string;
+      reason: string;
+      changedFiles: string[];
+      timestampMs: number;
     };

package/src/cli/index.ts

@@ -112,6 +112,7 @@ Run options:
   --no-log               Disable event log file output
   --allow-network        Allow network access for bash tool
   --max-output-bytes N   Max tool output bytes (default: 200000)
+  --hot                  Enable hot module replacement (watch & reload workflow on file changes)
   --tool-timeout-ms N    Tool timeout in ms (default: 60000)
   --version, -v          Print version
 `);
@@ -130,8 +131,32 @@ Run options:
       process.exit(4);
     }
     const resolvedWorkflowPath = resolve(process.cwd(), workflowPath);
+    if (args.hot) {
+      process.env.SMITHERS_HOT = "1";
+    }
     const workflow = await loadWorkflow(workflowPath);
     ensureSmithersTables(workflow.db as any);
+    if (args.hot) {
+      process.stderr.write(`[hot] Hot reload enabled\n`);
+    }
+
+    // Register cleanup to close the SQLite connection before process exit.
+    // This prevents libsqlite3 fatal "unfinalized statement" errors that
+    // crash the process when bun's GC tries to close the Database while
+    // Drizzle's prepared statements are still alive.
+    const closeSqlite = () => {
+      try {
+        const client: any = (workflow.db as any)?.$client;
+        if (client && typeof client.close === "function") {
+          client.close();
+        }
+      } catch {
+        // Best-effort — ignore errors during cleanup
+      }
+    };
+    process.on("exit", closeSqlite);
+    process.on("SIGINT", () => { closeSqlite(); process.exit(130); });
+    process.on("SIGTERM", () => { closeSqlite(); process.exit(143); });
     const input = args.input ? parseJsonOrExit(args.input, "input") : {};
     const runId = args["run-id"];
     const resume = cmd === "resume" || Boolean(args.resume);
@@ -227,6 +252,26 @@ Run options:
         case "FrameCommitted":
           // Don't print frame commits - too noisy
           break;
+        case "WorkflowReloadDetected":
+          process.stderr.write(
+            `[${ts}] ⟳ File change detected: ${(event as any).changedFiles?.length ?? 0} file(s)\n`,
+          );
+          break;
+        case "WorkflowReloaded":
+          process.stderr.write(
+            `[${ts}] ⟳ Workflow reloaded (generation ${(event as any).generation})\n`,
+          );
+          break;
+        case "WorkflowReloadFailed":
+          process.stderr.write(
+            `[${ts}] ⚠ Workflow reload failed: ${typeof (event as any).error === "string" ? (event as any).error : ((event as any).error?.message ?? "unknown")}\n`,
+          );
+          break;
+        case "WorkflowReloadUnsafe":
+          process.stderr.write(
+            `[${ts}] ⚠ Workflow reload blocked: ${(event as any).reason}\n`,
+          );
+          break;
       }
     };
     const result = await runWorkflow(workflow, {
@@ -240,6 +285,7 @@ Run options:
       allowNetwork: Boolean(args["allow-network"]),
       maxOutputBytes,
       toolTimeoutMs,
+      hot: Boolean(args["hot"]),
       onProgress,
     });
     console.log(JSON.stringify(result, null, 2));

package/src/create.ts

@@ -13,8 +13,28 @@ import type { WorkflowProps, TaskProps } from "./components";
 import { zodToTable } from "./zodToTable";
 import { zodToCreateTableSQL } from "./zodToCreateTableSQL";
 import { camelToSnake } from "./camelToSnake";
+import { resolve } from "node:path";
 import type { z } from "zod";
 
+type HotCacheEntry = {
+  api: CreateSmithersApi<any>;
+  schemaSig: string;
+};
+const hotCache = new Map<string, HotCacheEntry>();
+
+function computeSchemaSig(
+  schemas: Record<string, any>,
+  dbPath: string,
+): string {
+  const parts: string[] = [dbPath];
+  for (const name of Object.keys(schemas).sort()) {
+    const tableName = camelToSnake(name);
+    const ddl = zodToCreateTableSQL(tableName, schemas[name]);
+    parts.push(`${name}:${ddl}`);
+  }
+  return parts.join("\n");
+}
+
 export type CreateSmithersApi<Schema = any> = {
   Workflow: (props: WorkflowProps) => React.ReactElement;
   Task: <Row>(props: TaskProps<Row>) => React.ReactElement;
@@ -51,6 +71,23 @@ export function createSmithers<
   schemas: Schemas,
   opts?: { dbPath?: string; journalMode?: string },
 ): CreateSmithersApi<Schemas> {
+  const dbPath = opts?.dbPath ?? "./smithers.db";
+  const absDbPath = resolve(process.cwd(), dbPath);
+
+  if (process.env.SMITHERS_HOT === "1") {
+    const sig = computeSchemaSig(schemas as Record<string, any>, absDbPath);
+    const cached = hotCache.get(absDbPath);
+    if (cached) {
+      if (cached.schemaSig !== sig) {
+        throw new Error(
+          "[smithers hot] Schema change detected; restart required to apply schema changes.",
+        );
+      }
+      return cached.api as any;
+    }
+    // Will cache after creating the API below
+  }
+
   // 1. Generate Drizzle tables from Zod schemas
   const tables: Record<string, any> = {};
   const inputTable = sqliteTable("input", {
@@ -64,11 +101,23 @@ export function createSmithers<
   }
 
   // 2. Create SQLite db
-  const dbPath = opts?.dbPath ?? "./smithers.db";
   const sqlite = new Database(dbPath);
   sqlite.exec(`PRAGMA journal_mode = ${opts?.journalMode ?? "WAL"}`);
+  sqlite.exec("PRAGMA busy_timeout = 5000");
   sqlite.exec("PRAGMA foreign_keys = ON");
 
+  // Register a process-exit hook to explicitly close the Database.
+  // bun:sqlite's GC finalizer calls sqlite3_close() which fatally aborts if
+  // Drizzle's cached prepared statements haven't been finalized first.
+  // Calling close() ourselves lets sqlite3 finalize everything gracefully.
+  let dbClosed = false;
+  const closeDb = () => {
+    if (dbClosed) return;
+    dbClosed = true;
+    try { sqlite.close(); } catch {}
+  };
+  process.on("exit", closeDb);
+
   // 3. Auto-create tables using CREATE TABLE IF NOT EXISTS
   sqlite.exec(
     `CREATE TABLE IF NOT EXISTS "input" (run_id TEXT PRIMARY KEY, payload TEXT)`,
@@ -146,13 +195,20 @@ export function createSmithers<
     } as SmithersWorkflow<any>;
   }
 
-  return {
+  const api = {
     Workflow,
     Task,
     useCtx,
     smithers: boundSmithers,
     db,
-    tables: tables as { [K in keyof Schemas]: any },
-    outputs: schemas as { [K in keyof Schemas]: Schemas[K] },
+    tables: tables as any,
+    outputs: schemas as any,
   };
+
+  if (process.env.SMITHERS_HOT === "1") {
+    const sig = computeSchemaSig(schemas as Record<string, any>, absDbPath);
+    hotCache.set(absDbPath, { api: api as any, schemaSig: sig });
+  }
+
+  return api;
 }

package/src/db/adapter.ts

@@ -155,6 +155,13 @@ export class SmithersDb {
       );
   }
 
+  async listAllInProgressAttempts() {
+    return this.db
+      .select()
+      .from(smithersAttempts)
+      .where(eq(smithersAttempts.state, "in-progress"));
+  }
+
   async insertFrame(row: any) {
     await this.db
       .insert(smithersFrames)

package/src/engine/index.ts

@@ -39,6 +39,8 @@ import { eq, getTableName } from "drizzle-orm";
 import { getTableColumns } from "drizzle-orm/utils";
 import { dirname, resolve } from "node:path";
 import { existsSync } from "node:fs";
+import { HotWorkflowController } from "../hot/HotWorkflowController";
+import type { HotReloadOptions } from "../RunOptions";
 import { spawn as nodeSpawn } from "node:child_process";
 import { platform } from "node:os";
 
@@ -123,15 +125,23 @@ async function ensureWorktree(
   worktreePath: string,
   branch?: string,
 ): Promise<void> {
-  if (createdWorktrees.has(worktreePath)) {
-    if (existsSync(worktreePath)) return;
-    // Process-global cache can become stale if the path is later deleted.
-    createdWorktrees.delete(worktreePath);
-  }
   if (existsSync(worktreePath)) {
+    // Worktree exists — rebase onto latest main so work starts from tip.
+    const vcs = findVcsRoot(rootDir);
+    if (vcs?.type === "jj") {
+      const { runJj } = await import("../vcs/jj");
+      await runJj(["git", "fetch"], { cwd: worktreePath });
+      await runJj(["rebase", "-d", "main"], { cwd: worktreePath });
+    } else if (vcs?.type === "git") {
+      await runGitCommand(worktreePath, ["fetch", "origin"]);
+      await runGitCommand(worktreePath, ["rebase", "origin/main"]);
+    }
     createdWorktrees.add(worktreePath);
     return;
   }
+  if (createdWorktrees.has(worktreePath)) {
+    createdWorktrees.delete(worktreePath);
+  }
 
   // Walk up from rootDir to find the actual VCS root
   const vcs = findVcsRoot(rootDir);
@@ -296,6 +306,12 @@ function resolveLogDir(
   return resolve(rootDir, ".smithers", "executions", runId, "logs");
 }
 
+function normalizeHotOptions(hot: boolean | HotReloadOptions | undefined): HotReloadOptions & { enabled: boolean } {
+  if (!hot) return { enabled: false };
+  if (hot === true) return { enabled: true };
+  return { enabled: true, ...hot };
+}
+
 function assertInputObject(input: unknown) {
   if (!input || typeof input !== "object" || Array.isArray(input)) {
     throw new SmithersError("INVALID_INPUT", "Run input must be a JSON object");
@@ -722,6 +738,7 @@ async function executeTask(
   workflowName: string,
   cacheEnabled: boolean,
   signal?: AbortSignal,
+  disabledAgents?: Set<any>,
 ) {
   const attempts = await adapter.listAttempts(
     runId,
@@ -777,6 +794,7 @@ async function executeTask(
   let cacheKey: string | null = null;
   let cacheJjBase: string | null = null;
   let responseText: string | null = null;
+  let effectiveAgent: any = null;
   // Resolve effective root once so both caching and execution share it.
   const taskRoot = desc.worktreePath ?? toolConfig.rootDir;
 
@@ -823,8 +841,11 @@ async function executeTask(
     }
 
     if (!payload) {
-      const agents = Array.isArray(desc.agent) ? desc.agent : (desc.agent ? [desc.agent] : []);
-      const effectiveAgent = agents[Math.min(attemptNo - 1, agents.length - 1)];
+      const allAgents = Array.isArray(desc.agent) ? desc.agent : (desc.agent ? [desc.agent] : []);
+      const agents = disabledAgents ? allAgents.filter((a: any) => !disabledAgents.has(a)) : allAgents;
+      effectiveAgent = agents.length > 0
+        ? agents[Math.min(attemptNo - 1, agents.length - 1)]
+        : allAgents[Math.min(attemptNo - 1, allAgents.length - 1)]; // fallback to disabled agent if all disabled
       if (effectiveAgent) {
         // Use fallback agent on retry attempts when available
         const result = await runWithToolContext(
@@ -1365,6 +1386,17 @@ async function executeTask(
       label: desc.label ?? null,
     });
 
+    // Circuit-breaker: disable agents that fail with auth errors
+    if (disabledAgents && effectiveAgent) {
+      const errStr = String((err as any)?.message ?? err ?? "") + (responseText ?? "");
+      const isAuthError = /invalid_authentication|401|api.key.*invalid|expired.*credentials|authentication.*failed/i.test(errStr);
+      if (isAuthError) {
+        disabledAgents.add(effectiveAgent);
+        const agentName = effectiveAgent?.model ?? effectiveAgent?.id ?? "unknown";
+        console.log(`[smithers] Circuit-breaker: disabled agent ${agentName} due to auth failure`);
+      }
+    }
+
     await eventBus.emitEventWithPersist({
       type: "NodeFailed",
       runId,
@@ -1464,6 +1496,11 @@ export async function runWorkflow<Schema>(
     eventBus.on("event", (e: SmithersEvent) => opts.onProgress?.(e));
   }
 
+  const hotOpts = normalizeHotOptions(opts.hot);
+  let hotController: HotWorkflowController | null = null;
+  let hotPendingFiles: string[] | null = null;
+  let workflowRef = workflow;
+
   const wakeLock = acquireCaffeinate();
   try {
     const existingRun = await adapter.getRun(runId);
@@ -1540,6 +1577,25 @@ export async function runWorkflow<Schema>(
 
     await cancelStaleAttempts(adapter, runId);
 
+    // Cancel orphaned in-progress attempts from previous runs (killed processes)
+    {
+      const allInProgress = await adapter.listAllInProgressAttempts();
+      const now = nowMs();
+      for (const attempt of allInProgress) {
+        if (attempt.runId === runId) continue;
+        await adapter.updateAttempt(
+          attempt.runId,
+          attempt.nodeId,
+          attempt.iteration,
+          attempt.attempt,
+          {
+            state: "cancelled",
+            finishedAtMs: now,
+          },
+        );
+      }
+    }
+
     if (opts.resume) {
       // On resume, cancel ALL in-progress attempts since the previous process is dead
       const staleInProgress = await adapter.listInProgressAttempts(runId);
@@ -1568,9 +1624,13 @@ export async function runWorkflow<Schema>(
       }
     }
 
+    const disabledAgents = new Set<any>();
     const renderer = new SmithersRenderer();
     let frameNo = (await adapter.getLastFrame(runId))?.frameNo ?? 0;
     let defaultIteration = 0;
+    // Track in-flight task promises across loop iterations so we
+    // wait for them before declaring the run finished.
+    const inflight = new Set<Promise<void>>();
     if (opts.resume) {
       const nodes = await adapter.listNodes(runId);
       const maxIteration = nodes.reduce(
@@ -1583,6 +1643,15 @@ export async function runWorkflow<Schema>(
       await adapter.listRalph(runId),
     );
 
+    if (hotOpts.enabled && (resolvedWorkflowPath ?? opts.workflowPath)) {
+      process.env.SMITHERS_HOT = "1";
+      hotController = new HotWorkflowController(
+        resolvedWorkflowPath ?? opts.workflowPath!,
+        hotOpts,
+      );
+      await hotController.init();
+    }
+
     while (true) {
       if (opts.signal?.aborted) {
         await adapter.updateRun(runId, {
@@ -1597,6 +1666,64 @@ export async function runWorkflow<Schema>(
         return { runId, status: "cancelled" };
       }
 
+      // Process pending hot reload
+      if (hotController && hotPendingFiles) {
+        const result = await hotController.reload(hotPendingFiles);
+        hotPendingFiles = null;
+
+        switch (result.type) {
+          case "reloaded":
+            workflowRef = { ...workflowRef, build: result.newBuild };
+            await eventBus.emitEventWithPersist({
+              type: "WorkflowReloaded",
+              runId,
+              generation: result.generation,
+              changedFiles: result.changedFiles,
+              timestampMs: nowMs(),
+            });
+            opts.onProgress?.({
+              type: "WorkflowReloaded",
+              runId,
+              generation: result.generation,
+              changedFiles: result.changedFiles,
+              timestampMs: nowMs(),
+            });
+            break;
+          case "failed":
+            await eventBus.emitEventWithPersist({
+              type: "WorkflowReloadFailed",
+              runId,
+              error: result.error instanceof Error ? result.error.message : String(result.error),
+              changedFiles: result.changedFiles,
+              timestampMs: nowMs(),
+            });
+            opts.onProgress?.({
+              type: "WorkflowReloadFailed",
+              runId,
+              error: result.error instanceof Error ? result.error.message : String(result.error),
+              changedFiles: result.changedFiles,
+              timestampMs: nowMs(),
+            });
+            break;
+          case "unsafe":
+            await eventBus.emitEventWithPersist({
+              type: "WorkflowReloadUnsafe",
+              runId,
+              reason: result.reason,
+              changedFiles: result.changedFiles,
+              timestampMs: nowMs(),
+            });
+            opts.onProgress?.({
+              type: "WorkflowReloadUnsafe",
+              runId,
+              reason: result.reason,
+              changedFiles: result.changedFiles,
+              timestampMs: nowMs(),
+            });
+            break;
+        }
+      }
+
       const inputRow = await loadInput(db, inputTable, runId);
       const outputs = await loadOutputs(db, schema, runId);
       const ralphIterations = ralphIterationsFromState(ralphState);
@@ -1611,7 +1738,7 @@ export async function runWorkflow<Schema>(
       });
 
       const { xml, tasks, mountedTaskIds } = await renderer.render(
-        workflow.build(ctx),
+        workflowRef.build(ctx),
         {
           ralphIterations,
           defaultIteration,
@@ -1662,6 +1789,7 @@ export async function runWorkflow<Schema>(
       const inProgress = await adapter.listInProgressAttempts(runId);
       const mountedSet = new Set(mountedTaskIds);
       if (
+        !hotOpts.enabled &&
         inProgress.some(
           (a: any) => !mountedSet.has(`${a.nodeId}::${a.iteration ?? 0}`),
         )
@@ -1711,6 +1839,25 @@ export async function runWorkflow<Schema>(
       );
 
       if (runnable.length === 0) {
+        // If tasks are still in-flight, wait for one to finish then
+        // loop back to re-evaluate instead of declaring the run done.
+        if (inflight.size > 0) {
+          {
+            const waitables: Promise<any>[] = [...inflight];
+            if (hotController) {
+              waitables.push(
+                hotController.wait().then((files) => {
+                  hotPendingFiles = files;
+                }),
+              );
+            }
+            if (waitables.length > 0) {
+              await Promise.race(waitables);
+            }
+          }
+          continue;
+        }
+
         if (schedule.waitingApprovalExists) {
           await adapter.updateRun(runId, { status: "waiting-approval" });
           await eventBus.emitEventWithPersist({
@@ -1834,21 +1981,37 @@ export async function runWorkflow<Schema>(
         toolTimeoutMs,
       };
 
-      await Promise.all(
-        runnable.map((task) =>
-          executeTask(
-            adapter,
-            db,
-            runId,
-            task,
-            eventBus,
-            toolConfig,
-            workflowName,
-            cacheEnabled,
-            opts.signal,
-          ),
-        ),
-      );
+      // Launch new tasks and track them in the persistent inflight set.
+      for (const task of runnable) {
+        const p = executeTask(
+          adapter,
+          db,
+          runId,
+          task,
+          eventBus,
+          toolConfig,
+          workflowName,
+          cacheEnabled,
+          opts.signal,
+          disabledAgents,
+        ).finally(() => inflight.delete(p));
+        inflight.add(p);
+      }
+      // Wait for at least one task to finish, then loop back to
+      // re-render and schedule newly runnable tasks.
+      {
+        const waitables: Promise<any>[] = [...inflight];
+        if (hotController) {
+          waitables.push(
+            hotController.wait().then((files) => {
+              hotPendingFiles = files;
+            }),
+          );
+        }
+        if (waitables.length > 0) {
+          await Promise.race(waitables);
+        }
+      }
     }
   } catch (err) {
     if (process.env.SMITHERS_DEBUG) {
@@ -1868,6 +2031,7 @@ export async function runWorkflow<Schema>(
     });
     return { runId, status: "failed", error: errorInfo };
   } finally {
+    await hotController?.close();
     wakeLock.release();
   }
 }

package/src/hot/HotWorkflowController.ts

@@ -0,0 +1,142 @@
+import { resolve, dirname } from "node:path";
+import { mkdir, rm } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { WatchTree } from "./watch";
+import { buildOverlay, cleanupGenerations, resolveOverlayEntry } from "./overlay";
+import type { SmithersWorkflow } from "../SmithersWorkflow";
+import type { HotReloadOptions } from "../RunOptions";
+
+export type HotReloadEvent =
+  | { type: "reloaded"; generation: number; changedFiles: string[]; newBuild: SmithersWorkflow<any>["build"] }
+  | { type: "failed"; generation: number; changedFiles: string[]; error: unknown }
+  | { type: "unsafe"; generation: number; changedFiles: string[]; reason: string };
+
+const DEFAULT_MAX_GENERATIONS = 3;
+const DEFAULT_DEBOUNCE_MS = 100;
+
+export class HotWorkflowController {
+  private entryPath: string;
+  private hotRoot: string;
+  private outDir: string;
+  private maxGenerations: number;
+  private watcher: WatchTree;
+  private generation = 0;
+  private closed = false;
+
+  constructor(entryPath: string, opts?: HotReloadOptions) {
+    this.entryPath = resolve(entryPath);
+    this.hotRoot = opts?.rootDir
+      ? resolve(opts.rootDir)
+      : dirname(this.entryPath);
+    this.outDir = opts?.outDir
+      ? resolve(opts.outDir)
+      : resolve(this.hotRoot, ".smithers", "hmr");
+    this.maxGenerations = opts?.maxGenerations ?? DEFAULT_MAX_GENERATIONS;
+    this.watcher = new WatchTree(this.hotRoot, {
+      debounceMs: opts?.debounceMs ?? DEFAULT_DEBOUNCE_MS,
+    });
+  }
+
+  /** Initialize: start file watchers. Call once before using wait/reload. */
+  async init(): Promise<void> {
+    await mkdir(this.outDir, { recursive: true });
+    await this.watcher.start();
+  }
+
+  /** Current generation number. */
+  get gen(): number {
+    return this.generation;
+  }
+
+  /**
+   * Wait for the next file change event.
+   * Returns the list of changed file paths.
+   * Use this in Promise.race with inflight tasks to wake the engine loop.
+   */
+  async wait(): Promise<string[]> {
+    return this.watcher.wait();
+  }
+
+  /**
+   * Perform a hot reload:
+   * 1. Build a new generation overlay
+   * 2. Import the workflow module from the overlay
+   * 3. Validate the module
+   * 4. Return the result (reloaded, failed, or unsafe)
+   *
+   * The caller is responsible for swapping workflow.build on success.
+   */
+  async reload(changedFiles: string[]): Promise<HotReloadEvent> {
+    this.generation += 1;
+    const gen = this.generation;
+
+    try {
+      // 1. Build overlay
+      const genDir = await buildOverlay(this.hotRoot, this.outDir, gen);
+
+      // 2. Resolve entry path in overlay
+      const overlayEntry = resolveOverlayEntry(this.entryPath, this.hotRoot, genDir);
+      const overlayUrl = pathToFileURL(overlayEntry).href;
+
+      // 3. Import fresh module
+      let mod: any;
+      try {
+        mod = await import(overlayUrl);
+      } catch (err: any) {
+        return { type: "failed", generation: gen, changedFiles, error: err };
+      }
+
+      // 4. Validate module shape
+      const workflow = mod.default as SmithersWorkflow<any> | undefined;
+      if (!workflow) {
+        return {
+          type: "failed",
+          generation: gen,
+          changedFiles,
+          error: new Error("Reloaded module does not export default"),
+        };
+      }
+      if (typeof workflow.build !== "function") {
+        return {
+          type: "failed",
+          generation: gen,
+          changedFiles,
+          error: new Error("Reloaded module default does not have a build function"),
+        };
+      }
+
+      // 5. Cleanup old generations
+      await cleanupGenerations(this.outDir, this.maxGenerations);
+
+      // 6. Return success with the new build function
+      return {
+        type: "reloaded",
+        generation: gen,
+        changedFiles,
+        newBuild: workflow.build,
+      };
+    } catch (err: any) {
+      if (err?.message?.includes("Schema change detected")) {
+        return {
+          type: "unsafe",
+          generation: gen,
+          changedFiles,
+          reason: err.message,
+        };
+      }
+      return { type: "failed", generation: gen, changedFiles, error: err };
+    }
+  }
+
+  /** Stop watchers and clean up overlay directory. */
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    this.watcher.close();
+    try {
+      await rm(this.outDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}

package/src/hot/index.ts

@@ -0,0 +1,6 @@
+export { WatchTree } from "./watch";
+export type { WatchTreeOptions } from "./watch";
+export { buildOverlay, cleanupGenerations, resolveOverlayEntry } from "./overlay";
+export type { OverlayOptions } from "./overlay";
+export { HotWorkflowController } from "./HotWorkflowController";
+export type { HotReloadEvent } from "./HotWorkflowController";

package/src/hot/overlay.ts

@@ -0,0 +1,113 @@
+import { readdir, mkdir, link, copyFile, rm, stat } from "node:fs/promises";
+import { resolve, relative, join, dirname } from "node:path";
+import { existsSync } from "node:fs";
+
+const DEFAULT_EXCLUDE = [
+  "node_modules",
+  ".git",
+  ".jj",
+  ".smithers",
+  ".DS_Store",
+];
+
+export type OverlayOptions = {
+  /** Directory basenames to exclude from overlay */
+  exclude?: string[];
+};
+
+/**
+ * Build a generation overlay by hardlinking (or copying) the hot root
+ * tree into a new generation directory.
+ *
+ * Returns the absolute path to the overlay directory.
+ */
+export async function buildOverlay(
+  hotRoot: string,
+  outDir: string,
+  generation: number,
+  opts?: OverlayOptions,
+): Promise<string> {
+  const exclude = new Set(opts?.exclude ?? DEFAULT_EXCLUDE);
+  const genDir = join(outDir, `gen-${generation}`);
+  await mkdir(genDir, { recursive: true });
+  await mirrorTree(hotRoot, genDir, exclude);
+  return genDir;
+}
+
+/**
+ * Recursively mirror `src` into `dest`, using hardlinks where possible
+ * and falling back to copy. Skips excluded directory basenames.
+ */
+async function mirrorTree(
+  src: string,
+  dest: string,
+  exclude: Set<string>,
+): Promise<void> {
+  const entries = await readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (exclude.has(entry.name)) continue;
+    // Skip hidden files/dirs (dotfiles)
+    if (entry.name.startsWith(".")) continue;
+
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await mkdir(destPath, { recursive: true });
+      await mirrorTree(srcPath, destPath, exclude);
+    } else if (entry.isFile()) {
+      try {
+        await link(srcPath, destPath);
+      } catch {
+        // Hardlink failed (cross-device, permissions, etc.) — fall back to copy
+        await mkdir(dirname(destPath), { recursive: true });
+        await copyFile(srcPath, destPath);
+      }
+    }
+    // Skip symlinks, sockets, etc.
+  }
+}
+
+/**
+ * Remove old generation directories, keeping only the last `keepLast`.
+ */
+export async function cleanupGenerations(
+  outDir: string,
+  keepLast: number,
+): Promise<void> {
+  if (!existsSync(outDir)) return;
+
+  const entries = await readdir(outDir, { withFileTypes: true });
+  const genDirs = entries
+    .filter((e) => e.isDirectory() && e.name.startsWith("gen-"))
+    .map((e) => {
+      const num = parseInt(e.name.slice(4), 10);
+      return { name: e.name, num: isNaN(num) ? -1 : num };
+    })
+    .filter((e) => e.num >= 0)
+    .sort((a, b) => a.num - b.num);
+
+  // Keep only the last `keepLast` generations
+  const toRemove = genDirs.slice(0, Math.max(0, genDirs.length - keepLast));
+  for (const dir of toRemove) {
+    try {
+      await rm(join(outDir, dir.name), { recursive: true, force: true });
+    } catch {
+      // Best effort
+    }
+  }
+}
+
+/**
+ * Resolve the overlay entry path given the original entry path,
+ * the hot root, and the overlay generation directory.
+ */
+export function resolveOverlayEntry(
+  entryPath: string,
+  hotRoot: string,
+  genDir: string,
+): string {
+  const rel = relative(hotRoot, entryPath);
+  return resolve(genDir, rel);
+}

package/src/hot/watch.ts

@@ -0,0 +1,126 @@
+import { watch, type FSWatcher } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { resolve, relative } from "node:path";
+
+const DEFAULT_IGNORE = [
+  "node_modules",
+  ".git",
+  ".jj",
+  ".smithers",
+];
+
+export type WatchTreeOptions = {
+  /** Patterns to ignore (directory basenames) */
+  ignore?: string[];
+  /** Debounce interval in ms (default: 100) */
+  debounceMs?: number;
+};
+
+export class WatchTree {
+  private watchers: FSWatcher[] = [];
+  private rootDir: string;
+  private ignore: string[];
+  private debounceMs: number;
+  private changedFiles = new Set<string>();
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private waitResolve: ((files: string[]) => void) | null = null;
+  private closed = false;
+
+  constructor(rootDir: string, opts?: WatchTreeOptions) {
+    this.rootDir = resolve(rootDir);
+    this.ignore = opts?.ignore ?? DEFAULT_IGNORE;
+    this.debounceMs = opts?.debounceMs ?? 100;
+  }
+
+  /** Start watching. Call once. */
+  async start(): Promise<void> {
+    await this.watchDir(this.rootDir);
+  }
+
+  /**
+   * Returns a promise that resolves with changed file paths
+   * the next time file changes are detected (after debounce).
+   * Can be called repeatedly.
+   */
+  wait(): Promise<string[]> {
+    // If there are already buffered changes, resolve immediately
+    if (this.changedFiles.size > 0) {
+      const files = [...this.changedFiles];
+      this.changedFiles.clear();
+      return Promise.resolve(files);
+    }
+    return new Promise<string[]>((resolve) => {
+      this.waitResolve = resolve;
+    });
+  }
+
+  /** Stop all watchers and clean up. */
+  close(): void {
+    this.closed = true;
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    for (const w of this.watchers) {
+      try { w.close(); } catch {}
+    }
+    this.watchers = [];
+    // Resolve any pending wait with empty array
+    if (this.waitResolve) {
+      this.waitResolve([]);
+      this.waitResolve = null;
+    }
+  }
+
+  private shouldIgnore(name: string): boolean {
+    return this.ignore.includes(name) || name.startsWith(".");
+  }
+
+  private async watchDir(dir: string): Promise<void> {
+    if (this.closed) return;
+
+    const baseName = dir.split("/").pop() ?? "";
+    if (baseName && this.shouldIgnore(baseName) && dir !== this.rootDir) return;
+
+    try {
+      const watcher = watch(dir, (eventType, filename) => {
+        if (!filename || this.closed) return;
+        // Ignore hidden files and ignored dirs
+        const parts = filename.split("/");
+        if (parts.some((p) => this.shouldIgnore(p))) return;
+
+        const fullPath = resolve(dir, filename);
+        this.onFileChange(fullPath);
+      });
+      this.watchers.push(watcher);
+
+      // Recursively watch subdirectories
+      const entries = await readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && !this.shouldIgnore(entry.name)) {
+          await this.watchDir(resolve(dir, entry.name));
+        }
+      }
+    } catch {
+      // Directory may have been deleted; ignore
+    }
+  }
+
+  private onFileChange(filePath: string): void {
+    this.changedFiles.add(filePath);
+
+    // Debounce: reset timer on each change
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => {
+      this.flush();
+    }, this.debounceMs);
+  }
+
+  private flush(): void {
+    if (this.changedFiles.size === 0) return;
+    const files = [...this.changedFiles];
+    this.changedFiles.clear();
+
+    if (this.waitResolve) {
+      this.waitResolve(files);
+      this.waitResolve = null;
+    }
+  }
+}