@smithers-orchestrator/driver 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/driver",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Workflow execution driver — runs tasks, acts on EngineDecisions, reports results",
   "type": "module",
   "sideEffects": false,
@@ -63,11 +63,11 @@
   "dependencies": {
     "effect": "^3.21.1",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/graph": "0.22.0",
-    "@smithers-orchestrator/errors": "0.22.0",
-    "@smithers-orchestrator/scheduler": "0.22.0",
-    "@smithers-orchestrator/observability": "0.22.0",
-    "@smithers-orchestrator/db": "0.22.0"
+    "@smithers-orchestrator/db": "0.24.0",
+    "@smithers-orchestrator/errors": "0.24.0",
+    "@smithers-orchestrator/graph": "0.24.0",
+    "@smithers-orchestrator/observability": "0.24.0",
+    "@smithers-orchestrator/scheduler": "0.24.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/RunOptions.ts

@@ -4,7 +4,7 @@ import type { SmithersEvent } from "@smithers-orchestrator/observability/Smither
 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>) */
+  /** Directory for generation overlays (default: rootDir/.smithers/hmr) */
   outDir?: string;
   /** Max overlay generations to keep (default: 3) */
   maxGenerations?: number;

package/src/SmithersCtx.js

@@ -1,15 +1,17 @@
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { stripAutoColumns } from "@smithers-orchestrator/db/output";
 import { buildCurrentScopes } from "./buildCurrentScopes.js";
 import { filterRowsByNodeId } from "./filterRowsByNodeId.js";
 import { normalizeInputRow } from "./normalizeInputRow.js";
 import { withLogicalIterationShortcuts } from "./withLogicalIterationShortcuts.js";
+import { resolveWorktreePath } from "@smithers-orchestrator/graph";
 /** @typedef {import("./OutputKey.ts").OutputKey} OutputKey */
 /** @typedef {import("./SafeParser.ts").SafeParser} SafeParser */
 /** @typedef {import("./SmithersCtxOptions.ts").SmithersCtxOptions} SmithersCtxOptions */
 /** @typedef {import("./RunAuthContext.ts").RunAuthContext} RunAuthContext */
 /** @typedef {import("./SmithersRuntimeConfig.ts").SmithersRuntimeConfig} SmithersRuntimeConfig */
 /** @typedef {unknown} TableRef */
-/** @typedef {Record<string, unknown> & { iteration?: number; nodeId?: string }} OutputRow */
+/** @typedef {Record<string, unknown>} OutputRow User-visible output row — harness metadata fields (runId, nodeId, iteration) are stripped. */
 /**
  * @template Schema
  * @typedef {import("./OutputAccessor.ts").OutputAccessor<Schema>} OutputAccessor
@@ -50,6 +52,8 @@ export class SmithersCtx {
     auth;
     /** @type {SmithersRuntimeConfig | null | undefined} */
     __smithersRuntime;
+    /** @type {Record<string, string>} */
+    _worktreePaths;
     /** @type {OutputAccessor<Schema>} */
     outputs;
     /** @type {import("./OutputSnapshot.ts").OutputSnapshot} */
@@ -68,9 +72,20 @@ export class SmithersCtx {
         this.input = /** @type {Schema extends { input: infer T } ? T : unknown} */ (normalizeInputRow(opts.input));
         this.auth = opts.auth ?? null;
         this.__smithersRuntime = opts.runtimeConfig ?? null;
+        this._worktreePaths = opts.runtimeConfig?.worktreePaths ?? {};
         this._outputs = opts.outputs;
         this._zodToKeyName = opts.zodToKeyName;
         this._currentScopes = buildCurrentScopes(this.iterations);
+        /**
+         * Tasks that declared `deps` but could not resolve them this render, so
+         * they deferred (returned null) instead of mounting. The engine reads this
+         * after each render: a deferral is normal while an upstream is still
+         * producing, but one that survives to quiescence means the dependency can
+         * never resolve (e.g. a deps/needs key that maps to a node id no task
+         * produces) and the run would otherwise finish silently without it.
+         * @type {{ nodeId: string; waitingOn: string[] }[]}
+         */
+        this._deferredDeps = [];
         /**
          * @param {string} table
          */
@@ -80,6 +95,29 @@ export class SmithersCtx {
         }
         this.outputs = /** @type {OutputAccessor<Schema>} */ (/** @type {unknown} */ (outputsFn));
     }
+    /**
+     * Return the resolved absolute path for a rendered worktree or task id.
+     * The lookup is populated from task descriptors, so task node ids and
+     * explicit <Worktree id> values both work once the worktree has rendered.
+     *
+     * @param {string} id
+     * @returns {string | undefined}
+     */
+    worktreePath(id) {
+        return this._worktreePaths[id];
+    }
+    /**
+     * Resolve a <Worktree path> prop against the active workflow root using
+     * the same resolver graph extraction uses.
+     *
+     * @param {string} path
+     * @returns {string}
+     */
+    resolveWorktreePath(path) {
+        return resolveWorktreePath(path, {
+            baseRootDir: this.__smithersRuntime?.baseRootDir,
+        });
+    }
     /**
      * @param {TableRef} table
      * @param {OutputKey} key
@@ -90,7 +128,7 @@ export class SmithersCtx {
         if (!row) {
             throw new SmithersError("MISSING_OUTPUT", `Missing output for nodeId=${key.nodeId} iteration=${key.iteration ?? 0}`, { nodeId: key.nodeId, iteration: key.iteration ?? 0 });
         }
-        return row;
+        return /** @type {OutputRow} */ (stripAutoColumns(row));
     }
     /**
      * @param {TableRef} table
@@ -98,7 +136,8 @@ export class SmithersCtx {
      * @returns {OutputRow | undefined}
      */
     outputMaybe(table, key) {
-        return this.resolveRow(table, key);
+        const row = this.resolveRow(table, key);
+        return row !== undefined ? /** @type {OutputRow} */ (stripAutoColumns(row)) : undefined;
     }
     /**
      * @param {TableRef} table
@@ -179,6 +218,21 @@ export class SmithersCtx {
             return zodKey;
         return resolveDrizzleName(table) ?? String(table);
     }
+    /**
+     * Record that a task with `deps` deferred this render because its
+     * dependencies were not resolvable. Called by the Task component before it
+     * returns null. The engine inspects these at quiescence to turn a permanent
+     * deferral (a never-satisfiable dependency) into a loud error instead of a
+     * silent skip.
+     * @param {string} nodeId
+     * @param {string[]} waitingOn
+     * @returns {void}
+     */
+    recordDeferredDep(nodeId, waitingOn) {
+        if (typeof nodeId !== "string" || nodeId.length === 0)
+            return;
+        this._deferredDeps.push({ nodeId, waitingOn: Array.isArray(waitingOn) ? waitingOn : [] });
+    }
     /**
      * @param {TableRef} table
      * @param {OutputKey} key
@@ -188,8 +242,26 @@ export class SmithersCtx {
         const tableName = this.resolveTableName(table);
         const rows = this._outputs[tableName] ?? [];
         const matching = filterRowsByNodeId(rows, key.nodeId, this._currentScopes);
-        return matching.find((row) => {
-            return (row.iteration ?? 0) === (key.iteration ?? this.iteration);
-        });
+        const targetIteration = key.iteration ?? this.iteration;
+        const exact = matching.find((row) => (row.iteration ?? 0) === targetIteration);
+        if (exact)
+            return exact;
+        // Cross-loop-boundary resolution: a task INSIDE a loop (this.iteration >= 1)
+        // that depends — via deps/needs — on a task OUTSIDE the loop never matched
+        // the strict equality above, because the upstream wrote its row with an
+        // unscoped nodeId at its own iteration (typically 0) while the depender
+        // renders at the loop iteration. That mismatch made the dependent task
+        // resolve `undefined` and unmount forever. Resolve an unscoped producer
+        // (one that ran outside any loop) at its own iteration instead.
+        //
+        // The relaxation is deliberately narrow: it only applies when the caller
+        // did not pin an explicit iteration, and only to rows whose nodeId carries
+        // no loop scope (`@@`). An in-loop producer always writes scoped rows, so it
+        // keeps the strict gate above — a not-yet-produced iteration still defers
+        // instead of resolving stale data from an earlier pass.
+        if (key.iteration === undefined) {
+            return matching.find((row) => typeof row.nodeId === "string" && !row.nodeId.includes("@@"));
+        }
+        return undefined;
     }
 }

package/src/SmithersRuntimeConfig.ts

@@ -1,3 +1,6 @@
 export type SmithersRuntimeConfig = {
   cliAgentToolsDefault?: "all" | "explicit-only";
+  baseRootDir?: string;
+  workflowPath?: string | null;
+  worktreePaths?: Record<string, string>;
 };

package/src/SpawnCaptureOptions.ts

@@ -6,6 +6,13 @@ export type SpawnCaptureOptions = {
   timeoutMs?: number;
   idleTimeoutMs?: number;
   maxOutputBytes?: number;
+  /**
+   * Which end of overflowing STDOUT to keep. CLI agents that emit their final
+   * result at the end of an NDJSON stream should keep the tail. Stderr always
+   * keeps the head: failure classification reads the leading error text.
+   * @default "head"
+   */
+  truncateKeep?: "head" | "tail";
   detached?: boolean;
   onStdout?: (chunk: string) => void;
   onStderr?: (chunk: string) => void;

package/src/SpawnCaptureResult.ts

@@ -2,4 +2,8 @@ export type SpawnCaptureResult = {
   stdout: string;
   stderr: string;
   exitCode: number | null;
+  /** True when captured stdout exceeded maxOutputBytes and was truncated. */
+  stdoutTruncated: boolean;
+  /** True when captured stderr exceeded maxOutputBytes and was truncated. */
+  stderrTruncated: boolean;
 };

package/src/WorkflowDriver.js

@@ -1,3 +1,4 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { SmithersCtx } from "./SmithersCtx.js";
 import { defaultTaskExecutor } from "./defaultTaskExecutor.js";
 import { withAbort } from "./withAbort.js";
@@ -65,6 +66,23 @@ function recordFromIterations(iterations) {
     }
     return iterations;
 }
+/**
+ * @param {readonly TaskDescriptor[]} tasks
+ * @returns {Record<string, string>}
+ */
+function buildWorktreePathLookup(tasks) {
+    /** @type {Record<string, string>} */
+    const lookup = {};
+    for (const task of tasks) {
+        if (!task.worktreePath)
+            continue;
+        lookup[task.nodeId] = task.worktreePath;
+        if (task.worktreeId && lookup[task.worktreeId] === undefined) {
+            lookup[task.worktreeId] = task.worktreePath;
+        }
+    }
+    return lookup;
+}
 /**
  * @param {RenderContext} context
  * @param {ReadonlyMap<string, string>} [knownOutputTables]
@@ -153,6 +171,29 @@ async function loadCreateSession() {
     }
     return null;
 }
+/**
+ * Build a diagnostic for tasks that declared `deps` they could never resolve, so
+ * they deferred (returned null) instead of mounting and the run reached
+ * quiescence without them. Left undetected this is a silent skip — the run
+ * "finishes" without ever running the task.
+ * @param {{ nodeId: string; waitingOn: string[] }[]} deferred
+ * @returns {string}
+ */
+function describeDeferredDeadlock(deferred) {
+    const lines = deferred.map(({ nodeId, waitingOn }) => {
+        const detail = waitingOn.length === 0
+            ? "its deps never resolved"
+            : `waiting on ${waitingOn.map((id) => `'${id}'`).join(", ")}`;
+        return `  - '${nodeId}' never ran (${detail})`;
+    });
+    return [
+        "Workflow has task(s) that can never run: their deps reference outputs no task produces.",
+        ...lines,
+        "",
+        "A deps={{ <key>: ... }} entry resolves <key> as the upstream task's id unless you remap it. " +
+            "Add needs={{ <key>: '<upstream task id>' }} (or rename the upstream task to match the key) so the dependency points at a real task.",
+    ].join("\n");
+}
 /**
  * @param {unknown} error
  * @returns {boolean}
@@ -225,10 +266,18 @@ export class WorkflowDriver {
     activeOptions;
     /** @type {import("@smithers-orchestrator/graph").WorkflowGraph | undefined} */
     lastGraph;
+    /** @type {{ nodeId: string; waitingOn: string[] }[]} Tasks that deferred on unresolved deps in the latest render. */
+    lastDeferredDeps = [];
+    /** @type {Record<string, string>} */
+    worktreePathsById = {};
     /** @type {Map<string, string>} */
     outputTablesByNodeId = new Map();
     /** @type {OutputSnapshot} */
     baseOutputs = {};
+    /** @type {Map<string, Promise<{ key: string; task: TaskDescriptor; kind: "completed" | "failed" | "cancelled"; output?: unknown; error?: unknown }>>} */
+    inflightTasks = new Map();
+    /** @type {Array<{ key: string; task: TaskDescriptor; kind: "completed" | "failed" | "cancelled"; output?: unknown; error?: unknown }>} */
+    settledTasks = [];
     /**
      * @param {import("./WorkflowDriverOptions.ts").WorkflowDriverOptions<Schema>} options
      */
@@ -298,10 +347,21 @@ export class WorkflowDriver {
                     break;
                 }
                 case "ContinueAsNew":
+                    await this.drainInflight();
                     return this.continueAsNew(decision.transition);
-                case "Finished":
+                case "Finished": {
+                    if (this.lastDeferredDeps.length > 0) {
+                        await this.drainInflight();
+                        return {
+                            runId,
+                            status: "failed",
+                            error: new SmithersError("DEPENDENCY_DEADLOCK", describeDeferredDeadlock(this.lastDeferredDeps)),
+                        };
+                    }
                     return decision.result;
+                }
                 case "Failed":
+                    await this.drainInflight();
                     return { runId, status: "failed", error: decision.error };
                 default:
                     return {
@@ -344,6 +404,8 @@ export class WorkflowDriver {
         }
         const iteration = typeof context.iteration === "number" ? context.iteration : 0;
         const iterations = recordFromIterations(context.iterations ?? context.ralphIterations);
+        const baseRootDir = this.activeOptions?.rootDir ?? this.rootDir;
+        const workflowPath = this.activeOptions?.workflowPath ?? this.workflowPath ?? null;
         const ctx = new SmithersCtx({
             runId: context.runId,
             iteration,
@@ -352,21 +414,31 @@ export class WorkflowDriver {
             auth: context.auth,
             outputs: mergeOutputSnapshots(this.baseOutputs, snapshotFromContext(context, this.outputTablesByNodeId)),
             zodToKeyName: this.workflow.zodToKeyName,
-            runtimeConfig: this.activeOptions?.cliAgentToolsDefault
-                ? { cliAgentToolsDefault: this.activeOptions.cliAgentToolsDefault }
-                : undefined,
+            runtimeConfig: {
+                ...(this.activeOptions?.cliAgentToolsDefault
+                    ? { cliAgentToolsDefault: this.activeOptions.cliAgentToolsDefault }
+                    : {}),
+                baseRootDir,
+                workflowPath,
+                worktreePaths: this.worktreePathsById,
+            },
         });
         const graph = await this.renderer.render(this.workflow.build(ctx), {
             ralphIterations: context.iterations ?? context.ralphIterations,
             defaultIteration: iteration,
-            baseRootDir: this.activeOptions?.rootDir ?? this.rootDir,
-            workflowPath: this.activeOptions?.workflowPath ?? this.workflowPath ?? null,
+            baseRootDir,
+            workflowPath,
         });
+        // Capture tasks that deferred on unresolved deps this render so the run
+        // loop can fail loudly if any survive to a Finished decision instead of
+        // silently skipping them.
+        this.lastDeferredDeps = ctx._deferredDeps ?? [];
         for (const task of graph.tasks) {
             if (task.outputTableName) {
                 this.outputTablesByNodeId.set(task.nodeId, task.outputTableName);
             }
         }
+        this.worktreePathsById = buildWorktreePathLookup(graph.tasks);
         this.lastGraph = graph;
         return this.runEffect(this.session.submitGraph(graph));
     }
@@ -386,47 +458,98 @@ export class WorkflowDriver {
         if (context.signal?.aborted) {
             return this.cancelRun();
         }
-        let latestDecision;
-        let cancelled = false;
+        for (const task of tasks) {
+            this.startInflightTask(task, context);
+        }
+        return this.nextCompletionDecision();
+    }
+    /**
+   * Start a task without blocking the driver loop on its completion. Settled
+   * tasks queue in `settledTasks` and are reported to the session one at a
+   * time from `nextCompletionDecision`, so each decision is computed against
+   * fresh session state and a slow task never blocks scheduling work that
+   * became ready elsewhere in the graph (#267).
+   * @param {TaskDescriptor} task
+   * @param {{ runId: string; options: RunOptions; signal?: AbortSignal }} context
+   */
+    startInflightTask(task, context) {
+        const key = `${task.nodeId}::${task.iteration}`;
+        if (this.inflightTasks.has(key)) {
+            return;
+        }
+        const promise = (async () => {
+            try {
+                const output = await withAbort(Promise.resolve().then(() => this.executeTask(task, context)), context.signal);
+                return { key, task, kind: /** @type {const} */ ("completed"), output };
+            }
+            catch (error) {
+                if (context.signal?.aborted || isAbortError(error)) {
+                    return { key, task, kind: /** @type {const} */ ("cancelled") };
+                }
+                return { key, task, kind: /** @type {const} */ ("failed"), error };
+            }
+        })().then((settled) => {
+            this.inflightTasks.delete(key);
+            this.settledTasks.push(settled);
+            return settled;
+        });
+        this.inflightTasks.set(key, promise);
+    }
+    /**
+   * Wait for the next settled task (or an optional deadline) and report it to
+   * the session for a fresh decision. Completions that landed while a previous
+   * one was being processed drain from `settledTasks` first.
+   * @param {number | null} [deadlineMs]
+   * @returns {Promise<EngineDecision | RunResult>}
+   */
+    async nextCompletionDecision(deadlineMs = null) {
+        if (!this.session) {
+            throw new Error("WorkflowSession is not initialized.");
+        }
         const waitStart = performance.now();
         try {
-            await Promise.all(tasks.map(async (task) => {
-                let report;
-                try {
-                    const output = await withAbort(Promise.resolve().then(() => this.executeTask(task, context)), context.signal);
-                    report = await this.runEffect(this.session.taskCompleted({
-                        nodeId: task.nodeId,
-                        iteration: task.iteration,
-                        output,
-                    }));
+            if (this.settledTasks.length === 0 && this.inflightTasks.size > 0) {
+                const racers = [...this.inflightTasks.values()];
+                if (deadlineMs != null) {
+                    racers.push(sleepWithAbort(deadlineMs, this.activeOptions?.signal).then(() => null));
                 }
-                catch (error) {
-                    if (context.signal?.aborted || isAbortError(error)) {
-                        cancelled = true;
-                        return;
-                    }
-                    report = await this.runEffect(this.session.taskFailed({
-                        nodeId: task.nodeId,
-                        iteration: task.iteration,
-                        error,
-                    }));
-                }
-                if (isEngineDecision(report)) {
-                    latestDecision = report;
-                }
-            }));
+                await Promise.race(racers);
+            }
         }
         finally {
             await this.onSchedulerWait?.(performance.now() - waitStart, {
                 runId: this.activeRunId,
-                tasks,
+                tasks: [],
             });
         }
-        if (cancelled || context.signal?.aborted) {
+        if (this.activeOptions?.signal?.aborted) {
             return this.cancelRun();
         }
-        if (latestDecision) {
-            return latestDecision;
+        const settled = this.settledTasks.shift();
+        if (!settled) {
+            // Deadline elapsed (retry backoff / timer) without a completion —
+            // re-submit the last graph for a fresh decision.
+            if (this.lastGraph) {
+                return this.runEffect(this.session.submitGraph(this.lastGraph));
+            }
+            return { runId: this.activeRunId, status: "waiting-event" };
+        }
+        if (settled.kind === "cancelled") {
+            return this.cancelRun();
+        }
+        const report = settled.kind === "completed"
+            ? await this.runEffect(this.session.taskCompleted({
+                nodeId: settled.task.nodeId,
+                iteration: settled.task.iteration,
+                output: settled.output,
+            }))
+            : await this.runEffect(this.session.taskFailed({
+                nodeId: settled.task.nodeId,
+                iteration: settled.task.iteration,
+                error: settled.error,
+            }));
+        if (isEngineDecision(report)) {
+            return report;
         }
         if (typeof this.session.getNextDecision === "function") {
             return this.runEffect(this.session.getNextDecision());
@@ -434,10 +557,36 @@ export class WorkflowDriver {
         throw new Error("WorkflowSession did not provide the next EngineDecision.");
     }
     /**
+   * Await every in-flight task without reporting further decisions. Used
+   * before run-level exits (failure, continue-as-new) so task executors are
+   * not abandoned mid-write. This matches the pre-#267 barrier semantics:
+   * failure reporting waits for in-flight siblings (bounded by their
+   * timeouts), trading latency for the invariant that no executor writes
+   * after the run is terminal. Fail-fast would need a per-run abort threaded
+   * through executors.
+   */
+    async drainInflight() {
+        while (this.inflightTasks.size > 0) {
+            await Promise.allSettled([...this.inflightTasks.values()]);
+        }
+        this.settledTasks.length = 0;
+    }
+    /**
    * @param {WaitReason} reason
    * @returns {Promise<EngineDecision | RunResult>}
    */
     async handleWait(reason) {
+        if (this.inflightTasks.size > 0 || this.settledTasks.length > 0) {
+            // Work is still in flight — consume the next completion instead of
+            // suspending the run. Deadline-style waits keep their deadline so a
+            // retry backoff or timer elsewhere in the graph still fires on time.
+            const deadlineMs = reason._tag === "RetryBackoff"
+                ? Math.max(0, reason.waitMs)
+                : reason._tag === "Timer"
+                    ? Math.max(0, reason.resumeAtMs - Date.now())
+                    : null;
+            return this.nextCompletionDecision(deadlineMs);
+        }
         if (this.onWait) {
             return this.onWait(reason, {
                 runId: this.activeRunId,

package/src/child-process.js

@@ -13,11 +13,13 @@ import { logDebug, logWarning } from "@smithers-orchestrator/observability/loggi
  * @param {number} maxBytes
  * @returns {string}
  */
-function truncateToBytes(text, maxBytes) {
+function truncateToBytes(text, maxBytes, keep = "head") {
     const buf = Buffer.from(text, "utf8");
     if (buf.length <= maxBytes)
         return text;
-    return buf.subarray(0, maxBytes).toString("utf8");
+    return keep === "tail"
+        ? buf.subarray(buf.length - maxBytes).toString("utf8")
+        : buf.subarray(0, maxBytes).toString("utf8");
 }
 /**
  * @param {string} command
@@ -26,7 +28,7 @@ function truncateToBytes(text, maxBytes) {
  * @returns {Effect.Effect<SpawnCaptureResult, SmithersError>}
  */
 export function spawnCaptureEffect(command, args, options) {
-    const { cwd, env, input, signal, timeoutMs, idleTimeoutMs, maxOutputBytes = 200_000, detached = false, onStdout, onStderr, } = options;
+    const { cwd, env, input, signal, timeoutMs, idleTimeoutMs, maxOutputBytes = 200_000, truncateKeep = "head", detached = false, onStdout, onStderr, } = options;
     const errorDetails = {
         command,
         args,
@@ -160,7 +162,7 @@ export function spawnCaptureEffect(command, args, options) {
                     stream: "stdout",
                 }, span);
             }
-            stdout = truncateToBytes(nextStdout, maxOutputBytes);
+            stdout = truncateToBytes(nextStdout, maxOutputBytes, truncateKeep);
             onStdout?.(text);
         });
         child.stderr?.on("data", (chunk) => {
@@ -197,7 +199,7 @@ export function spawnCaptureEffect(command, args, options) {
             }
         });
         child.on("close", (code) => {
-            finalize({ stdout, stderr, exitCode: code ?? null });
+            finalize({ stdout, stderr, exitCode: code ?? null, stdoutTruncated, stderrTruncated });
         });
         child.stdin?.on("error", (error) => {
             logWarning("child process stdin error", {

package/src/index.d.ts

@@ -43,7 +43,7 @@ type RunAuthContext$2 = {
 type HotReloadOptions$1 = {
     /** Root directory to watch for changes (default: auto-detect from workflow entry) */
     rootDir?: string;
-    /** Directory for generation overlays (default: .smithers/hmr/<runId>) */
+    /** Directory for generation overlays (default: rootDir/.smithers/hmr) */
     outDir?: string;
     /** Max overlay generations to keep (default: 3) */
     maxGenerations?: number;
@@ -68,6 +68,7 @@ type RunOptions$2 = {
     maxOutputBytes?: number;
     toolTimeoutMs?: number;
     hot?: boolean | HotReloadOptions$1;
+    annotations?: Record<string, string | number | boolean>;
     auth?: RunAuthContext$2 | null;
     config?: Record<string, unknown>;
     cliAgentToolsDefault?: "all" | "explicit-only";
@@ -142,6 +143,9 @@ type OutputForTable<Schema, Table> = Table extends OutputSchemaKey<Schema> ? Inf
 
 type SmithersRuntimeConfig$1 = {
     cliAgentToolsDefault?: "all" | "explicit-only";
+    baseRootDir?: string;
+    workflowPath?: string | null;
+    worktreePaths?: Record<string, string>;
 };
 
 type OutputSnapshot$2<TFallback = unknown> = {
@@ -196,6 +200,8 @@ declare class SmithersCtx<Schema extends unknown = unknown> {
     auth: RunAuthContext$1 | null;
     /** @type {SmithersRuntimeConfig | null | undefined} */
     __smithersRuntime: SmithersRuntimeConfig | null | undefined;
+    /** @type {Record<string, string>} */
+    _worktreePaths: Record<string, string>;
     /** @type {OutputAccessor<Schema>} */
     outputs: OutputAccessor$1<Schema>;
     /** @type {import("./OutputSnapshot.ts").OutputSnapshot} */
@@ -204,6 +210,23 @@ declare class SmithersCtx<Schema extends unknown = unknown> {
     _zodToKeyName: Map<unknown, string> | undefined;
     /** @type {Set<string>} */
     _currentScopes: Set<string>;
+    /**
+     * Return the resolved absolute path for a rendered worktree or task id.
+     * The lookup is populated from task descriptors, so task node ids and
+     * explicit <Worktree id> values both work once the worktree has rendered.
+     *
+     * @param {string} id
+     * @returns {string | undefined}
+     */
+    worktreePath(id: string): string | undefined;
+    /**
+     * Resolve a <Worktree path> prop against the active workflow root using
+     * the same resolver graph extraction uses.
+     *
+     * @param {string} path
+     * @returns {string}
+     */
+    resolveWorktreePath(path: string): string;
     /**
      * @param {TableRef} table
      * @param {OutputKey} key
@@ -252,10 +275,8 @@ type SmithersCtxOptions$1 = SmithersCtxOptions$2;
 type RunAuthContext$1 = RunAuthContext$2;
 type SmithersRuntimeConfig = SmithersRuntimeConfig$1;
 type TableRef = unknown;
-type OutputRow = Record<string, unknown> & {
-    iteration?: number;
-    nodeId?: string;
-};
+/** User-visible output row — harness metadata fields (runId, nodeId, iteration) are stripped. */
+type OutputRow = Record<string, unknown>;
 type OutputAccessor$1<Schema> = OutputAccessor$2<Schema>;
 
 type WorkflowElement = {