@brutalsystems/muster 0.7.8 → 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/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/package.json

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