@tuned-tensor/cli 0.4.24 → 0.5.0

package/dist/index.js

@@ -1,7 +1,162 @@
 #!/usr/bin/env node
 
-// src/index.ts
+// src/cli.ts
+import { spawn as spawn4 } from "child_process";
+import { constants as osConstants2 } from "os";
 import { Command } from "commander";
+import chalk7 from "chalk";
+
+// src/local-runner.ts
+import { constants as osConstants } from "os";
+import { randomUUID } from "crypto";
+import { createRequire } from "module";
+import { spawn } from "child_process";
+import {
+  readFile,
+  rm,
+  stat,
+  writeFile
+} from "fs/promises";
+import {
+  basename as basename2,
+  dirname,
+  isAbsolute,
+  join as join2,
+  resolve
+} from "path";
+
+// src/base-models.ts
+var SUPPORTED_BASE_MODELS = [
+  "google/gemma-4-E2B-it",
+  "google/gemma-4-E4B-it",
+  "Qwen/Qwen3.5-2B",
+  "Qwen/Qwen3-VL-2B-Instruct",
+  "Qwen/Qwen3.5-4B",
+  "meta-llama/Llama-3.2-3B-Instruct",
+  "microsoft/Phi-4-mini-instruct",
+  "ibm-granite/granite-3.3-2b-instruct",
+  "bigcode/starcoder2-3b"
+];
+var BASE_MODEL_ALIASES = /* @__PURE__ */ new Map();
+for (const model of SUPPORTED_BASE_MODELS) {
+  BASE_MODEL_ALIASES.set(model.toLowerCase(), model);
+}
+for (const [alias, model] of [
+  ["google/gemma-4-E2B", "google/gemma-4-E2B-it"],
+  ["google/gemma-4-e2b", "google/gemma-4-E2B-it"],
+  ["google/gemma-4-e2b-it", "google/gemma-4-E2B-it"],
+  ["google/gemma-4-E4B", "google/gemma-4-E4B-it"],
+  ["google/gemma-4-e4b", "google/gemma-4-E4B-it"],
+  ["google/gemma-4-e4b-it", "google/gemma-4-E4B-it"],
+  ["qwen/qwen3.5-2b", "Qwen/Qwen3.5-2B"],
+  ["Qwen/Qwen3.5-2B-Base", "Qwen/Qwen3.5-2B"],
+  ["qwen/qwen3.5-2b-base", "Qwen/Qwen3.5-2B"],
+  ["qwen/qwen3-vl-2b-instruct", "Qwen/Qwen3-VL-2B-Instruct"],
+  ["Qwen/Qwen3-VL-2B", "Qwen/Qwen3-VL-2B-Instruct"],
+  ["qwen/qwen3-vl-2b", "Qwen/Qwen3-VL-2B-Instruct"],
+  ["qwen/qwen3.5-4b", "Qwen/Qwen3.5-4B"],
+  ["Qwen/Qwen3.5-4B-Base", "Qwen/Qwen3.5-4B"],
+  ["qwen/qwen3.5-4b-base", "Qwen/Qwen3.5-4B"],
+  ["meta-llama/llama-3.2-3b-instruct", "meta-llama/Llama-3.2-3B-Instruct"],
+  ["meta-llama/Llama-3.2-3B", "meta-llama/Llama-3.2-3B-Instruct"],
+  ["meta-llama/llama-3.2-3b", "meta-llama/Llama-3.2-3B-Instruct"],
+  ["microsoft/phi-4-mini-instruct", "microsoft/Phi-4-mini-instruct"],
+  ["phi-4-mini-instruct", "microsoft/Phi-4-mini-instruct"],
+  ["ibm-granite/granite-3.3-2b-instruct", "ibm-granite/granite-3.3-2b-instruct"],
+  ["granite-3.3-2b-instruct", "ibm-granite/granite-3.3-2b-instruct"],
+  ["bigcode/starcoder2-3b", "bigcode/starcoder2-3b"],
+  ["starcoder2-3b", "bigcode/starcoder2-3b"]
+]) {
+  BASE_MODEL_ALIASES.set(alias.toLowerCase(), model);
+}
+var UnsupportedBaseModelError = class extends Error {
+  constructor(model) {
+    const supported = SUPPORTED_BASE_MODELS.join(", ");
+    super(
+      `Unsupported base_model "${String(model)}". Supported base models: ${supported}`
+    );
+    this.name = "UnsupportedBaseModelError";
+  }
+};
+function canonicalizeBaseModel(model) {
+  if (typeof model !== "string" || !model.trim()) {
+    throw new UnsupportedBaseModelError(model);
+  }
+  const canonical = BASE_MODEL_ALIASES.get(model.trim().toLowerCase());
+  if (!canonical) {
+    throw new UnsupportedBaseModelError(model);
+  }
+  return canonical;
+}
+function canonicalizeSpecBaseModel(body) {
+  if ("base_model" in body && body.base_model !== void 0) {
+    return { ...body, base_model: canonicalizeBaseModel(body.base_model) };
+  }
+  return body;
+}
+
+// src/project-spec.ts
+var CLOUD_SPEC_KEYS = [
+  "name",
+  "description",
+  "base_model",
+  "system_prompt",
+  "guidelines",
+  "constraints",
+  "examples",
+  "eval_cases"
+];
+var LOCAL_ONLY_SPEC_KEYS = [
+  "hyperparameters",
+  "dataset_prebuilt"
+];
+var LOCAL_SPEC_KEYS = [
+  "id",
+  "name",
+  "description",
+  "system_prompt",
+  "guidelines",
+  "constraints",
+  "base_model",
+  "examples",
+  ...LOCAL_ONLY_SPEC_KEYS
+];
+var CLOUD_SPEC_KEY_SET = new Set(CLOUD_SPEC_KEYS);
+var LOCAL_ONLY_SPEC_KEY_SET = new Set(LOCAL_ONLY_SPEC_KEYS);
+var LOCAL_SPEC_KEY_SET = new Set(LOCAL_SPEC_KEYS);
+var KNOWN_PROJECT_SPEC_KEY_SET = /* @__PURE__ */ new Set([
+  ...CLOUD_SPEC_KEYS,
+  ...LOCAL_SPEC_KEYS
+]);
+function projectSpec(raw, supportedKeys) {
+  const body = {};
+  const droppedKeys = [];
+  for (const [key, value] of Object.entries(raw)) {
+    if (supportedKeys.has(key)) {
+      body[key] = value;
+    } else {
+      droppedKeys.push(key);
+    }
+  }
+  return {
+    body: canonicalizeSpecBaseModel(body),
+    droppedKeys
+  };
+}
+function projectCloudSpec(raw) {
+  return projectSpec(raw, CLOUD_SPEC_KEY_SET);
+}
+function projectLocalSpec(raw) {
+  return projectSpec(raw, LOCAL_SPEC_KEY_SET);
+}
+function hasLocalOnlySpecFields(raw) {
+  return Object.keys(raw).some((key) => LOCAL_ONLY_SPEC_KEY_SET.has(key));
+}
+function unknownProjectSpecKeys(raw) {
+  return Object.keys(raw).filter(
+    (key) => !KNOWN_PROJECT_SPEC_KEY_SET.has(key)
+  );
+}
 
 // src/output.ts
 import chalk from "chalk";
@@ -12,7 +167,13 @@ import { readFileSync as readFileSync2, statSync } from "fs";
 import { basename } from "path";
 
 // src/config.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
 import { homedir } from "os";
 import { join } from "path";
 var CONFIG_DIR_NAME = "tuned-tensor";
@@ -36,8 +197,13 @@ function readConfig() {
 }
 function writeConfig(config) {
   const dir = getConfigDir();
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + "\n");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 448 });
+  chmodSync(dir, 448);
+  const path = getConfigPath();
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n", {
+    mode: 384
+  });
+  chmodSync(path, 384);
 }
 function updateConfig(partial) {
   const current = readConfig();
@@ -45,7 +211,7 @@ function updateConfig(partial) {
 }
 function clearConfig() {
   const path = getConfigPath();
-  if (existsSync(path)) writeFileSync(path, "{}\n");
+  if (existsSync(path)) writeConfig({});
 }
 var DEFAULT_BASE_URL = "https://tunedtensor.com";
 function getBaseUrl(opts) {
@@ -57,9 +223,9 @@ function getApiKey(opts) {
 
 // src/client.ts
 var ApiError = class extends Error {
-  constructor(status, code, message) {
+  constructor(status2, code, message) {
     super(message);
-    this.status = status;
+    this.status = status2;
     this.code = code;
     this.name = "ApiError";
   }
@@ -140,12 +306,12 @@ function isJsonMode() {
 function printJson(data) {
   console.log(JSON.stringify(data, null, 2));
 }
-function printTable(headers, rows, meta) {
+function printTable(headers, rows2, meta) {
   const table = new Table({
     head: headers.map((h) => chalk.bold.cyan(h)),
     style: { head: [], border: [] }
   });
-  for (const row of rows) {
+  for (const row of rows2) {
     table.push(row);
   }
   console.log(table.toString());
@@ -158,103 +324,1782 @@ Page ${meta.page}/${totalPages} (${meta.total} total)`
       )
     );
   }
-}
-function printDetail(fields) {
-  const maxLabel = Math.max(...fields.map(([l]) => l.length));
-  for (const [label, value] of fields) {
-    const paddedLabel = label.padEnd(maxLabel);
-    console.log(`${chalk.bold.cyan(paddedLabel)}  ${value ?? chalk.dim("\u2014")}`);
+}
+function printDetail(fields) {
+  const maxLabel = Math.max(...fields.map(([l]) => l.length));
+  for (const [label, value] of fields) {
+    const paddedLabel = label.padEnd(maxLabel);
+    console.log(`${chalk.bold.cyan(paddedLabel)}  ${value ?? chalk.dim("\u2014")}`);
+  }
+}
+function printSuccess(message) {
+  console.log(chalk.green("\u2713") + " " + message);
+}
+function printWarning(message) {
+  console.log(chalk.yellow("!") + " " + message);
+}
+function printError(message) {
+  console.error(chalk.red("\u2717") + " " + message);
+}
+function reportError(err) {
+  const isApi = err instanceof ApiError;
+  const message = err?.message || String(err);
+  if (jsonMode) {
+    printJson({
+      error: {
+        status: isApi ? err.status : null,
+        code: isApi ? err.code : "CLI_ERROR",
+        message
+      }
+    });
+  } else if (isApi) {
+    printError(`[${err.status}] ${message}`);
+  } else {
+    printError(message);
+  }
+}
+function formatDate(iso) {
+  if (!iso) return "\u2014";
+  return new Date(iso).toLocaleString();
+}
+function formatStatus(status2) {
+  const map = {
+    completed: chalk.green,
+    running: chalk.blue,
+    training: chalk.blue,
+    evaluating: chalk.blue,
+    preparing: chalk.yellow,
+    pending: chalk.yellow,
+    uploading: chalk.yellow,
+    failed: chalk.red,
+    cancelled: chalk.dim,
+    validated: chalk.green,
+    invalid: chalk.red
+  };
+  const colorFn = map[status2] || chalk.white;
+  return colorFn(status2);
+}
+function truncate(str, max) {
+  if (str.length <= max) return str;
+  return str.slice(0, max - 1) + "\u2026";
+}
+function shortId(id) {
+  return id.slice(0, 8);
+}
+
+// src/local-output.ts
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function text(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return void 0;
+}
+function number(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function record(value) {
+  return isRecord(value) ? value : void 0;
+}
+function rows(value) {
+  return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function displayId(value) {
+  const id = text(value);
+  return id ? shortId(id) : "\u2014";
+}
+function displayNumber(value, digits = 4) {
+  const parsed = number(value);
+  if (parsed === void 0) return void 0;
+  return parsed.toFixed(digits).replace(/\.?0+$/, "");
+}
+function displayBytes(value) {
+  const bytes = number(value);
+  if (bytes === void 0 || bytes < 0) return void 0;
+  const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+  let amount = bytes;
+  let unit = 0;
+  while (amount >= 1024 && unit < units.length - 1) {
+    amount /= 1024;
+    unit += 1;
+  }
+  const precision = amount >= 10 || unit === 0 ? 0 : 1;
+  return `${amount.toFixed(precision)} ${units[unit]}`;
+}
+function displayCommand(value) {
+  if (!Array.isArray(value) || !value.every((part) => typeof part === "string")) {
+    return void 0;
+  }
+  return value.map(
+    (part) => /[\s"'\\]/.test(part) ? JSON.stringify(part) : part
+  ).join(" ");
+}
+function status(value) {
+  const parsed = text(value) ?? "unknown";
+  return formatStatus(parsed);
+}
+function gateFrom(value) {
+  return record(record(value)?.general_regression);
+}
+function renderGate(value) {
+  const gate = gateFrom(value);
+  if (!gate) {
+    printWarning(
+      "General regression was not run; this model cannot be activated yet."
+    );
+    return;
+  }
+  if (gate.passed === true) {
+    printSuccess("General regression gate passed");
+    return;
+  }
+  printWarning(
+    "The local run completed, but the general regression gate failed."
+  );
+  const failures = Array.isArray(gate.failures) ? gate.failures.filter(
+    (failure) => typeof failure === "string"
+  ) : [];
+  for (const failure of failures) printWarning(failure);
+}
+function renderDoctor(value) {
+  const checks = rows(value.checks);
+  printTable(
+    ["Check", "Status", "Details"],
+    checks.map((check) => [
+      text(check.name) ?? "unknown",
+      check.ok === true ? formatStatus("completed") : formatStatus("failed"),
+      truncate(text(check.message) ?? text(check.detail) ?? "\u2014", 100)
+    ])
+  );
+  if (value.ok === true) {
+    printSuccess("Local environment is ready");
+  } else {
+    printError("Local environment needs attention");
+  }
+  if (value.config_path) {
+    printDetail([["Config", text(value.config_path)]]);
+  }
+}
+function renderInit(value) {
+  printSuccess("Created local Tuned Tensor project");
+  printDetail([
+    ["Path", text(value.path)],
+    ["Name", text(value.name)],
+    ["ID", text(value.id)],
+    ["Base model", text(value.base_model)],
+    ["Config", text(value.config_path)]
+  ]);
+}
+function renderValidate(value) {
+  printSuccess("Local behavior spec is valid");
+  printDetail([
+    ["Input", text(value.input_path)],
+    ["Config", text(value.config_path)],
+    ["Spec", text(value.behavior_spec_id)],
+    ["Base model", text(value.base_model)],
+    ["Dataset", text(value.dataset_format)],
+    ["Artifacts", text(value.artifact_root)],
+    ["Store", text(value.store_root)],
+    ["Dry run", text(value.dry_run)]
+  ]);
+}
+function renderRun(value) {
+  const runStatus = text(value.status) ?? "unknown";
+  if (runStatus === "completed") {
+    printSuccess("Local run completed");
+  } else {
+    printWarning(`Local run finished with status ${runStatus}`);
+  }
+  const comparison = record(value.comparison);
+  printDetail([
+    ["Run", text(value.run_id)],
+    ["Status", status(runStatus)],
+    ["Model", text(value.model_id) ?? text(value.fine_tuned_model_id)],
+    ["Report", text(value.report_path)],
+    ["Artifacts", text(value.artifact_dir)],
+    ["Score delta", displayNumber(comparison?.avg_score_delta)],
+    ["Pass-rate delta", displayNumber(comparison?.pass_rate_delta)]
+  ]);
+  renderGate(value);
+}
+function renderRunsList(value) {
+  const runRows = rows(value);
+  if (runRows.length === 0) {
+    printWarning("No local runs found.");
+    return;
+  }
+  printTable(
+    ["Run", "Spec", "Status", "Stage", "Model", "Updated"],
+    runRows.map((run) => [
+      displayId(run.id),
+      truncate(text(run.spec_name) ?? displayId(run.behavior_spec_id), 28),
+      status(run.status),
+      text(run.current_stage) ?? "\u2014",
+      displayId(run.model_id),
+      formatDate(text(run.updated_at))
+    ])
+  );
+}
+function renderRunEvents(value) {
+  const eventRows = rows(value);
+  if (eventRows.length === 0) {
+    printWarning("No local run events found.");
+    return;
+  }
+  printTable(
+    ["Time", "Stage", "Status", "Message"],
+    eventRows.map((event) => [
+      formatDate(text(event.occurred_at)),
+      text(event.stage) ?? "\u2014",
+      status(event.status),
+      truncate(text(event.message) ?? "\u2014", 80)
+    ])
+  );
+}
+function renderRunRecord(value) {
+  printDetail([
+    ["Run", text(value.id) ?? text(value.run_id)],
+    ["Spec", text(value.spec_name) ?? text(value.behavior_spec_id)],
+    ["Status", status(value.status)],
+    ["Stage", text(value.current_stage)],
+    ["Model", text(value.model_id) ?? text(value.fine_tuned_model_id)],
+    ["Base model", text(value.base_model)],
+    ["Report", text(value.report_path)],
+    ["Artifacts", text(value.artifact_dir)],
+    ["Updated", formatDate(text(value.updated_at) ?? text(value.created_at))]
+  ]);
+}
+function renderRunReport(value) {
+  const baseline = record(value.baseline);
+  const candidate = record(value.candidate);
+  const comparison = record(value.comparison);
+  const metadata = record(value.run_metadata);
+  printDetail([
+    ["Run", text(value.run_id)],
+    ["Status", status(value.status)],
+    ["Base model", text(value.base_model)],
+    ["Tuned model", text(value.fine_tuned_model_id)],
+    ["Training examples", text(metadata?.training_example_count)],
+    ["Evaluation examples", text(metadata?.eval_examples_used)],
+    ["Baseline score", displayNumber(baseline?.avg_score)],
+    ["Candidate score", displayNumber(candidate?.avg_score)],
+    ["Score delta", displayNumber(comparison?.avg_score_delta)],
+    ["Pass-rate delta", displayNumber(comparison?.pass_rate_delta)],
+    ["Regressions", text(comparison?.regressions)],
+    ["Improvements", text(comparison?.improvements)]
+  ]);
+  renderGate(value);
+}
+function renderRunComparison(value) {
+  const runA = record(value.run_a);
+  const runB = record(value.run_b);
+  const shared = record(value.shared);
+  const sharedA = record(shared?.run_a);
+  const sharedB = record(shared?.run_b);
+  printTable(
+    ["Run", "Candidate score", "Token F1", "Examples"],
+    [
+      [
+        displayId(runA?.run_id),
+        displayNumber(sharedA?.candidate_avg_score) ?? "\u2014",
+        displayNumber(sharedA?.candidate_avg_token_f1) ?? "\u2014",
+        text(shared?.examples) ?? "0"
+      ],
+      [
+        displayId(runB?.run_id),
+        displayNumber(sharedB?.candidate_avg_score) ?? "\u2014",
+        displayNumber(sharedB?.candidate_avg_token_f1) ?? "\u2014",
+        text(shared?.examples) ?? "0"
+      ]
+    ]
+  );
+  const notes = Array.isArray(value.notes) ? value.notes.filter((note) => typeof note === "string") : [];
+  for (const note of notes) printWarning(note);
+}
+function renderModelsList(value) {
+  const modelRows = rows(value);
+  if (modelRows.length === 0) {
+    printWarning("No local models found.");
+    return;
+  }
+  printTable(
+    ["Model", "Base model", "Run", "Provider", "Created"],
+    modelRows.map((model) => [
+      displayId(model.id),
+      truncate(text(model.base_model) ?? "\u2014", 32),
+      displayId(model.run_id),
+      text(model.provider) ?? "\u2014",
+      formatDate(text(model.created_at))
+    ])
+  );
+}
+function renderModelRecord(value) {
+  const model = record(value.model) ?? value;
+  const artifact = record(value.artifact);
+  const integrity = record(value.integrity);
+  printDetail([
+    ["Model", text(model.id) ?? text(value.active)],
+    ["Base model", text(model.base_model)],
+    ["Run", text(model.run_id)],
+    ["Provider", text(model.provider)],
+    ["Artifact", text(model.artifact_uri) ?? text(artifact?.path)],
+    ["Manifest", text(value.manifest_path)],
+    ["Verified files", text(integrity?.checked)],
+    ["Created", formatDate(text(model.created_at))]
+  ]);
+}
+function renderModelPrefetch(value) {
+  printSuccess(
+    value.local_files_only === true ? "Verified the local base-model snapshot" : "Base model is ready locally"
+  );
+  printDetail([
+    ["Base model", text(value.base_model)],
+    ["Revision", text(value.snapshot_revision)],
+    ["Snapshot", text(value.snapshot_path)],
+    ["Files", text(value.file_count)],
+    ["Size", displayBytes(value.size_bytes)],
+    ["Cache", text(value.model_cache) ?? text(value.hf_home)]
+  ]);
+}
+function renderActiveModel(value) {
+  const active = text(value.active) ?? "base";
+  const pointer = record(value.pointer);
+  if (pointer?.action === "activate") {
+    printSuccess(`Activated local model ${active}`);
+  } else if (pointer?.action === "rollback") {
+    printSuccess(`Rolled back to ${active}`);
+  }
+  printDetail([
+    ["Active", active],
+    ["Run", text(pointer?.run_id)],
+    ["Previous", text(pointer?.previous_model_id) ?? "base"],
+    ["Changed", formatDate(text(pointer?.activated_at))],
+    ["Manifest", text(value.manifest_path)]
+  ]);
+}
+function renderServePlan(value) {
+  printSuccess("Local serving plan is valid");
+  printDetail([
+    ["Model", text(value.model_id) ?? text(value.base_model)],
+    ["URL", text(value.url)],
+    ["Artifact", text(value.artifact_path)],
+    ["Manifest", text(value.manifest_path)],
+    ["Command", displayCommand(value.command)]
+  ]);
+}
+function renderKnownJson(args, value) {
+  const command = args[0];
+  const subcommand = args[1];
+  if (command === "doctor" && isRecord(value)) {
+    renderDoctor(value);
+    return true;
+  }
+  if (command === "init" && isRecord(value)) {
+    renderInit(value);
+    return true;
+  }
+  if (command === "validate" && isRecord(value)) {
+    renderValidate(value);
+    return true;
+  }
+  if (command === "run" && isRecord(value)) {
+    renderRun(value);
+    return true;
+  }
+  if (command === "runs") {
+    if ((subcommand === void 0 || subcommand === "list") && Array.isArray(value)) {
+      renderRunsList(value);
+      return true;
+    }
+    if (subcommand === "events" && Array.isArray(value)) {
+      renderRunEvents(value);
+      return true;
+    }
+    if (subcommand === "get" && isRecord(value)) {
+      renderRunRecord(value);
+      return true;
+    }
+    if (subcommand === "report" && isRecord(value)) {
+      renderRunReport(value);
+      return true;
+    }
+    if (subcommand === "compare" && isRecord(value)) {
+      renderRunComparison(value);
+      return true;
+    }
+  }
+  if (command === "models") {
+    if ((subcommand === void 0 || subcommand === "list") && Array.isArray(value)) {
+      renderModelsList(value);
+      return true;
+    }
+    if ((subcommand === "get" || subcommand === "verify") && isRecord(value)) {
+      if (subcommand === "verify") printSuccess("Local model artifact is valid");
+      renderModelRecord(value);
+      return true;
+    }
+    if ((subcommand === "prefetch" || subcommand === "verify-base") && isRecord(value)) {
+      renderModelPrefetch(value);
+      return true;
+    }
+    if (["active", "activate", "rollback"].includes(subcommand ?? "") && isRecord(value)) {
+      renderActiveModel(value);
+      return true;
+    }
+    if (subcommand === "serve" && isRecord(value)) {
+      renderServePlan(value);
+      return true;
+    }
+  }
+  if (command === "serve" && isRecord(value)) {
+    renderServePlan(value);
+    return true;
+  }
+  return false;
+}
+function lastNonEmptyLine(value) {
+  return value.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).at(-1);
+}
+function adaptLocalCliText(value) {
+  return value.replace(
+    /(?<![.@/\w])tuned-tensor-local(?=$|[\s:`\]])/g,
+    "tt local"
+  ).replace(/(?<![.@/\w])tt-local(?=$|[\s:`\]])/g, "tt local");
+}
+function localCliErrorEnvelope(payload) {
+  const rawMessage = payload.errorMessage ?? (payload.stderr.trim() || void 0) ?? lastNonEmptyLine(payload.stdout) ?? `tt local exited with code ${payload.exitCode}.`;
+  return {
+    error: {
+      status: null,
+      code: "LOCAL_CLI_ERROR",
+      message: adaptLocalCliText(rawMessage),
+      exit_code: payload.exitCode,
+      signal: payload.signal
+    }
+  };
+}
+function localCliTextEnvelope(payload) {
+  const output = adaptLocalCliText(payload.stdout).trim();
+  if (payload.args[0] === "info") {
+    const lines = output.split(/\r?\n/);
+    const heading = lines[0]?.match(/^([^:]+):\s*(.+)$/);
+    const fields = Object.fromEntries(
+      lines.slice(1).flatMap((line) => {
+        const match = line.match(/^([^:]+):\s*(.*)$/);
+        return match ? [[match[1].trim().toLowerCase().replaceAll(" ", "_"), match[2].trim()]] : [];
+      })
+    );
+    if (heading) {
+      return {
+        data: {
+          name: heading[1],
+          description: heading[2],
+          ...fields
+        }
+      };
+    }
+  }
+  return { data: { output } };
+}
+function renderLocalOutput(payload, options = {}) {
+  if (payload.streamingStdout && payload.exitCode === 0 && !payload.errorMessage) {
+    return;
+  }
+  const output = options.stdout ?? process.stdout;
+  if (options.jsonMode) {
+    if (payload.hasJson) {
+      output.write(payload.stdout);
+      return;
+    }
+    if (payload.exitCode !== 0 || payload.errorMessage) {
+      output.write(`${JSON.stringify(localCliErrorEnvelope(payload), null, 2)}
+`);
+      return;
+    }
+    output.write(`${JSON.stringify(localCliTextEnvelope(payload), null, 2)}
+`);
+    return;
+  }
+  if (payload.droppedSpecKeys.length > 0) {
+    printWarning(
+      `Ignored project field(s) unsupported by the local runtime: ${payload.droppedSpecKeys.join(", ")}.`
+    );
+  }
+  if (payload.hasJson && renderKnownJson(payload.args, payload.json)) return;
+  if (payload.hasJson) {
+    printJson(payload.json);
+    return;
+  }
+  if (payload.stdout) output.write(adaptLocalCliText(payload.stdout));
+  if (payload.exitCode !== 0 && !payload.stderr && !payload.stdout) {
+    printError(
+      payload.errorMessage ? adaptLocalCliText(payload.errorMessage) : `tt local exited with code ${payload.exitCode}.`
+    );
+  }
+}
+
+// src/local-runner.ts
+var localRequire = createRequire(import.meta.url);
+var DEFAULT_SPEC_NAME = "tunedtensor.json";
+var VALUE_OPTIONS = /* @__PURE__ */ new Set([
+  "--config",
+  "--name",
+  "--model",
+  "--output",
+  "--profile",
+  "--host",
+  "--port",
+  "--device",
+  "--max-tokens",
+  "--temperature",
+  "--top-p",
+  "--max-concurrent-requests",
+  "--spec",
+  "--api-key-env"
+]);
+function isOptionWithInlineValue(value) {
+  const equals = value.indexOf("=");
+  return equals !== -1 && VALUE_OPTIONS.has(value.slice(0, equals));
+}
+function positionalIndices(args, start) {
+  const indices = [];
+  let optionsEnded = false;
+  for (let index = start; index < args.length; index += 1) {
+    const value = args[index];
+    if (!optionsEnded && value === "--") {
+      optionsEnded = true;
+      continue;
+    }
+    if (!optionsEnded && value.startsWith("-")) {
+      if (!isOptionWithInlineValue(value) && VALUE_OPTIONS.has(value)) index += 1;
+      continue;
+    }
+    indices.push(index);
+  }
+  return indices;
+}
+function optionValueArgument(args, name) {
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === name) {
+      const path = args[index + 1];
+      if (!path) return null;
+      return {
+        path,
+        replace(projectedPath) {
+          args[index + 1] = projectedPath;
+        }
+      };
+    }
+    if (value.startsWith(`${name}=`)) {
+      const path = value.slice(name.length + 1);
+      if (!path) return null;
+      return {
+        path,
+        replace(projectedPath) {
+          args[index] = `${name}=${projectedPath}`;
+        }
+      };
+    }
+  }
+  return null;
+}
+function positionalSpecArgument(args, start, defaultPath) {
+  const positional = positionalIndices(args, start)[0];
+  if (positional !== void 0) {
+    return {
+      path: args[positional],
+      replace(projectedPath) {
+        args[positional] = projectedPath;
+      }
+    };
+  }
+  return {
+    path: defaultPath,
+    replace(projectedPath) {
+      args.splice(start, 0, projectedPath);
+    }
+  };
+}
+function selectedSpecArgument(args, cwd) {
+  const command = args[0];
+  if (["doctor", "validate", "run"].includes(command ?? "")) {
+    return positionalSpecArgument(args, 1, join2(cwd, DEFAULT_SPEC_NAME));
+  }
+  if (command === "models" && ["prefetch", "verify-base"].includes(args[1] ?? "")) {
+    return positionalSpecArgument(args, 2, join2(cwd, DEFAULT_SPEC_NAME));
+  }
+  const serves = command === "serve" || command === "models" && args[1] === "serve";
+  if (!serves) return null;
+  const explicit = optionValueArgument(args, "--spec");
+  if (explicit) return explicit;
+  return null;
+}
+async function pathIsFile(path) {
+  return (await stat(path).catch(() => null))?.isFile() ?? false;
+}
+function resolveFromCwd(path, cwd) {
+  if (isAbsolute(path)) return path;
+  return resolve(cwd, path);
+}
+async function projectSpecArguments(originalArgs, cwd) {
+  const args = [...originalArgs];
+  if (args.includes("--help") || args.includes("-h")) {
+    return {
+      args,
+      droppedSpecKeys: [],
+      pathReplacements: [],
+      cleanup: async () => {
+      }
+    };
+  }
+  const selected = selectedSpecArgument(args, cwd);
+  if (!selected) {
+    return {
+      args,
+      droppedSpecKeys: [],
+      pathReplacements: [],
+      cleanup: async () => {
+      }
+    };
+  }
+  const sourcePath = resolveFromCwd(selected.path, cwd);
+  if (!await pathIsFile(sourcePath)) {
+    return {
+      args,
+      droppedSpecKeys: [],
+      pathReplacements: [],
+      cleanup: async () => {
+      }
+    };
+  }
+  const raw = JSON.parse(await readFile(sourcePath, "utf8"));
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${sourcePath} must contain a JSON object.`);
+  }
+  const body = raw;
+  const runRequestKeys = [
+    "run_id",
+    "behavior_spec_id",
+    "run_number",
+    "spec_snapshot"
+  ].filter((key) => key in body);
+  if ("spec_snapshot" in body || runRequestKeys.length >= 2) {
+    return {
+      args,
+      droppedSpecKeys: [],
+      pathReplacements: [],
+      cleanup: async () => {
+      }
+    };
+  }
+  const projected = projectLocalSpec(body);
+  if (projected.droppedKeys.length === 0) {
+    return {
+      args,
+      droppedSpecKeys: [],
+      pathReplacements: [],
+      cleanup: async () => {
+      }
+    };
+  }
+  const temporaryPath = join2(
+    dirname(sourcePath),
+    `.${basename2(sourcePath)}.tt-local-${process.pid}-${randomUUID()}.json`
+  );
+  await writeFile(
+    temporaryPath,
+    `${JSON.stringify(projected.body, null, 2)}
+`,
+    { encoding: "utf8", flag: "wx", mode: 384 }
+  );
+  selected.replace(temporaryPath);
+  return {
+    args,
+    droppedSpecKeys: projected.droppedKeys,
+    pathReplacements: [{
+      sourcePath,
+      projectedPath: temporaryPath
+    }],
+    cleanup: () => rm(temporaryPath, { force: true })
+  };
+}
+function resolveLocalCliEntrypoint() {
+  try {
+    return localRequire.resolve("@tuned-tensor/local");
+  } catch (error) {
+    throw new Error(
+      "TT Local is not installed. Reinstall @tuned-tensor/cli with its local runtime dependency.",
+      { cause: error }
+    );
+  }
+}
+function localCommandStreamsStdout(args) {
+  const serves = args[0] === "serve" || args[0] === "models" && args[1] === "serve";
+  return serves && !args.includes("--print-command") && !args.includes("--help") && !args.includes("-h");
+}
+function parseJsonOutput(stdout2) {
+  if (!stdout2.trim()) return { hasJson: false, json: void 0 };
+  try {
+    return { hasJson: true, json: JSON.parse(stdout2) };
+  } catch {
+    return { hasJson: false, json: void 0 };
+  }
+}
+function signalExitCode(signal) {
+  if (!signal) return 1;
+  const signalNumber = osConstants.signals[signal];
+  return typeof signalNumber === "number" ? 128 + signalNumber : 1;
+}
+function writeStream(stream, chunk) {
+  stream.write(chunk);
+}
+function normalizeProjectedPaths(value, replacements) {
+  let normalized = value;
+  for (const replacement of replacements) {
+    const encodedProjectedPath = JSON.stringify(
+      replacement.projectedPath
+    ).slice(1, -1);
+    const encodedSourcePath = JSON.stringify(
+      replacement.sourcePath
+    ).slice(1, -1);
+    normalized = normalized.replaceAll(encodedProjectedPath, encodedSourcePath).replaceAll(replacement.projectedPath, replacement.sourcePath);
+  }
+  return normalized;
+}
+async function spawnLocalCli(args) {
+  const output = args.stdout ?? process.stdout;
+  const errors = args.stderr ?? process.stderr;
+  const pipeInput = Boolean(args.stdin && args.stdin !== process.stdin);
+  const pipeStreamingOutput = args.streamingStdout && Boolean(args.stdout && args.stdout !== process.stdout);
+  const child = spawn(
+    args.nodeExecutable,
+    [args.entrypoint, ...args.commandArgs],
+    {
+      cwd: args.cwd,
+      env: args.env,
+      stdio: [
+        pipeInput ? "pipe" : "inherit",
+        args.streamingStdout && !pipeStreamingOutput ? "inherit" : "pipe",
+        "pipe"
+      ],
+      detached: process.platform !== "win32"
+    }
+  );
+  if (pipeInput && args.stdin && child.stdin) args.stdin.pipe(child.stdin);
+  let stdout2 = "";
+  let stderr = "";
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (chunk) => {
+    const normalized = normalizeProjectedPaths(
+      chunk,
+      args.pathReplacements
+    );
+    if (args.streamingStdout) writeStream(output, normalized);
+    else stdout2 += normalized;
+  });
+  child.stderr?.on("data", (chunk) => {
+    const normalized = normalizeProjectedPaths(
+      chunk,
+      args.pathReplacements
+    );
+    stderr += normalized;
+    writeStream(
+      errors,
+      args.jsonMode ? normalized : adaptLocalCliText(normalized)
+    );
+  });
+  return new Promise((resolveChild) => {
+    let spawnError;
+    const forwardSignal = (signal) => {
+      const childSignal = signal === "SIGHUP" ? "SIGTERM" : signal;
+      if (child.pid && process.platform !== "win32") {
+        try {
+          process.kill(-child.pid, childSignal);
+          return;
+        } catch {
+        }
+      }
+      child.kill(childSignal);
+    };
+    const onSigint = () => forwardSignal("SIGINT");
+    const onSigterm = () => forwardSignal("SIGTERM");
+    const onSighup = () => forwardSignal("SIGHUP");
+    const cleanup = () => {
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+      if (process.platform !== "win32") process.off("SIGHUP", onSighup);
+    };
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    if (process.platform !== "win32") process.on("SIGHUP", onSighup);
+    child.once("error", (error) => {
+      spawnError = error;
+    });
+    child.once("close", (code, signal) => {
+      cleanup();
+      resolveChild({
+        exitCode: spawnError ? 1 : code ?? signalExitCode(signal),
+        signal,
+        stdout: stdout2,
+        stderr,
+        ...spawnError ? { errorMessage: spawnError.message } : {}
+      });
+    });
+  });
+}
+function setupFailure(originalArgs, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    args: [...originalArgs],
+    projectedArgs: [...originalArgs],
+    entrypoint: null,
+    exitCode: 1,
+    signal: null,
+    stdout: "",
+    stderr: "",
+    hasJson: false,
+    json: void 0,
+    streamingStdout: false,
+    droppedSpecKeys: [],
+    errorMessage: message
+  };
+}
+async function runLocalCommand(args, options = {}) {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  let projected;
+  try {
+    const entrypoint = options.entrypoint ?? resolveLocalCliEntrypoint();
+    projected = await projectSpecArguments(args, cwd);
+    const streamingStdout = localCommandStreamsStdout(projected.args);
+    const result = await spawnLocalCli({
+      entrypoint,
+      commandArgs: projected.args,
+      cwd,
+      env: options.env ?? process.env,
+      nodeExecutable: options.nodeExecutable ?? process.execPath,
+      streamingStdout,
+      jsonMode: options.jsonMode ?? false,
+      stdin: options.stdin,
+      stdout: options.stdout,
+      stderr: options.stderr,
+      pathReplacements: projected.pathReplacements
+    });
+    const parsed = parseJsonOutput(result.stdout);
+    return {
+      args: [...args],
+      projectedArgs: projected.args,
+      entrypoint,
+      ...result,
+      ...parsed,
+      streamingStdout,
+      droppedSpecKeys: projected.droppedSpecKeys
+    };
+  } catch (error) {
+    return setupFailure(args, error);
+  } finally {
+    await projected?.cleanup().catch(() => void 0);
+  }
+}
+async function executeLocalCommand(args, options = {}) {
+  const result = await runLocalCommand(args, options);
+  renderLocalOutput(result, {
+    jsonMode: options.jsonMode,
+    stdout: options.stdout
+  });
+  if (result.exitCode !== 0) process.exitCode = result.exitCode;
+  return result;
+}
+
+// src/shell.ts
+import chalk2 from "chalk";
+import { stat as stat3 } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import { isAbsolute as isAbsolute3, resolve as resolve3 } from "path";
+import { createInterface } from "readline";
+
+// src/command-catalog.ts
+var CLOUD = ["cloud"];
+var LOCAL = ["local"];
+var BOTH = ["cloud", "local"];
+var COMMAND_CATALOG = [
+  { path: "init", description: "Create a behaviour-spec project.", group: "Workflow", modes: BOTH },
+  { path: "eval", description: "Validate a managed-service behaviour spec.", group: "Workflow", modes: CLOUD },
+  { path: "push", description: "Create or update the cloud behaviour spec.", group: "Workflow", modes: CLOUD },
+  { path: "validate", description: "Validate a local fine-tuning project.", group: "Workflow", modes: LOCAL },
+  { path: "doctor", description: "Check the local host and run prerequisites.", group: "Workflow", modes: LOCAL },
+  { path: "run", description: "Run the local fine-tuning and evaluation workflow.", group: "Workflow", modes: LOCAL },
+  { path: "runs list", description: "List runs.", group: "Inspect", modes: BOTH },
+  { path: "runs get", description: "Show a run.", group: "Inspect", modes: BOTH },
+  { path: "runs report", description: "Show a run report.", group: "Inspect", modes: BOTH },
+  { 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 estimate", description: "Estimate managed run cost and duration.", group: "Workflow", modes: CLOUD },
+  { path: "runs start", description: "Start a managed fine-tuning run.", group: "Workflow", modes: CLOUD },
+  { path: "runs watch", description: "Watch a managed run.", group: "Inspect", modes: CLOUD },
+  { path: "runs diagnose", description: "Show managed run diagnostics.", group: "Inspect", modes: CLOUD },
+  { path: "runs cancel", description: "Cancel a managed run.", group: "Workflow", modes: CLOUD },
+  { path: "models list", description: "List models.", group: "Inspect", modes: BOTH },
+  { path: "models get", description: "Show a model.", group: "Inspect", modes: BOTH },
+  { path: "models base", description: "List managed-service base models.", group: "Inspect", modes: CLOUD },
+  { path: "models download", description: "Download a managed model artifact.", group: "Serving", modes: CLOUD },
+  { path: "models export", description: "Export a managed model to GGUF or Ollama.", group: "Serving", modes: CLOUD },
+  { path: "models setup-runtime", description: "Install the managed model-serving runtime.", group: "Serving", modes: CLOUD },
+  { path: "models serve", description: "Serve a model through an OpenAI-compatible API.", group: "Serving", modes: BOTH },
+  { path: "models delete", description: "Delete a managed model.", group: "Workflow", modes: CLOUD },
+  { 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: "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: "specs list", description: "List cloud behaviour specs.", group: "Inspect", modes: CLOUD },
+  { path: "specs get", description: "Show a cloud behaviour spec.", group: "Inspect", modes: CLOUD },
+  { path: "specs create", description: "Create a cloud behaviour spec.", group: "Workflow", modes: CLOUD },
+  { path: "specs update", description: "Update a cloud behaviour spec.", group: "Workflow", modes: CLOUD },
+  { path: "specs delete", description: "Delete a cloud behaviour spec.", group: "Workflow", modes: CLOUD },
+  { path: "datasets list", description: "List cloud datasets.", group: "Data", modes: CLOUD },
+  { path: "datasets get", description: "Show a cloud dataset.", group: "Data", modes: CLOUD },
+  { path: "datasets upload", description: "Upload a cloud dataset.", group: "Data", modes: CLOUD },
+  { path: "datasets delete", description: "Delete a cloud dataset.", group: "Data", modes: CLOUD },
+  { path: "label upload", description: "Start a cloud teacher-labeling job.", group: "Data", modes: CLOUD },
+  { path: "label watch", description: "Watch a cloud labeling job.", group: "Data", modes: CLOUD },
+  { path: "label list", description: "List cloud labeling jobs.", group: "Data", modes: CLOUD },
+  { path: "label status", description: "Show cloud labeling-job status.", group: "Data", modes: CLOUD },
+  { path: "label rows", description: "Review labeled rows.", group: "Data", modes: CLOUD },
+  { path: "label accept", description: "Accept labeled rows.", group: "Data", modes: CLOUD },
+  { path: "label reject", description: "Reject labeled rows.", group: "Data", modes: CLOUD },
+  { path: "label edit", description: "Edit a labeled row.", group: "Data", modes: CLOUD },
+  { path: "label promote", description: "Promote reviewed rows to a dataset.", group: "Data", modes: CLOUD },
+  { path: "label cancel", description: "Cancel a labeling job.", group: "Data", modes: CLOUD },
+  { path: "auth login", description: "Store a cloud API key.", group: "Account", modes: CLOUD },
+  { path: "auth logout", description: "Remove stored cloud credentials.", group: "Account", modes: CLOUD },
+  { path: "auth status", description: "Show cloud authentication status.", group: "Account", modes: CLOUD },
+  { path: "balance", description: "Show cloud credit balance.", group: "Account", modes: CLOUD },
+  { path: "topup", description: "Open a cloud credit checkout.", group: "Account", modes: CLOUD },
+  { path: "info", description: "Show TT Local package information.", group: "Inspect", modes: LOCAL }
+];
+var SLASH_COMMANDS = [
+  { path: "/help", description: "Show commands; add a word to filter." },
+  { path: "/status", description: "Show lightweight workflow status." },
+  { path: "/context", description: "Show the current project and backend context." },
+  { path: "/mode cloud", description: "Use the managed cloud workflow." },
+  { path: "/mode local", description: "Use the local GPU workflow." },
+  { path: "/cd", description: "Change the shell's working directory." },
+  { path: "/clear", description: "Clear the terminal." },
+  { path: "/exit", description: "Exit the TT shell." }
+];
+function catalogForMode(mode) {
+  return COMMAND_CATALOG.filter((command) => command.modes.includes(mode));
+}
+function commandPathsForMode(mode) {
+  return [...new Set(catalogForMode(mode).map((command) => command.path))].sort((left, right) => left.localeCompare(right));
+}
+function groupedCatalog(mode, query) {
+  const normalizedQuery = query?.trim().toLowerCase();
+  const matches = catalogForMode(mode).filter((command) => {
+    if (!normalizedQuery) return true;
+    return command.path.toLowerCase().includes(normalizedQuery) || command.description.toLowerCase().includes(normalizedQuery) || command.group.toLowerCase().includes(normalizedQuery);
+  });
+  const groups = /* @__PURE__ */ new Map();
+  for (const command of matches) {
+    const group = groups.get(command.group) ?? [];
+    group.push(command);
+    groups.set(command.group, group);
+  }
+  return groups;
+}
+function completionTarget(line, activeMode) {
+  const leadingWhitespace = line.match(/^\s*/)?.[0] ?? "";
+  const content = line.slice(leadingWhitespace.length);
+  const override = content.match(/^(cloud|local)(?:\s+|$)/);
+  if (!override) {
+    return { prefix: leadingWhitespace, mode: activeMode, fragment: content };
+  }
+  const mode = override[1];
+  const prefix = `${leadingWhitespace}${mode} `;
+  return {
+    prefix,
+    mode,
+    fragment: content.slice(override[0].length)
+  };
+}
+function createCommandCompleter(getMode) {
+  return (line) => {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("/")) {
+      const candidates = SLASH_COMMANDS.map((command) => command.path);
+      const matches2 = candidates.filter((candidate) => candidate.startsWith(trimmed));
+      return [matches2.length > 0 ? matches2 : candidates, line];
+    }
+    if (trimmed.startsWith("?")) {
+      return [["?"], line];
+    }
+    const { prefix, mode, fragment } = completionTarget(line, getMode());
+    const paths = commandPathsForMode(mode);
+    const targetCandidates = paths.map((path) => `${prefix}${path}`);
+    if (!prefix.trim()) targetCandidates.unshift("cloud ", "local ");
+    const normalizedLine = line.trimStart().toLowerCase();
+    const normalizedFragment = fragment.toLowerCase();
+    const matches = targetCandidates.filter((candidate) => {
+      if (prefix.trim()) return candidate.toLowerCase().startsWith(`${prefix.toLowerCase()}${normalizedFragment}`);
+      return candidate.toLowerCase().startsWith(normalizedLine);
+    });
+    return [matches.length > 0 ? matches : targetCandidates, line];
+  };
+}
+
+// src/shell-context.ts
+import { readFile as readFile2, readdir, stat as stat2 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { basename as basename3, dirname as dirname2, isAbsolute as isAbsolute2, join as join3, resolve as resolve2 } from "path";
+async function readJsonObject(path) {
+  try {
+    const parsed = JSON.parse(await readFile2(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { found: true, invalid: true };
+    }
+    return {
+      found: true,
+      value: parsed,
+      invalid: false
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { found: false, invalid: false };
+    }
+    return { found: true, invalid: true };
+  }
+}
+function stringField(value, key) {
+  const field = value?.[key];
+  return typeof field === "string" && field.trim() ? field : void 0;
+}
+function expandPath(value, baseDirectory, homeDirectory) {
+  if (value === "~") return homeDirectory;
+  if (value.startsWith("~/")) return resolve2(homeDirectory, value.slice(2));
+  return isAbsolute2(value) ? resolve2(value) : resolve2(baseDirectory, value);
+}
+function environmentHome(env) {
+  return env.HOME ? resolve2(env.HOME) : homedir2();
+}
+function cloudConfigPath(env, homeDirectory) {
+  const configHome = env.XDG_CONFIG_HOME ? resolve2(env.XDG_CONFIG_HOME) : join3(homeDirectory, ".config");
+  return join3(configHome, "tuned-tensor", "config.json");
+}
+function redactApiKey(key) {
+  if (!key) return void 0;
+  if (key.length <= 4) return "\u2026";
+  const prefixLength = key.length > 8 ? 8 : Math.max(1, Math.floor(key.length / 2));
+  return `${key.slice(0, prefixLength)}\u2026`;
+}
+function targetFromEnvironment(env) {
+  const value = env.TT_TARGET?.trim().toLowerCase();
+  return value === "cloud" || value === "local" ? value : void 0;
+}
+async function adjacentFile(path) {
+  try {
+    return (await stat2(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+async function readActiveModelId(storeRoot) {
+  const result = await readJsonObject(join3(storeRoot, "active-model.json"));
+  if (!result.found || result.invalid) return void 0;
+  const modelId = result.value?.model_id;
+  if (modelId === null) return "base";
+  return typeof modelId === "string" && modelId ? modelId : void 0;
+}
+async function readLatestRun(storeRoot) {
+  const runsRoot = join3(storeRoot, "runs");
+  let names;
+  try {
+    names = (await readdir(runsRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return void 0;
+  }
+  const states = await Promise.all(names.map(async (name) => {
+    const result = await readJsonObject(join3(runsRoot, name, "state.json"));
+    if (!result.found || result.invalid || !result.value) return void 0;
+    const id = stringField(result.value, "id") ?? name;
+    const state = {
+      id,
+      status: stringField(result.value, "status"),
+      specName: stringField(result.value, "spec_name"),
+      updatedAt: stringField(result.value, "updated_at")
+    };
+    return state;
+  }));
+  return states.filter((state) => Boolean(state)).sort((left, right) => {
+    const leftUpdated = left.updatedAt ?? "";
+    const rightUpdated = right.updatedAt ?? "";
+    if (leftUpdated !== rightUpdated) {
+      return rightUpdated.localeCompare(leftUpdated);
+    }
+    return right.id.localeCompare(left.id);
+  })[0];
+}
+async function discoverShellContext(options = {}) {
+  const env = options.env ?? process.env;
+  const cwd = resolve2(options.cwd ?? process.cwd());
+  const homeDirectory = environmentHome(env);
+  const warnings = [];
+  const specPath = join3(cwd, "tunedtensor.json");
+  const specJson = await readJsonObject(specPath);
+  let spec;
+  if (specJson.found) {
+    if (specJson.invalid || !specJson.value) {
+      spec = { path: specPath, parseError: true };
+      warnings.push("tunedtensor.json could not be parsed.");
+    } else {
+      const examples = specJson.value.examples;
+      spec = {
+        path: specPath,
+        id: stringField(specJson.value, "id"),
+        name: stringField(specJson.value, "name"),
+        baseModel: stringField(specJson.value, "base_model"),
+        exampleCount: Array.isArray(examples) ? examples.length : void 0,
+        parseError: false
+      };
+    }
+  }
+  const localConfigPath = join3(cwd, "local-runner.json");
+  const hasAdjacentLocalConfig = await adjacentFile(localConfigPath);
+  const localConfigJson = hasAdjacentLocalConfig ? await readJsonObject(localConfigPath) : { found: false, invalid: false };
+  if (localConfigJson.invalid) {
+    warnings.push("local-runner.json could not be parsed.");
+  }
+  const localConfigDirectory = hasAdjacentLocalConfig ? dirname2(localConfigPath) : cwd;
+  const configuredArtifactRoot = stringField(localConfigJson.value, "artifactRoot");
+  const configuredStoreRoot = stringField(localConfigJson.value, "storeRoot");
+  const artifactRoot = configuredArtifactRoot ? expandPath(configuredArtifactRoot, localConfigDirectory, homeDirectory) : resolve2(cwd, ".tt-local", "artifacts");
+  const storeRoot = configuredStoreRoot ? expandPath(configuredStoreRoot, localConfigDirectory, homeDirectory) : env.TT_LOCAL_HOME ? expandPath(env.TT_LOCAL_HOME, cwd, homeDirectory) : join3(homeDirectory, ".tuned-tensor-local");
+  const cloudPath = cloudConfigPath(env, homeDirectory);
+  const cloudConfigJson = await readJsonObject(cloudPath);
+  if (cloudConfigJson.invalid) {
+    warnings.push("The Tuned Tensor cloud config could not be parsed.");
+  }
+  const environmentApiKey = env.TUNED_TENSOR_API_KEY?.trim();
+  const storedApiKey = stringField(cloudConfigJson.value, "api_key");
+  const apiKey = environmentApiKey || storedApiKey;
+  const baseUrl = env.TUNED_TENSOR_URL?.trim() || stringField(cloudConfigJson.value, "base_url") || "https://tunedtensor.com";
+  const environmentTarget = targetFromEnvironment(env);
+  if (env.TT_TARGET && !environmentTarget) {
+    warnings.push(`Ignoring invalid TT_TARGET=${JSON.stringify(env.TT_TARGET)}; use cloud or local.`);
+  }
+  const inferredTarget = environmentTarget ?? (hasAdjacentLocalConfig ? "local" : "cloud");
+  const targetSource = environmentTarget ? "environment" : hasAdjacentLocalConfig ? "adjacent-config" : "default-cloud";
+  const [activeModelId, latestRun] = await Promise.all([
+    readActiveModelId(storeRoot),
+    readLatestRun(storeRoot)
+  ]);
+  return {
+    cwd,
+    projectName: basename3(cwd) || cwd,
+    inferredTarget,
+    targetSource,
+    spec,
+    cloud: {
+      authenticated: Boolean(apiKey),
+      keyPrefix: redactApiKey(apiKey),
+      baseUrl,
+      configPath: cloudPath,
+      configFound: cloudConfigJson.found
+    },
+    local: {
+      configPath: hasAdjacentLocalConfig ? localConfigPath : void 0,
+      artifactRoot,
+      storeRoot,
+      activeModelId,
+      latestRun
+    },
+    warnings
+  };
+}
+function valueOrDash(value) {
+  return value === void 0 || value === "" ? "\u2014" : String(value);
+}
+function targetSourceLabel(source) {
+  switch (source) {
+    case "environment":
+      return "TT_TARGET";
+    case "adjacent-config":
+      return "adjacent local-runner.json";
+    default:
+      return "default";
+  }
+}
+function formatShellContext(context, selectedTarget, targetSource) {
+  const specLabel = context.spec ? context.spec.parseError ? `${context.spec.path} (invalid JSON)` : context.spec.path : "not found";
+  const sourceLabel = targetSource === "session" ? "session" : targetSource === "command-option" ? "--target" : targetSourceLabel(targetSource);
+  const lines = [
+    `Target         ${selectedTarget} (${sourceLabel})`,
+    `Project        ${context.projectName}`,
+    `Directory      ${context.cwd}`,
+    `Spec           ${specLabel}`,
+    `Spec ID        ${valueOrDash(context.spec?.id)}`,
+    `Base model     ${valueOrDash(context.spec?.baseModel)}`,
+    `Examples       ${valueOrDash(context.spec?.exampleCount)}`,
+    `Cloud endpoint ${context.cloud.baseUrl}`,
+    `Cloud auth     ${context.cloud.authenticated ? `yes (${context.cloud.keyPrefix})` : "no"}`,
+    `Local config   ${context.local.configPath ?? "not found"}`,
+    `Artifact root  ${context.local.artifactRoot}`,
+    `Store root     ${context.local.storeRoot}`
+  ];
+  for (const warning of context.warnings) lines.push(`Warning        ${warning}`);
+  return lines;
+}
+function formatShellStatus(context, selectedTarget) {
+  const lines = [
+    `Workflow       ${selectedTarget}`,
+    `Spec           ${context.spec?.name ?? (context.spec ? "unnamed" : "not found")}`
+  ];
+  if (selectedTarget === "cloud") {
+    lines.push(
+      `Authentication ${context.cloud.authenticated ? `ready (${context.cloud.keyPrefix})` : "not configured"}`,
+      `Endpoint       ${context.cloud.baseUrl}`,
+      "Remote status  not queried"
+    );
+  } else {
+    lines.push(
+      `Local config   ${context.local.configPath ?? "not found"}`,
+      `Active model   ${context.local.activeModelId ?? "base"}`,
+      `Latest run     ${context.local.latestRun ? `${context.local.latestRun.id} (${context.local.latestRun.status ?? "unknown"})` : "none"}`,
+      "Host checks    not run (use doctor)"
+    );
+  }
+  return lines;
+}
+
+// src/shell.ts
+var ShellParseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ShellParseError";
+  }
+};
+function operatorError(operator) {
+  return new ShellParseError(
+    `Shell operator ${JSON.stringify(operator)} is not supported. Run TT commands directly; pipes, redirects, and command substitution are disabled.`
+  );
+}
+function tokenizeShellInput(input) {
+  if (input.includes("\0")) {
+    throw new ShellParseError("Command input must not contain NUL bytes.");
+  }
+  if (/[\r\n]/.test(input)) {
+    throw new ShellParseError("Enter one command at a time.");
+  }
+  if (input.trimStart().startsWith("!")) {
+    throw new ShellParseError("Shell escapes are disabled; enter a TT command instead.");
+  }
+  const tokens = [];
+  let token = "";
+  let tokenStarted = false;
+  let quote = "none";
+  const finishToken = () => {
+    if (!tokenStarted) return;
+    tokens.push(token);
+    token = "";
+    tokenStarted = false;
+  };
+  for (let index = 0; index < input.length; index += 1) {
+    const character = input[index];
+    if (quote === "single") {
+      if (character === "'") {
+        quote = "none";
+      } else {
+        token += character;
+      }
+      continue;
+    }
+    if (quote === "double") {
+      if (character === '"') {
+        quote = "none";
+        continue;
+      }
+      if (character === "\\") {
+        const escaped = input[index + 1];
+        if (escaped === void 0) {
+          throw new ShellParseError("Command ends with an unfinished escape.");
+        }
+        token += escaped;
+        tokenStarted = true;
+        index += 1;
+        continue;
+      }
+      if (character === "`") throw operatorError("`\u2026`");
+      if (character === "$" && input[index + 1] === "(") {
+        throw operatorError("$(\u2026)");
+      }
+      token += character;
+      tokenStarted = true;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      finishToken();
+      continue;
+    }
+    if (character === "'") {
+      quote = "single";
+      tokenStarted = true;
+      continue;
+    }
+    if (character === '"') {
+      quote = "double";
+      tokenStarted = true;
+      continue;
+    }
+    if (character === "\\") {
+      const escaped = input[index + 1];
+      if (escaped === void 0) {
+        throw new ShellParseError("Command ends with an unfinished escape.");
+      }
+      token += escaped;
+      tokenStarted = true;
+      index += 1;
+      continue;
+    }
+    if (character === "`") throw operatorError("`\u2026`");
+    if (character === "$" && input[index + 1] === "(") {
+      throw operatorError("$(\u2026)");
+    }
+    if (character === "|" || character === ">" || character === "<" || character === ";" || character === "&") {
+      const doubled = input[index + 1] === character && (character === "|" || character === "&");
+      throw operatorError(doubled ? character.repeat(2) : character);
+    }
+    token += character;
+    tokenStarted = true;
+  }
+  if (quote !== "none") {
+    throw new ShellParseError(
+      `Command has an unterminated ${quote === "single" ? "single" : "double"} quote.`
+    );
+  }
+  finishToken();
+  return tokens;
+}
+function routeShellCommand(input, activeMode) {
+  let args = tokenizeShellInput(input);
+  if (args.length === 0) return null;
+  if (args[0] === "tt") {
+    args = args.slice(1);
+    if (args.length === 0) {
+      throw new ShellParseError("The TT shell is already open; enter a command such as `runs list`.");
+    }
+  }
+  if (args[0]?.startsWith("/")) {
+    throw new ShellParseError("Slash commands are session commands and cannot be routed to a workflow.");
+  }
+  const override = args[0];
+  if (override === "cloud" || override === "local") {
+    if (args.length === 1) {
+      throw new ShellParseError(`Add a ${override} command, or use \`/mode ${override}\` to switch workflows.`);
+    }
+    return { target: override, args: args.slice(1) };
+  }
+  return { target: activeMode, args };
+}
+var SLASH_NAMES = /* @__PURE__ */ new Set([
+  "help",
+  "status",
+  "context",
+  "mode",
+  "clear",
+  "cd",
+  "exit"
+]);
+function parseSlashCommand(input) {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+  if (trimmed === "?") return { name: "help", args: [] };
+  if (trimmed.startsWith("? ")) {
+    return {
+      name: "help",
+      args: tokenizeShellInput(trimmed.slice(1))
+    };
+  }
+  if (!trimmed.startsWith("/")) return null;
+  if (trimmed === "/") return { name: "palette", args: [] };
+  const tokens = tokenizeShellInput(trimmed);
+  const rawName = tokens[0].slice(1).toLowerCase();
+  if (!SLASH_NAMES.has(rawName)) {
+    throw new ShellParseError(`Unknown session command: /${rawName}. Use /help to see available commands.`);
+  }
+  return {
+    name: rawName,
+    args: tokens.slice(1)
+  };
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function assertNoArgs(command, args) {
+  if (args.length > 0) {
+    throw new ShellParseError(`/${command} does not accept arguments.`);
+  }
+}
+function expandDirectory(value, cwd, env) {
+  const home = env.HOME ? resolve3(env.HOME) : homedir3();
+  if (value === "~") return home;
+  if (value.startsWith("~/")) return resolve3(home, value.slice(2));
+  return isAbsolute3(value) ? resolve3(value) : resolve3(cwd, value);
+}
+function helpText(mode, query, palette = false) {
+  const groups = groupedCatalog(mode, query);
+  const lines = [];
+  lines.push(palette ? `Commands for ${mode} \u2014 type a command or use cloud/local as a one-shot prefix` : `TT ${mode} commands${query ? ` matching ${JSON.stringify(query)}` : ""}`);
+  if (groups.size === 0) {
+    lines.push("  No matching commands.");
+  } else {
+    for (const [group, commands] of groups) {
+      lines.push(`
+${group}`);
+      for (const command of commands) {
+        lines.push(`  ${command.path.padEnd(22)} ${command.description}`);
+      }
+    }
+  }
+  if (!query) {
+    lines.push("\nSession");
+    for (const command of SLASH_COMMANDS) {
+      lines.push(`  ${command.path.padEnd(22)} ${command.description}`);
+    }
+    lines.push("  ?                      Alias for /help.");
+    lines.push("\nUse Tab to complete commands. Shell operators and shell escapes are disabled.");
+  }
+  return `${lines.join("\n")}
+`;
+}
+function renderShellBanner(snapshot) {
+  const spec = snapshot.context.spec?.name ?? snapshot.context.spec?.path ?? "no spec";
+  return [
+    chalk2.bold.cyan("Tuned Tensor"),
+    `  ${chalk2.bold(snapshot.mode)} \xB7 ${snapshot.context.projectName} \xB7 ${spec}`,
+    chalk2.dim("  /help for commands \xB7 /mode cloud|local to switch workflows"),
+    ""
+  ].join("\n");
+}
+function renderShellPrompt(snapshot) {
+  return `${chalk2.cyan("tt")} ${chalk2.bold(snapshot.mode)} ${chalk2.dim(snapshot.context.projectName)} \u203A `;
+}
+var TunedTensorShellSession = class _TunedTensorShellSession {
+  constructor(runner, io, env, contextProvider, initialContext) {
+    this.runner = runner;
+    this.io = io;
+    this.env = env;
+    this.contextProvider = contextProvider;
+    this.mode = initialContext.inferredTarget;
+    this.modeSource = initialContext.targetSource;
+    this.cwd = initialContext.cwd;
+    this.context = initialContext;
+  }
+  mode;
+  modeSource;
+  cwd;
+  context;
+  static async create(options) {
+    const env = options.env ?? process.env;
+    const cwd = resolve3(options.cwd ?? process.cwd());
+    const contextProvider = options.contextProvider ?? ((input) => discoverShellContext(input));
+    const initialContext = await contextProvider({ cwd, env });
+    return new _TunedTensorShellSession(
+      options.runner,
+      options.io,
+      env,
+      contextProvider,
+      initialContext
+    );
+  }
+  snapshot() {
+    return {
+      mode: this.mode,
+      modeSource: this.modeSource,
+      cwd: this.cwd,
+      context: this.context
+    };
+  }
+  prompt() {
+    return renderShellPrompt(this.snapshot());
+  }
+  banner() {
+    return renderShellBanner(this.snapshot());
+  }
+  async refreshContext() {
+    this.context = await this.contextProvider({ cwd: this.cwd, env: this.env });
+    this.cwd = this.context.cwd;
+    if (this.modeSource !== "session" && this.modeSource !== "environment") {
+      this.mode = this.context.inferredTarget;
+      this.modeSource = this.context.targetSource;
+    }
+  }
+  writeLines(lines) {
+    this.io.write(`${lines.join("\n")}
+`);
+  }
+  async handleSlash(command) {
+    switch (command.name) {
+      case "palette":
+        this.io.write(helpText(this.mode, void 0, true));
+        return "continue";
+      case "help":
+        this.io.write(helpText(this.mode, command.args.join(" ") || void 0));
+        return "continue";
+      case "status":
+        assertNoArgs("status", command.args);
+        await this.refreshContext();
+        this.writeLines(formatShellStatus(this.context, this.mode));
+        return "continue";
+      case "context":
+        assertNoArgs("context", command.args);
+        await this.refreshContext();
+        this.writeLines(formatShellContext(this.context, this.mode, this.modeSource));
+        return "continue";
+      case "mode": {
+        if (command.args.length === 0) {
+          this.io.write(`Current workflow: ${this.mode}
+`);
+          return "continue";
+        }
+        if (command.args.length !== 1 || !["cloud", "local"].includes(command.args[0])) {
+          throw new ShellParseError("Usage: /mode cloud|local");
+        }
+        this.mode = command.args[0];
+        this.modeSource = "session";
+        this.io.write(`Workflow switched to ${this.mode}.
+`);
+        return "continue";
+      }
+      case "clear":
+        assertNoArgs("clear", command.args);
+        this.io.clear();
+        return "continue";
+      case "cd": {
+        if (command.args.length === 0) {
+          this.io.write(`${this.cwd}
+`);
+          return "continue";
+        }
+        if (command.args.length !== 1) {
+          throw new ShellParseError("Usage: /cd <directory>; quote paths containing spaces.");
+        }
+        const nextDirectory = expandDirectory(command.args[0], this.cwd, this.env);
+        const metadata = await stat3(nextDirectory).catch(() => null);
+        if (!metadata?.isDirectory()) {
+          throw new ShellParseError(`Not a directory: ${nextDirectory}`);
+        }
+        this.cwd = nextDirectory;
+        await this.refreshContext();
+        this.io.write(`Directory: ${this.cwd}
+`);
+        return "continue";
+      }
+      case "exit":
+        assertNoArgs("exit", command.args);
+        return "exit";
+    }
+  }
+  async handleLine(input) {
+    try {
+      const slash = parseSlashCommand(input);
+      if (slash) return await this.handleSlash(slash);
+      const routed = routeShellCommand(input, this.mode);
+      if (!routed) return "continue";
+      await this.runner({
+        target: routed.target,
+        args: [...routed.args],
+        cwd: this.cwd
+      });
+      await this.refreshContext();
+      return "continue";
+    } catch (error) {
+      this.io.writeError(`${chalk2.red("Error:")} ${errorMessage(error)}
+`);
+      return "continue";
+    }
   }
+};
+async function createShellSession(options) {
+  return TunedTensorShellSession.create(options);
 }
-function printSuccess(message) {
-  console.log(chalk.green("\u2713") + " " + message);
+function streamIsTTY(stream) {
+  return Boolean(stream.isTTY);
 }
-function printWarning(message) {
-  console.log(chalk.yellow("!") + " " + message);
+async function withForegroundSignalHandoff(control, run) {
+  const signals = control.signals ?? process;
+  const restoreRawMode = control.input.isRaw === true && typeof control.input.setRawMode === "function";
+  const keepParentAlive = () => {
+  };
+  control.pauseReadline();
+  if (restoreRawMode) control.input.setRawMode(false);
+  signals.on("SIGINT", keepParentAlive);
+  try {
+    return await run();
+  } finally {
+    signals.off("SIGINT", keepParentAlive);
+    if (restoreRawMode) control.input.setRawMode(true);
+    control.resumeReadline();
+  }
 }
-function printError(message) {
-  console.error(chalk.red("\u2717") + " " + message);
+function streamIO(output, error) {
+  return {
+    write(text2) {
+      output.write(text2);
+    },
+    writeError(text2) {
+      error.write(text2);
+    },
+    clear() {
+      output.write("\x1B[2J\x1B[H");
+    }
+  };
 }
-function reportError(err) {
-  const isApi = err instanceof ApiError;
-  const message = err?.message || String(err);
-  if (jsonMode) {
-    printJson({
-      error: {
-        status: isApi ? err.status : null,
-        code: isApi ? err.code : "CLI_ERROR",
-        message
+async function startInteractiveShell(options) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const error = options.error ?? process.stderr;
+  if (options.requireTTY !== false && (!streamIsTTY(input) || !streamIsTTY(output))) {
+    throw new Error("The interactive TT shell requires a TTY.");
+  }
+  let readline;
+  const terminalInput = input;
+  const foregroundRunner = (request2) => withForegroundSignalHandoff(
+    {
+      input: terminalInput,
+      pauseReadline: () => readline?.pause(),
+      resumeReadline: () => readline?.resume()
+    },
+    () => options.runner(request2)
+  );
+  const session = await createShellSession({
+    runner: foregroundRunner,
+    io: streamIO(output, error),
+    cwd: options.cwd,
+    env: options.env
+  });
+  const completer = createCommandCompleter(() => session.snapshot().mode);
+  readline = createInterface({
+    input,
+    output,
+    terminal: true,
+    historySize: 100,
+    removeHistoryDuplicates: true,
+    completer
+  });
+  readline.on("SIGINT", () => {
+    output.write("\n");
+    readline?.setPrompt(session.prompt());
+    readline?.write(null, { ctrl: true, name: "u" });
+  });
+  output.write(session.banner());
+  readline.setPrompt(session.prompt());
+  readline.prompt();
+  try {
+    for await (const line of readline) {
+      const action = await session.handleLine(line);
+      if (action === "exit") {
+        readline.close();
+        break;
       }
-    });
-  } else if (isApi) {
-    printError(`[${err.status}] ${message}`);
-  } else {
-    printError(message);
+      readline.setPrompt(session.prompt());
+      readline.prompt();
+    }
+  } finally {
+    readline.close();
   }
 }
-function formatDate(iso) {
-  if (!iso) return "\u2014";
-  return new Date(iso).toLocaleString();
-}
-function formatStatus(status) {
-  const map = {
-    completed: chalk.green,
-    running: chalk.blue,
-    training: chalk.blue,
-    evaluating: chalk.blue,
-    preparing: chalk.yellow,
-    pending: chalk.yellow,
-    uploading: chalk.yellow,
-    failed: chalk.red,
-    cancelled: chalk.dim,
-    validated: chalk.green,
-    invalid: chalk.red
-  };
-  const colorFn = map[status] || chalk.white;
-  return colorFn(status);
-}
-function truncate(str, max) {
-  if (str.length <= max) return str;
-  return str.slice(0, max - 1) + "\u2026";
+function ciEnabled(value) {
+  if (!value) return false;
+  return !["0", "false", "no", "off"].includes(value.trim().toLowerCase());
 }
-function shortId(id) {
-  return id.slice(0, 8);
+function shouldStartInteractiveShell(options) {
+  const env = options.env ?? process.env;
+  return options.args.length === 0 && options.stdinIsTTY === true && options.stdoutIsTTY === true && !ciEnabled(env.CI) && env.TERM !== "dumb";
 }
 
 // src/commands/auth.ts
-import { createInterface } from "readline/promises";
+import { createInterface as createInterface2 } from "readline/promises";
 import { stdin, stdout } from "process";
-import chalk2 from "chalk";
+import { Writable } from "stream";
+import chalk3 from "chalk";
+async function promptForApiKey(input = stdin, output = stdout) {
+  if (input.isTTY !== true || output.isTTY !== true) {
+    throw new Error(
+      "An API key is required in non-interactive mode. Pass it to `tt auth login <key>` or set TUNED_TENSOR_API_KEY."
+    );
+  }
+  let muted = false;
+  const maskedOutput = new Writable({
+    write(chunk, _encoding, callback) {
+      if (!muted) output.write(chunk);
+      callback();
+    }
+  });
+  const rl = createInterface2({
+    input,
+    output: maskedOutput,
+    terminal: true
+  });
+  try {
+    const pending = rl.question("Enter your API key (tt_...): ");
+    muted = true;
+    return await pending;
+  } finally {
+    muted = false;
+    output.write("\n");
+    rl.close();
+  }
+}
 function registerAuthCommands(parent) {
   const auth = parent.command("auth").description("Manage authentication");
   auth.command("login").description("Store an API key for authentication").argument("[key]", "API key (tt_...). If omitted, you will be prompted.").action(async (key) => {
     let apiKey = key;
     if (!apiKey) {
+      if (isJsonMode()) {
+        throw new Error(
+          "An API key argument is required in JSON mode. Use `tt --json auth login <key>`."
+        );
+      }
       const settingsUrl = `${DEFAULT_BASE_URL}/dashboard/settings`;
       console.log();
       console.log(
-        `  To get your API key, go to ${chalk2.bold("Settings \u2192 API Keys")} in the Tuned Tensor dashboard:`
+        `  To get your API key, go to ${chalk3.bold("Settings \u2192 API Keys")} in the Tuned Tensor dashboard:`
       );
-      console.log(`  ${chalk2.cyan.underline(settingsUrl)}`);
+      console.log(`  ${chalk3.cyan.underline(settingsUrl)}`);
       console.log();
-      const rl = createInterface({ input: stdin, output: stdout });
-      apiKey = await rl.question("Enter your API key (tt_...): ");
-      rl.close();
+      apiKey = await promptForApiKey();
     }
     apiKey = apiKey.trim();
     if (!apiKey.startsWith("tt_") || apiKey.length !== 51) {
-      printError(
+      throw new Error(
         "Invalid API key format. Keys start with tt_ and are 51 characters long."
       );
-      process.exit(1);
     }
     updateConfig({ api_key: apiKey });
+    if (isJsonMode()) {
+      printJson({
+        authenticated: true,
+        key_prefix: `${apiKey.slice(0, 8)}...`,
+        base_url: getBaseUrl(parent.opts())
+      });
+      return;
+    }
     printSuccess(
       `API key stored (${apiKey.slice(0, 8)}...). You're ready to go.`
     );
   });
   auth.command("logout").description("Remove stored credentials").action(() => {
     clearConfig();
+    if (isJsonMode()) {
+      printJson({ authenticated: false });
+      return;
+    }
     printSuccess("Credentials removed.");
   });
   auth.command("status").description("Show current authentication status").action(() => {
@@ -382,87 +2227,7 @@ function resolveLabelingJobId(prefix, opts) {
   );
 }
 
-// src/base-models.ts
-var SUPPORTED_BASE_MODELS = [
-  "google/gemma-4-E2B-it",
-  "google/gemma-4-E4B-it",
-  "Qwen/Qwen3.5-2B",
-  "Qwen/Qwen3-VL-2B-Instruct",
-  "Qwen/Qwen3.5-4B",
-  "meta-llama/Llama-3.2-3B-Instruct",
-  "microsoft/Phi-4-mini-instruct",
-  "ibm-granite/granite-3.3-2b-instruct",
-  "bigcode/starcoder2-3b"
-];
-var BASE_MODEL_ALIASES = /* @__PURE__ */ new Map();
-for (const model of SUPPORTED_BASE_MODELS) {
-  BASE_MODEL_ALIASES.set(model.toLowerCase(), model);
-}
-for (const [alias, model] of [
-  ["google/gemma-4-E2B", "google/gemma-4-E2B-it"],
-  ["google/gemma-4-e2b", "google/gemma-4-E2B-it"],
-  ["google/gemma-4-e2b-it", "google/gemma-4-E2B-it"],
-  ["google/gemma-4-E4B", "google/gemma-4-E4B-it"],
-  ["google/gemma-4-e4b", "google/gemma-4-E4B-it"],
-  ["google/gemma-4-e4b-it", "google/gemma-4-E4B-it"],
-  ["qwen/qwen3.5-2b", "Qwen/Qwen3.5-2B"],
-  ["Qwen/Qwen3.5-2B-Base", "Qwen/Qwen3.5-2B"],
-  ["qwen/qwen3.5-2b-base", "Qwen/Qwen3.5-2B"],
-  ["qwen/qwen3-vl-2b-instruct", "Qwen/Qwen3-VL-2B-Instruct"],
-  ["Qwen/Qwen3-VL-2B", "Qwen/Qwen3-VL-2B-Instruct"],
-  ["qwen/qwen3-vl-2b", "Qwen/Qwen3-VL-2B-Instruct"],
-  ["qwen/qwen3.5-4b", "Qwen/Qwen3.5-4B"],
-  ["Qwen/Qwen3.5-4B-Base", "Qwen/Qwen3.5-4B"],
-  ["qwen/qwen3.5-4b-base", "Qwen/Qwen3.5-4B"],
-  ["meta-llama/llama-3.2-3b-instruct", "meta-llama/Llama-3.2-3B-Instruct"],
-  ["meta-llama/Llama-3.2-3B", "meta-llama/Llama-3.2-3B-Instruct"],
-  ["meta-llama/llama-3.2-3b", "meta-llama/Llama-3.2-3B-Instruct"],
-  ["microsoft/phi-4-mini-instruct", "microsoft/Phi-4-mini-instruct"],
-  ["phi-4-mini-instruct", "microsoft/Phi-4-mini-instruct"],
-  ["ibm-granite/granite-3.3-2b-instruct", "ibm-granite/granite-3.3-2b-instruct"],
-  ["granite-3.3-2b-instruct", "ibm-granite/granite-3.3-2b-instruct"],
-  ["bigcode/starcoder2-3b", "bigcode/starcoder2-3b"],
-  ["starcoder2-3b", "bigcode/starcoder2-3b"]
-]) {
-  BASE_MODEL_ALIASES.set(alias.toLowerCase(), model);
-}
-var UnsupportedBaseModelError = class extends Error {
-  constructor(model) {
-    const supported = SUPPORTED_BASE_MODELS.join(", ");
-    super(
-      `Unsupported base_model "${String(model)}". Supported base models: ${supported}`
-    );
-    this.name = "UnsupportedBaseModelError";
-  }
-};
-function canonicalizeBaseModel(model) {
-  if (typeof model !== "string" || !model.trim()) {
-    throw new UnsupportedBaseModelError(model);
-  }
-  const canonical = BASE_MODEL_ALIASES.get(model.trim().toLowerCase());
-  if (!canonical) {
-    throw new UnsupportedBaseModelError(model);
-  }
-  return canonical;
-}
-function canonicalizeSpecBaseModel(body) {
-  if ("base_model" in body && body.base_model !== void 0) {
-    return { ...body, base_model: canonicalizeBaseModel(body.base_model) };
-  }
-  return body;
-}
-
 // src/commands/specs.ts
-var SPEC_BODY_KEYS = /* @__PURE__ */ new Set([
-  "name",
-  "description",
-  "base_model",
-  "system_prompt",
-  "guidelines",
-  "constraints",
-  "examples",
-  "eval_cases"
-]);
 var RUN_INPUT_KEYS = ["run_id", "behavior_spec_id", "spec_snapshot", "run_number"];
 var SpecBodyError = class extends Error {
 };
@@ -493,15 +2258,13 @@ function loadSpecBody(filePath, mode) {
       `${filePath} is missing required field "name" (string).`
     );
   }
-  const unknown = Object.keys(body).filter(
-    (k) => !SPEC_BODY_KEYS.has(k) && k !== "id" && k !== "eval_cases"
-  );
+  const unknown = unknownProjectSpecKeys(body);
   if (unknown.length && !isJsonMode()) {
     printWarning(
-      `Unknown spec field(s) in ${filePath}: ${unknown.join(", ")}. They will be sent but may be rejected by the API.`
+      `Unknown spec field(s) in ${filePath}: ${unknown.join(", ")}. They will be ignored by the cloud API.`
     );
   }
-  return canonicalizeSpecBaseModel(body);
+  return projectCloudSpec(body).body;
 }
 function registerSpecsCommands(parent) {
   const specs = parent.command("specs").description("Manage behaviour specs");
@@ -1195,18 +2958,18 @@ function findControlChar(value) {
 function formatCodepoint(code) {
   return `U+${code.toString(16).toUpperCase().padStart(4, "0")}`;
 }
-function detectRowFormat(record) {
-  const input = record.input;
-  if (input && typeof input === "object" && typeof input.prompt === "string" && Array.isArray(input.assets) && input.assets.length > 0 && typeof record.output === "string") {
+function detectRowFormat(record2) {
+  const input = record2.input;
+  if (input && typeof input === "object" && typeof input.prompt === "string" && Array.isArray(input.assets) && input.assets.length > 0 && typeof record2.output === "string") {
     return "document_ocr_jsonl";
   }
-  if (typeof record.input === "string" || typeof record.output === "string" || !("input" in record) || !("output" in record)) {
+  if (typeof record2.input === "string" || typeof record2.output === "string" || !("input" in record2) || !("output" in record2)) {
     return "jsonl";
   }
   return null;
 }
-function validateDocumentOcrRow(record, rowNumber, errors) {
-  const input = record.input;
+function validateDocumentOcrRow(record2, rowNumber, errors) {
+  const input = record2.input;
   const assets = input.assets;
   if (typeof input.prompt !== "string" || input.prompt.trim().length === 0) {
     errors.push(`Row ${rowNumber}: OCR input.prompt must be a non-empty string`);
@@ -1218,10 +2981,10 @@ function validateDocumentOcrRow(record, rowNumber, errors) {
       );
     }
   }
-  if (typeof record.output !== "string" || record.output.trim().length === 0) {
+  if (typeof record2.output !== "string" || record2.output.trim().length === 0) {
     errors.push(`Row ${rowNumber}: OCR output must be a non-empty string`);
   } else {
-    const hit = findControlChar(record.output);
+    const hit = findControlChar(record2.output);
     if (hit) {
       errors.push(
         `Row ${rowNumber}: OCR output contains invisible control character ${formatCodepoint(hit.codepoint)} (${hit.name}) at offset ${hit.offset} \u2014 strip or escape before uploading; some training paths split on it`
@@ -1290,14 +3053,14 @@ function validateDatasetFile(file, requestedFormat) {
       errors.push(`Row ${rowNumber}: expected an object with "input" and "output" fields`);
       continue;
     }
-    const record = row;
-    if ("messages" in record && !("input" in record) && !("output" in record)) {
+    const record2 = row;
+    if ("messages" in record2 && !("input" in record2) && !("output" in record2)) {
       errors.push(
         `Row ${rowNumber}: found OpenAI SFT-style "messages"; Tuned Tensor datasets require flat "input" and "output" strings`
       );
       continue;
     }
-    const rowFormat = detectRowFormat(record);
+    const rowFormat = detectRowFormat(record2);
     if (!rowFormat) {
       errors.push(
         `Row ${rowNumber}: expected text {"input": string, "output": string} or OCR {"input":{"prompt": string, "assets": [...]}, "output": string}`
@@ -1314,17 +3077,17 @@ function validateDatasetFile(file, requestedFormat) {
       continue;
     }
     if (rowFormat === "document_ocr_jsonl") {
-      validateDocumentOcrRow(record, rowNumber, errors);
+      validateDocumentOcrRow(record2, rowNumber, errors);
       continue;
     }
-    if (typeof record.input !== "string") {
+    if (typeof record2.input !== "string") {
       errors.push(`Row ${rowNumber}: missing string "input" field`);
     }
-    if (typeof record.output !== "string") {
+    if (typeof record2.output !== "string") {
       errors.push(`Row ${rowNumber}: missing string "output" field`);
     }
     for (const field of ["input", "output"]) {
-      const value = record[field];
+      const value = record2[field];
       if (typeof value !== "string") continue;
       const hit = findControlChar(value);
       if (hit) {
@@ -1452,7 +3215,7 @@ function formatCents2(cents) {
   return `$${(cents / 100).toFixed(2)}`;
 }
 function sleep(ms) {
-  return new Promise((resolve4) => setTimeout(resolve4, ms));
+  return new Promise((resolve7) => setTimeout(resolve7, ms));
 }
 function parseCsvHeader(line) {
   const fields = [];
@@ -1845,7 +3608,7 @@ function registerLabelCommands(parent) {
 }
 
 // src/commands/models.ts
-import { spawn as spawn2, execFileSync } from "child_process";
+import { spawn as spawn3, execFileSync } from "child_process";
 import { createHash } from "crypto";
 import {
   existsSync as existsSync5,
@@ -1858,14 +3621,14 @@ import {
   readdirSync,
   rmSync
 } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname as dirname2, join as join2, resolve as resolve2, basename as basename2, normalize, isAbsolute } from "path";
+import { homedir as homedir4 } from "os";
+import { dirname as dirname4, join as join4, resolve as resolve5, basename as basename4, normalize, isAbsolute as isAbsolute4 } from "path";
 import { Readable, Transform } from "stream";
 import { pipeline } from "stream/promises";
 
 // src/commands/init.ts
 import { existsSync as existsSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "fs";
-import { resolve } from "path";
+import { resolve as resolve4 } from "path";
 var DEFAULT_SPEC_FILE = "tunedtensor.json";
 var SCAFFOLD = {
   name: "My Agent",
@@ -1875,30 +3638,45 @@ var SCAFFOLD = {
   guidelines: [],
   constraints: [],
   examples: [
-    { input: "Hello", output: "Hi! How can I help you today?" }
-  ],
-  eval_cases: []
+    { input: "Hello", output: "Hi! How can I help you today?" },
+    {
+      input: "Summarize this update: The launch moved to Friday.",
+      output: "The launch is now scheduled for Friday."
+    }
+  ]
 };
 function registerInitCommand(parent) {
-  parent.command("init").description("Create a local behaviour spec file").option("-n, --name <name>", "Spec name").option("--model <model>", "Base model ID").option("-f, --file <path>", "Output file path", DEFAULT_SPEC_FILE).action(async (cmdOpts) => {
-    const filePath = resolve(cmdOpts.file);
+  parent.command("init").description("Create a behaviour spec project file").option("-n, --name <name>", "Spec name").option("--model <model>", "Base model ID").option("-f, --file <path>", "Output file path", DEFAULT_SPEC_FILE).action(async (cmdOpts) => {
+    const filePath = resolve4(cmdOpts.file);
     if (existsSync4(filePath)) {
+      if (isJsonMode()) {
+        printJson({ created: false, path: filePath });
+        return;
+      }
       printWarning(`${cmdOpts.file} already exists. Use tt eval to validate it or edit it directly.`);
       return;
     }
-    const spec = { ...SCAFFOLD };
+    const spec = {
+      ...SCAFFOLD,
+      examples: SCAFFOLD.examples.map((example) => ({ ...example }))
+    };
     if (cmdOpts.name) spec.name = cmdOpts.name;
     if (cmdOpts.model) spec.base_model = canonicalizeBaseModel(cmdOpts.model);
     writeFileSync2(filePath, JSON.stringify(spec, null, 2) + "\n");
+    if (isJsonMode()) {
+      printJson({ created: true, path: filePath, spec });
+      return;
+    }
     printSuccess(`Created ${cmdOpts.file}`);
     console.log("\nNext steps:");
     console.log("  1. Edit the spec: system_prompt, guidelines, examples");
-    console.log("  2. Validate spec:    tt eval");
-    console.log("  3. Push to remote:   tt push");
+    console.log("  2. Validate for cloud: tt eval");
+    console.log("  3. Push to cloud:      tt push");
+    console.log("     Or validate locally: tt local validate");
   });
 }
 function loadSpec(filePath) {
-  const resolved = resolve(filePath || DEFAULT_SPEC_FILE);
+  const resolved = resolve4(filePath || DEFAULT_SPEC_FILE);
   if (!existsSync4(resolved)) {
     printError(
       `Spec file not found: ${filePath || DEFAULT_SPEC_FILE}
@@ -1911,30 +3689,30 @@ Run \`tt init\` to create one.`
 }
 
 // src/serve-manager.ts
-import { spawn } from "child_process";
-import { randomUUID } from "crypto";
+import { spawn as spawn2 } from "child_process";
+import { randomUUID as randomUUID2 } from "crypto";
 import { appendFileSync, mkdirSync as mkdirSync2 } from "fs";
 import { createServer } from "http";
 import { createServer as createNetServer } from "net";
-import { dirname } from "path";
+import { dirname as dirname3 } from "path";
 var COMPLETION_ROUTES = /* @__PURE__ */ new Set(["/v1/chat/completions", "/chat/completions"]);
 function parsePositiveInteger(value, fallback) {
   return Number.isInteger(value) && value >= 0 ? value : fallback;
 }
 function sleep2(ms) {
-  return new Promise((resolve4) => setTimeout(resolve4, ms));
+  return new Promise((resolve7) => setTimeout(resolve7, ms));
 }
 function readRequestBody(req) {
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve7, reject) => {
     const chunks = [];
     req.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
-    req.on("end", () => resolve4(Buffer.concat(chunks)));
+    req.on("end", () => resolve7(Buffer.concat(chunks)));
     req.on("error", reject);
   });
 }
-function sendJson(res, status, payload) {
+function sendJson(res, status2, payload) {
   const body = Buffer.from(JSON.stringify(payload), "utf8");
-  res.writeHead(status, {
+  res.writeHead(status2, {
     "content-type": "application/json",
     "content-length": String(body.byteLength),
     "access-control-allow-origin": "*",
@@ -1996,7 +3774,7 @@ function errorSummary(response, fallback) {
   return typeof message === "string" ? message : fallback;
 }
 async function allocatePort(host) {
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve7, reject) => {
     const server = createNetServer();
     server.on("error", reject);
     server.listen(0, host, () => {
@@ -2006,14 +3784,14 @@ async function allocatePort(host) {
         return;
       }
       const port = address.port;
-      server.close(() => resolve4(port));
+      server.close(() => resolve7(port));
     });
   });
 }
 var ManagedModelServer = class {
   constructor(options) {
     this.options = options;
-    this.spawnModelServer = options.spawnModelServer ?? spawn;
+    this.spawnModelServer = options.spawnModelServer ?? spawn2;
     this.idleTimeoutMs = parsePositiveInteger(options.idleTimeoutSeconds, 300) * 1e3;
     this.restartAfterRequests = parsePositiveInteger(options.restartAfterRequests, 100);
     this.logRecordOverride = options.logRecord;
@@ -2046,11 +3824,11 @@ var ManagedModelServer = class {
         sendJson(res, 500, { error: { message: err instanceof Error ? err.message : String(err) } });
       });
     });
-    await new Promise((resolve4, reject) => {
+    await new Promise((resolve7, reject) => {
       this.server?.once("error", reject);
       this.server?.listen(this.options.publicPort, this.options.publicHost, () => {
         this.server?.off("error", reject);
-        resolve4();
+        resolve7();
       });
     });
   }
@@ -2060,15 +3838,15 @@ var ManagedModelServer = class {
     if (!this.server) return;
     const server = this.server;
     this.server = null;
-    await new Promise((resolve4, reject) => {
-      server.close((err) => err ? reject(err) : resolve4());
+    await new Promise((resolve7, reject) => {
+      server.close((err) => err ? reject(err) : resolve7());
     });
   }
   async run() {
     await this.start();
-    await new Promise((resolve4, reject) => {
+    await new Promise((resolve7, reject) => {
       this.server?.once("error", reject);
-      this.server?.once("close", resolve4);
+      this.server?.once("close", resolve7);
     });
   }
   async handle(req, res) {
@@ -2136,20 +3914,20 @@ var ManagedModelServer = class {
     });
   }
   async processGeneration(route, body, res, receivedAt) {
-    const requestId = `ttreq-${randomUUID()}`;
+    const requestId = `ttreq-${randomUUID2()}`;
     const startedAt = Date.now();
     const queuedMs = startedAt - receivedAt;
     this.activeRequests += 1;
     this.clearIdleTimer();
-    let status = 500;
+    let status2 = 500;
     let parsed = null;
     let failure = null;
     try {
       await this.ensureModelReady();
       const forwarded = await this.forwardGeneration(route, body);
-      status = forwarded.status;
+      status2 = forwarded.status;
       parsed = forwarded.parsed;
-      res.writeHead(status, {
+      res.writeHead(status2, {
         ...copyResponseHeaders(forwarded.headers),
         "content-length": String(Buffer.byteLength(forwarded.body))
       });
@@ -2158,8 +3936,8 @@ var ManagedModelServer = class {
       failure = errorSummary(parsed, null);
     } catch (err) {
       failure = err instanceof Error ? err.message : String(err);
-      status = 502;
-      sendJson(res, status, { error: { message: failure } });
+      status2 = 502;
+      sendJson(res, status2, { error: { message: failure } });
     } finally {
       const finishedAt = Date.now();
       this.activeRequests -= 1;
@@ -2172,13 +3950,13 @@ var ManagedModelServer = class {
           path: this.options.modelPath
         },
         request_bytes: body.byteLength,
-        response_status: status,
+        response_status: status2,
         latency_ms: finishedAt - receivedAt,
         queued_ms: queuedMs,
         prompt_tokens: usageNumber(parsed, "prompt_tokens"),
         completion_tokens: usageNumber(parsed, "completion_tokens"),
         total_tokens: usageNumber(parsed, "total_tokens"),
-        schema_validity: status < 400 ? true : status === 422 ? false : null,
+        schema_validity: status2 < 400 ? true : status2 === 422 ? false : null,
         gate_field: this.options.gateField,
         gate_result: this.extractGateResult(parsed),
         restart_count: this.restartCount,
@@ -2242,7 +4020,7 @@ var ManagedModelServer = class {
     try {
       child.kill("SIGTERM");
       await Promise.race([
-        new Promise((resolve4) => child.once("exit", () => resolve4())),
+        new Promise((resolve7) => child.once("exit", () => resolve7())),
         sleep2(5e3).then(() => {
           if (child.exitCode == null && child.signalCode == null) child.kill("SIGKILL");
         })
@@ -2259,8 +4037,8 @@ var ManagedModelServer = class {
       const response = await fetch(`http://127.0.0.1:${this.internalPort}/health`, {
         signal: controller.signal
       });
-      const text = await response.text();
-      return { ok: response.ok, body: tryJsonParse(text) };
+      const text2 = await response.text();
+      return { ok: response.ok, body: tryJsonParse(text2) };
     } catch {
       return { ok: false, body: null };
     } finally {
@@ -2284,12 +4062,12 @@ var ManagedModelServer = class {
       headers: { "content-type": "application/json" },
       body
     });
-    const text = await response.text();
+    const text2 = await response.text();
     return {
       status: response.status,
       headers: response.headers,
-      body: text,
-      parsed: tryJsonParse(text)
+      body: text2,
+      parsed: tryJsonParse(text2)
     };
   }
   extractGateResult(response) {
@@ -2312,15 +4090,15 @@ var ManagedModelServer = class {
     clearTimeout(this.idleTimer);
     this.idleTimer = null;
   }
-  writeLog(record) {
+  writeLog(record2) {
     if (this.logRecordOverride) {
-      this.logRecordOverride(record);
+      this.logRecordOverride(record2);
       return;
     }
-    const line = `${JSON.stringify(record)}
+    const line = `${JSON.stringify(record2)}
 `;
     if (this.options.logFile) {
-      mkdirSync2(dirname(this.options.logFile), { recursive: true });
+      mkdirSync2(dirname3(this.options.logFile), { recursive: true });
       appendFileSync(this.options.logFile, line, "utf8");
       return;
     }
@@ -2868,7 +4646,7 @@ if __name__ == "__main__":
 function resolveOutputPath(output, filename) {
   if (!output) return filename;
   if (existsSync5(output) && statSync4(output).isDirectory()) {
-    return join2(output, filename);
+    return join4(output, filename);
   }
   return output;
 }
@@ -2944,7 +4722,7 @@ async function downloadUrlToFile(url, outputPath) {
   if (!res.body) {
     throw new Error("Download failed: response body was empty");
   }
-  mkdirSync3(dirname2(outputPath), { recursive: true });
+  mkdirSync3(dirname4(outputPath), { recursive: true });
   const file = createWriteStream(outputPath);
   const contentLength = parseContentLength(res.headers.get("content-length"));
   const progress = createDownloadProgress(
@@ -2975,15 +4753,15 @@ async function downloadUrlToFile(url, outputPath) {
   return contentLength;
 }
 function defaultCacheDir() {
-  const root = process.env.XDG_CACHE_HOME || join2(homedir2(), ".cache");
-  return join2(root, "tuned-tensor", "models");
+  const root = process.env.XDG_CACHE_HOME || join4(homedir4(), ".cache");
+  return join4(root, "tuned-tensor", "models");
 }
 function runtimeDir(cacheDir) {
-  return join2(cacheDir, "_runtime");
+  return join4(cacheDir, "_runtime");
 }
 function runtimePythonPath(cacheDir) {
   const dir = runtimeDir(cacheDir);
-  return process.platform === "win32" ? join2(dir, "Scripts", "python.exe") : join2(dir, "bin", "python");
+  return process.platform === "win32" ? join4(dir, "Scripts", "python.exe") : join4(dir, "bin", "python");
 }
 function resolveServePython(cacheDir, explicitPython) {
   if (explicitPython) return explicitPython;
@@ -3056,7 +4834,7 @@ print(json.dumps({"missing": missing}))
   }
 }
 function setupRuntimeCommands(python, venvDir, deps) {
-  const venvPython = process.platform === "win32" ? join2(venvDir, "Scripts", "python.exe") : join2(venvDir, "bin", "python");
+  const venvPython = process.platform === "win32" ? join4(venvDir, "Scripts", "python.exe") : join4(venvDir, "bin", "python");
   return [
     [python, "-m", "venv", venvDir],
     [venvPython, "-m", "pip", "install", "--upgrade", "pip"],
@@ -3071,7 +4849,7 @@ function directoryHasFiles(path) {
 }
 function validateArchiveEntryPath(entry) {
   const normalized = normalize(entry).replace(/^[\\/]+/, "");
-  if (!entry.trim() || isAbsolute(entry) || normalized === ".." || normalized.startsWith(`..${"/"}`) || normalized.startsWith(`..${"\\"}`)) {
+  if (!entry.trim() || isAbsolute4(entry) || normalized === ".." || normalized.startsWith(`..${"/"}`) || normalized.startsWith(`..${"\\"}`)) {
     throw new Error(`Unsafe archive entry path: ${entry}`);
   }
   return normalized;
@@ -3094,9 +4872,9 @@ function extractArchive(archivePath, targetDir, force) {
   return targetDir;
 }
 function localArchiveCacheDir(archivePath, cacheDir) {
-  const resolved = resolve2(archivePath);
+  const resolved = resolve5(archivePath);
   const digest = createHash("sha256").update(resolved).digest("hex").slice(0, 12);
-  return join2(cacheDir, `local-${safeSegment(basename2(archivePath))}-${digest}`);
+  return join4(cacheDir, `local-${safeSegment(basename4(archivePath))}-${digest}`);
 }
 function buildSystemPrompt(spec) {
   const parts = [];
@@ -3112,9 +4890,9 @@ ${spec.constraints.map((c) => `- ${c}`).join("\n")}`);
   return parts.join("\n\n");
 }
 function findSpecPath(explicitPath, modelPath) {
-  const candidates = explicitPath ? [explicitPath] : [join2(process.cwd(), DEFAULT_SPEC_FILE), join2(modelPath, DEFAULT_SPEC_FILE)];
+  const candidates = explicitPath ? [explicitPath] : [join4(process.cwd(), DEFAULT_SPEC_FILE), join4(modelPath, DEFAULT_SPEC_FILE)];
   for (const candidate of candidates) {
-    const resolved = resolve2(candidate);
+    const resolved = resolve5(candidate);
     if (existsSync5(resolved) && statSync4(resolved).isFile()) return resolved;
   }
   return null;
@@ -3124,7 +4902,7 @@ function loadSystemPromptFromSpec(specPath) {
   return buildSystemPrompt(spec);
 }
 function loadJsonSchemaForServe(schemaPath) {
-  const resolved = resolve2(schemaPath);
+  const resolved = resolve5(schemaPath);
   if (!existsSync5(resolved) || !statSync4(resolved).isFile()) {
     throw new Error(`JSON schema file not found: ${schemaPath}`);
   }
@@ -3136,28 +4914,28 @@ function loadJsonSchemaForServe(schemaPath) {
   }
 }
 function writeReferenceServerScript(cacheDir) {
-  const scriptDir = join2(cacheDir, "_server");
+  const scriptDir = join4(cacheDir, "_server");
   mkdirSync3(scriptDir, { recursive: true });
-  const scriptPath = join2(scriptDir, "openai_reference_server.py");
+  const scriptPath = join4(scriptDir, "openai_reference_server.py");
   writeFileSync3(scriptPath, REFERENCE_SERVER_SCRIPT, "utf8");
   return scriptPath;
 }
 async function resolveServeTarget(target, opts, cacheDir, forceDownload) {
   if (existsSync5(target)) {
-    const resolved = resolve2(target);
+    const resolved = resolve5(target);
     const stats = statSync4(resolved);
     if (stats.isDirectory()) {
       return {
         modelPath: resolved,
-        modelName: basename2(resolved),
+        modelName: basename4(resolved),
         source: "local-directory"
       };
     }
     if (stats.isFile() && (resolved.endsWith(".tar.gz") || resolved.endsWith(".tgz"))) {
-      const extractDir2 = join2(localArchiveCacheDir(resolved, cacheDir), "model");
+      const extractDir2 = join4(localArchiveCacheDir(resolved, cacheDir), "model");
       return {
         modelPath: extractArchive(resolved, extractDir2, forceDownload),
-        modelName: basename2(resolved).replace(/\.t(ar\.)?gz$/, ""),
+        modelName: basename4(resolved).replace(/\.t(ar\.)?gz$/, ""),
         source: "local-archive"
       };
     }
@@ -3166,9 +4944,9 @@ async function resolveServeTarget(target, opts, cacheDir, forceDownload) {
   const fullId = await resolveModelId(target, opts);
   const { data: model } = await get(`/models/${fullId}`, void 0, opts);
   const { data } = await get(`/models/${fullId}/download`, void 0, opts);
-  const modelCacheDir = join2(cacheDir, fullId);
-  const archivePath = join2(modelCacheDir, data.filename);
-  const extractDir = join2(modelCacheDir, "model");
+  const modelCacheDir = join4(cacheDir, fullId);
+  const archivePath = join4(modelCacheDir, data.filename);
+  const extractDir = join4(modelCacheDir, "model");
   if (!existsSync5(archivePath) || forceDownload) {
     await downloadUrlToFile(data.url, archivePath);
   }
@@ -3274,7 +5052,7 @@ function ollamaSlug(name) {
 function firstExisting(candidates) {
   for (const candidate of candidates) {
     if (candidate && existsSync5(candidate) && statSync4(candidate).isFile()) {
-      return resolve2(candidate);
+      return resolve5(candidate);
     }
   }
   return null;
@@ -3284,14 +5062,14 @@ function llamaCppDir(explicit) {
 }
 function resolveConvertScript(opts, required) {
   if (opts.convertScript) {
-    const resolved = resolve2(opts.convertScript);
+    const resolved = resolve5(opts.convertScript);
     if (required && !existsSync5(resolved)) {
       throw new Error(`Conversion script not found: ${opts.convertScript}`);
     }
     return resolved;
   }
   const dir = llamaCppDir(opts.llamaCpp);
-  const candidates = dir ? [join2(dir, "convert_hf_to_gguf.py"), join2(dir, "convert-hf-to-gguf.py")] : [];
+  const candidates = dir ? [join4(dir, "convert_hf_to_gguf.py"), join4(dir, "convert-hf-to-gguf.py")] : [];
   const found = firstExisting(candidates);
   if (found) return found;
   if (required) {
@@ -3299,11 +5077,11 @@ function resolveConvertScript(opts, required) {
       "Could not find convert_hf_to_gguf.py. Pass --llama-cpp <dir> (a llama.cpp checkout) or --convert-script <path>. Get it from https://github.com/ggml-org/llama.cpp."
     );
   }
-  return dir ? join2(dir, "convert_hf_to_gguf.py") : "convert_hf_to_gguf.py";
+  return dir ? join4(dir, "convert_hf_to_gguf.py") : "convert_hf_to_gguf.py";
 }
 function resolveQuantizeBin(opts, required) {
   if (opts.quantizeBin) {
-    const resolved = resolve2(opts.quantizeBin);
+    const resolved = resolve5(opts.quantizeBin);
     if (required && !existsSync5(resolved)) {
       throw new Error(`llama-quantize binary not found: ${opts.quantizeBin}`);
     }
@@ -3312,10 +5090,10 @@ function resolveQuantizeBin(opts, required) {
   const dir = llamaCppDir(opts.llamaCpp);
   if (dir) {
     const candidates = [
-      join2(dir, "build", "bin", "llama-quantize"),
-      join2(dir, "build", "bin", "quantize"),
-      join2(dir, "llama-quantize"),
-      join2(dir, "quantize")
+      join4(dir, "build", "bin", "llama-quantize"),
+      join4(dir, "build", "bin", "quantize"),
+      join4(dir, "llama-quantize"),
+      join4(dir, "quantize")
     ];
     const found = firstExisting(candidates);
     if (found) return found;
@@ -3463,7 +5241,7 @@ function registerModelsCommands(parent) {
     }
     const quantPlan = planQuant(String(cmdOpts.quant));
     const printOnly = Boolean(cmdOpts.printCommand);
-    const cacheDir = resolve2(cmdOpts.cacheDir || defaultCacheDir());
+    const cacheDir = resolve5(cmdOpts.cacheDir || defaultCacheDir());
     mkdirSync3(cacheDir, { recursive: true });
     const serveTarget = await resolveServeTarget(
       target,
@@ -3472,9 +5250,9 @@ function registerModelsCommands(parent) {
       Boolean(cmdOpts.forceDownload)
     );
     const slug = ollamaSlug(serveTarget.modelName);
-    const outputDir = resolve2(cmdOpts.output || join2(process.cwd(), `${slug}-gguf`));
-    const finalPath = join2(outputDir, `${slug}.${quantPlan.quant}.gguf`);
-    const intermediatePath = quantPlan.requiresQuantize ? join2(outputDir, `${slug}.f16.gguf`) : void 0;
+    const outputDir = resolve5(cmdOpts.output || join4(process.cwd(), `${slug}-gguf`));
+    const finalPath = join4(outputDir, `${slug}.${quantPlan.quant}.gguf`);
+    const intermediatePath = quantPlan.requiresQuantize ? join4(outputDir, `${slug}.f16.gguf`) : void 0;
     const convertScript = resolveConvertScript(cmdOpts, !printOnly);
     const convertOutfile = intermediatePath ?? finalPath;
     const steps = [
@@ -3512,8 +5290,8 @@ function registerModelsCommands(parent) {
         }
         if (specPath) systemPrompt = loadSystemPromptFromSpec(specPath);
       }
-      modelfilePath = join2(outputDir, "Modelfile");
-      modelfileContent = buildModelfile(basename2(finalPath), systemPrompt);
+      modelfilePath = join4(outputDir, "Modelfile");
+      modelfileContent = buildModelfile(basename4(finalPath), systemPrompt);
       const createModel = cmdOpts.ollamaCreate !== false;
       if (createModel) {
         steps.push(
@@ -3599,7 +5377,7 @@ function registerModelsCommands(parent) {
     }
   });
   models.command("setup-runtime").description("Install an isolated Python runtime for local model serving").option("--python <path>", "Python 3.10-3.12 executable to create the runtime").option("--cache-dir <path>", "Cache directory for the managed runtime").option("-f, --force", "Recreate the runtime if it already exists").option("--print-command", "Print the setup commands without running them").action(async (cmdOpts) => {
-    const cacheDir = resolve2(cmdOpts.cacheDir || defaultCacheDir());
+    const cacheDir = resolve5(cmdOpts.cacheDir || defaultCacheDir());
     const venvDir = runtimeDir(cacheDir);
     const venvPython = runtimePythonPath(cacheDir);
     const python = pickRuntimePython(cmdOpts.python);
@@ -3645,7 +5423,7 @@ function registerModelsCommands(parent) {
   });
   models.command("serve").description("Serve a downloaded model with an OpenAI-compatible local API").argument("<target>", "Model ID/prefix, model directory, or .tar.gz artifact").option("--spec <path>", "Behavior spec JSON to apply as the default system prompt").option("--no-spec-prompt", "Do not auto-apply a behavior spec system prompt").option("--host <host>", "Host to bind", "127.0.0.1").option("--port <port>", "Port to bind", "8000").option("--python <path>", "Python executable").option("--cache-dir <path>", "Cache directory for downloaded/extracted models").option("--device <device>", "Inference device: auto, cpu, cuda, or mps", "auto").option("--force-download", "Re-download and re-extract model artifacts").option("--max-tokens <n>", "Default max completion tokens", "512").option("--temperature <n>", "Default sampling temperature", "0.7").option("--json-schema <path>", "JSON Schema file to enforce by default for chat completions").option("--json-repair-attempts <n>", "Number of JSON/schema repair retries", "1").option("--trust-remote-code", "Pass trust_remote_code=True to transformers").option("--managed", "Run a local lifecycle manager in front of the model server").option("--idle-timeout <seconds>", "Managed mode idle timeout before stopping the model", "300").option("--restart-after-requests <n>", "Managed mode restart threshold; 0 disables request-count restarts", "100").option("--gate-field <field>", "Response JSON field to log as the managed serving gate result", "should_process").option("--log-file <path>", "Write managed serving JSONL request logs to a file").option("--print-command", "Print the underlying Python command without starting it").action(async (target, cmdOpts) => {
     const opts = parent.opts();
-    const cacheDir = resolve2(cmdOpts.cacheDir || defaultCacheDir());
+    const cacheDir = resolve5(cmdOpts.cacheDir || defaultCacheDir());
     mkdirSync3(cacheDir, { recursive: true });
     const python = resolveServePython(cacheDir, cmdOpts.python);
     if (!cmdOpts.printCommand) ensureServingRuntime(python, cacheDir);
@@ -3694,7 +5472,7 @@ function registerModelsCommands(parent) {
       idle_timeout_seconds: idleTimeoutSeconds,
       restart_after_requests: restartAfterRequests,
       gate_field: String(cmdOpts.gateField),
-      log_file: cmdOpts.logFile ? resolve2(cmdOpts.logFile) : void 0
+      log_file: cmdOpts.logFile ? resolve5(cmdOpts.logFile) : void 0
     } : void 0;
     if (cmdOpts.printCommand) return printServeCommand(python, args, env, managedConfig);
     if (!isJsonMode()) {
@@ -3731,12 +5509,12 @@ function registerModelsCommands(parent) {
         idleTimeoutSeconds,
         restartAfterRequests,
         gateField: String(cmdOpts.gateField),
-        logFile: cmdOpts.logFile ? resolve2(cmdOpts.logFile) : void 0
+        logFile: cmdOpts.logFile ? resolve5(cmdOpts.logFile) : void 0
       });
       return;
     }
     await new Promise((resolvePromise, reject) => {
-      const child = spawn2(python, args, {
+      const child = spawn3(python, args, {
         stdio: "inherit",
         env: { ...process.env, ...env }
       });
@@ -3757,7 +5535,7 @@ function registerModelsCommands(parent) {
 }
 
 // src/commands/balance.ts
-import chalk3 from "chalk";
+import chalk4 from "chalk";
 var KIND_LABELS = {
   signup_bonus: "Signup bonus",
   topup: "Top-up",
@@ -3772,8 +5550,8 @@ function formatCents3(cents) {
   return `${sign}$${(abs / 100).toFixed(2)}`;
 }
 function formatSigned(cents) {
-  if (cents > 0) return chalk3.green(`+${formatCents3(cents)}`);
-  if (cents < 0) return chalk3.red(formatCents3(cents));
+  if (cents > 0) return chalk4.green(`+${formatCents3(cents)}`);
+  if (cents < 0) return chalk4.red(formatCents3(cents));
   return formatCents3(cents);
 }
 function registerBalanceCommands(parent) {
@@ -3788,7 +5566,7 @@ function registerBalanceCommands(parent) {
       return printJson({ balance, transactions });
     }
     const lowBalance = balance.balance_cents < 100;
-    const balanceLine = lowBalance ? chalk3.red(formatCents3(balance.balance_cents)) + chalk3.dim(" (low)") : chalk3.bold.green(formatCents3(balance.balance_cents));
+    const balanceLine = lowBalance ? chalk4.red(formatCents3(balance.balance_cents)) + chalk4.dim(" (low)") : chalk4.bold.green(formatCents3(balance.balance_cents));
     printDetail([
       ["Credits", balanceLine],
       [
@@ -3803,7 +5581,7 @@ function registerBalanceCommands(parent) {
     ]);
     if (transactions && transactions.length > 0) {
       console.log(`
-${chalk3.bold("Recent transactions")}`);
+${chalk4.bold("Recent transactions")}`);
       printTable(
         ["Date", "Type", "Amount", "Balance", "Reference"],
         transactions.map((row) => [
@@ -3811,19 +5589,19 @@ ${chalk3.bold("Recent transactions")}`);
           KIND_LABELS[row.kind] ?? row.kind,
           formatSigned(row.amount_cents),
           formatCents3(row.balance_after_cents),
-          row.reference_id ? shortId(row.reference_id) : chalk3.dim("\u2014")
+          row.reference_id ? shortId(row.reference_id) : chalk4.dim("\u2014")
         ])
       );
     } else {
       console.log(
         `
-${chalk3.dim("No transactions yet \u2014 run `tt topup` to add credits.")}`
+${chalk4.dim("No transactions yet \u2014 run `tt topup` to add credits.")}`
       );
     }
     if (lowBalance) {
       console.log(
         `
-${formatStatus("preparing")} ${chalk3.yellow(
+${formatStatus("preparing")} ${chalk4.yellow(
           "Run `tt topup` to add more credits before starting a run."
         )}`
       );
@@ -3832,7 +5610,7 @@ ${formatStatus("preparing")} ${chalk3.yellow(
 }
 
 // src/commands/topup.ts
-import chalk4 from "chalk";
+import chalk5 from "chalk";
 import open from "open";
 var PRESETS_USD = [10, 25, 50, 100];
 var MIN_USD = 5;
@@ -3871,9 +5649,9 @@ function registerTopupCommands(parent) {
           "amount is required in --json mode (use --amount <usd>)"
         );
       }
-      console.log(chalk4.bold("Add credits via Stripe Checkout"));
+      console.log(chalk5.bold("Add credits via Stripe Checkout"));
       console.log(
-        chalk4.dim(
+        chalk5.dim(
           `Quick picks: ${PRESETS_USD.map((n) => `$${n}`).join(", ")}`
         )
       );
@@ -3900,8 +5678,8 @@ function registerTopupCommands(parent) {
     }
     const url = data.checkout_url;
     console.log(
-      `${chalk4.bold("Checkout URL:")} ${chalk4.cyan(url)}
-` + chalk4.dim("Complete the payment to credit your account.")
+      `${chalk5.bold("Checkout URL:")} ${chalk5.cyan(url)}
+` + chalk5.dim("Complete the payment to credit your account.")
     );
     if (options.open !== false) {
       try {
@@ -3909,7 +5687,7 @@ function registerTopupCommands(parent) {
         printSuccess("Opened Stripe Checkout in your browser.");
       } catch {
         console.log(
-          chalk4.yellow(
+          chalk5.yellow(
             "Could not open browser automatically \u2014 copy the URL above."
           )
         );
@@ -3919,7 +5697,7 @@ function registerTopupCommands(parent) {
 }
 
 // src/commands/eval.ts
-import chalk5 from "chalk";
+import chalk6 from "chalk";
 
 // src/eval/rules.ts
 function validateSpec(spec) {
@@ -4054,12 +5832,12 @@ function checkExamplesAgainstConstraints(spec) {
   }
   return violations;
 }
-function evaluateConstraint(text, constraint) {
+function evaluateConstraint(text2, constraint) {
   const lower = constraint.toLowerCase();
   const neverMatch = lower.match(/^never (?:share|mention|include|reveal|use|say|output|return|give|provide|show|disclose|expose)\s+(.+)/);
   if (neverMatch) {
     const forbidden = neverMatch[1].replace(/['"]/g, "").trim();
-    if (text.toLowerCase().includes(forbidden.toLowerCase())) {
+    if (text2.toLowerCase().includes(forbidden.toLowerCase())) {
       return { passed: false, message: `Output contains "${forbidden}"` };
     }
     return { passed: true };
@@ -4067,7 +5845,7 @@ function evaluateConstraint(text, constraint) {
   const alwaysMatch = lower.match(/^always (?:include|use|start with|end with|contain|respond in|reply in)\s+(.+)/);
   if (alwaysMatch) {
     const required = alwaysMatch[1].replace(/['"]/g, "").trim();
-    if (!text.toLowerCase().includes(required.toLowerCase())) {
+    if (!text2.toLowerCase().includes(required.toLowerCase())) {
       return { passed: false, message: `Output missing "${required}"` };
     }
     return { passed: true };
@@ -4080,11 +5858,11 @@ function evaluateConstraint(text, constraint) {
 
 // src/commands/eval.ts
 function registerEvalCommand(parent) {
-  parent.command("eval").description("Validate a local behaviour spec").option("-m, --model <model>", "Deprecated; ignored because tt eval only validates the local spec").option("-f, --file <path>", "Spec file path", DEFAULT_SPEC_FILE).action(async (cmdOpts) => {
+  parent.command("eval").description("Validate a behaviour spec project file").option("-m, --model <model>", "Deprecated; ignored because tt eval only validates the local spec").option("-f, --file <path>", "Spec file path", DEFAULT_SPEC_FILE).action(async (cmdOpts) => {
     const spec = loadSpec(cmdOpts.file);
     const validation = validateSpec(spec);
     if (!isJsonMode()) {
-      console.log(chalk5.dim(`
+      console.log(chalk6.dim(`
 Spec: ${cmdOpts.file}
 `));
     }
@@ -4099,71 +5877,321 @@ Spec: ${cmdOpts.file}
   });
 }
 function printValidation(checks) {
-  console.log(chalk5.bold("Spec Validation"));
+  console.log(chalk6.bold("Spec Validation"));
   for (const check of checks) {
-    const icon = check.passed ? chalk5.green("\u2713") : chalk5.red("\u2717");
-    const msg = check.message ? chalk5.dim(` \u2014 ${check.message}`) : "";
+    const icon = check.passed ? chalk6.green("\u2713") : chalk6.red("\u2717");
+    const msg = check.message ? chalk6.dim(` \u2014 ${check.message}`) : "";
     console.log(`  ${icon} ${check.name}${msg}`);
   }
 }
 
 // src/commands/push.ts
 import { readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
-import { resolve as resolve3 } from "path";
+import { resolve as resolve6 } from "path";
+function persistRemoteId(filePath, id) {
+  const raw = JSON.parse(readFileSync8(filePath, "utf-8"));
+  raw.id = id;
+  writeFileSync4(filePath, JSON.stringify(raw, null, 2) + "\n");
+}
 function registerPushCommand(parent) {
   parent.command("push").description("Push local spec to the Tuned Tensor API").option("-f, --file <path>", "Spec file path", DEFAULT_SPEC_FILE).action(async (cmdOpts) => {
     const opts = parent.opts();
-    const filePath = resolve3(cmdOpts.file);
+    const filePath = resolve6(cmdOpts.file);
     const spec = loadSpec(cmdOpts.file);
     const evalCaseErrors = validateEvalCases(spec);
     if (evalCaseErrors.length > 0) {
       throw new Error(`Invalid eval_cases: ${evalCaseErrors.join("; ")}`);
     }
-    const { id, ...rawBody } = spec;
-    const body = canonicalizeSpecBaseModel(rawBody);
+    const rawSpec = spec;
+    const { body } = projectCloudSpec(rawSpec);
+    const id = spec.id;
+    const canRecoverLocalId = Boolean(
+      id && hasLocalOnlySpecFields(rawSpec)
+    );
     let data;
+    let created = false;
     if (id) {
-      const res = await put(`/behavior-specs/${id}`, body, opts);
-      data = res.data;
+      try {
+        const res = await put(
+          `/behavior-specs/${id}`,
+          body,
+          opts
+        );
+        data = res.data;
+      } catch (error) {
+        if (!canRecoverLocalId || !(error instanceof ApiError) || error.status !== 404) {
+          throw error;
+        }
+        const res = await post("/behavior-specs", body, opts);
+        data = res.data;
+        created = true;
+        persistRemoteId(filePath, data.id);
+      }
     } else {
       const res = await post("/behavior-specs", body, opts);
       data = res.data;
-      const raw = JSON.parse(readFileSync8(filePath, "utf-8"));
-      raw.id = data.id;
-      writeFileSync4(filePath, JSON.stringify(raw, null, 2) + "\n");
+      created = true;
+      persistRemoteId(filePath, data.id);
     }
     if (isJsonMode()) return printJson(data);
     printSuccess(
-      `Spec ${id ? "updated" : "created"}: ${data.name} (${shortId(data.id)})`
+      `Spec ${created ? "created" : "updated"}: ${data.name} (${shortId(data.id)})`
     );
   });
 }
 
-// src/index.ts
-var program = new Command();
-program.name("tt").description("Tuned Tensor CLI \u2014 fine-tune and evaluate LLMs").version("0.4.24").option("-k, --api-key <key>", "API key (overrides stored key)").option(
-  "-u, --base-url <url>",
-  "API base URL (default: https://tunedtensor.com)"
-).option("--json", "Output raw JSON").option("--no-color", "Disable colors").hook("preAction", (_thisCommand, actionCommand) => {
-  const rootOpts = program.opts();
-  if (rootOpts.json) setJsonMode(true);
-  if (rootOpts.color === false) {
-    process.env.FORCE_COLOR = "0";
+// src/cli.ts
+async function runSelfCommand(args, options = {}) {
+  const entrypoint = options.entrypoint ?? process.argv[1];
+  if (!entrypoint) {
+    throw new Error("Cannot locate the tt CLI entrypoint.");
+  }
+  return await new Promise((resolve7, reject) => {
+    const child = spawn4(process.execPath, [entrypoint, ...args], {
+      cwd: options.cwd,
+      env: options.env ?? process.env,
+      stdio: "inherit",
+      detached: process.platform !== "win32"
+    });
+    const forwardSignal = (signal) => {
+      const childSignal = signal === "SIGHUP" ? "SIGTERM" : signal;
+      if (child.pid && process.platform !== "win32") {
+        try {
+          process.kill(-child.pid, childSignal);
+          return;
+        } catch {
+        }
+      }
+      child.kill(childSignal);
+    };
+    const onSigint = () => forwardSignal("SIGINT");
+    const onSigterm = () => forwardSignal("SIGTERM");
+    const onSighup = () => forwardSignal("SIGHUP");
+    const cleanup = () => {
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+      if (process.platform !== "win32") process.off("SIGHUP", onSighup);
+    };
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    if (process.platform !== "win32") process.on("SIGHUP", onSighup);
+    child.once("error", (error) => {
+      cleanup();
+      reject(error);
+    });
+    child.once("close", (exitCode, signal) => {
+      cleanup();
+      const signalNumber = signal ? osConstants2.signals[signal] : void 0;
+      resolve7({
+        exitCode: exitCode ?? (typeof signalNumber === "number" ? 128 + signalNumber : 1),
+        signal
+      });
+    });
+  });
+}
+function extractPassthroughOptions(args, root) {
+  let json = Boolean(root.json);
+  let color = root.color !== false;
+  const forwarded = [];
+  for (const arg of args) {
+    if (arg === "--json") {
+      json = true;
+    } else if (arg === "--no-color") {
+      color = false;
+    } else {
+      forwarded.push(arg);
+    }
   }
-});
-registerAuthCommands(program);
-registerSpecsCommands(program);
-registerRunsCommands(program);
-registerDatasetsCommands(program);
-registerLabelCommands(program);
-registerModelsCommands(program);
-registerBalanceCommands(program);
-registerTopupCommands(program);
-registerInitCommand(program);
-registerEvalCommand(program);
-registerPushCommand(program);
-if (process.argv.includes("--json")) setJsonMode(true);
-program.parseAsync().catch((err) => {
+  return { args: forwarded, json, color };
+}
+function childEnvironment(root, base) {
+  return {
+    ...base,
+    ...root.apiKey ? { TUNED_TENSOR_API_KEY: root.apiKey } : {},
+    ...root.baseUrl ? { TUNED_TENSOR_URL: root.baseUrl } : {},
+    ...root.color === false ? { FORCE_COLOR: "0" } : {}
+  };
+}
+function applyExitCode(result) {
+  if (result?.exitCode !== null && result?.exitCode !== void 0) {
+    process.exitCode = result.exitCode;
+  }
+}
+function createProgram(version, runtime = {}) {
+  const program = new Command();
+  const env = runtime.env ?? process.env;
+  const invokeSelf = runtime.runSelfCommand ?? runSelfCommand;
+  const invokeLocal = runtime.runLocalCommand ?? executeLocalCommand;
+  const launchShell = runtime.startShell ?? startInteractiveShell;
+  const cwd = runtime.cwd ?? process.cwd();
+  const shellRunner = async (request2) => {
+    const root = program.opts();
+    const args = request2.target === "local" ? ["local", ...request2.args] : request2.args;
+    return await invokeSelf(args, {
+      cwd: request2.cwd,
+      env: childEnvironment(root, env),
+      entrypoint: runtime.argv?.[1]
+    });
+  };
+  const openShell = async () => {
+    const root = program.opts();
+    const shellEnvironment = childEnvironment(root, env);
+    await launchShell({
+      runner: shellRunner,
+      input: runtime.stdin ?? process.stdin,
+      output: runtime.stdout ?? process.stdout,
+      error: runtime.stderr ?? process.stderr,
+      cwd,
+      env: shellEnvironment
+    });
+  };
+  program.name("tt").description("Tuned Tensor \u2014 one terminal for cloud and local fine-tuning").version(version).option("-k, --api-key <key>", "API key (overrides stored key)").option(
+    "-u, --base-url <url>",
+    "API base URL (default: https://tunedtensor.com)"
+  ).option("--json", "Output raw JSON").option("--no-color", "Disable colors").showSuggestionAfterError().hook("preAction", () => {
+    const root = program.opts();
+    if (root.json) setJsonMode(true);
+    if (root.color === false) {
+      process.env.FORCE_COLOR = "0";
+      chalk7.level = 0;
+    }
+  });
+  registerAuthCommands(program);
+  registerSpecsCommands(program);
+  registerRunsCommands(program);
+  registerDatasetsCommands(program);
+  registerLabelCommands(program);
+  registerModelsCommands(program);
+  registerBalanceCommands(program);
+  registerTopupCommands(program);
+  registerInitCommand(program);
+  registerEvalCommand(program);
+  registerPushCommand(program);
+  program.command("status").description("Show read-only cloud, local, and project context").option("--target <target>", "Show cloud or local workflow status").action(async (commandOptions) => {
+    const root = program.opts();
+    const context = await discoverShellContext({
+      cwd,
+      env: childEnvironment(root, env)
+    });
+    const target = commandOptions.target ?? context.inferredTarget;
+    if (target !== "cloud" && target !== "local") {
+      throw new Error("--target must be cloud or local.");
+    }
+    const output = runtime.stdout ?? process.stdout;
+    if (isJsonMode()) {
+      output.write(`${JSON.stringify({
+        target,
+        context
+      }, null, 2)}
+`);
+      return;
+    }
+    output.write(`${chalk7.bold.cyan("Tuned Tensor status")}
+`);
+    output.write(`${formatShellStatus(context, target).join("\n")}
+
+`);
+    output.write(`${chalk7.bold("Context")}
+`);
+    output.write(
+      `${formatShellContext(
+        context,
+        target,
+        commandOptions.target ? "command-option" : context.targetSource
+      ).join("\n")}
+`
+    );
+  });
+  program.command("local").description("Run the local CUDA training and model workflow").helpOption(false).allowUnknownOption().argument("[args...]", "TT Local command and arguments").action(async (args) => {
+    const root = program.opts();
+    const passthrough = extractPassthroughOptions(args, root);
+    if (!passthrough.color) chalk7.level = 0;
+    const result = await invokeLocal(
+      passthrough.args.length > 0 ? passthrough.args : ["--help"],
+      {
+        jsonMode: passthrough.json,
+        cwd,
+        env: childEnvironment(
+          { ...root, color: passthrough.color },
+          env
+        ),
+        stdin: runtime.stdin ?? process.stdin,
+        stdout: runtime.stdout ?? process.stdout,
+        stderr: runtime.stderr ?? process.stderr
+      }
+    );
+    applyExitCode(result);
+  });
+  program.command("cloud").description("Run a hosted command explicitly").helpOption(false).allowUnknownOption().argument("[args...]", "Hosted tt command and arguments").action(async (args) => {
+    const root = program.opts();
+    const passthrough = extractPassthroughOptions(args, root);
+    const forwarded = [
+      ...passthrough.json ? ["--json"] : [],
+      ...!passthrough.color ? ["--no-color"] : [],
+      ...passthrough.args.length > 0 ? passthrough.args : ["--help"]
+    ];
+    const result = await invokeSelf(forwarded, {
+      cwd,
+      env: childEnvironment(
+        { ...root, color: passthrough.color },
+        env
+      ),
+      entrypoint: runtime.argv?.[1]
+    });
+    applyExitCode(result);
+  });
+  program.command("shell").description("Open the interactive cloud/local terminal").action(openShell);
+  program.addHelpText(
+    "after",
+    `
+Workflows:
+  tt                     Open the interactive terminal (TTY only)
+  tt status              Inspect cloud/local project context
+  tt cloud <command>     Run a hosted command explicitly
+  tt local <command>     Run a local GPU command
+
+Examples:
+  tt runs list
+  tt local doctor tunedtensor.json
+  tt local run tunedtensor.json --dry-run
+`
+  );
+  return program;
+}
+async function runCli(version, runtime = {}) {
+  const argv = runtime.argv ?? process.argv;
+  const env = runtime.env ?? process.env;
+  const args = argv.slice(2);
+  if (shouldStartInteractiveShell({
+    args,
+    stdinIsTTY: runtime.stdinIsTTY ?? process.stdin.isTTY,
+    stdoutIsTTY: runtime.stdoutIsTTY ?? process.stdout.isTTY,
+    env
+  })) {
+    const invokeSelf = runtime.runSelfCommand ?? runSelfCommand;
+    await (runtime.startShell ?? startInteractiveShell)({
+      runner: async (request2) => await invokeSelf(
+        request2.target === "local" ? ["local", ...request2.args] : request2.args,
+        {
+          cwd: request2.cwd,
+          env,
+          entrypoint: argv[1]
+        }
+      ),
+      input: runtime.stdin ?? process.stdin,
+      output: runtime.stdout ?? process.stdout,
+      error: runtime.stderr ?? process.stderr,
+      cwd: runtime.cwd ?? process.cwd(),
+      env
+    });
+    return;
+  }
+  if (argv.includes("--json")) setJsonMode(true);
+  await createProgram(version, { ...runtime, argv }).parseAsync(argv);
+}
+
+// src/index.ts
+runCli("0.5.0").catch((err) => {
   reportError(err);
   process.exit(1);
 });