@brutalsystems/muster 0.7.17 → 0.7.19

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

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/identity-cli.js

@@ -1,7 +1,7 @@
 import { identityAuthState } from "./identity-auth.js";
 import { IdentityError, identityDirExists, identityMetaSchema, identityNameSchema, identityPath, listIdentities, readIdentity, writeIdentity, } from "./identity-store.js";
 import { removeStoredToken, writeStoredToken, } from "./identity-token.js";
-import { captureClaudeToken, redactToken, } from "./identity-login.js";
+import { captureClaudeToken, redactToken, resolveOnPath, } from "./identity-login.js";
 /**
  * The one-time login for each agent. Muster never performs it: each is an
  * interactive OAuth flow, and a command that appeared to do it for you would be
@@ -25,7 +25,12 @@ export async function setupIdentity(opts) {
     // a codex or opencode identity, where the credential is an auth file the
     // agent's own login writes into the template, it has exactly one effect: a new
     // way to fail. Refused where the operator types it.
-    if (opts.tokenEnv && opts.agent !== "claude")
+    // Checked against undefined, not truthiness: `--token-env ""` is falsy, so a
+    // truthiness test let an empty name past every guard and then dropped it,
+    // leaving the identity on neither credential route without saying so (#69).
+    if (opts.tokenEnv !== undefined && opts.tokenEnv.trim() === "")
+        throw new IdentityError(opts.name, "--token-env takes the name of an environment variable holding the token, not the token and not an empty value");
+    if (opts.tokenEnv !== undefined && opts.agent !== "claude")
         throw new IdentityError(name, `--token-env applies only to a claude identity; ${opts.agent} authenticates from an auth file in the template, and a token variable here would only add a way for the launch to fail`);
     // Distinguish "no such identity" from "an identity that is there but unusable".
     // Overwriting the second would silently repurpose a directory that still holds
@@ -150,24 +155,30 @@ export async function interactiveSetup(opts) {
             stored: false,
             note: `Run this once, then check with \`muster identities\`:\n\n    ${created.login}\n`,
         };
+    // Asked before anything is spawned, so "could not be started" is a fact about
+    // the filesystem rather than an inference from what the child printed. That
+    // inference was platform-dependent: a missing executable emits nothing under
+    // macOS and an error into the pty under Linux (#69).
+    if (!(await resolveOnPath("claude", opts.env ?? process.env)))
+        throw new IdentityError(opts.name, "`claude` is not on PATH, so the login could not be started; nothing was changed");
     write(`Running: claude setup-token\n${"─".repeat(50)}\n`);
     const result = await captureClaudeToken({
         dir: created.path,
         env: opts.env ?? process.env,
         onData: write,
-        ...(opts.stdin ? { stdin: opts.stdin } : {}),
+        stdin: opts.stdin,
     });
     write(`${"─".repeat(50)}\n`);
     // Checked BEFORE the token branch, deliberately: a login that failed writes
     // no credential even if something token-shaped went past on the way down.
     //
-    // This is also the case where the child never started at all. node-pty does
-    // not throw for a missing executable — it exits 1 having emitted zero bytes —
-    // so an operator with no `claude` on PATH used to be told Muster could not
-    // parse output that never existed, with no identity name and no hint that
-    // nothing had run. The child's own output is the error here, whatever it was.
+    // Two different events land here and they need different explanations. node-pty
+    // does not throw for a missing executable — it exits 1 having emitted zero
+    // bytes — which is exactly the exit shape of a login that failed on its own or
+    // that the operator interrupted. The exit code cannot tell them apart; whether
+    // anything was ever printed can (#69).
     if (result.exitCode !== 0)
-        throw new IdentityError(opts.name, `\`claude setup-token\` failed (exit ${result.exitCode}) and no credential was stored; its own output above is the error. If nothing was printed above it could not be started at all — check that \`claude\` is on PATH.`);
+        throw new IdentityError(opts.name, `\`claude setup-token\` ended without storing a credential (exit ${result.exitCode}); its own output above is the error. If you interrupted it, nothing was stored and nothing was changed.`);
     if (result.token) {
         const { clearedRoute } = await storeIdentityToken({
             home: opts.home,

package/dist/identity-login.js

@@ -1,3 +1,28 @@
+import { access, constants } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+/**
+ * Where `name` is on PATH, or undefined. The same lookup `tmuxExecutable` does,
+ * and the reason the login asks it: whether a child "could not be started" has
+ * to be decided before spawning, not inferred from what it printed. node-pty
+ * does not throw for a missing executable — it exits 1, emitting nothing on
+ * macOS and an error into the pty on Linux, so output was never the discriminator
+ * it appeared to be (#69).
+ */
+export async function resolveOnPath(name, env) {
+    for (const dir of (env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, name);
+        try {
+            await access(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Not here, or not executable. Keep looking.
+        }
+    }
+    return undefined;
+}
 /**
  * A Claude long-lived OAuth token, as `claude setup-token` prints it. The length
  * floor is what separates a real token from the literal word in help text.
@@ -257,8 +282,8 @@ function attachInput(pty, input, signals) {
  * status quo.
  */
 export async function captureClaudeToken(opts) {
-    const module = await import("node-pty");
-    const pty = module.spawn("claude", ["setup-token"], {
+    const spawn = opts.spawn ?? (await import("node-pty")).spawn;
+    const pty = spawn("claude", ["setup-token"], {
         cwd: opts.dir,
         env: { ...opts.env, CLAUDE_CONFIG_DIR: opts.dir },
         name: "xterm-256color",
@@ -278,7 +303,7 @@ export async function captureClaudeToken(opts) {
     // up before rethrowing, and enters raw mode last of all.
     let detachInput = () => { };
     try {
-        detachInput = attachInput(pty, opts.stdin ?? process.stdin, opts.signals ?? process);
+        detachInput = attachInput(pty, opts.stdin, opts.signals ?? process);
         const filter = createTokenFilter(opts.onData);
         const dataSub = pty.onData((chunk) => filter.push(chunk));
         const exitCode = await new Promise((resolve) => {

package/dist/muster.js

@@ -13,61 +13,13 @@ 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,7 +47,15 @@ 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") {
@@ -125,7 +85,7 @@ async function main() {
                 n,
                 p.identities,
             ])));
-            process.stdout.write(help +
+            process.stdout.write(topLevelHelp() +
                 "\n" +
                 statusText(view.identities, (await muster.summary()).sessions));
         }
@@ -263,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:
@@ -273,13 +247,21 @@ async function main() {
                 // year-long token to disk on the machine the operator explicitly asked
                 // to keep no credential at rest, while never recording the variable
                 // they named.
-                if (tokenEnv)
+                if (tokenEnv !== undefined && agent !== "claude")
+                    // Not the mutual-exclusion message: for codex and opencode
+                    // `--interactive` captures nothing and `--token-env` does not apply
+                    // at all, so describing them as two routes to choose between would
+                    // be describing Claude's behaviour at a different agent (#69).
+                    throw new IdentityError(identity, `--token-env applies only to a claude identity; ${agent} authenticates from an auth file in the template, and a token variable here would only add a way for the launch to fail`);
+                if (tokenEnv !== undefined)
                     throw new IdentityError(identity, "--interactive and --token-env are the two mutually exclusive credential routes: --interactive runs the login and stores a token in the identity, --token-env records the name of a variable to read one from instead. Pass one, not both.");
                 const result = await interactiveSetup({
                     home: musterHome(),
                     name: identity,
                     agent: agent,
                     isTTY: Boolean(process.stdin.isTTY),
+                    // The one place the operator's real keyboard is named.
+                    stdin: process.stdin,
                 });
                 process.stdout.write(`\n${result.note}\n`);
                 return;
@@ -291,7 +273,7 @@ async function main() {
                 home: musterHome(),
                 name: identity,
                 agent: agent,
-                ...(tokenEnv ? { tokenEnv } : {}),
+                ...(tokenEnv !== undefined ? { tokenEnv } : {}),
             })) + "\n");
         }
         else if (command === "identities") {
@@ -324,7 +306,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.7.17",
+  "version": "0.7.19",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {
@@ -12,7 +12,8 @@
   "scripts": {
     "build": "tsc && node scripts/prepare-bin.mjs",
     "test": "vitest run",
-    "check": "npm test && node scripts/check-tarball.mjs",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "check": "npm run typecheck && npm test && node scripts/check-tarball.mjs",
     "test:contract": "MUSTER_CONTRACT=1 vitest run test/contract.test.ts",
     "postinstall": "node scripts/prepare-pty.mjs",
     "pretest": "npm run build",