@tuned-tensor/cli 0.21.0 → 0.22.1

package/dist/index.js

@@ -8,6 +8,7 @@ import {
   TRAINING_MODELS,
   assertFoundationSettingsMatch,
   assessHardware,
+  auditRun,
   buildDecisionPythonCommand,
   buildFoundationPythonCommand,
   buildSystemMessage,
@@ -18,10 +19,12 @@ import {
   configForSpec,
   createExecutionPlan,
   createLocalStore,
+  createRunConsoleReporter,
   decisionLabels,
   defaultLocalHome,
   defaultStoreRoot,
   deriveSampleSeed,
+  ensureDatasetCached,
   evalReportSchema,
   evaluateCapabilities,
   expandUserPath,
@@ -30,6 +33,7 @@ import {
   formatHostStatusLine,
   getAgentConfigDir,
   getConfigDir,
+  getTunedTensorHome,
   hardenExistingLocalStore,
   isFoundationPipeline,
   loadLocalRunInput,
@@ -55,13 +59,13 @@ import {
   warningsFromSnapshot,
   withDecisionPythonEnvironment,
   withFoundationPythonEnvironment
-} from "./chunk-PVLX7LJI.js";
+} from "./chunk-RPWOCVIL.js";
 
 // src/cli.ts
-import { spawn as spawn4 } from "child_process";
+import { spawn as spawn6 } from "child_process";
 import { constants as osConstants2 } from "os";
 import { Command } from "commander";
-import chalk13 from "chalk";
+import chalk15 from "chalk";
 
 // src/local-agent-client.ts
 import { randomUUID as randomUUID5 } from "crypto";
@@ -2163,7 +2167,9 @@ function createTunedTensorTools(api, options = {}) {
           runtime: Type2.Optional(Type2.Union([Type2.Record(Type2.String(), Type2.Unknown()), Type2.Null()])),
           evaluation: Type2.Optional(Type2.Union([Type2.Record(Type2.String(), Type2.Unknown()), Type2.Null()])),
           pipeline: Type2.Optional(Type2.Union([Type2.Record(Type2.String(), Type2.Unknown()), Type2.Null()])),
-          dataset_prebuilt: Type2.Optional(Type2.Record(Type2.String(), Type2.Unknown()))
+          dataset_prebuilt: Type2.Optional(Type2.Record(Type2.String(), Type2.Unknown(), {
+            description: "Local chat JSONL files ({training, validation|test}), or a Hugging Face dataset: {huggingface: {repo, revision?: 40-char commit, columns?: {input, output}}, training: 'repo/path.jsonl', test|validation: ...}. The user downloads it with `tt datasets prefetch tunedtensor.json`."
+          }))
         }, { additionalProperties: false })
       }, { additionalProperties: false }),
       async (p) => {
@@ -3752,6 +3758,8 @@ function gpuDetail(gpu) {
   } else if (gpu.memory_total_bytes !== void 0) {
     const used = gpu.memory_used_bytes;
     parts.push(used === void 0 ? `${formatGiB(gpu.memory_total_bytes)} GiB VRAM` : `VRAM ${formatGiB(used)}/${formatGiB(gpu.memory_total_bytes)} GiB`);
+  } else if (gpu.unified_memory) {
+    parts.push("unified with system RAM");
   }
   if (gpu.temperature_c !== void 0) parts.push(`${Math.round(gpu.temperature_c)}\xB0C`);
   return parts.join("  ");
@@ -3903,6 +3911,7 @@ function renderBanner(input) {
 
 // src/local-runtime/live-usage.ts
 import { execFile } from "child_process";
+import { readFileSync as readFileSync5 } from "fs";
 import { statfs } from "fs/promises";
 import { cpus, freemem, homedir, loadavg, totalmem } from "os";
 import { dirname as dirname3, join as join7, resolve as resolve2 } from "path";
@@ -3974,6 +3983,50 @@ function queryNvidia(env, timeoutMs) {
 function tidyCpuModel(model) {
   return model.replace(/\((?:R|TM|tm|r)\)/g, "").replace(/\s+(?:CPU|Processor)\b/gi, "").replace(/\s*@\s*[\d.]+\s*[GM]Hz/i, "").replace(/\s+\d+-Core$/i, "").replace(/\s+/g, " ").trim() || "CPU";
 }
+var ARM_CORES = {
+  "0xd03": "Cortex-A53",
+  "0xd05": "Cortex-A55",
+  "0xd08": "Cortex-A72",
+  "0xd0b": "Cortex-A76",
+  "0xd0c": "Neoverse-N1",
+  "0xd40": "Neoverse-V1",
+  "0xd41": "Cortex-A78",
+  "0xd44": "Cortex-X1",
+  "0xd47": "Cortex-A710",
+  "0xd48": "Cortex-X2",
+  "0xd49": "Neoverse-N2",
+  "0xd4d": "Cortex-A715",
+  "0xd4e": "Cortex-X3",
+  "0xd4f": "Neoverse-V2",
+  "0xd80": "Cortex-A520",
+  "0xd81": "Cortex-A720",
+  "0xd82": "Cortex-X4",
+  "0xd84": "Neoverse-V3",
+  "0xd85": "Cortex-X925",
+  "0xd87": "Cortex-A725",
+  "0xd8e": "Neoverse-N3"
+};
+function armCpuModel(cpuinfo) {
+  const names = [];
+  let implementer;
+  for (const line of cpuinfo.split(/\r?\n/)) {
+    const [key, value] = line.split(":").map((item) => item.trim().toLowerCase());
+    if (key === "cpu implementer") implementer = value;
+    if (key !== "cpu part" || !value) continue;
+    const name = implementer === "0x41" ? ARM_CORES[value] : void 0;
+    if (name && !names.includes(name)) names.push(name);
+  }
+  return names.length > 0 ? names.join(" + ") : void 0;
+}
+function cpuModel(reported, platform, arch) {
+  const model = tidyCpuModel(reported ?? "");
+  if (platform !== "linux" || !/^(?:unknown|CPU)$/i.test(model)) return model;
+  try {
+    return armCpuModel(readFileSync5("/proc/cpuinfo", "utf8")) ?? (arch === "arm64" ? "Arm CPU" : model);
+  } catch {
+    return arch === "arm64" ? "Arm CPU" : model;
+  }
+}
 async function modelCacheDisk(env) {
   const path = resolve2(env.HF_HOME?.trim() || join7(homedir(), ".cache", "huggingface"));
   for (let probe = path, depth = 0; depth < 8; depth += 1) {
@@ -3992,9 +4045,9 @@ async function modelCacheDisk(env) {
   }
   return void 0;
 }
-function appleGpu(cpuModel, platform, arch) {
+function appleGpu(cpuModel2, platform, arch) {
   if (platform !== "darwin" || arch !== "arm64") return void 0;
-  const chip = /apple/i.test(cpuModel) ? cpuModel.trim() : "Apple Silicon";
+  const chip = /apple/i.test(cpuModel2) ? cpuModel2.trim() : "Apple Silicon";
   return {
     index: 0,
     name: `${chip} GPU`,
@@ -4015,7 +4068,7 @@ async function sampleLiveUsage(options = {}) {
   ]);
   const after = cpuTimes();
   const list = cpus();
-  const model = tidyCpuModel(list[0]?.model ?? "");
+  const model = cpuModel(list[0]?.model, platform, arch);
   const total = totalmem();
   const apple = nvidia.gpus.length === 0 ? appleGpu(model, platform, arch) : void 0;
   const [one, five, fifteen] = loadavg();
@@ -4061,17 +4114,21 @@ var COMMAND_CATALOG = [
   { path: "runs report", description: "Show a local run report.", group: "Inspect", modes: LOCAL },
   { path: "runs compare", description: "Compare two local run reports.", group: "Inspect", modes: LOCAL },
   { path: "runs events", description: "Show local run progress events.", group: "Inspect", modes: LOCAL },
+  { path: "runs audit", description: "Verify a run's event log and report, with timeline and provenance.", group: "Inspect", modes: LOCAL },
   { path: "models list", description: "List local models.", group: "Inspect", modes: LOCAL },
   { path: "models get", description: "Show a local model.", group: "Inspect", modes: LOCAL },
   { path: "models serve", description: "Serve a model through an OpenAI-compatible API.", group: "Serving", modes: LOCAL },
   { path: "models verify", description: "Verify a local model artifact.", group: "Serving", modes: LOCAL },
   { path: "models prefetch", description: "Download the local base-model snapshot.", group: "Serving", modes: LOCAL },
   { path: "models verify-base", description: "Verify the local base-model snapshot.", group: "Serving", modes: LOCAL },
+  { path: "datasets prefetch", description: "Download the spec's Hugging Face dataset files.", group: "Workflow", modes: LOCAL },
+  { path: "datasets verify", description: "Verify the cached Hugging Face dataset files.", group: "Workflow", modes: LOCAL },
   { path: "models active", description: "Show the active local model.", group: "Serving", modes: LOCAL },
   { path: "models activate", description: "Activate a verified local model.", group: "Serving", modes: LOCAL },
   { path: "models rollback", description: "Roll back the active local model.", group: "Serving", modes: LOCAL },
   { path: "serve", description: "Serve a local adapter, active model, or base model.", group: "Serving", modes: LOCAL },
   { path: "info", description: "Show local runtime package information.", group: "Inspect", modes: LOCAL },
+  { path: "upgrade", description: "Upgrade tt to the latest release.", group: "Inspect", modes: LOCAL },
   { path: "status", description: "Show local project context.", group: "Inspect", modes: LOCAL },
   { path: "agent models", description: "List provider models for the laptop-local TT agent.", group: "Inspect", modes: LOCAL },
   { path: "agent configure", description: "Select the laptop-local TT agent model.", group: "Inspect", modes: LOCAL },
@@ -6385,10 +6442,22 @@ function renderValidate(value) {
     ["Spec", text(value.behavior_spec_id)],
     ["Base model", text(value.base_model)],
     ["Dataset", text(value.dataset_format)],
+    ["Hugging Face", huggingFaceDatasetLabel(value)],
     ["Artifacts", text(value.artifact_root)],
     ["Store", text(value.store_root)],
     ["Dry run", text(value.dry_run)]
   ]);
+  if (value.dataset_status === "not_downloaded") {
+    printWarning(`Dataset files are not downloaded yet; dataset contents were not checked. Run \`${text(value.next_step) ?? "tt datasets prefetch"}\`.`);
+  }
+}
+function huggingFaceDatasetLabel(value) {
+  const source = record3(value.dataset_source) ?? record3(value.dataset_huggingface);
+  const repo = text(source?.repo);
+  if (!repo) return void 0;
+  const revision = text(source?.revision) ?? "main";
+  const status2 = value.dataset_status === "not_downloaded" ? "not downloaded" : "cached";
+  return `${repo}@${revision} (${status2}${source?.pinned === false || !text(source?.revision) ? ", unpinned" : ""})`;
 }
 function renderRun(value) {
   const runStatus = text(value.status) ?? "unknown";
@@ -6443,6 +6512,68 @@ function renderRunEvents(value) {
     ])
   );
 }
+function formatSeconds(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "running";
+  const seconds = Math.round(value);
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor(seconds % 3600 / 60);
+  const rest = seconds % 60;
+  if (hours) return `${hours}h ${String(minutes).padStart(2, "0")}m`;
+  if (minutes) return `${minutes}m ${String(rest).padStart(2, "0")}s`;
+  return `${rest}s`;
+}
+function shortHash(value) {
+  const hash = text(value);
+  return hash ? hash.slice(0, 12) : void 0;
+}
+function renderRunAudit(value) {
+  const verdict = text(value.verdict);
+  const chain = record3(value.chain);
+  const reportInfo = record3(value.report);
+  const findings = Array.isArray(value.findings) ? value.findings.map(String) : [];
+  if (verdict === "verified") printSuccess("Run evidence verified: event log intact and report unchanged since completion");
+  else if (verdict === "tampered") printError("Run evidence does not verify");
+  else printWarning("Run evidence is incomplete");
+  for (const finding of findings) console.log(`  - ${finding}`);
+  printDetail([
+    ["Run", text(value.run_id)],
+    ["Status", status(value.status)],
+    ["Event chain", `${text(chain?.status) ?? "\u2014"} (${text(chain?.chained_events) ?? 0}/${text(chain?.events) ?? 0} chained, head ${shortHash(chain?.head_hash) ?? "\u2014"})`],
+    ["Report sha256", shortHash(reportInfo?.recorded_sha256) ?? "not recorded"]
+  ]);
+  const timeline = rows(value.timeline);
+  if (timeline.length > 0) {
+    console.log("");
+    printTable(
+      ["Started", "Stage", "Duration", "Status"],
+      timeline.map((entry) => [
+        formatDate(text(entry.started_at)),
+        text(entry.stage) ?? "\u2014",
+        formatSeconds(entry.duration_seconds),
+        status(entry.status)
+      ])
+    );
+  }
+  const provenance = record3(value.provenance);
+  if (provenance) {
+    const software = record3(provenance.software);
+    const execution = record3(provenance.execution);
+    const spec = record3(provenance.spec);
+    const baseModel = record3(provenance.base_model);
+    const data3 = record3(provenance.data);
+    const files = record3(data3?.file_sha256) ?? {};
+    console.log("");
+    printDetail([
+      ["TT", `${text(software?.tt_version) ?? "\u2014"} (node ${text(software?.node_version) ?? "\u2014"}, ${text(software?.platform) ?? "\u2014"}/${text(software?.arch) ?? "\u2014"})`],
+      ["Execution", `${text(execution?.target) ?? "\u2014"}${text(execution?.instance_id) ? ` ${text(execution?.instance_id)}` : ""} via ${text(execution?.training_backend) ?? "\u2014"}`],
+      ["Spec", `${text(spec?.file_path) ?? text(spec?.behavior_spec_id) ?? "\u2014"} (sha256 ${shortHash(spec?.file_sha256) ?? shortHash(spec?.snapshot_sha256) ?? "\u2014"})`],
+      ["Base model", `${text(baseModel?.id) ?? "\u2014"}@${shortHash(baseModel?.revision) ?? "unpinned"}`],
+      ...Object.entries(files).map(([split, hash]) => [`Data ${split}`, `sha256 ${shortHash(hash)}`]),
+      ["Training data", `sha256 ${shortHash(data3?.compiled_training_sha256) ?? "\u2014"} (${text(data3?.training_examples) ?? "\u2014"} examples)`],
+      ["Evaluation", `${text(data3?.eval_examples_used) ?? "\u2014"}/${text(data3?.eval_examples_total) ?? "\u2014"} ${text(data3?.eval_split) ?? ""} (seed ${text(data3?.eval_sample_seed) ?? "\u2014"})`]
+    ]);
+  }
+}
 function renderRunRecord(value) {
   printDetail([
     ["Run", text(value.id) ?? text(value.run_id)],
@@ -6548,6 +6679,22 @@ function renderModelPrefetch(value) {
     ["Cache", text(value.model_cache) ?? text(value.hf_home)]
   ]);
 }
+function renderDatasetPrefetch(value) {
+  printSuccess(
+    value.local_files_only === true ? "Verified the cached Hugging Face dataset" : "Dataset is ready locally"
+  );
+  const files = record3(value.files) ?? {};
+  printDetail([
+    ["Dataset", text(value.repo)],
+    ["Revision", `${text(value.revision) ?? "\u2014"}${value.pinned === false ? " (unpinned: set dataset_prebuilt.huggingface.revision to pin it)" : ""}`],
+    ...Object.entries(files).map(([split, file]) => {
+      const entry = record3(file);
+      return [split[0].toUpperCase() + split.slice(1), `${text(entry?.path) ?? "\u2014"} (${displayBytes(entry?.size_bytes) ?? "\u2014"}, sha256 ${String(text(entry?.sha256) ?? "").slice(0, 12)})`];
+    }),
+    ["Snapshot", text(value.snapshot_path)],
+    ["Cache", text(value.hub_cache)]
+  ]);
+}
 function renderActiveModel(value) {
   const active = text(value.active) ?? "base";
   const pointer = record3(value.pointer);
@@ -6649,6 +6796,10 @@ function renderKnownJson(args2, value) {
       renderRunEvents(value);
       return true;
     }
+    if (subcommand === "audit" && isRecord4(value)) {
+      renderRunAudit(value);
+      return true;
+    }
     if (subcommand === "get" && isRecord4(value)) {
       renderRunRecord(value);
       return true;
@@ -6685,6 +6836,10 @@ function renderKnownJson(args2, value) {
       return true;
     }
   }
+  if (command === "datasets" && isRecord4(value)) {
+    renderDatasetPrefetch(value);
+    return true;
+  }
   if (command === "serve" && isRecord4(value)) {
     renderServePlan(value);
     return true;
@@ -6862,6 +7017,14 @@ function selectedSpecArgument(args2, cwd) {
   if (command === "models" && ["prefetch", "verify-base"].includes(args2[1] ?? "")) {
     return positionalSpecArgument(args2, 2, join9(cwd, DEFAULT_SPEC_NAME));
   }
+  if (command === "datasets") {
+    if (args2[1] === void 0 || args2[1].startsWith("-") || args2[1].endsWith(".json")) {
+      args2.splice(1, 0, "prefetch");
+    }
+    if (["prefetch", "verify"].includes(args2[1] ?? "")) {
+      return positionalSpecArgument(args2, 2, join9(cwd, DEFAULT_SPEC_NAME));
+    }
+  }
   const serves = command === "serve" || command === "models" && args2[1] === "serve";
   if (!serves) return null;
   const explicit = optionValueArgument(args2, "--spec");
@@ -7002,6 +7165,8 @@ function normalizeProjectedPaths(value, replacements) {
 async function spawnLocalCli(args2) {
   const output = args2.stdout ?? process.stdout;
   const errors = args2.stderr ?? process.stderr;
+  const errorTerminal = errors;
+  const childEnv = errorTerminal.isTTY && !args2.jsonMode && args2.env.TT_PROGRESS_TTY === void 0 ? { ...args2.env, TT_PROGRESS_TTY: "1", TT_PROGRESS_COLUMNS: String(errorTerminal.columns ?? 100) } : args2.env;
   const pipeInput = Boolean(args2.stdin && args2.stdin !== process.stdin);
   const pipeStreamingOutput = args2.streamingStdout && Boolean(args2.stdout && args2.stdout !== process.stdout);
   const child = spawn(
@@ -7009,7 +7174,7 @@ async function spawnLocalCli(args2) {
     [args2.entrypoint, ...args2.commandArgs],
     {
       cwd: args2.cwd,
-      env: args2.env,
+      env: childEnv,
       stdio: [
         pipeInput ? "pipe" : "inherit",
         args2.streamingStdout && !pipeStreamingOutput ? "inherit" : "pipe",
@@ -7173,7 +7338,8 @@ var LOCAL_COMMANDS = [
   "validate",
   "serve",
   "runs",
-  "models"
+  "models",
+  "datasets"
 ];
 var LOCAL_COMMAND_DESCRIPTIONS = {
   info: "Show the installed local runtime version and runner status",
@@ -7183,7 +7349,8 @@ var LOCAL_COMMAND_DESCRIPTIONS = {
   validate: "Validate a local behavior spec without executing it",
   serve: "Serve a verified adapter, the active model, or the protected base",
   runs: "Inspect locally stored runs",
-  models: "Inspect, verify, prefetch, or serve local models"
+  models: "Inspect, verify, prefetch, or serve local models",
+  datasets: "Download or verify the Hugging Face dataset a spec trains on"
 };
 function applyExitCode(result2) {
   if (result2?.exitCode !== null && result2?.exitCode !== void 0) {
@@ -7298,7 +7465,7 @@ function registerAgentCommands(parent, options) {
 }
 
 // src/commands/pipeline.ts
-import { existsSync as existsSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname9, join as join13, resolve as resolve8 } from "path";
 
 // src/local-runtime/project-migration.ts
@@ -8186,7 +8353,7 @@ function loadPipelineFile(path) {
   const resolved = resolve8(path);
   if (!existsSync4(resolved)) throw new Error(`Pipeline file not found: ${path}. Run \`tt pipeline init\` to create one.`);
   try {
-    return JSON.parse(readFileSync5(resolved, "utf8"));
+    return JSON.parse(readFileSync6(resolved, "utf8"));
   } catch (error) {
     throw new Error(`Pipeline file must be JSON: ${error.message}`);
   }
@@ -8202,7 +8369,7 @@ function resolvePipelineDocument(options, specRequired) {
     if (requested !== void 0) return { document: parsePipeline(requested) };
     throw new Error(`Behavior spec not found: ${options.spec}. Create tunedtensor.json or pass an explicit --file for a recipe-only preview.`);
   }
-  const source = readFileSync5(specPath, "utf8");
+  const source = readFileSync6(specPath, "utf8");
   const input = parseLocalRunInput(JSON.parse(source), specPath);
   const document = pipelineForRunInput(input, requested);
   const spec = {
@@ -8260,7 +8427,7 @@ function registerPipelineCommands(parent) {
   pipeline2.command("init").description("Write a canonical v1 pipeline recipe").option("-f, --file <path>", "Legacy standalone recipe output (default: embed in tunedtensor.json)").option("--engine <engine>", "adapter (default) or foundation").option("--spec <path>", "Foundation spec whose hyperparameters stamp the DAG").action(async (options) => {
     if (!options.file) {
       const path2 = resolve8(options.spec ?? DEFAULT_SPEC_FILE);
-      const raw = JSON.parse(readFileSync5(path2, "utf8"));
+      const raw = JSON.parse(readFileSync6(path2, "utf8"));
       const input = parseLocalRunInput(raw, path2);
       if (input.kind === "request") throw new Error("Pipeline init requires a behavior spec.");
       if (options.engine && options.engine !== (input.spec.engine ?? "adapter")) throw new Error("--engine must match the spec.");
@@ -8324,7 +8491,7 @@ function registerPipelineCommands(parent) {
     const plan = createExecutionPlan(document, { only: parseList(options.only), skip: parseList(options.skip) });
     outputPlan({ ...plan, ...spec ? { spec } : {} }, await hostWarningsForPipeline(document, input));
   });
-  pipeline2.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>", "Explicit pipeline recipe (default: derive from behavior spec)").option("--spec <path>", "Local behavior spec", DEFAULT_SPEC_FILE).option("--config <path>", "Local runtime config").option("--output <path>", "Foundation or decision run directory (must not already exist)").option("--resume <path>", "Resume a foundation run directory").option("--only <ids>", "Comma-separated step IDs to include").option("--skip <ids>", "Comma-separated step IDs to omit").action(async (options, command) => {
+  pipeline2.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>", "Explicit pipeline recipe (default: derive from behavior spec)").option("--spec <path>", "Local behavior spec", DEFAULT_SPEC_FILE).option("--config <path>", "Local runtime config").option("--output <path>", "Foundation or decision run directory (must not already exist)").option("--resume <path>", "Resume a foundation run directory").option("--only <ids>", "Comma-separated step IDs to include").option("--skip <ids>", "Comma-separated step IDs to omit").option("--verbose", "Also stream training and evaluation process logs").option("--quiet", "Do not print live stage progress").action(async (options, command) => {
     if (options.output && options.resume) {
       throw new Error("--output and --resume are mutually exclusive.");
     }
@@ -8387,7 +8554,19 @@ function registerPipelineCommands(parent) {
       ...plan.name ? { name: plan.name } : {},
       steps: plan.steps.map(({ transfers: _transfers, ...step }) => step)
     };
-    const result2 = await runLocalPipeline({ request: input.request, config, pipeline: localPipeline, ...input.kind === "spec" ? { projectSpec: input.spec } : {} });
+    const reporter = options.quiet ? void 0 : createRunConsoleReporter({ verbose: options.verbose });
+    const { request: request2 } = await ensureDatasetCached({ request: input.request, config, reporter });
+    const result2 = await runLocalPipeline({
+      request: request2,
+      config,
+      pipeline: localPipeline,
+      ...input.kind === "spec" ? { projectSpec: input.spec } : {},
+      ...spec ? { specFile: { path: spec.path, sha256: spec.sha256 } } : {},
+      ...reporter ? { reporter } : {}
+    });
+    if (!isJsonMode()) {
+      console.error(`Run ${result2.request.run_id}: \`tt runs audit ${result2.request.run_id}\` verifies its record and shows timing and provenance.`);
+    }
     if (isJsonMode()) return printJson({ ...result2, spec });
     printSuccess(`Pipeline completed with status ${result2.status}.`);
   });
@@ -8660,7 +8839,7 @@ function registerTopupCommands(parent) {
 
 // src/commands/publish.ts
 import { createInterface as createInterface4 } from "readline/promises";
-import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync7 } from "fs";
 import { homedir as homedir3 } from "os";
 import { isAbsolute as isAbsolute5, join as join14, resolve as resolve9 } from "path";
 import { stdin as defaultStdin, stdout as defaultStdout } from "process";
@@ -8677,13 +8856,13 @@ function resolvePublishStoreRoot(options) {
   const localConfigPath = join14(cwd, "local-runner.json");
   const projectPath = join14(cwd, "tunedtensor.json");
   if (existsSync5(projectPath)) {
-    const spec = localBehaviorSpecFileSchema.parse(JSON.parse(readFileSync6(projectPath, "utf8")));
+    const spec = localBehaviorSpecFileSchema.parse(JSON.parse(readFileSync7(projectPath, "utf8")));
     if (existsSync5(localConfigPath) && (spec.runtime || spec.evaluation)) throw new Error("Conflicting configuration sources; migrate local-runner.json first.");
     if (!existsSync5(localConfigPath)) return expandPath2(spec.runtime?.storeRoot ?? (env.TT_LOCAL_HOME?.trim() || DEFAULT_PROJECT_STORE_ROOT), cwd, homeDirectory);
   }
   if (existsSync5(localConfigPath)) {
     try {
-      const raw = JSON.parse(readFileSync6(localConfigPath, "utf-8"));
+      const raw = JSON.parse(readFileSync7(localConfigPath, "utf-8"));
       if (typeof raw.storeRoot === "string" && raw.storeRoot.trim()) {
         return expandPath2(raw.storeRoot, cwd, homeDirectory);
       }
@@ -8747,7 +8926,7 @@ function assertPublishPayloadSize(payload) {
   }
 }
 function registerPublishCommand(parent) {
-  parent.command("publish").description("Publish local run evidence to the Tuned Tensor dashboard").argument("[runId]", "Local run id or prefix (defaults to latest completed/failed run)").option("-k, --api-key <key>", "API key (tt_...)").option("-u, --base-url <url>", "API base URL").option("-y, --yes", "Skip confirmation prompt").option("--dry-run", "Show what would be published without uploading").action(async (runId, cmdOpts) => {
+  parent.command("publish").description("Publish local run evidence to the Tuned Tensor dashboard").argument("[runId]", "Local run id or prefix (defaults to latest completed/failed run)").option("-k, --api-key <key>", "API key (tt_...)").option("-u, --base-url <url>", "API base URL").option("-y, --yes", "Skip confirmation prompt").option("--dry-run", "Show what would be published without uploading").option("--allow-unverified", "Publish evidence that cannot be fully verified (older TT versions, unreadable events)").action(async (runId, cmdOpts) => {
     const inherited = parent.optsWithGlobals();
     const opts = {
       apiKey: cmdOpts.apiKey ?? inherited.apiKey,
@@ -8766,12 +8945,27 @@ function registerPublishCommand(parent) {
     const report = runReportSchema.parse(rawReport);
     const specRecord = await store.getSpec(run.behavior_spec_id);
     const exampleCount = report.candidate.results.length || report.baseline.results.length;
+    const audit = await auditRun(store, run.id);
+    if (audit.verdict === "tampered") {
+      throw new Error(
+        `Run ${run.id} evidence does not verify: ${audit.findings.join(" ")} Inspect it with \`tt runs audit ${run.id}\`; tampered runs are not published.`
+      );
+    }
     const payload = {
       spec: {
         id: specRecord.id,
         ...specRecord.spec
       },
-      report
+      report: {
+        ...report,
+        audit: {
+          verdict: audit.verdict,
+          findings: audit.findings,
+          event_chain: { status: audit.chain.status, events: audit.chain.events, head_hash: audit.chain.head_hash },
+          report_sha256: audit.report.recorded_sha256,
+          timeline: audit.timeline
+        }
+      }
     };
     assertPublishPayloadSize(payload);
     if (isJsonMode() && cmdOpts.dryRun) {
@@ -8799,6 +8993,14 @@ function registerPublishCommand(parent) {
       printWarning(
         "Prompts and model outputs from the run report will be uploaded to your Tuned Tensor account."
       );
+      if (audit.verdict !== "verified") {
+        printWarning(`Run evidence is unverified: ${audit.findings.join(" ")}`);
+      }
+    }
+    if (audit.verdict !== "verified" && !cmdOpts.allowUnverified && !cmdOpts.dryRun) {
+      throw new Error(
+        `Run ${run.id} evidence cannot be fully verified: ${audit.findings.join(" ")} Review it with \`tt runs audit\`, then pass --allow-unverified to publish it anyway; the dashboard will show it as unverified.`
+      );
     }
     if (cmdOpts.dryRun) {
       if (isJsonMode()) {
@@ -8843,7 +9045,7 @@ function registerPublishCommand(parent) {
 }
 
 // src/commands/specs.ts
-import { readFileSync as readFileSync7 } from "fs";
+import { readFileSync as readFileSync8 } from "fs";
 
 // src/resolve.ts
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -8947,7 +9149,7 @@ var SpecBodyError = class extends Error {
 function loadSpecBody(filePath, mode) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync7(filePath, "utf-8"));
+    parsed = JSON.parse(readFileSync8(filePath, "utf-8"));
   } catch (e) {
     throw new SpecBodyError(
       `Could not parse ${filePath}: ${e.message}`
@@ -9076,7 +9278,7 @@ function registerSpecsCommands(parent) {
 }
 
 // src/commands/datasets.ts
-import { existsSync as existsSync6, readFileSync as readFileSync8, statSync as statSync2 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync9, statSync as statSync2 } from "fs";
 var DOCUMENT_OCR_MIME_TYPES = /* @__PURE__ */ new Set(["image/png", "image/jpeg", "image/webp"]);
 function formatBytes(bytes) {
   if (bytes < 1024) return `${bytes} B`;
@@ -9206,7 +9408,7 @@ function parseDatasetFormat(value) {
   throw new Error("--format must be one of: jsonl, document_ocr_jsonl");
 }
 function validateDatasetFile(file, requestedFormat) {
-  const lines = readFileSync8(file, "utf8").split(/\r?\n/);
+  const lines = readFileSync9(file, "utf8").split(/\r?\n/);
   const errors = [];
   let rowCount = 0;
   let detectedFormat = null;
@@ -9338,7 +9540,7 @@ function registerDatasetsCommands(parent) {
     }
     const format = validateDatasetFile(file, parseDatasetFormat(cmdOpts.format));
     const name = cmdOpts.name || file.split("/").pop().replace(/\.jsonl?$/, "");
-    const fileBytes = readFileSync8(file);
+    const fileBytes = readFileSync9(file);
     const uploadUrl = await post(
       "/datasets/upload-url",
       {
@@ -9383,7 +9585,7 @@ function registerDatasetsCommands(parent) {
 }
 
 // src/commands/label.ts
-import { existsSync as existsSync7, readFileSync as readFileSync9, statSync as statSync3 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync10, statSync as statSync3 } from "fs";
 function formatCents2(cents) {
   return `$${(cents / 100).toFixed(2)}`;
 }
@@ -9427,7 +9629,7 @@ function validateUnlabeledFile(file, inputColumn) {
         "CSV uploads need --input-column <name> to say which column holds the input text."
       );
     }
-    const firstLine = readFileSync9(file, "utf8").split(/\r?\n/, 1)[0] ?? "";
+    const firstLine = readFileSync10(file, "utf8").split(/\r?\n/, 1)[0] ?? "";
     const columns = parseCsvHeader(firstLine);
     if (!columns.includes(inputColumn)) {
       throw new Error(
@@ -9439,7 +9641,7 @@ function validateUnlabeledFile(file, inputColumn) {
   if (!lower.endsWith(".jsonl") && !lower.endsWith(".json")) {
     throw new Error("Labeling source file must be .jsonl or .csv");
   }
-  const lines = readFileSync9(file, "utf8").split(/\r?\n/);
+  const lines = readFileSync10(file, "utf8").split(/\r?\n/);
   const errors = [];
   let rowCount = 0;
   for (const [index, rawLine] of lines.entries()) {
@@ -9562,7 +9764,7 @@ function registerLabelCommands(parent) {
     const { format } = validateUnlabeledFile(file, cmdOpts.inputColumn);
     const specId = await resolveSpecId(cmdOpts.spec, opts);
     const name = cmdOpts.name || file.split("/").pop().replace(/\.(jsonl|json|csv)$/, "");
-    const fileBytes = readFileSync9(file);
+    const fileBytes = readFileSync10(file);
     const contentType = format === "csv" ? "text/csv" : "application/jsonl";
     const { data: uploadUrl } = await post(
       "/labeling-jobs/upload-url",
@@ -9735,7 +9937,7 @@ function registerLabelCommands(parent) {
       printError("Provide --output <text> or --file <path>.");
       process.exit(1);
     }
-    const output = cmdOpts.output ?? readFileSync9(cmdOpts.file, "utf8");
+    const output = cmdOpts.output ?? readFileSync10(cmdOpts.file, "utf8");
     const jobId = await resolveLabelingJobId(id, opts);
     const indexes = parseIndexList(cmdOpts.row);
     const rowIds = await resolveRowIds(jobId, indexes, opts);
@@ -10225,7 +10427,7 @@ import {
   statSync as statSync4,
   createWriteStream,
   unlinkSync,
-  readFileSync as readFileSync11,
+  readFileSync as readFileSync12,
   writeFileSync as writeFileSync5,
   readdirSync,
   rmSync
@@ -10236,7 +10438,7 @@ import { Readable, Transform } from "stream";
 import { pipeline } from "stream/promises";
 
 // src/commands/init.ts
-import { existsSync as existsSync8, readFileSync as readFileSync10, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync8, readFileSync as readFileSync11, writeFileSync as writeFileSync4 } from "fs";
 import { resolve as resolve10 } from "path";
 var DEFAULT_SPEC_FILE2 = "tunedtensor.json";
 function loadSpec(filePath) {
@@ -10248,7 +10450,7 @@ Run \`tt init\` to create one.`
     );
     process.exit(1);
   }
-  const raw = JSON.parse(readFileSync10(resolved, "utf-8"));
+  const raw = JSON.parse(readFileSync11(resolved, "utf-8"));
   return raw;
 }
 
@@ -11462,7 +11664,7 @@ function findSpecPath(explicitPath, modelPath) {
   return null;
 }
 function loadSystemPromptFromSpec(specPath) {
-  const spec = JSON.parse(readFileSync11(specPath, "utf8"));
+  const spec = JSON.parse(readFileSync12(specPath, "utf8"));
   return buildSystemPrompt(spec);
 }
 function loadJsonSchemaForServe(schemaPath) {
@@ -11471,7 +11673,7 @@ function loadJsonSchemaForServe(schemaPath) {
     throw new Error(`JSON schema file not found: ${schemaPath}`);
   }
   try {
-    const schema = JSON.parse(readFileSync11(resolved, "utf8"));
+    const schema = JSON.parse(readFileSync12(resolved, "utf8"));
     return JSON.stringify(schema);
   } catch (err) {
     throw new Error(`JSON schema file is not valid JSON: ${schemaPath}`);
@@ -12099,10 +12301,10 @@ function registerModelsCommands(parent) {
 }
 
 // src/commands/push.ts
-import { readFileSync as readFileSync12, writeFileSync as writeFileSync6 } from "fs";
+import { readFileSync as readFileSync13, writeFileSync as writeFileSync6 } from "fs";
 import { resolve as resolve12 } from "path";
 function persistRemoteId(filePath, id) {
-  const raw = JSON.parse(readFileSync12(filePath, "utf-8"));
+  const raw = JSON.parse(readFileSync13(filePath, "utf-8"));
   raw.id = id;
   writeFileSync6(filePath, JSON.stringify(raw, null, 2) + "\n");
 }
@@ -12185,8 +12387,20 @@ function registerUsageCommand(parent) {
   });
 }
 
+// src/commands/upgrade.ts
+import { spawn as spawn5 } from "child_process";
+import { accessSync, constants as constants3, existsSync as existsSync10, readFileSync as readFileSync15, realpathSync } from "fs";
+import { dirname as dirname13, join as join17 } from "path";
+import chalk14 from "chalk";
+
 // src/update-check.ts
+import { spawn as spawn4 } from "child_process";
+import { mkdirSync as mkdirSync5, readFileSync as readFileSync14, writeFileSync as writeFileSync7 } from "fs";
+import { dirname as dirname12, join as join16 } from "path";
+import chalk13 from "chalk";
+var CLI_PACKAGE_NAME = "@tuned-tensor/cli";
 var PACKAGE_LATEST_URL = "https://registry.npmjs.org/@tuned-tensor%2fcli/latest";
+var DEFAULT_CACHE_MAX_AGE_MS = 12 * 60 * 60 * 1e3;
 function parseVersion(version) {
   const match = version.trim().match(
     /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
@@ -12230,11 +12444,50 @@ function compareVersions(left, right) {
   }
   return comparePrerelease(left.prerelease, right.prerelease);
 }
-async function checkForCliUpdate(currentVersion, options = {}) {
+function getCliUpdateCacheFile(env = process.env) {
+  return join16(getTunedTensorHome(env), "update-check.json");
+}
+function cliUpdateChecksDisabled(env = process.env) {
+  return [env.TT_NO_UPDATE_CHECK, env.NO_UPDATE_NOTIFIER, env.CI].some((value) => value !== void 0 && value !== "" && value !== "0" && value !== "false");
+}
+function readUpdateCache(file) {
+  try {
+    const payload = JSON.parse(readFileSync14(file, "utf8"));
+    if (typeof payload.checkedAt !== "number" || typeof payload.latestVersion !== "string" || !parseVersion(payload.latestVersion)) return null;
+    return { checkedAt: payload.checkedAt, latestVersion: payload.latestVersion };
+  } catch {
+    return null;
+  }
+}
+function writeUpdateCache(file, cache) {
+  try {
+    mkdirSync5(dirname12(file), { recursive: true });
+    writeFileSync7(file, `${JSON.stringify(cache)}
+`);
+  } catch {
+  }
+}
+function recordLatestCliVersion(cacheFile, latestVersion, now = Date.now()) {
+  writeUpdateCache(cacheFile, { checkedAt: now, latestVersion });
+}
+function compareCliVersions(left, right) {
+  const parsedLeft = parseVersion(left);
+  const parsedRight = parseVersion(right);
+  if (!parsedLeft || !parsedRight) return null;
+  return compareVersions(parsedLeft, parsedRight);
+}
+function newerStableRelease(currentVersion, latestVersion) {
+  if (!latestVersion) return null;
   const current = parseVersion(currentVersion);
-  if (!current) return null;
+  const latest = parseVersion(latestVersion);
+  if (!current || !latest || latest.prerelease.length > 0 || compareVersions(latest, current) <= 0) return null;
+  return { currentVersion, latestVersion };
+}
+async function fetchLatestCliVersion(options = {}) {
   const controller = new AbortController();
-  const timeoutMs = options.timeoutMs ?? 750;
+  const abort = () => controller.abort();
+  options.signal?.addEventListener("abort", abort, { once: true });
+  const timeoutMs = options.timeoutMs ?? 1500;
   let timeout;
   const request2 = (async () => {
     try {
@@ -12246,11 +12499,7 @@ async function checkForCliUpdate(currentVersion, options = {}) {
       const payload = await response.json();
       if (typeof payload.version !== "string") return null;
       const latest = parseVersion(payload.version);
-      if (!latest || latest.prerelease.length > 0 || compareVersions(latest, current) <= 0) return null;
-      return {
-        currentVersion,
-        latestVersion: payload.version
-      };
+      return latest && latest.prerelease.length === 0 ? payload.version : null;
     } catch {
       return null;
     }
@@ -12265,15 +12514,211 @@ async function checkForCliUpdate(currentVersion, options = {}) {
     return await Promise.race([request2, deadline]);
   } finally {
     if (timeout) clearTimeout(timeout);
+    options.signal?.removeEventListener("abort", abort);
+  }
+}
+function cachedCliUpdate(currentVersion, cacheFile) {
+  return newerStableRelease(currentVersion, readUpdateCache(cacheFile)?.latestVersion);
+}
+function cliUpdateCacheIsStale(cacheFile, options = {}) {
+  const cache = readUpdateCache(cacheFile);
+  const now = (options.now ?? Date.now)();
+  return !cache || now - cache.checkedAt >= (options.cacheMaxAgeMs ?? DEFAULT_CACHE_MAX_AGE_MS);
+}
+async function refreshCliUpdateCache(cacheFile, options = {}) {
+  const latest = await fetchLatestCliVersion(options);
+  if (latest) recordLatestCliVersion(cacheFile, latest, (options.now ?? Date.now)());
+  return latest;
+}
+var REFRESH_SCRIPT = `
+const [url, file] = process.argv.slice(1);
+const fs = require("node:fs");
+const path = require("node:path");
+fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10000) })
+  .then((response) => response.ok ? response.json() : null)
+  .then((payload) => {
+    if (!payload || typeof payload.version !== "string") return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ checkedAt: Date.now(), latestVersion: payload.version }) + "\\n");
+  })
+  .catch(() => {});
+`;
+function spawnCliUpdateRefresh(cacheFile) {
+  const cached = readUpdateCache(cacheFile);
+  if (cached) recordLatestCliVersion(cacheFile, cached.latestVersion);
+  try {
+    const child = spawn4(
+      process.execPath,
+      ["-e", REFRESH_SCRIPT, PACKAGE_LATEST_URL, cacheFile],
+      { detached: true, stdio: "ignore", windowsHide: true }
+    );
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
   }
 }
+async function checkForCliUpdate(currentVersion, options = {}) {
+  if (!parseVersion(currentVersion)) return null;
+  const { cacheFile } = options;
+  if (cacheFile && !cliUpdateCacheIsStale(cacheFile, options)) {
+    return cachedCliUpdate(currentVersion, cacheFile);
+  }
+  const latest = cacheFile ? await refreshCliUpdateCache(cacheFile, options) : await fetchLatestCliVersion(options);
+  return newerStableRelease(
+    currentVersion,
+    latest ?? (cacheFile ? readUpdateCache(cacheFile)?.latestVersion : void 0)
+  );
+}
 function formatCliUpdateNotice(update) {
   return [
-    `Update available: tt ${update.currentVersion} \u2192 ${update.latestVersion}`,
-    "Upgrade with: npm install -g @tuned-tensor/cli@latest"
+    chalk13.yellow(`Update available: tt ${update.currentVersion} \u2192 ${chalk13.bold(update.latestVersion)}`),
+    `Run ${chalk13.bold("tt upgrade")} to install it.`
   ].join("\n");
 }
 
+// src/commands/upgrade.ts
+function resolveGlobalInstall(entrypoint, platform = process.platform) {
+  if (!entrypoint) return null;
+  let script;
+  try {
+    script = realpathSync(entrypoint);
+  } catch {
+    return null;
+  }
+  if (/[\\/]_npx[\\/]/.test(script)) return null;
+  const match = platform === "win32" ? script.match(/^(.*)\\node_modules\\@tuned-tensor\\cli\\dist\\index\.js$/i) : script.match(/^(.*)\/lib\/node_modules\/@tuned-tensor\/cli\/dist\/index\.js$/);
+  if (!match?.[1]) return null;
+  return { prefix: match[1], packageDir: dirname13(dirname13(script)) };
+}
+function prefixIsWritable(prefix, platform) {
+  const modules = platform === "win32" ? join17(prefix, "node_modules") : join17(prefix, "lib", "node_modules");
+  try {
+    accessSync(existsSync10(modules) ? modules : prefix, constants3.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function installedVersion(packageDir) {
+  try {
+    const manifest = JSON.parse(readFileSync15(join17(packageDir, "package.json"), "utf8"));
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function quoteForCmd(arg) {
+  return /[\s"&|<>^]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg;
+}
+function defaultNpmRunner(platform) {
+  return async (args2) => await new Promise((resolve13, reject) => {
+    const windows = platform === "win32";
+    const child = spawn5(
+      windows ? "npm.cmd" : "npm",
+      windows ? args2.map(quoteForCmd) : args2,
+      {
+        shell: windows,
+        // Keep stdout clean for --json; npm progress goes to stderr.
+        stdio: ["ignore", isJsonMode() ? 2 : "inherit", "inherit"]
+      }
+    );
+    child.once("error", reject);
+    child.once("close", (code2) => resolve13(code2 ?? 1));
+  });
+}
+function formatCommand(args2) {
+  return ["npm", ...args2].map((arg) => /\s/.test(arg) ? JSON.stringify(arg) : arg).join(" ");
+}
+function registerUpgradeCommand(program, deps) {
+  program.command("upgrade").alias("update").description("Upgrade tt to the latest release").argument("[version]", "Version or npm dist-tag to install (default: latest)").option("--check", "Only report whether an update is available").addHelpText(
+    "after",
+    `
+Examples:
+  tt upgrade             Install the latest stable release
+  tt upgrade --check     Report whether a newer release exists
+  tt upgrade beta        Opt in to the beta channel
+  tt upgrade 0.21.0      Install a specific version
+
+Set TT_NO_UPDATE_CHECK=1 to silence update notices.
+`
+  ).action(async (requested, options) => {
+    const platform = deps.platform ?? process.platform;
+    const cacheFile = getCliUpdateCacheFile(deps.env);
+    const current = deps.version;
+    const target = requested?.trim() || "latest";
+    let latest;
+    if (target === "latest") {
+      latest = await fetchLatestCliVersion({ fetchImpl: deps.fetchImpl, timeoutMs: 1e4 }) ?? void 0;
+      if (!latest) {
+        throw new Error(
+          "Could not reach the npm registry to look up the latest tt release. Check your connection and try again."
+        );
+      }
+      recordLatestCliVersion(cacheFile, latest);
+      const comparison = compareCliVersions(latest, current);
+      if (comparison !== null && comparison <= 0) {
+        if (isJsonMode()) {
+          printJson({ current_version: current, latest_version: latest, update_available: false });
+        } else {
+          printSuccess(`tt ${current} is the latest version.`);
+        }
+        return;
+      }
+    }
+    if (options.check) {
+      if (isJsonMode()) {
+        printJson({ current_version: current, latest_version: latest ?? null, update_available: Boolean(latest) });
+      } else if (latest) {
+        console.log(`Update available: tt ${current} \u2192 ${chalk14.bold(latest)}`);
+        console.log(`Run ${chalk14.bold("tt upgrade")} to install it.`);
+      } else {
+        console.log(`tt ${current} is installed. Run ${chalk14.bold(`tt upgrade ${target}`)} to install ${target}.`);
+      }
+      return;
+    }
+    const install = resolveGlobalInstall(deps.entrypoint, platform);
+    const packageSpec = `${CLI_PACKAGE_NAME}@${target}`;
+    if (!install) {
+      throw new Error(
+        `This tt (${deps.entrypoint ?? "unknown path"}) was not installed with npm -g, so it can't upgrade itself.
+Upgrade it the way you installed it, for example:
+  npm install -g --ignore-scripts ${packageSpec}`
+      );
+    }
+    const npmArgs = ["install", "-g", "--ignore-scripts", "--prefix", install.prefix, packageSpec];
+    if (!prefixIsWritable(install.prefix, platform)) {
+      throw new Error(
+        `tt is installed in ${install.prefix}, which this user can't write to. Run:
+  sudo ${formatCommand(npmArgs)}`
+      );
+    }
+    if (!isJsonMode()) {
+      console.log(`Upgrading tt ${current} \u2192 ${chalk14.bold(latest ?? target)}`);
+      console.log(chalk14.dim(`$ ${formatCommand(npmArgs)}`));
+    }
+    let code2;
+    try {
+      code2 = await (deps.runNpm ?? defaultNpmRunner(platform))(npmArgs);
+    } catch (error) {
+      throw new Error(
+        `Could not run npm (${error instanceof Error ? error.message : String(error)}). Run it yourself:
+  ${formatCommand(npmArgs)}`
+      );
+    }
+    if (code2 !== 0) {
+      throw new Error(`npm exited with code ${code2}. Run it yourself to see details:
+  ${formatCommand(npmArgs)}`);
+    }
+    const installed = installedVersion(install.packageDir) ?? latest ?? target;
+    if (isJsonMode()) {
+      printJson({ previous_version: current, version: installed, prefix: install.prefix });
+    } else {
+      printSuccess(`Upgraded tt ${current} \u2192 ${installed}. Restart any open tt sessions to use it.`);
+    }
+  });
+}
+
 // src/cli.ts
 function createAccountToolApi(opts) {
   return {
@@ -12384,7 +12829,7 @@ async function runSelfCommand(args2, options = {}) {
     throw new Error("Cannot locate the tt CLI entrypoint.");
   }
   return await new Promise((resolve13, reject) => {
-    const child = spawn4(process.execPath, [entrypoint, ...args2], {
+    const child = spawn6(process.execPath, [entrypoint, ...args2], {
       cwd: options.cwd,
       env: options.env ?? process.env,
       stdio: "inherit",
@@ -12486,7 +12931,7 @@ function createProgram(version, runtime = {}) {
     if (root.json) setJsonMode(true);
     if (root.color === false) {
       process.env.FORCE_COLOR = "0";
-      chalk13.level = 0;
+      chalk15.level = 0;
     }
   });
   registerLocalCommands(program, {
@@ -12505,6 +12950,11 @@ function createProgram(version, runtime = {}) {
   registerUsageCommand(program);
   registerPublishCommand(program);
   registerCloudCommands(program);
+  registerUpgradeCommand(program, {
+    version,
+    entrypoint: runtime.argv?.[1] ?? process.argv[1],
+    env
+  });
   registerAgentCommands(program, {
     get env() {
       return childEnvironment2(program.opts(), env);
@@ -12524,12 +12974,12 @@ function createProgram(version, runtime = {}) {
 `);
       return;
     }
-    output.write(`${chalk13.bold.hex("#8B5CF6")("Tuned Tensor status")}
+    output.write(`${chalk15.bold.hex("#8B5CF6")("Tuned Tensor status")}
 `);
     output.write(`${formatShellStatus(context).join("\n")}
 
 `);
-    output.write(`${chalk13.bold("Context")}
+    output.write(`${chalk15.bold("Context")}
 `);
     output.write(`${formatShellContext(context).join("\n")}
 `);
@@ -12585,7 +13035,11 @@ async function runCli(version, runtime = {}) {
     const error = runtime.stderr ?? process.stderr;
     let update = null;
     try {
-      update = await (runtime.checkForUpdate ?? checkForCliUpdate)(version);
+      if (runtime.checkForUpdate) {
+        update = await runtime.checkForUpdate(version);
+      } else if (!cliUpdateChecksDisabled(env)) {
+        update = await checkForCliUpdate(version, { cacheFile: getCliUpdateCacheFile(env) });
+      }
     } catch {
     }
     if (update) {
@@ -12626,11 +13080,29 @@ async function runCli(version, runtime = {}) {
     return;
   }
   if (argv.includes("--json")) setJsonMode(true);
-  await createProgram(version, { ...runtime, argv }).parseAsync(argv);
+  const notifier = startCommandUpdateNotifier(version, args2, runtime, env);
+  try {
+    await createProgram(version, { ...runtime, argv }).parseAsync(argv);
+  } finally {
+    notifier?.();
+  }
+}
+function startCommandUpdateNotifier(version, args2, runtime, env) {
+  const error = runtime.stderr ?? process.stderr;
+  if (runtime.checkForUpdate || error.isTTY !== true || cliUpdateChecksDisabled(env) || args2.some((arg) => ["--json", "--version", "-V", "--help", "-h"].includes(arg)) || ["upgrade", "update", "help"].includes(args2[0] ?? "")) return null;
+  const cacheFile = getCliUpdateCacheFile(env);
+  if (cliUpdateCacheIsStale(cacheFile)) spawnCliUpdateRefresh(cacheFile);
+  return () => {
+    if (isJsonMode()) return;
+    const update = cachedCliUpdate(version, cacheFile);
+    if (update) error.write(`
+${formatCliUpdateNotice(update)}
+`);
+  };
 }
 
 // src/index.ts
-runCli("0.21.0").catch((err) => {
+runCli("0.22.1").catch((err) => {
   reportError(err);
   process.exit(1);
 });