vgxness 1.9.8 → 1.10.1

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(),
@@ -102,7 +100,7 @@ function unsupportedProviderEnvelope(input) {
         supported: false,
         status: 'unsupported',
         code: 'UNSUPPORTED_PROVIDER',
-        summary: `${input.provider} is a recognized provider value, but read-only provider change planning currently supports OpenCode and Claude.`,
+        summary: `[read-only] ${input.provider} is a recognized provider value, but provider change planning currently supports OpenCode and Claude. No provider config was written. This diagnostic does not install or repair provider config.`,
         providerIdentity: {
             provider: input.provider,
             adapter: input.provider,
@@ -116,7 +114,7 @@ function unsupportedProviderEnvelope(input) {
         backupRollback: descriptiveBackupPolicy(false),
         confirmations: confirmationPolicy(),
         risks: ['No provider-specific change preview is available for this provider yet.'],
-        warnings: ['Known provider enum value is unsupported by this read-only planner.'],
+        warnings: ['Known provider enum value is unsupported by this read-only planner. No files were written.'],
     };
 }
 function blockedPlanEnvelope(input, status, doctor, message) {
@@ -126,7 +124,7 @@ function blockedPlanEnvelope(input, status, doctor, message) {
         supported: true,
         status: 'blocked',
         code: 'PLAN_UNAVAILABLE',
-        summary: `${providerName} change planning could not resolve the future MCP server command: ${message}`,
+        summary: `[read-only] ${providerName} change planning could not resolve the future MCP server command: ${message}. No provider config was written. This diagnostic does not install or repair provider config.`,
         providerIdentity: {
             provider: input.provider,
             adapter: input.provider,
@@ -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: {
@@ -144,7 +143,7 @@ function blockedPlanEnvelope(input, status, doctor, message) {
         backupRollback: descriptiveBackupPolicy(false),
         confirmations: confirmationPolicy(),
         risks: ['Future write planning requires a resolvable VGXNESS database path.'],
-        warnings: [message],
+        warnings: [message, 'No files were written.'],
     };
 }
 function opencodeEnvelope(input, status, doctor, installPlan, source) {
@@ -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}. No provider config was written. This diagnostic does not install or repair provider config.` : '[read-only] Claude planning completed. No provider config was written. This diagnostic does not install or repair provider config. A 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,
     };
 }
@@ -304,7 +307,7 @@ function confirmationPolicy() {
         requiredNow: false,
         requiredBeforeFutureWrite: true,
         acceptedMutationInputs: false,
-        message: 'This response is read-only; any future provider config write must be requested and confirmed separately.',
+        message: '[read-only] No provider config was written. Any future provider config write must be requested and confirmed separately.',
     };
 }
 function statusWarnings(status) {
@@ -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')
@@ -336,6 +339,6 @@ function risksForClaude(status, doctor, plan, source) {
 }
 function summaryForOpenCode(input, plan) {
     if (plan.status === 'refused')
-        return `Read-only OpenCode ${input.changeType} planning completed; future install is currently refused: ${plan.message}`;
-    return `Read-only OpenCode ${input.changeType} planning completed; future confirmed write would ${plan.action} ${plan.targetPath}.`;
+        return `[read-only] OpenCode ${input.changeType} planning completed; future install is currently refused: ${plan.message}. No provider config was written. This diagnostic does not install or repair provider config.`;
+    return `[read-only] OpenCode ${input.changeType} planning completed. No provider config was written. This diagnostic does not install or repair provider config. A future confirmed write would ${plan.action} ${plan.targetPath}.`;
 }

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,19 +164,26 @@ 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) {
+    const suffix = '[read-only] No provider config was written. This diagnostic does not install or repair provider config.';
     if (status === 'healthy')
-        return 'Provider doctor checks passed; no configuration was changed.';
+        return `Provider doctor checks passed. ${suffix}`;
     if (status === 'degraded')
-        return `Provider doctor found warnings and ${recommendationCount} recommendation(s); no configuration was changed.`;
+        return `Provider doctor found warnings and ${recommendationCount} recommendation(s). ${suffix}`;
     if (status === 'failed')
-        return `Provider doctor found ${failedCount} failed check(s); no configuration was changed.`;
+        return `Provider doctor found ${failedCount} failed check(s). ${suffix}`;
     if (status === 'skipped')
-        return 'Provider doctor checks were skipped.';
-    return 'Provider doctor status is unknown; review checks before continuing.';
+        return `Provider doctor checks were skipped. ${suffix}`;
+    return `Provider doctor status is unknown; review checks before continuing. ${suffix}`;
 }
 function compactChecks(checks, mode) {
     if (mode === 'verbose')
@@ -272,7 +281,7 @@ function readonlySafetyCheck(before, after) {
         ? {
             id: 'provider-config-readonly-safety',
             status: 'pass',
-            detail: 'Provider config path existence and mtimes were unchanged; no repair/install/write occurred.',
+            detail: '[read-only] Provider config path existence and mtimes were unchanged. No files were written. This diagnostic does not install or repair provider config.',
         }
         : { id: 'provider-config-readonly-safety', status: 'fail', detail: 'Provider config path existence or mtimes changed during read-only doctor.' };
 }
@@ -289,6 +298,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) {
@@ -345,22 +354,24 @@ function hasProjectConfigAlongsideUser(paths) {
     return paths.some((path) => path.label.startsWith('user ') && path.exists) && paths.some((path) => !path.label.startsWith('user ') && path.exists);
 }
 function summarizeStatus(status, mcpEntry) {
+    const suffix = '[read-only] No provider config was written. This diagnostic does not install or repair provider config.';
     if (status === 'ready')
-        return 'OpenCode provider config is readable and the vgxness MCP entry is present.';
+        return `OpenCode provider config is readable and the vgxness MCP entry is present. ${suffix}`;
     if (status === 'not-configured')
-        return mcpEntry.detail;
+        return `${mcpEntry.detail} ${suffix}`;
     if (status === 'warning')
-        return 'OpenCode provider config has warnings; no changes were made.';
-    return 'OpenCode provider status check found a blocking issue; no changes were made.';
+        return `OpenCode provider config has warnings. ${suffix}`;
+    return `OpenCode provider status check found a blocking issue. ${suffix}`;
 }
 function summarizeClaudeStatus(status, mcpEntry) {
+    const suffix = '[read-only] No provider config was written. This diagnostic does not install or repair provider config.';
     if (status === 'ready')
-        return 'Claude project .mcp.json and VGXNESS agent files are readable and configured.';
+        return `Claude provider files were inspected and VGXNESS entries are readable. ${suffix}`;
     if (status === 'not-configured')
-        return mcpEntry.detail;
+        return `${mcpEntry.detail} ${suffix}`;
     if (status === 'warning')
-        return 'Claude provider project config has warnings; no changes were made.';
-    return 'Claude provider status check found a blocking issue; no changes were made.';
+        return `Claude provider project config has warnings. ${suffix}`;
+    return `Claude provider status check found a blocking issue. ${suffix}`;
 }
 function nextActionFor(status, mcpEntry, sddNext) {
     if (sddNext !== undefined)

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',