zelpi 0.1.0

package/cli/commands.mjs

@@ -0,0 +1,406 @@
+// zosCLI — command handlers. Each maps a verb to the API-hooks layer, the
+// kernel profile router, or the hub/repo. Rendering uses cli/ui.mjs.
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import * as api from "./client.mjs";
+import * as cfg from "./config.mjs";
+import { PROFILES, PROFILE_KEYS, resolveProfile, routingNote } from "./kernel.mjs";
+import { SOCS, CHASSIS, MODELS, FAMILIES, resolveModel, chassisByName } from "./hub.mjs";
+import { c, sym, table, bar, kv, heading, hexAccent } from "./ui.mjs";
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), "../../");
+const out = (s = "") => console.log(s);
+const pct = (q) => `${Math.round((q || 0) * 100)}%`;
+
+const STATUS_COLOR = {
+  idle: c.gray, navigating: c.cyan, scanning: c.blue, manipulating: c.yellow,
+  paused: c.red, charging: c.magenta,
+};
+const MODEL_STATUS_COLOR = {
+  training: c.yellow, ready: c.cyan, deployed: c.ok, archived: c.gray,
+};
+const KIND_LAYER = { vla: "S2 · VLA", act: "S1 · ACT", mhal: "S0 · M-HAL" };
+
+function profileBadge(key) {
+  const p = PROFILES[key] ?? PROFILES.balanced;
+  return `${hexAccent(profileHex(key), p.glyph + " " + p.label)}  ${c.dim("(" + routingNote(key) + ")")}`;
+}
+function profileHex(key) {
+  return { balanced: "#94a3b8", robustness: "#60a5fa", optimisation: "#34d399", "system-critical": "#f87171" }[key] ?? "#94a3b8";
+}
+
+// ── status ───────────────────────────────────────────────────────────────────
+export async function status() {
+  const h = await api.health();
+  out(heading("ZelPi · status"));
+  out(kv("Backend", `${cfg.httpBase()}   ${sym.ok} ${c.ok("live")}`));
+  out(kv("Store", h.store ?? "—"));
+  out(kv("Profile", profileBadge(h.profile ?? "balanced")));
+  out(kv("Fleet", `${h.fleet} online`));
+  out(kv("Active tasks", String(h.tasks ?? 0)));
+  const llm = h.llm || {};
+  const llmTxt = !llm.enabled
+    ? c.dim("disabled — deterministic parser")
+    : llm.reachable
+      ? c.ok(`${llm.provider} ready (${llm.model})`)
+      : c.warn(`${llm.provider} unreachable — deterministic fallback`);
+  out(kv("System 2 LLM", llmTxt));
+  out(kv("ROS link", h.ros?.connected ? c.ok("connected") : c.dim("disconnected")));
+  out(kv("Foundry", h.foundry?.enabled ? (h.foundry.reachable ? c.ok("MLflow connected") : c.warn("unreachable")) : c.dim("off (local training)")));
+
+  const snap = await api.snapshot();
+  const dep = snap?.metrics?.deployed ?? {};
+  const depTxt = ["vla", "act", "mhal"]
+    .map((k) => (dep[k] ? `${k.toUpperCase()} ${dep[k].name} v${dep[k].version} ${c.dim("(" + pct(dep[k].quality) + ")")}` : `${k.toUpperCase()} ${c.dim("—")}`))
+    .join("  " + sym.dot + "  ");
+  out(kv("Deployed", depTxt));
+  out();
+}
+
+// ── fleet ──────────────────────────────────────────────────────────────────--
+export async function fleet(args, flags) {
+  if (args[0] === "enroll") return enroll(args.slice(1), flags);
+  const snap = await api.snapshot();
+  out(heading(`ZelPi · fleet  (${snap.robots.length} online)`));
+  const rows = snap.robots.map((r) => [
+    c.bold(r.name),
+    r.chassis,
+    r.bus,
+    (STATUS_COLOR[r.status] ?? ((x) => x))(r.status),
+    bar(r.battery / 100, 10, r.battery < 25 ? c.red : c.green) + " " + pct(r.battery / 100),
+    r.taskId ?? c.dim("—"),
+    c.dim(`(${r.pos.x.toFixed(0)},${r.pos.y.toFixed(0)})`),
+  ]);
+  out(table(["NAME", "CHASSIS", "BUS", "STATUS", "BATTERY", "TASK", "POS"], rows));
+  out();
+}
+
+async function enroll(args, flags) {
+  const name = flags.name || flags.chassis || args.join(" ");
+  const preset = chassisByName(flags.chassis || args.join(" "));
+  if (!preset) {
+    out(`${sym.err} unknown chassis. Available:`);
+    for (const ch of CHASSIS) out(`  ${sym.dot} ${c.bold(ch.chassis)} ${c.dim(`(${ch.bus}, ${ch.joints} joints)`)}`);
+    out(`\n  ${c.dim('e.g.  npx zelpi fleet enroll --chassis "Quadruped" --name Rex --aisle 2')}`);
+    return;
+  }
+  const spec = {
+    name: flags.name || preset.chassis.split(" ")[0],
+    chassis: preset.chassis,
+    bus: preset.bus,
+    joints: preset.joints,
+    aisle: Number(flags.aisle ?? 1),
+  };
+  const before = await api.snapshot();
+  await api.command({ type: "enrollEmbodiment", spec }, { settle: 3 });
+  const after = await api.snapshot();
+  const added = after.robots.find((r) => !before.robots.some((b) => b.id === r.id));
+  out(`${sym.ok} enrolled ${c.bold(added?.name ?? spec.name)} ${c.dim(`(${spec.chassis}, ${spec.bus}, ${spec.joints} joints, aisle ${spec.aisle})`)}`);
+  out(`  ${c.dim("M-HAL adapting hardware-abstraction layer · M2M identity issued.")}`);
+}
+
+// ── models (the VLM/WM/VLA/LLM layer) ────────────────────────────────────────
+export async function models(args, flags) {
+  if (args[0] === "train") return trainModel(args.slice(1), flags);
+  if (args[0] === "deploy") return deployModel(args.slice(1), flags);
+  const snap = await api.snapshot();
+  out(heading(`ZelPi · models  (${snap.models.length})`));
+  const rows = snap.models.map((m) => [
+    c.dim(m.id),
+    KIND_LAYER[m.kind] ?? m.kind,
+    c.bold(m.name),
+    "v" + m.version,
+    (MODEL_STATUS_COLOR[m.status] ?? ((x) => x))(m.status === "deployed" ? "● deployed" : m.status),
+    m.status === "training"
+      ? bar(m.trainProgress, 12, c.yellow) + " " + pct(m.trainProgress)
+      : bar(m.quality, 12, c.green) + " " + pct(m.quality),
+    m.embodiment,
+  ]);
+  out(table(["ID", "LAYER", "NAME", "VER", "STATUS", "QUALITY/TRAIN", "EMBODIMENT"], rows));
+  out(`\n  ${c.dim("train:  npx zelpi models train --kind vla|act|mhal --name <n>     deploy:  npx zelpi models deploy <id>")}`);
+  out();
+}
+
+async function trainModel(args, flags) {
+  const kind = (flags.kind || args[0] || "").toLowerCase();
+  if (!["vla", "act", "mhal"].includes(kind)) {
+    out(`${sym.err} --kind must be one of: vla (S2) · act (S1) · mhal (S0)`);
+    return;
+  }
+  const name = flags.name || args.find((a) => a !== kind) || `${kind}-edge`;
+  const embodiment = flags.embodiment || "universal";
+  const before = await api.snapshot();
+  await api.command({ type: "createModel", kind, name, embodiment }, { settle: 3 });
+  const after = await api.snapshot();
+  const mdl = after.models.find((m) => !before.models.some((b) => b.id === m.id)) || after.models.find((m) => m.name === name);
+  out(`${sym.ok} training ${c.bold(name)} ${c.dim(`(${KIND_LAYER[kind]}, embodiment: ${embodiment})`)}`);
+  if (mdl) out(`  ${c.dim(`id ${mdl.id} · fitting on ${(mdl.datasetMB / 1024).toFixed(2)} GB edge experience → Cloud GPU. Deploy when ready: npx zelpi models deploy ${mdl.id}`)}`);
+  out(`  ${c.dim("watch live:  npx zelpi watch")}`);
+}
+
+async function deployModel(args, flags) {
+  const id = args[0] || flags.id;
+  if (!id) return out(`${sym.err} usage: npx zelpi models deploy <id>`);
+  const snap = await api.snapshot();
+  const mdl = snap.models.find((m) => m.id === id);
+  if (!mdl) return out(`${sym.err} no model ${id}. List: npx zelpi models`);
+  if (mdl.status === "training") return out(`${sym.warn} ${id} still training (${pct(mdl.trainProgress)}). Wait for 'ready'.`);
+  await api.command({ type: "deployModel", id }, { settle: 3 });
+  out(`${sym.ok} deployed ${c.bold(mdl.name)} v${mdl.version} → ${c.bold(KIND_LAYER[mdl.kind])} ${c.dim(`(quality ${pct(mdl.quality)})`)}`);
+  out(`  ${c.dim("Global model pushed to fleet; prior version demoted.")}`);
+}
+
+// ── hub / repo (SOCs · chassis · HF model registry) ──────────────────────────
+export async function hub(args, flags) {
+  const sub = args[0];
+  if (sub === "pull") return pull(args.slice(1), flags);
+  if (sub === "socs" || sub === "soc") return out(socsTable());
+  if (sub === "chassis") return out(chassisTable());
+  if (sub === "models" || sub === "registry") return out(modelsTable());
+  out(heading("ZelPi · hub — compatible SOCs, chassis & model registry"));
+  out(socsTable());
+  out(chassisTable());
+  out(modelsTable());
+  out(`\n  ${c.dim("load a model:  npx zelpi hub pull pi0        or any HF id:  npx zelpi hub pull openvla/openvla-7b")}`);
+  out();
+}
+
+function socsTable() {
+  const rows = SOCS.map((s) => [c.bold(s.id), s.vendor, s.accel, String(s.tops) + " TOPS", s.bus, s.note]);
+  return heading("Compatible SOCs (edge inference targets)") + "\n" +
+    table(["SOC", "VENDOR", "ACCELERATOR", "COMPUTE", "BUS", "NOTE"], rows);
+}
+function chassisTable() {
+  const rows = CHASSIS.map((ch) => [c.bold(ch.chassis), ch.bus, String(ch.joints)]);
+  return heading("Chassis embodiments (M-HAL targets)") + "\n" +
+    table(["CHASSIS", "BUS", "JOINTS"], rows);
+}
+function modelsTable() {
+  const rows = MODELS.map((m) => [c.bold(m.key), m.family, (KIND_LAYER[m.kind] ?? m.kind), m.hf, m.license, m.note]);
+  return heading(`Model registry — families: ${FAMILIES.join(" · ")}  (→ .hf)`) + "\n" +
+    table(["KEY", "FAMILY", "LAYER", "HUGGINGFACE", "LICENSE", "NOTE"], rows);
+}
+
+async function pull(args, flags) {
+  const ref = args[0] || flags.model;
+  if (!ref) return out(`${sym.err} usage: npx zelpi hub pull <key|hf-id>   (e.g. pi0, openvla/openvla-7b)`);
+  const m = resolveModel(ref);
+  const name = flags.name || m.name;
+  out(`${m.known ? sym.ok : sym.warn} resolving ${c.bold(ref)} ${c.dim(`→ ${m.family} · ${KIND_LAYER[m.kind]} · ${m.license}`)}`);
+  out(`  ${c.dim(`loading weights from Hugging Face: ${m.hf}`)}`);
+  const before = await api.snapshot();
+  await api.command({ type: "createModel", kind: m.kind, name, embodiment: flags.embodiment || "universal" }, { settle: 3 });
+  const after = await api.snapshot();
+  const mdl = after.models.find((x) => !before.models.some((b) => b.id === x.id)) || after.models.find((x) => x.name === name);
+  out(`${sym.ok} registered ${c.bold(name)} → fine-tuning on fleet experience (Cloud GPU).`);
+  if (mdl) out(`  ${c.dim(`id ${mdl.id} · deploy when ready:  npx zelpi models deploy ${mdl.id}`)}`);
+}
+
+// ── profile (kernel QoS router) ──────────────────────────────────────────────
+export async function profile(args) {
+  if (!args[0]) {
+    const snap = await api.snapshot().catch(() => null);
+    const active = snap?.profile ?? cfg.load().profile;
+    out(heading("ZelPi · kernel profiles"));
+    for (const k of PROFILE_KEYS) {
+      const p = PROFILES[k];
+      const mark = k === active ? c.ok("●") : c.gray("○");
+      out(`  ${mark} ${hexAccent(profileHex(k), p.glyph + " " + p.label.padEnd(26))} ${c.dim(p.desc)}`);
+      out(`      ${c.dim(routingNote(k))}`);
+    }
+    out(`\n  ${c.dim("switch:  npx zelpi profile optimisation")}`);
+    return;
+  }
+  const key = resolveProfile(args[0]);
+  if (!key) return out(`${sym.err} unknown profile '${args[0]}'. One of: ${PROFILE_KEYS.join(", ")}`);
+  await api.command({ type: "setProfile", profile: key }, { settle: 2 });
+  cfg.set("profile", key);
+  out(`${sym.ok} kernel profile → ${profileBadge(key)}`);
+}
+
+// ── intent (routed through the active/selected profile) ──────────────────────
+export async function intent(args, flags) {
+  const text = args.join(" ").trim();
+  if (!text) return out(`${sym.err} usage: npx zelpi intent "Inventory Aisle 4"  [--profile optimisation]`);
+  if (flags.profile) {
+    const key = resolveProfile(flags.profile);
+    if (!key) return out(`${sym.err} unknown profile '${flags.profile}'`);
+    await api.command({ type: "setProfile", profile: key }, { settle: 1 });
+    cfg.set("profile", key);
+    out(`${sym.dot} routing via ${profileBadge(key)}`);
+  }
+  const before = await api.snapshot();
+  const beforeIds = new Set(before.tasks.map((t) => t.id));
+  out(`${sym.arrow} ${c.bold(text)} ${c.dim("· System 2 planning…")}`);
+  // The intent is planned asynchronously (LLM); wait for the new task to land.
+  const after = await api.command(
+    { type: "intent", text },
+    { until: (s) => s.tasks.some((t) => !beforeIds.has(t.id)), timeout: 12000 },
+  );
+  const task = after.tasks.find((t) => !beforeIds.has(t.id)) || after.tasks[after.tasks.length - 1];
+  if (!task) return out(`  ${c.dim("(dispatched)")}`);
+  const robot = after.robots.find((r) => r.id === task.robotId);
+  out(`  ${sym.ok} ${c.bold(task.id)} ${c.dim("·")} ${task.summary}`);
+  out(`  ${c.dim("assigned →")} ${c.bold(robot?.name ?? task.robotId)} ${c.dim(`(${robot?.chassis ?? "?"})`)}`);
+  for (const st of task.subtasks) {
+    const g = { queued: c.gray("○"), active: c.cyan("◉"), done: c.ok("✓"), blocked: c.red("⚠") }[st.state] ?? "·";
+    out(`    ${g} ${st.label} ${c.dim(`[${st.agent}/${st.kind}]`)}`);
+  }
+  if (after.safety) out(`\n  ${sym.warn} ${c.red("Safety gate raised:")} ${after.safety.message}\n     ${c.dim("resolve:")} npx zelpi safety ${after.safety.options.map((o) => o.toLowerCase()).join(" | ")}`);
+  out(`  ${c.dim("watch it run:  npx zelpi watch")}`);
+}
+
+// ── safety broker / HITL gate ────────────────────────────────────────────────
+export async function safety(args) {
+  const snap = await api.snapshot();
+  if (!snap.safety) {
+    out(`${sym.ok} no pending safety gate. Fleet trajectories clear.`);
+    return;
+  }
+  const s = snap.safety;
+  if (!args[0]) {
+    out(heading("ZelPi · Safety Broker — HITL gate"));
+    out(`  ${sym.warn} ${c.red(s.kind.toUpperCase())}: ${s.message}`);
+    const robot = snap.robots.find((r) => r.id === s.robotId);
+    out(`  ${c.dim("robot:")} ${robot?.name ?? s.robotId}   ${c.dim("task:")} ${s.taskId}`);
+    out(`  ${c.dim("decide:")} ${s.options.map((o) => c.bold(o)).join(c.dim(" | "))}`);
+    out(`\n  ${c.dim("e.g.  npx zelpi safety " + s.options[0].toLowerCase())}`);
+    return;
+  }
+  const choice = s.options.find((o) => o.toLowerCase() === args[0].toLowerCase()) || args[0];
+  await api.command({ type: "resolveSafety", option: choice }, { settle: 3 });
+  out(`${sym.ok} resolved HITL gate → ${c.bold(choice)}`);
+}
+
+// ── live watch (activity feed + metrics) ─────────────────────────────────────
+export function watch() {
+  out(c.dim("watching ZelPi — Ctrl-C to stop\n"));
+  let lastLogId = 0;
+  let firstFrame = true;
+  const stop = api.watch((snap) => {
+    if (firstFrame) {
+      const known = snap.logs.map((l) => l.id);
+      lastLogId = known.length ? Math.max(...known) : 0;
+      firstFrame = false;
+      renderHeader(snap);
+      return;
+    }
+    for (const log of snap.logs) {
+      if (log.id <= lastLogId) continue;
+      lastLogId = log.id;
+      out(formatLog(log));
+    }
+  });
+  process.on("SIGINT", () => { stop(); out("\n" + c.dim("stopped.")); process.exit(0); });
+}
+
+const SYS_COLOR = { S3: c.magenta, S2: c.blue, S1: c.green, S0: c.yellow, SAFETY: c.red, HITL: c.yellow, OP: c.cyan };
+const LEVEL_GLYPH = { info: c.gray("·"), act: c.cyan("▸"), warn: c.warn("▲"), alert: c.red("⚠"), ok: c.ok("✓") };
+function formatLog(l) {
+  const sys = (SYS_COLOR[l.system] ?? ((x) => x))(l.system.padEnd(6));
+  return `  ${c.dim(l.t.toFixed(1).padStart(6))}  ${LEVEL_GLYPH[l.level] ?? "·"} ${sys} ${l.text}`;
+}
+function renderHeader(snap) {
+  const m = snap.metrics;
+  out(c.dim(`  clock ${m.clock.toFixed(0)}s · fleet ${m.fleetOnline} · tasks ${m.activeTasks} · profile ${snap.profile} · S2 ${m.hz.S2.toFixed(1)}Hz S1 ${m.hz.S1.toFixed(0)}Hz S0 ${m.hz.S0.toFixed(0)}Hz`));
+  out(c.gray("  " + "─".repeat(60)));
+}
+
+// ── lifecycle: pause / resume / reset ────────────────────────────────────────
+export async function pause() {
+  const snap = await api.command({ type: "togglePause" }, { settle: 2 });
+  out(`${sym.ok} fleet ${snap?.paused ? c.warn("paused") : c.ok("running")}`);
+}
+export const resume = pause;
+export async function reset() {
+  await api.command({ type: "reset" }, { settle: 2 });
+  out(`${sym.ok} world reset to seed state.`);
+}
+
+// ── metrics (Prometheus exposition passthrough) ──────────────────────────────
+export async function metrics() {
+  const txt = await api.metricsText();
+  out(typeof txt === "string" ? txt : JSON.stringify(txt, null, 2));
+}
+
+// ── login (fetch a dev JWT, persist to config) ───────────────────────────────
+export async function login(args) {
+  const user = args[0] || "operator";
+  const res = await api.login(user);
+  if (res.token) {
+    cfg.set("token", res.token);
+    out(`${sym.ok} token stored for ${c.bold(user)} ${c.dim(res.authEnabled ? "(auth enforced)" : "(auth currently off)")}`);
+  } else {
+    out(`${sym.err} no token returned`);
+  }
+}
+
+// ── up: boot the backend (full repo backend if present, else embedded) ───────
+export async function up(args, flags) {
+  // already live?
+  try {
+    const h = await api.health();
+    out(`${sym.ok} backend already live at ${cfg.httpBase()} ${c.dim(`(fleet ${h.fleet}, store ${h.store})`)}`);
+    if (!flags.force) return;
+  } catch { /* not up — boot it */ }
+
+  const serverEntry = path.join(REPO_ROOT, "server", "server.ts");
+  const useFull = !flags.embedded && fs.existsSync(serverEntry);
+  if (useFull) {
+    const ros = flags.ros ? "server:ros" : "server";
+    out(`${sym.arrow} starting full backend ${c.dim(`(npm run ${ros}, LLM-capable) — Ctrl-C to stop`)}\n`);
+    const child = spawn("npm", ["run", ros], { cwd: REPO_ROOT, stdio: "inherit", env: process.env });
+    child.on("exit", (code) => process.exit(code ?? 0));
+    await new Promise(() => {}); // keep foreground until the child exits
+    return;
+  }
+  // self-contained embedded backend (no repo / no tsx needed)
+  await serverForeground(args, flags);
+}
+
+// ── __server: run the embedded backend foreground (also spawned as a daemon) ──
+export async function serverForeground(args, flags) {
+  const port = Number(flags.port ?? cfg.load().port ?? 8787);
+  const quiet = !!flags.quiet;
+  const { createEmbeddedServer } = await import("./embedded.mjs");
+  let handle;
+  try {
+    handle = await createEmbeddedServer({ port });
+  } catch (e) {
+    if (e?.code === "EADDRINUSE") { if (!quiet) out(`${sym.warn} port ${port} already in use — a backend may already be running.`); return; }
+    throw e;
+  }
+  if (!quiet) {
+    out(`${sym.ok} ${c.ok("embedded ZelPi backend live")} ${c.dim(`→ http://127.0.0.1:${port} (ws://127.0.0.1:${port})`)}`);
+    out(`  ${c.dim("deterministic System-2 parser · state persists to ~/.zelpi· Ctrl-C to stop")}`);
+  }
+  const shutdown = () => { handle.close(); process.exit(0); };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  await new Promise(() => {}); // run until killed
+}
+
+// ── down: stop the embedded daemon ───────────────────────────────────────────
+export async function down() {
+  const { stopDaemon } = await import("./daemon.mjs");
+  const info = stopDaemon();
+  if (info?.pid) out(`${sym.ok} stopped embedded backend ${c.dim(`(pid ${info.pid})`)}`);
+  else out(`${sym.dot} no embedded backend daemon was running.`);
+}
+
+// ── config ───────────────────────────────────────────────────────────────────
+export function config(args) {
+  if (args[0] === "set" && args[1] && args[2] !== undefined) {
+    const value = args[1] === "port" ? Number(args[2]) : args[2];
+    cfg.set(args[1], value);
+    out(`${sym.ok} ${args[1]} = ${args[2]}`);
+    return;
+  }
+  const conf = cfg.load();
+  out(heading("ZelPi · config") + `  ${c.dim(cfg.CONFIG_FILE)}`);
+  for (const [k, v] of Object.entries(conf)) out(kv(k, k === "token" && v ? c.dim("(set)") : String(v || c.dim("—"))));
+  out(`\n  ${c.dim("set:  npx zelpi config set host 10.0.0.5    npx zelpi config set port 8787")}`);
+}

package/cli/config.mjs

@@ -0,0 +1,58 @@
+// pi-os CLI — persistent config (~/.pi-os/config.json).
+// Stores the backend endpoint, auth token, and the active kernel profile so the
+// CLI behaves like a stateful OS shell across invocations.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const DIR = path.join(os.homedir(), ".pi-os");
+const FILE = path.join(DIR, "config.json");
+
+const DEFAULTS = {
+  // The MCP / API-hooks endpoint the CLI drives. HTTP for /health + db views,
+  // ws:// for the live command + snapshot channel.
+  host: "127.0.0.1",
+  port: 8787,
+  token: process.env.PIOS_TOKEN ?? "",
+  profile: "balanced",
+};
+
+export function load() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(FILE, "utf8"));
+    return { ...DEFAULTS, ...raw };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+export function save(cfg) {
+  try {
+    fs.mkdirSync(DIR, { recursive: true });
+    fs.writeFileSync(FILE, JSON.stringify(cfg, null, 2));
+  } catch {
+    /* best-effort; CLI still works with in-memory config */
+  }
+}
+
+export function set(key, value) {
+  const cfg = load();
+  cfg[key] = value;
+  save(cfg);
+  return cfg;
+}
+
+export function httpBase(cfg = load()) {
+  const env = process.env.PIOS_HOST;
+  if (env) return env.replace(/\/$/, "");
+  return `http://${cfg.host}:${cfg.port}`;
+}
+
+export function wsUrl(cfg = load()) {
+  const env = process.env.PIOS_WS_URL;
+  const base = env || `ws://${cfg.host}:${cfg.port}`;
+  return cfg.token ? `${base}?token=${encodeURIComponent(cfg.token)}` : base;
+}
+
+export { FILE as CONFIG_FILE };

package/cli/daemon.mjs

@@ -0,0 +1,75 @@
+// pi-os CLI — local embedded-backend lifecycle.
+// `ensureBackend()` makes one-shot commands "just work" after `npm i -g zelpi`:
+// if the configured backend is local and not running, it boots the embedded
+// server (cli/embedded.mjs) as a detached daemon and waits for health. Remote
+// backends (PIOS_HOST set to another machine) are left untouched.
+
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { httpBase, load } from "./config.mjs";
+
+const BIN = path.resolve(fileURLToPath(import.meta.url), "../../bin/pi-os.mjs");
+const DAEMON_FILE = path.join(os.homedir(), ".pi-os", "daemon.json");
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function reachable(base, timeout = 800) {
+  try {
+    const res = await fetch(base + "/health", { signal: AbortSignal.timeout(timeout) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function isLocal(base) {
+  try {
+    const h = new URL(base).hostname;
+    return h === "127.0.0.1" || h === "localhost" || h === "::1";
+  } catch {
+    return false;
+  }
+}
+
+/** Ensure a backend is up. Auto-starts the embedded daemon for local targets.
+ *  Returns { mode: "remote" | "running" | "started" | "unreachable" }. */
+export async function ensureBackend() {
+  const base = httpBase();
+  if (await reachable(base)) return { mode: "running", base };
+  if (!isLocal(base)) return { mode: "remote", base }; // user manages the remote host
+  if (process.env.PIOS_NO_AUTOSTART) return { mode: "unreachable", base };
+
+  const port = load().port || 8787;
+  const child = spawn(process.execPath, [BIN, "__server", "--port", String(port), "--quiet"], {
+    detached: true,
+    stdio: "ignore",
+    env: process.env,
+  });
+  child.unref();
+  try {
+    fs.mkdirSync(path.dirname(DAEMON_FILE), { recursive: true });
+    fs.writeFileSync(DAEMON_FILE, JSON.stringify({ pid: child.pid, port, startedAt: Date.now() }));
+  } catch { /* best-effort */ }
+
+  for (let i = 0; i < 40; i++) {
+    if (await reachable(base, 400)) return { mode: "started", base, pid: child.pid };
+    await sleep(150);
+  }
+  return { mode: "unreachable", base };
+}
+
+/** Stop the embedded daemon if we started one. */
+export function stopDaemon() {
+  let info;
+  try { info = JSON.parse(fs.readFileSync(DAEMON_FILE, "utf8")); } catch { return null; }
+  if (info?.pid) {
+    try { process.kill(info.pid); } catch { /* already gone */ }
+  }
+  try { fs.rmSync(DAEMON_FILE); } catch {}
+  return info;
+}
+
+export { DAEMON_FILE };

package/cli/dispatch.mjs

@@ -0,0 +1,70 @@
+// zosCLI — argument parsing + verb→handler dispatch. Shared by the binary
+// entrypoint and the interactive REPL so both speak an identical command set.
+
+import * as cmd from "./commands.mjs";
+import { mcp } from "./mcp.mjs";
+import { c, sym } from "./ui.mjs";
+
+/** Split tokens into positional args and --flags (--k v / --k=v / --bool). */
+export function parseArgs(tokens) {
+  const _ = [];
+  const flags = {};
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.startsWith("--")) {
+      const body = t.slice(2);
+      if (body.includes("=")) {
+        const [k, ...v] = body.split("=");
+        flags[k] = v.join("=");
+      } else if (tokens[i + 1] != null && !tokens[i + 1].startsWith("--")) {
+        flags[body] = tokens[++i];
+      } else {
+        flags[body] = true;
+      }
+    } else {
+      _.push(t);
+    }
+  }
+  return { _, flags };
+}
+
+// Verb → handler. Aliases point at the same function.
+export const COMMANDS = {
+  status: cmd.status, stat: cmd.status, st: cmd.status,
+  intent: cmd.intent, run: cmd.intent, do: cmd.intent,
+  fleet: cmd.fleet, robots: cmd.fleet,
+  models: cmd.models, model: cmd.models,
+  hub: cmd.hub, repo: cmd.hub,
+  profile: cmd.profile, prof: cmd.profile,
+  safety: cmd.safety, hitl: cmd.safety,
+  watch: cmd.watch, logs: cmd.watch, feed: cmd.watch,
+  pause: cmd.pause, resume: cmd.resume,
+  reset: cmd.reset,
+  metrics: cmd.metrics,
+  login: cmd.login,
+  up: cmd.up, serve: cmd.up, start: cmd.up,
+  down: cmd.down, stop: cmd.down,
+  config: cmd.config,
+  mcp: () => mcp(),
+  __server: cmd.serverForeground,
+};
+
+// Commands that should NOT trigger embedded-backend auto-start.
+export const NO_AUTOSTART = new Set(["help", "version", "config", "up", "serve", "start", "down", "stop", "__server"]);
+
+/** Run a parsed argv (array of tokens). Returns a promise. */
+export async function run(tokens) {
+  const verb = tokens[0];
+  const handler = COMMANDS[verb];
+  const { _, flags } = parseArgs(tokens.slice(1));
+  if (!handler) {
+    // No verb match: in an OS shell, bare text is an intent.
+    if (verb && !verb.startsWith("-")) {
+      const parsed = parseArgs(tokens);
+      return cmd.intent(parsed._, parsed.flags);
+    }
+    console.log(`${sym.err} unknown command '${verb}'. Try: ${c.dim("npx zelpi help")}`);
+    return;
+  }
+  return handler(_, flags);
+}