@brutalsystems/muster 0.7.6 → 0.7.8

package/README.md

@@ -37,6 +37,15 @@ Updating on disk is not enough; restart the session too.
 
 ## Build and run locally
 
+`npm run check` is the local gate: it builds, runs the suite, then packs and
+verifies the tarball — the same `scripts/check-tarball.mjs` the CI packing job
+runs, so the two cannot disagree about what "verified" means. `npm test` alone
+does not pack anything, so tarball drift is green locally and red on push.
+
+It is not everything CI does: CI additionally runs the suite across the Node
+version matrix, and the contract suite runs only on release. Passing `check` is
+necessary rather than sufficient.
+
 Requires Node 22.12+ (tested with 24.16), TypeScript 5, Codex 0.155.1, Claude
 Code 2.1.267, and OpenCode 1.18.31 or newer. Newer OpenCode releases must retain
 the CLI and loopback HTTP API used by Muster. Terminal drivers use tmux or
@@ -447,10 +456,11 @@ built-in list is fixed, so a tool added by a future OpenCode release would not
 be denied by it; launches that select no MCP server keep the wildcard. With no plugins
 selected it also uses `--pure` and pins an empty plugin list, so inherited
 plugins do not enter the child process. Selecting a plugin with `--plugin`
-necessarily relaxes that: OpenCode merges project-local `.opencode/plugin`
-discovery into any non-empty plugin list, so the child also loads whatever
-plugins the target repository ships. Select plugins only for repositories
-trusted with that.
+necessarily relaxes that: OpenCode merges project-local plugin discovery into
+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.
 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/hosts/tmux.js

@@ -5,6 +5,41 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { command, processRef, stopTree } from "../identity/processes.js";
 import { terminalAvailable, tmuxExecutable, openTerminal } from "./terminal.js";
+/** tmux rewrites every control character in `-F` output to an underscore when
+ * it runs without a UTF-8 locale — LANG, LC_ALL and LC_CTYPE all unset, which is
+ * ordinary for a launchd job, a bare `ssh host cmd`, or an agent harness. A tab
+ * delimiter then arrives as `@0_11657` and nothing parses. That is #21, filed as
+ * a tmux 3.7c bug on two Macs; it is neither version nor machine specific —
+ * `env -u LANG -u LC_ALL -u LC_CTYPE` reproduces it anywhere, and exporting a
+ * UTF-8 locale makes it vanish on the machines that "had" it.
+ *
+ * So no format here may contain a character tmux is willing to rewrite.
+ * Printable ASCII passes through untouched, and a pipe cannot occur in
+ * #{window_id} (@N), #{pane_pid} (digits), or a session name muster generates.
+ * The one free-text field is read last and keeps whatever it splits into. */
+const FIELD = "|";
+export const LAUNCH_FORMAT = `#{window_id}${FIELD}#{pane_pid}`;
+export const LIST_FORMAT = `#{window_id}${FIELD}#{pane_pid}${FIELD}#{session_name}${FIELD}#{window_name}`;
+export const CLEANUP_FORMAT = `#{window_id}${FIELD}#{pane_start_command}`;
+export function parseWindowRow(output) {
+    const [hostRef, pid] = output.trim().split(FIELD);
+    if (!hostRef || !/^@\d+$/.test(hostRef) || !Number(pid))
+        throw new Error("tmux returned an invalid window identity: " +
+            JSON.stringify(output.length > 200 ? output.slice(0, 200) + "\u2026" : output));
+    return { hostRef, pid: Number(pid) };
+}
+export function parseWindowList(output) {
+    return output
+        .trim()
+        .split("\n")
+        .map((row) => row.split(FIELD))
+        .filter(([, , session]) => session === "muster" || /^muster-[0-9a-f-]{36}$/.test(session ?? ""))
+        .map(([hostRef, pid, , ...label]) => ({
+        hostRef: hostRef,
+        pid: Number(pid),
+        label: label.join(FIELD),
+    }));
+}
 export class TmuxHost {
     server;
     id = "tmux";
@@ -43,7 +78,7 @@ export class TmuxHost {
             "-d",
             "-P",
             "-F",
-            "#{window_id}\t#{pane_pid}",
+            LAUNCH_FORMAT,
             "-n",
             opts.label.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 64) || "agent",
             "-c",
@@ -56,10 +91,7 @@ export class TmuxHost {
             // Window selection is session-wide: sharing a session makes every
             // attached terminal follow whichever agent was opened most recently.
             const output = await this.call(["new-session", "-s", `muster-${randomUUID()}`, ...common], opts.deadline);
-            const [hostRef, pid] = output.trim().split("\t");
-            if (!hostRef || !/^@\d+$/.test(hostRef) || !Number(pid))
-                throw new Error("tmux returned an invalid window identity");
-            return { hostRef, pid: Number(pid) };
+            return parseWindowRow(output);
         }
         catch (e) {
             // The client can time out just after tmux creates the window.
@@ -68,11 +100,11 @@ export class TmuxHost {
                     "list-windows",
                     "-a",
                     "-F",
-                    "#{window_id}\t#{pane_start_command}",
+                    CLEANUP_FORMAT,
                 ]);
                 for (const row of windows.split("\n"))
                     if (row.includes(file))
-                        await this.stop(row.split("\t")[0]);
+                        await this.stop(row.split(FIELD)[0]);
             }
             catch { }
             await rm(dir, { recursive: true, force: true });
@@ -81,22 +113,7 @@ export class TmuxHost {
     }
     async list() {
         try {
-            return (await this.call([
-                "list-windows",
-                "-a",
-                "-F",
-                "#{window_id}\t#{pane_pid}\t#{window_name}\t#{session_name}",
-            ]))
-                .trim()
-                .split("\n")
-                .filter((l) => {
-                const session = l.split("\t")[3];
-                return (session === "muster" || /^muster-[0-9a-f-]{36}$/.test(session ?? ""));
-            })
-                .map((l) => {
-                const [hostRef, pid, label] = l.split("\t");
-                return { hostRef: hostRef, pid: Number(pid), label: label };
-            });
+            return parseWindowList(await this.call(["list-windows", "-a", "-F", LIST_FORMAT]));
         }
         catch {
             return [];

package/dist/identity/codex.js

@@ -5,7 +5,7 @@ import { readdir, realpath } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { command, descendants } from "./processes.js";
-export async function resolveCodex(root, env, deadline, isDirectCli) {
+export async function resolveCodex(root, env, deadline, rejectionOf) {
     let dir = join(env.CODEX_HOME ?? join(env.HOME ?? homedir(), ".codex"), "thread-writer-locks");
     try {
         dir = await realpath(dir);
@@ -49,13 +49,25 @@ export async function resolveCodex(root, env, deadline, isDirectCli) {
         }
     }
     let candidates = [...matches];
-    if (candidates.length > 1 && isDirectCli) {
+    if (candidates.length && rejectionOf) {
         // Auto-review owns internal threads in the same process. Inspect only
         // identities already tied to our descendants; never diff global sessions.
+        // Screening the sole candidate too costs one extra round trip, and buys the
+        // reason a lock cannot be messaged: returning the thread and letting
+        // readiness reject it puts that reason after the launch deadline, where the
+        // loop discards it (#20). Raised here it becomes the diagnostic, and a
+        // later pass can still find a messageable thread.
         const selected = [];
-        for (const candidate of candidates)
-            if (await isDirectCli(candidate[0]))
+        let rejection;
+        for (const candidate of candidates) {
+            const reason = await rejectionOf(candidate[0]);
+            if (reason === null)
                 selected.push(candidate);
+            else
+                rejection ??= reason;
+        }
+        if (!selected.length)
+            throw new Error(rejection);
         candidates = selected;
     }
     if (candidates.length > 1)

package/dist/reach/codex.js

@@ -1,11 +1,22 @@
-export async function codexReachable(rpc, id, deadline) {
-    const { thread } = await rpc.call("thread/read", { threadId: id }, deadline);
+/** Why a thread cannot serve as a messageable session identity, or null if it
+ * can. One source of truth: the launch loop screens candidate writer locks with
+ * this, and readiness re-checks it on the thread it settled on. */
+export function threadRejection(thread, id) {
     if (!thread || thread.id !== id)
-        throw new Error("thread/read returned no matching thread");
+        return "thread/read returned no matching thread";
     if (thread.source === "exec")
-        throw new Error("source is exec, not a messageable session");
+        return "source is exec, not a messageable session";
     if (thread.ephemeral === true || thread.canAcceptDirectInput === false)
-        throw new Error("thread cannot accept direct input");
+        return "thread cannot accept direct input";
+    if (thread.source !== "cli")
+        return "source is not a direct CLI session";
+    return null;
+}
+export async function codexReachable(rpc, id, deadline) {
+    const { thread } = await rpc.call("thread/read", { threadId: id }, deadline);
+    const rejection = threadRejection(thread, id);
+    if (rejection)
+        throw new Error(rejection);
     const listing = await rpc.call("thread/list", { limit: 100, useStateDbOnly: true }, deadline);
     const metadata = Array.isArray(listing.data)
         ? listing.data.find((t) => t.id === id)

package/dist/run.js

@@ -12,7 +12,7 @@ import { processRef, isSame, stopTree, delay, descendants, } from "./identity/pr
 import { resolveCodex } from "./identity/codex.js";
 import { resolveClaude } from "./identity/claude.js";
 import { openCodeEndpointOwnedBy, resolveOpenCode, } from "./identity/opencode.js";
-import { codexReachable } from "./reach/codex.js";
+import { codexReachable, threadRejection } from "./reach/codex.js";
 import { claudeReachable } from "./reach/claude.js";
 import { openCodeReachable } from "./reach/opencode.js";
 import { assertClaudePolicy } from "./claude-policy.js";
@@ -195,13 +195,10 @@ export class Muster {
                         ? await resolveCodex(root.pid, this.env, deadline, async (id) => {
                             try {
                                 const { thread } = await rpc.call("thread/read", { threadId: id }, deadline);
-                                return (thread?.id === id &&
-                                    thread.source === "cli" &&
-                                    thread.ephemeral !== true &&
-                                    thread.canAcceptDirectInput !== false);
+                                return threadRejection(thread, id);
                             }
-                            catch {
-                                return false;
+                            catch (e) {
+                                return e.message;
                             }
                         })
                         : req.runtime === "opencode"
@@ -280,6 +277,11 @@ export class Muster {
                 catch (e) {
                     if (openingTerminal)
                         throw e;
+                    // An error arriving after the deadline is dropped, because most of
+                    // them are artifacts of the deadline itself — aborted round trips
+                    // that would overwrite a real diagnosis with "timed out". The cost is
+                    // that a genuine answer landing a moment late is lost too, so raise
+                    // one as early as it is known rather than at readiness (#20).
                     if (Date.now() < deadline)
                         diagnostic = e.message;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {
@@ -12,6 +12,7 @@
   "scripts": {
     "build": "tsc && node scripts/prepare-bin.mjs",
     "test": "vitest run",
+    "check": "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",