moshcode 0.90.0 → 0.92.0

package/prd/README.md

@@ -27,4 +27,6 @@ Start one with `moshcode prd "<idea>"` (TUI: `/prd`).
 | [0009](0009-persistent-agent-runtime.md) | Keep the herd alive — a persistent runtime, semantic agent state, and one control surface for humans and agents | Accepted |
 | [0010](0010-cloud-settings-sync.md) | Sync the pit's settings to your moshcode.sh account | Draft |
 | [0011](0011-herd-agent-protocol.md) | Teach the herd the agent protocol — hooks-first state, a task ledger, and an A2A surface for local and remote agents | Draft |
+| [0012](0012-billing-baked-into-the-agent-cli.md) | Bake billing into the agent CLI — timer, clients, teams, rates, invoices, rails | Draft |
+| [0013](0013-persistent-ssh-workspaces.md) | Add persistent SSH workspaces for humans and agents | Draft |
 <!-- PRD-INDEX:END -->

package/src/cli-schema.mjs

@@ -207,6 +207,36 @@ export const CORE_CLI_COMMANDS = [
     seeAlso: ["herd", "ps"],
     note: "this brings back the shape — sessions, directories, engines. the processes are new; work that was in flight is not still running.",
   },
+  {
+    name: "ssh",
+    group: "runtime",
+    description: "persistent SSH workspaces — one connection, many clean commands",
+    synopsis: [
+      ["moshcode ssh", "targets, and whether each one is connected"],
+      ["moshcode ssh <name>", "an interactive shell over the shared connection"],
+      ["moshcode ssh exec <name> [flags] -- <command…>", "one command over it: stdout, stderr and exit status kept apart"],
+      ["moshcode ssh <verb> [args…]", "add, open, check, close, put, get, shell, bench"],
+    ],
+    verbs: "SSH_VERBS",
+    flags: [
+      ["--json", "machine-readable, on every verb that does not take the terminal", ""],
+      ["--persist <dur>", "how long the connection outlives its last client", "10m"],
+    ],
+    examples: [
+      ["moshcode ssh add dev deploy@example.com --cwd /srv/app", "a name for a box (or an alias from ~/.ssh/config)"],
+      ["moshcode ssh open dev", "authenticate once"],
+      ["moshcode ssh exec dev -- git status --short", "…then every command reuses it"],
+      ["moshcode ssh exec dev --json -- pnpm test", "exit code, stdout and stderr as one object"],
+      ["git diff | moshcode ssh exec dev --stdin -- git apply -", "a multi-file patch in one round trip"],
+      ["moshcode ssh dev", "a real shell on the same connection"],
+      ["moshcode ssh shell dev --name app", "a remote tmux shell that survives your laptop sleeping"],
+      ["moshcode ssh close dev", "hang up (or let --persist expire)"],
+    ],
+    seeAlso: ["herd", "shell"],
+    note: "nothing secret is stored: targets.json holds a host, a port and a directory, and OpenSSH keeps using your ~/.ssh, "
+      + "agent, known_hosts and ProxyJump exactly as it does at the prompt. `exec` gives every call a fresh command channel — "
+      + "no shell state carries between calls; `shell` is for the workflows that need it.",
+  },
   {
     name: "install",
     group: "engines",
@@ -1325,6 +1355,82 @@ export const HERD_VERBS = [
 // The business layer's verbs. Flatter than the herd's on purpose: these are
 // commands somebody types between other work, and a verb that needs a paragraph
 // to explain itself is a verb in the wrong place.
+export const SSH_VERBS = [
+  { name: "list", description: "every target, and whether its connection is up",
+    synopsis: [["moshcode ssh [list] [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "add", description: "name a box: user@host, or an alias from ~/.ssh/config",
+    synopsis: [["moshcode ssh add <name> <user@host|alias> [--port N] [--cwd PATH] [--persist 10m]", ""]],
+    flags: [
+      ["--port <n>", "ssh port, when ~/.ssh/config does not say", "22"],
+      ["--cwd <path>", "where exec and the interactive shell start", "the remote login directory"],
+      ["--persist <dur>", "how long the connection outlives its last client", "10m"],
+      ["--json", "machine-readable", ""],
+    ] },
+  { name: "remove", description: "forget a target (and close its connection)",
+    synopsis: [["moshcode ssh remove <name>", ""]] },
+  { name: "show", description: "one target in full, with its socket and state",
+    synopsis: [["moshcode ssh show <name> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "open", description: "authenticate once and keep the connection",
+    synopsis: [["moshcode ssh open <name> [--persist 10m] [--batch] [--json]", ""]],
+    flags: [
+      ["--persist <dur>", "how long it outlives its last client", "10m"],
+      ["--batch", "never prompt — fail instead (the default when stdin is not a terminal)", ""],
+      ["--json", "machine-readable; alreadyOpen says whether it was up", ""],
+    ] },
+  { name: "check", description: "is the connection up? (exit 0 yes, 1 no)",
+    synopsis: [["moshcode ssh check <name> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "close", description: "hang up, with ssh's own -O exit",
+    synopsis: [["moshcode ssh close <name> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "exec", description: "one command over the connection — no PTY, no shared shell state",
+    synopsis: [["moshcode ssh exec <name> [--cwd PATH] [--env K=V…] [--stdin] [--tty] [--timeout 2m] [--sh] [--json] -- <command…>", ""]],
+    flags: [
+      ["--cwd <path>", "run it here, this once", "the target's cwd"],
+      ["--env <K=V>", "an environment variable for this command only (repeatable)", ""],
+      ["--stdin", "forward this process's stdin, raw", ""],
+      ["--tty", "allocate a terminal (sudo, editors, anything that insists)", ""],
+      ["--timeout <dur>", "kill it after this long — exit 124", ""],
+      ["--sh", "the one argument is a shell snippet, pipes and all", ""],
+      ["--batch", "never prompt for auth — fail instead", ""],
+      ["--json", "{ ok, transportOk, code, signal, stdout, stderr, durationMs }", ""],
+    ],
+    examples: [
+      ["moshcode ssh exec dev -- git status --short", ""],
+      ["moshcode ssh exec dev --json -- grep -rn TODO src", "exit 1 is grep's answer, not a transport failure"],
+      ["moshcode ssh exec dev --sh 'git log --oneline | head -5'", "a pipeline, on purpose"],
+    ] },
+  { name: "put", description: "copy a file up over the connection, atomically",
+    synopsis: [["moshcode ssh put <name> <local> <remote> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "get", description: "copy a file down over the connection",
+    synopsis: [["moshcode ssh get <name> <remote> <local> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "shell", description: "a persistent remote shell in tmux, and the verbs to drive it",
+    synopsis: [
+      ["moshcode ssh shell <name> --name <session>", "create or attach — Ctrl-b d leaves it running"],
+      ["moshcode ssh shell send <name>/<session> <text>", "type a line into it"],
+      ["moshcode ssh shell read <name>/<session> [--lines N]", "its screen, as text"],
+      ["moshcode ssh shell kill <name>/<session>", "end it"],
+      ["moshcode ssh shell list <name>", "every moshcode shell on the box"],
+    ],
+    flags: [
+      ["--name <session>", "which shell", "main"],
+      ["--lines <n>", "how much screen to read", "60"],
+      ["--json", "machine-readable", ""],
+    ],
+    examples: [
+      ["moshcode ssh shell dev --name app", ""],
+      ["moshcode ssh shell send dev/app \"pnpm dev\"", ""],
+      ["moshcode ssh shell read dev/app --lines 40", ""],
+    ] },
+  { name: "bench", description: "measure fresh connections against the shared one, on this host",
+    synopsis: [["moshcode ssh bench <name> [--n 20] [--json]", ""]],
+    flags: [["--n <runs>", "how many of each", "20"], ["--json", "machine-readable", ""]] },
+];
+
 export const TIMER_VERBS = [
   { name: "on", description: "start the clock", synopsis: [["moshcode timer on [client] [--task …] [--agents N|auto]", ""]] },
   { name: "off", description: "stop it and write the entry", synopsis: [["moshcode timer off [--note …]", ""]] },
@@ -1377,6 +1483,7 @@ export const PAYMENT_VERBS = [
 
 export const VERB_TABLES = {
   HERD_VERBS,
+  SSH_VERBS,
   TIMER_VERBS,
   CLIENT_VERBS,
   TEAM_VERBS,
@@ -1428,6 +1535,8 @@ export const PIT_COMMANDS = [
     description: "block until a session is blocked or done" },
   { name: "restore", args: "[--resume]", cli: "restore",
     description: "rebuild the herd's sessions after a reboot" },
+  { name: "ssh", args: "[name|verb] [args…]", cli: "ssh",
+    description: "persistent SSH workspaces — one connection, many clean commands" },
   { name: "tools", args: "[name] [args…]", cli: "tools",
     description: "list workflow tools, or run one" },
   { name: "trade", args: "<verb> [args…]", cli: "trade",
@@ -1487,6 +1596,20 @@ 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: "on | off | cpu <n> | io <n> | mem <size>", pitOnly: true,
+    description: "run engines at low priority so the box stays usable",
+    synopsis: [
+      ["/nice [status]", "what the throttle is set to"],
+      ["/nice on | off", "toggle it (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 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"] },
   { 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/commands.mjs

@@ -22,6 +22,27 @@ import { capture, killSession, remoteStatus, sendPrompt } from "./herd.mjs";
 import { herdStart, isRemoteMember, roster, waitForMany, waitMember } from "./herd-cli.mjs";
 import { endTask, findTask, readTasks, startTask } from "./herd-tasks.mjs";
 import { shellInvocation } from "./shell.mjs";
+import {
+  checkMaster as sshCheckMaster, closeMaster as sshCloseMaster, exec as sshRun, get as sshGetFile,
+  openMaster as sshOpenMaster, parseSessionRef as sshParseSessionRef, parseTimeout as parseSshTimeout,
+  put as sshPutFile, resolveTarget as sshResolve,
+  shellKill as sshShellKillRemote, shellRead as sshShellReadRemote, shellSend as sshShellSendRemote,
+} from "./ssh.mjs";
+
+/** The registry entry for a named ssh target, or a moshscript error naming the verb. */
+function sshTarget(name, verb) {
+  if (!name) throw new Error(`moshscript: ${verb}(name) requires a target name`);
+  const found = sshResolve(String(name));
+  if (found.error) throw new Error(`moshscript: ${verb}: ${found.error.replace(/^ssh: /, "")}`);
+  return found.entry;
+}
+
+/** `dev/app` → the target entry and the session name, or a moshscript error. */
+function sshShellRef(ref, verb) {
+  const parsed = sshParseSessionRef(ref);
+  if (parsed.error) throw new Error(`moshscript: ${verb}: ${parsed.error.replace(/^ssh: /, "")}`);
+  return { found: sshTarget(parsed.name, verb), session: parsed.session };
+}
 import { captureSpec } from "./pty.mjs";
 import { identity, loginAuto, logout as forgetCreds } from "./auth.mjs";
 import { expandAlias, getAlias, loadAliases, removeAlias, setAlias } from "./aliases.mjs";
@@ -654,6 +675,148 @@ const COMMANDS = [
     },
   },
 
+  // SSH workspaces (PRD 0013 R49–R52). Value-returning for the herd's reason:
+  // a script that runs a command on a remote box wants its stdout back, and a
+  // cliVerb's { ok, code } cannot carry it. Each returns the same object the
+  // CLI prints under --json, so a script and a shell pipeline read one shape.
+  //
+  //   sshOpen("dev");
+  //   const r = sshExec("dev", ["git", "status", "--short"], { cwd: "/srv/app" });
+  //   if (!r.ok) say(r.stderr);
+  //   sshExec("dev", ["git", "apply", "-"], { stdin: patch });
+  //   sshClose("dev");
+  {
+    name: "sshOpen",
+    summary: "authenticate to a named ssh target once and keep the connection",
+    usage: "sshOpen(name, { persist })",
+    detail: "returns { ok, connected, alreadyOpen }; a live connection is left alone",
+    run(ctx, name, opts = {}) {
+      const found = sshTarget(name, "sshOpen");
+      if (ctx.dryRun) { ctx.out(`  🔌 sshOpen(${name}) → would open a master to ${found.target}`); return { ok: true, target: found.name, connected: true, dryRun: true }; }
+      const r = sshOpenMaster(found, { persist: opts.persist, batch: opts.batch });
+      ctx.out(r.ok ? `  🔌 sshOpen(${name}) → ${r.alreadyOpen ? "already connected" : "connected"}` : `  ✗ sshOpen(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshCheck",
+    summary: "is the connection to a target up?",
+    usage: "sshCheck(name)",
+    detail: "returns { connected, stale, pid }; never connects",
+    run(ctx, name) {
+      const found = sshTarget(name, "sshCheck");
+      if (ctx.dryRun) return { target: found.name, connected: false, dryRun: true };
+      const s = sshCheckMaster(found);
+      return { target: found.name, connected: s.connected, stale: s.stale, pid: s.pid ?? null };
+    },
+  },
+  {
+    name: "sshExec",
+    summary: "run one command over the shared connection and RETURN its result",
+    usage: "sshExec(name, [cmd, ...args], { cwd, env, stdin, timeout, sh })",
+    detail: "returns { ok, transportOk, code, signal, stdout, stderr, durationMs }; opens the connection if it is down. ok is the command's verdict, transportOk is ssh's",
+    run(ctx, name, argv, opts = {}) {
+      const found = sshTarget(name, "sshExec");
+      const command = Array.isArray(argv) ? argv.map(String) : [String(argv ?? "")].filter(Boolean);
+      if (!command.length) throw new Error("moshscript: sshExec(name, [command, ...args]) needs a command");
+      if (ctx.dryRun) {
+        ctx.out(`  ▶ sshExec(${name}) → would run on ${found.target}: ${command.join(" ")}`);
+        return { ok: true, transportOk: true, target: found.name, connected: true, code: 0, signal: null, stdout: "", stderr: "", durationMs: 0, dryRun: true };
+      }
+      ctx.out(`  ▶ sshExec(${name}) → ${command.join(" ").slice(0, 60)}${command.join(" ").length > 60 ? "…" : ""}`);
+      const timeoutMs = opts.timeout === undefined ? undefined
+        : (typeof opts.timeout === "number" ? opts.timeout : parseSshTimeout(opts.timeout));
+      const r = sshRun(found, command, {
+        cwd: opts.cwd, remoteEnv: opts.env || {}, stdin: opts.stdin, sh: Boolean(opts.sh), timeoutMs, persist: opts.persist, batch: opts.batch ?? true,
+      });
+      if (!r.transportOk) ctx.out(`  ✗ sshExec(${name}) → ${r.error}`);
+      else if (!r.ok) ctx.out(`  ✗ sshExec(${name}) exited ${r.signal || r.code}`);
+      return r;
+    },
+  },
+  {
+    name: "sshClose",
+    summary: "hang up a target's connection",
+    usage: "sshClose(name)",
+    detail: "returns { ok, closed, wasOpen }",
+    run(ctx, name) {
+      const found = sshTarget(name, "sshClose");
+      if (ctx.dryRun) { ctx.out(`  🔌 sshClose(${name}) → would send -O exit`); return { ok: true, target: found.name, closed: true, dryRun: true }; }
+      const r = sshCloseMaster(found);
+      ctx.out(r.ok ? `  🔌 sshClose(${name}) → ${r.wasOpen ? "closed" : "was not connected"}` : `  ✗ sshClose(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshPut",
+    summary: "copy a local file to a target, atomically",
+    usage: "sshPut(name, local, remote)",
+    detail: "returns { ok, remote }; scp to a temp path over the shared connection, then rename",
+    run(ctx, name, local, remote) {
+      const found = sshTarget(name, "sshPut");
+      if (!local || !remote) throw new Error("moshscript: sshPut(name, local, remote) needs both paths");
+      if (ctx.dryRun) { ctx.out(`  📤 sshPut(${name}) → would copy ${local} to ${remote}`); return { ok: true, target: found.name, dryRun: true }; }
+      const r = sshPutFile(found, String(local), String(remote));
+      ctx.out(r.ok ? `  📤 sshPut(${name}) → ${r.remote}` : `  ✗ sshPut(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshGet",
+    summary: "copy a file down from a target",
+    usage: "sshGet(name, remote, local)",
+    detail: "returns { ok, local }",
+    run(ctx, name, remote, local) {
+      const found = sshTarget(name, "sshGet");
+      if (!local || !remote) throw new Error("moshscript: sshGet(name, remote, local) needs both paths");
+      if (ctx.dryRun) { ctx.out(`  📥 sshGet(${name}) → would copy ${remote} to ${local}`); return { ok: true, target: found.name, dryRun: true }; }
+      const r = sshGetFile(found, String(remote), String(local));
+      ctx.out(r.ok ? `  📥 sshGet(${name}) → ${r.local}` : `  ✗ sshGet(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshShellSend",
+    summary: "type a line into a persistent remote shell",
+    usage: 'sshShellSend("dev/app", text)',
+    detail: "returns { ok }; literal text then Enter, into the remote tmux session",
+    run(ctx, ref, ...words) {
+      const { found, session } = sshShellRef(ref, "sshShellSend");
+      const text = words.join(" ");
+      if (!text) throw new Error("moshscript: sshShellSend(ref, text) needs text");
+      if (ctx.dryRun) { ctx.out(`  💬 sshShellSend(${ref}) → would send: ${text}`); return { ok: true, dryRun: true }; }
+      const r = sshShellSendRemote(found, session, text);
+      if (!r.ok) ctx.out(`  ✗ sshShellSend(${ref}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshShellRead",
+    summary: "the screen of a persistent remote shell, as a string",
+    usage: 'sshShellRead("dev/app", { lines })',
+    detail: "returns the text (empty on failure); the same capture-pane the CLI's read prints",
+    run(ctx, ref, opts = {}) {
+      const { found, session } = sshShellRef(ref, "sshShellRead");
+      if (ctx.dryRun) { ctx.out(`  📖 sshShellRead(${ref}) → would capture the pane`); return ""; }
+      const r = sshShellReadRemote(found, session, { lines: opts.lines });
+      if (!r.ok) { ctx.out(`  ✗ sshShellRead(${ref}) → ${r.error}`); return ""; }
+      return r.screen;
+    },
+  },
+  {
+    name: "sshShellKill",
+    summary: "end a persistent remote shell",
+    usage: 'sshShellKill("dev/app")',
+    detail: "returns { ok }",
+    run(ctx, ref) {
+      const { found, session } = sshShellRef(ref, "sshShellKill");
+      if (ctx.dryRun) { ctx.out(`  ☠ sshShellKill(${ref}) → would kill the session`); return { ok: true, dryRun: true }; }
+      const r = sshShellKillRemote(found, session);
+      if (!r.ok) ctx.out(`  ✗ sshShellKill(${ref}) → ${r.error}`);
+      return r;
+    },
+  },
+
   // CLI verbs — each is `moshcode <name> ...args`. This is the whole point:
   // scripting the CLI. Add a capability by adding a line here.
   //
@@ -695,6 +858,7 @@ const COMMANDS = [
   cliVerb("elevenlabs", "drive the ElevenLabs CLI (Eleven Agents, voices, TTS, dubbing)"),
   cliVerb("trade", "look up tickers, inspect markets, and preview/place Alpaca orders"),
   cliVerb("pwd", "print the current repo/location"),
+  cliVerb("ssh", "persistent SSH workspaces (moshcode ssh <verb>) — see sshExec/sshOpen for values"),
 
   // Research and feeds. The *Read() verbs above return the data; these are the
   // rendered CLI, for when a script wants the table on the operator's screen.

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,199 @@
+// 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");
+}
+
+/**
+ * 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 = loadNice(),
+  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 };
+}