@tuned-tensor/cli 0.13.1-beta.1 → 0.13.1-beta.2

package/dist/index.js

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 import {
   TRAINING_MODELS,
+  assertFoundationSpecReady,
   assertLocalRunInputReady,
+  buildFoundationPythonCommand,
   loadLocalRunInput,
   loadLocalRunnerConfig,
-  runLocalPipeline
-} from "./chunk-YJYCGSHJ.js";
+  runLocalPipeline,
+  runLoggedProcess,
+  withFoundationPythonEnvironment
+} from "./chunk-2P2RL23O.js";
 
 // src/cli.ts
 import { spawn as spawn2 } from "child_process";
@@ -38,16 +42,18 @@ function validateSpec(spec) {
     passed: Boolean(spec.system_prompt?.trim()),
     message: spec.system_prompt?.trim() ? void 0 : "Spec is missing a system_prompt"
   });
+  const isFoundation = spec.engine === "foundation";
   checks.push({
-    name: "Has base model",
-    passed: Boolean(spec.base_model?.trim()),
-    message: spec.base_model?.trim() ? void 0 : "Spec is missing a base_model"
+    name: isFoundation ? "Has foundation engine" : "Has base model",
+    passed: isFoundation ? spec.foundation != null && typeof spec.foundation === "object" : Boolean(spec.base_model?.trim()),
+    message: isFoundation ? spec.foundation != null ? void 0 : "Foundation spec is missing a foundation block" : spec.base_model?.trim() ? void 0 : "Spec is missing a base_model"
   });
   const exCount = spec.examples?.length ?? 0;
+  const minExamples = isFoundation ? 2 : 1;
   checks.push({
     name: "Has examples",
-    passed: exCount > 0,
-    message: exCount > 0 ? `${exCount} example(s)` : "Add at least one example"
+    passed: exCount >= minExamples,
+    message: exCount >= minExamples ? `${exCount} example(s)` : isFoundation ? "Add at least two chat examples" : "Add at least one example"
   });
   checks.push({
     name: "Has guidelines",
@@ -666,14 +672,13 @@ function missingProviderAuthMessage() {
 function unknownAgentProviderMessage(provider) {
   return `Unknown provider "${provider}". Use /login <id> or /model <id>.`;
 }
-var MIN_REDACTED_SECRET_LENGTH = 8;
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function pushSecret(secrets, value) {
   if (typeof value !== "string") return;
   const secret = value.trim();
-  if (secret.length < MIN_REDACTED_SECRET_LENGTH) return;
+  if (!secret) return;
   if (!secrets.includes(secret)) secrets.push(secret);
 }
 function persistProviderApiKey(provider, apiKey, authPath = getAgentAuthPath()) {
@@ -914,7 +919,9 @@ import {
   PIPELINE_STEP_CAPABILITIES,
   PIPELINE_STEP_USES,
   PIPELINE_TARGETS,
+  canonicalFoundationPipeline as canonicalFoundationPipeline2,
   canonicalJson,
+  isFoundationPipeline,
   parsePipeline as parsePipeline2,
   pipelineDocumentSchema as pipelineDocumentSchema2,
   pipelineHash
@@ -922,8 +929,84 @@ import {
 function stepReferences(step) {
   if (step.uses === "evaluate") return step.with.model === "base" ? [] : [step.with.model];
   if (step.uses === "compare") return [step.with.before, step.with.after];
+  if (step.uses === "pretrain") return [step.with.tokenizer];
+  if (step.uses === "finetune" || step.uses === "rl") return [step.with.model];
   return [];
 }
+function pipelineFromFoundationHyperparameters(name, hp) {
+  const lastTrainId = hp.rl_steps > 0 ? "rl" : "sft";
+  const steps = [
+    {
+      id: "tokenize",
+      uses: "tokenize",
+      target: "local",
+      with: { vocabSize: hp.vocab_size, maxChars: hp.max_chars }
+    },
+    {
+      id: "pretrain",
+      uses: "pretrain",
+      target: "local",
+      with: {
+        tokenizer: { from: "tokenize.tokenizer" },
+        depth: hp.depth,
+        steps: hp.pretrain_steps,
+        batchSize: hp.batch_size,
+        sequenceLength: hp.sequence_length,
+        nprocPerNode: hp.nproc_per_node
+      }
+    },
+    {
+      id: "bpb",
+      uses: "evaluate",
+      target: "local",
+      with: { model: { from: "pretrain.model" }, evaluator: "bpb" }
+    },
+    {
+      id: "sft",
+      uses: "finetune",
+      target: "local",
+      with: {
+        model: { from: "pretrain.model" },
+        steps: hp.finetune_steps,
+        batchSize: hp.batch_size
+      }
+    },
+    {
+      id: "chat",
+      uses: "evaluate",
+      target: "local",
+      with: { model: { from: "sft.model" }, evaluator: "chat" }
+    }
+  ];
+  if (hp.rl_steps > 0) {
+    steps.push(
+      {
+        id: "rl",
+        uses: "rl",
+        target: "local",
+        with: { model: { from: "sft.model" }, steps: hp.rl_steps }
+      },
+      {
+        id: "chat_rl",
+        uses: "evaluate",
+        target: "local",
+        with: { model: { from: "rl.model" }, evaluator: "chat" }
+      }
+    );
+  }
+  steps.push({
+    id: "infer",
+    uses: "evaluate",
+    target: "local",
+    with: { model: { from: `${lastTrainId}.model` }, evaluator: "inference" }
+  });
+  return {
+    version: 1,
+    name,
+    runtime: { engine: "foundation" },
+    steps
+  };
+}
 function producerId(reference) {
   return reference.from.slice(0, reference.from.lastIndexOf("."));
 }
@@ -3617,7 +3700,9 @@ var CLOUD_SPEC_KEYS = [
 ];
 var LOCAL_ONLY_SPEC_KEYS = [
   "hyperparameters",
-  "dataset_prebuilt"
+  "dataset_prebuilt",
+  "engine",
+  "foundation"
 ];
 var LOCAL_SPEC_KEYS = [
   "id",
@@ -4739,16 +4824,342 @@ function registerAgentCommands(parent, options) {
 
 // src/commands/pipeline.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
-import { resolve as resolve4 } from "path";
+import { resolve as resolve5 } from "path";
+
+// src/local-runtime/foundation-runner.ts
+import { createHash as createHash2, randomUUID as randomUUID5 } from "crypto";
+import { createReadStream } from "fs";
+import { chmod as chmod2, lstat as lstat3, mkdir as mkdir3, open as open2, readdir as readdir3, readFile as readFile4 } from "fs/promises";
+import { dirname as dirname4, join as join7, resolve as resolve4 } from "path";
+function isRef(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value) && typeof value.from === "string";
+}
+function parseRef(value) {
+  const index = value.from.lastIndexOf(".");
+  if (index <= 0) throw new Error(`Invalid artifact reference: ${value.from}`);
+  return { stepId: value.from.slice(0, index), kind: value.from.slice(index + 1) };
+}
+async function hashPath(path) {
+  const info = await lstat3(path);
+  if (info.isSymbolicLink()) {
+    throw new Error(`Foundation artifacts must not contain symbolic links: ${path}`);
+  }
+  const hash = createHash2("sha256");
+  if (info.isDirectory()) {
+    for (const name of (await readdir3(path)).sort()) {
+      hash.update(name);
+      hash.update(await hashPath(join7(path, name)));
+    }
+    return hash.digest("hex");
+  }
+  if (!info.isFile()) {
+    throw new Error(`Foundation artifacts must contain only regular files and directories: ${path}`);
+  }
+  await new Promise((done, reject) => {
+    const stream = createReadStream(path);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", () => done());
+  });
+  return hash.digest("hex");
+}
+async function makePrivateTree(path) {
+  const info = await lstat3(path);
+  if (info.isSymbolicLink()) {
+    throw new Error(`Foundation artifacts must not contain symbolic links: ${path}`);
+  }
+  if (info.isDirectory()) {
+    await chmod2(path, 448);
+    for (const name of await readdir3(path)) {
+      await makePrivateTree(join7(path, name));
+    }
+    return;
+  }
+  if (info.isFile()) {
+    await chmod2(path, 384);
+    return;
+  }
+  throw new Error(`Foundation artifacts must contain only regular files and directories: ${path}`);
+}
+async function readRequiredJsonObject(path, description) {
+  let content;
+  try {
+    content = await readFile4(path, "utf8");
+  } catch (error) {
+    throw new Error(`${description} is missing or unreadable: ${path}`, { cause: error });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    throw new Error(`${description} is not valid JSON: ${path}`, { cause: error });
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${description} must be a JSON object: ${path}`);
+  }
+  return parsed;
+}
+async function writePrivateText(path, content) {
+  const file = await open2(path, "w", 384);
+  try {
+    await file.chmod(384);
+    await file.writeFile(content, "utf8");
+  } finally {
+    await file.close();
+  }
+}
+async function artifactFor(path) {
+  return { path, sha256: await hashPath(path) };
+}
+async function requireRegularNonemptyFile(path, description) {
+  let info;
+  try {
+    info = await lstat3(path);
+  } catch (error) {
+    throw new Error(`${description} is missing: ${path}`, { cause: error });
+  }
+  if (info.isSymbolicLink() || !info.isFile() || info.size === 0) {
+    throw new Error(`${description} must be a non-empty regular file: ${path}`);
+  }
+}
+function requirePositiveIntegerFields(value, fields, description) {
+  for (const field of fields) {
+    if (!Number.isInteger(value[field]) || Number(value[field]) <= 0) {
+      throw new Error(`${description}.${field} must be a positive integer.`);
+    }
+  }
+}
+function stepConfig(step) {
+  if (step.uses === "train") return {};
+  if (step.uses === "tokenize") return { ...step.with ?? {} };
+  return { ...step.with };
+}
+function assertFoundationPlanSupported(spec, plan) {
+  const supported = /* @__PURE__ */ new Set(["tokenize", "pretrain", "finetune", "rl", "evaluate"]);
+  const unsupported = plan.steps.find((step) => !supported.has(step.uses));
+  if (unsupported) {
+    throw new Error(
+      `Foundation runner does not implement ${unsupported.uses} (step ${unsupported.id}).`
+    );
+  }
+  if (plan.steps.some((step) => step.uses === "rl")) {
+    const invalidReward = spec.examples.findIndex(
+      (example) => !/-?\d+(?:\.\d+)?/.test(example.output.replaceAll(",", ""))
+    );
+    if (invalidReward >= 0) {
+      throw new Error(
+        `Foundation RL requires a numeric expected output for every example; examples[${invalidReward}].output has none.`
+      );
+    }
+  }
+  for (const step of plan.steps) {
+    if (step.uses !== "pretrain") continue;
+    const processCount = step.with.nprocPerNode ?? spec.foundation.nproc_per_node;
+    if (processCount !== 1) {
+      throw new Error(
+        `Foundation nproc_per_node is ${processCount}; only 1 is supported by the current single-process runtime.`
+      );
+    }
+  }
+}
+async function defaultFoundationSpawn(args2) {
+  const launched = buildFoundationPythonCommand(args2.entrypoint, ["--config", args2.configPath]);
+  const result2 = await runLoggedProcess({
+    command: launched.command,
+    commandArgs: launched.commandArgs,
+    env: withFoundationPythonEnvironment(process.env),
+    logPath: args2.logPath,
+    stage: args2.stepId
+  });
+  if (result2.exitCode !== 0) {
+    throw new Error(
+      `Foundation step "${args2.stepId}" failed (exit ${result2.exitCode}).${result2.stderr ? `
+${result2.stderr}` : ""}`
+    );
+  }
+}
+async function runFoundationPipeline(args2) {
+  assertFoundationPlanSupported(args2.spec, args2.plan);
+  const outputDir = resolve4(
+    args2.outputDir ?? join7(dirname4(resolve4(args2.specPath)), ".tt-foundation-runs", randomUUID5())
+  );
+  await mkdir3(outputDir, { recursive: true, mode: 448 });
+  await chmod2(outputDir, 448);
+  const spawnStep = args2.spawnStep ?? defaultFoundationSpawn;
+  const produced = /* @__PURE__ */ new Map();
+  const steps = [];
+  const examples = args2.spec.examples.map((example) => ({ input: example.input, output: example.output }));
+  const hp = args2.spec.foundation;
+  let tokenizerDir;
+  let modelDir;
+  const resolveKind = (stepId, kind) => {
+    const path = produced.get(stepId)?.[kind];
+    if (!path) throw new Error(`Step ${stepId} did not produce ${kind}.`);
+    return path;
+  };
+  const resolveFrom = (value, kind, fallback) => {
+    if (isRef(value)) return resolveKind(parseRef(value).stepId, parseRef(value).kind);
+    if (fallback) return fallback;
+    throw new Error(`Missing ${kind} artifact.`);
+  };
+  for (const step of args2.plan.steps) {
+    const stepDir = join7(outputDir, step.id);
+    const output = join7(stepDir, "output");
+    await mkdir3(stepDir, { recursive: true, mode: 448 });
+    await chmod2(stepDir, 448);
+    await mkdir3(output, { recursive: true, mode: 448 });
+    await chmod2(output, 448);
+    const configPath2 = join7(stepDir, "config.json");
+    const logPath = join7(stepDir, "step.log");
+    const fields = stepConfig(step);
+    let entrypoint;
+    let config;
+    if (step.uses === "tokenize") {
+      entrypoint = "train_tokenizer.py";
+      config = {
+        output_dir: output,
+        vocab_size: fields.vocabSize ?? hp.vocab_size,
+        max_chars: fields.maxChars ?? hp.max_chars,
+        system_prompt: args2.spec.system_prompt,
+        examples
+      };
+    } else if (step.uses === "pretrain") {
+      tokenizerDir = resolveFrom(fields.tokenizer, "tokenizer", tokenizerDir);
+      entrypoint = "pretrain.py";
+      config = {
+        tokenizer_dir: tokenizerDir,
+        output_dir: output,
+        depth: fields.depth ?? hp.depth,
+        steps: fields.steps ?? hp.pretrain_steps,
+        batch_size: fields.batchSize ?? hp.batch_size,
+        sequence_length: fields.sequenceLength ?? hp.sequence_length,
+        nproc_per_node: fields.nprocPerNode ?? hp.nproc_per_node,
+        max_chars: hp.max_chars,
+        system_prompt: args2.spec.system_prompt,
+        examples
+      };
+    } else if (step.uses === "finetune") {
+      modelDir = resolveFrom(fields.model, "model", modelDir);
+      entrypoint = "finetune.py";
+      config = {
+        model_dir: modelDir,
+        tokenizer_dir: tokenizerDir,
+        output_dir: output,
+        steps: fields.steps ?? hp.finetune_steps,
+        batch_size: fields.batchSize ?? hp.batch_size,
+        sequence_length: hp.sequence_length,
+        system_prompt: args2.spec.system_prompt,
+        examples
+      };
+    } else if (step.uses === "rl") {
+      modelDir = resolveFrom(fields.model, "model", modelDir);
+      entrypoint = "rl.py";
+      config = {
+        model_dir: modelDir,
+        tokenizer_dir: tokenizerDir,
+        output_dir: output,
+        steps: fields.steps ?? hp.rl_steps,
+        system_prompt: args2.spec.system_prompt,
+        examples
+      };
+    } else if (step.uses === "evaluate") {
+      modelDir = resolveFrom(fields.model, "model", modelDir);
+      entrypoint = "evaluate.py";
+      config = {
+        evaluator: fields.evaluator ?? "bpb",
+        model_dir: modelDir,
+        tokenizer_dir: tokenizerDir,
+        output_dir: output,
+        sequence_length: hp.sequence_length,
+        max_chars: hp.max_chars,
+        system_prompt: args2.spec.system_prompt,
+        examples
+      };
+    } else {
+      throw new Error(`Foundation runner does not implement ${step.uses} (step ${step.id}).`);
+    }
+    if ((step.uses === "finetune" || step.uses === "rl" || step.uses === "evaluate") && !tokenizerDir) {
+      throw new Error(`Step ${step.id} needs a tokenizer from an earlier tokenize step.`);
+    }
+    await writePrivateText(configPath2, `${JSON.stringify(config, null, 2)}
+`);
+    await spawnStep({ entrypoint, configPath: configPath2, logPath, stepId: step.id });
+    await makePrivateTree(stepDir);
+    const metrics = await readRequiredJsonObject(
+      join7(output, "metrics.json"),
+      `Foundation step "${step.id}" metrics`
+    );
+    if (metrics.ok !== true) {
+      throw new Error(`Foundation step "${step.id}" metrics must report ok: true.`);
+    }
+    const artifacts = {};
+    const record4 = {};
+    if (step.uses === "tokenize") {
+      const tokenizerPath = join7(output, "tokenizer.json");
+      await requireRegularNonemptyFile(tokenizerPath, `Foundation step "${step.id}" tokenizer.json`);
+      await readRequiredJsonObject(tokenizerPath, `Foundation step "${step.id}" tokenizer.json`);
+      record4.tokenizer = output;
+      tokenizerDir = output;
+      artifacts.tokenizer = await artifactFor(output);
+    } else if (step.uses === "pretrain" || step.uses === "finetune" || step.uses === "rl") {
+      const modelPath = join7(output, "model.safetensors");
+      const modelConfigPath = join7(output, "config.json");
+      await requireRegularNonemptyFile(modelPath, `Foundation step "${step.id}" model.safetensors`);
+      const modelConfig = await readRequiredJsonObject(
+        modelConfigPath,
+        `Foundation step "${step.id}" config.json`
+      );
+      requirePositiveIntegerFields(
+        modelConfig,
+        ["depth", "width", "heads", "vocab_size", "sequence_length"],
+        `Foundation step "${step.id}" config.json`
+      );
+      record4.model = output;
+      modelDir = output;
+      artifacts.model = await artifactFor(output);
+    } else if (step.uses === "evaluate") {
+      const reportPath2 = join7(output, "report.json");
+      const stepReport = await readRequiredJsonObject(
+        reportPath2,
+        `Foundation step "${step.id}" report.json`
+      );
+      if (stepReport.ok !== true) {
+        throw new Error(`Foundation step "${step.id}" report.json must report ok: true.`);
+      }
+      record4.report = reportPath2;
+      artifacts.report = await artifactFor(reportPath2);
+    }
+    produced.set(step.id, record4);
+    steps.push({ id: step.id, uses: step.uses, metrics, artifacts });
+  }
+  const report = {
+    status: "succeeded",
+    ...args2.plan.name ? { name: args2.plan.name } : {},
+    spec: args2.specPath,
+    steps
+  };
+  const reportPath = join7(outputDir, "report.json");
+  await writePrivateText(reportPath, `${JSON.stringify(report, null, 2)}
+`);
+  return {
+    status: "succeeded",
+    ...args2.plan.name ? { name: args2.plan.name } : {},
+    report_path: reportPath,
+    steps
+  };
+}
+
+// src/commands/pipeline.ts
 var DEFAULT_PIPELINE_FILE = "tunedtensor.pipeline.json";
+var DEFAULT_SPEC_FILE = "tunedtensor.json";
 function parseList(value) {
   if (!value) return void 0;
   const ids = value.split(",").map((id) => id.trim()).filter(Boolean);
   if (!ids.length) throw new Error("Step selection must name at least one step.");
   return ids;
 }
-function loadPipeline(path) {
-  const resolved = resolve4(path);
+function loadPipelineFile(path) {
+  const resolved = resolve5(path);
   if (!existsSync4(resolved)) throw new Error(`Pipeline file not found: ${path}. Run \`tt pipeline init\` to create one.`);
   try {
     return JSON.parse(readFileSync4(resolved, "utf8"));
@@ -4756,6 +5167,45 @@ function loadPipeline(path) {
     throw new Error(`Pipeline file must be JSON: ${error.message}`);
   }
 }
+function pipelineFromSpec(input) {
+  return pipelineFromFoundationHyperparameters(input.spec.name, input.spec.foundation);
+}
+function isParsedFoundationPipeline(document) {
+  try {
+    return isFoundationPipeline(parsePipeline2(document));
+  } catch {
+    return false;
+  }
+}
+async function resolvePipelineDocument(options) {
+  const filePath = resolve5(options.file);
+  const fileExists = existsSync4(filePath);
+  const specPath = options.spec ? resolve5(options.spec) : void 0;
+  const specInput = specPath && existsSync4(specPath) ? await loadLocalRunInput(specPath) : void 0;
+  if (specInput?.kind === "foundation-spec") {
+    if (fileExists) {
+      const document = loadPipelineFile(options.file);
+      if (isParsedFoundationPipeline(document)) return document;
+      throw new Error(
+        `Pipeline file ${options.file} is an adapter recipe, but ${options.spec} is a foundation spec. Use a foundation pipeline, omit --file, or pass an adapter spec.`
+      );
+    }
+    return pipelineFromSpec(specInput);
+  }
+  if (fileExists) {
+    const document = loadPipelineFile(options.file);
+    if (specInput && isParsedFoundationPipeline(document)) {
+      throw new Error(
+        `Pipeline file ${options.file} is a foundation recipe, but ${options.spec} is an adapter spec. Use a foundation spec, omit --file, or pass an adapter pipeline.`
+      );
+    }
+    return document;
+  }
+  if (specPath && !existsSync4(specPath)) await loadLocalRunInput(specPath);
+  throw new Error(
+    `Pipeline file not found: ${options.file}. Run \`tt pipeline init\` or pass a foundation --spec.`
+  );
+}
 function outputPlan(plan) {
   if (isJsonMode()) return printJson(plan);
   const typed = plan;
@@ -4766,28 +5216,49 @@ function outputPlan(plan) {
 }
 function registerPipelineCommands(parent) {
   const pipeline = parent.command("pipeline").description("Create, validate, inspect, and safely dry-run ordered pipeline recipes");
-  pipeline.command("init").description("Write a canonical v1 pipeline recipe").option("-f, --file <path>", "Output file", DEFAULT_PIPELINE_FILE).action((options) => {
-    const path = resolve4(options.file);
+  pipeline.command("init").description("Write a canonical v1 pipeline recipe").option("-f, --file <path>", "Output file", DEFAULT_PIPELINE_FILE).option("--engine <engine>", "adapter (default) or foundation").option("--spec <path>", "Foundation spec whose hyperparameters stamp the DAG").action(async (options) => {
+    const engine = options.engine ?? "adapter";
+    if (engine !== "adapter" && engine !== "foundation") {
+      throw new Error(`--engine must be adapter or foundation, got: ${engine}`);
+    }
+    if (engine !== "foundation" && options.spec) {
+      throw new Error("--spec is only valid with --engine foundation.");
+    }
+    const path = resolve5(options.file);
     if (existsSync4(path)) throw new Error(`Pipeline file already exists: ${options.file}.`);
-    const recipe = canonicalPipeline("local");
+    let recipe;
+    if (engine === "foundation") {
+      if (options.spec) {
+        const input = await loadLocalRunInput(resolve5(options.spec));
+        if (input.kind !== "foundation-spec") {
+          throw new Error("--spec must be a foundation tunedtensor.json.");
+        }
+        recipe = pipelineFromSpec(input);
+      } else {
+        recipe = canonicalFoundationPipeline2();
+      }
+    } else {
+      recipe = canonicalPipeline("local");
+    }
     writeFileSync3(path, `${JSON.stringify(recipe, null, 2)}
 `);
     if (isJsonMode()) return printJson({ created: true, path, pipeline: recipe });
     printSuccess(`Created ${options.file}`);
   });
-  pipeline.command("validate").description("Validate a pipeline without any execution or transfer").option("-f, --file <path>", "Pipeline file", DEFAULT_PIPELINE_FILE).action((options) => {
-    const errors = validatePipeline(loadPipeline(options.file));
+  pipeline.command("validate").description("Validate a pipeline without any execution or transfer").option("-f, --file <path>", "Pipeline file", DEFAULT_PIPELINE_FILE).option("--spec <path>", "Local behavior spec used to detect leftover engine mismatches", DEFAULT_SPEC_FILE).action(async (options) => {
+    const errors = validatePipeline(await resolvePipelineDocument(options));
     const result2 = { valid: errors.length === 0, errors };
     if (isJsonMode()) return printJson(result2);
     if (errors.length) throw new Error(`Invalid pipeline:
 - ${errors.join("\n- ")}`);
     printSuccess("Pipeline is valid.");
   });
-  pipeline.command("plan").description("Resolve step targets and required artifact transfers").option("-f, --file <path>", "Pipeline file", DEFAULT_PIPELINE_FILE).option("--only <ids>", "Comma-separated step IDs to include").option("--skip <ids>", "Comma-separated step IDs to omit").action((options) => {
-    outputPlan(createExecutionPlan(loadPipeline(options.file), { only: parseList(options.only), skip: parseList(options.skip) }));
+  pipeline.command("plan").description("Resolve step targets and required artifact transfers").option("-f, --file <path>", "Pipeline file", DEFAULT_PIPELINE_FILE).option("--spec <path>", "Local behavior spec used to detect leftover engine mismatches", DEFAULT_SPEC_FILE).option("--only <ids>", "Comma-separated step IDs to include").option("--skip <ids>", "Comma-separated step IDs to omit").action(async (options) => {
+    outputPlan(createExecutionPlan(await resolvePipelineDocument(options), { only: parseList(options.only), skip: parseList(options.skip) }));
   });
-  pipeline.command("run").description("Run an ordered local pipeline, or safely preview any pipeline").option("--dry-run", "Resolve and display only; never execute, transfer, or reserve credits").option("-f, --file <path>", "Pipeline file", DEFAULT_PIPELINE_FILE).option("--spec <path>", "Local behavior spec", "tunedtensor.json").option("--config <path>", "Local runtime config").option("--only <ids>", "Comma-separated step IDs to include").option("--skip <ids>", "Comma-separated step IDs to omit").action(async (options) => {
-    const plan = createExecutionPlan(loadPipeline(options.file), { only: parseList(options.only), skip: parseList(options.skip) });
+  pipeline.command("run").description("Run an ordered local pipeline, or safely preview any pipeline").option("--dry-run", "Resolve and display only; never execute, transfer, or reserve credits").option("-f, --file <path>", "Pipeline file", DEFAULT_PIPELINE_FILE).option("--spec <path>", "Local behavior spec", DEFAULT_SPEC_FILE).option("--config <path>", "Local runtime config").option("--only <ids>", "Comma-separated step IDs to include").option("--skip <ids>", "Comma-separated step IDs to omit").action(async (options) => {
+    const document = await resolvePipelineDocument(options);
+    const plan = createExecutionPlan(document, { only: parseList(options.only), skip: parseList(options.skip) });
     if (options.dryRun) {
       if (isJsonMode()) return printJson({ dry_run: true, ...plan });
       console.log("Dry run only \u2014 no execution, artifact transfer, or credit reservation will occur.");
@@ -4797,9 +5268,23 @@ function registerPipelineCommands(parent) {
     if (remote) {
       throw new Error(`Step "${remote.id}" targets cloud execution. This CLI is local-only; rewrite that step to local or use --dry-run.`);
     }
-    const input = await loadLocalRunInput(resolve4(options.spec));
+    const input = await loadLocalRunInput(resolve5(options.spec));
+    if (isParsedFoundationPipeline(document) || input.kind === "foundation-spec") {
+      if (input.kind !== "foundation-spec") {
+        throw new Error("Foundation pipelines require a foundation tunedtensor.json --spec.");
+      }
+      assertFoundationSpecReady(input.spec);
+      const result3 = await runFoundationPipeline({
+        spec: input.spec,
+        plan,
+        specPath: resolve5(options.spec)
+      });
+      if (isJsonMode()) return printJson(result3);
+      printSuccess(`Foundation pipeline completed. Report: ${result3.report_path}`);
+      return;
+    }
     assertLocalRunInputReady(input.request);
-    const config = await loadLocalRunnerConfig(options.config ? resolve4(options.config) : void 0);
+    const config = await loadLocalRunnerConfig(options.config ? resolve5(options.config) : void 0);
     const localPipeline = {
       version: 1,
       ...plan.name ? { name: plan.name } : {},
@@ -4881,10 +5366,10 @@ async function checkForCliUpdate(currentVersion, options = {}) {
       return null;
     }
   })();
-  const deadline = new Promise((resolve5) => {
+  const deadline = new Promise((resolve6) => {
     timeout = setTimeout(() => {
       controller.abort();
-      resolve5(null);
+      resolve6(null);
     }, timeoutMs);
   });
   try {
@@ -4982,7 +5467,7 @@ async function runSelfCommand(args2, options = {}) {
   if (!entrypoint) {
     throw new Error("Cannot locate the tt CLI entrypoint.");
   }
-  return await new Promise((resolve5, reject) => {
+  return await new Promise((resolve6, reject) => {
     const child = spawn2(process.execPath, [entrypoint, ...args2], {
       cwd: options.cwd,
       env: options.env ?? process.env,
@@ -5018,7 +5503,7 @@ async function runSelfCommand(args2, options = {}) {
     child.once("close", (exitCode, signal) => {
       cleanup();
       const signalNumber = signal ? osConstants2.signals[signal] : void 0;
-      resolve5({
+      resolve6({
         exitCode: exitCode ?? (typeof signalNumber === "number" ? 128 + signalNumber : 1),
         signal
       });
@@ -5206,7 +5691,7 @@ async function runCli(version, runtime = {}) {
 }
 
 // src/index.ts
-runCli("0.13.1-beta.1").catch((err) => {
+runCli("0.13.1-beta.2").catch((err) => {
   reportError(err);
   process.exit(1);
 });