@brutalsystems/muster 0.7.7 → 0.7.9

package/README.md

@@ -180,6 +180,37 @@ OpenCode sessions otherwise use the same tmux/pty, viewer, list, stop, and human
 output behavior described above; OpenCode tasks use the same detached output
 and exit-status lifecycle as other tasks.
 
+## Process ownership
+
+Muster identifies a launched process by its **pid paired with its start time**,
+and revalidates that pair whenever the registry is touched — including after
+Muster itself restarts.
+
+This is not a compromise chosen for convenience. On macOS it is the strongest
+check the public platform offers:
+
+- There is no cgroup. Process groups and sessions are the nearest approximation
+  and are escapable by design, so they bound a tree rather than owning it.
+- The kernel's unique process identifier is not exposed in the public SDK.
+- The audit-token route requires a message from the target process, which a
+  supervisor observing arbitrary children never has.
+
+Two consequences worth stating, because both look like redundant work to a
+reader who does not know why they are there:
+
+- **Identity is revalidated at the moment of use, not at discovery.** Every
+  signal, every status answer and every registry pass re-checks the pair. A pid
+  discovered a moment ago may already belong to something else.
+- **Revalidation after a Muster restart is deliberate.** Comparable supervisors
+  trust what they recorded before they died. Muster does not, which is why a
+  session that ended while Muster was not running is reported as ended rather
+  than as running.
+
+Process-tree membership is derived from the parent chain, which has a known
+limit: a child reparented after its own parent exits leaves the chain and cannot
+be recovered from it. Tracking that needs a membership signal the chain does not
+carry.
+
 ## Configuration and permissions
 
 Muster reads `~/.muster/config.toml` once at startup and **never writes it**.

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

@@ -1,3 +1,24 @@
+/**
+ * Process identity on macOS.
+ *
+ * A launched process is identified by `(pid, start time)`. That pair is the
+ * ceiling of what this platform offers a supervisor, not a shortcut taken to
+ * avoid something better: there is no cgroup to own a tree, the kernel's unique
+ * process identifier is absent from the public SDK, and `audit_token` requires
+ * a message from the target that arbitrary children never send.
+ *
+ * Two rules follow, and both look like wasted work if the reason is not stated:
+ *
+ * 1. Revalidate at the moment of use, never at discovery. The gap between
+ *    learning a pid and acting on it is where reuse happens, so `isSame()` is
+ *    called immediately before each signal rather than once per operation.
+ * 2. Revalidation survives our own restart. The registry re-checks generations
+ *    on every transaction, so a process that died while Muster was not running
+ *    is reported as dead rather than trusted from what was recorded.
+ *
+ * Membership is derived from the parent chain and inherits its one real limit:
+ * a reparented child is unreachable from the root. See issue #24.
+ */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const exec = promisify(execFile);
@@ -35,25 +56,59 @@ export async function descendants(root, deadline = Date.now() + 1000) {
     }
     return [...found];
 }
+async function liveTree(root) {
+    return (await Promise.all((await descendants(root)).map(processRef))).filter((r) => !!r);
+}
+function signal(ref, name) {
+    try {
+        process.kill(ref.pid, name);
+    }
+    catch { }
+}
+/**
+ * A tree enumerated once, before the wait between SIGTERM and SIGKILL, cannot
+ * contain anything the tree forked during that wait — and a process asked to
+ * terminate is exactly the kind that spawns a last child. So the membership is
+ * re-read after the wait and unioned with what was already known, and only then
+ * is the kill pass run. Each entry is still revalidated immediately before
+ * every signal, because a pid that exits between discovery and the signal may
+ * already belong to something else.
+ *
+ * Reparented descendants are a separate gap: once an intermediate process dies,
+ * its children leave the parent chain entirely and no re-read will find them.
+ * That needs a membership signal the chain does not provide (see issue #24).
+ */
 export async function stopTree(ref) {
     if (!(await isSame(ref)))
         return;
-    const refs = (await Promise.all((await descendants(ref.pid)).map(processRef))).filter((r) => !!r);
-    for (const r of refs.reverse())
-        if (await isSame(r)) {
-            try {
-                process.kill(r.pid, "SIGTERM");
+    const known = new Map();
+    const remember = (refs) => {
+        const added = [];
+        for (const r of refs) {
+            const key = `${r.pid}:${r.start}`;
+            if (!known.has(key)) {
+                known.set(key, r);
+                added.push(r);
             }
-            catch { }
         }
+        return added;
+    };
+    const deepestFirst = () => [...known.values()].reverse();
+    remember(await liveTree(ref.pid));
+    for (const r of deepestFirst())
+        if (await isSame(r))
+            signal(r, "SIGTERM");
     await delay(150);
-    for (const r of refs)
-        if (await isSame(r)) {
-            try {
-                process.kill(r.pid, "SIGKILL");
-            }
-            catch { }
-        }
+    const late = (await isSame(ref)) ? remember(await liveTree(ref.pid)) : [];
+    if (late.length) {
+        for (const r of late.reverse())
+            if (await isSame(r))
+                signal(r, "SIGTERM");
+        await delay(50);
+    }
+    for (const r of deepestFirst())
+        if (await isSame(r))
+            signal(r, "SIGKILL");
 }
 // Called only by a terminal/task supervisor that is the leader of its own group.
 // Keeping the supervisor alive until this point prevents process-group ID reuse.

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.7",
+  "version": "0.7.9",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {