@brutalsystems/muster 0.8.0 → 0.8.2

package/README.md

@@ -55,9 +55,22 @@ driver is an unavailable v1 stub.
 
 Before launching a Claude session, open Claude normally in the target directory
 and complete its workspace-trust review yourself, then exit that setup session.
-This is a one-time prerequisite for each directory Claude requires you to trust.
-Muster never accepts trust prompts or changes trust settings. An untrusted
-directory can block startup; Muster times out and cleans up that launch.
+This is a one-time prerequisite for each directory Claude requires you to trust,
+and trust is **not inherited**: accepting `~/Source/arm` says nothing about
+`~/Source/arm/centrumx`, which still stops at its own dialog. Muster never
+accepts trust prompts or changes trust settings. An untrusted directory blocks
+startup; Muster times out and cleans up that launch.
+
+A session sitting on that dialog has no registry record at all, so the timeout
+used to look identical to a hung or crashed launch. Muster now reads
+`hasTrustDialogAccepted` for the working directory out of the profile's
+`.claude.json` when a Claude launch times out with nothing registered, and
+either names the untrusted directory and the one-time fix or rules trust out
+and points at the remaining consent screens — a login prompt, or the
+confirmation Claude asks for the first time a profile uses bypass-permissions
+mode. That read happens only on the failure path and only ever reads. A
+`--kind task` launch into the same directory is the cheap discriminator by
+hand: it runs headless and never sees the dialog.
 
 ```sh
 npm ci
@@ -405,6 +418,19 @@ arrive after startup; this v1 is not an enterprise policy-enforcement layer.
 Claude permissions and its command sandbox are different mechanisms; neither
 claim implies that every external tool is OS-sandboxed.
 
+**`workspace-write` does not fence Claude's Write tool, only its Bash.** This
+is measured, not inferred — see "Write/Bash fence asymmetry" in
+[PROBE_RESULTS.md](./PROBE_RESULTS.md). At `--level work` an agent's Bash write
+outside the working tree is refused with `Operation not permitted`, while the
+Write tool creates the same path successfully. The practical consequence is
+that **an agent can create files outside the tree that it cannot then delete**,
+because creation goes through Write and cleanup goes through Bash. No setting
+Muster writes expresses the missing fence: the alternative, `deny`, blocks the
+Write tool everywhere rather than by path, including inside the tree. Treat
+`work` as "Bash is confined to the workspace", not "writes are". If that
+distinction matters for a given launch, the containment that does hold for both
+is `read`.
+
 OpenCode keeps normal provider/model configuration and launches with `--pure`
 unless plugins are selected, which disables inherited external plugins.
 Providers declared under `[opencode.provider]` and a model named by

package/dist/duration.js

@@ -11,8 +11,10 @@ export function parseDuration(value, label) {
     const raw = value.trim();
     if (raw.toLowerCase() === "off")
         return "off";
-    const match = /^(\d+)([smh])$/.exec(raw);
-    const seconds = match ? Number(match[1]) * UNITS[match[2]] : 0;
+    const match = /^(\d+)([smh])$/i.exec(raw);
+    const seconds = match
+        ? Number(match[1]) * UNITS[match[2].toLowerCase()]
+        : 0;
     if (!match || seconds <= 0)
         throw new Error(`${label} must be a duration like 90s, 30m, 4h, or off (got ${JSON.stringify(value)})`);
     return seconds;

package/dist/format.js

@@ -15,6 +15,15 @@ function argument(value) {
 export function humanColorEnabled(isTTY, env) {
     return isTTY === true && env.NO_COLOR === undefined && env.TERM !== "dumb";
 }
+/** Rendered from seconds rather than rounded to minutes: parseDuration accepts
+ *  45s, and "1m" for a 45s limit misreports it. */
+function duration(seconds) {
+    return seconds % 3600 === 0
+        ? `${seconds / 3600}h`
+        : seconds % 60 === 0
+            ? `${seconds / 60}m`
+            : `${seconds}s`;
+}
 function recordHuman(record, color) {
     const paint = (value, code) => color ? `\u001b[${code}m${value}\u001b[0m` : value;
     const field = (label, value) => `  ${paint(label + ":", 90)} ${value}`;
@@ -54,13 +63,6 @@ function recordHuman(record, color) {
             : record.model_source === "config"
                 ? " (configured default)"
                 : ""}`));
-    // Rendered from seconds rather than rounded to minutes: parseDuration accepts
-    // 45s, and "1m" for a 45s limit misreports it.
-    const duration = (seconds) => seconds % 3600 === 0
-        ? `${seconds / 3600}h`
-        : seconds % 60 === 0
-            ? `${seconds / 60}m`
-            : `${seconds}s`;
     if (record.idle_timeout)
         lines.push(field("Idle timeout", duration(record.idle_timeout)));
     if (record.ttl)

package/dist/guard.js

@@ -265,17 +265,20 @@ export const DEFAULT_IDLE_TIMEOUT = 1800;
  * under `host = "pty"` in config and then never arm it.
  */
 export function resolveLifecycle(req, config, reapable) {
-    const one = (flag, configured, label, fallback) => {
+    const one = (flag, configured, label, configLabel, fallback) => {
         // `off` asks for nothing, so it is accepted even where a lifecycle cannot
         // be honoured: a wrapper that always passes it defensively must still be
         // able to launch a pty session.
         if (flag !== undefined && !reapable && flag.trim().toLowerCase() !== "off")
             throw new Error(`${label} applies to tmux sessions, which outlive the process that ` +
                 `launched them; this launch is ${req.kind === "task" ? "a task" : `hosted on ${req.host ?? "the configured host"}`}`);
+        // Each source names ITSELF in the error: a bad config value reported as
+        // "--idle-timeout must be ..." sends the reader looking for a flag they
+        // never typed.
         const chosen = flag !== undefined
             ? parseDuration(flag, label)
             : configured !== undefined
-                ? parseDuration(configured, label)
+                ? parseDuration(configured, configLabel)
                 : undefined;
         if (!reapable)
             return null;
@@ -284,8 +287,8 @@ export function resolveLifecycle(req, config, reapable) {
         return chosen === "off" ? null : chosen;
     };
     return {
-        idleTimeout: one(req.idleTimeout, config.session.idle_timeout, "--idle-timeout", DEFAULT_IDLE_TIMEOUT),
-        ttl: one(req.ttl, config.session.ttl, "--ttl", null),
+        idleTimeout: one(req.idleTimeout, config.session.idle_timeout, "--idle-timeout", "[session] idle_timeout", DEFAULT_IDLE_TIMEOUT),
+        ttl: one(req.ttl, config.session.ttl, "--ttl", "[session] ttl", null),
     };
 }
 export function runtimeArgs(req) {

package/dist/hosts/tmux.js

@@ -57,6 +57,19 @@ export function parseWindowList(output) {
         label: label.join(FIELD),
     }));
 }
+/**
+ * One shell command line for `run-shell`.
+ *
+ * Two escapes, not one. POSIX single-quoting keeps the shell from splitting an
+ * argument, and `#` is doubled because tmux expands the command as a FORMAT
+ * before any shell sees it: an unescaped `#{pane_pid}` inside a path is
+ * silently replaced, and quoting cannot prevent that.
+ */
+export function tmuxCommand(argv) {
+    return argv
+        .map((a) => `'${a.replaceAll("'", `'\\''`).replaceAll("#", "##")}'`)
+        .join(" ");
+}
 export class TmuxHost {
     server;
     id = "tmux";
@@ -86,6 +99,11 @@ export class TmuxHost {
     capabilities() {
         return { watchable: true, attachable: true, survivesParentExit: true };
     }
+    /** The tmux server this host talks to, so a caller needing it in an armed
+     *  command does not reach in with a structural cast. */
+    socketName() {
+        return this.server;
+    }
     /** Null when the window is gone — the caller stops rather than guesses. */
     async sessionState(hostRef) {
         try {
@@ -113,7 +131,7 @@ export class TmuxHost {
             "-b",
             "-d",
             String(Math.max(1, Math.round(seconds))),
-            argv.map((a) => `'${a.replaceAll("'", `'\\''`)}'`).join(" "),
+            tmuxCommand(argv),
         ]);
     }
     async launch(opts) {

package/dist/identity/claude.js

@@ -13,10 +13,73 @@ import { descendants } from "./processes.js";
  * reporting anything useful.
  */
 export function claudeSessionsDir(env) {
+    return join(claudeConfigDir(env), "sessions");
+}
+/** The configuration directory itself, which `claudeSessionsDir` and the
+ * workspace-trust read below both hang off. Split out so the two cannot drift:
+ * a trust decision read from a different directory than the one the launch
+ * records its session in would describe a profile nobody is launching. */
+export function claudeConfigDir(env) {
     const configured = env.CLAUDE_CONFIG_DIR;
     if (typeof configured === "string" && configured.length)
-        return join(configured, "sessions");
-    return join(env.HOME ?? homedir(), ".claude", "sessions");
+        return configured;
+    return join(env.HOME ?? homedir(), ".claude");
+}
+/**
+ * Whether Claude Code has recorded an accepted workspace-trust dialog for one
+ * directory, in the profile a launch would use. Trust is per-directory and is
+ * NOT inherited from a parent: a trusted `/Source/arm` says nothing about
+ * `/Source/arm/centrumx`, and the child still stops at the dialog.
+ *
+ * This only ever READS. Muster does not accept the dialog on the operator's
+ * behalf — `setWorkspaceTrust` writes that flag into an identity copy Muster
+ * itself created, never into the live `~/.claude.json`, and this must not
+ * become a way around that.
+ *
+ * Every failure answers `false`, because the only caller is a diagnostic on a
+ * launch that has already failed. A missing, unreadable or malformed file
+ * means Muster cannot say trust was accepted, which is exactly what `false`
+ * reports here; throwing would replace a useful message with a worse one.
+ */
+export async function claudeWorkspaceTrusted(env, cwd) {
+    let raw;
+    try {
+        raw = await readFile(join(claudeConfigDir(env), ".claude.json"), "utf8");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const data = JSON.parse(raw);
+        return data.projects?.[cwd]?.hasTrustDialogAccepted === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The message a Claude launch dies with when no session ever registered.
+ *
+ * A session sitting on a consent screen has no registry record at all, so the
+ * timeout looks identical to a hung or crashed launch. Several unrelated
+ * screens produce it — workspace trust, login, the first use of
+ * bypass-permissions mode — and the old message guessed at two of them
+ * together. Trust is the one Muster can actually check, so it is either named
+ * or ruled out; the rest are listed only once it has been ruled out.
+ *
+ * A `--kind task` launch into the same directory is the cheap discriminator:
+ * it runs headless and never sees the dialog, so it succeeds where a session
+ * hangs.
+ */
+export function claudeRegistryDiagnostic(trusted, cwd, configDir) {
+    if (!trusted)
+        return (`no Claude session registry found: workspace trust has not been ` +
+            `accepted for ${cwd} in ${configDir} — accept it once with ` +
+            `\`cd ${cwd} && claude\`, then retry (trust is per-directory and is ` +
+            `not inherited from a parent directory)`);
+    return (`no Claude session registry found (${cwd} is trusted, so check the ` +
+        `terminal for a login prompt, or for the one-time confirmation Claude ` +
+        `asks for the first time a profile uses bypass-permissions mode)`);
 }
 export async function resolveClaude(root, env, deadline) {
     const dir = claudeSessionsDir(env);

package/dist/reap.js

@@ -1,5 +1,8 @@
 import { Registry } from "./registry.js";
-const MIN_POLL = 30, MAX_POLL = 300;
+// The floor is low so a short limit is honoured rather than rounded up: a 45s
+// ttl behind a 30s floor fires at up to 75s. A session with a limit that short
+// does not live long enough for the extra polls to matter.
+const MIN_POLL = 5, MAX_POLL = 300;
 /**
  * Derived from the SHORTER active expiry: a 4h idle timeout paired with a 2m
  * ttl must not poll on the 4h scale, or the ttl overshoots by minutes.

package/dist/run.js

@@ -16,7 +16,7 @@ import { LaunchLog } from "./log.js";
 import { hosts, selectHost } from "./hosts/index.js";
 import { processRef, isSame, stopTree, delay, descendants, ownedGroup, } from "./identity/processes.js";
 import { resolveCodex } from "./identity/codex.js";
-import { resolveClaude } from "./identity/claude.js";
+import { claudeConfigDir, claudeRegistryDiagnostic, claudeWorkspaceTrusted, resolveClaude, } from "./identity/claude.js";
 import { openCodeEndpointOwnedBy, resolveOpenCode, } from "./identity/opencode.js";
 import { codexReachable, threadRejection } from "./reach/codex.js";
 import { claudeReachable } from "./reach/claude.js";
@@ -451,8 +451,8 @@ export class Muster {
             // armed before the window is recorded would poll a target the registry
             // cannot name. `schedule` is optional on the host interface, so pty and
             // macos-terminal opt out by not implementing it.
-            if (driver?.schedule && (lifecycle.idleTimeout ?? lifecycle.ttl))
-                await driver
+            if (driver?.schedule && (lifecycle.idleTimeout ?? lifecycle.ttl)) {
+                const armed = await driver
                     .schedule(pollInterval(lifecycle), [
                     process.execPath,
                     // ../dist/muster.js, not ./muster.js: this resolves from src/run.ts
@@ -463,17 +463,33 @@ export class Muster {
                     "--home",
                     this.home,
                     "--socket",
-                    driver.server ?? "muster",
+                    driver.socketName?.() ?? "muster",
                     entry.launchId,
                 ])
-                    // A lifecycle that cannot be armed must not fail the launch: the
-                    // session is up and usable, and the orphan risk is what we had before.
-                    .catch(() => { });
+                    .then(() => true, () => false);
+                // A lifecycle that could not be armed must not fail the launch — the
+                // session is up and usable, and the orphan risk is what we had before.
+                // But it must not be REPORTED either: a record promising an expiry
+                // nothing will honour is worse than one promising none, because there
+                // is no way to tell from the outside.
+                if (!armed) {
+                    lifecycle.idleTimeout = null;
+                    lifecycle.ttl = null;
+                    entry = await this.registry.update(entry.launchId, {
+                        idleTimeout: null,
+                        ttl: null,
+                    });
+                }
+            }
             let diagnostic = req.runtime === "claude"
                 ? "no Claude session registry found (check terminal for workspace trust or login prompts)"
                 : req.runtime === "opencode"
                     ? "no OpenCode session matched the launch endpoint, cwd, and creation window"
                     : "no descendant runtime identity found";
+            // Kept so the throw below can tell "nothing ever registered" from a
+            // diagnosis the loop actually earned. Only the first case can be about a
+            // consent screen; anything later means a session existed.
+            const neverRegistered = diagnostic;
             // `resolveEnv`, not `hostEnv`: this connection is how the thread
             // `resolveCodex` found gets READ — both its `rejectionOf` screen, where a
             // non-null answer is fatal, and `codexReachable` at readiness. An
@@ -608,6 +624,13 @@ export class Muster {
                 }
                 await delay(Math.min(250, Math.max(0, deadline - Date.now())));
             }
+            // Resolved here rather than before the launch: this reads the operator's
+            // live `.claude.json`, and a launch that is going to work should not pay
+            // for it. Failing closed is also wrong before a launch — `--kind task`
+            // runs headless and never sees the dialog, so refusing an untrusted
+            // directory up front would break task launches that work today.
+            if (req.runtime === "claude" && diagnostic === neverRegistered)
+                diagnostic = claudeRegistryDiagnostic(await claudeWorkspaceTrusted(resolveEnv, req.cwd), req.cwd, claudeConfigDir(resolveEnv));
             throw new Error(`${diagnostic} after ${this.config.launch_timeout_sec}s`);
         }
         catch (e) {

package/package.json

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