@brutalsystems/muster 3.3.2 → 3.3.4

package/dist/help.js

@@ -138,7 +138,7 @@ export const COMMANDS = [
             ["--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.",
+            "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, 124 on timeout, printing the record as it stands, and 75 when the registry is locked (as every command does): retry.",
         ],
         examples: [
             "muster wait 6fae755b-8f5d-4425-8ed7-69e84bfac8c5",

package/dist/hosts/tmux.js

@@ -210,14 +210,19 @@ export class TmuxHost {
      * Run `argv` in the background after `seconds`, scheduled by the tmux server
      * itself. This is what lets a lifecycle outlive every muster process: nothing
      * of ours is running between the call and the job.
+     *
+     * The job's output goes to `log`, and it always exits 0. tmux shows a
+     * `run-shell` job's non-zero exit as "'<cmd>' returned 1" in whichever pane
+     * is active on the server, which is someone else's session, and it never
+     * shows the job's stderr, so the error itself was lost (#65).
      */
-    async schedule(seconds, argv) {
+    async schedule(seconds, argv, log) {
         await this.call([
             "run-shell",
             "-b",
             "-d",
             String(Math.max(1, Math.round(seconds))),
-            tmuxCommand(argv),
+            `${tmuxCommand(argv)} >>${tmuxCommand([log])} 2>&1 || true`,
         ]);
     }
     async launch(opts) {

package/dist/muster.js

@@ -6,6 +6,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { Muster, UnknownRun, durableId, failedLaunchId } from "./run.js";
+import { RegistryLocked } from "./registry.js";
 import { waitSeconds } from "./duration.js";
 import { delay } from "./identity/processes.js";
 import { formatHuman, humanColorEnabled, statusText } from "./format.js";
@@ -111,6 +112,30 @@ async function main() {
     const allowLaunch = argv[0] === "mcp" && argv[1] === ALLOW_LAUNCH;
     if (argv[0] === "mcp" && argv.length > (allowLaunch ? 2 : 1))
         throw new Error(`mcp takes ${ALLOW_LAUNCH}, or one of ${MCP_SUBCOMMANDS.join(", ")}`);
+    // Before Muster.create(), which reads the real home's config: a broken
+    // config.toml failed every poll outside `reapCheck`, whose own catch is what
+    // re-arms, so the session's idle timeout was silently dropped (#65).
+    if (argv[0] === "reap-check") {
+        const { values, positionals } = parseArgs({
+            args: argv.slice(1),
+            allowPositionals: true,
+            strict: true,
+            options: CLI_OPTIONS,
+        });
+        // Hidden: armed by muster itself as a tmux job, never typed by a person.
+        if (positionals.length !== 1 || !values.socket)
+            throw new Error("reap-check requires --socket and one launch id");
+        const { reapCheck } = await import("./reap.js");
+        await reapCheck({
+            home: values.home ?? musterHome(),
+            socket: values.socket,
+            ...(values["stop-now"] ? { stopNow: true } : {}),
+            launchId: positionals[0],
+            // The exact command that was armed, so a re-arm reproduces itself.
+            argv: [...process.argv],
+        });
+        return;
+    }
     const muster = await Muster.create();
     let shutdown;
     const close = () => (shutdown ??= (async () => {
@@ -452,24 +477,6 @@ async function main() {
                 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
-            // this dispatch. Harmless (nothing is owned, so `close()` stops nothing)
-            // but it means a broken ~/.muster/config.toml would fail every poll.
-            // Left as-is: moving that create changes every command's startup.
-            if (positionals.length !== 1 || !socket)
-                throw new Error("reap-check requires --socket and one launch id");
-            const { reapCheck } = await import("./reap.js");
-            await reapCheck({
-                home: homeFlag ?? musterHome(),
-                socket,
-                ...(stopNow ? { stopNow: true } : {}),
-                launchId: positionals[0],
-                // The exact command that was armed, so a re-arm reproduces itself.
-                argv: [...process.argv],
-            });
-        }
         else
             throw new Error(topLevelHelp());
     }
@@ -485,6 +492,11 @@ main().catch((e) => {
         commandHelp(command)
         ? `\n[muster] see \`muster ${command} --help\` for its options`
         : "";
-    process.stderr.write(`[muster] ${e.message}${hint}\n`);
-    process.exitCode = 1;
+    // reap-check's stderr is the reap log, read later by someone asking which
+    // poll failed and when.
+    const context = command === "reap-check"
+        ? `${new Date().toISOString()} reap-check ${process.argv.slice(3).find((a) => /^[0-9a-f-]{36}$/i.test(a)) ?? "?"}: `
+        : "";
+    process.stderr.write(`[muster] ${context}${e.message}${hint}\n`);
+    process.exitCode = e instanceof RegistryLocked ? RegistryLocked.exitCode : 1;
 });

package/dist/reap.js

@@ -1,4 +1,13 @@
+import { join } from "node:path";
 import { Registry } from "./registry.js";
+/**
+ * Where the reaper's tmux jobs write their output, under muster's home. Not
+ * launches.jsonl: that is one JSON event per line, and raw shell output would
+ * break every reader of it.
+ */
+export function reapLog(home) {
+    return join(home, "reap.log");
+}
 // The floor is low so a short limit is honoured rather than rounded up: a 45s
 // ttl behind a 30s floor fires at up to 75s. A session with a limit that short
 // does not live long enough for the extra polls to matter.
@@ -57,11 +66,11 @@ export function decide(entry, state) {
 export async function reapCheck(opts) {
     const rearm = async (seconds) => {
         const schedule = opts.schedule ??
-            (async (s, argv) => {
+            (async (s, argv, log) => {
                 const { TmuxHost } = await import("./hosts/tmux.js");
-                await new TmuxHost(opts.socket).schedule(s, argv);
+                await new TmuxHost(opts.socket).schedule(s, argv, log);
             });
-        await schedule(seconds, opts.argv);
+        await schedule(seconds, opts.argv, reapLog(opts.home));
         return { action: "rearm", seconds };
     };
     try {
@@ -92,7 +101,24 @@ export async function reapCheck(opts) {
                 ((e, args) => {
                     // Detached and unref'd so it survives the tmux server exiting as the
                     // session it is stopping goes away.
-                    void import("node:child_process").then(({ spawn }) => spawn(e, args, { detached: true, stdio: "ignore" }).unref());
+                    // Its output goes to the reap log too: with stdio ignored, a stop
+                    // that failed left no trace anywhere.
+                    void Promise.all([
+                        import("node:child_process"),
+                        import("node:fs"),
+                    ]).then(([{ spawn }, { openSync, closeSync }]) => {
+                        let out = "ignore";
+                        try {
+                            out = openSync(reapLog(opts.home), "a", 0o600);
+                        }
+                        catch { }
+                        spawn(e, args, {
+                            detached: true,
+                            stdio: ["ignore", out, out],
+                        }).unref();
+                        if (out !== "ignore")
+                            closeSync(out);
+                    });
                 });
             spawnFn(exec, [...opts.argv.slice(1), "--stop-now"]);
         }

package/dist/registry.js

@@ -38,12 +38,25 @@ export class IdempotencyKeyReuse extends Error {
     }
 }
 /**
- * A lock directory with no owner file is presumed live for this long. Long
- * enough that no transaction comes near it, and the holder writes its owner
- * file immediately after taking the lock, so in practice only a lock left by a
- * version that wrote none (an empty directory) ever reaches it.
+ * A lock directory with no owner file is presumed live for this long. A
+ * transaction holds the lock for milliseconds and the holder writes its owner
+ * file immediately after taking it, so a lock still unowned this long was left
+ * by a holder killed in between, or by a version that wrote none (#64). Three
+ * default lock waits: one waiter may still time out on it, the next breaks it.
  */
-const UNOWNED_LOCK_MS = 60_000;
+const UNOWNED_LOCK_MS = 15_000;
+/**
+ * The registry is busy, not broken and not empty: the CLI exits 75
+ * (EX_TEMPFAIL, "try again later") for it, so a script polling `list` or
+ * `wait` can tell it from a run that is gone (#64) and retry.
+ */
+export class RegistryLocked extends Error {
+    static exitCode = 75;
+    constructor(message) {
+        super(message);
+        this.name = "RegistryLocked";
+    }
+}
 let self;
 /** Statuses whose process is over: such an entry no longer holds its id. */
 const FINISHED = ["exited", "failed", "stopped"];
@@ -84,9 +97,14 @@ export class Registry {
                     continue;
                 if (Date.now() > deadline) {
                     const owner = await lockOwner(lock);
-                    throw new Error(owner
-                        ? `Registry locked, held by pid ${owner.pid}; verify no Muster operation is running before removing registry.lock`
-                        : "Registry locked; verify no Muster operation is running before removing registry.lock");
+                    const age = await ageMs(lock);
+                    const held = [
+                        owner ? `held by pid ${owner.pid}` : "with no owner recorded",
+                        age === undefined ? undefined : `for ${Math.round(age / 1000)}s`,
+                    ]
+                        .filter(Boolean)
+                        .join(" ");
+                    throw new RegistryLocked(`Registry locked, ${held}; retry shortly. If it persists, verify no Muster operation is running before removing ${lock}`);
                 }
                 await delay(20);
             }

package/dist/run.js

@@ -11,7 +11,7 @@ import { assertEnforcementMeetsMinimum, assertLevelWithinCeiling, assertMayAct,
 import { IdentityError, readIdentity, } from "./identity-store.js";
 import { resolveCredential } from "./identity-token.js";
 import { copyIdentity, identityEnv } from "./identity-copy.js";
-import { currentEntry, Registry } from "./registry.js";
+import { currentEntry, Registry, RegistryLocked, } from "./registry.js";
 import { LaunchLog } from "./log.js";
 import { hosts, selectHost } from "./hosts/index.js";
 import { AGENTS } from "./agents.js";
@@ -31,7 +31,7 @@ import { allocateLoopbackPort, OpenCodeHttp } from "./opencode-http.js";
 import { assertOpenCodeVersion, openCodeMcpNames, openCodeSessionLaunch, openCodeTaskLaunch, } from "./opencode-policy.js";
 import { assignNames, resolvePeer, runtimeName, suffixOf, } from "./naming.js";
 import { selectMcp, prepareMcp, mcpEnvironment, } from "./mcp.js";
-import { pollInterval } from "./reap.js";
+import { pollInterval, reapLog } from "./reap.js";
 import { selectPlugins } from "./plugins.js";
 import { prepareOnExit, runOnExitCommand } from "./on-exit.js";
 function taskHandle(entry, pid) {
@@ -714,7 +714,7 @@ export class Muster {
                 "--socket",
                 driver.socketName?.() ?? "muster",
                 entry.launchId,
-            ])
+            ], reapLog(this.home))
                 .then(() => true, () => false);
             // A lifecycle that could not be armed must not fail the launch — the
             // session is up and usable, and the orphan risk is what we had before.
@@ -1470,6 +1470,10 @@ export class Muster {
             return await this.find(id);
         }
         catch (e) {
+            // Busy is not gone: `wait` exits 2 for an UnknownRun, and a poller that
+            // read a lock as "no such run" is how #64 ended a wait loop early.
+            if (e instanceof RegistryLocked)
+                throw e;
             const message = e.message;
             // The resolver's "unknown: <every live name>" reads as a list of
             // matches; the ambiguous case does want its candidates, so it keeps them.

package/package.json

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