@brutalsystems/muster 0.7.8 → 0.7.10

package/README.md

@@ -180,6 +180,70 @@ 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.
 
+## Repeating a launch request
+
+`--request-key KEY` (MCP: `requestKey`) names the launch *request*, not the
+session it produces. Sending the same key again returns the launch it already
+produced instead of starting a second agent:
+
+```sh
+muster run codex --prompt "Review the auth flow" --request-key review-auth-7f3a
+```
+
+A key is bound to the parameters it was first seen with — runtime, kind,
+resolved working directory, the instruction, the effective permissions, the
+selected MCP servers and plugins, and the model. Sending the same key with any
+of those changed is **refused**, rather than answered with a session that does
+something other than what was asked. Launching something genuinely different
+means using a different key.
+
+The fingerprint is computed here, after validation, rather than accepted from
+the caller: two machines canonicalize a path differently, and a fingerprint
+computed before validation would disagree with itself.
+
+What a repeat returns depends on what the first attempt did:
+
+| First attempt | A repeat gets |
+| --- | --- |
+| Reachable session or running task | That session or task, unchanged |
+| Still launching | Refused — ask for its status instead |
+| Failed, exited or stopped | Refused, naming the recorded outcome |
+
+A repeat never consumes launch capacity, including when the concurrency cap is
+full of the very launch being asked about. Omitting the key leaves behaviour
+exactly as it was: every request is its own launch.
+
+## 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/guard.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import { mcpName, claudeMcpConfig } from "./mcp.js";
 import { pluginName } from "./plugins.js";
@@ -22,6 +23,7 @@ export const runSchema = z
     mcp: z.array(mcpName).optional(),
     plugin: z.array(pluginName).optional(),
     model: z.string().min(1).optional(),
+    requestKey: z.string().min(1).max(200).optional(),
     args: z.array(z.string()).default([]),
 })
     .strict();
@@ -40,6 +42,37 @@ export function resolvePermissions(req, config) {
         throw new Error("--permissions bypass requires --sandbox full-access");
     return { permissions, sandbox };
 }
+/**
+ * What a request key is bound to, so the same key arriving with different
+ * parameters can be refused rather than silently answered with the wrong
+ * session.
+ *
+ * Computed here, after validation and after defaults are resolved, rather than
+ * accepted from the caller: a sender and a receiver canonicalize a path
+ * differently (symlinks, /private, a different home directory), and a
+ * fingerprint computed before validation would disagree with itself across
+ * machines.
+ *
+ * Covers what changes *what gets launched*. Excludes anything cosmetic or
+ * derived at launch — timestamps, the key itself, pids, ports, tmux targets —
+ * because changing those should not make this a different request.
+ */
+export function paramsFingerprint(req, permissions, mcp, plugins) {
+    return createHash("sha256")
+        .update(JSON.stringify([
+        req.runtime,
+        req.kind,
+        req.cwd,
+        createHash("sha256").update(req.prompt).digest("hex"),
+        permissions.permissions,
+        permissions.sandbox,
+        [...mcp].sort(),
+        [...plugins].sort(),
+        req.model ?? null,
+        req.args,
+    ]))
+        .digest("hex");
+}
 export function runtimeArgs(req) {
     const result = [];
     const allowed = req.runtime === "claude"

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/muster.js

@@ -17,7 +17,7 @@ const listSchema = z
 const idSchema = z.object({ id: z.string().min(1) }).strict();
 const { version } = createRequire(import.meta.url)("../package.json");
 const help = `Usage:
-  muster run <codex|claude|opencode> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [--terminal APP] [-- RUNTIME_OPTIONS]
+  muster run <codex|claude|opencode> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [--terminal APP] [--request-key KEY] [-- RUNTIME_OPTIONS]
   muster list [--kind session|task] [--format json|human]
   muster stop <id> [--format json|human]
   muster output <id>
@@ -37,6 +37,9 @@ which also admits any plugin the target repository ships.
 --model PROVIDER/MODEL selects the OpenCode model, overriding the configured
 [opencode] model. Providers defined under [opencode.provider] are supplied to
 the child, so launches do not depend on the user's own OpenCode config.
+--request-key KEY names the launch request itself. Sending the same key again
+returns the launch it already produced rather than starting a second one, and
+sending it with different parameters is refused rather than answered.
 run, list and stop default to JSON. output prints raw task text.
 
 doctor checks path-configured plugins against the packages they came from: a
@@ -126,6 +129,12 @@ async function main() {
                                 items: { type: "string", pattern: "^[a-zA-Z0-9_-]+$" },
                                 description: "Configured MCP server names. Omit for session defaults; [] disables all. Tasks have no defaults.",
                             },
+                            requestKey: {
+                                type: "string",
+                                minLength: 1,
+                                maxLength: 200,
+                                description: "Caller-owned identity for this launch. Repeating it returns the launch it already produced instead of starting another; repeating it with different parameters is refused.",
+                            },
                             args: { type: "array", items: { type: "string" } },
                         },
                         required: ["runtime", "prompt"],
@@ -217,9 +226,12 @@ async function main() {
                 plugin: { type: "string", multiple: true },
                 model: { type: "string" },
                 "no-plugin": { type: "boolean" },
+                "request-key": { type: "string" },
             },
         });
-        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, ...values } = parsed;
+        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, ...values } = parsed;
+        if (requestKey !== undefined && command !== "run")
+            throw new Error("--request-key applies only to run");
         if (noMcp !== undefined && command !== "run")
             throw new Error("--no-mcp applies only to run");
         if (noMcp && values.mcp)
@@ -242,7 +254,12 @@ async function main() {
         if (command === "run") {
             const runtime = positionals[0];
             const args = positionals.slice(1);
-            const record = await muster.run({ runtime, ...values, args });
+            const record = await muster.run({
+                runtime,
+                ...values,
+                ...(requestKey === undefined ? {} : { requestKey }),
+                args,
+            });
             print(record);
             if (record.kind === "session" && record.host === "pty") {
                 process.stderr.write("[muster] pty: not watchable or attachable; this process owns the session. Ctrl-C stops it.\n");

package/dist/registry.js

@@ -2,6 +2,25 @@ import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { processRef, isSame, delay, } from "./identity/processes.js";
+/**
+ * A request key arrived again with different parameters. Distinct from a launch
+ * failure: nothing was attempted, and the caller reused a key it should have
+ * rotated.
+ */
+export class IdempotencyKeyReuse extends Error {
+    requestKey;
+    recorded;
+    offered;
+    constructor(requestKey, recorded, offered) {
+        super(`Request key ${requestKey} was recorded with different parameters ` +
+            `(recorded ${recorded.slice(0, 12)}, offered ${offered.slice(0, 12)}). ` +
+            `Use a new key to launch something different.`);
+        this.requestKey = requestKey;
+        this.recorded = recorded;
+        this.offered = offered;
+        this.name = "IdempotencyKeyReuse";
+    }
+}
 export class Registry {
     home;
     constructor(home) {
@@ -65,11 +84,28 @@ export class Registry {
     async all() {
         return this.transaction(async (entries) => structuredClone(entries));
     }
-    async reserve(req, cap) {
+    /**
+     * The lookup runs inside the same transaction as the write, so the mkdir lock
+     * that already serializes reservations serializes deduplication too.
+     *
+     * Order is load-bearing: a match returns before the cap is consulted, because
+     * the entry it returns is already counted against the cap. Checking capacity
+     * first would reject a retry of a launch that succeeded, which reads as a
+     * failure and invites a third attempt.
+     */
+    async reserve(req, cap, idem) {
         const owner = await processRef(process.pid);
         if (!owner)
             throw new Error("Cannot identify Muster owner process");
         return this.transaction(async (entries) => {
+            if (idem) {
+                const prior = entries.find((e) => e.requestKey === idem.requestKey);
+                if (prior) {
+                    if (prior.paramsFingerprint !== idem.paramsFingerprint)
+                        throw new IdempotencyKeyReuse(idem.requestKey, prior.paramsFingerprint ?? "none", idem.paramsFingerprint);
+                    return { entry: structuredClone(prior), deduped: true };
+                }
+            }
             if (entries.filter((e) => e.status === "starting" || e.status === "running")
                 .length >= cap)
                 throw new Error(`Concurrency cap reached (${cap})`);
@@ -78,12 +114,13 @@ export class Registry {
                 ...req,
                 id,
                 launchId: id,
+                ...(idem ?? {}),
                 status: "starting",
                 createdAt: new Date().toISOString(),
                 owner,
             };
             entries.push(entry);
-            return { ...entry };
+            return { entry: { ...entry }, deduped: false };
         });
     }
     async update(id, patch) {

package/dist/run.js

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { loadConfig } from "./config.js";
-import { runSchema, launchArgs, launchEnv, resolvePermissions, runtimeArgs, } from "./guard.js";
+import { runSchema, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, runtimeArgs, } from "./guard.js";
 import { Registry } from "./registry.js";
 import { LaunchLog } from "./log.js";
 import { hosts, selectHost } from "./hosts/index.js";
@@ -23,6 +23,20 @@ import { assertOpenCodeVersion, openCodeMcpNames, openCodeSessionLaunch, openCod
 import { assignNames, resolvePeer, runtimeName, } from "./naming.js";
 import { selectMcp, prepareMcp, mcpEnvironment } from "./mcp.js";
 import { selectPlugins } from "./plugins.js";
+function taskHandle(entry, pid) {
+    return {
+        kind: "task",
+        permissions: entry.permissions,
+        sandbox: entry.sandbox,
+        mcp: entry.mcp ?? [],
+        ...(entry.mcp_warnings ? { mcp_warnings: entry.mcp_warnings } : {}),
+        id: entry.id,
+        runtime: entry.runtime,
+        state: "running",
+        cwd: entry.cwd,
+        pid,
+    };
+}
 export class Muster {
     config;
     home;
@@ -86,7 +100,22 @@ export class Muster {
             await assertClaudePolicy(this.env);
         if (req.runtime === "opencode")
             await assertOpenCodeVersion(this.env, "1.18.31", Date.now() + 4000);
-        const reservation = await this.registry.reserve({ runtime: req.runtime, kind: req.kind, cwd: req.cwd, ...permissions }, this.config.max_concurrent);
+        const { entry: reservation, deduped } = await this.registry.reserve({ runtime: req.runtime, kind: req.kind, cwd: req.cwd, ...permissions }, this.config.max_concurrent, req.requestKey
+            ? {
+                requestKey: req.requestKey,
+                paramsFingerprint: paramsFingerprint(req, permissions, selectedMcp.map((s) => s.name), selectedPlugins.map((p) => p.name)),
+            }
+            : undefined);
+        if (deduped) {
+            await this.log.write({
+                event: "deduped",
+                launch_id: reservation.launchId,
+                request_key: req.requestKey,
+                status: reservation.status,
+                requester,
+            });
+            return this.recordedOutcome(reservation);
+        }
         this.owned.add(reservation.launchId);
         let entry = reservation;
         const startedAt = Date.now();
@@ -305,6 +334,32 @@ export class Muster {
             await rpc?.close();
         }
     }
+    /**
+     * The answer to a request we have already seen. Never a new launch: a repeat
+     * of a request that succeeded must return what it produced, and a repeat of
+     * one that did not must report that rather than quietly trying again.
+     *
+     * A launch still in flight is refused rather than answered, because there is
+     * nothing yet to return and inventing a pending result would let a caller
+     * treat it as a session.
+     */
+    recordedOutcome(entry) {
+        const key = entry.requestKey;
+        if (entry.status === "starting")
+            throw new Error(`Request key ${key} is already launching (${entry.launchId}); ask for its status rather than launching again`);
+        if (entry.status !== "running")
+            throw new Error(`Request key ${key} already resolved as ${entry.status}` +
+                (entry.error ? `: ${entry.error}` : "") +
+                `; use a different key to launch again`);
+        if (entry.kind === "task") {
+            if (!entry.root)
+                throw new Error(`Request key ${key} has no recorded task process`);
+            return taskHandle(entry, entry.root.pid);
+        }
+        if (!entry.peer)
+            throw new Error(`Request key ${key} has no recorded session`);
+        return entry.peer;
+    }
     async startTask(entry, argv, env) {
         const dir = join(this.home, "tasks", entry.id);
         await mkdir(dir, { recursive: true, mode: 0o700 });
@@ -342,18 +397,7 @@ export class Muster {
             });
             await writeFile(startPath, "start", { mode: 0o600 });
             child.unref();
-            const handle = {
-                kind: "task",
-                permissions: entry.permissions,
-                sandbox: entry.sandbox,
-                mcp: entry.mcp ?? [],
-                ...(entry.mcp_warnings ? { mcp_warnings: entry.mcp_warnings } : {}),
-                id: entry.id,
-                runtime: entry.runtime,
-                state: "running",
-                cwd: entry.cwd,
-                pid: root.pid,
-            };
+            const handle = taskHandle(entry, root.pid);
             await this.log.write({
                 event: "started",
                 launch_id: entry.launchId,

package/package.json

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