@brutalsystems/muster 0.7.14 → 0.7.16

package/README.md

@@ -157,7 +157,10 @@ 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:** each agent has its own session on the dedicated `muster` tmux
-  server. Opening or exiting one agent does not switch another agent's viewer.
+  server. `MUSTER_TMUX_SERVER` names a different one, for a caller that must not
+  share the machine's Muster server — Muster's own test suite sets it, so a gate
+  run cannot leave sessions beside yours. Opening or exiting one agent does not
+  switch another agent's viewer.
   Watchable and attachable; survives the CLI or MCP server exiting.
   Use the returned attach hint to reconnect to that agent.
 - **pty:** not watchable or attachable. The CLI prints the peer record and stays
@@ -564,36 +567,62 @@ under one makes a launch state which account it runs as instead of silently
 inheriting whatever the environment happened to imply.
 
 ```sh
-muster setup-identity --identity work --agent claude --token-env CLAUDE_WORK_TOKEN
+muster setup-identity --identity work --agent claude --interactive
 muster setup-identity --identity ci-bot --agent codex
 muster setup-identity --identity research --agent opencode
 ```
 
-`--token-env` names the environment variable holding a Claude Code token (from
-`claude setup-token`) — never the token itself. It applies to Claude **only**,
-and Claude **requires** it: Claude's keychain credential is keyed to the
+Claude needs a credential of its own: its keychain credential is keyed to the
 template directory's own path, and a launch runs from a per-launch copy whose
 path hashes to a different keychain service name, so a token is the only thing
 that can authenticate a Claude identity launch. `muster run --identity` refuses
-a Claude identity without one rather than spawning an agent that cannot log in.
-Codex and OpenCode authenticate from an auth file inside the template, so
-`--token-env` is refused for them — it could only ever add a way for the launch
-to fail.
+a Claude identity with neither route configured rather than spawning an agent
+that cannot log in. There are two ways to give it one:
+
+- **`--interactive` (recommended).** Runs `claude setup-token` itself inside a
+  pty with your terminal attached both ways — you see the flow and approve the
+  browser step, and anything it asks you (the `Paste code here if prompted:`
+  fallback, say, which is what an ssh session gets) reaches it from your
+  keyboard. It captures the token from the output and stores it at
+  `~/.muster/identities/<name>/token`, mode `0600` — the same directory
+  Codex and OpenCode identities already hold their own `auth.json` in. The
+  command prints a redacted confirmation of what it stored, never the token
+  (`muster identities` later reports only that a stored token is present). If
+  the login's output format ever changes so the token isn't recognised, this
+  fails open: nothing is redacted or captured, the token appears exactly as it
+  does today, and the command says it could not store one and points you at
+  `--token-env` to record the one now on your screen. It needs a terminal, and
+  refuses when stdin is not one.
+- **`--token-env NAME`**, for a machine that should keep no credential at
+  rest — CI, say. It names the environment variable holding a Claude Code
+  token (from a `claude setup-token` run yourself) — never the token itself.
+  It applies to Claude **only**; Codex and OpenCode authenticate from an auth
+  file inside the template, so `--token-env` is refused for them — it could
+  only ever add a way for the launch to fail.
+
+An identity holds exactly one of these routes at a time: storing a token
+clears a declared `--token-env`, and passing `--token-env` deletes a stored
+token. `setup-identity` says which route it removed, if either. Passing
+`--interactive` and `--token-env` in the same command is refused rather than
+resolved by precedence — they ask for opposite things, and choosing one for
+you would be choosing where the credential lives.
 
 `setup-identity` creates the template (or reuses an existing one for the same
-agent — it refuses to repurpose one that belongs to a different agent),
-prints the **one-time login** for that agent to run yourself, and reports
-whether a credential is already configured:
+agent — it refuses to repurpose one that belongs to a different agent) and
+reports whether a credential is already configured. Without `--interactive`
+it prints the **one-time login** for that agent to run yourself instead of
+running it for you:
 
 ```sh
-CLAUDE_CONFIG_DIR=~/.muster/identities/work claude setup-token   # then export it
+CLAUDE_CONFIG_DIR=~/.muster/identities/work claude setup-token   # then export it, or use --interactive
 CODEX_HOME=~/.muster/identities/ci-bot codex login
 OPENCODE_CONFIG_DIR=~/.muster/identities/research opencode auth login
 ```
 
-Muster never performs that login itself — each is an interactive OAuth flow,
-and a command that appeared to do it for you would be hiding a credential
-prompt. Run the printed command, complete the flow, then check the result:
+Muster never performs a login without `--interactive` — each is an
+interactive OAuth flow, and a command that appeared to do it for you without
+showing you the flow would be hiding a credential prompt. Run the printed
+command, complete the flow, then check the result:
 
 ```sh
 muster identities
@@ -633,20 +662,27 @@ configuration.
 Five things worth stating plainly, because each is a sharp edge:
 
 1. **`muster identities` reports *configured*, never *valid*.** A keychain
-   item, an auth file or a set variable proves a credential exists — not that
-   it still works. Tokens expire and are revoked; there is no way to check
-   that without exercising the credential, and `identities` does not do that.
-2. **The identity store holds credentials at rest** for Codex and OpenCode,
-   because their own logins write auth files directly into it. Directories are
-   `0700`, and deleting an identity deletes a credential — there is no
-   separate secret to revoke elsewhere first. Claude Code is the exception:
-   its credential lives in the macOS keychain (scoped to the identity's
-   directory path), or is supplied by `--token-env`, never as a file in the
-   identity directory.
-3. **Use `claude setup-token` with `--token-env`, not `ANTHROPIC_API_KEY`.**
-   The OAuth token from `setup-token` bills the account's Claude subscription.
-   An `ANTHROPIC_API_KEY` silently moves the same account onto pay-per-token
-   API billing instead — same agent, very different bill, no error either way.
+   item, an auth file, a stored token or a set variable proves a credential
+   exists — not that it still works. Tokens expire and are revoked; there is
+   no way to check that without exercising the credential, and `identities`
+   does not do that.
+2. **The identity store holds credentials at rest**, for every agent that
+   keeps one there. Codex and OpenCode always do, because their own logins
+   write auth files directly into the template. A Claude identity created
+   with `--interactive` does too, at `~/.muster/identities/<name>/token` —
+   the same directory, the same `0700`/`0600` protection, nothing more:
+   storing it does not make it any safer at rest than Codex's or OpenCode's
+   `auth.json` sitting right beside it, it just makes Claude consistent with
+   them instead of relying on the operator's shell rc file. Directories are
+   `0700`, and deleting an identity deletes whatever credential it holds —
+   there is no separate secret to revoke elsewhere first. The one route with
+   nothing at rest is `--token-env`: it names a variable instead, so the
+   credential lives only in whichever environment sets that variable.
+3. **Use `--interactive`, or `claude setup-token` with `--token-env` — never
+   `ANTHROPIC_API_KEY`.** The OAuth token from `setup-token` bills the
+   account's Claude subscription. An `ANTHROPIC_API_KEY` silently moves the
+   same account onto pay-per-token API billing instead — same agent, very
+   different bill, no error either way.
 4. **A Claude identity's token is briefly written to disk during a launch.**
    The tmux host serialises the whole launch specification — environment
    included — to a temporary `launch.json` at mode `0600` and removes it once

package/dist/hosts/index.js

@@ -1,8 +1,20 @@
 import { TmuxHost } from "./tmux.js";
 import { PtyHost } from "./pty.js";
 import { MacosTerminalHost } from "./macos-terminal.js";
-export function hosts() {
-    return [new TmuxHost(), new PtyHost(), new MacosTerminalHost()];
+/**
+ * There is one Muster tmux server per machine, which is why the name is a
+ * default rather than a parameter everywhere. `MUSTER_TMUX_SERVER` overrides it
+ * for callers that must not share that server — the suite above all, whose
+ * launches would otherwise land beside a developer's real sessions on `-L
+ * muster` and stay there, since a tmux launch is meant to survive its parent
+ * exiting (#57).
+ */
+export function hosts(env = process.env) {
+    return [
+        new TmuxHost(env.MUSTER_TMUX_SERVER || undefined),
+        new PtyHost(),
+        new MacosTerminalHost(),
+    ];
 }
 export async function selectHost(id, drivers) {
     for (const driver of drivers)

package/dist/identity-auth.js

@@ -3,7 +3,8 @@ import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { promisify } from "node:util";
-import { identityPath } from "./identity-store.js";
+import { identityPath, IdentityError, } from "./identity-store.js";
+import { resolveCredential } from "./identity-token.js";
 const run = promisify(execFile);
 /**
  * Claude Code stores its credential in the macOS keychain under a service name
@@ -37,21 +38,35 @@ export async function identityAuthState(home, name, meta, env, probe = keychainH
     const no = (detail) => ({ state: "not-configured", detail });
     const yes = (detail) => ({ state: "configured", detail });
     if (meta.agent === "claude") {
-        if (meta.token_env)
-            return env[meta.token_env]
-                ? yes(`token variable ${meta.token_env} is set`)
-                : no(`token variable ${meta.token_env} is not set`);
+        // A broken credential must not take the whole listing down with it.
+        // `describeIdentities` calls this once per identity with no error handling
+        // of its own, so an IdentityError thrown here — an empty token file, an
+        // unreadable one — would make `muster identities` fail outright and report
+        // nothing about the identities that are fine. That is the same hazard the
+        // stale-grant comment in identity-cli.ts already names: a local problem
+        // turning into a total outage. Reported as a state, not raised.
+        let credential;
+        try {
+            credential = await resolveCredential(home, name, meta, env);
+        }
+        catch (e) {
+            return no(e instanceof IdentityError ? e.message : String(e));
+        }
+        if (credential.route === "env")
+            return credential.token
+                ? yes(`token variable ${credential.variable} is set`)
+                : no(`token variable ${credential.variable} is not set`);
+        if (credential.token)
+            return yes("a stored token is present");
         // A keychain item for the TEMPLATE's path proves the template is usable
         // where it sits, and nothing more. A launch never points Claude at the
         // template: it copies it, and the copy's path hashes to a DIFFERENT service
         // name with no fallback (see claudeKeychainService above). So the keychain
         // route cannot produce a launch, and reporting "configured" for it would
-        // promise one that dies at its deadline. `token_env` is the only route a
-        // Claude identity can launch under, so its absence is not-configured
-        // regardless of what the keychain holds.
+        // promise one that dies at its deadline.
         return no((await probe(claudeKeychainService(dir)))
-            ? "a keychain item exists for this identity's template path, but a launch runs from a copy whose path hashes to a different service name — mint a token with `claude setup-token` and name the variable with --token-env"
-            : "no credential for a launch — mint a token with `claude setup-token` and name the variable with --token-env");
+            ? "a keychain item exists for this identity's template path, but a launch runs from a copy whose path hashes to a different service name — run `setup-identity --interactive` to store a token instead"
+            : "no credential for a launch — run `setup-identity --interactive` to log in and store a token");
     }
     // Codex keeps a flat JSON auth file. OpenCode splits config from data: its
     // auth file lives under a data root the binary itself always suffixes with
@@ -59,7 +74,9 @@ export async function identityAuthState(home, name, meta, env, probe = keychainH
     // against the installed 1.18.32 binary and the real ~/.local/share/opencode
     // layout; see identity-copy.ts and task-4-report.md). The identity template
     // mirrors that shape under data/opencode/auth.json.
-    const file = meta.agent === "opencode" ? join("data", "opencode", "auth.json") : "auth.json";
+    const file = meta.agent === "opencode"
+        ? join("data", "opencode", "auth.json")
+        : "auth.json";
     return (await readsAsJson(join(dir, file)))
         ? yes(`${file} is present`)
         : no(`${file} is missing or unreadable — log in for this identity`);

package/dist/identity-cli.js

@@ -1,5 +1,7 @@
 import { identityAuthState } from "./identity-auth.js";
 import { IdentityError, identityDirExists, identityMetaSchema, identityNameSchema, identityPath, listIdentities, readIdentity, writeIdentity, } from "./identity-store.js";
+import { removeStoredToken, writeStoredToken, } from "./identity-token.js";
+import { captureClaudeToken, redactToken, } from "./identity-login.js";
 /**
  * The one-time login for each agent. Muster never performs it: each is an
  * interactive OAuth flow, and a command that appeared to do it for you would be
@@ -17,10 +19,12 @@ function loginCommand(agent, dir) {
 }
 export async function setupIdentity(opts) {
     const name = identityNameSchema.parse(opts.name);
-    // token_env is consumed ONLY by identityEnv's Claude branch, and
-    // identityAuthState ignores it for the others — while the launch path refuses
-    // when the named variable is unset. So on a codex or opencode identity it has
-    // exactly one effect: a new way to fail. Refused where the operator types it.
+    // token_env is consumed ONLY by `resolveCredential`, which both
+    // `identityAuthState` and the launch path reach exclusively from their Claude
+    // branch — and the launch path refuses when the named variable is unset. So on
+    // a codex or opencode identity, where the credential is an auth file the
+    // agent's own login writes into the template, it has exactly one effect: a new
+    // way to fail. Refused where the operator types it.
     if (opts.tokenEnv && opts.agent !== "claude")
         throw new IdentityError(name, `--token-env applies only to a claude identity; ${opts.agent} authenticates from an auth file in the template, and a token variable here would only add a way for the launch to fail`);
     // Distinguish "no such identity" from "an identity that is there but unusable".
@@ -52,6 +56,15 @@ export async function setupIdentity(opts) {
                 ? { token_env: existing.token_env }
                 : {}),
     });
+    // One route per identity. An operator naming a variable has chosen the env
+    // route, so a stored token is now dead weight. Order matters: remove the
+    // stale token BEFORE recording the env route. If removal fails, the identity
+    // holds neither route and reports not-configured — the operator re-runs and
+    // succeeds. Writing first fails worse: both routes coexist on the failure
+    // path, with a secret at rest that nothing reads.
+    let clearedRoute;
+    if (opts.tokenEnv !== undefined && (await removeStoredToken(opts.home, name)))
+        clearedRoute = `removed this identity's stored token; ${opts.tokenEnv} is now its credential`;
     if (created || tokenEnvChanged)
         await writeIdentity(opts.home, name, meta);
     const current = await readIdentity(opts.home, name);
@@ -61,8 +74,37 @@ export async function setupIdentity(opts) {
         path: dir,
         login: loginCommand(current.agent, dir),
         auth: await identityAuthState(opts.home, name, current, opts.env ?? process.env),
+        ...(clearedRoute ? { clearedRoute } : {}),
     };
 }
+/**
+ * Store a token as this identity's credential, and clear the other route.
+ *
+ * Clearing is not tidiness. An identity left with both a stored token and a
+ * declared `token_env` has an account that depends on whether a variable
+ * happens to be exported — exactly the defect storing the token exists to
+ * remove.
+ */
+export async function storeIdentityToken(opts) {
+    const name = identityNameSchema.parse(opts.name);
+    const meta = await readIdentity(opts.home, name); // throws if unusable
+    if (meta.agent !== "claude")
+        throw new IdentityError(name, `a token applies only to a claude identity; ${meta.agent} authenticates from an auth file its own login writes into the template`);
+    // Order matters, and not for tidiness. If the token were written first and
+    // clearing token_env then failed, the identity would hold BOTH routes — and
+    // `resolveCredential` prefers the env route, so the token just stored would be
+    // silently ignored while the command reported success. Clearing first fails
+    // the other way: an identity with neither route, which reports
+    // `not-configured` and tells the operator exactly what to do.
+    let clearedRoute;
+    if (meta.token_env) {
+        const { token_env: cleared, ...rest } = meta;
+        await writeIdentity(opts.home, name, identityMetaSchema.parse(rest));
+        clearedRoute = `cleared token_env ${cleared}; this identity now uses its stored token`;
+    }
+    await writeStoredToken(opts.home, name, opts.token);
+    return clearedRoute ? { clearedRoute } : {};
+}
 export async function describeIdentities(home, env, 
 /** Profile grants, so stale ones surface without a launch having to fail. */
 grants = {}) {
@@ -86,3 +128,69 @@ grants = {}) {
                 staleGrants.push({ profile, identity });
     return { identities, staleGrants };
 }
+/**
+ * The guided path: create the identity, run its login, store what comes back.
+ *
+ * `isTTY`, `write`, `env` and `stdin` are parameters rather than direct reads of
+ * `process` so the whole shipped path — refusal, capture, storage and note — is
+ * testable without a terminal, with a fake `claude` on `env.PATH`.
+ */
+export async function interactiveSetup(opts) {
+    const write = opts.write ?? ((t) => process.stdout.write(t));
+    if (!opts.isTTY)
+        throw new IdentityError(opts.name, "interactive setup needs a terminal; run it yourself, or use --token-env for an unattended machine");
+    const created = await setupIdentity({
+        home: opts.home,
+        name: opts.name,
+        agent: opts.agent,
+    });
+    if (opts.agent !== "claude")
+        return {
+            path: created.path,
+            stored: false,
+            note: `Run this once, then check with \`muster identities\`:\n\n    ${created.login}\n`,
+        };
+    write(`Running: claude setup-token\n${"─".repeat(50)}\n`);
+    const result = await captureClaudeToken({
+        dir: created.path,
+        env: opts.env ?? process.env,
+        onData: write,
+        ...(opts.stdin ? { stdin: opts.stdin } : {}),
+    });
+    write(`${"─".repeat(50)}\n`);
+    // Checked BEFORE the token branch, deliberately: a login that failed writes
+    // no credential even if something token-shaped went past on the way down.
+    //
+    // This is also the case where the child never started at all. node-pty does
+    // not throw for a missing executable — it exits 1 having emitted zero bytes —
+    // so an operator with no `claude` on PATH used to be told Muster could not
+    // parse output that never existed, with no identity name and no hint that
+    // nothing had run. The child's own output is the error here, whatever it was.
+    if (result.exitCode !== 0)
+        throw new IdentityError(opts.name, `\`claude setup-token\` failed (exit ${result.exitCode}) and no credential was stored; its own output above is the error. If nothing was printed above it could not be started at all — check that \`claude\` is on PATH.`);
+    if (result.token) {
+        const { clearedRoute } = await storeIdentityToken({
+            home: opts.home,
+            name: opts.name,
+            token: result.token,
+        });
+        return {
+            path: created.path,
+            stored: true,
+            note: `Token captured and stored (${redactToken(result.token)}). It was not printed here.` +
+                (clearedRoute ? `\n${clearedRoute}` : ""),
+        };
+    }
+    // Exit 0 and no match: the login worked and its output format changed. Fails
+    // open, so the token is above in clear and the operator has it.
+    //
+    // The one thing this must NOT say is "run --interactive again": a second run
+    // performs a second `claude setup-token` and mints a DIFFERENT token, so it
+    // can never store the one already in the scrollback. `--token-env` is the
+    // only route that can record it.
+    return {
+        path: created.path,
+        stored: false,
+        note: `Muster could not recognise a token in that output, so nothing was stored — but the login itself succeeded, and the token is above in clear. Record it by naming the variable that holds it:\n\n    export CLAUDE_TOKEN=<the token above>\n    muster setup-identity --identity ${opts.name} --agent claude --token-env CLAUDE_TOKEN\n`,
+    };
+}

package/dist/identity-copy.js

@@ -1,5 +1,6 @@
 import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import TOML from "@iarna/toml";
 import { identityPath } from "./identity-store.js";
 /**
  * What a copy must contain: enough to start authenticated, onboarded, and
@@ -63,7 +64,14 @@ export async function copyIdentity(home, name, meta, launchId) {
  * The variables the AGENT receives. Muster's own subprocesses never get these:
  * a version probe pointed at a per-launch copy answers the wrong question.
  */
-export function identityEnv(meta, copyPath, sourceEnv) {
+export function identityEnv(meta, copyPath, sourceEnv, 
+/**
+ * The already-resolved token. Resolved by the caller rather than here, because
+ * the file route needs async IO and because resolving it against the TEMPLATE
+ * keeps the number of on-disk copies of the secret at one — the per-launch
+ * copy never carries it.
+ */
+credential) {
     if (meta.agent === "codex")
         return { CODEX_HOME: copyPath };
     if (meta.agent === "opencode")
@@ -77,12 +85,9 @@ export function identityEnv(meta, copyPath, sourceEnv) {
             XDG_DATA_HOME: join(copyPath, "data"),
         };
     const env = { CLAUDE_CONFIG_DIR: copyPath };
-    if (meta.token_env) {
-        const token = sourceEnv[meta.token_env];
-        // Absence is the caller's problem to report before spawning; see run.ts.
-        if (typeof token === "string" && token.length)
-            env.CLAUDE_CODE_OAUTH_TOKEN = token;
-    }
+    // Absence is the caller's problem to report before spawning; see run.ts.
+    if (credential)
+        env.CLAUDE_CODE_OAUTH_TOKEN = credential;
     return env;
 }
 /**
@@ -122,3 +127,62 @@ export async function setWorkspaceTrust(copyPath, cwd) {
     data.projects = projects;
     await writeFile(file, JSON.stringify(data), { mode: 0o600 });
 }
+/**
+ * Set Codex's directory-trust flag for one directory, inside a copy Muster just
+ * created. Codex has its own gate, unrelated to Claude's: without a
+ * `[projects."<dir>"] trust_level = "trusted"` entry in the config.toml it
+ * reads, the TUI stops on "Do you trust the contents of this directory?" before
+ * it ever opens a thread. No thread is opened, so no thread-writer lock is
+ * written, so `resolveCodex` finds nothing and the launch burns its whole
+ * deadline reporting `no descendant runtime identity found`.
+ *
+ * A fresh identity copy has no `projects` table at all, which made EVERY Codex
+ * identity launch fail exactly that way — measured, not inferred: the pane was
+ * captured mid-launch sitting on the prompt while the copy filled with Codex's
+ * own sqlite state and never grew a `thread-writer-locks/` directory.
+ *
+ * `-c projects."<dir>".trust_level="trusted"` does NOT satisfy the gate. It
+ * parses and is accepted, and the prompt still appears: the check reads
+ * persisted config, so the entry has to be in the file.
+ *
+ * The user's real `~/.codex/config.toml` is never touched, for the same reason
+ * `setWorkspaceTrust` leaves the live `~/.claude.json` alone.
+ */
+export async function setCodexWorkspaceTrust(copyPath, cwd) {
+    const file = join(copyPath, "config.toml");
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (e) {
+        // A template that has never been logged into has no config.toml; Codex
+        // runs on defaults. Anything else — EACCES, EISDIR — is a real failure,
+        // and swallowing it would hand the agent a config missing every setting
+        // the template's own login wrote.
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    let data = {};
+    if (raw !== undefined)
+        try {
+            data = TOML.parse(raw);
+        }
+        catch (e) {
+            // A file that EXISTS and does not parse is not "no file yet". Codex would
+            // refuse it too, so writing over it trades one clear failure for a silent
+            // loss of the template's settings.
+            throw new Error(`${file} exists but is not valid TOML: ${String(e)}`);
+        }
+    const projects = (data.projects ?? {});
+    const existing = (projects[cwd] ?? {});
+    if (existing.trust_level === "trusted")
+        return;
+    projects[cwd] = { ...existing, trust_level: "trusted" };
+    data.projects = projects;
+    // Re-serialised rather than appended, so an entry the template already
+    // carries with a different trust_level is corrected instead of duplicated —
+    // a duplicate table is a TOML error and Codex would refuse the whole file.
+    // Comments and key order in the copy are lost; the copy is per-launch and
+    // machine-read, and the template it came from is untouched.
+    await writeFile(file, TOML.stringify(data), { mode: 0o600 });
+}

package/dist/identity-login.js

@@ -0,0 +1,314 @@
+/**
+ * A Claude long-lived OAuth token, as `claude setup-token` prints it. The length
+ * floor is what separates a real token from the literal word in help text.
+ */
+export const CLAUDE_TOKEN_PATTERN = /sk-ant-oat01-[A-Za-z0-9_-]{40,}/;
+/** The token's fixed literal prefix, used to detect an in-progress match. */
+const TOKEN_PREFIX = "sk-ant-oat01-";
+/** The character class the token body is drawn from, after the prefix. */
+const TOKEN_BODY_CHAR = /[A-Za-z0-9_-]/;
+/** Enough to recognise which token this is; never enough to use it. */
+export function redactToken(token) {
+    return `${token.slice(0, 12)}…${token.slice(-5)}`;
+}
+/**
+ * How many leading characters of `text` are safe to release right now — the
+ * rest, a trailing suffix, could still turn into (part of) a token given more
+ * input and must be held back.
+ *
+ * Two shapes count as "could still turn into a token":
+ *  - a trailing partial prefix of the literal `sk-ant-oat01-` (e.g. text
+ *    ending in `sk-ant-o` might still complete into the literal on the next
+ *    push), and
+ *  - an already-open run: the literal prefix followed by an unbroken run of
+ *    token-body characters that reaches all the way to the end of `text` —
+ *    the body has no upper bound, so more valid characters could still
+ *    arrive and extend it.
+ *
+ * Everything else — including a run of token-body characters that is *not*
+ * preceded by the literal prefix, and ordinary prose — is not a live prefix
+ * of the pattern and is safe to release immediately. That is what keeps the
+ * held-back tail bounded for realistic non-token output (prompts with no
+ * trailing newline, a `\r`-redrawn spinner) instead of waiting on a newline
+ * that may never come.
+ */
+function livePrefixStart(text) {
+    // An open run: the FIRST literal occurrence with nothing but body characters
+    // between it and the end of `text`. First, not rightmost, and that direction
+    // is load-bearing. The literal's own `-` is a body character, so a token can
+    // contain a second occurrence of the literal inside its body. Cutting at the
+    // rightmost one releases everything before it — the token's own head — in
+    // clear, and then captures only the truncated tail as the token, storing an
+    // unusable credential while reporting success. Holding from the first open
+    // occurrence is strictly more conservative and still exactly minimal: every
+    // later occurrence lies inside the run being held.
+    for (let i = 0; i + TOKEN_PREFIX.length <= text.length; i++) {
+        if (!text.startsWith(TOKEN_PREFIX, i))
+            continue;
+        let open = true;
+        for (let j = i + TOKEN_PREFIX.length; j < text.length; j++) {
+            if (!TOKEN_BODY_CHAR.test(text.charAt(j))) {
+                open = false;
+                break;
+            }
+        }
+        if (open)
+            return i;
+    }
+    // A partial prefix of the literal itself, still trailing at the very end.
+    for (let n = Math.min(TOKEN_PREFIX.length - 1, text.length); n >= 1; n--) {
+        if (text.endsWith(TOKEN_PREFIX.slice(0, n)))
+            return text.length - n;
+    }
+    return text.length;
+}
+/**
+ * Relays a stream while holding back any token it contains.
+ *
+ * Buffers on the boundary of what could still become a token match — never a
+ * fixed byte count, and never "wait for the next newline". A byte-count tail
+ * can split a token across two relayed pieces, neither of which matches the
+ * pattern, and the operator's scrollback then holds both halves in clear:
+ * that is the exact leak this object exists to prevent. Waiting for a
+ * newline is wrong in the other direction: it holds back ordinary, non-token
+ * output — a prompt printed with no trailing newline, a `\r`-redrawn spinner
+ * — until the process exits, and grows the held-back tail without bound for
+ * as long as no newline arrives. `livePrefixStart` computes the exact
+ * minimal suffix that could still extend into a match, so anything else
+ * streams through immediately, and a real, complete token is still always
+ * relayed whole or not at all.
+ *
+ * A run of token-body characters that never terminates — the child never
+ * stops emitting, or line-wraps the token before the pattern's length floor
+ * is reached — stays held until `flush()`. That is the one place an
+ * unbounded hold is both correct and expected: the stream has ended, so
+ * whatever's left is exactly as complete as it will ever be.
+ *
+ * Matches are found with a fresh, local `/g` regex built from
+ * `CLAUDE_TOKEN_PATTERN.source` on every call, never by setting `g` on
+ * `CLAUDE_TOKEN_PATTERN` itself — a shared exported regex with `g` set
+ * carries `lastIndex` across unrelated calls and would silently skip matches
+ * for every other caller of the pattern.
+ */
+export function createTokenFilter(onData) {
+    let carry = "";
+    let token;
+    let redacted = false;
+    const relay = (text) => {
+        if (!text)
+            return;
+        const matches = text.match(new RegExp(CLAUDE_TOKEN_PATTERN.source, "g"));
+        if (!matches)
+            return onData(text);
+        token ??= matches[0];
+        redacted = true;
+        let out = text;
+        for (const m of matches)
+            out = out.split(m).join(redactToken(m));
+        onData(out);
+    };
+    return {
+        push(chunk) {
+            const text = carry + chunk;
+            const cut = livePrefixStart(text);
+            carry = text.slice(cut);
+            if (cut > 0)
+                relay(text.slice(0, cut));
+        },
+        flush() {
+            const rest = carry;
+            carry = "";
+            relay(rest);
+        },
+        get token() {
+            return token;
+        },
+        get redacted() {
+            return redacted;
+        },
+    };
+}
+/**
+ * Attach the operator's keyboard to the child for the life of the capture, and
+ * return the function that puts the terminal back.
+ *
+ * Without this the login is half-attached: the operator sees `Paste code here
+ * if prompted:` — the documented fallback whenever the browser callback cannot
+ * reach the local listener, which is every ssh session — and nothing they type
+ * reaches the child. There is deliberately no timeout, and Ctrl-C goes to
+ * Muster rather than the pty child (node-pty puts it in its own session), so
+ * the flow hangs until the operator kills Muster.
+ *
+ * Raw mode is what makes that keyboard useful (no local echo of a pasted code,
+ * single keypresses delivered immediately) and it is also the one thing in this
+ * whole change that can damage the operator's shell: a leaked raw mode leaves
+ * their terminal with no echo and no Ctrl-C long after Muster has exited. So
+ * the returned restore is the requirement, the caller runs it in a `finally`,
+ * it is idempotent, and it puts raw mode back FIRST — before anything else that
+ * could throw and skip it.
+ *
+ * Two things guard the window the caller's `finally` cannot reach — the one
+ * between entering raw mode and the restore being in the caller's hands:
+ *
+ *  - **Raw mode is entered LAST**, after the listener is attached and the
+ *    stream resumed. That is the whole of the fix, and it is why the attach
+ *    order below must not be "tidied". Guarding the call site instead cannot
+ *    work: a throw partway through this function never returns a restore for
+ *    any `finally` to run, so the ordering has to make the window not exist.
+ *    The `catch` is only for the stragglers — a throw before raw mode still
+ *    has a resumed stream and a live listener to undo.
+ *  - **A signal net.** A `kill -TERM` from another window, or an uncaught
+ *    exception raised outside the capture's promise chain, ends the process
+ *    without unwinding any `finally`. So SIGINT/SIGTERM/`exit` handlers run
+ *    the same restore. They are removed by that restore, so repeated captures
+ *    cannot accumulate handlers and a completed one leaves none behind — and
+ *    because the handler is gone by the time it re-raises, the signal keeps
+ *    its normal effect (node's default disposition: terminate, 128 + signum).
+ *
+ * Only a TTY is touched. A piped stdin has no raw mode to set, and nothing is
+ * forwarded from it: `--interactive` already refuses a non-terminal stdin.
+ */
+function attachInput(pty, input, signals) {
+    if (!input.isTTY)
+        return () => { };
+    const wasRaw = input.isRaw === true;
+    const wasPaused = input.isPaused();
+    const forward = (chunk) => {
+        try {
+            pty.write(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+        }
+        catch {
+            // The child is gone and the exit path is already settling; a keystroke
+            // that lands in that window is not worth failing the login over.
+        }
+    };
+    const hooked = [];
+    let restored = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        try {
+            input.setRawMode(wasRaw);
+        }
+        catch {
+            // Nothing better to do: the terminal is whatever it is.
+        }
+        try {
+            input.off("data", forward);
+        }
+        catch {
+            // Ditto.
+        }
+        if (wasPaused)
+            try {
+                input.pause();
+            }
+            catch {
+                // Ditto.
+            }
+        for (const [event, handler] of hooked.splice(0))
+            try {
+                signals.off(event, handler);
+            }
+            catch {
+                // Ditto.
+            }
+    };
+    try {
+        for (const signal of ["SIGINT", "SIGTERM"]) {
+            const handler = () => {
+                restore();
+                // The restore above removed this handler, so this re-raise reaches
+                // node's default disposition rather than looping back in here.
+                signals.kill(signals.pid, signal);
+            };
+            hooked.push([signal, handler]);
+            signals.once(signal, handler);
+        }
+        // Covers what no signal does: an uncaught exception, or a `process.exit`
+        // from somewhere else entirely.
+        const onExit = () => restore();
+        hooked.push(["exit", onExit]);
+        signals.once("exit", onExit);
+        input.on("data", forward);
+        input.resume();
+        // LAST. See the ordering note above; do not move this up.
+        input.setRawMode(true);
+    }
+    catch (err) {
+        restore();
+        throw err;
+    }
+    return restore;
+}
+/**
+ * Run `claude setup-token` against an identity's template and capture the token
+ * it prints, relaying everything else so the operator still sees and approves
+ * the browser step.
+ *
+ * Fails OPEN. If the output format changes and the pattern stops matching,
+ * nothing is redacted and nothing is captured: the operator sees exactly what
+ * they see today, and — the login itself having succeeded — the caller reports
+ * that it could not recognise a token and points at `--token-env` to record the
+ * one now in their scrollback. (Re-running `--interactive` cannot: it mints a
+ * different token.) The alternatives — silently leaking because redaction
+ * broke, or silently refusing because capture broke — are both worse than the
+ * status quo.
+ */
+export async function captureClaudeToken(opts) {
+    const module = await import("node-pty");
+    const pty = module.spawn("claude", ["setup-token"], {
+        cwd: opts.dir,
+        env: { ...opts.env, CLAUDE_CONFIG_DIR: opts.dir },
+        name: "xterm-256color",
+        // Load-bearing, not cosmetic: `claude` renders the token inside a
+        // bordered box sized to the terminal width, and a narrower column count
+        // wraps the token itself across a hard line break. A token split by a
+        // real newline matches nothing on either side of the break, which
+        // defeats this filter entirely. Do not "tidy" this back toward a more
+        // realistic terminal width.
+        cols: 1000,
+        rows: 30,
+    });
+    // Inside the `try`, so the `finally` below is in charge of the restore from
+    // the moment there is one — on every exit path: normal exit, an error from the
+    // pty, a rejected await. A throw from inside `attachInput` itself never gets
+    // here at all, which is why that function restores whatever it managed to set
+    // up before rethrowing, and enters raw mode last of all.
+    let detachInput = () => { };
+    try {
+        detachInput = attachInput(pty, opts.stdin ?? process.stdin, opts.signals ?? process);
+        const filter = createTokenFilter(opts.onData);
+        const dataSub = pty.onData((chunk) => filter.push(chunk));
+        const exitCode = await new Promise((resolve) => {
+            const exitSub = pty.onExit(({ exitCode }) => {
+                exitSub.dispose();
+                // node-pty can still have an onData chunk queued when onExit fires;
+                // resolving synchronously here risks flushing before it arrives and
+                // silently dropping a token that lands right at process exit.
+                // Deferring to a macrotask lets any already-queued onData run first.
+                setImmediate(() => resolve(exitCode));
+            });
+        });
+        dataSub.dispose();
+        filter.flush();
+        try {
+            // Defensive: the process has already exited by the time we get here, so
+            // this is normally a no-op. It costs nothing to make sure nothing is
+            // left running once this promise settles.
+            pty.kill();
+        }
+        catch {
+            // Already gone.
+        }
+        return {
+            ...(filter.token ? { token: filter.token } : {}),
+            exitCode,
+            redacted: filter.redacted,
+        };
+    }
+    finally {
+        detachInput();
+    }
+}

package/dist/identity-token.js

@@ -0,0 +1,82 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { IdentityError, identityPath } from "./identity-store.js";
+/**
+ * Where an identity's own credential lives, for the agents whose login does not
+ * write one into the template itself. Deliberately the same directory Codex and
+ * OpenCode identities already hold `auth.json` in, so one statement is true of
+ * every agent: deleting an identity's directory revokes its credential.
+ */
+export const tokenPath = (home, name) => join(identityPath(home, name), "token");
+/**
+ * The stored token, or undefined when there is none.
+ *
+ * Absent and empty are different answers. A missing file is an identity that
+ * has not been logged in yet; a file holding nothing is a broken write, and
+ * reporting it as "not configured" would send the operator to create a
+ * credential they already tried to create.
+ */
+export async function readStoredToken(home, name) {
+    const file = tokenPath(home, name);
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return undefined;
+        // EACCES, EISDIR and friends are real failures. Swallowing them would
+        // report "no credential" for an identity whose credential is right there.
+        throw new IdentityError(name, `token could not be read (${code ?? String(e)})`);
+    }
+    const token = raw.trim();
+    if (!token)
+        throw new IdentityError(name, "token file is empty — store it again with `setup-identity --interactive`");
+    return token;
+}
+export async function writeStoredToken(home, name, token) {
+    const value = token.trim();
+    if (!value)
+        throw new IdentityError(name, "refusing to store an empty token");
+    const dir = identityPath(home, name);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    // Written whole or not at all. A truncated credential reads as present and
+    // fails at the agent, which is the worst of both outcomes.
+    const temp = join(dir, `.token.${randomUUID()}`);
+    try {
+        await writeFile(temp, value + "\n", { mode: 0o600 });
+        await rename(temp, tokenPath(home, name));
+    }
+    catch (e) {
+        await rm(temp, { force: true });
+        const code = e.code;
+        throw new IdentityError(name, `token could not be written (${code ?? String(e)})`);
+    }
+}
+/** True when a token file was there to remove. */
+export async function removeStoredToken(home, name) {
+    try {
+        await rm(tokenPath(home, name));
+        return true;
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return false;
+        throw new IdentityError(name, `token could not be removed (${code ?? String(e)})`);
+    }
+}
+export async function resolveCredential(home, name, meta, env) {
+    if (meta.token_env)
+        return {
+            route: "env",
+            variable: meta.token_env,
+            token: env[meta.token_env] || undefined,
+        };
+    // No environment is consulted here, and that is the point. A file-route
+    // identity answers identically in every shell, which is what makes
+    // `muster identities` mean the same thing wherever it is run.
+    return { route: "file", token: await readStoredToken(home, name) };
+}

package/dist/muster.js

@@ -10,7 +10,8 @@ import { delay } from "./identity/processes.js";
 import { formatHuman, humanColorEnabled } from "./format.js";
 import { checkPlugins, npmRegistry } from "./doctor.js";
 import { loadConfig, musterHome } from "./config.js";
-import { describeIdentities, setupIdentity } from "./identity-cli.js";
+import { describeIdentities, interactiveSetup, setupIdentity, } from "./identity-cli.js";
+import { IdentityError } from "./identity-store.js";
 import { MCP_TOOLS } from "./mcp-tools.js";
 const listSchema = z
     .object({ kind: z.enum(["session", "task"]).optional() })
@@ -23,7 +24,7 @@ const help = `Usage:
   muster stop <id> [--format json|human]
   muster output <id>
   muster doctor [--format json|human]
-  muster setup-identity --identity NAME --agent <codex|claude|opencode> [--token-env VAR]
+  muster setup-identity --identity NAME --agent <codex|claude|opencode> [--token-env VAR] [--interactive]
   muster identities [--format json|human]
   muster mcp
   muster --version
@@ -50,6 +51,11 @@ configured, a launch outside all of them is refused.
 --request-key KEY names the launch request itself. Sending the same key again
 returns the launch it already produced rather than starting a second one, and
 sending it with different parameters is refused rather than answered.
+setup-identity takes either --interactive (Muster runs the Claude login and
+stores the token in the identity) or --token-env VAR (the identity reads its
+token from that variable instead, keeping nothing at rest). They are the two
+mutually exclusive credential routes; passing both is an error rather than a
+precedence rule.
 run, list and stop default to JSON. output prints raw task text.
 
 doctor checks path-configured plugins against the packages they came from: a
@@ -182,6 +188,7 @@ async function main() {
                 identity: { type: "string" },
                 agent: { type: "string" },
                 "token-env": { type: "string" },
+                interactive: { type: "boolean" },
             },
         });
         const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, ...values } = parsed;
@@ -235,6 +242,24 @@ async function main() {
             const { identity, agent, "token-env": tokenEnv, } = values;
             if (!identity || !agent)
                 throw new Error("setup-identity requires --identity and --agent");
+            if (values.interactive) {
+                // Refused, not ranked. These are the two mutually exclusive credential
+                // routes, and the interactive branch is taken before tokenEnv is read:
+                // silently preferring it would run a browser login and write a
+                // year-long token to disk on the machine the operator explicitly asked
+                // to keep no credential at rest, while never recording the variable
+                // they named.
+                if (tokenEnv)
+                    throw new IdentityError(identity, "--interactive and --token-env are the two mutually exclusive credential routes: --interactive runs the login and stores a token in the identity, --token-env records the name of a variable to read one from instead. Pass one, not both.");
+                const result = await interactiveSetup({
+                    home: musterHome(),
+                    name: identity,
+                    agent: agent,
+                    isTTY: Boolean(process.stdin.isTTY),
+                });
+                process.stdout.write(`\n${result.note}\n`);
+                return;
+            }
             // Not routed through print(): its RecordView/DoctorView shapes are for
             // run/list/stop/doctor, and an identity record shares no field with
             // either, so this always prints JSON.

package/dist/run.js

@@ -9,7 +9,8 @@ import { enforcementGrade } from "./enforcement.js";
 import { LOCAL } from "./requester.js";
 import { assertEnforcementMeetsMinimum, assertLevelWithinCeiling, assertMayAct, resolveIdentityForRequest, resolveRequesterPolicy, RequesterPolicyRefusal, } from "./requester-policy.js";
 import { IdentityError, readIdentity, } from "./identity-store.js";
-import { copyIdentity, identityEnv, setWorkspaceTrust, } from "./identity-copy.js";
+import { resolveCredential } from "./identity-token.js";
+import { copyIdentity, identityEnv, setCodexWorkspaceTrust, setWorkspaceTrust, } from "./identity-copy.js";
 import { Registry } from "./registry.js";
 import { LaunchLog } from "./log.js";
 import { hosts, selectHost } from "./hosts/index.js";
@@ -90,7 +91,7 @@ export class Muster {
     }
     static async create(opts = {}) {
         const env = launchEnv(opts.env ?? process.env), home = opts.home ?? join(env.HOME ?? homedir(), ".muster");
-        return new Muster(await loadConfig(home), home, env, opts.drivers ?? hosts(), { ...(opts.env ?? process.env) });
+        return new Muster(await loadConfig(home), home, env, opts.drivers ?? hosts(opts.env ?? process.env), { ...(opts.env ?? process.env) });
     }
     run(input, requester = LOCAL) {
         if (this.closing)
@@ -169,6 +170,7 @@ export class Muster {
         // read-only half, and the copy happens below once that id exists.
         const identityName = resolveIdentityForRequest(req.identity, policy);
         let identityMeta;
+        let credential;
         if (identityName) {
             identityMeta = await readIdentity(this.home, identityName);
             if (identityMeta.agent !== req.runtime)
@@ -176,20 +178,20 @@ export class Muster {
             // Claude is the one runtime whose credential cannot survive the copy. It
             // is keyed by the configuration directory's PATH, and a launch points
             // Claude at the per-launch copy, which hashes to a service name that does
-            // not exist — the unsuffixed item is not a fallback. So `token_env` is the
-            // only route a Claude identity can launch under. Without this, such an
-            // identity would pass validation, copy, spawn a real agent and die at the
-            // deadline with "no Claude session registry found".
-            if (identityMeta.agent === "claude" && !identityMeta.token_env)
-                throw new IdentityError(identityName, "a Claude identity needs a token: run `claude setup-token`, export the " +
-                    "token, and name the variable with --token-env. The keychain credential " +
-                    "is keyed to the template's own path and cannot be used from the " +
-                    "per-launch copy a launch actually runs from");
-            // Reported now rather than by an agent that starts unauthenticated: the
-            // variable is read from the unfiltered source environment because that is
-            // where the operator set it, and `hostEnv` filters CLAUDE_CODE_* away.
-            if (identityMeta.token_env && !this.sourceEnv[identityMeta.token_env])
-                throw new IdentityError(identityName, `needs ${identityMeta.token_env} set in the environment`);
+            // not exist — the unsuffixed item is not a fallback. So a token is the
+            // only route a Claude identity can launch under.
+            //
+            // Resolved from the TEMPLATE, which exists now; the copy does not yet.
+            if (identityMeta.agent === "claude") {
+                credential = await resolveCredential(this.home, identityName, identityMeta, 
+                // The unfiltered source environment, because that is where the
+                // operator set the variable and `hostEnv` filters CLAUDE_CODE_* away.
+                this.sourceEnv);
+                if (!credential.token)
+                    throw new IdentityError(identityName, credential.route === "env"
+                        ? `needs ${credential.variable} set in the environment`
+                        : "has no credential — run `setup-identity --interactive` to log in and store a token");
+            }
         }
         /**
          * The one request every permission- and argv-deriving helper is given.
@@ -314,9 +316,15 @@ export class Muster {
                     // session never registers, and the launch burns its whole deadline.
                     // `assertAllowedWorkspace` already realpaths for containment.
                     await setWorkspaceTrust(copy, await realpath(req.cwd));
+                // Codex gates the same way behind a different file and a different key,
+                // and a fresh copy trusts nothing — so every Codex identity launch sat
+                // on "Do you trust the contents of this directory?" until the deadline.
+                // Resolved for the same reason: Codex keys `projects` by its own cwd.
+                else if (identityMeta.agent === "codex")
+                    await setCodexWorkspaceTrust(copy, await realpath(req.cwd));
                 runtimeEnv = {
                     ...runtimeEnv,
-                    ...identityEnv(identityMeta, copy, this.sourceEnv),
+                    ...identityEnv(identityMeta, copy, this.sourceEnv, credential?.token),
                 };
                 entry = await this.registry.update(entry.launchId, {
                     identityPath: copy,

package/package.json

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