vgxness 1.9.8 → 1.10.0

package/dist/mcp/client-install-opencode-contract.js

@@ -2,14 +2,15 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, } from './opencode-default-agent-config.js';
 const opencodeConfigSchema = 'https://opencode.ai/config.json';
-const supportedConfigTargets = ['.opencode/opencode.json', 'opencode.json', '.opencode/opencode.jsonc', 'opencode.jsonc'];
+const opencodeUserGlobalOnlyMessage = 'VGX-managed OpenCode configuration is user-global only. Project/local OpenCode files are treated as external/manual diagnostics and will not be written by VGXNESS. Re-run without the project/local install scope.';
 export function resolveOpenCodeMcpInstallTarget(input) {
     const scope = input.scope ?? 'user';
     if (scope === 'project')
         return {
-            ok: true,
+            ok: false,
             scope,
-            path: join(input.cwd, '.opencode', 'opencode.json'),
+            reason: 'legacy_project_scope',
+            message: opencodeUserGlobalOnlyMessage,
         };
     const home = input.env?.HOME;
     if (typeof home !== 'string' || home.trim().length === 0) {
@@ -38,73 +39,7 @@ export function planOpenCodeMcpInstall(input) {
     if (scope === 'user') {
         return planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness, bashPermissionPolicy);
     }
-    const existingTargets = supportedConfigTargets
-        .map((relativePath) => ({
-        relativePath,
-        absolutePath: join(input.cwd, relativePath),
-    }))
-        .filter((target) => existsSync(target.absolutePath));
-    if (existingTargets.length > 1) {
-        return refusal('ambiguous_target', `Multiple OpenCode project config targets exist: ${existingTargets.map((target) => target.relativePath).join(', ')}. Remove ambiguity before installing.`, input.databasePath, databasePathSource, scope, undefined, [
-            {
-                kind: 'manual-check',
-                message: 'Remove ambiguity by keeping exactly one OpenCode project config target before installing.',
-            },
-        ], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    }
-    if (existingTargets.length === 0) {
-        return {
-            ...baseContract(input.databasePath, databasePathSource, scope, join(input.cwd, '.opencode', 'opencode.json'), false, 'create', agentPlan, overwriteVgxness, bashPermissionPolicy),
-            status: 'would_install',
-            action: 'create',
-            targetPath: join(input.cwd, '.opencode', 'opencode.json'),
-            backupRequired: false,
-            server,
-            preservedTopLevelKeys: createdConfigKeys(agentPlan),
-            existingSchema: null,
-        };
-    }
-    const [target] = existingTargets;
-    if (target === undefined)
-        return refusal('ambiguous_target', 'Unable to resolve OpenCode project config target.', input.databasePath, databasePathSource, scope, undefined, [], undefined, overwriteVgxness, bashPermissionPolicy);
-    if (target.relativePath.endsWith('.jsonc')) {
-        return refusal('unsupported_jsonc', `OpenCode JSONC config ${target.relativePath} is not supported yet; use JSON or remove comments first.`, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    }
-    const parsed = parseConfig(target.absolutePath);
-    if (!parsed.ok)
-        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    const config = parsed.value;
-    if (config.mcp !== undefined && !isRecord(config.mcp)) {
-        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    }
-    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness') && !overwriteVgxness) {
-        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    }
-    const agentConflict = findConflictingVgxnessAgents(config, agentPlan);
-    if (agentConflict.length > 0 && !overwriteVgxness) {
-        return refusal('existing_vgxness_agent', `Existing OpenCode config contains custom VGXNESS agent entries that would be overwritten: ${agentConflict.join(', ')}. Remove, rename, or manually reconcile them before installing.`, input.databasePath, databasePathSource, scope, target.absolutePath, [
-            {
-                kind: 'manual-check',
-                message: `Manually reconcile conflicting VGXNESS agent entries: ${agentConflict.join(', ')}.`,
-            },
-        ], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    }
-    if (agentPlan.installsAgents && config.agent !== undefined && !isRecord(config.agent)) {
-        return refusal('unsupported_config_shape', 'Existing top-level agent must be a JSON object before VGXNESS agent entries can be merged or overwritten.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    }
-    if (config.permission !== undefined && !isRecord(config.permission)) {
-        return refusal('unsupported_config_shape', 'Existing top-level permission must be a JSON object before VGXNESS can set top-level permission.bash to ask.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    }
-    return {
-        ...baseContract(input.databasePath, databasePathSource, scope, target.absolutePath, true, 'merge-preserve-existing', agentPlan, overwriteVgxness, bashPermissionPolicy),
-        status: 'would_install',
-        action: 'merge',
-        targetPath: target.absolutePath,
-        backupRequired: true,
-        server,
-        preservedTopLevelKeys: Object.keys(config),
-        existingSchema: typeof config.$schema === 'string' ? config.$schema : opencodeConfigSchema,
-    };
+    return refusal('unsupported_config_shape', opencodeUserGlobalOnlyMessage, input.databasePath, databasePathSource, scope, undefined, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
 }
 function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness, bashPermissionPolicy) {
     const target = resolveOpenCodeMcpInstallTarget({
@@ -263,8 +198,6 @@ function warningsForScope(scope, overwriteVgxness, agentPlan, bashPermissionPoli
         ]
         : [];
     const bashWarnings = bashPermissionPolicy.manager === 'allow' ? ['OpenCode top-level permission.bash is set to ask; the VGXNESS manager agent allows bash while SDD subagents keep explicit permissions.'] : ['OpenCode top-level permission.bash is set to ask.'];
-    if (scope === 'project')
-        return ['Restart OpenCode after installation so it reloads the project MCP config.', ...overwriteWarnings, ...bashWarnings];
     return [
         'Restart OpenCode after installation so it reloads the user MCP config.',
         'OpenCode project config may override user config for a workspace; check project-level config if vgxness is not visible.',
@@ -280,13 +213,6 @@ function createdConfigKeys(agentPlan) {
     return [...keys, 'permission'];
 }
 function manualTestForScope(scope, databasePath, source) {
-    if (scope === 'project') {
-        return {
-            restart: 'Restart OpenCode after the config is installed.',
-            verify: 'Open the project in OpenCode and verify the vgxness MCP server is available.',
-            doctorCommand: createVgxnessMcpDoctorCommand(databasePath, source),
-        };
-    }
     return {
         restart: 'Restart OpenCode after the user config is installed.',
         verify: 'Open OpenCode and verify the vgxness MCP server is available from the user OpenCode config; project config may override it.',

package/dist/mcp/opencode-visibility.js

@@ -15,7 +15,7 @@ export function createOpenCodeMcpVisibilityReport(options) {
     const projectVisibleFromCurrentCwd = cwdInsideProject && projectConfigExists && projectHasVgxnessServer;
     const userTarget = resolveOpenCodeMcpInstallTarget({ cwd: projectRoot, scope: 'user', env: options.env });
     const userReport = userTarget.ok ? userVisibilityReport(userTarget.path, projectVisibleFromCurrentCwd) : undefined;
-    const selectedTargetPath = targetScope === 'user' && userTarget.ok ? userTarget.path : projectTargetPath;
+    const selectedTargetPath = userTarget.ok ? userTarget.path : '$HOME/.config/opencode/opencode.json';
     const selectedReady = targetScope === 'user' ? userReport?.configExists === true && userReport.hasVgxnessServer : projectVisibleFromCurrentCwd;
     return {
         version: 1,
@@ -57,6 +57,9 @@ function buildGuidance(state) {
         guidance.push('User scope targets `$HOME/.config/opencode/opencode.json` and this diagnostic reads it without writing provider config.');
         guidance.push('Project OpenCode config can override user config for a workspace; inspect project config first when both define `mcp.vgxness`.');
     }
+    if (state.targetScope === 'project') {
+        guidance.push('VGX-managed OpenCode installs are user-global only; project OpenCode config is read as external/manual diagnostics and will not be written by VGXNESS.');
+    }
     if (state.userTargetMessage !== undefined)
         guidance.push(state.userTargetMessage);
     if (state.userOverridden)
@@ -65,8 +68,6 @@ function buildGuidance(state) {
         guidance.push('The project-local `vgxness` server is not expected to appear from outside the worktree.');
         guidance.push('Use `mcp install opencode --scope user --plan` to inspect the user config target without writing it.');
     }
-    if (!state.configExists && state.targetScope === 'project')
-        guidance.push('Expected project-local config `.opencode/opencode.json` was not found.');
     if (state.configExists && !state.hasVgxnessServer)
         guidance.push('Project-local config exists, but it does not define `mcp.vgxness`.');
     return guidance;

package/dist/mcp/provider-change-plan.js

@@ -2,8 +2,8 @@ import { resolveMemoryDatabasePath } from '../memory/storage-paths.js';
 import { planClaudeCodeMcpInstall } from './client-install-claude-code-contract.js';
 import { planOpenCodeMcpInstall } from './client-install-opencode-contract.js';
 import { ProviderDoctorService } from './provider-doctor.js';
+import { providerRuntimeContext } from './provider-health-types.js';
 import { ProviderStatusService } from './provider-status.js';
-import { resolveClaudeCodeScope } from './claude-code-scope.js';
 export const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
 export const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const safety = {
@@ -76,13 +76,10 @@ export class ProviderChangePlanService {
         const doctor = (this.deps.providerDoctor ?? new ProviderDoctorService()).getDoctor({ project: normalized.project, scope: normalized.scope, providerAdapter: 'claude', workspaceRoot: normalized.workspaceRoot, env: this.deps.env ?? process.env, payloadMode: normalized.payloadMode });
         if (!doctor.ok)
             return doctor;
-        const claudeScope = resolveClaudeCodeScope(normalized.scope);
-        if (!claudeScope.ok)
-            return claudeScope;
         const databasePath = resolveMemoryDatabasePath({ cwd: normalized.workspaceRoot, env: this.deps.env ?? process.env });
         if (!databasePath.ok)
             return { ok: true, value: blockedPlanEnvelope(normalized, status.value, doctor.value, databasePath.error.message) };
-        const installPlan = planClaudeCodeMcpInstall({ cwd: normalized.workspaceRoot, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source, scope: normalized.scope, env: this.deps.env ?? process.env });
+        const installPlan = planClaudeCodeMcpInstall({ cwd: normalized.workspaceRoot, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source, scope: 'user', env: this.deps.env ?? process.env });
         return { ok: true, value: claudeEnvelope(normalized, status.value, doctor.value, installPlan, databasePath.value.source) };
     }
 }
@@ -90,6 +87,7 @@ function normalizeInput(input) {
     return {
         project: input.project?.trim() || 'vgxness',
         scope: input.scope ?? 'project',
+        installTarget: input.installTarget ?? 'user-global',
         provider: input.provider,
         changeType: input.changeType,
         workspaceRoot: input.workspaceRoot.trim(),
@@ -134,6 +132,7 @@ function blockedPlanEnvelope(input, status, doctor, message) {
         },
         statusSummary: statusSummary(status),
         statusFindings: status.config,
+        configClassification: status.configClassification,
         doctorSummary: doctorSummary(doctor),
         doctorFindings: doctor.checks,
         previewEffects: {
@@ -162,6 +161,7 @@ function opencodeEnvelope(input, status, doctor, installPlan, source) {
         },
         statusSummary: statusSummary(status),
         statusFindings: status.config,
+        configClassification: status.configClassification,
         doctorSummary: doctorSummary(doctor),
         doctorFindings: doctor.checks,
         previewEffects: previewEffects(installPlan),
@@ -185,10 +185,11 @@ function claudeEnvelope(input, status, doctor, installPlan, source) {
         supported: true,
         status: installPlan.status === 'refused' ? 'blocked' : 'planned',
         ...(installPlan.status === 'refused' ? { code: 'PLAN_UNAVAILABLE' } : {}),
-        summary: installPlan.status === 'refused' ? `Read-only Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}` : `Read-only Claude ${input.changeType} planning completed; future confirmed write would update ${installPlan.canonicalClaudeScope === 'user' ? '~/.claude.json, user agents, and ~/.claude/CLAUDE.md' : 'project .mcp.json, agent files, and project-root CLAUDE.md'} as needed.`,
+        summary: installPlan.status === 'refused' ? `Read-only Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}` : 'Read-only Claude planning completed; future confirmed write would update ~/.claude.json, user agents, and ~/.claude/CLAUDE.md as needed. Project/local Claude files are diagnostics only.',
         providerIdentity: { provider: 'claude', adapter: 'claude', support: 'supported' },
         statusSummary: statusSummary(status),
         statusFindings: status.config,
+        configClassification: status.configClassification,
         doctorSummary: doctorSummary(doctor),
         doctorFindings: doctor.checks,
         previewEffects: previewEffectsClaude(installPlan),
@@ -205,11 +206,13 @@ function baseEnvelope(input) {
         kind: 'provider-change-plan',
         project: input.project,
         scope: input.scope,
+        installTarget: input.installTarget,
         provider: input.provider,
         requestedChangeType: input.changeType,
         normalizedChangeType: normalizeChangeType(input.provider, input.changeType),
         payloadMode: input.payloadMode,
         workspaceRoot: input.workspaceRoot,
+        runtimeContext: providerRuntimeContext(input),
         safety,
     };
 }
@@ -323,7 +326,7 @@ function risksForOpenCode(status, doctor, plan, source) {
     return risks;
 }
 function risksForClaude(status, doctor, plan, source) {
-    const risks = [plan.canonicalClaudeScope === 'user' ? 'Claude user/global files affect this OS user; backups are required before merging existing files.' : 'Claude project .mcp.json and project-root CLAUDE.md may affect collaborators if committed; review before committing.', 'Claude Code runtime MCP approval happens in Claude Code; this plan does not prove runtime connection.'];
+    const risks = ['Claude user/global files affect this OS user; backups are required before merging existing files.', 'Claude Code runtime MCP approval happens in Claude Code; this plan does not prove runtime connection.'];
     if (status.status !== 'ready')
         risks.push(`Provider status is ${status.status}; future writes should review status findings first.`);
     if (doctor.status !== 'healthy')

package/dist/mcp/provider-doctor.js

@@ -7,7 +7,7 @@ import { inspectClaudeCodeUserMcpConfig } from './claude-code-user-config.js';
 import { inspectClaudeUserMemory } from './claude-code-user-memory.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
 import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
-import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, providerHealthFailure, isUserGlobalScope, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, rollupProviderDoctor, } from './provider-health-types.js';
+import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, classifyProviderConfigPaths, providerHealthFailure, providerRuntimeContext, isUserGlobalScope, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, rollupProviderDoctor, } from './provider-health-types.js';
 import { inspectOpenCodeConfigPaths } from './provider-status.js';
 export class ProviderDoctorService {
     deps;
@@ -65,6 +65,8 @@ export class ProviderDoctorService {
                 providerAdapter: normalized.providerAdapter,
                 scope: normalized.scope,
                 workspaceRoot: normalized.workspaceRoot,
+                runtimeContext: providerRuntimeContext(normalized),
+                configClassification: classifyProviderConfigPaths(paths),
                 status,
                 payloadMode: normalized.payloadMode,
                 overallStatus: status,
@@ -105,24 +107,24 @@ export class ProviderDoctorService {
         const memoryFiles = advisoryPaths.filter((path) => existsSync(path));
         const checks = [
             { id: 'workspace-root', status: existsSync(normalized.workspaceRoot) ? 'pass' : 'fail', detail: `Workspace root ${existsSync(normalized.workspaceRoot) ? 'exists' : 'does not exist'}: ${normalized.workspaceRoot}` },
-            { id: 'provider-supported', status: 'pass', detail: 'Claude provider adapter selected for CLI MCP registration diagnostics, project .mcp.json compatibility, and Claude agents support.' },
+            { id: 'provider-supported', status: 'pass', detail: 'Claude provider adapter selected. VGX-managed Claude writes are user-global only; project Claude files are advisory external/manual diagnostics.' },
             { id: 'claude-scope', status: 'pass', detail: 'Claude scope project resolved to canonical project.' },
             { id: 'claude-cli-presence', status: 'warn', detail: 'Read-only doctor does not execute `claude --version`; CLI availability is diagnosed during explicit apply/preflight only.' },
-            { id: 'claude-project-mcp-readable', status: mcp.status === 'invalid' ? 'fail' : mcp.status === 'missing' ? 'not-configured' : 'pass', detail: mcp.message, ...(mcp.status === 'invalid' ? { remediation: 'Fix malformed .mcp.json before installing VGXNESS Claude support.' } : {}) },
-            { id: 'claude-vgxness-mcp-entry', status: mcp.status === 'configured' ? 'pass' : mcp.status === 'conflicting' ? 'fail' : 'not-configured', detail: mcp.message, ...(mcp.status === 'conflicting' ? { remediation: 'Manually reconcile mcpServers.vgxness before applying VGXNESS Claude support.' } : {}) },
-            { id: 'claude-agents-directory', status: agents.directoryExists ? 'pass' : 'not-configured', detail: agents.directoryExists ? 'Claude project agents directory exists.' : 'Claude project agents directory is missing; confirmed apply may create it.' },
+            { id: 'claude-project-mcp-readable', status: mcp.status === 'invalid' ? 'warn' : 'pass', detail: `${mcp.message} Advisory only; VGXNESS will not write project .mcp.json.`, ...(mcp.status === 'invalid' ? { remediation: 'Fix malformed project .mcp.json manually if Claude Code should read it.' } : {}) },
+            { id: 'claude-vgxness-mcp-entry', status: mcp.status === 'conflicting' ? 'warn' : 'pass', detail: `${mcp.message} Advisory only; managed Claude MCP registration is user-global.`, ...(mcp.status === 'conflicting' ? { remediation: 'Manually reconcile project mcpServers.vgxness only if you intend to keep external project Claude config.' } : {}) },
+            { id: 'claude-agents-directory', status: 'pass', detail: agents.directoryExists ? 'Claude project agents directory exists as external/manual diagnostics.' : 'Claude project agents directory is absent; VGXNESS will not create project-local Claude agents.' },
             {
                 id: 'claude-vgxness-agents',
-                status: blockingAgents.length > 0 ? 'fail' : missingAgents.length > 0 ? 'not-configured' : 'pass',
+                status: blockingAgents.length > 0 ? 'warn' : 'pass',
                 detail: blockingAgents.length > 0
-                    ? `Conflicting or invalid VGXNESS Claude agents: ${blockingAgents.map((agent) => agent.agentName).join(', ')}.`
+                    ? `External/manual project Claude agents conflict or are invalid; VGXNESS will not repair them: ${blockingAgents.map((agent) => agent.agentName).join(', ')}.`
                     : missingAgents.length > 0
-                        ? `Missing VGXNESS Claude agents: ${missingAgents.map((agent) => agent.agentName).join(', ')}.`
-                        : 'Expected VGXNESS Claude agent targets were inspected.',
+                        ? `Project-local VGXNESS Claude agents are absent; they are no longer managed targets.`
+                        : 'External/manual project Claude agent files were inspected.',
             },
-            { id: 'claude-agent-frontmatter', status: badFrontmatter.length === 0 ? 'pass' : 'fail', detail: badFrontmatter.length === 0 ? 'Expected Claude agent frontmatter is valid.' : `Invalid or missing frontmatter for: ${badFrontmatter.map((agent) => agent.agentName).join(', ')}.` },
-            { id: 'claude-agent-generated-metadata', status: badMarkers.length === 0 ? 'pass' : 'fail', detail: badMarkers.length === 0 ? 'Existing VGXNESS Claude agent files include generated metadata markers.' : `Missing VGXNESS generated marker for: ${badMarkers.map((agent) => agent.agentName).join(', ')}.` },
-            claudeProjectMemoryCheck(projectMemory),
+            { id: 'claude-agent-frontmatter', status: badFrontmatter.length === 0 ? 'pass' : 'warn', detail: badFrontmatter.length === 0 ? 'No invalid project Claude agent frontmatter was detected.' : `External/manual project Claude agent frontmatter is invalid for: ${badFrontmatter.map((agent) => agent.agentName).join(', ')}.` },
+            { id: 'claude-agent-generated-metadata', status: badMarkers.length === 0 ? 'pass' : 'warn', detail: badMarkers.length === 0 ? 'No project Claude agent metadata marker issues were detected.' : `External/manual project Claude agents are missing VGXNESS generated markers: ${badMarkers.map((agent) => agent.agentName).join(', ')}.` },
+            advisoryProjectMemoryCheck(projectMemory),
             { id: 'claude-project-memory-advisory', status: memoryFiles.length === 0 ? 'pass' : 'warn', detail: memoryFiles.length === 0 ? 'No Claude project memory/settings advisory files were found.' : `Advisory only; VGXNESS will not modify: ${memoryFiles.join(', ')}.` },
             readonlySafetyCheck(before, snapshotPaths(checkedPathList, normalized.workspaceRoot)),
         ];
@@ -131,7 +133,7 @@ export class ProviderDoctorService {
         const checkedPaths = normalized.payloadMode === 'verbose' ? checkedPathList : checkedPathList.filter((path) => existsSync(path) || path === mcp.path);
         const failedChecks = checks.filter((check) => check.status === 'fail').map((check) => check.id);
         const recommendations = checks.flatMap((check) => (check.remediation === undefined ? [] : [check.remediation]));
-        return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: PROVIDER_HEALTH_SAFETY } };
+        return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, runtimeContext: providerRuntimeContext(normalized), configClassification: externalProjectClassification(checkedPathList), status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: PROVIDER_HEALTH_SAFETY } };
     }
     getClaudeUserGlobalDoctor(normalized, canonicalScope = 'user', scopeWarnings = []) {
         const mcp = inspectClaudeCodeUserMcpConfig(normalized.env);
@@ -162,9 +164,15 @@ export class ProviderDoctorService {
         const failedChecks = checks.filter((check) => check.status === 'fail').map((check) => check.id);
         const recommendations = checks.flatMap((check) => (check.remediation === undefined ? [] : [check.remediation]));
         const checkedPaths = normalized.payloadMode === 'verbose' ? checkedPathList : checkedPathList.filter((path) => existsSync(path) || path === mcp.path || path === userMemory.path);
-        return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${canonicalScope}:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: { ...PROVIDER_HEALTH_SAFETY, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES } } };
+        return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, runtimeContext: providerRuntimeContext(normalized), configClassification: managedUserGlobalClassification(checkedPathList), status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${canonicalScope}:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: { ...PROVIDER_HEALTH_SAFETY, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES } } };
     }
 }
+function externalProjectClassification(paths) {
+    return { managedUserGlobalConfig: [], detectedExternalProjectConfig: paths.filter((path) => existsSync(path)), detectedExternalUserConfig: [] };
+}
+function managedUserGlobalClassification(paths) {
+    return { managedUserGlobalConfig: [...paths], detectedExternalProjectConfig: [], detectedExternalUserConfig: [] };
+}
 function summarizeDoctor(status, failedCount, recommendationCount) {
     if (status === 'healthy')
         return 'Provider doctor checks passed; no configuration was changed.';
@@ -289,6 +297,15 @@ function claudeProjectMemoryCheck(state) {
                 : { remediation: 'Run confirmed Claude project install when ready.' }),
     };
 }
+function advisoryProjectMemoryCheck(state) {
+    const status = state.status === 'blocked' || state.status === 'managed-stale' ? 'warn' : 'pass';
+    return {
+        id: 'claude-project-memory-managed-block',
+        status,
+        detail: `${state.message} Advisory only; VGXNESS will not write project-root CLAUDE.md.`,
+        ...(status === 'warn' ? { remediation: 'Manually reconcile project-root CLAUDE.md only if you intend to keep external project Claude memory.' } : {}),
+    };
+}
 function snapshotPaths(paths, workspaceRoot) {
     const unique = [...paths, `${workspaceRoot}/.vgx`];
     return Object.fromEntries(unique.map((path) => [path, existsSync(path) ? statSync(path).mtimeMs : false]));

package/dist/mcp/provider-health-types.js

@@ -12,9 +12,28 @@ export const PROVIDER_HEALTH_SAFETY = {
     executesProvider: false,
 };
 export const CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES = ['status', 'doctor', 'change-plan'];
+export function providerConfigPathDiagnostics(ownership, exists) {
+    return {
+        ownership,
+        managed: ownership === 'managed-user-global',
+        readOnlyDiagnostic: true,
+        mayAffectProviderBehaviorExternally: ownership.startsWith('external-') && exists,
+        ...(ownership === 'managed-user-global' ? { installTarget: 'user-global' } : {}),
+    };
+}
 export function isUserGlobalScope(scope) {
     return scope === 'personal' || scope === 'user';
 }
+export function providerRuntimeContext(input) {
+    return { project: input.project, workspaceRoot: input.workspaceRoot, diagnosticScope: input.scope };
+}
+export function classifyProviderConfigPaths(paths) {
+    return {
+        managedUserGlobalConfig: paths.filter((path) => path.diagnostics.ownership === 'managed-user-global').map((path) => path.path),
+        detectedExternalProjectConfig: paths.filter((path) => path.diagnostics.ownership === 'external-project' && path.exists).map((path) => path.path),
+        detectedExternalUserConfig: paths.filter((path) => path.diagnostics.ownership === 'external-user' && path.exists).map((path) => path.path),
+    };
+}
 export const REQUIRED_PROVIDER_MCP_TOOLS = ['vgxness_provider_status', 'vgxness_provider_doctor', 'vgxness_provider_change_plan'];
 export const REQUIRED_PROVIDER_NATIVE_MCP_TOOLS = [
     'vgxness_provider_status',

package/dist/mcp/provider-status.js

@@ -9,7 +9,7 @@ import { inspectClaudeUserMemory } from './claude-code-user-memory.js';
 import { resolveOpenCodeMcpInstallTarget } from './client-install-opencode-contract.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodePromptContractVersion, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
 import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
-import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, providerHealthFailure, isUserGlobalScope, REQUIRED_PROVIDER_MCP_TOOLS, rollupProviderHealth, } from './provider-health-types.js';
+import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, classifyProviderConfigPaths, providerConfigPathDiagnostics, providerRuntimeContext, providerHealthFailure, isUserGlobalScope, REQUIRED_PROVIDER_MCP_TOOLS, rollupProviderHealth, } from './provider-health-types.js';
 const projectConfigTargets = ['.opencode/opencode.json', 'opencode.json', '.opencode/opencode.jsonc', 'opencode.jsonc'];
 export class ProviderStatusService {
     deps;
@@ -59,6 +59,8 @@ export class ProviderStatusService {
             providerAdapter: normalized.providerAdapter,
             scope: normalized.scope,
             workspaceRoot: normalized.workspaceRoot,
+            runtimeContext: providerRuntimeContext(normalized),
+            configClassification: classifyProviderConfigPaths(paths),
             status,
             overallStatus: status,
             inspectedPaths: checkedPaths,
@@ -123,6 +125,8 @@ export class ProviderStatusService {
             providerAdapter: 'claude',
             scope: normalized.scope,
             workspaceRoot: normalized.workspaceRoot,
+            runtimeContext: providerRuntimeContext(normalized),
+            configClassification: classifyProviderConfigPaths(paths),
             status,
             overallStatus: status,
             inspectedPaths: checkedPaths,
@@ -153,7 +157,7 @@ export class ProviderStatusService {
         const mcpState = inspectClaudeCodeUserMcpConfig(normalized.env);
         const agents = inspectClaudeCodeAgents({ workspaceRoot: normalized.workspaceRoot, scope: 'user', env: normalized.env });
         const userMemory = inspectClaudeUserMemory(normalized.env);
-        const userMemoryPathStatus = { ...claudeProjectMemoryPathStatus(userMemory), label: 'user ~/.claude/CLAUDE.md managed block' };
+        const userMemoryPathStatus = { ...claudeProjectMemoryPathStatus(userMemory, 'managed-user-global'), label: 'user ~/.claude/CLAUDE.md managed block' };
         const paths = [claudeUserMcpConfigPathStatus(mcpState), userMemoryPathStatus];
         const mcpEntry = claudeUserMcpEntryStatus(mcpState);
         const agentStatuses = agents.agents.map((agent) => (agent.status === 'managed' ? 'pass' : agent.status === 'missing' ? 'not-configured' : 'fail'));
@@ -173,6 +177,8 @@ export class ProviderStatusService {
             providerAdapter: 'claude',
             scope: normalized.scope,
             workspaceRoot: normalized.workspaceRoot,
+            runtimeContext: providerRuntimeContext(normalized),
+            configClassification: classifyProviderConfigPaths(paths),
             status,
             overallStatus: status,
             inspectedPaths: checkedPaths,
@@ -211,7 +217,7 @@ function claudeConfigHealthStatus(statuses) {
         return 'warn';
     return 'pass';
 }
-function claudeProjectMemoryPathStatus(state) {
+function claudeProjectMemoryPathStatus(state, ownership = 'external-project') {
     const status = state.status === 'managed-current' ? 'pass' : state.status === 'managed-stale' ? 'warn' : state.status === 'blocked' ? 'fail' : 'not-configured';
     return {
         label: 'project CLAUDE.md managed block',
@@ -221,12 +227,13 @@ function claudeProjectMemoryPathStatus(state) {
         parsed: state.status === 'managed-current' || state.status === 'managed-stale',
         status,
         detail: state.message,
+        diagnostics: providerConfigPathDiagnostics(ownership, state.exists),
     };
 }
 function compactPaths(paths, mode) {
     if (mode === 'verbose')
         return paths;
-    return paths.map((path) => ({ label: path.label, path: path.path, status: path.status }));
+    return paths.map((path) => ({ label: path.label, path: path.path, status: path.status, diagnostics: path.diagnostics }));
 }
 function compactMcpEntry(entry, mode) {
     if (mode === 'verbose')
@@ -260,12 +267,12 @@ function readFirstParsedConfig(paths) {
     }
 }
 export function inspectProjectConfigPaths(workspaceRoot) {
-    return projectConfigTargets.map((relativePath) => inspectConfigPath(relativePath, join(workspaceRoot, relativePath)));
+    return projectConfigTargets.map((relativePath) => inspectConfigPath(relativePath, join(workspaceRoot, relativePath), 'external-project'));
 }
 export function inspectOpenCodeConfigPaths(workspaceRoot, env = process.env) {
     const userTarget = resolveOpenCodeMcpInstallTarget({ cwd: workspaceRoot, scope: 'user', env });
     const userPaths = userTarget.ok
-        ? [inspectConfigPath('user ~/.config/opencode/opencode.json', userTarget.path)]
+        ? [inspectConfigPath('user ~/.config/opencode/opencode.json', userTarget.path, 'managed-user-global')]
         : [
             {
                 label: 'user ~/.config/opencode/opencode.json',
@@ -275,13 +282,14 @@ export function inspectOpenCodeConfigPaths(workspaceRoot, env = process.env) {
                 parsed: false,
                 status: 'warn',
                 detail: userTarget.message,
+                diagnostics: providerConfigPathDiagnostics('managed-user-global', false),
             },
         ];
     return [...userPaths, ...inspectProjectConfigPaths(workspaceRoot)];
 }
-function inspectConfigPath(label, path) {
+function inspectConfigPath(label, path, ownership = 'not-managed') {
     if (!existsSync(path))
-        return { label, path, exists: false, readable: false, parsed: false, status: 'not-configured', detail: 'Config path does not exist.' };
+        return { label, path, exists: false, readable: false, parsed: false, status: 'not-configured', detail: 'Config path does not exist.', diagnostics: providerConfigPathDiagnostics(ownership, false) };
     if (label.endsWith('.jsonc'))
         return {
             label,
@@ -291,14 +299,15 @@ function inspectConfigPath(label, path) {
             parsed: false,
             status: 'warn',
             detail: 'JSONC config exists but is not parsed by this read-only status check.',
+            diagnostics: providerConfigPathDiagnostics(ownership, true),
         };
     try {
         JSON.parse(readFileSync(path, 'utf8'));
-        return { label, path, exists: true, readable: true, parsed: true, status: 'pass', detail: 'Config exists and parses as JSON.' };
+        return { label, path, exists: true, readable: true, parsed: true, status: 'pass', detail: 'Config exists and parses as JSON.', diagnostics: providerConfigPathDiagnostics(ownership, true) };
     }
     catch (cause) {
         const message = cause instanceof Error ? cause.message : String(cause);
-        return { label, path, exists: true, readable: false, parsed: false, status: 'fail', detail: `Config could not be read or parsed: ${message}` };
+        return { label, path, exists: true, readable: false, parsed: false, status: 'fail', detail: `Config could not be read or parsed: ${message}`, diagnostics: providerConfigPathDiagnostics(ownership, true) };
     }
 }
 function inspectOpenCodeMcpEntry(paths) {

package/dist/mcp/schema.js

@@ -97,7 +97,7 @@ export function toInternalVgxMcpToolName(toolName) {
     return EXPOSED_TO_INTERNAL_TOOL_NAMES[toolName];
 }
 const scopes = ['project', 'personal'];
-const providerScopes = ['project', 'personal', 'local', 'user'];
+const providerInstallTargets = ['user-global'];
 const agentModes = ['agent', 'subagent'];
 const memoryTypes = ['architecture', 'decision', 'bugfix', 'pattern', 'config', 'discovery', 'learning', 'preference', 'manual'];
 const activityKinds = ['prompt', 'tool_call', 'artifact', 'summary', 'error'];
@@ -469,7 +469,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_status: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(providerScopes).optional(),
+        scope: z.enum(scopes).optional(),
         providerAdapter: z.enum(['opencode', 'claude']).optional(),
         workspaceRoot: z.string().min(1).optional(),
         change: z.string().min(1).optional(),
@@ -479,7 +479,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_doctor: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(providerScopes).optional(),
+        scope: z.enum(scopes).optional(),
         providerAdapter: z.enum(['opencode', 'claude']).optional(),
         workspaceRoot: z.string().min(1).optional(),
         expectedPromptContractVersion: z.number().int().positive().optional(),
@@ -489,7 +489,8 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_change_plan: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(providerScopes).optional(),
+        scope: z.enum(scopes).optional(),
+        installTarget: z.enum(providerInstallTargets).optional(),
         provider: z.enum(providerChangePlanProviders),
         changeType: z.enum(providerChangePlanTypes),
         workspaceRoot: z.string().min(1),

package/dist/mcp/validation.js

@@ -16,6 +16,8 @@ const payloadModes = ['compact', 'verbose'];
 const contextCockpitLevels = ['compact', 'expanded', 'verbose'];
 const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
 const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
+const providerInstallTargets = ['user-global'];
+const providerUserGlobalOnlyMigrationMessage = 'VGX-managed provider configuration is user-global only for OpenCode and Claude. Project/local provider files are treated as external/manual diagnostics and will not be written by VGXNESS. Use installTarget: user-global.';
 const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const validMemoryTopicKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 const maxMemoryTitleLength = 200;
@@ -139,7 +141,7 @@ function readVerificationChangeType(record, tool) {
     return { ok: true, value: trimmed };
 }
 function validateProviderChangePlanInput(input, tool) {
-    const record = inputRecord(input, tool, ['project', 'scope', 'provider', 'changeType', 'workspaceRoot', 'payloadMode']);
+    const record = inputRecord(input, tool, ['project', 'scope', 'installTarget', 'provider', 'changeType', 'workspaceRoot', 'payloadMode']);
     if (!record.ok)
         return record;
     const provider = readRequiredOneOf(record.value, 'provider', providerChangePlanProviders, tool);
@@ -170,6 +172,14 @@ function validateProviderChangePlanInput(input, tool) {
         return scope;
     if (scope.value !== undefined)
         result.scope = scope.value;
+    if (typeof record.value.installTarget === 'string' && record.value.installTarget.trim() !== 'user-global') {
+        return validationFailure(providerUserGlobalOnlyMigrationMessage, tool);
+    }
+    const installTarget = readOptionalOneOf(record.value, 'installTarget', providerInstallTargets, tool);
+    if (!installTarget.ok)
+        return installTarget;
+    if (installTarget.value !== undefined)
+        result.installTarget = installTarget.value;
     return { ok: true, value: result };
 }
 function validateProviderHealthInput(input, tool) {

package/dist/setup/backup-rollback-service.js

@@ -1,6 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 export function createConfigBackupPath(targetPath, label = 'backup') {
     return `${targetPath}.${label}-${new Date().toISOString().replaceAll(/[-:.]/g, '')}`;
 }
@@ -202,12 +203,18 @@ function classifyBackup(backupPath) {
         return managedSummary(backupPath, metadataPath, parsed.value, validation.blockers, validation.warnings);
     }
     const target = inferRollbackTarget(backupPath);
+    const blockers = target.ok ? [] : [target.error.message];
+    if (target.ok) {
+        const rollbackTargetBlocker = validateProviderRollbackTarget(target.value);
+        if (rollbackTargetBlocker !== undefined)
+            blockers.push(rollbackTargetBlocker);
+    }
     return {
         kind: 'legacy',
         backupPath,
         provider: 'opencode',
         ...(target.ok ? { targetPath: target.value } : {}),
-        blockers: target.ok ? [] : [target.error.message],
+        blockers,
         warnings: ['Legacy backup has no VGXNESS sidecar metadata; target is inferred from the filename.'],
     };
 }
@@ -238,8 +245,32 @@ function validateMetadataBinding(backupPath, metadata) {
     }
     else
         blockers.push(`Backup file does not exist: ${backupPath}`);
+    const rollbackTargetBlocker = validateProviderRollbackTarget(metadata.target.path);
+    if (rollbackTargetBlocker !== undefined)
+        blockers.push(rollbackTargetBlocker);
     return { blockers, warnings };
 }
+function validateProviderRollbackTarget(targetPath) {
+    const normalizedTarget = resolve(targetPath);
+    if (isManagedUserGlobalProviderTarget(normalizedTarget))
+        return undefined;
+    return `Refusing to restore provider config backup to ${normalizedTarget}. VGX-managed provider rollback writes user-global OpenCode/Claude targets only; project-local provider files are external/manual diagnostics and will not be restored.`;
+}
+function isManagedUserGlobalProviderTarget(targetPath) {
+    const home = resolve(homedir());
+    if (targetPath === resolve(home, '.config', 'opencode', 'opencode.json'))
+        return true;
+    if (targetPath === resolve(home, '.claude.json'))
+        return true;
+    if (targetPath === resolve(home, '.claude', 'CLAUDE.md'))
+        return true;
+    const claudeAgentsRoot = resolve(home, '.claude', 'agents');
+    return isPathInside(claudeAgentsRoot, targetPath) && dirname(targetPath) === claudeAgentsRoot && basename(targetPath).endsWith('.md');
+}
+function isPathInside(parentPath, candidatePath) {
+    const relation = relative(parentPath, candidatePath);
+    return relation === '' || (relation !== '' && !relation.startsWith('..') && !isAbsolute(relation));
+}
 function managedSummary(backupPath, metadataPath, metadata, blockers, warnings) {
     return {
         kind: 'managed',