@brutalsystems/muster 3.0.2 → 3.1.1

package/README.md

@@ -70,6 +70,10 @@ muster run claude --prompt 'Review this project' --cwd .
 muster run codex --kind task --prompt 'Summarise the failing tests' --read-only
 muster output <id>
 
+# Knowing it has finished: block on it, or have muster run a command then.
+muster wait <id> --timeout 30m
+muster run codex --kind task --prompt 'Review' --on-exit 'notify "$MUSTER_STATE"'
+
 # What is running, and stopping it.
 muster list --format human
 muster stop <id>

package/dist/cli-options.js

@@ -0,0 +1,60 @@
+/**
+ * Every flag any command takes, in one table so `asksForHelp` can tell which
+ * flags consume the next word: `--prompt --help` is a prompt, not a request
+ * for help.
+ */
+export const CLI_OPTIONS = {
+    prompt: { type: "string" },
+    cwd: { type: "string" },
+    kind: { type: "string" },
+    host: { type: "string" },
+    open: { type: "boolean" },
+    terminal: { type: "string" },
+    format: { type: "string" },
+    permissions: { type: "string" },
+    sandbox: { type: "string" },
+    level: { type: "string" },
+    "read-only": { type: "boolean" },
+    "write-here": { type: "boolean" },
+    unrestricted: { type: "boolean" },
+    mcp: { type: "string", multiple: true },
+    options: { type: "string", multiple: true },
+    "no-mcp": { type: "boolean" },
+    plugin: { type: "string", multiple: true },
+    model: { type: "string" },
+    "idle-timeout": { type: "string" },
+    ttl: { type: "string" },
+    title: { type: "string" },
+    socket: { type: "string" },
+    home: { type: "string" },
+    "stop-now": { type: "boolean" },
+    "no-plugin": { type: "boolean" },
+    "request-key": { type: "string" },
+    project: { type: "string" },
+    identity: { type: "string" },
+    agent: { type: "string" },
+    "token-env": { type: "string" },
+    interactive: { type: "boolean" },
+    "on-exit": { type: "string" },
+    timeout: { type: "string" },
+};
+/**
+ * Whether a command's arguments ask for its help: `--help` or `-h` before any
+ * `--`, and not the value of a flag that takes one.
+ */
+export function asksForHelp(args) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--")
+            return false;
+        if (arg === "--help" || arg === "-h")
+            return true;
+        const name = arg.startsWith("--") ? arg.slice(2) : undefined;
+        const option = name && !name.includes("=")
+            ? CLI_OPTIONS[name]
+            : undefined;
+        if (option?.type === "string")
+            i++;
+    }
+    return false;
+}

package/dist/duration.js

@@ -19,3 +19,20 @@ export function parseDuration(value, label) {
         throw new Error(`${label} must be a duration like 90s, 30m, 4h, or off (got ${JSON.stringify(value)})`);
     return seconds;
 }
+/**
+ * `wait --timeout`: seconds as a bare number, which is what `timeout(1)` and
+ * shell callers write, or a duration. A lifecycle limit refuses the bare
+ * number because a wrong unit reaps a session; here the unit is the obvious
+ * one. `off` is refused: no timeout is spelled by leaving the flag out.
+ */
+export function waitSeconds(value) {
+    const raw = value.trim();
+    const seconds = /^\d+$/.test(raw)
+        ? Number(raw)
+        : /^\d+[smh]$/i.test(raw)
+            ? parseDuration(raw, "--timeout")
+            : 0;
+    if (seconds <= 0)
+        throw new Error(`--timeout must be seconds or a duration like 90s, 30m, 4h (got ${JSON.stringify(value)})`);
+    return seconds;
+}

package/dist/format.js

@@ -38,6 +38,9 @@ function recordHuman(record, color) {
     const id = record.id ?? record.thread_id ?? record.session_id;
     if (record.stopped === true)
         return `${paint("Stopped", 90)} ${clean(id)}.`;
+    // `stop` on a launch that had already ended changes nothing and says so.
+    if (record.stopped === false)
+        return `Not stopped: ${clean(id)} had already ${clean(record.state)}.`;
     // `muster title` answers with the id and the title alone, no kind.
     if (record.kind === undefined && record.title !== undefined)
         return `Titled ${clean(id)}: ${clean(record.title)}.`;

package/dist/help.js

@@ -97,6 +97,10 @@ export const COMMANDS = [
                 "--request-key KEY",
                 "name the request; sending it again returns the same launch",
             ],
+            [
+                "--on-exit COMMAND",
+                "run COMMAND with /bin/sh once the agent exits, however it ends; muster runs it, outside any sandbox, with MUSTER_ID, MUSTER_RUNTIME, MUSTER_KIND, MUSTER_STATE, MUSTER_EXIT_CODE, MUSTER_SIGNAL, MUSTER_OUTPUT, MUSTER_ERROR and MUSTER_RECORD set",
+            ],
             ["--format FORMAT", "json (default) or human"],
             ["-- RUNTIME_OPTIONS", "everything after -- is passed to the runtime"],
         ],
@@ -105,11 +109,32 @@ export const COMMANDS = [
             "A sealed launch does not read your profile's or the project's settings, so it also loads no rules or CLAUDE.md.",
             "Use one of the three flags, --level, or --permissions/--sandbox; naming two 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.",
+            "--on-exit: MUSTER_EXIT_CODE and MUSTER_SIGNAL are empty for a session, whose terminal keeps no exit status, and MUSTER_OUTPUT (the captured output's path) is empty for one too. The command's own output goes to ~/.muster/on-exit/<launch id>.log. A launch that fails at readiness runs it too, with MUSTER_STATE=failed and MUSTER_ERROR. wait and list show it as on_exit: {claimed_at, result}. It is not run if the machine restarts first.",
         ],
         examples: [
             "muster run claude --prompt 'Review this project' --cwd .",
             "muster run claude --read-only --prompt 'Audit this' --cwd .",
             "muster run codex --identity work --write-here --prompt 'Ship it'",
+            "muster run codex --kind task --prompt 'Review' --on-exit 'notify.sh'",
+        ],
+    },
+    {
+        name: "wait",
+        summary: "block until a session or task has ended",
+        synopsis: "muster wait <id> [--timeout SECONDS] [--format json|human]",
+        options: [
+            [
+                "--timeout SECONDS",
+                "give up after this long: seconds, or 90s, 30m, 4h",
+            ],
+            ["--format FORMAT", "json (default) or human"],
+        ],
+        notes: [
+            "Prints the final record, with state, exit_code and signal (null for a session, whose terminal keeps no exit status). Exits 0 when it has ended, 2 for an id that names nothing, and 124 on timeout, printing the record as it stands.",
+        ],
+        examples: [
+            "muster wait 6fae755b-8f5d-4425-8ed7-69e84bfac8c5",
+            "muster wait simple-cms-46 --timeout 30m",
         ],
     },
     {

package/dist/identity/claude.js

@@ -1,10 +1,11 @@
 /** Registry-reading mechanics vendored from Tin Can src/claude/discover.ts at
  * fbaaea5842fd4a5c86849d7f51c8e16b8683b058 (MIT). Only captured descendants are
  * read, rather than scanning and diffing live sessions. */
-import { readFile, access } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile, access, realpath } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { homedir } from "node:os";
-import { descendants } from "./processes.js";
+import { command, descendants } from "./processes.js";
+import { workspaceTrustKey } from "./workspace-key.js";
 /**
  * Where Claude Code records its sessions. `CLAUDE_CONFIG_DIR` relocates the whole
  * configuration directory, sessions included, so discovery must follow it —
@@ -15,10 +16,11 @@ import { descendants } from "./processes.js";
 export function claudeSessionsDir(env) {
     return join(claudeConfigDir(env), "sessions");
 }
-/** The configuration directory itself, which `claudeSessionsDir` and the
- * workspace-trust read below both hang off. Split out so the two cannot drift:
- * a trust decision read from a different directory than the one the launch
- * records its session in would describe a profile nobody is launching. */
+/** The configuration directory itself, which `claudeSessionsDir` and
+ * `claudeTrustFile` both follow. Resolved from the same CLAUDE_CONFIG_DIR so
+ * the two cannot drift: a trust decision read from a different profile than
+ * the one the launch records its session in would describe a profile nobody
+ * is launching. */
 export function claudeConfigDir(env) {
     const configured = env.CLAUDE_CONFIG_DIR;
     if (typeof configured === "string" && configured.length)
@@ -26,10 +28,49 @@ export function claudeConfigDir(env) {
     return join(env.HOME ?? homedir(), ".claude");
 }
 /**
- * Whether Claude Code has recorded an accepted workspace-trust dialog for one
- * directory, in the profile a launch would use. Trust is per-directory and is
- * NOT inherited from a parent: a trusted `/Source/arm` says nothing about
- * `/Source/arm/centrumx`, and the child still stops at the dialog.
+ * The file Claude Code keeps workspace trust in. Not inside the configuration
+ * directory by default: with no CLAUDE_CONFIG_DIR it is `~/.claude.json`,
+ * beside `~/.claude`, and only a relocated profile keeps it inside.
+ */
+export function claudeTrustFile(env) {
+    const configured = env.CLAUDE_CONFIG_DIR;
+    return typeof configured === "string" && configured.length
+        ? join(configured, ".claude.json")
+        : join(env.HOME ?? homedir(), ".claude.json");
+}
+/**
+ * Every key whose accepted dialog lets a launch in `cwd` past Claude's trust
+ * dialog. The dialog gate walks up from the launch directory and stops at the
+ * git repo's top level, or walks to `/` outside a repository — so a trusted
+ * parent counts inside its own repo and never across a repo boundary. The
+ * repo's own trust key (the main checkout, for a linked worktree) is what
+ * Muster writes, so it counts too. See `workspaceTrustKey`.
+ */
+async function trustKeys(cwd) {
+    const resolved = await realpath(cwd).catch(() => cwd);
+    let top;
+    try {
+        const shown = (await command("git", ["-C", resolved, "rev-parse", "--show-toplevel"], 2000)).trim();
+        if (shown)
+            top = await realpath(shown).catch(() => shown);
+    }
+    catch { }
+    const keys = new Set([cwd]);
+    for (let dir = resolved;; dir = dirname(dir)) {
+        keys.add(dir);
+        if (dir === top || dirname(dir) === dir)
+            break;
+    }
+    keys.add(await workspaceTrustKey(resolved));
+    return [...keys];
+}
+/**
+ * Whether Claude Code would let a session in `cwd` past its workspace-trust
+ * dialog, in the profile a launch would use: an accepted dialog on the
+ * directory, on an ancestor inside the same git repo, or on the repo's trust
+ * key. Checking the exact directory alone called every worktree and every
+ * subdirectory of a trusted repo untrusted, and blamed trust for a launch that
+ * had simply timed out (#68).
  *
  * This only ever READS. Muster does not accept the dialog on the operator's
  * behalf — `setWorkspaceTrust` writes that flag into an identity copy Muster
@@ -44,18 +85,20 @@ export function claudeConfigDir(env) {
 export async function claudeWorkspaceTrusted(env, cwd) {
     let raw;
     try {
-        raw = await readFile(join(claudeConfigDir(env), ".claude.json"), "utf8");
+        raw = await readFile(claudeTrustFile(env), "utf8");
     }
     catch {
         return false;
     }
+    let projects;
     try {
-        const data = JSON.parse(raw);
-        return data.projects?.[cwd]?.hasTrustDialogAccepted === true;
+        projects =
+            JSON.parse(raw).projects ?? {};
     }
     catch {
         return false;
     }
+    return (await trustKeys(cwd)).some((key) => projects[key]?.hasTrustDialogAccepted === true);
 }
 /**
  * The message a Claude launch dies with when no session ever registered.
@@ -74,12 +117,12 @@ export async function claudeWorkspaceTrusted(env, cwd) {
  * it runs headless and never sees the dialog, so it succeeds where a session
  * hangs.
  */
-export function claudeRegistryDiagnostic(trusted, cwd, configDir, opts = {}) {
+export function claudeRegistryDiagnostic(trusted, cwd, trustFile, opts = {}) {
     if (!trusted)
         return (`no Claude session registry found: workspace trust has not been ` +
-            `accepted for ${cwd} in ${configDir} — accept it once with ` +
-            `\`cd ${cwd} && claude\`, then retry (trust is per-directory and is ` +
-            `not inherited from a parent directory)`);
+            `accepted for ${cwd} in ${trustFile} — accept it once with ` +
+            `\`cd ${cwd} && claude\`, then retry (a trusted parent directory ` +
+            `counts only inside the same git repository)`);
     if (opts.bypassWarningPending)
         return (`no Claude session registry found (${cwd} is trusted for this profile): ` +
             `this launch runs in bypass permissions, and Claude stops on its ` +

package/dist/identity/processes.js

@@ -96,10 +96,13 @@ export async function descendants(root, deadline = Date.now() + 1000, group) {
 /** Whether anything still runs in a group we started. */
 export async function groupAlive(group, deadline = Date.now() + 1000) {
     try {
-        const rows = (await command("ps", ["-axo", "pid=,pgid="], Math.max(1, Math.min(1000, deadline - Date.now()))))
+        const rows = (await command("ps", ["-axo", "pid=,pgid=,stat="], Math.max(1, Math.min(1000, deadline - Date.now()))))
             .split("\n")
-            .map((l) => l.trim().split(/\s+/).map(Number));
-        return rows.some(([pid, pgid]) => pid && pid > 1 && pgid === group);
+            .map((l) => l.trim().split(/\s+/));
+        // A zombie is not alive, as `processRef` already holds: a group left with
+        // only an unreaped zombie in it has ended, and counting it kept `wait`
+        // waiting for as long as its parent chose not to reap.
+        return rows.some(([pid, pgid, stat]) => Number(pid) > 1 && Number(pgid) === group && !stat?.startsWith("Z"));
     }
     catch {
         return false;

package/dist/identity-copy.js

@@ -1,4 +1,4 @@
-import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { appendFile, copyFile, mkdir, readFile, writeFile, } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import TOML from "@iarna/toml";
 import { identityPath } from "./identity-store.js";
@@ -127,6 +127,15 @@ export async function setWorkspaceTrust(copyPath, cwd) {
     data.projects = projects;
     await writeFile(file, JSON.stringify(data), { mode: 0o600 });
 }
+function parses(text) {
+    try {
+        TOML.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Set Codex's directory-trust flag for one directory, inside a copy Muster just
  * created. Codex has its own gate, unrelated to Claude's: without a
@@ -145,8 +154,10 @@ export async function setWorkspaceTrust(copyPath, cwd) {
  * parses and is accepted, and the prompt still appears: the check reads
  * persisted config, so the entry has to be in the file.
  *
- * The user's real `~/.codex/config.toml` is never touched, for the same reason
- * `setWorkspaceTrust` leaves the live `~/.claude.json` alone.
+ * Also called on the user's own `~/.codex/config.toml`, for an
+ * `--options auto-approve-path` launch with no CODEX_HOME — the file that
+ * launch's Codex reads. That is why a new entry is appended rather than the
+ * file re-serialised.
  */
 export async function setCodexWorkspaceTrust(copyPath, cwd) {
     const file = join(copyPath, "config.toml");
@@ -177,6 +188,22 @@ export async function setCodexWorkspaceTrust(copyPath, cwd) {
     const existing = (projects[cwd] ?? {});
     if (existing.trust_level === "trusted")
         return;
+    // No entry yet: append one table, exactly as Codex itself does when you
+    // answer its dialog. This file may be the user's own `~/.codex/config.toml`
+    // (a launch with no CODEX_HOME), and re-serialising it would drop every
+    // comment and reorder every key in it. Not when the result would not parse
+    // — `projects` written as an inline table, under any quoting of its key,
+    // which a second `[projects.…]` header would redefine.
+    if (!(cwd in projects)) {
+        const lead = raw && !raw.endsWith("\n") ? "\n" : "";
+        const entry = `${lead}\n[projects.${JSON.stringify(cwd)}]\ntrust_level = "trusted"\n`;
+        if (parses((raw ?? "") + entry)) {
+            // ~/.codex itself may not exist on a machine that has never run Codex.
+            await mkdir(copyPath, { recursive: true, mode: 0o700 });
+            await appendFile(file, entry, { mode: 0o600 });
+            return;
+        }
+    }
     projects[cwd] = { ...existing, trust_level: "trusted" };
     data.projects = projects;
     // Re-serialised rather than appended, so an entry the template already

package/dist/muster.js

@@ -5,7 +5,8 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { Muster } from "./run.js";
+import { Muster, UnknownRun, durableId, failedLaunchId } from "./run.js";
+import { waitSeconds } from "./duration.js";
 import { delay } from "./identity/processes.js";
 import { formatHuman, humanColorEnabled, statusText } from "./format.js";
 import { checkPlugins, npmRegistry } from "./doctor.js";
@@ -17,6 +18,7 @@ import { toolGate } from "./mcp.js";
 import { ALLOW_LAUNCH, MCP_SUBCOMMANDS, mcpCommand, notEnabled, selfInvocation, } from "./mcp-install.js";
 import { normalizeOpenFlag, usesTerminalFlag } from "./guard.js";
 import { commandHelp, topLevelHelp } from "./help.js";
+import { CLI_OPTIONS, asksForHelp } from "./cli-options.js";
 import { promptForMissing, terminalReader } from "./prompt.js";
 const listSchema = z
     .object({ kind: z.enum(["session", "task"]).optional() })
@@ -67,9 +69,10 @@ async function main() {
     }
     // 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])) {
+    // "Unknown option '--help'". Anywhere among the command's own flags, so
+    // `muster run codex --help` is help too; see `asksForHelp` for the `--help`
+    // that is some flag's value, which still reaches the command.
+    if (commandHelp(argv[0] ?? "") && asksForHelp(argv.slice(1))) {
         process.stdout.write(commandHelp(argv[0]));
         return;
     }
@@ -201,41 +204,13 @@ async function main() {
             args: normalizeOpenFlag(argv),
             allowPositionals: true,
             strict: true,
-            options: {
-                prompt: { type: "string" },
-                cwd: { type: "string" },
-                kind: { type: "string" },
-                host: { type: "string" },
-                open: { type: "boolean" },
-                terminal: { type: "string" },
-                format: { type: "string" },
-                permissions: { type: "string" },
-                sandbox: { type: "string" },
-                level: { type: "string" },
-                "read-only": { type: "boolean" },
-                "write-here": { type: "boolean" },
-                unrestricted: { type: "boolean" },
-                mcp: { type: "string", multiple: true },
-                options: { type: "string", multiple: true },
-                "no-mcp": { type: "boolean" },
-                plugin: { type: "string", multiple: true },
-                model: { type: "string" },
-                "idle-timeout": { type: "string" },
-                ttl: { type: "string" },
-                title: { type: "string" },
-                socket: { type: "string" },
-                home: { type: "string" },
-                "stop-now": { type: "boolean" },
-                "no-plugin": { type: "boolean" },
-                "request-key": { type: "string" },
-                project: { type: "string" },
-                identity: { type: "string" },
-                agent: { type: "string" },
-                "token-env": { type: "string" },
-                interactive: { type: "boolean" },
-            },
+            options: CLI_OPTIONS,
         });
-        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, "idle-timeout": idleTimeout, socket, home: homeFlag, "stop-now": stopNow, "read-only": readOnly, "write-here": writeHere, unrestricted, ...values } = parsed;
+        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, "idle-timeout": idleTimeout, socket, home: homeFlag, "stop-now": stopNow, "read-only": readOnly, "write-here": writeHere, unrestricted, "on-exit": onExit, timeout, ...values } = parsed;
+        if (onExit !== undefined && command !== "run")
+            throw new Error("--on-exit applies only to run");
+        if (timeout !== undefined && command !== "wait")
+            throw new Error("--timeout applies only to wait");
         // The plain spellings of the three sealed levels. Each is a level, so the
         // existing exclusivity with --permissions/--sandbox applies unchanged once
         // it is folded into `values.level`.
@@ -267,7 +242,9 @@ async function main() {
             ["--home", homeFlag],
             ["--stop-now", stopNow],
         ])
-            if (value !== undefined && command !== "reap-check")
+            if (value !== undefined &&
+                command !== "reap-check" &&
+                !(name === "--home" && command === "on-exit-watch"))
                 throw new Error(`${name} applies only to reap-check`);
         if (requestKey !== undefined && command !== "run")
             throw new Error("--request-key applies only to run");
@@ -297,13 +274,41 @@ async function main() {
                 process.stderr.write("[muster] --terminal is deprecated and will be removed in v2; pass the app to --open instead, or set terminal in config.toml\n");
             const runtime = positionals[0];
             const args = positionals.slice(1);
-            const record = await muster.run({
-                runtime,
-                ...values,
-                ...(requestKey === undefined ? {} : { requestKey }),
-                ...(idleTimeout === undefined ? {} : { idleTimeout }),
-                args,
-            });
+            let record;
+            try {
+                record = await muster.run({
+                    runtime,
+                    ...values,
+                    ...(requestKey === undefined ? {} : { requestKey }),
+                    ...(idleTimeout === undefined ? {} : { idleTimeout }),
+                    args,
+                });
+            }
+            catch (e) {
+                // A launch that failed still ended, and the caller is waiting on its
+                // command to say so: armed on the failed entry, the watcher finds it
+                // already over and runs it with MUSTER_STATE=failed and MUSTER_ERROR.
+                // The launch's own error is still what this command fails with.
+                const launchId = failedLaunchId(e);
+                if (onExit !== undefined && launchId)
+                    await muster
+                        .armOnExit(launchId, onExit, process.cwd())
+                        .catch((armError) => process.stderr.write(`[muster] --on-exit not run for the failed launch: ${armError.message}\n`));
+                throw e;
+            }
+            // Armed after the launch and before the record is printed, so a caller
+            // that reads the record knows the watcher exists. A launch that is up
+            // but could not be armed still prints its record — the session is real
+            // and needs stopping — and then fails, because the caller asked for a
+            // signal it will not get.
+            if (onExit !== undefined)
+                try {
+                    await muster.armOnExit(durableId(record), onExit, process.cwd());
+                }
+                catch (e) {
+                    print(record);
+                    throw e;
+                }
             print(record);
             if (record.kind === "session" && record.host === "pty") {
                 process.stderr.write("[muster] pty: not watchable or attachable; this process owns the session. Ctrl-C stops it.\n");
@@ -409,6 +414,41 @@ async function main() {
             const { id } = idSchema.parse({ id: positionals[0] });
             print(await muster.title(id, positionals[1]));
         }
+        else if (command === "wait") {
+            if (positionals.length !== 1 || Object.keys(values).length)
+                throw new Error("wait requires exactly one id");
+            const { id } = idSchema.parse({ id: positionals[0] });
+            try {
+                const { done, record } = await muster.wait(id, {
+                    ...(timeout === undefined
+                        ? {}
+                        : { timeoutMs: waitSeconds(timeout) * 1000 }),
+                });
+                print(record);
+                // 124 is timeout(1)'s status, which a shell caller already tests for.
+                if (!done)
+                    process.exitCode = 124;
+            }
+            catch (e) {
+                if (!(e instanceof UnknownRun))
+                    throw e;
+                process.stderr.write(`[muster] ${e.message}\n`);
+                process.exitCode = 2;
+            }
+        }
+        else if (command === "on-exit-watch") {
+            // Hidden, like reap-check: started detached by `run --on-exit`, never
+            // typed. Its own exit status is unread; the command's goes to the log.
+            if (positionals.length !== 1 || !homeFlag)
+                throw new Error("on-exit-watch requires --home and one launch id");
+            const watcher = await Muster.create({ home: homeFlag });
+            try {
+                await watcher.runOnExit(positionals[0]);
+            }
+            finally {
+                await watcher.close();
+            }
+        }
         else if (command === "reap-check") {
             // Hidden: armed by muster itself as a tmux job, never typed by a person.
             // NOTE: `Muster.create()` above already ran against the REAL home before
@@ -435,6 +475,13 @@ async function main() {
     }
 }
 main().catch((e) => {
-    process.stderr.write(`[muster] ${e.message}\n`);
+    const command = process.argv[2] ?? "";
+    // parseArgs's own text explains how to pass a positional that starts with a
+    // dash, which is never what a mistyped flag meant; the flag list is.
+    const hint = e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" &&
+        commandHelp(command)
+        ? `\n[muster] see \`muster ${command} --help\` for its options`
+        : "";
+    process.stderr.write(`[muster] ${e.message}${hint}\n`);
     process.exitCode = 1;
 });

package/dist/on-exit.js

@@ -0,0 +1,98 @@
+/**
+ * Running an `--on-exit` command: what it is told, and where its output goes.
+ * Kept out of run.ts so the environment contract can be tested without a
+ * launch, since that contract is what every caller's script depends on.
+ */
+import { constants } from "node:fs";
+import { access, mkdir, open, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { spawn } from "node:child_process";
+/**
+ * The variables the command receives. Strings only, and an empty string where
+ * the fact was not observed — a session's exit status, a session's output —
+ * because a shell cannot tell an unset variable from a mistyped one.
+ */
+export function onExitEnv(entry, record) {
+    return {
+        MUSTER_ID: String(record.id),
+        MUSTER_RUNTIME: entry.runtime,
+        MUSTER_KIND: entry.kind,
+        MUSTER_STATE: String(record.state),
+        MUSTER_EXIT_CODE: record.exit_code === null || record.exit_code === undefined
+            ? ""
+            : String(record.exit_code),
+        MUSTER_SIGNAL: record.signal ? String(record.signal) : "",
+        // A path rather than the text: a task's output can be megabytes, and the
+        // environment has a size limit that would fail the command outright.
+        MUSTER_OUTPUT: entry.kind === "task" && entry.outputPath ? entry.outputPath : "",
+        // Why a launch failed before it was ever up (`MUSTER_STATE=failed`).
+        MUSTER_ERROR: record.error ? String(record.error) : "",
+        MUSTER_RECORD: JSON.stringify(record),
+    };
+}
+/**
+ * Why a directory cannot be a command's cwd, or undefined when it can: it must
+ * be a directory and searchable, because a spawn into one that is not fails
+ * after the claim is spent. Still a check, not a lock — the directory can
+ * change between here and the spawn, and that race is left to the spawn's own
+ * error, which the result records.
+ */
+async function enterable(dir) {
+    try {
+        if (!(await stat(dir)).isDirectory())
+            return "not a directory";
+        await access(dir, constants.X_OK);
+        return undefined;
+    }
+    catch (e) {
+        return e.message;
+    }
+}
+/**
+ * Where the command will run and where its output will go, settled before the
+ * command is claimed, because a claim is spent whether or not it then starts.
+ * Neither failure is allowed to cost the signal: a directory removed since the
+ * launch, or one that can no longer be entered, falls back to `fallbackCwd`
+ * (and that to `/`), and a log that cannot be opened leaves the output
+ * discarded. Each fallback is reported, for the launch log.
+ */
+export async function prepareOnExit(opts) {
+    const warnings = [];
+    let cwd = opts.cwd;
+    const unusable = await enterable(cwd);
+    if (unusable) {
+        warnings.push(`cwd ${cwd} unusable (${unusable}); ran in ${opts.fallbackCwd}`);
+        cwd = opts.fallbackCwd;
+        const fallback = await enterable(cwd);
+        if (fallback) {
+            warnings.push(`fallback ${cwd} unusable (${fallback}); ran in /`);
+            cwd = "/";
+        }
+    }
+    try {
+        await mkdir(dirname(opts.logPath), { recursive: true, mode: 0o700 });
+        return { cwd, log: await open(opts.logPath, "a", 0o600), warnings };
+    }
+    catch (e) {
+        warnings.push(`log ${opts.logPath} unusable (${e.message}); output discarded`);
+        return { cwd, warnings };
+    }
+}
+/**
+ * Runs `command` through `/bin/sh -c`, resolving to how it ended, or to why it
+ * never started. `onSpawn` is called once the shell is running, so whatever it
+ * does cannot keep the command from starting.
+ */
+export async function runOnExitCommand(opts) {
+    const out = opts.log?.fd ?? "ignore";
+    return new Promise((resolve) => {
+        const child = spawn("/bin/sh", ["-c", opts.command], {
+            cwd: opts.cwd,
+            env: { ...opts.env, ...onExitEnv(opts.entry, opts.record) },
+            stdio: ["ignore", out, out],
+        });
+        child.once("spawn", () => opts.onSpawn?.());
+        child.once("error", (e) => resolve({ exit_code: null, signal: null, error: e.message }));
+        child.once("exit", (code, signal) => resolve({ exit_code: code, signal: signal ?? null }));
+    });
+}