@brutalsystems/muster 3.3.1 → 3.3.3

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/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";
@@ -486,5 +487,5 @@ main().catch((e) => {
         ? `\n[muster] see \`muster ${command} --help\` for its options`
         : "";
     process.stderr.write(`[muster] ${e.message}${hint}\n`);
-    process.exitCode = 1;
+    process.exitCode = e instanceof RegistryLocked ? RegistryLocked.exitCode : 1;
 });

package/dist/reap.js

@@ -125,8 +125,10 @@ async function stopSession(home, socket, launchId) {
     });
     try {
         const entry = (await new Registry(home).all()).find((e) => e.launchId === launchId);
+        // By launch id: since --resume, the durable id may name a newer launch of
+        // the same session, which this check was not armed for.
         if (entry)
-            await muster.stop(entry.id);
+            await muster.stop(entry.launchId);
     }
     finally {
         await muster.close();

package/dist/registry.js

@@ -38,13 +38,41 @@ 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"];
+/**
+ * The entry a durable id names. One id can have several since `--resume`: the
+ * launches that ran a session before, now finished, and the one running it
+ * now. The live one is meant, else the newest; two live ones cannot arise,
+ * because `update` refuses a second live holder of an id.
+ */
+export function currentEntry(entries) {
+    const live = entries.filter((e) => !FINISHED.includes(e.status));
+    if (live.length > 1)
+        throw new Error("Ambiguous durable id; update by launchId");
+    return (live[0] ??
+        [...entries].sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0]);
+}
 export class Registry {
     home;
     lockWait;
@@ -69,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);
             }
@@ -300,16 +333,16 @@ export class Registry {
     async update(id, patch) {
         return this.transaction(async (entries) => {
             const byLaunch = entries.find((e) => e.launchId === id);
-            const durable = entries.filter((e) => e.id === id);
-            if (!byLaunch && durable.length > 1)
-                throw new Error("Ambiguous durable id; update by launchId");
-            const entry = byLaunch ?? durable[0];
+            const entry = byLaunch ?? currentEntry(entries.filter((e) => e.id === id));
             if (!entry)
                 throw new Error(`Unknown launch ${id}`);
             if ("requester" in patch)
                 throw new Error("requester is recorded once and cannot be updated");
             if (patch.id &&
-                entries.some((e) => e !== entry && e.runtime === entry.runtime && e.id === patch.id))
+                entries.some((e) => e !== entry &&
+                    e.runtime === entry.runtime &&
+                    e.id === patch.id &&
+                    !FINISHED.includes(e.status)))
                 throw new Error("Durable identity already registered");
             Object.assign(entry, patch);
             return structuredClone(entry);

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 { 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";
@@ -1185,11 +1185,21 @@ export class Muster {
     }
     async find(id) {
         const all = await this.registry.all();
+        // A launch id names exactly one launch, so a caller that holds one (the
+        // reaper) can never reach a later launch of the same resumed session.
+        const launch = all.find((e) => e.launchId === id);
+        if (launch)
+            return launch;
         const exact = all.filter((e) => e.id === id);
         if (exact.length === 1)
             return exact[0];
-        if (exact.length > 1)
-            throw new Error(`Ambiguous durable id: ${exact.map((e) => e.runtime + ":" + e.id).join(", ")}`);
+        // The same session under two runtimes is ambiguous. Under one, it was
+        // resumed: the launch running it now, else the latest, is the one meant.
+        if (exact.length > 1) {
+            if (new Set(exact.map((e) => e.runtime)).size > 1)
+                throw new Error(`Ambiguous durable id: ${exact.map((e) => e.runtime + ":" + e.id).join(", ")}`);
+            return currentEntry(exact);
+        }
         const peers = all.filter((e) => e.kind === "session" && e.status === "running" && e.peer);
         const named = peers.map((e) => ({
             runtime: runtimeName(e.runtime),
@@ -1460,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.1",
+  "version": "3.3.3",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {