@brutalsystems/muster 0.7.16 → 0.7.18

package/README.md

@@ -882,6 +882,10 @@ any non-empty plugin list, so the child also loads whatever plugins the target
 repository ships. It globs both spellings — `.opencode/plugin` and
 `.opencode/plugins` — so auditing only one of them misses half of what a
 repository can load. Select plugins only for repositories trusted with that.
+`--plugin NAME` is repeatable and replaces whatever plugins the configuration
+selects by default, rather than adding to them; `--no-plugin` selects none and
+is how a launch gets the `--pure` treatment above when the configuration would
+otherwise have chosen some. Both apply to OpenCode only.
 Claude connection specifications are stored with owner-only permissions under
 `~/.muster/mcp`, removed on stop, task completion, or when `list` observes an ended
 session. MCP server access is separate from filesystem sandbox permissions: a
@@ -892,8 +896,12 @@ selected external tool may have its own write or network capabilities.
 Installed deliberately, in the one session that should hold spawn authority —
 never at user scope.
 
-Muster exposes `run`, `list`, `stop`, and `output` over stdio. No arguments or
-`mcp` starts the server. Diagnostics go to stderr, never protocol stdout.
+Muster exposes `run`, `list`, `stop`, and `output` over stdio. `mcp` starts the
+server, and so does no arguments when stdin is not a terminal — which is what an
+MCP client provides. Typing `muster` at a terminal prints the usage text and a
+short status instead, because a server waiting for JSON-RPC on stdin is
+indistinguishable from a hang. `muster mcp` starts the server either way, so it
+can still be driven by hand to debug it. Diagnostics go to stderr, never protocol stdout.
 Schemas match the CLI (`args` is the array of optional runtime arguments).
 
 For a single Codex session, use per-invocation configuration:

package/dist/format.js

@@ -100,3 +100,29 @@ export function formatHuman(value, color = false) {
             : "No Muster runs.\n";
     return recordHuman(value, color) + "\n";
 }
+/**
+ * What a human sees when they type `muster` with no arguments at a terminal.
+ *
+ * With no arguments Muster starts the MCP server, which from a terminal looks
+ * exactly like a hang — the process is waiting for JSON-RPC on stdin and has
+ * nothing to say. The server path is reached by a pipe, never a TTY, so a
+ * terminal can be answered without changing what any MCP client gets.
+ *
+ * The session count is what the registry recorded, not what is running: it is
+ * read without the refresh `list` performs, because that refresh also reaps a
+ * terminal entry's identity copy and reaches an OpenCode session over HTTP.
+ * Neither belongs in the output of typing a bare command, so the wording says
+ * "recorded" and points at `list` for the authoritative answer.
+ */
+export function statusText(identities, sessions) {
+    const lines = [];
+    if (!identities.length)
+        lines.push("No identities yet — add one with:", "    muster setup-identity --identity NAME --agent <codex|claude|opencode> --interactive");
+    else
+        lines.push(`${identities.length} ${identities.length === 1 ? "identity" : "identities"} — ` +
+            identities.map((i) => `${i.name} ${i.auth.state}`).join(", "));
+    lines.push(sessions === 0
+        ? "No recorded sessions."
+        : `${sessions} recorded session${sessions === 1 ? "" : "s"} (muster list refreshes)`, "", "Starting the MCP server? Use `muster mcp`.");
+    return lines.join("\n") + "\n";
+}

package/dist/help.js

@@ -0,0 +1,195 @@
+const WIDTH = 80;
+const INDENT = "  ";
+const GUTTER = 2;
+function wrap(text, width) {
+    const words = text.split(/\s+/).filter(Boolean);
+    const lines = [];
+    let line = "";
+    for (const word of words) {
+        if (line && line.length + 1 + word.length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        lines.push(line);
+    return lines.length ? lines : [""];
+}
+/** Two columns, with a label too wide for its column taking a line of its own
+ *  rather than pushing every description of that row out past the margin. */
+function table(rows) {
+    const width = Math.min(26, Math.max(...rows.map(([label]) => label.length), 0));
+    const lead = INDENT.length + width + GUTTER;
+    return rows.flatMap(([label, description]) => {
+        const body = wrap(description, WIDTH - lead);
+        if (label.length > width)
+            return [INDENT + label, ...body.map((l) => " ".repeat(lead) + l)];
+        return body.map((line, i) => i === 0
+            ? INDENT + label.padEnd(width) + " ".repeat(GUTTER) + line
+            : " ".repeat(lead) + line);
+    });
+}
+export const COMMANDS = [
+    {
+        name: "run",
+        summary: "launch an agent session or task",
+        synopsis: "muster run <codex|claude|opencode> --prompt TEXT [options]",
+        options: [
+            ["--prompt TEXT", "the instruction to launch with"],
+            ["--cwd DIR", "the directory to launch in"],
+            ["--project NAME", "a directory named under [projects]; not with --cwd"],
+            ["--kind KIND", "session (default) or task"],
+            ["--host ID", "tmux, pty, or auto (default: tmux, then pty)"],
+            ["--identity NAME", "run as a configured identity"],
+            ["--open", "display the tmux session in a terminal (macOS)"],
+            ["--terminal APP", "auto, terminal, iterm2, or ghostty; needs --open"],
+            [
+                "--level LEVEL",
+                "read, work, or open: a legal permissions and sandbox pair",
+            ],
+            ["--permissions MODE", "auto, deny, or bypass"],
+            ["--sandbox MODE", "read-only, workspace-write, or full-access"],
+            ["--mcp NAME", "repeatable; replaces configured defaults"],
+            ["--no-mcp", "launch with no MCP servers"],
+            ["--plugin NAME", "repeatable; replaces configured defaults (OpenCode)"],
+            ["--no-plugin", "launch with no plugins"],
+            ["--model PROVIDER/MODEL", "select the OpenCode model"],
+            [
+                "--request-key KEY",
+                "name the request; sending it again returns the same launch",
+            ],
+            ["--format FORMAT", "json (default) or human"],
+            ["-- RUNTIME_OPTIONS", "everything after -- is passed to the runtime"],
+        ],
+        notes: [
+            "Naming both --level and --permissions or --sandbox is an error rather than a precedence rule.",
+            "A pty launch keeps this process running and Ctrl-C stops it; a tmux launch survives this process exiting.",
+        ],
+        examples: [
+            "muster run claude --prompt 'Review this project' --cwd .",
+            "muster run codex --identity work --level work --prompt 'Ship it'",
+        ],
+    },
+    {
+        name: "list",
+        summary: "show sessions and tasks",
+        synopsis: "muster list [--kind session|task] [--format json|human]",
+        options: [
+            ["--kind KIND", "show only session or only task entries"],
+            ["--format FORMAT", "json (default) or human"],
+        ],
+        notes: [
+            "Refreshes live metadata, and removes the per-launch identity copy of any entry that has ended.",
+        ],
+        examples: ["muster list --format human"],
+    },
+    {
+        name: "stop",
+        summary: "stop a session or task",
+        synopsis: "muster stop <id> [--format json|human]",
+        options: [["--format FORMAT", "json (default) or human"]],
+        examples: ["muster stop 6fae755b-8f5d-4425-8ed7-69e84bfac8c5"],
+    },
+    {
+        name: "output",
+        summary: "print a task's captured output",
+        synopsis: "muster output <id>",
+        options: [],
+        notes: ["Prints raw text; --format does not apply."],
+        examples: ["muster output 6fae755b-8f5d-4425-8ed7-69e84bfac8c5"],
+    },
+    {
+        name: "identities",
+        summary: "show configured identities",
+        synopsis: "muster identities [--format json|human]",
+        options: [["--format FORMAT", "json (default) or human"]],
+        examples: ["muster identities --format human"],
+    },
+    {
+        name: "setup-identity",
+        summary: "create or configure an identity",
+        synopsis: "muster setup-identity --identity NAME --agent AGENT [options]",
+        options: [
+            ["--identity NAME", "the identity to create or configure"],
+            ["--agent AGENT", "codex, claude, or opencode"],
+            ["--interactive", "run the login here and store what it returns"],
+            [
+                "--token-env VAR",
+                "read the token from that variable instead (Claude only)",
+            ],
+        ],
+        notes: [
+            "--interactive and --token-env are the two credential routes and cannot be combined; an identity holds one at a time.",
+            "Without --interactive the command prints the login for you to run yourself.",
+        ],
+        examples: [
+            "muster setup-identity --identity work --agent claude --interactive",
+            "muster setup-identity --identity ci --agent claude --token-env CLAUDE_TOKEN",
+        ],
+    },
+    {
+        name: "doctor",
+        summary: "check path-configured plugins for staleness",
+        synopsis: "muster doctor [--format json|human]",
+        options: [["--format FORMAT", "json (default) or human"]],
+        notes: [
+            "Compares each copy's mtime against the package it came from, and exits 1 when any is stale. Plugins named by npm are not checked.",
+        ],
+        examples: ["muster doctor --format human"],
+    },
+    {
+        name: "mcp",
+        summary: "start the MCP server on stdio",
+        synopsis: "muster mcp",
+        options: [],
+        notes: [
+            "Exposes run, list, stop and output. No arguments does the same when stdin is not a terminal, which is what an MCP client provides.",
+        ],
+        examples: ["muster mcp"],
+    },
+];
+export function topLevelHelp() {
+    const lines = [
+        "Usage: muster <command> [options]",
+        "",
+        "Commands:",
+        ...table(COMMANDS.map((c) => [c.name, c.summary])),
+        "",
+        "Options:",
+        ...table([
+            ["--format FORMAT", "json (default) or human, where a command takes it"],
+            ["--version", "print the version"],
+            ["--help", "print this, or a command's own help"],
+        ]),
+        "",
+        "See `muster <command> --help` for a command's options.",
+        "",
+        // Kept here rather than moved to the README: this is a safety statement
+        // about who gets launch authority, not reference detail, and it is only
+        // load-bearing where someone is about to install.
+        ...wrap("MCP: install deliberately in the one authorized session, never at user scope.", WIDTH),
+    ];
+    return lines.join("\n") + "\n";
+}
+export function commandHelp(name) {
+    const command = COMMANDS.find((c) => c.name === name);
+    if (!command)
+        return undefined;
+    const lines = [
+        `Usage: ${command.synopsis}`,
+        "",
+        ...wrap(command.summary, WIDTH),
+    ];
+    if (command.options.length)
+        lines.push("", "Options:", ...table(command.options));
+    for (const note of command.notes ?? [])
+        lines.push("", ...wrap(note, WIDTH));
+    if (command.examples.length) {
+        lines.push("", "Examples:");
+        for (const example of command.examples)
+            lines.push(INDENT + example);
+    }
+    return lines.join("\n") + "\n";
+}

package/dist/muster.js

@@ -7,67 +7,19 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { z } from "zod";
 import { Muster } from "./run.js";
 import { delay } from "./identity/processes.js";
-import { formatHuman, humanColorEnabled } from "./format.js";
+import { formatHuman, humanColorEnabled, statusText } from "./format.js";
 import { checkPlugins, npmRegistry } from "./doctor.js";
 import { loadConfig, musterHome } from "./config.js";
 import { describeIdentities, interactiveSetup, setupIdentity, } from "./identity-cli.js";
 import { IdentityError } from "./identity-store.js";
 import { MCP_TOOLS } from "./mcp-tools.js";
+import { commandHelp, topLevelHelp } from "./help.js";
+import { promptForMissing, terminalReader } from "./prompt.js";
 const listSchema = z
     .object({ kind: z.enum(["session", "task"]).optional() })
     .strict();
 const idSchema = z.object({ id: z.string().min(1) }).strict();
 const { version } = createRequire(import.meta.url)("../package.json");
-const help = `Usage:
-  muster run <codex|claude|opencode> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [--terminal APP] [--request-key KEY] [-- RUNTIME_OPTIONS]
-  muster list [--kind session|task] [--format json|human]
-  muster stop <id> [--format json|human]
-  muster output <id>
-  muster doctor [--format json|human]
-  muster setup-identity --identity NAME --agent <codex|claude|opencode> [--token-env VAR] [--interactive]
-  muster identities [--format json|human]
-  muster mcp
-  muster --version
-
-run also accepts --format json|human, --permissions auto|deny|bypass,
-and --sandbox read-only|workspace-write|full-access before -- RUNTIME_OPTIONS.
---level read|work|open names a legal permissions and sandbox pair: read is
-deny + read-only, work is auto + workspace-write, open is bypass + full-access
-and still requires allow_dangerous_flags. Naming both a level and either flag
-is an error rather than a precedence rule.
---open displays a tmux session on macOS. --terminal accepts auto (Terminal.app),
-terminal, iterm2, or ghostty, and requires --open.
---mcp NAME is repeatable and replaces configured session defaults; --no-mcp
-clears them. Tasks use no MCP defaults; select servers explicitly.
---plugin NAME is repeatable and replaces configured session defaults;
---no-plugin clears them. OpenCode only: selected plugins load in the child,
-which also admits any plugin the target repository ships.
---model PROVIDER/MODEL selects the OpenCode model, overriding the configured
-[opencode] model. Providers defined under [opencode.provider] are supplied to
-the child, so launches do not depend on the user's own OpenCode config.
---project NAME launches in a directory named under [projects] in config.toml,
-instead of --cwd; naming both is an error. When allowed_roots or [projects] are
-configured, a launch outside all of them is refused.
---request-key KEY names the launch request itself. Sending the same key again
-returns the launch it already produced rather than starting a second one, and
-sending it with different parameters is refused rather than answered.
-setup-identity takes either --interactive (Muster runs the Claude login and
-stores the token in the identity) or --token-env VAR (the identity reads its
-token from that variable instead, keeping nothing at rest). They are the two
-mutually exclusive credential routes; passing both is an error rather than a
-precedence rule.
-run, list and stop default to JSON. output prints raw task text.
-
-doctor checks path-configured plugins against the packages they came from: a
-copied file goes stale silently while the package moves on. It reads the copy's
-mtime, so a re-copied old file reads as current. Exits 1 when any plugin is
-stale. Plugins named by npm are not checked — OpenCode caches those instead,
-and the README covers clearing that cache.
-
-pty launches print their record and keep this process running. Ctrl-C stops the
-owned pty session. tmux launches survive this process exiting.
-MCP: install deliberately in the one authorized session, never at user scope.
-`;
 const text = (value) => ({
     content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
 });
@@ -95,21 +47,53 @@ function identitiesHuman(view, color) {
 async function main() {
     const argv = process.argv.slice(2);
     if (argv[0] === "--help" || argv[0] === "-h") {
-        process.stdout.write(help);
+        process.stdout.write(topLevelHelp());
+        return;
+    }
+    // Recognised before parsing, not during it: the parser is strict and has no
+    // `help` option, so `muster setup-identity --help` used to be answered with
+    // "Unknown option '--help'". Only in second position, so a `--help` that is
+    // some flag's value still reaches the command it was written for.
+    if ((argv[1] === "--help" || argv[1] === "-h") && commandHelp(argv[0])) {
+        process.stdout.write(commandHelp(argv[0]));
         return;
     }
     if (argv[0] === "--version" || argv[0] === "-v") {
         process.stdout.write(`${version}\n`);
         return;
     }
-    const mcp = argv.length === 0 || argv[0] === "mcp";
-    if (mcp && argv.length > 1)
+    // No arguments starts the MCP server: a documented entry point, and how a
+    // client configured with `command: "muster"` and no args reaches it. From a
+    // terminal that is indistinguishable from a hang — the process is waiting for
+    // JSON-RPC on stdin and has nothing to say. A client always arrives down a
+    // pipe and never a TTY, so a person can be answered without changing what any
+    // client gets. `muster mcp` stays unconditional, so the server can still be
+    // driven by hand in a terminal to debug it.
+    const bareAtTerminal = argv.length === 0 && Boolean(process.stdin.isTTY);
+    const mcp = !bareAtTerminal && (argv.length === 0 || argv[0] === "mcp");
+    if (argv[0] === "mcp" && argv.length > 1)
         throw new Error("mcp takes no arguments");
     const muster = await Muster.create();
     let shutdown;
     const close = () => (shutdown ??= (async () => {
         await muster.close();
     })());
+    if (bareAtTerminal) {
+        try {
+            const cfg = await loadConfig();
+            const view = await describeIdentities(musterHome(), process.env, Object.fromEntries(Object.entries(cfg.requester_profiles).map(([n, p]) => [
+                n,
+                p.identities,
+            ])));
+            process.stdout.write(topLevelHelp() +
+                "\n" +
+                statusText(view.identities, (await muster.summary()).sessions));
+        }
+        finally {
+            await close();
+        }
+        return;
+    }
     for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"])
         process.once(signal, () => {
             void close().then(() => process.exit(0), (e) => {
@@ -239,9 +223,23 @@ async function main() {
         else if (command === "setup-identity") {
             if (positionals.length)
                 throw new Error("setup-identity takes no positional arguments");
-            const { identity, agent, "token-env": tokenEnv, } = values;
-            if (!identity || !agent)
-                throw new Error("setup-identity requires --identity and --agent");
+            const { "token-env": tokenEnv } = values;
+            let { identity, agent } = values;
+            if (!identity || !agent) {
+                // Asking is what `--interactive` already implied. Without it the
+                // command is the unattended route and still requires both flags, and
+                // with it but no terminal there is nobody to ask — which is a different
+                // problem from having forgotten a flag, so it says so.
+                if (!values.interactive)
+                    throw new Error("setup-identity requires --identity and --agent");
+                if (!process.stdin.isTTY)
+                    throw new Error("--interactive needs a terminal to ask for --identity and --agent; pass both as flags for an unattended run");
+                ({ identity, agent } = await promptForMissing({
+                    identity,
+                    agent,
+                    ask: terminalReader(),
+                }));
+            }
             if (values.interactive) {
                 // Refused, not ranked. These are the two mutually exclusive credential
                 // routes, and the interactive branch is taken before tokenEnv is read:
@@ -300,7 +298,7 @@ async function main() {
                 process.stdout.write(await muster.output(id));
         }
         else
-            throw new Error(help);
+            throw new Error(topLevelHelp());
     }
     finally {
         await close();

package/dist/prompt.js

@@ -0,0 +1,50 @@
+import { createInterface } from "node:readline/promises";
+export const AGENTS = ["codex", "claude", "opencode"];
+/** The store's own rule (`identity-store.ts`), repeated here so a name this
+ *  accepts cannot be rejected a moment later by the thing it is typed for. */
+const NAME = /^[a-zA-Z0-9_-]+$/;
+const ATTEMPTS = 3;
+async function until(ask, question, parse, complaint, write) {
+    for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+        const value = parse((await ask(question)).trim());
+        if (value !== undefined)
+            return value;
+        if (attempt < ATTEMPTS)
+            write(`${complaint}\n`);
+    }
+    throw new Error(`${complaint} — no valid answer after three attempts.`);
+}
+/**
+ * Fills in what `setup-identity --interactive` was not given.
+ *
+ * `--interactive` used to mean only that the login runs here; `--identity` and
+ * `--agent` were still required, so the way a person naturally types the
+ * command was answered with "setup-identity requires --identity and --agent".
+ * Asking is what "interactive" already implied. Anything passed as a flag is
+ * kept as-is and not asked about, so a scripted invocation is unchanged.
+ */
+export async function promptForMissing(opts) {
+    const write = opts.write ?? ((text) => process.stderr.write(text));
+    const identity = opts.identity ??
+        (await until(opts.ask, "Identity name: ", (answer) => (NAME.test(answer) ? answer : undefined), "An identity name is letters, digits, dash or underscore", write));
+    const agent = opts.agent ??
+        (await until(opts.ask, `Agent [${AGENTS.join("/")}]: `, (answer) => AGENTS.includes(answer)
+            ? answer
+            : undefined, `An agent is one of ${AGENTS.join(", ")}`, write));
+    return { identity, agent };
+}
+/** The real terminal. Kept apart from the logic above so the logic needs none. */
+export function terminalReader() {
+    return async (question) => {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stderr,
+        });
+        try {
+            return await rl.question(question);
+        }
+        finally {
+            rl.close();
+        }
+    };
+}

package/dist/run.js

@@ -823,6 +823,21 @@ export class Muster {
      * with the supported entry point (#44), which is also what would need to
      * choose between hiding other requesters' entries and redacting them.
      */
+    /**
+     * Counts for the status line a bare `muster` prints at a terminal.
+     *
+     * Deliberately not `list`. That refreshes every entry, and a refresh removes
+     * a terminal entry's identity copy and MCP config and reaches an OpenCode
+     * session over HTTP — none of which belongs in the output of typing a bare
+     * command. This reads the registry and changes nothing, so what it reports is
+     * what was recorded rather than what is running, and the caller says so.
+     */
+    async summary() {
+        const entries = await this.registry.all();
+        return {
+            sessions: entries.filter((e) => e.kind === "session" && ["starting", "running"].includes(e.status)).length,
+        };
+    }
     async list(kind) {
         const entries = await this.registry.all();
         const result = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.7.16",
+  "version": "0.7.18",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {