zelpi 0.1.0

package/cli/embedded.mjs

@@ -0,0 +1,106 @@
+// pi-os CLI — embedded backend. Runs the bundled PiOsEngine in-process and
+// serves the exact same HTTP /health + WebSocket snapshot/command protocol the
+// full server (server/server.ts) speaks. This is what makes `npm i -g pios`
+// self-contained: no repo, no tsx, no database — the OS runs anywhere Node does.
+//
+// Intent parsing here is the deterministic offline parser baked into the engine
+// (no LLM/keys), matching the public offline web demo.
+
+import http from "node:http";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { WebSocketServer } from "ws";
+import { PiOsEngine } from "../dist/pios-engine.mjs";
+
+const TICK_MS = 25; // ~40 Hz
+const BROADCAST_EVERY = 3; // ~13 Hz snapshots
+const STATE_FILE = path.join(os.homedir(), ".pi-os", "embedded-state.json");
+
+export function createEmbeddedServer({ port = 8787, persist = true } = {}) {
+  const engine = new PiOsEngine();
+
+  if (persist) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
+      engine.importState(raw);
+    } catch { /* fresh world */ }
+  }
+
+  const health = () => {
+    const s = engine.getSnapshot();
+    return {
+      ok: true,
+      clock: s.metrics.clock,
+      fleet: s.robots.length,
+      tasks: s.tasks.length,
+      profile: s.profile,
+      store: "embedded",
+      llm: { enabled: false, provider: "off", reachable: false, model: "(deterministic)", url: "" },
+      ros: { enabled: false, connected: false, url: "" },
+      foundry: { enabled: false, reachable: false, url: "", tracked: 0 },
+      auth: { enabled: false },
+      embedded: true,
+    };
+  };
+
+  const server = http.createServer((req, res) => {
+    res.setHeader("access-control-allow-origin", "*");
+    res.setHeader("content-type", "application/json");
+    const url = req.url ?? "";
+    if (url === "/health") { res.writeHead(200); res.end(JSON.stringify(health())); return; }
+    if (url === "/db/tasks") { res.writeHead(200); res.end(JSON.stringify(engine.getSnapshot().tasks)); return; }
+    if (url === "/db/models") { res.writeHead(200); res.end(JSON.stringify(engine.getSnapshot().models)); return; }
+    res.writeHead(404); res.end("{}");
+  });
+
+  const wss = new WebSocketServer({ server });
+  const snapshotMessage = () => JSON.stringify({ type: "snapshot", snap: engine.getSnapshot() });
+  const broadcast = () => { const msg = snapshotMessage(); for (const c of wss.clients) if (c.readyState === 1) c.send(msg); };
+
+  wss.on("connection", (ws) => {
+    ws.send(snapshotMessage());
+    ws.on("message", (data) => {
+      let m;
+      try { m = JSON.parse(data.toString()); } catch { return; }
+      switch (m.type) {
+        case "intent": engine.submitIntent(String(m.text ?? "")); break;
+        case "resolveSafety": engine.resolveSafety(String(m.option ?? "")); break;
+        case "createModel": engine.createModel(m.kind, String(m.name ?? ""), String(m.embodiment ?? "universal")); break;
+        case "deployModel": engine.deployModel(String(m.id ?? "")); break;
+        case "enrollEmbodiment": engine.enrollEmbodiment(m.spec); break;
+        case "setProfile": engine.setProfile(m.profile); break;
+        case "togglePause": engine.togglePause(); break;
+        case "forceSafety": engine.forceSafety(); break;
+        case "reset": engine.reset(); break;
+      }
+    });
+  });
+
+  let last = Date.now();
+  let n = 0;
+  const tick = setInterval(() => {
+    const now = Date.now();
+    const dt = (now - last) / 1000;
+    last = now;
+    engine.tick(dt);
+    if (++n % BROADCAST_EVERY === 0) broadcast();
+  }, TICK_MS);
+
+  let saver = null;
+  const save = () => {
+    if (!persist) return;
+    try {
+      fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+      fs.writeFileSync(STATE_FILE, JSON.stringify(engine.exportState()));
+    } catch { /* best-effort */ }
+  };
+  if (persist) saver = setInterval(save, 3000);
+
+  const close = () => { clearInterval(tick); if (saver) clearInterval(saver); save(); try { wss.close(); } catch {} try { server.close(); } catch {} };
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => resolve({ engine, port, close }));
+  });
+}

package/cli/help.mjs

@@ -0,0 +1,44 @@
+// ZelPi CLI — help text.
+import { c } from "./ui.mjs";
+
+export const HELP = `
+${c.bold(c.cyan("ZelPi"))} ${c.dim("— Physical Intelligence Operating System · CLI")}
+
+${c.bold("USAGE")}
+  npx zelpi                     ${c.dim("interactive OS shell (REPL)")}
+  npx zelpi <command> [args] [--flags]
+
+${c.bold("COMMAND & CONTROL")}
+  status                         ${c.dim("backend health, profile, fleet, deployed models")}
+  intent "<text>" [--profile p]  ${c.dim('submit a natural-language intent (e.g. "Inventory Aisle 4")')}
+  safety [authorize|reroute|abort]  ${c.dim("show / resolve the Human-in-the-Loop gate")}
+  watch                          ${c.dim("stream the live activity feed (Ctrl-C to stop)")}
+  pause | resume | reset         ${c.dim("fleet lifecycle")}
+
+${c.bold("KERNEL — QoS profile router")}
+  profile                        ${c.dim("list profiles + the active one")}
+  profile <name>                 ${c.dim("balanced | robustness | optimisation | system-critical")}
+
+${c.bold("FLEET & EMBODIMENT")}
+  fleet                          ${c.dim("list robots")}
+  fleet enroll --chassis "<c>" [--name <n>] [--aisle <n>]
+
+${c.bold("MODELS — VLM · World-Model · VLA · LLM")}
+  models                         ${c.dim("list the model registry")}
+  models train --kind vla|act|mhal [--name <n>] [--embodiment <e>]
+  models deploy <id>             ${c.dim("promote a ready model to the live fleet")}
+
+${c.bold("HUB / REPO — SOCs · chassis · HuggingFace")}
+  hub [socs|chassis|models]      ${c.dim("compatible SOCs, embodiments, model registry")}
+  hub pull <key|hf-id>           ${c.dim("load a model from HF (e.g. pi0, openvla/openvla-7b)")}
+
+${c.bold("PLATFORM")}
+  up [--ros] [--force]           ${c.dim("boot the backend from this checkout")}
+  mcp                            ${c.dim("run the MCP server (expose ZelPi to AI agents over stdio)")}
+  login [user]                   ${c.dim("fetch + store a dev JWT")}
+  metrics                        ${c.dim("Prometheus exposition")}
+  config [set <key> <value>]     ${c.dim("backend host/port/token")}
+
+${c.bold("ENV")}
+  PIOS_HOST=http://host:port  PIOS_WS_URL=ws://host:port  PIOS_TOKEN=<jwt>  NO_COLOR=1
+`;

package/cli/hub.mjs

@@ -0,0 +1,76 @@
+// pi-os CLI — Hub / Repo: the bottom layer of the architecture diagram.
+// A catalog of compatible embedded SOCs, the chassis embodiments the M-HAL can
+// adapt to, and the model-architecture registry that bridges the diagram's model
+// families (VLM · World-Model · VLA · LLM) to Hugging Face checkpoints and to the
+// engine's policy layers (vla → S2, act → S1, mhal → S0). `pull` loads a model.
+
+// ── Compatible embedded SOCs (edge inference targets) ────────────────────────
+export const SOCS = [
+  { id: "jetson-agx-orin", vendor: "NVIDIA", accel: "Ampere GPU + 2×NVDLA", tops: 275, bus: "CAN/EtherCAT", ros: "ROS 2", profile: "system-critical", note: "Flagship edge — runs VLA + perception on-device." },
+  { id: "jetson-orin-nx", vendor: "NVIDIA", accel: "Ampere GPU", tops: 100, bus: "CAN", ros: "ROS 2", profile: "robustness", note: "Balanced humanoid/AMR compute." },
+  { id: "jetson-orin-nano", vendor: "NVIDIA", accel: "Ampere GPU", tops: 40, bus: "CAN", ros: "ROS 2", profile: "optimisation", note: "Low-power AMRs and sensors." },
+  { id: "qualcomm-qrb5165", vendor: "Qualcomm", accel: "Hexagon DSP + Adreno", tops: 15, bus: "CAN", ros: "ROS 2", profile: "optimisation", note: "RB5 robotics platform, 5G." },
+  { id: "rockchip-rk3588", vendor: "Rockchip", accel: "6 TOPS NPU", tops: 6, bus: "CAN", ros: "ROS 2 (community)", profile: "optimisation", note: "Cheap quantized-model inference." },
+  { id: "hailo8-rpi5", vendor: "Raspberry Pi + Hailo", accel: "Hailo-8 NPU", tops: 26, bus: "CAN (HAT)", ros: "ROS 2", profile: "optimisation", note: "Hobby/edge perception accelerator." },
+  { id: "ti-tda4vm", vendor: "Texas Instruments", accel: "C7x DSP + MMA", tops: 8, bus: "CAN-FD/EtherCAT", ros: "ROS 2", profile: "system-critical", note: "Automotive-grade, functional safety." },
+  { id: "amd-kria-k26", vendor: "AMD", accel: "FPGA (Zynq UltraScale+)", tops: 26, bus: "EtherCAT", ros: "ROS 2", profile: "system-critical", note: "Deterministic real-time control." },
+  { id: "renesas-rzv2h", vendor: "Renesas", accel: "DRP-AI3", tops: 80, bus: "EtherCAT", ros: "ROS 2", profile: "robustness", note: "Power-efficient vision + control." },
+];
+
+// ── Chassis embodiments (mirrors CHASSIS_PRESETS in lib/types.ts) ────────────
+export const CHASSIS = [
+  { chassis: "Humanoid biped", bus: "EtherCAT", joints: 28 },
+  { chassis: "6-DoF industrial arm", bus: "CAN", joints: 6 },
+  { chassis: "AMR cart", bus: "CAN", joints: 4 },
+  { chassis: "Quadruped", bus: "EtherCAT", joints: 12 },
+  { chassis: "Heavy-lift forklift", bus: "CAN", joints: 5 },
+  { chassis: "Dual-arm torso", bus: "EtherCAT", joints: 14 },
+];
+
+// ── Model-architecture registry (the VLM · WM · VLA · LLM layer) ──────────────
+// `kind` maps onto the engine's policy layers: vla→S2, act→S1, mhal→S0.
+export const MODELS = [
+  { key: "pi0", family: "VLA", kind: "vla", hf: "lerobot/pi0", license: "Apache-2.0", note: "Physical Intelligence π0 — generalist manipulation (flow-matching)." },
+  { key: "openvla-7b", family: "VLA", kind: "vla", hf: "openvla/openvla-7b", license: "MIT", note: "7B open VLA, strong generalist baseline." },
+  { key: "smolvla", family: "VLA", kind: "vla", hf: "lerobot/smolvla_base", license: "Apache-2.0", note: "Small efficient VLA for the edge." },
+  { key: "act", family: "ACT", kind: "act", hf: "lerobot/act", license: "Apache-2.0", note: "Action-Chunking Transformer visuomotor policy." },
+  { key: "diffusion-policy", family: "ACT", kind: "act", hf: "lerobot/diffusion_policy", license: "MIT", note: "Diffusion visuomotor policy." },
+  { key: "groot-n1", family: "World-Model", kind: "mhal", hf: "nvidia/GR00T-N1", license: "NVIDIA OSL", note: "Humanoid whole-body foundation behaviors." },
+  { key: "isaac-wbc", family: "World-Model", kind: "mhal", hf: "—", license: "BSD-3 (Isaac Lab)", note: "Per-embodiment RL whole-body control (you train it)." },
+  { key: "llama-3.3-70b", family: "LLM", kind: "vla", hf: "meta-llama/Llama-3.3-70B-Instruct", license: "Llama 3.3", note: "Cloud reasoning for intent decomposition (via gateway)." },
+  { key: "qwen2.5-vl", family: "VLM", kind: "vla", hf: "Qwen/Qwen2.5-VL-7B-Instruct", license: "Apache-2.0", note: "Vision-language grounding for the Command Center." },
+  { key: "sam2", family: "VLM", kind: "vla", hf: "facebook/sam2-hiera-large", license: "Apache-2.0", note: "Segment-Anything 2 — perception (Vision agent)." },
+];
+
+export const FAMILIES = ["VLM", "World-Model", "VLA", "LLM", "ACT"];
+
+/** Resolve a catalog key or a raw HF id into createModel() arguments. */
+export function resolveModel(idOrKey) {
+  if (!idOrKey) return null;
+  const q = String(idOrKey).trim();
+  const hit = MODELS.find((m) => m.key === q.toLowerCase() || m.hf === q);
+  if (hit) {
+    return { kind: hit.kind, name: hit.key, hf: hit.hf, family: hit.family, license: hit.license, known: true };
+  }
+  // Unknown HF id: accept it, infer the layer from the path heuristically.
+  const lower = q.toLowerCase();
+  const kind = /vla|pi0|openvla|smolvla|qwen|llama|vlm|sam/.test(lower)
+    ? "vla"
+    : /diffusion|act|policy/.test(lower)
+      ? "act"
+      : /groot|wbc|control|whole/.test(lower)
+        ? "mhal"
+        : "vla";
+  const name = q.split("/").pop().replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 32);
+  return { kind, name, hf: q, family: "VLA", license: "unknown", known: false };
+}
+
+export function chassisByName(name) {
+  if (!name) return null;
+  const q = String(name).toLowerCase();
+  return (
+    CHASSIS.find((c) => c.chassis.toLowerCase() === q) ||
+    CHASSIS.find((c) => c.chassis.toLowerCase().includes(q)) ||
+    null
+  );
+}

package/cli/kernel.mjs

@@ -0,0 +1,63 @@
+// pi-os CLI — Kernel: the QoS profile router from the architecture diagram.
+// Every intent is routed through one execution profile that trades execution
+// speed against Safety-Broker scrutiny. These specs mirror PROFILE_META in
+// lib/types.ts (the engine applies the same factors server-side).
+
+export const PROFILES = {
+  balanced: {
+    label: "Balanced (Kernel default)",
+    glyph: "◇",
+    desc: "Neutral routing — the kernel's baseline scheduler.",
+    speed: 1.0,
+    scrutiny: 1.0,
+    aliases: ["default", "neutral"],
+  },
+  robustness: {
+    label: "Robustness",
+    glyph: "▣",
+    desc: "Handle many SOCs, buses & hardware; multi-system spread, extra checks.",
+    speed: 0.95,
+    scrutiny: 1.2,
+    aliases: ["robust", "r"],
+  },
+  optimisation: {
+    label: "Optimisation",
+    glyph: "⚡",
+    desc: "Fastest response for routine tasks where speed beats deliberation.",
+    speed: 1.4,
+    scrutiny: 0.5,
+    aliases: ["optimization", "optimise", "optimize", "fast", "opt", "o"],
+  },
+  "system-critical": {
+    label: "System-Critical",
+    glyph: "◆",
+    desc: "Precise, high-integrity work — maximum Safety-Broker scrutiny.",
+    speed: 0.82,
+    scrutiny: 1.8,
+    aliases: ["critical", "syscrit", "sc", "safe", "precise"],
+  },
+};
+
+export const PROFILE_KEYS = Object.keys(PROFILES);
+
+/** Resolve a user-typed profile name or alias to a canonical key. */
+export function resolveProfile(input) {
+  if (!input) return null;
+  const k = String(input).toLowerCase().trim();
+  if (PROFILES[k]) return k;
+  for (const [key, spec] of Object.entries(PROFILES)) {
+    if (spec.aliases?.includes(k)) return key;
+  }
+  return null;
+}
+
+/** Human-readable summary of how a profile re-tunes the live stack. */
+export function routingNote(key) {
+  const p = PROFILES[key];
+  if (!p) return "";
+  const spd = Math.round((p.speed - 1) * 100);
+  const scr = Math.round((p.scrutiny - 1) * 100);
+  const spdTxt = spd === 0 ? "nominal speed" : `${spd > 0 ? "+" : ""}${spd}% execution speed`;
+  const scrTxt = scr === 0 ? "nominal gating" : `${scr > 0 ? "+" : ""}${scr}% Safety-Broker gating`;
+  return `${spdTxt}, ${scrTxt}`;
+}

package/cli/mcp.mjs

@@ -0,0 +1,144 @@
+// pi-os CLI — MCP server (the diagram's northbound "MCP / API Hooks" layer).
+// Exposes ZelPi as Model-Context-Protocol tools so an AI agent can drive the
+// fleet over stdio: newline-delimited JSON-RPC 2.0, zero dependencies.
+// IMPORTANT: stdout carries only protocol frames; all logging goes to stderr.
+
+import readline from "node:readline";
+import * as api from "./client.mjs";
+import { PROFILE_KEYS } from "./kernel.mjs";
+import { SOCS, MODELS } from "./hub.mjs";
+
+const log = (...a) => process.stderr.write("[pi-os mcp] " + a.join(" ") + "\n");
+const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+const ok = (id, result) => send({ jsonrpc: "2.0", id, result });
+const err = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+const textResult = (obj) => ({ content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }] });
+
+const TOOLS = [
+  {
+    name: "pios_status",
+    description: "Get ZelPi backend health: store, active kernel profile, fleet size, active tasks, LLM/ROS/Foundry status, and deployed models.",
+    inputSchema: { type: "object", properties: {} },
+    run: async () => {
+      const h = await api.health();
+      const snap = await api.snapshot();
+      return { ...h, deployed: snap?.metrics?.deployed };
+    },
+  },
+  {
+    name: "pios_intent",
+    description: "Submit a natural-language intent to the fleet (e.g. 'Inventory Aisle 4', 'Retrieve the green box from Aisle 3'). Optionally set the kernel QoS profile first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "the natural-language command" },
+        profile: { type: "string", enum: PROFILE_KEYS, description: "optional kernel profile to route through" },
+      },
+      required: ["text"],
+    },
+    run: async (a) => {
+      if (a.profile) await api.command({ type: "setProfile", profile: a.profile }, { settle: 1 });
+      const before = await api.snapshot();
+      const beforeIds = new Set(before.tasks.map((t) => t.id));
+      const after = await api.command(
+        { type: "intent", text: String(a.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.at(-1);
+      return { task, safety: after.safety };
+    },
+  },
+  {
+    name: "pios_set_profile",
+    description: "Set the kernel QoS execution profile (the diagram's profile router). System-Critical raises Safety-Broker scrutiny; Optimisation favors speed.",
+    inputSchema: { type: "object", properties: { profile: { type: "string", enum: PROFILE_KEYS } }, required: ["profile"] },
+    run: async (a) => {
+      const snap = await api.command({ type: "setProfile", profile: a.profile }, { settle: 2 });
+      return { profile: snap?.profile ?? a.profile };
+    },
+  },
+  {
+    name: "pios_fleet",
+    description: "List robots in the fleet with chassis, bus, status, battery, position, and assigned task.",
+    inputSchema: { type: "object", properties: {} },
+    run: async () => (await api.snapshot()).robots,
+  },
+  {
+    name: "pios_models",
+    description: "List the model registry (VLA/ACT/M-HAL artifacts) with status, version, quality, and training progress.",
+    inputSchema: { type: "object", properties: {} },
+    run: async () => (await api.snapshot()).models,
+  },
+  {
+    name: "pios_deploy_model",
+    description: "Deploy a ready model to the live fleet by id (promotes it, demotes the prior version on that layer).",
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+    run: async (a) => {
+      await api.command({ type: "deployModel", id: String(a.id) }, { settle: 3 });
+      return { deployed: a.id };
+    },
+  },
+  {
+    name: "pios_resolve_safety",
+    description: "Resolve the pending Human-in-the-Loop safety gate with an operator decision (e.g. Authorize, Reroute, Abort, Override).",
+    inputSchema: { type: "object", properties: { option: { type: "string" } }, required: ["option"] },
+    run: async (a) => {
+      const snap = await api.snapshot();
+      if (!snap.safety) return { resolved: false, reason: "no pending safety gate" };
+      await api.command({ type: "resolveSafety", option: String(a.option) }, { settle: 3 });
+      return { resolved: true, option: a.option };
+    },
+  },
+  {
+    name: "pios_hub",
+    description: "List the hub/repo: compatible embedded SOCs and the HuggingFace-backed model registry (VLM/World-Model/VLA/LLM families).",
+    inputSchema: { type: "object", properties: {} },
+    run: async () => ({ socs: SOCS, models: MODELS }),
+  },
+];
+
+const TOOL_MAP = Object.fromEntries(TOOLS.map((t) => [t.name, t]));
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+  switch (method) {
+    case "initialize":
+      return ok(id, {
+        protocolVersion: params?.protocolVersion ?? "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "zelpi", version: "0.1.0" },
+      });
+    case "notifications/initialized":
+    case "initialized":
+      return; // notification, no reply
+    case "ping":
+      return ok(id, {});
+    case "tools/list":
+      return ok(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+    case "tools/call": {
+      const tool = TOOL_MAP[params?.name];
+      if (!tool) return err(id, -32602, `unknown tool: ${params?.name}`);
+      try {
+        const result = await tool.run(params.arguments ?? {});
+        return ok(id, textResult(result));
+      } catch (e) {
+        return ok(id, { ...textResult(`error: ${e.message || e}`), isError: true });
+      }
+    }
+    default:
+      if (id !== undefined) return err(id, -32601, `method not found: ${method}`);
+  }
+}
+
+export function mcp() {
+  log(`serving ${TOOLS.length} tools over stdio → ${process.env.PIOS_HOST || "default backend"}`);
+  const rl = readline.createInterface({ input: process.stdin });
+  rl.on("line", async (line) => {
+    const s = line.trim();
+    if (!s) return;
+    let msg;
+    try { msg = JSON.parse(s); } catch { return log("bad JSON frame"); }
+    try { await handle(msg); } catch (e) { if (msg?.id !== undefined) err(msg.id, -32603, String(e.message || e)); }
+  });
+  rl.on("close", () => process.exit(0));
+}

package/cli/repl.mjs

@@ -0,0 +1,100 @@
+// pi-os CLI — interactive OS shell. A persistent prompt that speaks the same
+// command set as the binary (via dispatch). Bare text is treated as an intent,
+// so the shell behaves like a conversational operating system console.
+
+import readline from "node:readline";
+import { run } from "./dispatch.mjs";
+import * as api from "./client.mjs";
+import * as cfg from "./config.mjs";
+import { PROFILES } from "./kernel.mjs";
+import { c, sym, banner } from "./ui.mjs";
+import { HELP } from "./help.mjs";
+
+function tokenize(line) {
+  // split on spaces, honoring "double quotes" so intents can contain spaces
+  const out = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(line))) out.push(m[1] ?? m[2] ?? m[3]);
+  return out;
+}
+
+export async function repl() {
+  console.log(banner());
+  let live = false;
+  let profile = cfg.load().profile;
+  try {
+    const h = await api.health();
+    live = true;
+    profile = h.profile ?? profile;
+    console.log(`\n  ${sym.ok} ${c.ok("backend live")} ${c.dim(`· ${cfg.httpBase()} · fleet ${h.fleet} · store ${h.store}`)}`);
+  } catch {
+    console.log(`\n  ${sym.warn} ${c.warn("backend offline")} ${c.dim(`· ${cfg.httpBase()} — type 'up' to start it`)}`);
+  }
+  console.log(`  ${c.dim("type a command, an intent in plain English, or 'help'. 'exit' to quit.")}\n`);
+
+  const prompt = () => {
+    const p = PROFILES[profile] ?? PROFILES.balanced;
+    return `${c.cyan("zelpi")} ${c.dim(p.glyph)} ${c.gray("▸")} `;
+  };
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: prompt() });
+  rl.prompt();
+
+  // Process lines strictly one-at-a-time. readline (esp. with piped input) can
+  // emit many 'line' events plus 'close' synchronously; a queue lets each async
+  // command finish before the next runs, and defers exit until the queue drains.
+  const queue = [];
+  let busy = false;
+  let closing = false;
+
+  const finish = () => { console.log(c.dim("\nzos session closed.")); process.exit(0); };
+
+  async function pump() {
+    if (busy) return;
+    const line = queue.shift();
+    if (line === undefined) { if (closing) finish(); return; }
+    busy = true;
+    try {
+      await handle(line);
+    } catch (e) {
+      console.log(`${sym.err} ${c.red(e.message || String(e))}`);
+    } finally {
+      busy = false;
+      if (!closing) { rl.setPrompt(prompt()); rl.prompt(); }
+      pump();
+    }
+  }
+
+  async function handle(line) {
+    const tokens = tokenize(line.trim());
+    const verb = tokens[0];
+    if (!verb) return;
+    if (verb === "exit" || verb === "quit" || verb === "q") { closing = true; return; }
+    if (verb === "help" || verb === "?") { console.log(HELP); return; }
+    if (verb === "clear" || verb === "cls") { console.clear(); return; }
+    // 'watch' would block the REPL on SIGINT; run a bounded tail instead.
+    if (verb === "watch" || verb === "logs" || verb === "feed") { await tailOnce(); return; }
+    await run(tokens);
+    // keep the prompt's profile glyph in sync after a profile switch
+    const snap = await api.snapshot().catch(() => null);
+    if (snap?.profile) profile = snap.profile;
+  }
+
+  rl.on("line", (line) => { queue.push(line); pump(); });
+  rl.on("close", () => { closing = true; pump(); });
+}
+
+// In-REPL 'watch': print one rolling window of the activity feed, then return.
+function tailOnce() {
+  return new Promise((resolve) => {
+    let frames = 0;
+    let lastId = 0;
+    const stop = api.watch((snap) => {
+      if (frames === 0) lastId = snap.logs.length ? Math.max(...snap.logs.map((l) => l.id)) : 0;
+      for (const l of snap.logs) if (l.id > lastId) { lastId = l.id; console.log(`  ${c.dim(l.t.toFixed(1))} ${l.system} ${l.text}`); }
+      if (++frames > 60) { stop(); resolve(); } // ~5s window
+    });
+    setTimeout(() => { stop(); resolve(); }, 5000);
+  });
+}

package/cli/ui.mjs

@@ -0,0 +1,109 @@
+// pi-os CLI — terminal presentation layer (ANSI colors, boxes, tables, bars).
+// Zero dependencies. Respects NO_COLOR and non-TTY output.
+
+const COLOR = process.env.NO_COLOR == null && (process.stdout.isTTY ?? false);
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  gray: "\x1b[90m",
+  brightGreen: "\x1b[92m",
+  brightYellow: "\x1b[93m",
+  brightCyan: "\x1b[96m",
+};
+
+function wrap(code, s) {
+  return COLOR ? code + s + C.reset : String(s);
+}
+
+export const c = {
+  bold: (s) => wrap(C.bold, s),
+  dim: (s) => wrap(C.dim, s),
+  red: (s) => wrap(C.red, s),
+  green: (s) => wrap(C.green, s),
+  yellow: (s) => wrap(C.yellow, s),
+  blue: (s) => wrap(C.blue, s),
+  magenta: (s) => wrap(C.magenta, s),
+  cyan: (s) => wrap(C.cyan, s),
+  gray: (s) => wrap(C.gray, s),
+  ok: (s) => wrap(C.brightGreen, s),
+  warn: (s) => wrap(C.brightYellow, s),
+};
+
+/** Map a hex color from the domain meta to the nearest ANSI for accents. */
+export function hexAccent(hex, s) {
+  const map = {
+    "#60a5fa": c.blue,
+    "#34d399": c.green,
+    "#fbbf24": c.yellow,
+    "#c084fc": c.magenta,
+    "#f87171": c.red,
+    "#fb923c": c.yellow,
+    "#94a3b8": c.gray,
+  };
+  return (map[hex] ?? ((x) => x))(s);
+}
+
+// strip ANSI for width calculations
+const ANSI = /\x1b\[[0-9;]*m/g;
+export const visibleLen = (s) => String(s).replace(ANSI, "").length;
+
+export function pad(s, n, align = "left") {
+  const len = visibleLen(s);
+  if (len >= n) return s;
+  const fill = " ".repeat(n - len);
+  return align === "right" ? fill + s : s + fill;
+}
+
+/** Render a small table from rows of cells (already color-formatted ok). */
+export function table(headers, rows) {
+  const widths = headers.map((h, i) =>
+    Math.max(visibleLen(h), ...rows.map((r) => visibleLen(r[i] ?? "")))
+  );
+  const line = (cells) => cells.map((cell, i) => pad(cell ?? "", widths[i])).join("  ");
+  const out = [c.bold(line(headers)), c.gray(widths.map((w) => "─".repeat(w)).join("  "))];
+  for (const r of rows) out.push(line(r));
+  return out.join("\n");
+}
+
+/** A 0..1 progress / level bar. */
+export function bar(value, width = 16, color = c.green) {
+  const v = Math.max(0, Math.min(1, value || 0));
+  const filled = Math.round(v * width);
+  return color("█".repeat(filled)) + c.gray("░".repeat(width - filled));
+}
+
+export function banner() {
+  const art = [
+    "  ███████╗███████╗██╗     ██████╗ ██╗",
+    "  ╚══███╔╝██╔════╝██║     ██╔══██╗██║",
+    "    ███╔╝ █████╗  ██║     ██████╔╝██║",
+    "   ███╔╝  ██╔══╝  ██║     ██╔═══╝ ██║",
+    "  ███████╗███████╗███████╗██║     ██║",
+    "  ╚══════╝╚══════╝╚══════╝╚═╝     ╚═╝",
+  ];
+  return c.cyan(art.join("\n")) + "\n  " + c.dim("Physical Intelligence Operating System · CLI");
+}
+
+export const sym = {
+  ok: c.ok("✓"),
+  warn: c.warn("▲"),
+  err: c.red("✗"),
+  dot: c.gray("·"),
+  arrow: c.gray("→"),
+};
+
+export function heading(s) {
+  return "\n" + c.bold(c.cyan("▍" + s));
+}
+
+export function kv(key, value, keyWidth = 14) {
+  return "  " + c.gray(pad(key, keyWidth)) + " " + value;
+}