@brutalsystems/muster 0.7.5 → 0.7.7

package/README.md

@@ -37,6 +37,15 @@ Updating on disk is not enough; restart the session too.
 
 ## Build and run locally
 
+`npm run check` is the local gate: it builds, runs the suite, then packs and
+verifies the tarball — the same `scripts/check-tarball.mjs` the CI packing job
+runs, so the two cannot disagree about what "verified" means. `npm test` alone
+does not pack anything, so tarball drift is green locally and red on push.
+
+It is not everything CI does: CI additionally runs the suite across the Node
+version matrix, and the contract suite runs only on release. Passing `check` is
+necessary rather than sufficient.
+
 Requires Node 22.12+ (tested with 24.16), TypeScript 5, Codex 0.155.1, Claude
 Code 2.1.267, and OpenCode 1.18.31 or newer. Newer OpenCode releases must retain
 the CLI and loopback HTTP API used by Muster. Terminal drivers use tmux or
@@ -72,7 +81,8 @@ emit JSON; `output` prints the captured task output. `stop` also accepts an
 unambiguous peer name or canonical address, refusing ambiguity with candidates.
 Use the durable ID to stop a session whose runtime has renamed it.
 
-For readable terminal output, add `--format human` to `run`, `list`, or `stop`:
+For readable terminal output, add `--format human` to `run`, `list`, `stop`, or
+`doctor`:
 
 ```sh
 muster run codex --prompt 'Review this project' --format human
@@ -321,9 +331,35 @@ npm = "@brutalsystems/tincan-opencode"
 path = "~/.config/opencode/plugin/local-thing.ts"
 ```
 
-Prefer `npm` where the plugin is published. A copied file goes stale in
-silence — the package updates, the copy does not, and the old code keeps
-running against whatever it was built for. A specifier has no copy to go stale.
+Prefer `npm` where the plugin is published — but not because it avoids a stale
+copy. Both routes keep one. A copied file goes stale in silence: the package
+updates, the copy does not, and the old code keeps running against whatever it
+was built for. A specifier keeps its copy somewhere less obvious. OpenCode
+resolves the specifier once, writes a generated `package.json` pinning the
+resolved version alongside a lockfile, and caches that under the range it was
+asked for:
+
+```sh
+~/.cache/opencode/packages/@brutalsystems/tincan-opencode@latest
+```
+
+Publishing a new version does not change that directory and nothing warns, so
+the stale plugin keeps running and keeps reporting. Deleting it forces
+re-resolution on the next launch:
+
+```sh
+rm -rf ~/.cache/opencode/packages/@brutalsystems/tincan-opencode@latest
+```
+
+Muster passes the specifier through untouched, so pin a version where the
+staleness should be deliberate and visible in config rather than implicit in a
+cache. OpenCode keys a pinned specifier to its own directory, leaving the
+`@latest` copy alone:
+
+```toml
+[plugins.tincan]
+npm = "@brutalsystems/tincan-opencode@0.7.1"
+```
 
 A specifier needs the package to declare an entry point OpenCode's loader
 actually reads. It looks for `exports["./server"]` and falls back to `main`; it
@@ -332,16 +368,45 @@ its `package.json` is read, the session runs — and the plugin never executes,
 with nothing logged. If a specifier-named plugin appears to do nothing, check
 the package's entry points before looking anywhere else.
 
-Either way, confirm what a session actually loaded. It records the version, so
-compare that against what is installed:
+Either way, confirm what is actually loaded. `muster doctor` checks every
+path-configured plugin against the package it came from:
+
+```sh
+muster doctor --format human
+```
+
+```
+tincan @brutalsystems/tincan-opencode
+  Status: stale — copy predates 0.7.2, published 2026-09-21
+  Path: /Users/you/.config/opencode/plugin/tincan.ts
+
+1 stale plugin. Replace path with npm = "@brutalsystems/tincan-opencode" in [plugins.tincan], or re-copy the file.
+```
+
+The copied file carries no version of its own, so the check compares its mtime
+against the registry's publish time for the current release. That means a file
+re-copied recently reads as current even when its contents are old: doctor
+under-reports and never cries wolf. It exits 1 when anything is stale, and an
+unreachable registry is reported as such rather than failing the command.
+
+Muster knows the packages for the plugins it ships with. Name anything else,
+or override the default, with `published`:
+
+```toml
+[plugins.mine]
+path = "~/src/mine.ts"
+published = "@acme/mine-opencode"
+```
+
+Plugins named by `npm` are not checked: they keep no copy of their own, and
+clearing OpenCode's cache above is that remedy instead. For what a running
+session loaded rather than what is on disk, the records still carry the version:
 
 ```sh
 grep plugin_version ~/.tincan/peers/opencode/ses_*.json
 tincan --version
 ```
 
-Nothing else surfaces the difference.
-
 Registering Muster itself is the one case to think twice about. A definition
 whose command runs `muster mcp` gives every session that selects it `run`,
 `list`, `stop` and `output` — launch authority, held by an agent rather than by
@@ -391,10 +456,11 @@ built-in list is fixed, so a tool added by a future OpenCode release would not
 be denied by it; launches that select no MCP server keep the wildcard. With no plugins
 selected it also uses `--pure` and pins an empty plugin list, so inherited
 plugins do not enter the child process. Selecting a plugin with `--plugin`
-necessarily relaxes that: OpenCode merges project-local `.opencode/plugin`
-discovery into any non-empty plugin list, so the child also loads whatever
-plugins the target repository ships. Select plugins only for repositories
-trusted with that.
+necessarily relaxes that: OpenCode merges project-local plugin discovery into
+any non-empty plugin list, so the child also loads whatever plugins the target
+repository ships. It globs both spellings — `.opencode/plugin` and
+`.opencode/plugins` — so auditing only one of them misses half of what a
+repository can load. Select plugins only for repositories trusted with that.
 Claude connection specifications are stored with owner-only permissions under
 `~/.muster/mcp`, removed on stop, task completion, or when `list` observes an ended
 session. MCP server access is separate from filesystem sandbox permissions: a

package/dist/doctor.js

@@ -0,0 +1,77 @@
+import { stat } from "node:fs/promises";
+import { pluginPath, publishedPackage } from "./plugins.js";
+export async function checkPlugins(config, lookup) {
+    const plugins = [];
+    for (const [name, definition] of Object.entries(config.plugins)) {
+        // An npm-configured plugin has no copy of its own to go stale; OpenCode's
+        // package cache is the thing that pins it, and clearing that is a
+        // different remedy. README covers it.
+        if ("npm" in definition)
+            continue;
+        const path = pluginPath(definition.path);
+        const health = {
+            name,
+            path,
+            package: publishedPackage(name, definition),
+            status: "unchecked",
+        };
+        let mtime;
+        try {
+            mtime = (await stat(path)).mtime;
+        }
+        catch {
+            plugins.push({ ...health, status: "missing" });
+            continue;
+        }
+        health.local_mtime = mtime.toISOString();
+        if (!health.package) {
+            plugins.push(health);
+            continue;
+        }
+        let latest;
+        try {
+            latest = await lookup(health.package);
+        }
+        catch {
+            // An unreachable registry proves nothing about the copy. Reporting it as
+            // stale would cry wolf on a plane; reporting it as current would hide a
+            // real one.
+            plugins.push({ ...health, status: "unreachable" });
+            continue;
+        }
+        if (!latest) {
+            plugins.push({ ...health, status: "unpublished" });
+            continue;
+        }
+        plugins.push({
+            ...health,
+            published_version: latest.version,
+            published_at: latest.published,
+            status: mtime < new Date(latest.published) ? "stale" : "current",
+        });
+    }
+    return {
+        kind: "doctor",
+        plugins,
+        stale: plugins.filter((p) => p.status === "stale").length,
+    };
+}
+/**
+ * The full packument rather than the abbreviated one: `time` carries the
+ * publish dates and the abbreviated form omits it.
+ */
+export function npmRegistry(timeoutMs = 3000) {
+    return async (pkg) => {
+        const response = await fetch("https://registry.npmjs.org/" + pkg.replace("/", "%2F"), { signal: AbortSignal.timeout(timeoutMs) });
+        if (response.status === 404)
+            return null;
+        if (!response.ok)
+            throw new Error(`registry returned ${response.status} for ${pkg}`);
+        const body = (await response.json());
+        const version = body["dist-tags"]?.latest;
+        const published = version ? body.time?.[version] : undefined;
+        if (!version || !published)
+            throw new Error(`registry gave no current release for ${pkg}`);
+        return { version, published };
+    };
+}

package/dist/format.js

@@ -65,7 +65,35 @@ function recordHuman(record, color) {
         lines.push(field("Stop", paint(`muster stop ${argument(clean(id))}`, 36)));
     return lines.join("\n");
 }
+function doctorHuman(report, color) {
+    const paint = (value, code) => color ? `\u001b[${code}m${value}\u001b[0m` : value;
+    const field = (label, value) => `  ${paint(label + ":", 90)} ${value}`;
+    if (!report.plugins.length)
+        return "No path-configured plugins to check.\n";
+    const lines = [];
+    for (const plugin of report.plugins) {
+        const released = plugin.published_version ?? "?";
+        const when = (plugin.published_at ?? "").slice(0, 10);
+        const detail = {
+            stale: `copy predates ${released}, published ${when}`,
+            current: `copy is newer than ${released}`,
+            unpublished: "no such package on the registry",
+            unchecked: 'no package known; add published = "@scope/name"',
+            unreachable: "registry lookup failed; nothing proven either way",
+            missing: "no file at that path",
+        };
+        const code = plugin.status === "stale" ? 31 : plugin.status === "current" ? 32 : 33;
+        lines.push(`${paint(clean(plugin.name), 1)} ${clean(plugin.package ?? "-")}`, field("Status", `${paint(plugin.status, code)} \u2014 ${detail[plugin.status] ?? ""}`), field("Path", clean(plugin.path)));
+    }
+    const stale = report.plugins.filter((p) => p.status === "stale");
+    lines.push("", stale.length
+        ? `${stale.length} stale plugin${stale.length > 1 ? "s" : ""}. Replace path with npm = "${stale[0].package}" in [plugins.${stale[0].name}], or re-copy the file.`
+        : "No stale plugins.");
+    return lines.join("\n") + "\n";
+}
 export function formatHuman(value, color = false) {
+    if (!Array.isArray(value) && value.kind === "doctor")
+        return doctorHuman(value, color);
     if (Array.isArray(value))
         return value.length
             ? value.map((record) => recordHuman(record, color)).join("\n\n") + "\n"

package/dist/identity/codex.js

@@ -6,7 +6,6 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { command, descendants } from "./processes.js";
 export async function resolveCodex(root, env, deadline, isDirectCli) {
-    const family = new Set(await descendants(root, deadline));
     let dir = join(env.CODEX_HOME ?? join(env.HOME ?? homedir(), ".codex"), "thread-writer-locks");
     try {
         dir = await realpath(dir);
@@ -35,6 +34,9 @@ export async function resolveCodex(root, env, deadline, isDirectCli) {
     catch (e) {
         out = e.stdout ?? "";
     }
+    // Snapshot the family after lsof, not before: a lock holder that spawns
+    // during discovery is absent from an earlier snapshot, costing a whole pass.
+    const family = new Set(await descendants(root, deadline));
     let pid = 0;
     const matches = new Map();
     for (const line of out.split("\n")) {

package/dist/muster.js

@@ -9,6 +9,8 @@ import { Muster } from "./run.js";
 import { runSchema } from "./guard.js";
 import { delay } from "./identity/processes.js";
 import { formatHuman, humanColorEnabled } from "./format.js";
+import { checkPlugins, npmRegistry } from "./doctor.js";
+import { loadConfig } from "./config.js";
 const listSchema = z
     .object({ kind: z.enum(["session", "task"]).optional() })
     .strict();
@@ -19,6 +21,7 @@ const help = `Usage:
   muster list [--kind session|task] [--format json|human]
   muster stop <id> [--format json|human]
   muster output <id>
+  muster doctor [--format json|human]
   muster mcp
   muster --version
 
@@ -36,6 +39,12 @@ which also admits any plugin the target repository ships.
 the child, so launches do not depend on the user's own OpenCode config.
 run, list and stop default to JSON. output prints raw task text.
 
+doctor checks path-configured plugins against the packages they came from: a
+copied file goes stale silently while the package moves on. It reads the copy's
+mtime, so a re-copied old file reads as current. Exits 1 when any plugin is
+stale. Plugins named by npm are not checked — OpenCode caches those instead,
+and the README covers clearing that cache.
+
 pty launches print their record and keep this process running. Ctrl-C stops the
 owned pty session. tmux launches survive this process exiting.
 MCP: install deliberately in the one authorized session, never at user scope.
@@ -246,6 +255,14 @@ async function main() {
                 throw new Error("list takes no positional arguments");
             print(await muster.list(listSchema.parse(values).kind));
         }
+        else if (command === "doctor") {
+            if (positionals.length || Object.keys(values).length)
+                throw new Error("doctor takes no arguments");
+            const report = await checkPlugins(await loadConfig(), npmRegistry());
+            print(report);
+            if (report.stale)
+                process.exitCode = 1;
+        }
         else if (command === "stop" || command === "output") {
             if (positionals.length !== 1 || Object.keys(values).length)
                 throw new Error(`${command} requires exactly one id`);

package/dist/plugins.js

@@ -9,26 +9,55 @@ export const pluginName = z.string().regex(/^[a-zA-Z0-9_-]+$/);
  * file URL, while a specifier must be passed through untouched so OpenCode can
  * resolve and install it.
  *
- * The specifier form exists because a copied-on-disk plugin goes stale
- * silently: an old copy keeps running against whatever it was built for, and
- * an unloaded or outdated plugin is indistinguishable from no plugin at all.
+ * Neither form escapes staleness. A copied file goes stale on disk; a specifier
+ * goes stale in OpenCode's package cache, which resolves the range once and
+ * keeps serving that copy. A version can be pinned in the specifier where the
+ * staleness should be deliberate, since it is passed through untouched. Either
+ * way, an outdated plugin is indistinguishable from no plugin at all.
  */
-export const pluginSchema = z
-    .union([
-    z.object({ path: z.string().min(1) }).strict(),
+export const pluginSchema = z.union([
+    z
+        .object({
+        path: z.string().min(1),
+        // Names the published package a copied file came from, so `muster doctor`
+        // can check it. Meaningless alongside `npm`, which strict() rejects.
+        published: z.string().min(1).optional(),
+    })
+        .strict(),
     z.object({ npm: z.string().min(1) }).strict(),
-])
-    .refine((p) => "path" in p || "npm" in p, "a plugin needs either path or npm");
+], 
+// The union rejects a plugin carrying neither key before a refinement could
+// run, so the message belongs here: attached to the union it never fired,
+// and the operator saw "Invalid input" instead.
+{ errorMap: () => ({ message: "a plugin needs either path or npm" }) });
 /**
  * Operator definitions are written as ordinary paths, so `~` and relative
  * paths resolve here rather than in the launch path, where a wrong answer
  * would be harder to see.
  */
-function pluginUrl(path) {
+export function pluginPath(path) {
     const expanded = path.startsWith("~/")
         ? join(homedir(), path.slice(2))
         : path;
-    return pathToFileURL(resolve(expanded)).href;
+    return resolve(expanded);
+}
+function pluginUrl(path) {
+    return pathToFileURL(pluginPath(path)).href;
+}
+/**
+ * Packages Muster already knows are published, so a path-configured copy can be
+ * checked without the operator naming it. Keyed by the plugin's config name; a
+ * section named anything else needs an explicit `published`.
+ */
+const publishedPlugins = {
+    tincan: "@brutalsystems/tincan-opencode",
+    birddog: "@brutalsystems/birddog-opencode",
+};
+/** The package a path-configured plugin came from, or null if unknowable. */
+export function publishedPackage(name, plugin) {
+    if ("npm" in plugin)
+        return null;
+    return plugin.published ?? publishedPlugins[name] ?? null;
 }
 export function selectPlugins(req, config) {
     // Personal defaults apply to sessions, not unattended one-shot tasks —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {
@@ -12,6 +12,7 @@
   "scripts": {
     "build": "tsc && node scripts/prepare-bin.mjs",
     "test": "vitest run",
+    "check": "npm test && node scripts/check-tarball.mjs",
     "test:contract": "MUSTER_CONTRACT=1 vitest run test/contract.test.ts",
     "postinstall": "node scripts/prepare-pty.mjs",
     "pretest": "npm run build",