@brutalsystems/muster 0.7.12 → 0.7.14

package/README.md

@@ -413,11 +413,270 @@ No user-level runtime configuration is rewritten, and workspace-trust dialogs
 are never accepted automatically.
 
 Launch intent is fsynced to `~/.muster/launches.jsonl` before a runtime starts;
-ready/failure outcomes follow. The log contains the **full prompt**, cwd,
-requester, runtime, kind and host. Registry and task outputs also live under
-`~/.muster`, with private file permissions. An abandoned `registry.lock` fails
-closed: verify no Muster operation is running before removing that directory.
-There is no automatic time-based lock theft.
+ready/failure outcomes follow. For a local requester the log contains the
+**full prompt**, cwd, requester, runtime, kind and host. A non-local requester
+gets metadata-only logging instead — no prompt text and no environment values,
+see [Requester profiles and enrolments](#requester-profiles-and-enrolments)
+below. Registry and task outputs also live under `~/.muster`, with private
+file permissions. An abandoned `registry.lock` fails closed: verify no Muster
+operation is running before removing that directory. There is no automatic
+time-based lock theft. `launches.jsonl` rotates at 8 MiB: the file is renamed
+to `launches.jsonl.1`, replacing any previous generation, and a fresh file is
+opened at mode `0600`. One prior generation is kept; this bounds the file
+without adding a retention policy nobody asked for.
+
+### Containment levels
+
+`--level` names a legal `--permissions` / `--sandbox` pair. It is a spelling,
+not a second policy path, and naming both a level and either flag is an error.
+
+| Level  | Equivalent to                                                                        |
+| ------ | ------------------------------------------------------------------------------------- |
+| `read` | `--permissions deny --sandbox read-only`                                              |
+| `work` | `--permissions auto --sandbox workspace-write`                                        |
+| `open` | `--permissions bypass --sandbox full-access` (still requires `allow_dangerous_flags`) |
+
+`deny` with `workspace-write` or `full-access` has no level and stays available
+through the flags.
+
+Every launch also records how strongly its containment was imposed:
+
+| `enforcement` | Meaning                                                                     |
+| ------------- | ---------------------------------------------------------------------------- |
+| `kernel`      | Codex or Claude Code with an OS sandbox configured and active.              |
+| `tool-policy` | OpenCode — rules the agent is asked to respect, with no kernel enforcement. |
+| `none`        | `full-access` — the sandbox is deliberately disabled.                       |
+
+### Requester profiles and enrolments
+
+A non-local caller — one reached through a transport such as Tin Can rather
+than the local CLI or a local MCP client — is identified by an `(authority,
+subject)` tuple supplied by whatever already authenticated it. That tuple must
+be enrolled in `config.toml` and bound to a profile, or the request is
+refused. Two additions to `configSchema`, following the existing record style
+of `[projects]`, `[mcp_servers]` and `[plugins]`:
+
+```toml
+[requester_profiles.research]
+allowed_roots = ["/Users/mikewilliams/Source/brutalsystems"]
+level = "read"
+min_enforcement = "kernel"      # "tool-policy" to admit OpenCode here
+env_allow = ["GH_TOKEN"]
+env_defaults = { PATH = "/usr/bin:/bin", LANG = "en_US.UTF-8" }
+identities = ["research"]       # bounds which identities this requester may name
+
+[[requesters]]
+authority = "example.peer.v1"
+subject = "<opaque authenticated key id>"
+label = "m4pro"
+profile = "research"
+```
+
+`[[requesters]]` is an array of tables rather than a record keyed by
+`"authority:subject"`, so no separator can be ambiguous inside a subject. Two
+enrolments with the same `(authority, subject)` are a configuration error
+rather than a precedence rule. `label` is optional and never read for policy.
+
+`allowed_roots` is **required** on a profile and must be non-empty — it is the
+one key with no safe default, since the global `allowed_roots` defaults to
+empty and empty is read as permitting anything the account can reach. Every
+other key defaults to its narrowest value: `level` defaults to `read` and
+excludes `open` (no remote request may disable the sandbox), `min_enforcement`
+defaults to `kernel` (the default admits Codex and Claude Code; `tool-policy`
+is what admits OpenCode), and `env_allow`/`env_defaults` default to empty.
+Where a key appears in both, `env_defaults` wins — a profile that pins a value
+and also allows the key means the value it pinned, not the accepting shell's. A
+profile written as nothing but a required `allowed_roots` is therefore the
+most restrictive profile expressible.
+
+`identities` bounds which named identities (see [Agent
+identities](#agent-identities) above) a non-local requester may launch under,
+and it also defaults to its narrowest value — empty:
+
+- **Empty or omitted** refuses any identity the request names — the launch
+  falls back to lending the operator's own ambient account, same as before
+  identities existed.
+- **Exactly one** makes that identity the default: a request naming no
+  identity gets it anyway, and a request naming it explicitly gets the same
+  launch.
+- **Several** require the request to choose: a request naming none of them is
+  refused rather than guessing, and a request naming one outside the list is
+  refused too.
+
+A local requester has no profile and no ceiling here either — it may name any
+identity that exists, exactly as it may reach any root.
+
+A request naming no level resolves to its profile's level — never to the
+receiving machine's own `config.permissions` / `config.sandbox` defaults,
+which would let an unconfigured local default hand a remote caller more than
+its profile grants.
+
+**The `env_allow` trap.** A non-local launch's environment is composed from
+nothing — an allowlist, not the accepting shell's environment filtered by a
+denylist. That means a remote profile must list in `env_allow` (or supply in
+`env_defaults`) everything the runtime's own toolchain needs — not just what
+the agent's task needs. A missing entry does not present as a policy refusal;
+it presents as a **broken runtime** — a launch that starts and then fails in
+ways that look like a bug in Codex, Claude Code or OpenCode rather than a
+missing environment variable. This is exactly the diagnosis-confusing failure
+shape the rest of this feature avoids, so test a first remote profile with a
+trivial launch before relying on it.
+
+**`env_allow` is not the whole environment.** Two configured things still
+contribute variables read from the accepting process's unfiltered environment,
+exactly as for a local launch. A selected MCP server contributes its own declared
+`env_vars` and its `bearer_token_env_var`. And on every OpenCode launch, each
+configured `[opencode.provider]` contributes its API key, because the provider
+configuration handed to the runtime is built from them — so a remote OpenCode
+launch reaches this machine's model providers even with `env_allow = []`. That is the same principle applied
+one level up: a configured credential authenticates, one that merely happens to
+be present does not. It does mean a remote request may not choose which servers
+or plugins run: naming `mcp` or `plugin` is refused as not expressible
+remotely, and a remote launch gets this machine's configured `default_mcp` and
+`default_plugins`. To withhold a credential from a remote requester, withhold
+the server — a profile cannot withhold the variable alone. Provider keys cannot
+be withheld per requester at all today; a machine that must not lend its model
+providers should not enrol a remote requester for OpenCode.
+
+**What this does and does not defend against.** Muster does not authenticate
+its caller. A trusted local invoker that has already authenticated a remote
+peer passes along the provenance it established, and Muster applies least
+privilege to that provenance. This is not a defence against a compromised
+same-user process: anything able to exec Muster can already rewrite the very
+`config.toml` it reads, including its own enrolment and profile. The value is
+in what a legitimately-authenticated remote peer is confined to, not in
+resisting an attacker who is already running as the same local user.
+
+**Stop and output are asymmetric.** A local operator may stop or read the
+output of any launch on the machine, as before. A non-local requester may
+`stop` or read `output` for only the launches it asked for — an attempt to act
+on another requester's launch is refused. An entry with no recorded requester
+(older data, or a local launch) reads as local and is therefore protected the
+same as any other local launch. `list` is not scoped this way: every caller
+sees every launch on the machine, so the asymmetry covers acting on a launch,
+not seeing that it exists.
+
+## Agent identities
+
+An **identity** is a named, pre-authenticated template configuration for one
+agent, stored under `~/.muster/identities/<name>` at mode `0700`. Launching
+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 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
+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.
+
+`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:
+
+```sh
+CLAUDE_CONFIG_DIR=~/.muster/identities/work claude setup-token   # then export it
+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:
+
+```sh
+muster identities
+```
+
+Launch under a named identity with `--identity`:
+
+```sh
+muster run claude --identity work --cwd ~/projects/thing --prompt 'Ship it'
+```
+
+At launch, Muster copies a declared subset of that identity's files into a
+fresh per-launch directory under `~/.muster/identities-live/<launchId>/` and
+points the runtime's own configuration-location variable
+(`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, or `OPENCODE_CONFIG_DIR` +
+`XDG_DATA_HOME`) at that copy — never at the template itself, so one launch
+can never mutate another's credential.
+
+The copy lives only as long as the launch. `muster stop` removes it directly,
+and otherwise it is removed by the **first `muster list` after the entry
+reaches a terminal status** (`exited`, `failed`, `stopped`, `unknown`). There
+is no prune operation — an earlier draft of this documentation said the copy
+was retained until the entry was pruned, and that was never what was built.
+This matters for two reasons: an agent writes its own session transcript into
+its configuration directory, so that transcript goes with the copy moments
+after the launch ends (capture it while the launch is still running if you
+need it), and resume/fork (#32) cannot assume a copy is still there.
+
+Launching without `--identity` sets none of this: behaviour is exactly as
+before, using the ambient environment.
+
+Session discovery follows the same relocated path, so a Claude identity's
+sessions are found even though `CLAUDE_CONFIG_DIR` no longer points at
+`~/.claude` — this was previously refused outright as an unsupported
+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.
+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
+   the launch is recorded. That is the same treatment every other launch
+   variable gets, not special handling for this one, but it does mean a
+   long-lived subscription token passes through disk; a launch whose host
+   temp directory leaks (a crash before cleanup, a misconfigured `TMPDIR`)
+   leaves it there.
+5. **A requester profile with no `identities` lends the operator's own
+   account** to that requester, because the launch falls back to the ambient
+   environment exactly as it did before identities existed. That is preserved
+   for compatibility, not a recommendation — an operator should set
+   `identities` on any requester profile whose access they actually care
+   about bounding.
+
+A Claude launch under an identity also marks the launch's working directory
+trusted *inside that launch's own copy* of the configuration, so a brand-new
+directory starts as a registered session without anyone accepting a trust
+dialog. This is distinct from the ordinary Claude prerequisite described
+above: it only ever writes to the per-launch copy, never to the operator's own
+`~/.claude.json`, and only applies to launches under an identity. A launch
+without `--identity` still requires the operator to have trusted the directory
+themselves beforehand.
+
+Automated tests use fake runtimes, so they prove the plumbing — the copy, the
+variables, the trust flag, the lifecycle — but not that a real agent starts
+authenticated from a copy. See
+[docs/identity-verification.md](./docs/identity-verification.md) for the
+manual checklist that covers that, and for which agents have actually been
+verified.
 
 ## Optional tools for launched agents
 

package/dist/claude-policy.js

@@ -6,8 +6,6 @@ import { promisify } from "node:util";
 /** Claude's CLI cannot report all effective enterprise policy before starting.
  * Refuse detected managed sources rather than pretending inline settings win. */
 export async function assertClaudePolicy(env) {
-    if (env.CLAUDE_CONFIG_DIR)
-        throw new Error("Custom CLAUDE_CONFIG_DIR is unsupported: Tin Can discovers ~/.claude/sessions");
     const home = env.HOME ?? homedir();
     const system = process.platform === "darwin"
         ? "/Library/Application Support/ClaudeCode"

package/dist/config.js

@@ -6,13 +6,60 @@ import { z } from "zod";
 import { mcpName, mcpServerSchema } from "./mcp.js";
 import { pluginName, pluginSchema } from "./plugins.js";
 import { openCodeSectionSchema } from "./providers.js";
+import { identityNameSchema } from "./identity-store.js";
+import { authoritySchema, subjectSchema } from "./requester.js";
+import { RequesterConfigError } from "./requester-policy.js";
+/**
+ * What a remote requester is permitted here. Every default is the narrowest
+ * value, so the shortest profile is the most restrictive one.
+ *
+ * `allowed_roots` is the one key with no safe default: the global
+ * `allowed_roots` defaults to empty, which `assertAllowedWorkspace` reads as
+ * permitting anything the account can reach, so inheriting it would hand an
+ * unconfigured profile the whole filesystem.
+ *
+ * `level` excludes `open` deliberately — no remote request may disable the
+ * sandbox, and a config naming it should fail loudly rather than be checked for
+ * at launch.
+ *
+ * `min_enforcement` is the one key whose default excludes a runtime rather than
+ * narrowing a permission: `kernel` admits Codex and Claude Code, and
+ * `tool-policy` is what admits OpenCode.
+ */
+export const requesterProfileSchema = z
+    .object({
+    allowed_roots: z.array(z.string().min(1)).min(1),
+    level: z.enum(["read", "work"]).default("read"),
+    min_enforcement: z.enum(["kernel", "tool-policy"]).default("kernel"),
+    env_allow: z.array(z.string().min(1)).default([]),
+    /**
+     * Baseline overrides, e.g. a PATH that does not depend on the accepting
+     * shell. It wins over the source environment for every key it sets,
+     * `env_allow` entries included: a profile that pins a value and also allows
+     * the key meant the value it pinned.
+     */
+    env_defaults: z.record(z.string().min(1), z.string()).default({}),
+    /** Which identities this requester may launch under. Empty refuses any. */
+    identities: z.array(identityNameSchema).default([]),
+})
+    .strict();
+/** Binding an authenticated `(authority, subject)` to a profile. The grant. */
+export const requesterEnrolmentSchema = z
+    .object({
+    authority: authoritySchema,
+    subject: subjectSchema,
+    label: z.string().min(1).max(200).optional(),
+    profile: z.string().min(1),
+})
+    .strict();
 export const configSchema = z
     .object({
     host: z.enum(["auto", "tmux", "pty", "macos-terminal"]).default("auto"),
     launch_timeout_sec: z.number().finite().positive().max(600).default(30),
     max_concurrent: z.number().int().positive().max(1000).default(4),
     allowed_roots: z.array(z.string().min(1)).default([]),
-    projects: z.record(z.string().regex(/^[a-zA-Z0-9_-]+$/), z.string().min(1))
+    projects: z
+        .record(z.string().regex(/^[a-zA-Z0-9_-]+$/), z.string().min(1))
         .default({}),
     permissions: z.enum(["auto", "deny", "bypass"]).default("deny"),
     sandbox: z
@@ -29,6 +76,10 @@ export const configSchema = z
     plugins: z.record(pluginName, pluginSchema).default({}),
     opencode: openCodeSectionSchema,
     allow_dangerous_flags: z.boolean().default(false),
+    requester_profiles: z
+        .record(z.string().regex(/^[a-zA-Z0-9_-]+$/), requesterProfileSchema)
+        .default({}),
+    requesters: z.array(requesterEnrolmentSchema).default([]),
 })
     .strict();
 export const musterHome = () => join(homedir(), ".muster");
@@ -42,6 +93,18 @@ export async function loadConfig(home = musterHome()) {
             throw e;
     }
     const result = configSchema.parse(value);
+    const seen = new Set();
+    for (const e of result.requesters) {
+        // The spec lists both of these under RequesterConfigError, and the error
+        // model exists so a transport maps to stable codes without matching on
+        // message text. A plain Error is indistinguishable from a parse failure.
+        if (!result.requester_profiles[e.profile])
+            throw new RequesterConfigError(`Requester ${e.authority}/${e.subject} names unknown profile ${e.profile}. Configured: ${Object.keys(result.requester_profiles).join(", ") || "none"}`);
+        const key = [e.authority, e.subject].join("\0");
+        if (seen.has(key))
+            throw new RequesterConfigError(`Duplicate requester enrolment for ${e.authority}/${e.subject}`);
+        seen.add(key);
+    }
     if ((["danger-full-access", "full-access"].includes(result.sandbox) ||
         result.permissions === "bypass") &&
         !result.allow_dangerous_flags)

package/dist/enforcement.js

@@ -0,0 +1,5 @@
+export function enforcementGrade(runtime, resolved) {
+    if (resolved.sandbox === "full-access")
+        return "none";
+    return runtime === "opencode" ? "tool-policy" : "kernel";
+}

package/dist/guard.js

@@ -4,6 +4,7 @@ import { realpath } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
 import { mcpName, claudeMcpConfig } from "./mcp.js";
 import { pluginName } from "./plugins.js";
+import { RequesterConfigError } from "./requester-policy.js";
 export const runSchema = z
     .object({
     runtime: z.enum(["codex", "claude", "opencode"]),
@@ -28,11 +29,48 @@ export const runSchema = z
         .string()
         .regex(/^[a-zA-Z0-9_-]+$/)
         .optional(),
+    /** Name of a stored identity to launch under. See src/identity-store.ts. */
+    identity: z
+        .string()
+        .regex(/^[a-zA-Z0-9_-]+$/)
+        .optional(),
     requestKey: z.string().min(1).max(200).optional(),
+    level: z.enum(["read", "work", "open"]).optional(),
     args: z.array(z.string()).default([]),
 })
     .strict();
+/**
+ * A level is a spelling of a legal `permissions` + `sandbox` pair, not a second
+ * policy path — `test/level.test.ts` asserts the equivalence for all three.
+ * The two legal combinations no level names, `deny` + `workspace-write` and
+ * `deny` + `full-access`, stay reachable through the flags.
+ */
+export const LEVELS = {
+    read: { permissions: "deny", sandbox: "read-only" },
+    work: { permissions: "auto", sandbox: "workspace-write" },
+    open: { permissions: "bypass", sandbox: "full-access" },
+};
+/**
+ * Checked against raw input before parsing, like `project` and `cwd`: once
+ * defaults have been applied a caller's value is indistinguishable from one
+ * Muster chose.
+ */
+export function assertLevelExclusive(input) {
+    if (typeof input !== "object" || input === null)
+        return;
+    const o = input;
+    if (o.level !== undefined &&
+        (o.permissions !== undefined || o.sandbox !== undefined))
+        throw new Error("use level or permissions/sandbox, not both");
+}
 export function resolvePermissions(req, config) {
+    if (req.level) {
+        const pair = { ...LEVELS[req.level] };
+        if ((pair.permissions === "bypass" || pair.sandbox === "full-access") &&
+            !config.allow_dangerous_flags)
+            throw new Error("bypass or full-access requires allow_dangerous_flags=true in config.toml");
+        return pair;
+    }
     const permissions = req.permissions ?? config.permissions;
     const configuredSandbox = req.sandbox ?? config.sandbox;
     const sandbox = configuredSandbox === "danger-full-access"
@@ -108,6 +146,12 @@ export function paramsFingerprint(req, permissions, mcp, plugins) {
         [...mcp].sort(),
         [...plugins].sort(),
         req.model ?? null,
+        // Hashed because it selects which account's credentials the agent
+        // holds. Without it, one request key reused across two identities
+        // dedupes: the caller asks for account-b and is handed the launch
+        // already running under account-a, reported as success. A reused key
+        // with different parameters must be refused, not answered.
+        req.identity ?? null,
         req.args,
     ]))
         .digest("hex");
@@ -209,3 +253,62 @@ export function launchEnv(env) {
     const blocked = /^(CLAUDECODE|CLAUDE_CODE_|CODEX_THREAD_ID$|TMUX$|TMUX_PANE$|MCP_)/;
     return Object.fromEntries(Object.entries(env).filter(([k, v]) => typeof v === "string" && !blocked.test(k)));
 }
+/**
+ * What a composed environment must contain to launch at all. `LANG` is here
+ * deliberately: an empty or absent `LANG` has broken every tmux launch on the
+ * remote hosts before, and a composed environment is exactly where it goes
+ * missing.
+ */
+export const BASELINE_ENV = [
+    "PATH",
+    "HOME",
+    "USER",
+    "SHELL",
+    "TMPDIR",
+    "TERM",
+    "LANG",
+];
+/**
+ * The base environment handed to the launched agent — distinct from the
+ * environment Muster's own subprocesses run in, which stays denylist-filtered
+ * from the parent because it is Muster's own machinery on its own machine and
+ * never reaches an agent.
+ *
+ * Local requesters keep the denylist: the user's own machine, the user's own
+ * credentials, long-standing documented behaviour. Remote requesters get an
+ * allowlist composed from nothing, because the alternative hands an agent
+ * whatever happened to be in the environment of the process that accepted the
+ * request — a set nobody chose.
+ */
+export function agentBaseEnv(requester, profile, sourceEnv) {
+    if (requester.kind === "local")
+        return launchEnv(sourceEnv);
+    if (!profile)
+        throw new RequesterConfigError("a remote requester reached environment composition without a profile");
+    const env = {};
+    // Allow-listed variables come from the accepting environment.
+    for (const key of profile.env_allow) {
+        const value = sourceEnv[key];
+        if (typeof value === "string")
+            env[key] = value;
+    }
+    // The baseline a launch cannot run without, from the profile where it sets one.
+    for (const key of BASELINE_ENV) {
+        const value = profile.env_defaults[key] ?? sourceEnv[key];
+        if (typeof value === "string" && value.length)
+            env[key] = value;
+    }
+    // `env_defaults` wins over everything above, and is delivered even for a key
+    // that is neither baseline nor allow-listed. A profile that sets a value meant
+    // the value it chose; dropping it would leave the profile reading as though it
+    // supplies something it never delivers, and pinning `PATH` while handing over
+    // the accepting shell's raw one is precisely the mismatch this feature exists
+    // to remove.
+    for (const [key, value] of Object.entries(profile.env_defaults))
+        if (typeof value === "string" && value.length)
+            env[key] = value;
+    for (const required of ["PATH", "LANG"])
+        if (!env[required])
+            throw new RequesterConfigError(`composed environment for this requester has no ${required}; set it under the profile's [env_defaults] table`);
+    return env;
+}

package/dist/identity/claude.js

@@ -5,8 +5,21 @@ import { readFile, access } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { descendants } from "./processes.js";
+/**
+ * Where Claude Code records its sessions. `CLAUDE_CONFIG_DIR` relocates the whole
+ * configuration directory, sessions included, so discovery must follow it —
+ * otherwise a launch whose configuration was relocated records its session
+ * somewhere Muster never looks, and resolution fails at the deadline rather than
+ * reporting anything useful.
+ */
+export function claudeSessionsDir(env) {
+    const configured = env.CLAUDE_CONFIG_DIR;
+    if (typeof configured === "string" && configured.length)
+        return join(configured, "sessions");
+    return join(env.HOME ?? homedir(), ".claude", "sessions");
+}
 export async function resolveClaude(root, env, deadline) {
-    const dir = join(env.HOME ?? homedir(), ".claude", "sessions");
+    const dir = claudeSessionsDir(env);
     const matches = [];
     for (const pid of await descendants(root, deadline)) {
         if (Date.now() >= deadline)

package/dist/identity-auth.js

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+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";
+const run = promisify(execFile);
+/**
+ * Claude Code stores its credential in the macOS keychain under a service name
+ * derived from the configuration directory's PATH, which is why a copied
+ * directory cannot authenticate: it hashes to a name that does not exist.
+ */
+export function claudeKeychainService(configDir) {
+    return ("Claude Code-credentials-" +
+        createHash("sha256").update(configDir).digest("hex").slice(0, 8));
+}
+async function keychainHas(service) {
+    try {
+        await run("security", ["find-generic-password", "-s", service]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readsAsJson(file) {
+    try {
+        JSON.parse(await readFile(file, "utf8"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function identityAuthState(home, name, meta, env, probe = keychainHas) {
+    const dir = identityPath(home, name);
+    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 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.
+        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");
+    }
+    // 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
+    // "opencode" (join(XDG_DATA_HOME, "opencode", "auth.json") — confirmed
+    // 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";
+    return (await readsAsJson(join(dir, file)))
+        ? yes(`${file} is present`)
+        : no(`${file} is missing or unreadable — log in for this identity`);
+}