@ashlr/hub 3.4.0 → 3.5.0

package/dist/core/verse/mcp-scope.js

@@ -0,0 +1,149 @@
+/**
+ * core/verse/mcp-scope.ts — MCP scope, as reported by Locus.
+ *
+ * docs/VERSE-WORKSPACES.md §3: "a server appropriate for a personal account
+ * may be wrong for a client's. Locus already models exactly this — principal,
+ * tenant, sealed session — so scope should be asked of Locus rather than
+ * reinvented in the hub, and the hub should hold opaque references rather
+ * than copies of anything sensitive."
+ *
+ * So this module OWNS NO SCOPE. It asks `src/core/integrations/locus.ts` and
+ * projects the answer onto a transport shape. Two rules follow from that:
+ *
+ *   1. Every field here is an OPAQUE REFERENCE Locus already publishes in its
+ *      own `agent report --json` (alias, tenant, binding_id, principal). None
+ *      of them is a credential, and none of them is derived, inferred or
+ *      cached by the hub. When Locus says nothing, this says nothing — it
+ *      never substitutes a hub-local notion of "which account is this".
+ *   2. Mutation admission is NOT decided here either. It is decided by the
+ *      repo's existing pre-mutate gate (`assertLocusPreMutate`), whose mode
+ *      ladder (off | warn | enforce) is already the contract every other
+ *      spawn site in this repo obeys — see src/core/run/engines.ts:662. A new
+ *      surface inventing a stricter or looser rule than the dispatch path is
+ *      exactly the "reinvented in the hub" failure this file exists to avoid.
+ *
+ * Pure projection + one shell-out through locus.ts. Never throws.
+ */
+import { assertLocusPreMutate, locusAgentReport, } from '../integrations/locus.js';
+// ---------------------------------------------------------------------------
+// Projection
+// ---------------------------------------------------------------------------
+const UNAVAILABLE = {
+    available: false,
+    pinned: false,
+    aliasRef: null,
+    tenantRef: null,
+    principalRef: null,
+    bindingRef: null,
+    sealOk: null,
+    expired: null,
+    frozen: null,
+    expiresAt: null,
+    status: null,
+    statusOneline: null,
+    reason: 'mcp-scope-locus-unavailable',
+};
+/** A non-empty string, or null. Locus's optional fields arrive as either. */
+function ref(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/** A boolean, or null when Locus did not report the flag at all. */
+function flag(value) {
+    return typeof value === 'boolean' ? value : null;
+}
+/**
+ * Project one `locus agent report --json` probe onto {@link VerseMcpScope}.
+ *
+ * Pure: pass a canned {@link LocusProbeResult} in tests rather than shelling
+ * out. An unavailable probe, a null report and a null pin are three different
+ * facts and each gets its own reason.
+ */
+export function projectVerseMcpScope(probe) {
+    if (!probe.available || probe.report === null)
+        return UNAVAILABLE;
+    const report = probe.report;
+    const pin = report.pin ?? null;
+    const base = {
+        available: true,
+        status: ref(report.status),
+        statusOneline: ref(report.status_oneline),
+    };
+    if (pin === null || pin.pinned !== true) {
+        return {
+            ...UNAVAILABLE,
+            ...base,
+            pinned: false,
+            reason: 'mcp-scope-unpinned',
+        };
+    }
+    const sealOk = flag(pin.seal_ok);
+    const expired = flag(pin.expired);
+    // Order matters: an expired pin whose seal never verified is reported as
+    // seal-unverified, because that is the more fundamental failure and the one
+    // the operator has to fix first.
+    const reason = sealOk === false ? 'mcp-scope-seal-unverified'
+        : expired === true ? 'mcp-scope-expired'
+            : 'mcp-scope-pinned';
+    return {
+        ...base,
+        pinned: true,
+        aliasRef: ref(pin.alias),
+        tenantRef: ref(pin.tenant),
+        principalRef: ref(pin.principal),
+        bindingRef: ref(pin.binding_id),
+        sealOk,
+        expired,
+        frozen: flag(pin.frozen),
+        expiresAt: ref(pin.expires_at),
+        reason,
+    };
+}
+/**
+ * Ask Locus for the current scope.
+ *
+ * `read` is the injection seam: production passes nothing and gets the real
+ * `locusAgentReport()` shell-out; tests pass a function returning a canned
+ * probe and never spawn anything. Never throws — locusAgentReport() already
+ * reports failure as `{available: false}` rather than raising.
+ */
+export function readVerseMcpScope(read = locusAgentReport) {
+    try {
+        return projectVerseMcpScope(read());
+    }
+    catch {
+        return UNAVAILABLE;
+    }
+}
+/**
+ * The scope a write would land under, plus the repo's existing admission
+ * decision for it.
+ *
+ * `decide` and `read` are injection seams for tests. In production both shell
+ * out to Locus once each.
+ */
+export function readVerseMcpScopeGate(options = {}) {
+    const scope = readVerseMcpScope(options.read ?? locusAgentReport);
+    let decision;
+    try {
+        decision = options.decide
+            ? options.decide()
+            // `arguments.length >= 2` inside assertLocusPreMutate distinguishes
+            // "config omitted -> read ~/.ashlr" from "config null -> no config", so
+            // the two calls must stay separate rather than passing `undefined`.
+            : 'config' in options
+                ? assertLocusPreMutate(options.env, options.config)
+                : assertLocusPreMutate(options.env);
+    }
+    catch {
+        // Fail closed on an unexpected throw: an undecidable gate is not an open
+        // one for a surface that installs arbitrary code.
+        decision = { allow: false, mode: 'enforce', blockers: ['locus pre-mutate gate could not be evaluated'] };
+    }
+    return {
+        scope,
+        mode: decision.mode,
+        allow: decision.allow,
+        blockers: [...decision.blockers],
+    };
+}
+//# sourceMappingURL=mcp-scope.js.map

package/dist/core/verse/mcp-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-scope.js","sourceRoot":"","sources":["../../../src/core/verse/mcp-scope.ts"],"names":[],"mappings":"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"}

package/dist/core/verse/mcp-seat-view.d.ts

@@ -0,0 +1,197 @@
+/**
+ * core/verse/mcp-seat-view.ts — which MCP servers each Verse seat would load.
+ *
+ * READ-ONLY. Nothing in this file writes, installs, enables or disables
+ * anything. docs/VERSE-WORKSPACES.md §3 asks for exactly one thing first:
+ * "Surface which servers each seat would load, since a server configured for
+ * one account should not silently apply to another."
+ *
+ * ── The finding this module exists to make visible ──────────────────────────
+ *
+ * `discoverMcpServers()` scans HOME-level JSON configs (see
+ * `knownConfigPaths()`): ~/.claude.json, ~/.claude/settings.json, ~/.mcp.json,
+ * ~/.ashlrcode/settings.json, ~/.ashlr-workbench/settings.json,
+ * ~/.aw/settings.json, ~/.ashlr/settings.json.
+ *
+ * NO VERSE SEAT READS ANY OF THEM. Verified against the adapters and the
+ * launcher, not recalled:
+ *
+ *   - CLAUDE and LOCAL seats: `buildClaudeLaunch` (src/core/verse/adapters/
+ *     claude.ts) puts `--strict-mcp-config --mcp-config '{"mcpServers":{}}'`
+ *     in every turn's argv, for both engines. That is a complete override:
+ *     the seat loads ZERO MCP servers, whatever any config file says.
+ *   - CODEX and GROK seats: their adapters add no MCP flag, so each loads its
+ *     OWN native config — and the account is pinned by a private per-account
+ *     state directory (`CODEX_HOME` / `GROK_HOME` / `CLAUDE_CONFIG_DIR` =
+ *     `<profile>/native-state`, src/core/resources/native-profile.ts:72-78,
+ *     :108). That directory is per ACCOUNT, so two Codex accounts already
+ *     cannot share a server by accident. Their config is `config.toml` —
+ *     TOML, which `discoverMcpServers()` (JSON only) cannot read.
+ *
+ * Reporting a machine-wide server list as "what this seat runs" would
+ * therefore be a lie in every direction at once: it would show servers no
+ * seat loads, and hide the per-account TOML that Codex and Grok actually do.
+ * So this module reports the two things separately and names the reason for
+ * each, and reports EMPTY rather than guessing.
+ *
+ * ── What may leave this module ──────────────────────────────────────────────
+ *
+ * Never: a launcher argv, an absolute native-profile path, a home-anchored
+ * absolute path, or a real env value. Config files are identified by their
+ * path RELATIVE TO $HOME (`.claude.json`, `.ashlr/settings.json`), which
+ * names the file precisely and carries no username. Every spec crosses the
+ * boundary through `redactEnv()`, whose whole reason for existing is that
+ * these specs carry secrets.
+ */
+import type { McpServerSpec } from '../types.js';
+import type { VerseEngine } from './types.js';
+import { type VerseAccountIdentity } from './accounts.js';
+import { type VerseMcpScope } from './mcp-scope.js';
+/**
+ * Engines whose adapter argv pins an EMPTY `--mcp-config` under
+ * `--strict-mcp-config`, so the seat can load nothing at all.
+ *
+ * Both entries come from one function: `buildClaudeLaunch` serves engine
+ * 'claude' and engine 'local' alike (the latter is the same `claude` binary
+ * with ANTHROPIC_BASE_URL pointed at Ollama).
+ *
+ * If that argv ever loses those two flags this constant becomes a lie, which
+ * is why `test/verse-mcp-seat-view.test.ts` asserts the flags are still in the
+ * adapter's real output rather than trusting this list.
+ */
+export declare const VERSE_MCP_ISOLATED_ENGINES: readonly VerseEngine[];
+/** The two argv flags that make an isolated seat isolated. Asserted in tests. */
+export declare const VERSE_MCP_ISOLATION_FLAGS: readonly string[];
+/** Why a seat loads what it loads. Machine-readable, verbatim, never prose. */
+export type VerseMcpSeatReason = 
+/** The adapter pins an empty --mcp-config: this seat loads nothing. */
+'mcp-seat-isolated-by-adapter'
+/** The account's private config file does not exist. */
+ | 'mcp-account-config-absent'
+/** The config exists but is TOML, which this JSON-only discovery does not parse. */
+ | 'mcp-account-config-not-json'
+/** The config exists, is JSON, and was read. */
+ | 'mcp-account-config-read'
+/** The config exists but could not be read or parsed. */
+ | 'mcp-account-config-unreadable'
+/** The account's private state directory could not be resolved. */
+ | 'mcp-account-profile-unresolved';
+/**
+ * One MCP server, safe to serialize.
+ *
+ * `command` and `args` are shown IN FULL and verbatim: docs/VERSE-WORKSPACES.md
+ * §3 requires the operator to read what they are about to run. `env` keys are
+ * shown; every env VALUE is the literal `'<set>'` from `redactEnv`.
+ */
+export interface VerseMcpServerView {
+    name: string;
+    command: string;
+    args: string[];
+    /** Keys only — every value is `'<set>'`. Null when the spec sets no env. */
+    env: Record<string, string> | null;
+    /** Config file path RELATIVE TO $HOME. Never absolute, never a username. */
+    sourceRef: string;
+}
+/** What one seat would load, and why. */
+export interface VerseMcpSeatView {
+    seatId: string;
+    label: string;
+    engine: VerseEngine;
+    accountId: string;
+    /** Servers this seat would actually load. Empty is a real answer. */
+    servers: VerseMcpServerView[];
+    reason: VerseMcpSeatReason;
+    /**
+     * The account config file this seat reads, named relative to the account's
+     * own private state directory (e.g. `config.toml`). The directory itself is
+     * private and is never published.
+     */
+    configFile: string | null;
+    configFormat: 'json' | 'toml' | null;
+    /** Plain facts the UI must show rather than implying a fault. */
+    notes: string[];
+}
+/** Servers configured on this machine that no Verse seat reads. */
+export interface VerseMcpMachineRegistry {
+    servers: VerseMcpServerView[];
+    /**
+     * TRUE when at least one server is configured machine-wide. Combined with
+     * every seat reporting none, that is the fact worth surfacing loudly.
+     */
+    configured: boolean;
+    note: string;
+}
+export interface VerseMcpSnapshot {
+    sampledAt: string;
+    seats: VerseMcpSeatView[];
+    machine: VerseMcpMachineRegistry;
+    scope: VerseMcpScope;
+    notes: string[];
+}
+export declare const VERSE_MCP_ISOLATED_NOTE: string;
+export declare const VERSE_MCP_TOML_NOTE: string;
+export declare const VERSE_MCP_PER_ACCOUNT_NOTE: string;
+export declare const VERSE_MCP_MACHINE_UNUSED_NOTE: string;
+export declare const VERSE_MCP_MACHINE_EMPTY_NOTE = "No MCP servers are configured in this machine's home-level configs.";
+/**
+ * Name a config file by its path relative to $HOME (`.claude.json`,
+ * `.ashlr/settings.json`). Precise enough to act on, and free of the username
+ * that an absolute path would carry.
+ *
+ * A path outside $HOME is reported as `(outside home)` — its basename alone
+ * would be ambiguous and its full path is not ours to publish.
+ */
+export declare function homeRelativeSourceRef(path: string, home?: string): string;
+/** Project one discovered spec for transport, env values redacted. */
+export declare function projectMcpServerView(spec: McpServerSpec, home?: string): VerseMcpServerView;
+/**
+ * Resolve an account's private native state directory WITHOUT publishing it.
+ *
+ * connections.json carries each account's launcher argv. That argv is the
+ * account's identity and never leaves the server (src/core/verse/seats.ts:9).
+ * We read it here only to locate `<profile>/profile.json`, whose
+ * `nativeStatePath` is the directory the provider CLI is pinned to
+ * (`CODEX_HOME` / `GROK_HOME` / `CLAUDE_CONFIG_DIR`).
+ *
+ * Returns null rather than guessing when anything is missing.
+ */
+export declare function resolveAccountStateRoots(accountsRoot: string): Map<string, string>;
+/** The minimum a seat must carry for this view. Keeps tests free of fixtures. */
+export interface VerseMcpSeatInput {
+    id: string;
+    label: string;
+    engine: VerseEngine;
+    accountId: string;
+}
+/**
+ * Derive what one seat would load.
+ *
+ * `stateRoots` maps accountId -> private state directory (from
+ * {@link resolveAccountStateRoots}). A seat whose account is absent from it
+ * reports `mcp-account-profile-unresolved` rather than falling back to a
+ * machine-wide list.
+ */
+export declare function deriveVerseMcpSeatView(seat: VerseMcpSeatInput, stateRoots: ReadonlyMap<string, string>, home?: string): VerseMcpSeatView;
+/** The machine-wide registry, and the fact that no seat reads it. */
+export declare function buildVerseMcpMachineRegistry(paths?: string[], home?: string): VerseMcpMachineRegistry;
+export interface VerseMcpSnapshotOptions {
+    accountsRoot: string;
+    /** Seats to describe. Callers pass `discoverSeats()`'s public seat list. */
+    seats: readonly VerseMcpSeatInput[];
+    /** Injected machine config paths (tests). Defaults to knownConfigPaths(). */
+    machineConfigPaths?: string[];
+    /** Injected scope read (tests). Defaults to the real Locus shell-out. */
+    scope?: VerseMcpScope;
+    /** Injected home (tests). */
+    home?: string;
+}
+/**
+ * The read-only answer to "which MCP servers would each seat load".
+ *
+ * Deliberately does no discovery of its own beyond the two registries: it
+ * never enables, disables or reorders anything, and it never reports a server
+ * against a seat that would not load it.
+ */
+export declare function buildVerseMcpSnapshot(options: VerseMcpSnapshotOptions): VerseMcpSnapshot;
+/** Account identities, re-exported so a caller needs one import for the view. */
+export declare function verseMcpAccountIdentities(accountsRoot: string): VerseAccountIdentity[];

package/dist/core/verse/mcp-seat-view.js

@@ -0,0 +1,322 @@
+/**
+ * core/verse/mcp-seat-view.ts — which MCP servers each Verse seat would load.
+ *
+ * READ-ONLY. Nothing in this file writes, installs, enables or disables
+ * anything. docs/VERSE-WORKSPACES.md §3 asks for exactly one thing first:
+ * "Surface which servers each seat would load, since a server configured for
+ * one account should not silently apply to another."
+ *
+ * ── The finding this module exists to make visible ──────────────────────────
+ *
+ * `discoverMcpServers()` scans HOME-level JSON configs (see
+ * `knownConfigPaths()`): ~/.claude.json, ~/.claude/settings.json, ~/.mcp.json,
+ * ~/.ashlrcode/settings.json, ~/.ashlr-workbench/settings.json,
+ * ~/.aw/settings.json, ~/.ashlr/settings.json.
+ *
+ * NO VERSE SEAT READS ANY OF THEM. Verified against the adapters and the
+ * launcher, not recalled:
+ *
+ *   - CLAUDE and LOCAL seats: `buildClaudeLaunch` (src/core/verse/adapters/
+ *     claude.ts) puts `--strict-mcp-config --mcp-config '{"mcpServers":{}}'`
+ *     in every turn's argv, for both engines. That is a complete override:
+ *     the seat loads ZERO MCP servers, whatever any config file says.
+ *   - CODEX and GROK seats: their adapters add no MCP flag, so each loads its
+ *     OWN native config — and the account is pinned by a private per-account
+ *     state directory (`CODEX_HOME` / `GROK_HOME` / `CLAUDE_CONFIG_DIR` =
+ *     `<profile>/native-state`, src/core/resources/native-profile.ts:72-78,
+ *     :108). That directory is per ACCOUNT, so two Codex accounts already
+ *     cannot share a server by accident. Their config is `config.toml` —
+ *     TOML, which `discoverMcpServers()` (JSON only) cannot read.
+ *
+ * Reporting a machine-wide server list as "what this seat runs" would
+ * therefore be a lie in every direction at once: it would show servers no
+ * seat loads, and hide the per-account TOML that Codex and Grok actually do.
+ * So this module reports the two things separately and names the reason for
+ * each, and reports EMPTY rather than guessing.
+ *
+ * ── What may leave this module ──────────────────────────────────────────────
+ *
+ * Never: a launcher argv, an absolute native-profile path, a home-anchored
+ * absolute path, or a real env value. Config files are identified by their
+ * path RELATIVE TO $HOME (`.claude.json`, `.ashlr/settings.json`), which
+ * names the file precisely and carries no username. Every spec crosses the
+ * boundary through `redactEnv()`, whose whole reason for existing is that
+ * these specs carry secrets.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, isAbsolute, sep } from 'node:path';
+import { discoverMcpServers, redactEnv } from '../mcp-registry.js';
+import { readVerseAccountIdentities } from './accounts.js';
+import { readVerseMcpScope } from './mcp-scope.js';
+// ---------------------------------------------------------------------------
+// Verified facts about the adapters, encoded once
+// ---------------------------------------------------------------------------
+/**
+ * Engines whose adapter argv pins an EMPTY `--mcp-config` under
+ * `--strict-mcp-config`, so the seat can load nothing at all.
+ *
+ * Both entries come from one function: `buildClaudeLaunch` serves engine
+ * 'claude' and engine 'local' alike (the latter is the same `claude` binary
+ * with ANTHROPIC_BASE_URL pointed at Ollama).
+ *
+ * If that argv ever loses those two flags this constant becomes a lie, which
+ * is why `test/verse-mcp-seat-view.test.ts` asserts the flags are still in the
+ * adapter's real output rather than trusting this list.
+ */
+export const VERSE_MCP_ISOLATED_ENGINES = ['claude', 'local'];
+/** The two argv flags that make an isolated seat isolated. Asserted in tests. */
+export const VERSE_MCP_ISOLATION_FLAGS = ['--strict-mcp-config', '--mcp-config'];
+/**
+ * Per-account native config file, relative to that account's private state
+ * directory. Claude's is listed for completeness even though a Claude seat is
+ * isolated by its adapter before the file is ever consulted.
+ */
+const NATIVE_CONFIG_FILE = {
+    codex: { file: 'config.toml', format: 'toml' },
+    grok: { file: 'config.toml', format: 'toml' },
+    claude: { file: '.claude.json', format: 'json' },
+};
+// ---------------------------------------------------------------------------
+// Notes (plain language, no machine codes)
+// ---------------------------------------------------------------------------
+export const VERSE_MCP_ISOLATED_NOTE = 'Every turn on this seat is launched with --strict-mcp-config and an empty --mcp-config, ' +
+    'so it loads no MCP servers at all regardless of what any config file holds.';
+export const VERSE_MCP_TOML_NOTE = 'This account keeps its MCP servers in a TOML config, which is read by the provider CLI ' +
+    'itself and is not parsed here. Hub cannot list or change it without rewriting the ' +
+    "operator's TOML, which it deliberately does not do.";
+export const VERSE_MCP_PER_ACCOUNT_NOTE = 'This account runs against its own private state directory, so a server configured for ' +
+    'another account does not reach it.';
+export const VERSE_MCP_MACHINE_UNUSED_NOTE = 'These servers are configured in this machine\'s home-level configs. No Verse seat reads ' +
+    'them: Claude and local seats are launched with an empty --mcp-config, and Codex and Grok ' +
+    'seats read their own per-account config instead.';
+export const VERSE_MCP_MACHINE_EMPTY_NOTE = 'No MCP servers are configured in this machine\'s home-level configs.';
+// ---------------------------------------------------------------------------
+// Path handling — nothing absolute crosses the boundary
+// ---------------------------------------------------------------------------
+/**
+ * Name a config file by its path relative to $HOME (`.claude.json`,
+ * `.ashlr/settings.json`). Precise enough to act on, and free of the username
+ * that an absolute path would carry.
+ *
+ * A path outside $HOME is reported as `(outside home)` — its basename alone
+ * would be ambiguous and its full path is not ours to publish.
+ */
+export function homeRelativeSourceRef(path, home = homedir()) {
+    if (!isAbsolute(path))
+        return path;
+    const rel = relative(home, path);
+    if (rel.length === 0 || rel.startsWith('..') || isAbsolute(rel))
+        return '(outside home)';
+    return rel.split(sep).join('/');
+}
+/** Project one discovered spec for transport, env values redacted. */
+export function projectMcpServerView(spec, home = homedir()) {
+    const safe = redactEnv(spec);
+    return {
+        name: safe.name,
+        command: safe.command,
+        args: [...safe.args],
+        env: safe.env && Object.keys(safe.env).length > 0 ? { ...safe.env } : null,
+        sourceRef: homeRelativeSourceRef(safe.source, home),
+    };
+}
+// ---------------------------------------------------------------------------
+// Per-account private state directory
+// ---------------------------------------------------------------------------
+/**
+ * Resolve an account's private native state directory WITHOUT publishing it.
+ *
+ * connections.json carries each account's launcher argv. That argv is the
+ * account's identity and never leaves the server (src/core/verse/seats.ts:9).
+ * We read it here only to locate `<profile>/profile.json`, whose
+ * `nativeStatePath` is the directory the provider CLI is pinned to
+ * (`CODEX_HOME` / `GROK_HOME` / `CLAUDE_CONFIG_DIR`).
+ *
+ * Returns null rather than guessing when anything is missing.
+ */
+export function resolveAccountStateRoots(accountsRoot) {
+    const out = new Map();
+    let parsed;
+    try {
+        const raw = readFileSync(join(accountsRoot, 'connections.json'), 'utf8');
+        if (raw.length > 1024 * 1024)
+            return out;
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return out;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return out;
+    const accounts = parsed['accounts'];
+    if (!Array.isArray(accounts))
+        return out;
+    for (const entry of accounts) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const row = entry;
+        const id = row['id'];
+        const command = row['command'];
+        if (typeof id !== 'string' || id.length === 0 || !Array.isArray(command))
+            continue;
+        const launcher = command.find((part) => typeof part === 'string' && part.endsWith('launcher.mjs'));
+        if (launcher === undefined)
+            continue;
+        // profile.json is the launcher's own manifest (ResourceNativeProfile). It
+        // also carries the argv, so only `nativeStatePath` is lifted out of it.
+        let stateRoot = null;
+        try {
+            const manifest = JSON.parse(readFileSync(join(dirname(launcher), 'profile.json'), 'utf8'));
+            if (manifest !== null && typeof manifest === 'object' && !Array.isArray(manifest)) {
+                const value = manifest['nativeStatePath'];
+                if (typeof value === 'string' && value.length > 0)
+                    stateRoot = value;
+            }
+        }
+        catch {
+            stateRoot = null;
+        }
+        if (stateRoot !== null)
+            out.set(id, stateRoot);
+    }
+    return out;
+}
+/**
+ * Read one account's private JSON MCP registry.
+ *
+ * Only ever called for a JSON-format config. TOML is refused upstream rather
+ * than half-parsed.
+ */
+function readAccountJsonServers(stateRoot, file, home) {
+    const path = join(stateRoot, file);
+    if (!existsSync(path))
+        return { servers: [], ok: true };
+    // discoverMcpServers takes injected paths and never throws; a malformed
+    // config comes back as an empty registry, which we cannot distinguish from
+    // a config with no servers. That ambiguity is acceptable here because both
+    // render identically ("this seat loads nothing from its own config").
+    try {
+        const registry = discoverMcpServers([path]);
+        return { servers: registry.servers.map((spec) => projectMcpServerView(spec, home)), ok: true };
+    }
+    catch {
+        return { servers: [], ok: false };
+    }
+}
+/**
+ * Derive what one seat would load.
+ *
+ * `stateRoots` maps accountId -> private state directory (from
+ * {@link resolveAccountStateRoots}). A seat whose account is absent from it
+ * reports `mcp-account-profile-unresolved` rather than falling back to a
+ * machine-wide list.
+ */
+export function deriveVerseMcpSeatView(seat, stateRoots, home = homedir()) {
+    const base = { seatId: seat.id, label: seat.label, engine: seat.engine, accountId: seat.accountId };
+    // 1. Adapter isolation wins over every config on disk. Checking it FIRST is
+    //    the point: a Claude seat with a fully populated ~/.claude.json still
+    //    loads nothing, and saying otherwise is the exact lie this file avoids.
+    if (VERSE_MCP_ISOLATED_ENGINES.includes(seat.engine)) {
+        return {
+            ...base,
+            servers: [],
+            reason: 'mcp-seat-isolated-by-adapter',
+            configFile: null,
+            configFormat: null,
+            notes: [VERSE_MCP_ISOLATED_NOTE],
+        };
+    }
+    // 2. Native seats read their own per-account config.
+    const provider = seat.engine;
+    const config = NATIVE_CONFIG_FILE[provider];
+    if (config === undefined) {
+        return {
+            ...base,
+            servers: [],
+            reason: 'mcp-account-profile-unresolved',
+            configFile: null,
+            configFormat: null,
+            notes: [],
+        };
+    }
+    const stateRoot = stateRoots.get(seat.accountId);
+    if (stateRoot === undefined) {
+        return {
+            ...base,
+            servers: [],
+            reason: 'mcp-account-profile-unresolved',
+            configFile: config.file,
+            configFormat: config.format,
+            notes: [VERSE_MCP_PER_ACCOUNT_NOTE],
+        };
+    }
+    const exists = existsSync(join(stateRoot, config.file));
+    if (!exists) {
+        return {
+            ...base,
+            servers: [],
+            reason: 'mcp-account-config-absent',
+            configFile: config.file,
+            configFormat: config.format,
+            notes: [VERSE_MCP_PER_ACCOUNT_NOTE],
+        };
+    }
+    if (config.format === 'toml') {
+        return {
+            ...base,
+            servers: [],
+            reason: 'mcp-account-config-not-json',
+            configFile: config.file,
+            configFormat: 'toml',
+            notes: [VERSE_MCP_TOML_NOTE, VERSE_MCP_PER_ACCOUNT_NOTE],
+        };
+    }
+    const read = readAccountJsonServers(stateRoot, config.file, home);
+    return {
+        ...base,
+        servers: read.servers,
+        reason: read.ok ? 'mcp-account-config-read' : 'mcp-account-config-unreadable',
+        configFile: config.file,
+        configFormat: 'json',
+        notes: [VERSE_MCP_PER_ACCOUNT_NOTE],
+    };
+}
+// ---------------------------------------------------------------------------
+// Snapshot
+// ---------------------------------------------------------------------------
+/** The machine-wide registry, and the fact that no seat reads it. */
+export function buildVerseMcpMachineRegistry(paths, home = homedir()) {
+    const registry = discoverMcpServers(paths);
+    const servers = registry.servers.map((spec) => projectMcpServerView(spec, home));
+    return {
+        servers,
+        configured: servers.length > 0,
+        note: servers.length > 0 ? VERSE_MCP_MACHINE_UNUSED_NOTE : VERSE_MCP_MACHINE_EMPTY_NOTE,
+    };
+}
+/**
+ * The read-only answer to "which MCP servers would each seat load".
+ *
+ * Deliberately does no discovery of its own beyond the two registries: it
+ * never enables, disables or reorders anything, and it never reports a server
+ * against a seat that would not load it.
+ */
+export function buildVerseMcpSnapshot(options) {
+    const home = options.home ?? homedir();
+    const stateRoots = resolveAccountStateRoots(options.accountsRoot);
+    const seats = options.seats.map((seat) => deriveVerseMcpSeatView(seat, stateRoots, home));
+    const machine = buildVerseMcpMachineRegistry(options.machineConfigPaths, home);
+    const scope = options.scope ?? readVerseMcpScope();
+    const notes = [];
+    if (machine.configured && seats.every((seat) => seat.servers.length === 0)) {
+        notes.push(`${machine.servers.length} MCP server${machine.servers.length === 1 ? ' is' : 's are'} configured ` +
+            'on this machine and no Verse seat loads any of them.');
+    }
+    return { sampledAt: new Date().toISOString(), seats, machine, scope, notes };
+}
+/** Account identities, re-exported so a caller needs one import for the view. */
+export function verseMcpAccountIdentities(accountsRoot) {
+    return readVerseAccountIdentities(accountsRoot);
+}
+//# sourceMappingURL=mcp-seat-view.js.map