taskflow-core 0.1.8 → 0.2.1

package/dist/schema.d.ts

@@ -5,6 +5,13 @@
  * to a subagent (an isolated `pi` process). Phases form a DAG via `dependsOn`.
  */
 import { Type, type Static } from "typebox";
+/** Closed set of native phase kinds — single source of truth for DSL + FlowIR. */
+export declare const PHASE_TYPES: readonly ["agent", "parallel", "map", "gate", "reduce", "approval", "flow", "loop", "tournament", "script", 
+/** First completed branch wins (Horizon B). */
+"race", 
+/** Dynamic sub-DAG: nested sub-flow or graft-promote into parent (Horizon B). */
+"expand"];
+export type PhaseType = (typeof PHASE_TYPES)[number];
 /** Loop iteration bounds. Authors may lower the max; the hard cap is a runaway guard. */
 export declare const LOOP_DEFAULT_MAX_ITERATIONS = 10;
 export declare const LOOP_HARD_MAX_ITERATIONS = 100;
@@ -25,6 +32,9 @@ export declare const TOURNAMENT_HARD_MAX_VARIANTS = 20;
 declare const TOURNAMENT_MODES: readonly ["best", "aggregate"];
 /** @internal */
 export type TournamentMode = (typeof TOURNAMENT_MODES)[number];
+/** Cross-host thinking levels and compatibility aliases accepted by authored flows. */
+export declare const THINKING_LEVELS: readonly ["off", "none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 declare const CACHE_SCOPES: readonly ["run-only", "cross-run", "off"];
 export type CacheScope = (typeof CACHE_SCOPES)[number];
 declare const ParallelTaskSchema: Type.TObject<{
@@ -54,7 +64,7 @@ declare const BudgetSchema: Type.TObject<{
 }>;
 declare const PhaseSchema: Type.TObject<{
     id: Type.TString;
-    type: Type.TOptional<Type.TUnsafe<"agent" | "approval" | "flow" | "gate" | "loop" | "map" | "parallel" | "reduce" | "script" | "tournament">>;
+    type: Type.TOptional<Type.TUnsafe<"agent" | "approval" | "expand" | "flow" | "gate" | "loop" | "map" | "parallel" | "race" | "reduce" | "script" | "tournament">>;
     agent: Type.TOptional<Type.TString>;
     task: Type.TOptional<Type.TString>;
     over: Type.TOptional<Type.TString>;
@@ -63,9 +73,20 @@ declare const PhaseSchema: Type.TObject<{
         task: Type.TString;
         agent: Type.TOptional<Type.TString>;
     }>>>;
+    /**
+     * [race] When true (default), abort in-flight loser branches after the first branch
+     * **succeeds** (best-effort `AbortSignal`). Race semantics are first-**success**
+     * (failed settles do not win). Set `false` to let losers run to natural completion.
+     */
+    cancelLosers: Type.TOptional<Type.TBoolean>;
     from: Type.TOptional<Type.TArray<Type.TString>>;
     use: Type.TOptional<Type.TString>;
+    /** [expand] Fragment source — string interpolation or inline Taskflow / phases (same as flow.def). */
     def: Type.TOptional<Type.TUnknown>;
+    /** [expand] nested (default) = isolated sub-flow; graft = run fragment then promote phase states onto the parent under prefixed ids. */
+    expandMode: Type.TOptional<Type.TUnsafe<"graft" | "nested">>;
+    /** [expand] Max nodes accepted from a dynamic fragment (default 50, hard 100). */
+    maxNodes: Type.TOptional<Type.TNumber>;
     with: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
     run: Type.TOptional<Type.TUnion<[Type.TString, Type.TArray<Type.TString>]>>;
     input: Type.TOptional<Type.TString>;
@@ -89,7 +110,7 @@ declare const PhaseSchema: Type.TObject<{
     output: Type.TOptional<Type.TUnsafe<"json" | "text">>;
     expect: Type.TOptional<Type.TUnknown>;
     model: Type.TOptional<Type.TString>;
-    thinking: Type.TOptional<Type.TString>;
+    thinking: Type.TOptional<Type.TUnsafe<"high" | "low" | "max" | "medium" | "minimal" | "none" | "off" | "ultra" | "xhigh">>;
     tools: Type.TOptional<Type.TArray<Type.TString>>;
     cwd: Type.TOptional<Type.TString>;
     final: Type.TOptional<Type.TBoolean>;
@@ -108,20 +129,78 @@ declare const PhaseSchema: Type.TObject<{
     }>>;
     shareContext: Type.TOptional<Type.TBoolean>;
 }>;
-declare const ArgSpecSchema: Type.TObject<{
+declare const ArgSpecSchema: Type.TUnion<[Type.TObject<{
+    type: Type.TOptional<Type.TNever>;
     default: Type.TOptional<Type.TUnknown>;
     description: Type.TOptional<Type.TString>;
     required: Type.TOptional<Type.TBoolean>;
-}>;
+}>, Type.TObject<{
+    type: Type.TLiteral<"string">;
+    default: Type.TOptional<Type.TString>;
+    description: Type.TOptional<Type.TString>;
+    required: Type.TOptional<Type.TBoolean>;
+}>, Type.TObject<{
+    type: Type.TLiteral<"relative-path">;
+    default: Type.TOptional<Type.TString>;
+    description: Type.TOptional<Type.TString>;
+    required: Type.TOptional<Type.TBoolean>;
+}>, Type.TObject<{
+    type: Type.TLiteral<"number">;
+    default: Type.TOptional<Type.TNumber>;
+    minimum: Type.TOptional<Type.TNumber>;
+    maximum: Type.TOptional<Type.TNumber>;
+    description: Type.TOptional<Type.TString>;
+    required: Type.TOptional<Type.TBoolean>;
+}>, Type.TObject<{
+    type: Type.TLiteral<"boolean">;
+    default: Type.TOptional<Type.TBoolean>;
+    description: Type.TOptional<Type.TString>;
+    required: Type.TOptional<Type.TBoolean>;
+}>, Type.TObject<{
+    type: Type.TLiteral<"enum">;
+    values: Type.TArray<Type.TUnion<[Type.TString, Type.TNumber]>>;
+    default: Type.TOptional<Type.TUnion<[Type.TString, Type.TNumber]>>;
+    description: Type.TOptional<Type.TString>;
+    required: Type.TOptional<Type.TBoolean>;
+}>]>;
 export declare const TaskflowSchema: Type.TObject<{
     name: Type.TString;
     description: Type.TOptional<Type.TString>;
     version: Type.TOptional<Type.TNumber>;
-    args: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
+    args: Type.TOptional<Type.TRecord<"^.*$", Type.TUnion<[Type.TObject<{
+        type: Type.TOptional<Type.TNever>;
         default: Type.TOptional<Type.TUnknown>;
         description: Type.TOptional<Type.TString>;
         required: Type.TOptional<Type.TBoolean>;
-    }>>>;
+    }>, Type.TObject<{
+        type: Type.TLiteral<"string">;
+        default: Type.TOptional<Type.TString>;
+        description: Type.TOptional<Type.TString>;
+        required: Type.TOptional<Type.TBoolean>;
+    }>, Type.TObject<{
+        type: Type.TLiteral<"relative-path">;
+        default: Type.TOptional<Type.TString>;
+        description: Type.TOptional<Type.TString>;
+        required: Type.TOptional<Type.TBoolean>;
+    }>, Type.TObject<{
+        type: Type.TLiteral<"number">;
+        default: Type.TOptional<Type.TNumber>;
+        minimum: Type.TOptional<Type.TNumber>;
+        maximum: Type.TOptional<Type.TNumber>;
+        description: Type.TOptional<Type.TString>;
+        required: Type.TOptional<Type.TBoolean>;
+    }>, Type.TObject<{
+        type: Type.TLiteral<"boolean">;
+        default: Type.TOptional<Type.TBoolean>;
+        description: Type.TOptional<Type.TString>;
+        required: Type.TOptional<Type.TBoolean>;
+    }>, Type.TObject<{
+        type: Type.TLiteral<"enum">;
+        values: Type.TArray<Type.TUnion<[Type.TString, Type.TNumber]>>;
+        default: Type.TOptional<Type.TUnion<[Type.TString, Type.TNumber]>>;
+        description: Type.TOptional<Type.TString>;
+        required: Type.TOptional<Type.TBoolean>;
+    }>]>>>;
     concurrency: Type.TOptional<Type.TNumber>;
     budget: Type.TOptional<Type.TObject<{
         maxUSD: Type.TOptional<Type.TNumber>;
@@ -133,7 +212,7 @@ export declare const TaskflowSchema: Type.TObject<{
     incremental: Type.TOptional<Type.TBoolean>;
     phases: Type.TArray<Type.TObject<{
         id: Type.TString;
-        type: Type.TOptional<Type.TUnsafe<"agent" | "approval" | "flow" | "gate" | "loop" | "map" | "parallel" | "reduce" | "script" | "tournament">>;
+        type: Type.TOptional<Type.TUnsafe<"agent" | "approval" | "expand" | "flow" | "gate" | "loop" | "map" | "parallel" | "race" | "reduce" | "script" | "tournament">>;
         agent: Type.TOptional<Type.TString>;
         task: Type.TOptional<Type.TString>;
         over: Type.TOptional<Type.TString>;
@@ -142,9 +221,20 @@ export declare const TaskflowSchema: Type.TObject<{
             task: Type.TString;
             agent: Type.TOptional<Type.TString>;
         }>>>;
+        /**
+         * [race] When true (default), abort in-flight loser branches after the first branch
+         * **succeeds** (best-effort `AbortSignal`). Race semantics are first-**success**
+         * (failed settles do not win). Set `false` to let losers run to natural completion.
+         */
+        cancelLosers: Type.TOptional<Type.TBoolean>;
         from: Type.TOptional<Type.TArray<Type.TString>>;
         use: Type.TOptional<Type.TString>;
+        /** [expand] Fragment source — string interpolation or inline Taskflow / phases (same as flow.def). */
         def: Type.TOptional<Type.TUnknown>;
+        /** [expand] nested (default) = isolated sub-flow; graft = run fragment then promote phase states onto the parent under prefixed ids. */
+        expandMode: Type.TOptional<Type.TUnsafe<"graft" | "nested">>;
+        /** [expand] Max nodes accepted from a dynamic fragment (default 50, hard 100). */
+        maxNodes: Type.TOptional<Type.TNumber>;
         with: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
         run: Type.TOptional<Type.TUnion<[Type.TString, Type.TArray<Type.TString>]>>;
         input: Type.TOptional<Type.TString>;
@@ -168,7 +258,7 @@ export declare const TaskflowSchema: Type.TObject<{
         output: Type.TOptional<Type.TUnsafe<"json" | "text">>;
         expect: Type.TOptional<Type.TUnknown>;
         model: Type.TOptional<Type.TString>;
-        thinking: Type.TOptional<Type.TString>;
+        thinking: Type.TOptional<Type.TUnsafe<"high" | "low" | "max" | "medium" | "minimal" | "none" | "off" | "ultra" | "xhigh">>;
         tools: Type.TOptional<Type.TArray<Type.TString>>;
         cwd: Type.TOptional<Type.TString>;
         final: Type.TOptional<Type.TBoolean>;
@@ -234,9 +324,14 @@ export interface ValidationOptions {
     strict?: boolean;
     /** When true, this flow is a runtime-generated (`flow { def }`) sub-flow whose
      *  content is LLM-authored / untrusted. Enables hardening checks: breadth caps
-     *  (phase count, map items, concurrency) and cwd containment under `cwd`. */
+     *  (phase count, map items, concurrency) and denial of cwd/context/script
+     *  resource capabilities until a FileBroker/sandbox exists. */
     dynamic?: boolean;
 }
+/** Validate resolved invocation values independently of full flow structure.
+ * Runtime calls this at the Core boundary so direct, resume, and detached
+ * execution cannot bypass adapter-level typed-arg checks. */
+export declare function validateInvocationArgs(def: Pick<Taskflow, "args">, args: Record<string, unknown>): string[];
 export declare function validateTaskflow(def: unknown, opts?: ValidationOptions): ValidationResult;
 export declare function collectRefs(phase: Phase): {
     steps: string[];

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema.js

@@ -9,11 +9,28 @@ import { StringEnum } from "./typebox-helpers.js";
 import { contractShapeErrors } from "./contract.js";
 import { scorerShapeErrors } from "./scorers.js";
 import { Type } from "typebox";
-import { WORKSPACE_KEYWORDS } from "./workspace.js";
+import { Errors as SchemaErrors } from "typebox/value";
+import { cwdArgName, hasCwdPlaceholder, normalizeRelativePath } from "./cwd-bridge.js";
 // ---------------------------------------------------------------------------
 // Phase types
 // ---------------------------------------------------------------------------
-const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow", "loop", "tournament", "script"];
+/** Closed set of native phase kinds — single source of truth for DSL + FlowIR. */
+export const PHASE_TYPES = [
+    "agent",
+    "parallel",
+    "map",
+    "gate",
+    "reduce",
+    "approval",
+    "flow",
+    "loop",
+    "tournament",
+    "script",
+    /** First completed branch wins (Horizon B). */
+    "race",
+    /** Dynamic sub-DAG: nested sub-flow or graft-promote into parent (Horizon B). */
+    "expand",
+];
 /** Loop iteration bounds. Authors may lower the max; the hard cap is a runaway guard. */
 export const LOOP_DEFAULT_MAX_ITERATIONS = 10;
 export const LOOP_HARD_MAX_ITERATIONS = 100;
@@ -34,13 +51,13 @@ export const TOURNAMENT_HARD_MAX_VARIANTS = 20;
 const TOURNAMENT_MODES = ["best", "aggregate"];
 const OUTPUT_FORMATS = ["text", "json"];
 const JOIN_MODES = ["all", "any"];
+/** Cross-host thinking levels and compatibility aliases accepted by authored flows. */
+export const THINKING_LEVELS = ["off", "none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
 const CACHE_SCOPES = ["run-only", "cross-run", "off"];
 /** Allowed fingerprint entry prefixes. `glob!:` = content-hash variant of `glob:`. */
 const CACHE_FINGERPRINT_PREFIXES = ["git:", "glob:", "glob!:", "file:", "env:"];
 /** Phase types that must NOT be cached across runs (a fresh result is required each run). */
-const CACHE_CROSS_RUN_BLOCKED_TYPES = ["gate", "approval", "loop", "tournament", "script"];
-/** `cwd` is a literal path / workspace keyword, not an interpolated field. */
-const CWD_PLACEHOLDER_RE = /\{[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*\}/;
+const CACHE_CROSS_RUN_BLOCKED_TYPES = ["gate", "approval", "loop", "tournament", "script", "race", "expand"];
 const ParallelTaskSchema = Type.Object({
     task: Type.String({ description: "Task for this parallel branch (supports interpolation)" }),
     agent: Type.Optional(Type.String({ description: "Override the phase agent for this branch" })),
@@ -70,9 +87,9 @@ const CacheSchema = Type.Object({
 }, { additionalProperties: false });
 /** Run-wide cost / token ceiling. Exceeding it halts the run (remaining phases skipped). */
 const BudgetSchema = Type.Object({
-    maxUSD: Type.Optional(Type.Number({ description: "Halt the run once accumulated cost exceeds this many USD" })),
-    maxTokens: Type.Optional(Type.Number({ description: "Halt the run once accumulated input+output tokens exceed this" })),
-}, { additionalProperties: false });
+    maxUSD: Type.Optional(Type.Number({ minimum: 0, description: "Halt the run once accumulated cost exceeds this many USD" })),
+    maxTokens: Type.Optional(Type.Number({ minimum: 0, description: "Halt the run once accumulated input+output tokens exceed this" })),
+}, { additionalProperties: false, minProperties: 1 });
 const PhaseSchema = Type.Object({
     id: Type.String({ description: "Unique phase identifier (referenced via {steps.<id>.output})" }),
     type: Type.Optional(StringEnum(PHASE_TYPES, { description: "Phase kind", default: "agent" })),
@@ -81,15 +98,32 @@ const PhaseSchema = Type.Object({
     // map fan-out
     over: Type.Optional(Type.String({ description: "[map] Interpolation ref resolving to an array to fan out over" })),
     as: Type.Optional(Type.String({ description: "[map] Loop variable name (default: item)", default: "item" })),
-    // parallel static branches
-    branches: Type.Optional(Type.Array(ParallelTaskSchema, { description: "[parallel] Static task branches" })),
+    // parallel / race static branches
+    branches: Type.Optional(Type.Array(ParallelTaskSchema, {
+        description: "[parallel|race|tournament] Static task branches",
+    })),
+    /**
+     * [race] When true (default), abort in-flight loser branches after the first branch
+     * **succeeds** (best-effort `AbortSignal`). Race semantics are first-**success**
+     * (failed settles do not win). Set `false` to let losers run to natural completion.
+     */
+    cancelLosers: Type.Optional(Type.Boolean({ default: true })),
     // reduce
     from: Type.Optional(Type.Array(Type.String(), { description: "[reduce] Phase ids whose outputs are aggregated" })),
-    // sub-workflow (flow)
+    // sub-workflow (flow) + expand fragment
     use: Type.Optional(Type.String({ description: "[flow] Name of a saved taskflow to run as this phase" })),
+    /** [expand] Fragment source — string interpolation or inline Taskflow / phases (same as flow.def). */
+    // reuses `def` below for expand as well
     def: Type.Optional(Type.Unknown({
-        description: "[flow] Inline sub-flow definition, resolved at runtime. Mutually exclusive with 'use'. A string is interpolated (e.g. '{steps.plan.json}') then JSON-parsed; an object is used directly. The result must be a Taskflow ({name,phases}) or a bare phases array / {phases:[...]} (auto-wrapped). Validated + verified before execution; on any failure the phase fails-open (defError) without aborting the run.",
+        description: "[flow|expand] Inline sub-flow / fragment definition, resolved at runtime. Mutually exclusive with 'use' on flow. A string is interpolated (e.g. '{steps.plan.json}') then JSON-parsed; an object is used directly. The result must be a Taskflow ({name,phases}) or a bare phases array / {phases:[...]} (auto-wrapped). Validated + verified before execution; on any failure the phase fails-open (defError) without aborting the run.",
     })),
+    /** [expand] nested (default) = isolated sub-flow; graft = run fragment then promote phase states onto the parent under prefixed ids. */
+    expandMode: Type.Optional(StringEnum(["nested", "graft"], {
+        description: "[expand] nested (default) | graft (promote child phase states onto parent)",
+        default: "nested",
+    })),
+    /** [expand] Max nodes accepted from a dynamic fragment (default 50, hard 100). */
+    maxNodes: Type.Optional(Type.Number({ default: 50 })),
     with: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
         description: "[flow] Args passed to the sub-flow (string values support interpolation)",
     })),
@@ -146,9 +180,11 @@ const PhaseSchema = Type.Object({
         description: "Output contract for this phase's JSON output (requires output:'json'). A small JSON-Schema-like shape: {type, properties, required, items, enum}. Validated the moment the subagent finishes; a violation fails the phase with a precise diagnostic (eligible for the phase's explicit 'retry'). Valid for agent/gate/reduce/loop phases.",
     })),
     model: Type.Optional(Type.String({ description: "Model override for this phase" })),
-    thinking: Type.Optional(Type.String({ description: "Thinking level override for this phase" })),
+    thinking: Type.Optional(StringEnum(THINKING_LEVELS, {
+        description: "Thinking level override for this phase. Unknown values are rejected instead of silently inheriting the host default.",
+    })),
     tools: Type.Optional(Type.Array(Type.String(), { description: "Restrict tools for this phase's agent" })),
-    cwd: Type.Optional(Type.String({ description: "Working directory for this phase's subagent. A literal path, or a reserved keyword: 'temp' (ephemeral dir, removed after the phase), 'dedicated' (persistent dir under the run state, kept), or 'worktree' (a git worktree on a throwaway branch, removed after the phase)." })),
+    cwd: Type.Optional(Type.String({ description: "Working directory for this phase. Accepts a literal path; a reserved keyword ('temp', 'dedicated', 'worktree'); or the exact whole placeholder {args.X} when X is declared type:'relative-path'. The 0.2.1 argument bridge requires an explicit host resolve-only opt-in." })),
     final: Type.Optional(Type.Boolean({ description: "Mark this phase's output as the workflow result" })),
     optional: Type.Optional(Type.Boolean({ description: "If true, a failure does not abort the run", default: false })),
     idempotent: Type.Optional(Type.Boolean({
@@ -178,11 +214,53 @@ const PhaseSchema = Type.Object({
         description: "Opt into the Shared Context Tree for this phase: the subagent gets ctx_read/ctx_write (a blackboard shared with siblings/ancestors, to avoid re-reading files) and ctx_report/ctx_spawn (report upward + queue child tasks the runtime picks up). Default false — existing flows are unaffected.",
     })),
 }, { additionalProperties: false });
-const ArgSpecSchema = Type.Object({
+const LegacyArgSpecSchema = Type.Object({
+    type: Type.Optional(Type.Never()),
     default: Type.Optional(Type.Unknown()),
     description: Type.Optional(Type.String()),
     required: Type.Optional(Type.Boolean()),
 }, { additionalProperties: false });
+const StringArgSpecSchema = Type.Object({
+    type: Type.Literal("string"),
+    default: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const RelativePathArgSpecSchema = Type.Object({
+    type: Type.Literal("relative-path"),
+    default: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const NumberArgSpecSchema = Type.Object({
+    type: Type.Literal("number"),
+    default: Type.Optional(Type.Number()),
+    minimum: Type.Optional(Type.Number()),
+    maximum: Type.Optional(Type.Number()),
+    description: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const BooleanArgSpecSchema = Type.Object({
+    type: Type.Literal("boolean"),
+    default: Type.Optional(Type.Boolean()),
+    description: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const EnumArgSpecSchema = Type.Object({
+    type: Type.Literal("enum"),
+    values: Type.Array(Type.Union([Type.String(), Type.Number()]), { minItems: 1 }),
+    default: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+    description: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const ArgSpecSchema = Type.Union([
+    LegacyArgSpecSchema,
+    StringArgSpecSchema,
+    RelativePathArgSpecSchema,
+    NumberArgSpecSchema,
+    BooleanArgSpecSchema,
+    EnumArgSpecSchema,
+]);
 export const TaskflowSchema = Type.Object({
     name: Type.String({ minLength: 1, description: "Workflow name (becomes /tf:<name> command when saved)" }),
     description: Type.Optional(Type.String()),
@@ -332,6 +410,58 @@ export function parseTtlMs(ttl) {
     const mult = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
     return n * mult[unit];
 }
+function typedArgValueErrors(name, spec, value, source) {
+    const prefix = `Argument '${name}' ${source}`;
+    if (spec.type === "relative-path") {
+        const r = normalizeRelativePath(value);
+        return r.ok ? [] : [`${prefix} ${r.message}`];
+    }
+    if (spec.type === "string") {
+        if (typeof value !== "string")
+            return [`${prefix} must be a string, got ${value === null ? "null" : typeof value}`];
+        return [];
+    }
+    if (spec.type === "number") {
+        if (typeof value !== "number" || !Number.isFinite(value))
+            return [`${prefix} must be a finite number`];
+        if (spec.minimum !== undefined && value < spec.minimum)
+            return [`${prefix} must be >= ${spec.minimum}`];
+        if (spec.maximum !== undefined && value > spec.maximum)
+            return [`${prefix} must be <= ${spec.maximum}`];
+        return [];
+    }
+    if (spec.type === "boolean") {
+        return typeof value === "boolean" ? [] : [`${prefix} must be a boolean, got ${value === null ? "null" : typeof value}`];
+    }
+    if (spec.type === "enum") {
+        const values = Array.isArray(spec.values) ? spec.values : [];
+        return values.some((v) => Object.is(v, value)) ? [] : [`${prefix} must be one of ${JSON.stringify(values)}`];
+    }
+    return [];
+}
+/** Validate resolved invocation values independently of full flow structure.
+ * Runtime calls this at the Core boundary so direct, resume, and detached
+ * execution cannot bypass adapter-level typed-arg checks. */
+export function validateInvocationArgs(def, args) {
+    const errors = [];
+    const specs = (def.args ?? {});
+    for (const [name, spec] of Object.entries(specs)) {
+        // Full structural validation owns malformed specs. Keep this boundary
+        // total so validateTaskflow() reports SchemaErrors instead of throwing
+        // while it performs the optional invocation-value pass.
+        if (typeof spec !== "object" || spec === null || Array.isArray(spec))
+            continue;
+        const typedSpec = spec;
+        if (!(name in args)) {
+            if (typedSpec.type !== undefined && typedSpec.required === true && typedSpec.default === undefined)
+                errors.push(`Missing required argument '${name}'`);
+            continue;
+        }
+        if (typedSpec.type !== undefined)
+            errors.push(...typedArgValueErrors(name, typedSpec, args[name], "invocation"));
+    }
+    return errors;
+}
 export function validateTaskflow(def, opts = {}) {
     const errors = [];
     const warnings = [];
@@ -340,12 +470,60 @@ export function validateTaskflow(def, opts = {}) {
     }
     const flow = def;
     const strict = opts.strict ?? flow.strictInterpolation === true;
+    for (const issue of SchemaErrors(TaskflowSchema, def)) {
+        const pathLabel = issue.instancePath || "/";
+        const extras = issue.params && "additionalProperties" in issue.params
+            ? issue.params.additionalProperties
+            : undefined;
+        if (Array.isArray(extras) && extras.length > 0) {
+            for (const key of extras)
+                errors.push(`${pathLabel}: unknown field '${String(key)}'`);
+        }
+        else {
+            errors.push(`${pathLabel}: ${issue.message}`);
+        }
+    }
     if (!flow.name || typeof flow.name !== "string")
         errors.push("Missing or invalid 'name'");
     if (!Array.isArray(flow.phases) || flow.phases.length === 0) {
         errors.push("Taskflow must have at least one phase");
         return { ok: false, errors, warnings };
     }
+    // Typed invocation args are the trust boundary for resource selectors. Legacy
+    // specs remain valid for every flow version, but can never feed a cwd bridge.
+    // `version` is informational metadata, not a schema-version selector.
+    const argSpecs = (typeof flow.args === "object" && flow.args !== null && !Array.isArray(flow.args)
+        ? flow.args
+        : {});
+    for (const [name, spec] of Object.entries(argSpecs)) {
+        if (!spec || typeof spec !== "object" || Array.isArray(spec))
+            continue;
+        if (spec.type === "number" && spec.minimum !== undefined && spec.maximum !== undefined && spec.minimum > spec.maximum) {
+            errors.push(`Argument '${name}': minimum must be <= maximum`);
+        }
+        if (spec.type === "enum" && Array.isArray(spec.values) && new Set(spec.values.map((v) => `${typeof v}:${String(v)}`)).size !== spec.values.length) {
+            errors.push(`Argument '${name}': enum values must be unique`);
+        }
+        if (spec.default !== undefined && spec.type !== undefined) {
+            errors.push(...typedArgValueErrors(name, spec, spec.default, "default"));
+        }
+    }
+    if (opts.args !== undefined) {
+        errors.push(...validateInvocationArgs(flow, opts.args));
+        for (const [name, spec] of Object.entries(argSpecs)) {
+            if (!spec || typeof spec !== "object" || Array.isArray(spec))
+                continue;
+            if (spec.type === undefined && spec.required === true && spec.default === undefined && !(name in opts.args)) {
+                warnings.push(`Legacy untyped argument '${name}' is marked required but remains advisory; add an explicit type to enforce it`);
+            }
+        }
+        for (const name of Object.keys(opts.args)) {
+            if (name in argSpecs)
+                continue;
+            if (strict)
+                warnings.push(`Invocation argument '${name}' is undeclared`);
+        }
+    }
     // Hardening for runtime-generated (untrusted) sub-flows: bound breadth and
     // contain filesystem access. These do NOT apply to authored/saved flows.
     if (opts.dynamic) {
@@ -355,10 +533,12 @@ export function validateTaskflow(def, opts = {}) {
         if (typeof flow.concurrency === "number" && flow.concurrency > MAX_DYNAMIC_CONCURRENCY) {
             errors.push(`Dynamic sub-flow concurrency too high (${flow.concurrency}, max ${MAX_DYNAMIC_CONCURRENCY})`);
         }
-        const root = opts.cwd ? path.resolve(opts.cwd) : undefined;
         for (const p of flow.phases) {
             if (!p || typeof p !== "object")
                 continue;
+            if (Array.isArray(p.context) && p.context.length > 0) {
+                errors.push(`Dynamic sub-flow phase '${p.id}': context file pre-reads are not allowed in generated flows`);
+            }
             // A generated phase may not execute shell commands. `script` runs an
             // arbitrary command — a strictly larger capability than the reserved
             // cwd keywords blocked below — so an LLM-authored plan (flow{def} /
@@ -393,20 +573,11 @@ export function validateTaskflow(def, opts = {}) {
             if (typeof p.concurrency === "number" && p.concurrency > MAX_DYNAMIC_CONCURRENCY) {
                 errors.push(`Dynamic sub-flow phase '${p.id}': concurrency too high (${p.concurrency}, max ${MAX_DYNAMIC_CONCURRENCY})`);
             }
-            // cwd containment: a generated phase may not escape the run's cwd, and
-            // may not request a reserved workspace keyword (temp/dedicated/worktree)
-            // — LLM-authored sub-flows must not allocate isolated dirs or git
-            // worktrees that mutate the repo. Only author-written flows may.
+            // W1a/FileBroker is not available yet, so a generated phase may not
+            // choose any cwd. Lexical containment is insufficient because symlinks
+            // and time-of-check/time-of-use races can cross the invocation boundary.
             if (typeof p.cwd === "string") {
-                if (WORKSPACE_KEYWORDS.includes(p.cwd)) {
-                    errors.push(`Dynamic sub-flow phase '${p.id}': cwd '${p.cwd}' is a reserved workspace keyword not allowed in generated flows`);
-                }
-                else if (root) {
-                    const resolved = path.resolve(root, p.cwd);
-                    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
-                        errors.push(`Dynamic sub-flow phase '${p.id}': cwd '${p.cwd}' escapes the run directory`);
-                    }
-                }
+                errors.push(`Dynamic sub-flow phase '${p.id}': cwd selection is not allowed in generated flows`);
             }
         }
     }
@@ -461,8 +632,30 @@ export function validateTaskflow(def, opts = {}) {
                 errors.push(`Phase '${p.id}': '${key}' must be a string, got ${typeof v}`);
             }
         }
-        if (typeof p.cwd === "string" && CWD_PLACEHOLDER_RE.test(p.cwd)) {
-            errors.push(`Phase '${p.id}': 'cwd' does not support interpolation placeholders (${p.cwd}). Use a literal path, or a reserved workspace keyword ('temp', 'dedicated', 'worktree').`);
+        if (typeof p.thinking === "string" &&
+            !THINKING_LEVELS.includes(p.thinking)) {
+            errors.push(`Phase '${p.id}': 'thinking' must be one of ${THINKING_LEVELS.join(", ")}; got '${p.thinking}'`);
+        }
+        if (typeof p.cwd === "string" && hasCwdPlaceholder(p.cwd)) {
+            const argName = cwdArgName(p.cwd);
+            if (!argName) {
+                errors.push(`Phase '${p.id}': dynamic 'cwd' must be exactly one whole {args.X} placeholder; concatenation, multiple placeholders, and {steps.*} are forbidden.`);
+            }
+            else {
+                const spec = argSpecs[argName];
+                if (!spec) {
+                    errors.push(`Phase '${p.id}': cwd references undeclared argument '${argName}'`);
+                }
+                else if (spec.type !== "relative-path") {
+                    errors.push(`Phase '${p.id}': cwd argument '${argName}' must be declared with type 'relative-path'`);
+                }
+                if (p.cache?.scope === "cross-run") {
+                    errors.push(`Phase '${p.id}': cwd selected by an argument cannot use cache.scope 'cross-run' until workspace state restoration is available.`);
+                }
+                if (p.retry && typeof p.retry.max === "number" && p.retry.max > 0) {
+                    errors.push(`Phase '${p.id}': cwd selected by an argument cannot use retry.max > 0 because a failed resolve-only write has an unknown filesystem outcome and must be reconciled before another attempt.`);
+                }
+            }
         }
         // dependsOn / from entries are string phase-id refs that flow into the graph
         // helpers and nodeId(); a non-string entry would crash the renderer.
@@ -535,7 +728,9 @@ export function validateTaskflow(def, opts = {}) {
                     warnings.push(`Phase '${p.id}' (gate): both 'eval' and 'score' are set — eval runs first (all-pass skips the gate entirely), then score. This is valid but usually one of the two suffices.`);
                 }
                 // Judge agent naming convention (mirrors the phase-agent check below).
-                const judgeAgent = scoreVal.judge?.agent;
+                const judgeAgent = scoreVal !== null && typeof scoreVal === "object"
+                    ? scoreVal.judge?.agent
+                    : undefined;
                 if (typeof judgeAgent === "string" && judgeAgent.includes("_")) {
                     errors.push(`Phase '${p.id}': score.judge.agent '${judgeAgent}' uses underscores — use hyphens`);
                 }
@@ -591,6 +786,27 @@ export function validateTaskflow(def, opts = {}) {
             if (!p.branches || p.branches.length === 0)
                 errors.push(`Phase '${p.id}' (parallel) requires non-empty 'branches'`);
         }
+        if (type === "race") {
+            if (!p.branches || p.branches.length === 0)
+                errors.push(`Phase '${p.id}' (race) requires non-empty 'branches'`);
+            else if (p.branches.length < 2)
+                errors.push(`Phase '${p.id}' (race): needs at least 2 branches`);
+            if (p.cancelLosers !== undefined && typeof p.cancelLosers !== "boolean") {
+                errors.push(`Phase '${p.id}' (race): cancelLosers must be a boolean`);
+            }
+        }
+        if (type === "expand") {
+            if (p.def === undefined)
+                errors.push(`Phase '${p.id}' (expand) requires 'def' (fragment Taskflow or {steps.X.json})`);
+            const em = p.expandMode;
+            if (em !== undefined && em !== "nested" && em !== "graft") {
+                errors.push(`Phase '${p.id}' (expand): expandMode must be 'nested' or 'graft'`);
+            }
+            const maxN = p.maxNodes;
+            if (maxN !== undefined && (typeof maxN !== "number" || maxN < 1 || maxN > MAX_DYNAMIC_PHASES)) {
+                errors.push(`Phase '${p.id}' (expand): maxNodes must be 1..${MAX_DYNAMIC_PHASES}`);
+            }
+        }
         if (type === "reduce") {
             if (!p.from || p.from.length === 0)
                 errors.push(`Phase '${p.id}' (reduce) requires 'from'`);
@@ -896,6 +1112,7 @@ export function collectRefs(phase) {
     scan(phase.over);
     scan(phase.when);
     scan(phase.until);
+    scan(phase.cwd);
     // Script phases: the array form of `run` supports {steps.X}/{args.X}
     // interpolation (the string form does NOT — it's a raw shell command,
     // validation rejects placeholders in it), and `input` (stdin) does too.