@brutalsystems/muster 0.9.1 → 0.10.0

package/CANONICAL_ID.md

@@ -1,6 +1,6 @@
 # Tin Can — Address Format
 
-> **Normative for `@brutalsystems/tincan` 1.6.0.**
+> **Normative for `@brutalsystems/tincan` 1.9.2.**
 >
 > This describes what Tin Can does today, precisely enough for another tool to
 > produce addresses Tin Can will resolve. It is a write-down of shipped
@@ -140,6 +140,18 @@ The separator is `.` so that an address needs no shell quoting.
 `canonical_id` is always fully qualified, whether or not there is a collision.
 It is the form to record in logs and to pass between tools.
 
+**Do not recover the suffix from a canonical id by string surgery.** Taking the
+last dot-separated segment gave the three-character suffix before 1.0.0 and
+gives the whole durable id now — `01a0b9b4-a33e-7ab1-80a0-bb715504a0fb`, not
+`0fb`. A reimplementation that does this builds qualified addresses that look
+right and match nothing, and the failure surfaces as `unknown`, which names a
+missing peer rather than a malformed address. Reported by muster, where it made
+every `slug.suffix` address fail silently until a test was written for it.
+
+Derive the suffix from the **uuid**, with `suffixOf` — the last three hex
+characters of the id with non-hex removed. The canonical form is an address to
+pass along whole, not a record to parse fields out of.
+
 ## Collision
 
 A peer is suffixed in its **display** form when either:

package/CONTRACT_PROVENANCE.md

@@ -370,3 +370,114 @@ rule it documents — refuse a prefix that ends at a segment boundary — fails
 new case *and* `resolve: unambiguous prefix resolves` together, in this copy.
 That pair failing together is the argument for Tin Can's decision to document
 the defect rather than change resolution, and it reproduces here.
+
+## Re-sync to Tin Can 1.7.0 — 2026-09-24
+
+The copies are now from tag `v1.7.0`, commit
+`f2aaeb20ea278c229afe955db59f69301fc6626f`.
+
+| File | SHA-256 |
+| --- | --- |
+| `CANONICAL_ID.md` | `8d5e93894e5c43cc854330f7b64ebbdcc450649cfa910c8b4015edf2559125e7` |
+| `test/fixtures/canonical-id.json` | `1db118b22484271932e7cde33c1c80b469563f18f2961532d6910d79ce1e4c3b` |
+
+`tincan_version: 1.7.0`, still 40 cases: 8 slugify, 7 suffix, 12 assignment, 13
+resolution. **No expected value moved and no case was added.** Diffed
+`v1.6.0..v1.7.0` upstream before copying: `src/naming.ts` does not appear in the
+diff at all, the fixture's only changed line is its `tincan_version`, and
+`CANONICAL_ID.md` gains fourteen lines of warning with no normative change. So
+`naming.ts` is untouched here and the contract suite is expected to stay 4/4
+without it — this is a re-label plus a doc, not an address-format change.
+
+What the doc gains is the hazard this repo hit and reported: recovering the
+three-hex suffix by taking a canonical id's last dot-separated segment returned
+the suffix before 1.0.0 and returns the whole uuid now, so every qualified
+`slug.suffix` address resolves as `unknown` — a missing peer, not a malformed
+address, which is why it stayed quiet here until a test was written for it.
+Tin Can names Muster as where it was found. The rule is to derive the suffix
+from the uuid via `suffixOf` and otherwise pass a canonical id along whole
+rather than parse fields out of it.
+
+**A re-sync touches three sites, not two.** Both Tin Can pins —
+`RELEASING.md` and `.github/workflows/publish.yml` — plus the SHA-256 drift
+hashes in `test/naming.test.ts` ("contract copies remain frozen"), which must
+move whenever a copied file changes. The two pins are the ones handed down in
+conversation; the hashes were found by grepping for the old version and the old
+digests rather than by working from that list, so grep the repo instead of
+trusting an enumeration. That advice earned itself twice over: this very
+enumeration missed `README.md`, which carried a literal baseline of its own —
+recorded below.
+
+Moving only the first pin is what made v0.9.0 an inert tag that published
+nothing. `test/workflow-npm-pin.test.ts` now fails when the two pins disagree,
+or when the `publish.yml` pin and the fixture's `tincan_version` disagree, and
+that guard was re-confirmed by mutation here rather than assumed: reverting
+`publish.yml` alone to 1.6.0 fails both assertions, and restoring it passes
+them. A stale drift hash fails `npm run check` on its own.
+
+### The pin sites became one derived value
+
+Recording the fix rather than only the incident. The two Tin Can pins no longer
+restate a version; both compute it from this fixture's `tincan_version`. That
+field is the single place saying which Tin Can the vendored copies describe, so
+a pin can no longer lag it — the v0.9.0 failure class is closed structurally
+instead of guarded after the fact.
+
+The guard that replaced the old agreement tests asserts the derivation
+expression itself, not the word `tincan_version`. The first version of it
+checked for the word and **passed against a `publish.yml` whose command had
+been mutated to `ver="1.6.0"`**, because the prose explaining the derivation
+contains that word too. It was caught by running the mutation rather than by
+reading the test. A guard that cannot fail is the thing this document exists to
+prevent, so the failure is written down next to the fix.
+
+### README.md was a fourth site, and had already gone stale
+
+The enumeration above missed it. `README.md`'s Verification section named its own
+baseline — **Tin Can 0.6.4** in prose, and `@brutalsystems/tincan@0.6.4` in a
+copy-paste command — and had drifted unnoticed while the vendored copies moved to
+1.6.0 and then 1.9.2. Nothing failed, because it gates nothing: it is
+instructions for a human, so the cost was silence rather than an inert tag.
+
+That makes it worse than a failing pin, not better. Anyone following the README
+installed a Tin Can four minors behind the one the fixture describes and watched
+the contract suite pass 4/4 — which reads as confirmation that the contract holds
+at a version nobody vendored.
+
+Fixed the same way as the other two sites: the command derives `ver` from the
+fixture, and the prose points at `tincan_version` rather than naming a release.
+`test/workflow-npm-pin.test.ts` now includes `README.md` in the derivation loop,
+and adds one assertion that its Verification section names no Tin Can version in
+prose at all, because prose restates a pin as easily as a command does. Both were
+watched failing against the stale README before anything was changed — the
+literal-pin assertion on the command, and `expected 'Tin Can 0.6.4' to be
+undefined` on the prose — and the derived command was then extracted from the
+README and run end to end, installing 1.9.2 and passing the contract suite 4/4.
+
+The prose assertion is scoped to `## Verification` on purpose. Elsewhere the
+README records what was observed at a particular Tin Can — "Tin Can 0.6.0
+delivers over v1, so nothing here depends on the v2 path" — which is a historical
+claim and stays pinned to its version deliberately. A whole-file regex would fail
+on those and teach the next person to delete the guard.
+
+## Re-sync to Tin Can 1.9.2 — 2026-09-25
+
+Copies are from tag `v1.9.2`.
+
+| File | SHA-256 |
+| --- | --- |
+| `CANONICAL_ID.md` | `6e0dde03154956a480ae59f4d31b727ecc5a9e735c185fed6e4445f2574263a9` |
+| `test/fixtures/canonical-id.json` | `b91406e068f6bec18629a4d2b9e91bc4d2e5a0487e4b6b4534fd5ba37c7f617a` |
+
+`tincan_version: 1.9.2`, still 40 cases. Diffing `v1.7.0..v1.9.2` upstream, the
+ONLY change across all three contract files is the version string in two lines —
+`naming.ts` does not appear, and no fixture case or expected value moved. 1.8.0
+(log chaining, arrival record), 1.9.0 (version reporting in `peers`), 1.9.1 and
+1.9.2 (registration drift) do not touch the address format. Verified here rather
+than taken from upstream's word: they explicitly said not to treat their summary
+as a re-copy signal.
+
+**This re-sync needed no pin edit.** The pins derive from `tincan_version`, so
+updating the fixture moved CI on its own — the first cut where the failure class
+that produced v0.9.0 had nothing to act on. The drift hashes still moved, which
+is the third site behaving exactly as documented above.

package/README.md

@@ -492,6 +492,30 @@ Every launch also records how strongly its containment was imposed:
 | `tool-policy` | OpenCode — rules the agent is asked to respect, with no kernel enforcement. |
 | `none`        | `full-access` — the sandbox is deliberately disabled.                       |
 
+#### What a sandboxed launch may write
+
+Muster names the write roots rather than leaving them to default. Under
+`workspace-write` a launched Claude session may write its cwd, `$TMPDIR`, and
+**its own configuration directory** — the `CLAUDE_CONFIG_DIR` the child will
+actually use, which an identity launch or a requester profile's `env_defaults`
+may relocate. That last root is granted because an agent's memory lives there:
+without it every Bash write to memory failed with `EPERM` while the in-process
+file tools succeeded, which reads from inside the session as a path bug rather
+than a boundary.
+
+Under `read` nothing is writable, including the config dir. Under `full-access`
+there is no sandbox to grant into.
+
+One path stays denied that muster cannot open: **`$CLAUDE_CONFIG_DIR/projects/`**
+(and `shell-snapshots/`). Claude Code refuses writes there in a sandboxed Bash
+regardless of what muster grants — naming those directories explicitly in
+`allowWrite` changes nothing, which is presumably deliberate, since a session's
+own transcripts live there. Project-scoped memory under
+`projects/<cwd-slug>/memory` is therefore reachable only through the file tools,
+which are in-process and not kernel-sandboxed. Note that `work` implies auto
+mode, which asks the model to prefer shell commands for file edits, so a session
+saving project-scoped memory has to be told to use `Write`/`Edit` instead.
+
 ### Requester profiles and enrolments
 
 A non-local caller — one reached through a transport such as Tin Can rather
@@ -1024,19 +1048,25 @@ The ordinary suite requires tmux, node-pty, POSIX `ps`/`lsof`, and Python 3 for
 real file locks in the fake Codex executable. It uses isolated runtime homes and
 no model APIs. It skips the four explicitly invoked compatibility cases.
 
-The verified contract baseline is **Tin Can 0.6.4**. The suite spawns an installed binary as an MCP
-subprocess, compares durable IDs, and verifies delivery to fake runtimes through
-both terminal hosts. A missing binary or missing durable field fails the test.
-For reproducible verification, install that exact release outside Muster:
+The verified contract baseline is the Tin Can named by `tincan_version` in the
+frozen fixture, `test/fixtures/canonical-id.json`. That field is the single place
+recording which release the vendored copies describe, and both `RELEASING.md` and
+`publish.yml` derive their pin from it. The suite spawns an installed binary as
+an MCP subprocess, compares durable IDs, and verifies delivery to fake runtimes
+through both terminal hosts. A missing binary or missing durable field fails the
+test. For reproducible verification, install that exact release outside Muster —
+derived here too, rather than typed, so this command cannot name a release the
+fixture has moved past:
 
 ```sh
 contract_dir=$(mktemp -d)
-npm install --prefix "$contract_dir" --no-save @brutalsystems/tincan@0.6.4
+ver=$(node -p "require('./test/fixtures/canonical-id.json').tincan_version")
+npm install --prefix "$contract_dir" --no-save "@brutalsystems/tincan@$ver"
 MUSTER_TINCAN_BIN="$contract_dir/node_modules/.bin/tincan" npm run test:contract
 ```
 
-Verification uses the published 0.6.4 release installed in an isolated
-temporary directory. No Tin Can source edits are made.
+Verification uses that published release installed in an isolated temporary
+directory. No Tin Can source edits are made.
 Fixture version metadata alone does not indicate address-format drift: compare
 the case arrays. Those arrays cover naming only, not peer-list membership or
 state semantics. Upgrades require separate compatibility verification; passing

package/dist/guard.js

@@ -1,7 +1,9 @@
 import { z } from "zod";
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { realpath } from "node:fs/promises";
-import { isAbsolute, relative, resolve } from "node:path";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { mcpName, claudeMcpConfig } from "./mcp.js";
 import { pluginName } from "./plugins.js";
 import { RequesterConfigError } from "./requester-policy.js";
@@ -316,7 +318,47 @@ export function runtimeArgs(req) {
     }
     return result;
 }
-export function launchArgs(req, config, mcp = [], bridgePath) {
+/**
+ * The config dir the launched agent will actually use. `launchEnv`'s blocklist
+ * is /^(CLAUDECODE|CLAUDE_CODE_|...)/, which does not match CLAUDE_CONFIG_DIR,
+ * so the child inherits whatever the caller set and this resolves to the same
+ * dir the child will open.
+ */
+export function claudeConfigDir(env) {
+    const configured = env.CLAUDE_CONFIG_DIR;
+    if (configured && configured.trim().length > 0)
+        return resolve(configured);
+    return join(env.HOME ?? homedir(), ".claude");
+}
+/**
+ * The keys of a profile's own settings.json that name its skill set rather than
+ * its policy. `--setting-sources ""` is what keeps `permissions`, `sandbox` and
+ * `hooks` muster's alone — forwarding those would let a settings file re-widen
+ * what `assertClaudePolicy` refuses to take on trust — so only these two are
+ * carried across, and muster's keys are spread after them and win regardless.
+ */
+const forwardedSettings = ["enabledPlugins", "extraKnownMarketplaces"];
+function profilePluginSettings(configDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(configDir, "settings.json"), "utf8"));
+    }
+    catch {
+        // No settings file, unreadable, or not JSON: a launch with built-in skills
+        // only is degraded but correct, and failing here would take the sandbox fix
+        // down with it.
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return {};
+    const source = parsed;
+    const out = {};
+    for (const key of forwardedSettings)
+        if (source[key] !== undefined)
+            out[key] = source[key];
+    return out;
+}
+export function launchArgs(req, config, mcp = [], bridgePath, env = process.env) {
     // Before `runtimeArgs`, so this function owns every model error on its own
     // rather than by its caller's discipline: `Muster.launch` happens to resolve
     // first, but `launchArgs` is exported and an input carrying both a model
@@ -357,7 +399,9 @@ export function launchArgs(req, config, mcp = [], bridgePath) {
         : policy.permissions === "bypass"
             ? "bypassPermissions"
             : "dontAsk";
+    const configDir = claudeConfigDir(env);
     const settings = {
+        ...profilePluginSettings(configDir),
         disableAllHooks: true,
         permissions: {
             defaultMode: mode,
@@ -374,7 +418,17 @@ export function launchArgs(req, config, mcp = [], bridgePath) {
             autoAllowBashIfSandboxed: true,
             allowUnsandboxedCommands: false,
             excludedCommands: [],
-            filesystem: { denyWrite: readonly ? ["/"] : [] },
+            filesystem: {
+                denyWrite: readonly ? ["/"] : [],
+                // The agent's own memory lives under the config dir, outside the cwd
+                // that Claude Code defaults the write root to, so Bash writes to it
+                // failed with EPERM while the in-process file tools succeeded (#80).
+                // Granted only under workspace-write: read-only must stay read-only,
+                // and full-access has no sandbox to grant into.
+                ...(policy.sandbox === "workspace-write"
+                    ? { allowWrite: [configDir] }
+                    : {}),
+            },
         },
     };
     return [

package/dist/run.js

@@ -240,7 +240,7 @@ export class Muster {
         if (req.runtime === "opencode")
             runtimeArgs(effective);
         else
-            argv = launchArgs(effective, this.config);
+            argv = launchArgs(effective, this.config, [], undefined, this.sourceEnv);
         const driver = req.kind === "session"
             ? await selectHost(req.open ? "tmux" : requestedHost, this.drivers)
             : undefined;
@@ -389,7 +389,10 @@ export class Muster {
                 await writeFile(bridgePath, JSON.stringify(Object.fromEntries(prepared.servers.map((s) => [s.name, s.config]))), { mode: 0o600 });
             }
             if (req.runtime !== "opencode")
-                argv = launchArgs(effective, this.config, prepared.servers, bridgePath);
+                // `runtimeEnv`, not the host's: an identity launch relocates
+                // CLAUDE_CONFIG_DIR to the per-launch copy, and the sandbox must grant
+                // the dir the child will actually open, not the one Muster runs under.
+                argv = launchArgs(effective, this.config, prepared.servers, bridgePath, runtimeEnv);
             if (req.runtime === "codex") {
                 codexPolicy = await codexPolicyArgs(runtimeEnv, req.cwd, deadline, prepared.servers, req.kind === "task");
                 argv.splice(1, 0, ...codexPolicy);

package/package.json

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

package/test/fixtures/canonical-id.json

@@ -1,6 +1,6 @@
 {
   "$comment": "FROZEN. Describes @brutalsystems/tincan address behaviour as shipped. Adding cases is fine; changing an expected value means the address format changed - see CANONICAL_ID.md, 'Changing this format'.",
-  "tincan_version": "1.6.0",
+  "tincan_version": "1.9.2",
   "spec": "CANONICAL_ID.md",
   "slugify": [
     {