moshcode 0.91.0 → 0.93.0

package/README.md

@@ -1010,6 +1010,58 @@ an equity's score, and each response ships the `caveats` that say so. Prices are
 Alpaca's US venue alone and can differ materially from other exchanges. Research
 aid, not advice — and like `stocks`, nothing under `crypto` can place an order.
 
+### Throttle (`/nice`)
+
+The pit's job is starting other people's programs, and some of them are not shy.
+Run a few engines at once on a box you also want to type on and you get the
+failure everyone knows: nothing crashed, but the machine stops answering.
+
+```text
+/nice agents claude    # throttle this one engine
+/nice pnpm -r build    # …or this one shell line
+/nice merge            # …or any other pit command
+
+/nice on          # or throttle everything from here on
+/nice mem 2G      # a ceiling, so a runaway dies alone
+/nice cpu 15      # yield more (nice takes -20..19)
+/nice             # what it is set to
+/nice off         # back to normal priority (the default)
+```
+
+`/nice <line>` is the form to reach for. It runs **anything the pit can already
+run** — a pit command, an engine, a tool, one of your aliases, or a bare shell
+line — at low priority, without changing any setting. It works on all of those
+because it hands the rest of the line back to the top of the dispatcher exactly
+as an alias expansion does, rather than keeping a list of its own that would
+drift. The leading slash is optional: `/nice agents claude` and
+`/nice /agents claude` are the same line.
+
+The throttle lasts exactly as long as the line that asked for it, including
+through an alias that expands into something else. The next thing you type is
+back to normal.
+
+`/nice on` is the other half, for when the box is shared all day and you would
+rather decide once. It is off by default — a throttle nobody asked for is a slow
+engine nobody can explain — and it applies to engines started *after* you turn
+it on. The settings words (`on`, `off`, `status`, `cpu`, `io`, `mem`) win the
+first position, so a program named `on` is not reachable through `/nice`.
+
+**`nice` alone is half a fix, and it is worth knowing which half.** It reorders
+CPU, so it buys back the part of a freeze you could have waited out. It does
+nothing about memory, and memory is the stall that actually costs you a session:
+once free RAM runs out the kernel reclaims, reclaim goes to disk, and no
+scheduling priority makes that faster. That is why `/nice mem` exists — it puts
+the engine in a systemd scope with a hard ceiling, so the one runaway process
+gets killed instead of the whole box going unresponsive.
+
+The ceiling is the one setting that can silently not apply: `systemd-run --user`
+needs a systemd user session, and an ssh login without lingering has none.
+`/nice` says so in its status line rather than pretending, and the CPU and I/O
+halves still work. On a box with no `nice` or `ionice` at all, and on Windows,
+the whole thing is a no-op — engines spawn exactly as they did before.
+
+Settings live in `~/.moshcode/nice.json`, owner-only like the history file.
+
 ### Aliases (`/alias`)
 
 The pit is a prompt you sit at all day, so it lets you name the lines you keep

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moshcode",
-  "version": "0.91.0",
+  "version": "0.93.0",
   "type": "module",
   "description": "moshcode \u2014 a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
   "repository": {

package/src/cli-schema.mjs

@@ -1596,6 +1596,23 @@ export const PIT_COMMANDS = [
     description: "show the current dir + git repo/branch/origin" },
   { name: "shell", aliases: ["sh"], args: "[cmd]", pitOnly: true,
     description: "drop into $SHELL (exit → back to the pit); also !cmd" },
+  { name: "nice", aliases: ["throttle"], args: "<command> | on | off | cpu <n> | io <n> | mem <size>", pitOnly: true,
+    description: "run something at low priority so the box stays usable",
+    synopsis: [
+      ["/nice <command> [args]", "run one line throttled — a pit command, engine, tool, alias or shell line"],
+      ["/nice [status]", "what the throttle is set to"],
+      ["/nice on | off", "throttle everything from here on (off by default)"],
+      ["/nice cpu <-20..19>", "nice level — higher yields more CPU"],
+      ["/nice io <0..7>", "ionice best-effort level"],
+      ["/nice mem <size> | off", "memory ceiling per engine (needs systemd)"],
+    ],
+    examples: [
+      ["/nice agents claude", "throttle this engine, leave the setting alone"],
+      ["/nice pnpm -r build", "a shell line works too"],
+      ["/nice on", "nice -n10 + ionice -c2 -n7 for every engine started after"],
+      ["/nice mem 2G", "the ceiling nice(1) can't give you — a runaway dies alone"],
+    ],
+    seeAlso: ["agents", "start", "alias"] },
   { name: "alias", aliases: ["aliases"], args: 'set <name> "<cmd>" | list | get | rm | install <tool>', pitOnly: true,
     description: "name a line you keep retyping; /<name> runs it",
     synopsis: [

package/src/engines.mjs

@@ -37,6 +37,7 @@ import { homedir } from "node:os";
 import path from "node:path";
 
 import { setActiveChildInput } from "./mirror.mjs";
+import { throttleSpec } from "./nice.mjs";
 import { captureSpec } from "./pty.mjs";
 
 export const ENGINES = {
@@ -338,7 +339,22 @@ function nodeShebang(file) {
   }
 }
 
+/**
+ * Where every CLI the pit starts is turned into a spawnable command.
+ *
+ * Both launch paths go through here — `runCmd` for installers and updaters,
+ * `openPassthrough` for the engines themselves — which makes it the one place
+ * the resource throttle has to be applied to cover all of them. It wraps
+ * *outside* resolution on purpose: `nice` needs a real executable to hand off
+ * to, and an unresolved binary must still produce its own ENOENT rather than
+ * one from a wrapper that obscures which program was actually missing.
+ * `/nice off` (the default) returns the spec untouched.
+ */
 function spawnSpec(bin, args = [], extraDirs = []) {
+  return throttleSpec(resolveSpec(bin, args, extraDirs));
+}
+
+function resolveSpec(bin, args = [], extraDirs = []) {
   const resolved = resolveExecutable(bin, extraDirs);
   // Unresolved, so hand the spawn the preferred name and let it produce the
   // ENOENT — a list would be spawned as a single nonsense filename.

package/src/nice.mjs

@@ -0,0 +1,235 @@
+// Run the CLIs the pit launches at a lower priority than everything else.
+//
+// The pit's whole job is starting other people's programs, and some of them are
+// not shy: a coding engine holding a big context, a bundler, a browser under
+// test. Start a few at once on a box you also want to type on and you get the
+// failure everyone knows — the machine stops answering. Nothing crashed. Every
+// core is busy, the last of the RAM went to swap, and the swap went to disk.
+//
+// `nice` is the classic answer to that and it is *half* of one. It reorders CPU
+// and nothing else, so it fixes the part of the freeze you can wait out and not
+// the part that kills a process. The stall that actually costs you an afternoon
+// is memory: once free RAM runs out the kernel starts reclaiming, reclaim goes
+// to disk, and no scheduling priority on earth makes that faster. So a throttle
+// worth the name has to cover three resources, not one:
+//
+//   CPU     nice -n 10          the engine yields to whatever you are typing in
+//   I/O     ionice -c 2 -n 7    its reads stop starving the rest of the box
+//   memory  systemd-run scope   a ceiling, so a runaway dies alone
+//
+// Only the first two are free. A memory ceiling needs a cgroup, which on a
+// normal login means a systemd user session, which not every box has — an ssh
+// login without lingering enabled is the common way to not have one. So the
+// memory cap is opt-in (`/nice mem 2G`) rather than default: a throttle that
+// refuses to launch anything on a box without systemd would be worse than no
+// throttle at all. CPU and I/O work everywhere that has the binaries, and
+// degrade to "no wrapper" where they don't.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+/** Same 0600 as aliases and history: this file records how you run things. */
+const FILE_MODE = 0o600;
+
+/**
+ * `nice -n 10` and `ionice -c 2 -n 7` — deliberately not the extremes.
+ *
+ * nice 19 and ionice class 3 (idle) both mean "run only when nothing else
+ * wants the machine", which sounds right and is not: an engine that yields
+ * *completely* can take minutes to answer while a single background job holds
+ * the box, and a coding CLI that never finishes reads as broken rather than as
+ * polite. 10 and 7 are "last in line among normal work", which is the actual
+ * intent — you keep your terminal, the engine keeps making progress.
+ */
+export const DEFAULTS = Object.freeze({ cpu: 10, io: 7, memoryMax: "", memoryHigh: "" });
+
+/** A memory size systemd would accept: 512M, 2G, 1500K, or a byte count. */
+const MEM_RE = /^\d+(\.\d+)?[KMGT]?$/i;
+
+/** Where the throttle setting lives. Derived per call so tests can move $HOME. */
+export function niceFile() {
+  return path.join(os.homedir(), ".moshcode", "nice.json");
+}
+
+/**
+ * `/nice <line>` throttles one line without changing the saved setting.
+ *
+ * Module-level rather than threaded through every call because the thing being
+ * throttled is not a function argument -- it is whatever that line eventually
+ * spawns, which may be an alias that expands to a pit command that starts an
+ * engine, three dispatch rounds later. The pit reads one line at a time and
+ * fully awaits it, so "armed until the next line the user types" is both the
+ * simplest implementation and exactly the intent.
+ */
+let oneShot = false;
+
+/** Throttle whatever the current line ends up spawning. */
+export function armOneShot() { oneShot = true; }
+
+/**
+ * Stop throttling. The pit calls this when it reads a fresh line, NOT when a
+ * command finishes: one typed line can dispatch several times through alias
+ * expansion, and all of it is the line the user asked to be nice.
+ */
+export function disarmOneShot() { oneShot = false; }
+
+/** Is a one-shot throttle in force? */
+export function oneShotArmed() { return oneShot; }
+
+/**
+ * The settings a spawn should actually use: what is saved, plus a one-shot.
+ *
+ * `/nice on` and `/nice <cmd>` end in the same place by design -- a spawn does
+ * not need to know which of the two asked for it.
+ */
+export function effectiveNice() {
+  const saved = loadNice();
+  return oneShot ? { ...saved, on: true } : saved;
+}
+
+/**
+ * The current settings, always a complete object.
+ *
+ * Read on the spawn path for every CLI the pit starts, so a missing,
+ * unreadable, or hand-mangled file has to read as "throttle off" rather than
+ * throw. A file that says something we don't recognise loses only the field it
+ * got wrong: the point of this object is to decide how to launch a program, and
+ * one bad key must not stop the program launching.
+ */
+export function loadNice() {
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(niceFile(), "utf8")); }
+  catch { return { on: false, ...DEFAULTS }; }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { on: false, ...DEFAULTS };
+  const num = (v, fallback) => (Number.isInteger(v) ? v : fallback);
+  const mem = (v) => (typeof v === "string" && MEM_RE.test(v.trim()) ? v.trim().toUpperCase() : "");
+  return {
+    on: parsed.on === true,
+    cpu: clampCpu(num(parsed.cpu, DEFAULTS.cpu)),
+    io: clampIo(num(parsed.io, DEFAULTS.io)),
+    memoryMax: mem(parsed.memoryMax),
+    memoryHigh: mem(parsed.memoryHigh),
+  };
+}
+
+/** nice(1) accepts -20..19; anything else is a typo, not an intention. */
+export function clampCpu(n) { return Math.min(19, Math.max(-20, n)); }
+/** ionice best-effort levels are 0..7. */
+export function clampIo(n) { return Math.min(7, Math.max(0, n)); }
+
+/** Persist settings, creating ~/.moshcode on first use. */
+export function saveNice(settings) {
+  const file = niceFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const body = {
+    on: settings.on === true,
+    cpu: clampCpu(Number.isInteger(settings.cpu) ? settings.cpu : DEFAULTS.cpu),
+    io: clampIo(Number.isInteger(settings.io) ? settings.io : DEFAULTS.io),
+    memoryMax: settings.memoryMax || "",
+    memoryHigh: settings.memoryHigh || "",
+  };
+  fs.writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`, { mode: FILE_MODE });
+  // `mode` only applies at creation; tighten every write the way aliases does.
+  try { fs.chmodSync(file, FILE_MODE); } catch { /* best effort */ }
+  return body;
+}
+
+/** Is `bin` runnable here? Cached, because this is asked on every spawn. */
+const lookupCache = new Map();
+export function haveBin(bin, { spawn = spawnSync } = {}) {
+  if (lookupCache.has(bin)) return lookupCache.get(bin);
+  let found = false;
+  try { found = spawn("sh", ["-c", `command -v ${bin}`], { stdio: "ignore" }).status === 0; }
+  catch { found = false; }
+  lookupCache.set(bin, found);
+  return found;
+}
+
+/** Only used by tests, which need to ask about a box they are pretending about. */
+export function resetBinCache() { lookupCache.clear(); }
+
+/** Is a memory ceiling actually enforceable here? Needs a systemd user cgroup. */
+export function canCapMemory({ has = haveBin, env = process.env } = {}) {
+  if (!has("systemd-run")) return false;
+  // --user needs a session bus to place the scope in. Over ssh without
+  // lingering there is none, and systemd-run fails rather than degrading —
+  // which would take the engine down with it. Check before, not after.
+  return Boolean(env.XDG_RUNTIME_DIR || env.DBUS_SESSION_BUS_ADDRESS);
+}
+
+/**
+ * Wrap a spawn spec so the child runs throttled. Returns a new spec plus a
+ * short `how` describing what was actually applied.
+ *
+ * Everything here is best-effort by design: each wrapper is added only if its
+ * binary exists, and a box with none of them gets the original spec back. The
+ * alternative — refusing to launch, or launching a command line referencing a
+ * binary that isn't there — turns a comfort feature into an outage.
+ *
+ * Windows has no nice/ionice/cgroups in this form, so it is a no-op there
+ * rather than a wrong guess.
+ */
+export function throttleSpec(spec, {
+  settings = effectiveNice(),
+  has = haveBin,
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  const plain = { cmd: spec.cmd, args: spec.args ?? [], throttled: false, how: "" };
+  if (!settings.on || platform === "win32") return plain;
+
+  let cmd = spec.cmd;
+  let args = [...(spec.args ?? [])];
+  const how = [];
+
+  // Innermost first: each wrapper below prepends, so build outward.
+  if (has("ionice")) {
+    args = ["-c", "2", "-n", String(settings.io), cmd, ...args];
+    cmd = "ionice";
+    how.push(`ionice -c2 -n${settings.io}`);
+  }
+  if (has("nice")) {
+    args = ["-n", String(settings.cpu), cmd, ...args];
+    cmd = "nice";
+    how.push(`nice -n${settings.cpu}`);
+  }
+  // Outermost, so the scope contains the whole niced pipeline rather than
+  // sitting inside it — a cgroup only accounts for what it encloses.
+  const caps = [];
+  if (settings.memoryHigh) caps.push(`MemoryHigh=${settings.memoryHigh}`);
+  if (settings.memoryMax) caps.push(`MemoryMax=${settings.memoryMax}`);
+  if (caps.length && canCapMemory({ has, env })) {
+    const props = caps.flatMap((p) => ["-p", p]);
+    args = ["--user", "--scope", "--quiet", ...props, "--", cmd, ...args];
+    cmd = "systemd-run";
+    how.push(caps.join(" "));
+  }
+
+  if (cmd === spec.cmd) return plain;
+  return { cmd, args, throttled: true, how: how.join(" ") };
+}
+
+/** One line for `/nice` with no arguments. */
+export function describeNice(settings = loadNice(), opts = {}) {
+  if (!settings.on) return "throttle is off — CLIs run at normal priority";
+  const parts = [`nice -n${settings.cpu}`, `ionice -c2 -n${settings.io}`];
+  if (settings.memoryMax || settings.memoryHigh) {
+    const caps = [
+      settings.memoryHigh ? `MemoryHigh=${settings.memoryHigh}` : "",
+      settings.memoryMax ? `MemoryMax=${settings.memoryMax}` : "",
+    ].filter(Boolean).join(" ");
+    parts.push(canCapMemory(opts) ? caps : `${caps} (no systemd user session here — not applied)`);
+  }
+  return `throttle is on — ${parts.join(", ")}`;
+}
+
+/** Validate a memory size the way the command wants to report it. */
+export function parseMemory(value) {
+  const clean = String(value ?? "").trim().toUpperCase();
+  if (!clean || clean === "OFF" || clean === "NONE") return { ok: true, value: "" };
+  if (!MEM_RE.test(clean)) {
+    return { ok: false, error: `"${value}" isn't a memory size — try 2G, 1500M, or off` };
+  }
+  return { ok: true, value: clean };
+}

package/src/tui.mjs

@@ -22,6 +22,10 @@ import { activeChildInput, createMirror, pressKey, setActiveSink, teeOutput } fr
 import { fetchMotdAd } from "./ads.mjs";
 import { runScript } from "./runtime.mjs";
 import { moshVocabulary } from "./commands.mjs";
+import {
+  loadNice, saveNice, describeNice, canCapMemory, parseMemory,
+  armOneShot, disarmOneShot,
+} from "./nice.mjs";
 import { mcpCommand, pluginCommand, skillCommand } from "./integrations.mjs";
 import { stocksCommand } from "./advisor.mjs";
 import { cryptoCommand } from "./crypto.mjs";
@@ -388,6 +392,73 @@ function isInstalledTool(key) {
  * line, not an argument list: re-joining tokens would drop the quoting that the
  * shell still has to read.
  */
+/**
+ * The words that mean "configure the throttle" rather than "run this".
+ *
+ * Kept next to the command that implements them so the two cannot drift: every
+ * other first word after `/nice` is a line to run, so adding a verb here
+ * without teaching niceCommand about it would make that word silently
+ * unrunnable rather than produce an error.
+ */
+const NICE_SETTING_VERBS = new Set(["on", "off", "status", "cpu", "io", "mem", "memory"]);
+
+/**
+ * `/nice` — run the CLIs the pit starts at a lower priority than your terminal.
+ *
+ * A toggle rather than a per-launch flag because the thing being tuned is the
+ * box, not the command: you decide once that this machine is shared, and every
+ * engine started afterwards honours it. Off by default — a throttle nobody
+ * asked for is a slow engine nobody can explain.
+ */
+function niceCommand(rest) {
+  const [verb, ...args] = rest.filter((a) => a !== "--json");
+  const sub = String(verb ?? "").toLowerCase();
+  const json = rest.includes("--json");
+  const settings = loadNice();
+
+  if (json) { console.log(JSON.stringify(settings, null, 2)); return; }
+
+  if (!verb || sub === "status") {
+    console.log(info(describeNice(settings)));
+    if (!settings.on) console.log(ash(`   ${acid("/nice on")} throttles CPU and I/O for every engine the pit starts`));
+    else if (!settings.memoryMax) console.log(ash(`   ${acid("/nice mem 2G")} adds a memory ceiling — the part nice(1) can't do`));
+    return;
+  }
+
+  if (sub === "on" || sub === "off") {
+    const saved = saveNice({ ...settings, on: sub === "on" });
+    console.log(ok(describeNice(saved)));
+    if (saved.on) console.log(ash("   applies to engines started from here on; anything already running keeps its priority"));
+    return;
+  }
+
+  if (sub === "cpu" || sub === "io") {
+    const n = Number(args[0]);
+    if (!Number.isInteger(n)) {
+      console.log(err(`usage: /nice ${sub} <number>${sub === "cpu" ? "  (-20..19, higher = yields more)" : "  (0..7, higher = yields more)"}`));
+      return;
+    }
+    const saved = saveNice({ ...settings, [sub]: n });
+    console.log(ok(describeNice(saved)));
+    return;
+  }
+
+  if (sub === "mem" || sub === "memory") {
+    const parsed = parseMemory(args[0]);
+    if (!parsed.ok) { console.log(err(parsed.error)); return; }
+    const saved = saveNice({ ...settings, memoryMax: parsed.value });
+    console.log(ok(describeNice(saved)));
+    // Worth saying plainly: this is the one setting that can silently not apply.
+    if (parsed.value && !canCapMemory()) {
+      console.log(ash("   no systemd user session on this box, so the ceiling is recorded but not enforced"));
+      console.log(ash(`   ${acid("loginctl enable-linger $USER")} gives this login one`));
+    }
+    return;
+  }
+
+  console.log(err(`/nice ${sub} isn't a thing — try on, off, cpu <n>, io <n>, or mem <size>`));
+}
+
 function aliasCommand(rest, line) {
   const json = rest.includes("--json");
   // `--json` is the listing's flag wherever it appears, so `/alias --json` is a
@@ -871,6 +942,11 @@ export async function tui() {
       finally { atPrompt(null); }
       if (line == null) break; // Ctrl-D
       expansions = 0;
+      // A one-shot `/nice <line>` lasts exactly as long as the line that asked
+      // for it. Cleared here, where a REAL line is read, and not when a command
+      // returns: one typed line can dispatch several times through alias
+      // expansion, and all of that is still the line the user said to be nice.
+      disarmOneShot();
       line = line.trim();
       if (!line) continue;
       saveHistory(); // readline just recorded this line into the shared history
@@ -936,6 +1012,31 @@ export async function tui() {
       continue;
     }
     if (cmd === "alias" || cmd === "aliases") { aliasCommand(rest, line); continue; }
+    if (cmd === "nice" || cmd === "throttle") {
+      // `/nice <line>` runs one line throttled without touching the setting --
+      // the form anyone who has used nice(1) reaches for first. The settings
+      // verbs win the name, so a command called `on` is unreachable this way;
+      // that is the right trade for `/nice on` meaning what it obviously means.
+      const sub = String(rest[0] ?? "").toLowerCase().replace(/^\//, "");
+      // A leading flag (`/nice --json`) is asking about the throttle, not
+      // naming a program: no line the pit runs starts with a dash.
+      if (!rest.length || sub.startsWith("-") || NICE_SETTING_VERBS.has(sub)) {
+        niceCommand(rest);
+        continue;
+      }
+
+      // Hand the remainder back to the top of this loop rather than dispatching
+      // it here, exactly as alias expansion does. That is what makes `/nice`
+      // work on anything the pit can already run -- a pit command, an engine, a
+      // tool, an alias, or a bare shell line -- with no roster of its own to
+      // drift out of date. The leading slash is optional because the dispatcher
+      // strips one anyway, so `/nice agents claude` and `/nice /agents claude`
+      // are the same line.
+      armOneShot();
+      pending = commandRemainder(line);
+      console.log(ash(`  ▸ throttled: ${pending}`));
+      continue;
+    }
     if (cmd === "pwd" || cmd === "where") { printPwd(); continue; }
     if (cmd === "login") {
       const device = rest.includes("--device") || rest.includes("device") || rest.includes("-d");