@brutalsystems/muster 0.1.0

package/CANONICAL_ID.md

@@ -0,0 +1,168 @@
+# Tin Can — Address Format
+
+> **Normative for `@brutalsystems/tincan` 0.1.0.**
+>
+> 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
+> behaviour, not a design. Where the behaviour is wrong, it is marked **Known
+> defect** and preserved anyway — see [Known defects](#known-defects).
+>
+> The executable form is [`test/fixtures/canonical-id.json`](test/fixtures/canonical-id.json),
+> asserted by `test/canonical-id.test.ts`. Copy that fixture rather than
+> reimplementing from prose.
+>
+> **The implementation is authoritative.** If this document and Tin Can
+> disagree, Tin Can is right and this document has a bug. The fixture is the
+> regression net that keeps them together.
+
+## The pieces
+
+An address is built from two inputs:
+
+| Runtime | Name source | Id source |
+|---|---|---|
+| `codex` | thread title, or absent | `thread_id` |
+| `claude-code` | session name from the registry | `session_id` |
+
+Neither name is guaranteed unique, and neither is stable: **a name belongs to a
+process and dies with it.** Key durable records on the id, never on the address.
+
+## Slugify
+
+Applied to the runtime-supplied name.
+
+1. Lowercase the whole string.
+2. Replace every run of characters outside `[a-z0-9]` with a single `-`.
+3. Strip leading and trailing `-`.
+
+Consequences worth stating, because they are easy to get wrong:
+
+- **Non-ASCII is a separator, not transliterated.** `café ☕ time` → `caf-time`.
+- Runs collapse: `auth/refactor (v2)` → `auth-refactor-v2`.
+- Digits survive: `123` → `123`.
+- **The result may be empty.** `???` → `""`, `""` → `""`.
+
+An empty slug is replaced by the literal `thread`. This applies both to a peer
+with no name at all and to a peer whose name slugifies away — which is where a
+[known defect](#known-defects) lives.
+
+## Suffix
+
+Applied to the id.
+
+1. Remove every character outside `[0-9a-f]`, case-insensitively.
+2. Take the **last three** characters of what remains.
+3. Lowercase.
+
+**The last three, not the first.** Codex thread ids are UUIDv7: the leading hex
+is a timestamp, so every thread live on a machine at the same time shares its
+first characters. A leading suffix disambiguates nothing. This has been
+specified wrongly before — verify against the fixture.
+
+- `01a0b9b4-a33e-7ab1-80a0-bb715504a0fb` → `0fb`
+- `5af69d42-2214-41d9-b13f-9c3177eb60ce` → `0ce`
+- Uppercase hex is kept, then lowered: `...ABC` → `abc`
+- Fewer than three hex characters yields a shorter suffix: `z-9` → `9`
+- No hex at all yields an empty suffix: `zzzz` → `""`
+
+## Forms
+
+Three forms exist. Two are emitted; all three are accepted as input.
+
+| Form | Shape | Emitted |
+|---|---|---|
+| **Display** | `auth-refactor` | by `peers`, when the slug does not collide |
+| **Qualified** | `auth-refactor.7f3` | by `peers`, only on collision |
+| **Canonical** | `codex:auth-refactor.7f3` | as `canonical_id`, always |
+
+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.
+
+## Collision
+
+A peer is suffixed in its **display** form when either:
+
+- another peer in the same listing has the same slug, or
+- the peer has no name (`rawName === null`), which is always suffixed.
+
+Otherwise the display form is the bare slug. Only colliding peers are suffixed;
+peers that do not collide keep their bare names in the same listing.
+
+## Resolution
+
+Input is trimmed and lowercased, then matched in two passes.
+
+**Pass 1 — exact.** Matches if the input equals the peer's display form, its
+qualified form, or its canonical id. One match resolves. More than one is
+refused as ambiguous.
+
+**Pass 2 — prefix**, only if pass 1 found nothing. Matches if the peer's slug or
+its qualified form *starts with* the input. One match resolves. More than one is
+refused as ambiguous.
+
+If neither pass matches, the result is refused as unknown.
+
+- **Case-insensitive** throughout. `AUTH-REFACTOR.7F3` resolves.
+- **Input is trimmed.** Surrounding whitespace is ignored.
+- **There is no minimum prefix length.** A one-character prefix resolves if it
+  is unambiguous. The empty string is a prefix of everything — see
+  [known defects](#known-defects).
+- **No tie-breaking.** Ambiguity is always refused, never guessed.
+
+### Refusal shape
+
+| Reason | `candidates` contains |
+|---|---|
+| `ambiguous` | every matching peer, in **qualified** form |
+| `unknown` | every peer in the listing, in **display** form |
+
+## Known defects
+
+Preserved in 0.1.0 by decision, not by oversight. They are in the fixture so
+that a second implementation matches Tin Can exactly, including where Tin Can is
+wrong. **Do not "correct" them independently** — that produces addresses that
+resolve in one tool and fail silently in the other.
+
+**1. `canonical_id` is not unique.** Two peers whose slugs match *and* whose ids
+share their last three hex characters produce the same `canonical_id`. Tin Can
+then refuses to resolve either, listing two identical candidates — a refusal
+that tells the caller to disambiguate using a string that does not
+disambiguate. The peers are unaddressable until one exits.
+
+Probability is roughly 1 in 4096 *given* a slug collision, and slug collisions
+are not rare: Codex titles threads from their first prompt, so two sessions
+started from similar prompts collide readily.
+
+**Consumers must therefore treat `canonical_id` as a display and correlation
+aid, not a primary key.** Key on `thread_id` / `session_id`.
+
+**2. A name that slugifies to empty is inconsistent with an unnamed peer.**
+Alone in a listing, a peer named `???` displays as `thread` with no suffix,
+while a peer with no name displays as `thread.<suffix>`. Both slug to `thread`,
+so when they appear together they collide and both are suffixed — the
+inconsistency only shows when each is alone.
+
+**3. The empty string resolves when exactly one peer exists.** Because the empty
+string is a prefix of every slug, `resolve("")` against a single-peer listing
+returns that peer rather than refusing. With two or more peers it is refused as
+ambiguous, as expected.
+
+## Changing this format
+
+The address format is a contract between Tin Can and tools built against it. A
+change to slugify, suffix derivation, collision handling, or resolution produces
+addresses that resolve in one tool and fail silently in the other — no error,
+just a message delivered nowhere.
+
+So:
+
+- **A change to any behaviour described here is a breaking change**, and ships
+  as a major version under semver.
+- Update this document and the fixture in the same commit as the code.
+- Adding cases to the fixture is not a breaking change. Changing an existing
+  expected value is.
+
+Fixing the known defects above is therefore a deliberate, coordinated release —
+not a bug fix to be slipped in.

package/CONTRACT_PROVENANCE.md

@@ -0,0 +1,53 @@
+# Tin Can contract provenance
+
+Copied verbatim from `https://github.com/BrutalSystems/tincan` at commit
+`fbaaea5842fd4a5c86849d7f51c8e16b8683b058` on 2026-09-19.
+The contract describes `@brutalsystems/tincan` version `0.1.0`.
+
+| File | SHA-256 |
+| --- | --- |
+| `CANONICAL_ID.md` | `8cf4312d6af1c4d85ec0641d8739bec261be2feb35dd16bdd9d8be2b89551915` |
+| `test/fixtures/canonical-id.json` | `47fb41fe62efaab6d9ecc7a77623fb2761f79829faf8bcd67c6e54bc4414b751` |
+
+Both copies were verified byte-for-byte against the clean source checkout.
+The fixture contains 31 cases: 8 slugify, 6 suffix, 7 assignment, 10 resolution.
+
+Tin Can's fixture runner compares refusal candidates after sorting both arrays;
+candidate ordering is not asserted by the fixture. Preserve duplicate candidates.
+CLI runtime `claude` maps to address runtime `claude-code`.
+
+Known defects are intentionally preserved: non-unique canonical IDs,
+unnamed versus empty-slug display differences, and empty-input resolution.
+See the normative document for exact behavior.
+
+## Compatibility check against Tin Can 0.2.0
+
+On 2026-09-19, verified source commit
+`3f13fdcc9ac1246b2e5707b6a44f0cf8d207899f`: Claude `peers` now emits
+`session_id`; Codex emits `thread_id`. The integration test must compare those
+durable fields directly, in addition to verifying message delivery.
+
+The four fixture case arrays are identical to our 0.1.0 copy. The upstream
+fixture version is now 0.2.0; that metadata change is not a naming change.
+Our original frozen files remain unchanged. Their full-file hashes above
+detect local edits; they must not be compared to an entire newer upstream
+fixture to infer a format change.
+
+For case comparison, SHA-256 of UTF-8 `JSON.stringify` applied to an object
+with the keys `slugify`, `suffix`, `assign`, `resolve` in that order is:
+`a92936ef4b713641d29da3fbafccab0e6da79a54e27bfea3c6a779e801a925b3`.
+Both revisions produce this hash.
+
+## Upgrade boundary: listing and state
+
+The upstream release notes report that 0.3.0 expands
+Codex-hosted listings to both runtimes and 0.3.1 corrects Codex status decoding.
+These releases have not been verified by Muster's contract suite. The tested
+baseline remains exactly 0.2.0; README installation instructions pin it outside
+Muster's dependency tree.
+
+Inspection confirms the contract test does not assert total peer counts,
+same-runtime exclusion, or Tin Can state. Its count assertion applies only to
+the matching canonical ID in the isolated test environment. Naming hashes do
+not cover listing membership, self-exclusion, or state semantics. A future
+upgrade must test these behaviors separately where relied upon.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# Muster
+
+[![license](https://img.shields.io/github/license/BrutalSystems/muster)](./LICENSE)
+
+Muster launches instructed Codex or Claude Code agents on this machine. A
+`session` returns an address only after its runtime is reachable. A `task`
+runs once, captures output, and never advertises a peer address.
+
+**Live launch verification:** Codex and Claude both launched and answered their
+initial prompts without terminal interaction. Claude requires a directory
+already trusted by the operator. The automated suite uses fake runtimes,
+not real models.
+
+## Build and run locally
+
+Requires Node 22.12+ (tested with 24.16), TypeScript 5, and Codex 0.155.1 / Claude
+Code 2.1.267. Terminal drivers use tmux or node-pty. Process discovery currently
+requires a POSIX host with `ps` and `lsof`; the terminal interface itself is
+platform-neutral. The macOS Terminal 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.
+
+```sh
+npm ci
+npm run build
+node dist/muster.js run codex --prompt 'Review the authentication flow'
+node dist/muster.js run claude --prompt 'Summarize the project' --host tmux
+node dist/muster.js run codex --kind task --prompt 'Explain the test layout'
+node dist/muster.js list
+node dist/muster.js list --kind task
+node dist/muster.js output RUN_ID
+node dist/muster.js stop THREAD_OR_SESSION_OR_RUN_ID
+```
+
+`--prompt` is required and cannot be blank. `--cwd` defaults to the current
+working directory. `--kind` defaults to `session`. All commands except `output`
+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.
+
+`run` accepts an optional `--` followed by runtime arguments. The normal allowlist
+is `--model` / `-m`, plus Claude's `--effort`. Unknown options, bundled short
+options, config injection and permission overrides are refused. Prompt strings
+are passed as a single literal argument after the runtime's option terminator.
+
+## Terminal lifetime
+
+Auto-selection tries tmux, then pty. Every peer includes `host`, `capabilities`
+and `attach_hint`. Watchability is separate from the runtime's idle/busy state.
+
+- **tmux:** a window in the dedicated `muster` session on the `muster` tmux
+  server. Watchable and attachable; survives the CLI or MCP server exiting.
+  Use the returned attach hint, or `tmux -L muster attach -t muster`.
+- **pty:** not watchable or attachable. The CLI prints the peer record and stays
+  running to own the terminal. Ctrl-C stops it. MCP-owned pty sessions stop when
+  the MCP server disconnects. There is no persistent pty daemon.
+- **task:** a per-run worker captures stdout/stderr and exit status after the
+  launching CLI exits. It supervises one task, with no retry or restart behavior.
+
+`list` refreshes live session metadata and shows ended runs distinctly. A timeout
+or startup failure cleans the process tree and host window, logs failure, and
+returns an error instead of a peer record.
+
+## Configuration and permissions
+
+Muster reads `~/.muster/config.toml` once at startup and **never writes it**.
+Missing configuration uses these defaults:
+
+```toml
+host = "auto"
+launch_timeout_sec = 30
+max_concurrent = 4
+sandbox = "read-only"
+allow_dangerous_flags = false
+```
+
+Choose `sandbox = "workspace-write"` yourself when agents should edit files.
+`danger-full-access` additionally requires `allow_dangerous_flags = true`.
+The concurrency cap is shared by separate CLI/MCP processes, including pending
+launches. Settings apply to both kinds; tasks are read-only by default.
+
+Codex gets an explicit sandbox and never-ask approval policy. Muster enumerates
+and explicitly disables inherited MCP servers, then verifies the effective
+configuration. Hooks, plugins, app connectors, automatic skill-MCP installation
+and external notifications are disabled for the child. Unknown MCP names that
+cannot be addressed safely are refused.
+
+Claude's built-in tools default to enabled. Its command sandbox is enabled,
+requires availability, and forbids unsandboxed retries. File-writing tools and
+sandbox writes are denied in read-only mode; permissions use `dontAsk` so an
+unattended child does not auto-grant escalations. User/project settings and MCP
+servers are not inherited. Detected managed policy is refused because the CLI
+cannot prove that inline settings override it. Enterprise remote policy can
+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.
+
+These child restrictions deliberately prevent propagating spawn authority.
+Custom MCP tools—including Tin Can—are not automatically injected into the
+child. The child's runtime inbox remains reachable from an external Tin Can.
+No user-level runtime configuration is rewritten, and workspace-trust dialogs
+are never accepted automatically.
+
+Launch intent is fsynced to `~/.muster/launches.jsonl` before a runtime starts;
+ready/failure outcomes follow. The log contains the **full prompt**, cwd,
+requester, runtime, kind and host. Registry and task outputs also live under
+`~/.muster`, with private file permissions. An abandoned `registry.lock` fails
+closed: verify no Muster operation is running before removing that directory.
+There is no automatic time-based lock theft.
+
+## MCP installation
+
+Installed deliberately, in the one session that should hold spawn authority —
+never at user scope.
+
+Muster exposes `run`, `list`, `stop`, and `output` over stdio. No arguments or
+`mcp` starts the server. Diagnostics go to stderr, never protocol stdout.
+Schemas match the CLI (`args` is the array of optional runtime arguments).
+
+For a single Codex session, use per-invocation configuration:
+
+```sh
+codex -c 'mcp_servers.muster.command="node"' \
+  -c 'mcp_servers.muster.args=["/absolute/path/to/muster/dist/muster.js","mcp"]'
+```
+
+For a single Claude session:
+
+```sh
+claude --mcp-config '{"mcpServers":{"muster":{"command":"node","args":["/absolute/path/to/muster/dist/muster.js","mcp"]}}}'
+```
+
+Do not add Muster to `~/.codex/config.toml`, Claude's user-scope MCP registry,
+or another shared configuration that grants launch authority to every agent.
+
+## Tin Can compatibility
+
+Muster has no Tin Can build or runtime dependency. Each tool implements the
+written address contract independently. Vendored mechanics carry source-commit
+headers and the original MIT license in `TINCAN_LICENSE`.
+
+Addresses belong to running sessions and can expire or collide. Store
+`thread_id` / `session_id`, and re-resolve through Tin Can's `peers` before
+sending instead of caching a launch address. Canonical IDs are not unique keys.
+The frozen cases intentionally preserve Tin Can's known naming defects.
+
+Codex `idle` means reachable and not known to be busy, not guaranteed free.
+The querying app-server can report `notLoaded` for a live thread; Muster maps
+that to `idle`. Claude state comes from its session registry.
+
+## Verification
+
+```sh
+npm test
+npm run build
+npm run test:contract
+```
+
+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.2.0**. 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:
+
+```sh
+contract_dir=$(mktemp -d)
+npm install --prefix "$contract_dir" --no-save @brutalsystems/tincan@0.2.0
+MUSTER_TINCAN_BIN="$contract_dir/node_modules/.bin/tincan" npm run test:contract
+```
+
+Verification uses the published 0.2.0 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
+fixture hashes alone does not establish compatibility. The tests locate the
+launched peer by canonical ID and compare its durable ID; they do not assert a
+total peer count, exclude same-runtime peers, or assert Tin Can's busy state.
+`CONTRACT_PROVENANCE.md` records both types of integrity checks.
+
+One-time live probes are separate from the automated suite. Both runtimes
+launched and answered an initial prompt with the versions listed above; Claude
+used a directory already trusted by its operator. `npm test` does not run
+real models.
+
+## License and releases
+
+MIT © 2026 Mike Williams. See [LICENSE](./LICENSE). Vendored Tin Can code
+retains source attribution and its [MIT notice](./TINCAN_LICENSE).
+
+[RELEASING.md](./RELEASING.md) covers versioning, package inspection, publication,
+and release notes. Changes to the shared address format require an explicit
+contract update; Muster never independently fixes the frozen naming behavior.

package/TINCAN_LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/claude-policy.js

@@ -0,0 +1,51 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+/** Claude's CLI cannot report all effective enterprise policy before starting.
+ * Refuse detected managed sources rather than pretending inline settings win. */
+export async function assertClaudePolicy(env) {
+    if (env.CLAUDE_CONFIG_DIR)
+        throw new Error("Custom CLAUDE_CONFIG_DIR is unsupported: Tin Can discovers ~/.claude/sessions");
+    const home = env.HOME ?? homedir();
+    const system = process.platform === "darwin"
+        ? "/Library/Application Support/ClaudeCode"
+        : "/etc/claude-code";
+    const files = [
+        join(system, "managed-settings.json"),
+        join(system, "managed-mcp.json"),
+        join(home, ".claude", "remote-settings.json"),
+    ];
+    try {
+        for (const file of await readdir(join(system, "managed-settings.d")))
+            if (file.endsWith(".json"))
+                files.push(join(system, "managed-settings.d", file));
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    for (const file of files) {
+        try {
+            const settings = JSON.parse(await readFile(file, "utf8"));
+            if (settings && Object.keys(settings).length)
+                throw new Error(`Managed Claude policy detected at ${file}; effective sandbox policy cannot be verified by this v1 launcher`);
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+    }
+    if (process.platform === "darwin") {
+        try {
+            const { stdout } = await promisify(execFile)("defaults", ["read", "com.anthropic.claudecode"], { timeout: 1000, env });
+            if (stdout.trim())
+                throw new Error("Managed Claude preferences detected; effective sandbox policy cannot be verified by this v1 launcher");
+        }
+        catch (e) {
+            if (e.code !== 1)
+                throw e;
+        }
+    }
+}

package/dist/codex-policy.js

@@ -0,0 +1,40 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+export async function codexPolicyArgs(env, cwd, deadline = Date.now() + 8000) {
+    const args = [
+        "--disable",
+        "hooks",
+        "--disable",
+        "plugins",
+        "--disable",
+        "remote_plugin",
+        "--disable",
+        "apps",
+        "--disable",
+        "skill_mcp_dependency_install",
+        "-c",
+        "notify=[]",
+    ];
+    async function list(extra) {
+        const { stdout } = await exec("codex", [...extra, "mcp", "list", "--json"], {
+            env,
+            cwd,
+            timeout: Math.max(1, Math.min(4000, deadline - Date.now())),
+            maxBuffer: 1024 * 1024,
+        });
+        const value = JSON.parse(stdout);
+        if (!Array.isArray(value))
+            throw new Error("Cannot verify effective Codex MCP configuration");
+        return value;
+    }
+    for (const server of await list(args)) {
+        if (typeof server.name !== "string" ||
+            !/^[a-zA-Z0-9_-]+$/.test(server.name))
+            throw new Error("Cannot safely disable an inherited MCP server with a non-simple name");
+        args.push("-c", `mcp_servers.${server.name}.enabled=false`);
+    }
+    if ((await list(args)).some((s) => s.enabled !== false))
+        throw new Error("Inherited Codex MCP servers remain enabled; refusing launch");
+    return args;
+}

package/dist/codex-rpc.js

@@ -0,0 +1,116 @@
+import { codexPolicyArgs } from "./codex-policy.js";
+import { spawn } from "node:child_process";
+/** JSONL protocol mechanics independently adapted from Tin Can src/codex/cli.ts
+ * at fbaaea5842fd4a5c86849d7f51c8e16b8683b058 (MIT). */
+export class CodexRpc {
+    env;
+    cwd;
+    policy;
+    child;
+    serial = 0;
+    buffer = "";
+    initialized = false;
+    pending = new Map();
+    constructor(env, cwd = process.cwd(), policy) {
+        this.env = env;
+        this.cwd = cwd;
+        this.policy = policy;
+    }
+    async start(deadline) {
+        if (this.child)
+            return;
+        const policy = this.policy ?? (await codexPolicyArgs(this.env, this.cwd, deadline));
+        const child = spawn("codex", [...policy, "app-server", "--listen", "stdio://"], {
+            env: this.env,
+            cwd: this.cwd,
+            stdio: "pipe",
+        });
+        this.child = child;
+        child.stderr.resume();
+        const fail = (e) => {
+            for (const p of this.pending.values()) {
+                clearTimeout(p.timer);
+                p.reject(e);
+            }
+            this.pending.clear();
+        };
+        child.on("error", fail);
+        child.on("exit", () => fail(new Error("Codex app-server exited")));
+        child.stdin.on("error", fail);
+        child.stdout.on("data", (data) => {
+            this.buffer += data;
+            let i;
+            while ((i = this.buffer.indexOf("\n")) >= 0) {
+                const line = this.buffer.slice(0, i);
+                this.buffer = this.buffer.slice(i + 1);
+                let m;
+                try {
+                    m = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                const p = this.pending.get(m.id);
+                if (!p)
+                    continue;
+                clearTimeout(p.timer);
+                this.pending.delete(m.id);
+                if (m.error)
+                    p.reject(new Error(m.error.message ?? "Codex RPC error"));
+                else if (!m.result || typeof m.result !== "object")
+                    p.reject(new Error("Invalid Codex RPC result"));
+                else
+                    p.resolve(m.result);
+            }
+        });
+    }
+    send(method, params, deadline) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return Promise.reject(new Error(`Timed out calling ${method}`));
+        return new Promise((resolve, reject) => {
+            const id = ++this.serial;
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Timed out calling ${method}`));
+            }, Math.min(remaining, 2000));
+            this.pending.set(id, { resolve, reject, timer });
+            this.child.stdin.write(JSON.stringify({ id, method, params }) + "\n");
+        });
+    }
+    async call(method, params, deadline) {
+        await this.start(deadline);
+        if (!this.initialized) {
+            await this.send("initialize", {
+                clientInfo: { name: "muster", version: "0.1.0" },
+                capabilities: { experimentalApi: true },
+            }, deadline);
+            this.initialized = true;
+        }
+        return this.send(method, params, deadline);
+    }
+    async close() {
+        if (!this.child)
+            return;
+        const child = this.child;
+        this.child = undefined;
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(new Error("Codex RPC closed"));
+        }
+        this.pending.clear();
+        if (child.exitCode !== null)
+            return;
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                resolve();
+            }, 1000);
+            child.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            child.kill("SIGTERM");
+        });
+    }
+}