@smithers-orchestrator/graph 0.24.2 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/graph",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "Framework-neutral Smithers workflow graph model and extraction helpers",
   "type": "module",
   "sideEffects": false,
@@ -22,7 +22,7 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/errors": "0.24.2"
+    "@smithers-orchestrator/errors": "0.25.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/dom/extract.js

@@ -3,15 +3,16 @@
 /** @typedef {import("../HostText.ts").HostText} HostText */
 // @smithers-type-exports-end
 
-import { resolveStableId } from "@smithers-orchestrator/graph/utils/tree-ids";
+import { resolveStableId } from "../utils/tree-ids.js";
 import { getTableName } from "drizzle-orm";
-import { DEFAULT_MERGE_QUEUE_CONCURRENCY, WORKTREE_EMPTY_PATH_ERROR, } from "@smithers-orchestrator/graph/constants";
+import { DEFAULT_MERGE_QUEUE_CONCURRENCY, WORKTREE_EMPTY_PATH_ERROR, } from "../constants.js";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
-import { resolveWorktreePath } from "@smithers-orchestrator/graph/worktree-path";
+import { resolveWorktreePath } from "../worktree-path.js";
 
 /** @typedef {import("../ExtractOptions.ts").ExtractOptions} ExtractOptions */
 /** @typedef {import("../ExtractResult.ts").ExtractResult} ExtractResult */
 /** @typedef {import("../HostNode.ts").HostNode} HostNode */
+/** @typedef {import("../TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
 /** @typedef {import("../XmlNode.ts").XmlNode} XmlNode */
 
 // TODO(migration): Delegate extractFromHost to
@@ -48,13 +49,13 @@ const DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS = envHeartbeatTimeoutMs();
 const DEFAULT_SANDBOX_TASK_HEARTBEAT_TIMEOUT_MS = envHeartbeatTimeoutMs();
 /**
  * @param {unknown} value
- * @returns {boolean}
+ * @returns {value is any}
  */
 function isDrizzleTable(value) {
     if (!value || typeof value !== "object")
         return false;
     try {
-        const name = getTableName(value);
+        const name = getTableName(/** @type {any} */ (value));
         return typeof name === "string" && name.length > 0;
     }
     catch {
@@ -63,7 +64,7 @@ function isDrizzleTable(value) {
 }
 /**
  * @param {unknown} value
- * @returns {boolean}
+ * @returns {value is import("zod").ZodObject<any>}
  */
 function isZodObject(value) {
     return Boolean(value && typeof value === "object" && "shape" in value);
@@ -83,6 +84,15 @@ function parseHeartbeatTimeoutMs(raw) {
     }
     return Math.floor(candidate);
 }
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+function recordOrEmpty(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? /** @type {Record<string, unknown>} */ (value)
+        : {};
+}
 /**
  * @param {HostNode} node
  * @returns {XmlNode}
@@ -92,7 +102,7 @@ function toXmlNode(node) {
         return { kind: "text", text: node.text };
     }
     const element = {
-        kind: "element",
+        kind: /** @type {"element"} */ ("element"),
         tag: node.tag,
         props: node.props ?? {},
         children: node.children.map(toXmlNode),
@@ -112,11 +122,13 @@ function getRalphIteration(opts, id) {
     if (map instanceof Map) {
         return map.get(id) ?? fallback;
     }
-    const value = map[id];
+    const value = /** @type {Record<string, number>} */ (map)[id];
     return typeof value === "number" ? value : fallback;
 }
 /**
  * @param {Record<string, unknown>} raw
+ * @param {boolean} [isAgent]
+ * @returns {{ retries: number; retryPolicy: import("../RetryPolicy.ts").RetryPolicy | undefined }}
  */
 function resolveRetryConfig(raw, isAgent = false) {
     const noRetry = Boolean(raw.noRetry);
@@ -139,7 +151,7 @@ function resolveRetryConfig(raw, isAgent = false) {
     const retryPolicy = hasExplicitRetryPolicy
         ? /** @type {import("../RetryPolicy.ts").RetryPolicy} */ (raw.retryPolicy)
         : retries > 0
-            ? { backoff: "exponential", initialDelayMs: 1000 }
+            ? /** @type {import("../RetryPolicy.ts").RetryPolicy} */ ({ backoff: "exponential", initialDelayMs: 1000 })
             : undefined;
     return { retries, retryPolicy };
 }
@@ -152,7 +164,9 @@ export function extractFromHost(root, opts) {
     if (!root) {
         return { xml: null, tasks: [], mountedTaskIds: [] };
     }
+    /** @type {TaskDescriptor[]} */
     const tasks = [];
+    /** @type {string[]} */
     const mountedTaskIds = [];
     const seen = new Set();
     const seenRalph = new Set();
@@ -251,7 +265,10 @@ export function extractFromHost(root, opts) {
             if (!pathVal) {
                 throw new SmithersError("WORKTREE_EMPTY_PATH", WORKTREE_EMPTY_PATH_ERROR);
             }
-            const normPath = resolveWorktreePath(pathVal, { baseRootDir: opts?.baseRootDir });
+            const normPath = resolveWorktreePath(pathVal, {
+                baseRootDir: opts?.baseRootDir,
+                workflowPath: opts?.workflowPath,
+            });
             const branch = node.rawProps?.branch ? String(node.rawProps.branch) : undefined;
             const baseBranch = node.rawProps?.baseBranch ? String(node.rawProps.baseBranch) : undefined;
             nextWorktreeStack = [...worktreeStack, { id, path: normPath, branch, baseBranch }];
@@ -276,7 +293,7 @@ export function extractFromHost(root, opts) {
             }
             const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
             const outputTableName = outputTable
-                ? getTableName(outputTable)
+                ? getTableName(/** @type {any} */ (outputTable))
                 : typeof outputRaw === "string"
                     ? outputRaw
                     : "";
@@ -285,7 +302,9 @@ export function extractFromHost(root, opts) {
             const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : null;
             const heartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw);
             const continueOnFail = Boolean(raw.continueOnFail);
-            const cachePolicy = raw.cache && typeof raw.cache === "object" ? raw.cache : undefined;
+            const cachePolicy = raw.cache && typeof raw.cache === "object"
+                ? /** @type {import("../CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
+                : undefined;
             const dependsOn = Array.isArray(raw.dependsOn)
                 ? raw.dependsOn.filter((v) => typeof v === "string")
                 : undefined;
@@ -340,9 +359,9 @@ export function extractFromHost(root, opts) {
                         }
                         return result.output;
                     },
-                    label: raw.label,
+                    label: typeof raw.label === "string" ? raw.label : undefined,
                     meta: {
-                        ...raw.meta,
+                        ...recordOrEmpty(raw.meta),
                         __subflow: true,
                         __subflowMode: mode,
                         __subflowInput: raw.__smithersSubflowInput,
@@ -374,7 +393,7 @@ export function extractFromHost(root, opts) {
             }
             const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
             const outputTableName = outputTable
-                ? getTableName(outputTable)
+                ? getTableName(/** @type {any} */ (outputTable))
                 : typeof outputRaw === "string"
                     ? outputRaw
                     : "";
@@ -383,7 +402,9 @@ export function extractFromHost(root, opts) {
             const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : null;
             const heartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw) ?? DEFAULT_SANDBOX_TASK_HEARTBEAT_TIMEOUT_MS;
             const continueOnFail = Boolean(raw.continueOnFail);
-            const cachePolicy = raw.cache && typeof raw.cache === "object" ? raw.cache : undefined;
+            const cachePolicy = raw.cache && typeof raw.cache === "object"
+                ? /** @type {import("../CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
+                : undefined;
             const dependsOn = Array.isArray(raw.dependsOn)
                 ? raw.dependsOn.filter((v) => typeof v === "string")
                 : undefined;
@@ -468,9 +489,9 @@ export function extractFromHost(root, opts) {
                         },
                     });
                 },
-                label: raw.label,
+                label: typeof raw.label === "string" ? raw.label : undefined,
                 meta: {
-                    ...raw.meta,
+                    ...recordOrEmpty(raw.meta),
                     __sandbox: true,
                     __sandboxRuntime: runtime,
                     __sandboxProvider: provider,
@@ -520,12 +541,12 @@ export function extractFromHost(root, opts) {
             }
             const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
             const outputTableName = outputTable
-                ? getTableName(outputTable)
+                ? getTableName(/** @type {any} */ (outputTable))
                 : typeof outputRaw === "string"
                     ? outputRaw
                     : "";
             const outputRef = !outputTable && isZodObject(outputRaw) ? outputRaw : undefined;
-            const outputSchema = raw.outputSchema ?? outputRef;
+            const outputSchema = isZodObject(raw.outputSchema) ? raw.outputSchema : outputRef;
             const waitAsync = Boolean(raw.waitAsync);
             const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : null;
             const heartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw);
@@ -564,9 +585,9 @@ export function extractFromHost(root, opts) {
                 prompt: undefined,
                 staticPayload: undefined,
                 computeFn: undefined,
-                label: raw.label,
+                label: typeof raw.label === "string" ? raw.label : undefined,
                 meta: {
-                    ...raw.meta,
+                    ...recordOrEmpty(raw.meta),
                     __waitForEvent: true,
                     __eventName: raw.__smithersEventName ?? raw.event,
                     __correlationId: raw.__smithersCorrelationId ?? raw.correlationId,
@@ -646,9 +667,9 @@ export function extractFromHost(root, opts) {
                 prompt: undefined,
                 staticPayload: undefined,
                 computeFn: undefined,
-                label: raw.label ?? `timer:${nodeId}`,
+                label: typeof raw.label === "string" ? raw.label : `timer:${nodeId}`,
                 meta: {
-                    ...raw.meta,
+                    ...recordOrEmpty(raw.meta),
                     __timer: true,
                     __timerType: hasDuration ? "duration" : "absolute",
                     ...(hasDuration ? { __timerDuration: duration } : {}),
@@ -698,19 +719,21 @@ export function extractFromHost(root, opts) {
             }
             const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
             const outputTableName = outputTable
-                ? getTableName(outputTable)
+                ? getTableName(/** @type {any} */ (outputTable))
                 : typeof outputRaw === "string"
                     ? outputRaw
                     : "";
             const outputRef = !outputTable && isZodObject(outputRaw) ? outputRaw : undefined;
-            const outputSchema = raw.outputSchema ?? outputRef;
+            const outputSchema = isZodObject(raw.outputSchema) ? raw.outputSchema : outputRef;
             const needsApproval = Boolean(raw.needsApproval);
             const waitAsync = Boolean(raw.waitAsync);
+            /** @type {TaskDescriptor["approvalMode"]} */
             const approvalMode = raw.approvalMode === "decision" ||
                 raw.approvalMode === "select" ||
                 raw.approvalMode === "rank"
                 ? raw.approvalMode
                 : "gate";
+            /** @type {TaskDescriptor["approvalOnDeny"]} */
             const approvalOnDeny = raw.approvalOnDeny === "continue" ||
                 raw.approvalOnDeny === "skip" ||
                 raw.approvalOnDeny === "fail"
@@ -735,31 +758,36 @@ export function extractFromHost(root, opts) {
             const approvalAllowedUsers = Array.isArray(raw.approvalAllowedUsers)
                 ? raw.approvalAllowedUsers.filter((value) => typeof value === "string")
                 : undefined;
-            const approvalAutoApprove = raw.approvalAutoApprove && typeof raw.approvalAutoApprove === "object" && !Array.isArray(raw.approvalAutoApprove)
+            const approvalAutoApproveRaw = raw.approvalAutoApprove && typeof raw.approvalAutoApprove === "object" && !Array.isArray(raw.approvalAutoApprove)
+                ? /** @type {Record<string, unknown>} */ (raw.approvalAutoApprove)
+                : undefined;
+            const approvalAutoApprove = approvalAutoApproveRaw
                 ? {
-                    ...(typeof raw.approvalAutoApprove.after === "number"
-                        ? { after: raw.approvalAutoApprove.after }
+                    ...(typeof approvalAutoApproveRaw.after === "number"
+                        ? { after: approvalAutoApproveRaw.after }
                         : {}),
-                    ...(typeof raw.approvalAutoApprove.audit === "boolean"
-                        ? { audit: raw.approvalAutoApprove.audit }
+                    ...(typeof approvalAutoApproveRaw.audit === "boolean"
+                        ? { audit: approvalAutoApproveRaw.audit }
                         : {}),
-                    ...(typeof raw.approvalAutoApprove.conditionMet === "boolean"
-                        ? { conditionMet: raw.approvalAutoApprove.conditionMet }
+                    ...(typeof approvalAutoApproveRaw.conditionMet === "boolean"
+                        ? { conditionMet: approvalAutoApproveRaw.conditionMet }
                         : {}),
-                    ...(typeof raw.approvalAutoApprove.revertOnMet === "boolean"
-                        ? { revertOnMet: raw.approvalAutoApprove.revertOnMet }
+                    ...(typeof approvalAutoApproveRaw.revertOnMet === "boolean"
+                        ? { revertOnMet: approvalAutoApproveRaw.revertOnMet }
                         : {}),
                 }
                 : undefined;
             const skipIf = Boolean(raw.skipIf);
-            const agent = raw.agent;
+            const agent = /** @type {TaskDescriptor["agent"]} */ (raw.agent);
             const kind = raw.__smithersKind;
             const isAgent = kind === "agent" || Boolean(agent);
             const { retries, retryPolicy } = resolveRetryConfig(raw, isAgent);
             const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : null;
             const parsedHeartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw);
             const continueOnFail = Boolean(raw.continueOnFail);
-            const cachePolicy = raw.cache && typeof raw.cache === "object" ? raw.cache : undefined;
+            const cachePolicy = raw.cache && typeof raw.cache === "object"
+                ? /** @type {import("../CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
+                : undefined;
             const heartbeatTimeoutMs = parsedHeartbeatTimeoutMs ??
                 (isAgent ? DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS : null);
             const prompt = isAgent ? String(raw.children ?? "") : undefined;
@@ -767,8 +795,8 @@ export function extractFromHost(root, opts) {
                 throw new SmithersError("MDX_PRELOAD_INACTIVE", `Task "${raw.id ?? nodeId}" prompt resolved to [object Object] — MDX preload is likely not active.\n` +
                     `Check that bunfig.toml has a top-level preload (not under [run]) and mdxPlugin() is registered.`);
             }
-            const isCompute = kind === "compute" && typeof raw.__smithersComputeFn === "function";
-            const computeFn = isCompute ? raw.__smithersComputeFn : undefined;
+            const isCompute = (kind === "compute" || kind === "human") && typeof raw.__smithersComputeFn === "function";
+            const computeFn = isCompute ? /** @type {() => unknown} */ (raw.__smithersComputeFn) : undefined;
             const staticPayload = isAgent || isCompute
                 ? undefined
                 : (raw.__smithersPayload ?? raw.__payload ?? raw.children);
@@ -811,17 +839,23 @@ export function extractFromHost(root, opts) {
                 continueOnFail,
                 cachePolicy,
                 hijack: Boolean(raw.hijack),
-                onHijackExit: raw.onHijackExit === "reopen" ? "reopen" : "complete",
+                onHijackExit: /** @type {"reopen" | "complete"} */ (raw.onHijackExit === "reopen" ? "reopen" : "complete"),
                 agent,
                 prompt,
                 staticPayload,
                 computeFn,
-                label: raw.label,
-                meta: raw.meta,
-                scorers: raw.scorers,
+                label: typeof raw.label === "string" ? raw.label : undefined,
+                meta: raw.meta && typeof raw.meta === "object" && !Array.isArray(raw.meta)
+                    ? /** @type {Record<string, unknown>} */ (raw.meta)
+                    : undefined,
+                scorers: raw.scorers && typeof raw.scorers === "object" && !Array.isArray(raw.scorers)
+                    ? /** @type {import("../ScorersMap.ts").ScorersMap} */ (raw.scorers)
+                    : undefined,
                 parallelGroupId: parallelGroup?.id,
                 parallelMaxConcurrency: parallelGroup?.max,
-                memoryConfig: raw.memory ?? undefined,
+                memoryConfig: raw.memory && typeof raw.memory === "object" && !Array.isArray(raw.memory)
+                    ? /** @type {TaskDescriptor["memoryConfig"]} */ (raw.memory)
+                    : undefined,
             };
             // Worktree path is captured in typed fields (worktreeId/worktreePath) and
             // consumed by the engine; avoid attaching untyped ad-hoc properties.

package/src/extract.js

@@ -2,14 +2,12 @@ import { getTableName } from "drizzle-orm";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { validateForkSources } from "./validateForkSources.js";
 import { resolveWorktreePath } from "./worktree-path.js";
+import { DEFAULT_MERGE_QUEUE_CONCURRENCY, WORKTREE_EMPTY_PATH_ERROR } from "./constants.js";
 /** @typedef {import("./TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
 /** @typedef {import("./XmlNode.ts").XmlNode} XmlNode */
 /** @typedef {import("./ExtractOptions.ts").ExtractOptions} ExtractOptions */
 /** @typedef {import("./HostNode.ts").HostNode} HostNode */
 /** @typedef {import("./WorkflowGraph.ts").WorkflowGraph} WorkflowGraph */
-
-const DEFAULT_MERGE_QUEUE_CONCURRENCY = 1;
-const WORKTREE_EMPTY_PATH_ERROR = "<Worktree> requires a non-empty path prop";
 // Default per-task heartbeat timeout. 10 min is the floor for agent-backed
 // tasks: LLM CLIs (claude, codex, gemini, kimi) can sit silent for several
 // minutes during long deliberation or large-context reads. The previous
@@ -60,13 +58,13 @@ function isZodObject(value) {
 }
 /**
  * @param {unknown} value
- * @returns {boolean}
+ * @returns {value is any}
  */
 function isDrizzleTable(value) {
     if (!value || typeof value !== "object")
         return false;
     try {
-        const name = getTableName(value);
+        const name = getTableName(/** @type {any} */ (value));
         return typeof name === "string" && name.length > 0;
     }
     catch {
@@ -89,7 +87,7 @@ function resolveOutput(raw) {
     }
     const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
     const outputTableName = outputTable
-        ? getTableName(outputTable)
+        ? getTableName(/** @type {any} */ (outputTable))
         : typeof outputRaw === "string"
             ? outputRaw
             : "";
@@ -119,6 +117,8 @@ function parseHeartbeatTimeoutMs(raw) {
 }
 /**
  * @param {Record<string, unknown>} raw
+ * @param {boolean} [isAgent]
+ * @returns {{ retries: number; retryPolicy: import("./RetryPolicy.ts").RetryPolicy | undefined }}
  */
 function resolveRetryConfig(raw, isAgent = false) {
     const noRetry = Boolean(raw.noRetry);
@@ -135,12 +135,12 @@ function resolveRetryConfig(raw, isAgent = false) {
         : defaultNoRetryForContinueOnFail
             ? (isAgent ? 1 : 0)
             : hasExplicitRetries
-                ? raw.retries
+                ? /** @type {number} */ (raw.retries)
                 : Infinity;
     const retryPolicy = hasExplicitRetryPolicy
-        ? raw.retryPolicy
+        ? /** @type {import("./RetryPolicy.ts").RetryPolicy} */ (raw.retryPolicy)
         : retries > 0
-            ? { backoff: "exponential", initialDelayMs: 1000 }
+            ? /** @type {import("./RetryPolicy.ts").RetryPolicy} */ ({ backoff: "exponential", initialDelayMs: 1000 })
             : undefined;
     return { retries, retryPolicy };
 }
@@ -153,7 +153,7 @@ function toXmlNode(node) {
         return { kind: "text", text: node.text };
     }
     const element = {
-        kind: "element",
+        kind: /** @type {"element"} */ ("element"),
         tag: node.tag,
         props: node.props ?? {},
         children: node.children.map(toXmlNode),
@@ -173,7 +173,7 @@ function getRalphIteration(opts, id) {
     if (map instanceof Map) {
         return map.get(id) ?? fallback;
     }
-    const value = map[id];
+    const value = /** @type {Record<string, number>} */ (map)[id];
     return typeof value === "number" ? value : fallback;
 }
 /**
@@ -236,7 +236,7 @@ function approvalAutoApprove(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return undefined;
     }
-    const raw = value;
+    const raw = /** @type {Record<string, unknown>} */ (value);
     return {
         ...(typeof raw.after === "number" ? { after: raw.after } : {}),
         ...(typeof raw.audit === "boolean" ? { audit: raw.audit } : {}),
@@ -343,7 +343,9 @@ export function extractGraph(root, opts) {
     if (!root) {
         return { xml: null, tasks: [], mountedTaskIds: [] };
     }
+    /** @type {TaskDescriptor[]} */
     const tasks = [];
+    /** @type {string[]} */
     const mountedTaskIds = [];
     const seen = new Set();
     const seenRalph = new Set();
@@ -451,7 +453,7 @@ export function extractGraph(root, opts) {
                     heartbeatTimeoutMs: parseHeartbeatTimeoutMs(raw),
                     continueOnFail: Boolean(raw.continueOnFail),
                     cachePolicy: raw.cache && typeof raw.cache === "object"
-                        ? raw.cache
+                        ? /** @type {import("./CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
                         : undefined,
                     label: typeof raw.label === "string" ? raw.label : undefined,
                     meta: {
@@ -484,7 +486,7 @@ export function extractGraph(root, opts) {
                 heartbeatTimeoutMs: parseHeartbeatTimeoutMs(raw) ?? DEFAULT_SANDBOX_TASK_HEARTBEAT_TIMEOUT_MS,
                 continueOnFail: Boolean(raw.continueOnFail),
                 cachePolicy: raw.cache && typeof raw.cache === "object"
-                    ? raw.cache
+                    ? /** @type {import("./CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
                     : undefined,
                 label: typeof raw.label === "string" ? raw.label : undefined,
                 meta: {
@@ -622,7 +624,7 @@ export function extractGraph(root, opts) {
             const kind = raw.__smithersKind;
             const isAgent = kind === "agent" || Boolean(raw.agent);
             const { retries, retryPolicy } = resolveRetryConfig(raw, isAgent);
-            const isCompute = kind === "compute" && typeof raw.__smithersComputeFn === "function";
+            const isCompute = (kind === "compute" || kind === "human") && typeof raw.__smithersComputeFn === "function";
             const parsedHeartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw);
             const heartbeatTimeoutMs = parsedHeartbeatTimeoutMs ??
                 (isAgent ? DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS : null);
@@ -649,25 +651,27 @@ export function extractGraph(root, opts) {
                 heartbeatTimeoutMs,
                 continueOnFail: Boolean(raw.continueOnFail),
                 cachePolicy: raw.cache && typeof raw.cache === "object"
-                    ? raw.cache
+                    ? /** @type {import("./CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
                     : undefined,
                 hijack: Boolean(raw.hijack),
                 onHijackExit: raw.onHijackExit === "reopen" ? "reopen" : "complete",
-                agent: raw.agent,
+                agent: /** @type {TaskDescriptor["agent"]} */ (raw.agent),
                 prompt,
                 staticPayload: isAgent || isCompute
                     ? undefined
                     : (raw.__smithersPayload ?? raw.__payload ?? raw.children),
                 computeFn: isCompute
-                    ? raw.__smithersComputeFn
+                    ? /** @type {() => unknown} */ (raw.__smithersComputeFn)
                     : undefined,
                 label: typeof raw.label === "string" ? raw.label : undefined,
                 meta: raw.meta && typeof raw.meta === "object" && !Array.isArray(raw.meta)
-                    ? raw.meta
+                    ? /** @type {Record<string, unknown>} */ (raw.meta)
                     : undefined,
                 scorers: raw.scorers && typeof raw.scorers === "object" && !Array.isArray(raw.scorers)
-                    ? raw.scorers
+                    ? /** @type {import("./ScorersMap.ts").ScorersMap} */ (raw.scorers)
                     : undefined,
+                groundTruth: raw.groundTruth,
+                context: raw.context,
                 memoryConfig: raw.memory && typeof raw.memory === "object" && !Array.isArray(raw.memory)
                     ? raw.memory
                     : undefined,

package/src/index.d.ts

@@ -128,6 +128,8 @@ type TaskDescriptor$1 = {
     ralphId?: string;
     dependsOn?: string[];
     needs?: Record<string, string>;
+    /** Logical id of the task whose final agent session this task forks. Gates execution and seeds the session. */
+    forkSource?: string;
     worktreeId?: string;
     worktreePath?: string;
     worktreeBranch?: string;
@@ -167,6 +169,8 @@ type TaskDescriptor$1 = {
     label?: string;
     meta?: Record<string, unknown>;
     scorers?: ScorersMap$1;
+    groundTruth?: unknown;
+    context?: unknown;
     memoryConfig?: TaskMemoryConfig$1;
     aspects?: TaskAspects$1;
 };
@@ -204,13 +208,18 @@ declare function extractGraph(root: HostNode$1 | null, opts?: ExtractOptions$1):
 declare function extractFromHost(root: HostNode$1 | null, opts?: ExtractOptions$1): WorkflowGraph$1;
 /**
  * Resolve a <Worktree path> prop exactly the way graph extraction resolves it.
+ * Relative paths are resolved against the launch root (`--root`, the nearest
+ * `.smithers` anchor, or the operator cwd), never `dirname(workflowPath)`.
+ * `workflowPath` is threaded through graph/engine rendering for workflow
+ * identity and diagnostics only; it is not a worktree path resolution base.
  *
  * @param {unknown} path
- * @param {{ baseRootDir?: string }} [opts]
+ * @param {{ baseRootDir?: string; workflowPath?: string | null }} [opts]
  * @returns {string}
  */
 declare function resolveWorktreePath(path: unknown, opts?: {
     baseRootDir?: string;
+    workflowPath?: string | null;
 }): string;
 type ExtractOptions$1 = ExtractOptions$2;
 type HostNode$1 = HostNode$2;

package/src/index.js

@@ -22,6 +22,7 @@
 /** @typedef {import("./ScorerInput.ts").ScorerInput} ScorerInput */
 /** @typedef {import("./ScorersMap.ts").ScorersMap} ScorersMap */
 /** @typedef {import("./TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
+/** @typedef {import("./TaskAspects.ts").TaskAspects} TaskAspects */
 /** @typedef {import("./TaskMemoryConfig.ts").TaskMemoryConfig} TaskMemoryConfig */
 /** @typedef {import("./WorkflowGraph.ts").WorkflowGraph} WorkflowGraph */
 /** @typedef {import("./XmlElement.ts").XmlElement} XmlElement */

package/src/types.ts

@@ -191,6 +191,8 @@ export type TaskDescriptor = {
   label?: string;
   meta?: Record<string, unknown>;
   scorers?: ScorersMap;
+  groundTruth?: unknown;
+  context?: unknown;
 
   memoryConfig?: TaskMemoryConfig;
   /** Resolved `<Aspects>` budget configuration enforced by the engine at dispatch. */

package/src/validateForkSources.js

@@ -44,6 +44,10 @@ export function validateForkSources(tasks) {
     // fork edge. Used only for cycle detection.
     /** @type {Map<string, Set<string>>} */
     const adjacency = new Map();
+    /**
+     * @param {string} from
+     * @param {string} to
+     */
     const addEdge = (from, to) => {
         const cleanedFrom = logicalId(from);
         const cleanedTo = logicalId(to);

package/src/worktree-path.js

@@ -1,12 +1,16 @@
-import { isAbsolute, resolve } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { WORKTREE_EMPTY_PATH_ERROR } from "./constants.js";
 
 /**
  * Resolve a <Worktree path> prop exactly the way graph extraction resolves it.
+ * Relative paths are resolved against the launch root (`--root`, the nearest
+ * `.smithers` anchor, or the operator cwd), never `dirname(workflowPath)`.
+ * `workflowPath` is threaded through graph/engine rendering for workflow
+ * identity and diagnostics only; it is not a worktree path resolution base.
  *
  * @param {unknown} path
- * @param {{ baseRootDir?: string }} [opts]
+ * @param {{ baseRootDir?: string; workflowPath?: string | null }} [opts]
  * @returns {string}
  */
 export function resolveWorktreePath(path, opts) {
@@ -20,5 +24,43 @@ export function resolveWorktreePath(path, opts) {
     const base = typeof opts?.baseRootDir === "string" && opts.baseRootDir.length > 0
         ? opts.baseRootDir
         : process.cwd();
-    return resolve(base, pathVal);
+    const resolvedPath = resolve(base, pathVal);
+    warnRelativeWorktreePathOnce(pathVal, base, resolvedPath, opts?.workflowPath);
+    return resolvedPath;
+}
+
+let didWarnRelativeWorktreePath = false;
+
+/**
+ * Reset process-local relative worktree warning state for deterministic tests.
+ *
+ * @returns {void}
+ */
+export function resetRelativeWorktreePathWarningForTest() {
+    didWarnRelativeWorktreePath = false;
+}
+
+/**
+ * @param {string} pathVal
+ * @param {string} base
+ * @param {string} resolvedPath
+ * @param {string | null | undefined} workflowPath
+ * @returns {void}
+ */
+function warnRelativeWorktreePathOnce(pathVal, base, resolvedPath, workflowPath) {
+    if (didWarnRelativeWorktreePath) {
+        return;
+    }
+    didWarnRelativeWorktreePath = true;
+    const workflowDir = typeof workflowPath === "string" && workflowPath.length > 0
+        ? dirname(workflowPath)
+        : undefined;
+    console.warn("relative <Worktree path> resolved against launch root, not the workflow file directory", {
+        code: "WORKTREE_RELATIVE_PATH_BASE_ROOT",
+        path: pathVal,
+        base,
+        resolvedPath,
+        workflowPath,
+        workflowDir,
+    });
 }