agent-dealer 1.1.0 → 1.1.2

package/bundle/server/dist/runners/muse-config-core.js

@@ -0,0 +1,488 @@
+// NOT-180: per-attempt native Muse Code configuration.
+//
+// Materializes everything one `muse exec` attempt may see — settings.json, XDG dirs, auth link,
+// argv, env — outside the worktree, and refuses (before anything is written or spawned) when a
+// required restriction is not one NOT-177 proved Muse can enforce. Only controls recorded in
+// docs/evaluations/muse-code/headless-contract.md are emitted; nothing here is assumed.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const NOT_177_EVIDENCE = Object.freeze({
+    mcp_tool_allowlist_enforcement: false,
+    cron_tool_disable: false,
+});
+export const MUSE_MODEL = "muse-spark-1.3-contributor";
+export const AGENT_DECK_SERVER = "agent-deck";
+/** Deck reads a worker needs. `call_service_tool` (outbound mutation) is never in this list. */
+export const AGENT_DECK_READ_TOOLS = [
+    "get_bound_deck",
+    "get_playbook",
+    "list_service_tools",
+    "bind_workspace",
+];
+export const AGENT_DECK_DENIED_TOOLS = ["call_service_tool"];
+const CRON_TOOLS = ["cron_create", "cron_list", "cron_delete"];
+const REMINDERS = [
+    "skill-reminder",
+    "verify-reminder",
+    "memory-reminder",
+    "todo-reminder",
+    "goal-reminder",
+    "scope-reminder",
+];
+/** Flags that widen trust, sandbox, approvals or orchestration. Never emitted, refused if seen. */
+const FORBIDDEN_FLAGS = [
+    "--yolo",
+    "--disable-sandbox",
+    "--disable-approval",
+    "--trust-workspace",
+    "--worktree",
+    "-w",
+    "--subagent-worktree-isolation",
+    "--preset",
+    "--agents",
+    "--permission-profile",
+    "--no-session-log",
+];
+/** Which ambient env vars reach Muse. Everything else (META_API_KEY, MUSE_*, CODEX_HOME, ...) is dropped. */
+const ENV_ALLOWLIST = ["PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "TERM", "TMPDIR"];
+const ATTEMPT_PREFIX = "muse-attempt-";
+const SENTINEL = ".dealer-muse-attempt";
+/** Messages name fields and paths, never values that could be credentials. */
+export class MuseIsolationError extends Error {
+    code;
+    capabilities;
+    constructor(code, message, capabilities = []) {
+        super(message);
+        this.code = code;
+        this.capabilities = capabilities;
+        this.name = "MuseIsolationError";
+    }
+}
+/** Capabilities a role needs that the evidence does not prove. Both roles need both today. */
+export function unenforceableRestrictions(_role, evidence = NOT_177_EVIDENCE) {
+    const missing = [];
+    // Outbound mutation (`call_service_tool`) must stay denied for every role, and Muse only
+    // stores enabled_tools/disabled_tools unless this is proven.
+    if (!evidence.mcp_tool_allowlist_enforcement)
+        missing.push("mcp_tool_allowlist_enforcement");
+    // cron jobs are background orchestration that fired a second agent run inside the process.
+    if (!evidence.cron_tool_disable)
+        missing.push("cron_tool_disable");
+    return missing;
+}
+export function buildMuseSettings(agentDeck, evidence = NOT_177_EVIDENCE) {
+    const runtime_capabilities = {};
+    for (const name of REMINDERS) {
+        runtime_capabilities[`plugin:tbh-reminders:reminder:${name}`] = { enabled: false };
+    }
+    if (evidence.cron_tool_disable) {
+        for (const tool of CRON_TOOLS)
+            runtime_capabilities[`tool:${tool}`] = { enabled: false };
+    }
+    const server = {
+        type: "streamable-http",
+        url: agentDeck.url,
+        headers: {
+            "x-agent-deck-deck-id": agentDeck.deckId,
+            "x-agent-deck-workspace": agentDeck.workspace,
+        },
+        // `mode`, not `required`: writing both drops the whole MCP block. Never "optional".
+        mode: "required",
+    };
+    if (evidence.mcp_tool_allowlist_enforcement) {
+        server.enabled_tools = [...AGENT_DECK_READ_TOOLS];
+        server.disabled_tools = [...AGENT_DECK_DENIED_TOOLS];
+    }
+    return {
+        schema_version: 1,
+        run: { workflow_trigger_mode: "off", subagent_delegation_mode: "off" },
+        runtime_capabilities,
+        mcpServers: { [AGENT_DECK_SERVER]: server },
+    };
+}
+/** Whitelist check on a settings object (generated or re-read from disk). */
+export function assertMuseSettings(settings, agentDeck, evidence = NOT_177_EVIDENCE) {
+    const expected = buildMuseSettings(agentDeck, evidence);
+    if (JSON.stringify(sortKeys(settings)) !== JSON.stringify(sortKeys(expected))) {
+        throw new MuseIsolationError("invalid_settings", "Muse settings differ from the approved role settings (extra, missing, or altered keys)");
+    }
+    const servers = Object.keys(settings.mcpServers ?? {});
+    if (servers.length !== 1 || servers[0] !== AGENT_DECK_SERVER) {
+        throw new MuseIsolationError("invalid_settings", "Muse settings must configure exactly the agent-deck MCP server");
+    }
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => [k, sortKeys(v)]));
+    }
+    return value;
+}
+export function buildMuseArgv(input) {
+    const argv = [
+        "exec",
+        ...(input.apiKeyStdin ? ["--api-key-stdin"] : []),
+        "--json",
+        "--no-foreign-personal-context",
+        "--model",
+        MUSE_MODEL,
+        "--approval-mode",
+        "never",
+        "--approval-judge",
+        "off",
+        "--sandbox-network",
+        "restricted",
+        "--disable-web-tools",
+        "--session-id",
+        input.sessionId,
+        "--max-model-steps",
+        String(input.maxModelSteps),
+    ];
+    if (input.role === "reviewer")
+        argv.push("--disable-write", "--disable-shell");
+    argv.push(input.prompt);
+    assertMuseArgv(argv, input.role);
+    return argv;
+}
+/** Refuses argv that widens trust/sandbox/orchestration or drops a required restriction. */
+export function assertMuseArgv(argv, role) {
+    // The prompt is the last positional; flags inside it would be parsed by Muse.
+    const flags = argv.slice(0, -1);
+    for (const arg of flags) {
+        const name = arg.split("=")[0];
+        if (FORBIDDEN_FLAGS.includes(name)) {
+            throw new MuseIsolationError("invalid_argv", `Muse argv contains forbidden flag ${name}`);
+        }
+    }
+    if (argv[0] !== "exec")
+        throw new MuseIsolationError("invalid_argv", "Muse argv must start with exec");
+    const requireValue = (flag, value) => {
+        const i = flags.indexOf(flag);
+        if (i < 0 || flags[i + 1] !== value) {
+            throw new MuseIsolationError("invalid_argv", `Muse argv must set ${flag} ${value}`);
+        }
+    };
+    requireValue("--approval-mode", "never");
+    requireValue("--sandbox-network", "restricted");
+    requireValue("--model", MUSE_MODEL);
+    if (!flags.includes("--json"))
+        throw new MuseIsolationError("invalid_argv", "Muse argv must set --json");
+    if (!flags.includes("--no-foreign-personal-context")) {
+        throw new MuseIsolationError("invalid_argv", "Muse argv must set --no-foreign-personal-context");
+    }
+    const readOnly = flags.includes("--disable-write") && flags.includes("--disable-shell");
+    if (role === "reviewer" && !readOnly) {
+        throw new MuseIsolationError("invalid_argv", "Reviewer argv must set --disable-write and --disable-shell");
+    }
+    if (role === "developer" && (flags.includes("--disable-write") || flags.includes("--disable-shell"))) {
+        throw new MuseIsolationError("invalid_argv", "Developer argv must not disable write or shell");
+    }
+}
+/** Env for the child: filtered ambient vars plus the per-attempt XDG dirs. No credentials. */
+export function buildMuseEnv(root, ambient = process.env) {
+    const env = {};
+    for (const key of ENV_ALLOWLIST) {
+        const value = ambient[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(ambient)) {
+        if (key.startsWith("LC_") && value !== undefined)
+            env[key] = value;
+    }
+    env.MUSE_NO_AUTO_UPDATE = "1";
+    env.XDG_CONFIG_HOME = path.join(root, "config");
+    env.XDG_DATA_HOME = path.join(root, "data");
+    return env;
+}
+/** `$XDG_CONFIG_HOME/muse/auth.json` (or `~/.config/muse/auth.json`) of the operator. Never read. */
+export function defaultOperatorAuthPath(env = process.env) {
+    const configHome = env.XDG_CONFIG_HOME?.trim() || path.join(env.HOME ?? os.homedir(), ".config");
+    return path.join(configHome, "muse", "auth.json");
+}
+function isInside(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function realDir(p, label) {
+    if (!path.isAbsolute(p))
+        throw new MuseIsolationError("invalid_input", `${label} must be an absolute path`);
+    try {
+        if (!fs.statSync(p).isDirectory())
+            throw new Error("not a directory");
+        return fs.realpathSync(p);
+    }
+    catch {
+        throw new MuseIsolationError("invalid_input", `${label} must be an existing directory`);
+    }
+}
+function tempRoots() {
+    const roots = new Set(["/tmp", "/var/tmp", "/private/tmp", "/private/var/tmp", os.tmpdir()]);
+    for (const r of [...roots]) {
+        try {
+            roots.add(fs.realpathSync(r));
+        }
+        catch {
+            // Missing temp roots cannot host anything.
+        }
+    }
+    return [...roots];
+}
+function validateInput(input) {
+    if (input.role !== "developer" && input.role !== "reviewer") {
+        throw new MuseIsolationError("invalid_input", "role must be developer or reviewer");
+    }
+    const worktree = realDir(input.worktreePath, "worktreePath");
+    const baseDir = realDir(input.baseDir, "baseDir");
+    if (isInside(baseDir, worktree) || isInside(worktree, baseDir)) {
+        throw new MuseIsolationError("unsafe_path", "Per-attempt config must live outside the worktree");
+    }
+    // The Muse sandbox leaves temp dirs writable (probe 6), so neither the worktree nor the
+    // config can be protected from the worker there.
+    for (const tmp of tempRoots()) {
+        if (isInside(worktree, tmp) || isInside(baseDir, tmp)) {
+            throw new MuseIsolationError("unsafe_path", "Worktree and per-attempt config must not be under a temp dir");
+        }
+    }
+    const { url, deckId, workspace } = input.agentDeck ?? {};
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+            throw new Error("scheme");
+        if (parsed.username || parsed.password)
+            throw new Error("userinfo");
+    }
+    catch {
+        throw new MuseIsolationError("invalid_input", "agentDeck.url must be an http(s) URL without credentials");
+    }
+    if (!deckId?.trim() || !workspace?.trim()) {
+        throw new MuseIsolationError("invalid_input", "agentDeck.deckId and agentDeck.workspace are required");
+    }
+    let workspaceReal;
+    try {
+        workspaceReal = fs.realpathSync(workspace);
+    }
+    catch {
+        // Reported below.
+    }
+    if (workspaceReal !== worktree) {
+        throw new MuseIsolationError("invalid_input", "agentDeck.workspace must be the attempt's worktree");
+    }
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(input.sessionId ?? "")) {
+        throw new MuseIsolationError("invalid_input", "sessionId must be a UUID");
+    }
+    if (!Number.isInteger(input.maxModelSteps) || input.maxModelSteps < 1) {
+        throw new MuseIsolationError("invalid_input", "maxModelSteps must be a positive integer");
+    }
+    if (typeof input.prompt !== "string" || input.prompt.trim() === "" || input.prompt.startsWith("-")) {
+        throw new MuseIsolationError("invalid_input", "prompt must be non-empty and must not start with '-'");
+    }
+    const cred = input.credential;
+    if (cred?.kind === "auth-file") {
+        if (!path.isAbsolute(cred.path) || !fs.existsSync(cred.path) || !fs.statSync(cred.path).isFile()) {
+            throw new MuseIsolationError("invalid_input", "credential.path must be an existing auth file");
+        }
+    }
+    else if (cred?.kind === "api-key") {
+        if (typeof cred.apiKey !== "string" || cred.apiKey.trim() === "") {
+            throw new MuseIsolationError("invalid_input", "credential.apiKey must be non-empty");
+        }
+    }
+    else {
+        throw new MuseIsolationError("invalid_input", "credential is required");
+    }
+    return { worktree, baseDir };
+}
+export function createRedactor(secrets) {
+    const values = secrets.filter((s) => s.length > 0).sort((a, b) => b.length - a.length);
+    return (text) => {
+        let out = text;
+        for (const v of values)
+            out = out.split(v).join("[REDACTED]");
+        return out
+            .replace(/(META_API_KEY\s*=\s*)\S+/g, "$1[REDACTED]")
+            .replace(/(Bearer\s+)[A-Za-z0-9._~+/=-]{8,}/g, "$1[REDACTED]");
+    };
+}
+function writePrivate(file, content) {
+    fs.writeFileSync(file, content, { mode: 0o600, flag: "wx" });
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object") {
+        for (const v of Object.values(value))
+            deepFreeze(v);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** Copies the fields verify() depends on; malformed shapes are left for validateInput to reject. */
+function snapshotInput(raw) {
+    const deck = raw.agentDeck && typeof raw.agentDeck === "object" ? raw.agentDeck : undefined;
+    const cred = raw.credential && typeof raw.credential === "object" ? raw.credential : undefined;
+    return deepFreeze({
+        ...raw,
+        agentDeck: deck ? { url: deck.url, deckId: deck.deckId, workspace: deck.workspace } : raw.agentDeck,
+        credential: cred ? { ...cred } : raw.credential,
+        env: raw.env ? { ...raw.env } : undefined,
+    });
+}
+function sameJson(a, b) {
+    return JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b));
+}
+/**
+ * Validates, refuses unenforceable restrictions, then writes the per-attempt dir (0700) with
+ * settings.json (0600) and an auth link. Throws before spawn; leaves nothing behind on failure.
+ *
+ * Always uses the pinned `NOT_177_EVIDENCE`, under which both roles are currently refused. There is
+ * deliberately no runtime seam that accepts other evidence: the enforced-path tests load a
+ * source-rewritten copy of this file instead (see muse-config.test.ts).
+ */
+export function prepareMuseAttempt(input) {
+    return prepareWithEvidence(input, NOT_177_EVIDENCE);
+}
+// Not exported: evidence must never be caller-supplied.
+function prepareWithEvidence(rawInput, evidence) {
+    // Verification later runs against this snapshot, never against the caller's mutable object.
+    const input = snapshotInput(rawInput);
+    const missing = unenforceableRestrictions(input.role, evidence);
+    if (missing.length > 0) {
+        throw new MuseIsolationError("unenforceable_restriction", `Muse cannot mechanically enforce required restrictions for ${input.role}: ${missing.join(", ")}`, missing);
+    }
+    const { worktree, baseDir } = validateInput(input);
+    const agentDeck = input.agentDeck;
+    const credentialKind = input.credential.kind;
+    const settings = deepFreeze(buildMuseSettings(agentDeck, evidence));
+    assertMuseSettings(settings, agentDeck, evidence);
+    const apiKey = input.credential.kind === "api-key" ? input.credential.apiKey : undefined;
+    const argv = buildMuseArgv({
+        role: input.role,
+        sessionId: input.sessionId,
+        maxModelSteps: input.maxModelSteps,
+        prompt: input.prompt,
+        apiKeyStdin: apiKey !== undefined,
+    });
+    const root = fs.mkdtempSync(path.join(baseDir, ATTEMPT_PREFIX));
+    // Terminal only once the dir is confirmed gone, so a failed rmSync can be retried.
+    let cleaned = false;
+    const removeRoot = (requireSentinel) => {
+        if (cleaned)
+            return;
+        // Only a dir this module created (prefix) directly under baseDir is removed.
+        if (path.dirname(root) !== baseDir || !path.basename(root).startsWith(ATTEMPT_PREFIX))
+            return;
+        let present = true;
+        try {
+            fs.lstatSync(root);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            present = false;
+        }
+        if (present) {
+            // After construction the sentinel proves the dir is still ours; the dir mkdtemp just returned
+            // is ours by construction even if the sentinel was never written.
+            if (requireSentinel && !fs.existsSync(path.join(root, SENTINEL)))
+                return;
+            // rmSync unlinks the auth symlink without following it.
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+        cleaned = true;
+    };
+    const cleanup = () => removeRoot(true);
+    const abortConstruction = (original) => {
+        try {
+            removeRoot(false);
+        }
+        catch (rmErr) {
+            const reason = original instanceof Error ? original.message : "unknown error";
+            const rmReason = rmErr instanceof Error ? rmErr.message : "unknown error";
+            throw new MuseIsolationError("cleanup_failed", `Muse attempt setup failed (${reason}) and its dir ${root} could not be removed: ${rmReason}`);
+        }
+        throw original;
+    };
+    const settingsPath = path.join(root, "config", "muse", "settings.json");
+    const approved = deepFreeze({
+        cwd: worktree,
+        argv: [...argv],
+        env: buildMuseEnv(root, input.env),
+        stdin: apiKey === undefined ? undefined : `${apiKey}\n`,
+    });
+    const verify = (launch = attempt) => {
+        if (launch.cwd !== approved.cwd) {
+            throw new MuseIsolationError("invalid_argv", "Muse must be launched with cwd set to the assigned worktree");
+        }
+        if (fs.realpathSync(launch.cwd) !== worktree) {
+            throw new MuseIsolationError("invalid_argv", "Muse launch cwd no longer resolves to the assigned worktree");
+        }
+        if (!sameJson([...launch.argv], approved.argv)) {
+            throw new MuseIsolationError("invalid_argv", "Muse argv differs from the approved launch argv");
+        }
+        if (!sameJson(launch.env, approved.env)) {
+            throw new MuseIsolationError("invalid_argv", "Muse env differs from the approved launch env");
+        }
+        if (launch.stdin !== approved.stdin) {
+            throw new MuseIsolationError("invalid_argv", "Muse stdin differs from the approved launch stdin");
+        }
+        const expectDir = (dir) => {
+            if ((fs.statSync(dir).mode & 0o077) !== 0)
+                throw new MuseIsolationError("unsafe_path", "Attempt dir is not private");
+        };
+        let onDisk;
+        try {
+            expectDir(root);
+            if ((fs.statSync(settingsPath).mode & 0o077) !== 0) {
+                throw new MuseIsolationError("unsafe_path", "settings.json is not private");
+            }
+            onDisk = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+        }
+        catch (err) {
+            if (err instanceof MuseIsolationError)
+                throw err;
+            throw new MuseIsolationError("invalid_settings", "Muse settings.json is missing or unreadable");
+        }
+        assertMuseSettings(onDisk, agentDeck, evidence);
+        const entries = fs.readdirSync(path.dirname(settingsPath)).sort();
+        const allowed = credentialKind === "auth-file" ? ["auth.json", "settings.json"] : ["settings.json"];
+        if (entries.join() !== allowed.join()) {
+            throw new MuseIsolationError("invalid_settings", "Unexpected files in the per-attempt Muse config dir");
+        }
+        assertMuseArgv([...approved.argv], input.role);
+    };
+    try {
+        fs.chmodSync(root, 0o700);
+        writePrivate(path.join(root, SENTINEL), "");
+        fs.mkdirSync(path.dirname(settingsPath), { recursive: true, mode: 0o700 });
+        fs.mkdirSync(path.join(root, "data"), { recursive: true, mode: 0o700 });
+        writePrivate(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+        if (input.credential.kind === "auth-file") {
+            fs.symlinkSync(input.credential.path, path.join(path.dirname(settingsPath), "auth.json"));
+        }
+    }
+    catch (err) {
+        return abortConstruction(err);
+    }
+    const attempt = Object.freeze({
+        root,
+        settingsPath,
+        settings,
+        cwd: approved.cwd,
+        argv: approved.argv,
+        env: approved.env,
+        stdin: approved.stdin,
+        redact: createRedactor(apiKey ? [apiKey] : []),
+        verify,
+        cleanup,
+    });
+    try {
+        verify();
+    }
+    catch (err) {
+        return abortConstruction(err);
+    }
+    return attempt;
+}

package/bundle/server/dist/runners/muse-config.js

@@ -0,0 +1,5 @@
+// NOT-180: production entry point for per-attempt native Muse Code configuration.
+//
+// The implementation lives in muse-config-core.ts, which pins `prepareMuseAttempt` to
+// `NOT_177_EVIDENCE`. No module in the build exports a preparer that accepts caller-supplied evidence.
+export { AGENT_DECK_DENIED_TOOLS, AGENT_DECK_READ_TOOLS, AGENT_DECK_SERVER, MUSE_MODEL, MuseIsolationError, NOT_177_EVIDENCE, assertMuseArgv, assertMuseSettings, buildMuseArgv, buildMuseEnv, buildMuseSettings, createRedactor, defaultOperatorAuthPath, prepareMuseAttempt, unenforceableRestrictions, } from "./muse-config-core.js";

package/bundle/server/dist/runners/muse-config.test.js

@@ -0,0 +1,521 @@
+import { test, after, mock } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { assertMuseArgv, buildMuseArgv, prepareMuseAttempt as prepareMuseAttemptPinned, unenforceableRestrictions, } from "./muse-config.js";
+import { pathToFileURL } from "node:url";
+// The Muse sandbox leaves temp dirs writable, so the module refuses them: fixtures live under $HOME.
+const SCRATCH = fs.mkdtempSync(path.join(os.homedir(), ".dealer-muse-config-test-"));
+after(() => fs.rmSync(SCRATCH, { recursive: true, force: true }));
+const ENFORCED = { mcp_tool_allowlist_enforcement: true, cron_tool_disable: true };
+// Production code has no seam that accepts other enforcement evidence. The enforced paths are exercised
+// against a hypothetical build by loading a source-rewritten copy of the core with the pinned evidence
+// flipped to true. The copy lives in SCRATCH (outside src/ and dist/), so it never ships.
+async function loadEnforcedCore() {
+    const source = fs.readFileSync(path.join(import.meta.dirname, "muse-config-core.ts"), "utf8");
+    const literal = /(mcp_tool_allowlist_enforcement|cron_tool_disable): false,/g;
+    assert.equal(source.match(literal)?.length, 2, "pinned evidence literal changed; update the test rewrite");
+    const copy = path.join(SCRATCH, "muse-config-core.enforced.ts");
+    fs.writeFileSync(copy, source.replace(literal, "$1: true,"));
+    return import(pathToFileURL(copy).href);
+}
+const enforcedCore = await loadEnforcedCore();
+const prepareMuseAttempt = (i) => enforcedCore.prepareMuseAttempt(i);
+const SESSION = "11111111-2222-4333-8444-555555555555";
+const API_KEY = "mk-live-SECRET-0123456789abcdef";
+const DECK_URL = "http://127.0.0.1:1110/mcp";
+function fixture() {
+    const dir = fs.mkdtempSync(path.join(SCRATCH, "case-"));
+    const worktree = path.join(dir, "worktree");
+    const baseDir = path.join(dir, "attempts");
+    const operatorConfigHome = path.join(dir, "operator-config");
+    fs.mkdirSync(worktree);
+    fs.mkdirSync(baseDir);
+    fs.mkdirSync(path.join(operatorConfigHome, "muse"), { recursive: true });
+    const operatorAuth = path.join(operatorConfigHome, "muse", "auth.json");
+    fs.writeFileSync(operatorAuth, '{"token":"operator-owned"}');
+    return { worktree, baseDir, operatorAuth, operatorConfigHome };
+}
+function input(fx, role, over = {}) {
+    return {
+        role,
+        worktreePath: fx.worktree,
+        baseDir: fx.baseDir,
+        agentDeck: { url: DECK_URL, deckId: "deck-123", workspace: fx.worktree },
+        credential: { kind: "auth-file", path: fx.operatorAuth },
+        sessionId: SESSION,
+        prompt: "Implement the ticket",
+        maxModelSteps: 300,
+        env: { PATH: "/usr/bin", HOME: os.homedir() },
+        ...over,
+    };
+}
+function code(fn) {
+    try {
+        fn();
+    }
+    catch (err) {
+        // The enforced-core copy has its own MuseIsolationError class, so match by name.
+        assert.ok(err instanceof Error && err.name === "MuseIsolationError", String(err));
+        return err.code;
+    }
+    return undefined;
+}
+function walk(dir) {
+    return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+        const p = path.join(dir, e.name);
+        return e.isDirectory() ? walk(p) : [p];
+    });
+}
+test("with NOT-177 evidence both roles fail before anything is written", () => {
+    for (const role of ["developer", "reviewer"]) {
+        const fx = fixture();
+        let thrown;
+        try {
+            prepareMuseAttemptPinned(input(fx, role));
+        }
+        catch (err) {
+            thrown = err;
+        }
+        assert.equal(thrown?.code, "unenforceable_restriction", role);
+        assert.deepEqual([...thrown.capabilities], ["mcp_tool_allowlist_enforcement", "cron_tool_disable"]);
+        assert.deepEqual(fs.readdirSync(fx.baseDir), []);
+    }
+    assert.deepEqual(unenforceableRestrictions("developer", ENFORCED), []);
+    assert.deepEqual(unenforceableRestrictions("reviewer", { ...ENFORCED, cron_tool_disable: false }), [
+        "cron_tool_disable",
+    ]);
+});
+test("developer: only the assigned Agent Deck surface, sandbox on, no unrestricted flags", () => {
+    const fx = fixture();
+    const attempt = prepareMuseAttempt(input(fx, "developer"));
+    try {
+        assert.ok(!attempt.root.startsWith(fx.worktree), "config lives outside the worktree");
+        const onDisk = JSON.parse(fs.readFileSync(attempt.settingsPath, "utf8"));
+        assert.deepEqual(Object.keys(onDisk).sort(), ["mcpServers", "run", "runtime_capabilities", "schema_version"]);
+        assert.deepEqual(Object.keys(onDisk.mcpServers), ["agent-deck"]);
+        const server = onDisk.mcpServers["agent-deck"];
+        assert.equal(server.mode, "required");
+        assert.equal("required" in server, false, "mode and required together drop the MCP block");
+        assert.deepEqual(server.headers, {
+            "x-agent-deck-deck-id": "deck-123",
+            "x-agent-deck-workspace": fs.realpathSync(fx.worktree),
+        });
+        assert.deepEqual(server.enabled_tools, ["get_bound_deck", "get_playbook", "list_service_tools", "bind_workspace"]);
+        assert.deepEqual(server.disabled_tools, ["call_service_tool"]);
+        assert.deepEqual(onDisk.run, { workflow_trigger_mode: "off", subagent_delegation_mode: "off" });
+        for (const tool of ["cron_create", "cron_list", "cron_delete"]) {
+            assert.deepEqual(onDisk.runtime_capabilities[`tool:${tool}`], { enabled: false });
+        }
+        const flag = (f) => attempt.argv[attempt.argv.indexOf(f) + 1];
+        assert.equal(attempt.argv[0], "exec");
+        assert.equal(flag("--approval-mode"), "never");
+        assert.equal(flag("--sandbox-network"), "restricted");
+        assert.equal(flag("--model"), "muse-spark-1.3-contributor");
+        assert.equal(flag("--session-id"), SESSION);
+        assert.equal(attempt.argv.at(-1), "Implement the ticket");
+        for (const bad of ["--yolo", "--disable-sandbox", "--disable-approval", "--trust-workspace", "-w", "--worktree", "--disable-write", "--disable-shell"]) {
+            assert.equal(attempt.argv.includes(bad), false, bad);
+        }
+        assert.equal(fs.statSync(attempt.root).mode & 0o777, 0o700);
+        assert.equal(fs.statSync(attempt.settingsPath).mode & 0o777, 0o600);
+        assert.equal(attempt.env.XDG_CONFIG_HOME, path.join(attempt.root, "config"));
+        assert.equal(attempt.env.XDG_DATA_HOME, path.join(attempt.root, "data"));
+        assert.equal(attempt.env.MUSE_NO_AUTO_UPDATE, "1");
+        assert.equal(attempt.stdin, undefined);
+        assert.doesNotThrow(() => attempt.verify());
+    }
+    finally {
+        attempt.cleanup();
+    }
+});
+test("reviewer: read-only flags and the same deck reads, mutation denied", () => {
+    const fx = fixture();
+    const attempt = prepareMuseAttempt(input(fx, "reviewer"));
+    try {
+        assert.ok(attempt.argv.includes("--disable-write"));
+        assert.ok(attempt.argv.includes("--disable-shell"));
+        const server = attempt.settings.mcpServers["agent-deck"];
+        assert.equal(server.enabled_tools?.includes("call_service_tool"), false);
+        assert.deepEqual(server.disabled_tools, ["call_service_tool"]);
+        assert.deepEqual(Object.keys(attempt.settings.mcpServers), ["agent-deck"]);
+    }
+    finally {
+        attempt.cleanup();
+    }
+    // A reviewer argv without the read-only flags is refused, as is a developer with them.
+    assert.equal(code(() => assertMuseArgv(buildMuseArgv({ role: "developer", sessionId: SESSION, maxModelSteps: 5, prompt: "x" }), "reviewer")), "invalid_argv");
+    assert.equal(code(() => assertMuseArgv(buildMuseArgv({ role: "reviewer", sessionId: SESSION, maxModelSteps: 5, prompt: "x" }), "developer")), "invalid_argv");
+});
+test("argv guard refuses every trust/sandbox/orchestration widening flag", () => {
+    const base = buildMuseArgv({ role: "developer", sessionId: SESSION, maxModelSteps: 5, prompt: "x" });
+    for (const bad of ["--yolo", "--disable-sandbox", "--disable-approval", "--trust-workspace", "-w", "--worktree=nested", "--preset", "--agents", "--permission-profile"]) {
+        const argv = [...base.slice(0, -1), bad, "x"];
+        assert.equal(code(() => assertMuseArgv(argv, "developer")), "invalid_argv", bad);
+    }
+    const relaxed = base.map((a) => (a === "restricted" ? "proxy-only" : a));
+    assert.equal(code(() => assertMuseArgv(relaxed, "developer")), "invalid_argv");
+    const prompted = input(fixture(), "developer", { prompt: "--yolo" });
+    assert.equal(code(() => prepareMuseAttempt(prompted)), "invalid_input");
+});
+test("ambient Muse config, env, and workspace files cannot expand the attempt", () => {
+    const fx = fixture();
+    const ambientSettings = path.join(fx.operatorConfigHome, "muse", "settings.json");
+    const ambientBody = JSON.stringify({
+        schema_version: 1,
+        mcpServers: { evil: { type: "streamable-http", url: "http://evil.invalid/mcp", mode: "optional" } },
+        run: { workflow_trigger_mode: "auto", subagent_delegation_mode: "auto" },
+    });
+    fs.writeFileSync(ambientSettings, ambientBody);
+    fs.writeFileSync(path.join(fx.worktree, ".mcp.json"), '{"mcpServers":{"workspace-evil":{"command":"sh"}}}');
+    const attempt = prepareMuseAttempt(input(fx, "developer", {
+        env: {
+            PATH: "/usr/bin",
+            HOME: os.homedir(),
+            XDG_CONFIG_HOME: fx.operatorConfigHome,
+            XDG_DATA_HOME: "/operator/data",
+            META_API_KEY: API_KEY,
+            MUSE_PRESET: "yolo",
+            MUSE_NO_AUTO_UPDATE: "0",
+            CODEX_HOME: "/operator/codex",
+            LC_ALL: "C",
+        },
+    }));
+    try {
+        assert.deepEqual(Object.keys(attempt.settings.mcpServers), ["agent-deck"]);
+        assert.equal(attempt.env.XDG_CONFIG_HOME, path.join(attempt.root, "config"));
+        assert.equal(attempt.env.XDG_DATA_HOME, path.join(attempt.root, "data"));
+        assert.equal(attempt.env.MUSE_NO_AUTO_UPDATE, "1");
+        for (const dropped of ["META_API_KEY", "MUSE_PRESET", "CODEX_HOME"])
+            assert.equal(dropped in attempt.env, false, dropped);
+        assert.equal(attempt.env.LC_ALL, "C");
+        assert.equal(attempt.argv.includes("--trust-workspace"), false);
+        assert.ok(attempt.argv.includes("--no-foreign-personal-context"));
+        assert.ok(!fs.readFileSync(attempt.settingsPath, "utf8").includes("evil"));
+        // Someone widening the per-attempt config after the fact is caught before spawn.
+        const good = fs.readFileSync(attempt.settingsPath, "utf8");
+        const tamper = (mut) => {
+            const s = JSON.parse(good);
+            mut(s);
+            fs.writeFileSync(attempt.settingsPath, JSON.stringify(s));
+            return code(() => attempt.verify());
+        };
+        assert.equal(tamper((s) => (s.mcpServers.extra = { type: "streamable-http", url: DECK_URL, mode: "required" })), "invalid_settings");
+        assert.equal(tamper((s) => (s.run.subagent_delegation_mode = "auto")), "invalid_settings");
+        assert.equal(tamper((s) => (s.mcpServers["agent-deck"].disabled_tools = [])), "invalid_settings");
+        assert.equal(tamper((s) => delete s.run), "invalid_settings");
+        fs.writeFileSync(attempt.settingsPath, good);
+        fs.writeFileSync(path.join(path.dirname(attempt.settingsPath), "config.toml"), "x");
+        assert.equal(code(() => attempt.verify()), "invalid_settings");
+        fs.rmSync(path.join(path.dirname(attempt.settingsPath), "config.toml"));
+        fs.writeFileSync(attempt.settingsPath, "{not json");
+        assert.equal(code(() => attempt.verify()), "invalid_settings");
+        fs.rmSync(attempt.settingsPath);
+        assert.equal(code(() => attempt.verify()), "invalid_settings");
+    }
+    finally {
+        attempt.cleanup();
+    }
+    assert.equal(fs.readFileSync(ambientSettings, "utf8"), ambientBody);
+});
+test("required Agent Deck server: optional mode, bad url, and missing identity fail before spawn", () => {
+    const fx = fixture();
+    const attempt = prepareMuseAttempt(input(fx, "developer"));
+    try {
+        const s = JSON.parse(fs.readFileSync(attempt.settingsPath, "utf8"));
+        s.mcpServers["agent-deck"].mode = "optional";
+        fs.writeFileSync(attempt.settingsPath, JSON.stringify(s));
+        assert.equal(code(() => attempt.verify()), "invalid_settings");
+        s.mcpServers["agent-deck"].mode = "required";
+        s.mcpServers["agent-deck"].required = true;
+        fs.writeFileSync(attempt.settingsPath, JSON.stringify(s));
+        assert.equal(code(() => attempt.verify()), "invalid_settings");
+    }
+    finally {
+        attempt.cleanup();
+    }
+    const bad = [
+        { agentDeck: { url: "not a url", deckId: "d", workspace: fx.worktree } },
+        { agentDeck: { url: "file:///etc/passwd", deckId: "d", workspace: fx.worktree } },
+        { agentDeck: { url: "http://u:p@127.0.0.1:1110/mcp", deckId: "d", workspace: fx.worktree } },
+        { agentDeck: { url: DECK_URL, deckId: " ", workspace: fx.worktree } },
+        { agentDeck: { url: DECK_URL, deckId: "d", workspace: SCRATCH } },
+        { sessionId: "not-a-uuid" },
+        { maxModelSteps: 0 },
+        { credential: { kind: "auth-file", path: path.join(fx.baseDir, "missing.json") } },
+        { credential: { kind: "api-key", apiKey: "  " } },
+    ];
+    for (const over of bad) {
+        assert.equal(code(() => prepareMuseAttempt(input(fx, "developer", over))), "invalid_input", JSON.stringify(over));
+    }
+    assert.deepEqual(fs.readdirSync(fx.baseDir), [], "nothing is written when validation fails");
+});
+test("worktree and config must be separate, and neither may sit under a temp dir", () => {
+    const fx = fixture();
+    assert.equal(code(() => prepareMuseAttempt(input(fx, "developer", { baseDir: fx.worktree }))), "unsafe_path");
+    const inside = path.join(fx.worktree, "attempts");
+    fs.mkdirSync(inside);
+    assert.equal(code(() => prepareMuseAttempt(input(fx, "developer", { baseDir: inside }))), "unsafe_path");
+    const tmpWorktree = fs.mkdtempSync(path.join(os.tmpdir(), "muse-config-tmp-"));
+    try {
+        const agentDeck = { url: DECK_URL, deckId: "d", workspace: tmpWorktree };
+        assert.equal(code(() => prepareMuseAttempt(input(fx, "developer", { worktreePath: tmpWorktree, agentDeck }))), "unsafe_path");
+        assert.equal(code(() => prepareMuseAttempt(input(fx, "developer", { baseDir: tmpWorktree }))), "unsafe_path");
+    }
+    finally {
+        fs.rmSync(tmpWorktree, { recursive: true, force: true });
+    }
+});
+test("cleanup removes ephemeral config and auth link but never operator-owned state", () => {
+    const fx = fixture();
+    const attempt = prepareMuseAttempt(input(fx, "developer"));
+    const link = path.join(path.dirname(attempt.settingsPath), "auth.json");
+    assert.ok(fs.lstatSync(link).isSymbolicLink());
+    assert.equal(fs.readFileSync(link, "utf8"), '{"token":"operator-owned"}');
+    fs.writeFileSync(path.join(attempt.root, "data", "session.jsonl"), "muse wrote this");
+    const other = path.join(fx.baseDir, "someone-elses-dir");
+    fs.mkdirSync(other);
+    attempt.cleanup();
+    attempt.cleanup();
+    assert.equal(fs.existsSync(attempt.root), false);
+    assert.equal(fs.readFileSync(fx.operatorAuth, "utf8"), '{"token":"operator-owned"}');
+    assert.ok(fs.existsSync(other));
+    assert.ok(fs.existsSync(fx.worktree));
+    assert.deepEqual(fs.readdirSync(fx.worktree), [], "nothing is written into the worktree");
+    // Without the sentinel the dir is not ours to delete.
+    const foreign = prepareMuseAttempt(input(fx, "reviewer"));
+    fs.rmSync(path.join(foreign.root, ".dealer-muse-attempt"));
+    foreign.cleanup();
+    assert.ok(fs.existsSync(foreign.root));
+});
+test("cleanup is retryable: a transient rmSync failure does not strand the attempt dir", () => {
+    const fx = fixture();
+    const attempt = prepareMuseAttempt(input(fx, "developer"));
+    const link = path.join(path.dirname(attempt.settingsPath), "auth.json");
+    const realRm = fs.rmSync;
+    const rm = mock.method(fs, "rmSync", () => {
+        throw Object.assign(new Error("EBUSY: transient"), { code: "EBUSY" });
+    });
+    try {
+        assert.throws(() => attempt.cleanup(), /EBUSY/);
+        assert.throws(() => attempt.cleanup(), /EBUSY/, "a failed cleanup is not terminal");
+        assert.ok(fs.existsSync(attempt.settingsPath));
+        assert.ok(fs.lstatSync(link).isSymbolicLink());
+    }
+    finally {
+        rm.mock.restore();
+    }
+    assert.equal(fs.rmSync, realRm);
+    attempt.cleanup();
+    assert.equal(fs.existsSync(attempt.root), false);
+    assert.equal(fs.readFileSync(fx.operatorAuth, "utf8"), '{"token":"operator-owned"}');
+    assert.doesNotThrow(() => attempt.cleanup());
+});
+test("cleanup treats an already-removed dir as done", () => {
+    const fx = fixture();
+    const attempt = prepareMuseAttempt(input(fx, "developer"));
+    fs.rmSync(attempt.root, { recursive: true });
+    assert.doesNotThrow(() => attempt.cleanup());
+    assert.doesNotThrow(() => attempt.cleanup());
+});
+test("a failure before the sentinel is written still removes the new attempt dir", () => {
+    const fx = fixture();
+    const realWrite = fs.writeFileSync;
+    const write = mock.method(fs, "writeFileSync", ((file, ...rest) => {
+        if (String(file).endsWith(".dealer-muse-attempt"))
+            throw new Error("ENOSPC: injected");
+        return realWrite(file, ...rest);
+    }));
+    try {
+        assert.throws(() => prepareMuseAttempt(input(fx, "developer")), /ENOSPC: injected/);
+    }
+    finally {
+        write.mock.restore();
+    }
+    assert.deepEqual(fs.readdirSync(fx.baseDir), [], "no sentinel-less attempt dir is left behind");
+    assert.equal(fs.readFileSync(fx.operatorAuth, "utf8"), '{"token":"operator-owned"}');
+});
+test("if setup fails and the new dir cannot be removed, the failure names the stranded dir", () => {
+    const fx = fixture();
+    const realWrite = fs.writeFileSync;
+    const write = mock.method(fs, "writeFileSync", ((file, ...rest) => {
+        if (String(file).endsWith("settings.json"))
+            throw new Error("EIO: injected");
+        return realWrite(file, ...rest);
+    }));
+    const rm = mock.method(fs, "rmSync", () => {
+        throw new Error("EBUSY: transient");
+    });
+    let thrown;
+    try {
+        try {
+            prepareMuseAttempt(input(fx, "developer", { credential: { kind: "api-key", apiKey: API_KEY } }));
+        }
+        catch (err) {
+            thrown = err;
+        }
+    }
+    finally {
+        write.mock.restore();
+        rm.mock.restore();
+    }
+    assert.equal(thrown?.code, "cleanup_failed");
+    const [stranded] = fs.readdirSync(fx.baseDir);
+    assert.ok(stranded);
+    assert.ok(thrown.message.includes(stranded));
+    assert.ok(!thrown.message.includes(API_KEY));
+    // Nothing tracks it any more, so the operator removes it; the sentinel makes it identifiable.
+    assert.ok(fs.existsSync(path.join(fx.baseDir, stranded, ".dealer-muse-attempt")));
+});
+test("an unwritable base dir fails without leaving a partial attempt", () => {
+    const fx = fixture();
+    fs.chmodSync(fx.baseDir, 0o500);
+    try {
+        assert.throws(() => prepareMuseAttempt(input(fx, "developer")));
+    }
+    finally {
+        fs.chmodSync(fx.baseDir, 0o700);
+    }
+    assert.deepEqual(fs.readdirSync(fx.baseDir), []);
+});
+test("api key never reaches argv, env, disk, or error text; redact scrubs it", () => {
+    const fx = fixture();
+    const attempt = prepareMuseAttempt(input(fx, "developer", { credential: { kind: "api-key", apiKey: API_KEY } }));
+    try {
+        assert.equal(attempt.stdin, `${API_KEY}\n`);
+        assert.ok(attempt.argv.includes("--api-key-stdin"));
+        assert.ok(!JSON.stringify(attempt.argv).includes(API_KEY));
+        assert.ok(!JSON.stringify(attempt.env).includes(API_KEY));
+        for (const file of walk(attempt.root))
+            assert.ok(!fs.readFileSync(file, "utf8").includes(API_KEY), file);
+        assert.ok(!fs.existsSync(path.join(path.dirname(attempt.settingsPath), "auth.json")));
+        assert.doesNotThrow(() => attempt.verify());
+        const leaked = `fatal: key ${API_KEY} rejected; META_API_KEY=other-secret-value; Authorization: Bearer abcdef1234567890`;
+        const scrubbed = attempt.redact(leaked);
+        assert.ok(!scrubbed.includes(API_KEY));
+        assert.ok(!scrubbed.includes("other-secret-value"));
+        assert.ok(!scrubbed.includes("abcdef1234567890"));
+    }
+    finally {
+        attempt.cleanup();
+    }
+    for (const over of [{ sessionId: "bad" }, { prompt: "-x" }, {}]) {
+        try {
+            // The `{}` case goes through the pinned entry point, which refuses on NOT-177 evidence.
+            const prepare = Object.keys(over).length === 0 ? prepareMuseAttemptPinned : prepareMuseAttempt;
+            prepare(input(fx, "developer", { credential: { kind: "api-key", apiKey: API_KEY }, ...over }));
+            assert.fail("expected refusal");
+        }
+        catch (err) {
+            assert.ok(err instanceof Error && err.name === "MuseIsolationError");
+            assert.ok(!err.message.includes(API_KEY));
+            assert.ok(!String(err.stack).includes(API_KEY));
+        }
+    }
+    assert.deepEqual(fs.readdirSync(fx.baseDir), []);
+});
+test("callers cannot supply enforcement evidence: an injected evidence field is ignored", () => {
+    for (const role of ["developer", "reviewer"]) {
+        const fx = fixture();
+        const forged = { ...input(fx, role), evidence: ENFORCED };
+        assert.equal(code(() => prepareMuseAttemptPinned(forged)), "unenforceable_restriction", role);
+        assert.deepEqual(fs.readdirSync(fx.baseDir), []);
+    }
+});
+test("launch contract: cwd is the real worktree and argv/env/cwd/stdin must match exactly", () => {
+    const fx = fixture();
+    const link = path.join(fx.baseDir, "worktree-link");
+    fs.symlinkSync(fx.worktree, link);
+    const attempt = prepareMuseAttempt(input(fx, "developer", { worktreePath: link }));
+    try {
+        assert.equal(attempt.cwd, fs.realpathSync(fx.worktree));
+        assert.doesNotThrow(() => attempt.verify());
+        assert.doesNotThrow(() => attempt.verify({ cwd: attempt.cwd, argv: [...attempt.argv], env: { ...attempt.env }, stdin: attempt.stdin }));
+        // Returned data is immutable.
+        assert.throws(() => attempt.argv.push("--yolo"));
+        assert.throws(() => (attempt.env.XDG_CONFIG_HOME = "/ambient"));
+        assert.throws(() => (attempt.cwd = "/"));
+        assert.throws(() => (attempt.settings.mcpServers.extra = {}));
+        // A consumer that builds its own launch is checked against the approved one.
+        const launch = { cwd: attempt.cwd, argv: [...attempt.argv], env: { ...attempt.env }, stdin: attempt.stdin };
+        const without = (flag, n = 1) => {
+            const i = launch.argv.indexOf(flag);
+            return [...launch.argv.slice(0, i), ...launch.argv.slice(i + n)];
+        };
+        const widened = {
+            "spawn from server dir": { ...launch, cwd: process.cwd() },
+            "spawn from parent dir": { ...launch, cwd: path.dirname(fx.worktree) },
+            "drop --disable-web-tools": { ...launch, argv: without("--disable-web-tools") },
+            "drop --approval-judge off": { ...launch, argv: without("--approval-judge", 2) },
+            "add --base-url": { ...launch, argv: [...launch.argv.slice(0, -1), "--base-url", "http://evil.invalid", launch.argv.at(-1)] },
+            "duplicate flag": { ...launch, argv: [...launch.argv.slice(0, -1), "--json", launch.argv.at(-1)] },
+            "change prompt": { ...launch, argv: [...launch.argv.slice(0, -1), "other prompt"] },
+            "ambient XDG_CONFIG_HOME": { ...launch, env: { ...launch.env, XDG_CONFIG_HOME: fx.operatorConfigHome } },
+            "ambient XDG_DATA_HOME": { ...launch, env: { ...launch.env, XDG_DATA_HOME: "/operator/data" } },
+            "extra env": { ...launch, env: { ...launch.env, META_API_KEY: API_KEY } },
+            "dropped env": { ...launch, env: Object.fromEntries(Object.entries(launch.env).filter(([k]) => k !== "MUSE_NO_AUTO_UPDATE")) },
+            "injected stdin": { ...launch, stdin: "key\n" },
+        };
+        for (const [name, bad] of Object.entries(widened)) {
+            assert.equal(code(() => attempt.verify(bad)), "invalid_argv", name);
+        }
+    }
+    finally {
+        attempt.cleanup();
+    }
+});
+test("verification is snapshotted: mutating the original input cannot retarget the MCP server", () => {
+    const fx = fixture();
+    const original = input(fx, "developer");
+    const attempt = prepareMuseAttempt(original);
+    try {
+        // Attacker rewrites the caller's objects and settings.json to a different deck / URL.
+        original.agentDeck.url = "http://evil.invalid/mcp";
+        original.agentDeck.deckId = "deck-evil";
+        original.credential = { kind: "api-key", apiKey: API_KEY };
+        original.role = "reviewer";
+        const evil = JSON.parse(fs.readFileSync(attempt.settingsPath, "utf8"));
+        evil.mcpServers["agent-deck"].url = "http://evil.invalid/mcp";
+        evil.mcpServers["agent-deck"].headers["x-agent-deck-deck-id"] = "deck-evil";
+        fs.writeFileSync(attempt.settingsPath, JSON.stringify(evil));
+        assert.equal(code(() => attempt.verify()), "invalid_settings");
+        // Restoring the approved settings passes again, so verify compares against the snapshot.
+        evil.mcpServers["agent-deck"].url = DECK_URL;
+        evil.mcpServers["agent-deck"].headers["x-agent-deck-deck-id"] = "deck-123";
+        fs.writeFileSync(attempt.settingsPath, JSON.stringify(evil));
+        assert.doesNotThrow(() => attempt.verify());
+    }
+    finally {
+        attempt.cleanup();
+    }
+});
+test("no runtime export can produce a launchable attempt from caller-supplied evidence", async () => {
+    for (const mod of ["./muse-config.js", "./muse-config-core.js"]) {
+        const exported = (await import(mod));
+        assert.equal("prepareWithEvidence" in exported, false, mod);
+        assert.equal("museConfigTesting" in exported, false, mod);
+        // Only the pinned preparer returns a MuseAttempt-producing function; it takes exactly one argument.
+        for (const [name, value] of Object.entries(exported)) {
+            if (typeof value === "function" && /^prepare/.test(name))
+                assert.equal(value.length, 1, `${mod}#${name}`);
+        }
+    }
+    // The pinned core cannot be talked into success with a forged evidence argument or field.
+    const core = (await import("./muse-config-core.js"));
+    const fx = fixture();
+    const forged = () => core.prepareMuseAttempt(input(fx, "developer"), ENFORCED);
+    assert.equal(code(forged), "unenforceable_restriction");
+    assert.deepEqual(fs.readdirSync(fx.baseDir), []);
+});
+test("only muse-config.ts and tests import muse-config-core", () => {
+    const srcRoot = path.resolve(import.meta.dirname, "..");
+    const offenders = walk(srcRoot).filter((f) => {
+        if (!f.endsWith(".ts") || f.endsWith(".test.ts"))
+            return false;
+        if (path.basename(f) === "muse-config.ts" || path.basename(f) === "muse-config-core.ts")
+            return false;
+        return /muse-config-core/.test(fs.readFileSync(f, "utf8"));
+    });
+    assert.deepEqual(offenders, []);
+});

package/bundle/server/dist/runners/usage-cap.js

@@ -29,12 +29,11 @@ function fallbackUntil(nowMs = Date.now()) {
 function capReason(runtime, detail) {
     return `${runtime} usage capped — ${detail}`;
 }
+// `status` is the verdict on the plan window. `overageStatus` only says whether pay-as-you-go
+// overage is available: orgs with overage disabled report "rejected" on every event of a healthy
+// session (status "allowed", isUsingOverage false), so it must not open a deferral by itself.
 function isHardCapRateLimitInfo(info) {
-    if (info.status === "rejected")
-        return true;
-    if (info.overageStatus === "rejected")
-        return true;
-    return false;
+    return info.status === "rejected";
 }
 function signalFromRateLimitInfo(runtime, info, evidence, nowMs) {
     if (!isHardCapRateLimitInfo(info))

package/bundle/server/dist/runners/usage-cap.test.js

@@ -26,6 +26,15 @@ test("Claude rate_limit_event rejected writes runtime_availability with resetsAt
         assert.equal(avail.until, cap.unavailableUntil);
     }
 });
+test("allowed rate_limit_event with overage rejected (org disabled overage) is not a cap", () => {
+    const raw = [
+        '{"type":"rate_limit_event","rate_limit_info":{"status":"allowed","resetsAt":1784283600,"rateLimitType":"five_hour","overageStatus":"rejected","overageDisabledReason":"org_level_disabled_until","isUsingOverage":false,"unifiedWindows":{"five_hour":{"utilization":0.17,"resetsAt":1784283600}}}}',
+        '{"type":"result","is_error":false,"result":"done"}',
+    ].join("\n");
+    assert.equal(detectUsageCapFromNdjson(raw, "claude_code"), null);
+    assert.equal(recordUsageCapFromEvents(parseNdjson(raw), "claude_code"), null);
+    assert.equal(runtimeAvailability("claude_code").available, true);
+});
 test("allowed_warning rate_limit_event is ignored (hard cap only)", () => {
     const raw = [
         '{"type":"rate_limit_event","rate_limit_info":{"status":"allowed_warning","resetsAt":1784283600,"rateLimitType":"five_hour"}}',

package/bundle/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/server",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "type": "module",
   "main": "dist/index.js",
   "files": [
@@ -22,7 +22,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@agent-dealer/shared": "1.1.0",
+    "@agent-dealer/shared": "1.1.2",
     "@fastify/cors": "^11.0.1",
     "@fastify/static": "^8.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/bundle/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/shared",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/dist/start.js

@@ -124,6 +124,24 @@ async function ensurePortAvailable(host, port, probe) {
     }
     return null;
 }
+/**
+ * `--force` restart: stop the existing instance, then require the port to actually be free.
+ * `runStop()` can return 0 while a listener survives (an explicit AGENT_DEALER_HOME without run.json
+ * refuses to sweep the port), and `ensurePortAvailable` treats a healthy agent-dealer as available —
+ * so without this check the replacement server would launch onto an occupied port.
+ */
+async function stopForForcedRestart(host, port) {
+    console.log("[agent-dealer] Restarting existing instance (--force) ...");
+    await runStop();
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    if ((await probeAgentDealer(host, port)).up) {
+        console.error(`[agent-dealer] --force could not stop the agent-dealer still listening on ${host}:${port}.`);
+        console.error("[agent-dealer] It is not owned by this AGENT_DEALER_HOME, so it was left running.");
+        console.error(`[agent-dealer] Stop it from its own home, or kill it manually: lsof -ti :${port} -sTCP:LISTEN | xargs kill`);
+        return 1;
+    }
+    return null;
+}
 export async function runStart(options = {}) {
     const envFile = loadProdEnvFile();
     const home = prodHomeDir();
@@ -142,9 +160,10 @@ export async function runStart(options = {}) {
         const probe = await probeAgentDealer(host, port);
         if (probe.up) {
             if (options.force) {
-                console.log("[agent-dealer] Restarting existing instance (--force) ...");
-                await runStop();
-                await new Promise((resolve) => setTimeout(resolve, 500));
+                const stopError = await stopForForcedRestart(host, port);
+                if (stopError !== null) {
+                    return stopError;
+                }
             }
             else {
                 printRunningEndpoints(base, uiDist);
@@ -152,8 +171,7 @@ export async function runStart(options = {}) {
                 return 0;
             }
         }
-        const refreshedProbe = options.force ? await probeAgentDealer(host, port) : probe;
-        const portError = await ensurePortAvailable(host, port, refreshedProbe);
+        const portError = await ensurePortAvailable(host, port, options.force ? await probeAgentDealer(host, port) : probe);
         if (portError !== null) {
             return portError;
         }
@@ -163,9 +181,10 @@ export async function runStart(options = {}) {
     const probe = await probeAgentDealer(host, port);
     if (probe.up) {
         if (options.force) {
-            console.log("[agent-dealer] Restarting existing instance (--force) ...");
-            await runStop();
-            await new Promise((resolve) => setTimeout(resolve, 500));
+            const stopError = await stopForForcedRestart(host, port);
+            if (stopError !== null) {
+                return stopError;
+            }
         }
         else {
             printRunningEndpoints(base, uiDist);
@@ -173,8 +192,7 @@ export async function runStart(options = {}) {
             return 0;
         }
     }
-    const refreshedProbe = options.force ? await probeAgentDealer(host, port) : probe;
-    const portError = await ensurePortAvailable(host, port, refreshedProbe);
+    const portError = await ensurePortAvailable(host, port, options.force ? await probeAgentDealer(host, port) : probe);
     if (portError !== null) {
         return portError;
     }

package/dist/stop.js

@@ -39,17 +39,25 @@ export async function runStop() {
         }
         clearRunState();
     }
+    // An explicit AGENT_DEALER_HOME means "only this home" (smoke tests, side-by-side installs).
+    // Its run.json is the sole proof of ownership, so never sweep the port: with no run state the
+    // port falls back to the bundled 2222, which belongs to the default install.
+    const isolatedHome = Boolean(process.env.AGENT_DEALER_HOME?.trim());
     let probe = await probeAgentDealer(host, port);
     if (probe.up) {
-        for (const pid of listListeningPids(port)) {
-            if (terminatePid(pid, `listener on :${port}`)) {
-                stopped += 1;
+        if (!isolatedHome) {
+            for (const pid of listListeningPids(port)) {
+                if (terminatePid(pid, `listener on :${port}`)) {
+                    stopped += 1;
+                }
             }
         }
-        await waitForShutdown(host, port);
-        probe = await probeAgentDealer(host, port);
+        if (!isolatedHome || state) {
+            await waitForShutdown(host, port);
+            probe = await probeAgentDealer(host, port);
+        }
     }
-    if (probe.up) {
+    if (probe.up && (!isolatedHome || state)) {
         console.warn("[agent-dealer] agent-dealer still responds on configured port. Kill remaining processes manually:");
         console.warn(`  lsof -ti :${port} -sTCP:LISTEN | xargs kill`);
         return 1;

package/dist/stop.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/stop.test.js

@@ -0,0 +1,131 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runStart } from "./start.js";
+import { runStop } from "./stop.js";
+const HEALTH_SERVER = `
+const http = require("node:http");
+const server = http.createServer((req, res) => {
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify({ ok: true }));
+});
+server.listen(0, "127.0.0.1", () => console.log(server.address().port));
+`;
+/** A separate process answering /health, standing in for an agent-dealer server. */
+async function startFakeServer() {
+    const child = spawn(process.execPath, ["-e", HEALTH_SERVER], { stdio: ["ignore", "pipe", "inherit"] });
+    const port = await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.stdout.once("data", (chunk) => resolve(Number(String(chunk).trim())));
+    });
+    return { child, port };
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitUntilDead(pid) {
+    for (let i = 0; i < 25; i += 1) {
+        if (!isAlive(pid))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return false;
+}
+async function withEnv(env, fn) {
+    const saved = Object.fromEntries(Object.keys(env).map((key) => [key, process.env[key]]));
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    try {
+        await fn();
+    }
+    finally {
+        for (const [key, value] of Object.entries(saved)) {
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+    }
+}
+function tempHome() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), "agent-dealer-stop-"));
+}
+test("stop with an explicit AGENT_DEALER_HOME and no run state never kills a listener on the fallback port", async () => {
+    const { child, port } = await startFakeServer();
+    const home = tempHome();
+    try {
+        await withEnv({ AGENT_DEALER_HOME: home, PORT: String(port), WEB_PORT: undefined }, async () => {
+            assert.equal(await runStop(), 0);
+        });
+        assert.equal(isAlive(child.pid), true, "the unrelated listener must survive an isolated-home stop");
+    }
+    finally {
+        child.kill("SIGKILL");
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+});
+test("stop with an explicit AGENT_DEALER_HOME still terminates the pids recorded in its run.json", async () => {
+    const { child, port } = await startFakeServer();
+    const home = tempHome();
+    fs.writeFileSync(path.join(home, "run.json"), JSON.stringify({ host: "127.0.0.1", port, serverPid: child.pid, cliPid: 2 ** 22, startedAt: new Date().toISOString() }));
+    try {
+        await withEnv({ AGENT_DEALER_HOME: home, PORT: undefined, WEB_PORT: undefined }, async () => {
+            assert.equal(await runStop(), 0);
+        });
+        assert.equal(await waitUntilDead(child.pid), true);
+    }
+    finally {
+        child.kill("SIGKILL");
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+});
+test("stop on the default home keeps sweeping the port when run.json is lost", async () => {
+    const { child, port } = await startFakeServer();
+    const home = tempHome();
+    try {
+        await withEnv({ AGENT_DEALER_HOME: undefined, HOME: home, USERPROFILE: home, PORT: String(port), WEB_PORT: undefined }, async () => {
+            assert.equal(await runStop(), 0);
+        });
+        assert.equal(await waitUntilDead(child.pid), true);
+    }
+    finally {
+        child.kill("SIGKILL");
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+});
+async function assertForcedStartRefusesUnownedListener(options) {
+    const { child, port } = await startFakeServer();
+    const home = tempHome();
+    try {
+        await withEnv({ AGENT_DEALER_HOME: home, PORT: String(port), WEB_PORT: undefined }, async () => {
+            // The isolated-home stop leaves the listener up (no run.json = no proof of ownership).
+            // Forced start must fail instead of launching a second server onto the occupied port.
+            assert.equal(await runStart({ force: true, daemon: options.daemon, port }), 1);
+        });
+        assert.equal(isAlive(child.pid), true, "the unrelated listener must survive a forced start");
+        assert.equal(fs.existsSync(path.join(home, "run.json")), false, "no run state may be written for a server that never launched");
+    }
+    finally {
+        child.kill("SIGKILL");
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+}
+test("start --force in the foreground fails when the isolated-home stop leaves a listener up", async () => {
+    await assertForcedStartRefusesUnownedListener({ daemon: false });
+});
+test("start --daemon --force fails when the isolated-home stop leaves a listener up", async () => {
+    await assertForcedStartRefusesUnownedListener({ daemon: true });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dealer",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Human control plane for agent execution — queue, plan approval, audit",
   "license": "MIT",
   "type": "module",