@smithers-orchestrator/engine 0.20.4 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/engine",
-  "version": "0.20.4",
+  "version": "0.21.0",
   "description": "Concrete Smithers workflow execution engine",
   "type": "module",
   "sideEffects": false,
@@ -33,19 +33,19 @@
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/components": "0.20.4",
-    "@smithers-orchestrator/agents": "0.20.4",
-    "@smithers-orchestrator/driver": "0.20.4",
-    "@smithers-orchestrator/errors": "0.20.4",
-    "@smithers-orchestrator/graph": "0.20.4",
-    "@smithers-orchestrator/observability": "0.20.4",
-    "@smithers-orchestrator/sandbox": "0.20.4",
-    "@smithers-orchestrator/react-reconciler": "0.20.4",
-    "@smithers-orchestrator/scheduler": "0.20.4",
-    "@smithers-orchestrator/db": "0.20.4",
-    "@smithers-orchestrator/scorers": "0.20.4",
-    "@smithers-orchestrator/time-travel": "0.20.4",
-    "@smithers-orchestrator/vcs": "0.20.4"
+    "@smithers-orchestrator/agents": "0.21.0",
+    "@smithers-orchestrator/components": "0.21.0",
+    "@smithers-orchestrator/db": "0.21.0",
+    "@smithers-orchestrator/driver": "0.21.0",
+    "@smithers-orchestrator/errors": "0.21.0",
+    "@smithers-orchestrator/graph": "0.21.0",
+    "@smithers-orchestrator/observability": "0.21.0",
+    "@smithers-orchestrator/react-reconciler": "0.21.0",
+    "@smithers-orchestrator/sandbox": "0.21.0",
+    "@smithers-orchestrator/scheduler": "0.21.0",
+    "@smithers-orchestrator/scorers": "0.21.0",
+    "@smithers-orchestrator/time-travel": "0.21.0",
+    "@smithers-orchestrator/vcs": "0.21.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/cache-policy.js

@@ -0,0 +1,54 @@
+import { nowMs } from "@smithers-orchestrator/scheduler/nowMs";
+
+/**
+ * @typedef {import("@smithers-orchestrator/graph/TaskDescriptor").TaskDescriptor} TaskDescriptor
+ */
+
+/**
+ * @param {TaskDescriptor["cachePolicy"]} policy
+ * @returns {"run" | "workflow" | "global"}
+ */
+export function normalizeCacheScope(policy) {
+    return policy?.scope === "run" || policy?.scope === "global"
+        ? policy.scope
+        : "workflow";
+}
+
+/**
+ * @param {"run" | "workflow" | "global"} scope
+ * @param {string} runId
+ * @param {string} workflowName
+ * @param {TaskDescriptor} desc
+ * @returns {Record<string, unknown>}
+ */
+export function buildCacheScopeIdentity(scope, runId, workflowName, desc) {
+    const taskKey = desc.cachePolicy?.key ?? desc.nodeId;
+    const identity = {
+        taskKey,
+        outputTableName: desc.outputTableName,
+    };
+    if (scope === "global") {
+        return identity;
+    }
+    if (scope === "run") {
+        return { runId, workflowName, ...identity };
+    }
+    return { workflowName, ...identity };
+}
+
+/**
+ * @param {unknown} row
+ * @param {TaskDescriptor["cachePolicy"]} policy
+ * @returns {boolean}
+ */
+export function isFreshCacheRow(row, policy) {
+    const ttlMs = policy?.ttlMs;
+    if (ttlMs === undefined || ttlMs === null) {
+        return true;
+    }
+    if (typeof ttlMs !== "number" || !Number.isFinite(ttlMs) || ttlMs < 0) {
+        return false;
+    }
+    const createdAtMs = /** @type {{ createdAtMs?: unknown }} */ (row)?.createdAtMs;
+    return typeof createdAtMs === "number" && nowMs() - createdAtMs <= ttlMs;
+}

package/src/engine.js

@@ -30,14 +30,13 @@ import { Cause, Chunk, Duration, Effect, Exit, Fiber, Metric, Queue, Schedule }
 import { attemptDuration, cacheHits, cacheMisses, nodeDuration, promptSizeBytes, responseSizeBytes, runDuration, runsResumedTotal, schedulerConcurrencyUtilization, schedulerQueueDepth, schedulerWaitDuration, trackEvent, } from "@smithers-orchestrator/observability/metrics";
 import { runScorersAsync } from "@smithers-orchestrator/scorers/run-scorers";
 import { dirname, resolve } from "node:path";
-import { existsSync, statSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
 import { logDebug, logError, logInfo, logWarning } from "@smithers-orchestrator/observability/logging";
 import { isPidAlive, parseRuntimeOwnerPid } from "./runtime-owner.js";
 import { HotWorkflowController } from "./hot/index.js";
 import { spawn as nodeSpawn } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { platform } from "node:os";
 import { annotateSmithersTrace, smithersSpanNames, withSmithersSpan, } from "@smithers-orchestrator/observability";
 import { withTaskRuntime } from "@smithers-orchestrator/driver/task-runtime";
@@ -45,9 +44,13 @@ import { hashCapabilityRegistry } from "@smithers-orchestrator/agents/capability
 import { cancelPendingTimersBridge, executeTaskBridgeEffect, isBridgeManagedTimerTask as isTimerTask, resolveDeferredTaskStateBridge, } from "./effect/workflow-bridge.js";
 import { AlertRuntime } from "./alert-runtime.js";
 import { executeChildWorkflow } from "./child-workflow.js";
+import { executeSandbox } from "@smithers-orchestrator/sandbox/execute";
+import { applyDiffBundle } from "./effect/diff-bundle.js";
+import { buildCacheScopeIdentity, isFreshCacheRow, normalizeCacheScope } from "./cache-policy.js";
 import { runWorkflowWithMakeBridge } from "./effect/workflow-make-bridge.js";
 import { createWorkflowVersioningRuntime, getWorkflowPatchDecisions, withWorkflowVersioningRuntime, } from "./effect/versioning.js";
 import { runWithCorrelationContext, updateCurrentCorrelationContext, withCorrelationContext, } from "@smithers-orchestrator/observability/correlation";
+import { extractWorkflowImportSpecifiers, getWorkflowImportScanLoader, readWorkflowEntryHash, readWorkflowGraphHash, resolveWorkflowImport, sha256Hex, } from "./workflow-hash.js";
 /** @typedef {import("@smithers-orchestrator/graph/GraphSnapshot").GraphSnapshot} GraphSnapshot */
 /** @typedef {import("./HijackState.ts").HijackState} HijackState */
 /** @typedef {import("@smithers-orchestrator/driver/RunOptions").RunOptions} RunOptions */
@@ -61,13 +64,6 @@ import { runWithCorrelationContext, updateCurrentCorrelationContext, withCorrela
 /** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase<Record<string, unknown>>} BunSQLiteDatabase */
 /** @typedef {import("drizzle-orm/sqlite-core").SQLiteTable} SQLiteTable */
 
-/**
- * @param {string} input
- * @returns {string}
- */
-function sha256Hex(input) {
-    return createHash("sha256").update(input).digest("hex");
-}
 /**
  * Track which worktree paths have already been created this run so we don't
  * re-create them for every task sharing the same worktree.
@@ -1345,143 +1341,6 @@ function resolveLogDir(rootDir, runId, logDir) {
     }
     return resolve(rootDir, ".smithers", "executions", runId, "logs");
 }
-const STATIC_IMPORT_RE = /\b(?:import|export)\s+(?:[^"'`]*?\s+from\s*)?["']([^"']+)["']/g;
-const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
-const WORKFLOW_IMPORT_EXTENSIONS = [
-    "",
-    ".ts",
-    ".tsx",
-    ".mts",
-    ".cts",
-    ".js",
-    ".jsx",
-    ".mjs",
-    ".cjs",
-];
-/**
- * @param {string | null | undefined} sourcePath
- */
-function getWorkflowImportScanLoader(sourcePath) {
-    const lower = sourcePath?.toLowerCase() ?? "";
-    if (lower.endsWith(".tsx"))
-        return "tsx";
-    if (lower.endsWith(".jsx"))
-        return "jsx";
-    if (lower.endsWith(".ts") ||
-        lower.endsWith(".mts") ||
-        lower.endsWith(".cts")) {
-        return "ts";
-    }
-    return "js";
-}
-/**
- * @param {string | null} workflowPath
- * @returns {Promise<string | null>}
- */
-async function readWorkflowEntryHash(workflowPath) {
-    if (!workflowPath)
-        return null;
-    try {
-        const raw = await readFile(workflowPath, "utf8");
-        return sha256Hex(raw);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * @param {string} source
- * @param {string | null} [sourcePath]
- * @returns {string[]}
- */
-function extractWorkflowImportSpecifiers(source, sourcePath) {
-    if (typeof Bun !== "undefined" && typeof Bun.Transpiler === "function") {
-        try {
-            const scanned = new Bun.Transpiler({
-                loader: getWorkflowImportScanLoader(sourcePath),
-            }).scanImports(source);
-            const specifiers = new Set();
-            for (const entry of scanned) {
-                const specifier = entry?.path?.trim();
-                if (specifier?.startsWith(".")) {
-                    specifiers.add(specifier);
-                }
-            }
-            return [...specifiers];
-        }
-        catch {
-            // Fall back to regex scanning if Bun's parser cannot handle the source.
-        }
-    }
-    const specifiers = new Set();
-    for (const pattern of [STATIC_IMPORT_RE, DYNAMIC_IMPORT_RE]) {
-        pattern.lastIndex = 0;
-        let match;
-        while ((match = pattern.exec(source)) !== null) {
-            const specifier = match[1]?.trim();
-            if (!specifier?.startsWith("."))
-                continue;
-            specifiers.add(specifier);
-        }
-    }
-    return [...specifiers];
-}
-/**
- * @param {string} baseFile
- * @param {string} specifier
- * @returns {string | null}
- */
-function resolveWorkflowImport(baseFile, specifier) {
-    const basePath = resolve(dirname(baseFile), specifier);
-    const candidates = [
-        ...WORKFLOW_IMPORT_EXTENSIONS.map((ext) => `${basePath}${ext}`),
-        ...WORKFLOW_IMPORT_EXTENSIONS
-            .filter((ext) => ext.length > 0)
-            .map((ext) => resolve(basePath, `index${ext}`)),
-    ];
-    for (const candidate of candidates) {
-        if (existsSync(candidate) && statSync(candidate).isFile()) {
-            return resolve(candidate);
-        }
-    }
-    return null;
-}
-/**
- * @param {string} workflowPath
- * @returns {Promise<string[]>}
- */
-async function collectWorkflowModuleHashEntries(workflowPath, visited = new Set()) {
-    const resolvedPath = resolve(workflowPath);
-    if (visited.has(resolvedPath)) {
-        return [];
-    }
-    visited.add(resolvedPath);
-    const source = await readFile(resolvedPath, "utf8");
-    const entries = [`${resolvedPath}:${sha256Hex(source)}`];
-    for (const specifier of extractWorkflowImportSpecifiers(source, resolvedPath)) {
-        const importedPath = resolveWorkflowImport(resolvedPath, specifier);
-        if (!importedPath) {
-            throw new SmithersError("WORKFLOW_HASH_RESOLUTION_FAILED", `Unable to resolve workflow import "${specifier}" from ${resolvedPath}.`, { workflowPath: resolvedPath, specifier });
-        }
-        entries.push(...(await collectWorkflowModuleHashEntries(importedPath, visited)));
-    }
-    return entries;
-}
-/**
- * @param {string | null} workflowPath
- * @returns {Promise<string | null>}
- */
-async function readWorkflowGraphHash(workflowPath) {
-    if (!workflowPath)
-        return null;
-    try {
-        const entries = await collectWorkflowModuleHashEntries(workflowPath);
-        return sha256Hex(entries.sort().join("|"));
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * @param {string} cwd
  * @returns {Promise<string | null>}
@@ -1980,6 +1839,54 @@ function attachSubflowComputeFns(tasks, workflow, opts = {}) {
         task.meta = persistableMeta;
     }
 }
+/**
+ * @param {TaskDescriptor[]} tasks
+ * @param {SmithersWorkflow<any>} workflow
+ * @param {{ rootDir?: string; workflowPath?: string | null }} [opts]
+ */
+function attachSandboxComputeFns(tasks, workflow, opts = {}) {
+    for (const task of tasks) {
+        if (!task.meta?.__sandbox || task.computeFn)
+            continue;
+        const sandboxWorkflow = task.meta.__sandboxWorkflow;
+        if (!sandboxWorkflow)
+            continue;
+        const sandboxInput = task.meta.__sandboxInput;
+        const sandboxProvider = task.meta.__sandboxProvider;
+        const sandboxRuntime = task.meta.__sandboxRuntime;
+        const sandboxAllowNetwork = Boolean(task.meta.__sandboxAllowNetwork);
+        const sandboxReviewDiffs = task.meta.__sandboxReviewDiffs;
+        const sandboxAutoAcceptDiffs = task.meta.__sandboxAutoAcceptDiffs;
+        const sandboxAllowNested = Boolean(task.meta.__sandboxAllowNested);
+        const sandboxConfig = task.meta.__sandboxConfig && typeof task.meta.__sandboxConfig === "object"
+            ? task.meta.__sandboxConfig
+            : {};
+        task.computeFn = async () => executeSandbox({
+            parentWorkflow: workflow,
+            sandboxId: task.nodeId,
+            provider: sandboxProvider,
+            runtime: sandboxRuntime,
+            workflow: sandboxWorkflow,
+            executeChildWorkflow,
+            applyDiffBundle,
+            input: sandboxInput,
+            rootDir: task.worktreePath ?? opts.rootDir ?? process.cwd(),
+            allowNetwork: sandboxAllowNetwork,
+            maxOutputBytes: 200_000,
+            toolTimeoutMs: 60_000,
+            reviewDiffs: sandboxReviewDiffs,
+            autoAcceptDiffs: sandboxAutoAcceptDiffs,
+            allowNested: sandboxAllowNested,
+            config: sandboxConfig,
+        });
+        const {
+            __sandboxWorkflow: _workflow,
+            __sandboxProvider: _provider,
+            ...persistableMeta
+        } = task.meta;
+        task.meta = persistableMeta;
+    }
+}
 /**
  * @param {XmlNode} xml
  * @returns {string}
@@ -2660,6 +2567,9 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
     const taskRoot = desc.worktreePath ?? toolConfig.rootDir;
     const stepCacheEnabled = cacheEnabled || Boolean(desc.cachePolicy);
     const cacheAgent = Array.isArray(desc.agent) ? desc.agent[0] : desc.agent;
+    const cachePolicyTtlMs = typeof desc.cachePolicy?.ttlMs === "number" && Number.isFinite(desc.cachePolicy.ttlMs)
+        ? Math.max(0, desc.cachePolicy.ttlMs)
+        : null;
     let heartbeatWatchdogFiber = null;
     try {
         if (taskSignal.aborted) {
@@ -2732,6 +2642,7 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
             if (desc.cachePolicy) {
                 let cachePayload = null;
                 let cacheByOk = true;
+                const cacheScope = normalizeCacheScope(desc.cachePolicy);
                 try {
                     const ctx = await buildCacheContext(db, inputTable, runId, desc, descriptorMap, attemptNo);
                     if (desc.cachePolicy.by) {
@@ -2752,16 +2663,15 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
                     cacheKeyDisabled = true;
                 }
                 cacheBase = {
-                    workflowName,
-                    nodeId: desc.nodeId,
-                    iteration: desc.iteration,
-                    outputTableName: desc.outputTableName,
+                    cacheScope,
+                    ...buildCacheScopeIdentity(cacheScope, runId, workflowName, desc),
                     schemaSig,
                     outputSchemaSig,
                     agentSig,
                     toolsSig,
                     jjPointer: cacheJjBase,
                     cacheVersion: desc.cachePolicy.version ?? null,
+                    cacheKey: desc.cachePolicy.key ?? null,
                     cacheBy: cachePayload ?? null,
                 };
             }
@@ -2797,26 +2707,53 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
             }
             if (cacheKey) {
                 const cachedRow = await Effect.runPromise(adapter.getCache(cacheKey));
-                if (cachedRow) {
-                    const parsed = JSON.parse(cachedRow.payloadJson);
-                    const valid = validateOutput(desc.outputTable, parsed);
-                    if (valid.ok) {
-                        payload = valid.data;
-                        cached = true;
-                        void Effect.runPromise(Metric.increment(cacheHits));
-                        logInfo("cache hit for task output", {
+                if (cachedRow && isFreshCacheRow(cachedRow, desc.cachePolicy)) {
+                    const createdAtMs = Number(cachedRow.createdAtMs);
+                    const expired = cachePolicyTtlMs !== null &&
+                        Number.isFinite(createdAtMs) &&
+                        nowMs() - createdAtMs >= cachePolicyTtlMs;
+                    if (expired) {
+                        void Effect.runPromise(Metric.increment(cacheMisses));
+                        logInfo("cache entry expired for task output", {
                             runId,
                             nodeId: desc.nodeId,
                             iteration: desc.iteration,
                             attempt: attemptNo,
                             cacheKey,
+                            ttlMs: cachePolicyTtlMs,
                         }, "engine:task-cache");
                     }
                     else {
-                        void Effect.runPromise(Metric.increment(cacheMisses));
+                        const parsed = JSON.parse(cachedRow.payloadJson);
+                        const valid = validateOutput(desc.outputTable, parsed);
+                        if (valid.ok) {
+                            payload = valid.data;
+                            cached = true;
+                            void Effect.runPromise(Metric.increment(cacheHits));
+                            logInfo("cache hit for task output", {
+                                runId,
+                                nodeId: desc.nodeId,
+                                iteration: desc.iteration,
+                                attempt: attemptNo,
+                                cacheKey,
+                            }, "engine:task-cache");
+                        }
+                        else {
+                            void Effect.runPromise(Metric.increment(cacheMisses));
+                        }
                     }
                 }
                 else {
+                    if (cachedRow) {
+                        logInfo("cache entry expired for task output", {
+                            runId,
+                            nodeId: desc.nodeId,
+                            iteration: desc.iteration,
+                            attempt: attemptNo,
+                            cacheKey,
+                            ttlMs: desc.cachePolicy?.ttlMs,
+                        }, "engine:task-cache");
+                    }
                     void Effect.runPromise(Metric.increment(cacheMisses));
                 }
             }
@@ -4132,6 +4069,10 @@ async function renderFrameAsync(workflow, ctx, opts) {
         rootDir: opts?.baseRootDir,
         workflowPath: opts?.workflowPath,
     });
+    attachSandboxComputeFns(tasks, workflow, {
+        rootDir: opts?.baseRootDir,
+        workflowPath: opts?.workflowPath,
+    });
     return { runId: ctx.runId, frameNo: 0, xml: result.xml, tasks };
 }
 /**
@@ -5269,10 +5210,14 @@ async function runWorkflowBodyDriver(workflow, opts) {
                 const graph = await withWorkflowVersioningRuntime(workflowVersioning, () => renderer.render(element, renderOpts));
                 await workflowVersioning.flush();
                 resolveTaskOutputs(graph.tasks, workflowRef);
-                attachSubflowComputeFns(graph.tasks, workflowRef, {
-                    rootDir,
-                    workflowPath: resolvedWorkflowPath ?? opts.workflowPath,
-                });
+            attachSubflowComputeFns(graph.tasks, workflowRef, {
+                rootDir,
+                workflowPath: resolvedWorkflowPath ?? opts.workflowPath,
+            });
+            attachSandboxComputeFns(graph.tasks, workflowRef, {
+                rootDir,
+                workflowPath: resolvedWorkflowPath ?? opts.workflowPath,
+            });
                 lastGraph = graph;
                 descriptorMap = buildDescriptorMap(graph.tasks);
                 workflowName = getWorkflowNameFromXml(graph.xml);
@@ -6348,6 +6293,10 @@ async function runWorkflowBodyLegacy(workflow, opts) {
                 rootDir,
                 workflowPath: resolvedWorkflowPath ?? opts.workflowPath,
             });
+            attachSandboxComputeFns(tasks, workflow, {
+                rootDir,
+                workflowPath: resolvedWorkflowPath ?? opts.workflowPath,
+            });
             const workflowName = getWorkflowNameFromXml(xml);
             updateCurrentCorrelationContext({ workflowName });
             const cacheEnabled = workflow.opts.cache ??

package/src/hot/watch.js

@@ -1,6 +1,6 @@
 import { watch } from "node:fs";
-import { readdir } from "node:fs/promises";
-import { resolve } from "node:path";
+import { readdir, stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
 import { Effect } from "effect";
 import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
 import { logDebug, logInfo } from "@smithers-orchestrator/observability/logging";
@@ -12,13 +12,27 @@ const DEFAULT_IGNORE = [
     ".jj",
     ".smithers",
 ];
+const MIN_POLL_MS = 1000;
+const MAX_POLL_MS = 10_000;
+const MAX_POLL_FILES = 5000;
+class HotWatchScanLimitError extends Error {
+    constructor() {
+        super(`Hot watch polling skipped after ${MAX_POLL_FILES} files.`);
+        this.name = "HotWatchScanLimitError";
+    }
+}
 export class WatchTree {
     watchers = [];
     rootDir;
     ignore;
     debounceMs;
     changedFiles = new Set();
+    fileSignatures = new Map();
     debounceTimer = null;
+    pollTimer = null;
+    polling = false;
+    pollingDisabled = false;
+    currentPollIntervalMs = MIN_POLL_MS;
     waitResolve = null;
     closed = false;
     /**
@@ -53,6 +67,8 @@ export class WatchTree {
         this.closed = true;
         if (this.debounceTimer)
             clearTimeout(this.debounceTimer);
+        if (this.pollTimer)
+            clearTimeout(this.pollTimer);
         for (const w of this.watchers) {
             try {
                 w.close();
@@ -71,7 +87,31 @@ export class WatchTree {
     }
     startEffect() {
         return Effect.tryPromise({
-            try: () => this.watchDir(this.rootDir),
+            try: async () => {
+                try {
+                    this.fileSignatures = await this.scanFileSignatures(this.rootDir);
+                }
+                catch (error) {
+                    this.pollingDisabled = true;
+                    this.fileSignatures = new Map();
+                    if (error instanceof HotWatchScanLimitError) {
+                        logInfo("hot watch polling disabled by file count guard", {
+                            rootDir: this.rootDir,
+                            maxFiles: MAX_POLL_FILES,
+                        }, "hot:watch");
+                    }
+                    else {
+                        logInfo("hot watch polling disabled after initial scan failed", {
+                            rootDir: this.rootDir,
+                            errorName: error instanceof Error ? error.name : typeof error,
+                        }, "hot:watch");
+                    }
+                }
+                await this.watchDir(this.rootDir);
+                if (!this.pollingDisabled) {
+                    this.startPolling();
+                }
+            },
             catch: (cause) => toSmithersError(cause, "start hot watch tree"),
         }).pipe(Effect.annotateLogs({
             rootDir: this.rootDir,
@@ -105,6 +145,122 @@ export class WatchTree {
     shouldIgnore(name) {
         return this.ignore.includes(name) || name.startsWith(".");
     }
+    pollIntervalMs() {
+        return Math.min(MAX_POLL_MS, Math.max(MIN_POLL_MS, this.debounceMs * 4));
+    }
+    resetPollBackoff() {
+        this.currentPollIntervalMs = this.pollIntervalMs();
+    }
+    advancePollBackoff(changed) {
+        if (changed) {
+            this.resetPollBackoff();
+            return;
+        }
+        this.currentPollIntervalMs = Math.min(MAX_POLL_MS, Math.max(this.pollIntervalMs(), this.currentPollIntervalMs * 2));
+    }
+    scheduleNextPoll() {
+        if (this.pollTimer || this.closed || this.pollingDisabled)
+            return;
+        this.pollTimer = setTimeout(() => {
+            this.pollTimer = null;
+            void this.pollOnce().finally(() => {
+                this.scheduleNextPoll();
+            });
+        }, this.currentPollIntervalMs);
+    }
+    startPolling() {
+        if (this.pollTimer || this.closed || this.pollingDisabled)
+            return;
+        this.resetPollBackoff();
+        this.scheduleNextPoll();
+    }
+    async pollOnce() {
+        if (this.closed || this.polling || this.pollingDisabled)
+            return false;
+        this.polling = true;
+        try {
+            const next = await this.scanFileSignatures(this.rootDir);
+            const changed = this.recordScanChanges(next);
+            this.advancePollBackoff(changed);
+            return changed;
+        }
+        catch (error) {
+            if (error instanceof HotWatchScanLimitError) {
+                this.pollingDisabled = true;
+                logInfo("hot watch polling disabled by file count guard", {
+                    rootDir: this.rootDir,
+                    maxFiles: MAX_POLL_FILES,
+                }, "hot:watch");
+            }
+            else {
+                this.advancePollBackoff(false);
+            }
+            // Ignore transient filesystem races; the next interval will retry.
+            return false;
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    /**
+   * @param {string} dir
+   * @returns {Promise<Map<string, string>>}
+   */
+    async scanFileSignatures(dir) {
+        const files = new Map();
+        await this.scanDir(dir, files);
+        return files;
+    }
+    /**
+   * @param {string} dir
+   * @param {Map<string, string>} files
+   * @returns {Promise<void>}
+   */
+    async scanDir(dir, files) {
+        if (this.closed)
+            return;
+        const baseName = basename(dir);
+        if (baseName && this.shouldIgnore(baseName) && dir !== this.rootDir)
+            return;
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (this.shouldIgnore(entry.name))
+                continue;
+            if (files.size >= MAX_POLL_FILES) {
+                throw new HotWatchScanLimitError();
+            }
+            const fullPath = resolve(dir, entry.name);
+            if (entry.isDirectory()) {
+                await this.scanDir(fullPath, files);
+            }
+            else if (entry.isFile()) {
+                const info = await stat(fullPath).catch(() => null);
+                if (info?.isFile()) {
+                    files.set(fullPath, `${info.mtimeMs}:${info.size}`);
+                }
+            }
+        }
+    }
+    /**
+   * @param {Map<string, string>} next
+   */
+    recordScanChanges(next) {
+        let changed = false;
+        for (const [filePath, signature] of next) {
+            if (this.fileSignatures.get(filePath) !== signature) {
+                this.onFileChange(filePath);
+                changed = true;
+            }
+        }
+        for (const filePath of this.fileSignatures.keys()) {
+            if (!next.has(filePath)) {
+                this.onFileChange(filePath);
+                changed = true;
+            }
+        }
+        this.fileSignatures = next;
+        return changed;
+    }
     /**
    * @param {string} dir
    * @returns {Promise<void>}
@@ -112,7 +268,7 @@ export class WatchTree {
     async watchDir(dir) {
         if (this.closed)
             return;
-        const baseName = dir.split("/").pop() ?? "";
+        const baseName = basename(dir);
         if (baseName && this.shouldIgnore(baseName) && dir !== this.rootDir)
             return;
         try {
@@ -130,6 +286,8 @@ export class WatchTree {
                     fullPath,
                 }, "hot:watch");
                 this.onFileChange(fullPath);
+                this.resetPollBackoff();
+                void this.pollOnce();
             });
             this.watchers.push(watcher);
             // Recursively watch subdirectories

package/src/workflow-hash.js

@@ -0,0 +1,157 @@
+import { existsSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+
+const STATIC_IMPORT_RE = /\b(?:import|export)\s+(?:[^"'`]*?\s+from\s*)?["']([^"']+)["']/g;
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+const WORKFLOW_IMPORT_EXTENSIONS = [
+    "",
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".cts",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+];
+
+/**
+ * @param {string} input
+ * @returns {string}
+ */
+export function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+
+/**
+ * @param {string | null | undefined} sourcePath
+ */
+export function getWorkflowImportScanLoader(sourcePath) {
+    const lower = sourcePath?.toLowerCase() ?? "";
+    if (lower.endsWith(".tsx"))
+        return "tsx";
+    if (lower.endsWith(".jsx"))
+        return "jsx";
+    if (lower.endsWith(".ts") ||
+        lower.endsWith(".mts") ||
+        lower.endsWith(".cts")) {
+        return "ts";
+    }
+    return "js";
+}
+
+/**
+ * @param {string | null} workflowPath
+ * @returns {Promise<string | null>}
+ */
+export async function readWorkflowEntryHash(workflowPath) {
+    if (!workflowPath)
+        return null;
+    try {
+        const raw = await readFile(workflowPath, "utf8");
+        return sha256Hex(raw);
+    }
+    catch {
+        return null;
+    }
+}
+
+/**
+ * @param {string} source
+ * @param {string | null} [sourcePath]
+ * @returns {string[]}
+ */
+export function extractWorkflowImportSpecifiers(source, sourcePath) {
+    if (typeof Bun !== "undefined" && typeof Bun.Transpiler === "function") {
+        try {
+            const scanned = new Bun.Transpiler({
+                loader: getWorkflowImportScanLoader(sourcePath),
+            }).scanImports(source);
+            const specifiers = new Set();
+            for (const entry of scanned) {
+                const specifier = entry?.path?.trim();
+                if (specifier?.startsWith(".")) {
+                    specifiers.add(specifier);
+                }
+            }
+            return [...specifiers];
+        }
+        catch {
+            // Fall back to regex scanning if Bun's parser cannot handle the source.
+        }
+    }
+    const specifiers = new Set();
+    for (const pattern of [STATIC_IMPORT_RE, DYNAMIC_IMPORT_RE]) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(source)) !== null) {
+            const specifier = match[1]?.trim();
+            if (!specifier?.startsWith("."))
+                continue;
+            specifiers.add(specifier);
+        }
+    }
+    return [...specifiers];
+}
+
+/**
+ * @param {string} baseFile
+ * @param {string} specifier
+ * @returns {string | null}
+ */
+export function resolveWorkflowImport(baseFile, specifier) {
+    const basePath = resolve(dirname(baseFile), specifier);
+    const candidates = [
+        ...WORKFLOW_IMPORT_EXTENSIONS.map((ext) => `${basePath}${ext}`),
+        ...WORKFLOW_IMPORT_EXTENSIONS
+            .filter((ext) => ext.length > 0)
+            .map((ext) => resolve(basePath, `index${ext}`)),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate) && statSync(candidate).isFile()) {
+            return resolve(candidate);
+        }
+    }
+    return null;
+}
+
+/**
+ * @param {string} workflowPath
+ * @returns {Promise<string[]>}
+ */
+async function collectWorkflowModuleHashEntries(workflowPath, visited = new Set()) {
+    const resolvedPath = resolve(workflowPath);
+    if (visited.has(resolvedPath)) {
+        return [];
+    }
+    visited.add(resolvedPath);
+    const source = await readFile(resolvedPath, "utf8");
+    const entries = [`${resolvedPath}:${sha256Hex(source)}`];
+    for (const specifier of extractWorkflowImportSpecifiers(source, resolvedPath)) {
+        const importedPath = resolveWorkflowImport(resolvedPath, specifier);
+        if (!importedPath) {
+            throw new SmithersError("WORKFLOW_HASH_RESOLUTION_FAILED", `Unable to resolve workflow import "${specifier}" from ${resolvedPath}.`, { workflowPath: resolvedPath, specifier });
+        }
+        entries.push(...(await collectWorkflowModuleHashEntries(importedPath, visited)));
+    }
+    return entries;
+}
+
+/**
+ * @param {string | null} workflowPath
+ * @returns {Promise<string | null>}
+ */
+export async function readWorkflowGraphHash(workflowPath) {
+    if (!workflowPath)
+        return null;
+    try {
+        const entries = await collectWorkflowModuleHashEntries(workflowPath);
+        return sha256Hex(entries.sort().join("|"));
+    }
+    catch {
+        return null;
+    }
+}