moshcode 0.33.0 → 0.34.0

package/README.md

@@ -125,10 +125,68 @@ moshcode attach api                      # step in; Ctrl-b d steps back out
 moshcode kill api                        # end it
 ```
 
+### A workspace: a few shells and an agent
+
+This is what most people actually want — a couple of shells to work in and an
+agent or two running beside them, none of which die when the terminal does:
+
+```sh
+cd ~/src/coinpay
+moshcode herd shell --name work          # a plain $SHELL
+moshcode herd shell --name logs          # another
+moshcode agents claude -d --name api     # and an agent
+```
+
+```sh
+$ moshcode ps
+  api    claude  blocked   ~/src/coinpay   3m
+  logs   shell   idle      ~/src/coinpay   3m
+  work   shell   idle      ~/src/coinpay   3m
+
+⚠ 1 waiting on you — moshcode attach api
+```
+
+`moshcode attach work` puts you in one; `Ctrl-b s` hops between all three;
+`Ctrl-b d` leaves the lot running. Close the laptop and they are still there.
+
+### Agents moshcode does not ship
+
+`start` only knows the engines moshcode installs. `run` takes anything —
+an agent with no install spec here, a build, a script:
+
+```sh
+moshcode herd run --name cur -- cursor-agent
+moshcode herd run --name build -- npm run watch
+```
+
+Everything after `--` is the command, flags and all. These get a roster entry
+and the same state detection as a known engine: the shared rules match what a
+terminal *draws* — a y/n prompt, a numbered menu, "esc to interrupt" — not
+anything engine-specific, so an agent moshcode has never heard of still shows up
+`blocked` when it stops to ask you something.
+
 Close the terminal, drop the SSH link, come back tomorrow — `moshcode ps` still
 answers, and `moshcode attach` puts you back inside. In the pit the same verbs
 are `/ps`, `/attach`, `/kill`, and the roster prints on the way in.
 
+### Switching between them without leaving
+
+Every session lives in one tmux server that moshcode owns, so once you are
+attached to any of them you can move around the whole herd without going back to
+the pit:
+
+| key | |
+|---|---|
+| `Ctrl-b s` | pick from a list of every session |
+| `Ctrl-b )` / `Ctrl-b (` | next / previous session |
+| `Ctrl-b L` | back to the one you were just in |
+| `Ctrl-b d` | detach — the session keeps running |
+
+That server is started without your `~/.tmux.conf`, so these are the stock
+bindings whatever your own tmux does with the prefix. Under the no-tmux fallback
+there is no switcher: detach with `Ctrl-]` and `moshcode attach <name>` the next
+one.
+
 ### Which one needs you
 
 Every session carries a state: `working`, `blocked`, `done`, `idle`, or

package/package.json

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

package/src/cli-schema.mjs

@@ -79,12 +79,25 @@ export const CORE_CLI_COMMANDS = [
     verbs: "HERD_VERBS",
     flags: [["--json", "machine-readable, on every verb", ""]],
     examples: [
-      ["moshcode herd start claude --name api", "start one and get your prompt back"],
-      ["moshcode herd prompt api \"run the tests\" --wait", "hand it work and block until it lands"],
-      ["moshcode herd read api --lines 40", "read its screen without attaching"],
+      ["# a workspace: two shells and an agent, none of which die with this terminal", ""],
+      ["moshcode herd shell --name work", "a plain $SHELL you can come back to"],
+      ["moshcode herd shell --name logs", "another one"],
+      ["moshcode agents claude -d --name api", "an agent, detached"],
+      ["moshcode ps", "all three, and which one is blocked"],
+      ["moshcode attach api", "step in · Ctrl-b s switches · Ctrl-b d leaves it running"],
+      ["", ""],
+      ["# an agent moshcode has no install spec for", ""],
+      ["moshcode herd run --name cur -- cursor-agent", "anything at all runs in the herd"],
+      ["", ""],
+      ["# driving one without attaching", ""],
+      ["moshcode herd prompt api \"run the tests\" --wait", "hand it work, block until it lands"],
+      ["moshcode herd read api --lines 40", "read its screen"],
     ],
     seeAlso: ["ps", "attach", "wait", "restore", "start"],
-    note: "sessions live in a tmux server moshcode owns, or under script(1) when there is no tmux. with neither, launches stay in the foreground and say so.",
+    note: "`start` is for the engines moshcode installs; `run` and `shell` take anything else, "
+      + "so an agent it has never heard of still gets a roster entry and blocked/idle detection. "
+      + "sessions live in a tmux server moshcode owns, or under script(1) when there is no tmux. "
+      + "with neither, launches stay in the foreground and say so.",
   },
   {
     name: "ps",
@@ -103,7 +116,10 @@ export const CORE_CLI_COMMANDS = [
     synopsis: [["moshcode attach <name>", "detach again with Ctrl-b d (or Ctrl-] without tmux)"]],
     examples: [["moshcode attach api", ""]],
     seeAlso: ["ps", "herd", "kill"],
-    note: "detaching leaves the session running. ending it is `moshcode kill`.",
+    note: "detaching leaves the session running; ending it is `moshcode kill`. "
+      + "the whole herd shares one tmux server, so from inside any session Ctrl-b s picks another, "
+      + "Ctrl-b ) and Ctrl-b ( step through them, and Ctrl-b L goes back to the last one — "
+      + "no switcher under the no-tmux fallback, where Ctrl-] detaches instead.",
   },
   {
     name: "kill",
@@ -720,6 +736,16 @@ export const HERD_VERBS = [
       ["--agent", "autonomous mode — bypasses the engine's approvals", ""],
       ["--json", "machine-readable", ""],
     ] },
+  { name: "run", description: "run ANY command in the herd — an agent moshcode does not ship, a build, a script",
+    synopsis: [["moshcode herd run [--name <slug>] -- <command…>", "everything after -- is the command"]],
+    flags: [
+      ["--name <slug>", "session name", "<command>-<dir>"],
+      ["--cwd <dir>", "where to run it", "this directory"],
+      ["--json", "machine-readable", ""],
+    ] },
+  { name: "shell", description: "a plain $SHELL in the herd",
+    synopsis: [["moshcode herd shell [--name <slug>]", ""]],
+    flags: [["--name <slug>", "session name", "shell-<dir>"], ["--cwd <dir>", "where to run it", "this directory"]] },
   { name: "attach", description: "put this terminal inside a session",
     synopsis: [["moshcode herd attach <name>", ""]] },
   { name: "kill", description: "end a session",

package/src/help.mjs

@@ -167,7 +167,11 @@ export function wrap(text, indent = 0, width = WIDTH) {
 
 /** `  name        description`, wrapped, for a two-column list. */
 function row(left, right, pad = 22) {
-  const head = `  ${left.padEnd(pad)}`;
+  // padEnd does nothing when the left column is already wider than the pad, so
+  // a long example used to butt straight against its comment:
+  // `… "run the tests" --wait# hand it work`. One guaranteed space keeps the
+  // two readable however long the command gets.
+  const head = left.length >= pad ? `  ${left} ` : `  ${left.padEnd(pad)}`;
   if (!right) return head.trimEnd();
   const wrapped = wrap(right, head.length, WIDTH);
   return `${head}${wrapped}`;

package/src/herd-cli.mjs

@@ -11,7 +11,7 @@ import path from "node:path";
 import {
   attachSession, capture, defaultName, detectSubstrate, forgetSession, HERD_SOCKET,
   herdDir, killSession, listSessions, readManifest, rememberSession, sendKeys, sendPrompt,
-  startSession, stopRuntime, substrateNote, validName, NAME_RE,
+  slugifyName, startSession, stopRuntime, substrateNote, validName, NAME_RE,
 } from "./herd.mjs";
 import { clearReport, reportState, STATES, withState } from "./herd-state.mjs";
 import { ENGINES, resolveEngine, resolveExecutable, agentLaunchArgs } from "./engines.mjs";
@@ -182,6 +182,79 @@ export function herdStart(argv, { write = console.log } = {}) {
   return EXIT.matched;
 }
 
+/**
+ * Run anything at all in the herd — a shell, or an agent moshcode does not ship
+ * an install spec for.
+ *
+ * `herd start` is deliberately limited to the engines in ENGINES, because it
+ * does engine-specific things: agent-mode flags, env stripping, resume args.
+ * That made the herd useless for the two most common things people actually
+ * want in it — a couple of shells, and whichever agent they use that moshcode
+ * has never heard of (cursor-agent, copilot, amp, a local script).
+ *
+ * So this is the escape hatch, and it is the same model herdr uses: a session
+ * holds a process, and an agent is just a process we happen to recognise.
+ * Detection still works, because the shared rules in herd-state.mjs match what
+ * a terminal draws — a y/n prompt, a numbered menu, "esc to interrupt" — rather
+ * than anything engine-specific. An unknown agent that stops to ask a question
+ * shows up `blocked` without moshcode knowing what it is.
+ */
+export function herdRun(argv, { write = console.log, shell = false } = {}) {
+  const substrate = requireSubstrate(write);
+  if (!substrate) return EXIT.usage;
+
+  const flags = { name: null, cwd: process.cwd(), json: false };
+  const command = [];
+  let afterSeparator = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (afterSeparator) { command.push(a); continue; }
+    // Everything after `--` belongs to the command, flags included — otherwise
+    // `herd run -- claude --json` would have its --json eaten by us.
+    if (a === "--") { afterSeparator = true; }
+    else if (a === "--name") flags.name = argv[++i];
+    else if (a.startsWith("--name=")) flags.name = a.slice(7);
+    else if (a === "--cwd") flags.cwd = path.resolve(argv[++i] || ".");
+    else if (a === "--json") flags.json = true;
+    else command.push(a);
+  }
+
+  if (shell && !command.length) {
+    command.push(process.env.SHELL || (process.platform === "win32" ? "cmd.exe" : "/bin/sh"));
+  }
+  if (!command.length) {
+    write(err('usage: moshcode herd run [--name <slug>] -- <command…>'));
+    write(info(`e.g. ${acid('moshcode herd run --name build -- npm run watch')}`));
+    return EXIT.usage;
+  }
+
+  const [bin, ...args] = command;
+  const label = shell ? "shell" : path.basename(bin);
+  const taken = listSessions().map((s) => s.name);
+  const name = flags.name || defaultName(slugifyName(label), flags.cwd, taken);
+  if (!validName(name)) {
+    write(err(`invalid name ${JSON.stringify(name)} — must match ${NAME_RE}`));
+    return EXIT.usage;
+  }
+
+  const started = startSession({ name, engine: label, bin, args, cwd: flags.cwd, substrate });
+  if (!started.ok) {
+    write(err(String(started.error?.message || started.error)));
+    return EXIT.usage;
+  }
+
+  if (flags.json) {
+    write(JSON.stringify({ name, engine: label, cwd: flags.cwd, substrate }, null, 2));
+    return EXIT.matched;
+  }
+  write(ok(`${bone(name)} — ${label} running in the herd. the prompt is yours.`));
+  write(info(`attach: ${acid(`moshcode attach ${name}`)} · roster: ${acid("moshcode ps")}`));
+  return EXIT.matched;
+}
+
+/** A plain $SHELL in the herd — the common case of herdRun. */
+export const herdShell = (argv, options = {}) => herdRun(argv, { ...options, shell: true });
+
 /**
  * Pull the herd flags out of an engine launch (PRD 0009 R3).
  *
@@ -646,7 +719,8 @@ export function herdStop(argv, { write = console.log } = {}) {
 
 const VERBS = {
   ps: herdPs, list: herdPs, status: herdStatus,
-  start: herdStart, attach: herdAttach, kill: herdKill, prune: herdPrune,
+  start: herdStart, run: herdRun, shell: herdShell,
+  attach: herdAttach, kill: herdKill, prune: herdPrune,
   read: herdRead, prompt: herdPrompt, "send-keys": herdSendKeys,
   wait: herdWait, restore: herdRestore, report: herdReport,
   notify: herdNotify, watch: herdWatch, stop: herdStop,

package/src/herd-state.mjs

@@ -80,7 +80,25 @@ export const COMMON_RULES = {
     /\bctrl\+c to (?:stop|cancel|interrupt)\b/i,
     /\bpress esc to cancel\b/i,
   ],
-  idle: [],
+  // A prompt sitting at the very end of the screen, waiting for a keystroke —
+  // a shell's `$`, a root `#`, zsh/starship's `❯`/`➜`, an agent's `>` composer.
+  // Anchored to the end of the *capture* rather than to any line, because a `$`
+  // in the middle of output is a dollar sign and not an invitation.
+  //
+  // Checked after blocked and working, so the cost of a false positive is only
+  // `idle` where `unknown` was already the honest answer. This is what stops a
+  // couple of shells in the herd reading `unknown` forever.
+  idle: [
+    // The glyph last: `… $`, `… #`, `… ❯`.
+    /[$%#>❯➜»]\s*$/,
+    // The glyph first, with the path after it: `➜  ~/src/api `, which is what
+    // zsh and starship actually draw. Restricted to ❯ and ➜ because those are
+    // prompt characters and almost nothing else; `>` and `#` in that position
+    // are markdown quotes and headings, which agents print all the time.
+    // Claude Code's `❯ 2. Dark mode` selector reaches the blocked rule first,
+    // so a menu still reads blocked rather than idle.
+    /(?:^|\n)[^\n]*[❯➜][^\n]*$/,
+  ],
 };
 
 /**