@tuned-tensor/cli 0.9.0 → 0.9.1

package/dist/local-runtime.js

@@ -0,0 +1,1630 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_LOCAL_SPEC_PATH,
+  assertArtifactManifest,
+  assertLocalRunInputReady,
+  assertUsableModelArtifact,
+  baseModelRevisionSchema,
+  behaviorSpecExampleSchema,
+  buildBundledPythonCommand,
+  buildModelPrefetchPayload,
+  buildSystemMessage,
+  canonicalLocalPipeline,
+  comparisonReportSchema,
+  compileSpecToJsonl,
+  createLocalStore,
+  datasetFormatSchema,
+  datasetPrebuiltSchema,
+  defaultLocalHome,
+  evalExampleResultSchema,
+  evalReportSchema,
+  evalSplitSchema,
+  evaluateGeneralRegressionGate,
+  evaluationSuiteFromChatJsonl,
+  exampleToChatRow,
+  examplesFromChatJsonl,
+  examplesFromSpec,
+  fineTuneHyperparametersSchema,
+  fineTuneRunRequestSchema,
+  fingerprintLocalBaseModel,
+  forwardStreamLines,
+  generatedPlaceholderIssues,
+  initLocalRunnerConfigFile,
+  initLocalSpecFile,
+  isTerminalRunState,
+  jsonFieldMetricsSchema,
+  loadJsonFile,
+  loadLocalRunInput,
+  loadLocalRunnerConfig,
+  loadRunRequest,
+  localBehaviorSpecFileSchema,
+  localRunnerConfigSchema,
+  localRuntimePackageRoot,
+  localStorePaths,
+  minimalMachineLearningEnvironment,
+  normalizeChatJsonlForRelocation,
+  prefetchBaseModel,
+  reportInBackground,
+  resolveLocalRunInputPaths,
+  resolveTrainingModel,
+  runLocalFineTune,
+  runLocalPipeline,
+  runReportSchema,
+  runRequestFromLocalSpec,
+  sanitizeLogLine,
+  specSnapshotSchema,
+  tokenF1,
+  trainingReportSchema,
+  validateLocalFineTuneInput,
+  validateLocalPipeline,
+  verifyLocalBaseModel,
+  withBundledPythonEnvironment,
+  withHuggingFaceCacheEnvironment,
+  withOfflineHuggingFaceCacheEnvironment,
+  writeJsonAtomic
+} from "./chunk-DAP2Z7EZ.js";
+
+// src/local-runtime/index.ts
+import { readFileSync, realpathSync } from "fs";
+import { createHash } from "crypto";
+import { readFile as readFile2, stat } from "fs/promises";
+import { basename, dirname, join as join3, resolve as resolve3 } from "path";
+import { cwd } from "process";
+import { fileURLToPath as fileURLToPath2 } from "url";
+
+// src/local-runtime/compare.ts
+function byPrompt(report) {
+  return new Map(report.results.map((result) => [result.prompt, result]));
+}
+function avg(values) {
+  return values.length > 0 ? values.reduce((sum, value) => sum + value, 0) / values.length : null;
+}
+function summarizeRun(report) {
+  return {
+    run_id: report.run_id,
+    started_at: report.run_metadata.started_at,
+    base_model: report.base_model,
+    training_example_count: report.run_metadata.training_example_count,
+    eval_examples_used: report.run_metadata.eval_examples_used,
+    baseline_avg_score: report.baseline.avg_score,
+    candidate_avg_score: report.candidate.avg_score,
+    candidate_avg_token_f1: report.candidate.avg_token_f1 ?? null,
+    avg_score_delta: report.comparison.avg_score_delta
+  };
+}
+function subsetSide(prompts, baseline, candidate) {
+  const candidateResults = prompts.map((prompt) => candidate.get(prompt)).filter((result) => Boolean(result));
+  return {
+    baseline_avg_score: avg(prompts.map((prompt) => baseline.get(prompt)?.score).filter((score) => typeof score === "number")),
+    candidate_avg_score: avg(candidateResults.map((result) => result.score)),
+    candidate_avg_token_f1: avg(candidateResults.map((result) => tokenF1(result.expected, result.actual)))
+  };
+}
+function compareRuns(a, b) {
+  const aCandidate = byPrompt(a.candidate);
+  const bCandidate = byPrompt(b.candidate);
+  const aBaseline = byPrompt(a.baseline);
+  const bBaseline = byPrompt(b.baseline);
+  const sharedPrompts = [...bCandidate.keys()].filter((prompt) => aCandidate.has(prompt));
+  const bOnlyPrompts = [...bCandidate.keys()].filter((prompt) => !aCandidate.has(prompt));
+  const sharedA = subsetSide(sharedPrompts, aBaseline, aCandidate);
+  const sharedB = subsetSide(sharedPrompts, bBaseline, bCandidate);
+  const runA = summarizeRun(a);
+  const runB = summarizeRun(b);
+  const notes = [];
+  if (bOnlyPrompts.length > 0) {
+    notes.push(
+      `run_b evaluated ${bOnlyPrompts.length} example(s) run_a never saw; headline avg_score_delta values are not directly comparable across the two runs. Use the shared subset for recipe comparisons.`
+    );
+  }
+  return {
+    run_a: runA,
+    run_b: runB,
+    shared: {
+      examples: sharedPrompts.length,
+      run_a: sharedA,
+      run_b: sharedB,
+      candidate_avg_score_delta: sharedA.candidate_avg_score !== null && sharedB.candidate_avg_score !== null ? sharedB.candidate_avg_score - sharedA.candidate_avg_score : null,
+      candidate_avg_token_f1_delta: sharedA.candidate_avg_token_f1 !== null && sharedB.candidate_avg_token_f1 !== null ? sharedB.candidate_avg_token_f1 - sharedA.candidate_avg_token_f1 : null
+    },
+    b_only: { examples: bOnlyPrompts.length, ...subsetSide(bOnlyPrompts, bBaseline, bCandidate) },
+    notes
+  };
+}
+
+// src/local-runtime/doctor.ts
+import { constants } from "fs";
+import { access, mkdir, statfs, unlink, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join, resolve } from "path";
+import { spawn } from "child_process";
+async function runCommand(command, args, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  let interrupted;
+  const result = await new Promise((resolveResult) => {
+    let settled = false;
+    let stdout = "";
+    let stderr = "";
+    let stopError;
+    let forceKillTimer = null;
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env ?? process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: process.platform !== "win32"
+    });
+    const killProcessGroup = (signal) => {
+      if (child.pid && process.platform !== "win32") {
+        try {
+          process.kill(-child.pid, signal);
+          return;
+        } catch {
+        }
+      }
+      child.kill(signal);
+    };
+    const requestStop = (signal = "SIGTERM") => {
+      killProcessGroup(signal);
+      if (!forceKillTimer) {
+        forceKillTimer = setTimeout(() => killProcessGroup("SIGKILL"), 5e3);
+        forceKillTimer.unref();
+      }
+    };
+    const onSigint = () => {
+      interrupted = "interrupted by SIGINT";
+      stopError = interrupted;
+      requestStop("SIGINT");
+    };
+    const onSigterm = () => {
+      interrupted = "interrupted by SIGTERM";
+      stopError = interrupted;
+      requestStop("SIGTERM");
+    };
+    const finish = (result2) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+      resolveResult(result2);
+    };
+    const timer = setTimeout(() => {
+      stopError = `timed out after ${timeoutMs}ms`;
+      requestStop();
+    }, timeoutMs);
+    timer.unref();
+    process.once("SIGINT", onSigint);
+    process.once("SIGTERM", onSigterm);
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      finish({ code: null, stdout, stderr, error: error.message });
+    });
+    child.on("close", (code) => {
+      finish({ code: stopError ? null : code, stdout, stderr, error: stopError });
+    });
+  });
+  if (interrupted) throw new Error(interrupted);
+  return result;
+}
+function firstLine(value) {
+  return value.trim().split(/\r?\n/)[0] ?? "";
+}
+function commandText(command, args) {
+  return [command, ...args].map((part) => /\s/.test(part) ? JSON.stringify(part) : part).join(" ");
+}
+async function writableDirectoryCheck(name, path) {
+  const resolvedPath = resolve(path);
+  const probePath = join(resolvedPath, `.tt-local-write-probe-${process.pid}-${Date.now()}`);
+  try {
+    await mkdir(resolvedPath, { recursive: true });
+    await access(resolvedPath, constants.R_OK | constants.W_OK);
+    await writeFile(probePath, "ok\n", { flag: "wx" });
+    await unlink(probePath);
+    const fs = await statfs(resolvedPath);
+    const freeBytes = Number(fs.bavail) * Number(fs.bsize);
+    return {
+      name,
+      ok: true,
+      message: `${resolvedPath} is writable (${Math.round(freeBytes / 1024 ** 3 * 10) / 10} GiB available)`,
+      details: { path: resolvedPath, free_bytes: freeBytes }
+    };
+  } catch (error) {
+    await unlink(probePath).catch(() => void 0);
+    return {
+      name,
+      ok: false,
+      message: `${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`,
+      details: { path: resolvedPath }
+    };
+  }
+}
+function pythonProbeSource(device) {
+  return [
+    "import json",
+    "import torch, transformers, peft, huggingface_hub",
+    `requested = ${JSON.stringify(device)}`,
+    "assert torch.cuda.is_available(), 'TT Local training requires CUDA but torch.cuda.is_available() is false'",
+    "props = torch.cuda.get_device_properties(0)",
+    "print(json.dumps({'python_ok': True, 'torch': torch.__version__, 'transformers': transformers.__version__, 'cuda_available': True, 'cuda_device': torch.cuda.get_device_name(0), 'compute_capability': list(torch.cuda.get_device_capability(0)), 'total_memory_bytes': props.total_memory, 'evaluation_device': requested}))"
+  ].join("; ");
+}
+function pythonProbePlan(args) {
+  const entrypoint = buildBundledPythonCommand(
+    "-c",
+    [pythonProbeSource(args.device)]
+  );
+  const env = withBundledPythonEnvironment(
+    withHuggingFaceCacheEnvironment(
+      minimalMachineLearningEnvironment(process.env),
+      args.modelCache
+    )
+  );
+  return {
+    name: "python-runtime",
+    command: entrypoint.command,
+    args: entrypoint.commandArgs,
+    env
+  };
+}
+function buildDoctorPythonPlans(config) {
+  if (config.dryRun) return [];
+  return [
+    pythonProbePlan({
+      device: config.evaluation.inference.device,
+      modelCache: config.paths.modelCache
+    })
+  ];
+}
+function placeholderSpecCheck(request) {
+  const placeholder = request.spec_snapshot.examples.some(
+    (example) => /replace this with/i.test(example.input) || /replace this with/i.test(example.output)
+  ) || /describe the behavior this local model should learn/i.test(request.spec_snapshot.system_prompt);
+  return {
+    name: "spec-content",
+    ok: !placeholder,
+    message: placeholder ? "The spec still contains generated placeholder content; edit it before training." : `${request.spec_snapshot.examples.length} spec example(s); base model ${request.spec_snapshot.base_model}`
+  };
+}
+async function localBaseModelCheck(path) {
+  const resolvedPath = resolve(path);
+  try {
+    const verified = await verifyLocalBaseModel(resolvedPath);
+    return {
+      name: "local-base-model",
+      ok: true,
+      message: `${resolvedPath} is a valid local Hugging Face snapshot directory.`,
+      details: { path: resolvedPath, file_count: verified.fileCount, size_bytes: verified.sizeBytes }
+    };
+  } catch (error) {
+    return {
+      name: "local-base-model",
+      ok: false,
+      message: error instanceof Error ? error.message : String(error),
+      details: { path: resolvedPath }
+    };
+  }
+}
+async function runDoctor(config, request) {
+  const checks = [];
+  const nodeVersion = process.versions.node;
+  const nodeMajor = Number(nodeVersion.split(".")[0]);
+  checks.push({ name: "node", ok: nodeMajor >= 22, message: `Node ${nodeVersion}` });
+  checks.push(await writableDirectoryCheck("artifact-root", config.artifactRoot));
+  checks.push(await writableDirectoryCheck("store-root", config.storeRoot ?? defaultLocalHome()));
+  checks.push(await writableDirectoryCheck(
+    "model-cache",
+    config.paths.modelCache ?? process.env.HF_HOME ?? join(homedir(), ".cache", "huggingface")
+  ));
+  if (config.paths.baseModel) checks.push(await localBaseModelCheck(config.paths.baseModel));
+  if (request) {
+    checks.push(placeholderSpecCheck(request));
+    resolveTrainingModel(request.spec_snapshot.base_model);
+  }
+  const pythonPlans = buildDoctorPythonPlans(config);
+  if (pythonPlans.length > 0) {
+    const uvVersion = await runCommand("uv", ["--version"]);
+    checks.push({
+      name: "uv",
+      ok: uvVersion.code === 0,
+      message: uvVersion.code === 0 ? firstLine(uvVersion.stdout) : uvVersion.error ?? (firstLine(uvVersion.stderr) || "uv is not available")
+    });
+    if (uvVersion.code === 0) {
+      const uniquePlans = /* @__PURE__ */ new Map();
+      for (const plan of pythonPlans) {
+        const key = JSON.stringify([plan.command, plan.args, plan.env]);
+        if (!uniquePlans.has(key)) uniquePlans.set(key, plan);
+      }
+      for (const plan of uniquePlans.values()) {
+        const result = await runCommand(plan.command, plan.args, {
+          env: plan.env,
+          timeoutMs: 18e5
+        });
+        checks.push({
+          name: plan.name,
+          ok: result.code === 0,
+          message: result.code === 0 ? firstLine(result.stdout) : result.error ?? (firstLine(result.stderr) || `${plan.command} exited ${result.code}`),
+          details: { command: commandText(plan.command, plan.args) }
+        });
+      }
+    }
+  } else {
+    checks.push({
+      name: "python-runtime",
+      ok: true,
+      message: config.dryRun ? "Python dependency checks skipped because dryRun is enabled." : "Python dependency checks were skipped."
+    });
+  }
+  const device = config.evaluation.inference.device;
+  if (!config.dryRun) {
+    const nvidiaSmi = await runCommand("nvidia-smi", []);
+    checks.push({
+      name: "nvidia-smi",
+      ok: nvidiaSmi.code === 0,
+      message: nvidiaSmi.code === 0 ? firstLine(nvidiaSmi.stdout) : nvidiaSmi.error ?? (firstLine(nvidiaSmi.stderr) || "nvidia-smi not available")
+    });
+  } else {
+    checks.push({
+      name: "nvidia-smi",
+      ok: true,
+      message: config.dryRun ? "GPU checks skipped because dryRun is enabled." : `nvidia-smi is not required for device=${device}.`
+    });
+  }
+  const trainingCommand = buildBundledPythonCommand("train.py").displayCommand;
+  checks.push({
+    name: "effective-plan",
+    ok: true,
+    message: "Resolved the configured training and evaluation plan.",
+    details: {
+      training_command: trainingCommand ?? null,
+      evaluation_provider: "transformers",
+      evaluation_device: device,
+      artifact_root: resolve(config.artifactRoot),
+      store_root: resolve(config.storeRoot ?? defaultLocalHome()),
+      model_cache: resolve(config.paths.modelCache ?? process.env.HF_HOME ?? join(homedir(), ".cache", "huggingface")),
+      base_model: request?.spec_snapshot.base_model ?? null,
+      scoring_mode: config.evaluation.scoring.mode
+    }
+  });
+  return checks;
+}
+
+// src/local-runtime/model-server.ts
+import { spawn as spawn2 } from "child_process";
+import { resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+function localArtifactPath(uri) {
+  if (uri.startsWith("file://")) return fileURLToPath(uri);
+  if (/^[a-z][a-z0-9+.-]*:/i.test(uri)) {
+    throw new Error(`TT Local serving requires a local file artifact, got: ${uri}`);
+  }
+  return resolve2(uri);
+}
+function boundedNumber(name, value, minimum, maximum, integer = false) {
+  if (!Number.isFinite(value) || value < minimum || value > maximum || integer && !Number.isInteger(value)) {
+    throw new Error(`${name} must be between ${minimum} and ${maximum}`);
+  }
+  return value;
+}
+function isLoopbackHost(host) {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "[::1]";
+}
+function httpHost(host) {
+  return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+function buildModelServerLaunch(args) {
+  const options = args.options ?? {};
+  const host = options.host ?? "127.0.0.1";
+  const remote = !isLoopbackHost(host);
+  if (remote && !options.allowRemote) {
+    throw new Error("Refusing a non-loopback model server bind without --allow-remote.");
+  }
+  const apiKey = options.apiKeyEnv ? process.env[options.apiKeyEnv]?.trim() : void 0;
+  if (options.apiKeyEnv && !apiKey) throw new Error(`${options.apiKeyEnv} is not set.`);
+  if (remote && !apiKey) {
+    throw new Error("Non-loopback serving requires --api-key-env with a populated environment variable.");
+  }
+  const port = boundedNumber("port", options.port ?? 8e3, 1, 65535, true);
+  const maxTokens = boundedNumber("maxTokens", options.maxTokens ?? 512, 1, 8192, true);
+  const temperature = boundedNumber("temperature", options.temperature ?? 0, 0, 5);
+  const topP = boundedNumber("topP", options.topP ?? 1, 0, 1);
+  const maxConcurrentRequests = boundedNumber(
+    "maxConcurrentRequests",
+    options.maxConcurrentRequests ?? 1,
+    1,
+    8,
+    true
+  );
+  const artifactPath = args.artifactUri ? localArtifactPath(args.artifactUri) : void 0;
+  const recordedBaseModelPath = options.baseModelArtifactUri ? localArtifactPath(options.baseModelArtifactUri) : void 0;
+  const configuredBaseModelPath = args.config.paths.baseModel ? resolve2(args.config.paths.baseModel) : void 0;
+  if (recordedBaseModelPath && configuredBaseModelPath && resolve2(recordedBaseModelPath) !== configuredBaseModelPath) {
+    throw new Error(
+      `Configured paths.baseModel ${configuredBaseModelPath} does not match the base model recorded for this artifact: ` + recordedBaseModelPath
+    );
+  }
+  const localBaseModelPath = recordedBaseModelPath ?? configuredBaseModelPath;
+  resolveTrainingModel(args.baseModel);
+  const entrypoint = buildBundledPythonCommand("serve.py");
+  const env = withBundledPythonEnvironment(
+    withOfflineHuggingFaceCacheEnvironment({
+      ...minimalMachineLearningEnvironment(process.env),
+      ...artifactPath ? { TT_MODEL_ARTIFACT: artifactPath } : {},
+      TT_BASE_MODEL: localBaseModelPath ?? args.baseModel,
+      ...options.baseModelRevision && !localBaseModelPath ? { TT_BASE_MODEL_REVISION: options.baseModelRevision } : {},
+      TT_MODEL_NAME: args.modelName,
+      TT_MODEL_LOADER: "causal_lm",
+      TT_HOST: host,
+      TT_PORT: String(port),
+      TT_DEVICE: options.device ?? args.config.evaluation.inference.device,
+      TT_MAX_TOKENS: String(maxTokens),
+      TT_TEMPERATURE: String(temperature),
+      TT_TOP_P: String(topP),
+      TT_TRUST_REMOTE_CODE: "false",
+      TT_MAX_CONCURRENT_REQUESTS: String(maxConcurrentRequests),
+      ...options.systemPrompt ? { TT_SYSTEM_PROMPT: options.systemPrompt } : {},
+      ...apiKey ? { TT_API_KEY: apiKey } : {}
+    }, args.config.paths.modelCache)
+  );
+  return {
+    command: entrypoint.command,
+    commandArgs: entrypoint.commandArgs,
+    displayCommand: entrypoint.displayCommand,
+    env,
+    url: `http://${httpHost(host)}:${port}`,
+    modelName: args.modelName,
+    artifactPath
+  };
+}
+function buildLocalModelServerLaunch(args) {
+  return buildModelServerLaunch({
+    modelName: args.model.id,
+    baseModel: args.model.base_model,
+    artifactUri: args.model.artifact_uri,
+    config: args.config,
+    options: args.options
+  });
+}
+function buildLocalBaseModelServerLaunch(args) {
+  return buildModelServerLaunch({
+    modelName: `base:${args.baseModel}`,
+    baseModel: args.baseModel,
+    config: args.config,
+    options: args.options
+  });
+}
+async function serveLocalModel(launch) {
+  await new Promise((resolveServer, reject) => {
+    const child = spawn2(launch.command, launch.commandArgs, {
+      env: launch.env,
+      stdio: "inherit",
+      detached: process.platform !== "win32"
+    });
+    let stopping = false;
+    let forceKillTimer;
+    const killProcessGroup = (signal) => {
+      if (child.pid && process.platform !== "win32") {
+        try {
+          process.kill(-child.pid, signal);
+          return;
+        } catch {
+        }
+      }
+      child.kill(signal);
+    };
+    const stop = (signal) => {
+      if (stopping) return;
+      stopping = true;
+      killProcessGroup(signal);
+      forceKillTimer = setTimeout(() => killProcessGroup("SIGKILL"), 5e3);
+      forceKillTimer.unref();
+    };
+    const onSigint = () => stop("SIGINT");
+    const onSigterm = () => stop("SIGTERM");
+    const cleanup = () => {
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+    };
+    process.once("SIGINT", onSigint);
+    process.once("SIGTERM", onSigterm);
+    child.once("error", (error) => {
+      cleanup();
+      reject(error);
+    });
+    child.once("close", (code, signal) => {
+      cleanup();
+      if (stopping || signal === "SIGINT" || signal === "SIGTERM") {
+        resolveServer();
+      } else if (code === 0) {
+        resolveServer();
+      } else {
+        reject(new Error(`Local model server exited with code ${code ?? "unknown"}.`));
+      }
+    });
+  });
+}
+
+// src/local-runtime/active-model.ts
+import { appendFile, readFile } from "fs/promises";
+import { join as join2 } from "path";
+function pointerPath(store) {
+  return join2(store.root, "active-model.json");
+}
+function historyPath(store) {
+  return join2(store.root, "activation-history.jsonl");
+}
+async function readPointer(store) {
+  try {
+    const value = JSON.parse(await readFile(pointerPath(store), "utf8"));
+    if (value.schema_version !== 1 || !["activate", "rollback"].includes(value.action) || value.model_id !== null && typeof value.model_id !== "string" || value.run_id !== null && typeof value.run_id !== "string" || value.previous_model_id !== null && typeof value.previous_model_id !== "string") {
+      throw new Error("Active model pointer has an invalid shape.");
+    }
+    return value;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function assertModelCanActivate(store, modelId) {
+  const model = await store.getModel(modelId);
+  const run = await store.getRun(model.run_id);
+  if (run.status !== "completed") {
+    throw new Error(`Model ${model.id} belongs to run ${run.id}, which is not completed.`);
+  }
+  const report = runReportSchema.parse(
+    JSON.parse(await readFile(join2(model.artifact_dir, "run-report.json"), "utf8"))
+  );
+  if (!report.general_regression) {
+    throw new Error(`Model ${model.id} has no general regression evaluation.`);
+  }
+  if (!report.general_regression.passed) {
+    throw new Error(
+      `Model ${model.id} failed general regression: ` + (report.general_regression.failures.join(" ") || "regression budget exceeded")
+    );
+  }
+  return model;
+}
+async function publishPointer(store, pointer) {
+  await store.ensure();
+  await writeJsonAtomic(pointerPath(store), pointer);
+  await appendFile(historyPath(store), `${JSON.stringify(pointer)}
+`, "utf8");
+  return pointer;
+}
+async function getActiveModel(store) {
+  const pointer = await readPointer(store);
+  if (!pointer?.model_id) return { pointer, model: null };
+  return { pointer, model: await store.getModel(pointer.model_id) };
+}
+async function activateModel(store, modelId) {
+  const [model, current] = await Promise.all([
+    assertModelCanActivate(store, modelId),
+    readPointer(store)
+  ]);
+  if (current?.model_id === model.id) return current;
+  return publishPointer(store, {
+    schema_version: 1,
+    model_id: model.id,
+    run_id: model.run_id,
+    previous_model_id: current?.model_id ?? null,
+    activated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    action: "activate"
+  });
+}
+async function rollbackActiveModel(store) {
+  const current = await readPointer(store);
+  if (!current) throw new Error("No active-model history exists to roll back.");
+  const targetId = current.previous_model_id;
+  const target = targetId ? await assertModelCanActivate(store, targetId) : null;
+  return publishPointer(store, {
+    schema_version: 1,
+    model_id: target?.id ?? null,
+    run_id: target?.run_id ?? null,
+    previous_model_id: current.model_id,
+    activated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    action: "rollback"
+  });
+}
+
+// src/local-runtime/index.ts
+function packageVersion() {
+  try {
+    const packageJson = JSON.parse(
+      readFileSync(resolve3(localRuntimePackageRoot(import.meta.url), "package.json"), "utf8")
+    );
+    return typeof packageJson.version === "string" ? packageJson.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+var TT_LOCAL_VERSION = packageVersion();
+function getLocalRunnerInfo() {
+  return {
+    name: "tuned-tensor-local",
+    status: "local-runner-preview",
+    description: "Local CUDA LoRA fine-tuning with held-out base-versus-tuned evaluation.",
+    version: TT_LOCAL_VERSION
+  };
+}
+function readOption(argv, name) {
+  const index = argv.indexOf(name);
+  if (index !== -1) return argv[index + 1];
+  const inline = argv.find((value) => value.startsWith(`${name}=`));
+  return inline?.slice(name.length + 1);
+}
+function hasFlag(argv, name) {
+  return argv.includes(name);
+}
+function printHelp() {
+  console.log(`Usage: tt-local <command> [options]
+
+Commands:
+  info                              Show package and runner information
+  init [--name "My Local Model"] [--model Qwen/Qwen3.5-2B] [--output tunedtensor.json] [--profile spark] [--force]
+  doctor [tunedtensor.json] [--config local-runner.json]
+  validate [tunedtensor.json] [--config local-runner.json]
+  run [tunedtensor.json] [--config local-runner.json] [--dry-run] [--verbose] [--quiet]
+  serve <model-id|active|base> [--config local-runner.json] [--host 127.0.0.1] [--port 8000]
+  runs list|get|events|report|compare [args] [--config local-runner.json]
+  models list|get|verify|prefetch|verify-base|active|activate|rollback|serve [args] [--config local-runner.json]
+
+Global options:
+  -h, --help                       Show help
+  -V, --version                    Show the installed version
+
+The run command writes local artifacts under config.artifactRoot, defaulting to
+.tt-local/artifacts. The file-backed local store defaults to
+~/.tuned-tensor-local unless config.storeRoot or TT_LOCAL_HOME is set.`);
+}
+var CONFIG_OPTION = { name: "--config", value: "path", description: "Local runner config JSON path" };
+var VERBOSE_OPTION = { name: "--verbose", description: "Stream subprocess output" };
+var QUIET_OPTION = { name: "--quiet", description: "Suppress progress output on stderr" };
+var MODEL_SERVE_OPTIONS = [
+  CONFIG_OPTION,
+  { name: "--host", value: "host", description: "Bind host (localhost by default)" },
+  { name: "--port", value: "port", description: "Bind port" },
+  { name: "--device", value: "device", description: "cuda or cpu" },
+  { name: "--max-tokens", value: "count", description: "Default response token limit" },
+  { name: "--temperature", value: "number", description: "Default sampling temperature" },
+  { name: "--top-p", value: "number", description: "Default nucleus sampling threshold" },
+  { name: "--max-concurrent-requests", value: "count", description: "Concurrent generation limit" },
+  { name: "--spec", value: "path", description: "Behavior spec whose instructions are enforced" },
+  { name: "--no-spec-prompt", description: "Do not enforce the stored behavior-spec prompt" },
+  { name: "--allow-remote", description: "Allow a non-loopback bind" },
+  { name: "--api-key-env", value: "name", description: "Environment variable containing a bearer token" },
+  { name: "--print-command", description: "Validate and print the launch plan without starting" }
+];
+var COMMAND_DEFINITIONS = {
+  info: {
+    usage: "tt-local info",
+    description: "Show the installed TT Local version and runner status.",
+    options: [],
+    maxPositionals: 0
+  },
+  init: {
+    usage: "tt-local init [options]",
+    description: "Create a local tunedtensor.json behavior spec.",
+    options: [
+      { name: "--name", value: "name", description: "Behavior spec name" },
+      { name: "--model", value: "model", description: "Base model ID" },
+      { name: "--output", value: "path", description: "Output spec path" },
+      { name: "--profile", value: "profile", description: "Write a durable runner config (spark)" },
+      { name: "--config", value: "path", description: "Runner config path (written with --profile)" },
+      { name: "--force", description: "Overwrite an existing output file" }
+    ],
+    maxPositionals: 0
+  },
+  doctor: {
+    usage: "tt-local doctor [tunedtensor.json] [--config path]",
+    description: "Check the host and optional run input before starting work.",
+    options: [CONFIG_OPTION],
+    maxPositionals: 1
+  },
+  validate: {
+    usage: "tt-local validate [tunedtensor.json] [options]",
+    description: "Validate a local behavior spec without executing it.",
+    options: [CONFIG_OPTION],
+    maxPositionals: 1
+  },
+  run: {
+    usage: "tt-local run [tunedtensor.json] [options]",
+    description: "Run the baseline, fine-tuning, tuned evaluation, and report workflow.",
+    options: [
+      CONFIG_OPTION,
+      { name: "--dry-run", description: "Write representative artifacts without GPU work" },
+      VERBOSE_OPTION,
+      QUIET_OPTION
+    ],
+    maxPositionals: 1
+  },
+  serve: {
+    usage: "tt-local serve <model-id|active|base> [options]",
+    description: "Serve a verified adapter, the active model, or the protected base.",
+    options: MODEL_SERVE_OPTIONS,
+    minPositionals: 1,
+    maxPositionals: 1,
+    missingPositionalsMessage: "serve requires <model-id>"
+  }
+};
+var COMMAND_GROUPS = {
+  runs: {
+    description: "Inspect locally stored runs.",
+    defaultSubcommand: "list",
+    subcommands: {
+      list: { usage: "tt-local runs list [--config path]", description: "List local runs.", options: [CONFIG_OPTION], maxPositionals: 0 },
+      get: { usage: "tt-local runs get <run-id> [--config path]", description: "Get a local run.", options: [CONFIG_OPTION], minPositionals: 1, maxPositionals: 1, missingPositionalsMessage: "runs get requires <run-id>" },
+      events: { usage: "tt-local runs events <run-id> [--config path]", description: "List run events.", options: [CONFIG_OPTION], minPositionals: 1, maxPositionals: 1, missingPositionalsMessage: "runs events requires <run-id>" },
+      report: { usage: "tt-local runs report <run-id> [--config path]", description: "Show the baseline-vs-tuned report, including deltas and regressions.", options: [CONFIG_OPTION], minPositionals: 1, maxPositionals: 1, missingPositionalsMessage: "runs report requires <run-id>" },
+      compare: { usage: "tt-local runs compare <run-id-a> <run-id-b> [--config path]", description: "Compare two run reports.", options: [CONFIG_OPTION], minPositionals: 2, maxPositionals: 2, missingPositionalsMessage: "runs compare requires <run-id-a> <run-id-b>" }
+    }
+  },
+  models: {
+    description: "Inspect, verify, prefetch, or serve local models.",
+    defaultSubcommand: "list",
+    subcommands: {
+      list: { usage: "tt-local models list [--config path]", description: "List local models.", options: [CONFIG_OPTION], maxPositionals: 0 },
+      get: { usage: "tt-local models get <model-id> [--config path]", description: "Get a local model.", options: [CONFIG_OPTION], minPositionals: 1, maxPositionals: 1, missingPositionalsMessage: "models get requires <model-id>" },
+      verify: {
+        usage: "tt-local models verify <model-id-or-artifact-path> [--config path]",
+        description: "Verify a stored model or manifested artifact path.",
+        options: [CONFIG_OPTION],
+        minPositionals: 1,
+        maxPositionals: 1,
+        missingPositionalsMessage: "models verify requires <model-id-or-artifact-path>"
+      },
+      prefetch: {
+        usage: "tt-local models prefetch [tunedtensor.json] [options]",
+        description: "Download the configured base model before a run.",
+        options: [CONFIG_OPTION, VERBOSE_OPTION, QUIET_OPTION],
+        maxPositionals: 1
+      },
+      "verify-base": {
+        usage: "tt-local models verify-base [tunedtensor.json] [options]",
+        description: "Verify that the configured base-model snapshot is complete and locally available.",
+        options: [CONFIG_OPTION, VERBOSE_OPTION, QUIET_OPTION],
+        maxPositionals: 1
+      },
+      active: {
+        usage: "tt-local models active [--config path]",
+        description: "Show the active adapter, or the protected base when none is active.",
+        options: [CONFIG_OPTION],
+        maxPositionals: 0
+      },
+      activate: {
+        usage: "tt-local models activate <model-id> [--config path]",
+        description: "Activate a verified model whose general regression gate passed.",
+        options: [CONFIG_OPTION],
+        minPositionals: 1,
+        maxPositionals: 1,
+        missingPositionalsMessage: "models activate requires <model-id>"
+      },
+      rollback: {
+        usage: "tt-local models rollback [--config path]",
+        description: "Restore the previously active adapter or protected base.",
+        options: [CONFIG_OPTION],
+        maxPositionals: 0
+      },
+      serve: {
+        usage: "tt-local models serve <model-id|active|base> [options]",
+        description: "Alias for `tt-local serve`.",
+        options: MODEL_SERVE_OPTIONS,
+        minPositionals: 1,
+        maxPositionals: 1,
+        missingPositionalsMessage: "models serve requires <model-id>"
+      }
+    }
+  }
+};
+function hasHelpFlag(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}
+function printCommandHelp(definition) {
+  console.log(`Usage: ${definition.usage}
+
+${definition.description}`);
+  if (definition.options.length > 0) {
+    console.log("\nOptions:");
+    for (const option of definition.options) {
+      const label = option.value ? `${option.name} <${option.value}>` : option.name;
+      console.log(`  ${label.padEnd(34)} ${option.description}`);
+    }
+  }
+  console.log("  -h, --help                        Show help");
+}
+function printGroupHelp(command, group) {
+  console.log(`Usage: tt-local ${command} <command> [options]
+
+${group.description}
+
+Commands:`);
+  for (const [name, definition] of Object.entries(group.subcommands)) {
+    console.log(`  ${name.padEnd(16)} ${definition.description}`);
+  }
+  console.log("\nRun `tt-local " + command + " <command> --help` for command-specific help.");
+}
+function parseCommandArguments(tokens, definition) {
+  const options = new Map(definition.options.map((option) => [option.name, option]));
+  const seen = /* @__PURE__ */ new Set();
+  const positionals = [];
+  let optionsEnded = false;
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!optionsEnded && token === "--") {
+      optionsEnded = true;
+      continue;
+    }
+    if (!optionsEnded && token.startsWith("-")) {
+      const equalsIndex = token.indexOf("=");
+      const name = equalsIndex === -1 ? token : token.slice(0, equalsIndex);
+      const inlineValue = equalsIndex === -1 ? void 0 : token.slice(equalsIndex + 1);
+      const option = options.get(name);
+      if (!option) throw new Error(`Unknown option: ${name}`);
+      if (seen.has(name)) throw new Error(`Option ${name} may only be specified once.`);
+      seen.add(name);
+      if (option.value) {
+        if (inlineValue !== void 0) {
+          if (!inlineValue) throw new Error(`Option ${name} requires a value.`);
+          continue;
+        }
+        const value = tokens[index + 1];
+        if (value === void 0 || value.startsWith("-")) {
+          throw new Error(`Option ${name} requires a value.`);
+        }
+        index += 1;
+      } else if (inlineValue !== void 0) {
+        throw new Error(`Option ${name} does not accept a value.`);
+      }
+      continue;
+    }
+    positionals.push(token);
+  }
+  if (positionals.length < (definition.minPositionals ?? 0)) {
+    throw new Error(definition.missingPositionalsMessage ?? `Missing required argument. Usage: ${definition.usage}`);
+  }
+  if (definition.maxPositionals !== void 0 && positionals.length > definition.maxPositionals) {
+    throw new Error(`Too many arguments. Usage: ${definition.usage}`);
+  }
+  return positionals;
+}
+function parseCli(argv) {
+  const command = argv[2] ?? "info";
+  if (command === "--help" || command === "-h") {
+    return { command: "info", positionals: [], help: "top" };
+  }
+  if (command === "--version" || command === "-V") {
+    if (argv.length > 3) throw new Error(`${command} does not accept arguments.`);
+    return { command, positionals: [], help: "command" };
+  }
+  if (command.startsWith("-")) throw new Error(`Unknown option: ${command}`);
+  const definition = COMMAND_DEFINITIONS[command];
+  if (definition) {
+    if (hasHelpFlag(argv.slice(3))) {
+      return { command, positionals: [], help: "command", definition };
+    }
+    return {
+      command,
+      positionals: parseCommandArguments(argv.slice(3), definition),
+      help: "top",
+      definition
+    };
+  }
+  const group = COMMAND_GROUPS[command];
+  if (!group) throw new Error(`Unknown command: ${command}`);
+  if (argv[3] === "--help" || argv[3] === "-h") {
+    return { command, positionals: [], help: "group" };
+  }
+  const candidate = argv[3];
+  let subcommand;
+  let tokenStart;
+  if (candidate && !candidate.startsWith("-")) {
+    subcommand = candidate;
+    tokenStart = 4;
+  } else if (group.defaultSubcommand) {
+    subcommand = group.defaultSubcommand;
+    tokenStart = 3;
+  } else {
+    throw new Error(`${command} requires a subcommand. Run 'tt-local ${command} --help'.`);
+  }
+  const subcommandDefinition = group.subcommands[subcommand];
+  if (!subcommandDefinition) throw new Error(`Unknown ${command} command: ${subcommand}`);
+  if (hasHelpFlag(argv.slice(tokenStart))) {
+    return { command, subcommand, positionals: [], help: "command", definition: subcommandDefinition };
+  }
+  return {
+    command,
+    subcommand,
+    positionals: parseCommandArguments(argv.slice(tokenStart), subcommandDefinition),
+    help: "top",
+    definition: subcommandDefinition
+  };
+}
+function readNumberOption(argv, name) {
+  const value = readOption(argv, name);
+  return value ? Number(value) : void 0;
+}
+async function selectedConfigPath(argv, adjacentTo) {
+  const explicitPath = readOption(argv, "--config");
+  if (explicitPath) return resolve3(explicitPath);
+  const candidate = join3(adjacentTo ? dirname(resolve3(adjacentTo)) : cwd(), "local-runner.json");
+  const metadata = await stat(candidate).catch(() => null);
+  return metadata?.isFile() ? candidate : void 0;
+}
+async function configSelectionFromArgv(argv, adjacentTo) {
+  const path = await selectedConfigPath(argv, adjacentTo);
+  return {
+    config: await loadLocalRunnerConfig(path),
+    ...path ? { path } : {}
+  };
+}
+async function configFromArgv(argv, adjacentTo) {
+  return (await configSelectionFromArgv(argv, adjacentTo)).config;
+}
+async function loadCliBehaviorSpec(inputPath, runId) {
+  const input = await loadLocalRunInput(inputPath, {
+    ...runId ? { runId } : {}
+  });
+  if (input.kind !== "spec") {
+    throw new Error(`TT Local CLI expects a tunedtensor.json behavior spec, not a full run request: ${input.path}`);
+  }
+  return input;
+}
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+function shortValue(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) return `[${value.length} items]`;
+  return null;
+}
+function formatEvent(event) {
+  const detailText = Object.entries(event.details ?? {}).filter(([key]) => key !== "metrics").map(([key, value]) => {
+    const formatted = key === "command" && Array.isArray(value) ? value.join(" ") : shortValue(value);
+    return formatted ? `${key}=${formatted}` : null;
+  }).filter((value) => Boolean(value)).slice(0, 5).join(" ");
+  return sanitizeLogLine(`[tt-local] ${event.stage}: ${event.message}${detailText ? ` (${detailText})` : ""}`);
+}
+function createConsoleReporter(options) {
+  if (options.quiet) return void 0;
+  let lastLogLine = "";
+  return {
+    verbose: options.verbose,
+    onEvent(event) {
+      process.stderr.write(`${formatEvent(event)}
+`);
+    },
+    onLog(log) {
+      const line = sanitizeLogLine(`[tt-local] ${log.stage}${log.stream ? ` ${log.stream}` : ""}: ${log.message}`);
+      if (line === lastLogLine) return;
+      lastLogLine = line;
+      process.stderr.write(`${line}
+`);
+    }
+  };
+}
+async function verifyStoredModel(model) {
+  const manifestPath = join3(model.artifact_dir, "artifact-manifest.json");
+  const integrity = await assertArtifactManifest(manifestPath, {
+    requiredPaths: ["stage-metadata.json", "training-report.json"],
+    scopeToRequired: true,
+    verifyModel: true
+  });
+  const manifest = JSON.parse(await readFile2(manifestPath, "utf8"));
+  if (!manifest.model) {
+    throw new Error(`Artifact manifest does not contain a model contract: ${manifestPath}`);
+  }
+  const artifact = await assertUsableModelArtifact(model.artifact_uri);
+  if (typeof manifest.model.base_model_artifact_uri === "string" && typeof manifest.model.base_model_fingerprint === "string") {
+    const actualBaseFingerprint = await fingerprintLocalBaseModel(manifest.model.base_model_artifact_uri);
+    if (actualBaseFingerprint !== manifest.model.base_model_fingerprint) {
+      throw new Error("Recorded local base-model content no longer matches the model artifact contract.");
+    }
+  }
+  if (typeof manifest.model.artifact_root !== "string" || resolve3(manifest.model.artifact_root) !== resolve3(artifact.path)) {
+    throw new Error("Stored model record does not match the artifact covered by its manifest.");
+  }
+  if (manifest.model.base_model !== model.base_model) {
+    throw new Error("Stored model base model does not match its artifact manifest.");
+  }
+  return {
+    manifest_path: manifestPath,
+    integrity,
+    artifact,
+    contract: manifest.model
+  };
+}
+async function verifyActivationEvidence(model) {
+  await assertArtifactManifest(join3(model.artifact_dir, "artifact-manifest.json"), {
+    requiredPaths: [
+      "run-report.json",
+      "general-baseline-eval.json",
+      "general-candidate-eval.json"
+    ],
+    scopeToRequired: true,
+    verifyModel: true
+  });
+}
+async function verifyModelArtifactPath(input) {
+  const inputPath = resolve3(input);
+  let manifestPath;
+  let artifactUri = inputPath;
+  if (basename(inputPath) === "artifact-manifest.json") {
+    manifestPath = inputPath;
+    const raw = JSON.parse(await readFile2(inputPath, "utf8"));
+    if (typeof raw.model?.artifact_root !== "string") {
+      throw new Error(`Artifact manifest does not contain a model contract: ${inputPath}`);
+    }
+    artifactUri = raw.model.artifact_root;
+  } else {
+    const metadata = await stat(inputPath).catch(() => null);
+    if (!metadata) throw new Error(`Model not found and artifact path does not exist: ${input}`);
+    let current = metadata.isDirectory() ? inputPath : dirname(inputPath);
+    for (let depth = 0; depth < 8; depth += 1) {
+      const candidate = join3(current, "artifact-manifest.json");
+      const raw = await readFile2(candidate, "utf8").catch(() => null);
+      if (raw) {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.model?.artifact_root === "string" && resolve3(parsed.model.artifact_root) === resolve3(inputPath)) {
+          manifestPath = candidate;
+          break;
+        }
+      }
+      const parent = dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  if (!manifestPath) {
+    throw new Error(`No artifact manifest covering model path ${inputPath} was found in its parent run directory.`);
+  }
+  const integrity = await assertArtifactManifest(manifestPath, {
+    requiredPaths: ["stage-metadata.json", "training-report.json"],
+    scopeToRequired: true,
+    verifyModel: true
+  });
+  const manifest = JSON.parse(await readFile2(manifestPath, "utf8"));
+  if (!manifest.model) throw new Error(`Artifact manifest does not contain a model contract: ${manifestPath}`);
+  const artifact = await assertUsableModelArtifact(artifactUri);
+  if (typeof manifest.model.base_model_artifact_uri === "string" && typeof manifest.model.base_model_fingerprint === "string") {
+    const actualBaseFingerprint = await fingerprintLocalBaseModel(manifest.model.base_model_artifact_uri);
+    if (actualBaseFingerprint !== manifest.model.base_model_fingerprint) {
+      throw new Error("Recorded local base-model content no longer matches the model artifact contract.");
+    }
+  }
+  if (typeof manifest.model.artifact_root !== "string" || resolve3(manifest.model.artifact_root) !== resolve3(artifact.path)) {
+    throw new Error("Model path does not match the artifact covered by its manifest.");
+  }
+  return { manifest_path: manifestPath, integrity, artifact, contract: manifest.model };
+}
+async function modelSystemPrompt(args) {
+  const specPath = readOption(args.argv, "--spec");
+  if (specPath && hasFlag(args.argv, "--no-spec-prompt")) {
+    throw new Error("Use only one of --spec or --no-spec-prompt.");
+  }
+  if (hasFlag(args.argv, "--no-spec-prompt")) return void 0;
+  let spec;
+  if (specPath) {
+    const input = JSON.parse(await readFile2(resolve3(specPath), "utf8"));
+    const local = localBehaviorSpecFileSchema.safeParse(input);
+    if (!local.success) {
+      throw new Error(`--spec must contain a tunedtensor.json behavior spec: ${resolve3(specPath)}`);
+    }
+    spec = local.data;
+  } else {
+    const runRequestPath = join3(args.store.paths.runsDir, args.model.run_id, "request.json");
+    let persistedRequest = null;
+    try {
+      persistedRequest = fineTuneRunRequestSchema.parse(JSON.parse(await readFile2(runRequestPath, "utf8")));
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    spec = persistedRequest?.spec_snapshot ?? (await args.store.getSpec(args.model.behavior_spec_id)).spec;
+  }
+  if (spec.base_model !== args.model.base_model) {
+    throw new Error(
+      `Behavior spec base model ${spec.base_model} does not match stored model base ${args.model.base_model}.`
+    );
+  }
+  const prompt = buildSystemMessage(spec);
+  const metadata = JSON.parse(
+    await readFile2(join3(args.model.artifact_dir, "stage-metadata.json"), "utf8")
+  );
+  const promptHash = createHash("sha256").update(prompt).digest("hex");
+  if (metadata.system_prompt_sha256 !== promptHash) {
+    throw new Error(
+      "Behavior spec instructions do not match the prompt fingerprint used for this trained model. Pass the original --spec, or use --no-spec-prompt only when this change is intentional."
+    );
+  }
+  return prompt;
+}
+function modelServeDevice(argv) {
+  const value = readOption(argv, "--device");
+  if (value === void 0 || value === "cpu" || value === "cuda") {
+    return value;
+  }
+  throw new Error(`--device must be cuda or cpu; got: ${value}`);
+}
+async function serveStoredModelFromCli(args) {
+  const store = createLocalStore(args.config.storeRoot);
+  const model = await store.getModel(args.modelId);
+  const verified = await verifyStoredModel(model);
+  const launch = buildLocalModelServerLaunch({
+    model,
+    config: args.config,
+    options: {
+      host: readOption(args.argv, "--host"),
+      port: readNumberOption(args.argv, "--port"),
+      device: modelServeDevice(args.argv),
+      maxTokens: readNumberOption(args.argv, "--max-tokens"),
+      temperature: readNumberOption(args.argv, "--temperature"),
+      topP: readNumberOption(args.argv, "--top-p"),
+      maxConcurrentRequests: readNumberOption(args.argv, "--max-concurrent-requests"),
+      systemPrompt: await modelSystemPrompt({ argv: args.argv, model, store }),
+      allowRemote: hasFlag(args.argv, "--allow-remote"),
+      apiKeyEnv: readOption(args.argv, "--api-key-env"),
+      baseModelRevision: (() => {
+        const contract = verified.contract;
+        return typeof contract.base_model_revision === "string" ? contract.base_model_revision : void 0;
+      })(),
+      baseModelArtifactUri: (() => {
+        const contract = verified.contract;
+        return typeof contract.base_model_artifact_uri === "string" ? contract.base_model_artifact_uri : void 0;
+      })()
+    }
+  });
+  if (hasFlag(args.argv, "--print-command")) {
+    printJson({
+      ok: true,
+      model_id: model.id,
+      url: launch.url,
+      command: launch.displayCommand,
+      artifact_path: launch.artifactPath,
+      manifest_path: verified.manifest_path,
+      integrity: verified.integrity
+    });
+    return;
+  }
+  process.stderr.write(`[tt-local] verified ${verified.integrity.checked} artifact file(s)
+`);
+  process.stderr.write(`[tt-local] model API: ${launch.url}
+`);
+  await serveLocalModel(launch);
+}
+function serveOptionsFromArgv(argv) {
+  return {
+    host: readOption(argv, "--host"),
+    port: readNumberOption(argv, "--port"),
+    device: modelServeDevice(argv),
+    maxTokens: readNumberOption(argv, "--max-tokens"),
+    temperature: readNumberOption(argv, "--temperature"),
+    topP: readNumberOption(argv, "--top-p"),
+    maxConcurrentRequests: readNumberOption(argv, "--max-concurrent-requests"),
+    allowRemote: hasFlag(argv, "--allow-remote"),
+    apiKeyEnv: readOption(argv, "--api-key-env")
+  };
+}
+async function serveBaseModelFromCli(args) {
+  const explicitSpecPath = readOption(args.argv, "--spec");
+  if (explicitSpecPath && hasFlag(args.argv, "--no-spec-prompt")) {
+    throw new Error("Use only one of --spec or --no-spec-prompt.");
+  }
+  const defaultSpecPath = resolve3(DEFAULT_LOCAL_SPEC_PATH);
+  const specPath = explicitSpecPath ? resolve3(explicitSpecPath) : (await stat(defaultSpecPath).catch(() => null))?.isFile() ? defaultSpecPath : void 0;
+  const spec = specPath ? localBehaviorSpecFileSchema.parse(
+    JSON.parse(await readFile2(specPath, "utf8"))
+  ) : void 0;
+  let baseModel = spec?.base_model;
+  if (!baseModel) {
+    const store = createLocalStore(args.config.storeRoot);
+    const active = await getActiveModel(store);
+    const referenceModel = active.model ?? (active.pointer?.previous_model_id ? await store.getModel(active.pointer.previous_model_id) : null);
+    baseModel = referenceModel?.base_model;
+  }
+  if (!baseModel) {
+    throw new Error(
+      "Cannot identify the protected base model. Pass --spec <tunedtensor.json> or activate a model first."
+    );
+  }
+  const launch = buildLocalBaseModelServerLaunch({
+    baseModel,
+    config: args.config,
+    options: {
+      ...serveOptionsFromArgv(args.argv),
+      systemPrompt: explicitSpecPath && !hasFlag(args.argv, "--no-spec-prompt") ? buildSystemMessage(spec) : void 0,
+      baseModelRevision: spec?.hyperparameters?.base_model_revision
+    }
+  });
+  if (hasFlag(args.argv, "--print-command")) {
+    printJson({
+      ok: true,
+      model_id: null,
+      base_model: baseModel,
+      url: launch.url,
+      command: launch.displayCommand
+    });
+    return;
+  }
+  process.stderr.write(`[tt-local] protected base model API: ${launch.url}
+`);
+  await serveLocalModel(launch);
+}
+async function serveModelTargetFromCli(args) {
+  if (args.target === "base") {
+    return serveBaseModelFromCli(args);
+  }
+  if (args.target === "active") {
+    const store = createLocalStore(args.config.storeRoot);
+    const active = await getActiveModel(store);
+    if (!active.model) return serveBaseModelFromCli(args);
+    return serveStoredModelFromCli({
+      argv: args.argv,
+      modelId: active.model.id,
+      config: args.config
+    });
+  }
+  return serveStoredModelFromCli({
+    argv: args.argv,
+    modelId: args.target,
+    config: args.config
+  });
+}
+async function main(argv) {
+  const cli = parseCli(argv);
+  const command = cli.command;
+  if (command === "--version" || command === "-V") {
+    console.log(TT_LOCAL_VERSION);
+    return;
+  }
+  if (cli.help === "top" && (argv[2] === "--help" || argv[2] === "-h")) {
+    printHelp();
+    return;
+  }
+  if (cli.help === "group") {
+    printGroupHelp(command, COMMAND_GROUPS[command]);
+    return;
+  }
+  if (cli.help === "command" && cli.definition) {
+    printCommandHelp(cli.definition);
+    return;
+  }
+  if (command === "info") {
+    const info = getLocalRunnerInfo();
+    console.log(`${info.name}: ${info.description}`);
+    console.log(`Version: ${info.version}`);
+    console.log(`Status: ${info.status}`);
+    return;
+  }
+  if (command === "doctor") {
+    const inputPath = resolve3(cli.positionals[0] ?? DEFAULT_LOCAL_SPEC_PATH);
+    const configSelection = await configSelectionFromArgv(argv, inputPath);
+    const hasDefaultSpec = cli.positionals[0] ? true : Boolean((await stat(inputPath).catch(() => null))?.isFile());
+    const request = hasDefaultSpec ? (await loadCliBehaviorSpec(inputPath)).request : void 0;
+    const checks = await runDoctor(configSelection.config, request);
+    const ok = checks.every((check) => check.ok);
+    printJson({
+      ok,
+      config_path: configSelection.path ?? null,
+      checks
+    });
+    if (!ok) process.exitCode = 1;
+    return;
+  }
+  if (command === "init") {
+    const outputPath = resolve3(readOption(argv, "--output") ?? DEFAULT_LOCAL_SPEC_PATH);
+    const profile = readOption(argv, "--profile");
+    if (profile !== void 0 && profile !== "spark") {
+      throw new Error(`--profile must be spark, got: ${profile}`);
+    }
+    const spec = await initLocalSpecFile({
+      outputPath,
+      name: readOption(argv, "--name") ?? "Local Tuned Tensor Spec",
+      baseModel: readOption(argv, "--model") ?? "Qwen/Qwen3.5-2B",
+      force: hasFlag(argv, "--force")
+    });
+    const configPath = profile ? resolve3(readOption(argv, "--config") ?? resolve3(dirname(outputPath), "local-runner.json")) : await selectedConfigPath(argv, outputPath);
+    if (profile) {
+      await initLocalRunnerConfigFile({
+        outputPath: configPath,
+        profile,
+        force: hasFlag(argv, "--force")
+      });
+    } else if (configPath) {
+      await loadLocalRunnerConfig(configPath);
+    }
+    printJson({
+      ok: true,
+      path: outputPath,
+      id: spec.id,
+      name: spec.name,
+      base_model: spec.base_model,
+      config_path: configPath ?? null
+    });
+    return;
+  }
+  if (command === "validate") {
+    const inputPath = resolve3(cli.positionals[0] ?? DEFAULT_LOCAL_SPEC_PATH);
+    const input = await loadCliBehaviorSpec(inputPath);
+    assertLocalRunInputReady(input.request);
+    const configSelection = await configSelectionFromArgv(argv, inputPath);
+    const validated = await validateLocalFineTuneInput({
+      request: input.request,
+      config: configSelection.config
+    });
+    const request = validated.request;
+    const config = validated.config;
+    printJson({
+      ok: true,
+      input_path: input.path,
+      config_path: configSelection.path ?? null,
+      behavior_spec_id: request.behavior_spec_id,
+      base_model: request.spec_snapshot.base_model,
+      dataset_format: request.dataset_prebuilt?.format ?? null,
+      artifact_root: config.artifactRoot,
+      store_root: config.storeRoot,
+      dry_run: config.dryRun
+    });
+    return;
+  }
+  if (command === "run") {
+    const inputPath = resolve3(cli.positionals[0] ?? DEFAULT_LOCAL_SPEC_PATH);
+    const configSelection = await configSelectionFromArgv(argv, inputPath);
+    const configInput = configSelection.config;
+    const config = localRunnerConfigSchema.parse({
+      ...configInput,
+      dryRun: hasFlag(argv, "--dry-run") ? true : configInput.dryRun
+    });
+    const input = await loadCliBehaviorSpec(inputPath);
+    assertLocalRunInputReady(input.request);
+    const validated = await validateLocalFineTuneInput({
+      request: input.request,
+      config
+    });
+    let request = validated.request;
+    const reporter = createConsoleReporter({
+      verbose: hasFlag(argv, "--verbose"),
+      quiet: hasFlag(argv, "--quiet")
+    });
+    if (!config.dryRun && !config.paths.baseModel && !request.hyperparameters.base_model_revision) {
+      const prefetch = await prefetchBaseModel({
+        request,
+        config,
+        reporter
+      });
+      if (!prefetch.snapshot_revision) {
+        throw new Error("Base-model prefetch did not return an immutable snapshot revision.");
+      }
+      request = fineTuneRunRequestSchema.parse({
+        ...request,
+        hyperparameters: {
+          ...request.hyperparameters,
+          base_model_revision: prefetch.snapshot_revision
+        }
+      });
+    }
+    const result = await runLocalFineTune({
+      request,
+      config,
+      reporter
+    });
+    printJson({
+      status: result.report.status,
+      run_id: result.report.run_id,
+      behavior_spec_id: result.report.behavior_spec_id,
+      report_path: result.reportPath,
+      artifact_dir: result.artifactDir,
+      ...!config.dryRun ? {
+        model_id: `local-${result.report.run_id}`,
+        fine_tuned_model_id: result.report.fine_tuned_model_id
+      } : {},
+      training_log: result.report.training.log_uri,
+      baseline_eval: result.report.artifact_uris.baseline_eval,
+      candidate_eval: result.report.artifact_uris.candidate_eval,
+      comparison: result.report.comparison,
+      general_regression: result.report.general_regression
+    });
+    return;
+  }
+  if (command === "serve") {
+    const config = await configFromArgv(argv);
+    await serveModelTargetFromCli({
+      argv,
+      target: cli.positionals[0],
+      config
+    });
+    return;
+  }
+  if (command === "runs") {
+    const subcommand = cli.subcommand;
+    const config = await configFromArgv(argv);
+    const store = createLocalStore(config.storeRoot);
+    if (subcommand === "list") return printJson(await store.listRuns());
+    if (subcommand === "get") {
+      const id = cli.positionals[0];
+      if (!id) throw new Error("runs get requires <run-id>");
+      return printJson(await store.getRun(id));
+    }
+    if (subcommand === "events") {
+      const id = cli.positionals[0];
+      if (!id) throw new Error("runs events requires <run-id>");
+      return printJson(await store.getRunEvents(id));
+    }
+    if (subcommand === "report") {
+      const id = cli.positionals[0];
+      if (!id) throw new Error("runs report requires <run-id>");
+      return printJson(await store.getRunReport(id));
+    }
+    if (subcommand === "compare") {
+      const idA = cli.positionals[0];
+      const idB = cli.positionals[1];
+      if (!idA || !idB) throw new Error("runs compare requires <run-id-a> <run-id-b>");
+      const [reportA, reportB] = await Promise.all([
+        store.getRunReport(idA),
+        store.getRunReport(idB)
+      ]);
+      return printJson(compareRuns(reportA, reportB));
+    }
+    throw new Error(`Unknown runs command: ${subcommand}`);
+  }
+  if (command === "models") {
+    const subcommand = cli.subcommand;
+    const modelInputPath = subcommand === "prefetch" || subcommand === "verify-base" ? resolve3(cli.positionals[0] ?? DEFAULT_LOCAL_SPEC_PATH) : void 0;
+    const config = await configFromArgv(argv, modelInputPath);
+    const store = createLocalStore(config.storeRoot);
+    if (subcommand === "list") return printJson(await store.listModels());
+    if (subcommand === "get") {
+      const id = cli.positionals[0];
+      if (!id) throw new Error("models get requires <model-id>");
+      return printJson(await store.getModel(id));
+    }
+    if (subcommand === "verify") {
+      const id = cli.positionals[0];
+      if (!id) throw new Error("models verify requires <model-id-or-artifact-path>");
+      if (await stat(resolve3(id)).then(() => true, () => false)) {
+        return printJson({ ok: true, model: null, ...await verifyModelArtifactPath(id) });
+      }
+      const model = await store.getModel(id);
+      const verified = await verifyStoredModel(model);
+      return printJson({ ok: true, model, ...verified });
+    }
+    if (subcommand === "active") {
+      const active = await getActiveModel(store);
+      return printJson({
+        active: active.model?.id ?? "base",
+        pointer: active.pointer,
+        model: active.model
+      });
+    }
+    if (subcommand === "activate") {
+      const id = cli.positionals[0];
+      if (!id) throw new Error("models activate requires <model-id>");
+      const model = await store.getModel(id);
+      const verified = await verifyStoredModel(model);
+      await verifyActivationEvidence(model);
+      const pointer = await activateModel(store, model.id);
+      return printJson({
+        active: pointer.model_id,
+        pointer,
+        manifest_path: verified.manifest_path,
+        integrity: verified.integrity
+      });
+    }
+    if (subcommand === "rollback") {
+      const current = await getActiveModel(store);
+      if (current.pointer?.previous_model_id) {
+        const previous = await store.getModel(current.pointer.previous_model_id);
+        await verifyStoredModel(previous);
+        await verifyActivationEvidence(previous);
+      }
+      const pointer = await rollbackActiveModel(store);
+      return printJson({ active: pointer.model_id ?? "base", pointer });
+    }
+    if (subcommand === "prefetch" || subcommand === "verify-base") {
+      const input = await loadCliBehaviorSpec(modelInputPath);
+      const report = await prefetchBaseModel({
+        request: input.request,
+        config,
+        localOnly: subcommand === "verify-base",
+        reporter: createConsoleReporter({
+          verbose: hasFlag(argv, "--verbose"),
+          quiet: hasFlag(argv, "--quiet")
+        })
+      });
+      return printJson({
+        ...report,
+        input_path: input.path
+      });
+    }
+    if (subcommand === "serve") {
+      const id = cli.positionals[0];
+      if (!id) throw new Error("models serve requires <model-id>");
+      await serveModelTargetFromCli({ argv, target: id, config });
+      return;
+    }
+    throw new Error(`Unknown models command: ${subcommand}`);
+  }
+  console.error(`Unknown command: ${command}`);
+  process.exitCode = 1;
+}
+function isCliEntrypoint() {
+  if (!process.argv[1]) return false;
+  return realpathSync(fileURLToPath2(import.meta.url)) === realpathSync(process.argv[1]);
+}
+if (isCliEntrypoint()) {
+  main(process.argv).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}
+export {
+  DEFAULT_LOCAL_SPEC_PATH,
+  TT_LOCAL_VERSION,
+  activateModel,
+  assertLocalRunInputReady,
+  baseModelRevisionSchema,
+  behaviorSpecExampleSchema,
+  buildLocalBaseModelServerLaunch,
+  buildLocalModelServerLaunch,
+  buildModelPrefetchPayload,
+  buildSystemMessage,
+  canonicalLocalPipeline,
+  compareRuns,
+  comparisonReportSchema,
+  compileSpecToJsonl,
+  createLocalStore,
+  datasetFormatSchema,
+  datasetPrebuiltSchema,
+  defaultLocalHome,
+  evalExampleResultSchema,
+  evalReportSchema,
+  evalSplitSchema,
+  evaluateGeneralRegressionGate,
+  evaluationSuiteFromChatJsonl,
+  exampleToChatRow,
+  examplesFromChatJsonl,
+  examplesFromSpec,
+  fineTuneHyperparametersSchema,
+  fineTuneRunRequestSchema,
+  fingerprintLocalBaseModel,
+  forwardStreamLines,
+  generatedPlaceholderIssues,
+  getActiveModel,
+  getLocalRunnerInfo,
+  initLocalRunnerConfigFile,
+  initLocalSpecFile,
+  isTerminalRunState,
+  jsonFieldMetricsSchema,
+  loadJsonFile,
+  loadLocalRunInput,
+  loadLocalRunnerConfig,
+  loadRunRequest,
+  localBehaviorSpecFileSchema,
+  localRunnerConfigSchema,
+  localStorePaths,
+  normalizeChatJsonlForRelocation,
+  prefetchBaseModel,
+  reportInBackground,
+  resolveLocalRunInputPaths,
+  rollbackActiveModel,
+  runLocalFineTune,
+  runLocalPipeline,
+  runReportSchema,
+  runRequestFromLocalSpec,
+  sanitizeLogLine,
+  serveLocalModel,
+  specSnapshotSchema,
+  trainingReportSchema,
+  validateLocalFineTuneInput,
+  validateLocalPipeline,
+  verifyLocalBaseModel
+};
+//# sourceMappingURL=local-runtime.js.map